okstra 0.30.3 → 0.32.0

package/runtime/bin/okstra-render-report-views.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
-"""CLI entrypoint for Phase 7 step 1.5 — render two derived views of
-an okstra final-report markdown.
+"""CLI entrypoint for Phase 7 step 1.5 — render the self-contained HTML
+view of an okstra final-report markdown.
 
 Usage:
   okstra-render-report-views.py <path-to-final-report.md>
@@ -13,9 +13,8 @@ When the optional flags are omitted, the script infers what it can from
 the report path (``runs/<task-type>/reports/final-report-<task-type>-<seq>.md``)
 and the report's frontmatter / ``- Task Key:`` / ``- Task Type:`` lines.
 
-Outputs (idempotent — overwrites):
-  - <stem>.slim.md  — token-saving copy for the next-phase lead prompt
-  - <stem>.html      — single-file self-contained HTML view
+Output (idempotent — overwrites):
+  - <stem>.html  — single-file self-contained HTML view
 
 This script is the canonical single-reference-point. The Node CLI
 (``bin/okstra render-views``) is a thin wrapper that spawns it.
@@ -44,12 +43,21 @@ if (SCRIPTS_DIR / "okstra_ctl" / "report_views.py").is_file():
 elif HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
     sys.path.insert(0, str(HOME_LIB))
 
-from okstra_ctl.report_views import RunMeta, render_both_views  # noqa: E402
+from okstra_ctl.report_views import RunMeta, render_html_view  # noqa: E402
 
 
+_OKSTRA_HOME = Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra")))
+# Search order:
+#   1) dev tree (`<repo>/templates/reports`) — wins when this script runs from
+#      a source checkout or a link-mode install (the symlinked bin entrypoint
+#      resolves __file__ back into the repo).
+#   2) install tree (`~/.okstra/templates/reports`) — populated by
+#      `okstra install` copy mode via src/install.mjs. The legacy
+#      `~/.okstra/lib/templates/reports` path was never written by any
+#      install flow and is gone.
 _TEMPLATES_DIRS = (
     REPO_ROOT / "templates" / "reports",
-    Path.home() / ".okstra" / "lib" / "templates" / "reports",
+    _OKSTRA_HOME / "templates" / "reports",
 )
 
 # task-type itself can contain hyphens (``implementation-planning``,
@@ -98,7 +106,7 @@ def _infer_from_body(text: str) -> dict[str, str]:
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
-        description="Render slim AI + self-contained HTML views of an okstra final-report."
+        description="Render the self-contained HTML view of an okstra final-report."
     )
     parser.add_argument("report_path", type=Path)
     parser.add_argument("--task-key", default=None)
@@ -119,8 +127,7 @@ def main(argv: list[str] | None = None) -> int:
 
     css, js = _load_assets()
     meta = RunMeta(task_key=task_key, task_type=task_type, seq=seq, source_report=source_report)
-    slim_path, html_path = render_both_views(report_path, run_meta=meta, css=css, js=js)
-    print(f"slim: {slim_path}")
+    html_path = render_html_view(report_path, run_meta=meta, css=css, js=js)
     print(f"html: {html_path}")
     return 0
 

package/runtime/bin/okstra-token-usage.py

@@ -36,7 +36,9 @@ from okstra_token_usage import (  # noqa: E402,F401
     gemini_session_total,
     iter_jsonl,
     na_block,
-    substitute_final_report,
+    populate_and_render,
+    populate_data_token_cells,
+    SubstituteRefusedError,
     usage_block,
     utc_now,
 )

package/runtime/python/lib/okstra/globals.sh

@@ -154,7 +154,7 @@ GEMINI_WORKER_MODEL_EXECUTION_VALUE=""
 REPORT_WRITER_MODEL_DISPLAY=""
 REPORT_WRITER_MODEL_EXECUTION_VALUE=""
 DEFAULT_WORKERS="claude,codex,report-writer"
-DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus}"
+DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus-4-6}"
 DEFAULT_CLAUDE_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CLAUDE_MODEL:-sonnet}"
 DEFAULT_CODEX_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CODEX_MODEL:-gpt-5.5}"
 DEFAULT_GEMINI_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_GEMINI_MODEL:-auto}"

package/runtime/python/lib/okstra/usage.sh

@@ -71,7 +71,7 @@ options:
   --yes                Skip interactive prompting and confirmation. Requires all required arguments.
   --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer
                       (Gemini worker is optional; add `gemini` explicitly, e.g. --workers claude,codex,gemini,report-writer)
-  --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
+  --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus-4-6
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
   --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
   --gemini-model       Model for Gemini worker. Default: OKSTRA_DEFAULT_GEMINI_MODEL or auto
@@ -98,7 +98,7 @@ options:
   -h, --help           Show this help.
 
 model defaults:
-  Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
+  Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus-4-6
   Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
   Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -0,0 +1,253 @@
+"""Mini JSON Schema validator for the final-report data.json.
+
+This is a deliberately narrow JSON Schema implementation that supports
+exactly the keywords used by ``schemas/final-report-v1.0.schema.json``:
+
+  type, required, properties, additionalProperties, enum, const, pattern,
+  minLength, minItems, maxItems, items, minimum, maximum, $ref ($defs),
+  oneOf, allOf, if/then/else, contains, not
+
+We do NOT depend on the ``jsonschema`` PyPI package because its
+dependency tree (``referencing``, ``rpds-py``) includes a Rust C
+extension which we would have to vendor or ship pre-built per platform.
+The ~250 lines below cover everything the final-report schema needs;
+strict spec compliance is not a goal — strict validation of OUR schema is.
+
+Error messages include the JSON pointer of the failing field so the
+report-writer can fix the exact data.json cell.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+class SchemaError(ValueError):
+    """Raised when a schema itself is malformed (e.g. a $ref points
+    nowhere). Distinct from a data validation failure.
+    """
+
+
+def _format_path(path: tuple[str | int, ...]) -> str:
+    if not path:
+        return "<root>"
+    parts: list[str] = []
+    for p in path:
+        if isinstance(p, int):
+            parts.append(f"[{p}]")
+        else:
+            parts.append(f".{p}" if parts else p)
+    return "".join(parts)
+
+
+_TYPE_PYTHON: dict[str, tuple[type, ...]] = {
+    "object": (dict,),
+    "array": (list,),
+    "string": (str,),
+    "integer": (int,),
+    "number": (int, float),
+    "boolean": (bool,),
+    "null": (type(None),),
+}
+
+
+def _check_type(value: Any, expected: str) -> bool:
+    if expected == "integer":
+        # JSON Schema treats booleans as not integer.
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    return isinstance(value, _TYPE_PYTHON.get(expected, ()))
+
+
+def _resolve_ref(ref: str, root: dict) -> dict:
+    """Resolve a ``#/$defs/Name`` style reference against ``root``."""
+    if not ref.startswith("#/"):
+        raise SchemaError(f"only local refs are supported, got: {ref}")
+    parts = ref[2:].split("/")
+    node: Any = root
+    for part in parts:
+        if not isinstance(node, dict) or part not in node:
+            raise SchemaError(f"$ref target not found: {ref}")
+        node = node[part]
+    if not isinstance(node, dict):
+        raise SchemaError(f"$ref target is not a schema: {ref}")
+    return node
+
+
+class _Validator:
+    def __init__(self, root_schema: dict):
+        self.root = root_schema
+        self.errors: list[str] = []
+
+    def validate(self, instance: Any, schema: dict, path: tuple[str | int, ...]) -> None:
+        # Handle $ref first — everything else is composed under the
+        # resolved schema.
+        if "$ref" in schema:
+            schema = _resolve_ref(schema["$ref"], self.root)
+
+        # const / enum: strict equality / membership.
+        if "const" in schema and instance != schema["const"]:
+            self._err(path, f"value is not equal to const {schema['const']!r}")
+        if "enum" in schema and instance not in schema["enum"]:
+            self._err(path, f"value {instance!r} is not in enum {schema['enum']!r}")
+
+        # type
+        type_keyword = schema.get("type")
+        if type_keyword is not None:
+            types = type_keyword if isinstance(type_keyword, list) else [type_keyword]
+            if not any(_check_type(instance, t) for t in types):
+                self._err(
+                    path,
+                    f"value of type {type(instance).__name__} is not of expected type(s) {types}",
+                )
+                return  # further checks would compound the error
+
+        # String constraints
+        if isinstance(instance, str):
+            min_length = schema.get("minLength")
+            if min_length is not None and len(instance) < min_length:
+                self._err(path, f"string length {len(instance)} < minLength {min_length}")
+            pattern = schema.get("pattern")
+            if pattern is not None and not re.search(pattern, instance):
+                self._err(path, f"string does not match pattern {pattern!r}")
+
+        # Numeric constraints
+        if isinstance(instance, (int, float)) and not isinstance(instance, bool):
+            minimum = schema.get("minimum")
+            if minimum is not None and instance < minimum:
+                self._err(path, f"value {instance} < minimum {minimum}")
+            maximum = schema.get("maximum")
+            if maximum is not None and instance > maximum:
+                self._err(path, f"value {instance} > maximum {maximum}")
+
+        # Object constraints
+        if isinstance(instance, dict):
+            self._validate_object(instance, schema, path)
+
+        # Array constraints
+        if isinstance(instance, list):
+            self._validate_array(instance, schema, path)
+
+        # Composition keywords
+        for sub in schema.get("allOf", []):
+            self.validate(instance, sub, path)
+            # `if/then/else` lives inside an allOf entry in our schemas.
+            if "if" in sub:
+                self._validate_conditional(instance, sub, path)
+        if "if" in schema:
+            self._validate_conditional(instance, schema, path)
+        if "oneOf" in schema:
+            self._validate_one_of(instance, schema["oneOf"], path)
+        if "not" in schema:
+            self._validate_not(instance, schema["not"], path)
+
+    def _validate_object(self, instance: dict, schema: dict, path: tuple[str | int, ...]) -> None:
+        properties = schema.get("properties") or {}
+        required = schema.get("required") or []
+        for name in required:
+            if name not in instance:
+                self._err(path, f"required property '{name}' is missing")
+        for name, value in instance.items():
+            if name in properties:
+                self.validate(value, properties[name], path + (name,))
+            elif schema.get("additionalProperties") is False:
+                # Don't fire for keys we know are part of the conditional
+                # branches (we still validate values when they appear).
+                self._err(path, f"additional property '{name}' is not allowed")
+
+    def _validate_array(self, instance: list, schema: dict, path: tuple[str | int, ...]) -> None:
+        min_items = schema.get("minItems")
+        if min_items is not None and len(instance) < min_items:
+            self._err(path, f"array length {len(instance)} < minItems {min_items}")
+        max_items = schema.get("maxItems")
+        if max_items is not None and len(instance) > max_items:
+            self._err(path, f"array length {len(instance)} > maxItems {max_items}")
+        items = schema.get("items")
+        if items is not None:
+            for i, value in enumerate(instance):
+                self.validate(value, items, path + (i,))
+        contains = schema.get("contains")
+        if contains is not None and not any(
+            self._matches(value, contains) for value in instance
+        ):
+            self._err(path, f"array does not contain any item matching {self._summarise(contains)}")
+
+    def _validate_conditional(self, instance: Any, schema: dict, path: tuple[str | int, ...]) -> None:
+        if_schema = schema.get("if")
+        if if_schema is None:
+            return
+        if self._matches(instance, if_schema):
+            then_schema = schema.get("then")
+            if then_schema is not None:
+                self.validate(instance, then_schema, path)
+        else:
+            else_schema = schema.get("else")
+            if else_schema is not None:
+                self.validate(instance, else_schema, path)
+
+    def _validate_one_of(self, instance: Any, branches: list[dict], path: tuple[str | int, ...]) -> None:
+        matches = sum(1 for b in branches if self._matches(instance, b))
+        if matches != 1:
+            self._err(
+                path,
+                f"oneOf matched {matches} branches (expected exactly 1); "
+                f"branches: {[self._summarise(b) for b in branches]}",
+            )
+
+    def _validate_not(self, instance: Any, sub_schema: dict, path: tuple[str | int, ...]) -> None:
+        if self._matches(instance, sub_schema):
+            self._err(path, f"value must NOT match {self._summarise(sub_schema)}")
+
+    def _matches(self, instance: Any, schema: dict) -> bool:
+        """Cheap 'does this validate' probe used by if/oneOf/contains.
+        Returns True iff the sub-schema produces zero errors. Does not
+        mutate ``self.errors``.
+        """
+        probe = _Validator(self.root)
+        probe.validate(instance, schema, ())
+        return not probe.errors
+
+    @staticmethod
+    def _summarise(schema: dict) -> str:
+        keys = sorted(k for k in schema if k not in ("description", "$comment"))
+        return "{" + ", ".join(f"{k}={schema[k]!r}" for k in keys[:3]) + "}"
+
+    def _err(self, path: tuple[str | int, ...], message: str) -> None:
+        self.errors.append(f"{_format_path(path)}: {message}")
+
+
+def validate(data: Any, schema: dict) -> list[str]:
+    """Validate ``data`` against ``schema``. Returns the list of human-
+    readable error messages (empty when the data is valid)."""
+    v = _Validator(schema)
+    v.validate(data, schema, ())
+    return v.errors
+
+
+def load_schema(schema_path: Path | None = None) -> dict:
+    """Load the final-report schema. If ``schema_path`` is None, locate
+    ``schemas/final-report-v1.0.schema.json`` relative to this file's
+    repo root.
+    """
+    if schema_path is None:
+        here = Path(__file__).resolve()
+        for parent in [here, *here.parents]:
+            candidate = parent / "schemas" / "final-report-v1.0.schema.json"
+            if candidate.is_file():
+                schema_path = candidate
+                break
+        if schema_path is None:
+            raise SchemaError(
+                "could not locate schemas/final-report-v1.0.schema.json"
+            )
+    return json.loads(Path(schema_path).read_text(encoding="utf-8"))
+
+
+def validate_data_file(data_path: Path, schema_path: Path | None = None) -> list[str]:
+    """Convenience wrapper: read data.json, return validation errors."""
+    schema = load_schema(schema_path)
+    data = json.loads(Path(data_path).read_text(encoding="utf-8"))
+    return validate(data, schema)

package/runtime/python/okstra_ctl/models.py

@@ -11,6 +11,8 @@ CLAUDE_MAPPING = {
     "opus": ("opus", "opus"),
     "opus-4-7": ("opus-4-7", "claude-opus-4-7"),
     "claude-opus-4-7": ("opus-4-7", "claude-opus-4-7"),
+    "opus-4-6": ("opus-4-6", "claude-opus-4-6"),
+    "claude-opus-4-6": ("opus-4-6", "claude-opus-4-6"),
     "sonnet": ("sonnet", "sonnet"),
     "sonnet-4-6": ("sonnet-4-6", "claude-sonnet-4-6"),
     "claude-sonnet-4-6": ("sonnet-4-6", "claude-sonnet-4-6"),

package/runtime/python/okstra_ctl/render_final_report.py

@@ -0,0 +1,201 @@
+"""Render `final-report-<task-type>-<seq>.md` from its JSON SSOT.
+
+The JSON SSOT lives next to the rendered markdown as
+``final-report-<task-type>-<seq>.data.json``. The schema for that file is
+``schemas/final-report-v1.0.schema.json``. Report-writer-worker writes the
+data.json in Phase 6; this renderer + the Jinja2 template at
+``templates/reports/final-report.template.md`` deterministically produce
+the canonical user-facing markdown.
+
+Why this exists: prior to v0.32, report-writer-worker wrote the markdown
+directly. Free-form authoring led to silent contract violations — missing
+columns in the Execution Status table, omitted §7 phase-continuation
+rows, invented ``## Index`` sections. Routing everything through one
+template + schema cuts those failure modes to zero.
+
+Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
+the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
+data.json, then re-invokes this renderer so the markdown stays in sync.
+The markdown is never hand-edited.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+# Vendored jinja2 must be importable. The installer (``src/install.mjs``)
+# drops ``okstra_vendor/`` under ``~/.okstra/lib/python/``; in-repo runs
+# rely on ``scripts/`` being on PYTHONPATH. Either way the package
+# registers ``markupsafe`` and ``jinja2`` aliases in ``sys.modules`` so
+# downstream ``from jinja2 import ...`` resolves to the vendored copy.
+import okstra_vendor  # noqa: F401 — side effect: sys.modules aliases
+from jinja2 import ChainableUndefined, Environment, FileSystemLoader
+from jinja2 import select_autoescape  # noqa: F401 — kept for future HTML use
+
+
+DEFAULT_TEMPLATE_REL = ("templates", "reports", "final-report.template.md")
+
+
+class RenderError(RuntimeError):
+    """Raised when the data.json cannot be rendered. Wraps jinja2 errors
+    and IO errors with a single user-facing message so the CLI / Phase 6
+    surface one consistent failure shape.
+    """
+
+
+def _format_int(value: Any) -> str:
+    if value is None:
+        return "--"
+    try:
+        return f"{int(value):,}"
+    except (TypeError, ValueError):
+        return "--"
+
+
+def _format_usd(value: Any) -> str:
+    if value is None:
+        return "--"
+    try:
+        return f"${float(value):.2f}"
+    except (TypeError, ValueError):
+        return "--"
+
+
+def _format_duration_ms(value: Any) -> str:
+    if value is None:
+        return "--"
+    try:
+        ms = int(value)
+    except (TypeError, ValueError):
+        return "--"
+    total_seconds = ms // 1000
+    minutes, seconds = divmod(total_seconds, 60)
+    return f"{minutes}m {seconds:02d}s"
+
+
+def _yaml_scalar(value: Any) -> str:
+    """Serialize a scalar for the YAML frontmatter block.
+
+    Strings: wrap in double quotes and escape embedded double-quote /
+    backslash so the YAML parser at consumer side (Obsidian / okstra
+    runtime) does not choke on accidental colons or square brackets in
+    the value. Bools / numbers / None: render as-is.
+    """
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    text = str(value)
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _yaml_inline_list(values: list[str]) -> str:
+    """Render a list of strings as a YAML flow-style sequence on one line."""
+    return "[" + ", ".join(_yaml_scalar(v) for v in values) + "]"
+
+
+def _build_environment(template_dir: Path) -> Environment:
+    # ChainableUndefined lets optional fields (e.g.
+    # ``clarificationCarryIn``, ``ticketCoverage.omit``) silently evaluate
+    # to false in `{% if %}` tests instead of raising. Strict presence
+    # checking is the schema validator's job, not the renderer's — and
+    # the renderer can't tell "the writer forgot this required field"
+    # from "this field is intentionally absent on this task-type".
+    env = Environment(
+        loader=FileSystemLoader(str(template_dir)),
+        undefined=ChainableUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+    )
+    env.filters["format_int"] = _format_int
+    env.filters["format_usd"] = _format_usd
+    env.filters["format_duration_ms"] = _format_duration_ms
+    env.filters["yaml_scalar"] = _yaml_scalar
+    env.filters["yaml_inline_list"] = _yaml_inline_list
+    return env
+
+
+def render(data: dict, *, template_path: Path) -> str:
+    """Render ``data`` through the Jinja2 ``template_path`` and return the
+    final markdown as a string. Caller writes it to disk.
+
+    Raises ``RenderError`` on any template / IO / data structural failure
+    so the surface is one exception type rather than the broad jinja2
+    hierarchy.
+    """
+    if not template_path.is_file():
+        raise RenderError(f"template not found: {template_path}")
+
+    env = _build_environment(template_path.parent)
+    try:
+        template = env.get_template(template_path.name)
+        return template.render(**data)
+    except Exception as exc:  # jinja2.TemplateError, KeyError, etc.
+        raise RenderError(
+            f"render failed for template {template_path.name}: {exc}"
+        ) from exc
+
+
+def find_default_template(start: Path | None = None) -> Path:
+    """Locate the bundled final-report template.
+
+    Resolution order:
+      1. ``$OKSTRA_HOME/templates/reports/final-report.template.md`` (installed runtime).
+      2. ``<repo>/templates/reports/final-report.template.md`` (in-repo dev runs).
+         Repo root is detected by walking up from this file until a
+         ``templates/reports/final-report.template.md`` exists.
+
+    Raises ``RenderError`` if neither path is present.
+    """
+    okstra_home = os.environ.get("OKSTRA_HOME")
+    if okstra_home:
+        candidate = Path(okstra_home).joinpath(*DEFAULT_TEMPLATE_REL)
+        if candidate.is_file():
+            return candidate
+
+    here = Path(start or __file__).resolve()
+    for parent in [here, *here.parents]:
+        candidate = parent.joinpath(*DEFAULT_TEMPLATE_REL)
+        if candidate.is_file():
+            return candidate
+
+    raise RenderError(
+        "could not locate final-report.template.md. Set OKSTRA_HOME or "
+        "run from a checkout that contains templates/reports/."
+    )
+
+
+def render_to_file(
+    data_path: Path,
+    output_path: Path,
+    *,
+    template_path: Path | None = None,
+) -> int:
+    """Read ``data_path`` (JSON), render through Jinja2, write to
+    ``output_path``. Returns the number of bytes written.
+
+    The output is written atomically (write-then-rename) so a partial
+    write never produces a half-corrupt final-report on disk.
+    """
+    if not data_path.is_file():
+        raise RenderError(f"data file not found: {data_path}")
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RenderError(f"invalid JSON in {data_path}: {exc}") from exc
+
+    resolved_template = template_path or find_default_template(data_path)
+    rendered = render(data, template_path=resolved_template)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = output_path.with_suffix(output_path.suffix + f".tmp.{os.getpid()}")
+    tmp.write_text(rendered, encoding="utf-8")
+    tmp.replace(output_path)
+    return len(rendered.encode("utf-8"))