legal-ai/CLAUDE.md

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

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

רקע הפרויקט

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

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

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

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

מטרת המערכת

כלי עבודה שמסייע ליו"ר הוועדה: ניהול תיקים (ייבוא, סיווג, מעקב סטטוס) · בסיס ידע (פסיקה, ביטויי מעבר, לקחים, חקיקה) · חיפוש סמנטי (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/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/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/operations-runbook.md	עומק תפעולי — Deploy (Coolify/pm2), Paperclip-ops מלא (wakeup, sync, webhook, scheduled jobs, adapters), מבנה-תיקיות, Chair-Feedback, TaskMaster	לפני עבודה על 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–G11, וכללי-ההנדסה (§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, 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) — הסעיף הזה + 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.

• 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 (תפקיד, סטטוס, החלפה).

ניהול משימות — TaskMaster AI

תמיד TaskMaster (לא TASKS.md ידני). קובץ קנוני: ~/legal-ai/.taskmaster/tasks/tasks.json (tags: master, legal-ai). פקודות: get_tasks, next_task, add_task, update_task, expand_task.

⚠️ מלכוד cwd ב-CLI: --tag בוחר קבוצה בתוך הקובץ — לא לאיזה קובץ לכתוב (ה-CLI מאתר לפי cwd). תמיד cd ~/legal-ai לפני כל פקודה משנה, ואז אמת ב-MCP get_tasks. כשלא בטוחים — לערוך את הקובץ ישירות. פירוט: docs/operations-runbook.md.

---

עקרונות כתיבה קריטיים (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.