okstra 0.28.0 → 0.30.0

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

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Validate the two derived final-report views 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
+     ``<textarea>`` / ``<input>`` / ``<select>`` (form-attach is
+     restricted to §5 clarification rows).
+  5. 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
+     of the source MD (1:1).
+
+Exit codes: 0 on success, 1 on any failure. Failures are printed one
+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"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+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
+
+
+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
+
+
+def _main_body(html_text: str) -> str:
+    start = html_text.find("<main>")
+    end = html_text.find("</main>", start) if start >= 0 else -1
+    if start < 0 or end < 0:
+        return html_text
+    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
+    check that no form controls live inside them.
+    """
+    chunks: list[str] = []
+    headings = [
+        m for m in re.finditer(
+            r'<h([23])[^>]*>([^<]*?)</h[23]>', html_body
+        )
+    ]
+    for i, m in enumerate(headings):
+        text = m.group(2).strip()
+        if not text.startswith(("4.6", "4.7", "4.8")):
+            continue
+        start = m.end()
+        end = headings[i + 1].start() if i + 1 < len(headings) else len(html_body)
+        chunks.append(html_body[start:end])
+    return chunks
+
+
+def validate(report_path: Path) -> list[str]:
+    failures: list[str] = []
+    if not report_path.is_file():
+        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}")
+    if not html_path.is_file():
+        failures.append(f"missing html artifact: {html_path}")
+    if failures:
+        return failures
+
+    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)
+    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"
+        )
+    elif html_digest != expected_md_digest:
+        failures.append(
+            f"stale html: source-sha256 {html_digest[:12]}… does not match "
+            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
+    for chunk in _no_form_sections(html_body):
+        if "<textarea" in chunk or "<input" in chunk or "<select" in chunk:
+            failures.append(
+                "html §4.6/§4.7/§4.8 deliverable section contains a form control"
+            )
+            break
+
+    # (6) 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.
+    # 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)
+    html_ids = sorted(set(_RESPONSE_ID_ATTR_RE.findall(html_text)))
+    if md_ids != html_ids:
+        failures.append(
+            f"Response ID mismatch: MD §5 has {md_ids}, HTML has {html_ids}"
+        )
+
+    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)})
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate slim/html derived views of an okstra final-report."
+    )
+    parser.add_argument(
+        "report_path",
+        type=Path,
+        help="Path to the original final-report markdown.",
+    )
+    args = parser.parse_args(argv)
+    failures = validate(args.report_path)
+    for f in failures:
+        print(f, file=sys.stderr)
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/validators/validate-run.py

@@ -832,6 +832,70 @@ PLANNING_REQUIRED_SECTIONS = (
     "Plan Body Verification",
 )
 
+# §4.7 implementation deliverables — substring scan against report body.
+IMPLEMENTATION_REQUIRED_SECTIONS = (
+    "Approved Plan Reference",
+    "Commit List",
+    "Diff Summary",
+    "Out-of-plan Edits",
+    "Validation Evidence",
+    "Verifier Results",
+    "Rollback Verification",
+    "Routing Recommendation",
+)
+
+# §4.8 final-verification deliverables — substring scan against report body.
+FINAL_VERIFICATION_REQUIRED_SECTIONS = (
+    "Source Implementation Report",
+    "Acceptance Blockers",
+    "Residual Risk",
+    "Validation Evidence",
+    "Read-only Command Log",
+    "Routing Recommendation",
+)
+
+# Allowed Verdict Token vocabulary, by task-type. `release-handoff` is
+# author-tagged but reads its entry gate from final-verification's report
+# and renders `not-applicable` itself.
+FINAL_VERIFICATION_VERDICT_TOKENS = (
+    "accepted",
+    "conditional-accept",
+    "blocked",
+)
+
+# `## 2. Final Verdict` Verdict Token cell — captures the value between
+# backticks on the `Verdict Token` row. Tolerant to extra column whitespace
+# and to leading bold/italic markers in the label cell.
+_FINAL_VERDICT_TOKEN_RE = re.compile(
+    r"^\|[ \t]*\*{0,2}Verdict Token\*{0,2}[ \t]*\|[ \t]*`(?P<value>[^`\n]*)`",
+    re.MULTILINE,
+)
+
+# Verdict Card Verdict Token row (top-of-report at-a-glance). Same shape
+# as `_FINAL_VERDICT_TOKEN_RE` but matched against the first occurrence in
+# the Verdict Card block, scoped to the body between `## Verdict Card`
+# heading and the next `##` heading.
+_VERDICT_CARD_BLOCK_RE = re.compile(
+    r"^##[ \t]+Verdict Card[ \t]*$\n(?P<body>.*?)(?=^##[ \t]|\Z)",
+    re.DOTALL | re.MULTILINE,
+)
+
+# `## 2. Final Verdict` block scope — used to scope the Verdict Token
+# regex so that we don't accidentally match a Verdict Token row that
+# lives in the Verdict Card or anywhere else.
+_FINAL_VERDICT_BLOCK_RE = re.compile(
+    r"^##[ \t]+2\.[ \t]+Final Verdict[ \t]*$\n(?P<body>.*?)(?=^##[ \t]|\Z)",
+    re.DOTALL | re.MULTILINE,
+)
+
+# `## 4.6 Release Handoff Deliverables` and `## 4.6.6 Merge Conflict
+# Probe` are required when task-type == release-handoff. The probe sub-
+# section was retro-added to the template; old runs that predate it ship
+# without it, but new runs must include it.
+_MERGE_CONFLICT_PROBE_HEADING_RE = re.compile(
+    r"^###[ \t]+4\.6\.6[ \t]+Merge Conflict Probe\b", re.MULTILINE
+)
+
 PLAN_VERIFY_GATE_VALUES = (
     "passed",
     "passed-with-dissent",
@@ -861,6 +925,92 @@ _APPROVAL_CHECKBOX_RE = re.compile(
 )
 
 
+def _extract_final_verdict_token(content: str) -> str | None:
+    """Return the `Verdict Token` cell value from the `## 2. Final Verdict`
+    block, or None when the row is absent. Scoped to §2 so the Verdict
+    Card row (which has the same shape) does not shadow the authoritative
+    value.
+    """
+    block = _FINAL_VERDICT_BLOCK_RE.search(content)
+    if block is None:
+        return None
+    match = _FINAL_VERDICT_TOKEN_RE.search(block.group("body"))
+    if match is None:
+        return None
+    return match.group("value")
+
+
+def _extract_verdict_card_token(content: str) -> str | None:
+    """Return the `Verdict Token` cell from the Verdict Card block."""
+    block = _VERDICT_CARD_BLOCK_RE.search(content)
+    if block is None:
+        return None
+    match = _FINAL_VERDICT_TOKEN_RE.search(block.group("body"))
+    if match is None:
+        return None
+    return match.group("value")
+
+
+def _validate_verdict_card_consistency(content: str, failures: list[str]) -> None:
+    """Verdict Card is a non-authoritative index of §2. If both blocks
+    carry a Verdict Token row, the values MUST byte-match (modulo case
+    and surrounding whitespace) — divergence is a contract violation per
+    `okstra-report-writer` SKILL.md "Authoring Contract".
+    """
+    card_value = _extract_verdict_card_token(content)
+    final_value = _extract_final_verdict_token(content)
+    if card_value is None or final_value is None:
+        # Missing-Card and missing-§2 are surfaced by other checks; this
+        # function only enforces the consistency contract between the two.
+        return
+    if card_value.strip().lower() != final_value.strip().lower():
+        failures.append(
+            "Verdict Card `Verdict Token` value "
+            f"`{card_value}` does not match `## 2. Final Verdict` value "
+            f"`{final_value}` — the Card is a non-authoritative index and "
+            "MUST byte-match §2. Either fix the Card or update §2; do not "
+            "ship divergent values."
+        )
+
+
+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``.
+
+    Delegated to that script as a subprocess so the contract surface
+    stays in one place. Failures from the delegate are folded back as
+    structured ``report-views: <line>`` failure strings.
+    """
+    import subprocess
+
+    here = Path(__file__).resolve().parent
+    delegate = here / "validate-report-views.py"
+    if not delegate.is_file():
+        # The delegate is part of the same install bundle; absence is
+        # itself a broken installation rather than an optional feature.
+        failures.append(
+            f"validate-report-views.py missing under {here} — okstra install incomplete"
+        )
+        return
+    try:
+        proc = subprocess.run(
+            [sys.executable, str(delegate), str(report_path)],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except subprocess.TimeoutExpired:
+        failures.append("report-views validator timed out (30s)")
+        return
+    if proc.returncode != 0:
+        for line in proc.stderr.splitlines():
+            line = line.strip()
+            if line:
+                failures.append(f"report-views: {line}")
+
+
 def validate_phase_boundary(
     task_type: str,
     report_path: Path,
@@ -880,11 +1030,55 @@ def validate_phase_boundary(
       MUST be absent (lead converted findings into Clarification rows
       instead of opening the gate).
     """
-    if task_type != "implementation-planning":
-        return
     if not report_path.exists():
         return
     content = report_path.read_text()
+
+    # Verdict Card vs §2. Final Verdict Verdict Token consistency. The Card
+    # is a non-authoritative index; divergence is a contract violation.
+    _validate_verdict_card_consistency(content, failures)
+
+    if task_type == "implementation":
+        for needle in IMPLEMENTATION_REQUIRED_SECTIONS:
+            if needle not in content:
+                failures.append(
+                    "implementation report is missing required §4.7 "
+                    f"deliverable section: `{needle}`"
+                )
+
+    if task_type == "final-verification":
+        for needle in FINAL_VERIFICATION_REQUIRED_SECTIONS:
+            if needle not in content:
+                failures.append(
+                    "final-verification report is missing required §4.8 "
+                    f"deliverable section: `{needle}`"
+                )
+        token_value = _extract_final_verdict_token(content)
+        if token_value is None:
+            failures.append(
+                "final-verification report `## 2. Final Verdict` table is "
+                "missing the `Verdict Token` row — required by the release-"
+                "handoff entry gate."
+            )
+        elif token_value.strip().lower() not in FINAL_VERIFICATION_VERDICT_TOKENS:
+            failures.append(
+                "final-verification report `Verdict Token` value "
+                f"`{token_value}` is not one of "
+                f"{', '.join(FINAL_VERIFICATION_VERDICT_TOKENS)}."
+            )
+
+    if task_type == "release-handoff":
+        if _MERGE_CONFLICT_PROBE_HEADING_RE.search(content) is None:
+            failures.append(
+                "release-handoff report is missing `### 4.6.6 Merge Conflict "
+                "Probe` sub-section — required by the release-handoff profile "
+                "(self-review 6, merge-conflict probe audit). When the run is "
+                "`local only` / `skip`, record the single line `- Not run "
+                "(user picked local only or skip).` under the heading."
+            )
+
+    if task_type != "implementation-planning":
+        return
     for needle in PLANNING_REQUIRED_SECTIONS:
         if needle not in content:
             failures.append(
@@ -1123,6 +1317,14 @@ def attempt_token_usage_autofix(
         return "accuracy-failed", [
             f"Phase 7 token-usage substitution refused: {exc}"
         ]
+
+    # 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
+    # downstream report-views validator does not trip over the
+    # autofix's own side effect.
+    rerender_note = _rerender_report_views_after_autofix(report_path)
+
     detail = (
         f"replaced {replaced} placeholder(s)"
         if replaced > 0
@@ -1130,7 +1332,52 @@ def attempt_token_usage_autofix(
         if replaced == 0
         else "report file missing"
     )
-    return "recovered", [f"usageSummary repopulated; {detail}"]
+    msg = f"usageSummary repopulated; {detail}"
+    if rerender_note:
+        msg += f"; {rerender_note}"
+    return "recovered", [msg]
+
+
+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).
+    """
+    if not report_path.is_file():
+        return ""
+    try:
+        # Late import — keeps validate-run.py importable in environments
+        # that don't ship report_views (older installs).
+        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
+        templates_dir = (
+            Path(__file__).resolve().parent.parent / "templates" / "reports"
+        )
+        css = (templates_dir / "report.css").read_text(encoding="utf-8")
+        js = (templates_dir / "report.js").read_text(encoding="utf-8")
+    except Exception as exc:  # noqa: BLE001 — best-effort
+        return f"report-views re-render skipped ({exc})"
+
+    # Infer task-key / task-type / seq from path + body when possible;
+    # fall back to placeholders so the digest comparison (the actual
+    # contract) still works.
+    text = report_path.read_text(encoding="utf-8")
+    task_type_m = re.search(r"^- Task Type:\s*(\S+)", text, re.MULTILINE)
+    task_key_m = re.search(r"^- Task Key:\s*(\S+)", text, re.MULTILINE)
+    seq_m = re.search(r"-(\d+)\.md$", report_path.name)
+    meta = RunMeta(
+        task_key=task_key_m.group(1) if task_key_m else "unknown",
+        task_type=task_type_m.group(1) if task_type_m else "unknown",
+        seq=seq_m.group(1) if seq_m else "000",
+        source_report=report_path.name,
+    )
+    try:
+        render_both_views(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"
 
 
 def main() -> int:
@@ -1205,6 +1452,7 @@ def main() -> int:
     validate_phase_boundary(task_type, report_path, failures)
     if task_type:
         validate_worker_results_audit(report_path, task_type, failures)
+    validate_report_views(report_path, failures)
 
     validation_status = "passed" if not failures else "failed"
     update_validation_metadata(

package/runtime/validators/validate-workflow.sh

@@ -109,6 +109,10 @@ fi
 pass "Primary task discovery artifacts are valid"
 
 step "Preparing validator fixture artifacts for the primary task"
+# Fixture needs to render Phase 7 step 1.5 sibling artifacts; pass the
+# repo root so the heredoc can import okstra_ctl.report_views and load
+# inline assets from templates/reports/.
+export OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE="$WORKSPACE_ROOT"
 if ! prepare_run_validator_fixture "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID" codex; then
   fail "Failed to prepare validator fixture artifacts for the primary task"
 fi

package/src/install.mjs

@@ -24,6 +24,7 @@ const BIN_ENTRYPOINTS = [
   "okstra-central.sh",
   "okstra-token-usage.py",
   "okstra-error-log.py",
+  "okstra-render-report-views.py",
 ];
 
 const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra

package/src/render-views.mjs

@@ -0,0 +1,67 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra render-views — render slim AI + self-contained HTML views of a final-report
+
+A thin spawn shim over \`scripts/okstra-render-report-views.py\` (installed
+at \`$HOME/.okstra/bin/okstra-render-report-views.py\`). Reads the final-
+report MD and writes two siblings:
+
+  <stem>.slim.md   — token-saving AI consumption copy
+  <stem>.html       — single-file self-contained human view with form
+                       controls on §5 clarification rows
+
+Usage:
+  okstra render-views <path-to-final-report.md>
+      [--task-key <key>] [--task-type <type>] [--seq <NNN>]
+      [--source-report <project-relative-path>]
+
+When the optional flags are omitted the script infers from the report
+path and its '- Task Type:' / '- Task Key:' lines.
+`;
+
+function resolveEntrypoint(paths) {
+  // Prefer the installed copy under ~/.okstra/bin (what production users
+  // see); fall back to the in-repo dev source when running from a
+  // checkout that hasn't been installed.
+  const installed = resolvePath(paths.home, "bin", "okstra-render-report-views.py");
+  if (existsSync(installed)) return installed;
+  const here = fileURLToPath(new URL("..", import.meta.url));
+  const dev = resolvePath(here, "scripts", "okstra-render-report-views.py");
+  if (existsSync(dev)) return dev;
+  return null;
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stderr.write("error: missing <path-to-final-report.md>\n");
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  const paths = await resolvePaths();
+  const entry = resolveEntrypoint(paths);
+  if (!entry) {
+    process.stderr.write(
+      "error: okstra-render-report-views.py not found. " +
+      "Run `okstra install` to install the runtime.\n",
+    );
+    return 1;
+  }
+  return await new Promise((res) => {
+    const child = spawn("python3", [entry, ...args], {
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+    child.on("error", (err) => {
+      process.stderr.write(`error: ${err.message}\n`);
+      res(1);
+    });
+    child.on("close", (code) => res(code ?? 0));
+  });
+}