Files

Build & Deploy / build-and-deploy (push) Successful in 7s

Details

docs: case-deletion runbook (legal-ai + Paperclip + Gitea)

Captures the full deletion procedure we worked out empirically while
wiping case 8174-24 for a clean rerun. Covers all four systems where
case state lives, in dependency order:

  1. legal-ai DB + on-disk dir — DELETE /api/cases?remove_files=true
     (now actually works after 903fb4d added the missing db.delete_case)
  2. Paperclip DB — no API; raw SQL with explicit FK-blocker ordering
     (issue_comments, cost_events, finance_events, feedback_votes,
     issue_inbox_archives, issue_read_states must go before issues;
     heartbeat_runs.wakeup_request_id must be NULLed before
     agent_wakeup_requests can be deleted)
  3. Gitea — DELETE /api/v1/repos/cases/{N}
  4. Verification queries for each system

Two gotchas worth highlighting in the doc:
  • The case directory inside /data/cases is owned by root because the
    container runs as root — host-side rm needs sudo, or use the API
    (rmtree happens inside the container).
  • Paperclip projects are referenced via name LIKE '%{N}%' since
    there's no slug column. Stricter matching is recommended if N
    appears in multiple project names.

Linked from legal-ai/CLAUDE.md docs index. A future scripts/delete-case.sh
that automates the runbook with a confirmation prompt is noted as TODO
inside the runbook itself.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-30 14:54:21 +00:00

13 KiB

Raw Blame History

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

רקע הפרויקט

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

מה עושה ועדת ערר?

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

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

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

מטרת המערכת

לבנות כלי עבודה שמסייע ליו"ר הוועדה לנסח החלטות:

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

מה היה קודם (Legacy)

המערכת הקודמת היתה Obsidian vault עם Claude Code skills על שרת אחר. פותחו:

ניתוח סגנון של 3 החלטות (הכט — דחייה, בית הכרם — קבלה חלקית, אריאלי — השוואה)
ארכיטקטורת 12 בלוקים מבוססת CREAC / DITA / Akoma Ntoso / Federal Judicial Center
כללי כתיבה (רקע ניטרלי, ללא כפילות, טענות מקוריות בלבד)
לקחים מהשוואת טיוטות לגרסאות סופיות
סקריפט ייצוא DOCX

הידע שהופק מה-vault הוטמע במערכת הנוכחית — מסמכי ייחוס (docs/), קורפוס אימון (data/training/), ומבנה 12 בלוקים. ה-vault המקורי נמחק; הפרויקט הנוכחי עובד עם PostgreSQL + pgvector.

מסמכי ייחוס

מסמך	תוכן	מתי לקרוא
`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	לפני הוספת חברה/סוג ערר חדש
`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/decision-block-mapping.md`	מיפוי בלוקים להחלטות — איך 12 הבלוקים משתקפים ב-DOCX	להתמצאות במבנה
`docs/memory.md`	הקשר כללי — skills, פרויקטים שהושלמו, מבנה vault	להתמצאות כללית
`skills/decision/SKILL.md`	מדריך סגנון מלא של דפנה — טון, מבנה, ביטויים, מתודולוגיה	לפני כל כתיבת החלטה

שרת Nautilus (158.178.131.193)

שירות	תפקיד	כתובת
Coolify	ניהול containers	`http://158.178.131.193:8000`
PostgreSQL + pgvector	בסיס נתונים ראשי	`legal-ai-postgres`
Redis	תור משימות	`legal-ai-redis`
n8n	אוטומציית workflows	להגדרה
Gitea	מאגר קוד	`gitea.nautilus.marcusgroup.org/ezer-mishpati`
ezer-mishpati-web	ממשק העלאת מסמכים (Docker/Coolify)	`legal-ai.nautilus.marcusgroup.org`
Paperclip	סוכן AI — מריץ Claude Code agents (pm2, מקומי)	`localhost:3100`
Infisical	ניהול סודות	`secret.dev.marcus-law.co.il`

⚠️ ארכיטקטורת Deploy — חובה לקרוא

עוזר משפטי (Legal-AI) — רץ כ-Docker container דרך Coolify:

UUID: gyjo0mtw2c42ej3xxvbz8zio
שינוי קוד ב-web/ או web-ui/ לא נכנס לתוקף עד ש:
1. עושים git commit + git push origin main
2. מריצים deploy דרך Coolify (mcp__coolify__deploy)
3. ממתינים ~2-4 דקות לבנייה
אסור לנסות להריץ uvicorn מקומית — אין סביבת Python על המכונה
ה-container מריץ Next.js (:3000, חשוף) + FastAPI (:8000, פנימי)
בדיקה: curl https://legal-ai.nautilus.marcusgroup.org/api/...

Paperclip — רץ מקומית דרך pm2:

פורט: localhost:3100, DB: localhost:54329
שינויי קוד נכנסים לתוקף אחרי pm2 restart paperclip
אין צורך ב-Docker או Coolify

מבנה תיקיות

/home/chaim/legal-ai/
├── CLAUDE.md                          ← הקובץ הזה
├── Dockerfile                         ← Docker build
├── docs/                              ← תיעוד + לקחים
│   ├── architecture.md                   ארכיטקטורה
│   ├── block-schema.md                   12 בלוקים (המסמך החשוב ביותר)
│   ├── migration-plan.md                 תוכנית מעבר vault → DB
│   ├── legal-decision-lessons.md         לקחים מ-3 החלטות
│   └── memory.md                         הקשר כללי — skills, פרויקטים
├── skills/                            ← כלי עבודה ומדריכים
│   ├── decision/                         מדריך סגנון + references + 12 בלוקים
│   ├── assistant/                        קטלוג מסמכים
│   └── docx/                             עיצוב DOCX
├── data/
│   ├── training/                      ← 4 החלטות לאימון (DOCX)
│   ├── exports/                       ← טיוטות DOCX מיוצאות
│   └── cases/{case-number}/           ← תיקי עררים (מבנה שטוח, סטטוס ב-DB)
├── web/                               ← FastAPI backend (Python): 75 API endpoints
│   ├── app.py                            ← API ראשי
│   ├── paperclip_client.py               ← אינטגרציית Paperclip
│   └── gitea_client.py                   ← אינטגרציית Gitea
├── web-ui/                            ← Next.js frontend (TypeScript/React): ממשק המשתמש
│   └── next.config.ts                    ← proxy: /api/* → FastAPI :8000
├── mcp-server/                        ← MCP server + services + tools
└── scripts/                           ← סקריפטים וכלי עזר (ראה scripts/SCRIPTS.md)
    └── .archive/                      ← סקריפטים שהושלמו (לא להריץ)

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

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

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

הפרויקט משתמש ב-TaskMaster AI (MCP server) לניהול משימות מובנה:

תמיד להשתמש ב-TaskMaster לפירוק, מעקב וניהול משימות — לא ב-TASKS.md ידני
קובץ המשימות: tasks/tasks.json
פקודות עיקריות: get_tasks, next_task, add_task, update_task, expand_task
לפני התחלת עבודה → next_task כדי לדעת מה הבא לפי תלויות
אחרי סיום משימה → update_task עם status=done
משימה מורכבת → expand_task לפירוק לתתי-משימות

Paperclip — כללי אינטגרציה קריטיים

Wakeup API — תמיד דרך API, לעולם לא דרך DB

הנתיב הנכון: POST /api/agents/{agent-id}/wakeup (לא /wake!)
⚠️ אסור: INSERT INTO agent_wakeup_requests ישירות — זה יוצר רק רשומה בלי heartbeat_run, והסוכן לא יתעורר לעולם
⚠️ חובה לשלוח payload עם issueId — בלי זה הסוכן מתעורר בלי הקשר (בלי תיק, בלי issue, בלי cwd נכון)

דוגמה נכונה:

{"source": "automation", "triggerDetail": "system", "reason": "...",
 "payload": {"issueId": "...", "mutation": "comment", "commentId": "..."}}

Board API Key: שמור ב-DB (board_api_keys), auth: Authorization: Bearer pbk_...

ניתוב comments דרך CEO

כשמשתמש כותב תגובה על issue ב-Paperclip, הפלאגין (plugin-legal-ai) מעיר את ה-CEO דרך ctx.agents.invoke()
ה-CEO קורא את ה-comment, מחליט על ניתוב, ויוצר issue לסוכן המתאים
כל הסוכנים חייבים לקרוא comments אחרונים לפני שהם מתחילים לעבוד (HEARTBEAT שלבים 2b-2c)

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

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

הערות יו"ר (Chair Feedback)

מנגנון לתיעוד הערות דפנה על טיוטות:

DB: טבלת chair_feedback (case_id, block_id, feedback_text, category, lesson_extracted)
API: GET/POST /api/feedback, PATCH /api/feedback/{id}/resolve
MCP tools: record_chair_feedback, list_chair_feedback
UI: דף ניהול ב-/feedback (ב-Next.js)
קטגוריות: missing_content, wrong_tone, wrong_structure, factual_error, style, other

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

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

13 KiB Raw Blame History Unescape Escape