okstra 0.172.0 → 0.174.0

package/runtime/validators/validate-run.py

@@ -43,14 +43,16 @@ from okstra_project.dirs import tasks_root as _okstra_tasks_root  # noqa: E402
 from okstra_project.resolver import resolve_architecture  # noqa: E402
 
 from okstra_ctl.conformance import (  # noqa: E402
-    CAPABILITY_WHITELIST,
     detect_surfaces,
     evaluate_conformance,
     manifest_required_surfaces,
+    normalize_conformance_script as _normalize_conformance_script,
+    parse_conformance_tests as _parse_conformance_tests,
     qa_result_from_dict,
     validate_conformance_manifest,
 )
 from okstra_ctl.paths import RunRef  # noqa: E402
+from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION  # noqa: E402
 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
@@ -71,7 +73,12 @@ from okstra_ctl.incremental_scope import (  # noqa: E402
     coverage_row_blocked_on,
     stages_for_clarification,
 )
-from okstra_ctl.workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE  # noqa: E402
+from okstra_ctl.workflow import (  # noqa: E402
+    DEFAULT_NEXT_PHASE,
+    ERROR_ANALYSIS_ROUTING_DIRECTIONS,
+    PHASE_SEQUENCE,
+    REQUIREMENTS_DISCOVERY_ROUTING_TARGETS,
+)
 from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
     split_pipe_row as _split_pipe_row,
@@ -80,9 +87,16 @@ from okstra_ctl.final_report_paths import final_report_data_path as _data_path_f
 from okstra_ctl.improvement_assignment import (  # noqa: E402
     validate_primary_lens_assignments,
 )
+from okstra_ctl.implementation_options import (  # noqa: E402
+    validate_implementation_option_selection,
+)
+from okstra_ctl.implementation_direction import (  # noqa: E402
+    validate_selected_direction_plan,
+)
 from okstra_ctl.worker_prompt_policy import GRILLING_LOG_HEADER  # noqa: E402
 from okstra_ctl.scope_provenance import (  # noqa: E402
     brief_citation_problem,
+    brief_end_state_id_sequence,
     brief_end_state_ids,
     brief_headings,
     parse_source,
@@ -129,7 +143,7 @@ from okstra_ctl.convergence_provenance import (  # noqa: E402
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
-WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed", "tmux-pane"}
+WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed"}
 _AGENT_DISPATCH_DIGEST_KEYS = (
     "catalogDigest",
     "assignmentDigest",
@@ -406,7 +420,28 @@ def _error_analysis_next_phase(data: Mapping[str, Any]) -> str | None:
     if not isinstance(routing, Mapping):
         return None
     target = routing.get("nextTaskType")
-    if target in {"error-analysis", "implementation-planning"}:
+    if target in ERROR_ANALYSIS_ROUTING_DIRECTIONS:
+        return str(target)
+    return None
+
+
+def _requirements_discovery_next_phase(data: Mapping[str, Any]) -> str | None:
+    if not isinstance(data, Mapping):
+        return None
+    header = data.get("header")
+    if (
+        not isinstance(header, Mapping)
+        or header.get("taskType") != "requirements-discovery"
+    ):
+        return None
+    requirements = data.get("requirementsDiscovery")
+    if not isinstance(requirements, Mapping):
+        return None
+    routing = requirements.get("routing")
+    if not isinstance(routing, Mapping):
+        return None
+    target = routing.get("nextTaskType")
+    if target in REQUIREMENTS_DISCOVERY_ROUTING_TARGETS:
         return str(target)
     return None
 
@@ -445,11 +480,12 @@ def update_workflow_metadata(
         # Validation just passed → actively advance to the next phase in
         # the sequence rather than preserving a stale value that may equal
         # current_phase (which would cause the lifecycle pointer to stall).
-        report_next_phase = (
-            _error_analysis_next_phase(report_data or {})
-            if current_phase == "error-analysis"
-            else None
-        )
+        if current_phase == "requirements-discovery":
+            report_next_phase = _requirements_discovery_next_phase(report_data or {})
+        elif current_phase == "error-analysis":
+            report_next_phase = _error_analysis_next_phase(report_data or {})
+        else:
+            report_next_phase = None
         next_recommended_phase = report_next_phase or advance_next_phase(
             current_phase, phase_sequence
         )
@@ -1648,35 +1684,6 @@ def _approved_plan_stage_entry(
     }
 
 
-_CONFORMANCE_TESTS_RE = re.compile(
-    r"^(?P<script>\S+)\s+\(requires=\[(?P<requires>[^\]]+)\]\)$"
-)
-
-
-def _normalize_conformance_script(script: str) -> str:
-    prefix = "<task_root>/"
-    return script[len(prefix):] if script.startswith(prefix) else script
-
-
-def _parse_conformance_tests(value: object) -> tuple[str, frozenset[str]] | None:
-    """Parse `<script> (requires=[cap,...])` from a stage declaration."""
-    if not isinstance(value, str):
-        return None
-    match = _CONFORMANCE_TESTS_RE.fullmatch(value.strip())
-    if match is None:
-        return None
-    script = _normalize_conformance_script(match.group("script"))
-    capabilities = [part.strip() for part in match.group("requires").split(",")]
-    if (
-        not script
-        or any(not capability for capability in capabilities)
-        or len(set(capabilities)) != len(capabilities)
-        or any(capability not in CAPABILITY_WHITELIST for capability in capabilities)
-    ):
-        return None
-    return script, frozenset(capabilities)
-
-
 def _approved_plan_conformance_manifest(
     approved_plan_path: Path,
     task_root: Path,
@@ -2321,7 +2328,7 @@ def _validate_selfmock(report_path: Path, failures: list[str]) -> None:
     read the flat `self-mock.json`.
 
     Only the implementation template renders the §5.7.3 diff summary
-    (`templates/reports/final-report.template.md:589`); a final-verification report
+    (`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.
@@ -2683,65 +2690,6 @@ def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
                 )
 
 
-PLANNING_REQUIRED_SECTIONS = (
-    "Option Candidates",
-    "Trade-off",
-    "Recommended Option",
-    "Stage Map",
-    "Stepwise Execution Order",
-    "Dependency",
-    "Validation Checklist",
-    "Rollback",
-    "Requirement Coverage",
-    "Plan Body Verification",
-    "Cross-Project Dependencies",
-    "Decision Drafts",
-)
-
-# §5.7 implementation deliverables — substring scan against report body.
-IMPLEMENTATION_REQUIRED_SECTIONS = (
-    "Approved Plan Reference",
-    "Commit List",
-    "Diff Summary",
-    "Out-of-plan Edits",
-    "Stage Sidecar Evidence",
-    "Validation Evidence",
-    "Verifier Results",
-    "Rollback Verification",
-    "Manual User Test (Draft)",
-    "Routing Recommendation",
-)
-
-# §5.8 final-verification deliverables — substring scan against report body.
-FINAL_VERIFICATION_REQUIRED_SECTIONS = (
-    "Source Implementation Report",
-    "Acceptance Blockers",
-    "Residual Risk",
-    "Validation Evidence",
-    "Read-only Command Log",
-    "Conditional Acceptance Conditions",
-    "Manual User Test Results",
-    "Routing Recommendation",
-    "Could-Not-Verify Roll-up",
-)
-
-# Allowed Verdict Token vocabulary, by task-type. `release-handoff` is
-# author-tagged but reads its entry gate from final-verification's report
-# and renders `not-applicable` itself.
-FINAL_VERIFICATION_VERDICT_TOKENS = (
-    "accepted",
-    "conditional-accept",
-    "blocked",
-)
-
-# `## 7. Final Verdict` Verdict Token cell — captures the value between
-# backticks on the `Verdict Token` row. Tolerant to extra column whitespace
-# and to leading bold/italic markers in the label cell.
-_FINAL_VERDICT_TOKEN_RE = re.compile(
-    r"^\|[ \t]*\*{0,2}Verdict Token\*{0,2}[ \t]*\|[ \t]*`(?P<value>[^`\n]*)`",
-    re.MULTILINE,
-)
-
 # Verdict Card Verdict Token row (top-of-report at-a-glance). Same shape
 # as `_FINAL_VERDICT_TOKEN_RE` but matched against the first occurrence in
 # the Verdict Card block, scoped to the body between `## Verdict Card`
@@ -2752,23 +2700,6 @@ _VERDICT_CARD_BLOCK_RE = re.compile(
     re.DOTALL | re.MULTILINE,
 )
 
-# `## 7. Final Verdict` block scope — used to scope the Verdict Token
-# regex so that we don't accidentally match a Verdict Token row that
-# lives in the Verdict Card or anywhere else.
-_FINAL_VERDICT_BLOCK_RE = re.compile(
-    r"^##[ \t]+7\.[ \t]+Final Verdict" + _HEADING_TAIL
-    + r"\n(?P<body>.*?)(?=^##[ \t]|\Z)",
-    re.DOTALL | re.MULTILINE,
-)
-
-# `## 5.6 Release Handoff Deliverables` and `## 5.6.6 Merge Conflict
-# Probe` are required when task-type == release-handoff. The probe sub-
-# section was retro-added to the template; old runs that predate it ship
-# without it, but new runs must include it.
-_MERGE_CONFLICT_PROBE_HEADING_RE = re.compile(
-    r"^###[ \t]+5\.6\.6[ \t]+Merge Conflict Probe\b", re.MULTILINE
-)
-
 PLAN_VERIFY_GATE_VALUES = (
     "passed",
     "passed-with-dissent",
@@ -2776,207 +2707,10 @@ PLAN_VERIFY_GATE_VALUES = (
     "aborted-non-result",
 )
 
-# `Gate result:` line in §5.5.9 of the final report — captures the value
-# token that follows. Tolerates arbitrary markdown formatting between the
-# label and the value (backticks for inline code, double-asterisks for
-# bold, colons, hyphens, whitespace). The captured value is then
-# validated against `PLAN_VERIFY_GATE_VALUES` below so typo'd or unknown
-# values surface as their own failure rather than silently no-matching.
-_GATE_RESULT_RE = re.compile(
-    r"Gate result[^A-Za-z\n]+(?P<value>[a-z][a-z\-]+)",
-    re.IGNORECASE,
-)
-
-# §5.5.9 Plan Body Verification section body — scopes the gate-result search
-# so an earlier prose mention of "Gate result" elsewhere in the report cannot
-# hijack the authoritative value. Matched from the `Plan Body Verification`
-# heading to the next heading (or end-of-file).
-_PLAN_BODY_VERIFICATION_BLOCK_RE = re.compile(
-    r"^#{2,}[ \t][^\n]*\bPlan Body Verification\b[^\n]*\n"
-    r"(?P<body>.*?)(?=^#{2,}[ \t]|\Z)",
-    re.DOTALL | re.MULTILINE,
-)
-
-# Frontmatter approval flag — `approved: true|false` line inside the
-# leading `---` YAML block. Mirrors `APPROVED_FRONTMATTER_PATTERN` in
-# scripts/okstra_ctl/run.py.
-_APPROVED_FRONTMATTER_RE = re.compile(
-    r"^approved:[ \t]+(true|false)[ \t]*$",
-    re.IGNORECASE | re.MULTILINE,
-)
 # Tolerate a leading UTF-8 BOM and/or blank lines before the opening `---`
 # so a hand-edited or differently-rendered report does not silently bypass
 # the approved-frontmatter gate (the `.match` would otherwise return None).
 _FRONTMATTER_BLOCK_RE = re.compile(r"\A\ufeff?\s*---\n(.*?)\n---\n", re.DOTALL)
-_REQUIREMENT_COVERAGE_HEADING_RE = re.compile(
-    r"^###[ \t]+(?:5\.5\.8[ \t]+)?Requirement Coverage\b",
-    re.IGNORECASE | re.MULTILINE,
-)
-_NEXT_THIRD_LEVEL_HEADING_RE = re.compile(r"^###[ \t]+", re.MULTILINE)
-
-
-def _extract_final_verdict_token(content: str) -> str | None:
-    """Return the `Verdict Token` cell value from the `## 7. Final Verdict`
-    block, or None when the row is absent. Scoped to §7 so the Verdict
-    Card row (which has the same shape) does not shadow the authoritative
-    value.
-    """
-    block = _FINAL_VERDICT_BLOCK_RE.search(content)
-    if block is None:
-        return None
-    match = _FINAL_VERDICT_TOKEN_RE.search(block.group("body"))
-    if match is None:
-        return None
-    return match.group("value")
-
-
-# 렌더러는 ID 정의 셀(`<a id="r-001"></a>R-001`)에도 스크롤 앵커를 넣는다.
-# 셀 정규화 때 그 빈 앵커를 벗겨야 ID 컬럼이 bare 토큰으로 읽힌다
-# (clarification_items._CELL_ANCHOR_RE 와 동형).
-_CELL_ANCHOR_RE = re.compile(r'<a id="[^"]*"></a>')
-
-
-def _split_markdown_row(line: str) -> list[str]:
-    return [
-        _CELL_ANCHOR_RE.sub("", cell).strip().strip("`").strip()
-        for cell in _split_pipe_row(line)
-    ]
-
-
-def _append_requirement_coverage_failures(
-    content: str,
-    gate_value: str,
-    failures: list[str],
-) -> None:
-    """Validate implementation-planning §5.5.8 requirement coverage.
-
-    The table is intentionally lightweight: it cannot prove semantic truth, but
-    it makes requirement-to-plan mapping explicit and blocks publishable plans
-    that admit uncovered requirements.
-    """
-    heading = _REQUIREMENT_COVERAGE_HEADING_RE.search(content)
-    if heading is None:
-        failures.append(
-            "implementation-planning report is missing `Requirement Coverage` "
-            "section — every task-brief requirement must map to option/stage/step."
-        )
-        return
-
-    rest = content[heading.end():]
-    next_heading = _NEXT_THIRD_LEVEL_HEADING_RE.search(rest)
-    section = rest[: next_heading.start()] if next_heading else rest
-    lines = section.splitlines()
-
-    header_idx = -1
-    headers: list[str] = []
-    for idx, line in enumerate(lines):
-        if not line.lstrip().startswith("|"):
-            continue
-        cells = [c.lower() for c in _split_markdown_row(line)]
-        if "id" in cells and "requirement" in cells and "status" in cells:
-            header_idx = idx
-            headers = cells
-            break
-    if header_idx < 0:
-        failures.append(
-            "implementation-planning Requirement Coverage section has no table "
-            "with `ID`, `Requirement`, and `Status` columns."
-        )
-        return
-
-    id_col = headers.index("id")
-    status_col = headers.index("status")
-    rows: list[tuple[str, str]] = []
-    body_started = False
-    for line in lines[header_idx + 1:]:
-        if not line.lstrip().startswith("|"):
-            if body_started:
-                break
-            continue
-        if _is_markdown_separator(line):
-            body_started = True
-            continue
-        if not body_started:
-            continue
-        cells = _split_markdown_row(line)
-        if max(id_col, status_col) >= len(cells):
-            failures.append(
-                "implementation-planning Requirement Coverage table has a "
-                f"malformed row: `{line.strip()}`"
-            )
-            continue
-        rows.append((cells[id_col], cells[status_col].lower()))
-
-    if not rows:
-        failures.append(
-            "implementation-planning Requirement Coverage table has no data rows."
-        )
-        return
-
-    for row_id, status in rows:
-        # `status` is already lower-cased at parse time, so the blocker form
-        # arrives as `blocked c-001`; match lower-case here even though the
-        # canonical authored form (and the remedy message) is `blocked C-NNN`.
-        if not re.fullmatch(
-            r"covered|gap|blocked c-\d{3,}|"
-            r"documented-deviation — refs: (?:c-\d{3,}|d-\d{4,})"
-            r"(?:, (?:c-\d{3,}|d-\d{4,}))*; approval: "
-            r"(?:accepted|blocked c-\d{3,})",
-            status,
-        ):
-            failures.append(
-                "implementation-planning Requirement Coverage row "
-                f"`{row_id}` has invalid Status `{status}`; expected "
-                "`covered`, `gap`, `blocked C-NNN`, or a rendered "
-                "`documented-deviation` disposition."
-            )
-
-    if gate_value in ("passed", "passed-with-dissent"):
-        uncovered = [
-            f"{row_id} ({status})"
-            for row_id, status in rows
-            if status != "covered"
-            and not status.endswith("; approval: accepted")
-        ]
-        if uncovered:
-            failures.append(
-                "implementation-planning Gate result is publishable but "
-                "Requirement Coverage has uncovered row(s): "
-                + ", ".join(uncovered)
-            )
-def _extract_verdict_card_token(content: str) -> str | None:
-    """Return the `Verdict Token` cell from the Verdict Card block."""
-    block = _VERDICT_CARD_BLOCK_RE.search(content)
-    if block is None:
-        return None
-    match = _FINAL_VERDICT_TOKEN_RE.search(block.group("body"))
-    if match is None:
-        return None
-    return match.group("value")
-
-
-def _validate_verdict_card_consistency(content: str, failures: list[str]) -> None:
-    """Verdict Card is a non-authoritative index of §7. If both blocks
-    carry a Verdict Token row, the values MUST byte-match (modulo case
-    and surrounding whitespace) — divergence is a contract violation per
-    `report-writer` SKILL.md "Authoring Contract".
-    """
-    card_value = _extract_verdict_card_token(content)
-    final_value = _extract_final_verdict_token(content)
-    if card_value is None or final_value is None:
-        # Missing-Card and missing-§7 are surfaced by other checks; this
-        # function only enforces the consistency contract between the two.
-        return
-    if card_value.strip().lower() != final_value.strip().lower():
-        failures.append(
-            "Verdict Card `Verdict Token` value "
-            f"`{card_value}` does not match `## 7. Final Verdict` value "
-            f"`{final_value}` — the Card is a non-authoritative index and "
-            "MUST byte-match §7. Either fix the Card or update §7; do not "
-            "ship divergent values."
-        )
-
-
 def _validate_verdict_card_fields(data: dict, failures: list[str]) -> None:
     """`verdictCard.direction` must byte-match its authoritative home in §7.
 
@@ -3142,10 +2876,15 @@ def _validate_error_analysis_consistency(
     target = routing.get("nextTaskType")
     leading_cause_id = routing.get("leadingCauseId")
     candidate_id_set = set(candidate_ids)
-    if target == "implementation-planning":
+    if isinstance(target, str) and target not in ERROR_ANALYSIS_ROUTING_DIRECTIONS:
+        failures.append(
+            "final-report data.json: errorAnalysis.routing has unsupported "
+            f"routing target `{target}`."
+        )
+    if target == "implementation-option-selection":
         if not candidates:
             failures.append(
-                "final-report data.json: implementation-planning routing requires "
+                "final-report data.json: implementation-option-selection routing requires "
                 "at least one cause candidate."
             )
         if (
@@ -3153,7 +2892,7 @@ def _validate_error_analysis_consistency(
             or leading_cause_id not in candidate_id_set
         ):
             failures.append(
-                "final-report data.json: implementation-planning routing "
+                "final-report data.json: implementation-option-selection routing "
                 "leadingCauseId must reference a cause candidate."
             )
     elif target == "error-analysis" and (
@@ -3165,10 +2904,7 @@ def _validate_error_analysis_consistency(
             "empty or reference a cause candidate."
         )
 
-    expected_direction = {
-        "implementation-planning": "begin-planning",
-        "error-analysis": "continue-investigation",
-    }.get(target)
+    expected_direction = ERROR_ANALYSIS_ROUTING_DIRECTIONS.get(target)
     verdict_card_value = data.get("verdictCard")
     verdict_card = (
         verdict_card_value if isinstance(verdict_card_value, Mapping) else {}
@@ -3230,7 +2966,7 @@ def _validate_error_analysis_consistency(
 
     if isinstance(target, str) and target in {
         "error-analysis",
-        "implementation-planning",
+        "implementation-option-selection",
     }:
         for field_name, value in (
             ("verdictCard.nextStep", verdict_card.get("nextStep")),
@@ -3301,9 +3037,8 @@ def validate_final_report_data(
     The data.json is the source-of-truth that the renderer reads to
     produce the markdown. If schema validation passes here, the rendered
     markdown is guaranteed to contain every section / row the contract
-    requires (the template loops over the data). The downstream
-    substring checks in ``validate_phase_boundary`` are kept as a safety
-    net but are expected to be redundant.
+    requires (the template loops over the data), so the schema is the
+    only place the deliverable contract is enforced.
 
     Missing data.json is reported as a single failure rather than a
     cascade of substring failures — that points the writer at the right
@@ -3373,7 +3108,25 @@ def validate_final_report_data(
 
     task_type = (data.get("header") or {}).get("taskType")
     _validate_verifier_fail_blocks_verdict(data, failures)
-    if task_type == "implementation":
+    if task_type == "implementation-option-selection":
+        selection = data.get("implementationOptionSelection") or {}
+        validation_root = project_root or report_path.parent
+        original_ids = brief_end_state_id_sequence(
+            _brief_path_from_manifest(manifest, validation_root)
+        )
+        roster = manifest.get("recommendedWorkers") or ()
+        participating_analysers = tuple(
+            worker for worker in roster if worker != "report-writer"
+        )
+        failures.extend(
+            f"implementation-option-selection: {error}"
+            for error in validate_implementation_option_selection(
+                selection,
+                original_ids,
+                participating_analysers,
+            )
+        )
+    elif task_type == "implementation":
         _validate_stage_carry_sidecar_exists(data, report_path, failures)
     if task_type == "error-analysis":
         _validate_error_analysis_consistency(data, failures)
@@ -3382,6 +3135,31 @@ def validate_final_report_data(
         _validate_verified_row_recorded(data, report_path, failures)
     elif task_type == "implementation-planning":
         active_report_contracts = report_contracts or set()
+        planning = data.get("implementationPlanning") or {}
+        selected_direction_contract = (
+            isinstance(planning, Mapping)
+            and planning.get("planningContract") == "selected-direction"
+        )
+        if selected_direction_contract:
+            validation_root = project_root or report_path.parent
+            try:
+                brief_path = _brief_path_from_manifest(manifest, validation_root)
+            except (OSError, ValueError) as exc:
+                failures.append(
+                    "implementation-planning selected-direction: run manifest "
+                    f"taskBriefPath is malformed: {exc}"
+                )
+                brief_path = validation_root / "__invalid-brief__"
+            task_root = _task_root_from_run_dir(report_path.parent.parent)
+            snapshot_path = task_root / "instruction-set" / "selected-direction.json"
+            failures.extend(
+                f"implementation-planning selected-direction: {error}"
+                for error in validate_selected_direction_plan(
+                    data, brief_path, snapshot_path
+                )
+            )
+            if planning.get("outcome") == "direction-invalidated":
+                return data
         _validate_implementation_planning_cross_project(data, failures)
         _validate_implementation_planning_decision_drafts(data, failures)
         for warning in validate_plan_body_section(data, report_path, failures):
@@ -3401,8 +3179,9 @@ def validate_final_report_data(
             resolve_architecture(_project_root_from_report(report_path)),
             failures,
         )
-        _validate_requirement_deviations(data, failures)
-        _validate_requirement_coverage_covered_by(data, failures)
+        if not selected_direction_contract:
+            _validate_requirement_deviations(data, failures)
+            _validate_requirement_coverage_covered_by(data, failures)
         warnings = _validate_design_prep_contract(
             data,
             report_path,
@@ -7314,7 +7093,7 @@ def _validate_unverified_critic_gaps_recorded(data: dict, failures: list[str]) -
 
 
 # Allowed `fixability` values, mirroring the schema enum
-# (schemas/final-report-v1.0.schema.json planItems[].verdicts[].fixability).
+# (schemas/final-report-v2.0.schema.json planItems[].verdicts[].fixability).
 _FIXABILITY_VALUES = frozenset({"planner-fixable", "needs-user-input"})
 
 
@@ -7803,6 +7582,13 @@ def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
         )
 
 
+_FINAL_VERIFICATION_ROUTING_TOKEN_RE = re.compile(
+    r"(?<![A-Za-z-])(?:release-handoff\(stage-group\)|release-handoff|done|"
+    r"implementation|error-analysis|implementation-option-selection|"
+    r"implementation-planning)(?![A-Za-z-])"
+)
+
+
 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;
@@ -7817,7 +7603,16 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
     fv = data.get("finalVerification") or {}
     blockers = fv.get("acceptanceBlockers") or []
     conditions = verdict.get("conditionalAcceptanceConditions") or []
-    routing = fv.get("routingRecommendation") or ""
+    routing_value = fv.get("routingRecommendation")
+    routing = routing_value if isinstance(routing_value, str) else ""
+    routing_tokens = _FINAL_VERIFICATION_ROUTING_TOKEN_RE.findall(routing)
+    routing_token = routing_tokens[0] if len(routing_tokens) == 1 else None
+
+    if routing_token is None:
+        failures.append(
+            "final-verification: routingRecommendation must contain exactly one "
+            "supported routing token."
+        )
 
     if token == "accepted" and blockers:
         failures.append(
@@ -7834,7 +7629,10 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "final-verification: verdict `conditional-accept` but "
             "conditionalAcceptanceConditions is empty — list every condition."
         )
-    if "release-handoff" in routing and token != "accepted":
+    if (
+        routing_token in {"release-handoff", "release-handoff(stage-group)"}
+        and token != "accepted"
+    ):
         failures.append(
             f"final-verification: routingRecommendation cites `release-handoff` "
             f"but verdict is `{token}` — release-handoff routing is allowed only "
@@ -7847,8 +7645,7 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             f"final-verification: verificationScope must be `whole-task` or "
             f"`single-stage`, got {scope!r}."
         )
-    if (scope == "single-stage" and "release-handoff" in routing
-            and "release-handoff(stage-group)" not in routing):
+    if scope == "single-stage" and routing_token == "release-handoff":
         failures.append(
             "final-verification: verificationScope `single-stage` cannot recommend "
             "plain release-handoff routing — a single-stage accepted verdict may "
@@ -7917,14 +7714,13 @@ def _load_stage_validator():
 def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) -> None:
     """Run the stage relationship checks that schema v2 cannot express.
 
-    `_append_stage_structure_failures` scans rendered Markdown and sits after
-    the v2 early return in `validate_phase_boundary`, so for a v2 report the
-    depends-on DAG, parallel-stage file safety, RED→GREEN ordering, and the
-    TDD-exemption vocabulary had nothing enforcing them. The same validator
-    owns both modes so the rule vocabulary stays defined once.
+    The depends-on DAG, parallel-stage file safety, RED→GREEN ordering, and
+    the TDD-exemption vocabulary are relationships between stages, which a
+    JSON Schema cannot state. They are enforced here, against the data.json,
+    by the same validator that owns the rule vocabulary.
     """
-    if (data or {}).get("schemaVersion") != "2.0":
-        return  # v1 reports are covered by the Markdown scan.
+    if (data or {}).get("schemaVersion") != CURRENT_REPORT_SCHEMA_VERSION:
+        return  # Schema validation already rejected an unknown version.
     planning = (data or {}).get("implementationPlanning")
     if not isinstance(planning, Mapping):
         return  # Schema validation already reported the missing block.
@@ -7939,157 +7735,6 @@ def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) ->
         )
 
 
-def _append_stage_structure_failures(content: str, failures: list[str]) -> None:
-    """Enforce the Stage Map structural contract at the implementation-planning
-    boundary. Without this, a plan missing `## 5.5 Stage Map` passes the
-    planning gate, gets approved, and only fails later at the `implementation`
-    entry (validators/validate-implementation-plan-stages.py via
-    prepare_task_bundle). Running the same validator here moves the failure to
-    produce-time."""
-    mod = _load_stage_validator()
-    if mod is None:  # pragma: no cover — repo/runtime always ship the file
-        failures.append(f"cannot load Stage Map validator at {_STAGE_VALIDATOR_PATH}")
-        return
-    for e in mod.collect_validation_errors(content):
-        failures.append(
-            f"implementation-planning Stage Map structure invalid "
-            f"[{e.code} stage={e.stage}]: {e.message}"
-        )
-
-
-def validate_phase_boundary(
-    task_type: str,
-    report_path: Path,
-    failures: list[str],
-    *,
-    report_data: Mapping[str, Any] | None = None,
-) -> None:
-    """Phase-specific contract checks.
-
-    For `implementation-planning` runs, the final report must contain the
-    required deliverable sections; absence indicates a planning run that
-    skipped its core outputs (or an implementation run that ran under the
-    wrong task type).
-
-    Additionally enforces the Plan Body Verification gate (§5.5.9):
-    - gate ∈ {passed, passed-with-dissent} → top-level Approval checkbox
-      MUST be present.
-    - gate ∈ {blocked-by-disagreement, aborted-non-result} → checkbox
-      MUST be absent (lead converted findings into Clarification rows
-      instead of opening the gate).
-    """
-    if (report_data or {}).get("schemaVersion") == "2.0":
-        return
-    if not report_path.exists():
-        return
-    content = report_path.read_text()
-
-    # Verdict Card vs §7. Final Verdict Verdict Token consistency. The Card
-    # is a non-authoritative index; divergence is a contract violation.
-    _validate_verdict_card_consistency(content, failures)
-
-    if task_type == "implementation":
-        for needle in IMPLEMENTATION_REQUIRED_SECTIONS:
-            if needle not in content:
-                failures.append(
-                    "implementation report is missing required §5.7 "
-                    f"deliverable section: `{needle}`"
-                )
-
-    if task_type == "final-verification":
-        for needle in FINAL_VERIFICATION_REQUIRED_SECTIONS:
-            if needle not in content:
-                failures.append(
-                    "final-verification report is missing required §5.8 "
-                    f"deliverable section: `{needle}`"
-                )
-        token_value = _extract_final_verdict_token(content)
-        if token_value is None:
-            failures.append(
-                "final-verification report `## 7. Final Verdict` table is "
-                "missing the `Verdict Token` row — required by the release-"
-                "handoff entry gate."
-            )
-        elif token_value.strip().lower() not in FINAL_VERIFICATION_VERDICT_TOKENS:
-            failures.append(
-                "final-verification report `Verdict Token` value "
-                f"`{token_value}` is not one of "
-                f"{', '.join(FINAL_VERIFICATION_VERDICT_TOKENS)}."
-            )
-
-    if task_type == "release-handoff":
-        if _MERGE_CONFLICT_PROBE_HEADING_RE.search(content) is None:
-            failures.append(
-                "release-handoff report is missing `### 5.6.6 Merge Conflict "
-                "Probe` sub-section — required by the release-handoff profile "
-                "(self-review 6, merge-conflict probe audit). When the run is "
-                "`local checkout` / `skip`, record the single line `- Not run "
-                "(user picked local checkout or skip).` under the heading."
-            )
-
-    if task_type != "implementation-planning":
-        return
-    for needle in PLANNING_REQUIRED_SECTIONS:
-        if needle not in content:
-            failures.append(
-                "implementation-planning report is missing required section: "
-                f"`{needle}`"
-            )
-
-    # Scope the gate-result search to the §5.5.9 Plan Body Verification block
-    # so an earlier prose mention of "Gate result" cannot hijack the value.
-    pbv_block = _PLAN_BODY_VERIFICATION_BLOCK_RE.search(content)
-    gate_match = (
-        _GATE_RESULT_RE.search(pbv_block.group("body")) if pbv_block else None
-    )
-    if gate_match is None:
-        # The `Plan Body Verification` heading check above already covers
-        # the wholly-missing case; a heading present without a `Gate result`
-        # line is its own contract violation.
-        if "Plan Body Verification" in content:
-            failures.append(
-                "implementation-planning report has `Plan Body Verification` "
-                "section but no `Gate result:` line — required by §5.5.9."
-            )
-        return
-    gate_value = gate_match.group("value").strip().lower()
-    if gate_value not in PLAN_VERIFY_GATE_VALUES:
-        failures.append(
-            "implementation-planning report `Gate result` value "
-            f"`{gate_value}` is not one of "
-            f"{', '.join(PLAN_VERIFY_GATE_VALUES)}."
-        )
-        return
-    fm_block = _FRONTMATTER_BLOCK_RE.match(content)
-    fm_match = (
-        _APPROVED_FRONTMATTER_RE.search(fm_block.group(1)) if fm_block else None
-    )
-    if gate_value in ("passed", "passed-with-dissent") and fm_match is None:
-        failures.append(
-            "implementation-planning report Gate result is "
-            f"`{gate_value}` but the frontmatter `approved:` field is missing — "
-            "render `approved: false` so the user (or `--approve`) can flip it."
-        )
-    if (
-        gate_value in ("blocked-by-disagreement", "aborted-non-result")
-        and fm_match is not None
-        and fm_match.group(1).lower() == "true"
-    ):
-        failures.append(
-            "implementation-planning report Gate result is "
-            f"`{gate_value}` but the frontmatter has `approved: true` — gate "
-            "must NOT publish a pre-approved plan when verification did not pass."
-        )
-
-    _append_requirement_coverage_failures(content, gate_value, failures)
-
-    # Only a publishable plan (gate passed) can be flipped to `approved: true`
-    # and reach the `implementation` entry, so the Stage Map structure is
-    # enforced only here — a blocked/aborted plan may legitimately be incomplete.
-    if gate_value in ("passed", "passed-with-dissent"):
-        _append_stage_structure_failures(content, failures)
-
-
 def _brief_path_from_manifest(task_manifest: dict, project_root: Path) -> Path:
     """This run's brief, or a non-existent path when the manifest names none.
 
@@ -9092,12 +8737,6 @@ def main() -> int:
     )
     validate_team_state_usage(team_state, failures)
 
-    validate_phase_boundary(
-        task_type,
-        report_path,
-        failures,
-        report_data=validation_data,
-    )
     _validate_phase_boundary_error_log(
         report_path.parent.parent,
         task_type,
@@ -9144,16 +8783,28 @@ def main() -> int:
         for warning in conformance_warnings:
             print(f"validate-run: warning: {warning}", file=sys.stderr)
     if task_type in _BRIEF_DERIVED_PHASES:
-        brief_path = _brief_path_from_manifest(task_manifest, project_root)
+        planning = validation_data.get("implementationPlanning")
+        selected_direction_plan = (
+            task_type == "implementation-planning"
+            and isinstance(planning, Mapping)
+            and planning.get("planningContract") == "selected-direction"
+        )
+        brief_path = (
+            project_root / "__selected-direction-brief-validated-from-run-manifest__"
+            if selected_direction_plan
+            else _brief_path_from_manifest(task_manifest, project_root)
+        )
         if task_type in _END_STATE_PHASES:
             if task_type == "implementation-planning":
                 _validate_planning_conformance_declared(report_path, failures)
-            _validate_end_state_coverage(validation_data, brief_path, failures)
-            if task_type == "implementation-planning":
+            if not selected_direction_plan:
+                _validate_end_state_coverage(validation_data, brief_path, failures)
+            if task_type == "implementation-planning" and not selected_direction_plan:
                 _validate_requirement_provenance(
                     validation_data, brief_path, failures
                 )
                 _validate_stage_has_requirement(validation_data, failures)
+            if task_type == "implementation-planning":
                 _append_stage_data_failures(validation_data, failures)
         if task_type == "improvement-discovery":
             run_dir = report_path.parent.parent