okstra 0.48.0 → 0.50.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-compact-markdown-report-tables-design.md

@@ -0,0 +1,87 @@
+# 정본 final-report `.md` 표를 compact 하게 (옵션 X) — 설계
+
+- 작성일: 2026-06-05
+- 범위: final-report 정본 `.md` 의 narrative 표(§1 Summary, §1.1 Consensus, §1.2 Differences, §3.1 Primary Evidence, §3.2 Secondary, §4 Risks, Execution Status by Agent)를 **짧은 코드 컬럼을 `<br>` 로 한 셀에 stack 한 meta 컬럼 + 긴 prose 컬럼은 별도 컬럼** 으로 재구성해, markdown 에디터에서도 핵심 본문(요약·근거·이견·위험)이 넓게 읽히도록 한다. 이는 [`templates/reports/final-report.template.md`](../../../templates/reports/final-report.template.md) 의 jinja 레이아웃만 바꾸며, `data.json` 스키마·report-writer 계약은 불변이다.
+- 비범위
+  - **§5 Clarification Items 는 평면 8-컬럼 유지** — [`scripts/okstra_ctl/clarification_items.py`](../../../scripts/okstra_ctl/clarification_items.py) 가 `--resume-clarification` carry-in 을 위해 `|` 8-컬럼으로 파싱하고 validator 가 8-컬럼 스키마를 BLOCKING 으로 강제. §5 의 compact 는 HTML view 의 기존 grouping(이미 Expected form wide 까지 교정됨)이 담당한다.
+  - `data.json` 스키마·report-writer worker 의 출력 계약·convergence 상태 변경 없음 (같은 필드를 템플릿이 다르게 배치할 뿐).
+  - implementation-planning §4.5 deliverable 표(Stage Map / Stepwise 등)는 비대상 — validator 가 그 컬럼/헤딩을 substring 검사하므로 손대지 않는다.
+- 관계: 직전 작업(브랜치 `fix/report-table-grouping`, 커밋 `2343e30`)은 **HTML view 에서만** §1/§3/§4 를 grouped 로 만들었다. 본 설계(X)는 §1/§3/§4 를 `.md` 자체에서 compact 하게 만들어 그 HTML-only 접근을 **대체**한다 — 해당 표들은 더 이상 별도 `Ticket ID` 컬럼이 없어 report_views 의 generic grouping 분기가 발동하지 않으므로, 그 분기를 정리한다. §5 grouping(+Expected form wide) 은 유지된다.
+
+## 1. 동기
+
+사용자는 final-report 를 **`.md` 파일로 markdown 에디터에서 읽는다.** markdown 표는 colspan 이 없어, `ID·Ticket ID·Source·Kind·Status` 같은 짧은 코드 컬럼이 각각 한 칸씩 차지하면 정작 긴 prose 컬럼(요약·Statement·Evidence·Disagreement·Item·Risk)이 좁아져 세로로 한 글자씩 뭉개진다(실측: §1 Summary 의 "한 줄 요약"이 1글자/줄). HTML self-contained view 는 grouping 으로 해결되지만 `.md` 를 읽는 사용자에겐 닿지 않는다. 따라서 `.md` 자체에서 짧은 컬럼을 `<br>` 로 한 셀에 모아 컬럼 수를 줄이고 prose 에 폭을 준다.
+
+## 2. 핵심 설계
+
+### 2.1 대상 표와 meta/wide 분해
+
+각 표를 `[meta 컬럼] + [prose 컬럼들]` 로 재구성한다(meta = 짧은 코드 필드를 `<br>` stack):
+
+| 표 | meta 컬럼(한 셀에 `<br>` stack) | 별도 prose 컬럼 |
+|---|---|---|
+| §1 Summary | ID, Ticket ID, 출처 | 한 줄 요약 |
+| §1.1 Consensus | ID, Ticket ID, Source items | Statement, Evidence |
+| §1.2 Differences | ID, Ticket ID, Workers(position+item) | Disagreement, Evidence |
+| §3.1 Primary Evidence | ID, Ticket ID, Source items, Source(path:line) | Evidence |
+| §3.2 Secondary | ID, Ticket ID | Hypothesis or supporting evidence, Source / confidence |
+| §4 Risks | ID, Ticket ID | Item, Risk if ignored, Mitigation Owner |
+| Execution Status | Agent, Role, Model, Status, raw/billable tokens, cost, Duration | Summary of Key Findings |
+
+빈 상태(empty) 분기는 현행 그대로 유지(`emptyState.*`).
+
+### 2.2 meta 셀 포맷 (`<br>` stack, i18n)
+
+meta 셀은 headline(주 식별자) + `<br>` 로 이어지는 `라벨: 값` 들로 구성한다. 예 §1.1 한 row:
+
+```
+**C-1**<br>{ticketLabel}: `DEV-9184`<br>{sourceLabel}: claude:F-001, codex:1.1
+```
+
+- headline 은 ID(또는 Agent/Step)를 `**굵게**`.
+- 라벨은 기존 i18n 키를 재사용(`columns.ticketId`, `columns.source`, …); 없으면 신규 키 추가(예 `columns.recordMeta` = meta 컬럼 헤더 "항목"/"Record").
+- 값에 코드성인 것(ticket 등)은 기존처럼 백틱 유지.
+- meta 컬럼 헤더는 짧은 라벨(예 "항목" / "Record") — 신규 i18n 키.
+
+### 2.3 report_views 정합
+
+1. **`_inline` 가 `<br>` 를 보존**: 현재 `html.escape` 가 `<br>`→`&lt;br&gt;` 로 깨뜨린다. escape 후 `&lt;br&gt;` / `&lt;br/&gt;` / `&lt;br /&gt;` 를 `<br>` 로 복원(bold/code/link 복원과 동일 패턴). 이로써 HTML view 도 meta 셀이 줄바꿈으로 보인다.
+2. **generic Ticket-ID grouping 분기 제거**: §1/§3/§4 는 이제 `Ticket ID` 단독 컬럼이 없어 그 분기가 발동하지 않는다 — commit `2343e30` 가 추가한 generic 분기(+ 관련 헬퍼·테스트)를 정리한다. Execution Status 도 `.md` 에서 merged 되므로 그 explicit 분기 제거. **§5 Clarification grouping(+Expected form wide)만 남긴다**(§5 는 `.md` 평면 유지 → HTML 에서 grouping).
+3. **plain-table 폭 보강**: merged meta 컬럼은 좁게, prose 컬럼은 넓게 나오도록 plain 경로의 컬럼 폭 처리를 점검(필요 시 meta 컬럼에 narrow, prose 에 min-width).
+
+### 2.4 계약 영향
+
+- `data.json`·report-writer 계약·convergence 상태: **불변**. 템플릿이 같은 데이터를 다르게 배치.
+- §5 파서(`clarification_items.py`)·§5 8-컬럼 validator: **불변**(§5 평면 유지).
+- §1/§3/§4 컬럼 헤더를 substring 검사하는 validator/테스트는 없음(확인됨); 구현 단계에서 grep + 전체 테스트로 재확인.
+- carry-in 으로 다음 run 에 들어가는 `.md` 의 §1/§3/§4 는 LLM 이 컨텍스트로 읽을 뿐 코드가 컬럼 파싱하지 않으므로 `<br>` stack 도 안전.
+
+## 3. 변경 파일
+
+1. [`templates/reports/final-report.template.md`](../../../templates/reports/final-report.template.md) — §1/§1.1/§1.2/§3.1/§3.2/§4 + Execution Status 표를 meta(`<br>` stack) + prose 형태로 재작성.
+2. [`templates/reports/report.i18n.*`](../../../templates/reports/) (또는 i18n SOT) — meta 컬럼 헤더 + 필요한 라벨 키 추가(ko/en).
+3. [`scripts/okstra_ctl/report_views.py`](../../../scripts/okstra_ctl/report_views.py) — `_inline` `<br>` 보존; generic Ticket-ID grouping 분기 + Execution Status 분기 제거(§5 grouping 유지); plain 폭 보강.
+4. [`tests/test_report_views.py`](../../../tests/test_report_views.py) — `<br>` 보존 테스트; §1/§3/§4 가 더는 grouped 분기 안 타고 `<br>` 가 보존되는지; §5 는 여전히 grouped + Expected form wide.
+5. (필요 시) [`tests/test_render_*`](../../../tests/) — 템플릿 렌더 결과의 표 구조 스냅샷/스모크.
+6. [`CHANGES.md`](../../../CHANGES.md) — 사용자 영향 항목.
+
+## 4. Enforcement / 검증
+
+- 단위: `test_report_views.py` 로 `_inline` `<br>` 보존 + §5 grouping 유지를 잠금.
+- 템플릿 렌더: 실제 `data.json`(또는 픽스처)로 렌더해 §1/§3/§4/Exec 표가 meta+prose 형태로 나오는지 + §5 가 평면 8-컬럼인지 확인.
+- **실제 재렌더 검증(BLOCKING)**: 기존 사용자 리포트(또는 픽스처)를 렌더해 `.md` 와 HTML view 양쪽이 compact 하게 나오고 §5 carry-in 파서가 여전히 8-컬럼을 파싱하는지 실행 확인.
+- `python3 -m pytest tests/` + `bash validators/validate-workflow.sh` + `npm run build` 통과.
+
+## 5. 트레이드오프 / 리스크
+
+- **트레이드오프:** §1/§3/§4 의 HTML view 가 grp-meta "key: value" 폴리시 대신 `<br>` stack 형태가 된다(살짝 덜 꾸며짐). 대신 `.md`↔HTML 레이아웃이 일관되고 `.md` 자체가 어떤 에디터에서도 읽기 쉽다(사용자 목표).
+- **리스크 — 전 task-type 영향:** 템플릿이 공유라 모든 phase 의 final-report `.md` 구조가 바뀐다. 기계 파싱은 §5 뿐이라 안전하나, 구현 시 전체 테스트 + 실제 렌더로 회귀 확인.
+- **리스크 — `<br>` 미지원 에디터:** 드물게 표 셀 `<br>` 를 literal 로 보이는 렌더러가 있을 수 있음. 주류(GitHub/Obsidian/Typora/VS Code)는 지원. 정본 가독성 목표상 수용.
+
+## 6. 수용 기준
+
+1. final-report `.md` 의 §1/§1.1/§1.2/§3.1/§3.2/§4 + Execution Status 가 meta(`<br>` stack) + prose 컬럼 형태로 렌더된다.
+2. §5 Clarification 은 평면 8-컬럼 유지, carry-in 파서·validator 통과.
+3. HTML view 가 meta 셀의 `<br>` 를 줄바꿈으로 보여준다(`_inline` 보존).
+4. report_views 의 §1/§3/§4 generic grouping·Execution Status 분기는 제거되고 §5 grouping(+Expected form wide)은 유지.
+5. `python3 -m pytest tests/` + validator + build 통과 + 실제 재렌더 육안 확인.