okstra 0.102.2 → 0.102.3

package/docs/superpowers/specs/2026-06-10-stage-group-handoff-design.md

@@ -1,156 +0,0 @@
-# release-handoff stage-group 모드 — 설계
-
-- 작성일: 2026-06-10
-- 상태: 설계 승인됨 (사용자 승인 2026-06-10)
-- 선행: [stage-worktree-isolation-design.md](2026-06-06-stage-worktree-isolation-design.md), [final-verification-whole-task-gate-design.md](2026-06-06-final-verification-whole-task-gate-design.md)
-
-## 1. 배경 / 문제
-
-stage-worktree-isolation 모델에서 implementation 은 **1 run = 1 stage** 이고 stage 마다 격리 브랜치(`<prefix>-<task-id>-s<N>`)가 생긴다. 정식 release 경로는 "모든 stage 를 task-key 브랜치에 수동 머지 → whole-task final-verification `accepted` → release-handoff 로 task 당 PR 1개" 다 ([final-verification.md:40](../../../prompts/profiles/final-verification.md:40)).
-
-문제: stage 단위가 작을 때 task 전체가 끝나기를 기다렸다 PR 하나로 내거나, 반대로 stage 하나짜리 PR 을 여러 번 내는 것 둘 다 비효율이다. 사용자는 **한 task 안에서 stage 일부를 골라 묶어 하나의 PR** 로 내고 싶다 (예: stage 2+3 → PR 1, stage 4+5 → PR 2).
-
-현재 계약이 이를 막는 지점 세 곳:
-
-1. release-handoff 진입 게이트가 whole-task `accepted` 보고서 1개를 요구 ([release-handoff.md:14](../../../prompts/profiles/release-handoff.md:14)).
-2. 단독-stage 검증은 release-handoff 라우팅 금지 ([final-verification.md:29](../../../prompts/profiles/final-verification.md:29), [final-verification.md:40](../../../prompts/profiles/final-verification.md:40)).
-3. release-handoff 는 커밋 생성 금지 ([release-handoff.md:57](../../../prompts/profiles/release-handoff.md:57)) + "okstra 자동 머지 없음" 비목표 ([stage-worktree-isolation-design.md:7](2026-06-06-stage-worktree-isolation-design.md)) — 독립 stage 들은 서로 다른 브랜치에 있어 묶음 PR 의 head 브랜치를 만들 주체가 없다.
-
-## 2. 결정 요약 (브레인스토밍 Q&A)
-
-| 결정점 | 선택 |
-|---|---|
-| 묶음 단위 | 한 task 안의 **stage 일부 그룹** → PR 1개 |
-| 그룹 결정 시점 | **release-handoff 실행 중** 사용자가 PR 가능 stage 목록에서 선택 |
-| 수집 브랜치(그룹 머지) 소유 | **release-handoff** 가 수집 브랜치 생성 + stage 브랜치 merge |
-| 검증 게이트 | **stage 별 단독-stage `accepted` 합산** — 그룹 내 모든 stage 가 각자 accepted 면 진입 허용. 머지된 조합 자체는 미검증이며 충돌 프로브 + PR CI 가 보완 |
-| 의존 폐포 위반 시 | **차단 + 안내** (선행 자동 포함 아님 — 조용한 범위 확장 방지) |
-
-## 3. 목표 / 비목표
-
-목표:
-- release-handoff 에 **stage-group 모드** 추가: done + 단독 검증 accepted + 미-PR stage 들을 골라 수집 브랜치로 머지하고 PR 1개 생성.
-- 자격 판정·수집 머지·PR 기록을 Python 헬퍼 한 곳에서 **강제** (선언이 아니라 enforcement).
-- 기존 whole-task 경로는 불변 — stage-group 은 추가 모드다.
-
-비목표:
-- 여러 task 를 한 PR 로 묶기 (task-group 단위 PR).
-- 그룹 조합에 대한 별도 final-verification 모드 신설 (게이트는 stage 별 accepted 합산; 머지 후 재검증은 사용자가 원하면 단독으로 수행).
-- PR 머지·릴리스 발행 (기존 비목표 유지 — [release-handoff.md:99](../../../prompts/profiles/release-handoff.md:99)).
-- implementation / planning 의 stage 모델·worktree 모델 변경.
-
-## 4. 흐름
-
-```
-stage 2 done ── fv --stage 2 accepted ─┐
-stage 3 done ── fv --stage 3 accepted ─┤
-                                       ▼
-release-handoff (stage-group 모드)
-  G1  PR base 선택 (기존 Q2 와 동일 — 의존 폐포 판정에 필요해 맨 앞으로)
-  G2  stage 선택 (PR 가능 목록에서 multi-select)
-  assemble: 수집 브랜치 생성 + merge   ← okstra_ctl 헬퍼 (강제 지점)
-  Q2b 충돌 프로브 (기존)
-  Q3  PR 제목/본문 확인 (기존)
-  push + gh pr create (head = 수집 브랜치)
-  consumers 에 pr 행 기록
-```
-
-stage-group 모드에서는 base 선택이 stage 선택보다 **앞선다** — G2 조건 4(의존 폐포)의 ancestor 판정과 assemble 이 `origin/<chosen-base>` 를 필요로 하기 때문이다. whole-task 모드의 기존 Q1→Q2 순서는 불변.
-
-### 4.1 진입 게이트 (stage-group 모드)
-
-- brief 가 그룹 후보 stage 들의 **단독-stage final-verification 보고서 N 개**를 인용하고, 각각의 `Verdict Token` 이 `accepted` 인지 lead 가 확인한다. whole-task 모드의 단일 보고서 게이트([release-handoff.md:14](../../../prompts/profiles/release-handoff.md:14))와 병렬 분기.
-- 워킹트리 clean / base 브랜치 금지 / 커밋 존재 게이트는 기존 그대로 ([release-handoff.md:16-18](../../../prompts/profiles/release-handoff.md:16)).
-
-### 4.2 G2 — stage 선택
-
-lead 가 헬퍼(§6)에 G1 에서 고른 base 를 넘겨 **PR 가능 stage 목록**을 받아 multi-select 로 제시한다. PR 가능 조건(전부 헬퍼가 판정):
-
-1. consumers `status:done` ([consumers.py:37](../../../scripts/okstra_ctl/consumers.py:37) `latest_done_by_stage`).
-2. 해당 stage 의 단독-stage final-verification `accepted` 기록 존재 (§5.2 `verified` 행).
-3. 아직 어떤 `pr` 행에도 포함되지 않음 (§5.3).
-4. **의존 폐포**: 모든 선행 stage 가 (a) 같은 그룹에 선택되었거나, (b) 이미 PR 머지되어 `origin/<chosen-base>` 의 ancestor (`git merge-base --is-ancestor <선행 done head_commit> origin/<base>`). 위반 시 해당 조합을 **차단**하고 "선행 stage <N> 을 그룹에 포함하거나 먼저 PR-머지 후 재시도" 안내. 근거: 단일-의존 stage 브랜치는 선행 브랜치 위에 적층되므로([stage-worktree-isolation-design.md §2.2](2026-06-06-stage-worktree-isolation-design.md)), 선행을 빼고 후행만 PR 하면 선행 커밋이 묵시적으로 따라간다.
-
-### 4.3 assemble — 수집 브랜치 생성 + 머지
-
-- base: registry task-key 행의 `implementation_base_commit` ([worktree_registry.py:72](../../../scripts/okstra_ctl/worktree_registry.py:72), [worktree_registry.py:239](../../../scripts/okstra_ctl/worktree_registry.py:239) `get_implementation_base`).
-- 브랜치명: `<work-category-prefix>-<task-id>-g<stage들을 -로 연결>` (예: `feat-dev-9184-g2-3`). 정렬은 stage 번호 오름차순.
-- 워크트리: `~/.okstra/worktrees/<project>/<group>/<task-id>/group-<id>/`, registry 키 `<task-key>#group-<id>` 를 flock 예약 — stage-key 예약과 동일 메커니즘.
-- merge: 선택 stage 브랜치들을 stage 번호 순으로 `git merge` (merge 커밋 허용). **충돌 시 즉시 중단**(`git merge --abort` 후 종료) + 충돌 경로 목록과 "stage 간 충돌 — 수동 해소 또는 그룹 재구성" 안내. rebase / squash / force 금지 유지.
-- 멱등성: 동일 그룹 키의 수집 브랜치가 이미 존재하면 — 그 HEAD 가 동일 stage head 들의 merge 결과(각 stage `done.head_commit` 이 모두 ancestor)일 때만 재사용, 아니면 에러로 중단하고 정리 절차 안내.
-
-### 4.4 PR 초안 / 보고서
-
-- PR 제목/본문 초안 규칙은 기존과 동일하되([release-handoff.md:44-49](../../../prompts/profiles/release-handoff.md:44)), 소스가 stage 별 implementation 보고서 + 단독 검증 보고서 N 개로 늘어난다. diff 범위는 `implementation_base_commit..<수집 브랜치 HEAD>`.
-- 최종 보고서 deliverable 에 **Stage Group** 섹션 추가: 선택 stage 목록, 각 stage 의 검증 보고서 경로·Verdict Token, 수집 브랜치명, merge 커밋 SHA 목록, 의존 폐포 판정 결과.
-
-## 5. 데이터 모델
-
-### 5.1 registry — 그룹 키
-
-stage-key 와 동형의 그룹 키 엔트리:
-
-```jsonc
-"<proj>/<group>/<task-id>#group-g2-3": {
-  "branch": "feat-dev-9184-g2-3",
-  "worktree_path": ".../<task-id>/group-g2-3",
-  "base_ref": "<implementation_base_commit>",
-  "stages": [2, 3],
-  "status": "active"
-}
-```
-
-### 5.2 consumers — `verified` 행 (신규)
-
-단독-stage final-verification 이 `accepted` 로 끝나면 plan_run_root 의 consumers.jsonl 에 기록한다:
-
-```jsonc
-{"impl_task_key": "...", "stage": 2, "status": "verified", "verdict": "accepted", "report_path": "...", "ts": "..."}
-```
-
-- 현재 [consumers.py:50](../../../scripts/okstra_ctl/consumers.py:50) 의 `append_consumer` 는 `started|done` 만 허용 — 허용 집합을 확장한다.
-- 이 행이 G2 조건 2의 SSOT 다. 보고서 파일을 재파싱하지 않고 consumers 만 읽어 자격을 판정한다.
-
-### 5.3 consumers — `pr` 행 (신규)
-
-handoff 가 PR 생성(또는 재사용 확인)에 성공하면 기록한다:
-
-```jsonc
-{"impl_task_key": "...", "stages": [2, 3], "status": "pr", "branch": "feat-dev-9184-g2-3", "url": "https://github.com/...", "ts": "..."}
-```
-
-- "이미 PR 된 stage" 판정(G2 조건 3)의 SSOT. whole-task handoff 도 동일 행을 기록한다(`stages` = 전체) — 두 경로의 중복-PR 방지가 한 데이터로 수렴.
-
-## 6. 강제 지점 — okstra_ctl 헬퍼
-
-자격 판정·assemble·기록은 lead 의 자유 git 호출이 아니라 `scripts/okstra_ctl/` 의 헬퍼 함수(예: `handoff_assemble`)와 CLI 서브커맨드로 단일화한다. lead 는 두 번 호출한다:
-
-1. `handoff-eligible --base <chosen-base>` — PR 가능 stage 목록 + 각 stage 의 차단 사유(미검증/이미 PR/의존 폐포)를 JSON 으로 반환. G2 의 표시 데이터.
-2. `handoff-assemble --stages 2,3 --base <chosen-base>` — 조건 재검증(fail-fast, [run.py](../../../scripts/okstra_ctl/run.py) 의 `PrepareError` 패턴) → registry 그룹 키 예약 → 수집 워크트리/브랜치 생성 → merge → 결과(브랜치명·HEAD·merge SHA 목록) JSON 반환. 위반·충돌 시 비정상 종료 + actionable 메시지.
-
-`pr` 행 기록도 헬퍼 서브커맨드(`handoff-record-pr`)로 수행해 lead 의 수기 JSON append 를 금지한다.
-
-> declaration ↔ enforcement: 프로파일의 MUST 문구는 헬퍼가 보장하는 불변식의 서술이고, 검사 책임은 Python 에 있다 — whole-task 게이트 설계 §5 와 동일 원칙 ([final-verification-whole-task-gate-design.md](2026-06-06-final-verification-whole-task-gate-design.md)).
-
-## 7. 계약 변경점 (문서/프로파일)
-
-| 파일 | 변경 |
-|---|---|
-| [release-handoff.md](../../../prompts/profiles/release-handoff.md) | 진입 게이트에 stage-group 분기(§4.1), G1·G2 신설, allowed actions 에 헬퍼 호출·수집 merge 추가, 커밋 금지 조항을 "수집 브랜치 위 merge 커밋만 허용, 파일 변경 커밋·history rewrite 금지"로 정밀화, deliverable 에 Stage Group 섹션 |
-| [final-verification.md](../../../prompts/profiles/final-verification.md) | line 29·40 의 단독-stage 라우팅 금지를 "단독-stage `accepted` 는 `release-handoff(stage-group)` 라우팅 허용"으로 완화. whole-task 전용 문구는 "단일 task 전체 PR" 한정으로 수정. accepted 시 consumers `verified` 행 기록 의무 추가 |
-| [stage-worktree-isolation-design.md](2026-06-06-stage-worktree-isolation-design.md) | 비목표 "okstra 자동 머지 없음"에 "release-handoff stage-group 수집 머지는 예외(본 설계)" 주석 |
-| [docs/kr/architecture.md](../../kr/architecture.md) | release-handoff 절에 stage-group 모드·consumers `verified`/`pr` 행 계약 반영 |
-
-## 8. 테스트
-
-- unit (`tests/`):
-  - 자격 계산 — done/verified/pr/의존 폐포 각 조건의 포함·제외, ancestor 판정 분기.
-  - `append_consumer` 허용 집합 확장 (`verified`, `pr` 행 round-trip).
-  - registry 그룹 키 예약 — 동시 예약 직렬화, 기존 stage-key 와 비충돌.
-  - assemble — 정상 merge 그래프, 충돌 시 중단·정리, 멱등 재사용 vs 불일치 에러.
-- e2e: `tests-e2e/scenario-<다음 빈 번호>-stage-group-handoff.sh` — 독립 stage 2개 done + verified → eligible 목록 확인 → assemble → 수집 브랜치 커밋 그래프(`git merge-base --is-ancestor` 양방향) 검증 → pr 행 기록 확인. 임시 `OKSTRA_HOME`(`mktemp -d`) + `trap` 정리 관례 준수.
-
-## 9. 미해결 / 후속
-
-- 수집 워크트리·브랜치의 PR 머지 후 정리는 기존 수동 절차(`git worktree remove` → `branch -D` → registry 키 삭제)를 따른다. 자동 GC 는 후속.
-- 그룹 PR 이 base 에 머지된 뒤 남은 stage 들의 whole-task 검증 base 정합(이미 머지된 stage diff 의 중복 표시)은 whole-task 게이트의 기존 ancestor 검사로 흡수되는지 구현 단계에서 확인한다.

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

@@ -1,158 +0,0 @@
-# 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-fix-cycle-design.md

@@ -1,94 +0,0 @@
-# Fix Cycle — 완료된 task 의 사후 버그 핫픽스 이력 설계
-
-- 날짜: 2026-06-11
-- 상태: 설계 승인 대기
-- 배경: okstra 로 완료(release-handoff 까지)한 task 의 산출물에서 이후 버그가 발견되는 경우, 같은 task-id 위에서 핫픽스를 수행하고 그 수정 이력을 1급 레코드로 등록하며, 이후 brief / final-report / task 브라우징에서 해당 이력이 인지되어야 한다.
-
-## 결정 요약
-
-| 결정 지점 | 선택 |
-|---|---|
-| lifecycle 형태 | 기존 phase 재진입 (error-analysis → planning → implementation → …) + 이력 계층만 신설. 전용 hotfix task-type 없음 |
-| 진입 식별 | 자동 감지 + okstra-run wizard 확인 단계 (`fix_cycle_confirm`), CLI 는 `--fix-cycle <yes|no>` |
-| 이력 SSOT | `<task_root>/history/fix-cycles.jsonl` append-only 이벤트 행 (consumers.jsonl idiom) |
-| 소비처 | ① 후속 run 의 analysis-packet ② okstra-brief 인용 ③ final-report `## 5.10 Fix History` ④ task-manifest / task-index / task-catalog 요약 |
-
-## 1. 개념 모델
-
-**fix cycle** 은 "완료된 task 의 기존 산출물에서 발견된 버그 1건을 고치는 재진입 run 묶음"이다.
-
-- id: `fc-<NN>` (task 내 단조 증가, 2자리 zero-pad).
-- 상태: `open` → `closed` 둘뿐. 이벤트 행으로 표현하며 별도 mutable 상태 파일은 두지 않는다.
-- 대상 링크: 픽스 대상인 이전 final-report 의 project-relative 경로 (`target_report`). open 시점 task-manifest 의 `latestReportPath` 에서 채운다.
-- 증상 한 줄(`symptom`): 재진입 brief 의 `Request Summary` 첫 문장에서 파생한다. 사용자 추가 입력 없음.
-- 동시 open cycle 은 task 당 1개로 제한한다. 두 번째 버그는 첫 cycle 종료 후에 연다 (KISS).
-
-## 2. SSOT 파일 계약 — `history/fix-cycles.jsonl`
-
-위치: `<task_root>/history/fix-cycles.jsonl`. reader/writer 는 신규 모듈 `scripts/okstra_ctl/fix_cycles.py` 단 한 곳이다. [consumers.py](../../../scripts/okstra_ctl/consumers.py) 의 idiom 을 그대로 따른다 — append-only + mutex(`run_context` 의 mutex 헬퍼 재사용) + last-wins 읽기.
-
-이벤트 행 3종:
-
-```jsonl
-{"event":"opened","cycle":"fc-01","target_report":"<상대경로>","symptom":"...","opened_at":"<ISO>"}
-{"event":"run","cycle":"fc-01","task_type":"error-analysis","run_seq":3,"run_manifest":"<상대경로>"}
-{"event":"closed","cycle":"fc-01","closed_by":"release-handoff","report":"<상대경로>","closed_at":"<ISO>"}
-```
-
-- idempotency 키: `(cycle, event, run_manifest|None)` 튜플. 같은 행은 중복 append 되지 않는다.
-- 경로 필드는 run-manifest 와 같은 규칙으로 프로젝트 루트 기준 상대경로만 저장한다.
-- 파생 읽기 API: `open_cycle(rows) -> dict|None`, `summarize(rows) -> dict` (소비처들이 공유). `summarize` 의 `latest` 는 `{cycle, symptom, targetReport, closedAt}`.
-
-## 3. 진입: 자동 감지 + wizard 확인
-
-감지 조건 (prepare 시점):
-
-- 대상 task 의 `workflow.lastCompletedPhase == "release-handoff"` (done 계열 상태), **그리고**
-- 이번 run 의 task-type 이 분석 entry phase (`requirements-discovery` / `error-analysis` / `implementation-planning`) 중 하나일 때.
-- `improvement-discovery` sidetrack 은 제외.
-
-확인 UI:
-
-- okstra-run wizard 에 `fix_cycle_confirm` 단계 신설 — [wizard.py](../../../scripts/okstra_ctl/wizard.py) 의 `branch_confirm` 과 같은 step-registry 패턴 (`required` 술어 = 감지 조건, `owns` = `fix_cycle_confirmed`).
-- 옵션: "버그 픽스 사이클로 기록 (추천)" / "일반 후속 작업" / "직접 입력" — okstra-run 프롬프트 3-옵션 picker 규칙 준수.
-- CLI 비대화 경로(okstra.sh / Node CLI)는 `--fix-cycle <yes|no>` 플래그를 [prepare_task_bundle()](../../../scripts/okstra_ctl/run.py) 입력(`PrepareInputs`)으로 전달한다. 플래그가 주어지면 wizard 단계는 건너뛴다. 세 entry-point 모두 `prepare_task_bundle` 로 수렴하는 단일 참조 규칙을 유지하며, 환경 변수는 사용하지 않는다.
-
-확인되면 prepare 가 `opened` 행을 기록한다.
-
-## 4. run 부착과 종료
-
-- cycle 이 `open` 인 동안 같은 task 에서 도는 **모든** run 의 prepare 가 `run` 행을 append 한다 (task-type 불문 — 핫픽스 사이클의 implementation / final-verification / release-handoff 포함).
-- run-manifest 와 timeline 항목에 `fixCycleId` 필드를 추가한다 (open cycle 없으면 필드 생략).
-- 종료: release-handoff 결과가 기록되어 workflow 가 `done-or-follow-up` 에 도달하는 시점에 `closed` 행을 append 한다 ([workflow.py](../../../scripts/okstra_ctl/workflow.py) 의 `DEFAULT_NEXT_PHASE`). final-verification `accepted` 만으로는 닫지 않는다 — 아직 release 가 나가지 않은 상태이기 때문.
-
-## 5. 소비처 4곳 — 전부 파생 뷰
-
-쓰기 1곳(`fix_cycles.py`), 읽기 N곳 원칙. 모든 소비처는 `fix_cycles.summarize()` 가 만든 같은 요약을 사용한다.
-
-1. **analysis-packet**: [analysis_packet.py](../../../scripts/okstra_ctl/analysis_packet.py) 의 `build_analysis_packet()` 이 fix-cycles.jsonl 존재 시 `## Fix History` 섹션을 packet 에 주입한다 — open cycle 상세(대상 보고서·증상·부착 run 목록) + closed cycle 한 줄 목록. lead / worker 가 분석 입력으로 받는다.
-2. **task-manifest / task-index / task-catalog**: manifest 에 파생 요약 필드 `fixCycles` (`{count, openCycleId|null, latest: {cycle, symptom, targetReport, closedAt}}`), task-index 와 `.okstra/discovery/task-catalog.json` 항목에 같은 요약 1줄. manifest/index 작성 경로([render.py](../../../scripts/okstra_ctl/render.py))에서 함께 갱신한다.
-3. **final-report**: [final-report.template.md](../../../templates/reports/final-report.template.md) 에 조건부 `## 5.10 Fix History` 섹션 신설 (5.4~5.9 사용 중 확인). fix cycle 에 부착된 run 의 보고서에 cycle id · 대상 보고서 · 증상 · cycle 내 선행 run 목록이 들어간다. `final_report_schema.py` 에 대응 필드를 추가한다.
-4. **okstra-brief**: [skills/okstra-brief/SKILL.md](../../../skills/okstra-brief/SKILL.md) Step 3 (domain alignment scan) 에 "대상 task 의 `history/fix-cycles.jsonl` 이 존재하면 `summarize` 요약을 읽어 brief 의 `Task Continuity Notes` 에 인용" 지시를 추가한다.
-
-## 6. 강제 지점 (선언 ≠ 강제)
-
-| 계약 | 강제 위치 |
-|---|---|
-| 행 스키마 · idempotency · 단일 open cycle | `fix_cycles.py` 코드 + `tests/test_okstra_fix_cycles.py` |
-| `## 5.10 Fix History` 섹션 형태 | 기존 report validator 경로 (`validators/`) 에 검사 추가 |
-| wizard 단계 · `--fix-cycle` 플래그 | 기존 wizard / prepare 단위 테스트 패턴으로 커버 |
-| 감지 조건 (done + entry phase) | `prepare_task_bundle` 단위 테스트 |
-
-## 7. 문서
-
-- `docs/kr/architecture.md` — "Phase 간 정보 전달" 인근에 "Fix cycle (사후 버그 핫픽스 이력)" 절 추가, storage model 트리에 `history/fix-cycles.jsonl` 반영.
-- `docs/kr/cli.md` — `--fix-cycle` 플래그.
-- `CHANGES.md` — `사용자 영향:` 라인 포함 항목 추가.
-- 전부 한국어.
-
-## 비목표
-
-- 전용 hotfix task-type / fast path 신설 (phase gate 우회 없음).
-- task 당 동시 다중 open cycle.
-- 기존 timeline.json / run-manifest 의 구조 변경 (`fixCycleId` 필드 1개 추가 외).
-- 과거 완료 task 의 이력 소급 backfill.

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

@@ -1,89 +0,0 @@
-# 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` 도입분): 변경 없음.