okstra 0.178.0 → 0.179.0

package/runtime/validators/validate-run.py

@@ -93,6 +93,7 @@ from okstra_ctl.md_table import (  # noqa: E402
     split_pipe_row as _split_pipe_row,
 )
 from okstra_ctl.final_report_paths import final_report_data_path as _data_path_for  # noqa: E402
+from okstra_token_usage.report import _match_worker_index  # noqa: E402
 from okstra_ctl.improvement_assignment import (  # noqa: E402
     validate_primary_lens_assignments,
 )
@@ -743,8 +744,8 @@ def update_workflow_metadata(
             "latestTeamStatePath": run_manifest.get(
                 "teamStatePath", ""
             ),
-            "latestReportPath": task_manifest.get(
-                "latestReportPath", ""
+            "latestReportRecordPath": task_manifest.get(
+                "latestReportRecordPath", ""
             ),
             "latestResumeCommandPath": task_manifest.get(
                 "latestResumeCommandPath", ""
@@ -1660,39 +1661,51 @@ def _scan_token_usage_summary(
 # a section heading line (not as inline text inside a paragraph or table).
 _VERDICT_CARD_HEADING_RE = re.compile(r"^##[ \t]+Verdict Card\b", re.MULTILINE)
 
+def _team_state_worker_label(worker: Mapping[str, Any]) -> str:
+    role = str(worker.get("role") or "").strip()
+    worker_id = str(worker.get("workerId") or "").strip()
+    if role and worker_id:
+        return f"{role} (`{worker_id}`)"
+    return role or worker_id or "<unnamed>"
+
+
+def _unmatched_team_state_workers(
+    report_data: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+) -> list[dict]:
+    raw = team_state.get("workers")
+    workers = [row for row in raw if isinstance(row, dict)] if isinstance(raw, list) else []
+    used: set[int] = set()
+    for row in report_data.get("executionStatus") or []:
+        if not isinstance(row, dict):
+            continue
+        if "lead" in str(row.get("role") or "").lower():
+            continue
+        index = _match_worker_index(row, workers, used)
+        if index is not None:
+            used.add(index)
+    return [worker for index, worker in enumerate(workers) if index not in used]
+
+
 def _validate_v2_report(
     report_data: Mapping[str, Any],
-    required_agent_status_entries: list[str],
     failures: list[str],
+    *,
+    team_state: Mapping[str, Any] | None = None,
 ) -> None:
     """Contract checks for a schema-v2 report, read from its data.json.
 
-    The AI-handoff markdown is a deterministic rendering of this record, so the
-    checks that used to scan it — heading count and order, human-only fields
-    leaking into the AI artifact, a Reading Confirmation heading — were asking
-    whether the renderer had done its job, not whether the report was sound.
-    Schema enforcement in `render_final_report._enforce_schema` already answers
-    the second question, and the first is settled by the template. What is left
-    is the pair of facts the markdown could only ever carry second-hand: which
-    agents the run must account for, and whether the token cells were filled.
-
-    Both are scanned over the serialized record, as text, because that is what
-    the markdown scan was. Requiring each label to equal an
-    `executionStatus[].role` would be a stricter rule than the contract states
-    anywhere: the schema types `role` as a free string, no prompt or worker spec
-    fixes its vocabulary, and `okstra_token_usage.report._match_worker_index`
-    treats function-role spellings ("Analysis verifier", "Acceptance critic") as
-    a shape reports do take — matching them by containment, never equality.
-    Tightening this belongs with an authoring rule that says what to write, not
-    on its own. Nothing is lost by reading the record instead of its rendering:
-    the labels never come from the template or the i18n dictionaries.
+    Agent completeness is the team-state worker set versus `executionStatus`
+    rows, matched by `_match_worker_index` (role containment, then a unique
+    provider+model fallback). Token placeholders stay a serialized-record
+    scan. The full reading copy is not read.
     """
+    for worker in _unmatched_team_state_workers(report_data, team_state or {}):
+        failures.append(
+            "executionStatus is missing team-state worker "
+            f"{_team_state_worker_label(worker)}"
+        )
     serialized = json.dumps(report_data, ensure_ascii=False)
-    for label in required_agent_status_entries:
-        if label not in serialized:
-            failures.append(
-                f"final report does not include required agent status entry: {label}"
-            )
     for placeholder in TOKEN_PLACEHOLDERS:
         if placeholder in serialized:
             failures.append(
@@ -2875,13 +2888,14 @@ def validate_report(
     allow_unavailable_token_usage: bool = False,
     unavailable_ok_labels: frozenset[str] = frozenset(),
     report_data: Mapping[str, Any] | None = None,
+    team_state: Mapping[str, Any] | None = None,
 ) -> None:
-    if not report_path.exists():
-        failures.append(f"final report is missing: {report_path}")
+    if (report_data or {}).get("schemaVersion") == "2.0":
+        _validate_v2_report(report_data or {}, failures, team_state=team_state)
         return
 
-    if (report_data or {}).get("schemaVersion") == "2.0":
-        _validate_v2_report(report_data or {}, required_agent_status_entries, failures)
+    if not report_path.exists():
+        failures.append(f"final report is missing: {report_path}")
         return
 
     content = report_path.read_text()
@@ -3475,6 +3489,7 @@ def validate_final_report_data(
     # Called here rather than from a task-type branch: four profiles raise
     # clarification rows, and the gate scopes itself by task type internally.
     _validate_clarification_options(data, failures)
+    _validate_clarification_record_coordinates(data, failures)
     _validate_open_approval_blocker_provenance(data, failures)
 
     task_type = (data.get("header") or {}).get("taskType")
@@ -5413,6 +5428,48 @@ _REACH_TOKENS = frozenset({"in-repo", "cross-repo"})
 _LEGACY_EXPECTED_FORM_RE = re.compile(r"\b(?:Recommended|Alternatives):")
 
 
+_CLARIFICATION_SECTION_CITE_RE = re.compile(r"§\d")
+
+
+def _validate_clarification_record_coordinates(
+    data: dict, failures: list[str]
+) -> None:
+    """A clarification row may cite a record coordinate, not a section number.
+
+    `§4.7` exists only on one full reading copy. The report record identifies
+    a row by `id` (`RB-002`). schema-v1 has no record and is exempt.
+    """
+    if data.get("schemaVersion") != "2.0":
+        return
+    texts: list[tuple[str, str]] = []
+    for row in data.get("clarificationItems") or []:
+        if not isinstance(row, dict):
+            continue
+        row_id = str(row.get("id") or "<unknown>")
+        for field in ("statement", "expectedForm"):
+            texts.append((f"`{row_id}` {field}", str(row.get(field) or "")))
+        options = row.get("options") or []
+        if isinstance(options, list):
+            for index, option in enumerate(options):
+                if not isinstance(option, dict):
+                    continue
+                for field in ("answer", "rationale"):
+                    texts.append(
+                        (
+                            f"`{row_id}` options[{index}].{field}",
+                            str(option.get(field) or ""),
+                        )
+                    )
+    for label, text in texts:
+        if _CLARIFICATION_SECTION_CITE_RE.search(text):
+            failures.append(
+                f"final-report data.json: clarification {label} cites a "
+                "section number (`§…`). Cite a record coordinate (`RB-002`) "
+                "instead — a section number exists only on one full reading "
+                "copy."
+            )
+
+
 def _validate_clarification_options(data: dict, failures: list[str]) -> None:
     """A `decision` row must carry its choices as data, not as prose.
 
@@ -8922,8 +8979,8 @@ def _import_token_usage():
                 sys.path.insert(0, str(candidate))
             break
     from okstra_token_usage.collect import collect  # noqa: E402
-    from okstra_token_usage.report import populate_and_render  # noqa: E402
-    return collect, populate_and_render
+    from okstra_token_usage.report import populate_token_cells  # noqa: E402
+    return collect, populate_token_cells
 
 
 def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
@@ -9018,7 +9075,7 @@ def attempt_token_usage_autofix(
     if not _needs_token_autofix(team_state, report_path):
         return "skipped", []
     try:
-        collect, populate_and_render = _import_token_usage()
+        collect, populate_token_cells = _import_token_usage()
     except Exception as exc:  # noqa: BLE001
         return "import-failed", [f"okstra_token_usage import failed: {exc}"]
     try:
@@ -9041,7 +9098,7 @@ def attempt_token_usage_autofix(
     )
     data_path = _data_path_for(report_path)
     try:
-        replaced, _bytes = populate_and_render(data_path, updated)
+        replaced = populate_token_cells(data_path, updated)
     except Exception as exc:  # noqa: BLE001
         # `SubstituteRefusedError` (or any unexpected substitution
         # failure) — report it as an accuracy failure so the validator
@@ -9052,7 +9109,7 @@ def attempt_token_usage_autofix(
         ]
 
     # Phase 7 step 1.5 is BLOCKING and the autofix just mutated the
-    # source MD — any pre-existing html sibling is now stale by
+    # report record — any pre-existing html sibling is now stale by
     # construction. Re-render the html view in lock-step so the
     # downstream report-views validator does not trip over the
     # autofix's own side effect.
@@ -9203,7 +9260,7 @@ def main() -> int:
     parser.add_argument(
         "--report",
         required=True,
-        help="Project-relative or absolute path to the final report Markdown file.",
+        help="Project-relative or absolute path to the report record (.data.json). Schema-v1 reports still use the Markdown file.",
     )
     parser.add_argument(
         "--run-manifest",
@@ -9344,6 +9401,7 @@ def main() -> int:
         allow_unavailable_token_usage=_session_accounting(team_state) == "artifact-only",
         unavailable_ok_labels=_unavailable_usage_worker_labels(team_state),
         report_data=validation_data,
+        team_state=team_state,
     )
     validate_team_state_usage(team_state, failures)