legal-ai/CLAUDE.md

עוזר משפטי — Legal Decision Assistant

אינדקס דק. הכללים הקריטיים נמצאים כאן; העומק התפעולי (Deploy, Paperclip-ops, adapters, מבנה-תיקיות, Chair-Feedback, עבודה מול Gitea Issues) הוצא ל-docs/operations-runbook.md כדי לרזות את ההקשר הנטען בכל סשן.

רקע הפרויקט

מערכת AI לסיוע בכתיבת החלטות של ועדת ערר לתכנון ובניה, מחוז ירושלים, בראשות עו"ד דפנה תמיר.

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

שלושה סוגי עררים

סוג	מספרי תיקים	טון	מאפיין
רישוי ובנייה	1xxx	חם יחסית	הקשר תכנוני רחב, אלמנטים אנושיים
היטל השבחה	8xxx	קר ומקצועי	יבש, ללא רגשות
פיצויים (ס' 197)	9xxx	קר ומקצועי	דומה להיטל השבחה

מבנה מספר-תיק (נוהל-יו"ר 2026-06-11): <סידורי>-<חודש>-<שנה>. אורך הסידורי = סוג-הליך: 4 ספרות → ערר, 5 ספרות → בל"מ (85074-09-24). הספרה הראשונה עדיין קובעת תחום בשני האורכים. כלל חד-כיווני: 5-ספרתי הוא תמיד בל"מ; 4-ספרתי אינו מחייב ערר (בל"מ-מורשת מזוהה מהנושא). מקור-אמת: docs/spec/X1-identifiers.md §1א.

מטרת המערכת

כלי עבודה שמסייע ליו"ר הוועדה: ניהול תיקים (ייבוא, סיווג, מעקב סטטוס) · בסיס ידע (פסיקה, ביטויי מעבר, לקחים, חקיקה) · חיפוש סמנטי (RAG) · סיוע בכתיבה (טיוטות לפי 12 בלוקים בסגנון דפנה) · ייצוא DOCX.

⭐ יעד-העל: רכישת-הסגנון של דפנה (Style Acquisition)

היעד הראשי של המערכת הוא שהסוכנים יכתבו וינתחו עררים בדיוק כמו עו"ד דפנה תמיר — לא רק לייצר טיוטה תקנית, אלא להפנים את הקול והשיטה שלה. זה מחייב הפרדה מובהקת בין שתי תת-מערכות:

1. מערכת-הכתיבה (Writing) — מייצרת טיוטות (analyst/writer/qa/ceo). צרכן read-only של artifacts-הקול.
2. מערכת רכישת-הסגנון (Style Acquisition) — לומדת איך דפנה כותבת מכל זוג "טיוטה שלנו → סופי שלה", ומזינה חזרה את מערכת-הכתיבה. היחידה שכותבת ל-artifacts-הקול — תמיד דרך שער-יו"ר (INV-G10).

הגישה (state-of-the-art לדאטה-מועט): Text Style Transfer מבוסס Authorial Style Profiling — להכליל את סגנון דפנה ולהתאים לתיק. העתקת פסקאות מותרת לתוכן קבוע/נוסחאי; ניתוח ספציפי → להכליל; מהות משפטית (הלכה/עובדה) — אסור להעתיק מתיק לתיק. לא fine-tuning של משקולות (Opus סגור; קורפוס קטן מדי).

כלל-העל — INV-LRN4: כל החלטה אינה "סגורה" עד שהושוותה מול הגרסה הסופית של דפנה; כל סופי מנותח מול הטיוטה. INV-LRN5: שכבת-ידע-הקול לא תכיל מהות ספציפית — רק סגנון ושיטה. ספ מלא: docs/spec/07-learning.md §0. ארכיטקטורה ומשימות: תוכנית style-acquisition-subsystem.

Legacy: המערכת הקודמת היתה Obsidian vault עם Claude Code skills. הידע שהופק ממנה (ניתוח סגנון, 12 בלוקים מבוססי CREAC/DITA/Akoma-Ntoso/FJC, כללי כתיבה, לקחים, ייצוא DOCX) הוטמע בפרויקט הנוכחי (docs/, data/training/). ה-vault נמחק; כעת PostgreSQL + pgvector.

---

מסמכי ייחוס

מסמך	תוכן	מתי לקרוא
docs/spec/00-constitution.md	חוקת המערכת — ייעוד, 11 invariants גלובליים (G1–G11), כללי-הנדסה, אינדקס-ספ	לפני כל כתיבת/שינוי קוד (ראה §פרוטוקול כתיבת-קוד)
docs/spec/README.md	אינדקס ספ-המערכת — מחזור-חיים (01–07) + חוצי-שלבים (X1–X11). מקור-האמת ל"מהו תקין"	לפני כל כתיבת/שינוי קוד
docs/spec/gap-audit.md	מפת-פערים — 62 ממצאים → 15 יחידות-תיקון (FU); invariant מופר + file:line + תיקון מוצע	לפני נגיעה ב-GAP/FU קיים או תכנון FU חדש
docs/ia-audit-redesign.md + docs/spec/X17	אבחון משטח-ההפעלה + IA-יעד — 34 משטחים, 37 ממצאים; INV-IA1–IA6 (מקור-אמת יחיד/שער-אחד/ניווט-משימה) מרימים G2/G10 לשכבת-UI. גלי-איחוד #130–132	לפני עבודה על דפים/ניווט/cache או תורי-אישור
docs/architecture.md	ארכיטקטורת המערכת, תרשים רכיבים, זרימת נתונים, 4 שכבות DB	לפני עבודה על תשתית
docs/block-schema.md	הגדרת 12 בלוקים — content model, constraints, processing params	לפני כל כתיבת החלטה
docs/migration-plan.md	תוכנית מעבר vault → DB — טבלאות, עדיפויות, כמויות	לפני ייבוא נתונים
docs/legal-decision-lessons.md	לקחים מ-3 החלטות — מה עבד, מה השתנה, ביטויי מעבר חדשים	לפני כל כתיבת החלטה
docs/decision-methodology.md	מתודולוגיה אנליטית — איך לחשוב על החלטה מעין-שיפוטית	לפני כל כתיבת החלטה
docs/anti-hallucination-gate.md	שער anti-hallucination משותף (INV-AH) — 5 טכניקות מעוגנות-מקור (עיגון-מקור, quote-or-retract, abstention, תיוג-ודאות, CoVe). מקור-אמת אחד לכל הסוכנים	לפני כל אזכור פסיקה/חוק/הלכה/מספר
docs/garner-methodology-extraction.md	חומר מקור: מיצוי מספרי Garner על כתיבה משפטית	רק לבדיקת מקור
docs/fjc-principles-extraction.md	חומר מקור: מיצוי מ-Judicial Writing Manual (FJC)	רק לבדיקת מקור
docs/corpus-analysis.md	ניתוח שיטתי של 24 החלטות — מפת תוכן, דפוסי דיון תכנוני, פערים	לפני כל כתיבת החלטה
docs/product-specification.md	איפיון מוצר מלא — personas, תהליכים עסקיים, דרישות	להתמצאות עסקית/מוצרית
docs/new-company-setup-guide.md	מדריך הקמת חברה חדשה (CMPA) — skills, corpus, style analysis	לפני הוספת חברה/סוג ערר חדש
skills/new-company-setup/SKILL.md	Blueprint טכני מלא להוספת חברה — 11 שלבים מסודרים (companies, agents, runtime/adapter, skills, instructions, code, mappings) + checklist 10 מלכודות מ-Gap analysis #16-#28	חובה לפני הוספת חברה (יותר actionable מ-doc)
docs/audit-report.md	דוח audit של המערכת	רקע כללי
docs/case-migration-tracker.md	מעקב מיגרציה של תיקים קיימים	לצורך מעקב
docs/case-deletion-runbook.md	runbook מלא למחיקת תיק — legal-ai DB + disk + Paperclip + Gitea, FK ordering, fallback ל-SQL ישיר	לפני reset שלם של תיק (מבחן, מחיקה בטעות)
docs/paperclip-quirks.md	מלכודות ידועות ב-Paperclip — issue.released ש-flips done→todo, bash backtick trap, CEO auto-block, wakeup דרך DB	לפני שמייחסים באג בסוכן ל-skill — לבדוק קודם אם זה Paperclip-side
docs/decision-block-mapping.md	מיפוי בלוקים להחלטות — איך 12 הבלוקים משתקפים ב-DOCX	להתמצאות במבנה
docs/memory.md	הקשר כללי — skills, פרויקטים שהושלמו, מבנה vault	להתמצאות כללית
skills/decision/SKILL.md	מדריך סגנון מלא של דפנה — טון, מבנה, ביטויים, מתודולוגיה	לפני כל כתיבת החלטה
.claude/agents/HEARTBEAT.md	checklist הפעלת סוכן — routing, company filtering, quirks, wakeup עם UUID נכון	לפני כל עבודה על סוכנים
skills/dafna-decision-template/SKILL.md	export DOCX לפי styles של תבנית Word של דפנה — line classification, dash policy, placeholder handling	לפני export DOCX
docs/corpus-graph.md	מפת הקורפוס (/graph) — גרף ציטוטים אינטראקטיבי נייטיב; 6 שכבות (פסיקה/נושא/תחום/הלכות/חוסרי‑מחקר/יומונים), אנליטיקה (PageRank/אשכולות), endpoints, ואיך מוסיפים שכבה	לפני עבודה על דף /graph או web/graph_api.py
docs/taskmaster-to-gitea-migration.md	מיגרציית ניהול-המשימות — TaskMaster→Gitea Issues (2026-08-05), טבלת מיפוי מלאה, ומלכודת המספור בהפניות (#N) ישנות	כשנתקלים בהפניה (#N) בקומיט ישן, או כשמחפשים משימה שהייתה ב-TaskMaster
docs/operations-runbook.md	עומק תפעולי — Deploy (Coolify/pm2), Paperclip-ops מלא (wakeup, sync, webhook, scheduled jobs, adapters), מבנה-תיקיות, Chair-Feedback, Gitea Issues API	לפני עבודה על Deploy / אינטגרציית-Paperclip / adapters

---

פרוטוקול כתיבת-קוד — קודם הספ ⚠️

כלל-על. המקור הקנוני ל"מהו תקין הנדסית" הוא ספ-המערכת תחת docs/spec/ — לא הרגלים, לא "הקוד הקיים נראה ככה". כל קוד שנכתב בלי לעבור דרך הספ מסתכן בהחזרת כשל-השורש שהספ בא לייבש: מסלולים/קורפוסים מקבילים שמתפצלים (drift). זהו המקבילה האינטראקטיבית ל-INV-AG1 שכבר אוכף על סוכני Paperclip (HEARTBEAT.md §"קריאת-ספ").

לפני יצירה/שינוי של קוד ב-web/, mcp-server/, web-ui/, scripts/:

1. קרא docs/spec/00-constitution.md — ייעוד, ה-invariants הגלובליים G1–G12, וכללי-ההנדסה (§6). אינדקס-הספ ב-§7.
2. קרא את ספ-התחום הרלוונטי לפי האינדקס (§7) — לדוגמה: אחזור→03-retrieval.md, קליטה→01-ingest.md, נתונים→02-data-model.md, כלי-MCP→X9-mcp-tool-contract.md, UI↔API→X6-ui-api-contract.md, Paperclip/שער-הפלטפורמה→X3/X7/X15 (G12), עמידות-פייפליין→X16, env/secrets→X10-deploy-env-secrets.md.
3. ודא שהשינוי מקיים את ה-invariants — לא יוצר מסלול מקביל ליכולת קיימת (G2), לא מתקן תסמין בקריאה במקום נרמול במקור (G1), לא בולע שגיאות בשקט (כלל-הנדסה §6).
4. בדוק מול gap-audit.md — אם אתה נוגע ב-GAP/FU שכבר ממופה, התאם את העבודה ליחידת-התיקון; אל תפתור מחדש.
5. כל PR מצהיר invariants — אילו G*/INV-* ה-PR נוגע בהם / מקיים (ראה תבנית ה-PR ב-.gitea/PULL_REQUEST_TEMPLATE.md).

שתי שכבות-כללים מובחנות, שתיהן חלות:

• הנדסה (G1–G10, G12) — הסעיף הזה + docs/spec/. סמכות: ≥3 מקורות חיצוניים.
• תוכן משפטי (G11) — סעיף "עקרונות כתיבה קריטיים" למטה (12 בלוקים, רקע ניטרלי...). סמכות: היו"ר + מסמכי-הפרויקט.

אכיפה אוטומטית: hook PreToolUse (scripts/spec-guard.sh) מזכיר את הפרוטוקול בכל Edit/Write על נתיב-קוד.

---

בידוד-סשנים — worktree מבודד חובה ⚠️

כלל קשיח. בכל רגע נתון רצים כמה סשנים במקביל על אותו עץ-עבודה (~/legal-ai) — סשנים אינטראקטיביים של chaim וגם סוכני Paperclip. עץ-עבודה אחד = ענף-גיט אחד משותף, כך שסשן אחד מחליף branch / משאיר שינויים לא-מתויקים תוך כדי שאחר עובד → דריסה הדדית ומירוץ-ענף (feedback_shared_worktree_branch_race).

לכן — כל סשן שעומד לכתוב/לשנות קוד או תיעוד חייב לעבוד ב-git worktree מבודד משלו. אסור לערוך/לתייק בעץ-העבודה הראשי ~/legal-ai כשייתכן שסשן אחר פעיל.

הבידוד נתמך-סביבה — ההגדרות נשמרות ב-repo (.claude/settings.json, .worktreeinclude, .gitignore) כך שכל worktree שה-harness יוצר מקבל אוטומטית בסיס נקי, את התלויות, ואת ההרשאות. מקורות רשמיים: Run parallel sessions with worktrees, Settings → worktree.

הדרך המומלצת — worktree של ה-harness

cd ~/legal-ai && claude --worktree <slug>     # או, בתוך סשן: "עבוד ב-worktree" (כלי EnterWorktree)

נוצר תחת .claude/worktrees/<slug>/ על ענף worktree-<slug>, ומקבל אוטומטית: בסיס נקי מ-origin/main (worktree.baseRef: "fresh") · web-ui/node_modules כסימלינק (worktree.symlinkDirectories; אין צורך ב-npm ci) · .claude/settings.local.json + קבצי-env מקומיים (דרך .worktreeinclude) · ניקוי אוטומטי ביציאה (כולל עקיפת באג סימלינק #40259 דרך WorktreeRemove hook עם --force).

הפרוטוקול (חל על שתי הדרכים)

1. בתחילת עבודת-כתיבה — צור worktree (מומלץ: claude --worktree; ידני-fallback: git worktree add -b <branch> .claude/worktrees/<slug> origin/main — תחת .claude/worktrees/ כדי שההגדרות יחולו).
2. אמת ענף לפני כל commit — git branch --show-current (הרגל קשיח; ה-harness עלול להתעלם מ-baseRef:"fresh" — באג #60588 — אז ודא שהבסיס באמת origin/main).
3. push + PR + merge כרגיל (feedback_always_pr_merge) — PR תמיד ל-main. הרץ tests לפני merge.
4. נקה אחרי מיזוג — יציאת הסשן מנקה worktree של ה-harness אוטומטית; ידני: git worktree remove .claude/worktrees/<slug> && git worktree prune && git branch -D worktree-<slug>.
5. קריאה-בלבד (חקירה, סריקה, הרצת בדיקות ללא שינוי) — מותר בעץ הראשי; אין צורך ב-worktree.
6. אל תיגע בשינויים לא-מתויקים שאינם שלך בעץ הראשי — הם של סשן אחר. אם העץ הראשי על ענף זר — אל תתייק עליו.

בידוד-DB: ה-worktree מבודד-קבצים בלבד — לא בידוד-repo ולא בידוד-DB. אל תריץ migrations מ-2 worktrees במקביל על Postgres המשותף (localhost:5433) — סכמה שאף סשן לא מצפה לה (Run agents in parallel). סוכני Paperclip — אינם מבודדים (אומת 2026-06-06): 14 מתוך 16 הסוכנים רצים על אדפטר claude_local הרשמי, שמריץ claude -p ב-adapter_config.cwd=/home/chaim/legal-ai המשותף — אין לו אופציית worktreeMode/-w. כלומר כל סוכני Paperclip חולקים את עץ-העבודה הראשי. הסיכון ממותן ע"י כלל הסשנים נתמך-הסביבה למעלה + תזמור סדרתי ע"י ה-CEO — לא ע"י בידוד-worktree per-agent. ניתוח מלא: ארכיון TaskMaster legal-ai #104 (נסגר cancelled — "לתעד, לא לבדד").

---

Deploy — תמצית קריטית

שלושה מודלי-הרצה דרים יחד; ערבוב = הטעות הנפוצה. פירוט מלא, UUIDs ופקודות: docs/operations-runbook.md.

• legal-ai (web/, web-ui/) = Docker דרך Coolify. שינוי קוד לא נכנס לתוקף עד git commit + git push origin main → Gitea Actions בונה image → mcp__coolify__deploy (~2-4 דק'). אסור uvicorn/next dev מקומית — אין Python על המכונה. בדיקה: curl https://legal-ai.nautilus.marcusgroup.org/api/health.
• Paperclip = pm2 מקומי (localhost:3100). שינוי → pm2 restart paperclip. אין Docker/Coolify.
• legal-chat-service = pm2 מקומי (127.0.0.1:8770), גשר claude CLI לטאב הצ'אט ב-/training. שינוי → pm2 restart legal-chat-service.

---

Paperclip — כללים קריטיים (תמצית)

פירוט מלא + דוגמאות + פקודות sync: docs/operations-runbook.md.

G12 — שער-הפלטפורמה (docs/spec/X15-agent-platform-port.md): Paperclip היא מעטפת ניתנת-להחלפה מאחורי Port יחיד. מגע-Paperclip מותר רק ב-web/agent_platform_port.py + HEARTBEAT.md (לפרומפטים) + המעטפת המוצהרת (paperclip_client/api, plugin, adapters). אסור סמל ספציפי-Paperclip ב-mcp-server/src או ב-skills של ההחלטה/הסגנון. כל מגע חדש → דרך ה-Port.

• Wakeup תמיד דרך API: POST /api/agents/{agent-id}/wakeup עם payload.issueId. אסור INSERT INTO agent_wakeup_requests ישיר — הסוכן לא יתעורר לעולם (אין heartbeat_run).
• ניתוב comments דרך CEO: תגובת-משתמש → פלאגין מעיר CEO → CEO מנתב ויוצר issue. סוכנים קוראים comments אחרונים לפני עבודה (HEARTBEAT 2b-2c).
• קריאות API דרך helper בלבד: bash → scripts/pc.sh; Python → pc_request() מ-web/paperclip_api.py. אסור curl ישיר ל-Paperclip או httpx.AsyncClient ישיר.
• Cross-company sync: 14 סוכנים = 7 × 2 חברות (CMP=1xxx master, CMPA=8xxx mirror). אחרי כל שינוי הגדרות/skills של סוכן — להריץ scripts/sync_agents_across_companies.py --apply. מדלג על סוכנים עם adapter_type שונה בין החברות (למשל deepseek_local) — להחיל ידנית בשתיהן.

---

כלל: עדכון scripts/SCRIPTS.md

בכל פעם שנוצר, נמחק, או משתנה סקריפט בתיקיית scripts/ — חובה לעדכן את scripts/SCRIPTS.md (תפקיד, סטטוס, החלפה).

ניהול משימות — Gitea Issues ⚠️

מקור-האמת לעבודה הוא Gitea Issues — לא TaskMaster, לא הקובץ הזה, לא זיכרון. TaskMaster הוצא משימוש ב-2026-08-05. 26 המשימות הפתוחות הועברו ל-issues #433–#458 (מיפוי מלא: docs/taskmaster-to-gitea-migration.md). .taskmaster/tasks/tasks.json נשמר לקריאה-בלבד כארכיון היסטורי — אין לכתוב אליו ואין ליצור בו משימות חדשות.

המוסכמות מגיעות מ-infra/project-template — אותה מערכת תיוג ואותו workflow כמו שאר פרויקטי המשרד.

Session-Start Protocol

כשנפתח סשן עם "איפה אנחנו עומדים / מה נשאר / בוא נמשיך" — אל תשחזר מצב מזיכרון. קרא את ה-issues החיים קודם:

1. GET /api/v1/repos/ezer-mishpati/legal-ai/issues?state=open (טוקן מ-~/.git-credentials או Infisical /apps/legal-ai GITEA_TOKEN).
2. הבא בתור = ה-issue בעל העדיפות הגבוהה ביותר (p0-blocker → p1-high → p2-normal → p3-low; בתוך עדיפות — type:bug קודם).
3. דלג על status:in-progress (מישהו עובד), status:in-review (יש PR), status:needs-decision (ממתין להכרעת חיים/דפנה), status:blocked, status:deferred.
4. רק אחרי קריאת ה-issues — הצע את הצעד הבא.

Issue-First

• שום קוד בלי issue. כל תקלה/צורך/משימה → issue קודם.
• כל issue חייב: What & Why + Acceptance Criteria + הקשר. issue ללא AC אינו status:ready ואינו נלקח.
• Branch naming: <type>/<issue>-<slug> (feat/fix/chore/refactor/docs/test) — יצירת branch = בלעדיות על ה-issue.
• ה-PR מפנה ל-issue (Closes #N) ומצהיר invariants (ראה .gitea/PULL_REQUEST_TEMPLATE.md).

מערכת התיוג

שכבה	ערכים
type:	bug · feature · chore · spike
priority:	p0-blocker · p1-high · p2-normal · p3-low
status:	ready · in-progress · in-review · needs-decision · blocked · deferred · good-first-issue
size:	xs (<חצי יום) · s (~יום) · m (2-3 ימים) · l (שבוע+ — לשקול פיצול)
area:	agents · retrieval · extraction · writing · backend · frontend · mcp · infra · docs · ci · security

⚠️ הפניות (#N) בהודעות-commit מלפני 2026-08-05 מתייחסות למזהי TaskMaster, לא למספרי issue. מספרי ה-issue של legal-ai מתחילים ב-#433; מתחת לזה המספרים שייכים ל-PRs ולשני issues ישנים.

---

עקרונות כתיבה קריטיים (G11)

1. "מבחן השופט" — כל החלטה חייבת להיות קריאה לשופט שלא מכיר את התיק
2. "רקע ניטרלי" — בלוק ו = עובדות בלבד. אין ציטוטים מצדדים, אין מילות שיפוט
3. "ללא כפילות" — בלוק י (דיון) מפנה לבלוקים קודמים, לא חוזר עליהם
4. "טענות מקוריות בלבד" — בלוק ז = מכתבי טענות מקוריים בלבד. השלמות → בלוק ח
5. ארכיטקטורת 12 בלוקים — ראה docs/block-schema.md
6. צ'קליסט תוכן — בלוק י מקבל צ'קליסט תוכן אוטומטי לפי סוג הערר (ראה lessons.py: CONTENT_CHECKLISTS)

הערות יו"ר (Chair Feedback): מנגנון תיעוד הערות דפנה — טבלת chair_feedback, API /api/feedback, MCP record_chair_feedback/list_chair_feedback, UI /feedback. פירוט: docs/operations-runbook.md.

יו"ר: עו"ד דפנה תמיר

מדריך סגנון מלא: skills/decision/SKILL.md.