feat(drafting): טיוטת-ביניים דטרמיניסטית — נעיצת Opus 4.8 + effort per-בלוק (#204)

מנגנון-הייצור (claude_session→claude -p) לא העביר model/effort: BLOCK_CONFIG
הגדיר temp+model per-בלוק שהיו מטא-דאטה-מת (block_writer.py:447 העביר רק
prompt/timeout/tools). הייצור רץ על מודל ברירת-המחדל של ה-CLI עם פרומפטים-חופשיים
→ מקור אי-העקביות בטיוטת-הביניים.

תיקון (עקביות-מבנית, WS5):
- נעיצת model="claude-opus-4-8" (GENERATION_MODEL) לכל בלוקי-ה-AI + effort per-בלוק
  שמועבר בפועל דרך claude_session.query → `claude -p --model --effort`.
  מפת-effort: ה=medium · ו=medium · ז=high · ח=medium · ט=high · יא=high · י=xhigh.
- ניסוח-פתיחה קבוע לבלוק-ה (תמיד "לפנינו ערר…", סוף ל-OR "עניינה של החלטה זו").
- מבנה-פנימי קבוע לבלוק-ה; סדר-בלוקים בייצוא כבר קבוע (_INTERIM_BLOCK_ORDER).
- הסרת שדות temp/model המתים מ-BLOCK_CONFIG; "temp" deprecated (Opus 4.7/4.8 דוחים
  temperature→400). decision_blocks.temperature נשמר=0 לתאימות-עמודה בלבד.
- timeout נגזר מ-effort (לא מפיצול sonnet/opus שכבר לא קיים).
- עדכון endpoint reference /api/settings/mcp/blocks + blocks-tab + McpBlock לחשוף effort.
- ספ: docs/block-schema.md §3 (effort מחליף temperature), docs/spec/06-export.md
  (דטרמיניזם-מבני של טיוטת-הביניים).

G2 (מקור-אמת יחיד) — אין מסלול-ייצור מקביל: write_interim_draft מתזמר את אותו
write_and_store_block→write_block של ההחלטה המלאה.
claude_session-local-only — הייצור נשאר דרך גשר-ה-CLI, לא SDK/קונטיינר.
INV-EX1 — סדר-ייצוא דטרמיניסטי נשמר; G11 — עקרונות-הכתיבה ל-12 הבלוקים נשמרים.

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

mcp-server/src/legal_mcp/services/block_writer.py

@@ -35,29 +35,53 @@ logger = logging.getLogger(__name__)
 
 # ── Block configuration ───────────────────────────────────────────
 
-# Output token limits per Anthropic docs:
-# Opus 4.7: up to 128K output tokens (new tokenizer — ~35% more tokens)
-# Sonnet 4.6: up to 64K output tokens
-# Streaming required when max_tokens > 21,333
+# Generation is structurally deterministic (#204 / WS5): every AI block is
+# pinned to ONE model (Opus 4.8) with a per-block reasoning `effort`. The
+# generation path is claude_session.query → `claude -p` (subscription, near-zero
+# cost; local-only — see reference_claude_generation_path / claude_session
+# docstring). Opus 4.7/4.8 REMOVED temperature/top_p/top_k (sending them → HTTP
+# 400); the only knob is `effort` (low/medium/high/xhigh/max; default high).
+#
+# DEPRECATED FIELDS — DO NOT REINTRODUCE: earlier revisions carried per-block
+# `temp` (0/0.1/0.4) and `model` ("sonnet"/"opus"/"script"). Both were DEAD
+# METADATA: write_block called claude_session.query(prompt, …) WITHOUT model/
+# temp/effort, so generation ran on the CLI's default model with no temperature
+# knob at all (the table only stored a number in decision_blocks.temperature and
+# fed MODEL_MAP→timeout). They are removed here so the table no longer misleads.
+# The conceptual origin (gen_type → thinking-budget) now lives in `effort`; see
+# docs/block-schema.md §3.
+#
+# `gen_type` is retained (documentation/UI metadata + audit `generation_type`).
+# `model` below is the DISPATCH key only: "script" = template-fill (no LLM),
+# "ai" = generated via the pinned Opus model. It is NOT a model alias anymore.
+#
+# Output token note (Anthropic): Opus 4.8 supports large outputs; streaming is
+# handled by the CLI. `max_tokens` is advisory context for callers, not sent.
+GENERATION_MODEL = "claude-opus-4-8"  # single pinned model for every AI block (#204)
+
 BLOCK_CONFIG = {
-    "block-alef": {"index": 1, "title": "כותרת מוסדית", "gen_type": "template-fill", "temp": 0, "model": "script"},
-    "block-bet":  {"index": 2, "title": "הרכב הוועדה", "gen_type": "template-fill", "temp": 0, "model": "script"},
-    "block-gimel":{"index": 3, "title": "צדדים", "gen_type": "template-fill", "temp": 0, "model": "script"},
-    "block-dalet":{"index": 4, "title": "החלטה", "gen_type": "template-fill", "temp": 0, "model": "script"},
-    "block-he":   {"index": 5, "title": "פתיחה", "gen_type": "paraphrase", "temp": 0.2, "model": "sonnet", "max_tokens": 4096},
-    "block-vav":  {"index": 6, "title": "רקע עובדתי", "gen_type": "reproduction", "temp": 0, "model": "sonnet", "max_tokens": 16384},
-    "block-zayin":{"index": 7, "title": "טענות הצדדים", "gen_type": "paraphrase", "temp": 0.1, "model": "sonnet", "max_tokens": 16384},
-    "block-chet": {"index": 8, "title": "הליכים", "gen_type": "reproduction", "temp": 0, "model": "sonnet", "max_tokens": 8192},
-    "block-tet":  {"index": 9, "title": "תכניות חלות", "gen_type": "guided-synthesis", "temp": 0.2, "model": "opus", "max_tokens": 16384},
-    "block-yod":  {"index": 10, "title": "דיון והכרעה", "gen_type": "rhetorical-construction", "temp": 0.4, "model": "opus", "max_tokens": 16384},
-    "block-yod-alef": {"index": 11, "title": "סיכום", "gen_type": "paraphrase", "temp": 0.1, "model": "sonnet", "max_tokens": 8192},
-    "block-yod-bet":  {"index": 12, "title": "חתימות", "gen_type": "template-fill", "temp": 0, "model": "script"},
+    "block-alef": {"index": 1, "title": "כותרת מוסדית", "gen_type": "template-fill", "model": "script"},
+    "block-bet":  {"index": 2, "title": "הרכב הוועדה", "gen_type": "template-fill", "model": "script"},
+    "block-gimel":{"index": 3, "title": "צדדים", "gen_type": "template-fill", "model": "script"},
+    "block-dalet":{"index": 4, "title": "החלטה", "gen_type": "template-fill", "model": "script"},
+    "block-he":   {"index": 5, "title": "פתיחה", "gen_type": "paraphrase", "model": "ai", "effort": "medium", "max_tokens": 4096},
+    "block-vav":  {"index": 6, "title": "רקע עובדתי", "gen_type": "reproduction", "model": "ai", "effort": "medium", "max_tokens": 16384},
+    "block-zayin":{"index": 7, "title": "טענות הצדדים", "gen_type": "paraphrase", "model": "ai", "effort": "high", "max_tokens": 16384},
+    "block-chet": {"index": 8, "title": "הליכים", "gen_type": "reproduction", "model": "ai", "effort": "medium", "max_tokens": 8192},
+    "block-tet":  {"index": 9, "title": "תכניות חלות", "gen_type": "guided-synthesis", "model": "ai", "effort": "high", "max_tokens": 16384},
+    "block-yod":  {"index": 10, "title": "דיון והכרעה", "gen_type": "rhetorical-construction", "model": "ai", "effort": "xhigh", "max_tokens": 16384},
+    "block-yod-alef": {"index": 11, "title": "סיכום", "gen_type": "paraphrase", "model": "ai", "effort": "high", "max_tokens": 8192},
+    "block-yod-bet":  {"index": 12, "title": "חתימות", "gen_type": "template-fill", "model": "script"},
 }
 
-MODEL_MAP = {
-    "sonnet": "claude-sonnet-4-20250514",
-    "opus": "claude-opus-4-7",
-}
+# Default effort when a block lacks an explicit one (defensive; every AI block
+# above sets one). High is the safe default per the generation-path reference.
+DEFAULT_EFFORT = "high"
+
+# Blocks that take longer (deep reasoning) get the LONG timeout. The interim set
+# [he, vav, tet, zayin, chet] and the discussion block all run on the same pinned
+# Opus model, so timeout is driven by effort, not by a model split.
+_LONG_EFFORTS = frozenset({"high", "xhigh", "max"})
 
 
 # ── Template blocks (א-ד, יב) ────────────────────────────────────
@@ -120,11 +144,14 @@ TEMPLATE_WRITERS = {
 BLOCK_PROMPTS = {
     "block-he": """כתוב את בלוק הפתיחה (בלוק ה) של החלטת ועדת ערר.
 
-## כללים:
-- פתח ב"לפנינו ערר..." או "עניינה של החלטה זו..."
-- הגדר "להלן" מרכזיים: הוועדה המקומית, התכנית/הבקשה, המגרש
-- 1-2 סעיפים בלבד
-- אין ניתוח, אין ערכי שיפוט, אין ציטוטים מצדדים
+## מבנה קבוע (חובה — אותו מבנה בכל תיק):
+- **המשפט הראשון פותח תמיד במילה "לפנינו"** — נוסח קבוע: "לפנינו ערר על החלטת
+  [הוועדה המקומית] מיום [תאריך] בעניין [נושא הבקשה/התכנית]." (אל תשתמש ב"עניינה של
+  החלטה זו" או בכל פתיח חלופי — הפתיח אחיד.)
+- סעיף 1: הצגת הערר במשפט הקבוע לעיל + הגדרת ה"להלן" המרכזיים בסדר קבוע:
+  הוועדה המקומית → התכנית/הבקשה → המגרש/המקרקעין.
+- סעיף 2 (רק אם נדרש להשלמת "להלן" נוספים): הגדרות-נוספות בלבד.
+- **בדיוק 1-2 סעיפים.** אין ניתוח, אין ערכי שיפוט, אין ציטוטים מצדדים.
 - מספור: 1.
 
 ## פרטי התיק:
@@ -441,10 +468,19 @@ async def write_block(
             f"Reduce documents or call extract_appraiser_facts first."
         )
 
-    # Call Claude via Claude Code session (no API)
-    model_key = block_cfg["model"]
-    timeout = claude_session.LONG_TIMEOUT if model_key == "opus" else claude_session.DEFAULT_TIMEOUT
-    content = await claude_session.query(prompt, timeout=timeout, tools="")  # prose gen — no tool_use → no error_max_turns
+    # Call Claude via Claude Code session (no API). #204: pin the model + per-block
+    # reasoning effort so generation is structurally deterministic — these were
+    # previously NOT forwarded (the source of inconsistency). model/effort flow
+    # through claude_session.query → `claude -p --model … --effort …`.
+    effort = block_cfg.get("effort", DEFAULT_EFFORT)
+    timeout = claude_session.LONG_TIMEOUT if effort in _LONG_EFFORTS else claude_session.DEFAULT_TIMEOUT
+    content = await claude_session.query(
+        prompt,
+        timeout=timeout,
+        model=GENERATION_MODEL,
+        effort=effort,
+        tools="",  # prose gen — no tool_use → no error_max_turns
+    )
 
     sources = await _collect_block_sources(case_id, block_id)
     sources["case_law_ids"] = _precedent_case_law_ids
@@ -455,6 +491,7 @@ async def write_block(
 
 def _build_result(block_id: str, content: str, block_cfg: dict) -> dict:
     word_count = len(content.split())
+    is_ai = block_cfg["model"] == "ai"
     return {
         "block_id": block_id,
         "block_index": block_cfg["index"],
@@ -462,8 +499,14 @@ def _build_result(block_id: str, content: str, block_cfg: dict) -> dict:
         "content": content,
         "word_count": word_count,
         "generation_type": block_cfg["gen_type"],
-        "model_used": block_cfg["model"],
-        "temperature": block_cfg["temp"],
+        # AI blocks record the pinned model; template blocks record "script".
+        "model_used": GENERATION_MODEL if is_ai else block_cfg["model"],
+        # The real generation knob (#204). None for template/script blocks.
+        "effort": block_cfg.get("effort", DEFAULT_EFFORT) if is_ai else None,
+        # DEPRECATED: temperature is not a real knob on Opus 4.7/4.8 (sending it
+        # → HTTP 400). Kept only to satisfy decision_blocks.temperature
+        # NUMERIC(3,2); always 0. Read `effort` instead.
+        "temperature": 0,
     }
 
 

mcp-server/src/legal_mcp/tools/drafting.py

@@ -516,9 +516,18 @@ async def export_docx(case_number: str, output_path: str = "") -> str:
 
 # ── Interim draft (pre-ruling) ────────────────────────────────────
 
-# Blocks written for the interim draft, in display order.
+# Blocks written for the interim draft, in a FIXED order.
 # This is the same content the chair sees in the final decision (same template,
-# same skill, same prompts) — minus opening, ruling, summary, signatures.
+# same skill, same prompts, same single canonical write path — block_writer) —
+# minus ruling, summary, signatures.
+#
+# Determinism (#204 / WS5): the interim draft is STRUCTURALLY deterministic.
+# Each block is generated by block_writer.write_block, which now pins the model
+# (Opus 4.8) and a per-block reasoning effort, and uses fixed structural prompts
+# (e.g. block-he's opening is always "לפנינו ערר…"). The display order on export
+# is fixed separately by docx_exporter._INTERIM_BLOCK_ORDER. There is no parallel
+# generation path (G2): write_interim_draft is a thin orchestrator over the same
+# write_and_store_block used by the full decision.
 _INTERIM_BLOCKS = ["block-he", "block-vav", "block-tet", "block-zayin", "block-chet"]