okstra 0.141.3 → 0.143.0

package/runtime/validators/validate-run.py

@@ -8,9 +8,12 @@ import importlib.util
 import json
 import os
 import re
+import shlex
 import sys
+from collections.abc import Mapping
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
 
 # Make the okstra packages importable however this validator is reached:
 # ``scripts/`` next to the repo checkout, ``python/`` next to the installed
@@ -34,6 +37,7 @@ except ImportError:  # pragma: no cover — runtime guarantees this import
 
 from okstra_project import project_json_path  # noqa: E402
 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,
@@ -187,10 +191,29 @@ def advance_next_phase(
     return default_next_phase(current_phase)
 
 
+def _error_analysis_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") != "error-analysis":
+        return None
+    error_analysis = data.get("errorAnalysis")
+    if not isinstance(error_analysis, Mapping):
+        return None
+    routing = error_analysis.get("routing")
+    if not isinstance(routing, Mapping):
+        return None
+    target = routing.get("nextTaskType")
+    if target in {"error-analysis", "implementation-planning"}:
+        return str(target)
+    return None
+
+
 def update_workflow_metadata(
     run_manifest: dict,
     task_manifest: dict,
     validation_status: str,
+    report_data: Mapping[str, Any] | None = None,
 ) -> None:
     workflow = task_manifest.get("workflow", {})
     if not isinstance(workflow, dict):
@@ -220,7 +243,14 @@ 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).
-        next_recommended_phase = advance_next_phase(current_phase, phase_sequence)
+        report_next_phase = (
+            _error_analysis_next_phase(report_data or {})
+            if current_phase == "error-analysis"
+            else None
+        )
+        next_recommended_phase = report_next_phase or advance_next_phase(
+            current_phase, phase_sequence
+        )
     else:
         current_phase_state = "blocked"
         if current_phase:
@@ -321,6 +351,7 @@ def update_validation_metadata(
     task_manifest: dict,
     validation_status: str,
     failures: list[str],
+    report_data: Mapping[str, Any] | None = None,
 ) -> None:
     checked_at = utc_now()
 
@@ -349,7 +380,12 @@ def update_validation_metadata(
     task_manifest["currentStatus"] = (
         "completed" if validation_status == "passed" else "contract-violated"
     )
-    update_workflow_metadata(run_manifest, task_manifest, validation_status)
+    update_workflow_metadata(
+        run_manifest,
+        task_manifest,
+        validation_status,
+        report_data=report_data,
+    )
 
 
 def extract_contract(
@@ -1644,7 +1680,10 @@ def _validate_conformance(
 
 
 def _check_incremental_audit_block(
-    report_path: Path, content: str, failures: list[str]
+    report_path: Path,
+    content: str,
+    failures: list[str],
+    report_data: Mapping[str, Any] | None = None,
 ) -> None:
     """Enforce the Section 0 incremental audit block.
 
@@ -1656,7 +1695,11 @@ def _check_incremental_audit_block(
     decision are exempt, so this never conflicts with the empty-Section-0
     stub rule (that fires only when NO carry-in was provided at all).
     """
-    data = _load_final_report_data(report_path)
+    data = (
+        report_data
+        if report_data is not None
+        else _load_final_report_data(report_path)
+    )
     planning = data.get("implementationPlanning")
     if not isinstance(planning, dict):
         return
@@ -1688,6 +1731,7 @@ def validate_report(
     *,
     allow_unavailable_token_usage: bool = False,
     unavailable_ok_labels: frozenset[str] = frozenset(),
+    report_data: Mapping[str, Any] | None = None,
 ) -> None:
     if not report_path.exists():
         failures.append(f"final report is missing: {report_path}")
@@ -1778,7 +1822,12 @@ def validate_report(
 
     # Incremental audit block — an `incremental`-mode re-run must expose its
     # scope decision in Section 0 so the narrowed re-verification is auditable.
-    _check_incremental_audit_block(report_path, content, failures)
+    _check_incremental_audit_block(
+        report_path,
+        content,
+        failures,
+        report_data=report_data,
+    )
 
     # Deprecated section headings — pre-1.0 hard removal.
     for pattern, remedy in _DEPRECATED_FINAL_REPORT_PATTERNS:
@@ -2239,6 +2288,213 @@ def _validate_verdict_card_fields(data: dict, failures: list[str]) -> None:
     )
 
 
+def _route_target_matches(value: Any, target: str, *, command: bool) -> bool:
+    if not isinstance(value, str):
+        return False
+    if not command:
+        pattern = rf"(?<![\w-]){re.escape(target)}(?![\w-])"
+        return re.search(pattern, value) is not None
+    try:
+        tokens = shlex.split(value)
+    except ValueError:
+        return False
+    task_type_values: list[str] = []
+    for index, token in enumerate(tokens):
+        if token in {"task-type", "--task-type"}:
+            task_type_values.append(
+                tokens[index + 1] if index + 1 < len(tokens) else ""
+            )
+        for prefix in ("task-type=", "--task-type="):
+            if token.startswith(prefix):
+                task_type_values.append(token[len(prefix):])
+    return bool(task_type_values) and all(
+        task_type_value == target for task_type_value in task_type_values
+    )
+
+
+def _validate_error_analysis_consistency(
+    data: Mapping[str, Any], failures: list[str]
+) -> None:
+    error_analysis_value = data.get("errorAnalysis")
+    error_analysis = (
+        error_analysis_value if isinstance(error_analysis_value, Mapping) else {}
+    )
+    reproduction_value = error_analysis.get("reproduction")
+    reproduction = (
+        reproduction_value if isinstance(reproduction_value, Mapping) else {}
+    )
+    reproduction_status = reproduction.get("status")
+    blocked_reason = reproduction.get("blockedReason")
+    if reproduction_status == "blocked-before-repro":
+        if not isinstance(blocked_reason, str) or not blocked_reason.strip():
+            failures.append(
+                "final-report data.json: blocked-before-repro requires a non-empty "
+                "errorAnalysis.reproduction.blockedReason."
+            )
+    elif blocked_reason != "":
+        failures.append(
+            "final-report data.json: errorAnalysis.reproduction.blockedReason "
+            "must be exactly empty unless status is blocked-before-repro."
+        )
+
+    candidates_value = error_analysis.get("causeCandidates")
+    candidates = candidates_value if isinstance(candidates_value, list) else []
+    candidate_ids: list[str] = []
+    for candidate in candidates:
+        if not isinstance(candidate, Mapping):
+            continue
+        candidate_id = candidate.get("id")
+        if isinstance(candidate_id, str):
+            candidate_ids.append(candidate_id)
+    duplicate_ids = sorted(
+        candidate_id
+        for candidate_id in set(candidate_ids)
+        if candidate_ids.count(candidate_id) > 1
+    )
+    if duplicate_ids:
+        failures.append(
+            "final-report data.json: duplicate cause candidate id(s): "
+            + ", ".join(duplicate_ids)
+            + "."
+        )
+
+    routing_value = error_analysis.get("routing")
+    routing = routing_value if isinstance(routing_value, Mapping) else {}
+    target = routing.get("nextTaskType")
+    leading_cause_id = routing.get("leadingCauseId")
+    candidate_id_set = set(candidate_ids)
+    if target == "implementation-planning":
+        if not candidates:
+            failures.append(
+                "final-report data.json: implementation-planning routing requires "
+                "at least one cause candidate."
+            )
+        if (
+            not isinstance(leading_cause_id, str)
+            or leading_cause_id not in candidate_id_set
+        ):
+            failures.append(
+                "final-report data.json: implementation-planning routing "
+                "leadingCauseId must reference a cause candidate."
+            )
+    elif target == "error-analysis" and (
+        not isinstance(leading_cause_id, str)
+        or (leading_cause_id != "" and leading_cause_id not in candidate_id_set)
+    ):
+        failures.append(
+            "final-report data.json: error-analysis routing leadingCauseId must be "
+            "empty or reference a cause candidate."
+        )
+
+    expected_direction = {
+        "implementation-planning": "begin-planning",
+        "error-analysis": "continue-investigation",
+    }.get(target)
+    verdict_card_value = data.get("verdictCard")
+    verdict_card = (
+        verdict_card_value if isinstance(verdict_card_value, Mapping) else {}
+    )
+    final_verdict_value = data.get("finalVerdict")
+    final_verdict = (
+        final_verdict_value if isinstance(final_verdict_value, Mapping) else {}
+    )
+    if expected_direction:
+        for field_name, verdict in (
+            ("verdictCard", verdict_card),
+            ("finalVerdict", final_verdict),
+        ):
+            if verdict.get("direction") != expected_direction:
+                failures.append(
+                    f"final-report data.json: {field_name}.direction must be "
+                    f"`{expected_direction}` for `{target}` routing."
+                )
+
+    follow_up_tasks_value = data.get("followUpTasks")
+    follow_up_tasks = (
+        follow_up_tasks_value if isinstance(follow_up_tasks_value, list) else []
+    )
+    continuations = [
+        row
+        for row in follow_up_tasks
+        if isinstance(row, Mapping) and row.get("origin") == "phase-continuation"
+    ]
+    if len(continuations) != 1:
+        failures.append(
+            "final-report data.json: followUpTasks must contain exactly one "
+            "phase-continuation row."
+        )
+    else:
+        continuation = continuations[0]
+        frontmatter_value = data.get("frontmatter")
+        frontmatter = (
+            frontmatter_value if isinstance(frontmatter_value, Mapping) else {}
+        )
+        task_id = frontmatter.get("taskId")
+        if continuation.get("suggestedTaskType") != target:
+            failures.append(
+                "final-report data.json: phase-continuation suggestedTaskType "
+                "must match the routing target."
+            )
+        if continuation.get("newTaskId") != task_id:
+            failures.append(
+                "final-report data.json: phase-continuation newTaskId must match "
+                "frontmatter.taskId."
+            )
+        if continuation.get("priority") != "P0":
+            failures.append(
+                "final-report data.json: phase-continuation priority must be P0."
+            )
+        if continuation.get("autoSpawn") != "no":
+            failures.append(
+                "final-report data.json: phase-continuation autoSpawn must be no."
+            )
+
+    if isinstance(target, str) and target in {
+        "error-analysis",
+        "implementation-planning",
+    }:
+        for field_name, value in (
+            ("verdictCard.nextStep", verdict_card.get("nextStep")),
+            ("finalVerdict.nextStep", final_verdict.get("nextStep")),
+        ):
+            if not _route_target_matches(value, target, command=False):
+                failures.append(
+                    f"final-report data.json: {field_name} must contain routing "
+                    f"target `{target}`."
+                )
+
+        next_steps_value = data.get("recommendedNextSteps")
+        next_steps = next_steps_value if isinstance(next_steps_value, list) else []
+        first_step = (
+            next_steps[0]
+            if next_steps and isinstance(next_steps[0], Mapping)
+            else {}
+        )
+        step_text = first_step.get("text")
+        if not _route_target_matches(step_text, target, command=False):
+            failures.append(
+                "final-report data.json: recommendedNextSteps[0].text must contain "
+                f"routing target `{target}`."
+            )
+        commands_value = first_step.get("commands")
+        commands = commands_value if isinstance(commands_value, list) else []
+        if not commands:
+            failures.append(
+                "final-report data.json: recommendedNextSteps[0].commands must "
+                "contain at least one command."
+            )
+        for index, command_value in enumerate(commands):
+            command = command_value if isinstance(command_value, Mapping) else {}
+            for command_field in ("claudeCode", "terminal"):
+                value = command.get(command_field)
+                if not _route_target_matches(value, target, command=True):
+                    failures.append(
+                        "final-report data.json: recommendedNextSteps[0].commands"
+                        f"[{index}].{command_field} must contain routing target "
+                        f"`{target}`."
+                    )
+
+
 def _load_final_report_data(report_path: Path) -> dict:
     """Best-effort parse of the final-report data.json sibling. Returns {} when
     absent or unparseable — those conditions are already surfaced as failures by
@@ -2257,7 +2513,7 @@ def validate_final_report_data(
     failures: list[str],
     *,
     report_contracts: set[str] | None = None,
-) -> None:
+) -> Mapping[str, Any] | None:
     """Validate the final-report data.json against the v1.0 schema.
 
     The data.json is the source-of-truth that the renderer reads to
@@ -2270,6 +2526,8 @@ def validate_final_report_data(
     Missing data.json is reported as a single failure rather than a
     cascade of substring failures — that points the writer at the right
     fix (write the data.json) instead of futilely editing the markdown.
+    The returned mapping is the exact loaded snapshot consumed by later
+    finalization checks and workflow persistence.
     """
     if schema_validate is None or load_schema is None:
         # Module-load fallback path; should never fire in a real install.
@@ -2314,7 +2572,9 @@ def validate_final_report_data(
     _validate_verifier_fail_blocks_verdict(data, failures)
     if task_type == "implementation":
         _validate_stage_carry_sidecar_exists(data, report_path, failures)
-    if task_type == "final-verification":
+    if task_type == "error-analysis":
+        _validate_error_analysis_consistency(data, failures)
+    elif task_type == "final-verification":
         _validate_final_verification_consistency(data, failures)
         _validate_verified_row_recorded(data, report_path, failures)
     elif task_type == "implementation-planning":
@@ -2343,6 +2603,11 @@ def validate_final_report_data(
         _validate_round_recorded_verdicts(data, failures)
         _validate_verdicts_match_current_subjects(data, failures)
         _validate_plan_item_extraction_completeness(data, failures)
+        _validate_variation_point_analysis(
+            (data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
+            resolve_architecture(_project_root_from_report(report_path)),
+            failures,
+        )
         _validate_plan_item_subject_substance(data, failures)
         _validate_plan_body_clarification_matching(data, failures)
         _validate_disagree_has_fixability(data, failures)
@@ -2358,6 +2623,8 @@ def validate_final_report_data(
         for warning in warnings:
             print(f"validate-run: warning: {warning}", file=sys.stderr)
 
+    return data
+
 
 # path:line (foo.service.ts:268), an in-report ID (C-001 / E-006 / P-004), a
 # namespaced audit ref (claude:F-005), or a §section reference (§5.4) — any one
@@ -2524,10 +2791,16 @@ _PLAN_GATE_RANK = {
 
 # Breakage kinds where a single DISAGREE blocks the gate on its own (no majority
 # needed), because the defect is concrete, safety-critical, and adversarially
-# verifiable: `a` = cited path/symbol mismatch, `d` = rollback violates
-# commit/dependency order. `b`/`c`/`e` still need a majority — `b` in particular
-# is prone to planning-vs-implementation environment false positives.
-_SINGLE_VOTE_BLOCKING_KINDS = {"a", "d"}
+# verifiable: `a` = cited path/symbol mismatch. `b`/`c`/`e` still need a
+# majority — `b` in particular is prone to planning-vs-implementation
+# environment false positives.
+_SINGLE_VOTE_BLOCKING_KINDS = {"a"}
+
+# Rollback ordering (`d`) is executed by a human, not by okstra's workers or
+# verifiers, so a rollback-ordering dissent is recorded but never gates
+# approval: it is dropped from the blocking-disagree tally entirely, so an item
+# whose only DISAGREEs are advisory-only can never rise above `has-dissent`.
+_ADVISORY_ONLY_KINDS = {"d"}
 
 # Stop reasons that justify promoting a still-broken planner-fixable item to the
 # user: the self-fix budget ran out, or a round produced no net resolution so
@@ -2535,6 +2808,20 @@ _SINGLE_VOTE_BLOCKING_KINDS = {"a", "d"}
 _SELF_FIX_EXHAUSTED_REASONS = frozenset({"max-rounds-reached", "no-progress"})
 
 
+def _is_variation_point_item(item: dict) -> bool:
+    """Whether this is a `P-Var-*` variation-point item, which is majority-gated
+    (`prompts/lead/plan-body-verification.md` "`P-Var-<N>` … is majority-gated").
+    Whether a behavior has two implementations, and whether the plan extracted the
+    right interface for it, is a design judgement — it lacks the concrete certainty
+    of kind `a`, where a verifier points at two spelled-out references that
+    contradict each other. So kind `a` carries no extra weight on a P-Var item: it
+    neither single-vote-blocks nor counts as correctness-critical, exactly like the
+    `b` / `c` / `e` kinds the prompt routes P-Var defects to. Only a
+    `majority-disagree` gates it — that part is unchanged.
+    """
+    return str(item.get("id") or "").upper().startswith("P-VAR")
+
+
 def _classify_plan_item_gate(item: dict) -> str:
     """Recompute one plan item's gate class from its per-worker verdicts,
     per `prompts/lead/plan-body-verification.md` "Round protocol". Returns one of
@@ -2556,15 +2843,32 @@ def _classify_plan_item_gate(item: dict) -> str:
         return "all-non-result"
     disagree = [(vd, bk) for (vd, bk) in non_error if vd == "DISAGREE"]
     agree = [(vd, bk) for (vd, bk) in non_error if vd in ("AGREE", "SUPPLEMENT")]
-    disagree_kinds = {bk for (_vd, bk) in disagree if bk}
     if not disagree:
         return "full-consensus"
+    # Rollback is a human-run operation, so rollback dissent never blocks the
+    # gate — closed from two angles so a verifier cannot re-block it by relabelling:
+    #   (1) a whole rollback plan item (`P-Rb-*`) is advisory regardless of
+    #       breakage kind — otherwise a `DISAGREE(b)` "rollback command is
+    #       ambiguous" would sail past the kind-`d` exemption and block;
+    #   (2) a rollback-ordering dissent (`d`) is advisory on ANY item, since a
+    #       rollback-order defect raised against a non-rollback item is still a
+    #       human-run concern.
+    # Both are recorded as dissent and fold into `has-dissent`, never blocking.
+    if str(item.get("id") or "").upper().startswith("P-RB"):
+        return "has-dissent"
+    blocking_disagree = [(vd, bk) for (vd, bk) in disagree if bk not in _ADVISORY_ONLY_KINDS]
+    if not blocking_disagree:
+        return "has-dissent"
+    blocking_kinds = {bk for (_vd, bk) in blocking_disagree if bk}
     # Single-vote-blocking kinds: one confirmed DISAGREE on a concrete,
     # safety-critical, adversarially-verifiable defect is enough to block, even
     # in a two-worker roster — a lone correct dissent must not be outvoted here.
-    # `a`/`d` for any item; `f` only for P-Req items (requirement coverage).
+    # `a` for any item except `P-Var-*` (majority-gated, see
+    # `_is_variation_point_item`); `f` only for P-Req items (requirement coverage).
     is_req = str(item.get("id") or "").upper().startswith("P-REQ")
-    if disagree_kinds & _SINGLE_VOTE_BLOCKING_KINDS or (is_req and "f" in disagree_kinds):
+    if not _is_variation_point_item(item) and (
+        blocking_kinds & _SINGLE_VOTE_BLOCKING_KINDS or (is_req and "f" in blocking_kinds)
+    ):
         # "One confirmed DISAGREE" presupposes the item was actually
         # cross-verified. When the peer returned a non-result nothing confirmed
         # the dissent, so blocking here would reproduce the same
@@ -2577,7 +2881,7 @@ def _classify_plan_item_gate(item: dict) -> str:
     # two participating votes, so a lone surviving DISAGREE (its peer returned a
     # non-result) does NOT block. That fixes the paradox where a worker failure
     # made the gate stricter than a healthy roster would.
-    if len(non_error) >= 2 and len(disagree) > len(agree):
+    if len(non_error) >= 2 and len(blocking_disagree) > len(agree):
         return "majority-disagree"
     return "has-dissent"
 
@@ -2604,11 +2908,18 @@ def _has_planner_fixable_majority(item: dict) -> bool:
 
 def _is_correctness_critical(item: dict) -> bool:
     """Whether this item's defect would make `implementation` produce wrong or
-    unsafe code — the single-vote-blocking kinds `a` (cited path/symbol
-    mismatch) and `d` (rollback violates commit order) on any item, or `f`
-    (requirement-coverage mismatch) on a `P-Req-*` item. Kinds `b`/`c`/`e` are
-    plan-prose defects: they degrade the document, not the resulting code.
+    unsafe code — the single-vote-blocking kind `a` (cited path/symbol mismatch)
+    on any item but `P-Var-*`, or `f` (requirement-coverage mismatch) on a
+    `P-Req-*` item.
+    Kinds `b`/`c`/`e` are plan-prose defects: they degrade the document, not the
+    resulting code. Rollback ordering (`d`) is advisory — a human runs the
+    rollback — so it never counts as correctness-critical. A `P-Var-*` item is
+    majority-gated end to end, so a kind-`a` dissent on one is no more critical
+    than the `b`/`e` its defect should have been raised under; otherwise the same
+    mis-tag that no longer single-vote-blocks would still veto the downgrade.
     """
+    if _is_variation_point_item(item):
+        return False
     kinds = _disagree_breakage_kinds(item)
     is_req = str(item.get("id") or "").upper().startswith("P-REQ")
     return bool(kinds & _SINGLE_VOTE_BLOCKING_KINDS) or (is_req and "f" in kinds)
@@ -3677,20 +3988,6 @@ def _validate_missing_qa_categories_recorded(
         )
 
 
-def _load_report_data(report_path: Path) -> dict | None:
-    """The report's data.json, or ``None`` when it is missing or malformed.
-    Both cases are already reported by `validate_final_report_data`; callers
-    here only need to skip rather than re-report."""
-    data_path = _data_path_for(report_path)
-    if not data_path.is_file():
-        return None
-    try:
-        loaded = json.loads(data_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-    return loaded if isinstance(loaded, dict) else None
-
-
 def _validate_verification_target_match(
     data: dict,
     run_manifest: dict,
@@ -4131,6 +4428,87 @@ def _validate_plan_item_extraction_completeness(
         )
 
 
+def _validate_variation_point_analysis(
+    vpa: object,
+    architecture_style: str,
+    failures: list[str],
+) -> None:
+    """Conditional rules + architecture-style overlay for variation points.
+
+    The schema enforces shape only. Two layers of meaning sit on top:
+
+    Layer 1 is style-agnostic. Declaring "no variation exists" is a claim that
+    needs a written reason, and it must not be paired with declared points —
+    `plan_items._extract_variation_point_items` emits a lone `P-Var-0` in that
+    branch and drops them, so the contradiction would silently exempt every
+    declared point from per-point verification. `extract: true` is a claim in
+    the same way: it names the interface the next implementation plugs into and
+    the Stage Map stage that builds it, so both fields have to be filled. The
+    schema cannot carry this as a `minLength` — the empty string is the natural
+    shape of an `extract: false` decision.
+
+    Layer 2 fires only for a project that declares `architecture.style`
+    `hexagonal`: extracting a variation point there means introducing a port,
+    not a helper. An unconfigured project resolves to `none` and keeps layer-1
+    behaviour only.
+    """
+    if not isinstance(vpa, dict):
+        failures.append("variationPointAnalysis is missing or not an object")
+        return
+    # Schema violations are reported, not raised, so this check still runs on a
+    # malformed block. A type guard here keeps a bad field from aborting the
+    # whole validation and discarding every failure collected so far.
+    raw_points = vpa.get("points")
+    if raw_points is not None and not isinstance(raw_points, list):
+        failures.append("variationPointAnalysis: points must be an array")
+        return
+    points = raw_points or []
+    if not bool(vpa.get("hasMultipleImplementations")):
+        rationale = vpa.get("noVariationRationale")
+        if not isinstance(rationale, str) or not rationale.strip():
+            failures.append(
+                "variationPointAnalysis: hasMultipleImplementations=false "
+                "requires a non-empty noVariationRationale"
+            )
+        if points:
+            failures.append(
+                "variationPointAnalysis: hasMultipleImplementations=false but "
+                "points is non-empty — declared variation points would be "
+                "silently dropped"
+            )
+        return
+    if not points:
+        failures.append(
+            "variationPointAnalysis: hasMultipleImplementations=true requires "
+            "at least one point"
+        )
+        return
+    for index, point in enumerate(points, start=1):
+        if not isinstance(point, dict):
+            failures.append(
+                f"variationPointAnalysis point {index}: must be an object"
+            )
+            continue
+        decision = point.get("extractionDecision")
+        if not isinstance(decision, dict):
+            continue  # shape is the schema's job; don't double-report it.
+        if not decision.get("extract"):
+            continue
+        for field in ("interfaceKind", "coveredBy"):
+            value = decision.get(field)
+            if not isinstance(value, str) or not value.strip():
+                failures.append(
+                    f"variationPointAnalysis point {index}: extract=true "
+                    f"requires a non-empty {field}, got {value!r}"
+                )
+        if architecture_style == "hexagonal" and decision.get("interfaceKind") != "port":
+            failures.append(
+                f"variationPointAnalysis point {index}: architecture style "
+                f"'hexagonal' requires interfaceKind 'port', got "
+                f"{decision.get('interfaceKind')!r}"
+            )
+
+
 _DESIGN_PREP_CONTRACT = "implementation-design-prep-v1"
 _DESIGN_PREP_REQUEST_STATUSES = {"provisional", "blocked"}
 _DESIGN_PREP_TERMINAL_STATUSES = {"ready", "not-applicable"}
@@ -6209,20 +6587,20 @@ def main() -> int:
     report_contracts = _normalize_report_contracts(
         run_manifest.get("reportContracts")
     )
-    validate_final_report_data(
+    report_data = validate_final_report_data(
         report_path,
         failures,
         report_contracts=report_contracts,
     )
-    _validate_fix_cycle(
-        run_manifest, _load_final_report_data(report_path), failures
-    )
+    validation_data = report_data if isinstance(report_data, Mapping) else {}
+    _validate_fix_cycle(run_manifest, validation_data, failures)
     validate_report(
         report_path,
         contract["required_agent_status_entries"],
         failures,
         allow_unavailable_token_usage=_session_accounting(team_state) == "artifact-only",
         unavailable_ok_labels=_unavailable_usage_worker_labels(team_state),
+        report_data=validation_data,
     )
     validate_team_state_usage(team_state, failures)
 
@@ -6270,11 +6648,12 @@ def main() -> int:
         if task_type in _END_STATE_PHASES:
             if task_type == "implementation-planning":
                 _validate_planning_conformance_declared(report_path, failures)
-            report_data = _load_final_report_data(report_path)
-            _validate_end_state_coverage(report_data, brief_path, failures)
+            _validate_end_state_coverage(validation_data, brief_path, failures)
             if task_type == "implementation-planning":
-                _validate_requirement_provenance(report_data, brief_path, failures)
-                _validate_stage_has_requirement(report_data, failures)
+                _validate_requirement_provenance(
+                    validation_data, brief_path, failures
+                )
+                _validate_stage_has_requirement(validation_data, failures)
         if task_type == "improvement-discovery":
             run_dir = report_path.parent.parent
             _validate_improvement_discovery(report_path, run_dir, brief_path, failures)
@@ -6291,22 +6670,20 @@ def main() -> int:
     validate_report_views(report_path, failures)
     if task_type == "implementation":
         _validate_missing_qa_categories_recorded(
-            _load_report_data(report_path) or {}, project_root, failures
+            validation_data, project_root, failures
         )
     if task_type == "implementation-planning":
-        _validate_plan_body_state_file(
-            _load_report_data(report_path) or {}, report_path, failures
-        )
+        _validate_plan_body_state_file(validation_data, report_path, failures)
     if task_type == "final-verification":
         _validate_verification_target_match(
-            _load_report_data(report_path) or {},
+            validation_data,
             run_manifest,
             project_root,
             failures,
         )
     # Phase-agnostic: any task-type can be launched with a carry-in.
     _validate_clarification_carry_in_recorded(
-        _load_report_data(report_path) or {},
+        validation_data,
         report_path,
         run_manifest_path,
         project_root,
@@ -6315,7 +6692,12 @@ def main() -> int:
 
     validation_status = "passed" if not failures else "failed"
     update_validation_metadata(
-        team_state, run_manifest, task_manifest, validation_status, failures
+        team_state,
+        run_manifest,
+        task_manifest,
+        validation_status,
+        failures,
+        report_data=validation_data,
     )
 
     write_json(team_state_path, team_state)