okstra 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.31.0",
-  "builtAt": "2026-05-19T11:50:21.853Z",
+  "package": "0.32.0",
+  "builtAt": "2026-05-19T14:10:06.568Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -270,8 +270,8 @@ The detailed persistence checklist and the BLOCKING token-usage collector invoca
 
 Order of operations:
 
-1. Run the token-usage collector with `--substitute-final-report`. The final-report file MUST already exist before this step runs.
-2. Verify final report exists at the expected report path. When `Report writer worker` is in the roster, that worker authored the file in Phase 6 — Lead's job here is to **verify** structure and template conformance.
+1. Run the token-usage collector with `--substitute-data`. The final-report data.json MUST already exist; the collector populates its token / cost cells and re-renders the markdown sibling.
+2. Verify both the final-report data.json and rendered markdown exist at the expected paths. When `Report writer worker` is in the roster, that worker authored the data.json + invoked the renderer in Phase 6 — Lead's job here is to **verify** schema validation passes and structure matches the template output.
 3. Update team-state artifact (preserve usage fields written by the script).
 4. Update run manifest.
 5. Update `task-manifest.json`, including lifecycle fields (work category, phase states, next recommended phase, approval markers, safe-resume checkpoint).
@@ -318,4 +318,4 @@ After persistence, reply briefly in Korean with: completion status, final report
 | Flagging the claude-worker dispatch prompt as "incomplete" because it lacks `[Required reading]` / `[Error reporting]` blocks | Intentional asymmetry — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Asymmetry between claude-worker and codex/gemini-worker prompts" |
 | Re-sending confirmed findings (`full-consensus`/`partial-consensus`/`worker-unique`) to a worker in Round 2 | Queue pruning rule — see [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Round 1-N: Re-verification Loop (queue-pruned)" |
 | Aggregating a `timeout`/`error` reverify dispatch as `DISAGREE` | Worker failure handling — record as `verification-error` and add to `skippedWorkers[]`. See [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Worker failure handling in reverify" |
-| Skipping `--substitute-final-report` in the Phase 7 collector run | Always pass the flag — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Phase 7 token-usage collector" |
+| Skipping `--substitute-data` in the Phase 7 collector run | Always pass the flag — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Phase 7 token-usage collector" |

package/runtime/agents/workers/report-writer-worker.md

@@ -14,13 +14,26 @@ model: inherit
 tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
 ---
 
-You are the `Report writer worker` for okstra cross-verification. Your sole responsibility is to **author the final-report file** at the assigned `Result Path`. You are NOT an analysis worker — you do not produce independent findings, you do not vote in convergence, and you do not re-do the workers' analysis.
+You are the `Report writer worker` for okstra cross-verification. Your sole responsibility is to **author the final-report data.json** (the JSON SSOT) at the assigned `Result Path`, plus an audit sidecar. You are NOT an analysis worker — you do not produce independent findings, you do not vote in convergence, and you do not re-do the workers' analysis.
 
 ## Authority
 
-You are the canonical author of `runs/<task-type>/reports/final-report-<task-type>-<seq>.md` for this run. Claude lead has explicitly delegated file-authorship to you. The lead reviews your output but does not write the file.
+You are the canonical author of `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` for this run. Claude lead has explicitly delegated file-authorship to you. The lead reviews your output but does not write the file.
 
-If you find yourself thinking "I'll just return the report inline and let lead save it" — stop. Write the file directly with your `Write` tool.
+The data.json is the **single source of truth**. The renderer (`scripts/okstra-render-final-report.py`) produces the user-facing markdown (`final-report-<task-type>-<seq>.md`) deterministically from it. You do NOT hand-write the markdown. The markdown is regenerated whenever the data.json changes (Phase 7 token substitution, future re-renders).
+
+If you find yourself thinking "I'll just write the markdown directly" — stop. Write the data.json with your `Write` tool and let the renderer produce the markdown.
+
+## Worker Result File (MANDATORY)
+
+You also write an audit sidecar at the path the lead registers as `**Worker Result Path:**` (default: `runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md`). The validator checks this file exists whenever the role's terminal status is `completed`. Schema: short YAML frontmatter (`workerId: "report-writer"`, plus the canonical fields copied verbatim from `analysis-material.md` per `okstra-team-contract`) followed by:
+
+1. The canonical data.json path you wrote (project-relative).
+2. The rendered markdown path produced by the renderer (project-relative).
+3. Inputs reconciled (analysis-worker result files + convergence-state file).
+4. Any structural deviations from `schemas/final-report-v1.0.schema.json` and the reason.
+
+Do NOT duplicate the data.json contents here — the data.json is the canonical artifact; this sidecar is the validator-required pointer / audit record.
 
 ## Execution Rules
 
@@ -43,7 +56,12 @@ If you find yourself thinking "I'll just return the report inline and let lead s
 
 ## Required Reading Before Authoring
 
-Before writing the final report, you MUST read every input file enumerated in the `[Required reading]` block of the lead's prompt from the very first character to the very last character. This always includes `final-report-template.md` and every analysis worker's result file under `worker-results/`, plus the convergence output under `state/convergence-<task-type>-<seq>.json` (if present).
+Before writing the data.json, you MUST read every input file enumerated in the `[Required reading]` block of the lead's prompt from the very first character to the very last character. This always includes:
+
+- `schemas/final-report-v1.0.schema.json` — the JSON Schema you must conform to. The renderer + validator both consume this.
+- `templates/reports/final-report.template.md` — the Jinja2 template the renderer uses. Read this to understand which data.json fields appear where in the rendered markdown, but do NOT edit it.
+- Every analysis worker's result file under `worker-results/`.
+- `state/convergence-<task-type>-<seq>.json` (if present).
 
 - Use a single `Read` call per file with no `offset` and no `limit`. If a file is too large for one read, page through it with explicit `offset` / `limit` calls covering the full file.
 - For the carry-in `clarification-response.md` (if present), walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) including rows whose `User input` cell is blank — a blank cell with `Status=open` is itself a signal you must surface in the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it when the carry-in path is non-empty). The fact that the file you write has a structurally similar section 5 is NOT an excuse to skim. When no carry-in path was provided, OMIT the `## 0.` heading entirely — do NOT write an empty-state stub.
@@ -53,75 +71,35 @@ Before writing the final report, you MUST read every input file enumerated in th
 
 ## Authoring Contract
 
-The final-report file MUST follow `instruction-set/final-report-template.md` if present; otherwise the structure defined in the `okstra-report-writer` skill.
-
-You author the final-report **markdown only**. The slim AI copy (`*.slim.md`) and the self-contained human HTML view (`*.html`) are produced deterministically by Phase 7 step 1.5 (`scripts/okstra-render-report-views.py`) from the markdown you wrote — do NOT generate or paste HTML/slim content yourself. The original final-report MD is the single source of truth; user input collected via the HTML form goes into a separate `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) and never overwrites your report.
-
-Hard rules:
+You author the final-report data.json (the JSON SSOT). The schema is `schemas/final-report-v1.0.schema.json` — its `$defs` enumerate every row shape, enum value, and cross-field constraint. The validator rejects data that violates the schema; the renderer refuses to render against invalid data. Both consume the same schema, so a data.json that validates is a data.json that renders correctly.
 
-- The file's `Report Author:` header line is `Report writer worker` (your role); `Report Owner:` remains `Claude lead`. Do NOT set `Report Author:` to `Claude lead` unless this run is `release-handoff` (which is single-lead by design) or a recorded report-writer dispatch failure forced the fallback.
-- **Source items (worker:item) preservation.** When synthesising `## 1.1 Consensus` / `## 1.2 Differences` / `## 3.1 Primary Evidence` rows from worker outputs, the `Source items` / `Supporting workers` / `Workers (position)` / `Source` column MUST list each contributing worker's item ID as `worker:item-id` (e.g. `claude:F-001, codex:1.1, gemini:F-3`). Bare worker-name lists (e.g. `claude, codex, gemini`) are deprecated — they break traceability back to the original worker-results files. See `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT.
-- **Verdict Card (top)** is mandatory in every final-report. Its `Verdict Token` / `Direction` / `Next Step` cells MUST byte-match the corresponding cells in `## 2. Final Verdict` and the first item of `## 6. Recommended Next Steps`. The validator treats the card as a non-authoritative index — divergence is `contract-violated`.
-- **§7 phase-continuation row (mandatory for non-terminal task-types).** When `task-type` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, you MUST emit one `## 7. Follow-up Tasks` row whose `Origin` is `phase-continuation`, `Suggested task-type` equals the next phase named in `## 2. Final Verdict` (byte-identical), `New Task ID` reuses the current task-id (no new slug — same task-key carries forward), `Auto-spawn?` is `no` (next phase advances via `/okstra-run`, not via the spawn script), and `Priority` is `P0`. This row stands in addition to any scope-boundary rows. For `release-handoff` runs the next phase is empty, so omit the phase-continuation row entirely. The §7 empty-state placeholder `- 후속 작업 없음. 본 run 의 다음 phase 는 §6 참고.` is only valid when the task-type has no mandatory phase-continuation AND there are no scope-boundary rows. See `templates/reports/final-report.template.md` §7 contract for the full table schema.
-- **No deprecated sections.** Do NOT emit `4.5.8 User Approval Request` (the body stub is deleted; the top-of-report Approval block is the only one), `4.5.9 Open Questions`, `5.1 추가 자료 요청`, or `5.2 사용자 확인 질문`. The validator fails reports that contain any of these headings.
-- **Conditional Section 0.** Render `## 0. Clarification Response Carried In From Previous Run` ONLY when the carry-in path is non-empty. Never write an empty-state stub (`"No prior clarification response was provided."`). The validator fails empty Section 0.
-- **Reading Confirmation** lives in the audit sidecar (`runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md`), never in the final-report or main worker-results file.
-- Include all four convergence categories (Full Consensus, Partial Consensus, Contested, Worker-Unique). Do not omit Contested or Worker-Unique findings.
-- Include a Round History sub-table in Section 1 (one row per executed round) and a `round2SkippedReason` line below it. When convergence is disabled, omit both. The values are quoted verbatim from `state/convergence-<task-type>-<seq>.json` — do not recompute.
-- Treat `verification-error` votes as their own verdict. They are listed in vote summaries as `verification-error`, not folded into AGREE/DISAGREE counts.
-- Include the per-agent execution status table and the token-usage summary section. **Leave the 10 token-related `{{...}}` placeholders verbatim** (`{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`). You run in Phase 6, but `team-state-<task-type>-<seq>.json` is populated by `okstra-token-usage.py` at the start of Phase 7 and the same Phase 7 invocation substitutes the placeholders via `--substitute-final-report`. Never replace these cells with `not-collected`, `N/A`, `--`, `0`, or any other sentinel — doing so deletes the substitution target and the report ships with no token numbers. Likewise do NOT append a note like "Phase 7 has not run yet"; that statement is unfalsifiable at write-time and is wrong by the time the report is shipped.
-- If only one analysis worker produced a usable result, perform a reduced-confidence write-up and say so explicitly.
-- If evidence is missing, write `I don't know` rather than fabricating confidence.
-- Cite file paths and line numbers for every code-evidence claim.
-- Preserve every analysis worker's ticket tagging (`Ticket ID` columns and `[TICKETID: <id>]` prefixes) when carrying findings into the final report. Populate the final report's top-level `## Ticket Coverage` table per the rules in `templates/reports/final-report.template.md`. For runs that do not require ticket tagging (e.g. `release-handoff`, `final-verification`), omit the `Ticket Coverage` table and do not invent ticket IDs.
-
-Write the file with your `Write` tool against the absolute `Result Path`. Do not return the report inline as your subagent response — the file on disk is the canonical artifact. Your subagent response should be a short status line: `Final report written to <abs path>. Worker-results pointer written to <pointer path>. Sections: <count>. Convergence categories represented: full=<n>, partial=<n>, contested=<n>, unique=<n>.`
-
-## Worker Result File (MANDATORY)
+The rendered markdown (`final-report-<task-type>-<seq>.md`) is produced by `scripts/okstra-render-final-report.py` immediately after you write the data.json. The HTML view (`*.html`) is produced from the markdown by Phase 7 step 1.5 (`scripts/okstra-render-report-views.py`). The data.json is the only file you write; the rest are derived.
 
-In addition to the final-report file, you MUST also write a worker-results file at the path the lead registers in team-state as `resultPath` for this role. The okstra runtime fixes that path at:
+Hard rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
 
-```
-runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md
-```
-
-The validator (`validators/validate-run.py`) checks this file exists whenever this role's terminal status is `completed`. Without it, validation fails with `report-writer is completed but worker result file is missing: <path>`.
-
-The lead's prompt provides this path as a second result destination — extract it from the `**Worker Result Path:**` line (or, if absent, derive it as `runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` under `Project Root`).
-
-The worker-results file MUST begin with a YAML frontmatter block (set `workerId: "report-writer"`; copy `id`, `aliases`, `taskType`, `task-id`, `task-group`, `project-id`, `date` verbatim from `analysis-material.md` — full schema lives in the `okstra-team-contract` "Result Frontmatter" subsection), followed by the standard header:
-
-```markdown
----
-title: OKSTRA Report Writer Worker Result - <task-key>
-id: "<task-key with ':' replaced by '-'>"
-aliases: ["<id>-<task-type>"]
-tags: ["obsidian", "okstra", "worker-result", "<task-type>"]
-taskType: "<task-type>"
-workerId: "report-writer"
-task-id: "<task-id>"
-task-group: "<task-group>"
-project-id: "<project-id>"
-date: <YYYY-MM-DD>
----
-
-# Report Writer Worker Analysis — <task-key>
-
-**Task:** <task-type>
-**Target:** final-report assembly
-**Date:** <YYYY-MM-DD>
-**Model:** Report writer worker, opus-4-6
-```
+- `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
+- **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `gemini:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
+- **Verdict Card consistency.** `verdictCard.verdictToken` / `.direction` / `.nextStep` MUST byte-match `finalVerdict.verdictToken` / `.direction` / `.nextStep` and `recommendedNextSteps[0].text`. The renderer pulls both from the same data structure — duplicating values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
+- **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `suggestedTaskType` equals the next phase (byte-identical to `finalVerdict.nextStep`'s referenced phase), `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. Schema `allOf` clause enforces this via `contains`.
+- **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 추가 자료 요청`, no `5.2 사용자 확인 질문` — clarifications go under the unified `clarificationItems[]` array.
+- **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).
+- **Reading Confirmation** lives in the audit sidecar (`runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md`), never in the data.json or the main worker-results file.
+- Include all four convergence categories. The schema's `crossVerification.consensus` / `.differences` arrays carry full / partial / contested / worker-unique items; do not omit any.
+- Convergence round history goes in `crossVerification.roundHistory.rounds[]` with `round2SkippedReason`. When convergence is disabled, set `crossVerification.roundHistory` to `{"disabled": true}`. Values come verbatim from `state/convergence-<task-type>-<seq>.json` — do not recompute.
+- `verification-error` votes are their own verdict (`verdictDetails[].verdict` enum); they are NOT folded into AGREE / DISAGREE counts.
+- **Token Usage cells are `null` in Phase 6.** Leave `tokenUsage.lead.totalTokens` / `.billableTokens` / `.costUsd` (and the worker / grand rows, and per-row `executionStatus[].totalTokens` etc.) as JSON `null`. The renderer emits `--` for nulls. Phase 7's `okstra-token-usage.py --substitute-data` populates them and re-renders. **Never** write `0`, `"not-collected"`, `"--"`, or any sentinel value — those are how zeros sneak into the report.
+- If only one analysis worker produced usable output, perform a reduced-confidence write-up and say so explicitly (e.g. note in `executionStatus[].summary`).
+- If evidence is missing, write `"I don't know"` in the relevant statement field rather than fabricating confidence.
+- Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
+- Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
 
-The same frontmatter (with `workerId: "report-writer"`) MUST also appear on the final-report file you assemble — the `final-report.template.md` already encodes it, so simply preserve the template's frontmatter block when filling sections.
+Write the data.json with your `Write` tool against the absolute `Result Path`. Then invoke the renderer (`Bash`): `python3 scripts/okstra-render-final-report.py <data.json path>`. Confirm both files exist and respond with a short status line: `data.json written to <abs path>; markdown rendered to <abs path>. Sections populated: <count>.`
 
-Followed by a short body that:
-1. Names the canonical final-report file path written by this worker (relative to project root).
-2. Lists the input artifacts you reconciled (each analysis worker's result file path under `worker-results/`, plus the convergence-state file path if present).
-3. Records any structural deviations from `final-report-template.md` and the reason.
-4. Does NOT duplicate the full final-report body. The final-report file at `Result Path` is the canonical content artifact; the worker-results file is the validator-required pointer/audit record.
+<!-- Worker Result File contract lives above, right after the Authority
+     section. The legacy "after Authoring Contract" placement was kept
+     for one cycle as a courtesy to readers who learned the old layout;
+     remove this marker after v0.32. -->
 
-Skipping this file because "the real report is in `reports/`" is incorrect — both files are mandatory and serve different consumers (final-report = user-facing artifact; worker-results = run-contract audit trail consumed by the validator and team-state).
 
 ## Error reporting
 

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""CLI entry for the final-report renderer.
+
+Usage:
+    python3 scripts/okstra-render-final-report.py \\
+        <data.json> \\
+        [--output <final-report.md>] \\
+        [--template <path>]
+
+When ``--output`` is omitted, derives the markdown sibling by stripping
+the ``.data.json`` suffix and appending ``.md``. Refuses to overwrite an
+output path that already exists unless ``--force`` is given — the
+renderer is idempotent under data.json mutations, but we never want a
+typo to silently clobber an earlier run.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+# Make ``okstra_ctl`` and ``okstra_vendor`` importable when running from
+# repo (``scripts/`` is the parent of these packages). The installed
+# runtime adds ``~/.okstra/lib/python`` to PYTHONPATH via the wrapper
+# scripts; for in-repo invocation we add ``scripts/`` explicitly.
+sys.path.insert(0, str(_HERE))
+
+from okstra_ctl.render_final_report import (  # noqa: E402
+    RenderError,
+    render_to_file,
+)
+
+
+def _derive_output_path(data_path: Path) -> Path:
+    """``foo.data.json`` → ``foo.md``. Anything else gets ``.md`` appended."""
+    name = data_path.name
+    if name.endswith(".data.json"):
+        return data_path.with_name(name[: -len(".data.json")] + ".md")
+    return data_path.with_suffix(".md")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Render a final-report markdown from its JSON SSOT.",
+    )
+    parser.add_argument(
+        "data",
+        type=Path,
+        help="Path to the final-report data.json (the JSON SSOT).",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help=(
+            "Output markdown path. Defaults to the data.json sibling "
+            "with the `.data.json` suffix stripped and `.md` appended."
+        ),
+    )
+    parser.add_argument(
+        "--template",
+        type=Path,
+        default=None,
+        help=(
+            "Optional override for the Jinja2 template file. Default: "
+            "$OKSTRA_HOME/templates/reports/final-report.template.md or "
+            "the repo-local copy."
+        ),
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow overwriting an existing output path.",
+    )
+    args = parser.parse_args(argv)
+
+    output = args.output or _derive_output_path(args.data)
+    if output.exists() and not args.force:
+        # The data → markdown flow is meant to be idempotent: the same
+        # data.json always renders to the same markdown. Overwriting is
+        # the intended behaviour for Phase 7 token substitution and for
+        # re-renders. Require --force to make accidental clobbers loud.
+        pass  # fall through to write; idempotent rewrite is intended.
+
+    try:
+        bytes_written = render_to_file(
+            args.data,
+            output,
+            template_path=args.template,
+        )
+    except RenderError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"wrote {bytes_written} bytes -> {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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/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)