okstra 0.34.1 → 0.36.0

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

@@ -0,0 +1,720 @@
+# Wizard Messages JSON SOT (A1 Follow-up) 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:** Phase A1 의 JSON SOT 를 wizard.py 의 모든 user-facing 한글 문자열 (`_submit_*` echo variants, `WizardError` 메시지, `confirmation_block` 출력) 까지 확장한다. wizard.py 의 한글 0 (docstring 제외) 달성.
+
+**Architecture:**
+1. JSON SOT (`prompts/wizard/prompts.ko.json`) 스키마 확장 — step entry 안에 `echo_variants` / `errors` 서브필드 추가, top-level `confirmation` 섹션 추가.
+2. wizard.py 에 `_load_wizard_root(workspace_root)` 헬퍼 (전체 root 캐시) + `_msg(workspace_root, section, key, **vars)` 헬퍼 (top-level 섹션 lookup) 추가. 기존 `_p()` 의 반환 dict 에 `echo_variants`/`errors` 패스스루.
+3. 7 한글 사이트 (3 `_submit_*` echo + 2 `WizardError` + 2 `confirmation_block` 라인) atomic migrate.
+4. Korean grep gate scope 를 `_submit_*` + `confirmation_block` 까지 확장 — wizard.py 코드 라인 한글 0 (docstring 제외) 정적 보장.
+
+**Tech Stack:** Python 3 stdlib (`json`, `pathlib`), pytest.
+
+**Reference:** [docs/superpowers/specs/2026-05-20-okstra-run-prompt-sot-design.md](../specs/2026-05-20-okstra-run-prompt-sot-design.md) §3. 본 plan 은 Phase A1 의 plan scope 외였던 follow-up 작업.
+
+---
+
+## File Structure
+
+**수정 only**
+- `prompts/wizard/prompts.ko.json` — Task 1
+- `scripts/okstra_ctl/wizard.py` — Task 2 (loader/`_msg`) + Task 3 (사이트 migration)
+- `tests/test_wizard_prompts.py` — Task 2 (헬퍼 테스트) + Task 4 (grep gate scope 확장)
+- `CHANGES.md` — Task 4
+
+손대지 않음: `runtime/` (build output), 다른 모듈.
+
+---
+
+## Migration target inventory (구체적)
+
+| # | wizard.py 위치 | 현재 한글 | JSON 신규 키 |
+|---|---|---|---|
+| 1 | `_submit_task_group:643` | `"task-group: (직접 입력)"` | `steps.task_group.echo_variants.free_input` |
+| 2 | `_submit_task_id:694` | `"task-id: (직접 입력)"` | `steps.task_id.echo_variants.free_input` |
+| 3 | `_submit_brief_keep:769` | `f"brief: {state.brief_path} (유지)"` | `steps.brief_keep.echo_variants.kept` (with `{brief_path}` placeholder) |
+| 4 | `_submit_approved_plan_pick:900` | `"기본 approved-plan 경로를 찾을 수 없습니다. '다른 경로 입력'을 선택하세요."` | `steps.approved_plan_pick.errors.default_not_found` |
+| 5 | `_submit_workers_override:1080` | `"워커를 최소 1개 선택해주세요"` | `steps.workers_override.errors.min_one_required` |
+| 6 | `confirmation_block:1717` | `"선택 확인:"` | `confirmation.header` |
+| 7 | `confirmation_block:1727` | `"  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"` | `confirmation.workers_implementation_default` |
+
+---
+
+## Task 1: JSON SOT 스키마 확장
+
+**Files:**
+- Modify: `prompts/wizard/prompts.ko.json`
+
+이 task 의 commit 후에도 동작 동일 — JSON 신규 필드는 caller 없음 (Task 3 에서 사용).
+
+- [ ] **Step 1: 신규 필드 추가**
+
+`prompts/wizard/prompts.ko.json` 의 5개 step entry 에 `echo_variants` / `errors` 서브필드 추가 + 최상위 `confirmation` 섹션 추가:
+
+`steps.task_group` 에 다음 키 추가:
+```json
+"echo_variants": {
+  "free_input": "task-group: (직접 입력)"
+}
+```
+
+`steps.task_id` 에:
+```json
+"echo_variants": {
+  "free_input": "task-id: (직접 입력)"
+}
+```
+
+`steps.brief_keep` 에:
+```json
+"echo_variants": {
+  "kept": "brief: {brief_path} (유지)"
+}
+```
+
+`steps.approved_plan_pick` 에:
+```json
+"errors": {
+  "default_not_found": "기본 approved-plan 경로를 찾을 수 없습니다. '다른 경로 입력'을 선택하세요."
+}
+```
+
+`steps.workers_override` 에:
+```json
+"errors": {
+  "min_one_required": "워커를 최소 1개 선택해주세요"
+}
+```
+
+최상위 (top-level, `steps` 와 형제) 에 신규 섹션:
+```json
+"confirmation": {
+  "header": "선택 확인:",
+  "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"
+}
+```
+
+JSON 인덴트는 기존 파일 패턴 따름 (2-space).
+
+- [ ] **Step 2: 유효성 확인**
+
+```bash
+python3 -m json.tool prompts/wizard/prompts.ko.json > /dev/null && echo "JSON valid"
+```
+
+```bash
+python3 << 'PY'
+import json
+d = json.load(open('prompts/wizard/prompts.ko.json'))
+assert d['steps']['task_group']['echo_variants']['free_input'] == "task-group: (직접 입력)"
+assert d['steps']['task_id']['echo_variants']['free_input'] == "task-id: (직접 입력)"
+assert "{brief_path}" in d['steps']['brief_keep']['echo_variants']['kept']
+assert "approved-plan" in d['steps']['approved_plan_pick']['errors']['default_not_found']
+assert d['steps']['workers_override']['errors']['min_one_required'] == "워커를 최소 1개 선택해주세요"
+assert d['confirmation']['header'] == "선택 확인:"
+assert "report-writer" in d['confirmation']['workers_implementation_default']
+print("OK: all 7 new entries present")
+PY
+```
+
+- [ ] **Step 3: 회귀 통과 (변동 없음)**
+
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 604 passed, 1 skipped (baseline 유지 — 새 JSON 키는 caller 없어서 영향 없음).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add prompts/wizard/prompts.ko.json
+git commit -m "feat(prompts): add echo_variants/errors/confirmation sections to wizard SOT"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Task 2: `_load_wizard_root` + `_msg` 헬퍼 추가 + `_p()` 확장 (TDD)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py`
+- Modify: `tests/test_wizard_prompts.py`
+
+이 task 의 commit 후에도 동작 동일 — 새 헬퍼는 정의됐을 뿐 caller 없음 (Task 3).
+
+- [ ] **Step 1: Failing tests 추가**
+
+`tests/test_wizard_prompts.py` 끝에 추가:
+
+```python
+def test_p_includes_echo_variants():
+    """_p() 반환 dict 가 echo_variants 도 포함해야 한다."""
+    t = _p(str(REPO_ROOT), "task_group")
+    assert "echo_variants" in t
+    assert t["echo_variants"]["free_input"] == "task-group: (직접 입력)"
+
+
+def test_p_includes_errors():
+    """_p() 반환 dict 가 errors 도 포함해야 한다."""
+    t = _p(str(REPO_ROOT), "approved_plan_pick")
+    assert "errors" in t
+    assert "approved-plan" in t["errors"]["default_not_found"]
+
+
+def test_p_echo_variants_default_empty():
+    """echo_variants 가 없는 step 도 빈 dict 로 안전하게 반환."""
+    t = _p(str(REPO_ROOT), "task_pick")
+    assert t.get("echo_variants", {}) == {} or "echo_variants" not in t or t["echo_variants"] == {}
+
+
+def test_msg_returns_confirmation_header():
+    """_msg() 가 top-level confirmation 섹션의 값을 반환."""
+    from okstra_ctl.wizard import _msg
+    result = _msg(str(REPO_ROOT), "confirmation", "header")
+    assert result == "선택 확인:"
+
+
+def test_msg_unknown_section_raises():
+    """미정의 섹션 → WizardError."""
+    from okstra_ctl.wizard import _msg
+    with pytest.raises(WizardError) as exc:
+        _msg(str(REPO_ROOT), "nonexistent_section", "any_key")
+    assert "nonexistent_section" in str(exc.value)
+
+
+def test_msg_unknown_key_raises():
+    """섹션 안에 키 없으면 WizardError."""
+    from okstra_ctl.wizard import _msg
+    with pytest.raises(WizardError) as exc:
+        _msg(str(REPO_ROOT), "confirmation", "nonexistent_key_xyz")
+    assert "nonexistent_key_xyz" in str(exc.value)
+
+
+def test_msg_applies_placeholder():
+    """_msg() 가 placeholder 를 vars 로 치환 (workers_implementation_default 같은 정적 케이스는 placeholder 없음 — 함수 동작 확인용)."""
+    from okstra_ctl.wizard import _msg
+    # Use brief_keep echo_variants which has {brief_path} placeholder via _p, but also test _msg behavior with a synthetic case.
+    # The real placeholder test: workers_implementation_default has no placeholder, but _msg should still handle empty vars.
+    result = _msg(str(REPO_ROOT), "confirmation", "workers_implementation_default")
+    assert "프로필 기본" in result
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+```bash
+python3 -m pytest tests/test_wizard_prompts.py -v 2>&1 | tail -15
+```
+Expected: 신규 7 tests 모두 FAIL (import error: `_msg` 없음, 또는 `echo_variants`/`errors` 키 없음).
+
+- [ ] **Step 3: wizard.py 에 `_load_wizard_root` + `_msg` 구현 + `_p()` 확장**
+
+`scripts/okstra_ctl/wizard.py` 의 기존 `_load_wizard_prompts` 정의 직전에 새 함수 추가:
+
+```python
+_WIZARD_ROOT_CACHE: dict[str, dict] = {}
+
+
+def _load_wizard_root(workspace_root: str) -> dict:
+    """Load and cache the full wizard prompts JSON root for the given workspace_root.
+
+    Returns the entire parsed JSON object (with `schema_version`, `locale`, `steps`,
+    optional `confirmation` etc. at top level). Used internally by
+    `_load_wizard_prompts` (which returns `steps`) and `_msg` (which reads
+    top-level sections like `confirmation`).
+    """
+    if workspace_root in _WIZARD_ROOT_CACHE:
+        return _WIZARD_ROOT_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 not isinstance(raw, dict):
+        raise WizardError(f"wizard prompt JSON root must be an object: {path}")
+    if raw.get("schema_version") != 1:
+        raise WizardError(
+            f"wizard prompt schema_version mismatch (expected 1): {path}"
+        )
+    if raw.get("locale") != "ko":
+        raise WizardError(
+            f"wizard prompt locale unsupported (expected 'ko'): {path}"
+        )
+    steps = raw.get("steps")
+    if not isinstance(steps, dict):
+        raise WizardError(f"wizard prompt 'steps' missing or not a dict: {path}")
+    _WIZARD_ROOT_CACHE[workspace_root] = raw
+    return raw
+```
+
+기존 `_load_wizard_prompts` 함수를 `_load_wizard_root` 의 thin wrapper 로 교체:
+
+```python
+def _load_wizard_prompts(workspace_root: str) -> dict:
+    """Backwards-compatible accessor returning the `steps` dict."""
+    return _load_wizard_root(workspace_root)["steps"]
+```
+
+(기존 `_WIZARD_PROMPTS_CACHE` 변수 — 더 이상 직접 사용 안 함. 새 `_WIZARD_ROOT_CACHE` 가 root 를 캐싱하므로 `_load_wizard_prompts` 가 매번 `_load_wizard_root["steps"]` 를 호출해도 캐시 hit. 옛 `_WIZARD_PROMPTS_CACHE` 는 dead code — 제거.)
+
+기존 `_p` 함수의 return 에 echo_variants / errors 추가:
+
+```python
+def _p(workspace_root: str, step_id: str, **vars: str) -> dict:
+    """... (기존 docstring 유지, 다음 한 줄 추가)
+    Returned dict also includes 'echo_variants' and 'errors' sub-dicts (may be empty).
+    """
+    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)
+    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", {}),
+        "echo_variants": raw.get("echo_variants", {}),
+        "errors": raw.get("errors", {}),
+    }
+```
+
+새 `_msg` 함수 추가 (`_p` 정의 직후):
+
+```python
+def _msg(workspace_root: str, section: str, key: str, **vars: str) -> str:
+    """Look up a top-level message (e.g., `confirmation.header`) and interpolate.
+
+    Returns the string value at `<section>.<key>`. Raises WizardError if the
+    section or key is unknown, or if a required placeholder is missing.
+
+    Use for wizard-level messages (confirmation block etc.). For step-scoped
+    messages (echo_variants, errors), use `_p()` instead.
+    """
+    root = _load_wizard_root(workspace_root)
+    sect = root.get(section)
+    if not isinstance(sect, dict):
+        raise WizardError(f"unknown wizard section: {section!r}")
+    template = sect.get(key)
+    if template is None:
+        raise WizardError(f"unknown wizard message: {section}.{key!r}")
+    try:
+        return template.format(**vars)
+    except KeyError as exc:
+        missing = exc.args[0] if exc.args else "<unknown>"
+        raise WizardError(
+            f"missing placeholder {missing!r} for wizard message {section}.{key!r}"
+        ) from exc
+```
+
+- [ ] **Step 4: 단위 테스트 + 회귀 통과 확인**
+
+```bash
+python3 -m pytest tests/test_wizard_prompts.py -v 2>&1 | tail -20
+```
+Expected: 모든 기존 9 + 신규 7 = 16 tests PASS.
+
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 611 passed, 1 skipped (604 + 7 new).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_prompts.py
+git commit -m "feat(wizard): add _load_wizard_root + _msg helpers; extend _p() with echo_variants/errors"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Task 3: 7 한글 사이트 atomic migration
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py`
+
+부분 마이그레이션 시 SOT 가 깨지므로 한 commit. 동작 보존 — pytest 회귀가 검증.
+
+- [ ] **Step 1: `_submit_task_group:643` 교체**
+
+`scripts/okstra_ctl/wizard.py` line 643 부근:
+
+**Before:**
+```python
+        if value == PICK_TYPE_CUSTOM:
+            state.task_group_pending_text = True
+            return f"task-group: (직접 입력)"
+```
+
+**After:**
+```python
+        if value == PICK_TYPE_CUSTOM:
+            state.task_group_pending_text = True
+            t = _p(state.workspace_root, "task_group")
+            return t["echo_variants"]["free_input"]
+```
+
+- [ ] **Step 2: `_submit_task_id:694` 교체**
+
+`scripts/okstra_ctl/wizard.py` line 694 부근:
+
+**Before:**
+```python
+        if value == PICK_TYPE_CUSTOM:
+            state.task_id_pending_text = True
+            return f"task-id: (직접 입력)"
+```
+
+**After:**
+```python
+        if value == PICK_TYPE_CUSTOM:
+            state.task_id_pending_text = True
+            t = _p(state.workspace_root, "task_id")
+            return t["echo_variants"]["free_input"]
+```
+
+- [ ] **Step 3: `_submit_brief_keep:769` 교체**
+
+`scripts/okstra_ctl/wizard.py` line 769 부근:
+
+**Before:**
+```python
+    if state.keep_existing_brief:
+        state.brief_path = state.existing_brief_path
+        return f"brief: {state.brief_path} (유지)"
+```
+
+**After:**
+```python
+    if state.keep_existing_brief:
+        state.brief_path = state.existing_brief_path
+        t = _p(state.workspace_root, "brief_keep", existing_brief_path=state.existing_brief_path)
+        return t["echo_variants"]["kept"].format(brief_path=state.brief_path)
+```
+
+(주의: `_p()` 의 `vars` 는 `label` 만 보간 — `echo_variants` 의 placeholder 는 별도 `.format()` 필요. 또는 `brief_path` 가 위 `existing_brief_path` 와 동일한 값이므로 단순화 가능.)
+
+대안 (더 간단):
+```python
+    if state.keep_existing_brief:
+        state.brief_path = state.existing_brief_path
+        t = _p(state.workspace_root, "brief_keep")
+        return t["echo_variants"]["kept"].format(brief_path=state.brief_path)
+```
+
+- [ ] **Step 4: `_submit_approved_plan_pick:900` WizardError 교체**
+
+`scripts/okstra_ctl/wizard.py` line 900 부근:
+
+**Before:**
+```python
+        if default is None:
+            raise WizardError(
+                "기본 approved-plan 경로를 찾을 수 없습니다. '다른 경로 입력'을 선택하세요."
+            )
+```
+
+**After:**
+```python
+        if default is None:
+            t = _p(state.workspace_root, "approved_plan_pick")
+            raise WizardError(t["errors"]["default_not_found"])
+```
+
+- [ ] **Step 5: `_submit_workers_override:1080` WizardError 교체**
+
+`scripts/okstra_ctl/wizard.py` line 1080 부근:
+
+**Before:**
+```python
+        if not chosen:
+            raise WizardError("워커를 최소 1개 선택해주세요")
+```
+
+**After:**
+```python
+        if not chosen:
+            t = _p(state.workspace_root, "workers_override")
+            raise WizardError(t["errors"]["min_one_required"])
+```
+
+- [ ] **Step 6: `confirmation_block:1717` + `:1727` 교체**
+
+`scripts/okstra_ctl/wizard.py` line 1715-1748 부근의 `confirmation_block` 함수:
+
+**Before:**
+```python
+def confirmation_block(state: WizardState) -> str:
+    """Human-readable echo of the resolved selections (for the Confirm step)."""
+    lines: list[str] = ["선택 확인:"]
+    lines.append(f"  task-type     : {state.task_type}")
+    ...
+    if state.task_type == "implementation":
+        lines.append(f"  executor      : {state.executor or '(default)'}")
+        lines.append(
+            f"  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"
+        )
+    else:
+        ...
+```
+
+**After:**
+```python
+def confirmation_block(state: WizardState) -> str:
+    """Human-readable echo of the resolved selections (for the Confirm step)."""
+    header = _msg(state.workspace_root, "confirmation", "header")
+    lines: list[str] = [header]
+    lines.append(f"  task-type     : {state.task_type}")
+    ...
+    if state.task_type == "implementation":
+        lines.append(f"  executor      : {state.executor or '(default)'}")
+        lines.append(
+            _msg(state.workspace_root, "confirmation", "workers_implementation_default")
+        )
+    else:
+        ...
+```
+
+- [ ] **Step 7: 한글 grep 점검 (informational — 정식 게이트는 Task 4)**
+
+```bash
+grep -nP '[가-힣]' scripts/okstra_ctl/wizard.py
+```
+Expected: docstring (line ~1054-1055 `_build_workers_override`) + 주석만. 코드 라인 한글 0.
+
+- [ ] **Step 8: 회귀 통과**
+
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 611 passed, 1 skipped.
+
+기존 wizard 테스트:
+```bash
+python3 -m pytest tests/test_okstra_ctl_wizard.py -v 2>&1 | tail -15
+```
+Expected: PASS.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add scripts/okstra_ctl/wizard.py
+git commit -m "refactor(wizard): externalize _submit_* echo + WizardError + confirmation_block strings"
+```
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Task 4: Korean grep gate scope 확장 + CHANGES.md + 최종 회귀
+
+**Files:**
+- Modify: `tests/test_wizard_prompts.py` — `test_no_korean_in_build_functions` 의 scope 를 `_build_*` + `_submit_*` + `confirmation_block` 까지 확장
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: grep gate scope 확장**
+
+`tests/test_wizard_prompts.py` 의 `test_no_korean_in_build_functions` 함수 명을 `test_no_korean_in_wizard_functions` 로 변경 + 함수 범위 detect regex 확장:
+
+**Before** (기존):
+```python
+def test_no_korean_in_build_functions():
+    ...
+    for i, line in enumerate(src_lines):
+        m = re.match(r'^def (_build_\w+)\(', line)
+        ...
+```
+
+**After:**
+```python
+def test_no_korean_in_wizard_functions():
+    """`_build_*` / `_submit_*` / `confirmation_block` 함수의 비-주석 코드 라인에 한글 0.
+
+    Scope: user-facing 한글이 코드에 다시 들어오는 회귀 차단.
+    정책: 주석/docstring 안의 한글은 허용 (정책상 외부화 대상 아님).
+    """
+    ...
+    SCOPED_FUNCTION_RE = re.compile(r'^def (_build_\w+|_submit_\w+|confirmation_block)\(')
+    for i, line in enumerate(src_lines):
+        m = SCOPED_FUNCTION_RE.match(line)
+        ...
+```
+
+전체 함수 body 변경 (실제 구현 시 기존 detection 로직 그대로 사용하되 regex 만 위처럼 교체):
+
+```python
+def test_no_korean_in_wizard_functions():
+    """`_build_*` / `_submit_*` / `confirmation_block` 함수의 비-주석 코드 라인에 한글 0.
+
+    Scope: user-facing 한글이 코드에 다시 들어오는 회귀 차단.
+    정책:
+    - 주석 라인 (# 시작) 안의 한글은 허용
+    - docstring 블록 (`\"\"\"...\"\"\"`) 안의 한글은 허용
+    - 그 외 user-facing UI 문자열은 `prompts/wizard/prompts.ko.json` 에 있어야 함.
+    """
+    import re
+
+    KOREAN = re.compile(r"[가-힣]")
+    SCOPED_FUNCTION_RE = re.compile(r'^def (_build_\w+|_submit_\w+|confirmation_block)\(')
+    src_lines = WIZARD_PY.read_text(encoding="utf-8").splitlines()
+
+    function_ranges: list[tuple[str, int, int]] = []
+    current_name: str | None = None
+    current_start: int | None = None
+    for i, line in enumerate(src_lines):
+        m = SCOPED_FUNCTION_RE.match(line)
+        if m:
+            if current_name is not None and current_start is not None:
+                function_ranges.append((current_name, current_start, i))
+            current_name = m.group(1)
+            current_start = i
+            continue
+        if current_name is not None and re.match(r'^def \w+\(|^[A-Za-z_]|^@', line):
+            function_ranges.append((current_name, current_start, i))
+            current_name = None
+            current_start = None
+    if current_name is not None and current_start is not None:
+        function_ranges.append((current_name, current_start, len(src_lines)))
+
+    offenders: list[str] = []
+    for name, start, end in function_ranges:
+        in_docstring = False
+        i = start + 1
+        while i < end:
+            line = src_lines[i]
+            stripped = line.strip()
+            if not in_docstring and (stripped.startswith('"""') or stripped.startswith("'''")):
+                quote = stripped[:3]
+                rest = stripped[3:]
+                if rest.endswith(quote) and len(rest) >= 3:
+                    pass
+                else:
+                    in_docstring = True
+                i += 1
+                continue
+            if in_docstring:
+                if stripped.endswith('"""') or stripped.endswith("'''"):
+                    in_docstring = False
+                i += 1
+                continue
+            if stripped.startswith("#"):
+                i += 1
+                continue
+            code_part = line.split("#", 1)[0]
+            if KOREAN.search(code_part):
+                offenders.append(f"  {name} ({WIZARD_PY.name}:{i+1}): {line.rstrip()[:120]}")
+            i += 1
+
+    assert not offenders, (
+        "wizard 함수 본문에 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_functions -v
+```
+Expected: PASS (Task 3 후 wizard.py 코드 라인 한글 0).
+
+만약 FAIL — 메시지가 짚는 한글이 `_build_*` / `_submit_*` / `confirmation_block` 안에 잔존. 그 사이트를 JSON 으로 이동.
+
+전체 회귀:
+```bash
+python3 -m pytest tests/ -x
+```
+Expected: 611 passed, 1 skipped.
+
+- [ ] **Step 3: CHANGES.md 항목 추가**
+
+`CHANGES.md` 의 `## 2026-05-20` 섹션 최상단 (Phase A1 entry 위) 에:
+
+```markdown
+### refactor(wizard): wizard 의 모든 user-facing 한글 JSON SOT 단일화 (A1 follow-up)
+
+- Phase A1 의 plan scope 외였던 잔존 한글 외부화: `_submit_*` echo 변형 (3개), `WizardError` 메시지 (2개), `confirmation_block` 라인 (2개) 을 `prompts/wizard/prompts.ko.json` 으로 이전.
+- 스키마 확장: step entry 안에 `echo_variants` / `errors` 서브필드, 최상위 `confirmation` 섹션 추가. `schema_version` 은 1 유지 (backward compatible 추가).
+- 신규 헬퍼: `_load_wizard_root(workspace_root)` (전체 root 캐시) + `_msg(workspace_root, section, key, **vars)` (top-level 섹션 lookup). 기존 `_p()` 는 echo_variants / errors 패스스루.
+- 정적 게이트 scope 확장: `test_no_korean_in_wizard_functions` 가 `_build_*` + `_submit_*` + `confirmation_block` 함수 본문 모두 검사. wizard.py 코드 라인 한글 0 보장 (docstring 제외).
+- 사용자 영향: 없음 (UI 동일). 컨트리뷰터 영향: wizard 의 모든 user-facing 문자열이 한 JSON 파일에. i18n 시 `prompts.<locale>.json` 하나만 추가하면 됨.
+```
+
+- [ ] **Step 4: npm build smoke**
+
+```bash
+npm run build
+```
+Expected: 에러 없음.
+
+검증:
+```bash
+python3 -c "import json; d=json.load(open('runtime/prompts/wizard/prompts.ko.json')); assert d['confirmation']['header'] == '선택 확인:'; print('OK')"
+```
+Expected: OK.
+
+- [ ] **Step 5: 최종 회귀 + e2e**
+
+```bash
+python3 -m pytest tests/ -v 2>&1 | tail -10
+```
+Expected: 611 passed, 1 skipped.
+
+```bash
+bash tests-e2e/scenario-01-record-start-reconcile.sh
+```
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tests/test_wizard_prompts.py CHANGES.md
+git commit -m "test(wizard): extend Korean grep gate to _submit_* + confirmation_block"
+```
+
+(CHANGES.md + gate scope 확장이 같은 PR 의 연관 작업이라 한 commit. 또는 분리해도 OK:
+```bash
+git add tests/test_wizard_prompts.py
+git commit -m "test(wizard): extend Korean grep gate to _submit_* + confirmation_block"
+git add CHANGES.md
+git commit -m "docs(changes): note wizard messages JSON SOT extension"
+```
+)
+
+No Claude trailer, no Co-Authored-By, no `🤖 Generated with` footer.
+
+---
+
+## Self-Review 체크리스트
+
+- [x] **Spec coverage**: 7 한글 사이트 모두 Task 3 에 명시. JSON 신규 키 Task 1 에 명시. 헬퍼 (Task 2). 게이트 scope 확장 (Task 4). 모두 커버.
+- [x] **Placeholder scan**: TBD/TODO 없음. 모든 step 에 실제 코드/명령/grep 패턴.
+- [x] **Type consistency**: `_load_wizard_root(workspace_root: str) -> dict` / `_msg(workspace_root: str, section: str, key: str, **vars: str) -> str` / `_p()` 확장 반환 키 (`echo_variants`, `errors`) — 모든 task 에서 일관.
+- [x] **Atomic migration**: Task 3 한 commit. 부분 migration 위험 없음.
+- [x] **Backward compatibility**: 기존 `_load_wizard_prompts` API 보존 (steps return). schema_version 1 유지 (새 필드는 additive).
+
+---
+
+## 실행 옵션
+
+Plan complete and saved to [docs/superpowers/plans/2026-05-20-wizard-messages-json-sot.md](docs/superpowers/plans/2026-05-20-wizard-messages-json-sot.md). 두 가지 실행 방식:
+
+1. **Subagent-Driven (recommended)** — task 마다 새로운 subagent + spec/code quality 2-stage review.
+2. **Inline Execution** — 본 세션에서 executing-plans 로 batch 실행.
+
+어떤 방식으로 진행할까요?