Chaim
6a38789379
All checks were successful
Build & Deploy / build-and-deploy (push) Successful in 7s
Two latent issues surfaced today while watching the case 8174-24
end-to-end run, both worth documenting and engineering around because
they will recur on every future case.
Bug 1 — issue.released flips done→todo
After an agent successfully PATCHes its issue to "done", Paperclip's
internal issue.released action reverts the status to "todo" within
~30 seconds. This triggers a fresh wakeup of the same agent on a
task that is already complete.
Reproduced on CMPA-18 (30/04/26):
18:14:57 agent PATCH → status: done
18:15:35 Paperclip → issue.released → status: todo
18:15:54 new researcher run started
The fix at the right altitude (Paperclip itself) is outside our repo.
Mitigation in HEARTBEAT.md §3 — when an agent boots and finds the
issue in `todo` while expected outputs (file, DB rows) already exist,
it must short-circuit: post a "no change" comment, PATCH back to done,
and exit. Costs ~$0.20 per false wakeup but breaks the loop.
Bug 2 — Bash backtick trap on long comment bodies
Researcher agent built a curl pipeline like:
curl ... -d "$(python3 -c "body = '''...
📁 קובץ מחקר: `/path/to/file.md`
'''")"
The backticks around the file path (markdown convention) get
evaluated by the OUTER bash $(...) as command substitution. Bash
then tries to exec /path/to/file.md, which is not executable, and
prints "Permission denied" — a misleading error since the actual
file ownership is fine. The curl itself succeeded; only the bash
prelude noised up the log.
Fix in HEARTBEAT.md §4א: long bodies must go via Write→tempfile
then `curl -d @file`. Avoids every shell quoting edge case.
Files:
• docs/paperclip-quirks.md — new. Full writeup of both bugs plus
two prior known-quirks (CEO auto-block in_progress, INSERT vs
API for wakeups). Each section: what happens, empirical evidence
from logs, impact, workaround, status.
• .claude/agents/HEARTBEAT.md — added the self-recovery section to
§3 and the temp-file pattern to §4א. The temp-file pattern is the
canonical answer for any agent posting markdown comments —
applies to all 7 agents in this skill set.
• CLAUDE.md — referenced the new doc from the docs index.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
185 lines
13 KiB
Markdown
185 lines
13 KiB
Markdown
# עוזר משפטי — Legal Decision Assistant
|
||
|
||
## רקע הפרויקט
|
||
|
||
מערכת AI לסיוע בכתיבת החלטות של **ועדת ערר לתכנון ובניה, מחוז ירושלים**, בראשות **עו"ד דפנה תמיר**.
|
||
|
||
### מה עושה ועדת ערר?
|
||
ועדת ערר היא גוף מעין-שיפוטי שדן בעררים על החלטות ועדות מקומיות לתכנון ובניה. הוועדה מקבלת חומרי מקור (כתבי ערר, תגובות, פרוטוקולים, תכניות), דנה בטענות הצדדים, ומוציאה **החלטה כתובה מנומקת** — מסמך משפטי פורמלי שניתן לביקורת שיפוטית בבית משפט לעניינים מנהליים.
|
||
|
||
### שלושה סוגי עררים
|
||
| סוג | מספרי תיקים | טון | מאפיין |
|
||
|-----|-------------|-----|--------|
|
||
| רישוי ובנייה | 1xxx | חם יחסית | הקשר תכנוני רחב, אלמנטים אנושיים |
|
||
| היטל השבחה | 8xxx | קר ומקצועי | יבש, ללא רגשות |
|
||
| פיצויים (ס' 197) | 9xxx | קר ומקצועי | דומה להיטל השבחה |
|
||
|
||
### מטרת המערכת
|
||
לבנות כלי עבודה שמסייע ליו"ר הוועדה לנסח החלטות:
|
||
1. **ניהול תיקים** — ייבוא חומרי מקור, סיווג מסמכים, מעקב סטטוס
|
||
2. **בסיס ידע** — פסיקה, ביטויי מעבר, לקחים מהחלטות קודמות, חקיקה
|
||
3. **חיפוש סמנטי (RAG)** — מציאת תקדימים רלוונטיים ופסקאות דומות
|
||
4. **סיוע בכתיבה** — ייצור טיוטות לפי ארכיטקטורת 12 בלוקים בסגנון דפנה
|
||
5. **ייצוא 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`](docs/architecture.md) | ארכיטקטורת המערכת, תרשים רכיבים, זרימת נתונים, 4 שכבות DB | לפני עבודה על תשתית |
|
||
| [`docs/block-schema.md`](docs/block-schema.md) | הגדרת 12 בלוקים — content model, constraints, processing params | **לפני כל כתיבת החלטה** |
|
||
| [`docs/migration-plan.md`](docs/migration-plan.md) | תוכנית מעבר vault → DB — טבלאות, עדיפויות, כמויות | לפני ייבוא נתונים |
|
||
| [`docs/legal-decision-lessons.md`](docs/legal-decision-lessons.md) | לקחים מ-3 החלטות — מה עבד, מה השתנה, ביטויי מעבר חדשים | **לפני כל כתיבת החלטה** |
|
||
| [`docs/decision-methodology.md`](docs/decision-methodology.md) | **מתודולוגיה אנליטית — איך לחשוב על החלטה מעין-שיפוטית** | **לפני כל כתיבת החלטה** |
|
||
| `docs/garner-methodology-extraction.md` | חומר מקור: מיצוי מספרי Garner על כתיבה משפטית | רק לבדיקת מקור |
|
||
| `docs/fjc-principles-extraction.md` | חומר מקור: מיצוי מ-Judicial Writing Manual (FJC) | רק לבדיקת מקור |
|
||
| [`docs/corpus-analysis.md`](docs/corpus-analysis.md) | ניתוח שיטתי של 24 החלטות — מפת תוכן, דפוסי דיון תכנוני, פערים | **לפני כל כתיבת החלטה** |
|
||
| [`docs/product-specification.md`](docs/product-specification.md) | איפיון מוצר מלא — personas, תהליכים עסקיים, דרישות | להתמצאות עסקית/מוצרית |
|
||
| [`docs/new-company-setup-guide.md`](docs/new-company-setup-guide.md) | מדריך הקמת חברה חדשה (CMPA) — skills, corpus, style analysis | לפני הוספת חברה/סוג ערר חדש |
|
||
| [`docs/audit-report.md`](docs/audit-report.md) | דוח audit של המערכת | רקע כללי |
|
||
| [`docs/case-migration-tracker.md`](docs/case-migration-tracker.md) | מעקב מיגרציה של תיקים קיימים | לצורך מעקב |
|
||
| [`docs/case-deletion-runbook.md`](docs/case-deletion-runbook.md) | runbook מלא למחיקת תיק — legal-ai DB + disk + Paperclip + Gitea, FK ordering, fallback ל-SQL ישיר | לפני reset שלם של תיק (מבחן, מחיקה בטעות) |
|
||
| [`docs/paperclip-quirks.md`](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`](docs/decision-block-mapping.md) | מיפוי בלוקים להחלטות — איך 12 הבלוקים משתקפים ב-DOCX | להתמצאות במבנה |
|
||
| [`docs/memory.md`](docs/memory.md) | הקשר כללי — skills, פרויקטים שהושלמו, מבנה vault | להתמצאות כללית |
|
||
| [`skills/decision/SKILL.md`](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 נכון)
|
||
- דוגמה נכונה:
|
||
```json
|
||
{"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)
|
||
|
||
---
|
||
|
||
## עקרונות כתיבה קריטיים
|
||
|
||
1. **"מבחן השופט"** — כל החלטה חייבת להיות קריאה לשופט שלא מכיר את התיק
|
||
2. **"רקע ניטרלי"** — בלוק ו = עובדות בלבד. אין ציטוטים מצדדים, אין מילות שיפוט
|
||
3. **"ללא כפילות"** — בלוק י (דיון) מפנה לבלוקים קודמים, לא חוזר עליהם
|
||
4. **"טענות מקוריות בלבד"** — בלוק ז = מכתבי טענות מקוריים בלבד. השלמות → בלוק ח
|
||
5. **ארכיטקטורת 12 בלוקים** — ראה `docs/block-schema.md`
|
||
6. **צ'קליסט תוכן** — בלוק י מקבל צ'קליסט תוכן אוטומטי לפי סוג הערר (ראה `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`
|