okstra 0.49.0 → 0.51.0

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 검사 모두 불변.

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

@@ -0,0 +1,121 @@
+# okstra wizard 멀티탭 배치 프롬프트 설계
+
+- 작성일: 2026-06-05
+- 대상: `scripts/okstra_ctl/wizard.py`, `skills/okstra-run/SKILL.md`
+- 상태: 설계 승인 대기
+
+## 1. 배경 / 문제
+
+`okstra-run` 스킬은 wizard 상태 머신이 내보내는 프롬프트를 한 개씩
+`AskUserQuestion` 으로 렌더하고, 사용자가 답하면 다음 프롬프트를 받는 **답-대기 왕복**
+구조다 ([wizard.py:2238](../../../scripts/okstra_ctl/wizard.py), [SKILL.md:96](../../../skills/okstra-run/SKILL.md)).
+
+`use_defaults=False`(customize) 분기에서는 서로 의존이 없는 픽이 줄줄이 개별 프롬프트로
+나온다:
+
+- 모델: `lead_model` → (impl) `executor_model` / (그 외) 로스터별 `claude_model`·`codex_model`·`gemini_model` → `report_writer_model` — 최대 5회
+- 옵션: `directive_pick` → `related_tasks_pick` → `clarification_pick` → (release-handoff) `pr_template_pick` — 최대 4회
+
+각 픽이 별도 왕복이라 전체 입력에 시간이 오래 걸린다. **비슷한 유형의 독립 질문을 탭으로
+묶어 한 번의 `AskUserQuestion` 으로 받아** 왕복 수를 줄이는 것이 목표다.
+
+## 2. 핵심 원칙
+
+**기존 `Step` 은 그대로 두고 "방출(presentation) 계층" 에만 배치 개념을 추가한다.**
+
+- `answered` / `owns` / edit-rewind(`_reset_from`) / `_ready_for_confirm` 의 `custom_ids`
+  검사는 전부 **개별 step id 단위**로 유지된다 ([wizard.py:2149](../../../scripts/okstra_ctl/wizard.py)).
+- 그룹은 "서로 의존이 없는 픽 step 들을 한 화면에 모아 내보내는" 래퍼일 뿐, step 자체를
+  대체하지 않는다. 따라서 검증·되감기 로직은 무손상이다.
+
+## 3. 변경 사항
+
+### 3.1 새 prompt kind `pick_group`
+
+`Prompt` 직렬화에 멀티-질문 모양을 추가한다 ([wizard.py:299](../../../scripts/okstra_ctl/wizard.py)).
+
+```json
+{
+  "step": "<group-id>",
+  "kind": "pick_group",
+  "questions": [
+    { "step": "lead_model", "label": "...", "options": [ {"value":"..","label":".."} ], "multi": false },
+    { "step": "claude_model", "label": "...", "options": [...], "multi": false }
+  ]
+}
+```
+
+- `questions[]` 한 항목 = `AskUserQuestion` 탭 하나.
+- 각 항목은 기존 step 의 `build()` 가 만든 `label` / `options` 를 그대로 재사용한다(중복 정의 금지).
+- 기존 `kind: "pick"` / `"text"` / `"done"` 은 변경 없음.
+
+### 3.2 그룹 정의
+
+customize 분기의 **픽 step 만** 그룹화한다. 순서가 있는 명시적 정의를 wizard.py 에 둔다.
+
+| 그룹 id | 멤버 step (적용 가능할 때만) |
+|---|---|
+| `models` | `lead_model`, (impl) `executor_model` / (그 외) `claude_model`·`codex_model`·`gemini_model`, `report_writer_model` |
+| `options` | `directive_pick`, `related_tasks_pick`, `clarification_pick`, (release-handoff) `pr_template_pick` |
+
+**개별 유지(그룹화 금지) 대상**:
+
+- `*_TEXT` 후속(`directive`, `related_tasks`, `clarification`, `pr_template`): "직접 입력"
+  선택 시에만 나타나는 조건부 텍스트 입력. `AskUserQuestion` 은 텍스트 입력을 지원하지
+  않으므로 ([SKILL.md:50](../../../skills/okstra-run/SKILL.md)) 개별 텍스트 프롬프트로 유지.
+- `workers_override`: 어떤 모델 탭(claude/codex/gemini)이 적용되는지를 결정하므로 `models`
+  그룹보다 **반드시 선행**해야 한다. 개별 유지.
+- `pr_template_scope`: `pr_template_path` 가 정해진 뒤에야 적용되므로 개별 유지.
+
+### 3.3 엔진 `next_prompt` 수정
+
+[wizard.py:2238](../../../scripts/okstra_ctl/wizard.py) 의 다음-프롬프트 결정 로직:
+
+1. 기존대로 첫 번째 "적용 가능 + 미답변" step 을 찾는다.
+2. 그 step 이 그룹 멤버가 아니면 기존 `Prompt` 를 그대로 반환(동작 불변).
+3. 그룹 멤버이면 같은 그룹의 **적용 가능 + 미답변 픽 멤버**를 정의 순서대로 **최대 4개**까지
+   모아 `pick_group` 으로 반환한다.
+   - `AskUserQuestion` 의 질문 수 한도가 4개이기 때문.
+   - 비-implementation 풀 로스터(lead+claude+codex+gemini+report = 5)는 첫 4개만 한 배치로
+     나가고, 답변 후 5번째가 다음 배치로 자동 분리된다. **스킬에 청크 로직 불필요**, 최악 2화면.
+
+### 3.4 제출 경로 수정
+
+[wizard.py:2233](../../../scripts/okstra_ctl/wizard.py) 의 advance, CLI `--answer` 파싱([wizard.py:2363](../../../scripts/okstra_ctl/wizard.py)):
+
+- 현재 활성 프롬프트가 `pick_group` 이면 `--answer` 를 **JSON 객체 문자열**로 받는다.
+  ```
+  okstra wizard step --state-file <path> --answer '{"lead_model":"opus","claude_model":"default","report_writer_model":""}'
+  ```
+- 엔진은 각 키를 해당 멤버 step 의 `submit()` 으로 라우팅하고, 각 멤버를 개별적으로
+  `answered` 에 추가한다.
+- 키 누락 / 빈 값("" 또는 "default")은 기존 `_validate_model` 규칙대로 "phase 기본값"으로
+  처리된다 ([wizard.py:418](../../../scripts/okstra_ctl/wizard.py)). 멤버 중 하나라도
+  검증 실패하면 `ok:false` 로 같은 그룹을 재-프롬프트한다(부분 적용 금지: 전부 검증 통과해야
+  `answered` 마킹).
+
+### 3.5 SKILL.md 렌더 규칙 추가
+
+[SKILL.md:41-50](../../../skills/okstra-run/SKILL.md), [SKILL.md:96](../../../skills/okstra-run/SKILL.md):
+
+- `kind: "pick_group"` → `questions[]` 를 탭(질문)으로 갖는 `AskUserQuestion` **1회** 호출.
+  탭마다 `label` + `options`, `multiSelect` 는 `questions[].multi`.
+- 사용자의 탭별 선택값(`options[].value`)을 `questions[].step` 키로 묶어 JSON 문자열을 만들고,
+  단일 `--answer '<json>'` 으로 제출.
+- 리터럴-토큰 권한 규칙 유지: `--answer` 값은 셸 변수/`$(...)` 없이 리터럴 JSON 문자열로 전달.
+- 검증 실패(`ok:false`) 시 동일 그룹 재-프롬프트.
+
+## 4. 영향 / 비영향
+
+- **동작 변경**: customize 분기의 모델·옵션 픽이 멀티탭으로 묶여 왕복 횟수 감소
+  (모델 3~5픽 → 1~2회, 옵션 3~4픽 → 1회).
+- **불변**: `use_defaults=True` 경로, identity 단계(task pick/type/base-ref/plan/executor),
+  confirm/branch_confirm/edit-target, render-bundle 인자 매핑([wizard.py:2249](../../../scripts/okstra_ctl/wizard.py)).
+- **"직접 입력"** 을 고른 항목만 텍스트 후속이 개별 프롬프트로 남는다(불가피).
+
+## 5. 테스트
+
+- 기존 wizard 단위 테스트(`tests/`) 가 개별 step 계약을 그대로 통과해야 한다(그룹은 방출 계층만 변경).
+- 신규: `pick_group` 방출(멤버 4개 초과 → 2배치 분리), JSON `--answer` 라우팅(부분 검증 실패 시
+  재-프롬프트), workers_override 선행 → models 그룹 로스터 반영을 커버하는 테스트 추가.
+- `node bin/okstra --version` / `bash validators/validate-workflow.sh` 회귀 확인.

package/docs/task-process/error-analysis.md

@@ -87,7 +87,7 @@ final report는 다음을 담아야 한다.
 - evidence-backed cause analysis
 - uncertainty boundary
 - practical next diagnostic steps
-- blocking uncertainty가 있으면 `## 5. Clarification Items`, 보통 `Blocks=next-phase`
+- blocking uncertainty가 있으면 `## 1. Clarification Items`, 보통 `Blocks=next-phase`
 
 금지되는 것은 source edit, refactor, fix attempt, implementation design artifact, build/migration/deploy 실행이다. code나 log로 답할 수 있는 ambiguity를 사용자 질문으로 넘기는 것도 profile상 defect다.