okstra 0.23.0 → 0.24.0

package/runtime/python/okstra_token_usage/collect.py

@@ -90,8 +90,19 @@ def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
     # when TeamCreate succeeded); only fall back to the `okstra-<task-id>`
     # convention if team-state did not record one. Matching downstream is
     # case-insensitive so either casing works.
+    # Lead-written teamName lives at one of two paths depending on which
+    # version of the contract the run was authored under:
+    #   - nested:  state.team.teamName        (current documented schema)
+    #   - root:    state.teamName             (older convention; still common in
+    #                                          actual runs because the team
+    #                                          contract docs did not pin the
+    #                                          location until v0.24)
+    # Read both; whichever is non-empty wins. The fallback derives a short
+    # team name from task-id only and routinely mis-matches multi-segment
+    # task keys (e.g. `okstra-fontsninja-classifier-v2:DEV-9389:DEV-9389`),
+    # so it is a last resort.
     state_team = (state.get("team") or {})
-    team_name = state_team.get("teamName") or ""
+    team_name = state_team.get("teamName") or state.get("teamName") or ""
     if not team_name:
         task_id = task_key.rsplit(":", 1)[-1] if task_key else ""
         team_name = f"okstra-{task_id}" if task_id else ""

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -169,6 +169,7 @@ Place this section immediately after the execution status table.
 ```
 
 Token Summary Generation Rules:
+- **You author this section in Phase 6, BEFORE Phase 7 runs the collector.** Therefore you MUST leave the 10 placeholders (`{{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}}`) verbatim in the table cells — `okstra-token-usage.py --substitute-final-report` will fill them in Phase 7. Never replace any of these cells with a literal number, `not-collected`, `N/A`, `--`, `0`, or any other sentinel: that erases the substitution target, and the report ships with no token numbers. Also do not insert a note like "Phase 7 has not run yet" — the report is read AFTER Phase 7, so that statement is wrong on arrival.
 - All values come from `usageSummary` (populated by `scripts/okstra-token-usage.py` at the start of Phase 7). Do not estimate or invent.
 - **Lead** row: `usageSummary.leadTotalTokens` / `usageSummary.leadBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.lead`.
 - **Worker 합계** row: `usageSummary.workerTotalTokens` / `usageSummary.workerBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.claudeWorkers`.

package/runtime/skills/okstra-run/SKILL.md

@@ -5,13 +5,13 @@ description: Use when the user wants to start an okstra task (cross-verification
 
 # OKSTRA Run (in-session)
 
-Launch an okstra task — gather inputs interactively, render the full task bundle through the single python entrypoint, then take over as `Claude lead` in the current session.
+Launch an okstra task — gather inputs interactively via the **wizard state machine** (`okstra wizard ...`), then take over as `Claude lead` in the current session.
 
-**Single authority**: this skill and `okstra.sh` both call the exact same python function `okstra_ctl.run.prepare_task_bundle()`. The skill does NOT shell out to `okstra.sh` — that would create a second orchestration path and reintroduce env-var leakage between the parent claude session and child bash.
+**Single authority**: this skill drives `okstra wizard`, which owns every step (ordering, branching, validation). The skill is just a thin prompt-relay loop — it never decides "what to ask next" itself. If the flow needs to change, edit `scripts/okstra_ctl/wizard.py`, not this file.
 
 ## When to Use
 
-- The user is already inside a Claude Code session and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
+- The user is inside a Claude Code session and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
 - Continue an existing task (next phase) without leaving the current claude session.
 
 ## When NOT to Use
@@ -20,51 +20,47 @@ Launch an okstra task — gather inputs interactively, render the full task bund
 - User wants status only — use `okstra-status`.
 - User wants past runs — use `okstra-history`.
 
-## Prompt convention (use the right tool for the right input shape)
+## How the wizard talks to you
 
-`AskUserQuestion` always renders a picker UI with a forced auto-attached `Other` option. While the user types into `Other`, the picker re-renders and the experience feels out of sync. So:
+Every wizard call returns JSON. The two shapes you'll see:
 
-- **Use `AskUserQuestion` ONLY when the answer is a fixed pick from a short option set** (2–4 distinct, mutually exclusive choices). Examples in this skill: task-type choice (Step 4), executor provider (claude/codex/gemini), model picker (default/opus/sonnet/haiku per provider), Use defaults vs Customize, Proceed vs Edit confirmation.
-- **For pure free-text inputs** (file paths, task identifiers, CSV strings, free directives, branch names typed by the user) **do NOT use `AskUserQuestion`**. Instead, write a plain text message (e.g. `"Task group (예: backend-api, INV-1234)을 알려주세요. 빈 줄이면 취소."`) and consume the user's NEXT message as the answer. Then validate and re-prompt with another plain text message on failure.
-- **For "menu + free-text" places** (base-ref pickers, PR base branch) — show the menu with `AskUserQuestion` listing only the canonical options + a literal option labeled `직접 입력`. When the user picks `직접 입력`, follow up with a **separate** plain text prompt and consume the next user message. Do NOT rely on `Other` auto-text inside the picker — its re-render is the root cause of the lag.
+```json
+{ "ok": true, "echo": "task-group: backend-api",
+  "next": { "step": "task_id", "kind": "text", "label": "...", "options": [], "echoTemplate": "..." } }
+```
 
-Echo each captured answer on one short line (e.g. `task-group: backend-api`) so the user sees what was registered, regardless of which prompt shape was used.
+```json
+{ "ok": false, "error": "approved plan has no APPROVED marker: ...",
+  "current": { "step": "approved_plan", "kind": "text", "label": "..." } }
+```
 
-## Authority Files (disk-only — no env var caching for per-run identity)
+On `ok: false`, re-prompt with the same `current.step` using the error message. The wizard never advances on validation failure; the user retries the same step.
 
-Every step reads disk afresh. The `OKSTRA_*` env vars below identify the
-**runtime installation** (stable across runs) — they are NOT per-task identity.
+The wizard tells you *which UI to use* via `kind`:
 
-- `~/.okstra/version` — okstra runtime version stamp
-- `<PROJECT_ROOT>/.project-docs/okstra/project.json`
-- `<PROJECT_ROOT>/.project-docs/okstra/discovery/{task-catalog,latest-task}.json`
-- `<task-root>/task-manifest.json`
+- `kind: "pick"` → render `AskUserQuestion` with `label` and `options[].label` (use `options[].value` to call `--answer`).
+- `kind: "text"` → write `label` as a plain text message and consume the user's NEXT message as the answer.
+- `kind: "done"` → input collection finished; move to Step 5.
 
-## Step 0: Verify okstra runtime + project setup
+Never invent additional questions. Never reorder. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
 
-Do NOT hard-code or guess any okstra path. Every run loads them fresh from
-the single authority — `okstra`:
+## Step 1: Verify okstra runtime + project setup
 
 ```bash
-# 0) Resolve runner: prefer PATH (npm-installed) over npx (avoids per-call registry lookup).
-#    If the user installed okstra via npm, they control upgrade timing — do not force @latest.
 if command -v okstra >/dev/null 2>&1; then
   OKSTRA_CMD="okstra"
 else
   OKSTRA_CMD="npx -y okstra@latest"
 fi
 
-# 1) Ensure runtime is fresh (idempotent, cached when up-to-date)
 $OKSTRA_CMD ensure-installed >/dev/null 2>&1 || {
   echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
   exit 1
 }
 
-# 2) Load all runtime paths into the shell as OKSTRA_* exports
 eval "$($OKSTRA_CMD paths --shell)"
 export PYTHONPATH="$OKSTRA_PYTHONPATH"
 
-# 3) Verify the current project has okstra metadata (project.json + projectId)
 OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
   echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
   echo "$OKSTRA_PROJECT_INFO" >&2
@@ -72,250 +68,101 @@ OKSTRA_PROJECT_INFO="$($OKSTRA_CMD check-project --json)" || {
 }
 ```
 
-After Step 0 the following are guaranteed:
+If `OKSTRA_PROJECT_INFO.ok` is `false`, ask the user with a **plain text prompt** for an absolute project-root path; rerun `okstra check-project --cwd <path>`. Re-prompt with plain text on failure.
 
-| Variable | Meaning |
-|---|---|
-| `$OKSTRA_WORKSPACE` | passed to python as `workspace_root` (prompts/, templates/, validators/, agents/ root) |
-| `$OKSTRA_AGENTS_DIR` | source dir of worker `*.md` (subagent definitions) |
-| `$OKSTRA_PYTHONPATH` | already exported as `PYTHONPATH` |
-| `$OKSTRA_BIN` | bash entrypoints (`okstra.sh`, codex/gemini exec wrappers) |
-| `$OKSTRA_HOME` | `~/.okstra` (recent.jsonl, locks, projects/, archive/) |
-| `$OKSTRA_PROJECT_INFO` | JSON: `{ok, projectRoot, projectJsonPath, projectId}` — parse and reuse instead of re-resolving in Step 1 |
+Parse `projectRoot` and `projectId` from `OKSTRA_PROJECT_INFO`.
 
-## Step 1: Resolve PROJECT_ROOT and projectId
-
-Prefer `$OKSTRA_PROJECT_INFO` from Step 0 — it already carries `{ok, projectRoot, projectJsonPath, projectId}`. Only re-resolve when that JSON's `ok` is false (cwd outside an okstra project):
+## Step 2: Initialize the wizard
 
 ```bash
-okstra check-project --cwd "$(pwd)"
-```
+STATE_FILE="$(mktemp -t okstra-wizard.XXXX.json)"
 
-- If `ok: true`: read `projectRoot` and `projectId` from the JSON.
-- If `ok: false`: ask the user with a **plain text prompt** (not `AskUserQuestion` — this is pure free text per the convention above) for an absolute project-root path; rerun with `okstra check-project --cwd <their input>`. Re-prompt with another plain text message on failure.
-
-## Step 2: Choose task — existing vs new
-
-```bash
-okstra task-list --project "$PROJECT_ROOT"
+okstra wizard init \
+  --state-file "$STATE_FILE" \
+  --project-root "$projectRoot" \
+  --project-id "$projectId"
 ```
 
-Output is JSON `{ok, projectRoot, tasks: [...], latest: {...}|null}`.
-
-Use `AskUserQuestion`:
-
-- **Label**: "Which task?"
-- **Options**: each existing task with label `"<taskKey>  ·  <currentPhase or taskType>  ·  next: <nextRecommendedPhase>"`; mark the `latest` entry with `(latest)`. Final option: `"Start a brand-new task"`. Limit to 8 candidates per page; add `"More..."` if more exist.
-
-For an existing pick, read its `task-manifest.json` to capture `taskType` and `workflow.nextRecommendedPhase`.
-
-## Step 3: For new tasks — collect identity
-
-Skip if continuing existing.
-
-Use **plain text prompts** (one at a time — write the message and consume the user's next reply; do NOT use `AskUserQuestion` for these per the convention above):
-
-1. `"Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)"` → `task_group`
-2. `"Task id 를 알려주세요 (예: login-error-analysis, dev-9043)"` → `task_id`
-
-Validate that slugified `task_group` and `task_id` each contain at least one alphanumeric character. On failure, re-prompt with another plain text message stating the validation failure.
+Output: the same `{ok, next}` JSON described above. The first `next` is always `step: "task_pick"`.
 
-## Step 4: Choose task-type
+## Step 3: Run the prompt loop
 
-`AskUserQuestion` with six fixed options:
+Repeat until `next.kind == "done"`:
 
-| Option | Description |
-|---|---|
-| `requirements-discovery` | Classify request and route to next safe phase |
-| `error-analysis` | Evidence-based root-cause analysis (no code changes) |
-| `implementation-planning` | Plan options + request user approval |
-| `implementation` | Execute approved plan (requires `--approved-plan`) |
-| `final-verification` | Acceptance + residual-risk review |
-| `release-handoff` | Drive commit / push / PR with user-selected actions after `accepted` final-verification |
+1. **Render** the prompt according to `kind`:
+   - `pick` → `AskUserQuestion` with `label` and `options`. The user's chosen option's `value` is the answer string.
+   - `text` → plain text message containing `label`. Consume the user's next reply verbatim as the answer string (empty reply = empty string).
+2. **Submit** the answer:
+   ```bash
+   okstra wizard step --state-file "$STATE_FILE" --answer "$ANSWER"
+   ```
+3. **Handle result**:
+   - `ok: true` → echo `result.echo` to the user on one short line, then loop with `result.next`.
+   - `ok: false` → show `result.error` to the user verbatim, then loop with `result.current` (re-prompt the same step).
 
-For existing tasks, present `nextRecommendedPhase` as the first option (recommended default).
+That is the entire interactive flow. The wizard handles:
 
-If `implementation` chosen, ask two more questions in order:
-- **Plain text prompt** (file path is pure free text): `"approved final-report.md 의 경로를 알려주세요 (APPROVED 마커가 있어야 합니다)"`. The underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`. Re-prompt with plain text on failure.
-- **`AskUserQuestion`** with three options (`claude` / `codex` / `gemini`) — only this provider mutates project files; the other two run as read-only verifiers. Default `claude` (or `OKSTRA_DEFAULT_EXECUTOR` if set). Pass the answer through `PrepareInputs.executor`.
+- new-vs-existing task split, task-group / task-id slug validation,
+- task-type pick (with `nextRecommendedPhase` surfaced as recommended for existing tasks),
+- brief path (with `유지 / 변경` for existing tasks),
+- base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
+- `implementation`-only sub-flow: approved-plan path (APPROVED marker check) + executor pick,
+- `Use defaults / Customize` branch with profile-aware worker/model questions,
+- `release-handoff` PR template override + persist scope,
+- final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
 
-## Step 4.6: Base ref for the task worktree (first phase only)
+Do not second-guess the wizard. If the next prompt seems out of place, the bug is in `wizard.py`, not in your interpretation of the user's input.
 
-`okstra prepare` provisions a per-task git worktree on first phase of a task-key
-and reuses it on every subsequent phase. The base ref of that worktree is the
-**user's choice**, not the caller's current `HEAD`, so the worktree never
-silently inherits an unrelated branch you happen to be checked out on.
+## Step 4: Show the confirmation block before the final Proceed
 
-First, decide whether to ask:
+When `next.step == "confirm"`, before relaying the picker, fetch the human-readable selection summary:
 
 ```bash
-okstra worktree-lookup "<project-id>" "<task-group>" "<task-id>"
+okstra wizard confirmation --state-file "$STATE_FILE"
 ```
 
-Output JSON: `{ok: true, entry: null}` means no active worktree → **ASK**. A
-non-null `entry` with `status: "active"` → **REUSE**.
+Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Print `text` to the user, then render the `confirm` picker (Proceed / Edit).
 
-- `REUSE` → the registered worktree is reused; set `base_ref=""` and skip the
-  question (the registered base is authoritative).
-- `ASK` → this is the first phase for this task-key. Continue.
+## Step 5: Render the task bundle
 
-Use the **menu + free-text two-step pattern** (per the convention above):
-
-1. `AskUserQuestion` with label `"이 task worktree 의 base branch?"` and exactly these single-select options (NO auto-Other typing — the literal `직접 입력` option is the typed-input escape hatch):
-   1. `main` (recommended)
-   2. `dev`
-   3. `staging`
-   4. `preprod`
-   5. `prod`
-   6. `직접 입력`
-2. If the user picks `직접 입력`, follow up with a **plain text prompt**: `"base ref 를 입력해주세요 (branch, tag, 또는 short/full SHA)"`. Consume the user's next message as the chosen ref.
-3. Otherwise the picked option label is the chosen ref directly.
-
-Validate the chosen ref exists in the MAIN worktree before continuing:
+When `next.kind == "done"`, fetch the final args:
 
 ```bash
-git -C "$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir | xargs dirname)" \
-    rev-parse --verify --quiet "<chosen-ref>^{commit}" >/dev/null \
-  || { echo "ref not found locally: <chosen-ref>"; exit 1; }
-```
-
-On failure, re-prompt with a plain text message (or return to step 1's
-menu if the user wants to pick a different canonical branch). Echo the
-resolved short SHA back to the user (`base 확정: <ref> (<short-sha>)`)
-and capture `base_ref=<chosen-ref>` for Step 7.
-
-## Step 5: Brief path
-
-- New task: **plain text prompt** (file path is pure free text per the convention) `"task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)"`. Consume the user's next message; verify the file exists; on failure, re-prompt with another plain text message.
-- Existing task: default to the manifest's `taskBriefPath`. Show it; ask `AskUserQuestion` `"기존 경로를 유지할까요?"` with options `유지` / `변경`. On `변경`, follow up with a plain text prompt for the new path.
-
-## Step 6 (optional): Directive / workers / models / related / clarification
-
-Single `AskUserQuestion` first: `"기본 워커/모델로 진행할까요, 아니면 커스터마이즈할까요?"` (options: `Use defaults`, `Customize`).
-
-- `Use defaults` → all overrides remain empty.
-- `Customize` → the prompts you ask depend on the `task_type` chosen in Step 4. Blank answer always means "use default". Never call the prompt label "worker CSV" — use plain Korean labels as shown below.
-
-### Model selection options (used by 6a and 6b)
-
-All model prompts MUST use `AskUserQuestion` with a fixed option list — never free text. This prevents typos like `gpt-5.5-high` (a non-existent model) reaching the manifest. The options below are derived from `scripts/okstra_ctl/models.py` `*_MAPPING` and show "default + 3 latest". Blank/`default` means "use phase default".
-
-- **Claude (lead / claude-worker / report-writer)** options: `default`, `opus`, `sonnet`, `haiku`
-- **Codex (codex-worker)** options: `default`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`
-- **Gemini (gemini-worker)** options: `default`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `auto`
-
-When the user picks `default`, pass an empty string to the corresponding `--*-model` flag. Pick any other option ⇒ pass it verbatim. If the user truly needs a value outside the list (e.g. a pinned long-form id), they can use the question's built-in `Other` to type it — but the four canonical options cover the supported set, so `Other` should be rare.
-
-### 6a. `implementation` phase (executor-driven)
-
-In this phase the roster is fixed by the profile (executor + two verifiers + report-writer). The Step 4 `executor` answer already determines who mutates code; verifier models use phase-specific defaults (`Claude verifier`=sonnet, `Codex verifier`=gpt-5.5, `Gemini verifier`=auto). So ask **only three model prompts** (each via `AskUserQuestion` with options from the table above), plus directive/related/clarification:
-
-1. `AskUserQuestion` `"리더(Claude lead) 모델?"` (Claude options) → `lead_model`
-2. `AskUserQuestion` `"실행자({executor-provider}) 모델?"` with options matching the executor's provider (Claude / Codex / Gemini list above) → maps to `claude_model` / `codex_model` / `gemini_model`. The other two provider model fields stay empty (verifiers use defaults).
-3. `AskUserQuestion` `"리포트 작성자(report-writer) 모델?"` (Claude options) → `report_writer_model`
-4. **Plain text prompt** (free text) `"추가 directive 가 있으면 적어주세요 (없으면 빈 줄)"` → `directive`. Consume the user's next message verbatim; an empty line means "no directive".
-5. **Plain text prompt** (free text) `"관련 task id 목록을 쉼표로 구분해서 적어주세요 (없으면 빈 줄)"` → `related_tasks_raw`.
-
-Do NOT ask for `workers_override` in implementation — the profile's required roster must be preserved (verifier slots are mandatory). Leave `workers_override=""`.
-
-### 6b. Other phases (`requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`, `release-handoff`)
-
-**Before asking any worker/model question, resolve the profile's allowed roster:**
-
-```python
-from okstra_ctl.workers import resolve_profile_workers
-profile_workers = resolve_profile_workers(Path("<OKSTRA_PROMPTS_PROFILES_DIR>/<task-type>.md"))
+okstra wizard render-args --state-file "$STATE_FILE"
 ```
 
-This is the **only** set of worker IDs you may show or ask about. Never offer
-workers outside this list. Special cases:
-
-- If `profile_workers` is empty (e.g., `release-handoff` is lead-only with no
-  `- Required workers:` block), **skip the worker question and all
-  worker-model questions entirely** — only ask lead model, directive, related,
-  clarification. The backend forces `workers=[]` for these profiles.
-- Otherwise, the worker question must enumerate **only** `profile_workers` —
-  do NOT show `claude, codex, gemini, report-writer` blindly.
-
-Ask each in turn. **Model prompts use `AskUserQuestion`** with the fixed option lists above. **All other prompts use plain text messages** (do NOT wrap free-text inputs in `AskUserQuestion` — the auto-Other re-render lag is what we're avoiding). Skip any worker-model prompt whose worker is not in `profile_workers`.
-
-1. (only when `profile_workers` is non-empty) **Plain text prompt** `"참여 워커 목록을 쉼표로 구분해서 적어주세요. 빈 줄이면 프로필 기본값 <profile_workers_csv> 을 그대로 씁니다. 사용 가능한 워커: <profile_workers_csv>"` → `workers_override`. Validate the answer is a subset of `profile_workers`; on failure, re-prompt with another plain text message. (Backend also rejects violations with `WorkersError`.)
-2. `AskUserQuestion` `"리더(Claude lead) 모델?"` (Claude options) → `lead_model`
-3. (only if `claude` ∈ resolved workers) `AskUserQuestion` `"claude 워커 모델?"` (Claude options) → `claude_model`
-4. (only if `codex` ∈ resolved workers) `AskUserQuestion` `"codex 워커 모델?"` (Codex options) → `codex_model`
-5. (only if `gemini` ∈ resolved workers) `AskUserQuestion` `"gemini 워커 모델?"` (Gemini options) → `gemini_model`
-6. (only if `report-writer` ∈ resolved workers) `AskUserQuestion` `"리포트 작성자 모델?"` (Claude options) → `report_writer_model`
-7. `AskUserQuestion` `"추가 directive (선택, 빈 칸 가능)"` (free text) → `directive`
-8. `AskUserQuestion` `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` (free text) → `related_tasks_raw`
-9. `AskUserQuestion` `"clarification-response 파일 경로 (follow-up 시에만, 빈 칸 가능)"` (free text) → `clarification_response_path`
-10. (only when `task_type == "release-handoff"`) **Plain text prompt** `"PR 본문 템플릿 경로 1회성 override (빈 줄이면 project.json → ~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)"` → `pr_template_path`. The backend (`okstra_ctl.pr_template.resolve_pr_template_path`) validates the file exists and surfaces `PrTemplateError` on failure.
-    - **Persist follow-up** (only when the user typed a non-empty path AND it differs from any currently-registered project/global value): ask `AskUserQuestion` `"방금 입력한 경로를 영구 저장할까요?"` with three options:
-      1. `이번 run 만 (1회성)` — proceed with the override; do NOT touch project.json or global config.
-      2. `프로젝트에 저장 (project scope)` — run `okstra config set pr-template-path "<path>" --scope project` and use the override for this run too.
-      3. `전역에 저장 (global scope)` — run `okstra config set pr-template-path "<path>" --scope global` (must be absolute or `~/`-prefixed; if not, re-ask with a plain text prompt for an absolute version) and use the override for this run too.
-    - Skip the persist follow-up entirely when the user left the override blank, or when the typed value matches the value already stored at the scope it would land in (avoid no-op confirmations).
-
-For prompts whose target worker is NOT in the resolved workers list (after override), present a single confirmation line such as `gemini-model 생략 (workers에 gemini 없음)` so the user can see why the question was skipped.
-
-## Step 6.5: Confirm selections before rendering
-
-Before invoking `okstra render-bundle`, echo the resolved selections back to the user in a compact block so they can verify what will be passed. Show the **effective** values, not the raw input — i.e. when the user left a field blank, display `default` (and where known, the actual default such as `opus` / `sonnet`). Example for an `implementation` run:
-
-```
-선택 확인:
-  task-type     : implementation
-  task-key      : <group>/<id>
-  base-ref      : main (resolved <short-sha>)   ← worktree base, first phase only
-  executor      : codex
-  workers       : (프로필 기본 — executor + verifier 2 + report-writer)
-  lead-model    : default (opus)
-  codex-model   : gpt-5.5                ← executor model
-  claude-model  : default (sonnet)       ← verifier
-  gemini-model  : default (auto)         ← verifier
-  report-writer : default (opus)
-  directive     : (none)
-  approved-plan : <abs path>
-```
-
-Then `AskUserQuestion`: `"이대로 진행할까요?"` with options `Proceed` / `Edit`. On `Edit`, return to the relevant Step 6 sub-prompt.
-
-## Step 7: Call `okstra render-bundle`
-
-This is the single command that materializes the entire task bundle. The
-subcommand auto-supplies `--workspace-root` (from `okstra paths --field
-workspace`) and forces `--render-only`, so the current claude session itself
-takes over as lead — no new claude is spawned.
+Output: `{ok: true, args: {"project-root": "...", "task-type": "...", ...}}`. Build the `okstra render-bundle` invocation from `args`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
 ```bash
 okstra render-bundle \
-  --project-root "<project-root>" \
-  --project-id "<project-id>" \
-  --task-group "<task-group>" \
-  --task-id "<task-id>" \
-  --task-type "<task-type>" \
-  --task-brief "<brief-path-from-user>" \
-  --executor "<claude|codex|gemini or empty for default>" \
-  --approved-plan "<approved-plan-or-empty>" \
-  --base-ref "<chosen-ref-from-step-4.6 or empty when reusing existing worktree>" \
-  --workers "<comma-separated worker list, or empty for profile default; MUST be empty for implementation>" \
-  --directive "<directive or empty>" \
-  --lead-model "..." --claude-model "..." --codex-model "..." \
-  --gemini-model "..." --report-writer-model "..." \
-  --related-tasks "..." \
-  --clarification-response "<clarification-or-empty>" \
-  --pr-template-path "<pr-template-override-or-empty; release-handoff only>"
+  --project-root "<args.project-root>" \
+  --project-id   "<args.project-id>" \
+  --task-group   "<args.task-group>" \
+  --task-id      "<args.task-id>" \
+  --task-type    "<args.task-type>" \
+  --task-brief   "<args.task-brief>" \
+  --executor     "<args.executor>" \
+  --approved-plan "<args.approved-plan>" \
+  --base-ref     "<args.base-ref>" \
+  --workers      "<args.workers>" \
+  --directive    "<args.directive>" \
+  --lead-model   "<args.lead-model>" \
+  --claude-model "<args.claude-model>" \
+  --codex-model  "<args.codex-model>" \
+  --gemini-model "<args.gemini-model>" \
+  --report-writer-model "<args.report-writer-model>" \
+  --related-tasks "<args.related-tasks>" \
+  --clarification-response "<args.clarification-response>" \
+  --pr-template-path "<args.pr-template-path>"
 ```
 
-Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full
-rendered lead-prompt text (because `--render-only` is on). Parse the labelled
-lines to get `TASK_ROOT`, `INSTRUCTION_SET_DIR`, and from there the
-`claude-execution-prompt.md` path used by Step 8.
+`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT` and `INSTRUCTION_SET_DIR`.
+
+The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
-The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`),
-writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery
-files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
+You can delete `$STATE_FILE` after this point — its job is done.
 
-## Step 8: Take over as Claude lead
+## Step 6: Take over as Claude lead
 
 Read these files (do not paraphrase) and enter `Claude lead` mode:
 
@@ -330,26 +177,43 @@ Then proceed through the phases exactly as the lead prompt directs (Phase 1 cont
 Inform the user with one short line:
 > Took over as Claude lead for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
 
+## Persisting the PR template scope (release-handoff)
+
+When `wizard render-args` returns a non-empty `pr-template-path` AND the state has `pr_template_scope == "project"` or `"global"`, run the matching config command BEFORE `render-bundle`:
+
+```bash
+# project scope
+okstra config set pr-template-path "<path>" --scope project
+# global scope (must be absolute or ~/-prefixed)
+okstra config set pr-template-path "<path>" --scope global
+```
+
+The scope is exposed via `wizard render-args` only as the `pr-template-path` value (1-shot override); the persist hint lives in the wizard state. Read it with:
+
+```bash
+python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('pr_template_scope',''))" "$STATE_FILE"
+```
+
+(or just inspect the JSON state file directly — it is a plain serialized `WizardState`).
+
 ## Concurrency
 
 - `prepare_task_bundle` serializes per-task via `~/.okstra/.locks/<task-key>.lock`. Concurrent skill invocations on the same task wait; different tasks proceed in parallel.
-- The skill must NOT call `okstra.sh` or any other bash entrypoint that would re-implement the orchestration. The python function is the single authority.
-- No env var carries identity across steps — every step re-reads disk authority.
+- Each wizard run owns its own `$STATE_FILE`; two parallel skill invocations do not collide.
+- The skill must NOT call `okstra.sh` or any other bash entrypoint that would re-implement the orchestration. The wizard + `render-bundle` is the single authority.
 
 ## Failure Modes
 
 | Symptom | Cause | Fix |
 |---|---|---|
 | `okstra runtime missing: ...` | First run on this machine, or stale install | `npx okstra@latest install` once, retry. |
-| `OKSTRA_PYTHONPATH unbound` / `ModuleNotFoundError: okstra_project` | Step 0 was skipped or env vars dropped | Re-run Step 0; never invoke python without exporting `PYTHONPATH=$OKSTRA_PYTHONPATH`. |
-| `task root not found for <key>` | catalog entry stale or task-key typo | Re-run Step 2 (`okstra task-list`) and show available keys |
-| `PROJECT_ROOT 를 해석할 수 없습니다` | cwd outside okstra project, no git toplevel | Ask user for absolute path |
-| `approved plan has no recognised user-approval marker` | `implementation` without proper approval | Ask user to add `APPROVED` to the plan, or pick a different task-type |
-| `task brief not found` | brief-path doesn't resolve relative to cwd or project-root | Re-ask Step 5 |
-| record_start failed | `~/.okstra` lock or disk issue | Non-fatal — bundle is valid; warn and continue |
+| `No module named okstra_ctl.wizard` | Install predates wizard module | `npx okstra@latest install` to refresh. |
+| `wizard step` returns `ok: false` repeatedly | User keeps giving invalid answers | Echo the error verbatim and re-prompt the same step — do not advance. |
+| `task root not found for <key>` | catalog entry stale or task-key typo | Restart the wizard (`okstra wizard init`) to refresh the pick list. |
+| `approved plan has no APPROVED marker` | `implementation` without proper approval | Ask the user to add `APPROVED` to the plan, or pick a different task-type. |
 
 ## Output Rules
 
-- Echo each `AskUserQuestion` outcome on one short line so user sees what was captured.
-- Never invent identity; re-ask if blank.
-- After Step 8, begin the lead workflow without re-summarizing the skill itself.
+- Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
+- Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
+- After Step 6, begin the lead workflow without re-summarizing the skill itself.

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -486,6 +486,7 @@ The script reads:
 ## Team State Persistence
 
 Information to be recorded in the team-state JSON file:
+- `teamName` — record the string that was passed to `TeamCreate(team_name: ...)`. Either `state.teamName` (root) or `state.team.teamName` (nested) is accepted by `scripts/okstra_token_usage/collect.py`. Be consistent within a single run. Without this value the Phase 7 collector falls back to `okstra-<task-id>` (short form), which does NOT match worker jsonls whose team needle carries the full multi-segment task key — every worker will then be recorded as `source: "unavailable"`.
 - Current status of each worker role
 - Start/end times for each worker
 - Prompt history path for each worker

package/src/wizard.mjs

@@ -0,0 +1,105 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra wizard — interactive okstra-run input collector
+
+Used by the okstra-run skill to drive the per-step prompt loop. Each
+subcommand round-trips a JSON state file held by the skill.
+
+Subcommands:
+  init         seed a fresh wizard state and emit the first prompt
+  step         submit an answer (or fetch the current prompt) and emit next
+  render-args  emit the final --flag/value map for 'okstra render-bundle'
+  confirmation emit the multi-line confirmation echo block
+
+Usage:
+  okstra wizard init --state-file <path> --project-root <p> --project-id <id>
+  okstra wizard step --state-file <path> [--answer <value>]
+  okstra wizard render-args --state-file <path>
+  okstra wizard confirmation --state-file <path>
+
+'init' auto-fills --workspace-root from 'okstra paths --field workspace',
+so callers do not pass it.
+
+All subcommands emit a single JSON object on stdout. On validation failure
+'step' returns {ok:false, error, current} so the skill can re-prompt.
+`;
+
+function parseFlags(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (!a.startsWith("--")) {
+      throw new Error(`unexpected positional argument: ${a}`);
+    }
+    const key = a.slice(2);
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+      throw new Error(`flag --${key} requires a value`);
+    }
+    out[key] = next;
+    i += 1;
+  }
+  return out;
+}
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+
+  const [sub, ...rest] = args;
+  if (!["init", "step", "render-args", "confirmation"].includes(sub)) {
+    process.stderr.write(`error: unknown wizard subcommand '${sub}'\n\n${USAGE}`);
+    return 2;
+  }
+
+  let flags;
+  try {
+    flags = parseFlags(rest);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  if (!flags["state-file"]) {
+    process.stderr.write("error: --state-file is required\n");
+    return 2;
+  }
+
+  // build python argv
+  const pyArgs = [sub, "--state-file", flags["state-file"]];
+  if (sub === "init") {
+    if (!flags["project-root"] || !flags["project-id"]) {
+      process.stderr.write("error: init requires --project-root and --project-id\n");
+      return 2;
+    }
+    const paths = await resolvePaths();
+    pyArgs.push("--workspace-root", paths.workspace);
+    pyArgs.push("--project-root", flags["project-root"]);
+    pyArgs.push("--project-id", flags["project-id"]);
+  } else if (sub === "step" && flags.answer !== undefined) {
+    pyArgs.push("--answer", flags.answer);
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.wizard",
+    args: pyArgs,
+    stdio: "capture",
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    process.stdout.write(
+      JSON.stringify(
+        { ok: false, stage: "python", reason: result.stderr.trim() || "no output" },
+        null,
+        2,
+      ) + "\n",
+    );
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}