Compare commits
4 Commits
worktree-d
...
worktree-c
| Author | SHA1 | Date | |
|---|---|---|---|
| d65c335a4a | |||
| dc203c77eb | |||
| 180f70bcc0 | |||
| 1544669c7a |
40
CLAUDE.md
40
CLAUDE.md
@@ -1,6 +1,6 @@
|
||||
# עוזר משפטי — Legal Decision Assistant
|
||||
|
||||
> **אינדקס דק.** הכללים הקריטיים נמצאים כאן; העומק התפעולי (Deploy, Paperclip-ops, adapters, מבנה-תיקיות, Chair-Feedback, TaskMaster מלא) הוצא ל-[`docs/operations-runbook.md`](docs/operations-runbook.md) כדי לרזות את ההקשר הנטען בכל סשן.
|
||||
> **אינדקס דק.** הכללים הקריטיים נמצאים כאן; העומק התפעולי (Deploy, Paperclip-ops, adapters, מבנה-תיקיות, Chair-Feedback, עבודה מול Gitea Issues) הוצא ל-[`docs/operations-runbook.md`](docs/operations-runbook.md) כדי לרזות את ההקשר הנטען בכל סשן.
|
||||
|
||||
## רקע הפרויקט
|
||||
|
||||
@@ -64,7 +64,8 @@
|
||||
| [`.claude/agents/HEARTBEAT.md`](.claude/agents/HEARTBEAT.md) | checklist הפעלת סוכן — routing, company filtering, quirks, wakeup עם UUID נכון | **לפני כל עבודה על סוכנים** |
|
||||
| [`skills/dafna-decision-template/SKILL.md`](skills/dafna-decision-template/SKILL.md) | export DOCX לפי styles של תבנית Word של דפנה — line classification, dash policy, placeholder handling | לפני export DOCX |
|
||||
| [`docs/corpus-graph.md`](docs/corpus-graph.md) | **מפת הקורפוס** (`/graph`) — גרף ציטוטים אינטראקטיבי נייטיב; 6 שכבות (פסיקה/נושא/תחום/הלכות/חוסרי‑מחקר/יומונים), אנליטיקה (PageRank/אשכולות), endpoints, ואיך מוסיפים שכבה | לפני עבודה על דף `/graph` או `web/graph_api.py` |
|
||||
| [`docs/operations-runbook.md`](docs/operations-runbook.md) | **עומק תפעולי** — Deploy (Coolify/pm2), Paperclip-ops מלא (wakeup, sync, webhook, scheduled jobs, adapters), מבנה-תיקיות, Chair-Feedback, TaskMaster | לפני עבודה על Deploy / אינטגרציית-Paperclip / adapters |
|
||||
| [`docs/taskmaster-to-gitea-migration.md`](docs/taskmaster-to-gitea-migration.md) | **מיגרציית ניהול-המשימות** — TaskMaster→Gitea Issues (2026-08-05), טבלת מיפוי מלאה, ומלכודת המספור בהפניות `(#N)` ישנות | כשנתקלים בהפניה `(#N)` בקומיט ישן, או כשמחפשים משימה שהייתה ב-TaskMaster |
|
||||
| [`docs/operations-runbook.md`](docs/operations-runbook.md) | **עומק תפעולי** — Deploy (Coolify/pm2), Paperclip-ops מלא (wakeup, sync, webhook, scheduled jobs, adapters), מבנה-תיקיות, Chair-Feedback, Gitea Issues API | לפני עבודה על Deploy / אינטגרציית-Paperclip / adapters |
|
||||
|
||||
---
|
||||
|
||||
@@ -114,7 +115,7 @@ cd ~/legal-ai && claude --worktree <slug> # או, בתוך סשן: "עבוד
|
||||
6. **אל תיגע** בשינויים לא-מתויקים שאינם שלך בעץ הראשי — הם של סשן אחר. אם העץ הראשי על ענף זר — אל תתייק עליו.
|
||||
|
||||
> **בידוד-DB:** ה-worktree מבודד-קבצים בלבד — לא בידוד-repo ולא בידוד-DB. **אל תריץ migrations מ-2 worktrees במקביל** על Postgres המשותף (`localhost:5433`) — סכמה שאף סשן לא מצפה לה ([Run agents in parallel](https://code.claude.com/docs/en/agents)).
|
||||
> **סוכני 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 — "לתעד, לא לבדד").
|
||||
> **סוכני 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 — "לתעד, לא לבדד").
|
||||
|
||||
---
|
||||
|
||||
@@ -144,9 +145,36 @@ cd ~/legal-ai && claude --worktree <slug> # או, בתוך סשן: "עבוד
|
||||
## כלל: עדכון `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`](docs/operations-runbook.md).
|
||||
## ניהול משימות — Gitea Issues ⚠️
|
||||
|
||||
> **מקור-האמת לעבודה הוא [Gitea Issues](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues) — לא TaskMaster, לא הקובץ הזה, לא זיכרון.**
|
||||
> **TaskMaster הוצא משימוש ב-2026-08-05.** 26 המשימות הפתוחות הועברו ל-issues #433–#458 (מיפוי מלא: [`docs/taskmaster-to-gitea-migration.md`](docs/taskmaster-to-gitea-migration.md)). `.taskmaster/tasks/tasks.json` נשמר לקריאה-בלבד כארכיון היסטורי — **אין לכתוב אליו ואין ליצור בו משימות חדשות.**
|
||||
|
||||
המוסכמות מגיעות מ-[`infra/project-template`](https://gitea.marcus-law.co.il/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`](.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 ישנים.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -195,9 +195,33 @@ CEO שמתעורר מ-`weekly-feedback-job` כותב לקובץ בלבד — **
|
||||
|
||||
---
|
||||
|
||||
## ניהול משימות — TaskMaster AI (פירוט)
|
||||
## ניהול משימות — Gitea Issues (פירוט)
|
||||
|
||||
- קובץ המשימות הקנוני: `~/legal-ai/.taskmaster/tasks/tasks.json` (יחסי ל-project root, **לא** `~/.taskmaster/tasks/tasks.json`). מכיל את כל ה-tags של legal-ai (`master`, `legal-ai`).
|
||||
- פקודות עיקריות: `get_tasks`, `next_task`, `add_task`, `update_task`, `expand_task`
|
||||
- לפני התחלת עבודה → `next_task`; אחרי סיום → `update_task` עם status=done; משימה מורכבת → `expand_task`
|
||||
- **⚠️ מלכוד cwd ב-CLI:** הדגל `--tag` בוחר קבוצה לוגית *בתוך* הקובץ — הוא **לא** בוחר לאיזה `tasks.json` לכתוב. ה-CLI מאתר את הקובץ לפי ה-cwd. תמיד `cd ~/legal-ai` לפני `task-master add-task` או כל פקודה משנה, ואז אמת ב-MCP `get_tasks`. כשלא בטוחים — לערוך את `~/legal-ai/.taskmaster/tasks/tasks.json` ישירות.
|
||||
> **TaskMaster AI הוצא משימוש ב-2026-08-05.** מקור-האמת לעבודה הוא
|
||||
> [Gitea Issues](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues).
|
||||
> ה-workflow, מערכת התיוג ו-Session-Start Protocol מתועדים ב-[`CLAUDE.md`](../CLAUDE.md);
|
||||
> טבלת המיפוי TaskMaster→issue ב-[`taskmaster-to-gitea-migration.md`](taskmaster-to-gitea-migration.md).
|
||||
|
||||
### עבודה מול ה-API
|
||||
הטוקן: `~/.git-credentials` (שורת `gitea.nautilus`) או Infisical `/apps/legal-ai` `GITEA_TOKEN`.
|
||||
|
||||
```bash
|
||||
API=https://gitea.nautilus.marcusgroup.org/api/v1/repos/ezer-mishpati/legal-ai
|
||||
T=$(grep -m1 'gitea.nautilus' ~/.git-credentials | sed 's|.*://[^:]*:\([^@]*\)@.*|\1|')
|
||||
|
||||
# מה הבא בתור (דילוג על in-progress/in-review/blocked/deferred/needs-decision)
|
||||
curl -s -H "Authorization: token $T" "$API/issues?state=open&labels=priority:p1-high"
|
||||
|
||||
# issue חדש
|
||||
curl -s -X POST -H "Authorization: token $T" -H "Content-Type: application/json" \
|
||||
"$API/issues" -d '{"title":"...","body":"## What & Why\n...\n## Acceptance Criteria\n...","labels":[<ids>]}'
|
||||
|
||||
# תוויות (id ← שם)
|
||||
curl -s -H "Authorization: token $T" "$API/labels?limit=100"
|
||||
```
|
||||
|
||||
### ארכיון TaskMaster
|
||||
`~/legal-ai/.taskmaster/tasks/tasks.json` **מוקפא לקריאה-בלבד** — 166 משימות שהושלמו,
|
||||
4 שבוטלו, ו-26 הפתוחות שהועברו. שימושי לחפירה היסטורית ("למה עשינו X"), אבל
|
||||
**אין לכתוב אליו**. אם צריך הקשר ממשימה ישנה — לחפש בקובץ הזה, ולפתוח issue חדש
|
||||
אם נדרשת עבודה.
|
||||
|
||||
61
docs/taskmaster-to-gitea-migration.md
Normal file
61
docs/taskmaster-to-gitea-migration.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# מיגרציה: TaskMaster → Gitea Issues
|
||||
|
||||
**תאריך: 2026-08-05.** ניהול המשימות של legal-ai עבר מ-TaskMaster AI ל-[Gitea Issues](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues), לפי המוסכמות של [`infra/project-template`](https://gitea.marcus-law.co.il/infra/project-template).
|
||||
|
||||
## מה השתנה
|
||||
|
||||
- **מקור-האמת לעבודה = Gitea Issues.** לא TaskMaster, לא `CLAUDE.md`, לא זיכרון.
|
||||
- **`.taskmaster/tasks/tasks.json` הוקפא** — נשמר לקריאה-בלבד כארכיון היסטורי (166 משימות שהושלמו + 4 שבוטלו). אין לכתוב אליו ואין ליצור בו משימות חדשות.
|
||||
- **26 המשימות הפתוחות** הועברו ל-issues **#433–#458**, כל אחת עם `type` / `priority` / `area` / `status`, וגוף במבנה *What & Why → הקשר → Acceptance Criteria*.
|
||||
- **30 תוויות** נוצרו בריפו: 5 שכבות (`type`/`priority`/`status`/`size`/`area`). שכבות `type`/`priority`/`status`/`size` זהות לתבנית; שכבת `area` הותאמה לתחומי legal-ai.
|
||||
|
||||
## ⚠️ מלכודת מספור
|
||||
|
||||
ב-Gitea, issues ו-PRs חולקים מרחב-מספרים אחד. מספרי ה-issue של המיגרציה מתחילים ב-**#433** כי #1–#432 כבר תפוסים (2 issues ישנים + כל ה-PRs).
|
||||
|
||||
**לכן: כל הפניה `(#N)` בהודעת-commit מלפני 2026-08-05 מתייחסת למזהה TaskMaster — לא למספר issue.** למשל `fix(retrieval): ... (#232)` מפנה ל-TaskMaster #232, בעוד #232 ב-Gitea הוא PR ישן. הטבלה למטה היא הגשר.
|
||||
|
||||
## טבלת המיפוי
|
||||
|
||||
| TaskMaster | Gitea | תוויות | כותרת |
|
||||
|---|---|---|---|
|
||||
| #14 | [#433](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/433) | type:chore · priority:p3-low · status:deferred | Upgrade: speed up halacha+metadata extraction |
|
||||
| #116 | [#434](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/434) | type:chore · priority:p3-low · status:deferred | P2 (אופציונלי) — resume תוך-פאנל: פירוק הפאנל ל-map per-item |
|
||||
| #121 | [#435](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/435) | type:spike · priority:p1-high · status:needs-decision | מיפוי כל שערי-האישור-האנושי (חיים/דפנה) והכרעה פר-מקום: להחליף ב"קונצנזוס תלת-מודלי ללא-אדם"? |
|
||||
| #124 | [#436](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/436) | type:feature · priority:p3-low · status:ready | קטלוג עלון חודשי "עו"ד על נדל"ן" — פיצול ל-N רשומות digest (design-open) |
|
||||
| #125 | [#437](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/437) | type:chore · priority:p1-high · status:in-progress | אופרציונליזציה של לולאת רכישת-הסגנון — סגירת ממצאי אודיט #122 |
|
||||
| #126 | [#438](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/438) | type:chore · priority:p2-normal · status:in-progress | ניקוי persona "Hermes" → Curator + כיבוי self-learning אינרטי בפרופילי ה-curator |
|
||||
| #128 | [#439](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/439) | type:chore · priority:p2-normal · status:ready | X14 finalize: ניקוי-דיסק אחרי soak + replication off-site מתוזמן (SNSD) |
|
||||
| #129 | [#440](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/440) | type:chore · priority:p2-normal · status:ready | INV-STG1 Phase 2: read-wire ה-pipeline ל-ensure_local → כתיבת-בלוב ל-S3 בלבד (ללא דיסק) |
|
||||
| #147 | [#441](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/441) | type:bug · priority:p3-low | חילוץ-הלכות: אטומיות-מלאה ל-force re-extract (extract-then-swap / staging_run_id) |
|
||||
| #150 | [#442](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/442) | type:feature · priority:p2-normal | משיכת פרטי-תב"ע אוטומטית למרשם-התכניות (V38) + עיון בתכניות-מאושרות |
|
||||
| #154 | [#443](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/443) | type:feature · priority:p1-high | X11 Phase 2 — חיווט סמכות-תקדים מודעת-טיפול לסוכני-המחקר |
|
||||
| #155 | [#444](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/444) | type:bug · priority:p1-high | באג עמידות: ריצת-heartbeat כפולה על אותו issue דורסת טיוטת-קובץ תוך כדי כתיבה |
|
||||
| #163 | [#445](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/445) | type:bug · priority:p2-normal | חקירת אנומליית chunking — פסיקות עליון ארוכות מקבלות chunk יחיד → 0 הלכות |
|
||||
| #209 | [#446](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/446) | type:bug · priority:p3-low | Plugin status-sync מכוון ל-issue-ילד ומחזיר done→in_progress |
|
||||
| #217 | [#447](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/447) | type:chore · priority:p2-normal | בלוק-י: צמצום-הקשר ממוקד-רלוונטיות (איכות + מניעת-דחיסה) |
|
||||
| #218 | [#448](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/448) | type:feature · priority:p1-high · status:in-progress | Escalation primitive מדורג-חומרה בשער-הפלטפורמה (השראת Gastown gt escalate) |
|
||||
| #219 | [#449](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/449) | type:feature · priority:p1-high · status:in-progress | טלמטריה מובנית (OpenTelemetry) על שכבת-הסוכנים (השראת Gastown OTel) |
|
||||
| #220 | [#450](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/450) | type:feature · priority:p2-normal · status:in-progress | Seance — תשאול סשן-קודם לצמצום re-work של blind-heartbeats (השראת Gastown gt seance) |
|
||||
| #221 | [#451](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/451) | type:feature · priority:p2-normal · status:deferred | Molecules — פייפליין 12-הבלוקים כתבנית הצהרתית עם checkpoint-recovery (השראת Gastown formulas) |
|
||||
| #222 | [#452](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/452) | type:feature · priority:p2-normal · status:in-progress | טקסונומיית-בריאות מפורשת לסוכן ב-dashboard (Zombie/Stalled/Working/Idle — השראת Gastown gt feed --problems) |
|
||||
| #225 | [#453](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/453) | type:spike · priority:p2-normal · status:needs-decision | בית-אב לדוקטרינה-משפטית של דפנה (chair legal-doctrine home) — תכנון בלבד |
|
||||
| #228 | [#454](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/454) | type:bug · priority:p1-high | תשובת-interaction/הערה על issue בבעלות-אדם לא מעירה את ה-CEO — לנתב דרך פרימיטיב CEO-child (#227) |
|
||||
| #229 | [#455](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/455) | type:bug · priority:p1-high | block_writer שומר טקסט-שיחה של המודל לתוך תוכן הבלוק — נדרש שער-ניקוי בכתיבה |
|
||||
| #230 | [#456](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/456) | type:bug · priority:p2-normal | extractor._text_quality_ok לא מזהה סדר-קריאה RTL משובש ב-PDF דיגיטלי |
|
||||
| #231 | [#457](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/457) | type:bug · priority:p1-high · status:ready | סוכני Paperclip מנותקים משרת ה-MCP legal-ai — ACP הפך לברירת-מחדל ב-claude_local |
|
||||
| #233 | [#458](https://gitea.nautilus.marcusgroup.org/ezer-mishpati/legal-ai/issues/458) | type:bug · priority:p1-high · status:ready | צבירת-הטיעונים מוחקת צד שלם בשקט — 310 טענות עוררים → 0 טיעונים, status ok |
|
||||
|
||||
## משימות שנסגרו בזמן המיגרציה (לא הועברו)
|
||||
|
||||
| TaskMaster | למה נסגרה |
|
||||
|---|---|
|
||||
| #223 | PR #393 מוזג — בחירת פרוטוקול לפי `protocol_scope`. אומת ב-1069-04-26. |
|
||||
| #224 | PRs #392 + #403 מוזגו — `claims.party_name` במקור + פיצול משיבים. אומת ב-1069-04-26. |
|
||||
| #232 | PR #431 מוזג — 104 החלטות ועדות-ערר היו מסוננות מהחיפוש (סינון בברירת-מחדל). מלכודת 3 נסגרה ב-PR #432. |
|
||||
|
||||
## מה עדיין דורש עבודה ידנית
|
||||
|
||||
- **`size:` לא הוקצה** לאף issue — TaskMaster לא החזיק הערכות-גודל, ולא רציתי להמציא אותן. לפי כלל התבנית, issue ללא AC+size אינו `status:ready`.
|
||||
- **21 מתוך 26 issues ללא Acceptance Criteria** — הן הועברו מ-TaskMaster בלי `testStrategy`, וגוף ה-issue מסמן זאת במפורש. לפני לקיחת issue כזה — להגדיר AC, להקצות `size`, ולסמן `status:ready`.
|
||||
- 5 שכן קיבלו `status:ready` (היה להן `testStrategy`): #436, #439, #440, #457, #458.
|
||||
@@ -34,6 +34,26 @@ logger = logging.getLogger(__name__)
|
||||
_SUGGEST_PER_ISSUE = 4
|
||||
_SUGGEST_FLOOR = 0.45
|
||||
|
||||
#: Concurrent per-argument retrievals. The fan-out used to be unbounded — one
|
||||
#: task per legal argument — which is self-defeating, not merely risky: each
|
||||
#: task opens a Voyage embed call, and past ~8 in flight Voyage throttles, so
|
||||
#: every request stalls together. Measured on this corpus (32 arguments):
|
||||
#:
|
||||
#: one search alone ...... 1.2s
|
||||
#: 32 unbounded .......... 30.4s ← 25× a single search
|
||||
#: 32 at 8 concurrent .... 22.1s ← bounded is FASTER
|
||||
#:
|
||||
#: A 69-argument case (1069-04-26) therefore blew past the 30s proxy timeout and
|
||||
#: returned 500, and overlapping page reloads piled contention into Postgres
|
||||
#: deadlocks. Bounding the fan-out both fixes the failure and speeds it up.
|
||||
_MAX_CONCURRENT_LOOKUPS = 8
|
||||
|
||||
#: Wall-clock ceiling for the whole retrieval phase. The proxy gives up at 30s;
|
||||
#: cutting ourselves off earlier lets us return the suggestions that DID land
|
||||
#: instead of a 500 that shows the chair nothing. Partial results are labelled
|
||||
#: (``retrieval_complete: false``) rather than passed off as the full picture.
|
||||
_RETRIEVAL_BUDGET_S = 22.0
|
||||
|
||||
|
||||
async def build_view(case_number: str) -> dict:
|
||||
case = await db.get_case_by_number(case_number)
|
||||
@@ -87,9 +107,42 @@ async def build_view(case_number: str) -> dict:
|
||||
authority = await db.citation_authority(clids) if clids else {}
|
||||
return hits, authority
|
||||
|
||||
# Fan out the expensive per-argument retrieval concurrently — was a sequential
|
||||
# waterfall (N args × Voyage embed + vector search each). gather preserves order.
|
||||
fetched = await asyncio.gather(*(_fetch(a) for a in args)) if args else []
|
||||
# Fan out the expensive per-argument retrieval, but BOUNDED — see
|
||||
# _MAX_CONCURRENT_LOOKUPS. gather preserves order, so the zip below still
|
||||
# pairs each argument with its own result.
|
||||
_sem = asyncio.Semaphore(_MAX_CONCURRENT_LOOKUPS)
|
||||
|
||||
async def _fetch_bounded(a: dict) -> tuple[list[dict], dict]:
|
||||
async with _sem:
|
||||
return await _fetch(a)
|
||||
|
||||
retrieval_complete = True
|
||||
fetched: list[tuple[list[dict], dict]] = []
|
||||
if args:
|
||||
# Harvest whatever finished inside the budget, per argument. Deliberately
|
||||
# NOT wait_for(gather(...)): that cancels every task on timeout, so one
|
||||
# slow lookup would throw away the 30 that already succeeded and the page
|
||||
# would show nothing at all.
|
||||
tasks = [asyncio.ensure_future(_fetch_bounded(a)) for a in args]
|
||||
done, pending = await asyncio.wait(tasks, timeout=_RETRIEVAL_BUDGET_S)
|
||||
for t in pending:
|
||||
t.cancel()
|
||||
if pending:
|
||||
# Let the cancellations settle before the caller's DB pool unwinds —
|
||||
# a task cancelled mid-query otherwise surfaces as a stray
|
||||
# "connection_lost" future with no owner.
|
||||
await asyncio.gather(*pending, return_exceptions=True)
|
||||
retrieval_complete = False
|
||||
logger.warning(
|
||||
"citation_verification: retrieval budget of %.0fs exhausted for %s "
|
||||
"— %d of %d arguments returned suggestions, the rest are empty",
|
||||
_RETRIEVAL_BUDGET_S, case_number, len(done), len(args),
|
||||
)
|
||||
for t in tasks:
|
||||
if t in done and not t.cancelled() and t.exception() is None:
|
||||
fetched.append(t.result())
|
||||
else:
|
||||
fetched.append(([], {}))
|
||||
|
||||
out_args: list[dict] = []
|
||||
n_verified = 0
|
||||
@@ -137,6 +190,11 @@ async def build_view(case_number: str) -> dict:
|
||||
return {
|
||||
"status": "ok",
|
||||
"case_number": case_number,
|
||||
# False when the retrieval budget ran out: the attached/verified rows and
|
||||
# the radar are complete, but the corpus SUGGESTIONS are missing. The UI
|
||||
# must say so — an empty suggestion list otherwise reads as "no precedent
|
||||
# in the corpus supports this argument", which is a different claim.
|
||||
"retrieval_complete": retrieval_complete,
|
||||
"arguments": out_args,
|
||||
"summary": {
|
||||
"arguments_total": len(out_args),
|
||||
|
||||
81
mcp-server/tests/test_citation_view_fanout.py
Normal file
81
mcp-server/tests/test_citation_view_fanout.py
Normal file
@@ -0,0 +1,81 @@
|
||||
"""The citation-verification view must not fan out without a bound.
|
||||
|
||||
`build_view` used to spawn one retrieval task per legal argument with a bare
|
||||
`asyncio.gather`. Each task opens a Voyage embed call, and past ~8 in flight
|
||||
Voyage throttles — so the unbounded version was *slower* than a bounded one
|
||||
(32 arguments: 30.4s unbounded vs 22.1s at 8), and a 69-argument case blew past
|
||||
the 30s proxy timeout and returned 500 while overlapping reloads piled
|
||||
contention into Postgres deadlocks.
|
||||
|
||||
These tests pin the two properties that fix gave us: the fan-out is bounded,
|
||||
and a timeout yields the results that DID land instead of nothing.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
|
||||
import pytest
|
||||
|
||||
from legal_mcp.services import case_citation_verification as ccv
|
||||
|
||||
|
||||
def test_concurrency_bound_is_set_and_modest():
|
||||
assert 1 <= ccv._MAX_CONCURRENT_LOOKUPS <= 16, (
|
||||
"the bound exists to stay under Voyage's throttle point — a large value "
|
||||
"reintroduces the stall this was added to fix"
|
||||
)
|
||||
|
||||
|
||||
def test_retrieval_budget_leaves_room_under_the_proxy_timeout():
|
||||
"""The proxy gives up at 30s; we must cut ourselves off before that."""
|
||||
assert 0 < ccv._RETRIEVAL_BUDGET_S < 30
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_semaphore_actually_caps_in_flight_work():
|
||||
"""A semaphore of N never lets N+1 coroutines run the body at once."""
|
||||
limit = ccv._MAX_CONCURRENT_LOOKUPS
|
||||
sem = asyncio.Semaphore(limit)
|
||||
in_flight = 0
|
||||
peak = 0
|
||||
|
||||
async def worker():
|
||||
nonlocal in_flight, peak
|
||||
async with sem:
|
||||
in_flight += 1
|
||||
peak = max(peak, in_flight)
|
||||
await asyncio.sleep(0.01)
|
||||
in_flight -= 1
|
||||
|
||||
await asyncio.gather(*(worker() for _ in range(limit * 4)))
|
||||
assert peak <= limit
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_timeout_harvests_finished_work_instead_of_discarding_it():
|
||||
"""The regression: wait_for(gather(...)) cancels everything on timeout, so
|
||||
one slow lookup threw away every result that had already succeeded. The
|
||||
harvest pattern must keep them."""
|
||||
|
||||
async def quick(i):
|
||||
await asyncio.sleep(0.01)
|
||||
return i
|
||||
|
||||
async def never():
|
||||
await asyncio.sleep(30)
|
||||
return "unreachable"
|
||||
|
||||
tasks = [asyncio.ensure_future(quick(i)) for i in range(5)]
|
||||
tasks.append(asyncio.ensure_future(never()))
|
||||
|
||||
done, pending = await asyncio.wait(tasks, timeout=0.3)
|
||||
for t in pending:
|
||||
t.cancel()
|
||||
await asyncio.gather(*pending, return_exceptions=True)
|
||||
|
||||
harvested = [
|
||||
t.result() if (t in done and not t.cancelled() and t.exception() is None) else None
|
||||
for t in tasks
|
||||
]
|
||||
assert harvested[:5] == [0, 1, 2, 3, 4], "finished work must survive the timeout"
|
||||
assert harvested[5] is None, "the unfinished one is empty, not fabricated"
|
||||
assert len(pending) == 1
|
||||
Reference in New Issue
Block a user