okstra 0.146.1 → 0.148.0

package/README.md

@@ -20,7 +20,7 @@
 <a id="purpose"></a>
 ## 1. Purpose
 
-`okstra` is a **structured task runner that cross-verifies work inside Claude Code using a lead + worker model**. A Claude lead drives phase progression and dispatches independent analysis workers—**Claude and Codex by default**, with Antigravity added only when explicitly requested—plus a dedicated report writer for final synthesis.
+`okstra` is a **host-aware, multi-provider task runner that cross-verifies work with a lead + worker model**. The current Claude Code, Codex, or Antigravity host supplies the native lead session; every other selected provider runs through its registered CLI wrapper. Claude remains the compatibility default policy, not the owner of the lifecycle.
 
 The design rests on three principles:
 
@@ -28,6 +28,20 @@ The design rests on three principles:
 - **Persistent task identity**: a stable `<project-id>/<task-group>/<task-id>` task key carries context across phases, sessions, and model upgrades.
 - **Enforced lead/worker contract**: output schemas and validation procedures are bound to `templates/` + `validators/`, and the worker roster is fixed per phase.
 
+Role assignments are persisted separately from the host runtime, but the lead provider is always derived from that runtime:
+
+| Provider | Native host | CLI wrapper | Public roles |
+|---|---|---|---|
+| Claude | Claude Code | `okstra-claude-exec.sh` | lead, analysis, implementation, report writer |
+| Codex | Codex | `okstra-codex-exec.sh` | lead, analysis, implementation, report writer |
+| Antigravity | Antigravity CLI | `okstra-antigravity-exec.sh` | lead, analysis, and implementation |
+| Grok | none | `okstra-grok-exec.sh` | read-only analyser and critic |
+| Kimi | none | `okstra-kimi-exec.sh` | read-only analyser and critic |
+
+Grok and Kimi are intentionally read-only in this release. Their wrappers, model aliases, installation, diagnostics, and usage-pricing paths are integrated, but a real authenticated local invocation still depends on the corresponding CLI being installed and configured.
+
+The next direct-CLI candidates are Mistral Vibe and Qwen Code. DeepSeek V4, GLM-5.2, and MiniMax M2.7 remain API-adapter candidates because their current official coding-agent execution surfaces do not fit Okstra's wrapper contract as directly. Newly published provider models are exposed only after the corresponding local CLI reports them; this keeps model discovery separate from marketing availability.
+
 okstra is **not** a one-shot code review tool. It is for work that **spans multiple phases, needs input from multiple agents, and feeds each phase's output into the next phase**.
 
 <a id="structure"></a>
@@ -63,7 +77,7 @@ During `prepack`, `tools/build.mjs` rebuilds `runtime/` from `scripts/`, `skills
 ~/.okstra/                       runtime home, created by `okstra install`
 ├── version                      package version stamp
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
-├── bin/                         okstra.sh, codex-exec, antigravity-exec, ...
+├── bin/                         okstra.sh and Claude/Codex/Antigravity/Grok/Kimi wrappers
 ├── templates/                   report assets and settings templates
 ├── prompts/                     lead operating contracts (prompts/lead/*) + coding-preflight resource pack
 ├── installed-runtimes.json      installed runtime adapter manifest
@@ -82,7 +96,7 @@ During `prepack`, `tools/build.mjs` rebuilds `runtime/` from `scripts/`, `skills
 └── okstra-*/SKILL.md            8 user-facing skills only (setup/brief/run/memory/inspect/schedule/container/manager)
 
 ~/.claude/agents/                automatically discovered by Claude Code (when `~/.claude` exists)
-└── {claude,codex,antigravity,report-writer}-worker.md   worker subagent definitions
+└── {claude,codex,antigravity,grok,kimi,report-writer}-worker.md   worker definitions
                                  (required for Claude Code multi-agent dispatch)
 
 <project-root>/.okstra/
@@ -195,7 +209,7 @@ To start a task outside a Claude Code session:
   --task-brief ./brief.md
 ```
 
-`feature-analysis` is intentionally omitted from the standalone shell example. Start it with `/okstra-run`: the wizard collects its required feature target and passes that value through the internal Node render boundary. Standalone `okstra.sh` accepts neither `--analysis-target` nor `--evidence-inputs`.
+`feature-analysis` is intentionally omitted from the standalone shell example. Start it with the in-host `okstra-run` skill: the wizard collects its required feature target and passes that value through the internal Node render boundary. Standalone `okstra.sh` accepts neither `--analysis-target` nor `--evidence-inputs`.
 
 This starts a new `claude` process in the lead role. For the complete argument list, see `okstra.sh --help` or [`docs/cli.md`](docs/cli.md).
 
@@ -208,16 +222,16 @@ Notable flags added in 0.7.0 / 0.8.0:
 Major workflow changes added to `main` after 0.8.0:
 
 - **Automatic isolated worktrees for every task type** — During preparation, `okstra-ctl` runs `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` once per task key to create an isolated working tree and a `<work-category-namespace>/<task-id-segment>` branch (for example, `feature/dev-9436` or `fix/dev-7311`). The user chooses the base ref with `--base-ref`, using the same choices as the release-handoff PR base picker: `main`, `dev`, `staging`, `preprod`, `prod`, or a custom value. It is required in the first phase; the okstra-run skill collects it through `AskUserQuestion`, while non-interactive callers must pass `--base-ref` explicitly. Later **non-`implementation`** phases for the same task key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`) reuse the same path and branch. `implementation` runs are **stage-isolated**: each run executes one stage in its own `.../<task>/stage-<N>/` worktree on a `<work-category-namespace>/<task>-s<N>` branch, so independent stages with `depends-on (none)` can run concurrently without sharing a tree. The registry reserves both task keys and **stage keys** with flock. Provisioning is skipped when the caller is already in another worktree or project_root is not a Git repository; stage isolation degrades to a flat path in those cases. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus release/removal of the registry entry. Details: [`docs/architecture.md`](docs/architecture.md), in the *Task type* section, and [`docs/cli.md#--executor`](docs/cli.md#--executor).
-- **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. A Claude worker drafts candidate commit messages and a PR body, then the lead uses `AskUserQuestion` to ask, in order, for (1) an action (`commit only` / `commit + PR` / `skip`), (2) a PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / custom input), and (3) message handling (`use as-is` / `edit then proceed` / `cancel`). Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
+- **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. The current Okstra lead drafts the candidate messages and PR body inline, then uses the selected host adapter's user-prompt operation for the delivery choices. Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
 - **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/prd/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
 - **Profile worker-roster validation** — `--workers <csv>` and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's `Required workers:` block. Requesting a worker absent from the profile—for example, `codex` or `antigravity` for `release-handoff`—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
-- **Experimental Codex lead adapter** — `okstra codex-run <render-bundle args...>` prepares a `leadRuntime=codex` task bundle without launching Claude Code. `okstra codex-dispatch --project-root <dir> --run-manifest <path>` then executes the supported Codex-side roster subset: Codex and Antigravity CLI workers by default, with a Codex report writer available through `--enable-codex-report-writer --report-writer-codex-model <model>`. A successful Codex report-writer dispatch performs token/cost substitution, HTML view rendering, follow-up stub generation, and run validation in order. It shares the Claude lead path's manifest and schema and does not clone the project into a Codex-specific fork.
+- **Host-aware lead adapters** — the same `okstra-run` skill resolves Claude Code to `leadRuntime=claude-code`, Codex to `leadRuntime=codex`, Antigravity CLI to `leadRuntime=antigravity`, and another explicit host to `external`. Claude Code keeps Claude assignments native, Codex keeps Codex assignments native, and Antigravity keeps Antigravity assignments native; every other selected provider runs through its registered CLI wrapper. The lead provider is derived from the host and cannot be replaced independently. `leadAssignment` and every `workerAssignments[]` row record provider, model, and `runner`. `okstra codex-run` and `okstra codex-dispatch` remain low-level artifact/dispatch commands.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with `depends-on (none)` can be implemented concurrently in separate `implementation` runs. Each `implementation` invocation runs a single stage, selected with `--stage <auto|N>`, and creates an evidence sidecar at `carry/stage-<N>.json` for automatic carry-in to the next stage. The `implementation-planning` run directory accumulates `consumers.jsonl` reverse links that record which run consumed each stage.
 - **AI-prepared design preparation (implementation-planning → implementation)** — `implementation-planning` detects which stages need design input (domain contract, DB/table schema, external interface, transaction/consistency, transformation mapping, lifecycle, rollout/observability, manual user test) and has the AI draft a concrete proposal first, instead of handing the user an empty design document. Each item is assessed as `ready`, `provisional`, `blocked`, or `not-applicable`; a simple task may declare `no-design-inputs`. Phase 7 materializes an Okstra-owned request under `design-prep-requests/`, and `okstra design-prep <list|show|write>` or the okstra-run wizard records the confirmed answer as an **append-only** revision under `design-prep-inputs/`—neither path ever edits the approved planning snapshot. Before creating its worktree, `implementation` resolves only the items its selected stage cites in `stageRefs`: safe `provisional` assumptions are injected into the executor prompt so work proceeds, while an unsafe open decision makes only that stage wait or replan. A markerless legacy plan continues with a `legacy-unassessed` warning. Storage authorities: [`docs/architecture/storage-model.md`](docs/architecture/storage-model.md). CLI: [`docs/cli.md#okstra-design-prep`](docs/cli.md#okstra-design-prep).
 - **Phase 6 plan-body verification (implementation-planning only)** — Immediately after the report-writer worker drafts the final report and before the user approval gate, the lead performs one post-verification round. It extracts `P-Opt-*`, `P-Step-*`, `P-Dep-*`, `P-Val-*`, and `P-Rb-*` plan items from the synthesized `## 5.5` implementation plan deliverables and asks every analyzer worker for an `AGREE`, `DISAGREE(a-e)`, or `SUPPLEMENT` verdict. The aggregate result is `passed`, `passed-with-dissent`, `blocked-by-disagreement`, or `aborted-non-result`. The frontmatter `approved` field is always published as `false`; a blocking result keeps it false and becomes a row in `## 1. Clarification Items`. For fast iteration, opt out with `--no-plan-verification`. Contract details: the "Plan-body verification mode" section of [`prompts/lead/convergence.md`](prompts/lead/convergence.md) and [`docs/cli.md#--no-plan-verification`](docs/cli.md#--no-plan-verification).
 - **Brief as translation layer + Step 6.5 reporter batch confirmation** — `okstra-brief-gen` converts external input—an issue ticket, requirements document, or user message—verbatim and marks okstra-added content as labeled augmentation. Step 6.5 asks the user to confirm in one batch whether that conversion changed meaning and records the result in `Reporter Confirmations`. Every analysis profile requires this section before phase analysis begins; `validators/validate-brief.py` enforces the requirement.
 - **Artifact-home rule (`.okstra/`)** — `<project>/.okstra/` is the only project artifact root owned by okstra. Anything outside this root is not okstra memory and may be read only when explicitly cited in Source Material or Reporter Confirmations. Writing outside the root requires the same explicit requested path. Internal equivalents are `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records, evaluated during `implementation-planning`.
-- **Self-contained HTML final-report view** — After Phase 7 writes `final-report-<task-type>-<seq>.md`, `okstra render-views` automatically creates a sibling self-contained HTML view in the same `reports/` directory, with inline CSS/JavaScript and no external URLs. Its `Export user response` button serializes `## 1. Clarification Items` responses to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` for the next phase. View generation never changes the source Markdown.
+- **Separate AI and human final-report views** — New runs write `final-report-<task-type>-<seq>.data.json` against `schemas/final-report-v2.0.schema.json`. Phase 7 independently derives compact AI handoff Markdown with `templates/reports/final-report-v2.template.md` and a task-specific, self-contained human HTML view from that same data. Each of the ten task types owns a dedicated template under `templates/reports/html/tasks/`; the HTML emphasizes the task's decisions, findings, visualizations, evidence, and next actions instead of exposing worker discussion as the main narrative. CSS / JavaScript remain inline, print and no-JavaScript reading are supported, and `Export user response` writes the next-phase sidecar. Existing schema v1 data and quick Markdown reports retain the legacy conditional renderer.
 - **`improvement-discovery` task type (sidetrack entry point)** — Within a codebase scope and priority-lens allowlist, multi-worker consensus produces N improvement candidates, with a default of eight and a hard cap of 12. This is a sidetrack entry point outside `PHASE_SEQUENCE`; the user selects candidates and starts each under a new task ID with `requirements-discovery`, `implementation-planning`, or `error-analysis`. Lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](scripts/okstra_ctl/improvement_lenses.py). Output section: `## 5.9 Improvement Candidates` (11-column table). Validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
 - **Read-only analysis task types (independent sidetracks)** — `project-analysis` maps the current project's components, dependencies, entry points, data stores, external systems, and feature index. `feature-analysis` traces one existing feature through flows, domain rules, state changes, integrations, and test coverage. `change-impact-analysis` maps the blast radius of a proposed change across preserved behavior, dependencies, tests, and operations. These are independent sidetracks outside `PHASE_SEQUENCE`, not lifecycle phases. No edits, tests, builds, migrations, or deployments are allowed against the target project. Start analysis runs through `/okstra-run`; its wizard owns target and evidence collection before calling the internal Node render command. The final report remains immutable: the HTML `Analysis Review` records accept, revision, or reject in a user-response sidecar. A revision request prioritizes a same-task, same-type full rerun; that rerun reanalyzes the whole confirmed scope and resolves every affected report ID instead of patching only the disputed rows. Input details: [`docs/cli.md`](docs/cli.md#analysis-sidetrack-task-types).
 
@@ -227,14 +241,14 @@ Major workflow changes added to `main` after 0.8.0:
 | Command | Purpose |
 |---|---|
 | `npx -y okstra@latest paths` | Print runtime paths (`--field <name>` or `--shell`) |
-| `npx -y okstra@latest doctor [--runtime claude-code\|codex\|all] [--phase <phase>]` | Diagnose runtime, skills, and Python imports. `codex` excludes Claude skill checks; `--phase` adds readiness checks for implementation, final-verification, release-handoff, and improvement-discovery |
+| `npx -y okstra@latest doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>]` | Diagnose runtime, skills, and Python imports. `codex`, `antigravity`, and `external` exclude Claude skill checks; `--phase` adds readiness checks for implementation, final-verification, release-handoff, and improvement-discovery |
 | `npx -y okstra@latest ensure-installed` | Run an idempotent check and automatically reinstall stale assets (skills call this internally) |
 | `npx -y okstra@latest setup --project-id <id>` | Register the current project in `.okstra/project.json` |
 | `npx -y okstra@latest check-project` | Verify that the current project was registered with `setup` |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Read or write okstra settings. The current key is `pr-template-path`, which updates `prTemplatePath` in project.json or `~/.okstra/config.json` |
 | `npx -y okstra@latest memory <add\|list\|search\|show\|archive>` | Store, search, and archive global conversation memory in `~/.okstra/memory-book` |
 | `npx -y okstra@latest context-cost <task-key\|task-root> [--project-root <path>]` | Estimate lead, worker, and report-writer context/read costs for a task bundle |
-| `npx -y okstra@latest render-views <final-report.md>` | Regenerate the self-contained sibling HTML view for one final-report Markdown file (Phase 7 step 1.5; idempotent) |
+| `npx -y okstra@latest render-views <final-report.data.json\|final-report.md>` | Render schema v2 data directly with its task-specific human template, or use the schema v1 / quick-report compatibility path (Phase 7 step 1.5; idempotent) |
 | `npx -y okstra@latest token-usage ...` | Collect and substitute run token usage through the installed Python token-usage CLI wrapper |
 | `npx -y okstra@latest uninstall` | Remove the runtime and skills while preserving user data such as `recent.jsonl` and `projects/` |
 | `npx -y okstra@latest uninstall --purge -y` | Remove all assets, including user data |

package/docs/architecture/storage-model.md

@@ -11,52 +11,27 @@ Files created by `okstra` are stored in the following three areas according to t
 This is the task's primary directory.
 The task manifest, task index, instruction set, runs, and history are collected under this root.
 
-```text
-<target-project>/.okstra/tasks/<task-group>/<task-id>/
-├── task-manifest.json
-├── task-index.md
-├── instruction-set/
-│   ├── analysis-profile.md
-│   ├── analysis-packet.md       # analysis worker primary compact input
-│   ├── analysis-material.md
-│   ├── reference-expectations.md
-│   ├── task-brief.md
-│   ├── verification-target.md         # final-verification only; canonical target snapshot
-│   ├── directive.txt                  # optional (mirrors --directive)
-│   ├── final-report-schema.json
-│   ├── final-report-template.md
-│   └── claude-execution-prompt.md
-├── runs/
-│   └── <task-type>/
-│       ├── manifests/
-│       │   └── run-manifest-<task-type>-<seq>.json
-│       ├── state/
-│       │   └── team-state-<task-type>-<seq>.json
-│       ├── prompts/
-│       │   ├── claude-execution-prompt-<task-type>-<seq>.md
-│       │   ├── claude-worker-prompt-<task-type>-<seq>.md
-│       │   ├── codex-worker-prompt-<task-type>-<seq>.md
-│       │   ├── antigravity-worker-prompt-<task-type>-<seq>.md
-│       │   └── report-writer-worker-prompt-<task-type>-<seq>.md
-│       ├── reports/
-│       │   └── final-report-<task-type>-<seq>.md
-│       ├── design-prep-requests/       # implementation-planning only; deterministic Okstra-owned drafts
-│       ├── design-prep-inputs/         # implementation-planning only; append-only user/wizard responses
-│       ├── status/
-│       │   └── final-<task-type>-<seq>.status
-│       ├── sessions/
-│       │   └── claude-resume-<task-type>-<seq>.sh
-│       ├── logs/
-│       │   └── errors-<task-type>-<seq>.jsonl        # optional, lead-only writer
-│       └── worker-results/
-├── history/
-│   ├── timeline.json
-│   └── fix-cycles.jsonl          # optional, created only when entering a fix cycle (append-only)
-├── recap/
-│   └── recap-log.jsonl          # optional, append-only before/after summaries and Q&A for recap (other artifacts unchanged)
-└── notes/
-    └── <slug>-<YYYY-MM-DD>.md    # optional, agent-authored notes written by `okstra recap note` (evidence/decision-draft/analysis); inert — never auto-read by a run, fed forward only via --clarification-response
-```
+- `<target-project>/.okstra/tasks/<task-group>/<task-id>/`
+  - `task-manifest.json`
+  - `task-index.md`
+  - `instruction-set/`
+    - `analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`
+    - `verification-target.md` for final verification and optional `directive.txt`
+    - `final-report-schema.json`, `final-report-template.md`
+    - canonical `lead-execution-prompt.md` plus the `claude-execution-prompt.md` compatibility alias
+  - `runs/<task-type>/`
+    - `manifests/run-manifest-<task-type>-<seq>.json`
+    - `state/team-state-<task-type>-<seq>.json`
+    - `prompts/lead-execution-prompt-<task-type>-<seq>.md` and selected `<worker>-worker-prompt-<task-type>-<seq>.md` files
+    - `reports/final-report-<task-type>-<seq>.{data.json,md,html}`
+    - implementation-planning-only `design-prep-requests/` and `design-prep-inputs/`
+    - `status/final-<task-type>-<seq>.status`
+    - Claude compatibility launcher sessions under `sessions/claude-resume-<task-type>-<seq>.sh`
+    - optional lead-written `logs/errors-<task-type>-<seq>.jsonl`
+    - `worker-results/`
+  - `history/timeline.json` and optional append-only `history/fix-cycles.jsonl`
+  - optional append-only `recap/recap-log.jsonl`
+  - optional inert agent notes under `notes/<slug>-<YYYY-MM-DD>.md`; a run reads them only when explicitly carried through `--clarification-response`
 
 Actual directory segments may be normalized into slugs to create safe paths.
 However, the logical task key always retains the original input values in the form `project-id:task-group:task-id`.
@@ -74,13 +49,14 @@ The representative files below are all relative to the resolved run directory (`
 
 - `manifests/run-manifest-<task-type>-<seq>.json`
 - `state/team-state-<task-type>-<seq>.json`
-- `prompts/claude-execution-prompt-<task-type>-<seq>.md`
+- `prompts/lead-execution-prompt-<task-type>-<seq>.md` *(canonical; the Claude-named snapshot remains a compatibility alias)*
 - `prompts/<worker>-worker-prompt-<task-type>-<seq>.md`
 
-Unless `--render-only` is used, the handed-off Claude session typically adds the following result files to the current run.
+After the host-native lead takes over, the lead and its assigned workers add the following result files to the current run.
 - `sessions/claude-resume-<task-type>-<seq>.sh`
+- `reports/final-report-<task-type>-<seq>.data.json` *(schema v2 source of truth for both audiences; schema v1 remains readable for compatibility)*
 - `reports/final-report-<task-type>-<seq>.md`
-- `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 deterministic post-processing: self-contained HTML for human reviewers, with inline CSS/JS)*
+- `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 deterministic post-processing: task-specific, self-contained HTML for human reviewers, with inline CSS/JS)*
 - `design-prep-requests/design-prep-request-<seq>-PREP-<NNN>.md` *(implementation-planning only: deterministic AI-prepared request for a `provisional` or `blocked` design item)*
 - `design-prep-inputs/design-prep-input-<seq>-PREP-<NNN>-r<revision>-<uuid>.md` *(implementation-planning only: append-only confirmed user/wizard response)*
 - `user-responses/user-response-<task-type>-<seq>.md` *(A sidecar downloaded under the same name by the HTML `Export user response` button; storing it here lets `--resume-clarification` automatically attach it to `clarification-response.md` in the instruction set — `clarification_items.clarification_response_with_sidecars`)*
@@ -98,10 +74,8 @@ Design-preparation storage has three separate authorities:
 | `design-prep-inputs/design-prep-input-<seq>-PREP-<NNN>-r<revision>-<uuid>.md` | user or wizard | Append-only and written only after semantic confirmation. Existing revisions are never edited or reserved before confirmation. |
 
 The resolver selects the highest unique revision whose assessment fingerprint still matches the approved snapshot. Duplicate revision numbers and stale fingerprints are skipped with warnings rather than granted authority. A markerless legacy plan has no sidecars to migrate: it proceeds with the `legacy-unassessed` warning. This compatibility path does not rewrite its report.
-The final result files (`final-report` MD / status) are not files that `okstra` creates by saving stdout.
-They are results written directly into the current run by Claude, based on the task bundle prepared by `okstra`.
-The self-contained HTML view is generated deterministically from a single final-report MD input by `okstra render-views <final-report.md>` (Phase 7 step 1.5). Generating the view does not modify the original MD.
-By contrast, `sessions/claude-resume-<task-type>-<seq>.sh` is an interruption-recovery helper that `okstra` creates before launching Claude.
+The final result files are not created by saving worker stdout. The report writer writes `final-report-<task-type>-<seq>.data.json`; Phase 7 derives the Markdown and HTML siblings deterministically. New bundles use `schemas/final-report-v2.0.schema.json` and `templates/reports/final-report-v2.template.md`: AI handoff Markdown and task-specific human HTML are rendered independently from the same v2 data.json. Existing schema v1 data uses `schemas/final-report-v1.0.schema.json` and the legacy `templates/reports/final-report.template.md` compatibility path. Rendering never modifies the source data or a pre-existing Markdown input.
+For the standalone Claude launcher, `sessions/claude-resume-<task-type>-<seq>.sh` remains an interruption-recovery compatibility helper. In-host Codex runs use host task continuity plus the generic `leadSession` manifest identity.
 
 The resolved run directory collects execution history. It divides its contents into type-specific subdirectories such as `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, and `worker-results/`, then distinguishes each run-level artifact and result file with a `-<task-type>-<seq>` suffix (a three-digit, zero-padded per-category counter, such as `001` or `002`).
 Worker prompt history is retained not under `/tmp`, but always as a canonical artifact under `prompts/` for the current run.
@@ -167,7 +141,7 @@ Path segments are normalized into slugs. If a slug would be empty, as can happen
 
 ## Task manifest contract
 
-`task-manifest.json` is the canonical metadata file Claude uses to understand task continuity.
+`task-manifest.json` is the canonical metadata file the active Okstra lead uses to understand task continuity.
 As a general rule, this manifest records the absolute `projectRoot` path only once and expresses the remaining generated paths as project-relative fields whenever possible.
 
 Examples of key fields:
@@ -204,12 +178,13 @@ Examples of key fields:
 - `inputs`
 - `artifacts`
 - `resultContract`
-- `claudeSession`
+- `leadSession`
+- `claudeSession` *(Claude-host compatibility only)*
 - `fixCycles` *(derived summary — `{count, openCycleId, latest:{cycle, symptom, targetReport, closedAt}}`; recalculated on every prepare)*
 
 This manifest serves the following purposes.
 
-- Let Claude understand task continuity before reading the brief
+- Let the active lead understand task continuity before reading the brief
 - Establish which files should be read first
 - Establish how config files and deployment manifests should be interpreted against expected values
 - Establish the task key under which results accumulate
@@ -247,9 +222,7 @@ Each execution records the current run contract in the resolved `<run-dir>/manif
 `state/active-run-context-<task-type>-<seq>.json` is also the compact intake for lead Phase 1 starting with schemaVersion `2.0`. It stores only `identity` + `pathHints` and worker identities instead of repeated path strings, and the deterministic dispatcher hydrates it into the legacy active context shape when reading it.
 
 The path fields in `manifests/run-manifest-<task-type>-<seq>.json` are still stored as paths relative to the target project root for validator, team dispatch, and inspect compatibility.
-Immediately after `okstra` starts the Claude handoff, the current run status is usually recorded as `in-progress`.
-Claude then continues with saving the final results and updating status.
-Before launch, `okstra` also preallocates a session ID and creates, under the same run's `sessions/` directory, `claude-resume-<task-type>-<seq>.sh`.
+An in-host prepare records the run as `prepared` and the task as `ready-for-lead`; the current native host session then owns execution. The standalone Claude launcher records `in-progress` after preparing its compatibility resume script.
 
 Main contents:
 
@@ -262,7 +235,8 @@ Main contents:
 - related tasks
 - selected workers
 - worker model assignments
-- claude session id
+- lead session id and accounting mode
+- Claude session id only on the Claude compatibility path
 - resume command relative path
 - expected report relative path
 - expected status relative path
@@ -296,9 +270,9 @@ The history generally includes the following.
 - `fixCycleId` *(only when attached to a fix cycle; field omitted otherwise)*
 Reruns of the same task type reuse the same resolved run directory family. Non-stage runs use `runs/<task-type>/`, while `implementation` and single-stage `final-verification` runs use `runs/<task-type>/stage-<N>/`. Sequence-specific artifacts live beneath that resolved run directory, and each execution accumulates as a separate history entry because `run-manifest-<task-type>-<seq>.json` and related artifact paths are separated by per-category sequence suffixes (`<task-type>-<seq>`). The cross-category identifier is the manifest's `runDateTimeSegment` ISO timestamp field.
 
-## Claude operating contract
+## Lead operating contract
 
-After `okstra` runs, Claude should follow this default sequence when reading the current task.
+After `okstra` prepares a run, the host-native Okstra lead follows this default sequence when reading the current task.
 
 1. If task browsing or task-id disambiguation is required, first read `.okstra/discovery/task-catalog.json`.
 2. If the current task key or task path is not specified, read `.okstra/discovery/latest-task.json` as the current-task pointer.
@@ -309,13 +283,13 @@ After `okstra` runs, Claude should follow this default sequence when reading the
 6. Read `task-index.md` only when a quick summary is needed.
 7. Lazily read `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, and `final-report-template.md` when the packet is insufficient or when source citations/report writing require them.
 8. Consult `history/timeline.json` and previous run results if necessary.
-9. As `Claude lead`, organize roles according to the current run's worker roster (`Claude worker`, `Codex worker`, and `Report writer worker` by default; `Antigravity worker` only when explicitly included).
+9. As `Okstra lead`, organize roles from `workerAssignments[]`. The host provider stays native; Claude, Codex, Antigravity, Grok, and Kimi assignments use their persisted `native-session` or `cli-wrapper` runner.
 10. Save each selected worker prompt under the current run's `prompts/` directory at the assigned worker prompt history path before dispatching the worker.
     Every selected initial analyser receives the same full-core semantic body for its task, including final-verification. Dispatch and Phase 7 validate the same normalized equality policy; implementation executor, report-writer, and `-reverify-r<N>-` prompts are separate audiences.
 11. In convergence Round 0, the lead groups findings by semantic meaning and ticket set, then writes `state/convergence-groups-<task-type>-<seq>.json`. The deterministic engine seeds the working queue and generates each roster-aware reverify plan; lightweight reverify reads only that persisted batch and its embedded evidence.
 12. Collect a result or terminal status for each required worker.
-13. Unless the brief requires a more specific format, write the final Markdown report using the `final-report-template.md` structure.
-14. Save the result directly to `reports/final-report-<task-type>-<seq>.md` for the current run and, if necessary, update `status/final-<task-type>-<seq>.status`, `manifests/run-manifest-<task-type>-<seq>.json`, `task-manifest.json`, and `task-index.md` to match the current state.
+13. Write the final structured report to `reports/final-report-<task-type>-<seq>.data.json` using the versioned schema and exactly one task-type deliverable.
+14. Run Phase 7 so the AI handoff Markdown and task-specific human HTML are independently derived, then update `status/final-<task-type>-<seq>.status`, `manifests/run-manifest-<task-type>-<seq>.json`, `task-manifest.json`, and `task-index.md` to match the current state.
 
 Convergence keeps its decision trail under the run's `state/` directory: