feat(paperclip): close 11 integration gaps (#16-#28)

Brings the legal-ai ↔ Paperclip integration in line with the official Paperclip skill. Net effect: HEARTBEAT.md -47% (370→195 lines), all 14 agents on uniform runtime_config + budget + instructionsBundleMode, and two cross-company helpers replacing manual SQL. Highlights: - HEARTBEAT.md refactor: project-specific only, delegates to the official paperclipai/paperclip skill (loaded per agent). Adds heartbeat-context fast-path (§1.7) and PAPERCLIP_WAKE_PAYLOAD_JSON shortcut (§1.5). - Issue Thread Interactions API: legal-ceo.md now uses ask_user_questions / request_confirmation / suggest_tasks instead of free-text comments — gives chair structured UI with idempotency keys. - pc.sh + paperclip_api.pc_request: every API call goes through helpers that inject Authorization + X-Paperclip-Run-Id (audit trail). - sync_agents_across_companies.py: master(CMP)→mirror(CMPA) sync via Paperclip API, idempotent, with --verify and --apply modes. - skills/new-company-setup: 11-step blueprint distilling all 11 gaps into a single onboarding runbook for the next company. - .taskmaster: 12 tasks covering each gap (one already closed: #29). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-04 17:25:45 +00:00
parent 6f713042b5
commit cf5f6fe274
16 changed files with 1724 additions and 408 deletions
--- a/.claude/agents/HEARTBEAT.md
+++ b/.claude/agents/HEARTBEAT.md
@@ -1,197 +1,165 @@
-# HEARTBEAT.md — רשימת ביצוע לכל ריצה
+# HEARTBEAT.md — רשימת ביצוע לכל ריצה (Project-Specific)

-## שפה — כלל עליון
-
-**כל הפלט שלך חייב להיות בעברית בלבד.** זה כולל:
- Comments ב-Paperclip
- הודעות סטטוס
- תיאורי שגיאות
- סיכומים ודיווחים
- חשיבה פנימית (thinking)
-
-אין יוצאים מן הכלל. גם שמות tools, פקודות, ונתיבי קבצים — ההסבר סביבם בעברית.
+> **🎯 קובץ זה — Project-specific only.** ה-skill הרשמי `paperclipai/paperclip/paperclip` (טעון אוטומטית בכל heartbeat דרך `paperclipSkillSync`) מכיל את כל ה-API patterns הגנריים: identity (`/api/agents/me`), `PAPERCLIP_WAKE_PAYLOAD_JSON`, `APPROVAL_ID`, inbox, comments, checkout, status updates, וכו'. **קובץ זה מתעד רק התאמות שלנו** — סינון חברה, helpers, workarounds, ו-quirks.
+>
+> **בקונפליקט:** קובץ זה גובר על ה-skill (project-specific מנצח default).

 ---

-הרץ את הרשימה הזו בכל heartbeat.
+## שפה — כלל עליון

-## 1. זיהוי וסינון חברה
+**כל הפלט שלך חייב להיות בעברית בלבד.** כולל: comments, סטטוס, שגיאות, סיכומים, ו-thinking פנימי. אין יוצאים מן הכלל. גם שמות tools, פקודות, ונתיבי קבצים — ההסבר סביבם בעברית. ה-skill הרשמי באנגלית — תרגם אם נדרש.

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

-### ⚠️ סינון תיקים לפי חברה — כלל ברזל
+## §0. כל קריאה ל-Paperclip API — דרך `pc.sh` בלבד

-**אתה אחראי רק על תיקים ששייכים לחברה שלך.** הספרה הראשונה של מספר התיק קובעת:
-
-| חברה | 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. בדוק תיבת דואר
+**ה-skill הרשמי משתמש ב-`curl` ישיר. אצלנו אסור.** משתמשים ב-helper שלנו:

 ```bash
-curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" "$PAPERCLIP_API_URL/api/agents/me/inbox-lite"
+~/legal-ai/scripts/pc.sh <METHOD> <PATH> [BODY_JSON] [extra curl args...]
 ```

- תעדוף: `in_progress` קודם, אחר כך `todo`
- אם `PAPERCLIP_TASK_ID` מוגדר — תעדף אותו
+מוסיף אוטומטית: `Authorization`, `X-Paperclip-Run-Id` (audit), `Content-Type`, base URL.

-## 2b. קרא תגובות אחרונות על ה-issue
+**דוגמאות:**
+```bash
+~/legal-ai/scripts/pc.sh GET    "/api/agents/me/inbox-lite"
+~/legal-ai/scripts/pc.sh POST   "/api/issues/$ISSUE_ID/checkout"
+~/legal-ai/scripts/pc.sh PATCH  "/api/issues/$ISSUE_ID" '{"status":"done"}'
+```

-לפני שאתה מתחיל לעבוד, בדוק אם יש comments חדשים מחיים:
+**ל-body גדול עם backticks** — `Write` ל-temp file, אז `pc.sh ... "" -H "Content-Type: application/json" -d @/tmp/comment.json`. ראה §דיווח למה.
+
+---
+
+## §1. זיהוי וסינון חברה — כלל ברזל ⚠️
+
+| חברה | COMPANY_ID | סוגי תיקים | טווח מספרים | CEO Agent ID |
+|------|------------|-------------|---------------|---------------|
+| ועדת ערר רישוי ובניה (CMP) | `42a7acd0-30c5-4cbd-ac97-7424f65df294` | רישוי ובניה | **1xxx** | `752cebdd-6748-4a04-aacd-c7ab0294ef33` |
+| ועדת ערר היטלי השבחה (CMPA) | `8639e837-4c9d-47fa-a76b-95788d651896` | היטל השבחה + פיצויים ס' 197 | **8xxx, 9xxx** | `cdbfa8bc-3d61-41a4-a2e7-677ec7d34562` |
+
+- אם `$PAPERCLIP_COMPANY_ID` = `42a7acd0...` → רק תיקים ש-**1xxx**
+- אם `$PAPERCLIP_COMPANY_ID` = `8639e837...` → רק תיקים ש-**8xxx/9xxx**
+- **אסור** ליצור פרויקט/issue/תוכן לתיק שלא בטווח שלך
+- אם issue שהוקצה לך מכוון לתיק שלא בטווח — סרב בנימוס ב-comment, והעֵר את ה-CEO של החברה הנכונה
+
+---
+
+## §1.5. טיפול ב-wake (skill הרשמי + תוספות שלנו)
+
+ה-skill מסביר `PAPERCLIP_WAKE_PAYLOAD_JSON`, `APPROVAL_ID`, ו-`heartbeat-context` (Step 6). הוסף עליו:
+
+**1.5א. אם `$PAPERCLIP_WAKE_PAYLOAD_JSON` מכיל comment חדש מחיים** — התייחס אליו ב-comment הראשון שלך ("ראיתי שביקשת X — מבצע Y") **לפני** עבודה רחבה. זה מבטיח שחיים יודע שקלטת.
+
+**1.5ב. תמיד לקרוא `heartbeat-context`** — לא רק מה ש-skill ממליץ ("Prefer"). אצלנו ה-`attachments` המוחזרים חיוניים (חיים מעלה DOCX/PDF דרך comments). ראה §2.

 ```bash
-curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" | jq '[.[] | select(.authorUserId != null)] | .[-3:]'
+CONTEXT=$(~/legal-ai/scripts/pc.sh GET "/api/issues/$ISSUE_ID/heartbeat-context?wakeCommentId=$LATEST_COMMENT_ID")
+ATTACHMENTS=$(echo "$CONTEXT" | jq '.attachments')
 ```

- אם יש comment מחיים (authorUserId, לא authorAgentId) שנכתב **אחרי** ה-comment האחרון שלך — **קרא אותו בתשומת לב**
- אם ה-comment מכיל הוראות עבודה — **עקוב אחריהן**
- אם ה-comment מזכיר קובץ שהועלה — בדוק attachments (ראה 2c)
- אם ה-comment מבקש להעביר לסוכן אחר — **עצור**, פרסם comment שמאשר, והעֵר את ה-CEO
+**1.5ג. APPROVAL_ID flow** — אם חיים ענה על interaction (ראה `legal-ceo.md` §B/§C/§D), קרא תשובה דרך:
+```bash
+~/legal-ai/scripts/pc.sh GET "/api/issues/$PAPERCLIP_TASK_ID/interactions/$PAPERCLIP_APPROVAL_ID" | jq '{status, kind, response}'
+```
+**אסור** לפענח טקסט מ-comment חופשי כשיש APPROVAL_ID — זה הקלט הסטרוקטורלי.

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

-אם comment מחיים מזכיר קובץ או טיוטה:
+## §2. קבצים מצורפים — דרך `heartbeat-context`, **לא psql**
+
+ה-attachments זמינים ב-`$CONTEXT.attachments` (מ-§1.5ב):

 ```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;"
+echo "$CONTEXT" | jq '.attachments[] | {filename, contentPath, contentType, byteSize}'
+
+# נתיב מלא לקובץ:
+CONTENT_PATH=$(echo "$CONTEXT" | jq -r '.attachments[0].contentPath')
+FULL_PATH="/home/chaim/.paperclip/instances/default/data/storage/$CONTENT_PATH"
 ```

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

-## 3. Checkout ועבודה
+⚠️ **`psql` ישיר ל-`issue_attachments` — אסור.** ה-API הוא ה-source of truth (Gap #21).

+---
+
+## §3. self-recovery — `issue.released` bug
+
+⚠️ **Paperclip quirk ידוע**: לאחר ש-issue מסומן `done`, מנגנון `issue.released` עלול להחזיר אותו ל-`todo` תוך ~30s, וגורם ל-wakeup חוזר על משימה שכבר בוצעה (תועד ב-`docs/paperclip-quirks.md §1`).
+
+**לפני שמתחילים עבודה — בדוק שלא בוצעה כבר:**
+
+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 קודמים** — חפש "הושלם בהצלחה" מסוף-מצב
+
+**אם הכל קיים ותקין:** פרסם comment קצר ("אין שינוי — תוצרים קיימים מהריצה הקודמת"), `PATCH status=done`, צא נקי. **לא לעבוד פעמיים.**
+
+**אם משהו חסר/שונה:** עבוד רק על מה שחסר.
+
+---
+
+## §4. דיווח — חובה!
+
+**כל heartbeat שמסיים משימה:** comment + status + wake CEO. הסעיף הזה מתעד רק workarounds שלנו לא ב-skill.
+
+### §4א. dual-comment workaround ל-`backtick trap`
+
+**ל-body קצר (<500 תווים, בלי backticks/קוד/נתיבים)** — pattern רגיל:
 ```bash
-curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  "$PAPERCLIP_API_URL/api/issues/{issue-id}/checkout"
+~/legal-ai/scripts/pc.sh POST "/api/issues/{issue-id}/comments" '{"body": "סיכום..."}'
 ```

- עבוד על המשימה לפי ההוראות ב-AGENTS.md שלך
- השתמש בכלים המשפטיים (legal-ai MCP)
+**ל-body ארוך עם markdown/backticks/נתיבים — חובה שתי פעולות נפרדות:**

-### ⚠️ 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):
+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:
+2. אז `pc.sh` עם `-d @file` שקורא את הקובץ ישירות:
   ```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
+   ~/legal-ai/scripts/pc.sh POST "/api/issues/{issue-id}/comments" "" \
+     -H "Content-Type: application/json" -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`.
+⚠️ **למה לא bash heredoc / `python3 -c`:** backticks ב-markdown (`` `path/to/file` ``) ייפרשו על-ידי bash כ-command substitution גם בתוך מחרוזת Python. תקבל `Permission denied` מטעה. תועד ב-`docs/paperclip-quirks.md §2`.

-### 4ב. קבע סטטוס — done או blocked
+### §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"}'
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'    # הצליח
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "blocked"}' # נכשל / חסום
 ```

-**אם המשימה נכשלה או חסומה** (מסמך לא חולץ, 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".
+**אסור** `done` עם כשל שלא טופל. אם משהו נכשל → `blocked` + comment עם פירוט.

-### 4ג. העֵר את העוזר המשפטי (CEO) — חובה!
-אחרי כל סיום משימה (done או blocked), **העֵר את העוזר המשפטי של החברה שלך** כדי שיבדוק תוצאות ויחליט על הצעד הבא:
+### §4ג. wake CEO לפי חברה

-**⚠️ בחר CEO לפי חברה:**
-| חברה | COMPANY_ID | CEO Agent ID |
-|------|------------|-------------|
-| רישוי ובניה (CMP) | `42a7acd0-...` | `752cebdd-6748-4a04-aacd-c7ab0294ef33` |
-| היטלי השבחה (CMPA) | `8639e837-...` | `cdbfa8bc-3d61-41a4-a2e7-677ec7d34562` |
+**⚠️ CEO שונה לכל חברה** (ראה §1). UUID hardcoded **אסור** — תמיד דרך `$PAPERCLIP_COMPANY_ID`:

 ```bash
-# קבע CEO_ID לפי חברה:
 if [ "$PAPERCLIP_COMPANY_ID" = "8639e837-4c9d-47fa-a76b-95788d651896" ]; then
-  CEO_ID="cdbfa8bc-3d61-41a4-a2e7-677ec7d34562"
+  CEO_ID="cdbfa8bc-3d61-41a4-a2e7-677ec7d34562"  # CMPA
 else
-  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"
+  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"  # CMP
 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"}}'
+~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" \
+  '{"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 אוטומטי)
+⚠️ **חובה `payload.issueId`** — בלי זה הסוכן מתעורר בלי הקשר (בלי תיק, בלי cwd).
+⚠️ **wakeup לחברה אחרת נדחה** — `Agent key cannot access another company`.
+⚠️ **אסור** `INSERT INTO agent_wakeup_requests` ישיר — לא יוצר heartbeat_run, הסוכן לא מתעורר.

-**נתיבי 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. התראת מייל — כשנדרשת תשובה אנושית
-
-**כשהתוצאה דורשת החלטה או תשובה של חיים**, שלח מייל:
+## §5. התראת מייל — כשנדרשת תשובה אנושית

 ```bash
 python3 /home/chaim/legal-ai/scripts/notify.py \
@@ -199,22 +167,29 @@ python3 /home/chaim/legal-ai/scripts/notify.py \
  "תוכן ההודעה עם סיכום מה נדרש"
 ```

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

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

-## 6. Release
+---
+
+## §6. Release

 ```bash
-curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  "$PAPERCLIP_API_URL/api/issues/{issue-id}/release"
+~/legal-ai/scripts/pc.sh POST "/api/issues/{issue-id}/release"
 ```
+
+---
+
+## נתיבי API — הפניה ל-skill הרשמי
+
+| פעולה | איפה ב-skill |
+|--------|---------------|
+| Identity, inbox, pick work | Step 1, 3, 4 |
+| Wake payload + APPROVAL handling | Authentication + Step 2 |
+| Heartbeat-context, comments, attachments | Step 6 |
+| Checkout (with the `checkedOutByHarness` skip) | Step 5 |
+| Comment, status update, exit | Step 7-8 |
+| Routines, workflows, references | `references/` ב-skill |
+
+**שינויים project-specific מה-skill:** תועדו בקובץ זה (§0 pc.sh, §1 חברה, §2 attachments, §3 quirk, §4 dual-comment + CEO wakeup, §5 notify).
--- a/.claude/agents/legal-analyst.md
+++ b/.claude/agents/legal-analyst.md
@@ -170,11 +170,75 @@ tools:
 - **לא להמציא פסיקה** — אם יש אזכור במסמכי התיק, ניתן להתייחס. אם לא — נסח ללא הפניה
 - שימוש במונחים מקובלים בפסיקה הישראלית (מתאים לחיפוש ב-nevo/law-mate)

-## שלב 5: חיפוש פנימי בקורפוס
-חפש תקדימים רלוונטיים בקורפוס הפנימי:
- `search_decisions` — בהחלטות קודמות של דפנה
- `find_similar_cases` — תיקים דומים
-הוסף תוצאות רלוונטיות תחת כל סוגיה כ-"תקדימים מהקורפוס הפנימי".
+## שלב 5: חיפוש בשלושת הקורפוסים — חובה, עם תיעוד queries
+
+**חובה לבצע** — לא הצעה. בלי השלב הזה הניתוח חסר תקדימי-עליון רלוונטיים, וה-writer לא יוכל לכתוב CREAC מלא. נבחן ב-QA.
+
+### 5א. חיפוש בקורפוס הסמכותי (`search_precedent_library`) — חובה
+
+לכל **טענת סף** ולכל **סוגיה מרכזית** שזיהית — הרץ לפחות שאילתה אחת ל-`search_precedent_library` עם פילטרים:
+
+| סיווג תיק | practice_area |
+|------------|---------------|
+| 1xxx (רישוי ובניה) | `rishuy_uvniya` |
+| 8xxx (היטל השבחה) | `histael_hashbacha` |
+| 9xxx (פיצויים ס' 197) | `pitsuim_197` |
+
+אם הסוגיה מאוזכרת ב-`appeal_subtype` ידוע (כמו "שימוש חורג", "חריגות בנייה", "סטייה ניכרת") — הוסף `appeal_subtype` לפילטר. צמצום מוקדם > הרחבה מאוחרת.
+
+דוגמה:
+```
+search_precedent_library(
+  query="שימוש חורג מסחרי בייעוד נופש",
+  practice_area="rishuy_uvniya",
+  appeal_subtype="שימוש חורג",
+  limit=10
+)
+```
+
+### 5ב. חיפוש בקאנון של דפנה (`search_decisions`)
+
+לכל סוגיה — הרץ `search_decisions` כדי למצוא החלטות קודמות של דפנה באותה קטגוריה. אם דפנה כבר הכריעה בסוגיה דומה — תקדם אישי הוא חלק חובה מההנמקה (חיסכון או הבחנה).
+
+### 5ג. תיקים דומים (`find_similar_cases`)
+
+לכל סוגיה מרכזית — הרץ `find_similar_cases` לזיהוי דפוסים מבניים דומים בארכיון.
+
+### 5ד. תיעוד מחייב — סעיף "שאילתות לקורפוסים" ב-`analysis-and-research.md`
+
+ב-artifact הסופי, חובה להופיע סעיף חדש בשם **"7א. שאילתות לקורפוסים — log מלא"**, עם הפורמט הבא:
+
+```markdown
+## 7א. שאילתות לקורפוסים — log מלא
+
+### קורפוס סמכותי (search_precedent_library)
+
+#### Q1 — סוגיה: [שם הסוגיה]
+- **שאילתה:** "..."
+- **פילטרים:** practice_area=..., appeal_subtype=...
+- **תוצאות:** N
+- **נבחרו:**
+  - `[case_number]` — [למה רלוונטי, איזה headnote תומך]
+- **נדחו:**
+  - `[case_number]` — [למה לא רלוונטי]
+- **0 results?** ציין מפורש + נמק (אין מה למצוא, או הפילטר צר מדי)
+
+#### Q2 — ...
+
+### קאנון דפנה (search_decisions)
+
+#### Q1 — סוגיה: [שם]
+- **שאילתה:** "..."
+- **תוצאות:** N
+- **תקדים אישי שזוהה:** [שם תיק] — חיסכון/הבחנה?
+
+### תיקים דומים (find_similar_cases)
+- ...
+```
+
+**negative evidence חובה:** גם כששאילתה החזירה 0 תוצאות, חובה לתעד אותה. זה ההבדל בין "הקורפוס נסרק וריק" ל"הקורפוס לא נסרק". ה-QA יחזיר `needs_revision` אם הסעיף חסר או חסר queries.
+
+**מינימום:** מספר queries ב-Q1+Q2+Q3 לקורפוס הסמכותי = מספר טענות סף + מספר סוגיות מרכזיות. אם זיהית 5 סוגיות + 2 טענות סף → לפחות 7 queries.

 ## שלב 6: בדיקת שלמות — לפני שמסיימים!

@@ -224,19 +288,11 @@ FROM documents d WHERE d.case_id = '{case_id}' AND d.doc_type IN ('appeal', 'res

   **אם הכל עבר בהצלחה (בדיקות שלב 6 + טענות + עובדות שמאי):**
   ```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"}'
-   ```
+   ~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'```

   **אם בדיקות שלב 6 נכשלו או חילוץ נכשל:**
   ```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"}'
-   ```
+   ~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "blocked"}'```
   **אסור** לסיים `done` עם פלט חסר — אם ניסיון חוזר נכשל, סטטוס = `blocked` + comment עם פירוט.

 5. **שלח מייל**:
@@ -255,11 +311,7 @@ else
  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"   # CMP — רישוי ובניה
 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"}}'
-```
+~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" '{"source":"automation","triggerDetail":"system","reason":"מנתח משפטי סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-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`.

@@ -337,8 +389,12 @@ X שאלות עומדות להכרעה:
 - סעיף X לחוק...
 (הערה: התחל מלשון הטקסט הנורמטיבי. תקדים נדרש רק כשהטקסט עמום.)

-**תקדימים מהקורפוס הפנימי:**
- [אם נמצאו]
+**תקדימים מהקורפוס הסמכותי (search_precedent_library):**
+- [תקדים שנבחר עם citation, headnote, רלוונטיות]
+- (חובה לפחות שאילתה אחת ב-Q1 בסעיף 7א — גם אם 0 תוצאות, יש לתעד שם)
+
+**תקדימים מהקאנון של דפנה (search_decisions):**
+- [אם נמצאו — חיסכון או הבחנה?]

 **עמדת ועדת הערר:**
 [ימולא ע"י יו"ר הוועדה — עמדה/הנחיה לגבי סוגיה זו שתשמש את סוכן הכתיבה]
@@ -362,6 +418,9 @@ X שאלות עומדות להכרעה:
 - **סדר דיון מומלץ**: הסדר המומלץ לדיון בסוגיות בהחלטה
 - **תלויות**: סוגיות שהכרעתן תלויה בהכרעה בסוגיה אחרת
 - **הערכה כללית**: לאן נוטה הניתוח ומהם הסיכויים הכלליים של הערר
+
+## 7א. שאילתות לקורפוסים — log מלא
+[סעיף חובה לפי שלב 5ד — log כל קריאה ל-search_precedent_library, search_decisions, find_similar_cases. גם 0 results.]
 ```

 ## שלב 8: העמקת ניתוח (pass 2) — אחרי אישור כיוון
@@ -373,10 +432,14 @@ X שאלות עומדות להכרעה:
 ### 8א. אימות פסיקה
 סרוק את עמדות היו"ר וזהה כל אזכור פסיקה (בג"ץ, עע"מ, עת"מ, ע"א, ערר וכו').
 לכל פסק דין שמוזכר:
-1. חפש בקורפוס הפנימי (`search_decisions`, `find_similar_cases`)
-2. חפש במסמכי התיק (`search_case_documents`) — אולי מצוטט בכתבי הטענות
-3. **אם נמצא** — חלץ ציטוט מדויק, הקשר, רלוונטיות
-4. **אם לא נמצא** — סמן: "דורש אימות חיצוני" + נסח הנחיות חיפוש
+1. חפש ב**קורפוס הסמכותי** (`search_precedent_library`) — חובה ראשונה. שם נמצאות הלכות מאושרות עם supporting_quote מוכן לציטוט.
+2. חפש בקאנון דפנה (`search_decisions`, `find_similar_cases`)
+3. חפש במסמכי התיק (`search_case_documents`) — אולי מצוטט בכתבי הטענות
+4. **אם נמצא ב-precedent_library** — צטט citation+supporting_quote מדויקים מהקורפוס.
+5. **אם נמצא רק במסמכי התיק** — סמן: "מקור: כתבי טענות, דורש אימות מול הקורפוס".
+6. **אם לא נמצא בכלל** — סמן: "דורש אימות חיצוני" + נסח הנחיות חיפוש.
+
+הוסף לסעיף "7א. שאילתות לקורפוסים" כל query נוסף שהורצה ב-pass 2.

 הוסף לכל סוגיה תת-סעיף:

@@ -419,11 +482,7 @@ X שאלות עומדות להכרעה:
     CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"   # CMP — רישוי ובניה
   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":"מנתח משפטי סיים העמקת ניתוח (pass 2) [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-id]","mutation":"agent_completion"}}'
-   ```
+   ~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" '{"source":"automation","triggerDetail":"system","reason":"מנתח משפטי סיים העמקת ניתוח (pass 2) [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-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`).

 ## כללים קריטיים
--- a/.claude/agents/legal-ceo.md
+++ b/.claude/agents/legal-ceo.md
@@ -36,6 +36,9 @@ tools:
  - mcp__legal-ai__precedent_library_list
  - mcp__legal-ai__halacha_review
  - mcp__legal-ai__halachot_pending
+  - mcp__legal-ai__extract_appraiser_facts
+  - mcp__legal-ai__write_interim_draft
+  - mcp__legal-ai__export_interim_draft
 ---

 # עוזר משפטי — מנהל תהליך כתיבת החלטות
@@ -92,10 +95,7 @@ tools:

 ```bash
 # שלב 1: יצירת issue
-ISSUE_ID=$(curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues" \
-  -d '{"title": "[ערר CASE_NUMBER] ....", "description": "...", "parentId": "'$PAPERCLIP_TASK_ID'", "assigneeAgentId": "..."}' \
+ISSUE_ID=$(~/legal-ai/scripts/pc.sh POST "/api/companies/$PAPERCLIP_COMPANY_ID/issues" '{"title": "[ערר CASE_NUMBER] ....", "description": "...", "parentId": "'$PAPERCLIP_TASK_ID'", "assigneeAgentId": "..."}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

 # שלב 2 (חובה!): קישור ל-case number בעוזר המשפטי
@@ -223,7 +223,9 @@ Paperclip חוסם אוטומטית כל issue ב-`in_progress` שאין לו ru

 **מתי:** כשיש טענות מחולצות + מחקר תקדימים, אבל אין תוצאה עדיין

-פרסם comment ב-Paperclip:
+**שיטה — dual dispatch:** קודם פרסם comment עם הסיכום המלא (לתיעוד), ואז צור interaction עם כפתורים (לחיים).
+
+#### B.1 פרסם comment עם הסיכום

 ```
 ## סיכום תיק {case_number} — מוכן להחלטה
@@ -259,135 +261,151 @@ Paperclip חוסם אוטומטית כל issue ב-`in_progress` שאין לו ru
   - כלל: ...
   - עובדות: ...
   - שאלה: ...
-
---
-
-**מה התוצאה הצפויה?**
-1. 🔴 **דחייה** — הערר נדחה
-2. 🟡 **קבלה חלקית** — מתקבל עם תנאים
-3. 🟢 **קבלה מלאה** — הערר מתקבל
-
-@chaim — הגב עם מספר (1/2/3) + הערות אם יש
 ```

-**אחרי פרסום ה-comment:** עדכן את ה-issue הראשי ל-`status=in_review` (ראה "כלל קריטי: ניהול סטטוס issue" בראש הסעיף).
+#### B.2 צור interaction לבחירת תוצאה + טיפול בטענות

-לאחר שחיים בחר תוצאה, שאל אותו לסמן טיפול בכל טענה:
-
-```
-## טיפול בטענות — {case_number}
-
-סמן לכל טענה את סוג הטיפול:
-
-| # | טענה | טיפול |
-|---|------|-------|
-| 1 | {טענה 1} | דיון מלא / קיבוץ / דילוג |
-| 2 | {טענה 2} | דיון מלא / קיבוץ / דילוג |
-| 3 | {טענה 3} | דיון מלא / קיבוץ / דילוג |
-| ... | ... | ... |
-
-**הסבר:**
- **דיון מלא** — ניתוח סילוגיסטי מלא (כלל → עובדות → מסקנה)
- **קיבוץ** — טענות שמכוונות לאותה נקודה ייאגדו יחד
- **דילוג** — "לא מצאנו ממש" או "אין צורך להכריע נוכח מסקנתנו"
-
-@chaim — סמן בטבלה והחזר
+```bash
+~/legal-ai/scripts/pc.sh POST "/api/issues/$PAPERCLIP_TASK_ID/interactions" '{
+  "kind": "ask_user_questions",
+  "idempotencyKey": "outcome:'"$PAPERCLIP_TASK_ID"':v1",
+  "title": "תוצאה וטיפול בטענות — {case_number}",
+  "summary": "ראה את הסיכום ב-comment לעיל. שתי שאלות מובנות.",
+  "continuationPolicy": "wake_assignee",
+  "payload": {
+    "version": 1,
+    "submitLabel": "המשך לכיוונים",
+    "questions": [
+      {
+        "id": "outcome",
+        "prompt": "מה התוצאה?",
+        "selectionMode": "single",
+        "required": true,
+        "options": [
+          {"id":"reject", "label":"דחייה", "description":"הערר נדחה"},
+          {"id":"partial","label":"קבלה חלקית","description":"מתקבל עם תנאים"},
+          {"id":"accept", "label":"קבלה מלאה","description":"הערר מתקבל"}
+        ]
+      },
+      {
+        "id": "claims_treatment",
+        "prompt": "אילו טענות לדון בנפרד? (multi)",
+        "selectionMode": "multi",
+        "helpText": "סמן רק טענות שצריכות דיון מלא. השאר → קיבוץ או דילוג.",
+        "options": [
+          {"id":"claim_1","label":"{טענה 1 מקוצר}"},
+          {"id":"claim_2","label":"{טענה 2 מקוצר}"},
+          {"id":"claim_3","label":"{טענה 3 מקוצר}"}
+        ]
+      }
+    ]
+  }
+}'
 ```

-**אחרי פרסום ה-comment:** עדכן את ה-issue הראשי ל-`status=in_review`.
+**אחרי יצירת ה-interaction:** עדכן את ה-issue הראשי ל-`status=in_review` (ראה "כלל קריטי: ניהול סטטוס issue" בראש הסעיף). חיים יקבל UI עם dropdowns וכפתורי radio במקום להקליד מספרים.
+
+⚠️ **`idempotencyKey`** — חובה. אם תתעורר פעמיים, Paperclip לא יוצר 2 interactions זהים.

 **מתי לחזור אחורה:** אם הסיכום לא מצליח לנסח שאלות כסילוגיזמים מכווצים — ייתכן שחסר מידע עובדתי או נורמטיבי. חזור למנתח/חוקר להשלמה.

 ### שלב C: קליטת תוצאה וכיוונים סילוגיסטיים

-**מתי:** חיים הגיב עם מספר תוצאה + טיפול בטענות
+**מתי:** התעוררת עם `$PAPERCLIP_APPROVAL_ID` שמצביע על interaction מ-§B (תשובת תוצאה+טענות).

 0. **החזר את ה-issue הראשי ל-`status=in_progress`** (קיבלת קלט והמשכת לעבוד).
-1. קרא את ה-comment של חיים
-2. זהה את הבחירה (1=rejected, 2=partial, 3=accepted)
-3. הרץ `set_outcome(case_number, outcome, reasoning)`
-4. **חשוב סילוגיסטית** על 2-3 כיוונים לנימוק — אתה כבר Claude, אתה יודע את הטענות והתקדימים. בנה כל כיוון כסילוגיזם מלא.
+1. **קרא את תשובת חיים מה-API** (לא מ-comment חופשי):
+   ```bash
+   ~/legal-ai/scripts/pc.sh GET "/api/issues/$PAPERCLIP_TASK_ID/interactions/$PAPERCLIP_APPROVAL_ID" \
+     | jq '{status, payload: .response}'
+   ```
+   - תשובת `outcome`: `reject` / `partial` / `accept` (זהה ל-1/2/3 הישן)
+   - תשובת `claims_treatment`: array של claim IDs לדיון מלא
+2. הרץ `set_outcome(case_number, outcome, reasoning)`
+3. **חשוב סילוגיסטית** על 2-3 כיוונים לנימוק — אתה כבר Claude, אתה יודע את הטענות והתקדימים. בנה כל כיוון כסילוגיזם מלא.

   > **הערה טכנית:** אל תקרא ל-`brainstorm_directions` — זה מפעיל Claude בתוך Claude ולוקח יותר מדי זמן.

-5. פרסם comment עם **סדר סוגיות מוצע**:
+4. פרסם comment קצר עם **סדר סוגיות מוצע** (לתיעוד thread):

 ```
-## כיוונים אפשריים לנימוק — {outcome_hebrew}
+## כיוונים לנימוק — {outcome_hebrew}

 ### סדר הסוגיות המוצע
 1. {שאלת סף — אם רלוונטית}
 2. {הסוגיה המכריעה}
 3. {סוגיות נוספות לפי חוזק}

---
-
-### כיוון 1: {title}
-
-**כלל (הנחה עליונה):**
-{הוראת תכנית / סעיף חוק / הלכה פסוקה}
-
-**עובדות (הנחה תחתונה):**
-{העובדות הספציפיות של הערר שנבחנות לאור הכלל}
-
-**מסקנה:**
-{התוצאה שנובעת מהחלת הכלל על העובדות}
-
-**תקדימים תומכים:** {precedents}
-
---
-
-### כיוון 2: {title}
-
-**כלל (הנחה עליונה):**
-{...}
-
-**עובדות (הנחה תחתונה):**
-{...}
-
-**מסקנה:**
-{...}
-
-**תקדימים תומכים:** {precedents}
-
---
-
-### כיוון 3: {title}
-
-**כלל (הנחה עליונה):**
-{...}
-
-**עובדות (הנחה תחתונה):**
-{...}
-
-**מסקנה:**
-{...}
-
-**תקדימים תומכים:** {precedents}
-
---
-
-@chaim — איזה כיוון מועדף? (1/2/3)
-אפשר גם לשלב כיוונים או להוסיף הערות.
+(הכיוונים המלאים — בinteraction למטה)
 ```

-**אחרי פרסום ה-comment:** עדכן את ה-issue הראשי ל-`status=in_review`.
+5. צור **interaction לבחירת כיוון** עם detailsMarkdown מלא:
+
+```bash
+~/legal-ai/scripts/pc.sh POST "/api/issues/$PAPERCLIP_TASK_ID/interactions" '{
+  "kind": "ask_user_questions",
+  "idempotencyKey": "direction:'"$PAPERCLIP_TASK_ID"':v1",
+  "title": "בחירת כיוון לנימוק — {case_number}",
+  "summary": "3 כיוונים סילוגיסטיים. בחר אחד או שלב.",
+  "continuationPolicy": "wake_assignee",
+  "payload": {
+    "version": 1,
+    "submitLabel": "אישור כיוון — להעברה לכותב",
+    "questions": [
+      {
+        "id": "direction",
+        "prompt": "איזה כיוון מועדף?",
+        "selectionMode": "single",
+        "required": true,
+        "helpText": "ניתן לשלב כיוונים בהערות ב-comment נפרד אחרי הבחירה.",
+        "options": [
+          {
+            "id": "direction_1",
+            "label": "כיוון 1: {title}",
+            "description": "כלל: {הוראת תכנית/סעיף חוק/הלכה}\nעובדות: {ספציפיות הערר}\nמסקנה: {התוצאה}\nתקדימים: {precedents}"
+          },
+          {
+            "id": "direction_2",
+            "label": "כיוון 2: {title}",
+            "description": "כלל: {...}\nעובדות: {...}\nמסקנה: {...}\nתקדימים: {precedents}"
+          },
+          {
+            "id": "direction_3",
+            "label": "כיוון 3: {title}",
+            "description": "כלל: {...}\nעובדות: {...}\nמסקנה: {...}\nתקדימים: {precedents}"
+          }
+        ]
+      }
+    ]
+  }
+}'
+```
+
+⚠️ ה-`description` של כל option בעברית. ה-`label` קצר (3-4 מילים), ה-`description` הוא הסילוגיזם המלא — חיים רואה הכל בלי להקליד.
+
+**אחרי יצירת ה-interaction:** עדכן את ה-issue הראשי ל-`status=in_review`.

 **מתי לחזור אחורה:** אם לא ניתן לבנות סילוגיזם מלא (חסר כלל, חסרות עובדות, או המסקנה לא נובעת) — חזור לחוקר תקדימים או למנתח להשלמת החסר.

 ### שלב D: אישור כיוון והפעלת כתיבה

-**מתי:** חיים הגיב עם בחירת כיוון
+**מתי:** התעוררת עם `$PAPERCLIP_APPROVAL_ID` שמצביע על interaction מ-§C (תשובת כיוון).

 0. **החזר את ה-issue הראשי ל-`status=in_progress`** (קיבלת קלט והמשכת לעבוד).
-1. קרא את ה-comment של חיים
-2. זהה כיוון (1/2/3) + הערות נוספות
+1. **קרא את תשובת חיים מה-API:**
+   ```bash
+   ~/legal-ai/scripts/pc.sh GET "/api/issues/$PAPERCLIP_TASK_ID/interactions/$PAPERCLIP_APPROVAL_ID" \
+     | jq '{status, response: .response}'
+   ```
+   - `response.direction` יחזיר `direction_1` / `direction_2` / `direction_3`
+   - אם יש הערות נוספות — חיים יוסיף ב-comment נפרד; קרא את ה-comments האחרונים
+2. זהה את הכיוון מהתשובה (1/2/3 → לפי המספר ב-id)
 3. **אימות שלמות chair_directions** — לפני שליחה לכותב, ודא:
-   - [ ] טיפול בטענות (דיון מלא / קיבוץ / דילוג) מוגדר לכל טענה
-   - [ ] כיוון סילוגיסטי נבחר ומאושר
+   - [ ] טיפול בטענות (דיון מלא / קיבוץ / דילוג) מוגדר לכל טענה (מ-§B)
+   - [ ] כיוון סילוגיסטי נבחר ומאושר (מ-§C — interaction status=`answered`)
   - [ ] סדר סוגיות מוגדר
   - [ ] תקן ביקורת מצוין
-   - אם חסר פריט כלשהו — **שאל את חיים** לפני שממשיכים
+   - אם חסר פריט כלשהו — צור interaction חדש (`request_confirmation` או `ask_user_questions`) **לפני** שממשיכים. אסור לקרוא לחיים בcomment חופשי.
 4. הרץ `approve_direction(case_number, direction_index, additional_notes)`
 5. עדכן סטטוס: `case_update(status=direction_approved)`
 6. צור issue חדש ב-Paperclip:
@@ -396,7 +414,7 @@ Paperclip חוסם אוטומטית כל issue ב-`in_progress` שאין לו ru
   - תיאור: "כיוון אושר. בצע pass 2: אמת פסיקה מעמדות היו"ר, העמק עובדות לאור הכיוון שנבחר."
 7. פרסם comment: "כיוון אושר. הועבר למנתח להעמקת ניתוח לפני כתיבה."

-**מתי לחזור אחורה:** אם חיים שינה דעתו לגבי התוצאה או הכיוון, או אם חסר מידע — חזור לשלב B או C בהתאם.
+**מתי לחזור אחורה:** אם חיים דחה את ה-interaction (`status=rejected`) או שינה דעתו לגבי התוצאה או הכיוון, או אם חסר מידע — חזור לשלב B או C בהתאם וצור interaction חדש עם `idempotencyKey` מעודכן (לדוגמה `:v2`).

 ### שלב D2: אחרי העמקת ניתוח (pass 2)

@@ -474,6 +492,72 @@ Paperclip חוסם אוטומטית כל issue ב-`in_progress` שאין לו ru
 - השתמש ב-`revise_draft` בלבד במצב ג'.
 - אם המשתמש ביקש שינוי מאסיבי (שכתוב מלא של בלוק) — עדיף להציע לו לעבוד על זה בעריכה נוספת מצדו ולא לייצר revisions ארוכים.

+### שלב H: טיוטת ביניים (לבקשת חיים, לפני דיון והכרעה)
+
+**מתי:** חיים מבקש בקומנט "טיוטת ביניים" / "interim draft" / "טיוטה לפני דיון" / "תכין לי את הטיוטה עם טענות הצדדים". בכל שלב לפני שיש תוצאה (בד"כ כשהתיק ב-`research_complete` או `analyst_verified`).
+
+**מטרה:** ייצור מסמך עבודה לחיים עם פתיחה ניטרלית, רקע, תכניות+היתרים, טענות הצדדים, והליכים — **בלי דיון והכרעה**. חיים יכתוב את בלוק י בעצמו ואז נמשיך לזרימה הרגילה (QA + ייצוא סופי).
+
+**זה side-quest, לא חלק מהזרימה B-F.** אל תשנה `cases.status`. אל תייצר issues לסוכני משנה. הכלים `write_interim_draft` ו-`export_interim_draft` עושים הכל בעצמם.
+
+**זרימה (~5-10 דקות):**
+
+1. פרסם comment קצר: "מתחיל יצירת טיוטת ביניים — אעדכן בסיום." עדכן את ה-issue הראשי ל-`status=in_progress`.
+
+2. **חילוץ עובדות שמאיות** (אם תיק 8xxx/9xxx ויש מסמכי שומה):
+   ```
+   mcp__legal-ai__extract_appraiser_facts(case_number="...")
+   ```
+   ⚠️ אם מחזיר `status="sides_missing"` → דווח לחיים שאין תיוג `appraiser_side` במסמכי השומה (`document_update` עם `appraiser_side` בערכים `committee`/`appellant`/`deciding`). עצור עד שיתוקן.
+
+   אם הטבלה כבר מלאה — `write_interim_draft` ידלג על ההרצה אוטומטית, אז גם בלי הצעד הזה זה יעבוד.
+
+3. **כתיבת 5 הבלוקים:**
+   ```
+   mcp__legal-ai__write_interim_draft(
+     case_number="...",
+     instructions="לבלוק ה (פתיחה): נוסח ניטרלי לחלוטין — 'לפנינו ערר על שומה מכרעת...' + הגדרות 'להלן' בלבד. אין לרמוז על תוצאת הדיון, אין מילות שיפוט, אין אזכור 'דין הערר להידחות/להתקבל'. רק זיהוי הצדדים, השומה המכרעת, המקרקעין והגורם המחליט."
+   )
+   ```
+   הכלי כותב ל-DB את בלוקים ה (פתיחה), ו (רקע), ט (תכניות+היתרים מורחב), ז (טענות), ח (הליכים). מחזיר `word_count` לכל בלוק.
+
+4. **ייצוא DOCX:**
+   ```
+   mcp__legal-ai__export_interim_draft(case_number="...")
+   ```
+   מייצר `data/cases/{case_number}/exports/טיוטת-ביניים-v{N}.docx`, מעדכן `active_draft_path`.
+
+5. **דווח לחיים** (כולל מייל דרך `scripts/notify.py`):
+   ```
+   ## טיוטת ביניים מוכנה — ערר {case_number}
+
+   📄 **קובץ:** `data/cases/{case_number}/exports/טיוטת-ביניים-v{N}.docx`
+
+   ### מה כלול
+   | בלוק | כותרת | מילים |
+   |------|-------|-------|
+   | ה | פתיחה (ניטרלית) | {N} |
+   | ו | רקע עובדתי | {N} |
+   | ט | תכניות + היתרים | {N} |
+   | ז | טענות הצדדים | {N} |
+   | ח | הליכים | {N} |
+   | **סה"כ** | | **{N}** |
+
+   ### סתירות שמאיות שזוהו
+   {אם יש — רשימה קצרה: "תכנית X — שמאי A קבע ..., שמאי B קבע ...". אם אין — "לא זוהו סתירות בין שמאים."}
+
+   ### מה הלאה
+   הטיוטה מוכנה לעבודה. כשתסיים לכתוב את בלוק י, חזור ב-comment ונמשיך
+   לשלב F (QA + ייצוא סופי).
+   ```
+
+6. **סטטוס issue הראשי:** עדכן ל-`in_review` (ממתין לחיים שיכתוב את בלוק י).
+
+**אזהרות:**
+- אל תייצא DOCX סופי (`export_docx`) — זה לא תחליף לטיוטת ביניים.
+- אל תפעיל את שלב B (סיכום + שאלת תוצאה) במקביל — חיים מחליט מתי לעבור לזרימה הראשית.
+- אם בלוק ח חסר (אין פרוטוקול דיון/סיור) — ציין זאת בדוח. הכלי כותב מה שיש, אבל המשתמש צריך לדעת אם חסר.
+
 ## מפת סטטוסים

 **סטטוסים של התיק (`cases.status`) — כל סטטוס מתאים לפעולה אחת בדיוק:**
@@ -592,22 +676,18 @@ case_prefix="${case_number:0:1}"

 0. **החזר את ה-issue הראשי ל-`status=in_progress`** — אם ה-issue ב-`in_review` (כי המתנת לחיים) או ב-`blocked` (כי Paperclip חסם אוטומטית), הראשון דבר: עדכן ל-`in_progress` כדי לסמן שאתה עובד עליו.

-1. **קרא את ה-comments האחרונים** על ה-issue שצוין ב-prompt:
+1. **קרא את ההקשר המלא** — issue + ancestors + project + goal + comments + attachments בקריאה אחת (ראה `HEARTBEAT.md §1.7`):
   ```bash
-   curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-     "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" | jq '[.[] | select(.authorUserId != null)] | .[-3:]'
+   CONTEXT=$(~/legal-ai/scripts/pc.sh GET "/api/issues/$ISSUE_ID/heartbeat-context")
   ```

-2. **בדוק attachments** — אם חיים ציין קובץ שהועלה:
+2. **בדוק attachments** — אם חיים ציין קובץ שהועלה, הוא כבר ב-`$CONTEXT.attachments`:
   ```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
-   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;"
+   echo "$CONTEXT" | jq '.attachments[] | {filename, contentPath, contentType, byteSize}'
   ```
-   נתיב מלא לקובץ: `/home/chaim/.paperclip/instances/default/data/storage/{object_key}`
+   נתיב מלא לקובץ: `/home/chaim/.paperclip/instances/default/data/storage/$(echo $CONTEXT | jq -r '.attachments[0].contentPath')`
+
+   ⚠️ **אסור** psql ישיר ל-`issue_attachments` — ה-API הוא ה-source of truth.

 3. **אם יש טיוטה/קובץ — קרא אותו מילה במילה.** חפש בתוכו:
   - הוראות עריכה (טקסט כמו "צריך לערוך", "להוסיף", "חסר", "הוראות כתיבה")
@@ -658,34 +738,35 @@ case_prefix="${case_number:0:1}"
 ## נתיבי API — חובה!

 ```bash
-# קרא comments על issue
-curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" | jq '.[-1].body'
+# קרא comments על issue (אבל בד"כ עדיף heartbeat-context — ראה HEARTBEAT.md §1.7)
+~/legal-ai/scripts/pc.sh GET "/api/issues/{issue-id}/comments" | jq '.[-1].body'

 # פרסם comment
-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": "..."}'
+~/legal-ai/scripts/pc.sh POST "/api/issues/{issue-id}/comments" '{"body": "..."}'

 # צור issue חדש (עם הקצאה לסוכן → מפעיל wakeup אוטומטי!)
-curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "Content-Type: application/json" \
-  "$PAPERCLIP_API_URL/api/companies/42a7acd0-30c5-4cbd-ac97-7424f65df294/issues" \
-  -d '{"title":"...","projectId":"25c1b4a1-2c0e-4a2d-9938-8ae56ccda6f1","assigneeAgentId":"{agent-id}","description":"...","status":"todo"}'
+~/legal-ai/scripts/pc.sh POST "/api/companies/42a7acd0-30c5-4cbd-ac97-7424f65df294/issues" \
+  '{"title":"...","projectId":"25c1b4a1-2c0e-4a2d-9938-8ae56ccda6f1","assigneeAgentId":"{agent-id}","description":"...","status":"todo"}'

 # עדכן issue
-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"}'
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'
+
+# צור interaction מובנה לחיים (ראה §B/§C למעלה למבנה payload)
+~/legal-ai/scripts/pc.sh POST "/api/issues/{issue-id}/interactions" '{"kind":"...","payload":{...}}'
+
+# קרא תשובת interaction (כשהתעוררת עם $PAPERCLIP_APPROVAL_ID)
+~/legal-ai/scripts/pc.sh GET "/api/issues/{issue-id}/interactions/$PAPERCLIP_APPROVAL_ID" | jq '.'
 ```

 **⚠️ agent JWT לא יכול להעיר סוכנים אחרים ישירות.** כדי להעיר סוכן → **צור issue חדש + הקצה אליו** (Paperclip מפעיל wakeup אוטומטי על assignment).

-חפש ב-comment של חיים:
- מספר (1/2/3) → בחירה
- "כיוון" + מספר → אישור כיוון
- טבלת טיפול בטענות → סימון claim_handling
- שאלה → ענה
- הערה → שלב בתהליך
+## מתי להשתמש בinteraction לעומת comment
+
+| מצב | פתרון |
+|------|--------|
+| נדרשת בחירה מובנית מחיים (תוצאה, כיוון, אישור) | **interaction** (`ask_user_questions` / `request_confirmation`) — UI עם כפתורים |
+| הצעת עץ משימות לאישור | **interaction** (`suggest_tasks`) |
+| עדכון סטטוס/תיעוד מסע (לא דורש פעולה) | **comment** רגיל |
+| הסבר ארוך + שאלת בחירה | **dual** — comment עם הסבר + interaction עם options (ראה §B) |
+
+**אסור:** "@chaim — ענה 1/2/3 בcomment". זה anti-pattern. תמיד interaction עם options.
--- a/.claude/agents/legal-exporter.md
+++ b/.claude/agents/legal-exporter.md
@@ -122,19 +122,11 @@ tools:

 **אם הכל עבר בהצלחה (כל בדיקות השלב הקודם עברו, אין כשל בפלט):**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'```

 **אם בדיקות נכשלו, חסר פלט, או חסר מידע קריטי:**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "blocked"}'```
 **אסור** לסיים `done` עם פלט חסר — אם משהו נכשל, סטטוס = `blocked` + comment עם פירוט.

 ### העֵר את העוזר המשפטי (CEO) — חובה!
@@ -146,11 +138,7 @@ else
  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"   # CMP — רישוי ובניה
 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"}}'
-```
+~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" '{"source":"automation","triggerDetail":"system","reason":"מייצא טיוטה סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-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`.

--- a/.claude/agents/legal-proofreader.md
+++ b/.claude/agents/legal-proofreader.md
@@ -92,19 +92,11 @@ tools:

 **אם הכל עבר בהצלחה:**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'```

 **אם נכשלו תיקונים קריטיים או יש markers `[?]` רבים:**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "blocked"}'```
 **אסור** לסיים `done` עם פלט חסר — אם נכשל, סטטוס = `blocked` + comment עם פירוט.

 ### העֵר את העוזר המשפטי (CEO) — חובה!
@@ -117,10 +109,6 @@ else
  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"   # CMP — רישוי ובניה
 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"}}'
-```
+~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" '{"source":"automation","triggerDetail":"system","reason":"מגיה סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-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`.
--- a/.claude/agents/legal-qa.md
+++ b/.claude/agents/legal-qa.md
@@ -79,6 +79,29 @@ tools:
 - סעיפים 1, 2, 3... ללא איפוס בין בלוקים
 - ללא כפילויות במספור

+### 7א. שלמות חיפוש בקורפוסים (corpus_queries_logged) — critical
+
+ה-analyst וה-researcher חייבים לתעד queries לקורפוסים שלהם. בלי תיעוד — אין דרך לוודא שתקדימי עליון רלוונטיים לא הוחמצו.
+
+בדוק:
+1. **קיום סעיף "שאילתות לקורפוסים"**:
+   - ב-`{case_dir}/documents/research/analysis-and-research.md` — סעיף **7א** (לפי שלב 5ד של ה-analyst)
+   - ב-`{case_dir}/documents/research/precedent-research.md` — סעיף **ז** (לפי שלב 2ב.4 של ה-researcher)
+   - אם חסר באחד מהם — `corpus_queries_logged = fail` (critical, חוסם המשך).
+
+2. **מספר queries מינימלי לקורפוס הסמכותי (`search_precedent_library`):**
+   - `analyst >= (מספר טענות סף + מספר סוגיות מרכזיות)`
+   - `researcher >= מספר סוגיות מרכזיות`
+   - חישוב: ספור את הסוגיות בסעיף 6 של `analysis-and-research.md`. מתחת לסף → `fail`.
+
+3. **negative evidence מתועד:** גם 0-result query חייבת להופיע. אם מצאת queries שכולן 0-result — לא fail; פשוט תיעוד שהקורפוס דליל בנושא.
+
+4. **אצליבה הצלבה (cross-check):**
+   - הרץ `mcp__legal-ai__precedent_library_list(practice_area=X, search="<keyword מרכזי מהתיק>")` עם practice_area של התיק.
+   - אם החזיר תוצאות שלא מופיעות בסעיף "נבחרו" או "נדחו" של ה-analyst/researcher → `corpus_queries_logged = warning` (לא חוסם, אבל דווח לחיים).
+
+חומרה: **critical** — בלי queries מתועדות אין דרך לאמת שלא הוחמצה הלכה מחייבת.
+
 ### 7. עמידה במתודולוגיה (methodology_compliance)
 ראה `docs/decision-methodology.md` לעקרונות המלאים. בדוק:
 - לכל סוגיה בבלוק י — ניתן לזהות מבנה סילוגיסטי: כלל + עובדות + מסקנה?
@@ -137,6 +160,7 @@ tools:
 | משקלות | warning | מדווח, לא חוסם |
 | כפילות | warning | מדווח, לא חוסם |
 | מספור | warning | מדווח, לא חוסם |
+| **שאילתות לקורפוסים** | **critical** | **חוסם ייצוא** |
 | מתודולוגיה | critical | חוסם ייצוא |
 | **קול דפנה** | **critical** | **חוסם ייצוא** |

@@ -173,19 +197,11 @@ tools:

 **אם הכל עבר בהצלחה (כל בדיקות השלב הקודם עברו, אין כשל בפלט):**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'```

 **אם בדיקות נכשלו, חסר פלט, או חסר מידע קריטי:**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "blocked"}'```
 **אסור** לסיים `done` עם פלט חסר — אם משהו נכשל, סטטוס = `blocked` + comment עם פירוט.

 ### העֵר את העוזר המשפטי (CEO) — חובה!
@@ -197,10 +213,6 @@ else
  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"   # CMP — רישוי ובניה
 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"}}'
-```
+~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" '{"source":"automation","triggerDetail":"system","reason":"בודק איכות סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-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`.
--- a/.claude/agents/legal-researcher.md
+++ b/.claude/agents/legal-researcher.md
@@ -85,22 +85,77 @@ tools:
   - **האם זה תקדם מהקאנון של דפנה?** (בדוק `docs/daphna-precedent-network.md` — אם כן, ציין שזה התקדם המועדף שלה לסוגיה)
 4. הפק הפניות (`extract_references`)

-### שלב 2ב: בדיקה מצטלבת מול הקאנון של דפנה
-אחרי שאספת את הפסיקה הרלוונטית בתיק:
-1. **לכל סוגיה משפטית** בתיק — בדוק ב-`daphna-precedent-network.md`:
-   - האם יש תקדם מועדף של דפנה לסוגיה?
-   - האם הוא הוצג בכתבי הטענות? אם לא — סמן כתקדם שיש להוסיף
-2. **תקדמים אישיים**: `search_decisions` בקטגוריה זהה לתיק. אם דפנה כבר הכריעה בסוגיה דומה:
-   - אם תוצאה דומה: תקדם לחיסכון דוקטרינרי ("כפי שקבענו ב-X")
-   - אם תוצאה הפוכה: ציין כי **חובה** הבחנה (distinguishing)
-3. **קורפוס פסיקה סמכותית**: `search_precedent_library` — חיפוש סמנטי בהלכות שאושרו ע"י דפנה (פסיקת עליון/מנהלי/ועדות ערר אחרות). מחזיר rule_statement + supporting_quote + citation מוכנים לציטוט בבלוק י. אם הצדדים הפנו לפסק דין שלא בקורפוס — הוסף אותו דרך `precedent_attach` (לתיק) או דרך ממשק ההעלאה ב-`/precedents` (לקורפוס הקבוע).
-4. **דווח** איזה תקדמים מהקאנון רלוונטיים, איזה תקדמים אישיים נמצאו, ואילו הלכות מהקורפוס הסמכותי תומכות.
+### שלב 2ב: חיפוש מובנה בשלושת הקורפוסים — חובה, עם תיעוד queries

-**שלושת המקורות — אל תבלבל:**
- `search_decisions` = החלטות דפנה (style_corpus).
- `search_precedent_library` = פסיקה חיצונית סמכותית עם הלכות מאושרות.
+**חובה לבצע** — לא הצעה. הניתוח קודם הראה (ערר 1200-25) שאם הקורפוס לא נסרק במפורש, מפספסים תקדימי עליון רלוונטיים שיושבים בו. ה-QA יחזיר `needs_revision` אם סעיף ה-queries חסר.
+
+**שלושת הקורפוסים — אל תבלבל:**
+- `search_precedent_library` = פסיקה חיצונית סמכותית עם הלכות מאושרות (עליון/מנהלי/ועדות ערר אחרות) + supporting_quote מוכן.
+- `search_decisions` = החלטות דפנה (style_corpus) — הקאנון האישי שלה.
 - `precedent_search_library` = ציטוטים שדפנה צירפה ידנית לתיקים בעבר (case_precedents).

+#### 2ב.1 — קורפוס סמכותי (`search_precedent_library`) — חובה
+
+לכל **סוגיה משפטית מרכזית** בתיק — הרץ לפחות שאילתה אחת עם פילטרים:
+
+| סיווג תיק | practice_area |
+|------------|---------------|
+| 1xxx (רישוי ובניה) | `rishuy_uvniya` |
+| 8xxx (היטל השבחה) | `histael_hashbacha` |
+| 9xxx (פיצויים ס' 197) | `pitsuim_197` |
+
+אם הסוגיה ב-`appeal_subtype` ידוע (כמו "שימוש חורג", "סטייה ניכרת") — הוסף `appeal_subtype` לפילטר.
+
+```
+search_precedent_library(
+  query="...",
+  practice_area="rishuy_uvniya",
+  appeal_subtype="שימוש חורג",
+  limit=10
+)
+```
+
+#### 2ב.2 — קאנון דפנה (`search_decisions`)
+
+לכל סוגיה — בדוק אם דפנה כבר הכריעה:
+- אם תוצאה דומה: תקדם לחיסכון דוקטרינרי ("כפי שקבענו ב-X")
+- אם תוצאה הפוכה: ציין כי **חובה** הבחנה (distinguishing)
+
+#### 2ב.3 — בדיקה מצטלבת מול `daphna-precedent-network.md`
+
+לכל סוגיה — בדוק במסמך:
+- האם יש תקדם מועדף של דפנה?
+- האם הוצג בכתבי הטענות? אם לא — סמן כתקדם שיש להוסיף.
+
+#### 2ב.4 — תיעוד מחייב — סעיף "שאילתות לקורפוסים" ב-`precedent-research.md`
+
+חובה להופיע סעיף בשם **"ז. שאילתות לקורפוסים — log מלא"** עם:
+
+```markdown
+## ז. שאילתות לקורפוסים — log מלא
+
+### קורפוס סמכותי (search_precedent_library)
+
+#### Q1 — סוגיה: [שם]
+- **שאילתה:** "..."
+- **פילטרים:** practice_area=..., appeal_subtype=...
+- **תוצאות:** N
+- **נבחרו:** [case_number] — headnote/למה רלוונטי
+- **נדחו:** [case_number] — למה לא
+- **0 results?** ציין מפורש + נמק
+
+#### Q2 — ...
+
+### קאנון דפנה (search_decisions)
+#### Q1 — ...
+```
+
+**negative evidence חובה:** גם 0 results נרשם. זה ההבדל בין "נסרק וריק" ל"לא נסרק".
+
+**מינימום:** queries לקורפוס הסמכותי = מספר סוגיות מרכזיות שזוהו.
+
+5. **דווח** איזה תקדמים מהקאנון רלוונטיים, איזה תקדמים אישיים נמצאו, ואילו הלכות מהקורפוס הסמכותי תומכות.
+
 ### שלב 3: מיפוי תכנית
 1. קרא הוראות התכנית **במלואן** — לא רק את הסעיף הנטען
 2. זהה סעיפים רלוונטיים למחלוקת
@@ -158,19 +213,11 @@ python3 /home/chaim/legal-ai/scripts/notify.py \

 **אם הכל עבר בהצלחה (כל בדיקות השלב הקודם עברו, אין כשל בפלט):**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'```

 **אם בדיקות נכשלו, חסר פלט, או חסר מידע קריטי:**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "blocked"}'```
 **אסור** לסיים `done` עם פלט חסר — אם משהו נכשל, סטטוס = `blocked` + comment עם פירוט.

 ### העֵר את העוזר המשפטי (CEO) — חובה!
@@ -182,11 +229,7 @@ else
  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"   # CMP — רישוי ובניה
 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"}}'
-```
+~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" '{"source":"automation","triggerDetail":"system","reason":"חוקר תקדימים סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-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`.

--- a/.claude/agents/legal-writer.md
+++ b/.claude/agents/legal-writer.md
@@ -210,19 +210,11 @@ case_update(case_number, status="drafted")

 **אם הכל עבר בהצלחה (כל בדיקות השלב הקודם עברו, אין כשל בפלט):**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "done"}'```

 **אם בדיקות נכשלו, חסר פלט, או חסר מידע קריטי:**
 ```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"}'
-```
+~/legal-ai/scripts/pc.sh PATCH "/api/issues/{issue-id}" '{"status": "blocked"}'```
 **אסור** לסיים `done` עם פלט חסר — אם משהו נכשל, סטטוס = `blocked` + comment עם פירוט.

 ### העֵר את העוזר המשפטי (CEO) — חובה!
@@ -234,11 +226,7 @@ else
  CEO_ID="752cebdd-6748-4a04-aacd-c7ab0294ef33"   # CMP — רישוי ובניה
 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"}}'
-```
+~/legal-ai/scripts/pc.sh POST "/api/agents/$CEO_ID/wakeup" '{"source":"automation","triggerDetail":"system","reason":"כותב החלטה סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-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`.