From a5b22dadf31348429af6a2f243b3b6775f1f7f9f Mon Sep 17 00:00:00 2001 From: Chaim Date: Sat, 30 May 2026 14:05:06 +0000 Subject: [PATCH] docs(spec): master design for system spec + integrity layer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Establishes the foundation to fix a recurring root-cause failure class (non-canonical identifiers, asymmetric ingest paths, silent manual gates): - Confirmed system mission (quasi-judicial decision assistant; human decides) - Decomposition into 5 sub-projects (spec → audit → integrity layer → re-check → process agents) - spec-set structure under docs/spec/ (lifecycle-organized + cross-cutting files) - 11 global invariants + engineering rules, each backed by ≥3 authoritative sources (NCSC/JTC, FJC, CEPEJ, South Bucks; RAG/Lewis, Manning IR, Elastic/Pinecone/Weaviate; DAMA-DMBOK, ISO 8000, ISO 15489, Kleppmann, Codd, Fowler) - 3-source verification protocol; UNVERIFIED items escalated, not decided solo Co-Authored-By: Claude Opus 4.8 --- .../specs/2026-05-30-system-spec-design.md | 168 ++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-30-system-spec-design.md diff --git a/docs/superpowers/specs/2026-05-30-system-spec-design.md b/docs/superpowers/specs/2026-05-30-system-spec-design.md new file mode 100644 index 0000000..901efa2 --- /dev/null +++ b/docs/superpowers/specs/2026-05-30-system-spec-design.md @@ -0,0 +1,168 @@ +# מסמך-עיצוב אב — ספ המערכת והשכבה החסרה (System Spec & Integrity Layer) + +**תאריך:** 2026-05-30 +**סטטוס:** עיצוב מאושר (Design approved) — ממתין לכתיבת קבצי הספ +**בעלים:** חיים מרכוס +**הקשר:** מהלך-יסוד להגדרת "מהו תקין" במערכת *עוזר משפטי*, ולסגירת כשל-שורש חוזר. + +--- + +## 1. הבעיה — כשל-השורש החוזר + +מה שנחווה כ"כל פעם משהו אחר לא מדויק" אינו אוסף תקלות אקראיות אלא **כשל אחד שחוזר בתחפושות**. ראיות שצפו (30.5.2026): + +| תסמין | שורש | +|--------|------| +| `8126-25` לא נמצא (האמיתי `8126-03-25`); קומיט "tolerant case_number lookup" | אין מפתח קנוני — מתקנים תסמין בקריאה | +| 3 החלטות "סופר" ב-3 פורמטים שונים (`8126/24`, ציטוט-מלא-כ-case_number) | אין חוזה-נתונים אחיד | +| ערן סופר 8046/24 עלתה בלי metadata (headnote/summary/tags ריקים) | מסלול ה-ingest הפנימי לא מתזמן חילוץ metadata — אסימטרי למסלול החיצוני | +| 10/19 הלכות מאושרות, התגלה במקרה | שער ידני שקוף בלי נראות backlog | +| משימות #56, #57 | אי-עקביות בין רכיבים (דליפה חוצת-קורפוסים, chunker) | + +**אבחנה:** המערכת גדלה בקצב *הוספת יכולות* מהר יותר מקצב *שמירת עקביות* — מסלולים/כלים/קורפוסים מקבילים שנוספים בבידוד ומתפצלים (drift), בלי שכבה שמגדירה ואוכפת "תקין". כל פגם מתגלה בדיעבד, אחד-אחד. + +**התרופה:** לא לתקן 10 דברים — להוסיף **שכבה אחת חסרה**: חוקה + חוזה-שלמות + בדיקת-בריאות אחת + איחוד מסלולי ה-ingest. זה הופך כשל מ"מתפרץ במקום אקראי" ל"נחסם בכניסה, גלוי בדשבורד". + +--- + +## 2. ייעוד המערכת (מאושר ע"י חיים) + +> מערכת AI שמסייעת ליו"ר ועדת הערר לתכנון ובנייה (מחוז ירושלים, עו"ד דפנה תמיר) לנסח **החלטות מעין-שיפוטיות כתובות ומנומקות** — מסמכים משפטיים פורמליים שעומדים לביקורת שיפוטית — תוך שמירה על **הקול, השיקול והאחריות של היו"ר**. + +- **משרת:** יו"ר הוועדה (משתמש-על) והסוכנים הפועלים בשמה. +- **מחזור-חיים:** ניהול תיקים → בסיס ידע (3 קורפוסים) → אחזור סמנטי (RAG) → סיוע-כתיבה (12 בלוקים, סגנון דפנה) → ייצוא DOCX. +- **3 סוגי עררים:** רישוי ובנייה (1xxx, חם), היטל השבחה (8xxx, קר), פיצויים ס'197 (9xxx, קר). +- **ה"למה" העמוק:** המערכת מסייעת — היו"ר מכריעה (שערים קריטיים ידניים בכוונה); מנוע צבירת-ידע (לומד מהחלטות סופיות ומפידבק); רב-חברתי (CMP/CMPA). + +--- + +## 3. עקרונות-עבודה למהלך + +1. **אסור להניח שהקיים תקין.** כל מה שמופה בקוד/בקורפוס = "טענה לבדיקה", לא "אמת". "תקין" נגזר ממקורות חיצוניים, לא מהמערכת שתחת חשד. +2. **פרוטוקול אימות 3-מקורות:** כל invariant/חוק בספ מגובה ב-**≥3 מקורות סמכותיים מוכרים** בעלי ידע מקצועי מוכח. כשאין 3 → מסומן `⚠ UNVERIFIED` ומועלה לחיים, לא מוכרע לבד. +3. **מנגנון:** מחקר עצמאי → טיוטה לביקורת. +4. **מודל-שיתוף:** על החלטות טכניות/אדריכליות אני חוקר ומכריע מקצועית ומציג תוצאה מוגמרת. שואל את חיים רק במקום שבו *הוא* הסמכות — כוונה, עדיפויות עסקיות, עובדות משפטיות-דומייניות. + +--- + +## 4. פירוק ל-5 תת-פרויקטים (לפי תלות) + +| # | תת-פרויקט | תוצר | תלות | +|---|-----------|------|------| +| 1 | **ספ המערכת + חוקה** | spec-set ב-`docs/spec/` המגדיר מודל קנוני + invariants | — | +| 2 | **מפת הפערים (Audit)** | סריקה אמפירית מול הספ → רשימת משימות | תת-פרויקט 1 | +| 3 | **שכבת שלמות-נתונים** | חוזה-שלמות באכיפת-קוד + בדיקת-בריאות אחת + **איחוד מסלולי ingest** | 1, 2 | +| 4 | **בדיקה חוזרת** | הרצת בריאות/audit אחרי התיקון | 3 | +| 5 | **סוכני-תהליך** | add-feature / fix-feature / spec-guardian — מכירים את הספ, "עושים שיעורי בית", לומדים ומתעדכנים | 1 (3) | + +כל תת-פרויקט יקבל מחזור spec→plan→implementation משלו. מסמך זה מפרט את **תת-פרויקט 1** במלואו ומקבע את ההחלטות העקרוניות לכולם. + +--- + +## 5. מבנה הספ-set (תת-פרויקט 1) + +מיקום: **`docs/spec/`** (ספ חי). ארגון קבצי-תחום: **לפי מחזור-חיים** (גישה A) — חושף ישירות אסימטריות-זרימה. + +``` +docs/spec/ +├── 00-constitution.md ← ייעוד · invariants גלובליים · כללי-הנדסה · אינדקס · תבנית-invariant · פרוטוקול-אימות +│ ── מחזור-החיים ── +├── 01-ingest.md ← קליטה מאוחדת: מסמכי-תיק / פסיקה חיצונית / החלטות-ועדה — חוזה מסלול-יחיד +├── 02-data-model.md ← אחסון: ישויות (cases, case_law, documents, chunks, halachot…) + חוזה-שלמות לכל ישות +├── 03-retrieval.md ← 3 קורפוסים + כלי-חיפוש · hybrid/RRF · attribution · eval harness · invariants +├── 04-analysis-writing.md ← חילוץ טענות · 12 בלוקים · סגנון דפנה (מצטט block-schema.md וכו') +├── 05-qa-review.md ← שערי QA + שערים אנושיים (אישור הלכה, בחירת תוצאה, פידבק) כ-invariant +├── 06-export.md ← ייצוא DOCX לפי תבנית דפנה +├── 07-learning.md ← Hermes · לקחים · לולאת פידבק היו"ר · צמיחת קורפוס (quality-at-source) +│ ── חוצי-שלבים ── +├── X1-identifiers.md ← מודל מזהים קנוני: נרמול case_number **בכתיבה** · cases מול case_law · פורמטי ציטוט +├── X2-multi-company.md ← CMP/CMPA · 14 סוכנים · כללי sync +├── X3-integration-deploy.md ← Paperclip (wakeup, ניתוב comments, webhooks) · Coolify/pm2 +├── X4-agents.md ← מפת הסוכנים (דומיין + סוכני-התהליך מתת-פרויקט 5) +└── X5-audit-provenance.md ← audit-trail לשימוש ב-AI · עקיבוּת כל מקור מצוטט · שלמות-רשומה (CEPEJ/NCSC/ISO 15489) +``` + +**עקרונות:** כל קובץ עצמאי, ממוקד, agent-readable, יעד ≤~500 שורות (תפיחה = סימן לפיצול). `00-constitution.md` = שער-כניסה יחיד. מסמכים קיימים (`architecture.md`, `product-specification.md`, `block-schema.md`…) לא נמחקים ולא משוכפלים — מצוטטים כ"מקור" ומאומתים מול הסמכויות; סתירה = ממצא ל-audit. + +### תבנית-invariant (מבנה אחיד לכל חוק בספ) +``` +### INV-<תחום><מספר>: <כותרת קצרה> +**כלל:** <ניסוח נורמטיבי חד — מה חייב להתקיים> +**מקורות:** <≥3 סמכויות> | סטטוס: verified / ⚠ UNVERIFIED +**אכיפה:** <היכן/איך נאכף — schema, ולידציית-כתיבה, בדיקת-בריאות, שער> +**הפרה ידועה:** <דוגמה מהמערכת, אם יש — מקשר ל-audit> +``` + +--- + +## 6. ה-Invariants הגלובליים (לב `00-constitution.md`) + +כל אחד מגובה ב-≥3 סמכויות (פירוט ב-§9). אלה החוקים שמייבשים את כשל-השורש: + +| # | Invariant | סמכויות | +|---|-----------|---------| +| **G1** | מזהה קנוני, **מנורמל בכתיבה** (לא תיקון-סלחני בקריאה בלבד) | SSOT/normalization · Codd 1NF · Kleppmann | +| **G2** | מקור-אמת יחיד; **אין מסלולי-קוד מקבילים שמתפצלים** — אחים חולקים מסלול קנוני אחד; derived data משוחזר | Kleppmann (system of record) · Fowler (canonical model) · SSOT | +| **G3** | ingest **אחיד ו-idempotent** (upsert על מפתח דטרמיניסטי) | Kleppmann · Stripe/CDC idempotency · ISO 8000 | +| **G4** | **חוזה-שלמות:** שדות חובה מולאו לפני שרשומה "שמישה/ניתנת-לחיפוש"; נבדק מול spec מפורש | ISO 8000 · DAMA (completeness) · ISO 15489 (reliability) | +| **G5** | metadata מלא לכל פריט מואנדקס + **הפרדת-קורפוס נאכפת בכל מסלול-query** | Pinecone (multitenancy) · RAG attribution · ISO 8000 | +| **G6** | **re-index בכל שינוי תוכן** (אין embeddings מיושנים) | Pinecone · Weaviate · RAG freshness | +| **G7** | מיזוג **לפי דירוג (RRF)**, לא סכום-ציונים גולמי בין retrievers | Elastic · Weaviate · OpenSearch/Azure (corrob.) | +| **G8** | איכות-אחזור **נמדדת (precision+recall)**, לא מונחת | Manning (IR textbook) · RAG eval literature | +| **G9** | כל פלט **עקיב למקורו** + audit-trail לשימוש ב-AI | CEPEJ (user control) · NCSC · ISO 15489 | +| **G10** | המערכת מסייעת; **שערים אנושיים** (אישור הלכה/תוצאה/פידבק) הם invariant, לא רשות | NCSC · CEPEJ · FJC | +| **G11** | **תוכן החלטה מנומקת:** רקע ניטרלי · ללא כפילות · מענה לטענות המפסיד · מבחן-השופט · טענות מקוריות | FJC (Writing Manual) · South Bucks (adequacy) · חוק 1958 (חובת הנמקה) | + +### כללי-הנדסה (constitution — מונעים הישנות) +- **סימטריה:** אסור להוסיף מסלול מקביל ליכולת קיימת — מרחיבים את המסלול הקנוני. (נגזר מ-G2) +- **נרמול לא תיקון-תסמין:** מתקנים נתון במקור (קנוני), לא מטליאים בקריאה. (נגזר מ-G1) +- **Quality-at-source:** שלמות נאכפת קרוב ככל האפשר לקליטה. (Fowler/Data-Mesh) +- **אין בליעה שקטה:** רשומה חסרה מסומנת ומדווחת, לא מתקבלת בשקט. (תואם feedback קיים) + +--- + +## 7. פרוטוקול-אימות ומודל-שיתוף (ייכנס ל-`00-constitution.md`) + +- כל invariant נושא `מקורות` + `סטטוס: verified / ⚠ UNVERIFIED`. +- `⚠ UNVERIFIED` (פחות מ-3 מקורות) → לא מוכרע לבד; מועלה לחיים. +- החלטות טכניות → מחקר עצמאי + הכרעה מקצועית + הצגת תוצאה. שאלה לחיים רק במקום שהוא הסמכות. + +--- + +## 8. פריטים פתוחים — אימות-מקור-ראשוני נדרש +(החוקר אימת מסגרת; הפריטים הישראליים דורשים אימות לפני ציטוט כ-סמכות, בשלב כתיבת `04`/`05`/`X5`) +1. מספר הסעיף המדויק בחוק לתיקון סדרי המינהל (החלטות והנמקות) תשי"ט-1958 (וכן תיקון תשכ"ט-1969). +2. ציטוט מדויק מ-ברק-ארז, *משפט מינהלי*. +3. אסמכתאות פסיקה: בג"ץ 143/56; עע"ם 2994/21 (מעמד ועדת ערר כגוף תכנוני-מקצועי). + +--- + +## 9. נספח מקורות סמכותיים (מאומתים במחקר 30.5.2026) + +**ממשל-AI שיפוטי + מבנה החלטה מנומקת** +- NCSC / JTC — *Court Technology Standards* + *Principles & Practices for AI Use in Courts*. https://www.ncsc.org/our-centers-projects/joint-technology-committee/court-technology-standards +- Federal Judicial Center — *Judicial Writing Manual* (2d ed.). https://www.fjc.gov/content/judicial-writing-manual-pocket-guide-judges-second-edition +- Council of Europe / CEPEJ — *European Ethical Charter on the use of AI in judicial systems* (2018). +- *South Buckinghamshire DC v Porter (No 2)* [2004] UKHL 33 (adequacy of reasons). https://publications.parliament.uk/pa/ld200304/ldjudgmt/jd040701/south-1.htm +- חוק לתיקון סדרי המינהל (החלטות והנמקות), תשי"ט-1958. https://www.nevo.co.il/law_html/law00/98603.htm +- Kevin D. Ashley — *Artificial Intelligence and Legal Analytics* (CUP). + +**אחזור / RAG / IR** +- Lewis et al. (2020) — *Retrieval-Augmented Generation* (NeurIPS). https://arxiv.org/abs/2005.11401 +- Manning, Raghavan & Schütze — *Introduction to Information Retrieval* (CUP, 2008). https://nlp.stanford.edu/IR-book/ +- Elastic — *Reciprocal Rank Fusion*. https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion +- Pinecone — *Implement multitenancy*. https://docs.pinecone.io/guides/index-data/implement-multitenancy +- Weaviate — *Hybrid Search Explained*. https://weaviate.io/blog/hybrid-search-explained + +**שלמות-נתונים / איכות / רשומות** +- DAMA-DMBOK2 + DAMA-UK — *Six Primary Dimensions for Data Quality* (2013). +- ISO 8000 — Data quality (8000-8/61/110). +- ISO 15489-1:2016 — Records management (authenticity/reliability/integrity/usability). +- Martin Kleppmann — *Designing Data-Intensive Applications* (O'Reilly, 2017). +- E.F. Codd — Relational model & normalization (CACM 13(6), 1970). +- Martin Fowler — Canonical Data Model / Data Mesh (quality-at-source). + +--- + +## 10. השלב הבא +לאחר ביקורת חיים על מסמך זה → invoke `writing-plans` לבניית תוכנית-יישום מפורטת לתת-פרויקט 1 (כתיבת קבצי הספ-set, החל מ-`00-constitution.md`).