diff --git a/docs/spec/gap-audit.md b/docs/spec/gap-audit.md new file mode 100644 index 0000000..6537de4 --- /dev/null +++ b/docs/spec/gap-audit.md @@ -0,0 +1,125 @@ +# Gap-Audit — פערים בין המערכת הקיימת ל-spec + +מסמך זה הוא **מפת-הפערים הקנונית** בין המערכת הקיימת (קוד ב-`web/`, `mcp-server/`, +`scripts/`) לבין ה-invariants שב-[`docs/spec/`](README.md). הוא תוצר של תת-פרויקט 2 +(מיפוי-פערים), ומובחן מ-[`docs/audit-report.md`](../audit-report.md) הישן: ה-audit הוא +דוח-מצב נקודתי, וזה ה-gap-map שמקשר כל ממצא ל-invariant מופר וליחידת-תיקון. + +**איך הופק:** סקירה חוצת-קבצים של כל קבצי-הספ (00 + 01–07 + X1–X5) מול הקוד הקיים, +30.5.2026. כל ממצא נושא: `invariant מופר` (ה-G*/INV-* שהוא סותר), הערכת-`severity`, +`קבצים מושפעים` (file:line), ו-`תיקון מוצע`. + +**הערה על severity/priority:** דירוג ה-severity להלן הוא הערכה הנדסית (לפי סיכון +לשלמות-נתונים, דליפה חוצת-קורפוס, ועקיפת שער אנושי). **קביעת ה-priority בפועל — +מה לתקן ראשון — היא של היו"ר.** ה-severity מנמק; הוא אינו מכריע. + +--- + +## 23 הממצאים + +| ID | כותרת | invariant מופר | severity | קבצים מושפעים (file:line) | תיקון מוצע | +|----|-------|----------------|----------|---------------------------|------------| +| GAP-01 | שני מסלולי ingest מקבילים שמתפצלים | INV-ING1, G2 | High | `precedent_library.py:88`, `internal_decisions.py:73` | מסלול-קליטה קנוני יחיד; ישויות-אחיות חולקות פייפליין | +| GAP-02 | ingest פנימי מדלג על חילוץ metadata | INV-ING3, DM1, RET2 | Critical | `internal_decisions.py:208` | להוסיף `request_metadata_extraction` לכל סוג; חוסם indexing ריק | +| GAP-03 | אין upsert דטרמיניסטי על מזהה קנוני | INV-ING2, G3 | Critical | `precedent_library.py`, `internal_decisions.py` | upsert על מפתח קנוני — קליטה חוזרת = update לא duplicate | +| GAP-04 | ולידציית-enum א-סימטרית | INV-G4 | Medium | `precedent_library.py:131-134` | להחיל אותה ולידציית practice_area/source_type בשני המסלולים | +| GAP-05 | staging/derivation/citation-guard/multimodal/fallback א-סימטריים | INV-ING1, G2 | High | `01-ingest §4` (שני המסלולים) | מיזוג כל שלבי-העיבוד למסלול הקנוני האחד | +| GAP-06 | case_number מנורמל בקריאה בלבד | INV-G1, ID1 | High | `db.py:1196-1211` | נרמול בנקודת-הכתיבה; `8126-25`→canonical | +| GAP-07 | מספרי-תיק מעורבים (חודש/חסר) — reconciliation חד-פעמי | INV-ID1 | High | data (cases, case_law) | מיגרציה: canonical = הצורה הרשמית שהוקצתה [chair-confirmed] | +| GAP-08 | ציטוט-מלא נשמר כ-case_number | INV-DM2, ID2 | Medium | data (legacy pre-V15) | ניקוי: ציטוט = שדה-תצוגה נגזר, לא מזהה | +| GAP-09 | `embedding` אינו GENERATED (בניגוד ל-tsvectors) | INV-DM3, RET, G6 | High | schema (chunks/case_law) | re-index באכיפה — טריגר או GENERATED-equivalent בשינוי תוכן | +| GAP-10 | דליפת הלכה חוצת-קורפוס | INV-RET1, G5 | Critical | `db.py:3168`, `db.py:3401`, JOINs `3236-3238`/`3475-3477` | להוסיף `cl.source_kind` ל-halacha_filters | +| GAP-11 | אין eval harness / gold-set מתויג | INV-RET4, G8 | High | `telemetry.log_search_bg` (היחיד) | להקים eval harness + gold-set; precision/recall נמדד | +| GAP-12 | search_decisions מזהיר אך לא חוסם practice_area חסר | INV-RET, G5 | High | `search.py:45-49`, `search.py:172-176` | לחסום query בלי practice_area — ערבוב-תחום אסור | +| GAP-13 | אין דגל `searchable` מפורש | INV-DM1 | Medium | schema (case_law, chunks) | דגל `searchable` שמסומן רק כשחוזה-השלמות מתקיים | +| GAP-14 | backlog הלכות סמוי | INV-QA1, G10 | Medium | (אין health-check) | לחשוף `pending_review` ב-health-check / dashboard | +| GAP-15 | שער-ייצוא נאכף-זרימה ולא נאכף-קוד | INV-QA3, EX3 | Critical | `drafting.py:384` | `export_docx` קורא `validate_decision` + בודק `export_blocked` | +| GAP-16 | neutral_background קריטי-אך-עובר | INV-QA3 (`05 §1.2`) | High | `qa_validator.py:70` | בלוק-ו ריק/חסר = passed=False; חוסם ייצוא | +| GAP-17 | active_draft_path נגזר זוחל ל-source-of-truth | INV-EX1, AUD2 | High | `db.py:189` | DOCX = נגזר; re-sync בלוקים אחרי revise/apply_user_edit | +| GAP-18 | audit_log כמעט לא נכתב | INV-AUD1 | High | `cases.py:203` (היחיד) | כתיבת audit על upload/extract/write_block/export | +| GAP-19 | אין קישור block→source-chunks | INV-AUD1 | High | `decision_blocks` (model_used בלבד) | לתעד אילו chunks/precedents הזינו כל בלוק | +| GAP-20 | citation→corpus לא נאכף אוטומטית | INV-AUD3 | Medium | `decision_paragraphs.citations` | ולידציה שכל ציטוט בטקסט פתיר לקורפוס | +| GAP-21 | cross-company sync ידני ולא-נאכף | INV-MC1 | Medium | `sync_agents_across_companies.py:387-389` | אכיפת `--apply` אחרי שינוי-Master; להרעיש על דילוג adapter_type | +| GAP-22 | אינטגרציית-Paperclip על נוהל ולא מחסום-קוד | INV-INT1, INT3 | Medium | schema / lint (אין) | אילוץ-schema נגד DB-insert; linter נגד httpx/curl גולמי | +| GAP-23 | הספ עדיין לא מחובר לסוכנים | INV-AG1 | High | `.claude/agents/HEARTBEAT.md`, agent files | חובת קריאת 00-constitution + ספ-תחום לפני פעולה | + +--- + +## יחידות-תיקון מוצעות (Proposed Fix-Units) + +23 הממצאים מקובצים ל-8 יחידות-עבודה קוהרנטיות. הקיבוץ נגזר מהעיקרון שרבים מהממצאים +נפתרים יחד (כל פערי ה-ingest-asymmetry → יחידה אחת). זהו זרע למשימות TaskMaster +ולתת-פרויקט 3 (שכבת-שלמות). + +### FU-1 — איחוד מסלול-הקליטה (Unify ingest path) +- **מכסה:** GAP-01, GAP-02, GAP-04, GAP-05 +- **מספק invariants:** INV-ING1, INV-ING3, INV-G2, INV-G4; (תורם ל-DM1/RET2 דרך GAP-02) +- **effort:** L +- **תלויות:** — (יסוד — FU-2/FU-3 נשענים עליה) +- **סוג:** pure-code + +### FU-2 — קליטה idempotent + מזהים קנוניים +- **מכסה:** GAP-03, GAP-06, GAP-07, GAP-08, GAP-13 +- **מספק invariants:** INV-ING2, INV-G3, INV-G1, INV-ID1, INV-ID2, INV-DM2, INV-DM1 +- **effort:** L +- **תלויות:** FU-1 (מסלול אחד לפני upsert אחיד) +- **סוג:** **data-migration** — GAP-07 reconciliation של case_number מעורב (chair-confirmed), + GAP-08 ניקוי ציטוט-כ-מזהה; + code (upsert key, write-time normalize, דגל searchable) + +### FU-3 — re-index באכיפה בשינוי-תוכן +- **מכסה:** GAP-09 +- **מספק invariants:** INV-DM3, INV-G6, INV-RET (freshness) +- **effort:** M +- **תלויות:** FU-1 (re-embed יושב בקליטה הקנונית) +- **סוג:** **data-migration** — re-chunk/re-embed של רשומות קיימות + טריגר/אכיפה קדימה + +### FU-4 — הפרדת-קורפוס נאכפת בכל query +- **מכסה:** GAP-10, GAP-12 +- **מספק invariants:** INV-RET1, INV-G5 +- **effort:** M +- **תלויות:** — (עצמאי; דחוף — Critical leak) +- **סוג:** pure-code + +### FU-5 — eval harness + נראות-בריאות +- **מכסה:** GAP-11, GAP-14 +- **מספק invariants:** INV-RET4, INV-G8, INV-QA1, INV-G10 (נראות backlog) +- **effort:** M +- **תלויות:** FU-2 (gold-set יציב דורש מזהים קנוניים) +- **סוג:** pure-code + **chair-decision** — הגדרת gold-set מתויג דורשת אישור היו"ר + (מה "תוצאה נכונה" לכל query) + +### FU-6 — שערי-QA נאכפים-קוד (Code-enforced gates) +- **מכסה:** GAP-15, GAP-16 +- **מספק invariants:** INV-QA3, INV-EX3, INV-G10 +- **effort:** S +- **תלויות:** — (עצמאי; חוסם עקיפת-ייצוא) +- **סוג:** pure-code + +### FU-7 — Audit-trail + provenance (זרע תת-פרויקט 3) +- **מכסה:** GAP-17, GAP-18, GAP-19, GAP-20 +- **מספק invariants:** INV-AUD1, INV-AUD2, INV-AUD3, INV-EX1, INV-G9 +- **effort:** L +- **תלויות:** FU-1 (provenance נלכד בקליטה/כתיבה הקנונית) +- **סוג:** pure-code (schema-additive) — חלק מ-GAP-17 דורש **data-backfill** קל + לסנכרון בלוקים↔DOCX קיימים + +### FU-8 — מחסומי-תהליך הופכים למחסומי-קוד +- **מכסה:** GAP-21, GAP-22, GAP-23 +- **מספק invariants:** INV-MC1, INV-INT1, INV-INT3, INV-AG1 +- **effort:** M +- **תלויות:** ה-spec גמור (GAP-23 דורש קבצי-ספ יציבים לחבר לסוכנים) +- **סוג:** pure-code + **chair-decision** — GAP-23 (חיבור ספ לסוכני-Paperclip) הוא + prerequisite לתת-פרויקט 5 ומשנה התנהגות-סוכן בייצור + +--- + +## סיכום סיווג לפי סוג-עבודה + +- **pure-code (ללא מיגרציה):** FU-1, FU-4, FU-6; הליבה של FU-7, FU-8. +- **דורש data-migration:** FU-2 (case_number reconciliation, ניקוי ציטוטים), FU-3 + (re-chunk/re-embed), backfill קל ב-FU-7 (סנכרון בלוקים↔DOCX). +- **דורש chair-decision:** FU-5 (הגדרת gold-set), FU-8/GAP-23 (חיבור ספ לסוכנים); + GAP-07 כבר chair-confirmed (canonical = הצורה הרשמית שהוקצתה). + +**רצף מומלץ (תלויות):** FU-1 → FU-2 → FU-3; FU-4 ו-FU-6 במקביל (עצמאיים, Critical); +FU-7 אחרי FU-1; FU-5 אחרי FU-2; FU-8 אחרי ייצוב-הספ.