okstra 0.146.1 → 0.148.0

package/docs/for-ai/skills/okstra-run.md

@@ -10,7 +10,7 @@
 
 ## Purpose
 
-`okstra-run` starts an okstra task run inside the current Claude Code session. Input collection is owned entirely by the `okstra wizard` state machine; the skill relays the wizard prompts to the user and then prepares the task bundle via `okstra render-bundle`. Once the bundle is ready, the current session takes over as Claude lead.
+`okstra-run` starts an okstra task run inside the current supported agent host. Input collection is owned entirely by the `okstra wizard` state machine; the skill relays the wizard prompts to the user and then prepares the task bundle via `okstra render-bundle`. Once the bundle is ready, the current Claude Code, Codex, or Antigravity session takes over as the host-native Okstra lead.
 
 Single authority:
 
@@ -34,10 +34,10 @@ Do not use it when:
 
 ## Preflight
 
-A single Bash call:
+Resolve `<host-runtime>` from the executing harness: Claude Code → `claude-code`, Codex → `codex`, Antigravity CLI → `antigravity`, and another adapter host → `external`. This is a host capability, not a `PATH` inference or worker-provider choice. The lead provider is derived from this value and cannot be selected independently. Then make one Bash call:
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime <host-runtime> --json
 ```
 
 If there is no runtime or project setup (`ok:false`), point the user to `/okstra-setup` and stop. Do not create an `export PYTHONPATH`.
@@ -73,7 +73,7 @@ Carry the printed absolute path verbatim.
 wizard init:
 
 ```bash
-okstra wizard init --state-file /tmp/okstra-wizard/state.json --project-root /abs/project --project-id project-id
+okstra wizard init --state-file /tmp/okstra-wizard/state.json --project-root /abs/project --project-id project-id --host-runtime <host-runtime>
 ```
 
 The result is `{ok, next}` JSON. The first step is `task_pick`.
@@ -130,34 +130,13 @@ When `next.kind == "done"`:
 okstra wizard outcome --state-file /tmp/okstra-wizard/state.json
 ```
 
-Run `outcome.persistActions[]` first, then pass each key of the `outcome.renderArgs` object as an `okstra render-bundle` flag. Pass empty string values explicitly too. Exception: the `chain-stages` key is not a render-bundle flag — it drives the Step 7 unattended-chaining loop, so do not pass it as a flag (`run.py` accepts only `--stage`/`--stages`). In the render-bundle block, `--stage` is implementation·final-verification only, and `--stages` is release-handoff only (empty value = whole-task).
+Run `outcome.persistActions[]` first, then pass each key of the `outcome.renderArgs` object exactly once as an `okstra render-bundle` flag. Pass empty string values explicitly too, and add `--lead-runtime <host-runtime>` from preflight. Do not enumerate provider-specific keys in this manual; the wizard and provider registry own the emitted arguments. Exception: the `chain-stages` key is not a render-bundle flag — it drives the Step 7 unattended-chaining loop, so do not pass it as a flag (`run.py` accepts only `--stage`/`--stages`).
 
 ```bash
 okstra render-bundle \
-  --lead-runtime claude-code \
-  --project-root "<args.project-root>" \
-  --project-id "<args.project-id>" \
-  --task-group "<args.task-group>" \
-  --task-id "<args.task-id>" \
-  --task-type "<args.task-type>" \
-  --task-brief "<args.task-brief>" \
-  --executor "<args.executor>" \
-  --critic "<args.critic>" \
-  --approved-plan "<args.approved-plan>" \
-  --stage "<args.stage>" \
-  --stages "<args.stages>" \
-  --base-ref "<args.base-ref>" \
-  --workers "<args.workers>" \
-  --directive "<args.directive>" \
-  --lead-model "<args.lead-model>" \
-  --claude-model "<args.claude-model>" \
-  --codex-model "<args.codex-model>" \
-  --antigravity-model "<args.antigravity-model>" \
-  --report-writer-model "<args.report-writer-model>" \
-  --related-tasks "<args.related-tasks>" \
-  --clarification-response "<args.clarification-response>" \
-  --pr-template-path "<args.pr-template-path>" \
-  --fix-cycle "<args.fix-cycle>"
+  --lead-runtime <host-runtime> \
+  --<first-renderArgs-key> "<first-renderArgs-value>" \
+  --<each-remaining-renderArgs-key> "<corresponding-value>"
 ```
 
 Parse the following labeled lines from stdout.
@@ -227,14 +206,14 @@ okstra config set pr-template-path "<path>" --scope global
 
 Read the scope and path from the persist action of `okstra wizard outcome`, not from the wizard state file. Do not read the raw state file directly.
 
-## Claude lead takeover
+## Okstra lead takeover
 
-After render-bundle, read `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md` verbatim and proceed from Phase 1 in that prompt's order.
+After render-bundle, read `<INSTRUCTION_SET_PATH>/lead-execution-prompt.md` verbatim and proceed from Phase 1 in that prompt's order.
 
 Inform the user on one line.
 
 ```text
-Took over as Claude lead for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
+Took over as Okstra lead (`<host-runtime>`) for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
 ```
 
 For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements.
@@ -244,7 +223,7 @@ For a single-element chain, the end of Step 6 is the end of the run. Step 7 belo
 When `task-type == implementation` and the render-args `chain-stages` CSV has 2 or more elements, the current session acts as the orchestrator and runs the stages as an unattended chain in dependency order. Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`. For each stage `N` in the queue, in order:
 
 1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The `io`-only conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
-2. As in Step 6, become Claude lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
+2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
 3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
@@ -261,4 +240,4 @@ Once the whole queue is consumed, end the chain and report completion.
 - Dropping the `--answer` flag on an empty answer.
 - Bypassing the wizard/render-bundle path by calling `okstra.sh`.
 - Calling render-args on a state the user aborted before render-bundle.
-- Starting phase work arbitrarily before reading the Claude lead prompt.
+- Starting phase work arbitrarily before reading the Okstra lead prompt.

package/docs/performance-improvement-plan-v2.md

@@ -63,7 +63,7 @@ The current documentation and code contain two layers with similarly named phase
 
 Each okstra invocation performs exactly one task type. Moving to the next task type requires a new invocation.
 
-#### Claude lead operating phases
+#### Okstra lead operating phases
 
 Phases 1–7 in `prompts/lead/okstra-lead-contract.md` are operating steps that the lead performs within one task-type run.
 
@@ -81,7 +81,7 @@ Therefore, "P1 convergence improvement" in this document does not change the tas
 
 `prepare_task_bundle()` writes the instruction set and manifest-related files sequentially.
 
-- Instruction set: `analysis-profile.md`, `analysis-material.md`, `task-brief.md`, optional carry-in/directive, `reference-expectations.md`, `final-report-template.md`, `claude-execution-prompt.md`, and the prompt snapshot.
+- Instruction set: `analysis-profile.md`, `analysis-material.md`, `task-brief.md`, optional carry-in/directive, `reference-expectations.md`, `final-report-template.md`, canonical `lead-execution-prompt.md`, and the prompt snapshot.
 - Manifest/discovery: `team-state`, `task-manifest`, `task-index`, `run-manifest`, `timeline`, task catalog, and latest task.
 
 This serial rendering has room for improvement, but it is generally cheaper than external worker dispatch. Render parallelization is therefore not the first priority.

package/docs/pr-template-usage.md

@@ -1,6 +1,6 @@
 # PR template usage guide
 
-Summarizes the resolution rules, storage locations, and configuration methods for the Markdown template that `Claude lead` uses to write the PR body during the `release-handoff` phase.
+Summarizes the resolution rules, storage locations, and configuration methods for the Markdown template that the host-native `Okstra lead` uses to write the PR body during the `release-handoff` phase.
 
 Authoritative source of the resolution logic: [`scripts/okstra_ctl/pr_template.py`](../scripts/okstra_ctl/pr_template.py).
 

package/docs/project-structure-overview.md

@@ -20,7 +20,7 @@
 
 ## 1. Project identity
 
-`okstra` is a multi-agent cross-verification runtime for Claude Code, distributed as the npm package `okstra`. It is not a one-shot reviewer; it runs a lead + worker model across multiple lifecycle phases around a stable task key.
+`okstra` is a host-aware, multi-provider cross-verification runtime distributed as the npm package `okstra`. It is not a one-shot reviewer; it runs one neutral lifecycle core through Claude Code, Codex, or an explicit external adapter around a stable task key.
 
 Current baseline:
 
@@ -28,9 +28,9 @@ Current baseline:
 - Node CLI entrypoint: `bin/okstra`
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
-- installed skills: 8
-- worker agents: `claude`, `codex`, `antigravity`, `report-writer`
-- final report SSOT: `schemas/final-report-v1.0.schema.json` + `*.data.json`
+- installed skills: 13
+- provider workers: `claude`, `codex`, `antigravity`, `grok`, `kimi`; functional report writer: `report-writer`
+- final report SSOT: current `schemas/final-report-v2.0.schema.json` + `*.data.json`; schema v1 remains a compatibility contract
 
 Design principles:
 
@@ -180,14 +180,14 @@ Runtime/install asset changes follow this checklist:
 | `worktree-lookup` | `src/commands/execute/worktree-lookup.mjs` | Look up a task-key's registered worktree |
 | `plan-validate` | `src/commands/execute/plan-validate.mjs` | Check approved-plan approval marker |
 | `render-bundle` | `src/commands/execute/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
-| `run` | `src/commands/execute/run.mjs` | Host-aware execution front door (`auto` → Claude/Codex/external path selection) |
+| `run` | `src/commands/execute/run.mjs` | Host-aware execution front door (`auto` → Claude/Codex/Antigravity/external path selection) |
 | `codex-run`, `codex-dispatch` | `src/commands/execute/codex-*.mjs` | Codex lead dry-run bundle preparation and CLI-backed worker dispatch |
 | `team` | `src/commands/execute/team.mjs` | External lead tmux-pane worker dispatch / await / teardown |
 | `convergence` | `src/commands/execute/convergence.mjs` | Internal admin CLI for the deterministic Phase 5.5 convergence engine (`seed`/`plan-round`/`apply-round`/`apply-critic-gaps`/`finalize`/`validate`/`example`; Python: `okstra_ctl.convergence`) |
 | `plan-items` | `src/commands/execute/plan-items.mjs` | Internal admin CLI for deterministic plan-body item extraction and exact-match validation (`extract`/`validate`; Python: `okstra_ctl.plan_items_cli`) |
 | `report-finalize` | `src/commands/report/finalize.mjs` | Run the whole Phase 7 post-report sequence in contractual order (Python: `okstra_ctl.report_finalize`) — the single reference point shared with the Codex lead adapter |
-| `render-views` | `src/commands/report/render-views.mjs` | Generate the self-contained HTML report view |
-| `render-final-report`, `inject-report-index` | `src/commands/report/*.mjs` | Render final-report Markdown from data.json and inject top-of-report index anchors |
+| `render-views` | `src/commands/report/render-views.mjs` | Render schema v2 data with its task-specific human template, or use the schema v1 / quick-report compatibility view |
+| `render-final-report`, `inject-report-index` | `src/commands/report/*.mjs` | Render version-selected AI handoff Markdown from data.json; v1 index injection remains compatibility-only |
 | `wizard` | `src/commands/execute/wizard.mjs` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
 | `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
 | `spawn-followups`, `error-log` | `src/commands/execute/*.mjs` | Follow-up task bundle creation and run error-log append helpers |
@@ -218,8 +218,8 @@ Top-level scripts:
 | `okstra-claude-exec.sh`, `okstra-codex-exec.sh`, `okstra-antigravity-exec.sh` | Worker CLI wrappers with log/status sidecars |
 | `okstra-wrapper-status.py` | Heartbeat sidecar writer used by worker wrappers |
 | `okstra-token-usage.py` | Token usage CLI entrypoint |
-| `okstra-render-final-report.py` | Render final-report Markdown from data.json |
-| `okstra-render-report-views.py` | Render self-contained HTML views from final-report Markdown |
+| `okstra-render-final-report.py` | Render version-selected final-report Markdown from data.json |
+| `okstra-render-report-views.py` | Render schema v2 task-specific HTML directly from data.json, or a legacy view from schema v1 / quick Markdown |
 | `okstra-error-log.py` | Normalize worker/lead error sidecars |
 | `okstra-spawn-followups.py` | Follow-up spawning helper |
 | `okstra-trace-cleanup.sh` | tmux okstra pane cleanup (worker-agent + trace, excluding the lead pane), called by the lead at every worker round boundary — not once per phase; `--keep <substr>` (repeatable) spares panes whose title contains the substring, which is how an in-flight `report-writer-worker` survives a boundary; `--list` prints what would be reclaimed without killing; the `--reclaim-completed` mode reclaims only trace panes whose `@okstra_status` is terminated (stage=exited) and preserves in-progress panes |
@@ -260,7 +260,7 @@ Important modules:
 | `qa_commands.py` | QA command deny-list validation for plans |
 | `conformance.py` | validates task-level Tier 3 manifests, parses `QA-RESULT`, detects diff capability surfaces, and reduces results to PASS/ADVISORY/BLOCKING; DB/HTTP/external non-PASS is user-owned advisory while local IO and contract defects remain blocking, enforced by `scripts/okstra_ctl/conformance.py::decide_conformance_gate` and `validators/validate-run.py::_validate_conformance` |
 | `pr_template.py` | PR body template resolution for release-handoff |
-| `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report data.json → Markdown → Report View Model → self-contained HTML pipeline |
+| `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Versioned final-report contract: schema v2 data independently produces AI handoff Markdown and human HTML; schema v1 keeps the legacy Markdown/view pipeline |
 | `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
 | `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
 | `wizard_stage_intent.py` | stage-related intent projection of the `okstra-run` wizard output — normalizes whole-task (`__whole_task__`) vs single/multi stage selection into render-args (`resolve_wizard_stage_intent`) |
@@ -288,7 +288,7 @@ Important modules:
 | `manager_store.py` | Manager-owned state mutation — project membership, task planning, assignment, directives, event append |
 | `manager_sync.py` | One-way child project `.okstra` snapshot reader; corrupt child state becomes row-level `error` so other children continue |
 | `manager_launch.py` | Child launch packet and manager child context renderer; records `prepared` launch metadata/events without changing project-local task state |
-| `dispatch_core.py` | Backend-neutral worker dispatch core — worker execution/collection logic shared by any lead runtime (Claude/Codex/external); gates selected initial prompts through the shared cross-task contract before launch |
+| `dispatch_core.py` | Backend-neutral worker dispatch core — worker execution/collection logic shared by any lead runtime (Claude/Codex/Antigravity/external); gates selected initial prompts through the shared cross-task contract before launch |
 | `codex_dispatch.py` | Codex lead CLI-worker dispatcher — the `okstra codex-dispatch` backend. Reads the run manifest to run the Codex-side supported worker subset, applies the same cross-task initial-prompt gate, and performs token-usage substitution, view render, follow-up, and validation |
 | `analysis_packet.py` | assembles the compact analysis-worker input packet for a task run from worker-owned profile sections; report/lead procedure stays outside the packet |
 | `analysis_inputs.py` | shared input boundary for `project-analysis`, `feature-analysis`, and `change-impact-analysis` — validates evidence-report identity and review status, enforces the type-to-type relation allowlist, computes `exact`/`stale` freshness, and resolves free-text or `PF-NNN` feature targets for both wizard and prepare paths |
@@ -298,7 +298,7 @@ Important modules:
 | `work_categories.py` | requirements-discovery work-category (domain) **SSOT** (`is_valid_category`) — the work-category allowlist is defined only here |
 | `model_discovery.py` | pre-dispatch model-identity normalization for CLI workers — roster-gated label correction + a per-role reasoning-effort policy (deterministic, no per-run improvisation) for CLIs (agy) that bake effort into the model name |
 | `lead_runtime.py` | lead runtime metadata shared by the render and prepare paths (`LeadRuntimeInfo`) |
-| `lead_events.py` | structured JSONL events emitted by non-Claude lead runtimes |
+| `lead_events.py` | structured JSONL events emitted by artifact-accounted lead runtimes |
 | `team_reconcile.py` | stale team-member reconciliation at run-end teardown |
 | `worker_prompt_headers.py` | shared rendering of phase-aware worker prompt anchors (`worker_prompt_headers`): coding-preflight only for implementation and compact target identity for final-verification |
 | `worker_prompt_body.py` | provider-neutral initial analysis body/input renderer shared by Codex and external/team dispatch paths |
@@ -351,8 +351,10 @@ Token/cost accounting:
 
 | Path | Role |
 |---|---|
-| `templates/reports/final-report.template.md` | Jinja2 final-report Markdown template |
-| `templates/reports/report.css`, `report.js` | Inline assets for self-contained HTML report view |
+| `templates/reports/final-report.template.md` | Schema v1 compatibility Markdown template |
+| `templates/reports/final-report-v2.template.md` | Compact schema v2 AI handoff Markdown template |
+| `templates/reports/html/base.template.html`, `html/tasks/*.template.html` | Shared HTML shell plus ten dedicated task templates for human reports; task bodies are not shared |
+| `templates/reports/report.css`, `report.js` | Inline assets for self-contained HTML report views |
 | `templates/reports/*.template.md` | Inputs, schedule, user-response, settings templates |
 | `project-analysis-input.template.md`, `feature-analysis-input.template.md`, `change-impact-analysis-input.template.md` | Brief input templates for the three analysis sidetracks |
 | `user-response.template.md`, `report.js` | Analysis Review sidecar block and the browser control that exports accept/revision/reject without changing the source report |
@@ -364,7 +366,7 @@ Token/cost accounting:
 
 ### 4.8 `schemas/`
 
-`schemas/final-report-v1.0.schema.json` is the final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; the renderer produces Markdown from that JSON.
+`schemas/final-report-v2.0.schema.json` is the current final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; independent renderers produce AI handoff Markdown and task-specific human HTML. `schemas/final-report-v1.0.schema.json` remains supported for existing reports and quick-report compatibility.
 
 The deterministic convergence inputs are `schemas/convergence-groups-v1.0.schema.json`, `schemas/convergence-round-results-v1.0.schema.json`, and `schemas/convergence-critic-results-v1.0.schema.json`. `tools/build.mjs` syncs the entire source `schemas/` directory to `runtime/schemas/`; these JSON Schema files are runtime contracts, not Markdown publication-inventory entries.
 
@@ -377,7 +379,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 
 | File | Role |
 |---|---|
-| `validate-run.py` | Run/final-report contract validation |
+| `validate-run.py` | Version-aware run/final-report validation: schema v2 AI handoff order + structured data rules, with legacy schema v1 Markdown gates preserved |
 | `validate-brief.py`, `validate-brief.sh` | Brief frontmatter/body contract validation |
 | `validate-report-views.py` | HTML view validation (form-control placement / no external URLs / stale source digest / Response ID parity) |
 | `validate_analysis_report.py` | Cross-field validation for the three read-only analysis reports: frozen target/evidence snapshots, current-code evidence, review-source identity, and exact affected-ID resolution coverage on revision reruns |
@@ -397,7 +399,7 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
 | Skill | User-invocable | Role |
 |---|---:|---|
 | `okstra-brief-gen` | yes | Produce task brief from ticket/doc/link/conversation |
-| `okstra-run` | yes | Start/resume okstra task in current Claude Code session |
+| `okstra-run` | yes | Start/resume an okstra task in the current Claude Code, Codex, or Antigravity host session |
 | `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
 | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost), `errors` (error-log aggregation), `error-zip` (anonymized cross-project error bundle), `recap` (cross-run phase recap). `SKILL.md` is a thin core (preflight + dispatch table + shared rules) and each sub-command body lives in `skills/okstra-inspect/facets/<sub-command>.md`, lazily read only after dispatch resolves; the 1:1 match between dispatch rows and facet files is enforced by `tests/contract/test_okstra_inspect_facets.py` |
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
@@ -419,9 +421,11 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
 | `agents/workers/claude-worker.md` | Claude analyzer/verifier/executor spec |
 | `agents/workers/codex-worker.params.json` | Codex analyzer/verifier/executor wrapper params (build renders `.md` via `_cli-wrapper-template.md`) |
 | `agents/workers/antigravity-worker.params.json` | Antigravity analyzer/verifier/executor wrapper params (build renders `.md` via `_cli-wrapper-template.md`) |
+| `agents/workers/grok-worker.params.json` | Grok read-only analyser/critic wrapper params |
+| `agents/workers/kimi-worker.params.json` | Kimi read-only analyser/critic wrapper params |
 | `agents/workers/report-writer-worker.md` | data.json SSOT author and audit sidecar writer |
 
-The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Host mappings live under `prompts/lead/adapters/`: `claude-code.md`, `codex.md`, and `external.md`. All are runtime resources installed under `~/.okstra/prompts/lead/`, not agent skills.
+The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Host mappings live under `prompts/lead/adapters/`: `claude-code.md`, `codex.md`, `antigravity.md`, and `external.md`. All are runtime resources installed under `~/.okstra/prompts/lead/`, not agent skills.
 
 ### 4.12 `tests/` and `tests-e2e/`
 
@@ -498,15 +502,15 @@ Current report pipeline:
 
 1. Analysis workers write worker result files and the separate audit sidecars named by `Audit sidecar path`.
 2. The lead writes semantic groups; the convergence engine persists working state, per-round plans/results, an optional critic transition, and then a validated `state/convergence-<task-type>-<seq>.json` terminal state: schema v1.3 when newly finalized, or an unchanged historical final schema v1.0, v1.1, or v1.2 returned by `reuse-final`.
-3. Report-writer worker writes `reports/final-report-<task-type>-<seq>.data.json`.
+3. Report-writer worker writes `reports/final-report-<task-type>-<seq>.data.json` against the current schema v2 contract, including `humanSummary` and one task-type deliverable.
 4. For implementation-planning, `okstra plan-items extract` creates the complete `P-*` queue, `validate` proves it still matches data.json, and the analyser instances run the separate plan-body verification round.
-5. `scripts/okstra-render-final-report.py` renders Markdown.
+5. `scripts/okstra-render-final-report.py` renders compact AI handoff Markdown with `templates/reports/final-report-v2.template.md`.
 6. Token usage substitution fills usage/cost cells.
-7. `scripts/okstra-render-report-views.py` emits the self-contained `.html` view, and run validation checks the final artifacts.
+7. `scripts/okstra-render-report-views.py` independently selects one of ten dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks both derived artifacts. Schema v1 and quick Markdown inputs retain their legacy conditional path.
 
 For the three analysis sidetracks, the HTML view also exports an immutable-source `## ANALYSIS REVIEW` sidecar. A revision rerun carries that sidecar, reanalyzes the whole confirmed scope, and records one `analysisReviewResolution` row for every affected ID before `validate_analysis_report.py` accepts the result.
 
-The Markdown is derived, not the authoring source. The schema is the contract.
+Both Markdown and HTML are derived, not authoring sources. The schema is the contract.
 
 ---
 

package/docs/task-process/README.md

@@ -10,7 +10,7 @@
 
 ## 1. Reading order
 
-`okstra-run` is the path that starts a task inside a Claude Code session. This folder organizes that execution flow into two layers.
+`okstra-run` is the path that starts a task inside a supported Claude Code, Codex, or Antigravity host session. This folder organizes that execution flow into two layers.
 
 1. First read [common-flow.md](common-flow.md). It is the wizard, render-bundle, lead phase, and artifact flow shared by every task-type.
 2. Then read the document for the task-type you want to run.
@@ -20,14 +20,14 @@
 
 ```mermaid
 flowchart TD
-    U[User in Claude Code] --> S[/okstra-run skill/]
+    U[User in supported host] --> S[okstra-run skill]
     S --> R[Step 1<br/>ensure-installed / paths / check-project]
     R --> W[okstra wizard<br/>state machine]
     W --> A[render-args]
     A --> B[okstra render-bundle<br/>--render-only]
     B --> P[prepare_task_bundle()]
-    P --> I[instruction-set<br/>claude-execution-prompt.md]
-    I --> L[Current Claude session<br/>takes over as Claude lead]
+    P --> I[instruction-set<br/>lead-execution-prompt.md]
+    I --> L[Current host session<br/>takes over as Okstra lead]
     L --> F[Phase 1-7 lead workflow]
     F --> O[final-report + manifests + status]
 ```

package/docs/task-process/common-flow.md

@@ -6,21 +6,21 @@
 - [2. Where the two entrypoints meet](#2-where-the-two-entrypoints-meet)
 - [3. wizard input collection flow](#3-wizard-input-collection-flow)
 - [4. render-bundle and prepare_task_bundle](#4-render-bundle-and-prepare_task_bundle)
-- [5. Claude lead phase 1-7](#5-claude-lead-phase-1-7)
+- [5. Okstra lead phase 1-7](#5-okstra-lead-phase-1-7)
 - [6. artifact layout](#6-artifact-layout)
 - [7. Common branching rules](#7-common-branching-rules)
 - [8. Inconsistencies to watch for](#8-inconsistencies-to-watch-for)
 
 ## 1. One-line summary
 
-`okstra-run` is not a "skill that decides questions on its own" but a thin loop that relays the `okstra wizard` JSON state machine to the user. Once input collection finishes, it calls `okstra render-bundle`, and that command builds the task bundle through `python3 -m okstra_ctl.run --render-only`. After that, the current Claude Code session switches over to `Claude lead`.
+`okstra-run` is not a "skill that decides questions on its own" but a thin loop that relays the `okstra wizard` JSON state machine to the user. Once input collection finishes, it calls `okstra render-bundle`, and that command builds the task bundle through `python3 -m okstra_ctl.run --render-only`. After that, the current Claude Code, Codex, or Antigravity session switches over to the host-native `Okstra lead`.
 
 ## 2. Where the two entrypoints meet
 
 ```mermaid
 flowchart LR
-    subgraph InSession["Claude Code in-session"]
-        A[/okstra-run skill/] --> B[okstra wizard]
+    subgraph InSession["supported host session"]
+        A[okstra-run skill] --> B[okstra wizard]
         B --> C[okstra render-bundle<br/>forces --render-only]
     end
 
@@ -32,7 +32,7 @@ flowchart LR
     E --> P
     P --> G[task bundle artifacts]
     G --> H{launch mode}
-    H -->|render-only| I[current Claude reads lead prompt]
+    H -->|render-only| I[current host reads lead prompt]
     H -->|non-render-only| J[exec claude --session-id ...]
 ```
 
@@ -93,19 +93,19 @@ sequenceDiagram
     Py->>Home: record_start status=prepared
     Py-->>Node: task root, instruction-set, rendered lead prompt
     Node-->>Skill: stdout
-    Skill->>FS: read claude-execution-prompt.md
+    Skill->>FS: read lead-execution-prompt.md
 ```
 
-The Node shim for `render-bundle` is [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs). This shim attaches the `--workspace-root`, `--render-only`, and runtime resolution arguments directly. As a result, on the okstra-run path the initial run status starts at `prepared` and the task status starts at `instruction-set-generated`.
+The Node shim for `render-bundle` is [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs). This shim attaches the `--workspace-root`, `--render-only`, and runtime resolution arguments directly. As a result, on the okstra-run path the initial run status starts at `prepared` and the task status starts at `ready-for-lead`.
 
-## 5. Claude lead phase 1-7
+## 5. Okstra lead phase 1-7
 
 ```mermaid
 flowchart TD
     P1[Phase 1<br/>task bundle intake] --> P2[Phase 2<br/>worker prompt preparation]
-    P2 --> P3[Phase 3<br/>TeamCreate]
-    P3 -->|team ok| P4[Phase 4<br/>dispatch workers with team_name]
-    P3 -->|team unavailable| P5[Phase 5<br/>background fallback]
+    P2 --> P3[Phase 3<br/>resolve persisted runners]
+    P3 -->|native session| P4[Phase 4<br/>host-native dispatch]
+    P3 -->|CLI wrapper| P5[Phase 4<br/>provider CLI dispatch]
     P4 --> C[Phase 5.5<br/>convergence]
     P5 --> C
     C --> P6[Phase 6<br/>report-writer synthesis]
@@ -127,7 +127,7 @@ flowchart TD
     Root --> Hist[history/timeline.json]
     IS --> Profile[analysis-profile.md]
     IS --> Brief[task-brief.md]
-    IS --> Lead[claude-execution-prompt.md]
+    IS --> Lead[lead-execution-prompt.md]
     Runs --> Man[manifests/run-manifest-*.json]
     Runs --> Prompts[prompts/*-worker-prompt-*.md]
     Runs --> Results[worker-results/*.md]

package/docs/task-process/final-verification.md

@@ -45,7 +45,7 @@ sequenceDiagram
     participant C as consumers.jsonl
     participant Reg as worktree registry
     participant Git as verification worktree
-    participant Lead as Claude lead
+    participant Lead as Okstra lead
 
     P->>C: backfill carry and read done rows
     P->>Reg: resolve task or stage worktree
@@ -75,7 +75,7 @@ Once started, the lead treats `VERIFICATION_TARGET` as authoritative. It does no
 ```mermaid
 flowchart TD
     Gate[entry gate passed] --> Target[injected VERIFICATION_TARGET]
-    Target --> Lead[Claude lead confirms target snapshot]
+    Target --> Lead[Okstra lead confirms target snapshot]
     Lead --> CW[Claude verifier<br/>read-only]
     Lead --> XW[Codex verifier<br/>read-only]
     Lead --> GW{Antigravity opt-in?}

package/docs/task-process/implementation.md

@@ -102,7 +102,7 @@ These outcomes are enforced by
 
 ```mermaid
 flowchart TD
-    Lead[Claude lead] --> Exec[Executor<br/>selected provider]
+    Lead[Okstra lead<br/>host native] --> Exec[Executor<br/>selected provider]
     Lead --> CV[Claude verifier<br/>read-only]
     Lead --> XV[Codex verifier<br/>read-only]
     Lead --> GV{Antigravity in roster?}

package/docs/task-process/release-handoff.md

@@ -16,7 +16,7 @@
 
 `release-handoff` is the terminal phase that pushes an already-committed implementation result with an `accepted` verdict, or hands it off as a PR. whole-task mode packages the verified task branch as-is. stage-group mode can assemble the selected stages into a collector branch and bundle them into a single PR, and the merge commit created here is produced only by `okstra handoff assemble`.
 
-This phase has no worker dispatch. It does not use the `claude`, `codex`, or `report-writer` roster; the Claude lead performs git/gh inspection, user questions, the PR draft, and the final report all inline.
+This phase has no worker dispatch. It does not use a provider or report-writer roster; the host-native Okstra lead performs git/gh inspection, user questions, the PR draft, and the final report inline.
 
 ## 2. okstra-run wizard flow
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "okstra",
-  "version": "0.146.1",
-  "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
+  "version": "0.148.0",
+  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",
   "repository": {

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.146.1",
-  "builtAt": "2026-08-03T06:04:45.516Z",
+  "package": "0.148.0",
+  "builtAt": "2026-08-03T19:00:08.212Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/antigravity-worker.md

@@ -39,7 +39,7 @@ The wrapper internally runs:
 agy --print "<prompt>" --model "<model>" --add-dir "<project-root>" [--add-dir "<worktree-path>"] --dangerously-skip-permissions
 ```
 
-The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `agy --print ... < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(agy:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-antigravity-exec.sh:*)`.
+The wrapper exists because agent-host Bash permission matchers can reject simple-prefix matches when the command contains stdin/stderr redirects. Calling `agy --print ... < <path> 2>/dev/null` directly may trigger a permission prompt even when `Bash(agy:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-antigravity-exec.sh:*)`.
 
 **Do NOT** invoke `agy --print ... 2>>log > >(tee)` directly — always go through the wrapper. agy has no `--cd` flag, so the wrapper anchors workspace correctness via `--add-dir <project-root>` regardless of inherited cwd.
 
@@ -251,6 +251,6 @@ When this run's `task_type` is `implementation` and you are acting as the **Exec
 }
 ```
 
-Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The lead (`Claude lead`) is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
+Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The host-native Okstra lead is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
 
 This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.

package/runtime/agents/workers/claude-worker.md

@@ -120,6 +120,6 @@ When this run's `task_type` is `implementation` and you are acting as the **Exec
 }
 ```
 
-Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The lead (`Claude lead`) is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
+Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The host-native Okstra lead is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
 
 This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.

package/runtime/agents/workers/codex-worker.md

@@ -39,7 +39,7 @@ The wrapper internally runs:
 codex exec -C "<project-root>" [--add-dir "<worktree-path>"] --model "<model>" --sandbox workspace-write -c approval_policy=never - < "<prompt-path>" 2>/dev/null
 ```
 
-The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `codex exec ... < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(codex exec:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`.
+The wrapper exists because agent-host Bash permission matchers can reject simple-prefix matches when the command contains stdin/stderr redirects. Calling `codex exec ... < <path> 2>/dev/null` directly may trigger a permission prompt even when `Bash(codex exec:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`.
 
 **Do NOT use** the non-existent `-q` flag. The approval policy MUST be set with `-c approval_policy=never` (the `-a`/`--ask-for-approval` flag is NOT accepted by `codex exec` — it errors with `unexpected argument '-a'`); without `approval_policy=never` codex runs under the default `on-request` policy and, having no TTY to answer an approval prompt, ends the turn in a few seconds with exit 0 and no result file. **Do NOT** invoke `codex exec ... < ... 2>/dev/null` directly — always go through the wrapper.
 
@@ -251,6 +251,6 @@ When this run's `task_type` is `implementation` and you are acting as the **Exec
 }
 ```
 
-Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The lead (`Claude lead`) is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
+Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The host-native Okstra lead is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
 
 This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.