legal-ai/.claude/agents/HEARTBEAT.md

HEARTBEAT.md — רשימת ביצוע לכל ריצה

שפה — כלל עליון

כל הפלט שלך חייב להיות בעברית בלבד. זה כולל:

• Comments ב-Paperclip
• הודעות סטטוס
• תיאורי שגיאות
• סיכומים ודיווחים
• חשיבה פנימית (thinking)

אין יוצאים מן הכלל. גם שמות tools, פקודות, ונתיבי קבצים — ההסבר סביבם בעברית.

---

הרץ את הרשימה הזו בכל heartbeat.

1. זיהוי וסינון חברה

• וודא שאתה יודע מי אתה: $PAPERCLIP_AGENT_ID
• בדוק הקשר: $PAPERCLIP_TASK_ID, $PAPERCLIP_WAKE_REASON
• זהה את החברה שלך: $PAPERCLIP_COMPANY_ID

⚠️ סינון תיקים לפי חברה — כלל ברזל

אתה אחראי רק על תיקים ששייכים לחברה שלך. הספרה הראשונה של מספר התיק קובעת:

חברה	COMPANY_ID	סוגי תיקים	טווח מספרים
ועדת ערר רישוי ובניה	42a7acd0-30c5-4cbd-ac97-7424f65df294	רישוי ובניה	1xxx
ועדת ערר היטלי השבחה	8639e837-4c9d-47fa-a76b-95788d651896	היטל השבחה + פיצויים ס' 197	8xxx, 9xxx

• אם $PAPERCLIP_COMPANY_ID = 42a7acd0... → עבוד רק על תיקים שמתחילים ב-1
• אם $PAPERCLIP_COMPANY_ID = 8639e837... → עבוד רק על תיקים שמתחילים ב-8 או 9
• לעולם אל תיצור פרויקט, issue, או תוכן לתיק שלא בטווח שלך
• אם issue שהוקצה לך מכוון לתיק שלא בטווח שלך — סרב בנימוס ודווח ב-comment

2. בדוק תיבת דואר

curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" "$PAPERCLIP_API_URL/api/agents/me/inbox-lite"

• תעדוף: in_progress קודם, אחר כך todo
• אם PAPERCLIP_TASK_ID מוגדר — תעדף אותו

2b. קרא תגובות אחרונות על ה-issue

לפני שאתה מתחיל לעבוד, בדוק אם יש comments חדשים מחיים:

curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" | jq '[.[] | select(.authorUserId != null)] | .[-3:]'

• אם יש comment מחיים (authorUserId, לא authorAgentId) שנכתב אחרי ה-comment האחרון שלך — קרא אותו בתשומת לב
• אם ה-comment מכיל הוראות עבודה — עקוב אחריהן
• אם ה-comment מזכיר קובץ שהועלה — בדוק attachments (ראה 2c)
• אם ה-comment מבקש להעביר לסוכן אחר — עצור, פרסם comment שמאשר, והעֵר את ה-CEO

2c. בדוק קבצים מצורפים

אם comment מחיים מזכיר קובץ או טיוטה:

PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c "
SELECT a.original_filename, a.content_type, a.object_key, a.byte_size
FROM issue_attachments ia
JOIN assets a ON a.id = ia.asset_id
WHERE ia.issue_id = '{issue-id}'
ORDER BY ia.created_at DESC LIMIT 5;"

• נתיב מלא לקובץ: /home/chaim/.paperclip/instances/default/data/storage/{object_key}
• קבצי DOCX — קרא אותם עם Read
• השתמש בתוכן הקובץ כקלט לעבודתך

3. Checkout ועבודה

curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  "$PAPERCLIP_API_URL/api/issues/{issue-id}/checkout"

• עבוד על המשימה לפי ההוראות ב-AGENTS.md שלך
• השתמש בכלים המשפטיים (legal-ai MCP)

⚠️ self-recovery — issue ב-todo עם תוצרים קיימים

ל-Paperclip יש באג ידוע: לאחר ש-issue מתעדכן ל-done, מנגנון issue.released מחזיר אותו ל-todo תוך כ-30 שניות (תועד ב-docs/paperclip-quirks.md §1). זה גורם ל-wakeup חוזר של אותו סוכן על משימה שכבר בוצעה.

לפני שאתה מתחיל עבודה — בדוק שהמשימה לא בוצעה כבר:

1. בדוק תוצרים בדיסק: Glob על תיקיות ה-output הצפויות ({case_dir}/documents/research/*.md לחוקר, analysis-and-research.md למנתח, וכו')
2. בדוק תוצרים ב-DB: דרך MCP — precedent_list, get_claims, extract_appraiser_facts (status=completed)
3. בדוק comments קודמים על ה-issue — אם הסוכן הקודם פרסם "הושלם בהצלחה" מסוף-מצב

אם הכל קיים ותקין: אל תבצע עבודה כפולה. במקום זאת:

• פרסם comment קצר: "אין שינוי — כל התוצרים קיימים מהריצה הקודמת (X פריטים ב-DB, קובץ Y בדיסק). סוגר את ה-issue."
• PATCH /api/issues/{id} → done
• צא נקי

אם משהו חסר/שונה: עבוד על מה שחסר בלבד, לא על הכל מחדש.

4. דיווח — חובה!

לפני שאתה מסיים, תמיד:

4א. פרסם comment על ה-issue

ל-body קצר (<500 תווים, בלי backticks/קוד/נתיבים):

curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" \
  -d '{"body": "סיכום העבודה..."}'

ל-body ארוך / markdown עם נתיבים בbacktick / קוד — חובה שתי פעולות נפרדות:

1. כתוב את ה-JSON לקובץ זמני דרך Write tool (לא דרך bash heredoc):

   Write(file_path="/tmp/comment-{issue-id}.json",
         content=json.dumps({"body": markdown_body}, ensure_ascii=False))
   

2. אז curl -d @file שקורא את הקובץ ישירות — בלי shell expansion:

   curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     -H "Content-Type: application/json" \
     "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" \
     -d @/tmp/comment-{issue-id}.json
   

⚠️ למה לא bash heredoc / python3 -c: backticks ב-markdown (`path/to/file`) ייפרשו על ידי bash כ-command substitution גם כשהם בתוך מחרוזת Python. תקבל שגיאת Permission denied מטעה (bash מנסה להריץ את הנתיב כפקודה). הפתרון של temp-file חוסם את כל ה-shell quoting traps. תועד ב-docs/paperclip-quirks.md §2.

4ב. קבע סטטוס — done או blocked

אם המשימה הושלמה בהצלחה (כל המסמכים חולצו, כל הבדיקות עברו, אין חסימות):

curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$PAPERCLIP_API_URL/api/issues/{issue-id}" \
  -d '{"status": "done"}'

אם המשימה נכשלה או חסומה (מסמך לא חולץ, timeout, חוסר מידע, שגיאה שלא ניתנת לפתרון):

curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$PAPERCLIP_API_URL/api/issues/{issue-id}" \
  -d '{"status": "blocked"}'

אסור לסיים issue כ-"done" אם יש כשל שלא טופל. "done" = הכל הושלם בהצלחה. אם משהו נכשל — "blocked".

4ג. העֵר את העוזר המשפטי (CEO) — חובה!

אחרי כל סיום משימה (done או blocked), העֵר את העוזר המשפטי של החברה שלך כדי שיבדוק תוצאות ויחליט על הצעד הבא:

⚠️ בחר CEO לפי חברה:

חברה	COMPANY_ID	CEO Agent ID
רישוי ובניה (CMP)	42a7acd0-...	752cebdd-6748-4a04-aacd-c7ab0294ef33
היטלי השבחה (CMPA)	8639e837-...	cdbfa8bc-3d61-41a4-a2e7-677ec7d34562

# קבע CEO_ID לפי חברה:
if [ "$PAPERCLIP_COMPANY_ID" = "8639e837-4c9d-47fa-a76b-95788d651896" ]; then
  CEO_ID="cdbfa8bc-3d61-41a4-a2e7-677ec7d34562"
else
  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"
fi

curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$PAPERCLIP_API_URL/api/agents/$CEO_ID/wakeup" \
  -d '{"source":"automation","triggerDetail":"system","reason":"סוכן [שמך] סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-id]","mutation":"agent_completion"}}'

⚠️ כללי ברזל — Paperclip API:

1. אסור INSERT INTO agent_wakeup_requests — לא יוצר heartbeat_run, הסוכן לא יתעורר לעולם
2. חובה payload.issueId בכל wakeup — בלי זה הסוכן מתעורר בלי הקשר (בלי תיק, בלי cwd)
3. agent JWT לא יכול להעיר סוכנים אחרים — רק את עצמו. כדי להעיר סוכן אחר → צור issue + הקצה אליו (Paperclip מפעיל wakeup אוטומטי)

נתיבי API:

פעולה	נתיב
פרסום comment	POST /api/issues/{issue-id}/comments
יצירת issue	POST /api/companies/{company-id}/issues
עדכון issue	PATCH /api/issues/{issue-id}
wakeup עצמי/CEO	POST /api/agents/{agent-id}/wakeup (עם payload!)

5. התראת מייל — כשנדרשת תשובה אנושית

כשהתוצאה דורשת החלטה או תשובה של חיים, שלח מייל:

python3 /home/chaim/legal-ai/scripts/notify.py \
  "נדרשת תשובתך — [תיאור קצר]" \
  "תוכן ההודעה עם סיכום מה נדרש"

מתי לשלוח — תמיד:

• סיום כל משימה — עם סיכום קצר של מה בוצע
• בקשה לקביעת תוצאה (דחייה/קבלה/חלקית)
• בקשה לאישור כיוון נימוק
• דוח QA שנכשל (צריך החלטה על תיקונים)
• החלטה מוכנה לביקורת דפנה
• כל מצב שדורש פעולה אנושית ולא יכול להתקדם לבד
• שגיאה שלא ניתן לפתור ללא התערבות

מתי לא לשלוח:

• עדכוני סטטוס ביניים (רק בסיום)
• שגיאות טכניות שאפשר לפתור לבד

6. Release

curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  "$PAPERCLIP_API_URL/api/issues/{issue-id}/release"