diff --git a/docs/spec/00-constitution.md b/docs/spec/00-constitution.md new file mode 100644 index 0000000..c731a43 --- /dev/null +++ b/docs/spec/00-constitution.md @@ -0,0 +1,269 @@ +# 00 — חוקת המערכת (Constitution) + +זהו שער-הכניסה היחיד לספ המערכת *עוזר משפטי*. הוא מגדיר את הייעוד, עקרונות-העבודה, +תבנית ה-invariant, פרוטוקול-האימות, ה-invariants הגלובליים (G1–G11), כללי-ההנדסה, +אינדקס הספ ונספח המקורות. כל קובץ-תחום (01–07, X1–X5) כפוף לחוקה זו ומפנה אליה. + +--- + +## 1. ייעוד + +> מערכת AI שמסייעת ליו"ר ועדת הערר לתכנון ובנייה (מחוז ירושלים, עו"ד דפנה תמיר) לנסח +> **החלטות מעין-שיפוטיות כתובות ומנומקות** — מסמכים משפטיים פורמליים שעומדים לביקורת +> שיפוטית — תוך שמירה על **הקול, השיקול והאחריות של היו"ר**. + +- **משרת:** יו"ר הוועדה (משתמש-על) והסוכנים הפועלים בשמה. +- **מחזור-חיים:** ניהול תיקים → בסיס ידע (3 קורפוסים) → אחזור סמנטי (RAG) → סיוע-כתיבה + (12 בלוקים, סגנון דפנה) → ייצוא DOCX. +- **3 סוגי עררים:** רישוי ובנייה (1xxx, חם), היטל השבחה (8xxx, קר), פיצויים ס'197 (9xxx, קר). +- **ה"למה" העמוק:** המערכת מסייעת — היו"ר מכריעה (שערים קריטיים ידניים בכוונה); מנוע + צבירת-ידע (לומד מהחלטות סופיות ומפידבק); רב-חברתי (CMP/CMPA). + +--- + +## 2. עקרונות-עבודה + +1. **אסור להניח שהקיים תקין.** כל מה שמופה בקוד/בקורפוס = "טענה לבדיקה", לא "אמת". + "תקין" נגזר ממקורות חיצוניים סמכותיים, לא מהמערכת שתחת חשד. +2. **פרוטוקול אימות 3-מקורות:** כל invariant/חוק בספ מגובה ב-**≥3 מקורות סמכותיים מוכרים** + בעלי ידע מקצועי מוכח. כשאין 3 → מסומן `⚠ UNVERIFIED` ומועלה ליו"ר, לא מוכרע לבד. +3. **מנגנון:** מחקר עצמאי → טיוטה לביקורת. קודם חוקרים את הסמכויות החיצוניות, ורק אז + מנסחים את החוק/ההחלטה. +4. **מודל-שיתוף:** על החלטות טכניות/אדריכליות אני חוקר ומכריע מקצועית ומציג תוצאה + מוגמרת. שואל את היו"ר (חיים) רק במקום שבו *הוא* הסמכות — כוונה, עדיפויות עסקיות, + עובדות משפטיות-דומייניות. + +--- + +## 3. תבנית-invariant + +מבנה אחיד לכל חוק בספ (בכל הקבצים): + +``` +### INV-<תחום><מספר>: <כותרת קצרה> +**כלל:** <ניסוח נורמטיבי חד — מה חייב להתקיים> +**מקורות:** <≥3 סמכויות> | סטטוס: verified / ⚠ UNVERIFIED +**אכיפה:** <היכן/איך נאכף — schema / ולידציית-כתיבה / בדיקת-בריאות / שער אנושי> +**הפרה ידועה:** <דוגמה מהמערכת, אם יש — מקשר ל-audit; אחרת "—"> +``` + +--- + +## 4. פרוטוקול-אימות + +- כל invariant נושא שדה `מקורות` + `סטטוס: verified / ⚠ UNVERIFIED`. +- **verified** = מגובה ב-**≥3 מקורות סמכותיים** מוכרים בעלי ידע מקצועי מוכח. +- **⚠ UNVERIFIED** = פחות מ-3 מקורות מאומתים, או פריט שדורש אימות-מקור-ראשוני + (למשל ציטוט חקיקה ישראלי מדויק). פריט כזה **לא מוכרע לבד** — מועלה ליו"ר עם + הערת-הסלמה המתעדת מה חסר והיכן יאומת. +- החלטות טכניות → מחקר עצמאי + הכרעה מקצועית + הצגת תוצאה. שאלה ליו"ר רק במקום + שבו הוא הסמכות (ראה עיקרון 4 לעיל). + +--- + +## 5. Invariants גלובליים (G1–G11) + +אלה החוקים החוצים את כל המערכת — לב החוקה. כל אחד מגובה ב-≥3 סמכויות (נספח §8). +ביחד הם מייבשים את כשל-השורש החוזר: מסלולים/קורפוסים מקבילים שמתפצלים (drift) בלי +שכבה שמגדירה ואוכפת "תקין". + +### INV-G1: מזהה קנוני מנורמל בכתיבה +**כלל:** לכל ישות יש מזהה קנוני יחיד, **מנורמל בנקודת-הכתיבה** (לא תיקון-סלחני בקריאה +בלבד). `case_number` נשמר בצורה קנונית אחת; קריאה משווה מול הצורה הקנונית, לא מטליאה. +**מקורות:** SSOT (Single Source of Truth — normalization principle) · E.F. Codd, First +Normal Form (CACM 13(6), 1970) · Martin Kleppmann, *Designing Data-Intensive Applications* +(O'Reilly, 2017) | סטטוס: verified +**אכיפה:** schema (אילוץ ייחודיות על המפתח הקנוני) + ולידציית-כתיבה בנקודת-הקליטה; +מפורט ב-[X1-identifiers.md](X1-identifiers.md) ו-[02-data-model.md](02-data-model.md). +**הפרה ידועה:** `_normalize_case_number` סלחני בקריאה בלבד (קומיט "tolerant case_number +lookup"); `8126-25` לא נמצא מול האמיתי `8126-03-25` → ממצא ל-[audit](../audit-report.md). + +### INV-G2: מקור-אמת יחיד — אין מסלולים מקבילים מתפצלים +**כלל:** לכל סוג-נתון יש **מקור-אמת יחיד** ומסלול-קוד קנוני אחד. אסור להוסיף מסלול +מקביל ליכולת קיימת — ישויות-אחיות חולקות מסלול קנוני אחד; נתונים נגזרים (derived) +משוחזרים מהמקור, לא נכתבים במקביל. +**מקורות:** Martin Kleppmann (system of record vs. derived data, *DDIA* 2017) · Martin +Fowler (Canonical Data Model) · SSOT (Single Source of Truth) | סטטוס: verified +**אכיפה:** ביקורת-ארכיטקטורה + כלל-הנדסה "סימטריה" (§6); מפורט ב-[01-ingest.md](01-ingest.md). +**הפרה ידועה:** אסימטריה בין `ingest_precedent` (חיצוני, מתזמן חילוץ metadata) לבין +`ingest_internal_decision` (פנימי, לא מתזמן) → ממצא ל-[audit](../audit-report.md). + +### INV-G3: ingest אחיד ו-idempotent +**כלל:** קליטה היא **אחידה ו-idempotent** — upsert על מפתח דטרמיניסטי. קליטה חוזרת של +אותו פריט אינה יוצרת כפילות ואינה משנה תוצאה. +**מקורות:** Martin Kleppmann (*DDIA*, idempotence & exactly-once) · Stripe / CDC +idempotency-key pattern · ISO 8000 (Data quality) | סטטוס: verified +**אכיפה:** ולידציית-כתיבה + מפתח-upsert דטרמיניסטי בנקודת-הקליטה; מפורט ב- +[01-ingest.md](01-ingest.md). +**הפרה ידועה:** 3 החלטות "סופר" נקלטו ב-3 פורמטים שונים (`8126/24`, ציטוט-מלא +כ-case_number) — היעדר upsert דטרמיניסטי → ממצא ל-[audit](../audit-report.md). + +### INV-G4: חוזה-שלמות לפני "שמיש / ניתן-לחיפוש" +**כלל:** רשומה אינה נחשבת "שמישה" או "ניתנת-לחיפוש" עד ש**שדות-החובה שלה מולאו ואומתו +מול spec מפורש**. שלמות נבדקת לפני חשיפה לאחזור. +**מקורות:** ISO 8000 (completeness) · DAMA-UK *Six Primary Dimensions for Data Quality* +(2013, completeness) · ISO 15489-1:2016 (records reliability) | סטטוס: verified +**אכיפה:** חוזה-שלמות באכיפת-קוד + בדיקת-בריאות; מפורט ב-[02-data-model.md](02-data-model.md) +ו-[03-retrieval.md](03-retrieval.md). +**הפרה ידועה:** ערן סופר 8046/24 אונדקס עם `headnote`/`summary`/`tags` ריקים → ממצא +ל-[audit](../audit-report.md). + +### INV-G5: metadata מלא + הפרדת-קורפוס נאכפת בכל query +**כלל:** לכל פריט מואנדקס יש **metadata מלא** (כולל מזהה-מקור וסוג-קורפוס), ו**הפרדת- +הקורפוס נאכפת בכל מסלול-query** — אין דליפה בין 3 הקורפוסים. +**מקורות:** Pinecone (multitenancy / metadata filtering) · RAG attribution (Lewis et al., +2020, NeurIPS) · ISO 8000 (Data quality) | סטטוס: verified +**אכיפה:** schema (metadata חובה) + פילטר-קורפוס נאכף בשכבת-החיפוש; מפורט ב- +[03-retrieval.md](03-retrieval.md) ו-[X5-audit-provenance.md](X5-audit-provenance.md). +**הפרה ידועה:** משימה #56 — דליפת `source_kind` ב-`halacha_filters` בין קורפוסים → +ממצא ל-[audit](../audit-report.md). + +### INV-G6: re-index בכל שינוי תוכן +**כלל:** כל שינוי-תוכן של פריט מואנדקס מפעיל **re-index** של ה-embedding שלו. אין +embeddings מיושנים מול התוכן הנוכחי. +**מקורות:** Pinecone (index freshness / data sync) · Weaviate (re-vectorization on update) +· RAG freshness (Lewis et al., 2020) | סטטוס: verified +**אכיפה:** טריגר re-index בנקודת-העדכון + בדיקת-בריאות (גילוי drift); מפורט ב- +[02-data-model.md](02-data-model.md) ו-[03-retrieval.md](03-retrieval.md). +**הפרה ידועה:** — + +### INV-G7: מיזוג RRF — לא סכום-ציונים +**כלל:** מיזוג תוצאות בין retrievers נעשה **לפי דירוג (Reciprocal Rank Fusion)**, לא +סכום/ממוצע ציונים גולמיים — שכן ציונים בסקיילים שונים אינם בני-השוואה ישירה. +**מקורות:** Elastic (*Reciprocal Rank Fusion*) · Weaviate (*Hybrid Search Explained*) · +OpenSearch / Azure AI Search (corroborating RRF guidance) | סטטוס: verified +**אכיפה:** קוד-המיזוג בשכבת-האחזור; מפורט ב-[03-retrieval.md](03-retrieval.md). +**הפרה ידועה:** — + +### INV-G8: איכות-אחזור נמדדת — precision + recall +**כלל:** איכות-האחזור **נמדדת אמפירית (precision + recall)** באמצעות eval harness, לא +מונחת. שינוי בשכבת-האחזור מלווה במדידה. +**מקורות:** Manning, Raghavan & Schütze, *Introduction to Information Retrieval* (CUP, +2008) · RAG evaluation literature (Lewis et al., 2020 ואחריו) · Elastic (relevance +evaluation guidance) | סטטוס: verified +**אכיפה:** eval harness + בדיקת-בריאות תקופתית; מפורט ב-[03-retrieval.md](03-retrieval.md). +**הפרה ידועה:** — + +### INV-G9: עקיבוּת-מקור + audit-trail ל-AI +**כלל:** כל פלט של המערכת **עקיב למקורו** (citation/provenance), וכל שימוש ב-AI מתועד +ב-**audit-trail** הניתן לביקורת. +**מקורות:** Council of Europe / CEPEJ — *European Ethical Charter on AI in judicial systems* +(2018, user-control principle) · NCSC/JTC — *Principles & Practices for AI Use in Courts* · +ISO 15489-1:2016 (records authenticity/integrity) | סטטוס: verified +**אכיפה:** audit-trail באכיפת-קוד + עקיבוּת-מקור בכל פלט; מפורט ב- +[X5-audit-provenance.md](X5-audit-provenance.md). +**הפרה ידועה:** — + +### INV-G10: המערכת מסייעת — שערים אנושיים הם invariant +**כלל:** המערכת **מסייעת ואינה מחליפה את שיקול-הדעת האנושי**. השערים האנושיים (אישור +הלכה, בחירת תוצאה, פידבק היו"ר) הם **invariant — חובה, לא רשות**. +**מקורות:** NCSC/JTC — *Principles & Practices for AI Use in Courts* ("never replace human +judgment") · CEPEJ (2018, under user control) · Federal Judicial Center — *Judicial Writing +Manual* (2d ed.) | סטטוס: verified +**אכיפה:** שערים אנושיים בקוד-הזרימה (gate לא ניתן לעקיפה); מפורט ב-[05-qa-review.md](05-qa-review.md). +**הפרה ידועה:** 10/19 הלכות מאושרות, התגלה במקרה — שער ידני שקוף בלי נראות backlog → +ממצא ל-[audit](../audit-report.md). + +### INV-G11: תוכן החלטה מנומקת +**כלל:** החלטה מנומקת מקיימת: **רקע ניטרלי** (עובדות בלבד, ללא שיפוט) · **ללא כפילות** +(בלוק דיון מפנה, לא חוזר) · **מענה לטענות הצד המפסיד** · **"מבחן-השופט"** (קריא לשופט שלא +מכיר את התיק) · **טענות מקוריות בלבד** (מכתבי הטענות). +**מקורות:** +- Federal Judicial Center — *Judicial Writing Manual* (2d ed.) | סטטוס: verified +- *South Buckinghamshire DC v Porter (No 2)* [2004] UKHL 33 (adequacy of reasons) | + סטטוס: verified +- חוק לתיקון סדרי המינהל (החלטות והנמקות), תשי"ט-1958 (חובת הנמקה) | סטטוס: ⚠ UNVERIFIED +**אכיפה:** שערי QA + checklist-תוכן לפי סוג-ערר; מפורט ב-[04-analysis-writing.md](04-analysis-writing.md) +ו-[05-qa-review.md](05-qa-review.md). +**הפרה ידועה:** — +**הערת-הסלמה (⚠ UNVERIFIED):** מספר-הסעיף המדויק בחוק תשי"ט-1958 וכן תיקון תשכ"ט-1969 +דורשים אימות-מקור-ראשוני מול Nevo. G11 נשמר תקף עם **2 מקורות verified** (FJC + +South Bucks) + מקור-חקיקה אחד שספציפיות-הסעיף שלו לא-מאומתת. האימות המדויק +(§/תיקון) יבוצע בקובץ [04-analysis-writing.md](04-analysis-writing.md) ויועלה ליו"ר. + +--- + +## 6. כללי-הנדסה (מונעים הישנות) + +- **סימטריה:** אסור להוסיף מסלול מקביל ליכולת קיימת — מרחיבים את המסלול הקנוני + (נגזר מ-[G2](#inv-g2-מקור-אמת-יחיד--אין-מסלולים-מקבילים-מתפצלים)). +- **נרמול לא תיקון-תסמין:** מתקנים נתון במקור (קנוני), לא מטליאים בקריאה + (נגזר מ-[G1](#inv-g1-מזהה-קנוני-מנורמל-בכתיבה)). +- **Quality-at-source:** שלמות נאכפת קרוב ככל האפשר לקליטה (Martin Fowler — Data Mesh / + quality-at-source; נגזר מ-[G4](#inv-g4-חוזה-שלמות-לפני-שמיש--ניתן-לחיפוש)). +- **אין בליעה שקטה:** רשומה חסרה/פגומה מסומנת ומדווחת, לא מתקבלת בשקט (תואם feedback + קיים — אסור bare `except: pass`; נגזר מ-[G4](#inv-g4-חוזה-שלמות-לפני-שמיש--ניתן-לחיפוש)). + +--- + +## 7. אינדקס הספ + +| קובץ | תפקיד | אוכף invariants | +|------|--------|-----------------| +| [00-constitution.md](00-constitution.md) | חוקה — ייעוד, invariants גלובליים, כללי-הנדסה, אינדקס | G1–G11 | +| [01-ingest.md](01-ingest.md) | קליטה מאוחדת: מסמכי-תיק / פסיקה חיצונית / החלטות-ועדה — חוזה מסלול-יחיד | G2, G3 | +| [02-data-model.md](02-data-model.md) | אחסון: ישויות (cases, case_law, documents, chunks, halachot…) + חוזה-שלמות לכל ישות | G1, G4, G6 | +| [03-retrieval.md](03-retrieval.md) | 3 קורפוסים + כלי-חיפוש · hybrid/RRF · attribution · eval harness | G4, G5, G6, G7, G8 | +| [04-analysis-writing.md](04-analysis-writing.md) | חילוץ טענות · 12 בלוקים · סגנון דפנה (מצטט block-schema.md) | G11 | +| [05-qa-review.md](05-qa-review.md) | שערי QA + שערים אנושיים (אישור הלכה, בחירת תוצאה, פידבק) כ-invariant | G10, G11 | +| [06-export.md](06-export.md) | ייצוא DOCX לפי תבנית דפנה | — | +| [07-learning.md](07-learning.md) | Hermes · לקחים · לולאת פידבק היו"ר · צמיחת קורפוס (quality-at-source) | G4, G10 | +| [X1-identifiers.md](X1-identifiers.md) | מודל מזהים קנוני: נרמול case_number בכתיבה · cases מול case_law · פורמטי ציטוט | G1 | +| [X2-multi-company.md](X2-multi-company.md) | CMP/CMPA · 14 סוכנים · כללי sync | G2 | +| [X3-integration-deploy.md](X3-integration-deploy.md) | Paperclip (wakeup, ניתוב comments, webhooks) · Coolify/pm2 | — | +| [X4-agents.md](X4-agents.md) | מפת הסוכנים (דומיין + סוכני-התהליך) | G10 | +| [X5-audit-provenance.md](X5-audit-provenance.md) | audit-trail לשימוש ב-AI · עקיבוּת כל מקור מצוטט · שלמות-רשומה | G5, G9 | + +**עקרונות:** כל קובץ עצמאי, ממוקד, agent-readable, יעד ≤~500 שורות (תפיחה = סימן +לפיצול). מסמכים קיימים (`architecture.md`, `product-specification.md`, `block-schema.md`…) +לא נמחקים ולא משוכפלים — מצוטטים כ"מקור" ומאומתים מול הסמכויות; סתירה = ממצא ל-audit. + +--- + +## 8. נספח מקורות סמכותיים + +(מאומתים במחקר 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). + +--- + +## פריטים פתוחים — אימות-מקור-ראשוני נדרש + +(החוקר אימת מסגרת; הפריטים הישראליים דורשים אימות לפני ציטוט כ-סמכות, בשלב כתיבת +`04`/`05`/`X5`) + +1. מספר הסעיף המדויק בחוק לתיקון סדרי המינהל (החלטות והנמקות) תשי"ט-1958 (וכן תיקון + תשכ"ט-1969) — ⚠ UNVERIFIED, יאומת מול Nevo בקובץ [04-analysis-writing.md](04-analysis-writing.md). +2. ציטוט מדויק מ-ברק-ארז, *משפט מינהלי*. +3. אסמכתאות פסיקה: בג"ץ 143/56; עע"ם 2994/21 (מעמד ועדת ערר כגוף תכנוני-מקצועי).