okstra 0.23.0 → 0.24.0

package/bin/okstra

@@ -15,6 +15,7 @@ const COMMANDS = new Map([
   ["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)],
+  ["wizard", () => import("../src/wizard.mjs").then((m) => m.run)],
 ]);
 
 const USAGE = `okstra — multi-agent cross-verification orchestrator for Claude Code
@@ -51,6 +52,8 @@ Introspection commands (JSON output, used by skills to avoid python heredocs):
   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)
 
 Global options:
   --version              Print okstra version and exit

package/docs/kr/architecture.md

@@ -95,7 +95,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 `prepare_task_bundle` 의 두 caller:
 
 1. **`scripts/okstra.sh`**: CLI 인자를 파싱·확인하고 → `prepare_task_bundle` 호출 → `--render-only` 가 아니면 `claude --model ... --session-id ... "$PROMPT"` 를 `exec` 으로 띄움. ~160 줄의 thin wrapper.
-2. **`okstra-run` skill**: 같은 claude 세션 안에서 `AskUserQuestion` 으로 인자를 모은 뒤 → `prepare_task_bundle(render_only=True)` 직접 호출 → 렌더된 lead prompt 를 현재 세션이 그대로 읽어 lead 역할 수행. 새 claude 프로세스를 띄우지 않음.
+2. **`okstra-run` skill**: 같은 claude 세션 안에서 [`okstra_ctl.wizard`](../../scripts/okstra_ctl/wizard.py) 상태머신(`okstra wizard init|step|...` CLI)을 돌려 사용자 입력을 모은 뒤 → `okstra render-bundle` (즉 `prepare_task_bundle(render_only=True)`) 호출 → 렌더된 lead prompt 를 현재 세션이 그대로 읽어 lead 역할 수행. 새 claude 프로세스를 띄우지 않음. 분기/검증/순서는 모두 wizard 가 결정하므로 skill 본문은 `Prompt.kind` 에 맞춰 `AskUserQuestion`(`pick`) 또는 평문 메시지(`text`)를 띄우는 ~30 줄짜리 루프이다.
 
 판단 정책과 worker orchestration 은 lead claude 가 담당하고, okstra 의 prepare 단계는 그 lead 가 정확한 입력 묶음과 출력 골격을 받아 일을 시작할 수 있게 정형화된 자산을 준비할 뿐입니다.
 
@@ -167,7 +167,7 @@ okstra 의 prepare 단계는 디스크 권위 + 단일 python 진입점 모델
 ├────────────────────────────────────────────────────────────────┤
 │                                                                │
 │ scripts/okstra.sh         skills/okstra-run/SKILL.md           │
-│ (CLI: bash 인자 파싱)     (current claude 세션 안 AskUserQuestion) │
+│ (CLI: bash 인자 파싱)     (okstra_ctl.wizard 상태머신 루프)    │
 │      │                              │                          │
 │      └─────────────┬────────────────┘                          │
 │                    ▼                                           │

package/docs/kr/cli.md

@@ -492,6 +492,7 @@ 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` — approval marker 인식 결과와 sanitization 후 diff |
 | `okstra render-bundle <args…>` | `prepare_task_bundle(render_only=True)` 의 thin shim — `python3 -m okstra_ctl.run --render-only` 와 동일 시그니처 |
+| `okstra wizard <init\|step\|render-args\|confirmation> --state-file <path>` | okstra-run 인터랙티브 입력 상태머신 (`okstra_ctl.wizard`). `init` 으로 state file 을 시드한 뒤 skill 이 `step --answer <val>` 을 반복 호출하면 다음 `Prompt` JSON 을 받음. `render-args` 는 최종 `render-bundle` 인자 맵, `confirmation` 은 사용자 echo 블록을 반환 |
 
 > 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/_python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.
 

package/docs/project-structure-overview.md

@@ -101,6 +101,7 @@ okstra/
 | `worktree-lookup.mjs` | 작업별 git worktree 경로 조회 |
 | `plan-validate.mjs` | Approved plan 파일의 approval marker 검증 |
 | `render-bundle.mjs` | `prepare_task_bundle()` 산출 미리보기 |
+| `wizard.mjs` | okstra-run 인터랙티브 입력 상태머신 구동 (`init`/`step`/`render-args`/`confirmation`) |
 | `uninstall.mjs` | `~/.okstra` 및 스킬 제거 |
 
 **핵심 설계**: 모든 CLI 명령은 `okstra paths --shell` 결과를 환경변수로 로드한 뒤, Python의 단일 진입점 `okstra_ctl.run.prepare_task_bundle`을 호출한다. CLI(`okstra.sh`)와 skill(`okstra-run`)이 같은 Python 함수를 공유하는 **Rule of Two**를 강제한다.
@@ -126,6 +127,7 @@ okstra/
 | `workers.py` | Worker 모델 할당 (Claude/Codex/Gemini) |
 | `backfill.py` | 레거시 run 자동 마이그레이션 |
 | `models.py` | `ModelAssignment`, `PrepareInputs`, `PrepareOutputs` 데이터클래스 |
+| `wizard.py` | `WizardState`, `Prompt`, `STEPS` — okstra-run 입력 수집 상태머신 (단일 권위) |
 
 #### 3.2.2 `scripts/okstra_project/` — 프로젝트 메타 리졸버
 
@@ -242,7 +244,7 @@ okstra/
 
 ### 3.8 `bin/okstra` — Node.js CLI
 
-12개 명령(`paths`, `install`, `ensure-installed`, `uninstall`, `doctor`, `setup`, `check-project`, `task-list`, `task-show`, `worktree-lookup`, `plan-validate`, `render-bundle`) 라우터. 명령 파싱 → `src/<cmd>.mjs` 동적 로드 → `run(args)` 호출 → exit code 반환.
+13개 명령(`paths`, `install`, `ensure-installed`, `uninstall`, `doctor`, `setup`, `check-project`, `task-list`, `task-show`, `worktree-lookup`, `plan-validate`, `render-bundle`, `wizard`) 라우터. 명령 파싱 → `src/<cmd>.mjs` 동적 로드 → `run(args)` 호출 → exit code 반환.
 
 ---
 
@@ -306,6 +308,7 @@ okstra/
 | 프로젝트 | `setup.mjs`, `check-project.mjs` |
 | Task 조회 | `task-list.mjs`, `task-show.mjs` |
 | 실행 보조 | `worktree-lookup.mjs`, `plan-validate.mjs`, `render-bundle.mjs` |
+| 스킬 구동 | `wizard.mjs` |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.23.0",
-  "builtAt": "2026-05-15T01:56:19.363Z",
+  "package": "0.24.0",
+  "builtAt": "2026-05-15T05:35:39.299Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -61,7 +61,7 @@ Hard rules:
 - Include all four convergence categories (Full Consensus, Partial Consensus, Contested, Worker-Unique). Do not omit Contested or Worker-Unique findings.
 - Include a Round History sub-table in Section 1 (one row per executed round) and a `round2SkippedReason` line below it. When convergence is disabled, omit both. The values are quoted verbatim from `state/convergence-<task-type>-<seq>.json` — do not recompute.
 - Treat `verification-error` votes as their own verdict. They are listed in vote summaries as `verification-error`, not folded into AGREE/DISAGREE counts.
-- Include the per-agent execution status table and the token-usage summary section. All numbers come from `team-state-<task-type>-<seq>.json` (populated by `okstra-token-usage.py` at the start of Phase 7). Do not estimate or invent.
+- Include the per-agent execution status table and the token-usage summary section. **Leave the 10 token-related `{{...}}` placeholders verbatim** (`{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`). You run in Phase 6, but `team-state-<task-type>-<seq>.json` is populated by `okstra-token-usage.py` at the start of Phase 7 and the same Phase 7 invocation substitutes the placeholders via `--substitute-final-report`. Never replace these cells with `not-collected`, `N/A`, `--`, `0`, or any other sentinel — doing so deletes the substitution target and the report ships with no token numbers. Likewise do NOT append a note like "Phase 7 has not run yet"; that statement is unfalsifiable at write-time and is wrong by the time the report is shipped.
 - If only one analysis worker produced a usable result, perform a reduced-confidence write-up and say so explicitly.
 - If evidence is missing, write `I don't know` rather than fabricating confidence.
 - Cite file paths and line numbers for every code-evidence claim.