okstra 0.117.0 → 0.118.0

package/README.md

@@ -1,126 +1,133 @@
 # okstra
 
 > npm: [`okstra`](https://www.npmjs.com/package/okstra) · install: `npx -y okstra@latest install`
->
-> 한국어 매뉴얼: [`README.kr.md`](README.kr.md)
 
 ## Index
 
-- [1. Purpose](#1-purpose)
-- [2. Structure](#2-structure)
-  - [2.1 Repo layout](#21-repo-layout)
-  - [2.2 User-machine layout after install](#22-user-machine-layout-after-install)
-  - [2.3 Single-authority map](#23-single-authority-map)
-- [3. Manual](#3-manual)
-  - [3.1 First-time setup (once per machine)](#31-first-time-setup-once-per-machine)
-  - [3.2 Register a project (once per project)](#32-register-a-project-once-per-project)
-  - [3.3 Day-to-day commands](#33-day-to-day-commands)
-  - [3.4 CLI mode (optional)](#34-cli-mode-optional)
-  - [3.5 Ops commands](#35-ops-commands)
-- [4. Further reading](#4-further-reading)
-
+- [1. Purpose](#purpose)
+- [2. Structure](#structure)
+  - [2.1 Repo layout](#repo-layout)
+  - [2.2 User-machine layout after install](#user-machine-layout-after-install)
+  - [2.3 Single-authority map](#single-authority-map)
+- [3. Manual](#manual)
+  - [3.1 First-time setup (once per machine)](#first-time-setup)
+  - [3.2 Register a project (once per project)](#register-a-project)
+  - [3.3 Day-to-day commands](#day-to-day-commands)
+  - [3.4 CLI mode (optional)](#cli-mode)
+  - [3.5 Operations commands](#ops-commands)
+- [4. Further reading](#further-reading)
+
+<a id="purpose"></a>
 ## 1. Purpose
 
-`okstra` is a **structured task-execution runner for Claude Code that cross-verifies work with a lead + worker model**. The Claude lead drives phase progression and dispatches independent analysis workers — **Claude and Codex by default** (with **Antigravity** available as an opt-in extra) — plus a dedicated report-writer for the final synthesis.
+`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.
 
 The design rests on three principles:
 
-- **Single entry point (`prepare_task_bundle`)**: every caller — skill, bash CLI, in-session — produces the same task directory layout, manifest, and validation paths.
-- **Persistent task identity**: a stable `<project-id>/<task-group>/<task-id>` key carries context across phases, sessions, and model upgrades.
-- **Mandatory lead/worker contract**: output schemas and validation are bound to `templates/` + `validators/`; the worker roster is fixed per phase.
+- **Single entry point (`prepare_task_bundle`)**: every caller—skill, Bash CLI, or in-session invocation—produces the same task directory layout, manifest, and validation paths.
+- **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.
 
-okstra is **not** a one-shot code reviewer. It targets work that **spans multiple phases, needs multiple agents to weigh in, and where each phase's output feeds the next**.
+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>
 ## 2. Structure
 
+<a id="repo-layout"></a>
 ### 2.1 Repo layout
 
 ```
 okstra/                          npm package = repo root
 ├── package.json                 name: "okstra"
-├── bin/okstra                   Node CLI entrypoint
+├── bin/okstra                   Node CLI entry point
 ├── src/                         Node CLI command modules (install, wizard, config, render, token usage, ...)
-├── tools/build.mjs              runtime/ sync script (invoked by prepack)
+├── tools/build.mjs              runtime/ synchronization script (invoked by prepack)
 ├── runtime/                     gitignored install payload copied to ~/.okstra
-├── scripts/                     python + bash runtime sources
-├── skills/                      public skill markdown sources (9 user-facing skills)
-├── agents/                      worker agent markdown sources
+├── scripts/                     Python + Bash runtime sources
+├── skills/                      public skill Markdown sources (8 user-facing skills)
+├── agents/                      worker agent Markdown sources
 ├── prompts/, schemas/, templates/, validators/
+├── docs/                        English manuals (architecture, CLI, storage, container, performance)
 ├── tests/, tests-e2e/
 ├── .claude-plugin/plugin.json   secondary skills-CLI channel manifest
 ├── .github/workflows/           release-please.yml, release.yml
-└── RELEASING.md, CHANGELOG.md, README.md, README.kr.md
+└── RELEASING.md, CHANGELOG.md, README.md
 ```
 
-`runtime/` is rebuilt from `scripts/`, `skills/`, `agents/`, `prompts/`, `schemas/`, `templates/`, and `validators/` by `tools/build.mjs` during `prepack`. It is the install payload copied into `~/.okstra`; the npm package also ships the Node CLI (`bin/`, `src/`), docs, and READMEs.
+During `prepack`, `tools/build.mjs` rebuilds `runtime/` from `scripts/`, `skills/`, `agents/`, `prompts/`, `schemas/`, `templates/`, and `validators/`. This is the install payload copied to `~/.okstra`; the npm package also ships the Node CLI (`bin/`, `src/`), documentation, and the README.
 
+<a id="user-machine-layout-after-install"></a>
 ### 2.2 User-machine layout after install
 
 ```
-~/.okstra/                       runtime home, populated by `okstra install`
+~/.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, ...
-├── templates/                   report assets, settings template
-├── installed-runtimes.json      manifest of installed runtime adapters
-├── installed-skills.json        manifest of installed skills (used by uninstall)
-├── installed-agents.json        manifest of installed worker agents (used by uninstall)
-├── recent.jsonl, active.jsonl   run index
-├── memory-book/                 global conversation memory (okstra memory)
-├── projects/                    per-project metadata mirror
+├── templates/                   report assets and settings templates
+├── prompts/                     lead operating contracts (prompts/lead/*) + coding-preflight resource pack
+├── installed-runtimes.json      installed runtime adapter manifest
+├── installed-skills.json        installed skill manifest (used by uninstall)
+├── installed-agents.json        installed worker agent manifest (used by uninstall)
+├── recent.jsonl, active.jsonl   run indexes
+├── memory-book/                 global conversation memory (`okstra memory`)
+├── projects/                    per-project metadata mirrors
 ├── worktrees/                   one isolated git worktree per task-key
-│                                (shared by all phases; not auto-removed)
+│                                (shared by all phases; not removed automatically after a run)
 ├── archive/                     completed runs
 └── .locks/                      central/task mutex files
 
-~/.claude/skills/                discovered automatically by Claude Code (if ~/.claude exists)
-~/.agents/skills/                discovered by Agent-compatible hosts (created by install)
-└── okstra-*/SKILL.md            user-facing skills only (setup/brief/run/memory/inspect/schedule/container/manager)
+~/.claude/skills/                automatically discovered by Claude Code (when `~/.claude` exists)
+~/.agents/skills/                discovered by Agent-compatible hosts (created by `install`)
+└── okstra-*/SKILL.md            8 user-facing skills only (setup/brief/run/memory/inspect/schedule/container/manager)
 
-~/.claude/agents/                discovered automatically by Claude Code (if ~/.claude exists)
-└── {claude,codex,antigravity,report-writer}-worker.md   subagent definitions
+~/.claude/agents/                automatically discovered by Claude Code (when `~/.claude` exists)
+└── {claude,codex,antigravity,report-writer}-worker.md   worker subagent definitions
                                  (required for Claude Code multi-agent dispatch)
 
 <project-root>/.okstra/
-├── project.json                 {projectId, projectRoot, ...} (written by /okstra-setup)
+├── project.json                 {projectId, projectRoot, ...} (written by `/okstra-setup`)
 ├── discovery/{task-catalog,latest-task}.json
 ├── glossary.md                  okstra-owned project terminology
 ├── decisions/<NNNN>-<slug>.md   okstra-owned decision records
 └── tasks/<task-group>/<task-id>/   task bundle (runs, manifest, reports)
 ```
 
+<a id="single-authority-map"></a>
 ### 2.3 Single-authority map
 
 | Resource | Location | Owner |
 |---|---|---|
-| Runtime code (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
-| agents/prompts/schemas/templates/validators | npm package's `runtime/` | the `okstra` package (resolved via `okstra paths`) |
-| Skill markdown | `~/.claude/skills` or `~/.agents/skills` | `okstra install` (tracked per target in `installed-skills.json`) |
-| Worker agent markdown | `~/.claude/agents/<worker>.md` | `okstra install` when `~/.claude` exists (tracked in `installed-agents.json`) |
+| Runtime code (Python + Bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
+| agents/prompts/schemas/templates/validators | npm package `runtime/` | the `okstra` package itself (resolved by `okstra paths`) |
+| Skill Markdown | `~/.claude/skills` or `~/.agents/skills` | `okstra install` (tracked per target in `installed-skills.json`) |
+| Worker agent Markdown | `~/.claude/agents/<worker>.md` | `okstra install` when `~/.claude` exists (tracked in `installed-agents.json`) |
 | Project metadata | `<project>/.okstra/` | `/okstra-setup` + the project itself |
-| Run index | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
+| Run indexes | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 
+<a id="manual"></a>
 ## 3. Manual
 
+<a id="first-time-setup"></a>
 ### 3.1 First-time setup (once per machine)
 
 ```bash
 npx -y okstra@latest install
 ```
 
-Provisions `~/.okstra/{lib/python, bin, templates, prompts, version}` and the installed-asset manifests in `~/.okstra/`. Skill installation is host-home driven: if `~/.claude` exists, okstra copies public skills to `~/.claude/skills/` and worker agents to `~/.claude/agents/`; it always creates `~/.agents/skills/` and copies public skills there for Agent-compatible hosts. Lead/support contracts ship as runtime resources under `~/.okstra/prompts/` and are not agent skills. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
+This creates `~/.okstra/{lib/python, bin, templates, prompts, version}` and the installed asset manifests under `~/.okstra/`. Skill installation is based on host homes: if `~/.claude` exists, public skills are installed in `~/.claude/skills/` and worker agents in `~/.claude/agents/`; `~/.agents/skills/` is always created and receives public skills for Agent-compatible hosts. Only user entry-point skills appear in skill listings. Lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/`, outside skill discovery. Re-running the command is idempotent: per-file hashes are compared and only changed files are updated.
 
-Verify:
+Verify the installation:
 
 ```bash
 npx -y okstra@latest doctor
 ```
 
-A `result: OK` line means you're ready. Any FAIL row prints its remediation in-line (usually: rerun install).
+A `result: OK` line means the installation is ready. Each FAIL row prints its remediation inline—usually, rerun the install command.
 
 #### Optional: install the `okstra` command globally
 
-Every example in this README uses `npx -y okstra@latest <cmd>` so you don't need a global install. If you'd rather type a bare `okstra` (and skip npx's fetch / version-check on each invocation), install it globally:
+Every example in this README uses `npx -y okstra@latest <cmd>`, so a global install is unnecessary. To invoke okstra with a bare `okstra` command and avoid npx package fetching and version checks on every call, install it globally:
 
 ```bash
 npm i -g okstra
@@ -128,49 +135,52 @@ okstra --version       # confirm the CLI is on PATH
 okstra install          # same as 'npx -y okstra@latest install'
 ```
 
-The global install only registers the Node CLI on your PATH. The runtime (`~/.okstra/`) and host skill directories (`~/.claude/skills/` or `~/.agents/skills/`) are still provisioned by `okstra install` — they are not part of `npm i -g`. To upgrade later: `npm i -g okstra@latest && okstra install`. To remove the global binary: `npm uninstall -g okstra` (leaves `~/.okstra/` untouched; remove that with `okstra uninstall`).
+The global install only registers the Node CLI on PATH. The runtime (`~/.okstra/`) and host skill directories (`~/.claude/skills/` or `~/.agents/skills/`) are still created by `okstra install`; they are not included in `npm i -g`. To upgrade later, run `npm i -g okstra@latest && okstra install`. To remove the global binary, run `npm uninstall -g okstra` (this leaves `~/.okstra/` intact; remove that with `okstra uninstall`).
 
-**Skill behaviour with a global install.** All okstra skills auto-detect a PATH-resolved `okstra` and prefer it over `npx -y okstra@latest`. That means a global install removes the per-call npx fetch / version-check from every skill invocation (Step 0 of `okstra-run`, `okstra-inspect`, `okstra-schedule`, `okstra-setup` Step 2). Since the skill uses your globally installed version directly, *you* control upgrade timing — `@latest` is no longer forced on each call. Run `npm i -g okstra@latest && okstra install` whenever you want to pull a new release. If `okstra` is not on PATH the skill silently falls back to npx, so machines without a global install keep working unchanged.
+**Skill behavior with a global install.** Every okstra skill detects a PATH-resolved `okstra` command and prefers it over `npx -y okstra@latest`. A global install therefore removes the npx fetch/version-check cost from every skill invocation (Step 0 of `okstra-run`, `okstra-inspect`, `okstra-schedule`, and Step 0 of `okstra-setup` Step 2). Because each skill uses the installed version directly, **you control when upgrades happen**; `@latest` is no longer forced on every call. Run `npm i -g okstra@latest && okstra install` whenever you want a new release. If `okstra` is not on PATH, the skills automatically fall back to npx, so environments without a global install continue to work unchanged.
 
+<a id="register-a-project"></a>
 ### 3.2 Register a project (once per project)
 
 From the CLI:
 
 ```bash
-cd <your project>
+cd <target-project>
 npx -y okstra@latest setup --project-id <id>     # e.g. INV-1234, my-app, okstra
 ```
 
-Or, inside a Claude Code session, invoke the equivalent slash command:
+Or invoke the equivalent slash command inside a Claude Code session:
 
 ```
 /okstra-setup
 ```
 
-Both write `<project>/.okstra/project.json`. The CLI is non-interactive when `--project-id` is given (use it in CI); the slash command prompts via `AskUserQuestion`. Every other user-facing skill refuses to proceed until that file exists.
+Both commands write `<project>/.okstra/project.json`. With `--project-id`, the CLI is non-interactive and can be used in CI; the slash command prompts through `AskUserQuestion`. Every other user-facing skill refuses to run until this file exists.
 
+<a id="day-to-day-commands"></a>
 ### 3.3 Day-to-day commands
 
-User-facing slash commands inside a Claude Code session:
+Use these slash commands inside a Claude Code session:
 
-| Command | Use |
+| Command | Purpose |
 |---|---|
-| `/okstra-brief-gen` | Turn a ticket, requirements doc, link, or conversation into an `okstra-run` task brief |
-| `/okstra-run` | Start a new task (or resume the next phase of an existing one) |
-| `/okstra-memory` | Store/search/archive global conversation memory in `~/.okstra/memory-book` |
-| `/okstra-inspect` | Unified read-side. Sub-commands: `status` (phase / state, workStatus update), `history` (past runs, re-run, resume), `report` (find/read final-report), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory + cleanup), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `error-zip` (collect cross-project error logs into an anonymized zip and summarize clusters), `recap` (run-to-run before/after summary + free-form Q&A over a task's `.okstra` artifacts) |
-| `/okstra-rollup` | Roll up run results across every task in a task-group (or the whole project) — per-task runs/time/errors plus group totals — and synthesize a cross-task digest from the report files |
-| `/okstra-schedule` | Generate a work schedule for an entire task-group |
-| `/okstra-container-build` | Deploy a verified task's code as a local docker compose group and watch each container's logs (sub-commands: `up` / `status` / `logs` / `stop-watcher` / `down`) |
-| `/okstra-graphify` | Build and query a knowledge graph over the project's own `.okstra/` memory (final reports, `decisions/*.md`, `glossary.md`), scoped to `.okstra/` with outputs under `.okstra/graph/` (sub-commands: `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
+| `/okstra-brief-gen` | Convert a ticket, requirements document, link, or conversation into an `okstra-run` task brief |
+| `/okstra-run` | Start a new task or continue an existing task's next phase |
+| `/okstra-memory` | Store, search, and archive global conversation memory in `~/.okstra/memory-book` |
+| `/okstra-inspect` | Unified read side. Subcommands: `status` (phase/state and workStatus updates), `history` (past tasks, reruns, resumes), `report` (find/read final reports), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory and cleanup suggestions), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `error-zip` (collect cross-project error logs into an anonymized zip and summarize clusters), and `recap` (run-to-run before/after summary plus free-form Q&A over a task's `.okstra` artifacts) |
+| `/okstra-rollup` | Aggregate every task run in a task group or project, including per-task run counts, duration, errors, group totals, and a cross-task report digest |
+| `/okstra-schedule` | Generate a work schedule for an entire task group |
+| `/okstra-container-build` | Deploy a verified task's code as a local Docker Compose group and monitor per-container logs (subcommands: `up` / `status` / `logs` / `stop-watcher` / `down`) |
+| `/okstra-graphify` | Build and query a knowledge graph over the project's own `.okstra/` memory—final reports, `decisions/*.md`, and `glossary.md`—with scope restricted to `.okstra/` and output under `.okstra/graph/` (subcommands: `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
 | `/okstra-manager` | Coordinate cross-project okstra tasks through manager-owned plans, assignments, one-way project sync snapshots, status, and child launch context packets |
-| `/okstra-setup` | Per-project bootstrap (§3.2) |
+| `/okstra-setup` | Bootstrap a project as described in §3.2 |
 
-The lead operating contract and its support contracts — context-loader, team-contract, convergence, report-writer, and the coding-preflight pack — are **not** installed as agent skills. They ship as okstra runtime resources under `~/.okstra/prompts/` (`prompts/lead/*.md` and `prompts/coding-preflight/*`) and the generated launch prompt hands the lead their absolute paths. Reinstalling prunes any earlier copies of these from the agent skill homes, so they never appear as slash commands.
+The lead operating contract and support contracts—context loader, team contract, convergence, report writer, and the coding-preflight pack—are no longer installed as agent skills. They are installed as okstra runtime resources under `~/.okstra/prompts/` (`prompts/lead/*.md`, `prompts/coding-preflight/*`), and the generated launch prompt gives the lead their absolute paths. Reinstallation prunes legacy copies from agent skill homes, so they are not exposed as slash commands.
 
+<a id="cli-mode"></a>
 ### 3.4 CLI mode (optional)
 
-To kick off a task from outside a Claude Code session:
+To start a task outside a Claude Code session:
 
 ```bash
 ~/.okstra/bin/okstra.sh \
@@ -182,49 +192,50 @@ To kick off a task from outside a Claude Code session:
   --task-brief ./brief.md
 ```
 
-Spawns a fresh `claude` process and hands it the lead role. Full argument list: `okstra.sh --help`, or the [Required arguments](README.kr.md#required-arguments) section in the Korean manual.
+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).
 
 Notable flags added in 0.7.0 / 0.8.0:
 
-- `--executor claude|codex|antigravity` — pick the provider that mutates files during `--task-type implementation`. The other two providers are still dispatched as read-only verifiers (see [`docs/kr/cli.md`](docs/kr/cli.md#--executor)).
-- `--work-category bugfix|feature|refactor|ops|improvement` — classify a task when the lifecycle skips `requirements-discovery`.
-- `--approve` — combined with `--approved-plan`, flips the plan's YAML frontmatter `approved` field from `false` to `true` (replaces the removed `--ack-approved` alias and the older `[ ] Approved` checkbox marker).
+- `--executor claude|codex|antigravity` — selects the provider that may mutate files for `--task-type implementation`. The other two providers are dispatched as strict read-only verifiers in the same run ([`docs/cli.md`](docs/cli.md#--executor)).
+- `--work-category bugfix|feature|refactor|ops|improvement` — directly classifies work when the lifecycle skips the `requirements-discovery` phase.
+- `--approve` — with `--approved-plan`, toggles the plan's YAML frontmatter `approved` field from `false` to `true`, replacing the removed `--ack-approved` alias and the former `[ ] Approved` checkbox marker.
 
-Recent workflow additions (post-0.8.0, on `main`):
+Major workflow changes added to `main` after 0.8.0:
 
-- **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-namespace>/<task-id-segment>` (e.g. `feature/dev-9436`, `fix/dev-7311`) branched from the **user-chosen base ref** (`--base-ref`, mirroring the `release-handoff` PR-base picker: `main` / `dev` / `staging` / `preprod` / `prod` / any local ref) the first time a task-key is seen. `--base-ref` is required on first phase; the okstra-run skill collects it via `AskUserQuestion`, non-interactive callers must pass the flag explicitly. Every subsequent **non-`implementation`** phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. `implementation` runs are **stage-isolated** instead — each run owns exactly one stage in its own `.../<task>/stage-<N>/` worktree on branch `<work-category-namespace>/<task>-s<N>`, so independent (`depends-on (none)`) stages can be implemented in parallel across simultaneous runs without sharing a tree. A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) reserves task-keys **and stage-keys** across concurrent runs; all path/branch segments are sanitised (`/`, `:`, etc. → `-`). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops (stage isolation degrades to the flat path too). Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus releasing/removing the key from the registry. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
-- **`release-handoff` lifecycle phase** — runs after `final-verification` returns `verdict=accepted`. The lead drafts a commit message and PR body via a Claude worker, then prompts the user with `AskUserQuestion` for three choices: action (`commit only` / `commit + PR` / `skip`), PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / free-form), and message handling (`use as-is` / `edit then proceed` / `cancel`). Only user-selected mutating git/gh commands run. Force-push, base-branch direct push, hook bypass (`--no-verify`), and release publishing (`gh release`, `npm publish`, ...) are forbidden. Source code is not edited in this phase. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **Configurable PR body template** (release-handoff) — the PR body is filled from a markdown template chosen in priority order: per-run override (`--pr-template-path` or the okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled 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 paths relative to the project root; global scope requires absolute or `~/`-prefixed). `okstra config get pr-template-path --scope all` reports every scope plus the effective winner. The bundled default ships `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` with HTML comment guidance that the lead strips before opening the PR.
-- **Profile-roster worker validation** — `--workers <csv>` (and the okstra-run Step 6 worker prompt) are now restricted to the worker IDs declared by the chosen profile's `Required workers:` block. Asking for `codex` / `antigravity` on a profile that does not list them (e.g. `release-handoff`) is rejected with a clear error, and the interactive prompt only offers workers the profile actually accepts.
-- **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>` can then run the supported Codex-side subset of the roster (Codex/Antigravity CLI workers by default; Codex report-writer only with `--enable-codex-report-writer --report-writer-codex-model <model>`). Successful Codex report-writer dispatch runs token/cost substitution, HTML view rendering, follow-up stub generation, and run validation in order. This shares the same manifests/schemas as the Claude lead path; it does not clone the project into a separate Codex-specific fork.
-- **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map plus N stage sections; each stage has ≤6 steps and stages whose `depends-on (none)` can be executed in parallel by separate `implementation` runs. Each `implementation` invocation picks one stage (via `--stage <auto|N>`) and emits an evidence sidecar (`carry/stage-<N>.json`) that the next stage automatically inherits. The `implementation-planning` run directory accumulates a `consumers.jsonl` reverse-link showing which `implementation` runs consumed which stage.
-- **Phase 6 plan-body verification (implementation-planning only)** — after the Report writer worker authors the final-report draft and before the user approval gate, the lead runs one additional verification round: it extracts `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` items from the consolidated `## 5.5` implementation plan deliverables body and dispatches them to every analyser worker as `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`. The aggregated gate result is one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`. The frontmatter `approved` flag is always emitted as `false`; blocking gate results keep it false and become `## 1. Clarification Items` rows. Details: [`prompts/lead/convergence.md`](prompts/lead/convergence.md) "Plan-body verification mode" and [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
-- **Brief as translation layer + reporter batch confirmation (Step 6.5)** — `okstra-brief-gen` now produces the brief as a translation layer that preserves external inputs (issue ticket, requirements doc, user message) verbatim while labelling okstra augmentations. A new Step 6.5 walks the user through a single batch confirmation of any rewordings, recorded in a `Reporter Confirmations` section. Every analysis profile blocks phase entry until this section exists (validator: `validators/validate-brief.py`).
-- **Artifact-home rule (`.okstra/`)** — okstra's project artifact root is only `<project>/.okstra/`. Anything outside that root is not okstra memory; it may be read only when explicitly cited as Source Material or Reporter Confirmations, and writes require the same explicit request path. okstra-internal equivalents: `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records (evaluated in `implementation-planning`).
-- **Self-contained HTML final-report view** — after Phase 7 writes `final-report-<task-type>-<seq>.md`, `okstra render-views` automatically emits a sibling self-contained HTML view (inline CSS/JS, no external URLs) in the same `reports/` directory for human review. The HTML lets a reviewer fill in `## 1. Clarification Items` decisions and export them to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`, which the next phase consumes as input. The original MD is never modified by view generation.
-- **`improvement-discovery` task-type (sidetrack entry-point)** — Discover ranked improvement candidates within a codebase scope and lens whitelist via multi-worker consensus (default top-8, hard cap 12). Outside `PHASE_SEQUENCE`; the user selects candidates and opens each as a new task 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: `## 4.9 Improvement Candidates` (10-column table). Validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
+- **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).
+- **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.
+- **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.
+- **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.
+- **`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: `## 4.9 Improvement Candidates` (10-column table). Validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
 
-### 3.5 Ops commands
+<a id="ops-commands"></a>
+### 3.5 Operations commands
 
-| Command | Use |
+| 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 + python import; `codex` skips Claude skill checks. `--phase` adds readiness checks for implementation, final-verification, release-handoff, or improvement-discovery |
-| `npx -y okstra@latest ensure-installed` | Idempotent check, auto-reinstall if stale (skills call this internally) |
-| `npx -y okstra@latest setup --project-id <id>` | Register the current project (`.okstra/project.json`) |
-| `npx -y okstra@latest check-project` | Verify the current project has been registered with `setup` |
-| `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Read / write okstra settings; initial key `pr-template-path` (writes `prTemplatePath` to project.json or `~/.okstra/config.json`) |
-| `npx -y okstra@latest memory <add\|list\|search\|show\|archive>` | Store and find global conversation memory in `~/.okstra/memory-book` |
-| `npx -y okstra@latest context-cost <task-key\|task-root> [--project-root <path>]` | Estimate lead/worker/report-writer context and read cost for a task bundle |
-| `npx -y okstra@latest render-views <final-report.md>` | Regenerate the self-contained HTML sibling view from a final-report MD (Phase 7 step 1.5; idempotent) |
-| `npx -y okstra@latest token-usage ...` | Collect/substitute token usage for a run; wraps the installed Python token usage CLI |
-| `npx -y okstra@latest uninstall` | Remove runtime + skills; preserves user data (`recent.jsonl`, `projects/`, …) |
-| `npx -y okstra@latest uninstall --purge -y` | Remove everything including user data |
-
+| `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 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 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 |
+
+<a id="further-reading"></a>
 ## 4. Further reading
 
-- [`README.kr.md`](README.kr.md) — Korean translation of this README.
-- [`docs/kr/architecture.md`](docs/kr/architecture.md) — internal architecture, prompt/team contracts, storage model, task-type phase rules, lifecycle (Korean).
-- [`docs/kr/cli.md`](docs/kr/cli.md) — full `okstra.sh` argument reference and interactive input flow (Korean).
-- [`RELEASING.md`](RELEASING.md) — how versions are cut and published (release-please + manual fallback).
-- [`CHANGELOG.md`](CHANGELOG.md) — release-by-release change log.
+- [`docs/architecture.md`](docs/architecture.md) — detailed manual covering prompt and team contracts, storage, task-type phase rules, lifecycle, and workflow.
+- [`docs/cli.md`](docs/cli.md) — complete reference for `okstra.sh` arguments, options, and interactive input flow.
+- [`RELEASING.md`](RELEASING.md) — version cutting and publication through release-please or the manual fallback.
+- [`CHANGELOG.md`](CHANGELOG.md) — per-release change history.