okstra 0.78.2 → 0.80.0

package/README.kr.md

@@ -1,6 +1,6 @@
 # okstra
 
-> npm: [`okstra`](https://www.npmjs.com/package/okstra) · 설치: `npx -y okstra@latest install`
+> npm: [`okstra`](https://www.npmjs.com/package/okstra) · 설치: `npx -y okstra@latest install --runtime claude-code`
 >
 > English: [`README.md`](README.md)
 
@@ -105,7 +105,7 @@ okstra/                          npm 패키지 = repo 루트
 ### 3.1 최초 셋업 (머신당 1회)
 
 ```bash
-npx -y okstra@latest install
+npx -y okstra@latest install --runtime claude-code
 ```
 
 `~/.okstra/{lib/python, bin, templates, version}`, `~/.claude/skills/` 아래 스킬 마크다운 11개, `~/.claude/agents/` 아래 worker agent 4개, `~/.okstra/` 의 설치 asset manifest 를 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
@@ -125,7 +125,7 @@ npx -y okstra@latest doctor
 ```bash
 npm i -g okstra
 okstra --version       # CLI 가 PATH 에 잡혔는지 확인
-okstra install         # 'npx -y okstra@latest install' 와 동일
+okstra install --runtime claude-code   # 'npx -y okstra@latest install --runtime claude-code' 와 동일
 ```
 
 글로벌 설치는 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`).

package/README.md

@@ -1,6 +1,6 @@
 # okstra
 
-> npm: [`okstra`](https://www.npmjs.com/package/okstra) · install: `npx -y okstra@latest install`
+> npm: [`okstra`](https://www.npmjs.com/package/okstra) · install: `npx -y okstra@latest install --runtime claude-code`
 >
 > 한국어 매뉴얼: [`README.kr.md`](README.kr.md)
 
@@ -104,7 +104,7 @@ okstra/                          npm package = repo root
 ### 3.1 First-time setup (once per machine)
 
 ```bash
-npx -y okstra@latest install
+npx -y okstra@latest install --runtime claude-code
 ```
 
 Provisions `~/.okstra/{lib/python, bin, templates, version}`, the 11 skill markdown files under `~/.claude/skills/`, the 4 worker agents under `~/.claude/agents/`, and the installed-asset manifests in `~/.okstra/`. Re-running is idempotent — per-file hashes are compared and only changed files are touched.
@@ -124,7 +124,7 @@ Every example in this README uses `npx -y okstra@latest <cmd>` so you don't need
 ```bash
 npm i -g okstra
 okstra --version       # confirm the CLI is on PATH
-okstra install         # same as 'npx -y okstra@latest install'
+okstra install --runtime claude-code   # same as 'npx -y okstra@latest install --runtime claude-code'
 ```
 
 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`).

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`)을 설치합니다. `--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합니다.
+- **User-home install + project-local task bundles**: `npx okstra@latest install --runtime claude-code` 한 명령이 런타임(`~/.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

@@ -312,12 +312,29 @@ scripts/okstra.sh --task-type implementation-planning --workers claude,codex --p
 
 Lead 실행 adapter 를 지정합니다. 기본값은 `claude-code` 입니다.
 
+Lead runtime independence boundary:
+
 - `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 실행에 넘길 수 있습니다.
+- `external`: Claude Code Teams 없이 `--render-only --lead-runtime external` 로 task bundle 과 external lead prompt 를 준비하고, lead 는 `okstra team dispatch` / `okstra team await` / `okstra team teardown` 으로 tmux-pane worker lifecycle 을 관리합니다. 이 path 는 `TeamCreate` / `Agent(...)` 를 쓰지 않고 artifact-only accounting 을 사용합니다.
+
+현재 Claude Code 독립 범위는 external lead prompt + `okstra team *` worker dispatch 입니다. non-render `okstra_ctl.run --lead-runtime external` remains blocked; 완전한 external lead driver 는 아직 별도 구현 대상입니다. `--runtime external` does not install `~/.claude` assets, but selecting a `claude` worker still requires a local Claude CLI wrapper.
+
+### Runtime auto-detection (`auto`)
+
+`okstra run` 의 기본 runtime은 `auto` 입니다. `auto` 는 host 기반으로 `claude-code`, `codex`, `external` 중 하나로 resolve 됩니다 (`src/runtime-resolver.mjs`). 우선순위: 명시 runtime > `OKSTRA_RUNTIME_HOST` env > Claude Code skill handoff > tmux 가용 시 external > 그 외 fail-fast (safe fallback: 의도와 다른 runtime 으로 조용히 넘어가지 않음).
+
+- Claude Code 안에서는 `/okstra-run` 이 front door 입니다. bare `okstra run` 은 Claude Code `TeamCreate` / `Agent(...)` 를 호출할 수 없습니다.
+- Codex host: `okstra run` 이 `codex-run` -> `codex-dispatch` 를 orchestration 합니다.
+- generic terminal + tmux: `okstra run` 이 `render-bundle --lead-runtime external` -> `okstra team dispatch` -> `okstra team await` 를 orchestration 합니다.
+
+`okstra install` / `ensure-installed` / `doctor` / `render-bundle` 도 `auto` 를 기본값으로 받지만, host signal 이 없는 plain terminal 에서는 host 지정이 필요합니다. 그래서 Claude Code skill 들은 `--runtime claude-code` / `--lead-runtime claude-code` 를 명시합니다.
+
+`installed-runtimes.json` 은 schemaVersion 2 로 `installRequest`, `runtimeResolution`, `installedRuntimes`, `installedAssets` 를 분리합니다. 이전 `codexAdapter` / `externalAdapter` 는 v1 manifest read 호환 경로에서만 해석됩니다.
 
 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 후처리를 순서대로 수행합니다.
+이후 `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`)만 자동 선택하고, 명시 요청하면 미지원 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 경계입니다.
 

package/docs/project-structure-overview.md

@@ -106,8 +106,19 @@ So `runtime/` is not the only npm-published content. It is the install payload c
 
 `npm run build` and `prepack` both run this sync. Never hand-edit `runtime/`.
 
+Runtime/install asset changes follow this checklist:
+
+1. Add or edit the source asset under `scripts/`, `skills/`, `agents/`, `prompts/`, `schemas`, `templates`, or `validators`.
+2. Add a `tools/build.mjs` sync mapping when the asset must appear under `runtime/` (for example, a new executable such as `okstra-claude-exec.sh`).
+3. Run `npm run build`.
+4. Verify `tests-js/runtime-build-sync.test.mjs`.
+5. Verify `tests-js/install-runtime.test.mjs`.
+6. Reinstall or repack the package before testing global `okstra install`.
+
 ### 3.3 Install output
 
+`okstra install` copies from the installed npm package `runtime/` tree, not from the source checkout. `okstra -v` only proves the CLI version; the same semver can still point at stale package contents when the global package was installed before the latest build.
+
 `okstra install` copies or symlinks:
 
 - `runtime/python/*` → `~/.okstra/lib/python/`
@@ -120,6 +131,8 @@ So `runtime/` is not the only npm-published content. It is the install payload c
 
 `--link <repo>` mode is for development and symlinks installed files back to repo sources.
 
+`src/runtime-resolver.mjs` is the single reference point for runtime auto-detection. `okstra install` defaults to `--runtime auto`, records the request and resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree. Dynamic capabilities such as `tmux` and `codex` CLI availability are checked by `doctor` and `run`, not frozen into the install manifest. Claude Code skills pass explicit `--runtime claude-code` / `--lead-runtime claude-code` so they never depend on host auto-detection.
+
 ---
 
 ## 4. 폴더별 역할
@@ -379,8 +392,8 @@ Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a s
 
 ### 7.1 First setup
 
-1. `okstra install`
-2. `okstra doctor`
+1. `okstra install --runtime claude-code`
+2. `okstra doctor --runtime claude-code`
 3. inside target repo: `okstra setup --project-id <id>` or `/okstra-setup`
 
 ### 7.2 Brief creation