okstra 0.69.0 → 0.70.0

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 불변을 확인.

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

@@ -0,0 +1,89 @@
+# wizard whole-task final-verification 노출 설계
+
+- 작성일: 2026-06-11
+- 상태: 설계 승인됨 (사용자 승인 2026-06-11)
+- 선행: [final-verification-whole-task-gate-design.md](2026-06-06-final-verification-whole-task-gate-design.md), 커밋 `54b9482` (stage worktree 기반 검증으로 위저드 단순화)
+
+## 1. 배경 / 문제
+
+`final-verification` 은 두 검증 모드를 가진다 — (A) 전체-task 모드(모든 stage 머지 후 한 번), (B) 단독-stage 모드(격리 worktree에서 그 stage만). 이 두 모드와 자동 target 해소는 prepare 레이어에 이미 구현돼 있다([final-verification-whole-task-gate-design.md](2026-06-06-final-verification-whole-task-gate-design.md)).
+
+커밋 `54b9482` 은 단독-stage 위저드 UX를 단순화하면서(`base-ref`/branch-confirm 생략, 명시 stage 강제) **위저드에서 전체-task 모드를 선택할 길을 막았다**:
+
+- [`_stage_auto_allowed`](../../../scripts/okstra_ctl/wizard.py:778) 가 `implementation` 에서만 `True` → final-verification stage picker 에 전체 옵션이 뜨지 않는다.
+- [`_submit_stage_pick`](../../../scripts/okstra_ctl/wizard.py:1539) 와 [`render_args`](../../../scripts/okstra_ctl/wizard.py:2799) 가 final-verification + 비-명시-stage 를 거부한다.
+
+결과: 전체-task final-verification 은 CLI `okstra.sh --stage auto` (또는 stage 생략)로만 가능하고, okstra-run 위저드 사용자는 도달할 수 없다. prepare 는 이미 전체-task 를 지원하므로([run.py:1829](../../../scripts/okstra_ctl/run.py:1829), [run.py:1533](../../../scripts/okstra_ctl/run.py:1533)) **막힌 곳은 위저드 레이어뿐**이다.
+
+## 2. 목표 / 비목표
+
+목표:
+- okstra-run 위저드의 final-verification stage picker 에서 **전체-task 검증을 명시 항목으로 선택** 가능하게 한다.
+- picker 에 stage 별 **done 상태를 표시**해, 전체-task 가 안 되는 경우 어느 stage 가 미완인지 사용자가 바로 본다.
+- prepare 계약(CLI `--stage`)을 **변경하지 않는다** — 위저드가 기존 전체-task 트리거(빈 stage)를 emit 한다.
+
+비목표:
+- `implementation` 의 `auto` 토큰 의미("가장 낮은 ready stage")를 final-verification 에서 재사용하지 않는다. picker 라벨·내부 값 어디에도 `auto` 를 쓰지 않는다.
+- 머지/clean/active 전제의 위저드 사전 검사 — 이는 prepare 의 PrepareError 게이트에 위임한다(§4).
+- 자동 stage 머지(여전히 사용자 수동 머지).
+- prepare / `_reserve_final_verification_target` / target 해소 로직 변경.
+
+## 3. 노출 형태 — stage picker 명시 항목
+
+[`_build_stage_pick`](../../../scripts/okstra_ctl/wizard.py:1494) 가 final-verification 일 때:
+
+1. 각 stage 항목 라벨에 **done 마킹**을 붙인다. 예: `1: <제목>  [done]` / `2: <제목>  [미완]`.
+2. **모든** Stage Map stage 가 done 이면 picker 맨 위에 `전체 task 검증` 항목을 추가한다. done 이 아닌 stage 가 하나라도 있으면 이 항목을 노출하지 않는다 — picker 의 stage 별 `[미완]` 마킹이 그대로 보이므로 사용자가 왜 전체 검증이 불가능한지 자명하다.
+
+이 구조는 "stage 가 done 이 아닌 걸 보여준다" 는 요구를 충족하면서, 전체-task 선택 가능 여부도 같은 화면에서 드러낸다.
+
+## 4. done 상태 데이터원 — git 호출 없음
+
+위저드가 읽는 것은 prepare 와 동일한 SSOT 인 `consumers.jsonl` 의 `status:done` 행뿐이다. git 상태(머지/clean)는 위저드가 검사하지 않는다.
+
+- `plan_run_root` 도출: `Path(approved_plan_path).resolve().parents[1]` ([run.py:1525](../../../scripts/okstra_ctl/run.py:1525) 와 동일 규칙).
+- done 행: `backfill_done_from_carry(plan_run_root)` → `read_consumers(plan_run_root)` → `latest_done_by_stage(rows)` ([consumers.py:24](../../../scripts/okstra_ctl/consumers.py:24), [consumers.py:37](../../../scripts/okstra_ctl/consumers.py:37), [consumers.py:182](../../../scripts/okstra_ctl/consumers.py:182)).
+- Stage Map: 기존 `_build_stage_pick` 이 이미 승인 plan 을 `_parse_stage_map` 으로 파싱한다([wizard.py:1499](../../../scripts/okstra_ctl/wizard.py:1499)). 그 stage 번호 집합과 done 집합을 비교한다.
+
+책임 분담:
+- **위저드**: done 여부만 사전 표시(파일 읽기). 전체-task 항목 노출 게이트.
+- **prepare**: 머지(`head_commit` 이 task worktree HEAD 의 ancestor) · clean · task-key worktree active 를 최종 강제. 미충족이면 기존 PrepareError 로 어느 stage 가 미머지인지 안내([run.py:587](../../../scripts/okstra_ctl/run.py:587), [run.py:594](../../../scripts/okstra_ctl/run.py:594), [worktree.py:655](../../../scripts/okstra_ctl/worktree.py:655)).
+
+위저드가 git 을 호출하지 않으므로 picker 빌드가 가볍고, 전제 강제는 한 곳(prepare)에 단일화된다.
+
+## 5. prepare 계약 — 빈 stage emit (계약 무변경)
+
+전체-task 선택의 위저드 내부 표현과 prepare 로 넘기는 값을 분리한다:
+
+- 위저드 내부: `selected_stage` 에 명시 sentinel(예: `"whole-task"`)을 담는다.
+- [`render_args`](../../../scripts/okstra_ctl/wizard.py:2792): 이 sentinel 을 **빈 stage(`""`)** 로 변환해 prepare 에 넘긴다.
+
+prepare 는 빈/`auto` stage 를 이미 전체-task 로 해석한다(`if inp.stage and inp.stage != "auto"` 의 else 분기, [run.py:1829](../../../scripts/okstra_ctl/run.py:1829) · [run.py:1533](../../../scripts/okstra_ctl/run.py:1533)). 따라서 CLI `--stage` 계약·validator·prepare 분기 변경이 전혀 없고, 표면 어디에도 `auto` 가 노출되지 않는다.
+
+base-ref / branch-confirm skip 은 현행 유지([`_base_ref_required`](../../../scripts/okstra_ctl/wizard.py:766), [`_branch_confirm_required`](../../../scripts/okstra_ctl/wizard.py:774)) — 전체-task·단독-stage 모두 base 가 prepare 에서 자동 해소되므로 위저드가 base 를 물을 필요가 없다.
+
+## 6. 게이트 함수 조정
+
+| 함수 | 현재 | 변경 |
+|---|---|---|
+| [`_stage_auto_allowed`](../../../scripts/okstra_ctl/wizard.py:778) | `task_type == "implementation"` | final-verification 에서 "전체 task" 항목 노출을 **전 stage done** 조건으로 허용. (implementation 의 `auto` 와 의미가 다르므로 함수명/의도 재정의 또는 final-verification 전용 헬퍼 신설) |
+| [`_submit_stage_pick`](../../../scripts/okstra_ctl/wizard.py:1539) | `auto` 만 특수 처리, final-verification+auto 거부 | "전체 task" sentinel 수용 |
+| [`render_args`](../../../scripts/okstra_ctl/wizard.py:2799) | final-verification + (빈/auto) → `WizardError` | sentinel → 빈 stage 변환(§5); 단독은 기존대로 명시 번호 |
+| [`confirmation_block`](../../../scripts/okstra_ctl/wizard.py:2872) | stage 값 그대로 표기 | sentinel 을 사람이 읽을 라벨("전체 task")로 표기 |
+
+## 7. 프롬프트 (prompts/wizard/prompts.ko.json)
+
+`stage_pick` 프롬프트에 전체-task 항목 라벨과 stage done/미완 마킹 문자열을 추가한다. `54b9482` 가 제거한 `auto` 라벨은 복원하지 않는다 — 새 라벨은 `auto` 가 아닌 "전체 task 검증" 계열 문자열이다.
+
+## 8. 테스트
+
+- `tests/test_wizard_stage_pick.py`: final-verification + 전 stage done → "전체 task" 항목 노출 / 일부 미완 → 미노출 + 해당 stage `[미완]` 마킹.
+- `tests/test_wizard_final_verification_stage.py`: "전체 task" 선택 → `render_args` 가 빈 stage emit; 단독 선택 → 명시 번호 emit.
+- `tests/test_okstra_ctl_wizard.py`: 전체-task 경로에서도 base-ref/branch-confirm 단계가 생략되는지(현행 불변 회귀).
+- prepare 측 회귀는 `tests/test_final_verification_target.py` 기존 케이스로 충분(prepare 계약 무변경).
+
+## 9. 비변경 확인 (회귀 가드)
+
+- prepare 분기·`_reserve_final_verification_target`·target 해소: 변경 없음.
+- CLI `okstra.sh --stage`: 변경 없음(빈 stage = 전체-task 는 기존 계약).
+- 단독-stage 위저드 UX(`54b9482` 도입분): 변경 없음.

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.69.0",
-  "builtAt": "2026-06-10T15:26:59.219Z",
+  "package": "0.70.0",
+  "builtAt": "2026-06-10T17:00:34.215Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/wizard/prompts.ko.json

@@ -188,7 +188,10 @@
       "label_final_verification": "검증할 implementation stage 를 선택하세요.",
       "echo_template": "stage: {value}",
       "options": {
-        "auto": "auto (다음 미완료 stage)"
+        "auto": "auto (다음 미완료 stage)",
+        "whole_task": "전체 task 검증 (모든 stage)",
+        "done_mark": "[done]",
+        "undone_mark": "[미완]"
       }
     },
     "directive_pick": {
@@ -367,6 +370,7 @@
   },
   "confirmation": {
     "header": "선택 확인:",
-    "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"
+    "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)",
+    "stage_whole_task": "전체 task"
   }
 }

package/runtime/python/okstra_ctl/paths.py

@@ -124,14 +124,17 @@ def compute_run_paths(
     timeline_file = history_dir / "timeline.json"
 
     run_dir = runs_dir / task_type_segment
-    # implementation stage isolation: each stage's run artifacts live in a
-    # dedicated `stage-<N>` subtree (mirrors the per-stage worktree) so two
-    # concurrent `implementation` runs never share reports/state/worker-results.
+    # Stage isolation: each stage's run artifacts live in a dedicated
+    # `stage-<N>` subtree (mirrors the per-stage worktree) so two concurrent
+    # runs of the same task-key never share reports/state/worker-results.
+    # Applies to `implementation` and single-stage `final-verification`
+    # (whole-task final-verification has stage=None and stays flat).
     # consumers.jsonl + the worktree registry stay at the task-type level (the
     # shared stage ledger / occupancy SSOT); they are computed OUTSIDE this
     # function and are intentionally NOT stage-scoped. Other task-types have no
     # stage concept, so their run_dir is unchanged.
-    if task_type_segment == "implementation" and stage is not None:
+    if (task_type_segment in ("implementation", "final-verification")
+            and stage is not None):
         run_dir = run_dir / f"stage-{int(stage)}"
     run_manifests = run_dir / "manifests"
     run_state = run_dir / "state"

package/runtime/python/okstra_ctl/render.py

@@ -1681,11 +1681,18 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         )
     else:
         team_name = f'okstra-{ctx.get("TASK_KEY", "")}'
-        stage = str(ctx.get("EFFECTIVE_STAGES", "") or "").strip()
-        if task_type == "implementation" and stage:
+        impl_stage = str(ctx.get("EFFECTIVE_STAGES", "") or "").strip()
+        fv_stage = str(ctx.get("RUN_STAGE", "") or "").strip()
+        if task_type == "implementation" and impl_stage:
             # stage 격리 run 은 stage 별 team — 같은 task 의 다른 stage 가 남긴
             # team 과 이름이 충돌하지 않는다(worktree branch `-s<N>` 접미사와 동형).
-            team_name = f"{team_name}-s{stage}"
+            team_name = f"{team_name}-s{impl_stage}"
+        elif task_type == "final-verification" and fv_stage:
+            # 단일-stage final-verification 도 stage 별 team. `-fv-` 를 끼워
+            # 같은 stage 의 implementation team(`-s<N>`)과도 구분한다 — 둘은
+            # 동시에 살아 있을 수 있다. whole-task 검증(RUN_STAGE 빈 값)은
+            # 기본 이름 유지.
+            team_name = f"{team_name}-fv-s{fv_stage}"
         team_creation_gate_block = (
             "## Team Creation Gate (BLOCKING)\n"
             "\n"

package/runtime/python/okstra_ctl/run.py

@@ -1868,7 +1868,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     ):
         if inp.task_type == "final-verification" and inp.stage and inp.stage != "auto":
             worktree = _single_stage_final_verification_worktree(inp)
+            # Single-stage final-verification namespaces its run path under
+            # runs/final-verification/stage-<N> (same isolation as
+            # implementation) so concurrent per-stage verifications never
+            # share state/reports/worker-results.
+            fv_stage_arg = int(inp.stage)
         else:
+            fv_stage_arg = None
             try:
                 worktree = provision_task_worktree(
                     task_type=inp.task_type,
@@ -1890,8 +1896,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         # lands in runs/implementation/stage-<N>. The registry stage-key is
         # reserved exactly once here (inside provision_stage_worktree), and
         # the surrounding mutex makes the registry read in stage selection
-        # and that reserve atomic. Non-implementation task-types skip this
-        # entirely → stage_arg stays None → identical paths.
+        # and that reserve atomic. Other task-types skip this selection;
+        # single-stage final-verification threads its explicit stage via
+        # fv_stage_arg, everything else keeps stage_arg=None (flat paths).
         if inp.task_type == "implementation":
             impl_stage_selection = _select_and_provision_implementation_stage(
                 inp, ctx_stage_map, task_group_segment, task_id_segment,
@@ -1904,7 +1911,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             _clear_stale_stage_waiver(inp, project_root, impl_stage_selection.stage)
         else:
             impl_stage_selection = None
-            stage_arg = None
+            stage_arg = fv_stage_arg
 
     ctx = compute_and_write_run_context(
         workspace_root=workspace_root, project_root=project_root,

package/runtime/python/okstra_ctl/wizard.py

@@ -779,6 +779,54 @@ def _stage_auto_allowed(state: WizardState) -> bool:
     return state.task_type == "implementation"
 
 
+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)
+
+
 def _existing_task_brief(project_root: Path, task_key: str) -> str:
     """Read taskBriefPath from manifest for an existing task. Empty if none."""
     root = find_task_root(project_root, task_key)
@@ -1358,6 +1406,7 @@ _REUSE_LAST_TOKEN = "__reuse_last__"
 _SIBLINGS_TOKEN = "__siblings__"
 _LATEST_REPORT_TOKEN = "__latest_report__"
 _PROJECT_DEFAULT_TOKEN = "__project_default__"
+WHOLE_TASK_STAGE = "__whole_task__"
 
 
 def _list_implementation_planning_reports(
@@ -1493,37 +1542,31 @@ def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str
 
 def _build_stage_pick(state: WizardState) -> Prompt:
     """Parse the Stage Map from the approved plan and build the stage picker."""
-    import importlib.util as _ilu
-    import sys as _sys
     t = _p(state.workspace_root, "stage_pick")
-    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)
+    stages = _parse_stage_objects(state)
+    is_fv = state.task_type == "final-verification"
     label = (
         t.get("label_final_verification", t["label"])
-        if state.task_type == "final-verification"
-        else 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 _whole_task_allowed(state):
+        options.append(_opt(WHOLE_TASK_STAGE, t["options"]["whole_task"]))
     for s in stages:
         depends = ",".join(map(str, s.depends_on)) or "(none)"
+        suffix = ""
+        if is_fv:
+            mark = (t["options"]["done_mark"]
+                    if s.stage_number in done
+                    else t["options"]["undone_mark"])
+            suffix = f"  {mark}"
         options.append(_opt(
             str(s.stage_number),
-            f"{s.stage_number}: {s.title}  [depends-on: {depends} | steps: {s.step_count}]",
+            f"{s.stage_number}: {s.title}  "
+            f"[depends-on: {depends} | steps: {s.step_count}]{suffix}",
         ))
     return Prompt(
         step=S_STAGE_PICK, kind="pick",
@@ -1541,12 +1584,19 @@ def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
             raise WizardError(
                 "final-verification requires an explicit stage number"
             )
+    elif answer == WHOLE_TASK_STAGE:
+        if not _whole_task_allowed(state):
+            raise WizardError(
+                "whole-task verification requires final-verification "
+                "with all stages done"
+            )
     else:
         try:
             int(answer)
         except ValueError:
             raise WizardError(
-                f"answer must be 'auto' or a stage number, got {answer!r}"
+                f"answer must be 'auto', whole-task, or a stage number, "
+                f"got {answer!r}"
             )
     state.selected_stage = answer
     return f"stage: {answer}"
@@ -2797,11 +2847,14 @@ def render_args(state: WizardState) -> dict[str, str]:
     if state.task_type == "implementation":
         stage = state.selected_stage or "auto"
     elif state.task_type == "final-verification":
-        if not state.selected_stage or state.selected_stage == "auto":
+        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"
             )
-        stage = state.selected_stage
+        else:
+            stage = state.selected_stage
     else:
         stage = ""
     pr_template = (
@@ -2872,8 +2925,11 @@ def confirmation_block(state: WizardState) -> str:
     if state.task_type in _STAGE_SCOPED_TASK_TYPES:
         lines.append(f"  approved-plan : {state.approved_plan_path}")
         stage = (
-            state.selected_stage
-            or ("auto" if state.task_type == "implementation" else "(not selected)")
+            _msg(state.workspace_root, "confirmation", "stage_whole_task")
+            if state.selected_stage == WHOLE_TASK_STAGE
+            else (state.selected_stage
+                  or ("auto" if state.task_type == "implementation"
+                      else "(not selected)"))
         )
         lines.append(f"  stage         : {stage}")
     if state.clarification_response_path:

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

@@ -572,7 +572,7 @@ Promoted blockers enter `## 5.8 Acceptance Blockers`; since `accepted` requires
 
 ### State
 
-Critic output lives at `runs/final-verification/worker-results/<provider>-critic-final-verification-<seq>.md`. The convergence state `config.critic` summary (see §"Coverage critic pass") records `mode: "acceptance-devils-advocate"`, `candidatesProposed`, `confirmedBlockers`, `downgradedToResidual` (optional v1.2 fields; readers treat absence as null).
+Critic output lives in the run's `worker-results/` directory (`runs/final-verification/worker-results/` for whole-task verification, `runs/final-verification/stage-<N>/worker-results/` for single-stage), filename `<provider>-critic-final-verification-<seq>.md`. The convergence state `config.critic` summary (see §"Coverage critic pass") records `mode: "acceptance-devils-advocate"`, `candidatesProposed`, `confirmedBlockers`, `downgradedToResidual` (optional v1.2 fields; readers treat absence as null).
 
 ## Output
 

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

@@ -299,7 +299,7 @@ B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / t
 
 C. **`timeline.json` (specific run):** for a specific date or run, read `.okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
 
-D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
+D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Stage-isolated runs (`implementation`, single-stage `final-verification`) keep their reports one level deeper at `runs/<task-type-segment>/stage-<N>/reports/` — scan those subdirectories too; seq is independent per stage. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
 
 ### report.2 — Confirm existence