okstra 0.116.0 → 0.118.0

package/docs/kr/cli.md

@@ -1,657 +0,0 @@
-# okstra — CLI 인자 / 옵션 매뉴얼 (한국어)
-
-> 이 문서는 [README.kr.md](../../README.kr.md) 의 보충 문서입니다. 내부 아키텍처와 storage / workflow 계약은 [architecture.md](architecture.md) 를 참고하세요.
->
-> 이 문서는 `okstra.sh` 의 phase 실행 플래그를 다룹니다. 별개 진입점인 `okstra container` 의 sub-command 레퍼런스는 [container.md](container.md) 를 참고하세요.
-
----
-
-## 인덱스
-
-- [Command forms](#command-forms)
-- [Required arguments](#required-arguments)
-  - [`--project-id`](#--project-id)
-  - [`--task-group`](#--task-group)
-  - [`--task-id`](#--task-id)
-  - [`--task-type`](#--task-type)
-  - [`--task-brief`](#--task-brief)
-  - [`--yes`](#--yes)
-- [Optional arguments and options](#optional-arguments-and-options)
-  - [`--task-key`](#--task-key)
-  - [`--clarification-response`](#--clarification-response)
-  - [`--resume-clarification`](#--resume-clarification)
-  - [`--project-root`](#--project-root)
-  - [`--directive`](#--directive)
-  - [`--fix-cycle`](#--fix-cycle)
-  - [`--workers`](#--workers)
-  - [`--lead-runtime`](#--lead-runtime)
-  - [`--claude-model`](#--claude-model)
-  - [`--lead-model`](#--lead-model)
-  - [`--codex-model`](#--codex-model)
-  - [`--antigravity-model`](#--antigravity-model)
-  - [`--report-writer-model`](#--report-writer-model)
-  - [`--executor`](#--executor)
-  - [`--critic`](#--critic)
-  - [`--approved-plan`](#--approved-plan)
-  - [`--approve`](#--approve)
-  - [`--work-category`](#--work-category)
-  - [`--base-ref`](#--base-ref)
-  - [`--related-tasks`](#--related-tasks)
-  - [`--render-only`](#--render-only)
-  - [`--no-plan-verification`](#--no-plan-verification)
-- [Interactive input flow](#interactive-input-flow)
-- [Confirmation flow](#confirmation-flow)
-- [okstra Control Center — 설치 / 자주 쓰는 명령](#okstra-control-center--설치--자주-쓰는-명령)
-- [okstra Control Center](#okstra-control-center)
-  - [설치 (전역 wrapper)](#설치-전역-wrapper)
-  - [자주 쓰는 명령](#자주-쓰는-명령)
-  - [`okstra` Node CLI — introspection subcommands](#okstra-node-cli--introspection-subcommands)
-  - [Live-log sidecar](#live-log-sidecar)
-
----
-
-## Command forms
-
-기본 명령(첫 진입 / full args):
-
-```bash
-scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-runtime claude-code|codex] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--antigravity-model <model>] [--report-writer-model <model>] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
-```
-
-후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
-
-```bash
-scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> [--task-type <task-type>]
-```
-
-Clarification 답변 즉시 재실행:
-
-```bash
-scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
-```
-
-interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니다.
-
-- 필수 인자가 비어 있으면 stdin으로 직접 입력을 받습니다.
-- 입력이 모두 준비되면 실행 전 요약을 보여줍니다.
-- `y` 또는 `yes`를 입력했을 때만 실제 생성 또는 실행 단계로 진행합니다.
-- interactive가 아닌 실행에서는 누락 인자를 prompt하지 않고 에러로 종료합니다.
-- `--yes`를 사용하면 prompt와 confirmation을 모두 건너뛰지만, 이때는 모든 필수 인자가 반드시 이미 채워져 있어야 합니다.
-- 우선순위는 `명시적 CLI 인자 > interactive prompt 또는 non-interactive 에러`입니다.
-
-## Required arguments
-
-### `--project-id`
-
-전역에서 고유해야 하는 프로젝트 ID입니다. 첫 실행 시 `<PROJECT_ROOT>/.okstra/project.json` 에 자기 등록(self-registration)되며, 동일 PROJECT_ROOT 에서 재실행할 때 인자값과 저장된 `projectId` 가 다르면 즉시 에러로 종료합니다.
-
-예:
-
-- `sample-project-v2-api`
-- `jobs`
-
-### `--task-group`
-
-관련 task를 묶는 논리 그룹입니다.
-
-예:
-
-- `feature-8858`
-- `bugfix-auth`
-- `tasks`
-
-### `--task-id`
-
-같은 그룹 안에서 안정적으로 재사용할 task 식별자입니다.
-
-예:
-
-- `email-recipient-loss`
-- `8852`
-
-### `--task-type`
-
-이번 run의 목적과 profile 선택, run directory 세그먼트, lifecycle phase 라우팅을 결정하는 단일 입력값입니다.
-표준 값과 phase별 책임은 위 [Task type](#task-type) 섹션을 참고합니다.
-
-#### `--task-type improvement-discovery`
-
-`improvement-discovery` 는 `PHASE_SEQUENCE` 외부 sidetrack entry-point 입니다. 코드베이스 스코프와 lens 화이트리스트 안에서 multi-worker 합의로 개선 후보를 도출합니다.
-
-- 입력: frontmatter `scope: codebase` 마커가 있는 brief.
-  - `priority-lenses`: 1–4개. lens 화이트리스트는 `scripts/okstra_ctl/improvement_lenses.py` 의 `LENSES` 상수.
-  - `scan-scope`: 1개 이상의 경로.
-  - `out-of-scope`: 선택.
-  - `candidate-cap`: 1–12, 기본 8.
-- 출력: `## 5.9 Improvement Candidates` 표 (10 column: Cand ID / Lens / Title / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Evidence).
-- Verdict Token: `candidates-ready` / `no-candidates` / `blocked`.
-- 라우팅: 자동 spin-off 없음. 사용자가 후보를 골라 새 task-id 로 `requirements-discovery` / `implementation-planning` / `error-analysis` 진입.
-- 워커: claude + codex + antigravity + report-writer 모두 필수.
-- 양방향 grilling 두 지점: `okstra-brief-gen` Step 4 강화 (budget 8) + lead 의 Phase 1.5 reflect-back (budget 12).
-- Validator: `validators/validate_improvement_report.py` 가 `improvement-discovery` final-report 의 11항목 contract 를 강제.
-- `improvement-discovery` run 은 `PHASE_SEQUENCE` 에 포함되지 않으므로 `--task-key` 단축 경로의 `nextRecommendedPhase` 자동 채움 대상이 아닙니다.
-
-### `--task-brief`
-
-분석의 기준이 되는 task brief 문서 경로입니다.
-상대 경로는 대상 프로젝트 루트를 기준으로 해석됩니다.
-
-`release-handoff` 에는 적용되지 않습니다 — brief 는 entry phase
-(requirements-discovery / error-analysis / improvement-discovery)의 입력물이고,
-release-handoff 는 prepare 가 검증 보고서를 인용하는 input 문서
-(`<task_root>/release-handoff-input.md`)를 자동 생성해 brief 자리를 채웁니다.
-release-handoff 에 비어 있지 않은 `--task-brief` 를 주면 즉시 거부됩니다.
-
-예:
-
-- `.project-docs/linear/feature/8858/okstra-task-brief.md`
-- `.project-docs/tasks/8852/BUG_REPORT.md`
-
-### `--yes`
-
-interactive prompt와 confirmation을 생략합니다.
-
-대신 아래 조건이 강제됩니다.
-
-- `project-id`
-- `task-group`
-- `task-id`
-- `task-type`
-- `brief-path`
-
-즉, 필수 인자가 하나라도 비어 있으면 prompt하지 않고 즉시 종료합니다.
-
-예:
-
-```bash
-scripts/okstra.sh --yes --render-only --task-type error-analysis --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
-```
-
-## Optional arguments and options
-
-### `--task-key`
-
-기존 task에 대한 후속 phase를 시작할 때 `--project-id`/`--task-group`/`--task-id`를 한 번에 전달하는 단축 형식입니다.
-
-- 입력 형식: `<project-id>:<task-group>:<task-id>`
-- 동작:
-  - 세 ID로 split하여 `PROJECT_ID`/`TASK_GROUP`/`TASK_ID`에 채웁니다.
-  - 명시적으로 같은 값들이 함께 들어오면 일치할 때만 허용하고, 충돌하면 즉시 에러로 종료합니다.
-  - 해당 task의 `task-manifest.json`이 존재하면 누락된 `--task-brief`를 manifest의 `taskBriefPath` 로, 누락된 `--task-type`을 `workflow.nextRecommendedPhase` 로 자동 채웁니다.
-  - manifest가 없으면(첫 진입) 기존 누락-인자 검증이 그대로 동작합니다(=full args 강제).
-- 명시적으로 전달된 인자가 항상 manifest 값보다 우선합니다.
-- `nextRecommendedPhase`가 `pending-routing-decision` 또는 `done-or-follow-up`이면 자동 채움하지 않고, 사용자가 명시적으로 `--task-type`을 주거나 brief을 보강한 뒤 다시 실행해야 합니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-key jobs:tasks:8852
-```
-
-```bash
-scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
-```
-
-### `--clarification-response`
-
-이전 run의 final report(`## 1. Clarification Items`에 사용자가 답변을 inline으로 채운 파일)를 다음 run으로 carry-in합니다.
-
-- 입력: `<previous-run>/reports/final-report-<task-type>-<seq>.md` 경로
-- 동작: 파일을 현재 run의 `instruction-set/clarification-response.md`로 복사하고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
-- 사용 시점: `requirements-discovery`, `error-analysis`, `implementation-planning`처럼 미해결 질문이나 approval-blocking clarification 을 남기는 phase 이후, 사용자가 답변을 채워 다음 phase 또는 같은 phase resume 으로 넘길 때.
-
-예:
-
-```bash
-scripts/okstra.sh \
-  --task-type implementation-planning \
-  --project-id jobs --task-group tasks --task-id 8852 \
-  --task-brief .project-docs/tasks/8852/BUG_REPORT.md \
-  --clarification-response .okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
-```
-
-### `--resume-clarification`
-
-직전 `requirements-discovery` 또는 `error-analysis` run의 final report를 즉시 편집하고, 같은 phase를 자동으로 재실행합니다. `--clarification-response` 경로를 사용자가 직접 들고 다닐 필요가 없습니다.
-
-- 입력: task identity (`--project-id` + `--task-group` + `--task-id`, 또는 `--task-key <p>:<g>:<i>`)
-- 동작 순서:
-  1. task의 `runs/{requirements-discovery,error-analysis}/reports/final-report-*.md` 중 가장 최신 timestamp 파일을 자동 선택합니다.
-  2. `$EDITOR`(미설정 시 `vi`)로 해당 파일을 엽니다. 사용자는 Section 5의 `Q*` 행에 답변을 inline으로 채운 뒤 저장하고 종료합니다.
-  3. okstra가 같은 task-type으로 자기 자신을 `exec` 재호출하면서 편집된 파일을 `--clarification-response`로 carry-in 합니다.
-  4. 이후 confirmation, render, Claude handoff 흐름은 일반 실행과 동일합니다.
-- 명시적 `--task-type`을 함께 주면 그 task type의 reports/ 만 검색합니다. 생략 시 `error-analysis` → `requirements-discovery` 순으로 검색하고 timestamp가 더 큰 보고서를 사용합니다.
-- 다음 옵션과 함께 쓸 수 없습니다: `--render-only`, `--clarification-response`, `--approved-plan`.
-- `EDITOR`를 비대화형 도구(예: `true`)로 설정하면 답변 편집을 건너뛴 채 곧바로 재실행됩니다. 디버깅용으로만 권장합니다.
-
-예:
-
-```bash
-scripts/okstra.sh --resume-clarification --task-key jobs:tasks:8852
-```
-
-```bash
-EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --task-group tasks --task-id 8852
-```
-
-내부적으로는 다음과 동등합니다.
-
-```bash
-$EDITOR <project-root>/.okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
-scripts/okstra.sh --task-type <same-type> \
-  --project-id <p> --task-group <g> --task-id <i> \
-  --task-brief <from manifest> \
-  --clarification-response <edited final-report-<latest>.md>
-```
-
-### `--project-root`
-
-대상 프로젝트의 절대 경로입니다. 명시하지 않으면 `okstra.sh` 가 다음 우선순위로 자동 해석합니다.
-
-1. cwd 또는 그 조상 디렉토리 중 `.okstra/project.json` 보유 위치를 찾아 PROJECT_ROOT 로 채택합니다.
-2. 위가 실패하면 `git rev-parse --show-toplevel` 결과를 사용합니다.
-3. 모두 실패하면 즉시 에러로 종료합니다.
-
-해석된 PROJECT_ROOT 에서 첫 실행이라면 `<PROJECT_ROOT>/.okstra/project.json` 이 다음 스키마로 자동 생성됩니다.
-
-```json
-{
-  "projectId": "<--project-id 인자 값>",
-  "projectRoot": "<resolved absolute path>",
-  "createdAt": "<ISO8601 UTC>",
-  "updatedAt": "<ISO8601 UTC>"
-}
-```
-
-이미 존재하면 `projectId` 일치 검사 후 `projectRoot`/`updatedAt` 만 갱신합니다. `projectId` 가 다르면 즉시 에러로 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
-```
-
-### `--directive`
-
-사용자 의도를 자유 텍스트로 lead·worker·downstream skill에 전달하는 채널입니다. 값은 `instruction-set/analysis-material.md` 끝에 `## Directive` 섹션으로 임베딩되고, analysis worker 의 1차 입력인 `instruction-set/analysis-packet.md` 에도 포함됩니다. 동시에 `instruction-set/directive.txt`로 백업됩니다.
-
-용도:
-
-- 기본 heuristic을 뒤집고 싶을 때 — 예: "단일 XL task여도 Gantt 그려줘 (Phase 2개, 총 ~10d)", "Gantt 생략 사유를 명시해줘" (참고: `## Cumulative Timeline`은 schedule contract에서 제거되었으므로 더 이상 toggle 대상이 아닙니다)
-- 분석/계획의 강조점 지시 — 예: "rollout 리스크 우선 분석", "test 커버리지 부재를 별도 finding으로"
-- Phase/Step 분할이나 day 추정을 미리 제시 — 예: "Part 1: 4d, measure: 0.5d, Part 2: 4d, ops: 1d"
-
-해석 규칙:
-
-- lead·analysis worker는 compact intake(`active-run-context`, `analysis-packet.md`)를 1차 입력으로 읽으므로 directive가 별도 작업 없이 전파됩니다. `analysis-material.md`는 packet이 불충분하거나 source citation 검증이 필요할 때 여는 fallback입니다.
-- skill 측은 자체 contract보다 user prompt를 **우선** 적용해야 하며 (예: `okstra-schedule` 스킬의 "Directive override (highest priority)" 절), heuristic을 뒤집은 경우 결과 문서에 그 사실을 한 줄로 표시합니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-type implementation-planning ... \
-  --directive "Phase 2개(Part 1 ~4d, Part 2 ~5d, 순차)로 총 ~10d. Gantt 꼭 그려줘 (임계 경로 표시)."
-```
-
-### `--fix-cycle`
-
-- `--fix-cycle <yes|no>` — release-handoff 까지 완료된 task 에 entry phase (`requirements-discovery` / `error-analysis` / `implementation-planning`) 로 재진입할 때, 이번 재진입을 버그 픽스 사이클로 기록할지 여부. 미지정 시 기록하지 않습니다 (okstra-run wizard 경로는 `fix_cycle_confirm` 단계가 같은 입력을 받습니다).
-- `yes` 는 두 조건을 모두 만족해야 새 cycle 을 엽니다 — task-type 이 entry phase 이고, manifest 의 `workflow.lastCompletedPhase` 가 `release-handoff` 여야 합니다. 둘 중 하나라도 어긋나면 prepare 가 거부합니다. cycle 이 이미 open 이면 같은 task 의 이후 run 은 이 플래그 없이도 자동으로 부착됩니다.
-
-### `--workers`
-
-이번 run에서 사용할 worker 목록을 직접 지정합니다.
-생략하면 기본값 `claude,codex,report-writer`를 사용합니다. Antigravity worker는 옵션이며 필요할 때 `--workers claude,codex,antigravity,report-writer` 와 같이 명시적으로 추가하세요.
-지정하면 전달한 worker subset만 dedupe 후 기록됩니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
-```
-
-### `--lead-runtime`
-
-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` 은 runtime adapter 선택만 의미하며, `okstra install` 은 `~/.agents/skills/` 를 기본 생성하고 `~/.claude` 가 있으면 Claude skill/agent 도 설치합니다. `claude` worker 선택은 여전히 local Claude CLI wrapper 를 필요로 합니다.
-
-### Runtime auto-detection (`auto`)
-
-`okstra run` 의 기본 runtime은 `auto` 입니다. `auto` 는 host 기반으로 `claude-code`, `codex`, `external` 중 하나로 resolve 됩니다 (`src/lib/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 합니다.
-
-`doctor` / `render-bundle` 도 `auto` 를 기본값으로 받지만, host signal 이 없는 plain terminal 에서는 host 지정이 필요합니다. `okstra install` / `ensure-installed` 는 예외입니다. 설치는 runtime host 가 아니라 agent home 기준으로 공유 runtime 과 skill target 을 배치하므로, host signal 이 없어도 `auto` 요청과 미해결 상태를 manifest 에 기록하고 설치를 계속합니다. 스킬 복사 대상은 runtime resolution 이 아니라 agent home 존재 여부와 기본 Agent target 정책입니다. `~/.agents/skills/` 는 항상 생성하고, `~/.claude` 가 있으면 Claude skills/agents 도 설치합니다. Claude Code skill 들은 `--runtime claude-code` / `--lead-runtime claude-code` 를 명시하므로 실행 단계에서 host auto-detection 에 의존하지 않습니다.
-
-`installed-runtimes.json` 은 schemaVersion 2 로 `installRequest`, `runtimeResolution`, `installedRuntimes`, `installedAssets` 를 분리합니다. `installed-skills.json` 은 schemaVersion 2 target 목록(`provider`, `root`, `skills`)으로 Claude/Agent skill target 을 기록하며, uninstall 은 이 target 목록을 기준으로 제거합니다. 이전 `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[,antigravity[,report-writer]]` 가 기존 CLI wrapper 기반 worker 를 실행합니다. `--workers` 를 생략하면 run roster 중 Codex-side 지원 worker(`codex`, `antigravity`, 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 경계입니다.
-
-> 모든 `--*-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`
-> - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (기본), `gemini-3.5-flash` (그리고 `gemini 3.1 pro` / `gemini 3.5 flash` 공백 별칭). antigravity-worker 는 `agy` CLI 로 Gemini 계열 모델을 실행하므로 모델 ID 는 `gemini-*` 형식을 유지합니다.
-
-### `--claude-model`
-
-`Claude worker`에 사용할 모델을 지정합니다.
-지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CLAUDE_MODEL` 또는 fallback `opus`을 사용합니다.
-
-### `--lead-model`
-
-`Claude lead`에 사용할 모델을 지정합니다.
-지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_LEAD_MODEL` 또는 fallback `opus`을 사용합니다.
-
-### `--codex-model`
-
-`Codex worker`에 사용할 모델을 지정합니다.
-지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CODEX_MODEL` 또는 fallback `gpt-5.5`를 사용합니다.
-
-### `--antigravity-model`
-
-`Antigravity worker`에 사용할 모델을 지정합니다.
-지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL` 또는 fallback `auto`를 사용합니다.
-
-### `--report-writer-model`
-
-`Report writer worker`에 사용할 모델을 지정합니다.
-지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` 또는 lead 기본값을 사용합니다.
-
-중앙 기본값 환경 변수는 아래와 같습니다.
-
-- `OKSTRA_DEFAULT_LEAD_MODEL`
-- `OKSTRA_DEFAULT_CLAUDE_MODEL`
-- `OKSTRA_DEFAULT_CODEX_MODEL`
-- `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL`
-- `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
-- `OKSTRA_DEFAULT_EXECUTOR` (`claude` | `codex` | `antigravity`, fallback `claude`)
-
-fallback 기본값은 아래와 같습니다.
-
-- `Claude lead`: `opus`
-- `Report writer worker`: `opus`
-- `Claude worker`: `opus`
-- `Codex worker`: `gpt-5.5`
-- `Antigravity worker`: `auto`
-- Implementation executor: `claude` (즉 기본은 `Claude executor`)
-
-### `--executor`
-
-`--task-type implementation` 에서 Executor 역할을 맡을 provider 를 선택합니다. 값은 `claude` | `codex` | `antigravity` 중 하나이며, 다른 task-type 에서는 무시됩니다.
-
-- 기본값: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`
-- Executor 는 이 run 에서 **유일하게 프로젝트 파일을 mutate 할 수 있는 worker** 입니다. 나머지 두 provider 는 같은 run 에서 strict read-only verifier 로 dispatch 됩니다.
-- Executor 의 모델은 provider 별 worker 모델 플래그를 그대로 재사용합니다. 즉 `--executor codex` 이면 Executor 의 모델은 `--codex-model` (기본 `gpt-5.5`), `--executor antigravity` 이면 `--antigravity-model` (기본 `auto`) 가 됩니다.
-- Claude/Codex/Antigravity 세 verifier 는 executor provider 와 관계없이 항상 dispatch 됩니다. Executor 와 같은 provider 라도 별도 CLI 세션으로 verifier 가 호출되어 context 가 분리되므로 self-review 안전장치는 유지됩니다.
-- 실제 파일 변경은 Codex/Antigravity 의 경우 각 CLI 의 auto-edit 모드 (예: `codex exec --sandbox workspace-write`) 를 통해 일어나며, Claude-side Edit/Write tool 을 거치지 않습니다. implementation phase 에서 worker 가 mutation 을 수행하는 위치는 다음 항목에서 설명하는 task worktree 이며, 양쪽 wrapper(`scripts/okstra-codex-exec.sh`, `scripts/okstra-antigravity-exec.sh`) 는 worktree 경로를 4번째 positional 인자로 받아 codex 는 `--add-dir`, antigravity 는 `--include-directories` 로 forward 합니다. 누락하면 codex `workspace-write` 샌드박스가 worktree 쓰기를 EPERM 으로 거부합니다.
-- **Claude executor 의 cwd 처리**: Claude Bash tool 은 per-call cwd 인자를 받지 않고 lead session 의 cwd 를 상속하므로, cwd 에 민감한 toolchain (`cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, `go` 등) 을 worktree 안에서 실행하려면 호출을 `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` 로 prefix 해야 합니다. 단일 Bash 호출 안에서 `cd` 가 leading token 으로 남아야 Claude Code 의 permission auto-allow 가 정상 동작하므로 `bash -lc "..."` / `bash -c "..."` 로 감싸지 않습니다 (감싸면 `cd` 가 가려져 매 호출마다 permission prompt 가 발생). `git -C <path>`, `cargo --manifest-path`, `pytest --rootdir` 처럼 작업 디렉터리 플래그를 받는 도구는 `cd && ` chain 대신 해당 플래그를 우선 사용합니다. Edit/Write/Read tool 은 이미 절대경로를 사용하므로 별도 cwd 처리가 필요 없습니다. 이 규칙은 Claude executor 에만 적용되고 codex / antigravity executor 는 CLI wrapper 가 cwd 를 주입합니다.
-- **Task worktree (모든 task-type 자동 격리)**: 모든 task-type 의 첫 번째 phase prepare 단계에서 `okstra-ctl` 이 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` 에 `git worktree` 를 생성하고, 브랜치 `<work-category-namespace>/<task-id-segment>` (예: `feature/dev-9436`, `fix/dev-7311`) 를 main worktree `HEAD` 에서 분기합니다. 같은 task-key 의 이후 phase 는 동일한 path/branch 를 재사용하므로 status 가 `reused` 로 기록됩니다 (run-prep 시점에 새 `git worktree add` 가 일어나지 않음). 모든 segment 의 `/`·`:` 등 특수문자는 `-` 로 정규화되며, `~/.okstra/worktrees/registry.json` 가 task-key → path/branch 매핑을 전역 관리합니다 (flock-guarded). Executor 의 Edit/Write/build/test/commit, verifier 의 read 는 모두 이 worktree 안에서 수행됩니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 status 가 `skipped-in-worktree` / `skipped-not-git` 로 기록됩니다. 경로·브랜치 충돌은 `PrepareError` 로 즉시 실패시키며, run 종료 후 worktree 는 자동 삭제하지 않습니다 (수동: `git worktree remove` → `git branch -D` + registry 항목 삭제). **단, 아래 implementation stage 격리는 예외입니다.**
-- **implementation stage 격리 (동시 병렬)**: 위 task-key 단위 worktree 는 `requirements-discovery`~`implementation-planning` 에만 해당합니다. `implementation` task 의 각 run 은 **stage 별 격리 worktree** (`~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/stage-<N>/`, 브랜치 `<work-category-namespace>/<task-id-segment>-s<N>`)에서 실행됩니다. registry 가 stage-key (`<task-key>#stage-<N>`) 를 flock 으로 원자 예약하고, `_resolve_effective_stages` 가 `consumers.jsonl` 의 `started` 행 + registry 예약 stage 를 제외하며, stage 선택부터 worktree 생성·registry 예약까지가 task-key 단위 프로비저닝 mutex(`~/.okstra/.locks/worktree-provision/`) 한 임계구역 안에서 수행되므로, 두 `implementation` run 을 동시에 띄우면 서로 다른 ready stage 를 안전하게 잡습니다 (**한 run = 한 stage**). stage worktree 의 base 는 의존 종류로 결정됩니다 — 독립(`depends-on (none)`) = 공통 anchor(첫 stage 진입 시 task-key worktree HEAD 1회 고정), 단일 의존(`depends-on X`) = 선행 stage 의 done `head_commit`, 다중 의존(`depends-on X,Y…`) = 선행들이 모두 머지된 task worktree HEAD(`git merge-base --is-ancestor` 로 검증, 미머지 시 `PrepareError` 로 머지 안내). 실행할 stage 는 `--stage <auto|N>` (`okstra.sh`/`render-bundle` 공통) 또는 okstra-run wizard 의 `stage_pick` 단계로 지정합니다. `project_root` 가 git repo 가 아니거나 nested worktree 면 stage 격리도 평면 동작으로 degrade 합니다.
-- **단일-stage final-verification 산출물 격리**: `--task-type final-verification --stage <N>` 은 해당 implementation stage worktree 를 registry 에서 read-only 로 재사용하면서, run 산출물은 `runs/final-verification/stage-<N>/` 하위에 stage 별로 격리하고 팀 이름에 `-fv-s<N>` 접미사를 붙입니다. 서로 다른 stage 의 final-verification 을 동시에 띄워도 state·worker-results·팀이 충돌하지 않습니다 (같은 stage 를 동시에 두 번 띄우는 것은 격리되지 않음 — TeamCreate 이름 충돌로 즉시 실패). 전체-task 검증(stage 빈 값)은 평면 `runs/final-verification/` 를 유지합니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-type implementation \
-  --executor codex \
-  --codex-model gpt-5.5 \
-  --approved-plan .project-docs/.../runs/implementation-planning/.../reports/final-report-implementation-planning-001.md \
-  --project-id jobs --task-group tasks --task-id 8852 \
-  --task-brief .project-docs/tasks/8852/BUG_REPORT.md
-```
-
-### `--critic`
-
-Phase 5.6 의 opt-in critic pass 를 수행할 provider 를 선택합니다. 값은 `off` | `claude` | `codex` | `antigravity` 중 하나이며 기본값은 `off` 입니다.
-
-- critic 디스패치는 convergence(Phase 5.5) 첫 reverify 라운드와 동시에 실행되고(critic 입력은 Round 0 통합 결과로 고정), gap/blocker 검증 1라운드는 convergence 종료 후 Phase 5.6 에서 수행됩니다 — discovery / error-analysis / implementation-planning 에서는 coverage gap 탐지, final-verification 에서는 acceptance devil's-advocate 역할입니다. 상세 규약은 `prompts/lead/convergence.md` 의 "Coverage critic pass" / "Acceptance critic pass" 섹션을 따릅니다.
-- in-session `okstra-run` wizard 의 critic 선택 단계와 동일한 값 공간을 공유합니다. 허용값 검증은 `prepare_task_bundle` 의 `_resolve_model_bindings` 가 수행하며, 그 외 값은 `PrepareError` 로 즉시 거부됩니다.
-
-### `--approved-plan`
-
-`--task-type implementation` 의 입력으로, 이전 `implementation-planning` run 의 final report 경로를 받습니다. 이 파일의 YAML frontmatter 에는 `approved` field 가 있어야 하며 값이 `true` 여야 합니다.
-
-승인 형식:
-
-- final-report 의 leading `---` YAML 펜스 안에 정확히 한 줄: `approved: true` 또는 `approved: false`
-- 대소문자 무관 (`True` / `TRUE` 도 허용)
-- report-writer 는 항상 `approved: false` 로 발행하고, 사용자가 `true` 로 toggle 하면 implementation 진입 가능
-
-frontmatter `approved: true` 가 아니면 run 은 `contract-violated` 로 거부됩니다. 직접 파일을 편집하는 대신 `--approve` 플래그로 CLI 호출 자체를 승인 행위로 처리할 수도 있습니다.
-
-### `--approve`
-
-`--approved-plan` 과 `--task-type implementation` 과 함께 쓰는 플래그로, **CLI 호출 자체를 plan 승인 신호로 간주**합니다. 동작:
-
-- 지정된 `--approved-plan` 파일의 YAML frontmatter 에서 `approved: false` 라인을 `approved: true` 로 toggle 합니다.
-- 파일 끝에 audit 라인 (`- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\``) 을 append 합니다.
-- 이미 `approved: true` 인 파일이면 frontmatter 는 그대로 두고 audit 라인만 (한 번도 기록 안된 경우) 보강합니다.
-- 파일에 YAML frontmatter 가 없거나 `approved:` 라인이 없으면 즉시 에러로 종료합니다 (잘못된 plan 파일을 가리키고 있을 가능성).
-
-`--approve` 는 `--task-type implementation` 이 아닌 곳에서는 의미가 없으며 에러로 종료합니다. CI/스크립트 환경 또는 한 줄로 "승인 + 다음 phase 실행" 을 함께 처리하고 싶을 때 사용합니다. (이전에 존재하던 `--ack-approved` alias 는 0.8.0 에서 제거되었습니다.)
-
-예:
-
-```bash
-scripts/okstra.sh --task-type implementation \
-  --approve \
-  --approved-plan .project-docs/.../runs/implementation-planning/.../reports/final-report.md \
-  --project-id jobs --task-group tasks --task-id 8852 \
-  --task-brief .project-docs/tasks/8852/BUG_REPORT.md
-```
-
-### `--work-category`
-
-이번 task 의 작업 분류입니다. 값은 다음 중 하나입니다.
-
-- `bugfix`
-- `feature`
-- `refactor`
-- `ops`
-- `improvement`
-- `unknown` (기본값)
-
-평소에는 `requirements-discovery` phase 가 work-category 를 자동 추론하므로 명시할 필요가 없지만, 해당 phase 를 건너뛰는 lifecycle (예: 단발성 `implementation-planning` 부터 시작) 에서는 이 플래그로 분류를 직접 지정합니다. 값은 `task-manifest.json` 에 보존되어 schedule / status 스킬이 grouping 에 사용합니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-type implementation-planning \
-  --work-category refactor \
-  --project-id jobs --task-group tasks --task-id 8852 \
-  --task-brief .project-docs/tasks/8852/PLAN.md
-```
-
-### `--base-ref`
-
-task-key에 대한 격리 worktree를 처음 만들 때 기준으로 삼을 git ref입니다. 브랜치 이름, 태그, commit SHA를 받을 수 있습니다.
-
-- 첫 phase prepare에서는 필수입니다. `okstra-run` skill은 PR base picker와 같은 메뉴(`main`, `dev`, `staging`, `preprod`, `prod`, 직접 입력)로 값을 수집합니다.
-- 같은 task-key의 후속 phase에서는 registry에 저장된 worktree path / branch / base ref를 재사용하므로 새 값은 무시됩니다.
-- `project_root`가 git repo가 아니거나 이미 non-main worktree 안이면 provisioning이 skip되고 이 값도 사용되지 않습니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-type requirements-discovery \
-  --base-ref main \
-  --project-id jobs --task-group tasks --task-id 8852 \
-  --task-brief .project-docs/tasks/8852/BRIEF.md
-```
-
-### `--related-tasks`
-
-간단한 연관 task 식별자 목록을 쉼표로 전달합니다.
-
-예:
-
-```bash
-scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,reply-ui --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
-```
-
-연관 task는 참고용 메타데이터이며 현재 task key를 대체하지 않습니다.
-
-### `--render-only`
-
-실제 Claude 실행 없이 프롬프트와 task bundle만 생성합니다.
-
-이 모드에서는 아래를 수행하지 않습니다.
-
-- Claude 실행
-- `final-report-<task-type>-<seq>.md` 생성
-- `final-<task-type>-<seq>.status` 생성
-
-하지만 아래는 수행합니다.
-
-- stable task root 생성 또는 갱신
-- `task-manifest.json` 생성 또는 갱신
-- `task-index.md` 생성 또는 갱신
-- `instruction-set/` 생성 또는 갱신
-- `instruction-set/reference-expectations.md` 생성 또는 갱신
-- `instruction-set/final-report-template.md` 생성 또는 갱신
-- current `manifests/run-manifest-<task-type>-<seq>.json` 기록
-- `history/timeline.json` 갱신
-- project-level discovery pointer 생성 또는 갱신
-
-### `--no-plan-verification`
-
-`implementation-planning` task-type 의 Phase 6 plan-body verification 라운드를 끕니다. 기본값은 활성. 다른 task-type 에서는 무시됩니다.
-
-- **활성 (default)**: Phase 6 에서 Report writer worker 가 final-report draft 를 작성한 직후, lead 가 합성된 plan 의 §5.5 implementation plan deliverables 본문 (Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback) 을 `P-*` plan-item 단위로 쪼개 모든 analyser 워커 (`claude`, `codex`, 그리고 옵트인된 `antigravity`) 에게 reverify dispatch 합니다. 워커의 평결 (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) 을 집계해 4 가지 gate result (`passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`) 중 하나를 산출하고, `passed` / `passed-with-dissent` 일 때만 final-report 상단의 `- [ ] Approved` 마커가 렌더됩니다. majority DISAGREE 항목은 `## 1. Clarification Items` 의 `Blocks=approval` row 로 변환됩니다 (자동 revise 없음 — 사용자가 답변 후 같은 phase 를 resume 해야 함).
-- **비활성 (`--no-plan-verification` 전달 시)**: Phase 6 sub-step 전체가 skip 되고 final-report 상단의 Approval 마커가 무조건 렌더됩니다 (legacy 동작). 빠른 반복용 opt-out — handoff-ready plan 에는 권장하지 않습니다.
-- 본 flag 는 manifest 의 `convergence.planBodyVerification.enabled` 를 `false` 로 기록합니다. resume 명령에서도 같은 flag 를 명시해야 같은 동작이 유지됩니다 (`_canonical_argv` 가 resume fidelity emit 을 보장).
-- 자세한 라운드 프로토콜 / verdict semantics / state 파일 스키마는 `prompts/lead/convergence.md` 의 "Plan-body verification mode (implementation-planning only)" 섹션 참고.
-
-
-## Interactive input flow
-
-interactive terminal에서 필수 인자 일부를 생략하면 `okstra`가 아래 항목을 순서대로 물을 수 있습니다.
-
-- `Project ID`
-- `Task Group`
-- `Task ID`
-- `Task Type`
-- `Task Brief Path`
-
-예를 들어 아래처럼 실행할 수 있습니다.
-
-```bash
-scripts/okstra.sh --render-only --task-type error-analysis
-```
-
-그러면 누락된 필수값을 stdin으로 입력받은 뒤, 최종 요약과 confirmation을 거쳐 진행합니다.
-
-## Confirmation flow
-
-interactive 실행에서는 실제 파일 생성 전에 아래 성격의 요약을 보여줍니다.
-
-- render-only 여부
-- task type
-- project id
-- task group
-- task id
-- task brief path
-- analysis target
-- related tasks
-- selected workers
-- lead model
-- configured worker models
-- task key
-- task root
-- current run dir
-
-이후 `Continue? [y/yes]:` 프롬프트가 표시되며, `y` 또는 `yes`가 아니면 실행하지 않고 종료합니다.
-
-`--yes`를 사용하면 이 confirmation flow 자체를 건너뜁니다.
-
-
----
-
-## okstra Control Center — 설치 / 자주 쓰는 명령
-
-## okstra Control Center
-
-`okstra-ctl` 은 사용자 홈의 `~/.okstra/` 인덱스를 사용해 모든 타깃 프로젝트의 okstra run 을 가로질러 조회·모니터링·재실행할 수 있는 CLI 다.
-
-### 설치 (전역 wrapper)
-
-`okstra` 와 동일하게 `~/.local/bin/` 아래에 wrapper 를 두면 어디서든 호출 가능하다.
-
-```bash
-cat > ~/.local/bin/okstra-ctl <<'WRAPPER'
-#!/usr/bin/env bash
-exec /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-ctl.sh "$@"
-WRAPPER
-chmod +x ~/.local/bin/okstra-ctl
-```
-
-(`~/.local/bin` 이 `PATH` 에 포함되어 있어야 한다.)
-
-### 자주 쓰는 명령
-
-| 목적 | 명령 |
-|---|---|
-| 작업한 프로젝트 목록 | `okstra-ctl projects` |
-| 최근 run 검색 | `okstra-ctl list --since 7d` |
-| 특정 프로젝트만 | `okstra-ctl list --project sample-project` |
-| 진행 중 run 보기 | `okstra-ctl tail active` |
-| 단일 run 결과 메타 | `okstra-ctl show <runId-or-prefix>` |
-| 결과 보고서 경로 | `okstra-ctl open <runId-or-prefix>` |
-| final-report HTML view 재생성 | `okstra render-views <final-report.md>` |
-| 단일 재실행 | `okstra-ctl rerun <runId-or-prefix> --yes` |
-| 다중 재실행 | `okstra-ctl rerun --filter --project X --status failed --yes` |
-| 가장 최근 재실행 | `okstra-ctl rerun last --project X --task-group Y --yes` |
-| 백필/재스캔 | `okstra-ctl reindex` |
-| 활성 run 재조정 | `okstra-ctl reconcile [--project <id|all>]` |
-| 배치 진행 | `okstra-ctl batch status <batch-id>` |
-
-### `okstra` Node CLI — admin / introspection subcommands
-
-`okstra` Node CLI (`bin/okstra`) 는 installer/admin 명령과 skill / agent 가 사용하는 introspection 명령을 함께 제공합니다. Python 런타임을 직접 호출하지 않고 Node wrapper를 통하므로 `PYTHONPATH` wiring은 `src/lib/python-helper.mjs`가 처리합니다.
-
-| 명령 | 용도 |
-|---|---|
-| `okstra paths [--field <name>\|--shell]` | package/runtime/home/bin/pythonpath/version 경로 출력 |
-| `okstra install [--runtime claude-code\|codex\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | runtime, templates, skills, agents 설치/갱신. 기본 runtime 은 `auto`; 스킬 대상은 runtime 이 아니다. `~/.agents/skills/` 는 항상 생성하고, `~/.claude` 가 있으면 Claude skills + agents 도 설치한다 |
-| `okstra ensure-installed [--runtime claude-code\|codex\|external\|all] [-q]` | 설치 상태 확인, stale이면 같은 runtime 으로 재설치. 기본 `auto` 는 host signal 이 없어도 설치를 계속하며, Agent skill target 과 존재하는 Claude target 의 drift 를 검사한다 |
-| `okstra uninstall [--purge -y]` | 설치 자산 제거. 기본값은 `installed-skills.json` target 목록과 `installed-agents.json` 기준으로 제거하고 사용자 데이터는 보존 |
-| `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 preflight [--runtime <name>] [--cwd <dir>] [--json]` | 스킬 preflight 단일 호출: `ensure-installed`(stale 시 조용히 재설치) + `check-project` 를 합쳐 JSON 하나로 반환. 모든 프로젝트 스코프 스킬의 Step 0 이 이 명령 1회로 수렴한다 |
-| `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | 영구 설정 관리 (예: `pr-template-path`). 원자적 JSON 쓰기 |
-| `okstra memory <add\|list\|search\|show\|archive>` | `~/.okstra/memory-book` 전역 대화 메모리 관리. 프로젝트 `.okstra/` 와 분리된 user-home 저장소이며, `okstra 에 정리해서 보관해` 자연어 스킬의 CLI 기반 |
-| `okstra manager <init\|discover-projects\|new\|task>` | 여러 프로젝트의 okstra task 를 manager-owned context 로 묶는 공개 CLI. `new project`, `new task-group`, `new task` 로 manager 계획을 만들고, `task assign` / `task note` / `task sync` / `task status` / `task run` 으로 프로젝트별 할당과 snapshot 을 관리한다. `new project --project-root` 는 이미 존재하는 디렉터리만 받으며, 그 안의 `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행한다. child task key 는 공개 문서에서 `project-id:task-group:task-id` 전체 형식을 사용하고, 같은 manager task 안에서 child task id 가 다르면 `--child-task-id` 로 exact child 를 지정한다. `task run` 은 child lead 를 직접 실행하지 않고 `prepared` launch metadata/event 와 child launch context packet 을 JSON 으로 반환한다 |
-| `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]` | okstra-rollup 스킬의 read-only 백엔드. catalog 의 모든 task(또는 한 task-group)에 대해 task 별 run 수·소요 시간(raw ms)·에러 수·최신 report 경로와 group 차원 합계 및 상태/카테고리/phase 분포를 JSON 으로 출력한다. `--task-group` 생략 시 프로젝트 전체 catalog 를 대상으로 한다. 시간은 raw ms 이며 HH:MM:SS 포맷·report 본문 종합은 호출자(skill)에 위임한다. 단일 task drill-down 은 `okstra inspect` 계열을 쓴다 |
-| `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | 한 번만 실행: 프로젝트 산출물 루트를 `.project-docs/okstra/` → `.okstra/` 로 이동. 기본 dry-run, `--apply` 로 실제 실행. `git mv` (git worktree) + 빈 `.project-docs/` 제거 + `<PROJECT>/CLAUDE.md` import 라인 + `.gitignore` + `~/.okstra/{recent,active}.jsonl` + `~/.okstra/worktrees/registry.json` 의 해당 프로젝트 row 동기화. 이미 `.okstra/` 가 존재하거나 레거시 디렉토리가 없으면 exit 1 로 거부. v0.x 말까지 유지 후 제거 예정 |
-| `okstra task-list [--project-root <path>]` | `list_project_tasks` + `read_latest_task` 결과를 합쳐 task 카탈로그 + 최근 task 를 JSON 으로 반환 |
-| `okstra task-show <task-key> [--project-root <path>]` | Task Read-Side Snapshot 기반 workflow / phase / status / artifact 요약 |
-| `okstra set-work-status <token> <todo\|in-progress\|blocked\|done> [--note <text>] [--task-group <g>] [--project-root <dir>]` | task-manifest.json 의 사용자 관리 `workStatus`(+`workStatusUpdatedAt`, `--note` 시 `workStatusNote`) 갱신. `<token>` 은 전체 task-key 또는 bare task-id. manifest 렌더러와 동일한 직렬화 규칙으로 기록하며, 모호하면 `stage:"ambiguous"` + `matches[]` 로 반환한다 |
-| `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,antigravity,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 `*.html` (사람용 self-contained) view 를 결정론적으로 생성. 원본 MD 는 수정하지 않음. Node 위임 wrapper는 `scripts/okstra-render-report-views.py` 를 호출. `validators/validate-report-views.py` 가 form-control 위치 / 외부 URL 부재 / stale source digest / Response ID parity 를 검사 |
-| `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --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 블록을 반환. `outcome` 은 완료된 wizard 에서 `renderArgs`, `persistActions`, `confirmationText` 를 한 번에 반환하며, release-handoff 의 project/global PR template 저장은 `persistActions[].command == "config.set"` 로 노출된다. `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` 로 캐시를 우회해 전체 재스캔을 강제할 수 있음(정확성 폴백) |
-
-> 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/lib/python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.
-
-### Live-log sidecar
-
-codex / antigravity 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` / `antigravity-worker` / `report-writer-worker`, implementation role title, FleetView teammate prefix `✳ ` / `⠂ `)을 lead 세션 범위에서 함께 정리하며(lead 자신의 pane 은 제외), lead 는 새 phase 진입 전 `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` 를 한 번 실행해 stale pane 을 비웁니다.