okstra 0.76.0 → 0.78.0

package/README.kr.md

@@ -63,6 +63,7 @@ okstra/                          npm 패키지 = repo 루트
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
 ├── templates/                   report asset, settings template
+├── installed-runtimes.json      설치된 runtime adapter 매니페스트
 ├── installed-skills.json        설치된 스킬 매니페스트 (uninstall 이 사용)
 ├── installed-agents.json        설치된 워커 에이전트 매니페스트 (uninstall 이 사용)
 ├── recent.jsonl, active.jsonl   run 인덱스
@@ -127,7 +128,7 @@ okstra --version       # CLI 가 PATH 에 잡혔는지 확인
 okstra install         # 'npx -y okstra@latest install' 와 동일
 ```
 
-글로벌 설치는 Node CLI 를 PATH 에 등록할 뿐입니다. 런타임(`~/.okstra/`) 과 Claude 스킬(`~/.claude/skills/`) 은 여전히 `okstra install` 이 생성합니다 — `npm i -g` 에 포함되지 않습니다. 이후 업그레이드: `npm i -g okstra@latest && okstra install`. 글로벌 바이너리 제거: `npm uninstall -g okstra` (`~/.okstra/` 는 그대로; 그것까지 지우려면 `okstra uninstall`).
+글로벌 설치는 Node CLI 를 PATH 에 등록할 뿐입니다. 런타임(`~/.okstra/`) 과 Claude 스킬(`~/.claude/skills/`) 은 여전히 `okstra install` 이 생성합니다 — `npm i -g` 에 포함되지 않습니다. 실험적 Codex lead adapter 용 공유 runtime 만 설치하려면 `okstra install --runtime codex` 를 사용하세요 (`~/.claude` 자산은 건너뜀). 이후 업그레이드: `npm i -g okstra@latest && okstra install`. 글로벌 바이너리 제거: `npm uninstall -g okstra` (`~/.okstra/` 는 그대로; 그것까지 지우려면 `okstra uninstall`).
 
 **글로벌 설치 시 스킬 동작.** 모든 okstra 스킬은 PATH 에 잡힌 `okstra` 를 자동 감지하여 `npx -y okstra@latest` 대신 우선 사용합니다. 즉 글로벌 설치를 해두면 매 스킬 호출(`okstra-run`, `okstra-inspect`, `okstra-schedule`, `okstra-setup` Step 2 의 Step 0) 마다 npx 가 패키지 fetch / 버전 체크하던 비용이 사라집니다. 스킬이 본인이 설치한 버전을 그대로 쓰므로 **업그레이드 타이밍은 사용자가 통제** 합니다 — 더 이상 호출마다 `@latest` 가 강제되지 않습니다. 새 릴리스를 받으려면 원하는 시점에 `npm i -g okstra@latest && okstra install` 을 실행하세요. `okstra` 가 PATH 에 없으면 스킬은 자동으로 npx fallback 으로 동작하므로 글로벌 설치가 없는 환경에서도 변경 없이 그대로 동작합니다.
 
@@ -189,8 +190,9 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 
 - **모든 task-type 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 task-key 당 한 번 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>` (예: `feat-dev-9436`, `fix-dev-7311`) 를 만듭니다. base ref 는 사용자가 `--base-ref` 로 지정 (release-handoff PR base picker 와 동일한 메뉴: `main` / `dev` / `staging` / `preprod` / `prod` / 직접 입력). 첫 phase 에서는 필수이며, okstra-run skill 이 `AskUserQuestion` 으로 수집합니다 — 비대화형 호출자는 `--base-ref` 플래그를 직접 전달해야 prepare 가 통과합니다. 같은 task-key 의 후속 **비-`implementation`** phase(`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`)는 같은 path/branch를 재사용합니다. 반면 `implementation` run 은 **stage 격리** 로 동작합니다 — 각 run 이 자신의 `.../<task>/stage-<N>/` worktree(브랜치 `<prefix>-<task>-s<N>`)에서 한 stage 만 실행하므로, 독립(`depends-on (none)`) stage 를 별도 run 으로 **동시에 병렬 구현** 할 수 있습니다(트리 공유 없음). registry 는 task-key 와 **stage-key** 를 함께 flock 예약합니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다(stage 격리도 평면 경로로 degrade). 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>` + registry 항목 release/remove. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md`](docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md), [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — `final-verification` 이 `verdict=accepted` 를 반환한 직후에 실행되는 신규 phase. lead 가 Claude worker (drafter) 를 통해 commit message · PR body 후보를 만들고, `AskUserQuestion` 으로 사용자에게 (1) action (`commit only` / `commit + PR` / `skip`), (2) PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력), (3) message handling (`use as-is` / `edit then proceed` / `cancel`) 세 가지를 순서대로 묻습니다. 사용자가 메뉴로 선택한 git / gh 명령만 실행되고, force-push, base 브랜치 직접 push, hook bypass (`--no-verify`), release publish (`gh release`, `npm publish`, ...) 는 금지됩니다. 이 phase 에서는 소스 코드를 수정하지 않습니다. profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/okstra-run/templates/pr-body.template.md`. 템플릿 등록 명령: `okstra config set pr-template-path <path> [--scope project|global]` (project 스코프는 project root 기준 상대경로 허용, global 스코프는 절대경로 또는 `~/` 시작 경로만 허용). 현재 설정 확인: `okstra config get pr-template-path --scope all` 은 각 스코프 값 + 실제로 우승하는 경로(effective) 까지 보여줍니다. 디폴트 템플릿은 `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` 4 섹션 + HTML 주석으로 lead 작성 가이드를 포함하며, PR 생성 직전에 lead 가 주석을 제거합니다.
+- **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/templates/prd/pr-body.template.md`. 템플릿 등록 명령: `okstra config set pr-template-path <path> [--scope project|global]` (project 스코프는 project root 기준 상대경로 허용, global 스코프는 절대경로 또는 `~/` 시작 경로만 허용). 현재 설정 확인: `okstra config get pr-template-path --scope all` 은 각 스코프 값 + 실제로 우승하는 경로(effective) 까지 보여줍니다. 디폴트 템플릿은 `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` 4 섹션 + HTML 주석으로 lead 작성 가이드를 포함하며, PR 생성 직전에 lead 가 주석을 제거합니다.
 - **프로파일 워커 로스터 검증** — `--workers <csv>` 와 okstra-run Step 6 의 워커 prompt 는 해당 프로파일의 `Required workers:` 블록에 선언된 워커 ID 만 허용합니다. 프로파일에 없는 워커 (예: `release-handoff` 에서 `codex` / `gemini`) 를 요청하면 명확한 에러로 거절되고, 인터랙티브 prompt 도 프로파일이 실제로 받는 워커만 보여줍니다.
+- **실험적 Codex lead adapter** — `okstra codex-run <render-bundle args...>` 가 Claude Code 를 띄우지 않고 `leadRuntime=codex` task bundle 을 준비합니다. 이어서 `okstra codex-dispatch --project-root <dir> --run-manifest <path>` 로 roster 중 Codex-side 지원 subset 을 실행합니다(Codex/Gemini CLI worker 기본, Codex report-writer 는 `--enable-codex-report-writer --report-writer-codex-model <model>` opt-in 필요). 성공한 Codex report-writer dispatch 는 token/cost substitution, HTML view 렌더, follow-up stub 생성, run validation 을 순서대로 자동 실행합니다. Claude lead 경로와 같은 manifest/schema 를 공유하며, 프로젝트를 Codex 전용 fork 로 복제하지 않습니다.
 - **다단계 `implementation-planning` / `implementation`** — `implementation-planning` 은 항상 Stage Map + N 개 stage 섹션으로 산출합니다. 각 stage 의 step 은 ≤ 6 이며 `depends-on (none)` 인 stage 들은 별도 `implementation` run 으로 병렬 실행할 수 있습니다. 각 `implementation` 호출은 한 stage 만 실행하고 (`--stage <auto|N>`), 자동 생성되는 evidence sidecar (`carry/stage-<N>.json`) 가 다음 stage 의 carry-in 으로 흡수됩니다. `implementation-planning` run 디렉터리에 `consumers.jsonl` 역링크가 누적되어 어느 run 이 어느 stage 를 소비했는지 추적됩니다.
 - **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, 사용자 승인 gate 직전에 lead 가 1 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 5.5` implementation plan deliverables 본문에서 `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` plan-item 을 추출해 모든 analyser 워커에게 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 평결을 요청합니다. 집계된 gate 결과는 `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result` 중 하나. frontmatter `approved` 필드는 항상 `false` 로 발행되며, gate 가 `blocked-by-disagreement` 또는 `aborted-non-result` 일 때 writer 는 `approved: false` 를 유지해야 하고 (이런 gate 결과로 `approved: true` 로 ship 된 report 는 validator 가 거부), `majority-disagree` 항목을 `## 1. Clarification Items` 의 `Blocks=approval` row 로 변환합니다. 빠른 반복용 opt-out: `--no-plan-verification` (기본값: 활성). 자세한 라운드 프로토콜은 [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) 의 "Plan-body verification mode" 섹션과 [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 - **Brief = translation layer + Step 6.5 reporter batch confirmation** — `okstra-brief` 가 외부 입력 (이슈 ticket, 요구사항 문서, 사용자 메시지) 을 verbatim 으로 옮기되 okstra 가 추가한 부분은 labelled augmentation 으로 구분하는 translation layer 가 됐습니다. Step 6.5 가 brief 가 옮기는 과정에서 의미 변화가 발생했는지 사용자에게 일괄 확인받아 `Reporter Confirmations` 섹션에 기록하고, 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
@@ -203,7 +205,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | 커맨드 | 용도 |
 |---|---|
 | `npx -y okstra@latest paths` | 런타임 경로 출력 (`--field <name>` 또는 `--shell`) |
-| `npx -y okstra@latest doctor` | 런타임 + 스킬 + python import 진단 |
+| `npx -y okstra@latest doctor [--runtime claude-code\|codex\|all] [--phase <phase>]` | 런타임 + 스킬 + python import 진단. `codex` 는 Claude skill checks 를 제외하고, `--phase` 는 implementation / final-verification / release-handoff / improvement-discovery readiness 체크를 추가 |
 | `npx -y okstra@latest ensure-installed` | Idempotent 체크, stale 이면 자동 재설치 (스킬이 내부적으로 호출) |
 | `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.okstra/project.json`) |
 | `npx -y okstra@latest check-project` | 현재 프로젝트가 `setup` 으로 등록됐는지 검증 |

package/README.md

@@ -62,6 +62,7 @@ okstra/                          npm package = repo root
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
 ├── bin/                         okstra.sh, codex-exec, gemini-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
@@ -126,7 +127,7 @@ 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 the Claude skills (`~/.claude/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 your PATH. The runtime (`~/.okstra/`) and the Claude skills (`~/.claude/skills/`) are still provisioned by `okstra install` — they are not part of `npm i -g`. To install only the shared runtime for the experimental Codex lead adapter, use `okstra install --runtime codex` (skips `~/.claude` assets). 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`).
 
 **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.
 
@@ -188,8 +189,9 @@ Recent workflow additions (post-0.8.0, on `main`):
 
 - **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` 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 `<prefix>-<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), [`docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md`](docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md), 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/okstra-run/templates/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.
+- **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` / `gemini` 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/Gemini 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 now 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`; when the gate is `blocked-by-disagreement` or `aborted-non-result` the writer MUST keep it `false` (the validator refuses any report that publishes `approved: true` under such a gate) and convert `majority-disagree` items into `## 1. Clarification Items` rows with `Blocks=approval`. Disable for fast iteration with `--no-plan-verification` (default: enabled). Details: [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.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` 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`).
@@ -202,7 +204,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 | Command | Use |
 |---|---|
 | `npx -y okstra@latest paths` | Print runtime paths (`--field <name>` or `--shell`) |
-| `npx -y okstra@latest doctor` | Diagnose runtime + skills + python import |
+| `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` |

package/bin/okstra

@@ -1,122 +1,6 @@
 #!/usr/bin/env node
 import { getPackageVersion } from "../src/version.mjs";
-
-const COMMANDS = new Map([
-  ["paths", () => import("../src/paths.mjs").then((m) => m.run)],
-  ["install", () => import("../src/install.mjs").then((m) => m.runInstall)],
-  [
-    "ensure-installed",
-    () => import("../src/install.mjs").then((m) => m.runEnsureInstalled),
-  ],
-  [
-    "uninstall",
-    () => import("../src/uninstall.mjs").then((m) => m.runUninstall),
-  ],
-  ["doctor", () => import("../src/doctor.mjs").then((m) => m.run)],
-  ["setup", () => import("../src/setup.mjs").then((m) => m.run)],
-  [
-    "check-project",
-    () => import("../src/check-project.mjs").then((m) => m.run),
-  ],
-  ["config", () => import("../src/config.mjs").then((m) => m.run)],
-  ["migrate", () => import("../src/migrate.mjs").then((m) => m.run)],
-  [
-    "git-reconcile",
-    () => import("../src/git-reconcile.mjs").then((m) => m.run),
-  ],
-  ["handoff", () => import("../src/handoff.mjs").then((m) => m.run)],
-  ["task-list", () => import("../src/task-list.mjs").then((m) => m.run)],
-  ["task-show", () => import("../src/task-show.mjs").then((m) => m.run)],
-  ["context-cost", () => import("../src/context-cost.mjs").then((m) => m.run)],
-  [
-    "worktree-lookup",
-    () => import("../src/worktree-lookup.mjs").then((m) => m.run),
-  ],
-  [
-    "plan-validate",
-    () => import("../src/plan-validate.mjs").then((m) => m.run),
-  ],
-  [
-    "render-bundle",
-    () => import("../src/render-bundle.mjs").then((m) => m.run),
-  ],
-  ["render-views", () => import("../src/render-views.mjs").then((m) => m.run)],
-  [
-    "render-final-report",
-    () => import("../src/render-final-report.mjs").then((m) => m.run),
-  ],
-  [
-    "inject-report-index",
-    () => import("../src/inject-report-index.mjs").then((m) => m.run),
-  ],
-  [
-    "spawn-followups",
-    () => import("../src/spawn-followups.mjs").then((m) => m.run),
-  ],
-  ["error-log", () => import("../src/error-log.mjs").then((m) => m.run)],
-  ["wizard", () => import("../src/wizard.mjs").then((m) => m.run)],
-  ["token-usage", () => import("../src/token-usage.mjs").then((m) => m.run)],
-  ["memory", () => import("../src/memory.mjs").then((m) => m.run)],
-]);
-
-const USAGE = `okstra — multi-agent cross-verification orchestrator for Claude Code
-
-This CLI is the installer/admin tool. Day-to-day usage happens inside a
-Claude Code session via slash commands (/okstra-setup, /okstra-run, ...).
-
-Quick start (CLI):
-  1. npx -y okstra@latest install                       # one-time, this machine
-  2. cd <your project>
-  3. npx -y okstra@latest setup --project-id <id>       # one-time, this project
-  4. open a Claude Code session and run /okstra-run     # start a task
-
-Inside a Claude Code session you can replace step 3 with /okstra-setup —
-both write the same <PROJECT_ROOT>/.okstra/project.json.
-
-Usage:
-  okstra <command> [options]
-
-Admin commands:
-  install                Install runtime to ~/.okstra and skills to ~/.claude/skills
-  ensure-installed       Verify install is fresh; reinstall if stale (idempotent)
-  uninstall              Remove runtime + skills (user data preserved by default)
-  setup                  Register the current project (.okstra/project.json)
-  doctor                 Diagnostic check of the installed runtime
-  check-project          Verify the current project has been registered with setup
-  config                 Read / write okstra settings (e.g. PR template path)
-  migrate                Move legacy .project-docs/okstra/ to .okstra/ (one-shot)
-  git-reconcile          Reconcile stale stage SHAs after external git history changes
-  handoff                Stage-group release-handoff helpers (eligible/assemble/record)
-  paths                  Print runtime paths (workspace/agents/pythonpath/bin/home/version)
-
-Introspection commands (JSON output, used by skills to avoid python heredocs):
-  task-list              List tasks registered in the current project
-  task-show              Summarize a task's manifest + workflow phase state
-  context-cost           Estimate file/read context cost for a task bundle
-  worktree-lookup        Look up registered worktree for a task-key
-  plan-validate          Check an approved-plan file for the approval marker
-  render-bundle          Preview prepare_task_bundle() output (forwards to
-                         python3 -m okstra_ctl.run --render-only)
-  wizard                 Drive the okstra-run interactive input state machine
-                         (init / step / render-args / confirmation)
-  token-usage            Collect token usage for a run (wraps the installed
-                         okstra-token-usage.py so skills avoid emitting
-                         python3 "$HOME/..." invocations).
-  render-views           Render slim AI + self-contained HTML views of a final report
-  render-final-report    Render the markdown sibling of a final-report data.json
-  inject-report-index    Add the top-of-report Index + scroll anchors to a report
-  spawn-followups        Create follow-up task bundles from a final report
-  error-log              Append run error events to the run error log
-  memory                 Store and find user-home conversation memory under
-                         ~/.okstra/memory-book.
-
-Global options:
-  --version              Print okstra version and exit
-  --help                 Print this help
-
-Run 'okstra <command> --help' for command-specific options.
-Docs: https://github.com/Devonshin/okstra#readme
-`;
+import { COMMANDS, USAGE } from "../src/cli-registry.mjs";
 
 async function main(argv) {
   const args = argv.slice(2);

package/docs/contributor-change-matrix.md

@@ -0,0 +1,12 @@
+# Contributor Change Matrix
+
+Use this matrix before changing high-risk repo contracts. Update the source files and the tests in the same row together.
+
+| Change | Must update | Tests |
+|---|---|---|
+| Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/kr/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
+| Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
+| Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/test_repo_contracts.py` | worker roster contract tests |
+| Change report section | `schemas/final-report-v1.0.schema.json`, `templates/reports/final-report.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
+
+`runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.

package/docs/kr/architecture.md

@@ -18,7 +18,7 @@
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](../../scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
 - **Required team contract**: 각 phase profile의 `Required workers:` 블록이 roster의 권위입니다. 일반 분석 phase는 Claude/Codex analyser + report-writer를 기본으로 하고, Gemini는 profile과 `--workers`가 허용할 때만 포함됩니다. `release-handoff`처럼 lead-only에 가까운 phase는 별도 roster를 가집니다.
-- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 11종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. 전역 대화 메모리는 프로젝트와 분리된 `~/.okstra/memory-book/` 에 저장됩니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 11종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. `--runtime codex` 는 실험적 Codex lead adapter 용 공유 runtime 만 설치하고 `~/.claude` 자산을 건너뜁니다. 전역 대화 메모리는 프로젝트와 분리된 `~/.okstra/memory-book/` 에 저장됩니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Derived views and telemetry**: final-report data.json → Markdown → slim MD / self-contained HTML view, worker error sidecar, wrapper log sidecar, token usage / cost accounting을 제공합니다.
 

package/docs/kr/cli.md

@@ -22,6 +22,7 @@
   - [`--directive`](#--directive)
   - [`--fix-cycle`](#--fix-cycle)
   - [`--workers`](#--workers)
+  - [`--lead-runtime`](#--lead-runtime)
   - [`--claude-model`](#--claude-model)
   - [`--lead-model`](#--lead-model)
   - [`--codex-model`](#--codex-model)
@@ -52,7 +53,7 @@
 기본 명령(첫 진입 / full args):
 
 ```bash
-scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--critic off|claude|codex|gemini] [--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>]
+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>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--critic off|claude|codex|gemini] [--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>]
 ```
 
 후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
@@ -307,6 +308,19 @@ scripts/okstra.sh --task-type implementation-planning ... \
 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`
+
+Lead 실행 adapter 를 지정합니다. 기본값은 `claude-code` 입니다.
+
+- `claude-code`: 현재 기본 실행 경로입니다. Claude Code lead 가 `TeamCreate` / `Agent(...)` / Claude session jsonl 기반으로 worker dispatch 와 사용량 집계를 수행합니다.
+- `codex`: Codex lead adapter 용 runtime marker 입니다. `okstra codex-run` 이 `--render-only --lead-runtime codex` 를 소유해 task bundle 을 준비하고, 준비된 run manifest 는 `okstra codex-dispatch` 로 CLI-backed worker 실행에 넘길 수 있습니다.
+
+Codex lead dry-run 은 `okstra codex-run <args...>` 를 쓰면 됩니다. 이 명령은 `--render-only --lead-runtime codex` 를 직접 붙이고, worker dispatch 없이 준비된 task bundle 과 lead prompt 를 출력합니다.
+생성된 team-state / run-manifest / task-manifest 는 `leadEventsPath` 로 `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl` 를 가리키며, render 단계는 `bundle-prepared` event 를 기록합니다.
+이후 `okstra codex-dispatch --project-root <dir> --run-manifest <run-manifest> --workers codex[,gemini[,report-writer]]` 가 기존 CLI wrapper 기반 worker 를 실행합니다. `--workers` 를 생략하면 run roster 중 Codex-side 지원 worker(`codex`, `gemini`, opt-in 된 `report-writer`)만 자동 선택하고, `claude` 처럼 지원하지 않는 worker 를 명시 요청하면 실패합니다. `report-writer` 는 명시 opt-in (`--enable-codex-report-writer --report-writer-codex-model <model>`) 이 필요하며, 성공 시 token-usage substitution → render-views → spawn-followups → validate-run 후처리를 순서대로 수행합니다.
+
+Codex worker(`--workers codex`, `--codex-model`)와 Codex lead runtime 은 별개입니다. 전자는 Claude Code lead 가 dispatch 하는 worker provider 선택이고, 후자는 lead 자체를 Codex adapter 로 실행하기 위한 상위 runtime 경계입니다.
+
 > 모든 `--*-model` 플래그는 `scripts/okstra_ctl/models.py` 의 provider 별 mapping 에 등록된 alias 만 허용합니다. 등록되지 않은 값은 `UnknownModelError` 로 즉시 거부됩니다 (manifest 의 `modelExecutionValue` 와 실제 실행값 불일치로 인한 contract-violation 을 사전에 차단). 허용값:
 > - 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`
@@ -592,10 +606,10 @@ chmod +x ~/.local/bin/okstra-ctl
 | 명령 | 용도 |
 |---|---|
 | `okstra paths [--field <name>\|--shell]` | package/runtime/home/bin/pythonpath/version 경로 출력 |
-| `okstra install [--refresh\|--dry-run\|--link <repo>]` | runtime, templates, skills, agents 설치/갱신 |
-| `okstra ensure-installed [-q]` | 설치 상태 확인, stale이면 재설치 |
+| `okstra install [--runtime claude-code\|codex\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | runtime, templates, skills, agents 설치/갱신. 기본값 `claude-code` 는 기존처럼 Claude skills/agents 까지 설치한다. `codex` / `external` 은 공유 runtime 만 설치하고 `~/.claude` 자산을 건드리지 않는다 |
+| `okstra ensure-installed [--runtime claude-code\|codex\|external\|all] [-q]` | 설치 상태 확인, stale이면 같은 runtime 으로 재설치. `codex` / `external` runtime 은 Claude skills/agents drift 검사를 건너뛴다 |
 | `okstra uninstall [--purge -y]` | 설치 자산 제거. 기본값은 사용자 데이터 보존 |
-| `okstra doctor` | runtime + Python import + skill/agent 설치 진단 |
+| `okstra doctor [--runtime claude-code\|codex\|external\|all] [--phase <phase>] [--json]` | runtime + Python import + skill/agent 설치 진단. `codex` / `external` runtime 은 Claude skill checks 를 제외한다. `--phase` 는 `implementation`, `final-verification`, `release-handoff`, `improvement-discovery` 실행 전 readiness 체크를 추가한다 |
 | `okstra setup --project-id <id>` | 현재 프로젝트의 `.okstra/project.json` 생성/갱신 |
 | `okstra check-project [--json]` | 현재 프로젝트가 등록되었는지 검증 |
 | `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | 영구 설정 관리 (예: `pr-template-path`). 원자적 JSON 쓰기 |
@@ -606,6 +620,9 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra worktree-lookup <task-key>` | `worktree_registry.lookup` 결과 (예약된 path / branch / base ref / 현재 상태) |
 | `okstra plan-validate <plan-path>` | `_validate_approved_plan` — frontmatter `approved` 인식 결과와 Blocks=approval 미해결 행 진단 |
 | `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>]` | `prepare_task_bundle(render_only=True)` 의 thin shim — `python3 -m okstra_ctl.run --render-only` 와 동일 시그니처. `--stage` 는 `implementation` / `final-verification` 전용: 실행(검증)할 Stage Map 항목 지정. `implementation` 은 `auto` (기본값) = 의존성이 만족된 가장 빠른 미완료 stage, `<N>` = 강제 지정. `final-verification` 은 `<N>` = 해당 stage 단독 검증(산출물이 `runs/final-verification/stage-<N>/` 에 격리되고 팀 이름에 `-fv-s<N>` 접미사), 빈 값 = 전체-task 검증(평면 구조 유지). `--stages <csv>` 는 `release-handoff` 전용(별개 채널): PR 로 묶을 stage 번호들(stage-group 모드), 빈 값 = whole-task 모드. prepare 가 eligibility(`done`+`verified` accepted+미-`pr`)를 강제하고 검증 보고서 인용 input 문서를 자동 생성한다 |
+| `okstra codex-run <args…>` | Codex lead adapter dry-run entrypoint. `render-bundle` 과 같은 인자를 받되 `--render-only --lead-runtime codex` 를 wrapper 가 소유한다. task bundle 을 준비하고 Codex lead 가 읽을 prompt 를 출력하지만 worker dispatch 는 하지 않는다 |
+| `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers codex,gemini,report-writer]` | `codex-run` 이 준비한 run manifest 를 읽어 Codex-side 지원 worker subset 을 실행한다. `--workers` 생략 시 `claude` 같은 미지원 roster 항목은 건너뛰고, 명시 요청하면 실패한다. report-writer 는 `--enable-codex-report-writer --report-writer-codex-model <model>` opt-in 이 필요하며, 성공 시 token-usage substitution, HTML view 렌더, follow-up task stub 생성, 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]` | `leadRuntime=external` run manifest 를 읽어 tmux-pane worker dispatch / wait / teardown 을 수행한다. tmux pane 을 만들 수 없으면 CLI wrapper 로 graceful degrade 하고 `workerDispatches[].degradedFrom` 에 기록한다 |
 | `okstra render-views <final-report.md>` | Phase 7 step 1.5 — 토큰 치환된 final-report MD 한 본을 입력으로 sibling `*.slim.md` (AI 입력용) + `*.html` (사람용 self-contained) 두 view 를 결정론적으로 생성. 원본 MD 는 수정하지 않음. Node 위임 wrapper는 `scripts/okstra-render-report-views.py` 를 호출. `validators/validate-report-views.py` 가 substring 보존 / form-control 위치 / Response ID parity 를 검사 |
 | `okstra wizard <init\|step\|render-args\|confirmation> --state-file <path>` | okstra-run 인터랙티브 입력 상태머신 (`okstra_ctl.wizard`). `init` 으로 state file 을 시드한 뒤 skill 이 `step --answer <val>` 을 반복 호출하면 다음 `Prompt` JSON 을 받음. `--answer` 는 **필수**. 응답을 주지 않고 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek. `render-args` 는 최종 `render-bundle` 인자 맵, `confirmation` 은 사용자 echo 블록을 반환. `implementation` task type 에서는 `approved_plan_pick` 직후 `stage_pick` 단계가 추가되어 실행할 stage 를 선택하고, `executor_pick` 으로 넘어갑니다. brief 단계는 entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 나오며, downstream 은 manifest 의 brief 를 자동 carry-in 하고(미등록 시 `brief_carry` 3-옵션 fallback), `release-handoff` 는 brief 없이 `handoff_stage_pick` 멀티선택(eligible stage 묶음 / 전체 task)으로 진입합니다 |
 | `okstra token-usage ...` | 설치된 `okstra-token-usage.py` 를 감싸 run token usage 수집/치환을 수행. 세션 jsonl 은 기본적으로 `$OKSTRA_HOME/cache/token-usage/` 의 byte cursor 캐시로 증분 스캔하며, `--no-cache` 로 캐시를 우회해 전체 재스캔을 강제할 수 있음(정확성 폴백) |
@@ -614,4 +631,4 @@ chmod +x ~/.local/bin/okstra-ctl
 
 ### Live-log sidecar
 
-codex / gemini wrapper 는 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar 를 만들고 stdout / stderr 를 mirror 합니다. tmux 안에서 lead 를 띄우면 wrapper 가 자동으로 `tail -F` pane 을 분할합니다 (trace pane title: `<cli>-<role>-<pid>-tail`, caller (worker) pane title: `<cli>-<role>-<pid>` — wrapper PID 가 동일 role 의 동시 dispatch 를 구분합니다). 분할된 trace pane 은 `@okstra_trace_run=<RUN_DIR>` pane user-option 으로 태깅돼, Claude `/exit` 시 `SessionEnd` 훅이 `okstra-trace-cleanup.sh --reap` 로 (`$CLAUDE_PROJECT_DIR/.okstra/` scope) 자동 정리합니다. 같은 스크립트를 lead 가 `--run-dir <RUN_DIR>` 로 호출하면 그 run 의 trace pane + dispatch 된 worker-agent pane(title `claude-worker` / `codex-worker` / `gemini-worker` / `report-writer-worker`)을 lead 세션 범위에서 함께 정리하며(lead 자신의 pane 은 제외), lead 는 새 phase dispatch 직전 이를 호출해 이전 phase 의 okstra pane 을 자동 정리합니다. 사용량 인벤토리와 `find … -delete` cleanup 명령은 `okstra-logs` skill 이 read-only 로 제안합니다. 자세한 와이어링은 [`docs/kr/architecture.md`](architecture.md) 의 *Live-log mirror* 절 참고.
+codex / gemini wrapper 는 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar 를 만들고 stdout / stderr 를 mirror 합니다. tmux 안에서 lead 를 띄우면 wrapper 가 자동으로 `tail -F` pane 을 분할합니다 (trace pane title: `<cli>-<role>-<pid>-tail`, caller (worker) pane title: `<cli>-<role>-<pid>` — wrapper PID 가 동일 role 의 동시 dispatch 를 구분합니다). 분할된 trace pane 은 `@okstra_trace_run=<RUN_DIR>`, tmux-pane backend worker-compute pane 은 `@okstra_worker_run=<RUN_DIR>` pane user-option 으로 태깅돼, Claude `/exit` 시 `SessionEnd` 훅이 `okstra-trace-cleanup.sh --reap` 로 (`$CLAUDE_PROJECT_DIR/.okstra/` scope) 자동 정리합니다. 같은 스크립트를 lead 가 `--run-dir <RUN_DIR>` 로 호출하면 그 run 의 trace pane + worker-compute pane + dispatch 된 worker-agent pane(title `claude-worker` / `codex-worker` / `gemini-worker` / `report-writer-worker`)을 lead 세션 범위에서 함께 정리하며(lead 자신의 pane 은 제외), lead 는 새 phase 진입 전 `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` 를 한 번 실행해 stale pane 을 비웁니다.

package/docs/pr-template-usage.md

@@ -19,8 +19,8 @@
 
 ## 2. default 후보 경로
 
-1. `$OKSTRA_SKILLS_DIR/okstra-run/templates/pr-body.template.md` — 환경변수 `OKSTRA_SKILLS_DIR` 가 설정돼 있을 때만.
-2. `~/.claude/skills/okstra-run/templates/pr-body.template.md` — `npx okstra install` 이 깔아두는 표준 위치.
+1. `$OKSTRA_SKILLS_DIR/templates/prd/pr-body.template.md` — 환경변수 `OKSTRA_SKILLS_DIR` 가 설정돼 있을 때만.
+2. `~/.claude/skills/templates/prd/pr-body.template.md` — `npx okstra install` 이 깔아두는 표준 위치.
 
 후보들은 우선순위 순서대로 시도되며, 모두 부재 시 다음과 같이 명시적인 에러로 끝난다.
 
@@ -28,7 +28,7 @@
 
 ## 3. 소스 리포지토리 안 원본
 
-- [`skills/okstra-run/templates/pr-body.template.md`](../skills/okstra-run/templates/pr-body.template.md) — `npx okstra install` 이 §2 의 default 위치로 복사하는 원본. 카피를 바꾸고 싶으면 이 파일을 수정한 뒤 다시 install 한다.
+- [`skills/templates/prd/pr-body.template.md`](../templates/prd/pr-body.template.md) — `npx okstra install` 이 §2 의 default 위치로 복사하는 원본. 카피를 바꾸고 싶으면 이 파일을 수정한 뒤 다시 install 한다.
 
 ## 4. 설정 명령 — 영속화
 

package/docs/project-structure-overview.md

@@ -24,7 +24,7 @@
 
 현재 기준:
 
-- package version: `0.50.0`
+- package version: see `package.json`
 - Node CLI entrypoint: `bin/okstra`
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`

package/docs/superpowers/plans/2026-05-25-okstra-project-root-rename.md

@@ -25,7 +25,7 @@
 | Python 호출자 (하드코드) | ~15 | `scripts/okstra_ctl/{render,run,seeding,wizard,worktree,backfill,pr_template,sequence}.py`, `okstra-spawn-followups.py`, `okstra_token_usage/collect.py`, `validators/validate-*.py` |
 | Shell 스크립트 | 5 | `scripts/lib/okstra/{interactive,project-resolver,usage}.sh`, `scripts/lib/okstra-ctl/cmd-rerun.sh`, `validators/{lib/paths,lib/fixtures,validate-brief,validate-workflow}.sh` |
 | 스킬 / 프로필 / 에이전트 | 13 | `skills/okstra-*/SKILL.md`, `prompts/profiles/*.md`, `agents/{SKILL.md,workers/claude-worker.md}` |
-| 템플릿 | 4 | `templates/okstra.CLAUDE.md`, `templates/reports/{brief,task-brief}.template.md`, `skills/okstra-run/templates/pr-body.template.md` |
+| 템플릿 | 4 | `templates/okstra.CLAUDE.md`, `templates/reports/{brief,task-brief}.template.md`, `skills/templates/prd/pr-body.template.md` |
 | 테스트 | ~20 | `tests/test_okstra_*.py`, `tests-e2e/scenario-*.sh` 2개 |
 | 문서 | ~12 | `README{,.kr}.md`, `CLAUDE.md`, `docs/kr/{architecture,cli}.md`, `docs/project-structure-overview.md`, `docs/task-process/common-flow.md`, `docs/superpowers/plans/*` |
 | 제외 | — | `graphify-out/` (다음 update 시 재생성), `.project-docs/2026-05-10/feature-checklist.md` (okstra 무관) |