okstra 0.30.3 → 0.32.0

package/runtime/validators/validate-run.py

@@ -10,6 +10,25 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+# Make the in-tree ``okstra_ctl`` package importable when this validator
+# runs from the repo (the installed runtime already has ~/.okstra/lib/python
+# on PYTHONPATH so the import is a no-op there).
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+_SCRIPTS_DIR = _VALIDATORS_DIR.parent / "scripts"
+if _SCRIPTS_DIR.is_dir() and str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+try:
+    from okstra_ctl.final_report_schema import (
+        SchemaError,
+        load_schema,
+        validate as schema_validate,
+    )
+except ImportError:  # pragma: no cover — runtime guarantees this import
+    SchemaError = None  # type: ignore[assignment]
+    load_schema = None  # type: ignore[assignment]
+    schema_validate = None  # type: ignore[assignment]
+
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
 
@@ -558,7 +577,7 @@ def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
                         "Token Usage Summary cell contains sentinel value "
                         f"`{stripped}` on row labelled `{label_cell or '<unlabeled>'}` — "
                         "leave the `{{...}}` placeholder verbatim until "
-                        "`okstra-token-usage.py --substitute-final-report` runs "
+                        "`okstra-token-usage.py --substitute-data` runs "
                         "in Phase 7."
                     )
                     continue
@@ -567,7 +586,7 @@ def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
                         f"Token Usage Summary row `{label_cell or '<unlabeled>'}` has "
                         f"a zero value `{stripped}` — no okstra run consumes zero "
                         "tokens. Re-run `python3 scripts/okstra-token-usage.py "
-                        "<team-state> --write --summary --substitute-final-report "
+                        "<team-state> --write --summary --substitute-data "
                         "<report-path>` to repopulate from session jsonls. The "
                         "Codex/Gemini CLI row is the only place `$0.00` is "
                         "allowed (when no CLI work was billed)."
@@ -664,7 +683,7 @@ def validate_report(
         if placeholder in content:
             failures.append(
                 f"final report contains unsubstituted token placeholder `{placeholder}` — "
-                "run `okstra-token-usage.py ... --substitute-final-report <report-path>` during Phase 7"
+                "run `okstra-token-usage.py ... --substitute-data <report-path>` during Phase 7"
             )
 
     # Catch the "workers typed `0` / `pending` instead of the placeholder"
@@ -794,7 +813,7 @@ def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
         failures.append(
             "team-state.usageSummary is empty — Phase 7 token-usage collection was skipped. "
             "Run `python3 scripts/okstra-token-usage.py <team-state> --write --summary "
-            "--substitute-final-report <final-report>`."
+            "--substitute-data <final-report>`."
         )
         return
     # Reject zero-valued usage when the collector flagged any source as
@@ -973,11 +992,69 @@ def _validate_verdict_card_consistency(content: str, failures: list[str]) -> Non
         )
 
 
+def _data_path_for(report_path: Path) -> Path:
+    """Derive the final-report data.json sibling from the markdown path.
+    ``foo.md`` → ``foo.data.json``. The data.json is the canonical JSON
+    SSOT; the markdown is rendered from it.
+    """
+    name = report_path.name
+    if name.endswith(".md"):
+        return report_path.with_name(name[:-3] + ".data.json")
+    return report_path.with_suffix(".data.json")
+
+
+def validate_final_report_data(report_path: Path, failures: list[str]) -> 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
+    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.
+
+    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.
+    """
+    if schema_validate is None or load_schema is None:
+        # Module-load fallback path; should never fire in a real install.
+        failures.append(
+            "validate-run: okstra_ctl.final_report_schema is not importable — "
+            "install may be incomplete (scripts/ not on PYTHONPATH)."
+        )
+        return
+
+    data_path = _data_path_for(report_path)
+    if not data_path.is_file():
+        failures.append(
+            f"final-report data.json is missing at {data_path} — the renderer "
+            "needs this file as its single source of truth. The markdown "
+            "alone is no longer a valid run artifact."
+        )
+        return
+
+    try:
+        schema = load_schema()
+    except SchemaError as exc:
+        failures.append(f"final-report schema could not be loaded: {exc}")
+        return
+
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        failures.append(f"final-report data.json is not valid JSON: {exc}")
+        return
+
+    errors = schema_validate(data, schema)
+    for err in errors:
+        failures.append(f"final-report data.json: {err}")
+
+
 def validate_report_views(report_path: Path, failures: list[str]) -> None:
-    """Enforce Phase 7 step 1.5 (BLOCKING) — the slim AI copy and the
-    self-contained HTML view must exist next to the final-report MD,
-    and both must satisfy the contract checked by
-    ``validators/validate-report-views.py``.
+    """Enforce Phase 7 step 1.5 (BLOCKING) — the self-contained HTML
+    view must exist next to the final-report MD and satisfy the
+    contract checked by ``validators/validate-report-views.py``.
 
     Delegated to that script as a subprocess so the contract surface
     stays in one place. Failures from the delegate are folded back as
@@ -1192,8 +1269,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 substitute_final_report  # noqa: E402
-    return collect, substitute_final_report
+    from okstra_token_usage.report import populate_and_render  # noqa: E402
+    return collect, populate_and_render
 
 
 def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
@@ -1286,7 +1363,7 @@ def attempt_token_usage_autofix(
     if not _needs_token_autofix(team_state, report_path):
         return "skipped", []
     try:
-        collect, substitute_final_report = _import_token_usage()
+        collect, populate_and_render = _import_token_usage()
     except Exception as exc:  # noqa: BLE001
         return "import-failed", [f"okstra_token_usage import failed: {exc}"]
     try:
@@ -1307,8 +1384,9 @@ def attempt_token_usage_autofix(
     team_state_path.write_text(
         json.dumps(updated, indent=2, ensure_ascii=False) + "\n"
     )
+    data_path = _data_path_for(report_path)
     try:
-        replaced = substitute_final_report(report_path, updated)
+        replaced, _bytes = populate_and_render(data_path, updated)
     except Exception as exc:  # noqa: BLE001
         # `SubstituteRefusedError` (or any unexpected substitution
         # failure) — report it as an accuracy failure so the validator
@@ -1319,8 +1397,8 @@ def attempt_token_usage_autofix(
         ]
 
     # Phase 7 step 1.5 is BLOCKING and the autofix just mutated the
-    # source MD — any pre-existing slim/html sibling is now stale by
-    # construction. Re-render the derived views in lock-step so the
+    # source MD — 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.
     rerender_note = _rerender_report_views_after_autofix(report_path)
@@ -1339,9 +1417,9 @@ def attempt_token_usage_autofix(
 
 
 def _rerender_report_views_after_autofix(report_path: Path) -> str:
-    """Re-render ``*.slim.md`` and ``*.html`` siblings against the
-    just-substituted MD. Returns a short status note for the autofix
-    message (empty on no-op, descriptive on failure).
+    """Re-render the ``*.html`` sibling against the just-substituted MD.
+    Returns a short status note for the autofix message (empty on no-op,
+    descriptive on failure).
     """
     if not report_path.is_file():
         return ""
@@ -1351,7 +1429,7 @@ def _rerender_report_views_after_autofix(report_path: Path) -> str:
         scripts_dir = Path(__file__).resolve().parent.parent / "scripts"
         if str(scripts_dir) not in sys.path:
             sys.path.insert(0, str(scripts_dir))
-        from okstra_ctl.report_views import RunMeta, render_both_views
+        from okstra_ctl.report_views import RunMeta, render_html_view
         templates_dir = (
             Path(__file__).resolve().parent.parent / "templates" / "reports"
         )
@@ -1374,7 +1452,7 @@ def _rerender_report_views_after_autofix(report_path: Path) -> str:
         source_report=report_path.name,
     )
     try:
-        render_both_views(report_path, run_meta=meta, css=css, js=js)
+        render_html_view(report_path, run_meta=meta, css=css, js=js)
     except Exception as exc:  # noqa: BLE001
         return f"report-views re-render failed: {exc}"
     return "report-views re-rendered"
@@ -1445,6 +1523,11 @@ def main() -> int:
         failures.extend(autofix_messages)
     contract = extract_contract(run_manifest, task_manifest, failures)
     validate_team_state(team_state, project_root, contract, failures)
+    # Schema validation runs BEFORE markdown substring checks: if the
+    # data.json is well-formed, the rendered markdown is guaranteed to
+    # contain every required section. Substring checks below are a
+    # safety net for hand-edited or pre-v1.0 reports.
+    validate_final_report_data(report_path, failures)
     validate_report(report_path, contract["required_agent_status_entries"], failures)
     validate_team_state_usage(team_state, failures)
 

package/src/install.mjs

@@ -15,7 +15,7 @@ const SETTINGS_TEMPLATE_SRC_REL = ["templates", "reports", "settings.template.js
 // Destination under ~/.okstra/. Project-local .claude/settings.local.json symlinks here.
 const SETTINGS_TEMPLATE_DST_REL = ["templates", "settings.local.json"];
 
-const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
+const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "okstra_vendor", "lib"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
   "okstra-codex-exec.sh",
@@ -25,6 +25,8 @@ const BIN_ENTRYPOINTS = [
   "okstra-token-usage.py",
   "okstra-error-log.py",
   "okstra-render-report-views.py",
+  "okstra-render-final-report.py",
+  "okstra-wrapper-status.py",
 ];
 
 const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
@@ -40,6 +42,7 @@ Usage:
 Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/bin           <- runtime/bin
+  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
   ${"$HOME"}/.claude/agents/<worker>.md <- runtime/agents/workers/<worker>.md
@@ -550,10 +553,22 @@ export async function runInstall(args) {
     paths.bin,
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
+  // templates/ tree — report.css / report.js / *.template.md are consumed at
+  // runtime by okstra-render-report-views.py and final-report assembly. They
+  // are NOT covered by installSettingsTemplate (which only handles the
+  // editable settings.local.json sidecar), so without this step copy-mode
+  // installs miss every asset other than that single file. See
+  // okstra-render-report-views.py _TEMPLATES_DIRS for the lookup path.
+  const templatesResult = await copyTreeIfChanged(
+    join(runtimeRoot, "templates"),
+    join(paths.home, "templates"),
+    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
+  );
 
   if (!opts.quiet) {
     summarise("python", pythonResult, paths.pythonpath);
     summarise("bin", binResult, paths.bin);
+    summarise("templates", templatesResult, join(paths.home, "templates"));
   }
 
   if (pythonResult.missingSource && binResult.missingSource) {
@@ -561,6 +576,11 @@ export async function runInstall(args) {
       "warning: runtime/{python,bin} are both empty. Runtime sync (build step) has not been performed.\n",
     );
   }
+  if (templatesResult.missingSource) {
+    process.stderr.write(
+      "warning: runtime/templates is empty. report.css / report.js will be missing — re-run the build step.\n",
+    );
+  }
 
   const skillResult = await installSkillsCopy(runtimeRoot, opts);
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });