okstra 0.36.2 → 0.38.0

package/docs/superpowers/plans/2026-05-26-wizard-3-option-picker.md

@@ -0,0 +1,860 @@
+# wizard.py 모든 사용자 입력 단계 3-옵션 picker 통일 Implementation Plan
+
+> **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:** `okstra-run` 진행 중 사용자 입력이 필요한 모든 wizard 단계를 "추천 1~2개 + 직접 입력 = 총 3개 옵션" picker로 통일한다. 마지막 옵션은 항상 "직접 입력"이며, 추천 후보가 마땅치 않은 단계는 더미라도 1개를 박아 형태를 유지한다.
+
+**Architecture:** `scripts/okstra_ctl/wizard.py`가 단일 권위(single authority). 모든 prompt 정의(`label`, `options`)는 `prompts/wizard/prompts.ko.json` SSOT에서 읽고, 추천 후보 생성 로직은 wizard.py 의 `_build_*` 함수에 추가한다. `okstra-run` 스킬 본문은 picker를 발명하지 않고 wizard가 내려준 prompt를 그대로 릴레이한다. 사용자가 마지막 "직접 입력" 옵션을 고르면 별도의 `*_text` step으로 전이하여 자유 텍스트를 받는다 — 기존 `S_BASE_REF_PICK → S_BASE_REF_TEXT` 패턴을 모든 단계에 일반화하는 작업이다.
+
+**Tech Stack:** Python 3 (wizard 본체), JSON (prompt 정의 SSOT), pytest (단위 테스트), bash (e2e), Conventional Commits + release-please.
+
+---
+
+## 변경 대상 단계 요약
+
+| # | 단계 | 현 상태 | 목표 |
+|---|------|---------|------|
+| 1 | `S_BRIEF_PATH` | text only | `S_BRIEF_PATH_PICK`(3-옵션) + 기존 `S_BRIEF_PATH`(직접 입력 후 진입) |
+| 2 | `S_TASK_GROUP` (suggestion 없음 분기) | text 직진 | 항상 picker로 — 최근 task-group 추천 + 직접 입력 |
+| 3 | `S_TASK_ID` (suggestion 없음 분기) | text 직진 | 항상 picker로 — 같은 group 의 기존 task-id 추천 + 직접 입력 |
+| 4 | `S_APPROVED_PLAN_PICK` | 2-옵션 (default/other) | 3-옵션 — default + 같은 task의 다른 final-report 후보 + 직접 입력 |
+| 5 | `S_DIRECTIVE_PICK` | 2-옵션 (skip/enter) | 3-옵션 — skip(=빈 줄, phase default) + 이전 run directive 재사용 + 직접 입력 |
+| 6 | `S_RELATED_TASKS_PICK` | 2-옵션 (skip/enter) | 3-옵션 — skip + 같은 task-group 의 다른 task-id 자동 후보 + 직접 입력 |
+| 7 | `S_CLARIFICATION_PICK` | 2-옵션 (skip/enter) | 3-옵션 — skip + 최근 final-report-* 자동 추출 + 직접 입력 |
+| 8 | `S_PR_TEMPLATE_PICK` | 2-옵션 (skip/enter) | 3-옵션 — auto-resolve(=skip) + project.json 등록 경로 + 직접 입력 |
+
+영향 받지 않는 단계:
+- `S_TASK_PICK`, `S_TASK_TYPE`, `S_BASE_REF_PICK`, `S_BRIEF_KEEP`, `S_EXECUTOR`, `S_DEFAULTS_OR_CUSTOM`, `S_STAGE_PICK`, `S_WORKERS_OVERRIDE`, `S_PR_TEMPLATE_SCOPE`, `S_CONFIRM`, `S_EDIT_TARGET` — 이미 3개 이상 옵션이거나 자유 텍스트 입력 자체가 없는 단계.
+- `S_TASK_GROUP_TEXT`, `S_TASK_ID_TEXT`, `S_BASE_REF_TEXT`, `S_BRIEF_PATH`(개편 후), `S_APPROVED_PLAN`, `S_DIRECTIVE`, `S_RELATED_TASKS`, `S_CLARIFICATION`, `S_PR_TEMPLATE` — "직접 입력" 분기 뒤의 free-text step. 사용자가 picker 의 마지막 옵션을 명시적으로 골랐을 때만 진입하므로 그대로 둔다.
+
+## File Structure
+
+- Modify: `scripts/okstra_ctl/wizard.py` — `_build_*` / `_submit_*` 함수 8개 변경, step sequence 1곳 추가, 새 상수 토큰 추가.
+- Modify: `prompts/wizard/prompts.ko.json` — 단계별 `options` 블록 추가/수정.
+- Test: `tests/test_okstra_ctl_wizard.py` — 각 단계 picker 옵션 수 / 마지막이 "직접 입력" / 추천 분기 동작 검증.
+- Test: `tests/test_wizard_prompts.py` — SSOT JSON 무결성 검증 (옵션 수, 토큰 명).
+- E2E (선택): `tests-e2e/scenario-10-wizard-3-option-picker.sh` — 새 시나리오 추가 여부는 Task 9에서 결정.
+
+## 공통 규약
+
+- **마지막 옵션 값 토큰**: 신규 단계는 일관된 토큰 `__free_input__` 을 사용 (이미 `S_BASE_REF_PICK`, `S_TASK_GROUP`, `S_TASK_ID` 에서 같은 토큰 사용 중). `PICK_TYPE_CUSTOM = "__free_input__"` 상수가 이미 정의됨.
+- **마지막 옵션 라벨**: 모든 picker 에서 한국어 "직접 입력" 으로 통일 — 학습 비용 0.
+- **추천이 없는 경우의 더미 채우기**: 의미 있는 자동 추출 후보가 0개라면 "건너뛰기 (빈 줄 = phase default)" 1개를 추천으로 박는다. 이 경우 picker 는 (skip + 직접 입력) 2-옵션이 아니라 (skip + 비추천 안내 + 직접 입력) 3-옵션이 되도록 하지 않는다 — 사용자 결정(메모리 `feedback_okstra_run_prompts_offer_recommendations.md`)에서 "단계별 합리적 자동 추출이 안 되는 경우 더미 추천 1개를 박는다"고 정해진 바에 따라 진짜 의미 있는 후보가 1개라도 잡히면 그것을 추가하고, 진짜로 0개일 때만 2-옵션으로 폴백한다. **단, 폴백 시에도 라벨은 "직접 입력"으로 통일**.
+- **추천 후보 자동 추출 헬퍼**: 신규 추출 로직은 `wizard.py` 안의 module-level `def _suggest_<step>(state: WizardState) -> list[tuple[str, str]]:` 형태로 분리 — `_build_*` 가 호출. 테스트 가능성 확보.
+- **언어**: prompt label / option label 은 한국어, value 토큰은 영문 (`__free_input__`, `__skip__`, `__use_default__` 등 기존 컨벤션 유지).
+- **Pre-1.0**: 기존 2-옵션 토큰(`__skip__`, `__enter__`)은 그대로 유지하되, `__enter__` 의미가 "(직접 입력으로 분기)" 라는 것을 유지. 새 추천 토큰은 단계별로 `__recent__` / `__latest_report__` / `__project_default__` 등 의미 있는 이름.
+
+---
+
+### Task 1: `S_BRIEF_PATH` 를 picker → text 2-단계 흐름으로 분해
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:171` (S_BRIEF_PATH 상수 근처 → S_BRIEF_PATH_PICK 추가), `:824-844` (`_build_brief_path` / `_submit_brief_path`), `:1423` (step sequence 등록부)
+- Modify: `prompts/wizard/prompts.ko.json:69-72` (brief_path 블록 → `brief_path_pick` 추가)
+- Test: `tests/test_okstra_ctl_wizard.py` (새 테스트 함수 `test_brief_path_pick_offers_three_options`)
+
+- [ ] **Step 1.1: 실패 테스트 작성**
+
+`tests/test_okstra_ctl_wizard.py` 끝에 추가:
+
+```python
+def test_brief_path_pick_offers_three_options(tmp_path, monkeypatch):
+    """S_BRIEF_PATH_PICK 은 반드시 3개 옵션(추천 1~2 + 직접 입력) 을 제시한다."""
+    from scripts.okstra_ctl.wizard import (
+        WizardState, _build_brief_path_pick, S_BRIEF_PATH_PICK,
+    )
+
+    # 기존 brief 가 존재하는 경우: existing brief 추천 + 새 표준 경로 추천 + 직접 입력
+    project_root = tmp_path / "proj"
+    (project_root / ".okstra" / "tasks" / "tg" / "tid").mkdir(parents=True)
+    existing = project_root / ".okstra" / "tasks" / "tg" / "tid" / "brief.md"
+    existing.write_text("---\napproved: false\n---\n", encoding="utf-8")
+    state = WizardState(
+        workspace_root="/Volumes/Workspaces/workspace/projects/Okstra",
+        project_root=str(project_root),
+        project_id="proj",
+        task_group="tg",
+        task_id="tid",
+        existing_brief_path=str(existing.relative_to(project_root)),
+    )
+    p = _build_brief_path_pick(state)
+
+    assert p.step == S_BRIEF_PATH_PICK
+    assert p.kind == "pick"
+    assert len(p.options) >= 3
+    assert p.options[-1].value == "__free_input__"
+    assert p.options[-1].label == "직접 입력"
+```
+
+- [ ] **Step 1.2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py::test_brief_path_pick_offers_three_options -v`
+Expected: FAIL with `ImportError: cannot import name 'S_BRIEF_PATH_PICK'` 또는 `AttributeError`.
+
+- [ ] **Step 1.3: 상수 + SSOT JSON 추가**
+
+`scripts/okstra_ctl/wizard.py` 상단 (S_BRIEF_PATH 상수 근처, 약 171줄) 에 추가:
+
+```python
+S_BRIEF_PATH_PICK = "brief_path_pick"
+```
+
+`prompts/wizard/prompts.ko.json` 의 `"brief_path"` 블록 바로 위에 추가:
+
+```json
+    "brief_path_pick": {
+      "label": "task brief markdown 의 경로를 선택해주세요",
+      "echo_template": "brief(pick): {value}",
+      "options": {
+        "__existing__": "기존 brief 사용: {existing}",
+        "__standard__": "표준 경로 사용: {standard}",
+        "__free_input__": "직접 입력"
+      },
+      "errors": {
+        "existing_missing": "기존 brief 가 없습니다. 다른 옵션을 선택하세요."
+      }
+    },
+```
+
+- [ ] **Step 1.4: `_build_brief_path_pick` / `_submit_brief_path_pick` 구현**
+
+`scripts/okstra_ctl/wizard.py` 의 `_build_brief_path` 정의 위에 추가 (대략 824줄 근처):
+
+```python
+def _suggest_brief_path(state: WizardState) -> tuple[str, str]:
+    """Return (existing_brief_relpath_or_empty, standard_relpath).
+    standard_relpath = ".okstra/tasks/<task-group>/<task-id>/brief.md"."""
+    existing = state.existing_brief_path or ""
+    tg = slugify_task_segment(state.task_group) if state.task_group else ""
+    tid = slugify_task_segment(state.task_id) if state.task_id else ""
+    if tg and tid:
+        standard = str(Path(".okstra") / "tasks" / tg / tid / "brief.md")
+    else:
+        standard = ""
+    return existing, standard
+
+
+def _build_brief_path_pick(state: WizardState) -> Prompt:
+    existing, standard = _suggest_brief_path(state)
+    t = _p(state.workspace_root, "brief_path_pick",
+           existing=existing or "(없음)",
+           standard=standard or "(타깃 미정)")
+    options: list[Option] = []
+    if existing:
+        options.append(_opt("__existing__",
+                            t["options"]["__existing__"].format(existing=existing)))
+    if standard and standard != existing:
+        options.append(_opt("__standard__",
+                            t["options"]["__standard__"].format(standard=standard)))
+    options.append(_opt("__free_input__", t["options"]["__free_input__"]))
+    return Prompt(step=S_BRIEF_PATH_PICK, kind="pick",
+                  label=t["label"], options=options,
+                  echo_template=t["echo_template"])
+
+
+def _submit_brief_path_pick(state: WizardState, value: str) -> Optional[str]:
+    existing, standard = _suggest_brief_path(state)
+    if value == "__existing__":
+        if not existing:
+            t = _p(state.workspace_root, "brief_path_pick",
+                   existing="(없음)", standard=standard or "(타깃 미정)")
+            raise WizardError(t["errors"]["existing_missing"])
+        p = _require_file(existing, Path(state.project_root), "task brief")
+        state.brief_path = str(p)
+        state.brief_path_pending_text = False
+        return f"brief: {p}"
+    if value == "__standard__":
+        p = _require_file(standard, Path(state.project_root), "task brief")
+        state.brief_path = str(p)
+        state.brief_path_pending_text = False
+        return f"brief: {p}"
+    if value == "__free_input__":
+        state.brief_path_pending_text = True
+        state.brief_path = ""
+        return None
+    raise WizardError(
+        f"expected '__existing__', '__standard__', or '__free_input__', "
+        f"got: {value!r}"
+    )
+```
+
+`WizardState` dataclass(파일 상단 정의부) 에 새 플래그 필드 추가:
+
+```python
+    brief_path_pending_text: bool = False
+```
+
+- [ ] **Step 1.5: step sequence 에 등록**
+
+`wizard.py:1423` 근처 `Step(S_BRIEF_PATH, ...)` 정의 바로 위에 추가:
+
+```python
+    Step(S_BRIEF_PATH_PICK,
+         applies=lambda s: (s.is_new_task or not s.keep_existing_brief)
+                            and S_BRIEF_PATH_PICK not in s.answered
+                            and not s.brief_path_pending_text,
+         build=_build_brief_path_pick,
+         submit=_submit_brief_path_pick,
+         owns=("brief_path_pending_text",)),
+```
+
+기존 `Step(S_BRIEF_PATH, ...)` 의 `applies` 람다를 다음과 같이 수정 (해당 단계는 직접 입력 분기에서만 활성화):
+
+```python
+    Step(S_BRIEF_PATH,
+         applies=lambda s: s.brief_path_pending_text
+                            and S_BRIEF_PATH not in s.answered,
+         build=_build_brief_path,
+         submit=_submit_brief_path,
+         owns=("brief_path",)),
+```
+
+- [ ] **Step 1.6: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py::test_brief_path_pick_offers_three_options -v`
+Expected: PASS.
+
+추가로 기존 `tests/test_okstra_ctl_wizard.py` 의 brief 관련 테스트들이 깨지지 않는지 확인:
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py -v -k brief`
+Expected: 모든 brief 테스트 PASS — 필요 시 기존 테스트가 `brief_path_pending_text=True` 를 미리 세팅하도록 픽스 (한 줄 추가).
+
+- [ ] **Step 1.7: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py prompts/wizard/prompts.ko.json tests/test_okstra_ctl_wizard.py
+git commit -m "feat(wizard): brief-path를 3-옵션 picker로 분해"
+```
+
+---
+
+### Task 2: `S_TASK_GROUP` (suggestion 없을 때) 항상 picker 로
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:660-697`
+- Modify: `prompts/wizard/prompts.ko.json:13-19, 20-27`
+- Test: `tests/test_okstra_ctl_wizard.py` 끝에 `test_task_group_without_suggestion_offers_picker`
+
+- [ ] **Step 2.1: 실패 테스트 작성**
+
+```python
+def test_task_group_without_suggestion_offers_picker(tmp_path):
+    """task_group_suggestion 이 없어도 picker 가 떠야 한다."""
+    from scripts.okstra_ctl.wizard import WizardState, _build_task_group
+
+    state = WizardState(
+        workspace_root="/Volumes/Workspaces/workspace/projects/Okstra",
+        project_root=str(tmp_path),
+        project_id="proj",
+        is_new_task=True,
+        task_group_suggestion="",
+    )
+    p = _build_task_group(state)
+
+    assert p.kind == "pick"
+    assert len(p.options) >= 2
+    assert p.options[-1].value == "__free_input__"
+    assert p.options[-1].label == "직접 입력"
+```
+
+- [ ] **Step 2.2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py::test_task_group_without_suggestion_offers_picker -v`
+Expected: FAIL — `_build_task_group` 가 `kind="text"` 를 반환.
+
+- [ ] **Step 2.3: 추천 후보 헬퍼 추가**
+
+`_build_task_group` 위에 추가:
+
+```python
+def _suggest_recent_task_groups(state: WizardState, limit: int = 2) -> list[str]:
+    """프로젝트 catalog 에서 최근 task-group 후보를 limit 개까지 반환."""
+    if not state.project_root:
+        return []
+    try:
+        tasks = list_project_tasks(Path(state.project_root))
+    except Exception:
+        return []
+    seen: list[str] = []
+    for entry in tasks:
+        tg = entry.get("taskGroup") or ""
+        if tg and tg not in seen:
+            seen.append(tg)
+        if len(seen) >= limit:
+            break
+    return seen
+```
+
+- [ ] **Step 2.4: `_build_task_group` 재작성**
+
+`wizard.py:660-677` 의 `_build_task_group` 을 다음으로 교체:
+
+```python
+def _build_task_group(state: WizardState) -> Prompt:
+    sugg = state.task_group_suggestion
+    if sugg:
+        t = _p(state.workspace_root, "task_group_with_suggestion",
+               suggestion=sugg)
+        options = [
+            _opt(k, v.format(suggestion=sugg))
+            for k, v in t["options"].items()
+        ]
+        return Prompt(
+            step=S_TASK_GROUP, kind="pick",
+            label=t["label"], options=options,
+            echo_template=t["echo_template"],
+        )
+    # suggestion 이 없으면 catalog 의 최근 task-group 을 후보로 노출 + 직접 입력
+    recent = _suggest_recent_task_groups(state, limit=2)
+    t = _p(state.workspace_root, "task_group_no_suggestion")
+    options: list[Option] = []
+    for tg in recent:
+        options.append(_opt(f"__recent:{tg}", f"최근 사용: {tg}"))
+    options.append(_opt("__free_input__", t["options"]["__free_input__"]))
+    return Prompt(
+        step=S_TASK_GROUP, kind="pick",
+        label=t["label"], options=options,
+        echo_template=t["echo_template"],
+    )
+```
+
+- [ ] **Step 2.5: `_submit_task_group` 확장**
+
+`wizard.py:680-698` 의 `_submit_task_group` 에 `__recent:` 분기 추가:
+
+```python
+def _submit_task_group(state: WizardState, value: str) -> Optional[str]:
+    if state.task_group_suggestion:
+        if value == PICK_USE_SUGGESTED:
+            state.task_group = _slug_or_die(
+                state.task_group_suggestion, "task_group"
+            )
+            state.task_group_pending_text = False
+            return f"task-group: {state.task_group} (brief)"
+        if value == PICK_TYPE_CUSTOM:
+            state.task_group_pending_text = True
+            t = _p(state.workspace_root, "task_group_with_suggestion",
+                   suggestion=state.task_group_suggestion)
+            return t["echo_variants"]["free_input"]
+        raise WizardError(
+            f"expected {PICK_USE_SUGGESTED!r} or {PICK_TYPE_CUSTOM!r}, "
+            f"got: {value!r}"
+        )
+    if value.startswith("__recent:"):
+        tg = value[len("__recent:"):]
+        state.task_group = _slug_or_die(tg, "task_group")
+        state.task_group_pending_text = False
+        return f"task-group: {state.task_group} (recent)"
+    if value == PICK_TYPE_CUSTOM:
+        state.task_group_pending_text = True
+        return "task-group: (직접 입력)"
+    # 기존 호환: free-text 값이 직접 들어오는 케이스(폴백)
+    state.task_group = _slug_or_die(value, "task_group")
+    state.task_group_pending_text = False
+    return f"task-group: {state.task_group}"
+```
+
+- [ ] **Step 2.6: SSOT JSON 에 새 step 정의 추가**
+
+`prompts/wizard/prompts.ko.json` 의 `"task_group"` 블록 다음에 추가:
+
+```json
+    "task_group_no_suggestion": {
+      "label": "Task group? (예: backend-api, INV-1234)",
+      "echo_template": "task-group: {value}",
+      "options": {
+        "__free_input__": "직접 입력"
+      }
+    },
+```
+
+- [ ] **Step 2.7: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py -v -k task_group`
+Expected: 모든 task_group 테스트 PASS.
+
+- [ ] **Step 2.8: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py prompts/wizard/prompts.ko.json tests/test_okstra_ctl_wizard.py
+git commit -m "feat(wizard): task-group suggestion 없을 때도 3-옵션 picker"
+```
+
+---
+
+### Task 3: `S_TASK_ID` (suggestion 없을 때) 항상 picker 로
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:714-750`
+- Modify: `prompts/wizard/prompts.ko.json:32-46`
+- Test: `tests/test_okstra_ctl_wizard.py` — `test_task_id_without_suggestion_offers_picker`
+
+- [ ] **Step 3.1: 실패 테스트 작성**
+
+```python
+def test_task_id_without_suggestion_offers_picker(tmp_path):
+    from scripts.okstra_ctl.wizard import WizardState, _build_task_id
+
+    state = WizardState(
+        workspace_root="/Volumes/Workspaces/workspace/projects/Okstra",
+        project_root=str(tmp_path),
+        project_id="proj",
+        task_group="backend-api",
+        is_new_task=True,
+        task_id_suggestion="",
+    )
+    p = _build_task_id(state)
+
+    assert p.kind == "pick"
+    assert len(p.options) >= 1  # 최소 "직접 입력" 1개
+    assert p.options[-1].value == "__free_input__"
+    assert p.options[-1].label == "직접 입력"
+```
+
+- [ ] **Step 3.2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py::test_task_id_without_suggestion_offers_picker -v`
+Expected: FAIL — kind == "text".
+
+- [ ] **Step 3.3: 추천 후보 헬퍼 + `_build_task_id` 재작성**
+
+`_build_task_id` 위에 추가:
+
+```python
+def _suggest_recent_task_ids(state: WizardState, limit: int = 2) -> list[str]:
+    """현재 task_group 내의 최근 task-id 후보를 limit 개까지 반환."""
+    if not state.project_root or not state.task_group:
+        return []
+    try:
+        tasks = list_project_tasks(Path(state.project_root))
+    except Exception:
+        return []
+    seen: list[str] = []
+    for entry in tasks:
+        tg = entry.get("taskGroup") or ""
+        if tg != state.task_group:
+            continue
+        tid = entry.get("taskId") or ""
+        if tid and tid not in seen:
+            seen.append(tid)
+        if len(seen) >= limit:
+            break
+    return seen
+```
+
+`_build_task_id` 교체:
+
+```python
+def _build_task_id(state: WizardState) -> Prompt:
+    sugg = state.task_id_suggestion
+    if sugg:
+        t = _p(state.workspace_root, "task_id_with_suggestion",
+               suggestion=sugg)
+        options = [
+            _opt(k, v.format(suggestion=sugg))
+            for k, v in t["options"].items()
+        ]
+        return Prompt(
+            step=S_TASK_ID, kind="pick",
+            label=t["label"], options=options,
+            echo_template=t["echo_template"],
+        )
+    recent = _suggest_recent_task_ids(state, limit=2)
+    t = _p(state.workspace_root, "task_id_no_suggestion")
+    options: list[Option] = []
+    for tid in recent:
+        options.append(_opt(f"__recent:{tid}", f"같은 group 의 기존: {tid}"))
+    options.append(_opt("__free_input__", t["options"]["__free_input__"]))
+    return Prompt(
+        step=S_TASK_ID, kind="pick",
+        label=t["label"], options=options,
+        echo_template=t["echo_template"],
+    )
+```
+
+- [ ] **Step 3.4: `_submit_task_id` 확장**
+
+Task 2 의 `_submit_task_group` 과 동일 패턴으로 `__recent:` 분기 추가, `PICK_TYPE_CUSTOM` 직접 입력 분기 추가.
+
+- [ ] **Step 3.5: SSOT JSON 에 `task_id_no_suggestion` 추가**
+
+```json
+    "task_id_no_suggestion": {
+      "label": "Task id? (예: login-error-analysis, dev-9043)",
+      "echo_template": "task-id: {value}",
+      "options": {
+        "__free_input__": "직접 입력"
+      }
+    },
+```
+
+- [ ] **Step 3.6: 테스트 통과 확인 + 커밋**
+
+Run: `python3 -m pytest tests/test_okstra_ctl_wizard.py -v -k task_id`
+Expected: PASS.
+
+```bash
+git commit -m "feat(wizard): task-id suggestion 없을 때도 3-옵션 picker"
+```
+
+---
+
+### Task 4: `S_APPROVED_PLAN_PICK` 를 3-옵션으로 확장
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:930-962`
+- Modify: `prompts/wizard/prompts.ko.json:85-94`
+
+- [ ] **Step 4.1: 실패 테스트 작성**
+
+```python
+def test_approved_plan_pick_lists_other_reports(tmp_path):
+    """latest 외에 같은 task 의 다른 final-report 도 후보로 노출되어야 한다."""
+    from scripts.okstra_ctl.wizard import (
+        WizardState, _build_approved_plan_pick,
+    )
+    # 가짜 final-report 3개를 만들고 build 가 최소 3개 옵션(default + 다른 후보 1+ + 직접 입력) 을 노출하는지 확인.
+    ...  # 세부 setup 은 기존 _latest_implementation_planning_report 헬퍼 패턴 참고
+```
+
+(테스트 세부는 `_latest_implementation_planning_report` 가 사용하는 디렉토리 레이아웃을 그대로 재현)
+
+- [ ] **Step 4.2: 실패 확인 → 구현**
+
+`_latest_implementation_planning_report` 옆에 `_list_implementation_planning_reports(state, limit=3)` 헬퍼 추가:
+
+```python
+def _list_implementation_planning_reports(state: WizardState, limit: int = 3) -> list[Path]:
+    """task 의 implementation-planning runs 디렉토리에서 최신순으로 final-report 경로를 limit 개까지 반환."""
+    if not state.task_group or not state.task_id or not state.project_root:
+        return []
+    base = (tasks_root(state.project_root)
+            / slugify_task_segment(state.task_group)
+            / slugify_task_segment(state.task_id)
+            / "runs" / "implementation-planning")
+    if not base.is_dir():
+        return []
+    pat = re.compile(r"^final-report-implementation-planning-(\d+)\.md$")
+    found: list[tuple[int, Path]] = []
+    for run_dir in base.iterdir():
+        reports = run_dir / "reports"
+        if not reports.is_dir():
+            continue
+        for child in reports.iterdir():
+            m = pat.match(child.name)
+            if not m:
+                continue
+            found.append((int(m.group(1)), child))
+    found.sort(key=lambda x: -x[0])
+    out: list[Path] = []
+    for _, p in found[:limit]:
+        try:
+            out.append(p.relative_to(Path(state.project_root)))
+        except ValueError:
+            out.append(p)
+    return out
+```
+
+`_build_approved_plan_pick` 재작성:
+
+```python
+def _build_approved_plan_pick(state: WizardState) -> Prompt:
+    reports = _list_implementation_planning_reports(state, limit=3)
+    default = reports[0] if reports else None
+    t = _p(state.workspace_root, "approved_plan_pick",
+           default=str(default) if default is not None else "")
+    options: list[Option] = []
+    if default is not None:
+        options.append(_opt(PICK_USE_DEFAULT,
+                            t["options"][PICK_USE_DEFAULT].format(default=str(default))))
+    for p in reports[1:]:
+        options.append(_opt(f"__report:{p}", f"이전 보고서: {p}"))
+    options.append(_opt(PICK_OTHER, t["options"][PICK_OTHER]))
+    return Prompt(
+        step=S_APPROVED_PLAN_PICK, kind="pick",
+        label=t["label"], options=options,
+        echo_template=t["echo_template"],
+    )
+```
+
+`_submit_approved_plan_pick` 에 `__report:` 분기 추가 (default 분기와 동일 구조, path 만 다름).
+
+- [ ] **Step 4.3: SSOT JSON 의 `__other__` 라벨을 "직접 입력" 으로 통일**
+
+```json
+        "__other__": "직접 입력"
+```
+
+- [ ] **Step 4.4: 테스트 통과 확인 + 커밋**
+
+```bash
+git commit -m "feat(wizard): approved-plan picker에 과거 보고서 후보 노출"
+```
+
+---
+
+### Task 5: `S_DIRECTIVE_PICK` 를 3-옵션으로
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:1028-1046`
+- Modify: `prompts/wizard/prompts.ko.json:107-114`
+
+추천 후보 정책:
+- `__skip__`: "건너뛰기 (phase 기본값 사용 = 빈 줄)" — 항상 노출
+- `__reuse_last__`: 같은 task 의 가장 최근 run-inputs JSON 에서 `directive` 값을 자동 추출, 비어있지 않으면 노출 — 없으면 옵션 미노출
+- `__free_input__` (= 기존 `__enter__`): "직접 입력" — 항상 마지막
+
+`__enter__` 토큰은 `__free_input__` 으로 리네임 (라벨도 "직접 입력" 통일). Pre-1.0 정책에 따라 호환 토큰은 두지 않음.
+
+- [ ] **Step 5.1: 헬퍼 추가**
+
+```python
+def _suggest_last_directive(state: WizardState) -> str:
+    """같은 task 의 가장 최근 run-inputs-*.json 에서 directive 값을 자동 추출."""
+    if not state.task_group or not state.task_id or not state.project_root:
+        return ""
+    runs_base = (tasks_root(state.project_root)
+                 / slugify_task_segment(state.task_group)
+                 / slugify_task_segment(state.task_id) / "runs")
+    if not runs_base.is_dir():
+        return ""
+    candidates: list[tuple[float, Path]] = []
+    for phase_dir in runs_base.iterdir():
+        if not phase_dir.is_dir():
+            continue
+        for run_dir in phase_dir.iterdir():
+            for p in run_dir.glob("run-inputs-*.json"):
+                try:
+                    candidates.append((p.stat().st_mtime, p))
+                except OSError:
+                    continue
+    if not candidates:
+        return ""
+    candidates.sort(key=lambda x: -x[0])
+    import json as _json
+    try:
+        data = _json.loads(candidates[0][1].read_text(encoding="utf-8"))
+    except Exception:
+        return ""
+    val = data.get("directive") or ""
+    return val if isinstance(val, str) else ""
+```
+
+- [ ] **Step 5.2: `_build_directive_pick` 재작성**
+
+```python
+def _build_directive_pick(state: WizardState) -> Prompt:
+    last = _suggest_last_directive(state)
+    t = _p(state.workspace_root, "directive_pick")
+    options: list[Option] = []
+    options.append(_opt("__skip__", t["options"]["__skip__"]))
+    if last:
+        snippet = last[:60] + ("…" if len(last) > 60 else "")
+        options.append(_opt("__reuse_last__", f"이전 run 의 directive 재사용: {snippet}"))
+        state.last_directive_cached = last
+    options.append(_opt("__free_input__", t["options"]["__free_input__"]))
+    return Prompt(step=S_DIRECTIVE_PICK, kind="pick",
+                  label=t["label"], options=options,
+                  echo_template=t["echo_template"])
+```
+
+`WizardState` 에 `last_directive_cached: str = ""` 필드 추가 (재사용 분기에서 값을 그대로 쓰기 위해).
+
+- [ ] **Step 5.3: `_submit_directive_pick` 재작성**
+
+```python
+def _submit_directive_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == "__skip__":
+        state.directive = ""
+        state.directive_pending_text = False
+        return "directive: (none)"
+    if value == "__reuse_last__":
+        state.directive = state.last_directive_cached
+        state.directive_pending_text = False
+        return f"directive: {state.directive} (재사용)"
+    if value == "__free_input__":
+        state.directive_pending_text = True
+        return None
+    raise WizardError(
+        f"expected '__skip__', '__reuse_last__', or '__free_input__', "
+        f"got: {value!r}"
+    )
+```
+
+- [ ] **Step 5.4: SSOT JSON 옵션 토큰/라벨 통일**
+
+```json
+    "directive_pick": {
+      "label": "추가 directive 가 있나요?",
+      "echo_template": "directive(pick): {value}",
+      "options": {
+        "__skip__": "없음 (건너뛰기)",
+        "__free_input__": "직접 입력"
+      }
+    },
+```
+
+(`__reuse_last__` 옵션은 런타임 추가 시에만 노출되므로 SSOT 에 두지 않거나 옵션으로만 표기 — 라벨은 build 시 동적 결정 필요. 본 plan 에서는 SSOT 라벨은 base 옵션만 둔다)
+
+- [ ] **Step 5.5: 테스트 통과 + 커밋**
+
+```bash
+git commit -m "feat(wizard): directive picker에 이전 run 재사용 옵션 추가"
+```
+
+---
+
+### Task 6: `S_RELATED_TASKS_PICK` 를 3-옵션으로
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:1049-1067`
+- Modify: `prompts/wizard/prompts.ko.json:115-122`
+
+추천 후보 정책:
+- `__skip__`: 없음 — 항상
+- `__siblings__`: 같은 task-group 의 다른 task-id 들을 CSV 로 자동 추출 (비어있지 않으면 노출)
+- `__free_input__`: 직접 입력 — 항상 마지막
+
+- [ ] **Step 6.1~6.4: 헬퍼/build/submit/SSOT 동일 패턴으로 구현**
+
+`_suggest_sibling_task_ids(state)` 헬퍼는 Task 3 의 `_suggest_recent_task_ids` 와 유사하되 limit 제한 없이 전부 모아 CSV 조립.
+
+- [ ] **Step 6.5: 커밋**
+
+```bash
+git commit -m "feat(wizard): related-tasks picker에 sibling task-id 자동 추천"
+```
+
+---
+
+### Task 7: `S_CLARIFICATION_PICK` 를 3-옵션으로
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:1070-1088`
+- Modify: `prompts/wizard/prompts.ko.json:123-130`
+
+추천 후보 정책:
+- `__skip__`: 없음 — 항상
+- `__latest_report__`: 같은 task 의 가장 최근 `final-report-*.md` 경로 (clarification 은 follow-up 시 직전 보고서를 참조하는 경우가 흔함). `_list_implementation_planning_reports` 를 일반화해 phase 무관 latest report 헬퍼 추가 (`_latest_final_report(state)`).
+- `__free_input__`: 직접 입력 — 항상 마지막
+
+- [ ] **Step 7.1~7.5: 같은 패턴으로 구현 + 커밋**
+
+```bash
+git commit -m "feat(wizard): clarification picker에 최근 final-report 자동 추천"
+```
+
+---
+
+### Task 8: `S_PR_TEMPLATE_PICK` 를 3-옵션으로
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py:1091-1110`
+- Modify: `prompts/wizard/prompts.ko.json:131-138`
+
+추천 후보 정책:
+- `__skip__`: "자동 해석 (project.json → config → 기본)" — 항상 (auto-resolve = 빈 줄)
+- `__project_default__`: project.json 에 `prTemplatePath` 가 등록되어 있으면 그 경로 노출 — 없으면 옵션 미노출
+- `__free_input__`: 직접 입력 — 항상 마지막
+
+`okstra config get pr-template-path --scope project --json` 같은 기존 API 가 있는지 우선 확인 (Task 8.1 의 사전 조사). 없다면 `<project_root>/.okstra/project.json` 을 직접 읽어 `prTemplatePath` 필드 검사.
+
+- [ ] **Step 8.1~8.5: 동일 패턴 + 커밋**
+
+```bash
+git commit -m "feat(wizard): pr-template picker에 project default 후보 노출"
+```
+
+---
+
+### Task 9: 통합 검증 + e2e 시나리오 + 문서 업데이트
+
+**Files:**
+- Modify: `tests/test_wizard_prompts.py` — 모든 `*_pick` 단계가 최소 옵션 수와 마지막 옵션 토큰을 충족하는지 검증
+- (선택) Create: `tests-e2e/scenario-10-wizard-3-option-picker.sh` — wizard init → 각 단계 picker prompt JSON 검사
+- Modify: `CHANGES.md` — 사용자 영향 한 줄 추가
+- Modify: `skills/okstra-run/SKILL.md` — picker 가 표준이라는 점 한 줄 보강 (선택)
+
+- [ ] **Step 9.1: 옵션 수/마지막 토큰 통합 테스트**
+
+`tests/test_wizard_prompts.py` 끝에 추가:
+
+```python
+def test_every_pick_step_ends_with_free_input(tmp_path):
+    """모든 *_pick 단계는 최소 2개 옵션이며 마지막은 __free_input__ 토큰이어야 한다."""
+    from scripts.okstra_ctl.wizard import (
+        WizardState, _build_brief_path_pick, _build_task_group, _build_task_id,
+        _build_approved_plan_pick, _build_directive_pick,
+        _build_related_tasks_pick, _build_clarification_pick,
+        _build_pr_template_pick,
+    )
+    # 각 단계마다 합리적 state 를 만들어서 build → 옵션 마지막 검사
+    ...
+```
+
+- [ ] **Step 9.2: 전체 회귀 테스트**
+
+Run: `python3 -m pytest tests/ -v`
+Expected: 모두 PASS. 깨지는 테스트가 있으면 그 자리에서 수정.
+
+Run: `bash validators/validate-workflow.sh`
+Expected: PASS.
+
+- [ ] **Step 9.3: 빌드 + 스모크**
+
+```bash
+npm run build
+node bin/okstra --version
+node bin/okstra doctor
+```
+
+- [ ] **Step 9.4: e2e 시나리오 (선택)**
+
+여력이 되면 `tests-e2e/scenario-10-wizard-3-option-picker.sh` 추가:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+OKSTRA_HOME="$(mktemp -d)"
+export OKSTRA_HOME
+trap 'rm -rf "$OKSTRA_HOME"' EXIT
+
+# wizard init → 8개 picker 모두에서 kind=="pick" 및 마지막 option value==__free_input__ 확인
+...
+```
+
+- [ ] **Step 9.5: CHANGES.md 업데이트 (한국어, 사용자 영향)**
+
+```markdown
+## [Unreleased]
+- wizard 모든 입력 단계를 "추천 1~2개 + 직접 입력" 3-옵션 picker 로 통일
+  - 사용자 영향: okstra run 의 brief 경로, task-group/id, approved-plan, directive, related-tasks, clarification, pr-template 단계가 모두 picker 로 표시됨. 마지막 옵션은 항상 "직접 입력".
+```
+
+- [ ] **Step 9.6: 최종 커밋**
+
+```bash
+git add CHANGES.md tests/test_wizard_prompts.py tests-e2e/scenario-10-wizard-3-option-picker.sh
+git commit -m "test(wizard): 모든 picker 마지막 옵션이 직접 입력인지 검증"
+```
+
+---
+
+## Self-Review Checklist
+
+작업 종료 직전 다음을 확인:
+
+1. **Spec coverage** — 8개 단계 모두 picker(추천 1~2개 + 직접 입력)로 전환되었는가? Task 표와 대조하여 빠진 게 없는지 점검.
+2. **마지막 옵션 일관성** — 모든 `*_pick` 단계에서 `options[-1].value == "__free_input__"` 그리고 `options[-1].label == "직접 입력"` 인가? Task 9.1 의 통합 테스트가 이것을 강제.
+3. **단일 권위 유지** — `okstra-run` 스킬 본문이 picker 를 발명하는 추가 코드를 도입하지 않았는가? wizard.py 가 내려준 prompt 만 릴레이.
+4. **추천 후보 0개 폴백** — 의미 있는 자동 추출이 0개인 경우 폴백은 어떤 모습인가? `skip + 직접 입력` 2-옵션 또는 `skip + 더미 안내 + 직접 입력` 중 어느 쪽? 본 plan 은 2-옵션 폴백을 허용 (메모리 정책: "추천이 0개이면 폴백 OK") — 단, 마지막 옵션은 항상 "직접 입력".
+5. **Pre-1.0** — `__enter__` 토큰 제거 시 호환 shim 두지 말 것. CHANGES.md 에 명시.
+6. **테스트 격리** — 새 테스트가 `OKSTRA_HOME` 을 별도 tmp_path 로 사용하는가? `tests/conftest.py` 가 자동 격리하지만 e2e 는 명시적 `mktemp -d`.
+
+## 실행 핸드오프
+
+Plan 작성 완료. 실행 옵션:
+
+**1. Subagent-Driven (권장)** — Task 마다 신선한 subagent 를 띄워 두 단계 review checkpoint 로 점진 진행. 각 task 가 독립 commit 으로 끝나므로 적합.
+
+**2. Inline Execution** — 현 세션에서 `superpowers:executing-plans` 로 batch 진행. 8개 task × 평균 6-step = 약 50 step 이므로 컨텍스트 부담은 있으나 단일 세션 일관성 유지.