feat(learning): lesson synthesis — merge overlapping lessons into richer super-lessons (#158 / INV-LRN8)

הפתרון-האמיתי לחיתוך-השקט limit=15 (#157): במקום ערימת לקחים גולמיים חופפים, ממזגים
לקחי-סגנון דומים ל"לקח-על" אחד עשיר ומוכלל — הסט שזורם לכותב קטֵן ומשתבח (Authorial
Style Profiling). מחקה את סינתזת-הקנוני (V41/INV-LRN6) על אותה טבלה (G2, אין מאגר-מקביל).

מנגנון (services/lesson_synthesis.py, מסלול-יחיד):
- אשכול greedy לפי cosine (LESSON_SYNTH_CLUSTER_THRESHOLD) בתוך shard practice_area+category.
- מיזוג ע"י claude_session מעוגן-מקור (INV-AH, סגנון-בלבד INV-LRN5, abstain) + שער-drift
  (cosine מול centroid ≥ LESSON_SYNTH_DRIFT_FLOOR).
- לקח-על נכתב source='synthesis' + synthesized_from; המקורות→review_status='superseded'.
- שער מדורג-הפיך (הכרעת-יו"ר): מקורות approved → לקח-על approved (זורם), veto-יו"ר משחזר
  את המקורות (db.revert_lesson_synthesis, מחובר ל-PATCH lessons).
- idempotency: lookup-cosine מול synthesis קיים לפני INSERT.

נגזרות: SCHEMA_V46 (embedding vector(1024) + synthesized_from + ivfflat); כלי-MCP
lesson_synthesize_pending; scripts/backfill_lesson_synthesis.py (--dry-run/--apply, audit CSV);
config LESSON_SYNTH_*; spec INV-LRN8; SCRIPTS.md.

get_recent_decision_lessons ללא שינוי — superseded יוצא (מסנן approved), synthesis נכנס.
UI badges (synthesis/superseded) נדחים לשער-העיצוב (מוגנים ב-fallback, ללא קריסה).

בדיקות: py_compile ✓ · leak-guard G12 ✓ · smoke-test טהור לאשכול/cosine/centroid ✓.
אימות functional מלא (dry-run מול DB+voyage+claude CLI) — בהוסט אחרי-deploy, כמו V41.

Invariants: G2 (מסלול-יחיד, אותה טבלה), INV-AH (עיגון+drift), INV-LRN1/G10 (שער מדורג-הפיך),
INV-LRN5 (סגנון-בלבד), INV-LRN8 (חדש). depends-on #157/#159.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

scripts/SCRIPTS.md

@@ -71,6 +71,7 @@
 | `compute_principle_gold.py` | python | **#153 (נטוש)** — גישת זיהוי-זהב ברמת-עיקרון דרך התאמת-`match_context`→הלכה. **הוחלף** ע"י "מאומת=אזכור" (`build_verified_layer.py`) אחרי שההתאמה נכשלה (match_context=רשימת-הפניות). נשמר לעיון. | deprecated |
 | `cull_principles.py` | python | **#152 Phase C — סינון רטרואקטיבי של קורפוס-העקרונות דרך פאנל-3 (הפיך).** מריץ על כל עיקרון 'original' קיים את אותו משטר שה-extractor משתמש בו להבא (`services/panel_extraction.panel_keep_score`, G2): 3 שופטים (Claude מקומי + DeepSeek + Gemini) מצביעים keep+score → כלל-האישור (3 קולות→שורד · 2 וציון≥0.85→שורד · 2 ו<0.85→יו"ר · ≤1→נדחה) → תקרת `HALACHA_PANEL_MAX_NEW`=5 לכל החלטה לפי ציון (`apply_cap`). נדחה → `halachot.review_status='rejected'` + ה-canonical שלו `rejected` (הפיך, גיבוי-CSV ב-`data/audit/` לפני כל כתיבה). מרוסן ב-`usage_limits` (עוצר-רך בתקרת-שימוש, resumable). `--dry-run` (ברירת-מחדל) / `--apply` / `--sample N` (החלטות אקראיות) / `--limit N` / `--no-throttle` / `--verbose`. **חובה מקומי** (3 שופטים). הרץ: `cd mcp-server && HOME=/home/chaim .venv/bin/python ../scripts/cull_principles.py --apply`. | **חד-פעמי** (סינון ראשוני) + ניתן-לחזרה |
 | `backfill_canonical_synthesis.py` | python | **V41 Phase 4 — סינתזת-LLM ל-`canonical_statement` (idempotent + resumable).** עובר על canonicals ב-`review_status='pending_synthesis'` (רב-instance ראשונים) ומזקק לכל אחד ניסוח אחד כללי ומעוגן בציטוטי-המופעים (INV-AH) דרך `services/canonical_synthesis.py` (מסלול-יחיד, G2). שערים: עיגון/הימנעות, **drift-floor** (cosine מול המקור, ברירת-מחדל 0.80 — סטייה גדולה→נשמר המקור), ואיסור ציטוטי-תיק חדשים. בכל מקרה הסטטוס מתקדם ל-`pending_review` לשער-היו"ר (G10/INV-LRN6). מודל Opus (`HALACHA_CANONICAL_SYNTH_MODEL`). מרוסן ע"י `usage_limits` (עוצר-רך בתקרת-שימוש, resumable). `--dry-run` (ברירת-מחדל) / `--apply` / `--sample N` (מדגם אקראי לבדיקה) / `--limit N` / `--no-throttle` / `--verbose`. CSV-audit ל-`data/audit/canonical-synthesis-*.csv`. **חובה מקומי** (claude_session). הרץ: `cd mcp-server && HOME=/home/chaim .venv/bin/python ../scripts/backfill_canonical_synthesis.py --apply`. שוטף: כלי-MCP `canonical_synthesize_pending`. | **חד-פעמי** (המסה הראשונית) + idempotent לחדשים |
+| `backfill_lesson_synthesis.py` | python | **#158 / INV-LRN8 — סינתזת-LLM של `decision_lessons` (idempotent + resumable).** עובר על shards של `practice_area`+`category` עם ≥2 לקחי-סגנון `approved`, מאשכל near-duplicates (cosine ≥ `LESSON_SYNTH_CLUSTER_THRESHOLD`), וממזג כל אשכול ל"לקח-על" אחד מעוגן-מקור (INV-AH) עם **drift-floor** (`LESSON_SYNTH_DRIFT_FLOOR` מול centroid) דרך `services/lesson_synthesis.py` (מסלול-יחיד, G2). הלקח-על נכתב `source='synthesis'` (`review_status='approved'`, שער-מדורג-הפיך), המקורות→`superseded`. כך הסט שזורם לכותב קטֵן ומשתבח (פותר את חיתוך limit=15, #157). מודל Opus (`LESSON_SYNTH_MODEL`), מרוסן `usage_limits`. `--dry-run` (ברירת-מחדל) / `--apply` / `--practice-area` / `--category` / `--no-throttle` / `--verbose`. CSV-audit ל-`data/audit/lesson-synthesis-*.csv`. **חובה מקומי** (claude_session). הרץ: `cd mcp-server && HOME=/home/chaim .venv/bin/python ../scripts/backfill_lesson_synthesis.py --apply`. שוטף: כלי-MCP `lesson_synthesize_pending`. | idempotent — הרצה לפי צורך/כשמצטברים לקחים |
 | `halacha_batch_reconcile.py` | python | **#82.7** — dedup חוצה-פסקים offline (שמרני, **dry-run בלבד**). dedup-on-insert משווה רק תוך-פסק; כאן סף מחמיר (cosine ≥0.95, `--cosine`) ולא-הרסני: מאתר זוגות הלכות near-duplicate בין פסקים שונים (pgvector `<=>` exact) עם איתות לקסיקלי (Jaccard/Levenshtein) ומדווח ל-CSV ב-`data/audit/` לסקירת היו"ר. לא מדלג/ממזג/מוחק. `--include-pending`. **`--link`** רושם את הזוגות שנמצאו כ-`equivalent_halachot` (parallel authority, #84.2 — **deprecated post-V41** — השתמש ב-`backfill_canonical_halachot.py --apply` במקום). רץ עם venv של mcp-server. | **deprecated** — הוחלף ב-`backfill_canonical_halachot.py` (V41). נשמר לצורכי audit |
 | `calibrate_halacha_dedup.py` | python | **#82.1** — כיול ספי ה-dedup הלקסיקלי (#82.3) מול gold-set הניקוי. קורא `halacha-cleanup-manifest-*.csv` (זוגות duplicate↔survivor מתויגי-אדם), טוען טקסט-survivor מה-DB, ו-sweep של (jaccard_min × levenshtein_min) עם P/R/F1, מסמן את נקודת-העבודה המוגדרת. אימת ש-(0.55, 0.70) → **precision 1.0** (אפס false-merge), recall 0.30 — מתאים לאיתות-משני שחוסם auto-approve. `--manifest <path>`. רץ עם venv של mcp-server | חד-פעמי — כיול (בוצע 2026-06-06) |
 | `ab_halacha_opus48.py` | python | **A/B לא-הרסני לחילוץ הלכות (Claude)** — מריץ מחדש חילוץ הלכות על פסק-דין בודד דרך מודל/effort נבחרים (`AB_MODEL`/`AB_EFFORT`, ברירת-מחדל `claude-opus-4-8`/`xhigh`) ומשווה לסטטיסטיקות ההלכות הקיימות ב-DB **בלי למחוק/לכתוב כלום**. משכפל את `halacha_extractor.extract()` (אותם פרומפטים, בחירת-צ'אנקים, אימות-ציטוט) ומחליף רק את קריאת ה-LLM ב-`claude -p --model --effort`. מפיק `data/ab_halacha_<case>_<effort>.json`. הרצה: `DOTENV_PATH=/home/chaim/.env DATA_DIR=.../data .venv/bin/python scripts/ab_halacha_opus48.py <case_law_id>`. **ממצא 2026-05-31 (שטיין 1128-08-20):** Opus 4.8@xhigh חילץ 51 מול 124 בייצור (100% quote-verified מול 96%) אך ביטחון מכויל-נמוך יותר (חציון 0.75 מול 0.82) — ולכן **לא** מקטין את תור-האישור-הידני תחת sweep אוטו-אישור conf≥0.78 (26 מול 24). שיפור איכות, לא צמצום-תור. | ידני (החלטת מודל-חילוץ) |

scripts/backfill_lesson_synthesis.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Backfill — LLM synthesis of decision_lessons (#158 / INV-LRN8).
+
+WHAT THIS DOES
+--------------
+Walks (practice_area, category) shards that hold ≥2 live APPROVED style lessons,
+clusters near-duplicates (cosine), and asks a local ``claude_session`` model (Opus
+by default) to merge each cluster into ONE richer, generalised "super-lesson" —
+grounded in the source lessons (INV-AH) with a drift guard. Accepted merges are
+written as ``source='synthesis'`` rows (review_status='approved', graduated gate)
+and their sources flip to ``superseded`` (provenance, no longer writer-fed). The
+writer-fed set shrinks, so its limit=15 stops truncating (#157).
+
+All logic lives in services/lesson_synthesis.py (G2) — this is the batch driver:
+shard ordering, throttling, dry-run reporting and a CSV audit trail.
+
+IDEMPOTENCY / RESUME
+--------------------
+Re-running is safe: superseded sources are excluded from candidates, and an accepted
+merge that matches an existing synthesis (cosine) is skipped (duplicate_skipped).
+
+USAGE
+-----
+cd ~/legal-ai/mcp-server
+.venv/bin/python ../scripts/backfill_lesson_synthesis.py --dry-run                       # all shards, no writes
+.venv/bin/python ../scripts/backfill_lesson_synthesis.py --dry-run --practice-area rishuy_uvniya --category style
+.venv/bin/python ../scripts/backfill_lesson_synthesis.py --apply                         # full throttled run
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import csv
+import os
+import sys
+from collections import Counter
+from datetime import datetime, timezone
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "mcp-server", "src"))
+
+from legal_mcp.services import db, lesson_synthesis  # noqa: E402
+
+try:  # stdlib-only module, importable from system python too
+    from legal_mcp.services import usage_limits
+except Exception:  # pragma: no cover
+    usage_limits = None
+
+AUDIT_DIR = os.path.join(os.path.dirname(__file__), "..", "data", "audit")
+
+
+def _throttled() -> tuple[bool, str]:
+    if usage_limits is None:
+        return False, "usage_limits unavailable"
+    usage = usage_limits.subscription_usage()
+    if usage is None:
+        return False, "usage read failed (proceeding)"
+    over, _reset, detail = usage_limits.ceiling_status(usage)
+    return over, detail
+
+
+def _short(s: str, n: int = 100) -> str:
+    s = (s or "").replace("\n", " ")
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+async def _run(apply: bool, practice_area: str, category: str,
+               throttle: bool, verbose: bool) -> int:
+    if practice_area and category:
+        shards = [{"practice_area": practice_area, "category": category}]
+    else:
+        shards = await db.synthesis_shards(min_size=2)
+        if practice_area:
+            shards = [s for s in shards if s["practice_area"] == practice_area]
+        if category:
+            shards = [s for s in shards if s["category"] == category]
+
+    mode = "APPLY" if apply else "DRY-RUN"
+    print(f"[{mode}] {len(shards)} shards with ≥2 approved lessons "
+          f"(throttle={'on' if throttle else 'off'})\n")
+    if not shards:
+        print("nothing to do.")
+        return 0
+
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    os.makedirs(AUDIT_DIR, exist_ok=True)
+    audit_path = os.path.join(
+        AUDIT_DIR, f"lesson-synthesis-{'apply' if apply else 'dryrun'}-{stamp}.csv")
+    counts: Counter[str] = Counter()
+    stopped = False
+
+    with open(audit_path, "w", newline="", encoding="utf-8") as fh:
+        w = csv.writer(fh)
+        w.writerow(["practice_area", "category", "cluster_size", "status",
+                    "drift_cosine", "applied", "reason", "after", "member_ids"])
+        for n, s in enumerate(shards, 1):
+            if throttle:
+                over, detail = _throttled()
+                if over:
+                    print(f"\n⏸  usage ceiling reached ({detail}) — stopping at "
+                          f"shard {n - 1}/{len(shards)}. Re-run to resume.")
+                    stopped = True
+                    break
+            pa, cat = s["practice_area"], s["category"]
+            res = await lesson_synthesis.run_shard(pa, cat, apply=apply)
+            print(f"[{n}/{len(shards)}] {pa}/{cat}: {res['candidates']} candidates → "
+                  f"{len(res['clusters'])} clusters")
+            for c in res["clusters"]:
+                counts[c["status"]] += 1
+                w.writerow([pa, cat, len(c["members"]), c["status"],
+                            c.get("drift_cosine"), c.get("applied"),
+                            c.get("reason", ""), c.get("proposed", ""),
+                            "|".join(c["members"])])
+                mark = {"accepted": "✓", "duplicate_skipped": "=", "abstained": "·",
+                        "drift_rejected": "✗", "llm_error": "!", "too_small": "·"}.get(c["status"], "?")
+                print(f"      {mark} {c['status']:<18} size={len(c['members'])} "
+                      f"drift={c.get('drift_cosine')}{' [written]' if c.get('applied') else ''}")
+                if verbose and c.get("proposed"):
+                    print(f"        → {_short(c['proposed'])}")
+
+    processed = sum(counts.values())
+    print(f"\n── summary ({mode}) — {processed} clusters"
+          f"{' (stopped early)' if stopped else ''} ──")
+    for status, c in counts.most_common():
+        print(f"   {status:<18} {c}")
+    print(f"\naudit CSV: {audit_path}")
+    if not apply:
+        print("dry-run — nothing written. Re-run with --apply to commit.")
+    return 0
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="LLM synthesis of decision_lessons (#158 / INV-LRN8)")
+    p.add_argument("--apply", action="store_true", help="commit to the DB (default: dry-run)")
+    p.add_argument("--dry-run", action="store_true", help="explicit dry-run (default)")
+    p.add_argument("--practice-area", default="", help="limit to one practice_area")
+    p.add_argument("--category", default="", help="limit to one category (style/structure/lexicon/tabular)")
+    p.add_argument("--no-throttle", action="store_true", help="skip usage-ceiling checks")
+    p.add_argument("--verbose", action="store_true", help="print merged text per cluster")
+    args = p.parse_args()
+    return asyncio.run(_run(
+        apply=args.apply, practice_area=args.practice_area, category=args.category,
+        throttle=not args.no_throttle, verbose=args.verbose,
+    ))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())