legal-ai/docs/spec/X4-agents.md

X4 — מפת הסוכנים (Agents Map)

קובץ-תחום זה כפוף ל-חוקת המערכת והוא ה-deep-dive על מי הם הסוכנים של עוזר משפטי, מה תפקיד כל אחד, ואילו קבצי-ספ כל סוכן חייב לקרוא לפני שהוא פועל. הוא מסייע לסוכן לדעת באיזה ספ לקרוא — ומעגן את G10 (המערכת מסייעת; השערים האנושיים הם invariant): כל סוכן קורא את החוקה תחילה ופועל בתחום-אחריותו, לא מחליף את שיקול-הדעת האנושי.

invariant פרויקטלי-תפעולי. ה-invariants כאן הם עובדות על איך הסוכנים של המערכת הזו מאורגנים ומופעלים — לא תאוריה הנדסית כללית ולא תוכן משפטי. אין סמכות חיצונית ל"מי קורא מה לפני שהוא פועל"; לכן הם נושאים שדה מקור-סמכות = הראנבוקים וקבצי-הסוכן של הפרויקט עצמו (HEARTBEAT.md, קבצי הסוכן תחת .claude/agents/, ו-החוקה) — לא ≥3 מקורות חיצוניים וללא סטטוס verified/UNVERIFIED. אבל כל invariant נקשר לעיקרון הגלובלי שהוא משרת: כלל "קרא-לפני-שתפעל" + תחום-אחריות הם מופע של G10 (סיוע תחת שערים אנושיים) ו-G2.

---

1. ההפעלה המשותפת — HEARTBEAT.md

לפני כל עבודה, כל סוכן Paperclip עובר את ה-checklist המשותף ב-HEARTBEAT.md: זיהוי וסינון-חברה (§1), קריאת comments אחרונים (§1.5, 2b–2c), קריאת heartbeat-context עם attachments (§1.5ב), וקריאות-API דרך pc.sh בלבד (§0). HEARTBEAT גובר על ה-skill הרשמי של Paperclip בקונפליקט (project-specific מנצח default), אך אינו מחליף את החוקה — הוא מצטרף אליה: קודם החוקה (00) + ספ-התחום, אז ה-HEARTBEAT התפעולי.

הקשר רב-חברתי. ל-Paperclip אילוץ agents.company_id NOT NULL — אין סוכן משותף. לכן כל אחד מ-7 תפקידי הסוכן-הדומייני מיוצג בשתי רשומות (CMP / CMPA), וסוכן מטפל רק בתיקי-החברה שלו לפי $PAPERCLIP_COMPANY_ID (1xxx ל-CMP; 8xxx/9xxx ל-CMPA). ראה X2-multi-company.md.

---

2. מפת הסוכנים הדומייניים (7 תפקידים × 2 חברות)

הסט המדויק (ls .claude/agents/): HEARTBEAT.md, hermes-curator.md, legal-analyst.md, legal-ceo.md, legal-exporter.md, legal-proofreader.md, legal-qa.md, legal-researcher.md, legal-writer.md. התפקיד נלקח מה-frontmatter של כל קובץ; עמודת "ספ לקרוא" מקשרת תפקיד לקבצי-הספ שהוא אוכף/צורך.

סוכן (קובץ)	תפקיד (מה-frontmatter)	ספ-תחום לקרוא לפני פעולה
legal-ceo.md	מנהל תהליך כתיבת החלטות, מתזמר סוכנים, מפקח על התקדמות	00 + כל הספ (מתזמר → צריך תמונה מלאה); ניתוב comments → X3 §1ב
legal-proofreader.md	מגיה — תיקון שגיאות OCR בטקסט עברי לפני ניתוח	01-ingest.md (קליטה/טקסט-מחולץ)
legal-researcher.md	חוקר תקדימים — פסיקה, מיפוי תכניות, סיכום פרוטוקולים	03-retrieval.md (3 קורפוסים, hybrid/RRF, attribution); קליטת-פסיקה → 01-ingest.md
legal-analyst.md	מנתח משפטי — חילוץ טענות, ניתוח אסטרטגי, שאלות מחקר	02-data-model.md + 03-retrieval.md + 04-analysis-writing.md
legal-writer.md	כותב — כתיבת בלוקי ההחלטה בסגנון דפנה תמיר	04-analysis-writing.md + 05-qa-review.md (כותב מול שערי-QA)
legal-qa.md	בודק איכות — שלמות, ניטרליות, כיסוי טענות, משקלות לפני ייצוא	05-qa-review.md (שערי QA + שערים אנושיים)
legal-exporter.md	מייצא — בדיקה סופית, ייצוא DOCX, שמירה מגורסת	06-export.md (ייצוא DOCX לפי תבנית דפנה)
hermes-curator.md	Knowledge Curator (Hermes) — מנתח החלטות סופיות post-export, מציע עדכוני skills/lessons; read-only על תוכן, write רק על comments	07-learning.md (Hermes · לקחים · לולאת פידבק)

הערות על הסט:

• CEO = נקודת-הניתוב היחידה. תגובת-משתמש על issue מעירה את ה-CEO; הוא מחליט ניתוב ויוצר issue לסוכן-המשנה — סוכן-משנה לא מקבל עבודה ישירות מ-comment (X3 §1ב).
• Hermes — חיבור ישיר, לא דרך CEO. מופעל מ"סמן כסופי" ב-UI (mark-final → pc_wake_curator_for_final()), לא מ-CEO; ופועל על מודל deepseek_local (לא Claude Code) — ראה X2 INV-MC1 למלכודת ה-adapter_type-skip בסנכרון. הצעות ה-curator עוברות אישור-יו"ר ידני לפני commit ל-SKILL.md/lessons.md — מופע של G10.
• company_id פר-סוכן. כל שורה בטבלה מיוצגת פעמיים (CMP + CMPA); ה-CEO לכל חברה שונה (X2 §1). הסוכן פועל רק בטווח-החברה שלו (X2 §2).

2א. מפת-הרשאות (tool grants) — frontmatter מול הוראות

כל קובץ-סוכן מצהיר ב-frontmatter tools: (כולם: Read/Bash/Grep/Glob + תת-קבוצת mcp__legal-ai__*). מפת-ההרשאות חייבת לתאום את מה שהוראות-הסוכן מצריכות (X9 INV-TOOL6, INV-AG3 להלן).

סטטוס FU-13 — נסגר (2026-06-06): GAP-46 טופל בהכרעת-יו"ר "היבריד". התברר שהפער שמופה ב-31.5 היה רחב מדי — הכלים יוחסו לפי תיאור-התפקיד, לא לפי ההוראות בפועל. ההכרעה:

סוכן	מצב בפועל	פעולה ב-FU-13
legal-researcher	כבר מעניק extract_references + precedent_extract_halachot/precedent_extract_metadata/precedent_process_pending (frontmatter)	✅ אין פער — היה מיושן
legal-analyst	חסר aggregate_claims_to_arguments; הוראותיו לא השתמשו בו	✅ נוסף ל-frontmatter + שלב 7 ב-"שלב 1" (קיבוץ טענות→טיעונים)

extract_references / extract_internal_citations הם מטלת-מחקר (חילוץ ציטוטים/רפרנסים) ושייכים ל-legal-researcher (שמחזיק אותם) — לא ל-legal-analyst, שמאמת פסיקה דרך חיפוש (§8א בקובץ-הסוכן), לא חילוץ. לכן הוסרו מרשימת "החסרים" של ה-analyst (INV-AG3 "לא עודף").

→ gap-audit GAP-46.

---

3. סוכני-התהליך (תת-פרויקט 5) — סעיף שמור (RESERVED)

סטטוס: מתוכנן, טרם נבנה. הסעיף הזה הוא מקום שמור מכוון עבור סוכני-התהליך שיוגדרו בתת-פרויקט 5 — הם אינם קיימים כיום ואין לטעות בהם כמופעלים. הם מתועדים כאן כדי שהמפה תהיה שלמה ושכיוון-העבודה יהיה ברור, לא כ-TODO פתוח.

בניגוד לסוכנים הדומייניים (סעיף 2) שמטפלים בתיקי-עררים, סוכני-התהליך הם סוכנים שיקראו את ספ-המערכת (קבצי 00–07, X1–X5) ו"יעשו את שיעורי-הבית" — יפעלו על המערכת עצמה, לא על תיק. שלושה תפקידים מתוכננים:

סוכן-תהליך (מתוכנן)	תפקיד מיועד
add-feature	הוספת יכולת חדשה — קורא את הספ הרלוונטי, מאתר את ה-invariants שחלים, ומיישם בלי לשבור G1–G11
fix-feature	תיקון תקלה — מאתר את ה-invariant שהופֵר (מול audit-report.md) ומתקן במקור, לא בתסמין
spec-guardian	שמירת עקביות הספ — מאתר drift בין הקוד לספ ובין קבצי-הספ עצמם; סתירה = ממצא ל-audit

ההגדרה המלאה (frontmatter, tools, instructions, מיפוי תפקיד→ספ, ושערי-האישור) תיכתב בתת-פרויקט 5. עד אז — אין רשומות-סוכן, אין wakeup, ואין הסתמכות עליהם בזרימה.

---

4. Invariants של התחום (פרויקטלי-תפעולי)

INV-AG1: כל סוכן קורא את החוקה תחילה, אז את ספ-התחום הרלוונטי — לפני פעולה

כלל: כל סוכן (דומייני או תהליך) חייב לקרוא את 00-constitution.md תחילה, ואז את ספ-התחום הרלוונטי לתפקידו (לפי הטבלה בסעיף 2), לפני שהוא פועל. ה-checklist המשותף ב-HEARTBEAT מתבצע בכל ריצה; קריאת-הספ קודמת לעבודה המהותית. סוכן אינו פועל "מהזיכרון" — המקור הקנוני להתנהגות הוא החוקה + ספ-התחום (מופע של G10 — המערכת מסייעת תחת שערים אנושיים, והסוכן פועל בגבולות שהחוקה מגדירה). מקור-סמכות: HEARTBEAT.md (checklist הפעלה משותף) + קבצי-הסוכן תחת .claude/agents/ (frontmatter + instructions) + 00-constitution.md §7 (אינדקס הספ — איזה קובץ אוכף איזה invariant). (invariant פרויקטלי-תפעולי — ללא פרוטוקול ≥3-המקורות; משרת את העיקרון הגלובלי G10.) אכיפה: נוהל — מחוּוט (FU-8b, 2026-05-31): סעיף "קריאת-ספ — קודם החוקה (00), אז ספ-התחום" ב-HEARTBEAT.md (כולל טבלת תפקיד→ספ) + סעיף "קרא לפני פעולה (INV-AG1)" בכל אחד מ-8 קבצי-הסוכן. אכיפה פרוצדורלית (נוהל לפני עבודה), לא אוטומטית: אין שער-קוד שמכריח את הקריאה — זה גלום בטבע ה-invariant (פרויקטלי-תפעולי, מבוצע ע"י הסוכן). ראה §5. הפרה ידועה: —

INV-AG2: סוכן דומייני פועל רק בתחום-החברה שלו

כלל: סוכן דומייני מטפל רק בתיקי-החברה שלו לפי $PAPERCLIP_COMPANY_ID (CMP→1xxx; CMPA→8xxx/9xxx). אסור ליצור פרויקט/issue/תוכן לתיק מחוץ לטווח; issue מחוץ-לטווח → סירוב מנומס ב-comment + העֵרת ה-CEO של החברה הנכונה (מופע של G2 — הפרדה נאכפת לפי company_id, אין מסלולים חוצי-חברה מתפצלים; ראה X2 §2). מקור-סמכות: HEARTBEAT.md §1 (סינון-חברה — כלל-ברזל) + קבצי-הסוכן (סעיף "סינון תיקים לפי חברה") + X2-multi-company.md §2. (invariant פרויקטלי-תפעולי — ללא פרוטוקול ≥3-המקורות; משרת את העיקרון הגלובלי G2.) אכיפה: סינון-חברה ב-HEARTBEAT + גבול-חברה נאכף בצד-Paperclip (Agent key cannot access another company, X2 §2). הפרה ידועה: —

INV-AG3: מפת-ההרשאות תואמת את הוראות-הסוכן — לא חסר ולא עודף

כלל: ה-frontmatter tools: של כל סוכן מעניק בדיוק את הכלים שהוראותיו דורשות — כל כלי שההוראות מצריכות מוענק, וכלי שמוענק-ולא-בשימוש נבחן. מופע של G10 (שערים מוגדרים) ו-G2; מקביל ל-X9 INV-TOOL6. מקור-סמכות: frontmatter tools: מול ה-instructions בקבצי-.claude/agents/. (פרויקטלי-תפעולי.) אכיפה: בדיקת-עקביות tools↔instructions (FU-13 ✅ 2026-06-06). אכיפה אוטומטית עתידית — בתת-פרויקט 5 (spec-guardian). הפרה ידועה: — (טופל ב-FU-13: legal-analyst קיבל aggregate_claims_to_arguments; researcher כבר היה תקין; extract_references/extract_internal_citations הם מטלת-researcher, לא analyst — ראה §2א).

---

5. חיווט הספ לסוכנים — בוצע (FU-8b)

עד FU-8b קבצי-הסוכן וה-HEARTBEAT לא הפנו לספ-המערכת במפורש; הם הפנו ל-CLAUDE.md, למסמכי-docs/ הישנים, ול-skills. בוצע ב-2026-05-31 (FU-8b / GAP-23):

• HEARTBEAT.md: נוסף סעיף עליון "קריאת-ספ — קודם החוקה (00), אז ספ-התחום — לפני פעולה מהותית (INV-AG1)", לפני §0–§8 התפעוליים, ובו טבלת תפקיד→ספ (זהה לסעיף 2 כאן). זה ממקם את קריאת-החוקה קודם ל-checklist ההפעלה ("קודם החוקה (00) + ספ-התחום, אז ה-HEARTBEAT התפעולי").
• 8 קבצי-הסוכן: כל אחד קיבל סעיף "קרא לפני פעולה (INV-AG1)" בראש גוף-הקובץ — קריאת 00-constitution.md תחילה, ואז ספ-התחום הרלוונטי לתפקידו (לפי הטבלה בסעיף 2).
• אופי האכיפה: פרוצדורלית (נוהל), לא שער-קוד — ראה INV-AG1 "אכיפה".

זהו תנאי-מוקדם לסוכני-התהליך (סעיף 3), שכל עבודתם היא "לקרוא את הספ ולעשות שיעורי-בית".

---

6. הפניות-אחיות

• 00-constitution.md — G10 (שערים אנושיים) + G2 (מקור-אמת/הפרדה) + §7 אינדקס הספ.
• X2-multi-company.md — 14 סוכנים = 7 × 2, company_id פר-סוכן, כללי sync.
• X3-integration-deploy.md — wakeup, ניתוב comments דרך CEO, webhooks.
• ספ-התחום שכל סוכן צורך: 01-ingest.md, 02-data-model.md, 03-retrieval.md, 04-analysis-writing.md, 05-qa-review.md, 06-export.md, 07-learning.md.
• .claude/agents/HEARTBEAT.md + קבצי-הסוכן תחת .claude/agents/ — frontmatter (תפקיד) + instructions (סינון-חברה, זרימה).
• X9-mcp-tool-contract.md — חוזה-הכלים שההרשאות (INV-AG3 / §2א) מעניקות.
• skills/ — 5 skills (decision, assistant, docx, dafna-decision-template, new-company-setup); עקביות-skills↔סוכן + dedup → FU-13.