okstra 0.68.0 → 0.70.0

package/bin/okstra

@@ -41,6 +41,19 @@ const COMMANDS = new Map([
     () => import("../src/render-bundle.mjs").then((m) => m.run),
   ],
   ["render-views", () => import("../src/render-views.mjs").then((m) => m.run)],
+  [
+    "render-final-report",
+    () => import("../src/render-final-report.mjs").then((m) => m.run),
+  ],
+  [
+    "inject-report-index",
+    () => import("../src/inject-report-index.mjs").then((m) => m.run),
+  ],
+  [
+    "spawn-followups",
+    () => import("../src/spawn-followups.mjs").then((m) => m.run),
+  ],
+  ["error-log", () => import("../src/error-log.mjs").then((m) => m.run)],
   ["wizard", () => import("../src/wizard.mjs").then((m) => m.run)],
   ["token-usage", () => import("../src/token-usage.mjs").then((m) => m.run)],
   ["memory", () => import("../src/memory.mjs").then((m) => m.run)],
@@ -89,6 +102,11 @@ Introspection commands (JSON output, used by skills to avoid python heredocs):
   token-usage            Collect token usage for a run (wraps the installed
                          okstra-token-usage.py so skills avoid emitting
                          python3 "$HOME/..." invocations).
+  render-views           Render slim AI + self-contained HTML views of a final report
+  render-final-report    Render the markdown sibling of a final-report data.json
+  inject-report-index    Add the top-of-report Index + scroll anchors to a report
+  spawn-followups        Create follow-up task bundles from a final report
+  error-log              Append run error events to the run error log
   memory                 Store and find user-home conversation memory under
                          ~/.okstra/memory-book.
 

package/docs/kr/architecture.md

@@ -353,6 +353,7 @@ okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결
 - `implementation`을 제외한 모든 phase는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다(`final-verification`은 read-only 테스트 명령만 허용). `implementation`은 승인된 plan의 파일 목록 안에서만 edit/commit이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API는 여전히 금지됩니다.
 - **모든 task-type 격리 worktree (BLOCKING)**: 모든 task-type 의 첫 번째 phase prepare 단계에서 `okstra-ctl` 이 자동으로 task-key 단위 `git worktree` 를 생성하고, 같은 task-key 의 이후 phase (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) 는 동일한 worktree·브랜치를 재사용합니다. 위치는 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (segment 의 `/`·`:` 등 특수문자는 `-` 로 정규화) 이고, 브랜치 이름은 `<work-category-prefix>-<task-id-segment>` (예: `feat-dev-9436`, `fix-dev-7311`) 입니다. base ref 는 첫 phase prepare 시점의 main worktree `HEAD`. `~/.okstra/worktrees/registry.json` (flock-guarded) 가 task-key → path/branch 매핑을 전역 관리해 동시 실행 시 path·branch 충돌을 방지합니다. configured sync dirs 는 main worktree 에서 symlink 로 연결되어 task checkout 사이의 filesystem continuity 를 제공합니다 (sync 대상 목록은 `project.json` 의 `worktreeSyncDirs` 또는 `OKSTRA_WORKTREE_SYNC_DIRS` 환경변수로 override 가능; 빈 배열이면 sync 비활성화). 이 sync 는 okstra context/write boundary 를 확장하지 않습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 executor 는 project_root 에서 그대로 작업합니다. worktree 는 run 종료 후 자동 삭제되지 않으며 후속 phase·PR 작성·rollback 검증의 권위 artefact 입니다. 수동 cleanup: `git -C <main-worktree> worktree remove <path>` → `git -C <main-worktree> branch -D <branch>` + registry 항목 삭제. 자세한 동작은 `prompts/profiles/implementation.md` 의 *Task worktree* 블록과 `agents/SKILL.md` 의 *Task worktree (BLOCKING for every task-type)* 섹션 참고.
 - **implementation stage 격리 worktree (동시 병렬)**: 위 task-key 단위 worktree 는 `requirements-discovery`~`implementation-planning` 의 모델입니다. `implementation` task 는 **stage 격리** 로 동작합니다 (spec `docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md`) — **한 run = 한 stage**, 각 run 이 `.../<task-id-segment>/stage-<N>/` (브랜치 `<prefix>-<task-id-segment>-s<N>`) 격리 worktree 를 발급받습니다. registry 가 task-key 와 **stage-key** (`<task-key>#stage-<N>`) 를 함께 flock 예약하고, `_resolve_effective_stages` 가 `consumers.jsonl` 의 `started` + registry 예약 stage 를 ready 집합에서 제외하므로(점유 SSOT = registry), 사용자가 두 `implementation` run 을 동시에 띄우면 서로 다른 독립 stage 를 충돌 없이 진행합니다. base 결정: 독립 = 공통 anchor(첫 stage 진입 HEAD 고정), 단일 의존 = 선행 done commit, 다중 의존 = 선행이 모두 ancestor 인 task worktree HEAD(`git merge-base --is-ancestor`; 미머지 시 `PrepareError`). cost-aware-design 의 ready-set batch 는 stage 마다 격리 branch 가 필요해 의미를 잃으므로(같은 branch 에 두 stage-key reserve 시 branch-uniqueness 충돌) 폐기되었고, 순차 진행은 stage done 후 다음 run, 동시 진행은 별도 run 으로 — cost 등가. `--stage <auto|N>` 또는 wizard `stage_pick` 으로 stage 를 선택합니다. worktree 뿐 아니라 **run 산출물(report·state·worker-results·manifest)도 `runs/implementation/stage-<N>/` 로 stage 별 격리**되므로 동시 실행하는 두 stage 의 보고서·상태가 섞이지 않습니다. 반면 `consumers.jsonl` 과 worktree registry 는 stage 간 공유되는 조율 SSOT 라 task-type 루트(`runs/implementation/`)에 그대로 둡니다.
+- **단일-stage final-verification 의 run 산출물 격리 (동시 병렬)**: 단독-stage `final-verification`(`--stage <N>`)도 implementation 과 동일하게 run 산출물을 `runs/final-verification/stage-<N>/` 하위에 격리하고(seq 도 stage 별 독립), 팀 이름에 `-fv-s<N>` 접미사를 붙입니다 — `-fv-` 구분자로 같은 stage 의 implementation 팀(`-s<N>`)과도, 전체-task 검증의 기본 이름과도 충돌하지 않습니다. 따라서 여러 stage 의 final-verification 을 동시에 띄워도 state·worker-results·보고서·팀이 섞이지 않습니다. worktree 는 새로 만들지 않고 해당 implementation stage worktree 를 registry 에서 read-only 로 재사용하며, 그래서 registry stage-key 예약도 하지 않습니다 — **같은 stage 의 final-verification 을 동시에 두 번** 띄우는 경우는 격리되지 않고 `TeamCreate` 이름 충돌로 즉시 실패합니다(알려진 제약). 전체-task 검증(stage 빈 값)은 기존 평면 `runs/final-verification/` 구조를 유지합니다.
 - `implementation` 과 `release-handoff` 를 제외한 모든 phase 는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다 (`final-verification` 은 read-only 테스트 명령만 허용). `implementation` 은 승인된 plan 의 파일 목록 안에서만 edit/commit 이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API 는 여전히 금지됩니다. `release-handoff` 는 source code 자체는 수정하지 않고, 사용자가 메뉴로 선택한 commit / push / PR 명령만 실행합니다 (force push, base 브랜치 직접 push, hook bypass, release publish 는 여전히 금지).
 - 사용자가 "다음 단계 진행해" 같은 표현을 보내도, 그 발화만으로 다음 phase가 자동 시작되지 않습니다. 다음 phase는 새 `okstra.sh` 실행으로만 시작합니다.
 - **Authority & permissions assumption (모든 task-type 및 `okstra-schedule` 공통)**: 사용자(및 팀)는 예상되는 모든 작업에 대해 완전한 권한·승인 권한을 보유한다고 가정합니다. 외부 승인, 서드파티 액세스, 역할/IAM 권한, 조직적 sign-off, 법무·보안 검토, 벤더 협의, "권한 보유 여부 확인" 같은 항목을 routing 결정·missing inputs·clarification questions·risk·dependency·open questions·effort/day 추정에 포함하지 않습니다. okstra 내부 phase 핸드오프(`implementation-planning`의 `approved:` frontmatter 등)는 사용자 본인이 즉시 승인 가능한 내부 게이트이므로 영향 없으며, `implementation`의 forbidden actions(`git push`, prod deploy, shared-DB migration 등)도 권한 사유가 아닌 **안전 사유**로 계속 적용됩니다.

package/docs/kr/cli.md

@@ -355,6 +355,7 @@ fallback 기본값은 아래와 같습니다.
 - **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 / gemini 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-prefix>-<task-id-segment>` 를 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-prefix>-<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/` 를 유지합니다.
 
 예:
 
@@ -592,7 +593,7 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra task-show <task-key> [--project-root <path>]` | task-manifest.json 의 workflow / phase / status 요약 |
 | `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>]` | `prepare_task_bundle(render_only=True)` 의 thin shim — `python3 -m okstra_ctl.run --render-only` 와 동일 시그니처. `--stage` 는 `implementation` task 전용: 실행할 Stage Map 항목 지정. `auto` (기본값) = 의존성이 만족된 가장 빠른 미완료 stage, `<N>` = 강제 지정 |
+| `okstra render-bundle <args…> [--stage <auto\|N>]` | `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 검증(평면 구조 유지) |
 | `okstra render-views <final-report.md>` | Phase 7 step 1.5 — 토큰 치환된 final-report MD 한 본을 입력으로 sibling `*.slim.md` (AI 입력용) + `*.html` (사람용 self-contained) 두 view 를 결정론적으로 생성. 원본 MD 는 수정하지 않음. Node 위임 wrapper는 `scripts/okstra-render-report-views.py` 를 호출. `validators/validate-report-views.py` 가 substring 보존 / form-control 위치 / Response ID parity 를 검사 |
 | `okstra wizard <init\|step\|render-args\|confirmation> --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 블록을 반환. `implementation` task type 에서는 `approved_plan_pick` 직후 `stage_pick` 단계가 추가되어 실행할 stage 를 선택하고, `executor_pick` 으로 넘어갑니다 |
 | `okstra token-usage ...` | 설치된 `okstra-token-usage.py` 를 감싸 run token usage 수집/치환을 수행. 세션 jsonl 은 기본적으로 `$OKSTRA_HOME/cache/token-usage/` 의 byte cursor 캐시로 증분 스캔하며, `--no-cache` 로 캐시를 우회해 전체 재스캔을 강제할 수 있음(정확성 폴백) |

package/docs/superpowers/plans/2026-06-11-wizard-whole-task-final-verification.md

@@ -0,0 +1,526 @@
+# wizard whole-task final-verification 노출 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** okstra-run 위저드의 final-verification stage picker 에서 "전체 task 검증" 을 명시 항목으로 선택할 수 있게 한다(prepare 계약 무변경, `auto` 토큰 미사용).
+
+**Architecture:** 위저드 레이어만 수정한다. picker 가 `consumers.jsonl` 의 done 행을 읽어 stage 별 done 마킹을 붙이고, 전 stage done 일 때만 "전체 task" 항목(내부 sentinel `__whole_task__`)을 노출한다. `render_args` 가 sentinel 을 빈 stage(`""`)로 변환해 prepare 의 기존 whole-task 경로를 탄다. 머지/clean/active 전제는 prepare 의 PrepareError 게이트에 위임한다.
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/wizard.py`), JSON 프롬프트(`prompts/wizard/prompts.ko.json`), pytest.
+
+**Spec:** [2026-06-11-wizard-whole-task-final-verification-design.md](../specs/2026-06-11-wizard-whole-task-final-verification-design.md)
+
+---
+
+## File Structure
+
+- `scripts/okstra_ctl/wizard.py` — sentinel 상수, done/Stage-Map 헬퍼, picker·submit·render_args·confirmation 수정.
+- `prompts/wizard/prompts.ko.json` — `steps.stage_pick.options` 에 whole-task·done 마킹 라벨 추가.
+- `tests/test_wizard_stage_pick.py` — picker·submit·render_args 회귀 + 신규 케이스.
+- `tests/test_wizard_whole_task_fv.py` — done 헬퍼 + whole-task 노출 게이트 신규 테스트.
+
+기존 단독-stage UX(`54b9482`)·prepare·CLI 계약은 건드리지 않는다.
+
+---
+
+## Task 1: sentinel 상수 + done/Stage-Map 헬퍼
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py` (토큰 블록 1354-1360 근처, 헬퍼는 `_stage_auto_allowed` 1778 부근)
+- Test: `tests/test_wizard_whole_task_fv.py` (create)
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`tests/test_wizard_whole_task_fv.py`:
+
+```python
+import importlib
+import json
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+
+
+def _load_wizard():
+    if "okstra_ctl.wizard" in sys.modules:
+        return sys.modules["okstra_ctl.wizard"]
+    if str(REPO / "scripts") not in sys.path:
+        sys.path.insert(0, str(REPO / "scripts"))
+    return importlib.import_module("okstra_ctl.wizard")
+
+
+def _plan_run(tmp_path: Path, done_stages: list[int]) -> Path:
+    """plan_run_root/reports/plan.md + plan_run_root/consumers.jsonl 를 만들고
+    approved plan 경로를 돌려준다. plan_run_root == plan.resolve().parents[1]."""
+    run = tmp_path / "run"
+    (run / "reports").mkdir(parents=True)
+    plan = run / "reports" / "plan.md"
+    fixture = (REPO / "tests" / "fixtures" / "plans"
+               / "valid_three_stage_parallel.md").read_text(encoding="utf-8")
+    plan.write_text(fixture + "\n- [x] Approved\n", encoding="utf-8")
+    rows = [json.dumps({"status": "done", "stage": n,
+                        "impl_task_key": "k", "head_commit": f"sha{n}"})
+            for n in done_stages]
+    (run / "consumers.jsonl").write_text(
+        ("\n".join(rows) + "\n") if rows else "", encoding="utf-8")
+    return plan
+
+
+def test_done_stage_numbers_reads_consumers(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 3])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification",
+        approved_plan_path=str(plan))
+    assert wizard._done_stage_numbers(state) == {1, 3}
+
+
+def test_whole_task_allowed_true_when_all_done(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 2, 3])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification",
+        approved_plan_path=str(plan))
+    assert wizard._whole_task_allowed(state) is True
+
+
+def test_whole_task_allowed_false_when_partial(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 2])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification",
+        approved_plan_path=str(plan))
+    assert wizard._whole_task_allowed(state) is False
+
+
+def test_whole_task_allowed_false_for_implementation(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 2, 3])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="implementation",
+        approved_plan_path=str(plan))
+    assert wizard._whole_task_allowed(state) is False
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -v`
+Expected: FAIL — `AttributeError: module ... has no attribute '_done_stage_numbers'`
+
+- [ ] **Step 3: 최소 구현**
+
+`scripts/okstra_ctl/wizard.py` 의 토큰 블록(`_REUSE_LAST_TOKEN = "__reuse_last__"` 등이 있는 1354-1360 근처)에 sentinel 추가:
+
+```python
+WHOLE_TASK_STAGE = "__whole_task__"
+```
+
+`_stage_auto_allowed` 정의(1778 근처) 바로 아래에 헬퍼 3개 추가:
+
+```python
+def _parse_stage_objects(state: WizardState) -> list:
+    """승인 plan 의 Stage Map stage 객체 목록. validator 의 _parse_stage_map 재사용.
+    `_build_stage_pick` 과 `_whole_task_allowed` 가 공유한다."""
+    import importlib.util as _ilu
+    import sys as _sys
+    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
+    validator_path = (Path(state.workspace_root) / "validators"
+                      / "validate-implementation-plan-stages.py")
+    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
+    if spec is None or spec.loader is None:
+        raise WizardError(f"cannot load stage validator at {validator_path}")
+    mod = _ilu.module_from_spec(spec)
+    _sys.modules["_ip_stage_v_wizard"] = mod
+    try:
+        spec.loader.exec_module(mod)
+        stages, _errs = mod._parse_stage_map(plan_text)
+    finally:
+        _sys.modules.pop("_ip_stage_v_wizard", None)
+    return stages
+
+
+def _done_stage_numbers(state: WizardState) -> set:
+    """approved plan 을 소비한 implementation run 들의 consumers.jsonl 에서
+    done 처리된 stage 번호 집합. git 호출 없음 — 파일 읽기만(prepare 와 동일 SSOT)."""
+    if not state.approved_plan_path:
+        return set()
+    from .consumers import (read_consumers, backfill_done_from_carry,
+                            latest_done_by_stage)
+    plan_run_root = Path(state.approved_plan_path).resolve().parents[1]
+    backfill_done_from_carry(plan_run_root)
+    rows = read_consumers(plan_run_root)
+    return set(latest_done_by_stage(rows).keys())
+
+
+def _whole_task_allowed(state: WizardState) -> bool:
+    """final-verification 이고 Stage Map 의 모든 stage 가 done 일 때만 True.
+    위저드는 done 만 본다 — 머지/clean/active 는 prepare 게이트가 강제한다."""
+    if state.task_type != "final-verification":
+        return False
+    if not state.approved_plan_path:
+        return False
+    stages = _parse_stage_objects(state)
+    if not stages:
+        return False
+    done = _done_stage_numbers(state)
+    return all(s.stage_number in done for s in stages)
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -v`
+Expected: 4 PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_whole_task_fv.py
+git commit -m "feat(wizard): final-verification done/whole-task 헬퍼 추가"
+```
+
+---
+
+## Task 2: stage picker 에 done 마킹 + 전체 task 항목
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:1494-1533` (`_build_stage_pick`)
+- Modify: `prompts/wizard/prompts.ko.json` (`steps.stage_pick.options`)
+- Test: `tests/test_wizard_whole_task_fv.py`
+
+- [ ] **Step 1: 실패 테스트 추가**
+
+`tests/test_wizard_whole_task_fv.py` 끝에 추가(`_plan_run` 헬퍼 재사용):
+
+```python
+def test_picker_shows_whole_task_when_all_done(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 2, 3])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification",
+        approved_plan_path=str(plan))
+    prompt = wizard._build_stage_pick(state)
+    values = [o.value for o in prompt.options]
+    assert wizard.WHOLE_TASK_STAGE in values
+    assert "auto" not in values
+    assert values == [wizard.WHOLE_TASK_STAGE, "1", "2", "3"]
+
+
+def test_picker_hides_whole_task_when_partial(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 2])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification",
+        approved_plan_path=str(plan))
+    prompt = wizard._build_stage_pick(state)
+    values = [o.value for o in prompt.options]
+    assert wizard.WHOLE_TASK_STAGE not in values
+    # stage 3 미완 마킹이 라벨에 보인다
+    label_3 = next(o.label for o in prompt.options if o.value == "3")
+    assert "미완" in label_3
+    label_1 = next(o.label for o in prompt.options if o.value == "1")
+    assert "done" in label_1
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -k picker -v`
+Expected: FAIL — whole-task 항목이 없고 done 마킹이 없음
+
+- [ ] **Step 3: 구현**
+
+`prompts/wizard/prompts.ko.json` 의 `steps.stage_pick.options` 를 다음으로 교체:
+
+```json
+    "options": {
+      "auto": "auto (다음 미완료 stage)",
+      "whole_task": "전체 task 검증 (모든 stage)",
+      "done_mark": "[done]",
+      "undone_mark": "[미완]"
+    }
+```
+
+`scripts/okstra_ctl/wizard.py` 의 `_build_stage_pick` 본문을 교체(파싱은 `_parse_stage_objects` 로 위임):
+
+```python
+def _build_stage_pick(state: WizardState) -> Prompt:
+    """Parse the Stage Map from the approved plan and build the stage picker."""
+    t = _p(state.workspace_root, "stage_pick")
+    stages = _parse_stage_objects(state)
+    is_fv = state.task_type == "final-verification"
+    label = (
+        t.get("label_final_verification", t["label"])
+        if is_fv else t["label"]
+    )
+    done = _done_stage_numbers(state) if is_fv else set()
+    options = []
+    if _stage_auto_allowed(state):
+        options.append(_opt("auto", t["options"]["auto"]))
+    if is_fv and stages and all(s.stage_number in done for s in stages):
+        options.append(_opt(
+            WHOLE_TASK_STAGE,
+            t["options"].get("whole_task", "전체 task 검증 (모든 stage)"),
+        ))
+    for s in stages:
+        depends = ",".join(map(str, s.depends_on)) or "(none)"
+        suffix = ""
+        if is_fv:
+            mark = (t["options"].get("done_mark", "[done]")
+                    if s.stage_number in done
+                    else t["options"].get("undone_mark", "[미완]"))
+            suffix = f"  {mark}"
+        options.append(_opt(
+            str(s.stage_number),
+            f"{s.stage_number}: {s.title}  "
+            f"[depends-on: {depends} | steps: {s.step_count}]{suffix}",
+        ))
+    return Prompt(
+        step=S_STAGE_PICK, kind="pick",
+        label=label,
+        options=options,
+        echo_template=t["echo_template"],
+    )
+```
+
+- [ ] **Step 4: 테스트 통과 + 기존 picker 회귀 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py -v`
+Expected: 신규 picker 2 PASS + `test_final_verification_stage_pick_excludes_auto`(이제 stage 별 라벨에 `[미완]` 가 붙지만 value 는 `["1","2","3"]` 유지) 포함 기존 전부 PASS
+
+> 주의: `test_final_verification_stage_pick_excludes_auto` 는 done 행이 없는 plan 을 쓰므로 whole-task 항목이 안 뜨고 `values == ["1","2","3"]` 가 유지된다. 라벨 문자열은 검사하지 않으므로 마킹 추가와 무관하다.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py prompts/wizard/prompts.ko.json tests/test_wizard_whole_task_fv.py
+git commit -m "feat(wizard): final-verification picker 에 done 마킹 + 전체 task 항목"
+```
+
+---
+
+## Task 3: submit 이 전체 task sentinel 수용
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:1536-1552` (`_submit_stage_pick`)
+- Test: `tests/test_wizard_whole_task_fv.py`
+
+- [ ] **Step 1: 실패 테스트 추가**
+
+```python
+def test_submit_accepts_whole_task_for_fv(tmp_path):
+    wizard = _load_wizard()
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification")
+    result = wizard._submit_stage_pick(state, wizard.WHOLE_TASK_STAGE)
+    assert state.selected_stage == wizard.WHOLE_TASK_STAGE
+    assert result == f"stage: {wizard.WHOLE_TASK_STAGE}"
+
+
+def test_submit_rejects_whole_task_for_implementation(tmp_path):
+    wizard = _load_wizard()
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="implementation")
+    try:
+        wizard._submit_stage_pick(state, wizard.WHOLE_TASK_STAGE)
+        assert False, "expected WizardError"
+    except wizard.WizardError as exc:
+        assert "final-verification" in str(exc)
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -k submit -v`
+Expected: FAIL — sentinel 이 `int()` 분기로 빠져 "stage number" 에러
+
+- [ ] **Step 3: 구현**
+
+`_submit_stage_pick` 을 교체:
+
+```python
+def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
+    if not answer:
+        raise WizardError("value required")
+    if answer == "auto":
+        if not _stage_auto_allowed(state):
+            raise WizardError(
+                "final-verification requires an explicit stage number"
+            )
+    elif answer == WHOLE_TASK_STAGE:
+        if state.task_type != "final-verification":
+            raise WizardError(
+                "whole-task verification is only valid for final-verification"
+            )
+    else:
+        try:
+            int(answer)
+        except ValueError:
+            raise WizardError(
+                f"answer must be 'auto', whole-task, or a stage number, "
+                f"got {answer!r}"
+            )
+    state.selected_stage = answer
+    return f"stage: {answer}"
+```
+
+- [ ] **Step 4: 테스트 통과 + 기존 submit 회귀 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py -k submit -v`
+Expected: 신규 2 + 기존 submit 케이스 전부 PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_whole_task_fv.py
+git commit -m "feat(wizard): _submit_stage_pick 이 전체 task sentinel 수용"
+```
+
+---
+
+## Task 4: render_args 빈 stage 변환 + confirmation 라벨
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:2792-2806` (`render_args` stage 결정부)
+- Modify: `scripts/okstra_ctl/wizard.py:2872-2878` (`confirmation_block` stage 표기부)
+- Test: `tests/test_wizard_whole_task_fv.py`
+
+- [ ] **Step 1: 실패 테스트 추가**
+
+```python
+def test_render_args_whole_task_emits_empty_stage(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 2, 3])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification",
+        approved_plan_path=str(plan),
+        selected_stage=wizard.WHOLE_TASK_STAGE)
+    args = wizard.render_args(state)
+    assert args["stage"] == ""
+    assert args["base-ref"] == ""  # final-verification 은 base 자동 해소
+
+
+def test_render_args_single_stage_fv_keeps_number(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [2])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_type="final-verification",
+        approved_plan_path=str(plan), selected_stage="2")
+    args = wizard.render_args(state)
+    assert args["stage"] == "2"
+
+
+def test_confirmation_block_labels_whole_task(tmp_path):
+    wizard = _load_wizard()
+    plan = _plan_run(tmp_path, [1, 2, 3])
+    state = wizard.WizardState(
+        workspace_root=str(REPO), project_root=str(tmp_path),
+        project_id="demo", task_group="g", task_id="t",
+        task_type="final-verification", approved_plan_path=str(plan),
+        selected_stage=wizard.WHOLE_TASK_STAGE)
+    block = wizard.confirmation_block(state)
+    assert "전체 task" in block
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py -k "render_args or confirmation" -v`
+Expected: FAIL — sentinel 이 그대로 stage 로 새거나 `WizardError`("requires an explicit stage number")
+
+- [ ] **Step 3: 구현**
+
+`render_args` 의 stage 결정 블록(현재 `elif state.task_type == "final-verification":` 분기, 2799-2804)을 교체:
+
+```python
+    if state.task_type == "implementation":
+        stage = state.selected_stage or "auto"
+    elif state.task_type == "final-verification":
+        if state.selected_stage == WHOLE_TASK_STAGE:
+            stage = ""  # prepare 가 빈 stage 를 whole-task 로 해석
+        elif not state.selected_stage or state.selected_stage == "auto":
+            raise WizardError(
+                "final-verification requires an explicit stage number"
+            )
+        else:
+            stage = state.selected_stage
+    else:
+        stage = ""
+```
+
+`confirmation_block` 의 stage 표기 블록(2874-2878)을 교체:
+
+```python
+        stage = (
+            "전체 task"
+            if state.selected_stage == WHOLE_TASK_STAGE
+            else (state.selected_stage
+                  or ("auto" if state.task_type == "implementation"
+                      else "(not selected)"))
+        )
+```
+
+- [ ] **Step 4: 테스트 통과 + render_args 회귀 확인**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py -k "render_args or confirmation" -v`
+Expected: 신규 3 + 기존 render_args 케이스(`test_render_args_includes_stage_for_implementation` 등) 전부 PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_whole_task_fv.py
+git commit -m "feat(wizard): render_args 가 전체 task sentinel 을 빈 stage 로 변환"
+```
+
+---
+
+## Task 5: 통합 검증 + CHANGES 기록
+
+**Files:**
+- Modify: `CHANGES.md`
+- Test: 전체 위저드 스위트
+
+- [ ] **Step 1: 전체 위저드 테스트**
+
+Run: `python3 -m pytest tests/test_wizard_whole_task_fv.py tests/test_wizard_stage_pick.py tests/test_wizard_final_verification_stage.py tests/test_okstra_ctl_wizard.py -v`
+Expected: 전부 PASS (whole-task 경로에서도 base-ref/branch-confirm 생략이 유지되는지 `test_okstra_ctl_wizard.py` 가 커버)
+
+- [ ] **Step 2: build 후 runtime sync 확인**
+
+Run: `npm run build && node bin/okstra --version`
+Expected: 빌드 성공, 버전 출력. `runtime/` 에 prompts.ko.json·wizard.py 변경분이 반영됨(직접 편집 금지, 빌드로만).
+
+- [ ] **Step 3: CHANGES.md 항목 추가**
+
+`CHANGES.md` 의 최상단 날짜 섹션(`## 2026-06-11`, 없으면 생성)에 추가:
+
+```markdown
+### feat(wizard): final-verification 위저드에서 전체 task 검증 선택 지원
+
+- **배경**: `54b9482` 이후 okstra-run 위저드의 `final-verification` 은 명시 stage 만 선택 가능해, 모든 stage 를 머지한 뒤 한 번 도는 전체-task 검증을 CLI `--stage auto` 로만 할 수 있었다.
+- **해결**: stage picker 에 stage 별 done 마킹을 표시하고, 모든 stage 가 done 이면 "전체 task 검증" 항목을 노출한다. 선택 시 prepare 에 빈 stage 를 넘겨 기존 전체-task 경로를 탄다(`auto` 토큰 미사용, prepare 계약 무변경). 머지/clean 미충족은 prepare 의 기존 PrepareError 가 안내한다.
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후, 모든 stage 가 done 이면 위저드에서 "전체 task 검증" 을 골라 task 전체를 한 번에 검증할 수 있다.
+```
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add CHANGES.md runtime/
+git commit -m "docs(changes): wizard 전체 task final-verification 지원 기록 + runtime 빌드"
+```
+
+---
+
+## Self-Review 결과
+
+- **Spec coverage**: §3 노출(Task 2) · §4 done 데이터원(Task 1) · §5 빈 stage emit(Task 4) · §6 게이트 함수(Task 2~4) · §7 프롬프트(Task 2) · §8 테스트(Task 1~5) — 전부 매핑됨.
+- **Placeholder**: 모든 코드 스텝에 실제 본문 포함, TODO 없음.
+- **Type/이름 일관성**: `WHOLE_TASK_STAGE` sentinel 이 Task 1 정의 → 2·3·4 에서 동일 이름 사용. `_parse_stage_objects`/`_done_stage_numbers`/`_whole_task_allowed` 시그니처 일관.
+- **회귀**: 각 Task Step 4 가 기존 `test_wizard_stage_pick.py` 를 함께 돌려 단독-stage UX 불변을 확인.