okstra 0.117.0 → 0.119.0

package/docs/cli.md

@@ -0,0 +1,658 @@
+# okstra — CLI Argument and Option Manual
+
+> This document supplements [README.md](../README.md). For internal architecture and storage/workflow contracts, see [architecture.md](architecture.md).
+>
+> This manual covers the phase-execution flags of `okstra.sh`. For the subcommand reference of the separate `okstra container` entry point, see [container.md](container.md).
+
+---
+
+## Index
+
+- [Command forms](#command-forms)
+- [Required arguments](#required-arguments)
+  - [`--project-id`](#--project-id)
+  - [`--task-group`](#--task-group)
+  - [`--task-id`](#--task-id)
+  - [`--task-type`](#--task-type)
+  - [`--task-brief`](#--task-brief)
+  - [`--yes`](#--yes)
+- [Optional arguments and options](#optional-arguments-and-options)
+  - [`--task-key`](#--task-key)
+  - [`--clarification-response`](#--clarification-response)
+  - [`--resume-clarification`](#--resume-clarification)
+  - [`--project-root`](#--project-root)
+  - [`--directive`](#--directive)
+  - [`--fix-cycle`](#--fix-cycle)
+  - [`--workers`](#--workers)
+  - [`--lead-runtime`](#--lead-runtime)
+  - [`--claude-model`](#--claude-model)
+  - [`--lead-model`](#--lead-model)
+  - [`--codex-model`](#--codex-model)
+  - [`--antigravity-model`](#--antigravity-model)
+  - [`--report-writer-model`](#--report-writer-model)
+  - [`--executor`](#--executor)
+  - [`--critic`](#--critic)
+  - [`--approved-plan`](#--approved-plan)
+  - [`--approve`](#--approve)
+  - [`--work-category`](#--work-category)
+  - [`--base-ref`](#--base-ref)
+  - [`--related-tasks`](#--related-tasks)
+  - [`--render-only`](#--render-only)
+  - [`--no-plan-verification`](#--no-plan-verification)
+- [Interactive input flow](#interactive-input-flow)
+- [Confirmation flow](#confirmation-flow)
+- [okstra Control Center — installation and common commands](#control-center-install-and-common-commands)
+- [okstra Control Center](#okstra-control-center)
+  - [Installation (global wrapper)](#install-global-wrapper)
+  - [Common commands](#common-commands)
+  - [`okstra` Node CLI — introspection subcommands](#okstra-node-cli--introspection-subcommands)
+  - [Live-log sidecar](#live-log-sidecar)
+
+---
+
+## Command forms
+
+Base command for initial entry with full arguments:
+
+```bash
+scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-runtime claude-code|codex] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--antigravity-model <model>] [--report-writer-model <model>] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
+```
+
+Short form for a later phase when an existing task-manifest.json is available:
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> [--task-type <task-type>]
+```
+
+Immediately resume after answering clarification items:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
+```
+
+The following additional rules apply in an interactive terminal:
+
+- Missing required arguments are read directly from stdin.
+- Once all inputs are available, a summary is shown before execution.
+- Creation or execution proceeds only when you enter `y` or `yes`.
+- Non-interactive runs do not prompt for missing arguments and exit with an error instead.
+- `--yes` skips both prompts and confirmation, but all required arguments must already be present.
+- Precedence is `explicit CLI argument > interactive prompt or non-interactive error`.
+
+## Required arguments
+
+### `--project-id`
+
+A globally unique project ID. On the first run, it self-registers in `<PROJECT_ROOT>/.okstra/project.json`. On later runs from the same PROJECT_ROOT, okstra exits immediately if the argument differs from the stored `projectId`.
+
+Examples:
+
+- `sample-project-v2-api`
+- `jobs`
+
+### `--task-group`
+
+A logical group for related tasks.
+
+Examples:
+
+- `feature-8858`
+- `bugfix-auth`
+- `tasks`
+
+### `--task-id`
+
+A stable task identifier that can be reused within the same group.
+
+Examples:
+
+- `email-recipient-loss`
+- `8852`
+
+### `--task-type`
+
+The single input that determines the purpose of this run, profile selection, run-directory segment, and lifecycle phase routing.
+For standard values and phase-specific responsibilities, see [Task type](#--task-type) above.
+
+#### `--task-type improvement-discovery`
+
+`improvement-discovery` is a sidetrack entry point outside `PHASE_SEQUENCE`. It uses multi-worker consensus to find improvement candidates within the codebase scope and lens allowlist.
+
+- Input: a brief with the frontmatter marker `scope: codebase`.
+  - `priority-lenses`: one to four values. The lens allowlist is the `LENSES` constant in `scripts/okstra_ctl/improvement_lenses.py`.
+  - `scan-scope`: one or more paths.
+  - `out-of-scope`: optional.
+  - `candidate-cap`: 1–12; default 8.
+- Output: the `## 5.9 Improvement Candidates` table with 10 columns: Cand ID / Lens / Title / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Evidence.
+- Verdict Token: `candidates-ready` / `no-candidates` / `blocked`.
+- Routing: there is no automatic spin-off. The user selects candidates and starts each under a new task ID with `requirements-discovery`, `implementation-planning`, or `error-analysis`.
+- Workers: claude + codex + antigravity + report-writer are all required.
+- Two bidirectional grilling points: an enhanced Step 4 in `okstra-brief-gen` with a budget of 8, and the lead's Phase 1.5 reflect-back with a budget of 12.
+- Validator: `validators/validate_improvement_report.py` enforces the 11-part contract for an `improvement-discovery` final report.
+- Because an `improvement-discovery` run is not in `PHASE_SEQUENCE`, the `--task-key` short form does not automatically populate `nextRecommendedPhase` for it.
+
+### `--task-brief`
+
+The path to the task brief that serves as the basis for analysis.
+Relative paths are resolved from the target project root.
+
+This argument does not apply to `release-handoff`: a brief is input to an entry phase
+(requirements-discovery / error-analysis / improvement-discovery), while
+release-handoff preparation automatically creates an input document that cites the verification report
+at `<task_root>/release-handoff-input.md` and uses it in place of a brief.
+A non-empty `--task-brief` is rejected immediately for release-handoff.
+
+Examples:
+
+- `.project-docs/linear/feature/8858/okstra-task-brief.md`
+- `.project-docs/tasks/8852/BUG_REPORT.md`
+
+### `--yes`
+
+Skips interactive prompts and confirmation.
+
+The following values are required instead:
+
+- `project-id`
+- `task-group`
+- `task-id`
+- `task-type`
+- `brief-path`
+
+If any required argument is missing, the command exits immediately without prompting.
+
+Example:
+
+```bash
+scripts/okstra.sh --yes --render-only --task-type error-analysis --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+## Optional arguments and options
+
+### `--task-key`
+
+A short form that supplies `--project-id`, `--task-group`, and `--task-id` together when starting a later phase for an existing task.
+
+- Input format: `<project-id>:<task-group>:<task-id>`
+- Behavior:
+  - Splits the value into the three IDs and populates `PROJECT_ID`, `TASK_GROUP`, and `TASK_ID`.
+  - If the same values are also provided explicitly, they are accepted only when they match; a conflict exits immediately with an error.
+  - If the task has a `task-manifest.json`, a missing `--task-brief` is filled from the manifest's `taskBriefPath`, and a missing `--task-type` is filled from `workflow.nextRecommendedPhase`.
+  - Without a manifest, as on initial entry, the normal missing-argument validation remains in effect and full arguments are required.
+- Explicit arguments always take precedence over manifest values.
+- When `nextRecommendedPhase` is `pending-routing-decision` or `done-or-follow-up`, it is not filled automatically. Supply `--task-type` explicitly or supplement the brief, then rerun the command.
+
+Examples:
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852
+```
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
+```
+
+### `--clarification-response`
+
+Carries a previous run's final report—with user answers filled inline in `## 1. Clarification Items`—into the next run.
+
+- Input: a path matching `<previous-run>/reports/final-report-<task-type>-<seq>.md`.
+- Behavior: copies the file to the current run's `instruction-set/clarification-response.md`. In Section 0, the lead updates the `Status` of previous `Q*` rows to `resolved` or `obsolete`, then continues.
+- Use it after a phase such as `requirements-discovery`, `error-analysis`, or `implementation-planning` leaves unresolved questions or approval-blocking clarification. Fill in the answers, then carry the report into the next phase or a resume of the same phase.
+
+Example:
+
+```bash
+scripts/okstra.sh \
+  --task-type implementation-planning \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md \
+  --clarification-response .okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
+```
+
+### `--resume-clarification`
+
+Immediately edits the final report from the previous `requirements-discovery` or `error-analysis` run and automatically reruns the same phase. You do not need to manage the `--clarification-response` path manually.
+
+- Input: task identity supplied as `--project-id` + `--task-group` + `--task-id`, or as `--task-key <p>:<g>:<i>`.
+- Sequence:
+  1. Automatically selects the latest timestamped file under the task's `runs/{requirements-discovery,error-analysis}/reports/final-report-*.md` paths.
+  2. Opens the file with `$EDITOR`, or `vi` when unset. Fill answers inline in the Section 5 `Q*` rows, save, and exit.
+  3. okstra invokes itself again with `exec` for the same task type and carries the edited file in through `--clarification-response`.
+  4. Confirmation, rendering, and Claude handoff then proceed as in a normal run.
+- When an explicit `--task-type` is supplied, only that task type's reports are searched. Otherwise, okstra searches `error-analysis` and then `requirements-discovery` and uses the report with the later timestamp.
+- It cannot be combined with `--render-only`, `--clarification-response`, or `--approved-plan`.
+- Setting `EDITOR` to a non-interactive tool such as `true` skips answer editing and immediately reruns the task. This is recommended only for debugging.
+
+Examples:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key jobs:tasks:8852
+```
+
+```bash
+EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --task-group tasks --task-id 8852
+```
+
+Internally, this is equivalent to:
+
+```bash
+$EDITOR <project-root>/.okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
+scripts/okstra.sh --task-type <same-type> \
+  --project-id <p> --task-group <g> --task-id <i> \
+  --task-brief <from manifest> \
+  --clarification-response <edited final-report-<latest>.md>
+```
+
+### `--project-root`
+
+The absolute path to the target project. When omitted, `okstra.sh` resolves it in this order:
+
+1. Find the current directory or nearest ancestor containing `.okstra/project.json` and use it as PROJECT_ROOT.
+2. If that fails, use the result of `git rev-parse --show-toplevel`.
+3. If both fail, exit immediately with an error.
+
+On the first run from the resolved PROJECT_ROOT, `<PROJECT_ROOT>/.okstra/project.json` is created automatically with this schema:
+
+```json
+{
+  "projectId": "<--project-id argument value>",
+  "projectRoot": "<resolved absolute path>",
+  "createdAt": "<ISO8601 UTC>",
+  "updatedAt": "<ISO8601 UTC>"
+}
+```
+
+If the file already exists, okstra checks that `projectId` matches and updates only `projectRoot` and `updatedAt`. A mismatched `projectId` exits immediately, preventing two IDs from being used in the same directory.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
+```
+
+### `--directive`
+
+A free-text channel for passing user intent to the lead, workers, and downstream skills. The value is embedded in a `## Directive` section at the end of `instruction-set/analysis-material.md` and in `instruction-set/analysis-packet.md`, the analysis workers' primary input. It is also backed up to `instruction-set/directive.txt`.
+
+Use it to:
+
+- Override a default heuristic—for example, request a Gantt chart even for one XL task with two phases totaling about 10 days, or request an explicit reason for omitting one. `## Cumulative Timeline` has been removed from the schedule contract and is no longer a toggle.
+- Direct the emphasis of analysis or planning—for example, prioritize rollout risks or report missing test coverage as a separate finding.
+- Suggest Phase/Step divisions or day estimates in advance—for example, Part 1: 4d, measurement: 0.5d, Part 2: 4d, operations: 1d.
+
+Interpretation rules:
+
+- The lead and analysis workers read the compact intake (`active-run-context`, `analysis-packet.md`) first, so the directive propagates without separate work. `analysis-material.md` is a fallback when the packet is insufficient or source citations must be verified.
+- A skill must give the user prompt **precedence** over its own contract—for example, the "Directive override (highest priority)" section of the `okstra-schedule` skill. When a heuristic is overridden, the result document states that fact in one line.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning ... \
+  --directive "Use two sequential phases (Part 1 ~4d, Part 2 ~5d) for ~10d total. Include a Gantt chart with the critical path."
+```
+
+### `--fix-cycle`
+
+- `--fix-cycle <yes|no>` records whether re-entry into an entry phase (`requirements-discovery` / `error-analysis` / `implementation-planning`) after completion through release-handoff is a bug-fix cycle. When omitted, no cycle is recorded. The `fix_cycle_confirm` step in the okstra-run wizard accepts the same input.
+- `yes` opens a new cycle only when both conditions hold: the task type is an entry phase, and the manifest's `workflow.lastCompletedPhase` is `release-handoff`. Preparation rejects the request if either condition is false. Once a cycle is open, later runs for the same task attach to it automatically without this flag.
+
+### `--workers`
+
+Directly specifies the workers used in this run.
+The default is `claude,codex,report-writer`. Antigravity is optional; add it explicitly when needed, as in `--workers claude,codex,antigravity,report-writer`.
+When supplied, only the deduplicated worker subset is recorded.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--lead-runtime`
+
+Selects the lead execution adapter. The default is `claude-code`.
+
+Lead runtime independence boundary:
+
+- `claude-code`: the current default execution path. Claude Code v2.1.178 removed `TeamCreate`, and the session owns an implicit team. Workers are dispatched with `Agent(name: ..., run_in_background: true)` without `team_name`. `teamName` is audit/display metadata; Claude session JSONL is used for usage accounting.
+- `codex`: the runtime marker for the Codex lead adapter. `okstra codex-run` owns `--render-only --lead-runtime codex` to prepare a task bundle, and the prepared run manifest can be passed to `okstra codex-dispatch` for CLI-backed worker execution.
+- `external`: without Claude Code Teams, `--render-only --lead-runtime external` prepares the task bundle and external lead prompt. The lead manages the tmux-pane worker lifecycle with `okstra team dispatch`, `okstra team await`, and `okstra team teardown`. This path does not use `TeamCreate` / `Agent(...)` and uses artifact-only accounting.
+
+The current Claude Code independence boundary covers the external lead prompt and `okstra team *` worker dispatch. non-render `okstra_ctl.run --lead-runtime external` remains blocked; a complete external lead driver remains separate future work. `--runtime external` only selects the runtime adapter. `okstra install` creates `~/.agents/skills/` by default and also installs Claude skills and agents when `~/.claude` exists. Selecting the `claude` worker still requires the local Claude CLI wrapper.
+
+### Runtime auto-detection (`auto`)
+
+`okstra run` defaults to `auto`. `auto` resolves to one of `claude-code`, `codex`, or `external` based on the host through `src/lib/runtime-resolver.mjs`. Precedence: explicit runtime > the `OKSTRA_RUNTIME_HOST` environment variable > Claude Code skill handoff > external when tmux is available > fail fast otherwise. The safe fallback never silently selects a runtime different from the user's intent.
+
+- Inside Claude Code, `/okstra-run` is the front door. bare `okstra run` cannot invoke Claude Code `TeamCreate` / `Agent(...)`.
+- On a Codex host, `okstra run` orchestrates `codex-run` -> `codex-dispatch`.
+- In a generic terminal with tmux, `okstra run` orchestrates `render-bundle --lead-runtime external` -> `okstra team dispatch` -> `okstra team await`.
+
+`doctor` and `render-bundle` also default to `auto`, but a plain terminal without a host signal must specify a host. `okstra install` and `ensure-installed` are exceptions. Installation places the shared runtime and skill targets based on agent homes rather than the runtime host, so it records the `auto` request and unresolved state in the manifest and continues even without a host signal. Skill copy targets depend on the presence of agent homes and the default Agent target policy, not runtime resolution. `~/.agents/skills/` is always created, and Claude skills/agents are installed when `~/.claude` exists. Claude Code skills explicitly specify `--runtime claude-code` / `--lead-runtime claude-code`, so execution does not depend on host auto-detection.
+
+`installed-runtimes.json` uses schemaVersion 2 and separates `installRequest`, `runtimeResolution`, `installedRuntimes`, and `installedAssets`. `installed-skills.json` uses a schemaVersion 2 target list with `provider`, `root`, and `skills` to record Claude and Agent skill targets; uninstall removes files according to this list. `codexAdapter` / `externalAdapter` retain read compatibility with v1 manifests only.
+
+For a Codex lead dry run, use `okstra codex-run <args...>`. It adds `--render-only --lead-runtime codex` itself and prints the prepared task bundle and lead prompt without dispatching workers.
+The generated team-state, run manifest, and task manifest point `leadEventsPath` to `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl`; rendering records a `bundle-prepared` event.
+Then `okstra codex-dispatch --project-root <dir> --run-manifest <run-manifest> --workers codex[,antigravity[,report-writer]]` executes workers through the existing CLI wrappers. Without `--workers`, it automatically selects the Codex-side supported workers from the run roster: `codex`, `antigravity`, and an opted-in `report-writer`. Explicitly requesting an unsupported worker fails. `report-writer` requires explicit opt-in with `--enable-codex-report-writer --report-writer-codex-model <model>`; on success, postprocessing runs token-usage substitution → render-views → spawn-followups → validate-run in order.
+
+The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are separate. The former selects a worker provider dispatched by a Claude Code lead; the latter is the upper runtime boundary for running the lead itself through the Codex adapter.
+
+> Every `--*-model` flag accepts only aliases registered in the provider mappings in `scripts/okstra_ctl/models.py`. An unregistered value is immediately rejected with `UnknownModelError`, preventing a contract violation where the manifest's `modelExecutionValue` differs from the actual execution value. Allowed values:
+> - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `fable`, `fable-5`, `claude-fable-5`, `opus`, `opus-4-8`, `claude-opus-4-8`, `opus-4-7`, `claude-opus-4-7`, `opus-4-6`, `claude-opus-4-6`, `sonnet`, `sonnet-4-6`, `claude-sonnet-4-6`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`
+> - Codex (`--codex-model`): `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
+> - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-3.5-flash`, and the space-separated aliases `gemini 3.1 pro` / `gemini 3.5 flash`. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
+
+### `--claude-model`
+
+Selects the model used by the `Claude worker`.
+When omitted, it uses the central default `OKSTRA_DEFAULT_CLAUDE_MODEL`, falling back to `opus`.
+
+### `--lead-model`
+
+Selects the model used by the `Claude lead`.
+When omitted, it uses the central default `OKSTRA_DEFAULT_LEAD_MODEL`, falling back to `opus`.
+
+### `--codex-model`
+
+Selects the model used by the `Codex worker`.
+When omitted, it uses the central default `OKSTRA_DEFAULT_CODEX_MODEL`, falling back to `gpt-5.5`.
+
+### `--antigravity-model`
+
+Selects the model used by the `Antigravity worker`.
+When omitted, it uses the central default `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL`, falling back to `auto`.
+
+### `--report-writer-model`
+
+Selects the model used by the `Report writer worker`.
+When omitted, it uses the central default `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`, falling back to the lead default.
+
+The central-default environment variables are:
+
+- `OKSTRA_DEFAULT_LEAD_MODEL`
+- `OKSTRA_DEFAULT_CLAUDE_MODEL`
+- `OKSTRA_DEFAULT_CODEX_MODEL`
+- `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL`
+- `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
+- `OKSTRA_DEFAULT_EXECUTOR` (`claude` | `codex` | `antigravity`, fallback `claude`)
+
+Fallback defaults are:
+
+- `Claude lead`: `opus`
+- `Report writer worker`: `opus`
+- `Claude worker`: `opus`
+- `Codex worker`: `gpt-5.5`
+- `Antigravity worker`: `auto`
+- Implementation executor: `claude`, so the default is `Claude executor`.
+
+### `--executor`
+
+Selects the provider that performs the Executor role for `--task-type implementation`. The value is `claude`, `codex`, or `antigravity`; it is ignored for other task types.
+
+- Default: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`.
+- The Executor is the **only worker allowed to mutate project files** in this run. The other two providers are dispatched as strict read-only verifiers in the same run.
+- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.5`; with `--executor antigravity`, it comes from `--antigravity-model`, default `auto`.
+- All three Claude, Codex, and Antigravity verifiers are always dispatched regardless of the Executor provider. Even the verifier using the same provider runs in a separate CLI session with isolated context, preserving the self-review safeguard.
+- Codex and Antigravity mutate files through each CLI's auto-edit mode, for example `codex exec --sandbox workspace-write`, without passing through Claude-side Edit/Write tools. Mutations occur in the task worktree described below. Both wrappers—`scripts/okstra-codex-exec.sh` and `scripts/okstra-antigravity-exec.sh`—receive the worktree path as their fourth positional argument and forward it through `--add-dir` for Codex or `--include-directories` for Antigravity. Without it, the Codex `workspace-write` sandbox rejects worktree writes with EPERM.
+- **Claude Executor cwd handling**: Claude's Bash tool has no per-call cwd argument and inherits the lead session cwd. To run cwd-sensitive toolchains such as `cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, or `go` inside the worktree, prefix the invocation with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>`. Keep `cd` as the leading token in a single Bash call so Claude Code permission auto-allow works; do not wrap it in `bash -lc "..."` or `bash -c "..."`, which hides `cd` and causes a permission prompt on every call. Prefer a tool's working-directory option—such as `git -C <path>`, `cargo --manifest-path`, or `pytest --rootdir`—over a `cd && ` chain. Edit/Write/Read tools already use absolute paths and need no cwd handling. This rule applies only to the Claude Executor; the Codex and Antigravity wrappers inject cwd.
+- **Task worktree (automatic isolation for every task type)**: During the first phase's preparation for any task type, `okstra-ctl` creates a `git worktree` at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` and branches `<work-category-namespace>/<task-id-segment>` from the resolved commit of the user-selected `--base-ref`, for example `feature/dev-9436` or `fix/dev-7311`. Later phases for the same task key reuse the path and branch and record status `reused`; no new `git worktree add` occurs during run preparation. Special characters such as `/` and `:` in every segment are normalized to `-`, and `~/.okstra/worktrees/registry.json` globally manages task-key-to-path/branch mappings under flock. Executor edits, writes, builds, tests, and commits—and verifier reads—run in this worktree. If the caller is already in another worktree or project_root is not a Git repository, provisioning is skipped and records `skipped-in-worktree` or `skipped-not-git`. Path or branch collisions fail immediately with `PrepareError`. Worktrees are not deleted after a run; remove one manually with `git worktree remove`, then `git branch -D`, then delete the registry entry. **The implementation stage isolation below is the exception.**
+- **`implementation` stage isolation (concurrent parallelism)**: The task-key worktree above applies only from `requirements-discovery` through `implementation-planning`. Each `implementation` run executes in a **stage-specific isolated worktree** at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/stage-<N>/`, on branch `<work-category-namespace>/<task-id-segment>-s<N>`. The registry atomically reserves a stage key, `<task-key>#stage-<N>`, under flock. `_resolve_effective_stages` excludes `started` rows in `consumers.jsonl` and reserved stages. Stage selection, worktree creation, and registry reservation all happen in one critical section protected by the task-key provisioning mutex at `~/.okstra/.locks/worktree-provision/`, so concurrent `implementation` runs safely select different ready stages: **one run = one stage**. A stage worktree's base depends on its dependency shape: independent (`depends-on (none)`) uses the common anchor fixed once at first stage entry; a single dependency (`depends-on X`) uses the predecessor stage's completed `head_commit`; multiple dependencies (`depends-on X,Y…`) use task-worktree HEAD after all predecessors have been merged, verified with `git merge-base --is-ancestor`, and otherwise fail with `PrepareError` and merge guidance. Select the stage with `--stage <auto|N>` for `okstra.sh`/`render-bundle`, or with the okstra-run wizard's `stage_pick` step. If `project_root` is not a Git repository or is a nested worktree, stage isolation also degrades to flat operation.
+- **Single-stage `final-verification` artifact isolation**: `--task-type final-verification --stage <N>` reuses the implementation stage worktree read-only from the registry. Run artifacts are isolated per stage under `runs/final-verification/stage-<N>/`, and the team name receives a `-fv-s<N>` suffix. Concurrent final-verification runs for different stages do not collide in state, worker results, or team names. For concurrent verification of the same stage, `teamName` is only an audit label and each session has its own implicit team, so the sessions can coexist without a TeamCreate/name collision. This statement is limited to per-session team identity and does not claim safety for shared mutable state. Whole-task verification with an empty stage keeps the flat `runs/final-verification/` layout.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type implementation \
+  --executor codex \
+  --codex-model gpt-5.5 \
+  --approved-plan .project-docs/.../runs/implementation-planning/.../reports/final-report-implementation-planning-001.md \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--critic`
+
+Selects the provider for the opt-in Phase 5.6 critic pass. The value is `off`, `claude`, `codex`, or `antigravity`; the default is `off`.
+
+- Critic dispatch runs concurrently with the first convergence reverify round in Phase 5.5, with critic input fixed to the integrated Round 0 result. One gap/blocker verification round runs in Phase 5.6 after convergence finishes. It detects coverage gaps in discovery, error-analysis, and implementation-planning, and acts as an acceptance devil's advocate in final-verification. Follow the "Coverage critic pass" and "Acceptance critic pass" sections of `prompts/lead/convergence.md` for the detailed contract.
+- It shares the same value space as the critic-selection step in the in-session `okstra-run` wizard. `_resolve_model_bindings` in `prepare_task_bundle` validates the value; anything else is rejected immediately with `PrepareError`.
+
+### `--approved-plan`
+
+Accepts the path to a previous `implementation-planning` final report as input to `--task-type implementation`. The file's YAML frontmatter must contain an `approved` field whose value is `true`.
+
+Approval format:
+
+- Exactly one line inside the final report's leading `---` YAML fence: `approved: true` or `approved: false`.
+- Case-insensitive; `True` and `TRUE` are also accepted.
+- The report writer always publishes `approved: false`. Implementation becomes available after the user toggles it to `true`.
+
+When frontmatter is not `approved: true`, the run is rejected as `contract-violated`. Instead of editing the file directly, use `--approve` to treat the CLI invocation itself as the approval action.
+
+### `--approve`
+
+Used with `--approved-plan` and `--task-type implementation`, this flag **treats the CLI invocation itself as plan approval**:
+
+- Toggles `approved: false` to `approved: true` in the specified `--approved-plan` file's YAML frontmatter.
+- Appends the audit line (`- Approval time (CLI ack): <ISO8601> — recorded by \`okstra --approve\``) to the end of the file.
+- If the file is already `approved: true`, leaves frontmatter unchanged and adds the audit line only if it has never been recorded.
+- If the file has no YAML frontmatter or no `approved:` line, exits immediately with an error because the path may refer to the wrong plan file.
+
+Using `--approve` outside `--task-type implementation` is meaningless and exits with an error. Use it in CI or scripts, or when approval and the next phase must happen in a single command. The former `--ack-approved` alias was removed in 0.8.0.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type implementation \
+  --approve \
+  --approved-plan .project-docs/.../runs/implementation-planning/.../reports/final-report.md \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--work-category`
+
+Classifies the work in this task. Allowed values:
+
+- `bugfix`
+- `feature`
+- `refactor`
+- `ops`
+- `improvement`
+- `unknown` (default)
+
+Normally, the `requirements-discovery` phase infers work-category automatically. In a lifecycle that skips that phase—for example, one starting directly at `implementation-planning`—use this flag to classify the work explicitly. The value is preserved in `task-manifest.json` and used for grouping by the schedule and status skills.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning \
+  --work-category refactor \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/PLAN.md
+```
+
+### `--base-ref`
+
+The Git ref used as the base when the isolated worktree for a task key is first created. It may be a branch name, tag, or commit SHA.
+
+- Required during first-phase preparation. The `okstra-run` skill collects it through the same menu as the PR base picker: `main`, `dev`, `staging`, `preprod`, `prod`, or custom input.
+- Later phases for the same task key reuse the worktree path, branch, and base ref stored in the registry, so a new value is ignored.
+- If `project_root` is not a Git repository or is already inside a non-main worktree, provisioning is skipped and this value is unused.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type requirements-discovery \
+  --base-ref main \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BRIEF.md
+```
+
+### `--related-tasks`
+
+Accepts a comma-separated list of related task identifiers.
+
+Example:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,reply-ui --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+Related tasks are reference metadata and do not replace the current task key.
+
+### `--render-only`
+
+Creates the prompt and task bundle without executing Claude.
+
+This mode does not:
+
+- Execute Claude.
+- Create `final-report-<task-type>-<seq>.md`.
+- Create `final-<task-type>-<seq>.status`.
+
+It does:
+
+- Create or update the stable task root.
+- Create or update `task-manifest.json`.
+- Create or update `task-index.md`.
+- Create or update `instruction-set/`.
+- Create or update `instruction-set/reference-expectations.md`.
+- Create or update `instruction-set/final-report-template.md`.
+- Record the current `manifests/run-manifest-<task-type>-<seq>.json`.
+- Update `history/timeline.json`.
+- Create or update the project-level discovery pointer.
+
+### `--no-plan-verification`
+
+Disables the Phase 6 plan-body verification round for the `implementation-planning` task type. It is enabled by default and ignored for other task types.
+
+- **Enabled (default)**: Immediately after the report-writer worker drafts the final report in Phase 6, the lead divides the synthesized plan's §5.5 implementation plan deliverables—Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback—into `P-*` plan items and dispatches them for reverification to every analyzer worker: `claude`, `codex`, and opted-in `antigravity`. Worker verdicts (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) are aggregated into one of four gate results: `passed`, `passed-with-dissent`, `blocked-by-disagreement`, or `aborted-non-result`. The `- [ ] Approved` marker is rendered at the top of the final report only for `passed` or `passed-with-dissent`. Items with majority DISAGREE become rows with `Blocks=approval` in `## 1. Clarification Items`. There is no automatic revision; the user answers and resumes the same phase.
+- **Disabled (with `--no-plan-verification`)**: The entire Phase 6 substep is skipped and the Approval marker is always rendered at the top of the final report, matching legacy behavior. This is a fast-iteration opt-out and is not recommended for a handoff-ready plan.
+- The flag records `false` in the manifest at `convergence.planBodyVerification.enabled`. The resume command must include the same flag to preserve behavior; `_canonical_argv` guarantees faithful emission on resume.
+- For the detailed round protocol, verdict semantics, and state-file schema, see the "Plan-body verification mode (implementation-planning only)" section of `prompts/lead/convergence.md`.
+
+## Interactive input flow
+
+When required arguments are omitted in an interactive terminal, `okstra` may ask for these values in order:
+
+- `Project ID`
+- `Task Group`
+- `Task ID`
+- `Task Type`
+- `Task Brief Path`
+
+For example:
+
+```bash
+scripts/okstra.sh --render-only --task-type error-analysis
+```
+
+The command reads missing required values from stdin, then proceeds through the final summary and confirmation.
+
+## Confirmation flow
+
+Before creating files in an interactive run, okstra shows a summary containing:
+
+- Whether the run is render-only.
+- Task type.
+- Project ID.
+- Task group.
+- Task ID.
+- Task brief path.
+- Analysis target.
+- Related tasks.
+- Selected workers.
+- Lead model.
+- Configured worker models.
+- Task key.
+- Task root.
+- Current run directory.
+
+It then displays `Continue? [y/yes]:`. Any response other than `y` or `yes` exits without executing.
+
+`--yes` skips this confirmation flow entirely.
+
+---
+
+<a id="control-center-install-and-common-commands"></a>
+## okstra Control Center — installation and common commands
+
+## okstra Control Center
+
+`okstra-ctl` is a CLI for querying, monitoring, and rerunning okstra runs across all target projects through the indexes under the user's `~/.okstra/` home.
+
+<a id="install-global-wrapper"></a>
+### Installation (global wrapper)
+
+As with `okstra`, placing a wrapper under `~/.local/bin/` makes it available from any directory.
+
+```bash
+cat > ~/.local/bin/okstra-ctl <<'WRAPPER'
+#!/usr/bin/env bash
+exec /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-ctl.sh "$@"
+WRAPPER
+chmod +x ~/.local/bin/okstra-ctl
+```
+
+`~/.local/bin` must be included in `PATH`.
+
+<a id="common-commands"></a>
+### Common commands
+
+| Purpose | Command |
+|---|---|
+| List projects with recorded work | `okstra-ctl projects` |
+| Find recent runs | `okstra-ctl list --since 7d` |
+| Restrict results to one project | `okstra-ctl list --project sample-project` |
+| View in-progress runs | `okstra-ctl tail active` |
+| Show metadata for one run | `okstra-ctl show <runId-or-prefix>` |
+| Print the result-report path | `okstra-ctl open <runId-or-prefix>` |
+| Regenerate a final-report HTML view | `okstra render-views <final-report.md>` |
+| Rerun one run | `okstra-ctl rerun <runId-or-prefix> --yes` |
+| Rerun multiple filtered runs | `okstra-ctl rerun --filter --project X --status failed --yes` |
+| Rerun the latest matching run | `okstra-ctl rerun last --project X --task-group Y --yes` |
+| Backfill or rescan indexes | `okstra-ctl reindex` |
+| Reconcile active runs | `okstra-ctl reconcile [--project <id|all>]` |
+| Show batch progress | `okstra-ctl batch status <batch-id>` |
+
+### `okstra` Node CLI — introspection subcommands
+
+The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and introspection commands used by skills and agents. It goes through the Node wrapper instead of invoking the Python runtime directly, so `src/lib/python-helper.mjs` wires `PYTHONPATH`.
+
+| Command | Purpose |
+|---|---|
+| `okstra paths [--field <name>\|--shell]` | Print package, runtime, home, bin, Python path, and version locations |
+| `okstra install [--runtime claude-code\|codex\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | Install or update the runtime, templates, skills, and agents. The default runtime is `auto`; skill targets are not runtimes. `~/.agents/skills/` is always created, and Claude skills and agents are also installed when `~/.claude` exists |
+| `okstra ensure-installed [--runtime claude-code\|codex\|external\|all] [-q]` | Check installation state and reinstall stale assets for the same runtime. Default `auto` continues without a host signal and checks drift in the Agent skill target and any existing Claude target |
+| `okstra uninstall [--purge -y]` | Remove installed assets. By default, removes files listed by the `installed-skills.json` targets and `installed-agents.json` while preserving user data |
+| `okstra doctor [--runtime claude-code\|codex\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, and skill/agent installation. The `codex` and `external` runtimes omit Claude skill checks. `--phase` adds readiness checks for `implementation`, `final-verification`, `release-handoff`, or `improvement-discovery` |
+| `okstra setup --project-id <id>` | Create or update `.okstra/project.json` in the current project |
+| `okstra check-project [--json]` | Verify that the current project is registered |
+| `okstra preflight [--runtime <name>] [--cwd <dir>] [--json]` | Single skill-preflight call combining `ensure-installed`, with silent reinstall when stale, and `check-project` into one JSON response. Step 0 of every project-scoped skill converges on this command |
+| `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Manage persistent settings such as `pr-template-path` with atomic JSON writes |
+| `okstra memory <add\|list\|search\|show\|archive>` | Manage global conversation memory in `~/.okstra/memory-book`, a user-home store separate from project `.okstra/` and the CLI basis of the `save this in okstra` natural-language skill |
+| `okstra manager <init\|discover-projects\|new\|task>` | Public CLI for grouping cross-project okstra tasks into manager-owned context. `new project`, `new task-group`, and `new task` create manager plans; `task assign`, `task note`, `task sync`, `task status`, and `task run` manage per-project assignments and snapshots. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. Public documentation uses the full `project-id:task-group:task-id` child task key; when child task IDs differ within the same manager task, select the exact child with `--child-task-id`. `task run` does not execute the child lead directly; it returns `prepared` launch metadata/event and a child launch-context packet as JSON |
+| `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]` | Read-only backend for the okstra-rollup skill. For every catalog task, or one task group, it emits JSON with per-task run counts, raw duration in ms, error counts, latest report paths, group totals, and status/category/phase distributions. Omitting `--task-group` targets the whole project catalog. The caller skill formats raw ms as HH:MM:SS and synthesizes report prose. Use the `okstra inspect` family for a single-task drill-down |
+| `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | One-time migration of the project artifact root from `.project-docs/okstra/` to `.okstra/`. It is a dry run by default; `--apply` performs the move with `git mv` in a Git worktree, removes an empty `.project-docs/`, and synchronizes the `<PROJECT>/CLAUDE.md` import line, `.gitignore`, the project's rows in `~/.okstra/{recent,active}.jsonl`, and `~/.okstra/worktrees/registry.json`. It exits 1 if `.okstra/` already exists or the legacy directory is absent. Scheduled for removal by the end of v0.x |
+| `okstra task-list [--project-root <path>]` | Combine `list_project_tasks` and `read_latest_task` into JSON containing the task catalog and latest task |
+| `okstra task-show <task-key> [--project-root <path>]` | Summarize workflow, phase, status, and artifacts from the Task Read-Side Snapshot |
+| `okstra set-work-status <token> <todo\|in-progress\|blocked\|done> [--note <text>] [--task-group <g>] [--project-root <dir>]` | Update user-managed `workStatus` in task-manifest.json, along with `workStatusUpdatedAt` and, when `--note` is supplied, `workStatusNote`. `<token>` is a full task key or bare task ID. It uses the manifest renderer's serialization rules and returns `stage:"ambiguous"` plus `matches[]` when ambiguous |
+| `okstra worktree-lookup <task-key>` | Return the `worktree_registry.lookup` result: reserved path, branch, base ref, and current status |
+| `okstra plan-validate <plan-path>` | Run `_validate_approved_plan` and report frontmatter `approved` recognition plus unresolved Blocks=approval rows |
+| `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>]` | Thin shim over `prepare_task_bundle(render_only=True)` with the same signature as `python3 -m okstra_ctl.run --render-only`. `--stage` is for `implementation` and `final-verification`: for implementation, `auto` (default) selects the earliest incomplete stage with satisfied dependencies, while `<N>` forces a stage; for final-verification, `<N>` verifies one stage with artifacts under `runs/final-verification/stage-<N>/` and a `-fv-s<N>` team suffix, while an empty value performs whole-task verification with the flat layout. The separate `--stages <csv>` channel is for `release-handoff`: stage-group mode bundles the listed stage numbers into one PR, while an empty value selects whole-task mode. Preparation enforces eligibility—`done` + accepted `verified` + not yet `pr`—and automatically creates an input document that cites verification reports |
+| `okstra codex-run <args…>` | Codex lead-adapter dry-run entry point. Accepts the same arguments as `render-bundle` but owns `--render-only --lead-runtime codex`. It prepares the task bundle and prints the prompt for the Codex lead without dispatching workers |
+| `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers codex,antigravity,report-writer]` | Read a run manifest prepared by `codex-run` and execute the Codex-side supported worker subset. Without `--workers`, unsupported roster members such as `claude` are skipped; explicitly requesting one fails. The report writer requires opt-in with `--enable-codex-report-writer --report-writer-codex-model <model>`. On success, it automatically performs token-usage substitution, HTML view rendering, follow-up task-stub generation, and run validation |
+| `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down tmux-pane workers. If a tmux pane cannot be created, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
+| `okstra render-views <final-report.md>` | Phase 7 step 1.5: deterministically create a human-facing self-contained sibling `*.html` view from one final-report Markdown file after token substitution. The source Markdown is unchanged. The Node delegation wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies form-control placement, absence of external URLs, stale source digests, and Response ID parity |
+| `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, and improvement-discovery. Downstream phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |
+| `okstra token-usage ...` | Wrap the installed `okstra-token-usage.py` to collect and substitute run token usage. Session JSONL is incrementally scanned by default through a byte-cursor cache at `$OKSTRA_HOME/cache/token-usage/`; `--no-cache` bypasses the cache and forces a full rescan as an accuracy fallback |
+
+> Every subcommand is wired to `PYTHONPATH` and `~/.okstra/lib/python` by the Python helper (`src/lib/python-helper.mjs`) spawned by `bin/okstra`. When invoking `python3 -m okstra_ctl.*` directly, you must configure `PYTHONPATH` yourself.
+
+### Live-log sidecar
+
+For every dispatch, the Codex and Antigravity wrappers create a `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar and mirror stdout and stderr into it. When the lead runs inside tmux, the wrapper automatically splits a `tail -F` pane. The trace pane title is `<cli>-<role>-<pid>-tail`, and the caller/worker pane title is `<cli>-<role>-<pid>`; the wrapper PID distinguishes concurrent dispatches with the same role. Split trace panes are tagged with the `@okstra_trace_run=<RUN_DIR>` pane user option, and tmux-pane backend worker-compute panes with `@okstra_worker_run=<RUN_DIR>`. When Claude receives `/exit`, the `SessionEnd` hook automatically cleans them up within `$CLAUDE_PROJECT_DIR/.okstra/` scope by running `okstra-trace-cleanup.sh --reap`. When the lead calls the same script with `--run-dir <RUN_DIR>`, it removes the run's trace panes, worker-compute panes, and dispatched worker-agent panes within the lead-session scope, while excluding the lead's own pane. Worker-agent titles include `claude-worker`, `codex-worker`, `antigravity-worker`, `report-writer-worker`, implementation role titles, and FleetView teammate prefixes `✳ ` / `⠂ `. Before entering a new phase, the lead runs `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` once to clear stale panes.