From b46d25f6052191586596de93e6fd0884ab6ab28d Mon Sep 17 00:00:00 2001 From: Chaim Date: Sat, 30 May 2026 15:21:34 +0000 Subject: [PATCH] docs(spec): 07-learning loop Co-Authored-By: Claude Opus 4.8 --- docs/spec/07-learning.md | 189 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/spec/07-learning.md diff --git a/docs/spec/07-learning.md b/docs/spec/07-learning.md new file mode 100644 index 0000000..d557c6c --- /dev/null +++ b/docs/spec/07-learning.md @@ -0,0 +1,189 @@ +# 07 — לולאת הלמידה (Learning Loop) + +קובץ-תחום זה כפוף ל-[חוקת המערכת](00-constitution.md) ומפרט כיצד המערכת **לומדת לאורך +זמן** — מהחלטות סופיות (Hermes), מפידבק-היו"ר, ומצמיחת-הקורפוס — באופן שמזין חזרה את +הכתיבה ([04-analysis-writing.md](04-analysis-writing.md)) ואת שערי-האיכות +([05-qa-review.md](05-qa-review.md)). הוא אוכף את +[INV-G10](00-constitution.md#inv-g10-המערכת-מסייעת--שערים-אנושיים-הם-invariant) +(שערים אנושיים — אישור היו"ר על כל עדכון-ידע) ואת +[INV-G4](00-constitution.md#inv-g4-חוזה-שלמות-לפני-שמיש--ניתן-לחיפוש) / +כלל-ההנדסה **quality-at-source** (האחריות לאיכות יושבת במקור, לא בטלאי במורד הזרם). + +> **⚠ קובץ מעורב — שני מודלי-סמכות** (לפי החוקה §3, §5): +> - **שער-הממשל** (Hermes מציע — היו"ר מאשרת ידנית; אין auto-commit ל-SKILL/lessons) +> הוא **invariant הנדסי** במודל הממשל-שיפוטי → נושא `מקורות:` (NCSC/JTC · CEPEJ 2018 · +> FJC) + `סטטוס: verified`. +> - **כלל-ההנדסה quality-at-source** (היכן יושבת האחריות לאיכות-הידע) → invariant הנדסי +> במודל הנדסת-הנתונים → נושא `מקורות:` (Fowler — Data Mesh / quality-at-source · +> DAMA-UK · ISO 8000) + `סטטוס: verified`. + +--- + +## 1. שלוש לולאות-המשנה + +הלמידה אינה אירוע יחיד אלא **שלוש לולאות** המתנקזות לאותם מסמכי-ידע מוסמכים +([legal-decision-lessons.md](../legal-decision-lessons.md), +[skills/decision/SKILL.md](../../skills/decision/SKILL.md)) ולקורפוסים: + +### 1.1 לולאת-Hermes (post-export → הצעה → אישור) + +הסוכן [hermes-curator](../../.claude/agents/hermes-curator.md) (adapter `deepseek_local`, +פרופילים `curator-cmp` / `curator-cmpa`) נקרא **אחרי שדפנה מסמנת קובץ כסופי** ב-UI +(`POST /api/cases/{case_number}/exports/{filename}/mark-final` → `pc_wake_curator_for_final()` +ב-`web/paperclip_client.py` → sub-issue + wakeup; **חיבור ישיר מה-UI, לא דרך CEO** — +`hermes-curator.md:27-35`). הוא: + +- **קורא בלבד** את הטקסט הסופי (`case_get_final_text`), `get_style_guide`, ואת + `SKILL.md` / `legal-decision-lessons.md` / `corpus-analysis.md` המקומיים + (`hermes-curator.md:60-70`). +- מזהה **3–5 דפוסים/פערים** חדשים, כל ממצא מתויג `[סגנון]` / `[מבנה]` / + `[לקסיקון משפטי]` / `[טבלאי]` (`hermes-curator.md:99-108`). +- **מציע** — comment ב-Paperclip + רישום כל ממצא כ-`decision_lesson` דרך + `POST /api/training/corpus/{corpus_id}/lessons` (`source:"curator"`) שמופיע ב-UI + תחת הטאב "מה למדנו" (`hermes-curator.md:73-96`). +- **אינו מעדכן** קבצים בעצמו (skills/, lessons.py, DB) — רק מציע (`hermes-curator.md:125-130`). + +### 1.2 לולאת-פידבק-היו"ר (capture → ניתוח שבועי → לקחים) + +- **לכידה מובנית:** `record_chair_feedback` שומר הערת-דפנה בטבלת `chair_feedback` + (`category ∈ {missing_content, wrong_tone, wrong_structure, factual_error, style, + other}`) — `tools/workflow.py:348`, ראה [05-qa-review.md](05-qa-review.md) §2.3. +- **ניתוח שבועי:** ה-scheduled job `weekly-feedback-analysis` (ראשון 19:00, + `plugin-legal-ai/src/manifest.ts:175-179`) מושך `GET /api/chair-feedback/weekly-summary`, + ואם יש פריטים — **מעיר את ה-CEO** לעדכן את `legal-decision-lessons.md` עם הלקחים + החדשים (`worker.ts:784-837`; הוראת ה-prompt: "הוסף רק לקחים חדשים… קבץ לפי נושא" + — `worker.ts:830`). +- אין פריטים → הג'וב מדלג בשקט (`worker.ts:805`). ל-CEO שמתעורר מ-`weekly-feedback-job` + **אין `issueId`** — הוא כותב לקובץ בלבד, לא מפרסם comment ולא סוגר issue + (כלל מ-[CLAUDE.md](../../CLAUDE.md) "Scheduled Jobs"). + +### 1.3 לולאת-צמיחת-הקורפוס (החלטה סופית → קורפוס → אחזור) + +החלטה סופית נקלטת לקורפוס-הסגנון (`ingest_final_version` — ראה [06-export.md](06-export.md) +§ Hermes), ופסיקה/החלטות-ועדה חדשות נקלטות דרך המסלול הקנוני של +[01-ingest.md](01-ingest.md). כך הקורפוס שמזין את האחזור ([03-retrieval.md](03-retrieval.md)) +**גדל מהפלט עצמו** — והדיון הבא נשען על תקדים עשיר יותר. צמיחה זו כפופה לאותו חוזה-שלמות +([G4](00-constitution.md#inv-g4-חוזה-שלמות-לפני-שמיש--ניתן-לחיפוש)) כמו כל קליטה. + +--- + +## 2. הלולאה במלואה (הציור) + +``` + ┌──────────────────────────────────────────────────────┐ + │ │ + ┌─────────────▼─────────────┐ ┌────────────────────────┐ │ + │ כתיבה (04) │ ───▶ │ QA + שערים אנושיים (05)│ │ + │ 12 בלוקים · סגנון דפנה │ │ validate_decision + │ │ + │ ← lessons.py CONTENT_ │ │ פידבק-היו"ר │ │ + │ CHECKLISTS · SKILL.md │ └───────────┬────────────┘ │ + └───────────────────────────┘ │ ייצוא (06) │ + ▲ ▼ │ + │ ┌──────────────────────┐ │ + ┌────────┴──────────────┐ │ סימון "סופי" (UI) │ │ + │ legal-decision- │ │ mark-final │ │ + │ lessons.md + SKILL.md │ └───────┬──────────────┘ │ + │ (מסמכי-ידע מוסמכים) │ │ │ + └────────▲──────────────┘ ┌──────────┴───────────┐ │ + │ ▼ ▼ │ + │ ✋ אישור-יו"ר ידני ┌───────────────┐ ┌────────────────┐│ + └──────────────────────│ Hermes curator │ │ ingest_final → ││ + (commit ידני בלבד) │ → הצעות(comment)│ │ קורפוס-סגנון → ┘│ + └───────────────┘ │ אחזור (03) │ + ┌───────────────────────────┐ └────────────────┘ + │ פידבק-היו"ר (05) ──┐ │ + │ chair_feedback │ │ + └────────────────────┼───────┘ + ▼ + weekly-feedback-analysis (job) + │ מעיר CEO + ▼ + עדכון legal-decision-lessons.md ──┐ + └──▶ (חזרה ל-04 / lessons.py) +``` + +הקשר לכתיבה: הלקחים והצ'קליסטים שב-`CONTENT_CHECKLISTS` +(`mcp-server/src/legal_mcp/services/lessons.py:355`, בורר `get_content_checklist` +`:509-555`) ו-`get_lessons_for_outcome` (`lessons.py:309`) מוזרקים ל-prompt-הכתיבה לפי +סוג-ערר ותוצאה — ראה [04-analysis-writing.md](04-analysis-writing.md) §5. כל סגירה של +לולאה (Hermes או פידבק) שמשנה את `legal-decision-lessons.md` / `SKILL.md` משפיעה ישירות +על הכתיבה הבאה. + +--- + +## 3. Invariants של התחום + +### INV-LRN1: עדכון-ידע דורש אישור-יו"ר ידני — אין auto-commit (governance →G10) +**כלל:** מנגנוני-הלמידה (Hermes, ניתוח-פידבק שבועי) **מציעים בלבד**. כל שינוי ב- +[SKILL.md](../../skills/decision/SKILL.md) או ב-[legal-decision-lessons.md](../legal-decision-lessons.md) +מחייב **בחינה ואישור ידניים של היו"ר/חיים** ואז commit ידני — **לעולם לא auto-committed**. +Hermes כותב comment + `decision_lesson`, לא קבצים; ה-CEO השבועי כותב לקובץ אך הצעותיו +מאומתות ידנית לפני קיבוע. זהו פֶּאֶט של [INV-G10](00-constitution.md#inv-g10-המערכת-מסייעת--שערים-אנושיים-הם-invariant) +על שכבת-הידע: גם הלמידה כפופה לשיקול-הדעת האנושי. +**מקורות:** NCSC/JTC — *Principles & Practices for AI Use in Courts* (human-in-the-loop; +never replace human judgment) · Council of Europe / CEPEJ (2018, under user control) · +Federal Judicial Center — *Judicial Writing Manual* (2d ed.) | סטטוס: verified +**אכיפה:** הסוכן read-only על תוכן ו-write רק על comments (`hermes-curator.md:1-3, 125-130`); +תהליך-האישור — הצעת-curator כ-comment ב-Paperclip → חיים בוחן ומאשר ידנית → commit ל- +`SKILL.md` ו-`docs/legal-decision-lessons.md` (מ-[CLAUDE.md](../../CLAUDE.md) "Hermes Curator"); +ה-CEO השבועי מתעורר בלי `issueId` וכותב לקובץ בלבד ([CLAUDE.md](../../CLAUDE.md) "Scheduled Jobs"). +**הפרה ידועה:** — + +### INV-LRN2: האחריות לאיכות יושבת במקור — quality-at-source (engineering →G4) +**כלל:** האחריות לאיכות-הידע (לקחים, הלכות, metadata של פריטים מואנדקסים) נאכפת **קרוב +ככל האפשר לנקודת-היצירה/הקליטה** — בעת ניסוח-ההחלטה, בעת לכידת-הפידבק, ובעת קליטת-פריט — +**לא** מתוקנת בדיעבד במורד-הזרם (re-OCR, טלאי-קריאה, ניחוש בזמן-חיפוש). פריט-ידע חסר-שלמות +מסומן ומדווח בנקודת-הכניסה, לא מתקבל בשקט. +**מקורות:** Martin Fowler — *Data Mesh* (quality-at-source: domain owns data quality at +the point of creation) · DAMA-UK *Six Primary Dimensions for Data Quality* (2013, +completeness) · ISO 8000 (Data quality) | סטטוס: verified +**אכיפה:** חוזה-שלמות בקליטה ([01-ingest.md](01-ingest.md) §2, [02-data-model.md](02-data-model.md)) ++ "אין בליעה שקטה" (חוקה §6); לכידת-פידבק מובנית בנקודת-ההערה (`record_chair_feedback`, +`tools/workflow.py:348`); לקחים נשמרים מבני ולא ad-hoc (`lessons.py`, +[legal-decision-lessons.md](../legal-decision-lessons.md)). +**הפרה ידועה:** ראה [INV-G4](00-constitution.md#inv-g4-חוזה-שלמות-לפני-שמיש--ניתן-לחיפוש) +(ערן סופר 8046/24 אונדקס עם `headnote`/`summary`/`tags` ריקים — שלמות לא נאכפה במקור) → +ממצא ל-[audit](../audit-report.md). + +### INV-LRN3: ידע נלכד באופן מובנה — לא ad-hoc (engineering →G9) +**כלל:** פידבק ולקחים נלכדים ב**מבנה דטרמיניסטי ועקיב** — `chair_feedback` (עם `category` +ו-`block_id`), `decision_lessons` (עם `category`/`source`), ו-`CONTENT_CHECKLISTS` בקוד — +כך שהלמידה **עמידה וניתנת-לביקורת**, לא פזורה בהערות חופשיות. מקור-הלקח (`source:"curator"` +מול פידבק-יו"ר) משומר לעקיבוּת. +**מקורות:** ISO 15489-1:2016 (records reliability/authenticity) · DAMA-UK *Six Primary +Dimensions for Data Quality* (2013) · ISO 8000 (Data quality) | סטטוס: verified +**אכיפה:** טבלת `chair_feedback` + `record_chair_feedback`/`list_chair_feedback` +(`tools/workflow.py:348, 393`); `decision_lessons` עם `source`+`category` +(`hermes-curator.md:79-96`); `CONTENT_CHECKLISTS`/`get_lessons_for_outcome` +(`lessons.py:355, 309`). עקיבוּת-מקור קושרת ל-[X5-audit-provenance.md](X5-audit-provenance.md). +**הפרה ידועה:** — + +--- + +## 4. הג'ובים המתוזמנים (תמיכת-תשתית ללולאה) + +| Job (`manifest.ts`) | לוח-זמנים | תפקיד בלולאה | +|---------------------|-----------|---------------| +| `weekly-feedback-analysis` | ראשון 19:00 (`:175-179`) | מסכם פידבק-יו"ר → מעיר CEO לעדכון `legal-decision-lessons.md` (`worker.ts:784-837`) | +| `stale-case-reminder` | יומי 08:00 (`:169-172`) | תזכורת על תיקים תקועים 30+ ימים (`worker.ts:710-780`) — היגיינת-תהליך, לא ידע | +| `sync-case-status` | כל 15 דק' (`:162-166`) | מסנכרן סטטוסי-תיקים legal-ai↔Paperclip (`worker.ts:624`) — תשתית, לא ידע | + +רק `weekly-feedback-analysis` הוא חלק מלולאת-הלמידה; שני האחרים הם היגיינת-תהליך/סנכרון. + +--- + +## 5. הפניות-אחיות + +- [00-constitution.md](00-constitution.md#inv-g10-המערכת-מסייעת--שערים-אנושיים-הם-invariant) — + INV-G10 (שערים אנושיים) + [INV-G4](00-constitution.md#inv-g4-חוזה-שלמות-לפני-שמיש--ניתן-לחיפוש) + (quality-at-source) + כלל-ההנדסה §6. +- [04-analysis-writing.md](04-analysis-writing.md) — הכתיבה שהלקחים/הצ'קליסטים מזינים (§3, §5). +- [05-qa-review.md](05-qa-review.md) — שער פידבק-היו"ר (§2.3) שמתחיל את לולאת-הפידבק. +- [01-ingest.md](01-ingest.md) — קליטה אחידה (quality-at-source) לצמיחת-הקורפוס. +- [03-retrieval.md](03-retrieval.md) — האחזור שהקורפוס הגדל מזין. +- [06-export.md](06-export.md) — `mark-final` שמפעיל את Hermes + `ingest_final_version`. +- [X5-audit-provenance.md](X5-audit-provenance.md) — עקיבוּת-מקור של לקחים (`source`). +- הסוכן: [.claude/agents/hermes-curator.md](../../.claude/agents/hermes-curator.md). +- מסמכי-הידע המוסמכים: [legal-decision-lessons.md](../legal-decision-lessons.md) · + [skills/decision/SKILL.md](../../skills/decision/SKILL.md) · + [corpus-analysis.md](../corpus-analysis.md).