okstra 0.49.0 → 0.50.0

package/docs/kr/architecture.md

@@ -343,7 +343,7 @@ okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결
 |---|---|---|---|---|
 | `requirements-discovery` | 요청을 bugfix/feature/refactor/ops/improvement 중 하나로 분류하고 안전한 다음 phase로 라우팅 | work category, routing decision, missing-input list, clarification requests | `pending-routing-decision` (사용자 답변 후 결정) | 금지 |
 | `error-analysis` | 보고된 에러/사고의 증상·원인·재현 갭을 증거 기반으로 분석 | symptom/trigger 정리, root-cause 가설, reproduction gap, validation 경로 | `implementation-planning` | 금지 |
-| `implementation-planning` | 코딩 시작 전 안전한 구현 방향과 옵션을 평가 | 최소 2개 구현 옵션, 영향 파일 목록, trade-off, 단계별 실행 순서, validation/rollback, **User Approval Request** 블록, **§4.5.9 Plan Body Verification** (Phase 6 워커 사후 검증 라운드 — 합성된 plan 의 내적 일관성을 워커가 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 로 cross-verify; gate 결과가 `passed` / `passed-with-dissent` 일 때만 Approval 마커 렌더, `blocked-by-disagreement` / `aborted-non-result` 일 때는 majority DISAGREE 항목이 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환됨). **산출 구조**: 항상 `## 4.5 Stage Map` + N 개의 `## 4.5.<i> Stage <i>` 섹션. 각 stage 의 effective step ≤ 6. `depends-on (none)` 인 stage 들은 별도 `implementation` run 으로 병렬 실행 가능 | `implementation` (사용자 승인 후) | 금지 |
+| `implementation-planning` | 코딩 시작 전 안전한 구현 방향과 옵션을 평가 | 최소 2개 구현 옵션, 영향 파일 목록, trade-off, 단계별 실행 순서, validation/rollback, **User Approval Request** 블록, **§5.5.9 Plan Body Verification** (Phase 6 워커 사후 검증 라운드 — 합성된 plan 의 내적 일관성을 워커가 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 로 cross-verify; gate 결과가 `passed` / `passed-with-dissent` 일 때만 Approval 마커 렌더, `blocked-by-disagreement` / `aborted-non-result` 일 때는 majority DISAGREE 항목이 `## 1. Clarification Items` 의 `Blocks=approval` row 로 변환됨). **산출 구조**: 항상 `## 5.5 Stage Map` + N 개의 `## 5.5.<i> Stage <i>` 섹션. 각 stage 의 effective step ≤ 6. `depends-on (none)` 인 stage 들은 별도 `implementation` run 으로 병렬 실행 가능 | `implementation` (사용자 승인 후) | 금지 |
 | `implementation` | 승인된 `implementation-planning` final report의 단계대로 소스 코드를 수정. **한 run 에 한 stage 만 실행** (`--stage <auto\|N>` 인수로 stage 선택) | commit list, diff summary, out-of-plan edits 블록, validation/TDD evidence, rollback 검증, verifier 결과(Gemini/Codex/Claude), `carry/stage-<N>.json` evidence sidecar | `final-verification` | 허용 (승인된 plan의 파일 목록 한정, `git push`/publish/deploy/실제 migration 금지) |
 | `final-verification` | 완료된 작업의 잔존 결함·회귀 위험을 점검하고 release 판단 | acceptance verdict, residual risk, follow-up 라우팅(`error-analysis`/`implementation-planning`/`release-handoff`) | `pending-release-handoff` (verdict 가 `accepted` 일 때만 `release-handoff` 로 진입; 그 외에는 `error-analysis` 또는 `implementation-planning` 으로 리라우팅) | 금지 (read-only 테스트만 허용) |
 | `release-handoff` | `accepted` 받은 변경을 사용자가 선택한 방식대로 커밋·푸시·PR 로 전달 | 사용자 메뉴 응답(H1 action / H2 PR base / H3 message handling) 기록, 실행한 git/gh 명령 로그, commit SHA 목록, PR URL | `done-or-follow-up` | 허용 — 단 **사용자가 메뉴로 선택한 mutating 명령만** 실행. `git push --force*`, base 브랜치 직접 push, `--no-verify`, `gh release`, publish/deploy 는 금지. source code 자체는 수정 금지(이전 `implementation` 의 diff 를 그대로 패키징). |
@@ -370,12 +370,12 @@ okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결
 [brief: scope=codebase + priority-lenses]
         ↓ okstra-run --task-type improvement-discovery
 [improvement-discovery]
-        ↓ final-report (## 4.9 Improvement Candidates 후보 N개)
+        ↓ final-report (## 5.9 Improvement Candidates 후보 N개)
         ↓ (사용자가 후보 K개 선택, 각각 새 brief 작성)
 [requirements-discovery | implementation-planning | error-analysis] (선택된 후보별로 새 task-id 로)
 ````
 
-`PHASE_SEQUENCE` 의 정식 멤버에 들어가지 않는 sidetrack entry-point. 단방향 라이프사이클을 깨지 않으면서 코드베이스 발견 시나리오를 흡수한다. lens 화이트리스트와 candidate-cap 은 `scripts/okstra_ctl/improvement_lenses.py` SSOT 1개에서 통일된다. final-report 의 `## 4.9 Improvement Candidates` 표 (10 column) 는 `validators/validate_improvement_report.py` 의 11항목 contract 가 강제한다. 양방향 grilling 두 지점 (`okstra-brief` Step 4 강화 budget 8 + lead 의 Phase 1.5 reflect-back budget 12) 으로 사용자와 AI 의 이해도를 일치시킨다.
+`PHASE_SEQUENCE` 의 정식 멤버에 들어가지 않는 sidetrack entry-point. 단방향 라이프사이클을 깨지 않으면서 코드베이스 발견 시나리오를 흡수한다. lens 화이트리스트와 candidate-cap 은 `scripts/okstra_ctl/improvement_lenses.py` SSOT 1개에서 통일된다. final-report 의 `## 5.9 Improvement Candidates` 표 (10 column) 는 `validators/validate_improvement_report.py` 의 11항목 contract 가 강제한다. 양방향 grilling 두 지점 (`okstra-brief` Step 4 강화 budget 8 + lead 의 Phase 1.5 reflect-back budget 12) 으로 사용자와 AI 의 이해도를 일치시킨다.
 
 ### requirements-discovery fan-out
 
@@ -860,11 +860,11 @@ Claude가 작성하는 최종 보고서는 아래 구조를 우선 사용합니
 
 - `## Verdict Card` — **최상단 의무 섹션**. Final Conclusion / Verdict Token / Direction / Approval Required? / Next Step 5 행. Verdict Token / Direction / Next Step 셀은 본문 §2 (실행 현황) 와 §6 (다음 단계) 의 권위 셀과 byte-match 해야 합니다.
 - (선택) `## 0. Clarification Response Carried In From Previous Run` — 직전 run 에서 응답이 carry-in 된 경우에만 렌더링. 빈 carry-in 일 때는 헤딩 자체를 출력하지 않습니다.
-- `## 1. 문제 또는 검증 대상 요약` — §1.1 Consensus / §1.2 Differences 표 각각 `Source items (worker:item)` 컬럼 보존 (cross-worker traceability).
+- `## 1. 문제 또는 검증 대상 요약` — §6.1 Consensus / §6.2 Differences 표 각각 `Source items (worker:item)` 컬럼 보존 (cross-worker traceability).
 - `## 2. 에이전트별 실행 현황`
-- `## 3. Cross Verification 결과` — §3.1 Primary Evidence 에 `Source items (worker:item)` + `Source (path:line / log)` 컬럼.
-- `## 4. 최종 판단` — `implementation-planning` 의 §4.5.9 Plan Body Verification 은 `Verdict details` 표 (5-열, plan item × worker) 하나로 emit.
-- `## 5. Clarification Items` — 통합 8-열 표 한 곳. 기존 §5.1 / §5.2 / §4.5.8 / §4.5.9 Open Questions 는 deprecated 되어 validator 가 등장 시 fail.
+- `## 3. Cross Verification 결과` — §2.1 Primary Evidence 에 `Source items (worker:item)` + `Source (path:line / log)` 컬럼.
+- `## 4. 최종 판단` — `implementation-planning` 의 §5.5.9 Plan Body Verification 은 `Verdict details` 표 (5-열, plan item × worker) 하나로 emit.
+- `## 1. Clarification Items` — 통합 8-열 표 한 곳. 기존 §6.1 / §6.2 / §5.5.8 / §5.5.9 Open Questions 는 deprecated 되어 validator 가 등장 시 fail.
 - `## 6. 권장 다음 단계`
 - `## Token Usage Summary` — sentinel (`pending` / `N/A` / `--` / `?` / 빈 셀) 또는 zero (`0` / `$0.00`) 박제 시 validator 가 출고를 차단합니다. `Codex/Gemini CLI 추가 비용` 행만 "CLI 미사용" 의미로 `$0.00` 허용.
 
@@ -940,7 +940,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 두 view 를 결정
 phase 산출물의 출고 가능 여부를 강제하는 진입점:
 
 - `validators/validate-workflow.sh` — phase contract 통합 검증.
-- `validators/validate-run.py` — run-level final-report 본문 contract (Verdict Card 존재, deprecated §5.1/§5.2/§4.5.8/§4.5.9 Open Questions 부재, Plan Body Verification gate × Approval 마커 cross-check, Token Usage sentinel/zero 차단, 워커-결과 audit 사이드카 존재).
+- `validators/validate-run.py` — run-level final-report 본문 contract (Verdict Card 존재, deprecated §6.1/§6.2/§5.5.8/§5.5.9 Open Questions 부재, Plan Body Verification gate × Approval 마커 cross-check, Token Usage sentinel/zero 차단, 워커-결과 audit 사이드카 존재).
 - `validators/validate-report-views.py` — slim MD / HTML view 의 phase substring 보존 및 form-control 영역 검사.
 - `validators/validate-brief.py` — brief schema (front-matter, `Reporter Confirmations` 섹션 존재, root parent-id self 규칙, slug 컨벤션 등) 강제. `bash validators/validate-brief.sh <brief.md>` 가 thin wrapper.
 

package/docs/kr/cli.md

@@ -118,7 +118,7 @@ interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니
   - `scan-scope`: 1개 이상의 경로.
   - `out-of-scope`: 선택.
   - `candidate-cap`: 1–12, 기본 8.
-- 출력: `## 4.9 Improvement Candidates` 표 (10 column: Cand ID / Lens / Title / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Evidence).
+- 출력: `## 5.9 Improvement Candidates` 표 (10 column: Cand ID / Lens / Title / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Evidence).
 - Verdict Token: `candidates-ready` / `no-candidates` / `blocked`.
 - 라우팅: 자동 spin-off 없음. 사용자가 후보를 골라 새 task-id 로 `requirements-discovery` / `implementation-planning` / `error-analysis` 진입.
 - 워커: claude + codex + gemini + report-writer 모두 필수.
@@ -475,7 +475,7 @@ scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,
 
 `implementation-planning` task-type 의 Phase 6 plan-body verification 라운드를 끕니다. 기본값은 활성. 다른 task-type 에서는 무시됩니다.
 
-- **활성 (default)**: Phase 6 에서 Report writer worker 가 final-report draft 를 작성한 직후, lead 가 합성된 plan 의 §4.5 본문 (Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback) 을 `P-*` plan-item 단위로 쪼개 모든 analyser 워커 (`claude`, `codex`, 그리고 옵트인된 `gemini`) 에게 reverify dispatch 합니다. 워커의 평결 (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) 을 집계해 4 가지 gate result (`passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`) 중 하나를 산출하고, `passed` / `passed-with-dissent` 일 때만 final-report 상단의 `- [ ] Approved` 마커가 렌더됩니다. majority DISAGREE 항목은 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환됩니다 (자동 revise 없음 — 사용자가 답변 후 같은 phase 를 resume 해야 함).
+- **활성 (default)**: Phase 6 에서 Report writer worker 가 final-report draft 를 작성한 직후, lead 가 합성된 plan 의 §4.5 본문 (Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback) 을 `P-*` plan-item 단위로 쪼개 모든 analyser 워커 (`claude`, `codex`, 그리고 옵트인된 `gemini`) 에게 reverify dispatch 합니다. 워커의 평결 (`AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`) 을 집계해 4 가지 gate result (`passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`) 중 하나를 산출하고, `passed` / `passed-with-dissent` 일 때만 final-report 상단의 `- [ ] Approved` 마커가 렌더됩니다. majority DISAGREE 항목은 `## 1. Clarification Items` 의 `Blocks=approval` row 로 변환됩니다 (자동 revise 없음 — 사용자가 답변 후 같은 phase 를 resume 해야 함).
 - **비활성 (`--no-plan-verification` 전달 시)**: Phase 6 sub-step 전체가 skip 되고 final-report 상단의 Approval 마커가 무조건 렌더됩니다 (legacy 동작). 빠른 반복용 opt-out — handoff-ready plan 에는 권장하지 않습니다.
 - 본 flag 는 manifest 의 `convergence.planBodyVerification.enabled` 를 `false` 로 기록합니다. resume 명령에서도 같은 flag 를 명시해야 같은 동작이 유지됩니다 (`_canonical_argv` 가 resume fidelity emit 을 보장).
 - 자세한 라운드 프로토콜 / verdict semantics / state 파일 스키마는 `skills/okstra-convergence/SKILL.md` 의 "Plan-body verification mode (implementation-planning only)" 섹션 참고.

package/docs/project-structure-overview.md

@@ -237,7 +237,7 @@ Token/cost accounting:
 | `validate-brief.py`, `validate-brief.sh` | Brief frontmatter/body contract validation |
 | `validate-report-views.py` | Slim/HTML view validation |
 | `validate-schedule.py` | Schedule section/order/code validation |
-| `validate-implementation-plan-stages.py` | Stage Map 구조 강제 — S1–S8 규칙 검사 (`## 4.5 Stage Map` + `## 4.5.<i> Stage <i>` 섹션, stage 당 step ≤ 6 등) |
+| `validate-implementation-plan-stages.py` | Stage Map 구조 강제 — S1–S8 규칙 검사 (`## 5.5 Stage Map` + `## 5.5.<i> Stage <i>` 섹션, stage 당 step ≤ 6 등) |
 | `validate_improvement_report.py` | improvement-discovery final-report 의 11항목 contract 강제. `validate-run.py` 가 `task_type == "improvement-discovery"` 일 때 자동 호출 |
 | `validate-workflow.sh` | End-to-end fixture workflow validation |
 | `lib/*.sh` | Shared shell validator helpers and fixtures |
@@ -392,7 +392,7 @@ Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a s
 |---|---|---|
 | `requirements-discovery` | Classify and route work | `error-analysis` or `implementation-planning` |
 | `error-analysis` | Reproduce and explain failure | `implementation-planning` |
-| `implementation-planning` | Compare options, produce approval-ready plan; 산출은 항상 `## 4.5 Stage Map` + N 개의 `## 4.5.<i> Stage <i>` 섹션 구조. `implementation` 은 stage 단위로 분할 실행 가능 | `implementation` after approval |
+| `implementation-planning` | Compare options, produce approval-ready plan; 산출은 항상 `## 5.5 Stage Map` + N 개의 `## 5.5.<i> Stage <i>` 섹션 구조. `implementation` 은 stage 단위로 분할 실행 가능 | `implementation` after approval |
 | `implementation` | Executor changes code, verifiers check independently | `final-verification` |
 | `final-verification` | Read-only acceptance verification | `release-handoff` if accepted |
 | `release-handoff` | User-selected commit/PR handoff | done or follow-up |
@@ -436,7 +436,7 @@ When changing code, keep these docs in sync:
 | `Verdict Token` | `accepted`, `conditional-accept`, `blocked`, `not-applicable` |
 | `Direction` | `continue-investigation`, `begin-implementation`, `approve`, `reject`, `hold` |
 
-Clarifications now live in the unified `## 5. Clarification Items` table. Deprecated `5.1` / `5.2` split sections are no longer part of the schema.
+Clarifications now live in the unified `## 1. Clarification Items` table. Deprecated `5.1` / `5.2` split sections are no longer part of the schema.
 
 ---
 

package/docs/superpowers/plans/2026-06-05-wizard-batch-prompts.md

@@ -0,0 +1,559 @@
+# okstra wizard 멀티탭 배치 프롬프트 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** customize 분기에서 서로 의존 없는 픽 step들을 멀티탭 `AskUserQuestion` 한 번으로 묶어 wizard 입력 왕복 수를 줄인다.
+
+**Architecture:** 기존 `Step` 레지스트리는 그대로 두고 "방출 계층"에만 그룹 개념을 추가한다. `next_prompt`가 첫 적용 가능한 미답변 step이 그룹 멤버이면 같은 그룹의 적용가능·미답변 픽 멤버를 최대 4개까지 모아 새 `kind="pick_group"` 프롬프트로 내보내고, `submit`은 JSON `--answer`를 각 멤버 `submit()`으로 라우팅한다. `answered`/`owns`/edit-rewind/`_ready_for_confirm`은 전부 개별 step id 단위로 유지된다.
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/wizard.py`), pytest (`tests/`), okstra-run 스킬 마크다운.
+
+설계 문서: [docs/superpowers/specs/2026-06-05-wizard-batch-prompts-design.md](../specs/2026-06-05-wizard-batch-prompts-design.md)
+
+---
+
+## File Structure
+
+- Modify: `scripts/okstra_ctl/wizard.py`
+  - `Prompt` 데이터클래스 — `questions` 필드 + `to_json` 확장 ([wizard.py:299](../../../scripts/okstra_ctl/wizard.py))
+  - 그룹 상수/정의 — S_* 상수 블록 직후 ([wizard.py:206](../../../scripts/okstra_ctl/wizard.py))
+  - `_build_group_prompt` 신규 + `next_prompt` 수정 ([wizard.py:2221](../../../scripts/okstra_ctl/wizard.py))
+  - `_submit_group` 신규 + `submit` 수정 ([wizard.py:2232](../../../scripts/okstra_ctl/wizard.py))
+- Modify: `skills/okstra-run/SKILL.md` — `pick_group` 렌더 규칙 ([SKILL.md:41](../../../skills/okstra-run/SKILL.md))
+- Modify: `tests/test_okstra_ctl_wizard.py` — 그룹 흐름 반영 (`test_error_analysis_full_customize` 등)
+- Create: `tests/test_wizard_pick_group.py` — 그룹 방출/제출 단위 테스트
+
+---
+
+## Task 1: `pick_group` 데이터 모델
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:299-318` (`Prompt`)
+- Modify: `scripts/okstra_ctl/wizard.py:206` (그룹 상수)
+- Test: `tests/test_wizard_pick_group.py`
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`tests/test_wizard_pick_group.py` 생성:
+
+```python
+"""pick_group 방출/제출 단위 테스트."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+LIB_DIR = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl.wizard import (  # noqa: E402
+    GROUP_MAX_TABS,
+    GROUP_MODELS,
+    PROMPT_GROUPS,
+    Option,
+    Prompt,
+)
+
+
+def test_pick_group_to_json_carries_questions():
+    members = [
+        Prompt(step="lead_model", kind="pick", label="Lead",
+               options=[Option("default", "default")]),
+        Prompt(step="claude_model", kind="pick", label="Claude",
+               options=[Option("sonnet", "sonnet")]),
+    ]
+    p = Prompt(step=GROUP_MODELS, kind="pick_group",
+               label="모델", questions=members)
+    out = p.to_json()
+    assert out["kind"] == "pick_group"
+    assert [q["step"] for q in out["questions"]] == ["lead_model", "claude_model"]
+    assert out["questions"][0]["options"][0]["value"] == "default"
+    assert out["questions"][1]["multi"] is False
+
+
+def test_group_definitions_cover_model_and_option_picks():
+    assert GROUP_MAX_TABS == 4
+    assert "lead_model" in PROMPT_GROUPS[GROUP_MODELS]
+    assert "report_writer_model" in PROMPT_GROUPS[GROUP_MODELS]
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_pick_group.py -v`
+Expected: FAIL — `ImportError: cannot import name 'GROUP_MODELS'` / `Prompt` has no `questions`.
+
+- [ ] **Step 3: 구현 — `Prompt.questions` + 그룹 상수**
+
+`scripts/okstra_ctl/wizard.py` `Prompt` 데이터클래스 ([:299](../../../scripts/okstra_ctl/wizard.py)) 에 필드 추가 (`multi` 줄 바로 아래):
+
+```python
+    multi: bool = False  # only meaningful when kind == "pick"
+    # only meaningful when kind == "pick_group": one entry per AskUserQuestion tab
+    questions: list["Prompt"] = field(default_factory=list)
+```
+
+`to_json` ([:309](../../../scripts/okstra_ctl/wizard.py)) 를 교체:
+
+```python
+    def to_json(self) -> dict[str, Any]:
+        out = {
+            "step": self.step,
+            "kind": self.kind,
+            "label": self.label,
+            "options": [asdict(o) for o in self.options],
+            "help": self.help,
+            "echoTemplate": self.echo_template,
+            "multi": self.multi,
+        }
+        if self.kind == "pick_group":
+            out["questions"] = [
+                {"step": q.step, "label": q.label,
+                 "options": [asdict(o) for o in q.options],
+                 "multi": q.multi}
+                for q in self.questions
+            ]
+        return out
+```
+
+S_* 상수 블록 직후 (`S_DONE = "done"` 다음, [:206](../../../scripts/okstra_ctl/wizard.py)) 에 그룹 정의 추가:
+
+```python
+# ---- 멀티탭 배치 프롬프트 그룹 (방출 계층 전용) ----
+# 그룹 id 는 S_* 가 아니므로 prompts JSON SOT / step-id 동기화 검사 대상이 아니다.
+GROUP_MODELS = "models"
+GROUP_OPTIONS = "options"
+GROUP_MAX_TABS = 4  # AskUserQuestion 의 질문(탭) 수 한도
+
+# 멤버는 모두 서로 의존이 없는 단일선택 픽 step 이어야 한다.
+# *_TEXT 후속 / workers_override / pr_template_scope 는 의존성 때문에 개별 유지.
+PROMPT_GROUPS: dict[str, tuple[str, ...]] = {
+    GROUP_MODELS: (S_LEAD_MODEL, S_EXECUTOR_MODEL, S_CLAUDE_MODEL,
+                   S_CODEX_MODEL, S_GEMINI_MODEL, S_REPORT_WRITER_MODEL),
+    GROUP_OPTIONS: (S_DIRECTIVE_PICK, S_RELATED_TASKS_PICK,
+                    S_CLARIFICATION_PICK, S_PR_TEMPLATE_PICK),
+}
+GROUP_LABELS: dict[str, str] = {
+    GROUP_MODELS: "모델 선택 (탭별로 선택)",
+    GROUP_OPTIONS: "추가 옵션 (탭별로 선택)",
+}
+_STEP_TO_GROUP: dict[str, str] = {
+    sid: gid for gid, ids in PROMPT_GROUPS.items() for sid in ids
+}
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_wizard_pick_group.py -v`
+Expected: PASS (2 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_pick_group.py
+git commit -m "feat(wizard): add pick_group prompt model and group definitions"
+```
+
+---
+
+## Task 2: `next_prompt` 그룹 방출
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:2221-2229` (`next_prompt`)
+- Test: `tests/test_wizard_pick_group.py`
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`tests/test_wizard_pick_group.py` 에 추가:
+
+```python
+from okstra_ctl.wizard import next_prompt  # noqa: E402
+
+
+def _models_state():
+    """모델 그룹 직전까지 진행된 상태를 직접 구성한다 (비-implementation)."""
+    from okstra_ctl.wizard import WizardState
+    s = WizardState(workspace_root=".", project_root=".", project_id="p")
+    s.task_type = "error-analysis"
+    s.brief_path = "/tmp/brief.md"
+    s.base_ref = "main"
+    s.profile_workers = ["claude", "codex", "report-writer"]
+    s.profile_optional_workers = ["gemini"]
+    s.use_defaults = False
+    s.workers_override = "claude,codex,report-writer"
+    s.critic = "off"
+    # identity/critic/workers 단계를 answered 로 마킹해 모델 그룹이 첫 미답변이 되게 한다.
+    s.answered = [
+        "task_pick", "brief_path", "task_group", "task_id", "task_type",
+        "base_ref_pick", "critic_pick", "defaults_or_custom",
+        "workers_override",
+    ]
+    return s
+
+
+def test_next_prompt_emits_models_group():
+    p = next_prompt(_models_state())
+    assert p.kind == "pick_group"
+    assert p.step == GROUP_MODELS
+    steps = [q.step for q in p.questions]
+    # 로스터에 gemini 없음 → gemini_model 제외, executor 는 비-impl 이라 제외
+    assert steps == ["lead_model", "claude_model", "codex_model",
+                     "report_writer_model"]
+    assert len(steps) <= GROUP_MAX_TABS
+
+
+def test_models_group_caps_at_four_then_emits_remainder():
+    s = _models_state()
+    s.profile_workers = ["claude", "codex", "gemini", "report-writer"]
+    s.profile_optional_workers = []
+    s.workers_override = "claude,codex,gemini,report-writer"
+    p = next_prompt(s)
+    assert p.kind == "pick_group"
+    assert [q.step for q in p.questions] == [
+        "lead_model", "claude_model", "codex_model", "gemini_model"]
+    # 첫 4개를 answered 처리하면 5번째(report_writer)는 단일 픽으로 방출
+    s.answered += ["lead_model", "claude_model", "codex_model", "gemini_model"]
+    p2 = next_prompt(s)
+    assert p2.kind == "pick"
+    assert p2.step == "report_writer_model"
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_pick_group.py -k next_prompt -v`
+Expected: FAIL — `next_prompt` 가 `kind == "pick"` (S_LEAD_MODEL) 를 반환.
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/wizard.py` `next_prompt` ([:2221](../../../scripts/okstra_ctl/wizard.py)) 를 교체하고 헬퍼를 그 위에 추가:
+
+```python
+def _build_group_prompt(state: WizardState, group_id: str) -> Prompt:
+    """그룹의 적용가능·미답변 픽 멤버를 최대 GROUP_MAX_TABS 개 모은다.
+
+    멤버가 1개뿐이면 멀티탭 UI가 불필요하므로 그 멤버의 평범한 픽을 반환한다.
+    """
+    members: list[Prompt] = []
+    for sid in PROMPT_GROUPS[group_id]:
+        if sid in state.answered:
+            continue
+        step = STEP_BY_ID[sid]
+        if not step.applies(state):
+            continue
+        members.append(step.build(state))
+        if len(members) >= GROUP_MAX_TABS:
+            break
+    if len(members) == 1:
+        return members[0]
+    return Prompt(step=group_id, kind="pick_group",
+                  label=GROUP_LABELS[group_id], questions=members)
+
+
+def next_prompt(state: WizardState) -> Prompt:
+    if state.confirmed:
+        return Prompt(step=S_DONE, kind="done")
+    for step in STEPS:
+        if step.id in state.answered:
+            continue
+        if step.applies(state):
+            group_id = _STEP_TO_GROUP.get(step.id)
+            if group_id is not None:
+                return _build_group_prompt(state, group_id)
+            return step.build(state)
+    return Prompt(step=S_DONE, kind="done")
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_wizard_pick_group.py -k next_prompt -v`
+Expected: PASS (2 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_pick_group.py
+git commit -m "feat(wizard): emit pick_group in next_prompt with 4-tab cap"
+```
+
+---
+
+## Task 3: `submit` 그룹 라우팅
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:2232-2246` (`submit`)
+- Test: `tests/test_wizard_pick_group.py`
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+`tests/test_wizard_pick_group.py` 에 추가:
+
+```python
+import pytest  # noqa: E402
+
+from okstra_ctl.wizard import WizardError, submit  # noqa: E402
+
+
+def test_submit_group_routes_json_to_members():
+    s = _models_state()
+    answer = json.dumps({
+        "lead_model": "default",
+        "claude_model": "sonnet",
+        "codex_model": "gpt-5.5",
+        "report_writer_model": "default",
+    })
+    result = submit(s, answer)
+    assert s.claude_model == "sonnet"
+    assert s.codex_model == "gpt-5.5"
+    assert s.lead_model == ""          # default → 빈 문자열
+    assert s.report_writer_model == ""
+    # 모든 멤버가 개별적으로 answered 처리됨
+    for sid in ("lead_model", "claude_model", "codex_model",
+                "report_writer_model"):
+        assert sid in s.answered
+    assert result["next"]["step"] != GROUP_MODELS
+
+
+def test_submit_group_missing_key_defaults():
+    s = _models_state()
+    result = submit(s, json.dumps({"claude_model": "sonnet"}))
+    assert s.claude_model == "sonnet"
+    assert s.lead_model == ""
+    assert "lead_model" in s.answered
+
+
+def test_submit_group_invalid_json_raises():
+    s = _models_state()
+    with pytest.raises(WizardError):
+        submit(s, "not-json")
+
+
+def test_submit_group_invalid_model_raises_and_no_marking():
+    s = _models_state()
+    with pytest.raises(WizardError):
+        submit(s, json.dumps({"claude_model": "totally-unknown-model"}))
+    # 검증 실패 → 어떤 멤버도 answered 로 마킹되지 않음(전부 재-프롬프트)
+    assert "claude_model" not in s.answered
+    assert "lead_model" not in s.answered
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_pick_group.py -k submit -v`
+Expected: FAIL — `submit` 가 group step을 `STEP_BY_ID[prompt.step]` 에서 찾다 `KeyError`.
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/wizard.py` `submit` ([:2232](../../../scripts/okstra_ctl/wizard.py)) 를 교체하고 헬퍼를 그 위에 추가:
+
+```python
+def _submit_group(state: WizardState, prompt: Prompt, value: str) -> dict[str, Any]:
+    """pick_group 답(JSON 객체)을 각 멤버 submit() 으로 라우팅한다.
+
+    전부 검증 통과한 뒤에만 멤버들을 answered 로 마킹한다(부분 적용 금지).
+    멤버 submit 이 WizardError 를 던지면 그대로 전파되어 같은 그룹을 재-프롬프트한다.
+    """
+    try:
+        answers = json.loads(value or "{}")
+    except json.JSONDecodeError as exc:
+        raise WizardError(f"pick_group answer must be a JSON object: {exc}")
+    if not isinstance(answers, dict):
+        raise WizardError("pick_group answer must be a JSON object")
+    echoes: list[str] = []
+    for q in prompt.questions:
+        echo = STEP_BY_ID[q.step].submit(state, str(answers.get(q.step, "") or ""))
+        if echo:
+            echoes.append(echo)
+    for q in prompt.questions:
+        if q.step not in state.answered:
+            state.answered.append(q.step)
+    nxt = next_prompt(state)
+    return {"echo": "; ".join(echoes), "next": nxt.to_json()}
+
+
+def submit(state: WizardState, value: str) -> dict[str, Any]:
+    """Validate the answer for the *currently active* step and advance.
+
+    Returns {"echo": "...", "next": <Prompt JSON>}. Raises WizardError on
+    validation failure (caller may re-prompt).
+    """
+    prompt = next_prompt(state)
+    if prompt.kind == "done":
+        return {"echo": "", "next": prompt.to_json()}
+    if prompt.kind == "pick_group":
+        return _submit_group(state, prompt, value)
+    step = STEP_BY_ID[prompt.step]
+    echo = step.submit(state, value or "")
+    if prompt.step not in state.answered:
+        state.answered.append(prompt.step)
+    nxt = next_prompt(state)
+    return {"echo": echo or "", "next": nxt.to_json()}
+```
+
+> 참고: `_validate_model` 가 WizardError 를 던지면 그 시점 이전 멤버의 state 필드는 이미
+> 설정되어 있지만 `answered` 에는 추가되지 않는다. 재-프롬프트 시 같은 그룹이 다시 나오고
+> 사용자가 다시 고른 값으로 덮어쓰므로 결과적으로 안전하다.
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_wizard_pick_group.py -v`
+Expected: PASS (전체)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_pick_group.py
+git commit -m "feat(wizard): route pick_group JSON answers to member submits"
+```
+
+---
+
+## Task 4: 기존 customize 흐름 테스트 갱신
+
+**Files:**
+- Modify: `tests/test_okstra_ctl_wizard.py:389-501` (`test_error_analysis_full_customize`)
+- Modify: `tests/test_okstra_ctl_wizard.py` (그 외 `S_LEAD_MODEL`/`directive_pick` 단일픽을 가정하는 테스트)
+
+- [ ] **Step 1: 영향 테스트 식별**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py -v`
+Expected: 모델/옵션 단일픽을 가정하던 테스트가 FAIL (now `pick_group`). 실패 목록을 확인한다.
+
+- [ ] **Step 2: `test_error_analysis_full_customize` 갱신**
+
+`tests/test_okstra_ctl_wizard.py:444-466` (lead~report-writer 개별 블록) 을 그룹 제출로 교체:
+
+```python
+    # 7) 모델 그룹 (lead + claude + codex + report-writer, 로스터에 gemini 없음)
+    p = next_prompt(state)
+    assert p.kind == "pick_group"
+    assert p.step == "models"
+    assert [q.step for q in p.questions] == [
+        "lead_model", "claude_model", "codex_model", "report_writer_model"]
+    submit(state, json.dumps({
+        "lead_model": "default",
+        "claude_model": "sonnet",
+        "codex_model": "gpt-5.5",
+        "report_writer_model": "default",
+    }))
+    assert state.lead_model == ""
+    assert state.claude_model == "sonnet"
+    assert state.codex_model == "gpt-5.5"
+```
+
+이어서 `tests/test_okstra_ctl_wizard.py:468-481` (directive/related/clarification 개별 블록) 을 옵션 그룹 제출로 교체:
+
+```python
+    # 8) 옵션 그룹 (directive + related-tasks + clarification 픽)
+    p = next_prompt(state)
+    assert p.kind == "pick_group"
+    assert p.step == "options"
+    assert [q.step for q in p.questions] == [
+        "directive_pick", "related_tasks_pick", "clarification_pick"]
+    submit(state, json.dumps({
+        "directive_pick": "__skip__",
+        "related_tasks_pick": "__skip__",
+        "clarification_pick": "__skip__",
+    }))
+```
+
+파일 상단 import 에 `import json` 이 없으면 추가한다 (이미 있으면 생략).
+
+- [ ] **Step 3: 다른 영향 테스트 갱신**
+
+Step 1 에서 FAIL 한 나머지 테스트(예: `test_implementation_customize_has_executor_model_and_no_workers_override` [:611](../../../tests/test_okstra_ctl_wizard.py), 그 외 `assert p.step == S_LEAD_MODEL` / `== "directive_pick"` 를 직접 가정하는 테스트)를 동일 패턴으로 갱신한다. implementation 모델 그룹 멤버는 `["lead_model", "executor_model", "report_writer_model"]` 이다.
+
+각 실패 테스트에서:
+- `assert p.step == S_LEAD_MODEL` → 그룹 방출 (`p.kind == "pick_group"`, `p.step == "models"`) 로 변경하고, 개별 `submit(state, "...")` 호출을 단일 JSON `submit` 으로 합친다.
+- `assert p.step == "directive_pick"` → `options` 그룹 방출로 변경.
+
+- [ ] **Step 4: 전체 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py tests/test_wizard_pick_group.py -v`
+Expected: PASS (전체)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add tests/test_okstra_ctl_wizard.py
+git commit -m "test(wizard): adapt customize-branch tests to grouped prompts"
+```
+
+---
+
+## Task 5: SKILL.md `pick_group` 렌더 규칙
+
+**Files:**
+- Modify: `skills/okstra-run/SKILL.md:41-50`, `:96-98`
+
+- [ ] **Step 1: "How the wizard talks to you" 섹션에 규칙 추가**
+
+`skills/okstra-run/SKILL.md` 의 `kind` 설명 목록 ([:43](../../../skills/okstra-run/SKILL.md)) 바로 아래(`kind: "pick"` + `multi: true` 항목 다음)에 추가:
+
+```markdown
+- `kind: "pick_group"` → render a SINGLE `AskUserQuestion` whose `questions` array maps 1:1 to the wizard's `questions[]`. For each entry use `questions[].label`, `questions[].options[].label`, and `multiSelect: questions[].multi`. Collect the user's chosen `options[].value` per tab, build a JSON object keyed by each `questions[].step`, and submit it as a single literal `--answer '{"lead_model":"opus","claude_model":"default",...}'`. A tab the user leaves at its default still gets its `"default"`/`""` value in the JSON. Never split a `pick_group` into multiple `AskUserQuestion` calls — the wizard already capped it at 4 tabs and will emit any remainder as the next prompt.
+```
+
+- [ ] **Step 2: 프롬프트 루프 섹션에 동일 분기 추가**
+
+`skills/okstra-run/SKILL.md` Step 3 의 Render 목록 ([:96](../../../skills/okstra-run/SKILL.md)) 에 추가:
+
+```markdown
+   - `pick_group` → one `AskUserQuestion` with one question per `questions[]` entry (tab). Map each tab's selected `value` back by `questions[].step`, assemble a JSON object, and submit it as a single literal `--answer '<json>'`.
+```
+
+- [ ] **Step 3: 빌드 동기화**
+
+Run: `npm run build`
+Expected: 성공, `runtime/` 에 SKILL.md 반영.
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add skills/okstra-run/SKILL.md runtime/
+git commit -m "docs(skills/okstra-run): render pick_group as one multi-tab AskUserQuestion"
+```
+
+---
+
+## Task 6: 회귀 검증
+
+**Files:** (없음 — 검증만)
+
+- [ ] **Step 1: 전체 단위 테스트**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: 전체 PASS (특히 `tests/test_wizard_prompts.py` step-id 동기화/orphan 검사 — 그룹 상수는 `S_*` 가 아니므로 영향 없음).
+
+- [ ] **Step 2: phase contract validator**
+
+Run: `bash validators/validate-workflow.sh`
+Expected: 통과.
+
+- [ ] **Step 3: CLI smoke**
+
+Run: `node bin/okstra --version`
+Expected: 버전 출력.
+
+- [ ] **Step 4: CHANGES.md 항목 추가**
+
+`CHANGES.md` 상단에 사용자 영향 항목 추가:
+
+```markdown
+- okstra-run: customize 단계의 모델/옵션 선택을 멀티탭으로 묶어 입력 왕복 횟수를 줄임.
+  사용자 영향: lead/worker/report 모델과 directive/related-tasks/clarification 픽을 한 화면에서 선택.
+```
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add CHANGES.md
+git commit -m "docs(changes): log multi-tab wizard prompts"
+```
+
+---
+
+## Self-Review 메모
+
+- **Spec coverage**: pick_group 모델(§3.1)=Task1, 그룹정의(§3.2)=Task1, next_prompt(§3.3)=Task2, 제출(§3.4)=Task3, SKILL(§3.5)=Task5, 테스트(§5)=Task3·4·6. 전 항목 매핑됨.
+- **Type 일관성**: `GROUP_MODELS`/`GROUP_OPTIONS`/`GROUP_MAX_TABS`/`PROMPT_GROUPS`/`GROUP_LABELS`/`_STEP_TO_GROUP`/`_build_group_prompt`/`_submit_group`/`Prompt.questions` 식별자가 전 태스크에서 동일 표기.
+- **비영향**: `use_defaults=True` 경로, identity 단계, confirm/edit-target, `render_args`, `_ready_for_confirm` 의 개별 step 검사 모두 불변.