okstra 0.70.0 → 0.71.0

package/docs/kr/architecture.md

@@ -373,7 +373,9 @@ okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결
 - **whole-task (기본)**: task 전체를 1개 PR 로 내보냅니다. 기존 동작입니다.
 - **stage-group**: 단독-stage final-verification 에서 `accepted` 를 받은 stage 들 중 일부를 골라, 수집(collector) 브랜치로 묶어 1개 PR 로 내보냅니다. task 전체가 끝나기를 기다리지 않고 검증 완료된 stage 묶음 단위로 PR 을 낼 수 있습니다.
 
-stage-group 의 상호작용 순서: **G1 base 선택 → G2 stage multi-select → assemble(수집 브랜치 생성 + 선택 stage 머지) → 충돌 프로브 → PR 초안 → push/PR**.
+진입은 brief 없이 **task-id 기반**입니다 — brief 는 entry phase 의 입력물이고, release-handoff 는 prepare 가 approved plan 의 Stage Map + `consumers.jsonl` 로 자격을 판정한 뒤 검증 보고서를 인용하는 input 문서(`<task_root>/release-handoff-input.md`)를 자동 생성합니다. stage 선택은 okstra-run wizard 의 `handoff_stage_pick` 멀티선택(eligible stage 묶음 / accepted whole-task 보고서가 있으면 전체 task) 또는 CLI `--stages <csv>` 로 들어오고, run-context 의 `HANDOFF_MODE` / `HANDOFF_STAGES` 로 lead 에 노출됩니다.
+
+stage-group 의 상호작용 순서: **G1 base 선택 → G2 stage 확인(선택은 prepare 전에 끝남 — 재질문 없음) → assemble(수집 브랜치 생성 + 선택 stage 머지) → 충돌 프로브 → PR 초안 → push/PR**.
 
 - 자격 판정의 SSOT 는 `consumers.jsonl` 의 두 행입니다 — `verified`(어떤 stage 가 단독-stage final-verification 에서 accepted 됨), `pr`(어떤 stage 들이 어느 PR 로 나갔는지). `verified` 인데 아직 `pr` 에 안 들어간 stage 가 자격 후보입니다.
 - worktree registry 는 stage-group 점유를 `<task-key>#group-<id>` 키로 예약하고, 수집 브랜치 이름은 `<work-category-prefix>-<task-id-segment>-g2-3` (예: 선택한 stage 가 2·3 이면 `-g2-3`) 형태입니다.
@@ -680,6 +682,8 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 
 `okstra`는 brief-first 구조입니다. brief 는 외부 입력과 okstra 보강을 보존하는 정본 source material 이며, 워커가 필요로 할 추가 자료(보고서, 코드 스니펫, 로그 등)는 brief 내부의 `Evidence and Source Materials` 섹션에 inline 또는 path 로 모두 포함시킵니다.
 
+brief 의 **입력 시점은 entry phase 전용**입니다 — 사용자가 brief 경로를 직접 대는 것은 `requirements-discovery` / `error-analysis` / `improvement-discovery` 뿐이고, downstream phase(implementation-planning / implementation / final-verification)는 task manifest 의 `taskBriefPath` 를 자동 carry-in 합니다 (okstra-run wizard 가 묻지 않음; 미등록 시 entry 전환을 추천하는 fallback picker). `release-handoff` 는 brief 자체가 없으며 prepare 가 검증 보고서 인용 input 문서를 생성합니다.
+
 brief 는 **translation layer** 입니다 — 외부 입력 (이슈 트래커 ticket, 요구사항 문서, 사용자 메시지) 을 okstra-readable 형식으로 옮기되, 원문은 verbatim 으로 보존하고 okstra 가 추가한 부분은 labelled augmentation 으로 명확히 구분합니다. `okstra-brief` skill 의 산출이 source SSOT 이고, `prepare_task_bundle()` 은 분석 phase 마다 여기서 필요한 frontmatter, task-specific brief 섹션, reference expectations, carry-in clarification, directive 를 추출해 `instruction-set/analysis-packet.md` 를 만듭니다. 분석 워커의 1차 입력은 이 compact packet 이며, 원본 brief 와 profile/material 파일은 근거 확인이나 누락 보완이 필요할 때만 여는 fallback evidence 입니다.
 
 brief에는 보통 아래를 포함합니다.

package/docs/kr/cli.md

@@ -132,6 +132,12 @@ interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니
 분석의 기준이 되는 task brief 문서 경로입니다.
 상대 경로는 대상 프로젝트 루트를 기준으로 해석됩니다.
 
+`release-handoff` 에는 적용되지 않습니다 — brief 는 entry phase
+(requirements-discovery / error-analysis / improvement-discovery)의 입력물이고,
+release-handoff 는 prepare 가 검증 보고서를 인용하는 input 문서
+(`<task_root>/release-handoff-input.md`)를 자동 생성해 brief 자리를 채웁니다.
+release-handoff 에 비어 있지 않은 `--task-brief` 를 주면 즉시 거부됩니다.
+
 예:
 
 - `.project-docs/linear/feature/8858/okstra-task-brief.md`
@@ -593,9 +599,9 @@ 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` / `final-verification` 전용: 실행(검증)할 Stage Map 항목 지정. `implementation` 은 `auto` (기본값) = 의존성이 만족된 가장 빠른 미완료 stage, `<N>` = 강제 지정. `final-verification` 은 `<N>` = 해당 stage 단독 검증(산출물이 `runs/final-verification/stage-<N>/` 에 격리되고 팀 이름에 `-fv-s<N>` 접미사), 빈 값 = 전체-task 검증(평면 구조 유지) |
+| `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>]` | `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 검증(평면 구조 유지). `--stages <csv>` 는 `release-handoff` 전용(별개 채널): PR 로 묶을 stage 번호들(stage-group 모드), 빈 값 = whole-task 모드. prepare 가 eligibility(`done`+`verified` accepted+미-`pr`)를 강제하고 검증 보고서 인용 input 문서를 자동 생성한다 |
 | `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 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` 으로 넘어갑니다. brief 단계는 entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 나오며, downstream 은 manifest 의 brief 를 자동 carry-in 하고(미등록 시 `brief_carry` 3-옵션 fallback), `release-handoff` 는 brief 없이 `handoff_stage_pick` 멀티선택(eligible stage 묶음 / 전체 task)으로 진입합니다 |
 | `okstra token-usage ...` | 설치된 `okstra-token-usage.py` 를 감싸 run token usage 수집/치환을 수행. 세션 jsonl 은 기본적으로 `$OKSTRA_HOME/cache/token-usage/` 의 byte cursor 캐시로 증분 스캔하며, `--no-cache` 로 캐시를 우회해 전체 재스캔을 강제할 수 있음(정확성 폴백) |
 
 > 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/_python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.

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/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.70.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.70.0",
-  "builtAt": "2026-06-10T17:00:34.215Z",
+  "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}",
@@ -371,6 +407,8 @@
   "confirmation": {
     "header": "선택 확인:",
     "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)",
-    "stage_whole_task": "전체 task"
+    "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/run.py

@@ -291,6 +291,10 @@ class PrepareInputs:
     # prepare-time 에 task-level conformance 매니페스트 entry.waiver 를 채운다.
     qa_waiver: str = ""
     stage: str = "auto"
+    # release-handoff 전용: PR 로 내보낼 stage 묶음 (csv, 예: "2,3"). 빈 값 =
+    # whole-task 모드. `--stage`(impl/fv 의 Stage Map 실행/검증 선택)와는
+    # 별개 채널이다.
+    stages: str = ""
     clarification_response_path: str = ""  # absolute or empty
     # release-handoff 전용: PR 본문 템플릿 1회성 override. 빈 문자열이면
     # project.json → global config → 스킬 디폴트 순으로 해석된다.
@@ -1064,7 +1068,17 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     를 검증하고, implementation 일 때 stage map 을 파싱해 돌려준다 (그 외엔 빈 리스트)."""
     if not project_root.is_dir():
         raise PrepareError(f"project root not found: {project_root}")
-    if not inp.brief_path.is_file():
+    if inp.stages and inp.task_type != "release-handoff":
+        raise PrepareError(
+            "--stages is only meaningful with --task-type release-handoff; "
+            f"got {inp.task_type}"
+        )
+    if inp.task_type == "release-handoff":
+        # brief 는 entry phase 의 입력물 — release-handoff 는 검증 보고서를
+        # 인용하는 input 문서를 prepare 가 직접 생성해 brief 자리에 채운다
+        # (_materialize_release_handoff_input, 이 검증 직후 실행).
+        pass
+    elif not inp.brief_path.is_file():
         raise PrepareError(f"task brief not found: {inp.brief_path}")
     ctx_stage_map: list = []
     # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
@@ -1121,7 +1135,9 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
                 "--implementation-option is only meaningful with --task-type "
                 "implementation and --approved-plan <path>"
             )
-        if inp.stage != "auto":
+        # wizard 는 모든 flag 를 빈 값 포함 항상 전달하므로(`--stage ""`),
+        # 빈 문자열은 "stage 미지정" 으로 받아들인다.
+        if inp.stage not in ("", "auto"):
             raise PrepareError(
                 "--stage is only meaningful with --task-type implementation or "
                 f"final-verification; got {inp.task_type}"
@@ -1133,6 +1149,113 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     return ctx_stage_map
 
 
+def _collect_handoff_source_report_rows(
+    rows: list, nums: list,
+) -> list:
+    """선택 stage 들의 마지막 verified 행에서 인용 표 행을 만든다 (last-wins)."""
+    last_verified: dict = {}
+    for r in rows:
+        if r.get("status") == "verified" and isinstance(r.get("stage"), int):
+            last_verified[r["stage"]] = r
+    return [
+        f"| {n} | {last_verified[n].get('report_path', '')} "
+        f"| `{last_verified[n].get('verdict', '')}` |"
+        for n in nums
+    ]
+
+
+def _materialize_release_handoff_input(
+    workspace_root: Path, project_root: Path, inp: "PrepareInputs",
+) -> dict:
+    """release-handoff 의 입력 문서를 검증 보고서 인용으로 자동 생성한다.
+
+    brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 이 run 의
+    `--task-brief` 자리는 여기서 생성된 input 문서가 채운다. stage 자격은
+    okstra_ctl.handoff 의 SSOT 판정을 prepare 에서도 그대로 강제한다.
+    반환: ctx 에 올릴 {"HANDOFF_MODE": ..., "HANDOFF_STAGES": ...}."""
+    from .consumers import read_consumers
+    from .handoff import (HandoffError, _require_eligible,
+                          latest_whole_task_fv_accepted)
+    from .paths import task_dir
+    from .render import render_template_with_ctx
+    from .run_context import _now_task_date
+
+    # Path("") 는 "." 로 정규화된다 — 빈 brief 센티널은 둘 다로 들어올 수 있다.
+    if str(inp.brief_path).strip() not in ("", "."):
+        raise PrepareError(
+            "--task-brief is not accepted for --task-type release-handoff — "
+            "the input document is generated from the cited final-verification "
+            "reports (pick stages via --stages, or leave it empty for "
+            "whole-task)"
+        )
+    if not inp.approved_plan_path:
+        raise PrepareError(
+            "release-handoff requires --approved-plan "
+            "<implementation-planning final-report> — the Stage Map and the "
+            "consumers ledger drive stage eligibility"
+        )
+    plan = Path(inp.approved_plan_path)
+    if not plan.is_file():
+        raise PrepareError(f"approved plan not found: {plan}")
+    stage_map = _parse_stage_map_into_ctx(str(plan))
+    if not stage_map:
+        raise PrepareError(f"approved plan has no parsable Stage Map: {plan}")
+    rows = read_consumers(plan.resolve().parents[1])
+
+    if inp.stages:
+        try:
+            nums = sorted({int(x) for x in inp.stages.split(",") if x.strip()})
+        except ValueError:
+            raise PrepareError(
+                f"--stages must be a comma-separated int list, got {inp.stages!r}"
+            )
+        if not nums:
+            raise PrepareError("--stages must select at least one stage")
+        try:
+            _require_eligible(stage_map, rows, nums)
+        except HandoffError as exc:
+            raise PrepareError(str(exc)) from exc
+        mode = "stage-group"
+        stages_csv = ",".join(str(n) for n in nums)
+        report_rows = _collect_handoff_source_report_rows(rows, nums)
+    else:
+        report = latest_whole_task_fv_accepted(
+            project_root, inp.project_id, inp.task_group, inp.task_id)
+        if not report:
+            raise PrepareError(
+                "whole-task release-handoff requires an accepted whole-task "
+                "final-verification report — run final-verification first, "
+                "or pass --stages <csv> for a stage-group PR"
+            )
+        mode = "whole-task"
+        stages_csv = ""
+        report_relative = relative_to_project_root(Path(report), project_root)
+        report_rows = [f"| (all) | {report_relative or report} | `accepted` |"]
+
+    template = (workspace_root / "templates" / "reports"
+                / "release-handoff-input.template.md")
+    if not template.is_file():
+        raise PrepareError(
+            f"release-handoff input template missing: {template}.{_INSTALL_HINT}"
+        )
+    out = (task_dir(project_root, inp.task_group, inp.task_id)
+           / "release-handoff-input.md")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    render_template_with_ctx(str(template), str(out), {
+        "TASK_KEY": f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
+        "TASK_ID": inp.task_id,
+        "TASK_GROUP": inp.task_group,
+        "PROJECT_ID": inp.project_id,
+        "TASK_TYPE": inp.task_type,
+        "TASK_DATE": _now_task_date(),
+        "HANDOFF_MODE": mode,
+        "HANDOFF_STAGES": stages_csv or "(all)",
+        "HANDOFF_SOURCE_REPORTS": "\n".join(report_rows),
+    })
+    inp.brief_path = out
+    return {"HANDOFF_MODE": mode, "HANDOFF_STAGES": stages_csv}
+
+
 def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
     """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다."""
     if not inp.qa_waiver:
@@ -1822,6 +1945,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     final_report_template = assets.final_report_template
     ctx_stage_map = _validate_prepare_inputs(project_root, inp)
 
+    # release-handoff: 검증 보고서 인용 input 문서를 생성해 brief 자리에 채운다.
+    # 이후의 모든 brief 소비 경로(material/instruction-set 복사)는 그대로 동작한다.
+    handoff_tokens = {"HANDOFF_MODE": "", "HANDOFF_STAGES": ""}
+    if inp.task_type == "release-handoff":
+        handoff_tokens = _materialize_release_handoff_input(
+            workspace_root, project_root, inp)
+
     verify_installation(workspace_root)
     _register_and_check_project(project_root, inp)
 
@@ -1989,6 +2119,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "RECOMMENDED_ANALYSERS": selected_reviewers,
         "PR_TEMPLATE_PATH": pr_template_path_str,
         "PR_TEMPLATE_SOURCE": pr_template_source,
+        **handoff_tokens,
         "CLAUDE_SESSION_ID": claude_session_id,
         "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
         "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
@@ -2113,7 +2244,14 @@ def main(argv: list[str]) -> int:
     p.add_argument("--task-group", required=True)
     p.add_argument("--task-id", required=True)
     p.add_argument("--task-type", required=True)
-    p.add_argument("--task-brief", required=True, dest="task_brief")
+    p.add_argument(
+        "--task-brief", default="", dest="task_brief",
+        help=(
+            "Required for every task-type except release-handoff (whose input "
+            "document is generated by prepare from the cited "
+            "final-verification reports)."
+        ),
+    )
     p.add_argument("--directive", default="")
     p.add_argument("--workers", default="", dest="workers_override")
     p.add_argument("--lead-model", default="")
@@ -2135,6 +2273,15 @@ def main(argv: list[str]) -> int:
             "consumers.jsonl status:done. Numeric '<N>' = force that stage."
         ),
     )
+    p.add_argument(
+        "--stages", default="", dest="stages",
+        help=(
+            "release-handoff only. Comma-separated stage numbers to bundle "
+            "into one PR (stage-group mode); empty = whole-task mode. "
+            "Distinct from --stage (implementation/final-verification "
+            "Stage Map selection)."
+        ),
+    )
     p.add_argument(
         "--approve",
         action="store_true",
@@ -2206,10 +2353,22 @@ def main(argv: list[str]) -> int:
     args = p.parse_args(argv)
 
     project_root = Path(args.project_root).expanduser().resolve()
-    brief_abs = resolve_user_file(args.task_brief, project_root)
-    if brief_abs is None:
-        print(f"task brief not found: {args.task_brief}", file=__import__("sys").stderr)
-        return 1
+    if args.task_type == "release-handoff":
+        if args.task_brief:
+            print(
+                "--task-brief is not accepted for --task-type release-handoff "
+                "— the input document is generated from the cited "
+                "final-verification reports",
+                file=__import__("sys").stderr,
+            )
+            return 1
+        brief_abs = Path("")  # prepare 가 input 문서를 생성해 채운다
+    else:
+        brief_abs = resolve_user_file(args.task_brief, project_root)
+        if brief_abs is None:
+            print(f"task brief not found: {args.task_brief}",
+                  file=__import__("sys").stderr)
+            return 1
     clarification_abs = ""
     if args.clarification_response_path:
         cr = resolve_user_file(args.clarification_response_path, project_root)
@@ -2244,6 +2403,7 @@ def main(argv: list[str]) -> int:
         approved_plan_path=args.approved_plan_path,
         qa_waiver=args.qa_waiver,
         stage=args.stage,
+        stages=args.stages,
         clarification_response_path=clarification_abs,
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,

package/runtime/python/okstra_ctl/wizard.py

@@ -88,6 +88,13 @@ EXECUTORS = ["claude", "codex", "gemini"]
 # (or the whole task via `auto`). Both gate the approved-plan + stage steps.
 _STAGE_SCOPED_TASK_TYPES = ("implementation", "final-verification")
 
+# brief 는 entry phase 의 입력물(비개발자/타 팀의 아이디어·에러 초안)이다.
+# downstream phase 는 task manifest 의 taskBriefPath 를 자동 carry-in 하며
+# 위저드에서 brief 를 묻지 않는다 (release-handoff 는 prepare 가 검증 보고서
+# 인용 input 문서를 자동 생성하므로 brief 자체가 없다).
+_BRIEF_ENTRY_TASK_TYPES = ("requirements-discovery", "improvement-discovery",
+                           "error-analysis")
+
 CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
 BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
 
@@ -230,12 +237,14 @@ S_TASK_TYPE_TEXT = "task_type_text"
 S_BRIEF_KEEP = "brief_keep"
 S_BRIEF_PATH_PICK = "brief_path_pick"
 S_BRIEF_PATH = "brief_path"
+S_BRIEF_CARRY = "brief_carry"
 S_BASE_REF_PICK = "base_ref_pick"
 S_BASE_REF_TEXT = "base_ref_text"
 S_APPROVED_PLAN_PICK = "approved_plan_pick"
 S_APPROVED_PLAN = "approved_plan"
 S_APPROVE_PLAN_CONFIRM = "approve_plan_confirm"
 S_STAGE_PICK = "stage_pick"
+S_HANDOFF_STAGE_PICK = "handoff_stage_pick"
 S_EXECUTOR = "executor"
 S_CRITIC_PICK = "critic_pick"
 S_CRITIC_TEXT = "critic_text"
@@ -334,6 +343,11 @@ class WizardState:
     critic: str = ""
     critic_pending_text: bool = False
 
+    # release-handoff: PR 로 내보낼 범위. mode 는 stages 선택의 파생값이다 —
+    # whole-task = 빈 stages(whole-task 검증 기반 단일 PR), stage-group = csv.
+    handoff_mode: str = ""  # "" | "whole-task" | "stage-group"
+    handoff_stages: str = ""  # csv ("2,3"), whole-task 면 ""
+
     # resume: 직전 run-inputs 재사용 여부 (None=미응답, True=재사용, False=재입력)
     reuse_previous: Optional[bool] = None
 
@@ -767,6 +781,11 @@ def _base_ref_required(state: WizardState) -> bool:
     return state.task_type != "final-verification" and state.reuse_worktree is False
 
 
+def _brief_resolved(state: WizardState) -> bool:
+    """brief 입력이 끝났는가. release-handoff 는 brief 가 없는 phase 라 항상 True."""
+    return bool(state.brief_path) or state.task_type == "release-handoff"
+
+
 def _base_ref_ready(state: WizardState) -> bool:
     return not _base_ref_required(state) or S_BASE_REF_PICK in state.answered
 
@@ -1215,6 +1234,23 @@ def _build_task_type(state: WizardState) -> Prompt:
                   echo_template=t["echo_template"])
 
 
+def _carry_in_existing_brief(state: WizardState) -> str:
+    """downstream task-type 이 등록된 brief 를 자동 carry-in 한다. 주입한 경로(또는 '')."""
+    if state.task_type in _BRIEF_ENTRY_TASK_TYPES:
+        return ""
+    if state.task_type == "release-handoff":
+        return ""  # prepare 가 검증 보고서 인용 input 문서를 자동 생성한다
+    if state.brief_path or not state.existing_brief_path:
+        return ""
+    p = Path(state.existing_brief_path)
+    if not p.is_absolute():
+        p = Path(state.project_root) / p
+    if not p.is_file():
+        return ""  # manifest 경로가 깨졌으면 brief_carry 단계가 처리한다
+    state.brief_path = state.existing_brief_path
+    return state.brief_path
+
+
 def _apply_task_type(state: WizardState, value: str) -> str:
     if value not in TASK_TYPE_VALUES:
         raise WizardError(
@@ -1222,6 +1258,11 @@ def _apply_task_type(state: WizardState, value: str) -> str:
             f"(expected one of: {', '.join(TASK_TYPE_VALUES)})"
         )
     state.task_type = value
+    # brief_carry 의 "entry phase 로 전환" 이 task-type 을 리셋한 뒤 submit() 이
+    # brief_carry 를 answered 로 되돌려 놓는다 — task-type 을 다시 고르는 시점에
+    # 퍼지해야 downstream 재선택 시 carry 단계가 다시 나온다.
+    state.answered = [a for a in state.answered if a != S_BRIEF_CARRY]
+    carried = _carry_in_existing_brief(state)
     state.profile_workers = _load_profile_workers(
         Path(state.workspace_root), value
     )
@@ -1231,6 +1272,8 @@ def _apply_task_type(state: WizardState, value: str) -> str:
     # Reuse-worktree is decided once identity is final. Recompute here so
     # subsequent base-ref step knows whether to apply.
     state.reuse_worktree = _resolve_reuse_worktree(state)
+    if carried:
+        return f"task-type: {value}\nbrief (carry-in): {carried}"
     return f"task-type: {value}"
 
 
@@ -1357,6 +1400,37 @@ def _submit_brief_path(state: WizardState, value: str) -> Optional[str]:
     return f"brief: {p}"
 
 
+BRIEF_CARRY_SWITCH_ENTRY = "__switch_entry__"
+BRIEF_CARRY_ABORT = "__abort__"
+
+
+def _build_brief_carry(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "brief_carry", task_type=state.task_type)
+    return Prompt(
+        step=S_BRIEF_CARRY, kind="pick",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_brief_carry(state: WizardState, value: str) -> Optional[str]:
+    t = _p(state.workspace_root, "brief_carry", task_type=state.task_type)
+    if value == BRIEF_CARRY_SWITCH_ENTRY:
+        _reset_from(state, S_TASK_TYPE)
+        return t["echo_variants"]["switch_entry"]
+    if value == PICK_TYPE_CUSTOM:
+        state.brief_path_pending_text = True
+        return None
+    if value == BRIEF_CARRY_ABORT:
+        state.aborted = True
+        return t["echo_variants"]["abort"]
+    raise WizardError(
+        f"expected '{BRIEF_CARRY_SWITCH_ENTRY}', {PICK_TYPE_CUSTOM!r}, "
+        f"or '{BRIEF_CARRY_ABORT}', got: {value!r}"
+    )
+
+
 def _build_base_ref_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "base_ref_pick")
     recommended_suffix = t["options"].get("_RECOMMENDED_SUFFIX", "")
@@ -1602,6 +1676,105 @@ def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
     return f"stage: {answer}"
 
 
+def _handoff_msgs(state: WizardState) -> dict:
+    """handoff_stage_pick 의 JSON 텍스트 묶음 (label 미사용 조회용)."""
+    return _p(state.workspace_root, "handoff_stage_pick", blocked="")
+
+
+def _resolve_handoff_plan(state: WizardState) -> Path:
+    """release-handoff 의 approved plan 을 질문 없이 자동 해소한다.
+
+    plan 미존재/미승인은 사용자가 고칠 대상이 아니라 라이프사이클 선행 단계
+    누락이므로 picker 대신 안내 메시지로 즉시 실패한다."""
+    if state.approved_plan_path:
+        return Path(state.approved_plan_path)
+    t = _handoff_msgs(state)
+    latest = _latest_implementation_planning_report(state)
+    if latest is None:
+        raise WizardError(t["errors"]["no_plan"])
+    p, fully_approved = _classify_approved_plan(
+        str(latest), Path(state.project_root))
+    if not fully_approved:
+        raise WizardError(t["errors"]["plan_not_approved"].format(plan=p))
+    state.approved_plan_path = str(p)
+    return p
+
+
+def _handoff_eligibility(state: WizardState) -> list:
+    """stage 별 PR 자격 — okstra_ctl.handoff 의 SSOT 판정을 그대로 재사용한다."""
+    from okstra_ctl.handoff import compute_eligibility
+    from okstra_ctl.run import _parse_stage_map_into_ctx
+    from okstra_ctl.consumers import read_consumers
+    plan = _resolve_handoff_plan(state)
+    stage_map = _parse_stage_map_into_ctx(str(plan))
+    if not stage_map:
+        raise WizardError(
+            _handoff_msgs(state)["errors"]["no_stage_map"].format(plan=plan))
+    rows = read_consumers(plan.resolve().parents[1])
+    return compute_eligibility(stage_map, rows)
+
+
+def _latest_whole_task_fv_accepted(state: WizardState) -> str:
+    """accepted whole-task final-verification 보고서 경로 — handoff 모듈 SSOT 위임."""
+    from okstra_ctl.handoff import latest_whole_task_fv_accepted
+    return latest_whole_task_fv_accepted(
+        state.project_root, state.project_id, state.task_group, state.task_id)
+
+
+def _build_handoff_stage_pick(state: WizardState) -> Prompt:
+    elig = _handoff_eligibility(state)
+    eligible = [e for e in elig if e["eligible"]]
+    blocked = [e for e in elig if not e["eligible"]]
+    whole_task_report = _latest_whole_task_fv_accepted(state)
+    msgs = _handoff_msgs(state)
+    blocked_summary = ("; ".join(
+        f"stage {e['stage']} ({', '.join(e['reasons'])})" for e in blocked)
+        or msgs["labels"]["blocked_none"])
+    if not eligible and not whole_task_report:
+        raise WizardError(
+            msgs["errors"]["nothing_eligible"].format(blocked=blocked_summary))
+    t = _p(state.workspace_root, "handoff_stage_pick", blocked=blocked_summary)
+    options: list[Option] = []
+    if whole_task_report:
+        options.append(_opt(WHOLE_TASK_STAGE, t["labels"]["whole_task"]))
+    stage_label = t["labels"]["stage"]
+    for e in eligible:
+        deps = ", ".join(str(d) for d in e["depends_on"]) or "-"
+        options.append(_opt(str(e["stage"]),
+                            stage_label.format(stage=e["stage"], deps=deps)))
+    return Prompt(
+        step=S_HANDOFF_STAGE_PICK, kind="pick", multi=True,
+        label=t["label"], options=options,
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_handoff_stage_pick(state: WizardState, value: str) -> Optional[str]:
+    t = _handoff_msgs(state)
+    picks = [v.strip() for v in (value or "").split(",") if v.strip()]
+    if not picks:
+        raise WizardError(t["errors"]["none_selected"])
+    if WHOLE_TASK_STAGE in picks:
+        if len(picks) > 1:
+            raise WizardError(t["errors"]["whole_task_exclusive"])
+        if not _latest_whole_task_fv_accepted(state):
+            raise WizardError(t["errors"]["whole_task_missing"])
+        state.handoff_mode = "whole-task"
+        state.handoff_stages = ""
+        return t["echo_variants"]["whole_task"]
+    eligible = {str(e["stage"]) for e in _handoff_eligibility(state)
+                if e["eligible"]}
+    bad = [p for p in picks if p not in eligible]
+    if bad:
+        raise WizardError(t["errors"]["not_eligible"].format(
+            bad=", ".join(bad), eligible=", ".join(sorted(eligible))))
+    nums = sorted({int(p) for p in picks})
+    state.handoff_mode = "stage-group"
+    state.handoff_stages = ",".join(str(n) for n in nums)
+    return t["echo_variants"]["stage_group"].format(
+        stages=state.handoff_stages)
+
+
 def _suggest_latest_final_report(state: WizardState) -> str:
     """task 의 모든 phase runs 디렉토리에서 가장 최근 final-report-*.md 의 relpath 를 반환.
 
@@ -2364,16 +2537,40 @@ STEPS: list[Step] = [
                             and s.task_group_pending_text),
          build=_build_task_group_text, submit=_submit_task_group_text,
          owns=("task_group", "task_group_pending_text")),
+    # 신규 task 흐름 순서: task-group → task-type → (entry 면 brief) → task-id.
+    # brief 는 entry phase 전용 입력이므로 task-type 이 정해진 뒤에만 물을 수 있다.
+    Step(S_TASK_TYPE,
+         applies=lambda s: (s.is_new_task is not None
+                            and (s.is_new_task is False or bool(s.task_group))
+                            and S_TASK_TYPE not in s.answered),
+         build=_build_task_type, submit=_submit_task_type,
+         owns=("task_type", "profile_workers", "profile_optional_workers",
+               "reuse_worktree")),
+    Step(S_TASK_TYPE_TEXT,
+         applies=lambda s: (S_TASK_TYPE in s.answered
+                            and not s.task_type
+                            and S_TASK_TYPE_TEXT not in s.answered),
+         build=_build_task_type_text, submit=_submit_task_type_text,
+         owns=("task_type", "profile_workers", "profile_optional_workers",
+               "reuse_worktree")),
+    Step(S_BRIEF_KEEP,
+         applies=lambda s: (not s.is_new_task
+                            and s.task_type in _BRIEF_ENTRY_TASK_TYPES
+                            and bool(s.existing_brief_path)
+                            and s.keep_existing_brief is None
+                            and S_TASK_TYPE in s.answered),
+         build=_build_brief_keep, submit=_submit_brief_keep,
+         owns=("keep_existing_brief",)),
     Step(S_BRIEF_PATH_PICK,
          applies=lambda s: (
              not s.brief_path
              and not s.brief_path_pending_text
              and S_BRIEF_PATH_PICK not in s.answered
+             and S_TASK_TYPE in s.answered
+             and s.task_type in _BRIEF_ENTRY_TASK_TYPES
              and (
-                 (s.is_new_task is True and bool(s.task_group))
+                 s.is_new_task is True
                  or (s.is_new_task is False
-                     and S_TASK_TYPE in s.answered
-                     and bool(s.task_type)
                      and (s.keep_existing_brief is False
                           or not s.existing_brief_path))
              )
@@ -2385,49 +2582,39 @@ STEPS: list[Step] = [
                             and S_BRIEF_PATH not in s.answered,
          build=_build_brief_path, submit=_submit_brief_path,
          owns=("brief_path", "task_group_suggestion", "task_id_suggestion")),
+    # downstream task-type 인데 carry-in 할 brief 가 없을 때의 fallback.
+    # release-handoff 는 brief 자체가 없는 phase 라 대상에서 빠진다.
+    Step(S_BRIEF_CARRY,
+         applies=lambda s: (S_TASK_TYPE in s.answered
+                            and bool(s.task_type)
+                            and s.task_type not in _BRIEF_ENTRY_TASK_TYPES
+                            and s.task_type != "release-handoff"
+                            and not s.brief_path
+                            and not s.brief_path_pending_text),
+         build=_build_brief_carry, submit=_submit_brief_carry,
+         owns=("brief_path_pending_text",)),
     Step(S_TASK_ID,
          applies=lambda s: (bool(s.is_new_task)
-                            and bool(s.brief_path)
                             and bool(s.task_group)
+                            and _brief_resolved(s)
                             and not s.task_id
                             and not s.task_id_pending_text),
          build=_build_task_id, submit=_submit_task_id,
          owns=("task_id", "task_id_pending_text")),
     Step(S_TASK_ID_TEXT,
          applies=lambda s: (bool(s.is_new_task)
-                            and bool(s.brief_path)
                             and bool(s.task_group)
+                            and _brief_resolved(s)
                             and not s.task_id
                             and s.task_id_pending_text),
          build=_build_task_id_text, submit=_submit_task_id_text,
          owns=("task_id", "task_id_pending_text")),
-    Step(S_TASK_TYPE,
-         applies=lambda s: (s.is_new_task is not None
-                            and (s.is_new_task is False or bool(s.task_id))
-                            and S_TASK_TYPE not in s.answered),
-         build=_build_task_type, submit=_submit_task_type,
-         owns=("task_type", "profile_workers", "profile_optional_workers",
-               "reuse_worktree")),
-    Step(S_TASK_TYPE_TEXT,
-         applies=lambda s: (S_TASK_TYPE in s.answered
-                            and not s.task_type
-                            and S_TASK_TYPE_TEXT not in s.answered),
-         build=_build_task_type_text, submit=_submit_task_type_text,
-         owns=("task_type", "profile_workers", "profile_optional_workers",
-               "reuse_worktree")),
-    Step(S_BRIEF_KEEP,
-         applies=lambda s: (not s.is_new_task
-                            and bool(s.existing_brief_path)
-                            and s.keep_existing_brief is None
-                            and S_TASK_TYPE in s.answered
-                            and bool(s.task_type)),
-         build=_build_brief_keep, submit=_submit_brief_keep,
-         owns=("keep_existing_brief",)),
     Step(S_BASE_REF_PICK,
          applies=lambda s: (S_TASK_TYPE in s.answered
                             and _base_ref_required(s)
                             and S_BASE_REF_PICK not in s.answered
-                            and bool(s.brief_path)),
+                            and _brief_resolved(s)
+                            and (not s.is_new_task or bool(s.task_id))),
          build=_build_base_ref_pick, submit=_submit_base_ref_pick,
          owns=("base_ref", "base_ref_pending_text")),
     Step(S_BASE_REF_TEXT,
@@ -2468,6 +2655,13 @@ STEPS: list[Step] = [
                             and S_STAGE_PICK not in s.answered),
          build=_build_stage_pick, submit=_submit_stage_pick,
          owns=("selected_stage",)),
+    Step(S_HANDOFF_STAGE_PICK,
+         applies=lambda s: (s.task_type == "release-handoff"
+                            and bool(s.task_group)
+                            and bool(s.task_id)
+                            and S_HANDOFF_STAGE_PICK not in s.answered),
+         build=_build_handoff_stage_pick, submit=_submit_handoff_stage_pick,
+         owns=("handoff_mode", "handoff_stages", "approved_plan_path")),
     Step(S_EXECUTOR,
          applies=lambda s: (s.task_type == "implementation"
                             and bool(s.approved_plan_path)
@@ -2644,7 +2838,8 @@ def _identity_ready(s: WizardState) -> bool:
     """All identity questions (task pick → executor for impl) answered."""
     if not s.task_type:
         return False
-    if not s.brief_path:
+    # release-handoff 는 brief 가 없다 — prepare 가 검증 보고서 인용 input 을 생성한다.
+    if not s.brief_path and s.task_type != "release-handoff":
         return False
     if _base_ref_required(s) and S_BASE_REF_PICK not in s.answered:
         return False
@@ -2656,6 +2851,9 @@ def _identity_ready(s: WizardState) -> bool:
     if s.task_type == "implementation":
         if not s.executor:
             return False
+    if (s.task_type == "release-handoff"
+            and S_HANDOFF_STAGE_PICK not in s.answered):
+        return False
     return True
 
 
@@ -2708,6 +2906,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "base_ref_pending_text": False, "approved_plan_path": "",
     "approved_plan_pending_text": False,
     "selected_stage": "auto",
+    "handoff_mode": "", "handoff_stages": "",
     "executor": "", "critic": "", "critic_pending_text": False,
     "reuse_previous": None,
     "use_defaults": None, "workers_override": "",
@@ -2873,6 +3072,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "critic": state.critic,
         "approved-plan": state.approved_plan_path,
         "stage": stage,
+        "stages": state.handoff_stages,
         "base-ref": base_ref,
         "workers": workers,
         "directive": state.directive,
@@ -2934,6 +3134,16 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  stage         : {stage}")
     if state.clarification_response_path:
         lines.append(f"  clarification : {state.clarification_response_path}")
+    if state.task_type == "release-handoff" and state.handoff_mode:
+        scope = (
+            _msg(state.workspace_root, "confirmation",
+                 "handoff_scope_whole_task")
+            if state.handoff_mode == "whole-task"
+            else _msg(state.workspace_root, "confirmation",
+                      "handoff_scope_stage_group",
+                      stages=state.handoff_stages)
+        )
+        lines.append(f"  handoff scope : {scope}")
     if state.task_type == "release-handoff" and state.pr_template_path:
         lines.append(f"  pr-template   : {state.pr_template_path} ({state.pr_template_scope or 'once'})")
     return "\n".join(lines)

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

@@ -121,9 +121,10 @@ That is the entire interactive flow. The wizard handles:
 
 - new-vs-existing task split (남은 작업 — `workStatus != done` — 최신순 3개 추천 + 직접 입력), task-group / task-id slug validation (각각 최근 후보 3개 추천 + 직접 입력),
 - task-type pick (추천 3개 — `nextRecommendedPhase` recommended / 현재 phase 재실행 / 라이프사이클 다음 단계 — + 직접 입력; 직접 입력은 후속 `text` 단계에서 전체 task-type 화이트리스트로 검증),
-- brief path after task-group selection (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing tasks),
+- brief path — **entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 질문** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing entry tasks). downstream task-type 은 manifest 의 brief 를 자동 carry-in 하고, 등록 brief 가 없으면 `brief_carry` 3-옵션(entry 전환 추천 / 직접 입력 / 중단)이 뜬다. `release-handoff` 는 brief 단계가 아예 없다 — prepare 가 검증 보고서 인용 input 문서를 생성한다,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick,
+- `release-handoff`-only sub-flow: approved plan 자동 해소 후 `handoff_stage_pick` 멀티선택 — eligible stage 묶음(stage-group) 또는 전체 task(accepted whole-task 검증 보고서 존재 시) 선택; 결과는 render-args 의 `stages` 키(csv, whole-task 면 빈 값)로 나간다,
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
@@ -166,6 +167,7 @@ okstra render-bundle \
   --critic       "<args.critic>" \
   --approved-plan "<args.approved-plan>" \
   --stage        "<args.stage>" \
+  --stages       "<args.stages>" \
   --base-ref     "<args.base-ref>" \
   --workers      "<args.workers>" \
   --directive    "<args.directive>" \

package/runtime/templates/reports/release-handoff-input.template.md

@@ -25,11 +25,15 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Source Verification Report
 
-- Path (project-relative) to the `final-verification` final-report whose verdict authorises this handoff:
-- Verbatim quoted `Verdict Token` row from that report's `## 7. Final Verdict` table (MUST have value `accepted`):
-- Run timestamp of that final-verification run:
+- Mode: `{{HANDOFF_MODE}}`
+- Stages: `{{HANDOFF_STAGES}}`
+- Reports (one row per cited `final-verification` final-report; every Verdict Token MUST be `accepted`):
 
-> If this section is empty or cites a `Verdict Token` value other than `accepted`, the lead MUST end the run immediately and route back to `final-verification`. Release-handoff never operates on `conditional-accept` or `blocked` outcomes.
+| Stage | Report path (project-relative) | Verdict Token |
+|---|---|---|
+{{HANDOFF_SOURCE_REPORTS}}
+
+> This section is generated by `okstra render-bundle` from the consumers ledger (`verified` rows) / the latest accepted whole-task report — the lead re-confirms each cited report's `Verdict Token` and MUST end the run immediately (route back to `final-verification`) if any token is not `accepted`. Release-handoff never operates on `conditional-accept` or `blocked` outcomes.
 
 ## Working-Tree Snapshot (filled at run start)
 
@@ -83,5 +87,5 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Conversion Note
 
-- This input can be used as the release-handoff brief before creating `okstra-task-brief.md`.
-- Reuse the same `Task Group` and `Task ID` as the originating implementation / final-verification runs so the handoff stays attached to the same task history.
+- This document is generated by `okstra render-bundle --task-type release-handoff` and serves as the run's input in place of a task brief (briefs belong to entry phases only).
+- It reuses the same `Task Group` and `Task ID` as the originating implementation / final-verification runs so the handoff stays attached to the same task history.

package/src/render-bundle.mjs

@@ -18,7 +18,15 @@ Usage:
     [--gemini-model <m>] [--report-writer-model <m>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
-    [--pr-template-path <path>]   # release-handoff only
+    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>]
+
+  --stage             implementation / final-verification only
+  --stages            release-handoff only: PR stage bundle csv (empty = whole-task)
+  --pr-template-path  release-handoff only
+
+release-handoff takes NO --task-brief (briefs belong to entry phases) —
+prepare generates the run's input document from the cited verification
+reports instead.
 
 All flags pass through unchanged to \`python3 -m okstra_ctl.run\`. The
 shim auto-supplies \`--workspace-root\` (from \`okstra paths --field workspace\`)