ezer-mishpati/legal-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agents): centralize completion/wakeup protocol to HEARTBEAT §4 (R1, G12, #110)

Browse Source 
6 סוכני-העובד (writer/exporter/proofreader/qa/researcher/analyst) שכפלו inline את
בלוק-הדיווח-וההשכמה הזהה (PATCH done/blocked + CEO_ID if-block + wakeup JSON +
אזהרת agent_wakeup_requests) — שהוא כבר המקור הקנוני ב-HEARTBEAT.md §4ב/§4ג.

הוחלף בכל קובץ במצביע קומפקטי ל-HEARTBEAT §4ב/§4ג, תוך שימור: ה-rationale
(auto-retry), reason ספציפי-לתפקיד, ומלכודות ספציפיות (UUID של analyst, QA gate
של writer). כפילות הפרוטוקול הקשיח: 288→83 hits (היתרה: orchestration לגיטימי של
CEO + מצביעי-HEARTBEAT). סוכני gemini נשארו (וריאנט מצומצם מכוון, ללא CEO).

Invariants: G12 (פרומפטים מצביעים ל-HEARTBEAT, לא משכפלים פרוטוקול) · G2 (מקור יחיד).

הפצה לסוכנים-רצים: לאחר מיזוג — git pull בעץ הראשי + sync_agents_across_companies.py
(הפרומפטים נטענים מ-cwd המשותף). אומת מבנית: code-fences מאוזנים, מצביעי §4 מדויקים.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chaim
2026-06-10 09:22:20 +00:00
parent c903770fb3
commit 1c182edb29
6 changed files with 19 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
.claude/agents/legal-analyst.md
View File

@@ -312,16 +312,7 @@ FROM documents d WHERE d.case_id = '{case_id}' AND d.doc_type IN ('appeal', 'res
3. **עדכן סטטוס התיק** (`case_update` עם status = `documents_ready`)
4. **סגור את ה-issue של עצמך — חובה!** בלי זה Paperclip יחשוב שהמשימה עדיין רצה ויפעיל retry בלולאה (זה נצפה בפועל בריצת CMPA-16 — שלוש איטרציות מיותרות).
**אם הכל עבר בהצלחה (בדיקות שלב 6 + טענות + עובדות שמאי):**
```bash
~/legal-ai/scripts/pc.sh PATCH "/api/issues/$PAPERCLIP_TASK_ID" '{"status": "done"}'```
**אם בדיקות שלב 6 נכשלו או חילוץ נכשל:**
```bash
~/legal-ai/scripts/pc.sh PATCH "/api/issues/$PAPERCLIP_TASK_ID" '{"status": "blocked"}'```
**אסור** לסיים `done` עם פלט חסר — אם ניסיון חוזר נכשל, סטטוס = `blocked` + comment עם פירוט.
4. **סגור את ה-issue של עצמך — חובה!** בלי זה Paperclip יחשוב שהמשימה עדיין רצה ויפעיל retry בלולאה (נצפה ב-CMPA-16 — שלוש איטרציות מיותרות). PATCH סטטוס `done` (הצלחה: בדיקות שלב 6 + טענות + עובדות שמאי) או `blocked` (כשל/פלט-חסר) — פקודות מדויקות ב-[HEARTBEAT.md](HEARTBEAT.md) §4ב. **אסור** `done` עם פלט חסר.
5. **שלח מייל**:
```bash
@@ -331,20 +322,9 @@ FROM documents d WHERE d.case_id = '{case_id}' AND d.doc_type IN ('appeal', 'res
```
### העֵר את העוזר המשפטי (CEO) — חובה!
```bash
# $PAPERCLIP_TASK_ID הוא UUID המלא שPaperclip מספק בסביבת הריצה — לעולם לא CMP-XX
# אסור להחליף ידנית: משתמשים ב-$PAPERCLIP_TASK_ID ישירות
if [ "$PAPERCLIP_COMPANY_ID" = "8639e837-4c9d-47fa-a76b-95788d651896" ]; then
CEO_ID="cdbfa8bc-3d61-41a4-a2e7-677ec7d34562" # CMPA — היטלי השבחה
else
CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33" # CMP — רישוי ובניה
fi
~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" \
"{\"source\":\"automation\",\"triggerDetail\":\"system\",\"reason\":\"מנתח משפטי סיים $PAPERCLIP_TASK_ID בסטטוס done/blocked\",\"payload\":{\"issueId\":\"$PAPERCLIP_TASK_ID\",\"mutation\":\"agent_completion\"}}"```
**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
**⚠️ אסור לקבע UUID של CEO** — UUID שונה לכל חברה. תמיד דרך `$PAPERCLIP_COMPANY_ID`. wakeup לחברה אחרת נדחה: `Agent key cannot access another company`.
**⚠️ `$PAPERCLIP_TASK_ID` — זה UUID, לא CMP-XX.** המשתנה מוגדר אוטומטית ע"י Paperclip בסביבת הריצה. אם משתמשים בו ב-double-quotes (`"..."`), bash מרחיב אותו לערך האמיתי. שגיאת `invalid input syntax for type uuid` = שלחת CMP-XX במקום UUID.
wakeup ל-CEO עם `payload.issueId=$PAPERCLIP_TASK_ID` ו-`reason="מנתח משפטי סיים $PAPERCLIP_TASK_ID בסטטוס done/blocked"` — הפרוטוקול המלא (CEO לפי חברה, אזהרות) במקור היחיד [HEARTBEAT.md](HEARTBEAT.md) §4ג. **אסור** `INSERT INTO agent_wakeup_requests` ישיר; **אסור** לקבע UUID של CEO (נגזר מ-`$PAPERCLIP_COMPANY_ID`).
**⚠️ `$PAPERCLIP_TASK_ID` — זה UUID, לא CMP-XX.** מוגדר אוטומטית ע"י Paperclip; ב-double-quotes bash מרחיב לערך האמיתי. שגיאת `invalid input syntax for type uuid` = שלחת CMP-XX במקום UUID.
## מבנה הפלט המלא — analysis-and-research.md
@@ -504,18 +484,7 @@ X שאלות עומדות להכרעה:
"העמקת ניתוח הושלמה — ערר {case_number}" \
"סיכום: X פסקי דין אומתו, Y דורשים אימות חיצוני. ממצאים עובדתיים הועשרו."
```
6. **העֵר את ה-CEO — חובה!**
```bash
# CEO לפי חברה — אסור לקבע UUID, חברות שונות = CEO שונה
if [ "$PAPERCLIP_COMPANY_ID" = "8639e837-4c9d-47fa-a76b-95788d651896" ]; then
CEO_ID="cdbfa8bc-3d61-41a4-a2e7-677ec7d34562" # CMPA — היטלי השבחה
else
CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33" # CMP — רישוי ובניה
fi
~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" \
"{\"source\":\"automation\",\"triggerDetail\":\"system\",\"reason\":\"מנתח משפטי סיים העמקת ניתוח (pass 2) $PAPERCLIP_TASK_ID\",\"payload\":{\"issueId\":\"$PAPERCLIP_TASK_ID\",\"mutation\":\"agent_completion\"}}"```
**⚠️ אם ה-API מחזיר שגיאה — אל תיגע ב-DB.** `INSERT INTO agent_wakeup_requests` לא יוצר `heartbeat_run` והסוכן לא יתעורר לעולם. בדוק `$PAPERCLIP_COMPANY_ID` ו-`$PAPERCLIP_API_KEY`, ודאי שאתה לא קורא ל-CEO של חברה אחרת (`Agent key cannot access another company`).
6. **העֵר את ה-CEO — חובה!** wakeup עם `payload.issueId=$PAPERCLIP_TASK_ID` ו-`reason="מנתח משפטי סיים העמקת ניתוח (pass 2) $PAPERCLIP_TASK_ID"` — הפרוטוקול המלא (CEO לפי חברה, אזהרות) במקור היחיד [HEARTBEAT.md](HEARTBEAT.md) §4ג. **אם ה-API מחזיר שגיאה — אל תיגע ב-DB** (`INSERT INTO agent_wakeup_requests` לא יוצר `heartbeat_run`); בדוק `$PAPERCLIP_COMPANY_ID`/`$PAPERCLIP_API_KEY` ושאינך קורא ל-CEO של חברה אחרת.
## כללים קריטיים