okstra 0.34.1 → 0.36.1

package/docs/superpowers/plans/2026-05-20-wizard-prompt-json-sot-a1.md

@@ -0,0 +1,681 @@
+# Wizard Prompt JSON SOT (Phase A1) 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:** `scripts/okstra_ctl/wizard.py` 의 한글 UI 문자열 (label / echo_template / 정적 option label) 을 `prompts/wizard/prompts.ko.json` 단독 권위로 분리한다. wizard.py 는 상태 머신 + 동적 옵션 계산만 담당, 한글 문자열 0개.
+
+**Architecture:**
+1. JSON SOT 파일 `prompts/wizard/prompts.ko.json` — step id 별로 `label`, `echo_template`, (optional) `options{}` 보유.
+2. wizard.py 가 `workspace_root` 를 통해 JSON 을 lazy-load (기존 `prompts/profiles/*.md` 패턴과 동일 — install 시 `~/.okstra/` 로 복사 안 되고 npm 패키지의 `runtime/prompts/` 에서 직접 읽힘).
+3. 신규 `_p(workspace_root, step_id, **vars) -> dict` 헬퍼가 단일 lookup 진입점. placeholder 보간은 Python `str.format(**vars)`.
+4. `_build_*` 함수 ~28 개 일괄 migrate (atomic commit).
+5. 새 unit test 가 (a) step id 동기화 (wizard.py 의 `S_*` 상수 ↔ JSON 키 동치), (b) `_p()` placeholder 동작, (c) wizard.py 내 한글 문자 0개 grep gate 강제.
+
+**왜 JSON 인가** (spec 의 YAML 결정 변경):
+- 프로젝트는 npm 으로 배포 (`npx okstra@latest install`) — `pip install` 단계 없음.
+- PyYAML 은 stdlib 가 아니라 vendor 필요 — ~500KB 추가 비용. JSON 은 stdlib (`json`) — zero dep.
+- 구조 (label / echo_template / options) 와 placeholder 의미는 spec 와 동일.
+- 사용자 결정 (2026-05-20): JSON 채택.
+
+**Tech Stack:** Python 3 stdlib (`json`, `pathlib`, `re`), pytest, bash (grep gate)
+
+**Reference:** [docs/superpowers/specs/2026-05-20-okstra-run-prompt-sot-design.md](../specs/2026-05-20-okstra-run-prompt-sot-design.md) §3 (Phase A1). 본 plan 은 spec 의 YAML → JSON 으로 format 만 변경.
+
+---
+
+## File Structure
+
+**생성**
+- `prompts/wizard/prompts.ko.json` — 단일 SOT. ~28 step 엔트리.
+- `tests/test_wizard_prompts.py` — SOT-sync + `_p()` + Korean-char grep gate (Task 2 에서 생성, Task 4 에서 확장)
+
+**수정**
+- `scripts/okstra_ctl/wizard.py` — Task 2 에서 loader / `_p()` helper 추가, Task 3 에서 `_build_*` migrate
+- `CHANGES.md` — Task 5 사용자 영향 항목 추가
+
+**손대지 않음**
+- `tools/build.mjs` — 이미 `prompts/` 디렉터리 트리를 `runtime/prompts/` 로 동기화 — 자동으로 새 `wizard/` 서브디렉터리 포함
+- `src/install.mjs` — install 은 `prompts/` 를 `~/.okstra/` 로 복사 안 함. 그러나 wizard 가 `workspace_root` (npm 패키지의 `runtime/`) 에서 읽으므로 install 변경 불요
+- `runtime/` — 빌드 출력물, 수동 편집 금지
+
+---
+
+## Task 1: JSON SOT 파일 생성
+
+**Files:**
+- Create: `prompts/wizard/prompts.ko.json`
+
+이 task 는 wizard.py 의 한글 문자열을 **inventory** 하여 JSON 파일로 옮긴다. wizard.py 코드는 손대지 않음 (Task 3 에서). JSON 파일이 단독으로 commit 되어도 동작 동일성 유지 — 사용 caller 없음.
+
+### Step 1: wizard.py 의 prompt 사용처 inventory
+
+```bash
+grep -nE 'Prompt\(|label[ ]*=|echo_template[ ]*=' scripts/okstra_ctl/wizard.py | grep -vE '^[0-9]+:#' | head -80
+```
+
+추가 inventory:
+```bash
+grep -nE 'def _build_' scripts/okstra_ctl/wizard.py
+grep -nE '^S_[A-Z_]+ =' scripts/okstra_ctl/wizard.py
+```
+
+각 `_build_*(state) -> Prompt` 함수의 본문을 읽어 다음 데이터 형태로 추출:
+- step_id (S_* 상수 값 — 예: `S_TASK_PICK = "task_pick"` → step_id = `"task_pick"`)
+- `label` (한글 문자열, 또는 f-string interpolated 형태 — `{placeholder}` 로 변환)
+- `echo_template` (그대로)
+- 정적 옵션이 있다면 (value → label 매핑): 옵션 값 → 한글 라벨. 동적 옵션 (state-derived) 은 코드 잔류 — JSON 에 안 들어감.
+
+### Step 2: JSON 스키마 + 파일 작성
+
+`prompts/wizard/prompts.ko.json` 생성. 구조:
+
+```json
+{
+  "schema_version": 1,
+  "locale": "ko",
+  "steps": {
+    "task_pick": {
+      "label": "어느 task?",
+      "echo_template": "task: {value}",
+      "options": {
+        "_NEW_": "Start a brand-new task"
+      }
+    },
+    "task_group": {
+      "label": "Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)",
+      "echo_template": "task-group: {value}"
+    },
+    "task_group_with_suggestion": {
+      "label": "Task group? (brief 추천: {suggestion})",
+      "echo_template": "task-group: {value}"
+    },
+    "task_group_text": {
+      "label": "Task group 을 입력해주세요 (예: backend-api, INV-1234, refactor)",
+      "echo_template": "task-group: {value}"
+    },
+    "brief_keep": {
+      "label": "기존 brief 경로 [{existing_brief_path}] 를 유지할까요?",
+      "echo_template": "brief: {value}",
+      "options": {
+        "yes": "유지",
+        "no":  "변경"
+      }
+    }
+  }
+}
+```
+
+**규칙:**
+- 최상위 `schema_version` (정수, 현재 `1`), `locale` (`"ko"`), `steps` (dict)
+- `steps` 의 키 = wizard.py 의 `S_*` 상수의 값 (예: `S_TASK_PICK = "task_pick"` → 키 `"task_pick"`)
+- 각 step entry 는 반드시 `label`, `echo_template` 보유. `options` 는 정적 옵션이 있을 때만.
+- `label` 안의 placeholder 는 `{name}` (Python str.format 문법). `{value}` 는 echo_template 전용 placeholder (user answer).
+- 같은 step id 가 2개 형태 (예: suggestion 있는 pick + 없는 text) 면 별도 키로 (`task_group` + `task_group_with_suggestion`). 키 명명: 변형 형태에는 `_with_suggestion` / `_text` 같은 suffix.
+
+**Inventory 가이드** (wizard.py 의 _build_* 함수당 entry 작성):
+
+| `_build_*` 함수 (대략 위치) | step_id (JSON 키) | 비고 |
+|---|---|---|
+| `_build_task_pick` (~466) | `task_pick` | + 정적 option `_NEW_` |
+| `_build_task_group` (~521) | `task_group` + `task_group_with_suggestion` | sugg 분기 |
+| `_build_task_group_text` (~558) | `task_group_text` | |
+| `_build_task_id` (~570) | `task_id` + `task_id_with_suggestion` | |
+| `_build_task_id_text` (~605) | `task_id_text` | |
+| `_build_task_type` (~617) | `task_type` | |
+| `_build_brief_keep` (~650) | `brief_keep` | state interpolation `{existing_brief_path}` + 정적 options |
+| `_build_brief_path` (~669) | `brief_path` | |
+| `_build_base_ref_pick` (~691) | `base_ref_pick` | |
+| `_build_base_ref_text` (~714) | `base_ref_text` | |
+| `_build_approved_plan_pick` (~770) | `approved_plan_pick` | state interpolation `{default}` |
+| `_build_approved_plan` (~804) | `approved_plan` | |
+| `_build_directive_pick` (~819) | `directive_pick` | |
+| `_build_related_tasks_pick` (~842) | `related_tasks_pick` | |
+| `_build_clarification_pick` (~865) | `clarification_pick` | |
+| `_build_pr_template_pick` (~888) | `pr_template_pick` | |
+| `_build_executor` (~912) | `executor` | |
+| `_build_defaults_or_custom` (~930) | `defaults_or_custom` | |
+| `_build_workers_override` (~947) | `workers_override` | 동적 옵션 (worker 명) 은 코드 잔류 — label 만 JSON |
+| `_build_lead_model` (~995) | `lead_model` | |
+| `_build_executor_model` (~1005) | `executor_model` | |
+| `_build_claude_model` (~1020) | `claude_model` | |
+| `_build_codex_model` (~1030) | `codex_model` | |
+| `_build_gemini_model` (~1040) | `gemini_model` | |
+| `_build_report_writer_model` (~1050) | `report_writer_model` | |
+| `_build_directive` (~1062) | `directive` | |
+| `_build_related_tasks` (~1076) | `related_tasks` | |
+| `_build_clarification` (~1092) | `clarification` | |
+| `_build_pr_template` (~1111) | `pr_template` | |
+| `_build_pr_template_scope` (~1138) | `pr_template_scope` | + 옵션 |
+| `_build_confirm` (~1160) | `confirm` | + 옵션 (Proceed/Edit) |
+| `_build_edit_target` (~1182) | `edit_target` | |
+
+(목록은 시작점 — 실제 파일 grep 결과를 권위로 사용. 발견된 모든 `_build_*` 함수는 JSON 에 1 entry 가 있어야 한다.)
+
+**Note** — `_build_workers_override` 의 label 은 다음 같이 다중 줄 + 큰따옴표 escape 가 필요할 수 있음:
+```python
+label=("참여시킬 분석 워커를 선택해주세요 (최소 1개). "
+       "기본 셋은 task-type 별 ...")
+```
+이는 JSON 에서 하나의 string 으로 합쳐서 표현 (`" "` 로 줄바꿈 자리). 줄바꿈 `\n` 이 필요하면 명시.
+
+### Step 3: JSON 유효성 확인
+
+```bash
+python3 -c "import json; json.load(open('prompts/wizard/prompts.ko.json'))"
+```
+Expected: 에러 없이 종료.
+
+step id 카운트 확인 (대략 28-32):
+```bash
+python3 -c "import json; d=json.load(open('prompts/wizard/prompts.ko.json')); print(len(d['steps']), 'steps:', sorted(d['steps'].keys()))"
+```
+Expected: 28+ step (정확한 수는 wizard.py inventory 에 의존). 각 키가 wizard.py 의 `S_*` 상수 값에 1:1 대응.
+
+### Step 4: pytest 회귀 (변동 없음 보증)
+
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 595 passed, 1 skipped (Phase B1 baseline 그대로 — 이 task 는 JSON 파일만 추가, 어떤 코드도 안 손댐).
+
+### Step 5: Commit
+
+```bash
+git add prompts/wizard/prompts.ko.json
+git commit -m "feat(prompts): add prompts/wizard/prompts.ko.json (wizard prompt SOT)"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Task 2: wizard.py loader + `_p()` 헬퍼 + 기초 unit tests
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py` — `_load_wizard_prompts(workspace_root)` + `_p(workspace_root, step_id, **vars)` 추가. 아직 `_build_*` 안에서 호출 안 함.
+- Create: `tests/test_wizard_prompts.py` — SOT-sync + `_p()` 단위 테스트.
+
+이 task commit 후에도 외부 동작은 동일. 새 헬퍼는 정의됐을 뿐 caller 없음.
+
+### Step 1: Failing test 작성
+
+`tests/test_wizard_prompts.py` 생성:
+
+```python
+"""wizard.py prompt JSON SOT — loader + _p() 헬퍼 + step id 동기화."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+LIB_DIR = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl import wizard  # noqa: E402
+from okstra_ctl.wizard import WizardError, _p  # noqa: E402
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_prompts_json_loadable():
+    """JSON 파일이 schema_version=1, locale='ko', steps dict 보유."""
+    raw = wizard._load_wizard_prompts(str(REPO_ROOT))
+    assert isinstance(raw, dict)
+    assert raw  # not empty
+
+
+def test_p_returns_label_and_echo():
+    """_p() 가 step id 로 label + echo_template 을 반환."""
+    t = _p(str(REPO_ROOT), "task_pick")
+    assert "label" in t
+    assert "echo_template" in t
+    assert t["echo_template"] == "task: {value}"
+
+
+def test_p_applies_placeholder():
+    """_p() 가 placeholder 를 vars 로 치환."""
+    t = _p(str(REPO_ROOT), "brief_keep", existing_brief_path="/foo/bar.md")
+    assert "/foo/bar.md" in t["label"]
+
+
+def test_p_missing_step_raises():
+    """미정의 step id → WizardError."""
+    with pytest.raises(WizardError) as exc:
+        _p(str(REPO_ROOT), "nonexistent_step_xyz")
+    assert "nonexistent_step_xyz" in str(exc.value)
+
+
+def test_p_missing_placeholder_raises():
+    """label 에 placeholder 가 있는데 vars 안 주면 WizardError."""
+    with pytest.raises(WizardError) as exc:
+        _p(str(REPO_ROOT), "brief_keep")   # 'existing_brief_path' 미제공
+    assert "existing_brief_path" in str(exc.value) or "missing" in str(exc.value).lower()
+
+
+def test_step_id_sync_wizard_to_json():
+    """wizard.py 의 모든 S_* 상수값이 JSON 의 step id 로 존재해야 한다."""
+    import inspect
+    raw = wizard._load_wizard_prompts(str(REPO_ROOT))
+    json_keys = set(raw.keys())
+    wizard_step_ids = {
+        v for k, v in inspect.getmembers(wizard)
+        if k.startswith("S_") and isinstance(v, str)
+    }
+    # 일부 S_* 는 terminal/non-prompt (S_DONE 등) — JSON 에 없어도 OK.
+    # 단, JSON 에 있는 모든 키는 wizard 의 어딘가 (S_* 또는 _with_suggestion 변형)에서 사용돼야.
+    # 이 테스트는 JSON 잉여 키 (orphan) 검사를 강화:
+    SUFFIXES_ALLOWED = ("", "_with_suggestion", "_text")
+    orphans = []
+    for json_key in json_keys:
+        matched = False
+        for suffix in SUFFIXES_ALLOWED:
+            if json_key.endswith(suffix):
+                base = json_key[: -len(suffix)] if suffix else json_key
+                if base in wizard_step_ids or json_key in wizard_step_ids:
+                    matched = True
+                    break
+        if not matched:
+            orphans.append(json_key)
+    assert not orphans, f"JSON has step ids not referenced in wizard.py: {orphans}"
+```
+
+### Step 2: 테스트 실패 확인
+
+```bash
+python3 -m pytest tests/test_wizard_prompts.py -v
+```
+Expected: 모든 테스트 ImportError (`cannot import name '_p'` 또는 `_load_wizard_prompts`) 또는 AttributeError.
+
+### Step 3: wizard.py 에 loader + `_p()` 구현
+
+`scripts/okstra_ctl/wizard.py` 의 적절한 위치 (다른 모듈-레벨 helper 함수 근처, 예: `_profile_path` 정의 직후 ~ line 410) 에 다음 추가:
+
+```python
+# --------------------------------------------------------------------------- #
+# Wizard prompt JSON SOT (Phase A1)
+# --------------------------------------------------------------------------- #
+
+_WIZARD_PROMPTS_CACHE: dict[str, dict] = {}
+
+
+def _load_wizard_prompts(workspace_root: str) -> dict:
+    """Load and cache wizard prompts JSON for the given workspace root.
+
+    The JSON file lives at `<workspace_root>/prompts/wizard/prompts.ko.json`
+    in the okstra runtime tree. The SOT contract:
+    - Top-level fields: `schema_version` (1), `locale` ("ko"), `steps` (dict).
+    - Each entry in `steps[<step_id>]` has `label`, `echo_template`, and
+      optional `options` (dict[value → label] for static option pickers).
+
+    Loaded once per workspace_root path (cached) — re-imports are cheap.
+    """
+    if workspace_root in _WIZARD_PROMPTS_CACHE:
+        return _WIZARD_PROMPTS_CACHE[workspace_root]
+    path = Path(workspace_root) / "prompts" / "wizard" / "prompts.ko.json"
+    if not path.is_file():
+        raise WizardError(
+            f"wizard prompt SOT not found: {path}. "
+            "Re-run `okstra install` or check the workspace_root."
+        )
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise WizardError(f"wizard prompt JSON malformed: {path}: {exc}") from exc
+    if raw.get("schema_version") != 1:
+        raise WizardError(
+            f"wizard prompt schema_version mismatch (expected 1): {path}"
+        )
+    steps = raw.get("steps")
+    if not isinstance(steps, dict):
+        raise WizardError(f"wizard prompt 'steps' missing or not a dict: {path}")
+    _WIZARD_PROMPTS_CACHE[workspace_root] = steps
+    return steps
+
+
+def _p(workspace_root: str, step_id: str, **vars: str) -> dict:
+    """Look up a wizard prompt entry by step_id and interpolate placeholders.
+
+    Returns a dict with keys: 'label' (str, possibly interpolated),
+    'echo_template' (str, raw — contains `{value}` for the user's answer),
+    'options' (dict[value → label], may be empty).
+
+    Raises WizardError if the step_id is unknown or a required placeholder
+    is missing from the provided vars.
+    """
+    steps = _load_wizard_prompts(workspace_root)
+    raw = steps.get(step_id)
+    if raw is None:
+        raise WizardError(f"unknown wizard step_id: {step_id!r}")
+    label_template = raw.get("label", "")
+    try:
+        label = label_template.format(**vars) if vars else label_template
+    except KeyError as exc:
+        missing = exc.args[0] if exc.args else "<unknown>"
+        raise WizardError(
+            f"missing placeholder {missing!r} for wizard step {step_id!r}"
+        ) from exc
+    return {
+        "label": label,
+        "echo_template": raw.get("echo_template", ""),
+        "options": raw.get("options", {}),
+    }
+```
+
+상단 import 에 `import json` 이 없으면 추가. `Path` 는 이미 사용 중.
+
+### Step 4: 단위 테스트 통과 확인
+
+```bash
+python3 -m pytest tests/test_wizard_prompts.py -v
+```
+Expected: 6 tests PASS.
+
+전체 회귀:
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 601 passed, 1 skipped (595 + 6 new).
+
+### Step 5: Commit
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_prompts.py
+git commit -m "feat(wizard): add prompt JSON loader + _p() helper"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Task 3: `_build_*` 함수 migrate (atomic)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py` — 모든 `_build_*` 함수의 `Prompt(label=..., echo_template=..., options=[...])` 호출을 `_p()` lookup 기반으로 교체.
+
+이 task 가 핵심. 부분 마이그레이션 시 SOT 가 깨지므로 한 commit 에 묶음. 동작 변화 없음 — 회귀 테스트가 검증.
+
+### Step 1: 마이그레이션 패턴
+
+**Before (hard-coded Korean):**
+```python
+def _build_brief_keep(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_BRIEF_KEEP, kind="pick",
+        label=f"기존 brief 경로 [{state.existing_brief_path}] 를 유지할까요?",
+        options=[_opt("yes", "유지"), _opt("no", "변경")],
+        echo_template="brief: {value}",
+    )
+```
+
+**After (JSON lookup):**
+```python
+def _build_brief_keep(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "brief_keep",
+           existing_brief_path=state.existing_brief_path)
+    return Prompt(
+        step=S_BRIEF_KEEP, kind="pick",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
+    )
+```
+
+**규칙:**
+- `_p()` 의 첫 인자는 항상 `state.workspace_root`.
+- 두 번째 인자 (step_id) 는 `S_*` 상수의 값 (예: `S_BRIEF_KEEP` → `"brief_keep"`). 명시적 문자열로 — `S_BRIEF_KEEP` 값과 동일하게.
+- placeholder 가 있는 label 은 `**vars` 로 전달.
+- 정적 options 가 있으면 `t["options"]` 의 dict items 를 `_opt(value, label)` 로 변환.
+- 동적 options (예: `_build_workers_override` 의 worker 목록, `_build_task_pick` 의 task catalog) 는 **state 에서 계산해 직접 `options` 리스트에 추가** — JSON 에서 안 옴.
+- 동적 + 정적 hybrid (예: `_build_task_pick` 의 catalog tasks + 정적 `_NEW_` 옵션) 는: 동적 옵션을 코드에서 만들고, 마지막에 JSON 의 정적 옵션 (`t["options"]`) 도 추가:
+  ```python
+  options = [...]  # 동적 옵션
+  for value, label in t["options"].items():
+      options.append(_opt(value, label))
+  ```
+
+### Step 2: 모든 `_build_*` 함수 migrate
+
+`scripts/okstra_ctl/wizard.py` 의 28개 (대략) `_build_*` 함수를 위 패턴으로 변환:
+
+```bash
+grep -nE 'def _build_' scripts/okstra_ctl/wizard.py
+```
+
+각 함수마다:
+1. 첫 줄에 `t = _p(state.workspace_root, "<step_id>", **interpolation_vars)` 추가.
+2. `Prompt(...)` 호출에서:
+   - `label="..."` → `label=t["label"]`
+   - `echo_template="..."` → `echo_template=t["echo_template"]`
+   - 정적 `_opt(value, label)` 호출 → `_opt(value, t["options"][value])` 또는 위 hybrid 패턴.
+3. 함수 안에 한글 string literal 0개 — 확인 grep:
+   ```bash
+   grep -nP '[가-힣]' scripts/okstra_ctl/wizard.py
+   ```
+   Expected: 0 hits 또는 주석 (코멘트 안의 한글은 정책상 허용 — JSON SOT 의 대상은 user-facing UI 문자열뿐).
+
+**특수 케이스 — `_build_workers_override`** (line ~947):
+- label 이 multi-line — JSON 에서 단일 문자열로 합침.
+- 옵션은 동적 (worker 명 + "(옵션)" suffix 포함 가능). 동적 옵션의 한글 (`(옵션)` 등) 이 코드에 남아도 되는가? 정책: **이런 contextual suffix 는 JSON 안의 별도 항목으로** — 예: `t["options"]["_OPTIONAL_SUFFIX_"] = "(옵션)"` 또는 별도 step 의 `options` 안에. 가장 단순한 방법은 `_p()` 의 추가 placeholder 로 처리:
+  ```json
+  "workers_override": {
+    "label": "참여시킬 분석 워커를 선택해주세요 (최소 1개). ...",
+    "echo_template": "workers: {value}",
+    "options": { "_OPTIONAL_SUFFIX": " (옵션)" }
+  }
+  ```
+  코드 (`_build_workers_override`) 에서:
+  ```python
+  t = _p(state.workspace_root, "workers_override")
+  suffix = t["options"].get("_OPTIONAL_SUFFIX", "")
+  for w in candidates:
+      label = f"{w}{suffix}" if w in optional_set else w
+      options.append(_opt(value=w, label=label))
+  ```
+- 또는 더 깔끔하게: optional suffix 를 JSON 의 `metadata` 같은 별도 키에. step entry 스키마를 확장하면 됨. 본 plan 에서는 `_OPTIONAL_SUFFIX` 키를 옵션 dict 안에 두는 방식 채택 (스키마 변경 최소).
+
+**특수 케이스 — `_build_*_model`** (lead/executor/claude/codex/gemini/report_writer):
+- 6 함수가 공통 헬퍼 `_build_model_pick(state, step, label, echo, ...)` 같은 형태일 가능성 (확인 필요 — wizard.py:990-1050 부근).
+- 헬퍼가 step/label/echo 를 받는다면, 각 caller 가 `_p(...)` 로 미리 dict 받아서 헬퍼에 전달:
+  ```python
+  def _build_lead_model(state):
+      t = _p(state.workspace_root, "lead_model")
+      return _build_model_pick(state, S_LEAD_MODEL, t["label"], t["echo_template"])
+  ```
+- 6 함수 모두 같은 패턴.
+
+### Step 3: 회귀 통과 확인
+
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 601 passed, 1 skipped — wizard 기존 회귀 (test_okstra_ctl_wizard.py 등) 가 동작 보존을 검증.
+
+E2E (wizard 가 실행되는 시나리오 — 있다면):
+```bash
+ls tests-e2e/
+# scenario-* 안에서 wizard 가 실행되는 게 있는지 확인.
+```
+없을 경우 unit 회귀로 충분.
+
+### Step 4: 한글 grep 점검 (informational — 정식 게이트는 Task 4)
+
+```bash
+grep -nP '[가-힣]' scripts/okstra_ctl/wizard.py | grep -vE '^[0-9]+:[ ]*#'
+```
+Expected: 0 hits (주석 외).
+
+만약 주석 안 한글이 있고 의도된 한국어 설명이면 OK — 본 task 는 **user-facing UI 문자열** 만 외부화 대상.
+
+### Step 5: Commit
+
+```bash
+git add scripts/okstra_ctl/wizard.py
+git commit -m "refactor(wizard): externalize Korean prompts to prompts.ko.json"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Task 4: Korean-char grep gate test
+
+**Files:**
+- Modify: `tests/test_wizard_prompts.py` — wizard.py 안에 user-facing 한글 문자열이 다시 추가되지 않도록 정적 검사 추가.
+
+### Step 1: 추가할 테스트 함수
+
+`tests/test_wizard_prompts.py` 끝에 다음 추가:
+
+```python
+WIZARD_PY = Path(__file__).resolve().parents[1] / "scripts" / "okstra_ctl" / "wizard.py"
+
+
+def test_no_korean_in_wizard_py_code():
+    """wizard.py 의 비-주석 코드 라인에 한글 문자가 0개 — JSON SOT 회귀 방지.
+
+    주석 (`#` 시작) 안의 한글은 한국어 docstring/설명용으로 허용.
+    내용:
+    - user-facing UI 문자열 (label, echo, option label) 은 모두 prompts/wizard/prompts.ko.json 에 있어야 함.
+    """
+    import re
+
+    KOREAN = re.compile(r"[가-힣]")
+    offenders: list[str] = []
+    for lineno, raw in enumerate(WIZARD_PY.read_text(encoding="utf-8").splitlines(), 1):
+        # 빈 줄 / 주석만 있는 줄 skip
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        # 줄 안에 `#` 가 있으면 그 앞 부분만 검사 (inline comment 제외).
+        code_part = raw.split("#", 1)[0]
+        # 문자열 안의 한글도 violation — JSON 으로 옮겨야 함.
+        # docstring (3중 따옴표 영역) 안의 한글은? — 정책상 docstring 한글도 외부화 대상 아님 (코드 설명).
+        # 본 테스트는 단순 라인 기반 — docstring 안의 한글은 통과 (false negative). 정밀 검사가 필요하면 ast 사용.
+        # 일단 single/triple quoted string content 내 한글이 있어도 보수적으로 detection.
+        if KOREAN.search(code_part):
+            offenders.append(f"  {WIZARD_PY.name}:{lineno}: {raw.rstrip()[:120]}")
+    assert not offenders, (
+        "wizard.py 에 user-facing 한글 문자열이 남아 있음 — "
+        "prompts/wizard/prompts.ko.json 으로 이동 필요:\n" + "\n".join(offenders)
+    )
+```
+
+### Step 2: 테스트 실행
+
+```bash
+python3 -m pytest tests/test_wizard_prompts.py::test_no_korean_in_wizard_py_code -v
+```
+
+Expected:
+- Task 3 가 깨끗이 됐다면 PASS.
+- FAIL 이면 메시지가 짚는 라인의 한글을 JSON 으로 이동 + wizard.py 코드를 `_p()` lookup 으로 교체.
+
+전체 회귀:
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 602 passed, 1 skipped (601 + 1 new).
+
+### Step 3: 만약 docstring 안 한글이 false positive 로 잡히면
+
+본 테스트는 라인 기반 — docstring 안의 한국어 설명도 잡힐 수 있음. 옵션:
+- (a) docstring 한글도 영어로 (또는 별도 docs/ 파일로) 외부화 — 정책 강화.
+- (b) 테스트 strictness 완화 — docstring 라인을 skip 하도록 ast 사용으로 변경.
+
+본 plan 의 기본은 (a) — wizard.py 의 한글 자체를 0개로. docstring 도 영어 또는 외부 docs 로. 만약 한국어 docstring 보존이 우선이면 (b) 로 테스트 완화 후 별도 task.
+
+### Step 4: Commit
+
+```bash
+git add tests/test_wizard_prompts.py
+git commit -m "test(wizard): assert no Korean characters remain in wizard.py code"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Task 5: CHANGES.md + 최종 검증
+
+**Files:**
+- Modify: `CHANGES.md`
+
+### Step 1: CHANGES.md 항목 추가
+
+`CHANGES.md` 의 최상단 (오늘 date 섹션) 에:
+
+```markdown
+### refactor(wizard): wizard prompt 한글 문자열 JSON SOT 단일화 (2026-05-20)
+
+- `scripts/okstra_ctl/wizard.py` 의 한글 UI 문자열 (label, echo_template, 정적 option label) 을 `prompts/wizard/prompts.ko.json` 단독 권위로 이전.
+- 신규 `_p(workspace_root, step_id, **vars)` 헬퍼 — placeholder 보간 + step id lookup.
+- 한글 grep gate test 추가 — wizard.py 안에 user-facing 한글이 다시 들어오는 회귀 차단.
+- 사용자 영향: 없음 (UI 동일). 컨트리뷰터 영향: prompt 문구 수정 시 Python 코드 안 건드리고 JSON 만 편집.
+- i18n 준비: 향후 `prompts.en.yaml` / `prompts.<locale>.json` 추가 시 locale 선택 메커니즘만 추가하면 됨 (본 PR 범위 외).
+```
+
+기존 CHANGES.md 의 entry pattern (`### type(scope): summary` + 배경/변경/사용자 영향 구조) 을 따를 것 — `head -20 CHANGES.md` 로 먼저 확인.
+
+### Step 2: npm build smoke
+
+```bash
+npm run build
+```
+Expected: 에러 없음, `runtime/prompts/wizard/prompts.ko.json` 이 생성됨.
+
+검증:
+```bash
+test -f runtime/prompts/wizard/prompts.ko.json && echo OK
+```
+Expected: `OK`.
+
+### Step 3: 최종 회귀 3종
+
+```bash
+python3 -m pytest tests/ -v 2>&1 | tail -10
+```
+Expected: 602 passed, 1 skipped.
+
+```bash
+bash validators/validate-workflow.sh 2>&1 | tail -10
+```
+Expected: 기존 pre-existing failure 그대로 (Phase B1 후속과 무관).
+
+E2E (wizard 흐름이 들어간 시나리오 — 있다면 실행, 없으면 skip):
+```bash
+ls tests-e2e/scenario-*.sh | head -5
+```
+의도된 wizard 시나리오가 있으면 실행. 없으면 OK — wizard 의 회귀는 unit 으로 충분 (`tests/test_okstra_ctl_wizard.py`).
+
+### Step 4: Commit
+
+```bash
+git add CHANGES.md
+git commit -m "docs(changes): note wizard prompt JSON SOT unification"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Self-Review 체크리스트
+
+- [x] **Spec coverage**: design 문서 §3 (Phase A1) 의 모든 항목이 task 로 포함 — 3.1 외부화 대상 (Task 1: label/echo/정적 옵션, Task 3 의 동적 옵션 코드 잔류), 3.2 JSON 스키마 (Task 1 step 2), 3.3 loader/`_p()` (Task 2), 3.4 검증 (Task 2 의 SOT-sync test + Task 4 의 한글 grep gate), 3.5 마이그레이션 (Task 3 atomic), 3.6 의도적 안 하는 것 (i18n 활성화는 Task 5 CHANGES.md 에 언급), 3.7 실패모드 (`_p()` 의 WizardError).
+- [x] **Placeholder scan**: TBD/TODO 없음. 모든 step 에 실제 명령·코드·grep 패턴 명시. JSON 의 28+ entries 는 Task 1 의 inventory 절차로 명확히 — exact entries 는 wizard.py grep 결과를 권위로 사용.
+- [x] **Type consistency**: `_p(workspace_root: str, step_id: str, **vars: str) -> dict` / `_load_wizard_prompts(workspace_root: str) -> dict` / `WizardError(Exception)` (기존 — 본 plan 에서 새로 정의 안 함) — 모든 task 에서 동일.
+- [x] **Atomic migration**: Task 3 한 commit. 부분 마이그레이션 위험 없음.
+- [x] **Format 변경 (YAML → JSON)**: spec 의 의도를 보존하면서 zero-dep 구현 — design 문서와의 차이를 본 plan 의 "왜 JSON 인가" 섹션에 명시.
+
+---
+
+## 실행 옵션
+
+Plan complete and saved to [docs/superpowers/plans/2026-05-20-wizard-prompt-json-sot-a1.md](docs/superpowers/plans/2026-05-20-wizard-prompt-json-sot-a1.md). 두 가지 실행 방식:
+
+1. **Subagent-Driven (recommended)** — task 마다 새로운 subagent 가 들어가 작업, task 사이에서 review, 빠른 iteration
+2. **Inline Execution** — 본 세션 안에서 executing-plans 로 batch 실행, checkpoint 마다 review
+
+어떤 방식으로 진행할까요?