okstra 0.142.0 → 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
@@ -188,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):
@@ -221,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:
@@ -322,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()
 
@@ -350,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(
@@ -1645,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.
 
@@ -1657,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
@@ -1689,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}")
@@ -1779,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:
@@ -2240,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
@@ -2258,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
@@ -2271,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.
@@ -2315,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":
@@ -2364,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
@@ -3727,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,
@@ -6340,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)
 
@@ -6401,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)
@@ -6422,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,
@@ -6446,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)