okstra 0.22.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,41 +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`.
 
-## Authority Files (disk-only — no env var caching for per-run identity)
+## How the wizard talks to you
 
-Every step reads disk afresh. The `OKSTRA_*` env vars below identify the
-**runtime installation** (stable across runs) — they are NOT per-task identity.
+Every wizard call returns JSON. The two shapes you'll see:
 
-- `~/.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`
+```json
+{ "ok": true, "echo": "task-group: backend-api",
+  "next": { "step": "task_id", "kind": "text", "label": "...", "options": [], "echoTemplate": "..." } }
+```
+
+```json
+{ "ok": false, "error": "approved plan has no APPROVED marker: ...",
+  "current": { "step": "approved_plan", "kind": "text", "label": "..." } }
+```
+
+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.
 
-## Step 0: Verify okstra runtime + project setup
+The wizard tells you *which UI to use* via `kind`:
 
-Do NOT hard-code or guess any okstra path. Every run loads them fresh from
-the single authority — `okstra`:
+- `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.
+
+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.
+
+## 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
@@ -62,243 +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 (`AskUserQuestion`, free text) for an absolute project-root path; rerun with `okstra check-project --cwd <their input>`.
-
-## 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.
+Output: the same `{ok, next}` JSON described above. The first `next` is always `step: "task_pick"`.
 
-`AskUserQuestion` (free text, one at a time):
+## Step 3: Run the prompt loop
 
-1. `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`
-2. `"Task id (e.g. login-error-analysis, dev-9043)"` → `task_id`
+Repeat until `next.kind == "done"`:
 
-Validate that slugified `task_group` and `task_id` each contain at least one alphanumeric character. Re-ask if not.
+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).
 
-## Step 4: Choose task-type
+That is the entire interactive flow. The wizard handles:
 
-`AskUserQuestion` with six fixed options:
+- 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.
 
-| 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 |
+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.
 
-For existing tasks, present `nextRecommendedPhase` as the first option (recommended default).
+## Step 4: Show the confirmation block before the final Proceed
 
-If `implementation` chosen, ask two more `AskUserQuestion` in order:
-- `"Path to the approved final-report.md (must contain APPROVED marker)"` — the underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`.
-- `"Executor provider for this run (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`.
-
-## Step 4.6: Base ref for the task worktree (first phase only)
-
-`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.
-
-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**.
-
-- `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.
+Output: `{ok: true, text: "선택 확인:\n  task-type     : ...\n  ..."}`. Print `text` to the user, then render the `confirm` picker (Proceed / Edit).
 
-`AskUserQuestion` (mirrors the `release-handoff` PR-base picker):
+## Step 5: Render the task bundle
 
-- **Label**: `"이 task worktree 의 base branch?"`
-- **Options** (single-select):
-  1. `main` (recommended)
-  2. `dev`
-  3. `staging`
-  4. `preprod`
-  5. `prod`
-  6. Free text — let the user type any local ref (branch, tag, or full/short SHA).
-
-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; }
-```
-
-Re-ask on failure. 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: `AskUserQuestion` (free text) `"Path to the task brief markdown (relative to project root)"`. Verify file exists; re-ask on failure.
-- Existing task: default to the manifest's `taskBriefPath`. Show it; ask whether to keep or change.
-
-## 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. `AskUserQuestion` `"추가 directive (선택, 빈 칸 가능)"` (free text) → `directive`
-5. `AskUserQuestion` `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` (free text) → `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 option lists above; others are free text). Skip any worker-model prompt whose worker is not in `profile_workers`.
-
-1. (only when `profile_workers` is non-empty) `AskUserQuestion` `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 <profile_workers_csv>). 선택지: <profile_workers_csv>"` (free text) → `workers_override`. Validate the answer is a subset of `profile_workers`; re-ask on failure. (Backend will also reject 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"`) `AskUserQuestion` `"PR 본문 템플릿 경로 1회성 override (빈 칸 = project.json → ~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)"` (free text) → `pr_template_path`. The backend (`okstra_ctl.pr_template.resolve_pr_template_path`) validates the file exists and surfaces `PrTemplateError` on failure. If the user wants to persist the choice instead of a one-shot override, tell them to set `prTemplatePath` in `<project_root>/.project-docs/okstra/project.json` (project scope) or `~/.okstra/config.json` (global scope).
-
-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`.
 
-## Step 8: Take over as Claude lead
+You can delete `$STATE_FILE` after this point — its job is done.
+
+## Step 6: Take over as Claude lead
 
 Read these files (do not paraphrase) and enter `Claude lead` mode:
 
@@ -313,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-setup/SKILL.md

@@ -209,6 +209,43 @@ To opt out (advanced): replace the symlink with a regular file. okstra
 will detect that it is no longer a symlink on its next setup call and
 back it up as `.bak.<timestamp>` rather than overwriting silently.
 
+## Step 4.8 (optional): register a project PR body template
+
+`release-handoff` fills the PR body from a template. By default it uses the
+bundled skill template at
+`~/.claude/skills/okstra-run/templates/pr-body.template.md`. Most projects
+want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
+keep PRs consistent with what the team already merges manually.
+
+Ask the user with `AskUserQuestion` (fixed options, NOT free text — file
+path entry happens in the follow-up plain text prompt per the
+okstra-run prompt convention):
+
+- **Question**: `"이 프로젝트에서 release-handoff 가 사용할 PR 본문 템플릿을 등록할까요?"`
+- **Options**:
+  1. `이번 프로젝트만 (project scope)` — write to `<PROJECT_ROOT>/.project-docs/okstra/project.json` `prTemplatePath`.
+  2. `전역 (global scope)` — write to `~/.okstra/config.json` `prTemplatePath`.
+  3. `나중에` — skip.
+
+If the user picks scope 1 or 2, follow up with a **plain text prompt**:
+`"PR 본문 템플릿 파일 경로를 알려주세요. project 스코프는 project-root 기준 상대경로 또는 절대경로, global 스코프는 절대경로 또는 ~/ 시작 경로만 허용됩니다."` Consume the next user message, then run:
+
+```bash
+okstra config set pr-template-path "<typed-path>" --scope <project|global>
+```
+
+The command validates the value (global rejects relative paths) and
+writes atomically. Surface its stdout JSON so the user sees which file
+was updated.
+
+If the user chose `나중에`, tell them they can register later with one of:
+
+- `okstra config set pr-template-path <path> --scope project|global` from a
+  terminal, or
+- the per-run 1회성 override prompt during the next release-handoff run
+  (the run can also persist that override to project/global scope on the
+  spot — see the okstra-run skill).
+
 ## Step 5: Verify
 
 ```bash

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

@@ -202,7 +202,52 @@ Terminal statuses that can be recorded for a worker:
 
 **Authoritative source.** If other documents (SKILL.md, worker agent definitions) disagree with this section, this section wins.
 
-A successful worker result must include the following sections in this exact order:
+### Result Frontmatter (mandatory, precedes Section 0)
+
+Every worker result file MUST begin with a YAML frontmatter block. The values are sourced from the corresponding fields of the input files' frontmatter (e.g. `analysis-material.md`, `task-brief.md`) — copy them verbatim; do NOT regenerate them. Only `workerId` and `title` are worker-specific.
+
+```yaml
+---
+title: OKSTRA <Worker Role> Result - <task-key>
+id: "<task-key with ':' replaced by '-'>"
+aliases: ["<id>-<task-type>"]
+tags: ["obsidian", "okstra", "worker-result", "<task-type>"]
+taskType: "<task-type>"
+workerId: "<claude|codex|gemini|report-writer>"
+task-id: "<task-id>"
+task-group: "<task-group>"
+project-id: "<project-id>"
+date: <YYYY-MM-DD>
+---
+```
+
+Concrete example for a `claude-worker` result on task-key `fontsninja-classifier-v2:DEV-9388:DEV-9429` and task-type `implementation`:
+
+```yaml
+---
+title: OKSTRA Claude Worker Result - fontsninja-classifier-v2:DEV-9388:DEV-9429
+id: "fontsninja-classifier-v2-DEV-9388-DEV-9429"
+aliases: ["fontsninja-classifier-v2-DEV-9388-DEV-9429-implementation"]
+tags: ["obsidian", "okstra", "worker-result", "implementation"]
+taskType: "implementation"
+workerId: "claude"
+task-id: "DEV-9429"
+task-group: "DEV-9388"
+project-id: "fontsninja-classifier-v2"
+date: 2026-05-15
+---
+```
+
+Rules:
+- `id` is the run's `task-key` with `:` replaced by `-`. It is a scalar string, NOT an array.
+- `aliases` is a YAML array containing a single value `"<id>-<task-type>"`.
+- `taskType` mirrors the run's task type (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`).
+- `workerId` identifies which worker produced the file. Required values: `claude` / `codex` / `gemini` / `report-writer`.
+- Other fields (`task-id`, `task-group`, `project-id`, `date`) MUST match the input files' frontmatter exactly. If the input frontmatter is missing or unreadable, the worker MUST record a `tool-failure` and stop instead of guessing.
+
+The same frontmatter contract applies to the `Report writer worker`'s final-report file — the report-writer copies these values from its inputs and only swaps `workerId` to `report-writer`.
+
+A successful worker result must include the following sections in this exact order, beneath the frontmatter block:
 
 0. **Reading Confirmation** — one short line per input file (`task-brief.md`, `analysis-profile.md`, `analysis-material.md` if present, `reference-expectations.md`, `clarification-response.md` if a carry-in was provided, `final-report-template.md`) stating that the worker read it end-to-end. Each line takes the form `- Read <file-name> end-to-end (<line-count> lines).`. If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5; instead it records a `tool-failure` in the errors sidecar and stops. This section exists specifically to counteract the common failure mode where workers skim long inputs because they share structure with the file the run will eventually write into.
 1. Findings
@@ -441,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/runtime/templates/prd/brief.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Task Brief

package/runtime/templates/project-docs/task-index.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Task Summary

package/runtime/templates/reports/error-analysis-input.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # OKSTRA Error Analysis Input

package/runtime/templates/reports/final-report.template.md

@@ -8,6 +8,7 @@ date: {{TASK_DATE}}
 task-id: "{{TASK_ID}}"
 task-group: "{{TASK_GROUP}}"
 project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
 ---
 
 # {{TASK_KEY}} - Multi-Agent Cross Verification Final Report