okstra 0.151.0 → 0.152.0

package/runtime/validators/validate-run.py

@@ -103,6 +103,7 @@ from okstra_ctl.worker_prompt_contract import (  # noqa: E402
     PromptRecord,
     validate_initial_prompt_records,
 )
+from okstra_ctl.worker_prompt_headers import EVIDENCE_LEDGER_HEADER  # noqa: E402
 from validate_analysis_report import validate_analysis_report  # noqa: E402
 from okstra_ctl.convergence_engine import (  # noqa: E402
     grouped_input_digest,
@@ -2378,6 +2379,16 @@ def validate_report(
 _WORKER_RESULT_BASENAME_RE = re.compile(
     r"^(?P<worker>[a-z][a-z0-9-]*-worker)-(?P<task_type>[a-z][a-z-]*?)-(?P<seq>\d{3})\.md$"
 )
+_EVIDENCE_READ_RE = re.compile(
+    r"^- Evidence read: `(?P<path>[^`\n]+)`\s*$",
+    re.MULTILINE,
+)
+_FILE_LINE_CITATION_RE = re.compile(
+    r"`(?P<path>(?!https?://)[^`\n]+?):(?P<line>\d+(?:-\d+)?)`"
+)
+_EXTENSIONLESS_SOURCE_FILENAMES = frozenset(
+    {"Dockerfile", "Justfile", "Makefile", "Procfile", "Rakefile"}
+)
 
 _REPORT_BASENAME_SEQ_RE = re.compile(r"-(?P<seq>\d{3})(?:\.data)?\.(?:md|json)$")
 
@@ -2390,6 +2401,90 @@ def _report_run_seq(report_path: Path) -> str | None:
     return match.group("seq") if match else None
 
 
+def _cited_file_paths(content: str) -> set[str]:
+    paths: set[str] = set()
+    for match in _FILE_LINE_CITATION_RE.finditer(content):
+        path = match.group("path")
+        if _looks_like_file_path(path):
+            paths.add(path)
+    return paths
+
+
+def _looks_like_file_path(path: str) -> bool:
+    if (
+        not path
+        or path.startswith(("-", "$"))
+        or any(char.isspace() for char in path)
+    ):
+        return False
+    if re.fullmatch(r"[0-9a-fA-F]{7,64}", path):
+        return False
+    return (
+        "/" in path
+        or "." in Path(path).name
+        or Path(path).name in _EXTENSIONLESS_SOURCE_FILENAMES
+    )
+
+
+def _audit_evidence_read_paths(content: str) -> set[str]:
+    return {
+        match.group("path")
+        for match in _EVIDENCE_READ_RE.finditer(content)
+    }
+
+
+def _worker_prompt_path(
+    report_path: Path,
+    worker_role: str,
+    task_type: str,
+    seq: str,
+) -> Path:
+    return (
+        report_path.parent.parent
+        / "prompts"
+        / f"{worker_role}-prompt-{task_type}-{seq}.md"
+    )
+
+
+def _validate_worker_evidence_read_ledger(
+    *,
+    report_path: Path,
+    worker_role: str,
+    task_type: str,
+    seq: str,
+    result_name: str,
+    result_content: str,
+    audit_path: Path,
+    failures: list[str],
+) -> None:
+    if worker_role == "report-writer-worker":
+        return
+    prompt_path = _worker_prompt_path(report_path, worker_role, task_type, seq)
+    try:
+        prompt_content = prompt_path.read_text(encoding="utf-8")
+    except OSError:
+        return
+    if EVIDENCE_LEDGER_HEADER not in prompt_content.splitlines():
+        return
+    try:
+        audit_content = audit_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        failures.append(
+            f"worker audit sidecar unreadable: {audit_path.name} ({exc})"
+        )
+        return
+
+    missing_paths = sorted(
+        _cited_file_paths(result_content) - _audit_evidence_read_paths(audit_content)
+    )
+    for missing_path in missing_paths:
+        failures.append(
+            f"worker `{worker_role}` result `{result_name}` cites "
+            f"`{missing_path}:line` without an Evidence read row for "
+            f"`{missing_path}` in `{audit_path.name}`"
+        )
+
+
 def validate_worker_results_audit(
     report_path: Path, task_type: str, failures: list[str]
 ) -> None:
@@ -2404,6 +2499,10 @@ def validate_worker_results_audit(
     2. The matching audit sidecar exists at
        `<worker>-audit-<task-type>-<seq>.md`. Missing sidecar means the
        worker silently skipped the reading-confirmation step.
+    3. For new prompts carrying the required-v1 marker, every canonical
+       backticked `path:line` citation has a matching Evidence read row in
+       that audit sidecar. Historical prompts without the marker retain the
+       existence-only contract.
 
     Scoped to this run's seq. `worker-results/` accumulates every run's
     artifacts, so scanning the whole directory judged a run by files it did
@@ -2465,6 +2564,18 @@ def validate_worker_results_audit(
                 f"Confirmation block (one short line per input file). Workers "
                 f"write this in the same step as the main worker-results file."
             )
+            continue
+
+        _validate_worker_evidence_read_ledger(
+            report_path=report_path,
+            worker_role=worker_role,
+            task_type=task_type,
+            seq=seq,
+            result_name=rel,
+            result_content=content,
+            audit_path=audit_path,
+            failures=failures,
+        )
 
 
 def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
@@ -6066,6 +6177,31 @@ def _load_stage_validator():
     return mod
 
 
+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.
+    """
+    if (data or {}).get("schemaVersion") != "2.0":
+        return  # v1 reports are covered by the Markdown scan.
+    planning = (data or {}).get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        return  # Schema validation already reported the missing block.
+    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_data_validation_errors(dict(planning)):
+        failures.append(
+            f"implementation-planning stage contract invalid "
+            f"[{e.code} stage={e.stage}]: {e.message}"
+        )
+
+
 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
@@ -7309,6 +7445,7 @@ def main() -> int:
                     validation_data, brief_path, failures
                 )
                 _validate_stage_has_requirement(validation_data, failures)
+                _append_stage_data_failures(validation_data, failures)
         if task_type == "improvement-discovery":
             run_dir = report_path.parent.parent
             _validate_improvement_discovery(report_path, run_dir, brief_path, failures)