okstra 0.69.0 → 0.71.0

package/docs/superpowers/specs/2026-06-11-brief-entry-only-handoff-stage-entry-design.md

@@ -0,0 +1,158 @@
+# brief entry-phase 한정 + release-handoff task-id 기반 stage 진입 — 설계
+
+- 날짜: 2026-06-11
+- 상태: 구현 완료 (사용자 승인 후 구현 — §5.3 의 manifest 갱신 항목만 구현 시 수정)
+- 선행 설계: [2026-06-10-stage-group-handoff-design.md](2026-06-10-stage-group-handoff-design.md) (stage-group 백엔드), [2026-06-06-stage-worktree-isolation-design.md](2026-06-06-stage-worktree-isolation-design.md)
+
+## 1. 배경 / 문제
+
+brief 는 비개발자·타 팀·아이디어·에러 신고 초안을 담는 **entry-phase 입력물**인데, 현재 구조는 모든 phase 에서 brief 를 의식처럼 요구한다. 사용자가 실제 run 에서 확인한 문제 세 가지:
+
+1. **위저드가 전 task-type 에 brief 를 묻는다.** brief 단계에 task-type 필터가 없고([wizard.py:2367-2382](../../../scripts/okstra_ctl/wizard.py:2367)), 기존 task 면 `brief_keep` 으로 유지/변경을 또 묻는다([wizard.py:2418-2425](../../../scripts/okstra_ctl/wizard.py:2418)). downstream phase 의 brief 는 task manifest 의 `taskBriefPath` 로 이미 자동 해소 가능한데도([wizard.py:830-837](../../../scripts/okstra_ctl/wizard.py:830)) 사용자 입력을 요구한다.
+2. **release-handoff 의 실질 입력은 final-verification final-report 인데 위저드는 brief 경로를 요구한다.** stage-group 모드 진입 조건이 "brief 가 단독-stage 검증 보고서 N 개를 인용"이라는 수동 의식이고([release-handoff.md:15](../../../prompts/profiles/release-handoff.md:15)), 그 brief 를 만들어 주는 자동화는 없다 — [release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) 는 렌더러가 없는 죽은 템플릿이며 단수 인용 슬롯뿐이다. 모드(whole-task/stage-group)를 사용자에게 보여주는 지점도 위저드·brief·게이트 어디에도 없다.
+3. **stage 자격 판정 인프라는 이미 있다.** `okstra_ctl.handoff.compute_eligibility` 가 approved plan 의 Stage Map + `consumers.jsonl`(done + `verified` accepted + 미-`pr`)로 stage 별 PR 자격을 판정한다([handoff.py:36-39](../../../scripts/okstra_ctl/handoff.py:36)). task-id 만 있으면 계산되는 정보를 brief 인용으로 중복 선언하게 하는 것은 단일 참조점 위반이다.
+
+## 2. 결정 요약 (사용자 Q&A)
+
+| 질문 | 결정 |
+|---|---|
+| brief 는 어느 phase 입력인가 | entry phase(requirements-discovery / error-analysis / improvement-discovery) 전용. downstream 은 task-id 로 자동 carry-in |
+| release-handoff 진입 입력 | brief 경로가 아니라 task-id. 검증 완료(eligible) stage 를 멀티선택하거나 전체 선택 |
+| stage 선택 근거 | implementation-planning final-report 의 Stage Map + consumers 상태 (`handoff eligible` 재사용) |
+| PR 생성 후 stage worktree 정리 | **범위 제외** (사용자 결정 — PR 리뷰 수정이 stage 브랜치를 재사용하는 흐름과 충돌 위험) |
+
+## 3. 목표 / 비목표
+
+목표:
+
+- 위저드 brief 단계(`brief_path_pick`/`brief_path`/`brief_keep`)를 entry phase 에만 적용하고, downstream phase 는 manifest `taskBriefPath` 로 자동 해소한다.
+- release-handoff 위저드 진입을 brief picker 대신 **eligible stage picker** 로 교체한다. 모드는 선택 결과로 자동 결정된다.
+- prepare 가 release-handoff 의 입력 문서(검증 보고서 인용 래퍼)를 [release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) 로 **자동 생성**한다 — 죽은 템플릿의 부활, 수동 brief 작성 제거.
+- `--stage`(impl/fv 의 Stage Map 실행/검증 선택)와 release-handoff 의 stage 묶음 선택을 **별개 채널**로 유지하되, 후자를 위저드 → render-bundle 로 전달하는 `--stages` flag 를 신설한다.
+
+비목표:
+
+- PR 생성 후 worktree/branch/registry 정리 (사용자 결정으로 제외).
+- `handoff eligible / assemble / record-*` 백엔드 로직 변경 — 그대로 재사용한다.
+- 다른 phase 의 죽은 input 템플릿(`error-analysis-input` 등) 정비 — 후속 과제(§9).
+- okstra-brief 스킬 변경 — entry phase 용도 그대로.
+- prepare 의 `--task-brief` 필수 계약 변경 — 위저드/prepare 가 채워 넣는 방식만 바뀐다.
+
+## 4. 설계 A — brief 를 entry phase 전용으로
+
+### 4.1 task-type 분류 (SSOT 상수)
+
+`wizard.py` 에 상수 신설 (기존 `_STAGE_SCOPED_TASK_TYPES` [wizard.py:89](../../../scripts/okstra_ctl/wizard.py:89) 와 나란히):
+
+```python
+_BRIEF_ENTRY_TASK_TYPES = ("requirements-discovery", "error-analysis",
+                           "improvement-discovery")
+```
+
+downstream = 그 외 전부(implementation-planning, implementation, final-verification, release-handoff).
+
+### 4.2 위저드 단계 변경
+
+- `S_BRIEF_PATH_PICK` / `S_BRIEF_PATH` / `S_BRIEF_KEEP` 의 `applies` 에 `s.task_type in _BRIEF_ENTRY_TASK_TYPES` 게이트 추가.
+  - 주의: 현재 신규 task 흐름은 brief 선택이 task-type 선택보다 **앞선다**([wizard.py:2373](../../../scripts/okstra_ctl/wizard.py:2373) `is_new_task is True and bool(task_group)`). 게이트를 넣으려면 신규 task 의 단계 순서를 task-type 먼저로 재배열해야 한다(§8 테스트로 고정). 기존 task 흐름은 이미 task-type 이후에 brief 를 묻는다.
+- downstream + 기존 task: `_existing_task_brief()` 결과를 `state.brief_path` 에 **자동 주입**하고 brief 관련 단계를 모두 건너뛴다. 사용자에게 echo 한 줄로만 알린다 (`brief (carry-in): <path>`).
+- downstream + brief 미등록 (신규 task 로 downstream type 을 고르거나 manifest 에 `taskBriefPath` 없음): 3-옵션 picker (run-prompt 추천 규칙 준수):
+  1. (추천) entry phase 로 task-type 변경 — picker 가 entry 3종을 보여주고 task-type 단계로 되돌린다.
+  2. brief 경로 직접 입력 — 탈출구. 손으로 쓴 brief 로 downstream 부터 시작하는 기존 워크플로 보존.
+  3. 중단.
+- release-handoff 는 §5 의 자동 생성 입력이 brief 역할을 대체하므로 이 picker 대상에서도 제외된다.
+
+### 4.3 계약 불변 사항
+
+- prepare 의 `--task-brief` 필수 검증([run.py:2209-2212](../../../scripts/okstra_ctl/run.py:2209))과 downstream profile 들의 brief 인용(예: Requirement Coverage 가 brief heading 인용 — [implementation-planning.md:86](../../../prompts/profiles/implementation-planning.md:86))은 그대로다. brief 는 여전히 전 phase 의 요구사항 anchor 다 — 바뀌는 것은 "누가 경로를 대는가"(사용자 → 위저드 자동) 뿐이다.
+
+## 5. 설계 B — release-handoff: task-id 진입 + eligible stage picker
+
+### 5.1 위저드 흐름 (release-handoff 한정)
+
+```
+task 선택(기존 task 전제) → task-type=release-handoff
+  → approved-plan 자동 해소 (fv 와 동일: _latest_implementation_planning_report
+     + frontmatter approved: true 확인; 실패 시 implementation-planning 선행 안내)
+  → S_HANDOFF_STAGE_PICK (신규):
+       compute_eligibility 직접 호출 (python import — shell-out 금지, 단일 참조점)
+       옵션:
+         - "전체 task (whole-task 검증 기반)" — whole-task fv 보고서(accepted,
+           verificationScope=whole-task)가 존재할 때만 노출 → whole-task 모드
+         - eligible stage 멀티선택 (전체 eligible 선택 = "다 같이") → stage-group 모드
+         - blocked stage 는 reasons 와 함께 비선택 표시
+  → (이후 기존 단계: pr-template, 모델/directive 등 — 변경 없음)
+```
+
+- brief 단계 없음, base-ref 단계 없음(현행 유지 — PR base 는 run 중 G1/Q2 가 묻는다).
+- 모드 질문은 별도 단계가 아니라 **이 picker 의 선택지로 흡수**된다.
+
+### 5.2 인자 전달 — `--stages` 신설
+
+- `render_args()` 가 release-handoff 일 때 신규 키 `stages` 를 채운다: whole-task = `""`, stage-group = `"2,3"` (csv).
+- `render-bundle` / `okstra.sh` / `okstra_ctl.run` argparse 에 `--stages` 추가. **release-handoff 외 task-type 에서 비어 있지 않은 `--stages` 는 PrepareError** (어제 고친 `--stage` 빈 값 규칙과 동일하게, 빈 문자열은 미지정으로 통과 — [run.py:1124](../../../scripts/okstra_ctl/run.py:1124) 패턴).
+- `--stage` 와 `--stages` 는 다른 채널이다: 전자 = impl/fv 의 Stage Map 실행/검증 선택, 후자 = release-handoff 의 PR 묶음 선택. 도움말에 명시한다.
+
+### 5.3 prepare — 입력 문서 자동 생성
+
+release-handoff prepare 시:
+
+1. `compute_eligibility` 로 선택 stage 들의 자격을 **재검증** (위저드를 거치지 않은 CLI 경로도 같은 강제 지점을 통과).
+2. 각 선택 stage 의 단독 검증 보고서 경로·verdict 를 `consumers.jsonl` 의 `verified` 행(last-wins, [consumers.py:107-111](../../../scripts/okstra_ctl/consumers.py:107))에서 수집. whole-task 면 최신 whole-task fv final-report 에서 수집.
+3. [release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) 를 렌더링해 `<task_root>/release-handoff-input.md` 로 저장(매 run 덮어씀) → 이 파일이 그 run 의 brief 자리(`inp.brief_path`)를 채운다. manifest `taskBriefPath` 는 **갱신하지 않는다** — entry brief 포인터를 덮으면 이후 다른 phase 의 carry-in 이 handoff input 을 brief 로 오인하기 때문(구현 시 확정한 spec 수정).
+4. run-context 에 `HANDOFF_MODE` (`whole-task` | `stage-group`) 와 `HANDOFF_STAGES` 를 기록.
+
+### 5.4 템플릿 개정
+
+`## Source Verification Report` 를 단수/복수 겸용으로 교체:
+
+```markdown
+## Source Verification Report
+
+- Mode: `whole-task` | `stage-group`
+- Reports (one row per cited final-verification report):
+
+| Stage | Report path | Verdict Token (verbatim) | Run timestamp |
+|---|---|---|---|
+```
+
+whole-task 모드는 Stage 열을 `(all)` 한 행으로 채운다.
+
+### 5.5 profile 개정 ([release-handoff.md](../../../prompts/profiles/release-handoff.md))
+
+- 진입 게이트(:13-15): "brief 가 인용해야 한다" → "prepare 가 생성한 input 문서 + run-context 의 `HANDOFF_MODE`/`HANDOFF_STAGES` 를 읽고, 인용된 각 Verdict Token 이 `accepted` 인지 확인한다" 로 교체.
+- G2(:27): 위저드/CLI 에서 stage 가 이미 선택돼 있으므로 **재선택이 아니라 확인 표시**로 축소 — 선택 목록을 보여주고 진행. `okstra handoff eligible` 직접 호출 분기는 stage 선택 없이 진입한 비정상 경로의 방어로만 남긴다.
+- assemble(:28) 이후 흐름(G1 base → assemble → Q2b → Q3, record-pr)은 불변.
+
+## 6. 설계 C — final-verification
+
+stage picker(done 마킹 + 전체 task 검증)는 최근 작업으로 이미 사용자 모델과 일치한다. 이 설계에서는 §4 의 brief 자동 carry-in 만 적용된다.
+
+## 7. 영향 파일
+
+| 파일 | 변경 |
+|---|---|
+| [scripts/okstra_ctl/wizard.py](../../../scripts/okstra_ctl/wizard.py) | `_BRIEF_ENTRY_TASK_TYPES`, brief 단계 게이트·자동 주입·미등록 picker, 신규 task 단계 순서 재배열, `S_HANDOFF_STAGE_PICK`, `render_args` `stages` 키 |
+| [scripts/okstra_ctl/run.py](../../../scripts/okstra_ctl/run.py) | `--stages` argparse + 검증 + prepare 의 input 자동 생성·`HANDOFF_MODE`/`HANDOFF_STAGES` |
+| [scripts/okstra_ctl/handoff.py](../../../scripts/okstra_ctl/handoff.py) | (변경 없음 — import 재사용) |
+| [templates/reports/release-handoff-input.template.md](../../../templates/reports/release-handoff-input.template.md) | Source Verification Report 복수 양식 |
+| [prompts/profiles/release-handoff.md](../../../prompts/profiles/release-handoff.md) | 진입 게이트·G2 개정 |
+| [prompts/wizard/prompts.ko.json](../../../prompts/wizard/prompts.ko.json) | 신규/변경 prompt 문구 |
+| [skills/okstra-run/SKILL.md](../../../skills/okstra-run/SKILL.md) | render-bundle 호출부 `--stages`, brief 단계 서술 갱신 |
+| [scripts/okstra.sh](../../../scripts/okstra.sh) | `--stages` 전달 |
+| [docs/kr/cli.md](../../../docs/kr/cli.md), [docs/kr/architecture.md](../../../docs/kr/architecture.md), [docs/task-process/release-handoff.md](../../../docs/task-process/release-handoff.md) | 계약 서술 갱신 |
+
+## 8. 테스트
+
+- 위저드 단계 적용 매트릭스: entry 3종 = brief 단계 노출, downstream 4종 = 미노출 + 자동 주입 echo. 신규 task 단계 순서(task-type 이 brief 보다 먼저) 회귀.
+- downstream + brief 미등록 → 3-옵션 picker 노출, 각 분기 동작.
+- `S_HANDOFF_STAGE_PICK`: eligible/blocked 구성, whole-task 옵션 노출 조건, 멀티선택 → `render_args["stages"]` csv.
+- `--stages` 게이트: release-handoff 외 task-type 의 비어 있지 않은 값 거부, 빈 값 통과 (기존 [tests/test_prepare_stage_flag_gate.py](../../../tests/test_prepare_stage_flag_gate.py) 패턴).
+- prepare 입력 자동 생성: verified 행 인용 정확성(단위) + subprocess `--render-only` e2e 로 생성 파일·manifest 갱신 확인.
+- profile 계약: validators 의 release-handoff 관련 체크가 있다면 갱신분 통과.
+
+## 9. 미해결 / 후속
+
+- 다른 phase 의 죽은 input 템플릿([render.py:113-118](../../../scripts/okstra_ctl/render.py:113) 태그만 존재) 정리 또는 부활 — 별도 과제.
+- PR 생성 후 stage worktree/branch/registry 정리 — 이번 범위에서 명시적으로 제외(사용자 결정). 재논의 시 PR 리뷰 수정 흐름([okstra-run SKILL.md:228](../../../skills/okstra-run/SKILL.md:228))과의 충돌을 먼저 풀어야 한다.
+- okstra-brief 체인 다이어그램([SKILL.md:44-57](../../../skills/okstra-brief/SKILL.md:44))의 release-handoff 종단 표기 정합화.

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/docs/task-process/release-handoff.md

@@ -51,8 +51,9 @@ sequenceDiagram
     participant WT as worktree registry
     participant FS as task artifacts
 
-    W->>P: task-type=release-handoff, brief, optional pr-template-path
-    P->>P: validate profile and brief
+    W->>P: task-type=release-handoff, approved-plan, stages csv, optional pr-template-path
+    P->>P: enforce stage eligibility (consumers verified/pr rows)
+    P->>FS: generate release-handoff-input.md (cited verification reports)
     P->>P: force workers=[]
     P->>T: resolve PR template
     P->>WT: reuse or provision task worktree
@@ -67,7 +68,7 @@ profile에 `Required workers:` block이 없고 `run.py`도 `release-handoff`에
 
 ```mermaid
 flowchart TD
-    Brief[task brief] --> Source{Source Verification Report present?}
+    Brief[release-handoff-input.md<br/>generated by prepare] --> Source{Source Verification Report present?}
     Source -->|no| Block[blocked<br/>route final-verification]
     Source -->|yes| Verdict{Verdict Token == accepted?}
     Verdict -->|no| Block
@@ -82,8 +83,8 @@ flowchart TD
 
 lead는 사용자에게 push/PR 여부를 묻기 전에 다음을 확인한다.
 
-- task brief가 `## Source Verification Report`를 가리킨다.
-- 그 report의 `## 7. Final Verdict`에 `Verdict Token = accepted`가 정확히 있다.
+- prepare 가 생성한 input 문서(`release-handoff-input.md`)의 `## Source Verification Report` 가 모드(`HANDOFF_MODE`)와 인용 보고서 표를 담고 있다. brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 사용자의 stage 선택은 wizard `handoff_stage_pick` 또는 CLI `--stages` 로 prepare 전에 끝난다.
+- 인용된 각 report 의 `## 7. Final Verdict`에 `Verdict Token = accepted`가 정확히 있다.
 - working tree가 clean이다.
 - 현재 branch가 `main`, `master`, `prod`, `preprod`, `staging`, `dev` 같은 base branch가 아니다.
 - `<base>..HEAD` commit range가 비어 있지 않다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.69.0",
+  "version": "0.71.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.71.0",
+  "builtAt": "2026-06-10T18:46:31.471Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/lib/okstra/cli.sh

@@ -24,7 +24,10 @@ collect_required_arguments() {
   prompt_for_required_argument TASK_GROUP "Task Group"
   prompt_for_required_argument TASK_ID "Task ID"
   prompt_for_required_argument TASK_TYPE "Task Type"
-  prompt_for_required_argument BRIEF_PATH "Task Brief Path"
+  if [[ "$TASK_TYPE" != "release-handoff" ]]; then
+    # release-handoff 는 brief 가 없다 — prepare 가 검증 보고서 인용 input 을 생성.
+    prompt_for_required_argument BRIEF_PATH "Task Brief Path"
+  fi
 }
 
 require_option_value() {
@@ -103,6 +106,10 @@ while [[ $# -gt 0 ]]; do
       STAGE="$(require_option_value --stage "${2-}")"
       shift 2
       ;;
+    --stages)
+      STAGES="$(require_option_value --stages "${2-}")"
+      shift 2
+      ;;
     --qa-waiver)
       QA_WAIVER="$(require_option_value --qa-waiver "${2-}")"
       shift 2

package/runtime/bin/lib/okstra/interactive.sh

@@ -215,14 +215,16 @@ PY
     esac
   done <<<"$autofill_output"
 
-  if [[ -z "$BRIEF_PATH" && -n "$manifest_brief" ]]; then
-    BRIEF_PATH="$manifest_brief"
-    printf 'autofill: brief-path from task-manifest.json: %s\n' "$BRIEF_PATH" >&2
-  fi
   if [[ -z "$TASK_TYPE" && -n "$manifest_type" ]]; then
     TASK_TYPE="$manifest_type"
     printf 'autofill: task-type from manifest workflow.nextRecommendedPhase: %s\n' "$TASK_TYPE" >&2
   fi
+  # release-handoff 는 brief 입력이 없다 (prepare 가 검증 보고서 인용 input 을
+  # 생성) — task-type autofill 이후에 판정해야 하므로 순서가 위와 바뀌면 안 된다.
+  if [[ -z "$BRIEF_PATH" && -n "$manifest_brief" && "$TASK_TYPE" != "release-handoff" ]]; then
+    BRIEF_PATH="$manifest_brief"
+    printf 'autofill: brief-path from task-manifest.json: %s\n' "$BRIEF_PATH" >&2
+  fi
 }
 
 missing_required_arguments_summary() {
@@ -232,7 +234,8 @@ missing_required_arguments_summary() {
   [[ -z "$TASK_GROUP" ]] && missing+=("<task-group>")
   [[ -z "$TASK_ID" ]] && missing+=("<task-id>")
   [[ -z "$TASK_TYPE" ]] && missing+=("<task-type>")
-  [[ -z "$BRIEF_PATH" ]] && missing+=("<brief-path>")
+  # release-handoff 는 brief 입력이 없다 — prepare 가 input 문서를 생성한다.
+  [[ -z "$BRIEF_PATH" && "$TASK_TYPE" != "release-handoff" ]] && missing+=("<brief-path>")
 
   if (( ${#missing[@]} == 0 )); then
     printf '%s' ""

package/runtime/bin/okstra.sh

@@ -124,6 +124,7 @@ PY_ARGS=(
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")
 [[ -n "${STAGE-}" ]] && PY_ARGS+=(--stage "$STAGE")
+[[ -n "${STAGES-}" ]] && PY_ARGS+=(--stages "$STAGES")
 [[ -n "${QA_WAIVER-}" ]] && PY_ARGS+=(--qa-waiver "$QA_WAIVER")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$PLAN_VERIFICATION_ENABLED" == "false" ]] && PY_ARGS+=(--no-plan-verification)

package/runtime/prompts/profiles/release-handoff.md

@@ -11,8 +11,9 @@
   - The shared "authority & permissions assumption" rule from the common contract still applies: assume the user holds every permission needed; do not block on hypothetical approvals.
   - The shared "MCP read-only" rule still applies if the brief lists MCP servers, though most release-handoff runs do not use MCP.
 - Pre-handoff entry gate (mandatory — refuse to start if any item fails):
-  - **whole-task mode**: the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`; the lead confirms its `Verdict Token` is exactly `accepted` and its `verificationScope` is `whole-task`.
-  - **stage-group mode**: the brief cites N single-stage `final-verification` reports (one per candidate stage); the lead confirms each `Verdict Token` is `accepted`. Eligibility is re-enforced by `okstra handoff` — the lead never hand-computes it.
+  - the run's input document (`release-handoff-input.md`, generated by prepare in place of a task brief — briefs belong to entry phases only) carries a `## Source Verification Report` section with `Mode`, `Stages`, and one table row per cited `final-verification` final-report. The run context exposes the same selection as `HANDOFF_MODE` (`whole-task` | `stage-group`) and `HANDOFF_STAGES` (csv, empty for whole-task).
+  - **whole-task mode** (`HANDOFF_MODE=whole-task`): the lead opens the cited report and confirms its `Verdict Token` is exactly `accepted` and its `verificationScope` is `whole-task`.
+  - **stage-group mode** (`HANDOFF_MODE=stage-group`): the lead opens each cited single-stage report and confirms every `Verdict Token` is `accepted`. Eligibility was already enforced at prepare time (`okstra_ctl.handoff.compute_eligibility`) and is re-enforced by `okstra handoff assemble` — the lead never hand-computes it.
   - if the verdict is `conditional-accept`, `blocked`, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; Do NOT run any git command.
   - the lead MUST capture `git status --short` and confirm the working tree is clean. Dirty state aborts the run; release-handoff packages the commits produced by `implementation`, it does not stage or commit changes.
   - the lead MUST capture `git rev-parse --abbrev-ref HEAD` and record it as the **feature branch**. If the current branch is itself `main`, `master`, `prod`, `preprod`, `staging`, or `dev`, the run MUST end immediately — release-handoff never operates on a base branch.
@@ -23,11 +24,10 @@
      - `push + PR` — push the feature branch, then open or reuse a pull request.
      - `skip` — record the verified state and end the run without any git command.
      If the user picks `skip`, route directly to the final-report self-review pass.
-  - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage selection, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
-  1g. **G2 — stage selection**: run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and present the returned stages (eligible ones selectable, blocked ones listed with their `reasons`) as a multi-select. At least one stage must be selected.
+  - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage confirmation, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
+  1g. **G2 — stage confirmation**: the stage selection already happened before the run (wizard `handoff_stage_pick`, or the CLI `--stages` flag) and is fixed in `HANDOFF_STAGES`. Display it as a one-line confirmation (`PR 대상 stage: <csv> — 진행합니다`) and proceed; do NOT re-ask the multi-select. Only if `HANDOFF_MODE` is `stage-group` but `HANDOFF_STAGES` is empty (defensive, should not happen) run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and ask the user to pick from the eligible stages.
   2g. **assemble**: run `okstra handoff assemble --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <csv> --base <chosen-base>`. Exit 2 means a stage-vs-stage merge conflict: show the `conflicts` paths and stop (route: reshape the group or resolve manually). Exit 1 means an eligibility/closure violation: show the error verbatim and re-ask G2. On success the returned `branch` is the PR head branch for every subsequent step.
   2. **PR base branch** (only when the user picked `push + PR`) — present four options and capture exactly one:
-     - `staging`
      - `preprod`
      - `main`
      - `직접 입력` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)

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

@@ -123,6 +123,42 @@
       "label": "task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)",
       "echo_template": "brief: {value}"
     },
+    "handoff_stage_pick": {
+      "label": "PR 로 내보낼 범위를 선택하세요 (복수 선택 가능 — 검증 accepted + 미-PR stage 만 표시). 제외된 stage: {blocked}",
+      "echo_template": "handoff-scope: {value}",
+      "labels": {
+        "whole_task": "전체 task — whole-task 검증 기반 단일 PR (단독 선택)",
+        "stage": "stage {stage} (depends-on: {deps})",
+        "blocked_none": "없음"
+      },
+      "echo_variants": {
+        "whole_task": "handoff scope: 전체 task (whole-task 검증 기반)",
+        "stage_group": "handoff scope: stage-group ({stages})"
+      },
+      "errors": {
+        "no_plan": "release-handoff 는 이 task 의 implementation-planning final-report 가 필요합니다 — implementation-planning → implementation → final-verification 을 먼저 진행하세요.",
+        "plan_not_approved": "최신 plan 이 approved 상태가 아닙니다: {plan} — implementation 이 완료된 task 에서만 release-handoff 를 시작할 수 있습니다.",
+        "no_stage_map": "approved plan 에서 Stage Map 을 읽지 못했습니다: {plan}",
+        "nothing_eligible": "PR 로 내보낼 수 있는 범위가 없습니다 — 제외 사유: {blocked}. 단독-stage final-verification 의 accepted 기록(okstra handoff record-verified) 또는 whole-task 검증을 먼저 완료하세요.",
+        "none_selected": "최소 1개의 범위를 선택하세요",
+        "whole_task_exclusive": "'전체 task' 는 단독 선택만 가능합니다 — stage 묶음을 원하면 stage 번호들만 선택하세요",
+        "whole_task_missing": "accepted whole-task final-verification 보고서가 없습니다",
+        "not_eligible": "eligible 하지 않은 stage: {bad} (선택 가능: {eligible})"
+      }
+    },
+    "brief_carry": {
+      "label": "이 task 에 carry-in 할 brief 가 없습니다. {task_type} 는 entry phase 의 brief 를 이어받는 단계입니다 — 어떻게 진행할까요?",
+      "echo_template": "brief-carry: {value}",
+      "options": {
+        "__switch_entry__": "entry phase 로 전환 (추천) — requirements-discovery / error-analysis / improvement-discovery 부터 시작",
+        "__free_input__": "brief 경로 직접 입력",
+        "__abort__": "중단"
+      },
+      "echo_variants": {
+        "switch_entry": "brief-carry: entry phase 로 전환 — task-type 을 다시 선택합니다",
+        "abort": "brief-carry: 중단"
+      }
+    },
     "base_ref_pick": {
       "label": "이 task worktree 의 base branch?",
       "echo_template": "base-ref: {value}",
@@ -188,7 +224,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 +406,9 @@
   },
   "confirmation": {
     "header": "선택 확인:",
-    "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"
+    "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)",
+    "stage_whole_task": "전체 task",
+    "handoff_scope_whole_task": "전체 task (whole-task 검증 기반)",
+    "handoff_scope_stage_group": "stage-group ({stages})"
   }
 }

package/runtime/python/okstra_ctl/handoff.py

@@ -62,6 +62,35 @@ def compute_eligibility(stage_map: List[Dict[str, Any]],
     return out
 
 
+def latest_whole_task_fv_accepted(project_root, project_id: str,
+                                  task_group: str, task_id: str) -> str:
+    """accepted whole-task final-verification 보고서 경로. 없으면 ''.
+
+    판정의 SSOT 는 final-report 의 data.json 이다 (record_verified 와 동일
+    필드: header.taskType / verificationScope / finalVerdict.verdictToken).
+    whole-task run 산출물만 평면 reports/ 에 남으므로 stage-* 는 걸리지 않는다."""
+    from okstra_project.state import find_task_root
+    root = find_task_root(Path(project_root),
+                          f"{project_id}:{task_group}:{task_id}")
+    if root is None:
+        return ""
+    reports_dir = root / "runs" / "final-verification" / "reports"
+    for dj in sorted(reports_dir.glob("final-report-*.data.json"),
+                     reverse=True):
+        try:
+            data = json.loads(dj.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        token = ((data.get("finalVerdict") or {}).get("verdictToken")
+                 or "").strip().lower()
+        if ((data.get("header") or {}).get("taskType") == "final-verification"
+                and data.get("verificationScope") == "whole-task"
+                and token == "accepted"):
+            md = dj.with_name(dj.name[:-len(".data.json")] + ".md")
+            return str(md if md.is_file() else dj)
+    return ""
+
+
 def check_dependency_closure(
     selected: List[int],
     stage_map: List[Dict[str, Any]],

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"