okstra 0.158.1 → 0.160.0

package/runtime/validators/validate-run.py

@@ -66,6 +66,7 @@ from okstra_ctl.report_translation import (  # noqa: E402
     hangul_share,
 )
 from okstra_ctl.stage_citations import cited_stage_numbers  # noqa: E402
+from okstra_ctl.incremental_scope import coverage_row_blocked_on  # noqa: E402
 from okstra_ctl.workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE  # noqa: E402
 from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
@@ -103,7 +104,10 @@ from okstra_ctl.worker_prompt_contract import (  # noqa: E402
     PromptRecord,
     validate_initial_prompt_records,
 )
-from okstra_ctl.worker_prompt_headers import EVIDENCE_LEDGER_HEADER  # noqa: E402
+from okstra_ctl.worker_audit_ledger import (  # noqa: E402
+    READING_CONFIRMATION_HEADING_RE,
+    check_worker_results_audit,
+)
 from validate_analysis_report import validate_analysis_report  # noqa: E402
 from okstra_ctl.convergence_engine import (  # noqa: E402
     grouped_input_digest,
@@ -1082,7 +1086,7 @@ def _validate_v2_ai_handoff(content: str, failures: list[str]) -> None:
             "schema-v2 AI handoff markdown contains human-only field "
             f"{field!r}; render it only in the task-specific HTML."
         )
-    if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
+    if READING_CONFIRMATION_HEADING_RE.search(content) is not None:
         failures.append(
             "final report contains a `## 0. Reading Confirmation` heading — "
             "Reading Confirmation lives in the worker audit sidecar, never "
@@ -1102,12 +1106,6 @@ _REPORT_INDEX_ANCHOR_RE = re.compile(r'<a id="report-index"')
 # never anchored — i.e. an un-anchored ID that the Index cannot link to.
 _UNANCHORED_ID_ROW_RE = re.compile(r"^\|[ \t]*\*{0,2}([A-Z]{1,4}-\d{3,})\b", re.MULTILINE)
 
-# Reading Confirmation heading must NOT appear in the final-report — it
-# belongs in the worker audit sidecar (`<worker>-audit-<task-type>-<seq>.md`).
-_READING_CONFIRMATION_HEADING_RE = re.compile(
-    r"^##[ \t]+0\.[ \t]+Reading Confirmation\b", re.MULTILINE
-)
-
 # Empty Section 0 (Clarification Response Carried In) stub. When no
 # carry-in path is provided, the writer must OMIT the `## 0.` heading
 # entirely — emitting the heading followed by the "No prior clarification
@@ -2349,7 +2347,7 @@ def validate_report(
 
     # Reading Confirmation belongs in the worker audit sidecar, not the
     # user-facing final-report.
-    if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
+    if READING_CONFIRMATION_HEADING_RE.search(content) is not None:
         failures.append(
             "final report contains a `## 0. Reading Confirmation` heading — "
             "Reading Confirmation lives in the worker audit sidecar "
@@ -2385,27 +2383,6 @@ def validate_report(
             failures.append(f"final report contains {remedy}")
 
 
-# Worker-results filename pattern: `<worker-role>-<task-type>-<seq>.md`.
-# Every analysis-worker role name ends in `-worker` (`claude-worker`,
-# `codex-worker`, `antigravity-worker`, `report-writer-worker`), so anchor the
-# split on that suffix — otherwise `antigravity-worker-error-analysis-001.md`
-# ambiguously parses as `worker=antigravity, task=worker-error-analysis`.
-# Audit sidecars (`*-audit-*`) and errors sidecars (`.json`) are not
-# matched here.
-_WORKER_RESULT_BASENAME_RE = re.compile(
-    r"^(?P<worker>[a-z][a-z0-9-]*-worker)-(?P<task_type>[a-z][a-z-]*?)-(?P<seq>\d{3})\.md$"
-)
-_EVIDENCE_READ_RE = re.compile(
-    r"^- Evidence read: `(?P<path>[^`\n]+)`\s*$",
-    re.MULTILINE,
-)
-_FILE_LINE_CITATION_RE = re.compile(
-    r"`(?P<path>(?!https?://)[^`\n]+?):(?P<line>\d+(?:-\d+)?)`"
-)
-_EXTENSIONLESS_SOURCE_FILENAMES = frozenset(
-    {"Dockerfile", "Justfile", "Makefile", "Procfile", "Rakefile"}
-)
-
 _REPORT_BASENAME_SEQ_RE = re.compile(r"-(?P<seq>\d{3})(?:\.data)?\.(?:md|json)$")
 
 
@@ -2417,181 +2394,23 @@ def _report_run_seq(report_path: Path) -> str | None:
     return match.group("seq") if match else None
 
 
-def _cited_file_paths(content: str) -> set[str]:
-    paths: set[str] = set()
-    for match in _FILE_LINE_CITATION_RE.finditer(content):
-        path = match.group("path")
-        if _looks_like_file_path(path):
-            paths.add(path)
-    return paths
-
-
-def _looks_like_file_path(path: str) -> bool:
-    if (
-        not path
-        or path.startswith(("-", "$"))
-        or any(char.isspace() for char in path)
-    ):
-        return False
-    if re.fullmatch(r"[0-9a-fA-F]{7,64}", path):
-        return False
-    return (
-        "/" in path
-        or "." in Path(path).name
-        or Path(path).name in _EXTENSIONLESS_SOURCE_FILENAMES
-    )
-
-
-def _audit_evidence_read_paths(content: str) -> set[str]:
-    return {
-        match.group("path")
-        for match in _EVIDENCE_READ_RE.finditer(content)
-    }
-
-
-def _worker_prompt_path(
-    report_path: Path,
-    worker_role: str,
-    task_type: str,
-    seq: str,
-) -> Path:
-    return (
-        report_path.parent.parent
-        / "prompts"
-        / f"{worker_role}-prompt-{task_type}-{seq}.md"
-    )
-
-
-def _validate_worker_evidence_read_ledger(
-    *,
-    report_path: Path,
-    worker_role: str,
-    task_type: str,
-    seq: str,
-    result_name: str,
-    result_content: str,
-    audit_path: Path,
-    failures: list[str],
-) -> None:
-    if worker_role == "report-writer-worker":
-        return
-    prompt_path = _worker_prompt_path(report_path, worker_role, task_type, seq)
-    try:
-        prompt_content = prompt_path.read_text(encoding="utf-8")
-    except OSError:
-        return
-    if EVIDENCE_LEDGER_HEADER not in prompt_content.splitlines():
-        return
-    try:
-        audit_content = audit_path.read_text(encoding="utf-8")
-    except OSError as exc:
-        failures.append(
-            f"worker audit sidecar unreadable: {audit_path.name} ({exc})"
-        )
-        return
-
-    missing_paths = sorted(
-        _cited_file_paths(result_content) - _audit_evidence_read_paths(audit_content)
-    )
-    for missing_path in missing_paths:
-        failures.append(
-            f"worker `{worker_role}` result `{result_name}` cites "
-            f"`{missing_path}:line` without an Evidence read row for "
-            f"`{missing_path}` in `{audit_path.name}`"
-        )
-
-
 def validate_worker_results_audit(
     report_path: Path, task_type: str, failures: list[str]
 ) -> None:
-    """Enforce the worker audit sidecar contract.
-
-    For every `worker-results/<worker>-<task-type>-<seq>.md` **this run**
-    produced (skipping the audit sidecar itself), the validator checks:
-
-    1. The main worker-results file does NOT contain a `## 0. Reading
-       Confirmation` heading. That block moved to the audit sidecar with
-       the report-format readability pass.
-    2. The matching audit sidecar exists at
-       `<worker>-audit-<task-type>-<seq>.md`. Missing sidecar means the
-       worker silently skipped the reading-confirmation step.
-    3. For new prompts carrying the required-v1 marker, every canonical
-       backticked `path:line` citation has a matching Evidence read row in
-       that audit sidecar. Historical prompts without the marker retain the
-       existence-only contract.
-
-    Scoped to this run's seq. `worker-results/` accumulates every run's
-    artifacts, so scanning the whole directory judged a run by files it did
-    not produce: a task that once opted a worker in and later dropped it from
-    the roster failed forever on that worker's old sidecar, with no legitimate
-    remedy — the lead can neither fabricate a sidecar for a worker it never
-    dispatched nor delete a prior run's audit record.
-    """
-    # `report_path` is `runs/<task-type>/reports/final-report-...md`; the
-    # sibling `worker-results/` directory holds every worker artifact.
-    worker_results_dir = report_path.parent.parent / "worker-results"
-    if not worker_results_dir.is_dir():
-        # No worker-results directory means no analysis workers ran (e.g.
-        # `release-handoff` which is single-lead). Nothing to enforce.
-        return
-
-    run_seq = _report_run_seq(report_path)
-
-    for path in sorted(worker_results_dir.glob("*.md")):
-        name = path.name
-        if "-audit-" in name:
-            continue
-        match = _WORKER_RESULT_BASENAME_RE.match(name)
-        if match is None:
-            # Files that don't match the canonical pattern (e.g. ad-hoc
-            # notes left by the operator) are out of contract scope.
-            continue
-        if match.group("task_type") != task_type:
-            # Cross-phase artifacts shouldn't appear here; skip rather
-            # than fail to keep the check focused on the current phase.
-            continue
-        if run_seq is not None and match.group("seq") != run_seq:
-            # A prior run's artifact. Its contract was judged when it ran.
-            continue
-
-        worker_role = match.group("worker")
-        seq = match.group("seq")
-        rel = path.name
-        try:
-            content = path.read_text()
-        except OSError as exc:
-            failures.append(f"worker-results file unreadable: {rel} ({exc})")
-            continue
+    """Enforce the worker audit sidecar contract at Phase 7.
 
-        if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
-            failures.append(
-                f"worker-results file `{rel}` contains a `## 0. Reading "
-                f"Confirmation` heading — that block moved to the audit "
-                f"sidecar (`{worker_role}-audit-{task_type}-{seq}.md`). "
-                f"Remove the §0 heading + body from the main file and "
-                f"write a fresh sidecar."
-            )
-
-        audit_path = worker_results_dir / f"{worker_role}-audit-{task_type}-{seq}.md"
-        if not audit_path.exists():
-            failures.append(
-                f"worker `{worker_role}` produced `{rel}` but no audit sidecar "
-                f"at `{audit_path.name}` — the sidecar must carry the Reading "
-                f"Confirmation block (one short line per input file). Workers "
-                f"write this in the same step as the main worker-results file."
-            )
-            continue
-
-        _validate_worker_evidence_read_ledger(
-            report_path=report_path,
-            worker_role=worker_role,
-            task_type=task_type,
-            seq=seq,
-            result_name=rel,
-            result_content=content,
-            audit_path=audit_path,
-            failures=failures,
-        )
+    The rules themselves live in `okstra_ctl.worker_audit_ledger` so that
+    `okstra worker-audit-check` can apply the identical checks mid-run, while
+    the worker session is still alive and can fix its own citations. All this
+    wrapper adds is the Phase 7 anchor: the run directory and this run's seq,
+    both read off the report path.
+    """
+    failures.extend(check_worker_results_audit(
+        # `report_path` is `runs/<task-type>/reports/final-report-...md`.
+        report_path.parent.parent,
+        task_type,
+        _report_run_seq(report_path),
+    ))
 
 
 def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
@@ -2972,6 +2791,68 @@ def _route_target_matches(value: Any, target: str, *, command: bool) -> bool:
     )
 
 
+def _upstream_by_candidate(candidates: list[Any]) -> dict[str, list[str]]:
+    upstream: dict[str, list[str]] = {}
+    for candidate in candidates:
+        if not isinstance(candidate, Mapping):
+            continue
+        candidate_id = candidate.get("id")
+        declared = candidate.get("downstreamOf")
+        if isinstance(candidate_id, str) and isinstance(declared, list):
+            upstream[candidate_id] = [row for row in declared if isinstance(row, str)]
+    return upstream
+
+
+def _chain_cycle(upstream: dict[str, list[str]]) -> list[str]:
+    """The first cycle reachable through `downstreamOf`, as the ids that form it.
+
+    A cycle is a diagnosis that says each step is caused by the next, so it
+    names no first cause. It also hangs the figure's layering, which relaxes
+    until depths settle.
+    """
+    settled: set[str] = set()
+    for start in sorted(upstream):
+        stack = [start]
+        on_path: list[str] = []
+        while stack:
+            current = stack.pop()
+            if current in on_path:
+                return on_path[on_path.index(current):] + [current]
+            if current in settled or current not in upstream:
+                continue
+            on_path.append(current)
+            stack.extend(upstream[current])
+        settled.update(on_path)
+    return []
+
+
+def _validate_cause_chain(
+    candidates: list[Any], candidate_ids: set[str], failures: list[str]
+) -> None:
+    """`downstreamOf` must name a sibling candidate, and never itself."""
+    upstream = _upstream_by_candidate(candidates)
+    for candidate_id in sorted(upstream):
+        unknown = sorted(set(upstream[candidate_id]) - candidate_ids)
+        if unknown:
+            failures.append(
+                f"final-report data.json: {candidate_id}.downstreamOf names "
+                "unknown cause candidate(s): " + ", ".join(unknown) + "."
+            )
+        if candidate_id in upstream[candidate_id]:
+            failures.append(
+                f"final-report data.json: {candidate_id}.downstreamOf names itself."
+            )
+    cycle = _chain_cycle(
+        {key: [row for row in value if row in candidate_ids] for key, value in upstream.items()}
+    )
+    if cycle:
+        failures.append(
+            "final-report data.json: cause candidates form a downstreamOf cycle: "
+            + " -> ".join(cycle)
+            + "."
+        )
+
+
 def _validate_error_analysis_consistency(
     data: Mapping[str, Any], failures: list[str]
 ) -> None:
@@ -3018,6 +2899,8 @@ def _validate_error_analysis_consistency(
             + "."
         )
 
+    _validate_cause_chain(candidates, set(candidate_ids), failures)
+
     routing_value = error_analysis.get("routing")
     routing = routing_value if isinstance(routing_value, Mapping) else {}
     target = routing.get("nextTaskType")
@@ -3243,6 +3126,9 @@ def validate_final_report_data(
     _validate_verdict_card_fields(data, failures)
     # Phase-agnostic: the coverage critic runs in every finding-producing phase.
     _validate_unverified_critic_gaps_recorded(data, failures)
+    # Called here rather than from a task-type branch: four profiles raise
+    # clarification rows, and the gate scopes itself by task type internally.
+    _validate_clarification_options(data, failures)
 
     task_type = (data.get("header") or {}).get("taskType")
     _validate_verifier_fail_blocks_verdict(data, failures)
@@ -3267,6 +3153,8 @@ def validate_final_report_data(
             print(f"validate-run: warning: {warning}", file=sys.stderr)
         _validate_supersession_ledger(data, failures)
         _validate_clarification_evidence_note(data, failures)
+        _validate_approval_clarification_backtrace(data, failures)
+        _validate_rerun_guidance(data, failures)
         _validate_variation_point_analysis(
             (data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
             resolve_architecture(_project_root_from_report(report_path)),
@@ -3594,6 +3482,38 @@ def _self_fix_budget_exhausted(pbv: dict) -> bool:
     )
 
 
+def _state_classification(item: dict, gate_class: str) -> str:
+    """This item's `planItems[].rounds[].classification` for the state file.
+
+    The gate classifier deliberately folds `partial-consensus` and
+    `dissent-isolated` into `has-dissent` — only the majority-disagree boundary
+    moves the gate. The state file records the finer label, and the information
+    to recover it is in the same verdicts, so the mapping lives beside the
+    classifier rather than being re-invented by each lead.
+
+    *gate_class* is passed in rather than recomputed so that the caller's
+    effective classification — which may have been downgraded by
+    `_is_dissent_downgraded` — is the one this translates.
+
+    `contested` never appears: it is only meaningful at `maxRounds > 1`, and at
+    the default `maxRounds=1` the round protocol folds any otherwise-unresolved
+    item into `partial-consensus`.
+    """
+    if gate_class == "all-non-result":
+        # No non-error vote at all is the `needs-reverify` shape taken to its
+        # limit — "fewer than 2 participating votes" covers zero.
+        return "needs-reverify"
+    if gate_class != "has-dissent":
+        return gate_class
+    dissenting = sum(
+        1
+        for vote in (item.get("verdicts") or [])
+        if isinstance(vote, dict)
+        and str(vote.get("verdict") or "").strip().upper() == "DISAGREE"
+    )
+    return "dissent-isolated" if dissenting == 1 else "partial-consensus"
+
+
 def _is_dissent_downgraded(item: dict, pbv: dict) -> bool:
     """Whether a surviving `majority-disagree` item stops blocking approval.
 
@@ -4116,6 +4036,200 @@ def _validate_clarification_evidence_note(data: dict, failures: list[str]) -> No
         )
 
 
+_CLARIFICATION_OPTION_SCHEMA_VERSION = "2.0"
+# The four profiles that read `_clarification-recommendation.md`. Unlike the
+# evidence-note gate above — which is called from inside the
+# `implementation-planning` branch — this one is called phase-agnostically, so
+# the task-type filter here is the only thing scoping it.
+_CLARIFICATION_OPTION_TASK_TYPES = frozenset({
+    "error-analysis",
+    "implementation-planning",
+    "improvement-discovery",
+    "requirements-discovery",
+})
+# `in-repo` and `cross-repo` answer the same question, so exactly one may hold.
+_REACH_TOKENS = frozenset({"in-repo", "cross-repo"})
+_LEGACY_EXPECTED_FORM_RE = re.compile(r"\b(?:Recommended|Alternatives):")
+
+
+def _validate_clarification_options(data: dict, failures: list[str]) -> None:
+    """A `decision` row must carry its choices as data, not as prose.
+
+    The choices used to live inside the `expectedForm` string, where two
+    separate parsers split them differently and neither was checked — the board
+    the user picked from could disagree with the board the report meant.
+    Structured options remove the parsing; this gate keeps the structure
+    honest. Whether an impact claim is *true* is the adversarial round's job,
+    exactly as with `Evidence checked:`.
+
+    schema-v1 is exempt because it cannot comply: it keeps clarifications as a
+    Markdown table of strings and its schema forbids an `options` property, so
+    demanding one would fail every v1 `decision` row for a structure the format
+    has no place to hold.
+    """
+    if data.get("schemaVersion") != _CLARIFICATION_OPTION_SCHEMA_VERSION:
+        return
+    task_type = (data.get("header") or {}).get("taskType")
+    if task_type not in _CLARIFICATION_OPTION_TASK_TYPES:
+        return
+    for row in data.get("clarificationItems") or []:
+        if not isinstance(row, dict) or row.get("kind") != "decision":
+            continue
+        row_id = str(row.get("id") or "<unknown>")
+        _validate_option_set(row.get("options"), row_id, failures)
+        if _LEGACY_EXPECTED_FORM_RE.search(str(row.get("expectedForm") or "")):
+            failures.append(
+                f"final-report data.json: clarification `{row_id}` still encodes "
+                "its choices in `expectedForm` (`Recommended:` / `Alternatives:`). "
+                "Choices belong in `options[]`; `expectedForm` states only the "
+                "shape of the answer. Two sources for one fact leave consumers "
+                "disagreeing about which is authoritative."
+            )
+
+
+def _validate_option_set(
+    options: object, row_id: str, failures: list[str]
+) -> None:
+    """Check one `decision` row's `options[]` for pickability and reach."""
+    if not isinstance(options, list) or len(options) < 2:
+        failures.append(
+            f"final-report data.json: clarification `{row_id}` is a `decision` "
+            "but does not offer at least two `options[]`. A decision the user "
+            "cannot choose between is not a decision."
+        )
+        return
+    entries = [option for option in options if isinstance(option, dict)]
+    recommended = sum(1 for option in entries if option.get("role") == "recommended")
+    if recommended != 1:
+        failures.append(
+            f"final-report data.json: clarification `{row_id}` must carry exactly "
+            f"one `role: recommended` option (found {recommended}). The reader "
+            "needs to know which answer the run stands behind."
+        )
+    for index, option in enumerate(entries):
+        tokens = option.get("scopeImpact")
+        reach = (
+            [token for token in tokens if token in _REACH_TOKENS]
+            if isinstance(tokens, list)
+            else []
+        )
+        if len(reach) != 1:
+            failures.append(
+                f"final-report data.json: clarification `{row_id}` option "
+                f"[{index}] must declare exactly one reach token — `in-repo` or "
+                f"`cross-repo` (found {len(reach)}). The reader cannot weigh an "
+                "option whose reach is unstated or self-contradictory."
+            )
+
+
+def _has_clarification_backtrace(
+    row_id: str, plan_items: object, coverage: object
+) -> bool:
+    """Whether the plan records anything this clarification blocks.
+
+    Two link shapes, both authored by the same run: the `P-*` plan item that
+    carries the `clarificationId`, and the requirement-coverage row blocked on
+    the id. `incremental-scope` resolves impacted stages from exactly these
+    two, and the coverage side goes through its predicate so the gate and the
+    resolver cannot disagree about what counts as a link.
+    """
+    if isinstance(plan_items, list) and any(
+        isinstance(item, dict) and item.get("clarificationId") == row_id
+        for item in plan_items
+    ):
+        return True
+    return isinstance(coverage, list) and any(
+        coverage_row_blocked_on(row, row_id) for row in coverage
+    )
+
+
+def _validate_approval_clarification_backtrace(
+    data: dict, failures: list[str]
+) -> None:
+    """An approval blocker must record what it blocks.
+
+    `_validate_plan_body_clarification_matching` already walks the other
+    direction — a majority-disagree plan item must cite a `blocks: approval`
+    row. Nothing walked this way, so a row could withhold approval while
+    recording no blast radius at all. The cost lands on the re-run:
+    `incremental-scope` resolves impacted stages from these links and treats an
+    id that traces to no stage as grounds to re-verify everything, so one
+    unlinked blocker turns a narrow re-run into a full one.
+    """
+    if (data.get("header") or {}).get("taskType") != "implementation-planning":
+        return
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return
+    coverage = planning.get("requirementCoverage")
+    verification = planning.get("planBodyVerification")
+    plan_items = (
+        verification.get("planItems") if isinstance(verification, dict) else None
+    )
+    for row in data.get("clarificationItems") or []:
+        if not isinstance(row, dict) or row.get("blocks") != "approval":
+            continue
+        row_id = str(row.get("id") or "<unknown>")
+        if _has_clarification_backtrace(row_id, plan_items, coverage):
+            continue
+        failures.append(
+            f"final-report data.json: clarification `{row_id}` blocks approval "
+            "but has no back-trace into the plan — no plan item carries it as "
+            "`clarificationId`, and no requirement-coverage row is `blocked "
+            f"{row_id}` in its `status` or `approvalDisposition`. An item that "
+            "withholds approval without recording what it affects forces the "
+            "next re-run to re-verify everything."
+        )
+
+
+_RERUN_FLAG = "--answered-clarifications"
+
+
+def _next_step_texts(steps: object) -> list[str]:
+    """Every reader-visible string in `recommendedNextSteps`, prose and command."""
+    texts: list[str] = []
+    for step in steps if isinstance(steps, list) else []:
+        if not isinstance(step, dict):
+            continue
+        texts.append(str(step.get("text") or ""))
+        for command in step.get("commands") or []:
+            if isinstance(command, dict):
+                texts.append(str(command.get("claudeCode") or ""))
+                texts.append(str(command.get("terminal") or ""))
+    return texts
+
+
+def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
+    """A report that withholds approval must say how to come back from it.
+
+    The way forward — answer the blockers, then re-run carrying those ids —
+    lived only in the lead prompt, which is read *after* the next run has
+    already started. The person who has to act reads the report instead, and it
+    told them nothing about the next command. Requiring the flag by name is a
+    low bar deliberately: it does not check that the rest of the step is right,
+    only that the report stops leaving the reader to work the mechanics out.
+    """
+    if (data.get("header") or {}).get("taskType") != "implementation-planning":
+        return
+    has_blocker = any(
+        isinstance(row, dict) and row.get("blocks") == "approval"
+        for row in data.get("clarificationItems") or []
+    )
+    if not has_blocker:
+        return
+    if any(_RERUN_FLAG in text for text in _next_step_texts(
+        data.get("recommendedNextSteps")
+    )):
+        return
+    failures.append(
+        "final-report data.json: this plan withholds approval on a "
+        "`blocks: approval` clarification, but no `recommendedNextSteps` entry "
+        f"tells the reader how to resume — name the `{_RERUN_FLAG}` re-run in a "
+        "step's `text` or one of its `commands`. `okstra recap assemble` "
+        "prints the exact ids and flag value once the answers are recorded."
+    )
+
+
 def _validate_self_fix_grouping(data: dict, failures: list[str]) -> None:
     """A self-fix round must be instructed by cause, not as a flat item list.
 
@@ -5866,6 +5980,21 @@ def validate_plan_body_section(
     return [*_detect_self_fix_recurrence(pbv), *_detect_uniform_verifier(pbv)]
 
 
+def _gate_summary_item(item: dict, pbv: dict) -> dict:
+    """One `gate.items[]` row: the gate class plus its state-file counterpart."""
+    classification = (
+        "has-dissent"
+        if _is_dissent_downgraded(item, pbv)
+        else _classify_plan_item_gate(item)
+    )
+    return {
+        "id": item.get("id"),
+        "classification": classification,
+        "stateClassification": _state_classification(item, classification),
+        "correctnessCritical": _is_correctness_critical(item),
+    }
+
+
 def plan_body_gate_summary(data: dict) -> dict | None:
     """The §5.5.9 gate as the round protocol's step 5 needs it — per-item
     classification, the whole-gate value, and the `gateBlockedBy` causes, all
@@ -5887,13 +6016,7 @@ def plan_body_gate_summary(data: dict) -> dict | None:
     if recomputed is None:
         return None
     items = [
-        {
-            "id": item.get("id"),
-            "classification": "has-dissent"
-            if _is_dissent_downgraded(item, pbv)
-            else _classify_plan_item_gate(item),
-            "correctnessCritical": _is_correctness_critical(item),
-        }
+        _gate_summary_item(item, pbv)
         for item in (pbv.get("planItems") or [])
         if isinstance(item, dict)
     ]