okstra 0.31.0 → 0.32.0

package/runtime/templates/reports/report.css

@@ -118,13 +118,19 @@ th, td {
   word-break: keep-all;
   overflow-wrap: anywhere;
   min-width: 5ch;
-}
-/* Short single-token cells (<= 20 plain chars) — keep on one line so
- * status / ID / kind columns do not get squeezed into narrow stacks
- * by long-form neighbours. Class is applied by report_views._emit_table. */
-td.td-tight, th.td-tight {
+  /* No max-width: cells that carry prose (statement / source / scope)
+   * absorb the remaining horizontal space within `main`'s 120ch. */
+}
+/* Narrow columns — header AND every body cell of this column fit
+ * within 30 plain chars (per `_narrow_columns()` in report_views.py).
+ * Examples: ID, Ticket ID, Kind, Status, Priority, Auto-spawn?,
+ * 에이전트, 역할, 모델, 상태. Pinning `width: 5%` makes these
+ * columns shrink toward the suggestion while wide neighbours absorb
+ * the remainder, so a long-prose row never squashes ID-style stacks
+ * into one-character ladders. */
+td.td-narrow, th.td-narrow {
+  width: 5%;
   white-space: nowrap;
-  width: 1%;  /* shrink-to-fit under auto-layout */
 }
 thead th {
   position: sticky;

package/runtime/validators/lib/fixtures.sh

@@ -366,21 +366,21 @@ report_lines.extend(
 report_path.parent.mkdir(parents=True, exist_ok=True)
 report_path.write_text("\n".join(report_lines) + "\n")
 
-# Phase 7 step 1.5 (BLOCKING) — render the slim/html sibling artifacts
-# next to the final-report so validate-run.py's new report-views hook
-# passes. The workflow validator's fixture predates that step; we
-# materialise both files in-place using the same single-reference-point
-# helper the CLI uses.
+# Phase 7 step 1.5 (BLOCKING) — render the html sibling artifact next
+# to the final-report so validate-run.py's report-views hook passes.
+# The workflow validator's fixture predates that step; we materialise
+# the html file in-place using the same single-reference-point helper
+# the CLI uses.
 import os
 WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
 if WORKSPACE_ROOT:
     import sys as _sys
     _sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
     try:
-        from okstra_ctl.report_views import RunMeta, render_both_views
+        from okstra_ctl.report_views import RunMeta, render_html_view
         css = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.css").read_text(encoding="utf-8")
         js = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.js").read_text(encoding="utf-8")
-        render_both_views(
+        render_html_view(
             report_path,
             run_meta=RunMeta(
                 task_key=str(task_manifest.get("taskKey", "validation/fixture")),

package/runtime/validators/validate-report-views.py

@@ -1,20 +1,17 @@
 #!/usr/bin/env python3
-"""Validate the two derived final-report views produced by Phase 7 step
-1.5 (``scripts/okstra-render-report-views.py``).
+"""Validate the self-contained HTML view produced by Phase 7 step 1.5
+(``scripts/okstra-render-report-views.py``).
 
 Checks, for a given final-report MD path:
-  1. ``*.slim.md`` and ``*.html`` siblings both exist.
-  2. Slim preserves every phase-required substring from ``validate-run.py``
-     byte-identically (drift fence vs the report_views module).
-  3. HTML body (``<main>`` slice) contains the same plain-text
-     substrings (after html.unescape and the markdown ``#`` prefix is
-     stripped).
-  4. HTML's §4.6 / §4.7 / §4.8 deliverable regions contain no
+  1. ``*.html`` sibling exists.
+  2. HTML's ``source-sha256`` in run-meta matches the current MD body —
+     stale html detection.
+  3. HTML's §4.6 / §4.7 / §4.8 deliverable regions contain no
      ``<textarea>`` / ``<input>`` / ``<select>`` (form-attach is
      restricted to §5 clarification rows).
-  5. HTML has no external URLs in ``<script src=>`` / ``<link href=>`` /
+  4. HTML has no external URLs in ``<script src=>`` / ``<link href=>`` /
      ``<img src=>`` — self-contained guarantee.
-  6. Every Response ID in HTML matches the §5 Clarification Items table
+  5. Every Response ID in HTML matches the §5 Clarification Items table
      of the source MD (1:1).
 
 Exit codes: 0 on success, 1 on any failure. Failures are printed one
@@ -23,12 +20,9 @@ per line to stderr.
 from __future__ import annotations
 
 import argparse
-import html as html_lib
-import importlib.util
 import re
 import sys
 from pathlib import Path
-from typing import Iterable
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 SCRIPTS_DIR = REPO_ROOT / "scripts"
@@ -37,31 +31,17 @@ if str(SCRIPTS_DIR) not in sys.path:
 
 from okstra_ctl.clarification_items import parse_clarification_items  # noqa: E402
 from okstra_ctl.report_views import (  # noqa: E402
-    _strip_leading_digest_comment,
     extract_html_digest,
-    extract_slim_digest,
-    preserved_substrings,
-    slim_markdown,
     source_digest,
 )
 
 
-def _load_validate_run() -> object:
-    """Dynamically load validate-run.py — it's a stand-alone script
-    with a hyphenated name, not an importable module. We snapshot the
-    substring lists from it so drift between the two files surfaces
-    here rather than silently in production."""
-    path = REPO_ROOT / "validators" / "validate-run.py"
-    spec = importlib.util.spec_from_file_location("_okstra_validate_run", path)
-    assert spec and spec.loader, f"cannot load {path}"
-    mod = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(mod)
-    return mod
-
+_EXTERNAL_URL_RE = re.compile(
+    r'<(?:script|link|img|iframe|source|video|audio)\s[^>]*?(?:src|href)\s*=\s*["\']https?://',
+    re.IGNORECASE,
+)
 
-def _detect_task_type(md: str) -> str | None:
-    m = re.search(r"^- Task Type:\s*(\S+)", md, re.MULTILINE)
-    return m.group(1).strip() if m else None
+_RESPONSE_ID_ATTR_RE = re.compile(r'data-response-id="(C-\d+)"')
 
 
 def _main_body(html_text: str) -> str:
@@ -72,25 +52,6 @@ def _main_body(html_text: str) -> str:
     return html_text[start + len("<main>"): end]
 
 
-def _strip_md_prefix(sub: str) -> str:
-    s = sub
-    while s.startswith("#"):
-        s = s[1:]
-    return s.strip()
-
-
-_EXTERNAL_URL_RE = re.compile(
-    r'<(?:script|link|img|iframe|source|video|audio)\s[^>]*?(?:src|href)\s*=\s*["\']https?://',
-    re.IGNORECASE,
-)
-
-_RESPONSE_ID_ATTR_RE = re.compile(r'data-response-id="(C-\d+)"')
-
-_NO_FORM_HEADING_RE = re.compile(
-    r"<h[23][^>]*>\s*(?:4\.6|4\.7|4\.8)[\s\S]*?</h[23]>"
-)
-
-
 def _no_form_sections(html_body: str) -> list[str]:
     """Return a list of strings, each being the rendered chunk of a
     no-form section (4.6 / 4.7 / 4.8) up to the next h2/h3. Used to
@@ -118,50 +79,21 @@ def validate(report_path: Path) -> list[str]:
         return [f"final-report not found: {report_path}"]
 
     md = report_path.read_text(encoding="utf-8")
-    task_type = _detect_task_type(md)
-    slim_path = report_path.with_name(report_path.stem + ".slim.md")
     html_path = report_path.with_name(report_path.stem + ".html")
 
-    # (1) sibling artifacts exist
-    if not slim_path.is_file():
-        failures.append(f"missing slim artifact: {slim_path}")
+    # (1) sibling artifact exists
     if not html_path.is_file():
-        failures.append(f"missing html artifact: {html_path}")
-    if failures:
-        return failures
+        return [f"missing html artifact: {html_path}"]
 
-    slim = slim_path.read_text(encoding="utf-8")
     html_text = html_path.read_text(encoding="utf-8")
     html_body = _main_body(html_text)
-    html_body_text = html_lib.unescape(html_body)
 
-    # (2a) source-digest staleness — both derived views must carry the
-    # sha256 of the artifact derived from the *current* MD. A mismatch
-    # means the views were rendered against an older MD body and Phase
-    # 7 step 1.5 was not re-run.
-    #   - HTML digest is over the MD body (after stripping any stale
-    #     leading digest comment), so the expected value is the digest
-    #     of the current MD itself.
-    #   - slim digest is over the slim BODY (so any byte-difference
-    #     between expected and actual slim shows up as a digest
-    #     mismatch). We recompute the expected slim and extract its
-    #     embedded digest for comparison — equivalent to but cheaper
-    #     than diffing the full body.
-    expected_md_digest = source_digest(_strip_leading_digest_comment(md))
-    expected_slim_digest = extract_slim_digest(
-        slim_markdown(md, task_type=task_type)
-    )
-    slim_digest = extract_slim_digest(slim)
+    # (2) source-digest staleness — html's run-meta source-sha256 must
+    # match the current MD's digest. Mismatch means the html was
+    # rendered against an older MD body and Phase 7 step 1.5 was not
+    # re-run.
+    expected_md_digest = source_digest(md)
     html_digest = extract_html_digest(html_text)
-    if slim_digest is None:
-        failures.append(
-            "slim missing source-sha256 header — re-render with okstra render-views"
-        )
-    elif slim_digest != expected_slim_digest:
-        failures.append(
-            f"stale slim: body sha256 {slim_digest[:12]}… does not match "
-            f"current MD's rendered slim {str(expected_slim_digest)[:12]}…"
-        )
     if html_digest is None:
         failures.append(
             "html missing source-sha256 in run-meta — re-render with okstra render-views"
@@ -172,31 +104,7 @@ def validate(report_path: Path) -> list[str]:
             f"current MD {expected_md_digest[:12]}…"
         )
 
-    # (2b) drift fence: report_views.preserved_substrings(task_type)
-    #      must agree with validate-run.py's tuples for the same task_type.
-    vr = _load_validate_run()
-    drift = _diff_substring_lists(task_type, vr)
-    failures.extend(drift)
-
-    # (3) slim preserves every required substring byte-identically
-    for sub in preserved_substrings(task_type):
-        if sub in md and sub not in slim:
-            failures.append(f"slim dropped required substring: {sub!r}")
-        # Also forward-check against validate-run.py's tuples so a
-        # future addition there fails this validator immediately.
-    for sub in _validate_run_substrings(task_type, vr):
-        if sub in md and sub not in slim:
-            failures.append(f"slim dropped validate-run substring: {sub!r}")
-
-    # (4) html preserves the same set (modulo md prefix + html.escape)
-    for sub in preserved_substrings(task_type):
-        if sub not in md:
-            continue
-        needle = _strip_md_prefix(sub)
-        if needle not in html_body_text:
-            failures.append(f"html body dropped substring: {needle!r}")
-
-    # (5) deliverable sections contain no form controls
+    # (3) deliverable sections contain no form controls
     for chunk in _no_form_sections(html_body):
         if "<textarea" in chunk or "<input" in chunk or "<select" in chunk:
             failures.append(
@@ -204,11 +112,11 @@ def validate(report_path: Path) -> list[str]:
             )
             break
 
-    # (6) no external URLs in <script src> / <link href> / etc.
+    # (4) no external URLs in <script src> / <link href> / etc.
     if _EXTERNAL_URL_RE.search(html_text):
         failures.append("html contains external URL in script/link/img — must be self-contained")
 
-    # (7) Response ID parity: HTML form rows ↔ §5 C-* rows in MD.
+    # (5) Response ID parity: HTML form rows ↔ §5 C-* rows in MD.
     # Bidirectional — catches both "MD has C-* the HTML lost" AND
     # "HTML has stale C-* that the current MD no longer declares".
     md_ids = _md_response_ids(md)
@@ -221,43 +129,6 @@ def validate(report_path: Path) -> list[str]:
     return failures
 
 
-def _validate_run_substrings(task_type: str | None, vr) -> Iterable[str]:
-    if task_type == "implementation":
-        return getattr(vr, "IMPLEMENTATION_REQUIRED_SECTIONS", ())
-    if task_type == "final-verification":
-        return getattr(vr, "FINAL_VERIFICATION_REQUIRED_SECTIONS", ())
-    return ()
-
-
-def _diff_substring_lists(task_type: str | None, vr) -> list[str]:
-    """Surface drift between report_views and validate-run substring
-    tuples. The two MUST stay in lock-step."""
-    failures: list[str] = []
-    from okstra_ctl.report_views import (
-        PRESERVED_SUBSTRINGS_IMPLEMENTATION,
-        PRESERVED_SUBSTRINGS_FINAL_VERIFICATION,
-    )
-    impl_vr = set(getattr(vr, "IMPLEMENTATION_REQUIRED_SECTIONS", ()))
-    impl_rv = set(PRESERVED_SUBSTRINGS_IMPLEMENTATION)
-    if impl_vr != impl_rv:
-        missing_in_views = impl_vr - impl_rv
-        extra_in_views = impl_rv - impl_vr
-        failures.append(
-            "drift: PRESERVED_SUBSTRINGS_IMPLEMENTATION vs validate-run "
-            f"IMPLEMENTATION_REQUIRED_SECTIONS — missing in views {missing_in_views or '∅'}, "
-            f"extra in views {extra_in_views or '∅'}"
-        )
-    fv_vr = set(getattr(vr, "FINAL_VERIFICATION_REQUIRED_SECTIONS", ()))
-    fv_rv = set(PRESERVED_SUBSTRINGS_FINAL_VERIFICATION)
-    if fv_vr != fv_rv:
-        failures.append(
-            "drift: PRESERVED_SUBSTRINGS_FINAL_VERIFICATION vs validate-run "
-            f"FINAL_VERIFICATION_REQUIRED_SECTIONS — missing in views {fv_vr - fv_rv or '∅'}, "
-            f"extra in views {fv_rv - fv_vr or '∅'}"
-        )
-    return failures
-
-
 def _md_response_ids(md: str) -> list[str]:
     items = parse_clarification_items(md) or []
     return sorted({it.row_id for it in items if re.fullmatch(r"C-\d+", it.row_id)})
@@ -265,7 +136,7 @@ def _md_response_ids(md: str) -> list[str]:
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
-        description="Validate slim/html derived views of an okstra final-report."
+        description="Validate the self-contained HTML view of an okstra final-report."
     )
     parser.add_argument(
         "report_path",

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,7 @@ 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",
 ];
 
@@ -41,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
@@ -551,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) {
@@ -562,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 });