okstra 0.177.0 → 0.177.1

package/runtime/python/okstra_ctl/run.py

@@ -1929,12 +1929,19 @@ def _build_static_execution_manifest(
     plan: AssignmentPlan,
     context: AssignmentContext,
     lead: ResolvedAssignment,
+    translator: ResolvedAssignment,
 ) -> ExecutionManifest:
     participants: list[ParticipantAssignment] = []
     roles: list[RoleExecution] = []
+    # The translator is resolved outside the role plan, like the lead, and both
+    # are named in `invocationAssignments`. Without a role execution here,
+    # `agent-prompt materialize --audience translator` has no canonical
+    # identity to bind to and refuses — so a `reportLanguage: ko` run could
+    # never write its translation sidecar and rendered the English source.
     assignments = (
         lead,
         *(row for row in plan.assignments if row.role != "leader"),
+        translator,
     )
     for index, assignment in enumerate(assignments, start=1):
         participant_ref = f"participant-{index:03d}"
@@ -2145,8 +2152,14 @@ def _canonical_selection_provider_ids(
         and "implementer" not in scopes.global_
     )
     if implementer_uses_bundled_default:
+        # `--executor` names the provider that implements, so it belongs in the
+        # roster the same way the bundled default does. Reading only the default
+        # left `--executor <provider>` with no assignment of its own: the run
+        # rendered without that provider, and asking for it with `--workers`
+        # was refused as not being in the roster.
         selected.append(
-            _default("OKSTRA_DEFAULT_EXECUTOR", "claude")
+            (inp.executor or "").strip().lower()
+            or _default("OKSTRA_DEFAULT_EXECUTOR", "claude")
         )
     if _needs_profile_worker_candidates(profile, selection, scopes):
         selected.extend(
@@ -2302,6 +2315,7 @@ class RoleAssignment:
     role: str
     provider: str
     model_display: str
+    model_id: str
     model_execution_value: str
     runner: str
     host_runtime: str
@@ -2309,9 +2323,14 @@ class RoleAssignment:
     worker_id: str = ""
 
     def to_model_payload(self) -> dict[str, object]:
+        # `model` carries the catalog model id, not the display name: the run
+        # manifest's role executions record `modelId`, and the two are compared
+        # to bind an assignment to its execution. A display name that differs
+        # from its id (every antigravity and kimi model) made that comparison
+        # fail for the whole provider.
         return {
             "provider": self.provider,
-            "model": self.model_display,
+            "model": self.model_id,
             "modelExecutionValue": self.model_execution_value,
             "runner": self.runner,
             "hostRuntime": self.host_runtime,
@@ -2351,6 +2370,7 @@ class _ModelBindings:
     lead_assignment: RoleAssignment
     worker_assignments: tuple[RoleAssignment, ...]
     invocation_assignments: dict[str, dict[str, object]]
+    translator: ResolvedAssignment
 
 
 @dataclass(frozen=True)
@@ -2628,6 +2648,7 @@ def _resolve_model_bindings(
         resolved=translator_meta,
         role="translator",
     )
+    _reject_split_worker_models(executor_assignment, worker_assignments)
     invocation_assignments = _build_invocation_assignments(
         lead_assignment,
         worker_assignments,
@@ -2656,6 +2677,7 @@ def _resolve_model_bindings(
         lead_assignment=lead_assignment,
         worker_assignments=worker_assignments,
         invocation_assignments=invocation_assignments,
+        translator=translator_meta,
     )
 
 
@@ -2774,6 +2796,8 @@ def _project_model_bindings(
         provider: _legacy_projection_from_plan(provider, plan, context)
         for provider in ("claude", "codex", "antigravity")
     }
+    _reject_executor_outside_roster(executor_assignment, workers)
+    _reject_split_worker_models(executor_assignment, workers)
     invocation_assignments = _build_invocation_assignments(
         lead_assignment,
         workers,
@@ -2808,6 +2832,7 @@ def _project_model_bindings(
         lead_assignment=lead_assignment,
         worker_assignments=workers,
         invocation_assignments=invocation_assignments,
+        translator=translator,
     )
 
 
@@ -2858,6 +2883,64 @@ def _selected_execution_provider_ids(
     return tuple(dict.fromkeys(selected))
 
 
+def _reject_executor_outside_roster(
+    executor: RoleAssignment | None,
+    workers: tuple[RoleAssignment, ...],
+) -> None:
+    """Refuse an executor whose provider the roster never dispatches.
+
+    An implementation run opens its executor with `--workers <provider>`, so a
+    provider absent from the roster has no invocation to open. The legacy
+    selection path says so outright; the canonical path derived its roster from
+    role models alone, so `--executor <provider>` rendered fine and the run only
+    failed later, at `requested worker(s) are not in this run roster`.
+    """
+    if executor is None:
+        return
+    roster = {row.worker_id for row in workers if row.worker_id}
+    if executor.worker_id in roster:
+        return
+    raise PrepareError(
+        f"--executor {executor.worker_id} is not in this run's roster "
+        f"({', '.join(sorted(roster)) or 'empty'}); the executor is dispatched "
+        f"as a worker, so give it a roster slot — "
+        f"--role-model verifier={executor.worker_id}/<model> — or pick an "
+        f"executor already in the roster."
+    )
+
+
+def _reject_split_worker_models(
+    executor: RoleAssignment | None,
+    workers: tuple[RoleAssignment, ...],
+) -> None:
+    """Refuse one worker id standing for two roles on two different models.
+
+    The roster names a worker by provider, so an implementation run whose
+    executor and verifier are the same provider shares that id — but
+    `invocationAssignments["initial/<id>"]` can hold only one model, and it
+    holds the verifier's. Dispatch then looks the executor's role execution up
+    by that assignment, finds no row with a matching execution value, and stops
+    at `v2 execution identity does not match a canonical role execution`. The
+    render used to succeed and only the dispatch failed, by which point the run
+    had already claimed its stage.
+    """
+    if executor is None:
+        return
+    peer = next(
+        (row for row in workers if row.worker_id == executor.worker_id),
+        None,
+    )
+    if peer is None or peer.model_execution_value == executor.model_execution_value:
+        return
+    raise PrepareError(
+        f"worker {executor.worker_id!r} is the executor on "
+        f"{executor.model_execution_value!r} and a verifier on "
+        f"{peer.model_execution_value!r}; one worker id carries one model. "
+        f"Give both roles the same model, or pick a different --executor "
+        f"provider."
+    )
+
+
 def _resolve_executor_assignment(
     inp: PrepareInputs,
     workers: list[str],
@@ -2930,6 +3013,7 @@ def _role_assignment(
             role=role,
             provider=resolved.provider_id,
             model_display=resolved.display_name,
+            model_id=resolved.model_id,
             model_execution_value="unknown",
             runner="cli-wrapper",
             host_runtime=resolved.host_runtime,
@@ -2940,6 +3024,7 @@ def _role_assignment(
         role=role,
         provider=resolved.provider_id,
         model_display=resolved.display_name,
+        model_id=resolved.model_id,
         model_execution_value=binding.resolved_execution_value,
         runner=(
             "native-session"
@@ -4086,6 +4171,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         assignment_plan,
         assignment_context,
         models.lead,
+        models.translator,
     )
     dynamic_roles = tuple(
         requirement.role

package/runtime/python/okstra_ctl/team.py

@@ -2,8 +2,12 @@
 
 Under cmux this is every lead's door onto cmux surfaces, because okstra owns the
 panes there rather than the host. Outside cmux a worker owns no pane at all — it
-runs as a cli-wrapper subprocess — so there is nothing for teardown to reclaim.
-Which backend a run uses is read from its run manifest.
+runs as a cli-wrapper subprocess — so there is no pane for either closing
+command to act on. Which backend a run uses is read from its run manifest.
+
+`reclaim` is the round boundary and `teardown` is the end of the run: the first
+closes nothing but the finished dispatches' panes, the second takes every
+recorded pane and writes off whatever never finished.
 """
 from __future__ import annotations
 
@@ -18,7 +22,11 @@ from . import cmux
 from .adapters.dispatch import provider_worker_wrappers
 from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .application.dispatch_assignments import dispatch_assignments
-from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON, mutate_team_state
+from .dispatch_state import (
+    TEARDOWN_BEFORE_TERMINAL_REASON,
+    TERMINAL_WORKER_STATUSES,
+    mutate_team_state,
+)
 from .dispatch_core import (
     BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
@@ -34,7 +42,6 @@ from .session import observe_lead_session
 
 
 _SUPPORTED_WRAPPERS = provider_worker_wrappers(default_provider_registry())
-_TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -47,6 +54,8 @@ def main(argv: Sequence[str] | None = None) -> int:
             return _await(args)
         if args.command == "teardown":
             return _teardown(args)
+        if args.command == "reclaim":
+            return _reclaim(args)
     except DispatchError as exc:
         print(f"okstra team: {exc}", file=sys.stderr)
         return 2
@@ -62,6 +71,7 @@ def _parser() -> argparse.ArgumentParser:
     _add_dispatch_parser(sub)
     _add_await_parser(sub)
     _add_teardown_parser(sub)
+    _add_reclaim_parser(sub)
     return parser
 
 
@@ -85,7 +95,19 @@ def _add_await_parser(sub) -> None:
 
 
 def _add_teardown_parser(sub) -> None:
-    parser = sub.add_parser("teardown", help="reclaim this run's worker panes")
+    parser = sub.add_parser(
+        "teardown", help="close every recorded pane at the end of the run"
+    )
+    _add_run_args(parser)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--json", action="store_true")
+
+
+def _add_reclaim_parser(sub) -> None:
+    parser = sub.add_parser(
+        "reclaim",
+        help="close the finished dispatches' panes at a round boundary",
+    )
     _add_run_args(parser)
     parser.add_argument("--dry-run", action="store_true")
     parser.add_argument("--json", action="store_true")
@@ -161,8 +183,47 @@ def _teardown(args) -> int:
     team_state = _load_json(team_state_path, "team-state")
     panes = _reclaimable_panes(manifest, team_state)
     if args.dry_run:
-        _emit_teardown(args.json, panes)
+        _emit_panes(args.json, panes)
+        return 0
+    _close_panes(manifest, panes)
+    _mark_teardown_errors(team_state_path)
+    _emit_panes(args.json, panes)
+    return 0
+
+
+def _reclaim(args) -> int:
+    """Close the finished dispatches' surfaces at a round boundary.
+
+    Two things teardown does are wrong here. It closes every recorded surface,
+    which mid-round would kill the workers still running; and it writes off every
+    non-terminal dispatch as an error, which would drop a worker out of the retry
+    path it has not reached yet. So this shares the closing and the reporting and
+    nothing else.
+    """
+    manifest = _load_manifest(args.project_root, args.run_manifest)
+    _validate_team_manifest(manifest)
+    project_root = Path(args.project_root).resolve()
+    team_state_path = _resolve_project_path(
+        project_root, _require_string(manifest, "teamStatePath")
+    )
+    team_state = _load_json(team_state_path, "team-state")
+    panes = _reclaimable_panes(manifest, team_state, finished_only=True)
+    if args.dry_run:
+        _emit_panes(args.json, panes)
         return 0
+    _close_panes(manifest, panes)
+    _emit_panes(args.json, panes)
+    return 0
+
+
+def _close_panes(manifest: Mapping[str, Any], panes: list[dict[str, str]]) -> None:
+    """Close the given surfaces, then give the lead its width back.
+
+    The width recovery belongs here rather than to teardown alone. cmux hands the
+    freed width to a neighbour it picks, and that neighbour is not always the
+    lead — so a round boundary that closed panes and stopped there leaves the
+    lead squeezed for exactly the stretch the user spends reading it.
+    """
     from .adapters.runtime.assembly import port_for, runtime_chain
     from .domain.worker_runtime import RuntimeHandle, SURFACE_CMUX_PANE
 
@@ -178,9 +239,6 @@ def _teardown(args) -> int:
         chain[0].restore_lead()
     except (OSError, subprocess.SubprocessError, RuntimeError) as exc:
         print(f"okstra team: could not restore the lead's width: {exc}", file=sys.stderr)
-    _mark_teardown_errors(team_state_path)
-    _emit_teardown(args.json, panes)
-    return 0
 
 
 def _observe_lead_session_from_manifest(
@@ -240,10 +298,19 @@ def _await_payload(plan: DispatchPlan, completed: bool) -> dict[str, Any]:
 
 
 def _reclaimable_panes(
-    manifest: Mapping[str, Any], team_state: Mapping[str, Any]
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    *,
+    finished_only: bool = False,
 ) -> list[dict[str, str]]:
     """Everything this run owns and may close.
 
+    `finished_only` is what separates a round boundary from the end of the run.
+    Teardown closes every recorded surface because no dispatch is expected to
+    continue past it. Mid-round the live workers' surfaces must survive, so
+    reclaim asks for the finished ones only — closing an `in-progress` surface
+    kills that worker and the round has no result to show for it.
+
     The recorded ids are the only candidates. There is no per-pane tag API to
     sweep with, and scanning by title would be worse than nothing: cmux labels
     its own agent surfaces with the same glyph the harness uses for a teammate
@@ -254,8 +321,11 @@ def _reclaimable_panes(
     seen: set[str] = set()
     panes: list[dict[str, str]] = []
     for record in team_state.get("workerDispatches", []):
-        if isinstance(record, dict):
-            _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
+        if not isinstance(record, dict):
+            continue
+        if finished_only and record.get("status") not in TERMINAL_WORKER_STATUSES:
+            continue
+        _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
     if _is_cmux_run(manifest):
         return _still_open_surfaces(panes)
     return panes
@@ -295,7 +365,7 @@ def _mark_teardown_errors(team_state_path: Path) -> None:
     def mark(payload: dict[str, Any]) -> bool:
         changed = False
         for record in payload.get("workerDispatches", []):
-            if isinstance(record, dict) and record.get("status") not in _TERMINAL_STATUSES:
+            if isinstance(record, dict) and record.get("status") not in TERMINAL_WORKER_STATUSES:
                 record["status"] = "error"
                 record["reason"] = TEARDOWN_BEFORE_TERMINAL_REASON
                 changed = True
@@ -304,7 +374,7 @@ def _mark_teardown_errors(team_state_path: Path) -> None:
     mutate_team_state(team_state_path, mark)
 
 
-def _emit_teardown(as_json: bool, panes: list[dict[str, str]]) -> None:
+def _emit_panes(as_json: bool, panes: list[dict[str, str]]) -> None:
     if as_json:
         _print_json({"panes": panes})
         return

package/runtime/python/okstra_ctl/tmux.py

@@ -16,9 +16,8 @@ from typing import Optional, Sequence
 
 # container watcher/tail pane 전용 태그. 이 태그가 붙은 pane 은 세션 종료 후에도
 # 생존한다 — watcher/tail 의 "세션 후 생존" 불변식이다. 예전에는 SessionEnd 의
-# `okstra-trace-cleanup.sh --reap` 이 다른 태그만 스캔한다는 사실이 그 생존을
-# 지탱했지만, 지금은 그 모드와 훅 자체가 없어 pane 을 세션 경계에서 회수하는
-# 주체가 아예 없다. 회수는 `down` / `stop-watcher` 의 스코프 reap 뿐이다.
+# 태그 스캔이 다른 태그만 본다는 사실이 그 생존을 지탱했지만, 지금은 그 스캔과
+# 훅과 스크립트 자체가 없어 pane 을 세션 경계에서 회수하는 주체가 아예 없다. 회수는 `down` / `stop-watcher` 의 스코프 reap 뿐이다.
 CONTAINER_TAG_OPTION = "@okstra_container_run"
 
 

package/runtime/python/okstra_ctl/worker_runner.py

@@ -225,8 +225,8 @@ class _AbnormalExit:
     their default disposition ends the process outright, and nothing in this
     file runs (measured — a bash ``trap … EXIT`` does fire on SIGTERM, which is
     why the shell wrappers needed no equivalent of this class). Those two are
-    the common abnormal exits: a pane kill, ``okstra-trace-cleanup.sh``, session
-    teardown. Without this the sidecar stays at ``started`` and
+    the common abnormal exits: a pane close, ``okstra team reclaim`` /
+    ``okstra team teardown``, session teardown. Without this the sidecar stays at ``started`` and
     ``worker_liveness`` reads a dead worker as a working one.
 
     SIGKILL and a host crash remain uncovered because nothing can cover them. A

package/runtime/python/okstra_ctl/write_policy.py

@@ -175,7 +175,15 @@ def planned_paths_from_run_manifest(
     active_value = manifest.get("activeRunContextPath")
     if not isinstance(active_value, str) or not active_value:
         raise WritePolicyError("implementer write policy has no active run context")
-    active = _read_json(_rooted(project_root, active_value), "active run context")
+    # `compact_active_run_context` drops `sourceArtifacts` and stores path
+    # hints instead; the hydrator is what puts the block back. Reading the file
+    # raw always saw `None` here and reported the run as having no approved
+    # stage authority, which blocked every implementer dispatch.
+    from .path_hints import hydrate_active_run_context
+
+    active = hydrate_active_run_context(
+        _read_json(_rooted(project_root, active_value), "active run context")
+    )
     source = active.get("sourceArtifacts")
     run_inputs_value = source.get("runInputsPath") if isinstance(source, Mapping) else None
     run = active.get("run")

package/runtime/schemas/final-report-v2.0.schema.json

@@ -6999,7 +6999,9 @@
           "enum": [
             "Claude Code",
             "Codex",
-            "Antigravity"
+            "Antigravity",
+            "Grok",
+            "Kimi"
           ]
         },
         "role": {

package/runtime/skills/okstra-run/SKILL.md

@@ -239,9 +239,9 @@ okstra config set pr-template-path "<value>" --scope global
 
 If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
 
-Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — reclaim the prior round's completed teammate panes so they do not accumulate, in two passes and adding `--keep report-writer-worker` to **both** whenever the report writer is still in flight. First source the count: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` never kills and prints one `<pane_id>\t<pane_title>` line per pane it would reclaim — count those lines as `<n>`. Then run the same command **without** `--list` to perform the reclaim, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. Call both passes after collecting results and before the next dispatch so no in-flight worker pane is caught. This `tmux kill-pane`s the harness teammate panes; `shutdown_request` alone only idles the agent and never frees the pane, so it stays part of the run-end sequence for roster/token hygiene. `<RUN_DIR>` is the current (or just-finished) run's directory; its recorded `state/lead-pane.id` scopes the lead's session and the lead pane is never killed. In a non-tmux session there are no panes and the script is a silent no-op.
+Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate, in two passes. First count: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH> --dry-run` closes nothing and prints one `<paneId>\t<kind>` line per pane it would close — count those lines as `<n>`. Then run the same command **without** `--dry-run` to close them, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. `shutdown_request` alone only idles the agent and frees no pane, so it stays part of the run-end sequence for roster/token hygiene. A `cli-wrapper` run holds no pane at all, so `<n>` is `0` — still emit the checkpoint.
 
-Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same reclaim first: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` to count the panes, then the same command without `--list` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `trace-cleanup` call is what actually closes it. This keeps a user gate from being shown while finished worker panes remain; in-flight workers and an in-flight report writer are preserved.
+Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same two passes first: `okstra team reclaim … --dry-run` to count the panes, then the same command without `--dry-run` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `team reclaim` call is what closes it. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes.
 
 Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
 
@@ -359,7 +359,7 @@ Queue = the topologically-sorted stage list from splitting `orchestration.chainS
 
 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
-3. After confirming that `done` row was written, reclaim the completed teammate panes of the stage you just finished: run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<the run dir of the stage you just completed>"` (add `--keep report-writer-worker` if the report writer is still in flight). Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — reclaim the panes the same way, then stop the queue per "Stage ended FAIL" above.
+3. After confirming that `done` row was written, close the panes of the stage you just finished: run `okstra team teardown --project-root <projectRoot> --run-manifest <that stage's RUN_MANIFEST_PATH>`. That stage's run is over, so this is the run-end command rather than the round-boundary one. Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — close the panes the same way, then stop the queue per "Stage ended FAIL" above.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion to the user.

package/runtime/templates/reports/html/base.template.html

@@ -121,8 +121,7 @@
     "seq": runMeta.seq,
     "source-report": runMeta.source_report,
     "source-data": sourceData,
-    "source-data-sha256": dataSha256,
-    "source-md-sha256": markdownSha256
+    "source-data-sha256": dataSha256
   } | tojson }}</script>
   <script>{{ js | safe }}</script>
 </body>

package/runtime/validators/validate-report-views.py

@@ -2,20 +2,26 @@
 """Validate the self-contained HTML view produced by Phase 7 step 1.5
 (``scripts/okstra-render-report-views.py``).
 
-Checks, for a given final-report MD path:
-  1. ``*.html`` sibling exists when the report has clarification rows,
-     an analysis-review contract, or a plan-approval contract.
-  2. HTML's ``source-sha256`` in run-meta matches the current MD body —
-     stale html detection.
-  3. HTML's §5.6 / §5.7 / §5.8 deliverable regions contain no
-     ``<textarea>`` / ``<input>`` / ``<select>`` (form-attach is
-     restricted to §1 clarification rows).
-  4. HTML has no external URLs in ``<script src=>`` / ``<link href=>`` /
-     ``<img src=>`` — self-contained guarantee.
-  5. Every Response ID in HTML matches the §1 Clarification Items table
-     of the source MD (1:1).
-  6. Analysis reports contain all three Analysis Review decisions and an
-     affected-ID selector exactly matching the structured IDs in data.json.
+Takes the report's Markdown path as its handle and branches on schema.
+
+A schema-v2 report is checked against its ``.data.json`` — the record the
+HTML was rendered from — and never against the Markdown sibling, which is a
+second rendering of that same record:
+  1. the ``*.html`` sibling exists;
+  2. the document carries the task type's own template;
+  3. every human field the task type requires is present, and no audit field
+     leaked into the human main;
+  4. each visualization's svg node ids match its fallback ids;
+  5. the Response IDs in the HTML match ``clarificationItems[]`` 1:1;
+  6. no external URL appears in ``<script src=>`` / ``<link href=>`` /
+     ``<img src=>`` — the self-contained guarantee.
+
+A schema-v1 report keeps the Markdown as its source, so its checks read the
+§1 Clarification Items table (fail-closed when the heading is present but the
+table will not parse), require the HTML sibling only when the report carries
+clarification rows or an analysis-review / plan-approval contract, forbid form
+controls in the §5.6 / §5.7 / §5.8 deliverable regions, and enforce the same
+Response-ID parity and self-contained rules.
 
 Exit codes: 0 on success, 1 on any failure. Failures are printed one
 per line to stderr.
@@ -179,14 +185,21 @@ def _validate_analysis_review_html(
 
 
 def validate(report_path: Path) -> list[str]:
+    """Validate the html view of the report named by *report_path*.
+
+    A schema-v2 report is checked against its data.json and the rendered html;
+    the AI-handoff markdown is a sibling rendering of the same record and is
+    never read here, so it does not have to exist. Schema-v1 reports keep the
+    markdown as their source and still require it.
+    """
     failures: list[str] = []
+    v2 = _load_v2_data(report_path)
+    if v2 is not None:
+        return _validate_v2(report_path, v2[0], v2[1])
     if not report_path.is_file():
         return [f"final-report not found: {report_path}"]
 
     md = report_path.read_text(encoding="utf-8")
-    v2 = _load_v2_data(report_path)
-    if v2 is not None:
-        return _validate_v2(report_path, v2[0], v2[1])
     html_path = html_view_path(report_path)
     # §1 헤딩이 있는데 파싱이 실패하면 md_ids 가 빈 []이 되어 "clarification 없음
     # → skip" 으로 흘러 HTML form parity 게이트가 조용히 열린다. fail-closed.