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).
• שטן-מליץ (Gemini red-team) — שער-קבע אחרי הניתוח, לא חלק מ-7-הדומייניים. סוכן legal-analyst-gemini-critique (gemini_local, CMP+CMPA) רץ אחרי שלב-הניתוח של ה-Case Analyst (Opus) ולפני הכותב, כשער-קבע (standing gate) שה-CEO מפעיל אוטומטית — לא on-demand. הוא read-only ומפיק critique-gemini.md = מזכר-לידים לא-סמכותי. ה-CEO עוצר את הזרימה לאישור-יו"ר של הלידים (ה-issue הראשי ל-in_review); רק לידים שהיו"ר מאשר מומרים ל-chair_directions (דרך מנגנון-ההנחיות הקיים — record_chair_feedback → get_chair_directions → approve_direction), והכותב צורך רק את פלט-המנתח המעוגן + ההנחיות-המאושרות — לעולם לא את הלידים הגולמיים. מקיים INV-AG4 + 04-analysis-writing §1.6. מקור-אמת לזרימה: legal-ceo.md "שלב A2"/"שלב A3" + legal-analyst-gemini-critique.md.

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 הוא allow-list סגורה. כלי הרשום בשרת-ה-MCP אך חסר מהרשימה אינו ניתן לקריאה ע"י הסוכן — גם כשהשרת מחובר לחלוטין. הסוכן חווה זאת כ"הכלים לא נחשפים לסשן", ובלי הבנת המנגנון הוא נוטה לעקוף (SQL ישיר, סקריפט מקומי) במקום לדווח — וזה מסלול מקביל, כלומר הפרת G2. "מורים להריץ" כולל את ה-backend: טקסט של issue שנוצר ב-web/ ומכיל mcp__legal-ai__X הוא הוראה לכל דבר, ולכן מחייב הענקה.

מקור-סמכות: frontmatter tools: מול ה-instructions בקבצי-.claude/agents/ ומול הוראות-ה-backend ב-web/. (פרויקטלי-תפעולי.) אכיפה: ✅ אוטומטית מ-2026-08-04 — scripts/agent_tool_grants_guard.py, שער-CI קשיח (.gitea/workflows/agent-tool-grants.yaml), בדפוס leak_guard.py של G12. ארבעה כללים: (1) כל mcp__legal-ai__X ב-web/ מוענק לסוכן כלשהו · (2) כל mcp__legal-ai__X בגוף קובץ-סוכן מוענק באותו קובץ · (3) אין הענקה לכלי שאינו רשום בשרת · (4) שם-כלי בגרשיים-הפוכים ללא תחילית — מוענק, או מסווג מפורשות ב-CONTRASTIVE_OK (אזכור ניגודי / מטלת-סוכן-אחר / שם-עמודה מתנגש). לא-סוכנים ולכן מוחרגים: hermes-curator.md ו-legal-analyst-gemini-critique.md (בלי frontmatter בכוונה — האדפטר שולח פרומפט גולמי) ו-HEARTBEAT.md (checklist משותף). הפרה ידועה: — (היסטוריה: FU-13 ✅ 2026-06-06 — aggregate_claims_to_arguments ל-analyst; extract_references/extract_internal_citations הם מטלת-researcher, ראה §2א. הישנות 2026-08-04 — האכיפה הידנית לא החזיקה: analyze_protocol (‏24e3e2f, 2026-06-30) נרשם בשרת בלי הענקה, ו-#226 הוסיף delegation שמורה למנתח להריץ אותו → CMP-229 נשרף בשתי הרצות ועקף ל-SQL ידני. נסגר יחד עם get_protocol_analysis/get_legal_arguments/get_appraiser_facts ו-precedent_library_list ל-QA, והאכיפה הועברה ל-CI כדי שלא תישען שוב על משמעת ידנית.)

INV-AG4: שער שטן-מליץ — red-team לידים לא-סמכותיים תחת אישור-יו"ר

כלל: אחרי שלב-הניתוח (analysis-and-research.md תקין) ובלפני הפעלת הכותב, ה-CEO מפעיל אוטומטית את סוכן שטן-מליץ (Gemini red-team, read-only) כשער-קבע — לא on-demand. הפלט (critique-gemini.md) הוא מזכר-לידים לא-סמכותי; ה-CEO עוצר את הזרימה לעצירת-אישור קשיחה של היו"ר (issue ראשי ל-in_review + מייל) ואינו מתקדם לכותב בלי הכרעת-יו"ר מפורשת. רק לידים שהיו"ר אישר מומרים ל-chair_directions דרך מנגנון-ההנחיות הקיים (record_chair_feedback → get_chair_directions → approve_direction); לידים שנדחו נמחקים. הכותב צורך אך-ורק את פלט-המנתח המעוגן + ההנחיות-המאושרות — לעולם לא את הלידים הגולמיים. מופע של G10 (שער אנושי לא-עקיף) ושל INV-AH / INV-LRN5 (לידים לא-סמכותיים, אינם מוזנים אוטומטית לקול/למהות). מקור-סמכות: legal-ceo.md ("שלב A2"/"שלב A3" + "מפת סטטוסים") + legal-analyst-gemini-critique.md

• HEARTBEAT.md §7. (invariant פרויקטלי-תפעולי — ללא פרוטוקול ≥3-המקורות; משרת את G10 + INV-AH/INV-LRN5.) אכיפה: פרוצדורלית (נוהל ה-CEO — "אל תמשיך לכותב בלי critique-gemini.md + אישור-יו"ר ללידים")
• עצירת-in_review של ה-issue הראשי; אין שער-קוד אוטומטי (כמו יתר ה-INV-AG*). הפרה ידועה: — (שינוי-מדיניות יו"ר 2026-06-30: שטן-מליץ עבר מ-on-demand ל-שער-קבע; TaskMaster legal-ai #211).

---

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.