okstra 0.77.0 → 0.78.1

package/README.kr.md

@@ -205,7 +205,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | 커맨드 | 용도 |
 |---|---|
 | `npx -y okstra@latest paths` | 런타임 경로 출력 (`--field <name>` 또는 `--shell`) |
-| `npx -y okstra@latest doctor [--runtime claude-code\|codex\|all]` | 런타임 + 스킬 + python import 진단. `codex` 는 Claude skill checks 를 제외 |
+| `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

@@ -204,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 [--runtime claude-code\|codex\|all]` | Diagnose runtime + skills + python import. `codex` skips Claude skill checks |
+| `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,130 +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),
-  ],
-  ["codex-run", () => import("../src/codex-run.mjs").then((m) => m.run)],
-  [
-    "codex-dispatch",
-    () => import("../src/codex-dispatch.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; --runtime codex skips ~/.claude assets
-  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; --runtime codex skips Claude skills
-  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)
-  codex-run              Prepare a render-only Codex lead task bundle
-                         (--lead-runtime codex, no worker dispatch)
-  codex-dispatch         Dispatch CLI-backed workers for a prepared Codex run
-  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/cli.md

@@ -606,10 +606,10 @@ chmod +x ~/.local/bin/okstra-ctl
 | 명령 | 용도 |
 |---|---|
 | `okstra paths [--field <name>\|--shell]` | package/runtime/home/bin/pythonpath/version 경로 출력 |
-| `okstra install [--runtime claude-code\|codex\|all] [--refresh\|--dry-run\|--link <repo>]` | runtime, templates, skills, agents 설치/갱신. 기본값 `claude-code` 는 기존처럼 Claude skills/agents 까지 설치한다. `codex` 는 공유 runtime 만 설치하고 `~/.claude` 자산을 건드리지 않는다 |
-| `okstra ensure-installed [--runtime claude-code\|codex\|all] [-q]` | 설치 상태 확인, stale이면 같은 runtime 으로 재설치. `codex` runtime 은 Claude skills/agents drift 검사를 건너뛴다 |
+| `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 claude-code\|codex\|all]` | runtime + Python import + skill/agent 설치 진단. `codex` runtime 은 Claude skill checks 를 제외한다 |
+| `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 쓰기 |
@@ -622,6 +622,7 @@ chmod +x ~/.local/bin/okstra-ctl
 | `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` 로 캐시를 우회해 전체 재스캔을 강제할 수 있음(정확성 폴백) |
@@ -630,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/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`