Chaim
37c56ff22a
Extends the system spec beyond the core pipeline to the 8 surfaces outside it: - X6 UI↔API contract + design rules (INV-UI1..6) - X7 Paperclip client & connection params (INV-INT4..8) - X8 field-population & extraction provenance (INV-FP1..5) - X9 MCP tool contract — 71 tools (INV-TOOL1..6) - X10 deploy/env/secrets (INV-ENV1..5) - ui-audit.md — page-by-page UI audit (13 pages) - 02-data-model: derived-entity invariants (INV-DM4..6) - X4-agents: tool-grant map + INV-AG3 - gap-audit: GAP-24..62 → FU-9..15; cycle-1 (FU-1..8b) marked done - constitution §7 + README index (X1..X10) Planning/spec artifacts only — no application code. All engineering invariants backed by ≥3 sources; every finding carries verified file:line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
16 KiB
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 להלן).
פערים שנמצאו (אומת 31.5.2026 — legal-analyst.md לא מעניק את 3 הכלים; תיקון ב-FU-13):
| סוכן | כלי-חילוץ שההוראות דורשות אך לא מוענקים |
|---|---|
| legal-analyst | aggregate_claims_to_arguments, extract_references, extract_internal_citations |
| legal-researcher | precedent_extract_halachot, precedent_extract_metadata, precedent_process_pending |
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). כיום אין.
הפרה ידועה: legal-analyst חסר aggregate_claims_to_arguments/extract_references/extract_internal_citations; researcher חסר טריגרי-חילוץ (§2א; gap-audit GAP-46).
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.