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. בדוק תיבת דואר

```bash
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 חדשים מחיים:

```bash
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 מחיים מזכיר קובץ או טיוטה:

```bash
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 ועבודה

```bash
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/קוד/נתיבים):**
```bash
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:
   ```bash
   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

**אם המשימה הושלמה בהצלחה** (כל המסמכים חולצו, כל הבדיקות עברו, אין חסימות):
```bash
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, חוסר מידע, שגיאה שלא ניתנת לפתרון):
```bash
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` |

```bash
# קבע 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. התראת מייל — כשנדרשת תשובה אנושית

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

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

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

**מתי לא לשלוח:**
- עדכוני סטטוס ביניים (רק בסיום)
- שגיאות טכניות שאפשר לפתור לבד

## 6. Release

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