okstra 0.176.1 → 0.177.1

package/runtime/validators/validate-run.py

@@ -51,8 +51,17 @@ from okstra_ctl.conformance import (  # noqa: E402
     qa_result_from_dict,
     validate_conformance_manifest,
 )
+from okstra_ctl.dispatch_state import (  # noqa: E402
+    DispatchError,
+    v2_worker_state_key,
+)
 from okstra_ctl.paths import RunRef  # noqa: E402
 from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION  # noqa: E402
+from okstra_ctl.release_gate import (  # noqa: E402
+    RELEASE_HANDOFF_TARGETS,
+    blocking_condition_ids,
+    release_handoff_allowed,
+)
 from okstra_ctl.domain.host import HostNotRegistered  # noqa: E402
 from okstra_ctl.registry.host_registry import default_host_registry  # noqa: E402
 from okstra_ctl.build_tools import (  # noqa: E402
@@ -857,6 +866,12 @@ def extract_contract(
         required_worker_roles = []
         failures.append("requiredWorkerRoles is missing from run/task manifest")
 
+    optional_worker_roles = run_contract.get("optionalWorkerRoles")
+    if not isinstance(optional_worker_roles, list):
+        optional_worker_roles = task_contract.get("optionalWorkerRoles")
+    if not isinstance(optional_worker_roles, list):
+        optional_worker_roles = []
+
     lead_role = (
         run_contract.get("leadRole")
         or task_contract.get("leadRole")
@@ -887,6 +902,7 @@ def extract_contract(
             or ""
         ),
         "required_worker_roles": required_worker_roles,
+        "optional_worker_roles": optional_worker_roles,
         "required_agent_status_entries": [
             item
             for item in required_agent_status_entries
@@ -1211,6 +1227,24 @@ def _is_legal_concurrent_run_skip(
     )
 
 
+def _dispatch_roster_key(row: Mapping[str, Any]) -> str:
+    """The roster worker this dispatch row started, v1 or v2.
+
+    A v2 row carries no `workerId` — `_validate_agent_dispatch_contract`
+    fails the run when one is present, calling it a v1/v2 identity mix. So
+    reading the roster key off that field alone left every v2 row invisible
+    and reported workers okstra had in fact started as never dispatched. The
+    v2 projection is the one dispatch itself uses.
+    """
+    worker_id = str(row.get("workerId", "")).strip()
+    if worker_id:
+        return worker_id
+    try:
+        return v2_worker_state_key(row)
+    except DispatchError:
+        return ""
+
+
 def _validate_cmux_workers_were_dispatched_by_okstra(
     team_state: dict,
     workers: list,
@@ -1238,9 +1272,11 @@ def _validate_cmux_workers_were_dispatched_by_okstra(
     if str(adapter.get("name", "")).strip() != "cmux":
         return
     recorded = {
-        str(row.get("workerId", "")).strip()
+        key
         for row in team_state.get("workerDispatches") or []
         if isinstance(row, dict)
+        for key in (_dispatch_roster_key(row),)
+        if key
     }
     missing = []
     for worker in workers:
@@ -1442,7 +1478,15 @@ def validate_team_state(
         if status != "completed" and not reason:
             failures.append(f"{role} with status `{status}` must include a reason")
 
-    unexpected_roles = set(by_role) - set(expected_workers)
+    # A declared optional role may appear in the roster and may equally be
+    # absent: the run states which ones it can dispatch (today, the critics),
+    # and running one is not a contract violation.
+    optional_roles = {
+        str(worker.get("role", "")).strip()
+        for worker in contract.get("optional_worker_roles", [])
+        if isinstance(worker, dict) and str(worker.get("role", "")).strip()
+    }
+    unexpected_roles = set(by_role) - set(expected_workers) - optional_roles
     for role in sorted(unexpected_roles):
         failures.append(f"unexpected worker role detected: {role}")
 
@@ -1616,60 +1660,46 @@ def _scan_token_usage_summary(
 # a section heading line (not as inline text inside a paragraph or table).
 _VERDICT_CARD_HEADING_RE = re.compile(r"^##[ \t]+Verdict Card\b", re.MULTILINE)
 
-_V2_AI_HANDOFF_HEADINGS = (
-    "## AI Handoff Summary",
-    "## Clarification and User Decisions",
-    "## Evidence Ledger",
-    "## Task Deliverable:",
-    "## Cross Verification Audit",
-    "## Execution Audit",
-    "## Token and Cost Audit",
-)
-
-
-# `humanSummary` / `userNarrative` belong to the human HTML. The AI Markdown
-# renders field names as headings or bold labels
-# (scripts/okstra_ctl/report_markdown.py `humanise`), so this matches the two
-# forms the renderer can emit rather than the raw JSON key — a key name in
-# quotes no longer appears anywhere in the Markdown. Anchored to the start of a
-# line so the same words inside worker prose are not a violation.
-_V2_HUMAN_ONLY_RENDERED_RE = re.compile(
-    r"^(?:#{2,6}[ \t]+(?P<heading>Human Summary|User Narrative)[ \t]*$"
-    r"|[ \t]*-[ \t]+\*\*(?P<label>Human Summary|User Narrative)\*\*[ \t]*:)",
-    re.MULTILINE,
-)
-
-
-def _validate_v2_ai_handoff(content: str, failures: list[str]) -> None:
-    positions: list[int] = []
-    for heading in _V2_AI_HANDOFF_HEADINGS:
-        count = content.count(heading)
-        if count != 1:
+def _validate_v2_report(
+    report_data: Mapping[str, Any],
+    required_agent_status_entries: list[str],
+    failures: list[str],
+) -> None:
+    """Contract checks for a schema-v2 report, read from its data.json.
+
+    The AI-handoff markdown is a deterministic rendering of this record, so the
+    checks that used to scan it — heading count and order, human-only fields
+    leaking into the AI artifact, a Reading Confirmation heading — were asking
+    whether the renderer had done its job, not whether the report was sound.
+    Schema enforcement in `render_final_report._enforce_schema` already answers
+    the second question, and the first is settled by the template. What is left
+    is the pair of facts the markdown could only ever carry second-hand: which
+    agents the run must account for, and whether the token cells were filled.
+
+    Both are scanned over the serialized record, as text, because that is what
+    the markdown scan was. Requiring each label to equal an
+    `executionStatus[].role` would be a stricter rule than the contract states
+    anywhere: the schema types `role` as a free string, no prompt or worker spec
+    fixes its vocabulary, and `okstra_token_usage.report._match_worker_index`
+    treats function-role spellings ("Analysis verifier", "Acceptance critic") as
+    a shape reports do take — matching them by containment, never equality.
+    Tightening this belongs with an authoring rule that says what to write, not
+    on its own. Nothing is lost by reading the record instead of its rendering:
+    the labels never come from the template or the i18n dictionaries.
+    """
+    serialized = json.dumps(report_data, ensure_ascii=False)
+    for label in required_agent_status_entries:
+        if label not in serialized:
             failures.append(
-                "schema-v2 AI handoff markdown requires exactly one "
-                f"`{heading}` heading; found {count}."
+                f"final report does not include required agent status entry: {label}"
+            )
+    for placeholder in TOKEN_PLACEHOLDERS:
+        if placeholder in serialized:
+            failures.append(
+                f"final report contains unsubstituted token placeholder `{placeholder}` — "
+                "run `okstra-token-usage.py ... --substitute-data <report-path>` during Phase 7"
             )
-            continue
-        positions.append(content.index(heading))
-    if len(positions) == len(_V2_AI_HANDOFF_HEADINGS) and positions != sorted(
-        positions
-    ):
-        failures.append(
-            "schema-v2 AI handoff markdown heading order does not match "
-            "templates/reports/final-report-v2.template.md."
-        )
-    for match in _V2_HUMAN_ONLY_RENDERED_RE.finditer(content):
-        field = match.group("heading") or match.group("label")
-        failures.append(
-            "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:
-        failures.append(
-            "final report contains a `## 0. Reading Confirmation` heading — "
-            "Reading Confirmation lives in the worker audit sidecar, never "
-            "in the AI handoff markdown."
-        )
+
 
 # Top-of-report Index block. The renderer
 # (scripts/okstra_ctl/render_final_report.py) injects `<a id="report-index">`
@@ -1777,16 +1807,34 @@ def _load_conformance_results(qa_dir: Path, manifest: dict) -> dict:
     return results
 
 
-_DIFF_SUMMARY_RE = re.compile(r"^###\s+5\.7\.3\b.*?(?=^###\s|\Z)", re.MULTILINE | re.DOTALL)
-_DIFF_ROW_PATH_RE = re.compile(r"^\|\s*`([^`]+)`\s*\|", re.MULTILINE)
+def _diff_summary_files(report_data: Mapping[str, Any]) -> list[str]:
+    """implementation 리포트가 신고한 변경 파일 목록 (`implementation.diffSummary.files[].file`).
 
+    렌더된 §5.7.3 표를 정규식으로 긁던 자리다. 표는 data.json 의 이 배열에서
+    렌더되는 파생물이라, 표를 읽는 쪽은 렌더 형식이 바뀔 때마다 조용히 빈
+    목록을 돌려주고 — conformance / self-mock 두 게이트가 전부 통과로 열렸다.
+    스키마가 `implementation` 블록에서 `diffSummary` 를 required 로 잡고
+    `rawStat` 이 비어있지 않으면 `files` 최소 1행을 요구하므로, 여기서는
+    구조가 어긋난 경우만 빈 목록으로 떨어뜨린다.
 
-def _parse_diff_summary_files(content: str) -> list[str]:
-    """implementation 리포트 §5.7.3 Diff Summary 표의 첫 셀(백틱 경로)들을 추출."""
-    section = _DIFF_SUMMARY_RE.search(content)
-    if section is None:
+    `diffSummary` 를 가진 task-type 은 implementation 뿐이다. final-verification
+    은 diff 를 `diffSummaryQuote` 문자열로만 인용하므로 두 게이트는 거기서
+    (md 를 읽던 시절과 똑같이) vacuous 하다.
+    """
+    implementation = report_data.get("implementation")
+    if not isinstance(implementation, Mapping):
+        return []
+    diff_summary = implementation.get("diffSummary")
+    if not isinstance(diff_summary, Mapping):
         return []
-    return _DIFF_ROW_PATH_RE.findall(section.group(0))
+    rows = diff_summary.get("files")
+    if not isinstance(rows, list):
+        return []
+    return [
+        row["file"]
+        for row in rows
+        if isinstance(row, Mapping) and isinstance(row.get("file"), str) and row["file"]
+    ]
 
 
 _STAGE_RUN_DIR_RE = re.compile(r"^stage-\d+$")
@@ -2150,12 +2198,12 @@ def _validate_planning_conformance_declared(report_path: Path, failures: list[st
 
 
 def _validate_conformance_surfaces(
-    report_path: Path,
+    report_data: Mapping[str, Any],
     scoped_manifest: dict,
     surface_patterns: object,
     failures: list[str],
 ) -> None:
-    changed_files = _parse_diff_summary_files(report_path.read_text(encoding="utf-8"))
+    changed_files = _diff_summary_files(report_data)
     if not changed_files:
         return
     uncovered = (
@@ -2191,6 +2239,7 @@ def _validate_conformance(
     own stage suffix. Whole-task runs evaluate every entry.
     """
     warnings: list[str] = []
+    report_data = _load_final_report_data(report_path)
     # conformance 산출물은 task-level(<task_root>/qa)에 있어 planning/
     # implementation/final-verification 가 공유한다. report_path 는
     # task_root/runs/<task-type>/reports/final-report.md (implementation 은
@@ -2231,7 +2280,7 @@ def _validate_conformance(
                     f"{manifest_path} is absent"
                 )
         _validate_conformance_surfaces(
-            report_path,
+            report_data,
             empty_scoped_manifest,
             surface_patterns,
             failures,
@@ -2295,7 +2344,7 @@ def _validate_conformance(
                 f"docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md."
             )
     _validate_conformance_surfaces(
-        report_path,
+        report_data,
         scoped,
         surface_patterns,
         failures,
@@ -2633,13 +2682,13 @@ def _validate_selfmock(report_path: Path, failures: list[str]) -> None:
     Stage-isolated runs read their own `self-mock-stage-<N>.json`; whole-task runs
     read the flat `self-mock.json`.
 
-    Only the implementation template renders the §5.7.3 diff summary
-    (`templates/reports/final-report-v2.template.md:589`); a final-verification report
-    quotes the diff as a blockquote instead, so this gate is vacuous there by
-    design — self-mock is enforced at the implementation stage, and
-    final-verification is a read-only re-verify that adds no test files.
+    Only an implementation report carries `implementation.diffSummary.files[]`;
+    a final-verification report records the diff as the `diffSummaryQuote`
+    string instead, so this gate is vacuous there by design — self-mock is
+    enforced at the implementation stage, and final-verification is a read-only
+    re-verify that adds no test files.
     """
-    changed = _parse_diff_summary_files(report_path.read_text(encoding="utf-8"))
+    changed = _diff_summary_files(_load_final_report_data(report_path))
     test_files = [
         path
         for path in changed
@@ -2740,8 +2789,8 @@ def _check_selfmock_changed_files(
     `--changed-file` is what the mutation adapters select their production
     sources from. Omit it and every adapter gets an empty target set, which is
     not a finding but reads like one had been looked for. Requiring the sidecar
-    to account for every file in the §5.7.3 diff summary keeps "gate B saw this
-    stage" apart from "gate B was handed nothing".
+    to account for every file in `implementation.diffSummary.files[]` keeps
+    "gate B saw this stage" apart from "gate B was handed nothing".
 
     Coverage is asked of the WHOLE diff, not just its test files: the production
     sources are precisely the part gate A never looks at.
@@ -2766,7 +2815,8 @@ def _check_selfmock_changed_files(
             f"the mutation gate — {sidecar} records changedFiles={declared}. Each "
             "adapter picks its production sources out of that set, so a file left "
             "out is a file no mutant was ever generated for. Pass every path from "
-            "the §5.7.3 diff summary with `--changed-file`, production sources "
+            "the report's `implementation.diffSummary.files[]` with `--changed-file`, "
+            "production sources "
             "included — filtering to the test files leaves gate B nothing to run "
             "on and reports a pass it never earned."
         )
@@ -2830,6 +2880,10 @@ def validate_report(
         failures.append(f"final report is missing: {report_path}")
         return
 
+    if (report_data or {}).get("schemaVersion") == "2.0":
+        _validate_v2_report(report_data or {}, required_agent_status_entries, failures)
+        return
+
     content = report_path.read_text()
     for label in required_agent_status_entries:
         if label not in content:
@@ -2844,10 +2898,6 @@ def validate_report(
                 "run `okstra-token-usage.py ... --substitute-data <report-path>` during Phase 7"
             )
 
-    if (report_data or {}).get("schemaVersion") == "2.0":
-        _validate_v2_ai_handoff(content, failures)
-        return
-
     # Catch the "workers typed `0` / `pending` instead of the placeholder"
     # failure mode that bypasses the placeholder check above.
     _scan_token_usage_summary(
@@ -6247,7 +6297,7 @@ def _validate_verified_row_recorded(
     report_path: Path,
     failures: list[str],
 ) -> None:
-    """An accepted single-stage verification must leave its `verified` row.
+    """A release-ready single-stage verification must leave its `verified` row.
 
     `okstra handoff record-verified` validates its own inputs, but nothing
     checked that it ever ran. Skipping it leaves the report saying `accepted`
@@ -6258,8 +6308,7 @@ def _validate_verified_row_recorded(
     """
     if str(data.get("verificationScope") or "") != "single-stage":
         return
-    token = str((data.get("finalVerdict") or {}).get("verdictToken") or "").strip()
-    if token.lower() != "accepted":
+    if not release_handoff_allowed(data):
         return
     stages = {
         row.get("stage")
@@ -6279,7 +6328,7 @@ def _validate_verified_row_recorded(
     missing = sorted(s for s in stages if s not in verified)
     if missing:
         failures.append(
-            f"final-verification accepted stage(s) {missing} but "
+            f"final-verification cleared stage(s) {missing} for release but "
             "`runs/implementation-planning/consumers.jsonl` carries no "
             "`verified` row for them. Run `okstra handoff record-verified` "
             "before finishing — without that row the report says accepted "
@@ -6308,11 +6357,11 @@ def _validate_verifier_fail_blocks_verdict(data: dict, failures: list[str]) -> N
     })
     if not failed:
         return
-    token = str((data.get("verdictCard") or {}).get("verdictToken") or "").strip()
+    token = str((data.get("finalVerdict") or {}).get("verdictToken") or "").strip()
     if token in _PASSING_VERDICT_TOKENS:
         failures.append(
             f"final-report data.json: verifier(s) {failed} recorded "
-            f"`verdict: FAIL` but `verdictCard.verdictToken` is `{token}`. A "
+            f"`verdict: FAIL` but `finalVerdict.verdictToken` is `{token}`. A "
             "verifier rejection MUST survive into the published verdict — "
             "dropping it during synthesis is how rejected work reaches "
             "`release-handoff`. Either carry the FAIL into a blocking verdict "
@@ -7914,6 +7963,82 @@ def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
         )
 
 
+_ADDED_SURFACE_NO_CALLER_RE = re.compile(r"^\s*none\b", re.IGNORECASE)
+
+
+def _validate_added_surface_audit(data: dict, failures: list[str]) -> None:
+    """Every surface the diff added is traced to a requirement, exempted, or paid for.
+
+    The coverage table proves each requirement reached the diff. Nothing proved
+    the reverse — that each thing the diff added answers a requirement — so work
+    nobody asked for passed every gate. This check reads the reverse table and
+    refuses a row that calls itself over-delivery without the blocker or
+    condition it became: a caller-less surface is an acceptance blocker, and a
+    surface with callers but no requirement is a conditional-acceptance
+    condition (ADR-0009 grades the two differently on purpose).
+    """
+    fv = data.get("finalVerification")
+    if not isinstance(fv, Mapping):
+        return
+    rows = fv.get("addedSurfaceAudit")
+    if not isinstance(rows, list):
+        return
+    blocker_ids = {
+        str(row.get("id"))
+        for row in (fv.get("acceptanceBlockers") or [])
+        if isinstance(row, Mapping)
+    }
+    condition_ids = {
+        str(row.get("id"))
+        for row in ((data.get("finalVerdict") or {}).get(
+            "conditionalAcceptanceConditions") or [])
+        if isinstance(row, Mapping)
+    }
+    for row in rows:
+        if not isinstance(row, Mapping):
+            continue
+        row_id = str(row.get("id") or "<id 없음>")
+        disposition = str(row.get("disposition") or "")
+        note = str(row.get("note") or "")
+        if disposition == "traced" and not str(row.get("requirement") or "").strip():
+            failures.append(
+                f"final-verification: addedSurfaceAudit {row_id} is `traced` but "
+                "names no requirement — a surface is traced to something the "
+                "brief asked for, or it is not traced."
+            )
+            continue
+        if disposition != "over-delivery":
+            continue
+        caller_less = bool(
+            _ADDED_SURFACE_NO_CALLER_RE.match(str(row.get("callers") or ""))
+        )
+        expected, known = (
+            ("AB", blocker_ids) if caller_less else ("CA", condition_ids)
+        )
+        cited = set(re.findall(rf"\b{expected}-\d{{3,}}\b", note))
+        if not cited:
+            failures.append(
+                f"final-verification: addedSurfaceAudit {row_id} is "
+                f"`over-delivery` with callers "
+                f"{'none' if caller_less else 'recorded'}, so its note MUST cite "
+                f"the `{expected}-NNN` row it became — "
+                + (
+                    "a caller-less surface is an acceptance blocker"
+                    if caller_less
+                    else "a surface with callers but no requirement is a "
+                         "conditional-acceptance condition"
+                )
+                + "."
+            )
+            continue
+        missing = sorted(cited - known)
+        if missing:
+            failures.append(
+                f"final-verification: addedSurfaceAudit {row_id} cites "
+                f"{missing}, which the report does not carry."
+            )
+
+
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;
@@ -7923,6 +8048,7 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
     """
     if (data.get("header") or {}).get("taskType") != "final-verification":
         return
+    _validate_added_surface_audit(data, failures)
     verdict = data.get("finalVerdict") or {}
     token = (verdict.get("verdictToken") or "").strip().lower()
     fv = data.get("finalVerification") or {}
@@ -7954,14 +8080,19 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "final-verification: verdict `conditional-accept` but "
             "conditionalAcceptanceConditions is empty — list every condition."
         )
-    if (
-        routing_token in {"release-handoff", "release-handoff(stage-group)"}
-        and token != "accepted"
-    ):
+    if routing_token in RELEASE_HANDOFF_TARGETS and not release_handoff_allowed(data):
+        blocking = blocking_condition_ids(data)
+        reason = (
+            f"condition(s) {blocking} declare `blocksReleaseHandoff: true` "
+            "(a condition with no declaration counts as blocking)"
+            if blocking
+            else f"verdict is `{token}`"
+        )
         failures.append(
             f"final-verification: routingRecommendation cites `release-handoff` "
-            f"but verdict is `{token}` — release-handoff routing is allowed only "
-            "when the verdict is `accepted`."
+            f"but {reason} — release-handoff routing needs an `accepted` verdict, "
+            "or a `conditional-accept` whose every condition declares "
+            "`blocksReleaseHandoff: false`."
         )
 
     scope = data.get("verificationScope", "whole-task")

package/runtime/validators/validate_analysis_report.py

@@ -422,11 +422,8 @@ def _validate_analysis_verdict(
     expected = "blocked" if worker_blocked or scope_blocked else (
         "analysis-partial" if partial else "analysis-complete"
     )
-    actual = {
-        str((data.get("verdictCard") or {}).get("verdictToken") or ""),
-        str((data.get("finalVerdict") or {}).get("verdictToken") or ""),
-    }
-    if actual == {expected}:
+    actual = str((data.get("finalVerdict") or {}).get("verdictToken") or "")
+    if actual == expected:
         return
     reasons = []
     if worker_blocked:

package/runtime/validators/validate_session_conformance.py

@@ -1034,7 +1034,7 @@ def _check_batch_cleanup_checkpoints(
     실제로 일어났는지 (prompts/profiles/_common-contract.md 'Phase-start cleanup').
     R1=convergence round 1 직전, R2=report-writer dispatch 직전(수렴이 있었으면
     마지막 라운드 이후 별도 1회). ISO-8601 ts 는 lexicographic 비교가 곧 시간순."""
-    detail = "prompts/profiles/_common-contract.md 'Phase-start cleanup'"
+    detail = "prompts/lead/okstra-lead-contract.md 'Run-scoped worker-resource lifecycle'"
     cleanup_ts = sorted(ts for ts, _line in by_phase.get("phase-batch-cleanup", []))
     conv_ts = sorted(ts for ts, _line in by_phase.get("phase-5.5-convergence", []))
     synth_ts = sorted(ts for ts, _line in by_phase.get("phase-6-synthesis", []))