okstra 0.34.0 → 0.36.0

package/runtime/python/okstra_ctl/wizard.py

@@ -32,7 +32,10 @@ from okstra_ctl.models import (
     resolve_model_metadata,
 )
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
-from okstra_ctl.run import APPROVED_PLAN_PATTERN
+from okstra_ctl.run import (
+    APPROVED_FRONTMATTER_PATTERN,
+    _extract_frontmatter_block,
+)
 from okstra_ctl.workers import (
     ALLOWED_WORKERS,
     WorkersError,
@@ -54,11 +57,12 @@ from okstra_project.state import (
 
 TASK_TYPES: list[tuple[str, str]] = [
     ("requirements-discovery", "Classify request and route to next safe phase"),
+    ("improvement-discovery", "Find improvement candidates within a codebase scope and lens whitelist"),
     ("error-analysis", "Evidence-based root-cause analysis (no code changes)"),
     ("implementation-planning", "Plan options + request user approval"),
     ("implementation", "Execute approved plan (requires approved final-report)"),
     ("final-verification", "Acceptance + residual-risk review"),
-    ("release-handoff", "Drive commit/push/PR after accepted final-verification"),
+    ("release-handoff", "Drive commit/push/PR — reuse the implementation task-key (new keys fail the empty-commits gate)"),
 ]
 TASK_TYPE_VALUES = [tt for tt, _ in TASK_TYPES]
 
@@ -168,6 +172,7 @@ S_BASE_REF_PICK = "base_ref_pick"
 S_BASE_REF_TEXT = "base_ref_text"
 S_APPROVED_PLAN_PICK = "approved_plan_pick"
 S_APPROVED_PLAN = "approved_plan"
+S_STAGE_PICK = "stage_pick"
 S_EXECUTOR = "executor"
 S_DEFAULTS_OR_CUSTOM = "defaults_or_custom"
 S_WORKERS_OVERRIDE = "workers_override"
@@ -230,6 +235,7 @@ class WizardState:
     # impl extras
     approved_plan_path: str = ""
     approved_plan_pending_text: bool = False
+    selected_stage: str = "auto"
     executor: str = ""
 
     # customize
@@ -330,10 +336,24 @@ def _require_file(path_str: str, project_root: Path, label: str) -> Path:
 def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
     p = _require_file(path_str, project_root, "approved plan")
     body = p.read_text(encoding="utf-8", errors="replace")
-    if not APPROVED_PLAN_PATTERN.search(body):
+    frontmatter = _extract_frontmatter_block(body)
+    if frontmatter is None:
+        raise WizardError(
+            f"approved plan has no YAML frontmatter block: {p}\n"
+            "  expected the report to begin with `---\\n...\\n---\\n`."
+        )
+    m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
+    if not m:
+        raise WizardError(
+            f"approved plan frontmatter has no `approved:` field: {p}\n"
+            "  expected `approved: true` (report-writer emits `approved: false` "
+            "by default; flip it once approved)."
+        )
+    if m.group(1).lower() != "true":
         raise WizardError(
-            f"approved plan has no APPROVED marker: {p}\n"
-            '  canonical form (top of report): "- [x] Approved"'
+            f"approved plan is not yet approved (frontmatter `approved: {m.group(1)}`): {p}\n"
+            "  edit the report and change the line to `approved: true`, or re-run "
+            "okstra with `--approve` to flip it from the CLI."
         )
     return p
 
@@ -411,6 +431,122 @@ def _load_profile_optional_workers(
     return resolve_optional_workers(_profile_path(workspace_root, task_type))
 
 
+# --------------------------------------------------------------------------- #
+# Wizard prompt JSON SOT (Phase A1)
+# --------------------------------------------------------------------------- #
+
+_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). Callers that only need the steps
+    dict should index `["steps"]` on the return value; `_msg` 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
+
+
+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).
+
+    Returned dict also includes echo_variants and errors sub-dicts (may be empty).
+
+    Raises WizardError if the step_id is unknown or a required placeholder
+    is missing from the provided vars.
+    """
+    steps = _load_wizard_root(workspace_root)["steps"]
+    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", {}),
+    }
+
+
+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
+
+
+def _static_options(t: dict) -> list[tuple[str, str]]:
+    """Return (value, label) pairs from the SOT's static options dict, excluding
+    suffix-decoration tokens (`_<NAME>_SUFFIX` / `_<NAME>_LABEL`).
+
+    Used by hybrid `_build_*` functions that mix dynamic and static options to
+    avoid leaking `_RECOMMENDED_SUFFIX` / `_OPTIONAL_SUFFIX` / `_DEFAULT_SUFFIX`
+    as a literal option entry.
+    """
+    return [
+        (k, v) for k, v in t.get("options", {}).items()
+        if not (k.startswith("_") and (k.endswith("_SUFFIX") or k.endswith("_LABEL")))
+    ]
+
+
 def _resolved_roster(state: WizardState) -> list[str]:
     """Effective worker list AFTER override. Implementation: profile default
     (caller never asks for override). Others: override or profile default."""
@@ -464,24 +600,26 @@ def _opt(value: str, label: str = "", description: str = "") -> Option:
 # --- builders ---
 
 def _build_task_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "task_pick")
     project_root = Path(state.project_root)
     tasks = list_project_tasks(project_root)
     latest = read_latest_task(project_root) or {}
     latest_key = latest.get("taskKey") or ""
+    latest_suffix = t["options"].get("_LATEST_SUFFIX", "")
     options: list[Option] = []
     for entry in tasks[:8]:
         key = entry.get("taskKey") or ""
         ttype = entry.get("taskType") or ""
         phase = (entry.get("workflow") or {}).get("currentPhase") or ttype
         nxt = (entry.get("workflow") or {}).get("nextRecommendedPhase") or ""
-        suffix = "  (latest)" if key == latest_key else ""
+        suffix = latest_suffix if key == latest_key else ""
         label = f"{key}  ·  {phase}  ·  next: {nxt}{suffix}"
         options.append(_opt(value=key, label=label))
-    options.append(_opt(value=TASK_PICK_NEW_TOKEN,
-                        label="Start a brand-new task"))
+    for value, label in _static_options(t):
+        options.append(_opt(value=value, label=label))
     return Prompt(step=S_TASK_PICK, kind="pick",
-                  label="어느 task?", options=options,
-                  echo_template="task: {value}")
+                  label=t["label"], options=options,
+                  echo_template=t["echo_template"])
 
 
 def _submit_task_pick(state: WizardState, value: str) -> Optional[str]:
@@ -521,18 +659,21 @@ def _submit_task_pick(state: WizardState, value: str) -> Optional[str]:
 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=f"Task group? (brief 추천: {sugg})",
-            options=[
-                _opt(PICK_USE_SUGGESTED, f"brief 값 사용: {sugg}"),
-                _opt(PICK_TYPE_CUSTOM, "다른 값 입력"),
-            ],
-            echo_template="task-group: {value}",
+            label=t["label"], options=options,
+            echo_template=t["echo_template"],
         )
+    t = _p(state.workspace_root, "task_group")
     return Prompt(step=S_TASK_GROUP, kind="text",
-                  label="Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)",
-                  echo_template="task-group: {value}")
+                  label=t["label"],
+                  echo_template=t["echo_template"])
 
 
 def _submit_task_group(state: WizardState, value: str) -> Optional[str]:
@@ -545,7 +686,8 @@ def _submit_task_group(state: WizardState, value: str) -> Optional[str]:
             return f"task-group: {state.task_group} (brief)"
         if value == PICK_TYPE_CUSTOM:
             state.task_group_pending_text = True
-            return f"task-group: (직접 입력)"
+            t = _p(state.workspace_root, "task_group")
+            return t["echo_variants"]["free_input"]
         raise WizardError(
             f"expected {PICK_USE_SUGGESTED!r} or {PICK_TYPE_CUSTOM!r}, "
             f"got: {value!r}"
@@ -556,9 +698,10 @@ def _submit_task_group(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_task_group_text(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "task_group_text")
     return Prompt(step=S_TASK_GROUP_TEXT, kind="text",
-                  label="Task group 을 입력해주세요 (예: backend-api, INV-1234, refactor)",
-                  echo_template="task-group: {value}")
+                  label=t["label"],
+                  echo_template=t["echo_template"])
 
 
 def _submit_task_group_text(state: WizardState, value: str) -> Optional[str]:
@@ -570,18 +713,21 @@ def _submit_task_group_text(state: WizardState, value: str) -> Optional[str]:
 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=f"Task id? (brief 추천: {sugg})",
-            options=[
-                _opt(PICK_USE_SUGGESTED, f"brief 값 사용: {sugg}"),
-                _opt(PICK_TYPE_CUSTOM, "다른 값 입력"),
-            ],
-            echo_template="task-id: {value}",
+            label=t["label"], options=options,
+            echo_template=t["echo_template"],
         )
+    t = _p(state.workspace_root, "task_id")
     return Prompt(step=S_TASK_ID, kind="text",
-                  label="Task id 를 알려주세요 (예: login-error-analysis, dev-9043)",
-                  echo_template="task-id: {value}")
+                  label=t["label"],
+                  echo_template=t["echo_template"])
 
 
 def _submit_task_id(state: WizardState, value: str) -> Optional[str]:
@@ -592,7 +738,8 @@ def _submit_task_id(state: WizardState, value: str) -> Optional[str]:
             return f"task-id: {state.task_id} (brief)"
         if value == PICK_TYPE_CUSTOM:
             state.task_id_pending_text = True
-            return f"task-id: (직접 입력)"
+            t = _p(state.workspace_root, "task_id")
+            return t["echo_variants"]["free_input"]
         raise WizardError(
             f"expected {PICK_USE_SUGGESTED!r} or {PICK_TYPE_CUSTOM!r}, "
             f"got: {value!r}"
@@ -603,9 +750,10 @@ def _submit_task_id(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_task_id_text(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "task_id_text")
     return Prompt(step=S_TASK_ID_TEXT, kind="text",
-                  label="Task id 를 입력해주세요 (예: login-error-analysis, dev-9043)",
-                  echo_template="task-id: {value}")
+                  label=t["label"],
+                  echo_template=t["echo_template"])
 
 
 def _submit_task_id_text(state: WizardState, value: str) -> Optional[str]:
@@ -615,20 +763,22 @@ def _submit_task_id_text(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_task_type(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "task_type")
+    recommended_suffix = t["options"].get("_RECOMMENDED_SUFFIX", "")
     options: list[Option] = []
     recommended = state.task_type if not state.is_new_task else ""
     seen: list[str] = []
     if recommended and recommended in TASK_TYPE_VALUES:
         d = dict(TASK_TYPES)[recommended]
-        options.append(_opt(recommended, f"{recommended} (recommended)", d))
+        options.append(_opt(recommended, f"{recommended}{recommended_suffix}", d))
         seen.append(recommended)
     for tt, desc in TASK_TYPES:
         if tt in seen:
             continue
         options.append(_opt(tt, tt, desc))
     return Prompt(step=S_TASK_TYPE, kind="pick",
-                  label="Task type?", options=options,
-                  echo_template="task-type: {value}")
+                  label=t["label"], options=options,
+                  echo_template=t["echo_template"])
 
 
 def _submit_task_type(state: WizardState, value: str) -> Optional[str]:
@@ -648,11 +798,13 @@ def _submit_task_type(state: WizardState, value: str) -> Optional[str]:
 
 
 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=f"기존 brief 경로 [{state.existing_brief_path}] 를 유지할까요?",
-        options=[_opt("keep", "유지"), _opt("change", "변경")],
-        echo_template="brief: {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -662,15 +814,18 @@ def _submit_brief_keep(state: WizardState, value: str) -> Optional[str]:
     state.keep_existing_brief = value == "keep"
     if state.keep_existing_brief:
         state.brief_path = state.existing_brief_path
-        return f"brief: {state.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)
     return None  # next prompt is S_BRIEF_PATH
 
 
 def _build_brief_path(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "brief_path")
     return Prompt(
         step=S_BRIEF_PATH, kind="text",
-        label="task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)",
-        echo_template="brief: {value}",
+        label=t["label"],
+        echo_template=t["echo_template"],
     )
 
 
@@ -689,14 +844,17 @@ def _submit_brief_path(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_base_ref_pick(state: WizardState) -> Prompt:
-    options = [_opt(r, "main (recommended)" if r == "main" else r)
+    t = _p(state.workspace_root, "base_ref_pick")
+    recommended_suffix = t["options"].get("_RECOMMENDED_SUFFIX", "")
+    options = [_opt(r, f"main{recommended_suffix}" if r == "main" else r)
                for r in CANONICAL_BASE_REFS]
-    options.append(_opt(BASE_REF_FREE_INPUT_TOKEN, "직접 입력"))
+    for value, label in _static_options(t):
+        options.append(_opt(value=value, label=label))
     return Prompt(
         step=S_BASE_REF_PICK, kind="pick",
-        label="이 task worktree 의 base branch?",
+        label=t["label"],
         options=options,
-        echo_template="base-ref: {value}",
+        echo_template=t["echo_template"],
     )
 
 
@@ -712,10 +870,11 @@ def _submit_base_ref_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_base_ref_text(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "base_ref_text")
     return Prompt(
         step=S_BASE_REF_TEXT, kind="text",
-        label="base ref 를 입력해주세요 (branch, tag, 또는 short/full SHA)",
-        echo_template="base-ref: {value}",
+        label=t["label"],
+        echo_template=t["echo_template"],
     )
 
 
@@ -769,15 +928,17 @@ def _latest_implementation_planning_report(state: WizardState) -> Optional[Path]
 
 def _build_approved_plan_pick(state: WizardState) -> Prompt:
     default = _latest_implementation_planning_report(state)
+    t = _p(state.workspace_root, "approved_plan_pick",
+           default=str(default) if default is not None else "")
     options = [
-        _opt(PICK_USE_DEFAULT, f"기본 경로 사용: {default}"),
-        _opt(PICK_OTHER, "다른 경로 입력"),
+        _opt(k, v.format(default=str(default) if default is not None else ""))
+        for k, v in t["options"].items()
     ]
     return Prompt(
         step=S_APPROVED_PLAN_PICK, kind="pick",
-        label=f"approved final-report 경로 (기본: {default})",
+        label=t["label"],
         options=options,
-        echo_template="approved-plan(pick): {value}",
+        echo_template=t["echo_template"],
     )
 
 
@@ -785,9 +946,8 @@ def _submit_approved_plan_pick(state: WizardState, value: str) -> Optional[str]:
     if value == PICK_USE_DEFAULT:
         default = _latest_implementation_planning_report(state)
         if default is None:
-            raise WizardError(
-                "기본 approved-plan 경로를 찾을 수 없습니다. '다른 경로 입력'을 선택하세요."
-            )
+            t = _p(state.workspace_root, "approved_plan_pick", default="")
+            raise WizardError(t["errors"]["default_not_found"])
         p = _validate_approved_plan(str(default), Path(state.project_root))
         state.approved_plan_path = str(p)
         state.approved_plan_pending_text = False
@@ -802,10 +962,11 @@ def _submit_approved_plan_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_approved_plan(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "approved_plan")
     return Prompt(
         step=S_APPROVED_PLAN, kind="text",
-        label="approved final-report.md 의 경로를 알려주세요 (APPROVED 마커 필수)",
-        echo_template="approved-plan: {value}",
+        label=t["label"],
+        echo_template=t["echo_template"],
     )
 
 
@@ -816,15 +977,60 @@ def _submit_approved_plan(state: WizardState, value: str) -> Optional[str]:
     return f"approved-plan: {p}"
 
 
+def _build_stage_pick(state: WizardState) -> Prompt:
+    """Parse the Stage Map from the approved plan and build the stage picker."""
+    import importlib.util as _ilu
+    import sys as _sys
+    t = _p(state.workspace_root, "stage_pick")
+    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
+    validator_path = (
+        Path(state.workspace_root) / "validators"
+        / "validate-implementation-plan-stages.py"
+    )
+    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
+    mod = _ilu.module_from_spec(spec)  # type: ignore[arg-type]
+    _sys.modules["_ip_stage_v_wizard"] = mod
+    try:
+        spec.loader.exec_module(mod)  # type: ignore[union-attr]
+        stages, _errs = mod._parse_stage_map(plan_text)
+    finally:
+        _sys.modules.pop("_ip_stage_v_wizard", None)
+    options = [_opt(k, v) for k, v in t["options"].items()]
+    for s in stages:
+        depends = ",".join(map(str, s.depends_on)) or "(none)"
+        options.append(_opt(
+            str(s.stage_number),
+            f"{s.stage_number}: {s.title}  [depends-on: {depends} | steps: {s.step_count}]",
+        ))
+    return Prompt(
+        step=S_STAGE_PICK, kind="pick",
+        label=t["label"],
+        options=options,
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
+    if not answer:
+        raise WizardError("value required")
+    if answer != "auto":
+        try:
+            int(answer)
+        except ValueError:
+            raise WizardError(
+                f"answer must be 'auto' or a stage number, got {answer!r}"
+            )
+    state.selected_stage = answer
+    return f"stage: {answer}"
+
+
 def _build_directive_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "directive_pick")
     return Prompt(
         step=S_DIRECTIVE_PICK, kind="pick",
-        label="추가 directive 가 있나요?",
-        options=[
-            _opt(PICK_SKIP, "없음 (건너뛰기)"),
-            _opt(PICK_ENTER, "있음 (입력)"),
-        ],
-        echo_template="directive(pick): {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -840,14 +1046,12 @@ def _submit_directive_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_related_tasks_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "related_tasks_pick")
     return Prompt(
         step=S_RELATED_TASKS_PICK, kind="pick",
-        label="관련 task id 목록이 있나요?",
-        options=[
-            _opt(PICK_SKIP, "없음 (건너뛰기)"),
-            _opt(PICK_ENTER, "있음 (입력)"),
-        ],
-        echo_template="related-tasks(pick): {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -863,14 +1067,12 @@ def _submit_related_tasks_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_clarification_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "clarification_pick")
     return Prompt(
         step=S_CLARIFICATION_PICK, kind="pick",
-        label="clarification-response 파일 경로가 있나요? (follow-up 시에만)",
-        options=[
-            _opt(PICK_SKIP, "없음 (건너뛰기)"),
-            _opt(PICK_ENTER, "있음 (입력)"),
-        ],
-        echo_template="clarification(pick): {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -886,14 +1088,12 @@ def _submit_clarification_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_pr_template_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "pr_template_pick")
     return Prompt(
         step=S_PR_TEMPLATE_PICK, kind="pick",
-        label="PR 본문 템플릿 경로를 직접 지정할까요?",
-        options=[
-            _opt(PICK_SKIP, "자동 해석 (project.json → config → 기본)"),
-            _opt(PICK_ENTER, "직접 경로 입력 (1회성 override)"),
-        ],
-        echo_template="pr-template(pick): {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -910,13 +1110,15 @@ def _submit_pr_template_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_executor(state: WizardState) -> Prompt:
-    options = [_opt(e, e + (" (default)" if e == "claude" else ""))
+    t = _p(state.workspace_root, "executor")
+    default_suffix = t["options"].get("_DEFAULT_SUFFIX", "")
+    options = [_opt(e, e + (default_suffix if e == "claude" else ""))
                for e in EXECUTORS]
     return Prompt(
         step=S_EXECUTOR, kind="pick",
-        label="실행자 (executor)?",
+        label=t["label"],
         options=options,
-        echo_template="executor: {value}",
+        echo_template=t["echo_template"],
     )
 
 
@@ -928,12 +1130,12 @@ def _submit_executor(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_defaults_or_custom(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "defaults_or_custom")
     return Prompt(
         step=S_DEFAULTS_OR_CUSTOM, kind="pick",
-        label="기본 워커/모델로 진행할까요, 아니면 커스터마이즈할까요?",
-        options=[_opt("defaults", "Use defaults"),
-                 _opt("customize", "Customize")],
-        echo_template="customize: {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -947,6 +1149,8 @@ def _submit_defaults_or_custom(state: WizardState, value: str) -> Optional[str]:
 def _build_workers_override(state: WizardState) -> Prompt:
     """분석 워커 멀티픽. report-writer 는 옵션에서 빼고 항상 결과에 강제
     포함시킨다(프로필이 report-writer 를 Required 로 가질 때)."""
+    t = _p(state.workspace_root, "workers_override")
+    optional_suffix = t["options"].get("_OPTIONAL_SUFFIX", "")
     analyser_choices = [
         w for w in (state.profile_workers + state.profile_optional_workers)
         if w != "report-writer"
@@ -954,14 +1158,13 @@ def _build_workers_override(state: WizardState) -> Prompt:
     options: list[Option] = []
     for w in analyser_choices:
         is_optional = w in state.profile_optional_workers
-        label = f"{w} (옵션)" if is_optional else w
+        label = f"{w}{optional_suffix}" if is_optional else w
         options.append(_opt(value=w, label=label))
     return Prompt(
         step=S_WORKERS_OVERRIDE, kind="pick", multi=True,
-        label=("참여시킬 분석 워커를 선택해주세요 (최소 1개). "
-               "report-writer 는 항상 포함됩니다."),
+        label=t["label"],
         options=options,
-        echo_template="workers: {value}",
+        echo_template=t["echo_template"],
     )
 
 
@@ -970,7 +1173,8 @@ def _submit_workers_override(state: WizardState, value: str) -> Optional[str]:
     try:
         chosen = normalize_workers(raw) if raw else []
         if not chosen:
-            raise WizardError("워커를 최소 1개 선택해주세요")
+            t = _p(state.workspace_root, "workers_override")
+            raise WizardError(t["errors"]["min_one_required"])
         validate_workers_against_profile(
             chosen,
             state.profile_workers,
@@ -993,8 +1197,9 @@ def _model_pick(step: str, label: str, options: list[str], echo: str) -> Prompt:
 
 
 def _build_lead_model(state: WizardState) -> Prompt:
-    return _model_pick(S_LEAD_MODEL, "리더(Claude lead) 모델?",
-                       CLAUDE_MODEL_OPTIONS, "lead-model: {value}")
+    t = _p(state.workspace_root, "lead_model")
+    return _model_pick(S_LEAD_MODEL, t["label"],
+                       CLAUDE_MODEL_OPTIONS, t["echo_template"])
 
 
 def _submit_lead_model(state: WizardState, value: str) -> Optional[str]:
@@ -1003,11 +1208,12 @@ def _submit_lead_model(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_executor_model(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "executor_model", executor=state.executor)
     return _model_pick(
         S_EXECUTOR_MODEL,
-        f"실행자({state.executor}) 모델?",
+        t["label"],
         _executor_model_options(state.executor),
-        f"{state.executor}-model: {{value}}",
+        t["echo_template"].replace("{executor}", state.executor),
     )
 
 
@@ -1018,8 +1224,9 @@ def _submit_executor_model(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_claude_model(state: WizardState) -> Prompt:
-    return _model_pick(S_CLAUDE_MODEL, "claude 워커 모델?",
-                       CLAUDE_MODEL_OPTIONS, "claude-model: {value}")
+    t = _p(state.workspace_root, "claude_model")
+    return _model_pick(S_CLAUDE_MODEL, t["label"],
+                       CLAUDE_MODEL_OPTIONS, t["echo_template"])
 
 
 def _submit_claude_model(state: WizardState, value: str) -> Optional[str]:
@@ -1028,8 +1235,9 @@ def _submit_claude_model(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_codex_model(state: WizardState) -> Prompt:
-    return _model_pick(S_CODEX_MODEL, "codex 워커 모델?",
-                       CODEX_MODEL_OPTIONS, "codex-model: {value}")
+    t = _p(state.workspace_root, "codex_model")
+    return _model_pick(S_CODEX_MODEL, t["label"],
+                       CODEX_MODEL_OPTIONS, t["echo_template"])
 
 
 def _submit_codex_model(state: WizardState, value: str) -> Optional[str]:
@@ -1038,8 +1246,9 @@ def _submit_codex_model(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_gemini_model(state: WizardState) -> Prompt:
-    return _model_pick(S_GEMINI_MODEL, "gemini 워커 모델?",
-                       GEMINI_MODEL_OPTIONS, "gemini-model: {value}")
+    t = _p(state.workspace_root, "gemini_model")
+    return _model_pick(S_GEMINI_MODEL, t["label"],
+                       GEMINI_MODEL_OPTIONS, t["echo_template"])
 
 
 def _submit_gemini_model(state: WizardState, value: str) -> Optional[str]:
@@ -1048,10 +1257,11 @@ def _submit_gemini_model(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_report_writer_model(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "report_writer_model")
     return _model_pick(S_REPORT_WRITER_MODEL,
-                       "리포트 작성자(report-writer) 모델?",
+                       t["label"],
                        CLAUDE_MODEL_OPTIONS,
-                       "report-writer-model: {value}")
+                       t["echo_template"])
 
 
 def _submit_report_writer_model(state: WizardState, value: str) -> Optional[str]:
@@ -1060,10 +1270,11 @@ def _submit_report_writer_model(state: WizardState, value: str) -> Optional[str]
 
 
 def _build_directive(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "directive")
     return Prompt(
         step=S_DIRECTIVE, kind="text",
-        label="추가 directive 가 있으면 적어주세요 (없으면 빈 줄)",
-        echo_template="directive: {value}",
+        label=t["label"],
+        echo_template=t["echo_template"],
     )
 
 
@@ -1074,10 +1285,11 @@ def _submit_directive(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_related_tasks(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "related_tasks")
     return Prompt(
         step=S_RELATED_TASKS, kind="text",
-        label="관련 task id 목록을 쉼표로 구분해서 적어주세요 (없으면 빈 줄)",
-        echo_template="related-tasks: {value}",
+        label=t["label"],
+        echo_template=t["echo_template"],
     )
 
 
@@ -1088,10 +1300,11 @@ def _submit_related_tasks(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_clarification(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "clarification")
     return Prompt(
         step=S_CLARIFICATION, kind="text",
-        label="clarification-response 파일 경로 (follow-up 시에만, 없으면 빈 줄)",
-        echo_template="clarification: {value}",
+        label=t["label"],
+        echo_template=t["echo_template"],
     )
 
 
@@ -1107,11 +1320,11 @@ def _submit_clarification(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_pr_template(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "pr_template")
     return Prompt(
         step=S_PR_TEMPLATE, kind="text",
-        label=("PR 본문 템플릿 경로 1회성 override (빈 줄이면 project.json → "
-               "~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)"),
-        echo_template="pr-template: {value}",
+        label=t["label"],
+        echo_template=t["echo_template"],
     )
 
 
@@ -1134,15 +1347,12 @@ def _submit_pr_template(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_pr_template_scope(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "pr_template_scope")
     return Prompt(
         step=S_PR_TEMPLATE_SCOPE, kind="pick",
-        label="방금 입력한 경로를 영구 저장할까요?",
-        options=[
-            _opt("once", "이번 run 만 (1회성)"),
-            _opt("project", "프로젝트에 저장 (project scope)"),
-            _opt("global", "전역에 저장 (global scope)"),
-        ],
-        echo_template="pr-template-scope: {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -1156,11 +1366,12 @@ def _submit_pr_template_scope(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_confirm(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "confirm")
     return Prompt(
         step=S_CONFIRM, kind="pick",
-        label="이대로 진행할까요?",
-        options=[_opt("proceed", "Proceed"), _opt("edit", "Edit")],
-        echo_template="confirm: {value}",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
     )
 
 
@@ -1172,6 +1383,7 @@ def _submit_confirm(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_edit_target(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "edit_target")
     # offer every step that has been answered.
     options: list[Option] = []
     for sid in state.answered:
@@ -1180,9 +1392,9 @@ def _build_edit_target(state: WizardState) -> Prompt:
         options.append(_opt(sid, sid))
     return Prompt(
         step=S_EDIT_TARGET, kind="pick",
-        label="어느 step 으로 돌아갈까요?",
+        label=t["label"],
         options=options,
-        echo_template="edit-target: {value}",
+        echo_template=t["echo_template"],
     )
 
 
@@ -1303,6 +1515,12 @@ STEPS: list[Step] = [
                                  or _latest_implementation_planning_report(s) is None)),
          build=_build_approved_plan, submit=_submit_approved_plan,
          owns=("approved_plan_path", "approved_plan_pending_text")),
+    Step(S_STAGE_PICK,
+         applies=lambda s: (s.task_type == "implementation"
+                            and bool(s.approved_plan_path)
+                            and S_STAGE_PICK not in s.answered),
+         build=_build_stage_pick, submit=_submit_stage_pick,
+         owns=("selected_stage",)),
     Step(S_EXECUTOR,
          applies=lambda s: (s.task_type == "implementation"
                             and bool(s.approved_plan_path)
@@ -1500,6 +1718,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "brief_path": "", "reuse_worktree": None, "base_ref": "",
     "base_ref_pending_text": False, "approved_plan_path": "",
     "approved_plan_pending_text": False,
+    "selected_stage": "auto",
     "executor": "", "use_defaults": None, "workers_override": "",
     "lead_model": "", "claude_model": "", "codex_model": "",
     "gemini_model": "", "report_writer_model": "", "directive": "",
@@ -1583,6 +1802,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "task-brief": state.brief_path,
         "executor": state.executor,
         "approved-plan": state.approved_plan_path,
+        "stage": (state.selected_stage or "auto") if state.task_type == "implementation" else "",
         "base-ref": base_ref,
         "workers": workers,
         "directive": state.directive,
@@ -1599,7 +1819,8 @@ def render_args(state: WizardState) -> dict[str, str]:
 
 def confirmation_block(state: WizardState) -> str:
     """Human-readable echo of the resolved selections (for the Confirm step)."""
-    lines: list[str] = ["선택 확인:"]
+    header = _msg(state.workspace_root, "confirmation", "header")
+    lines: list[str] = [header]
     lines.append(f"  task-type     : {state.task_type}")
     lines.append(f"  task-key      : {state.task_group}/{state.task_id}")
     if state.reuse_worktree:
@@ -1609,7 +1830,7 @@ def confirmation_block(state: WizardState) -> str:
     if state.task_type == "implementation":
         lines.append(f"  executor      : {state.executor or '(default)'}")
         lines.append(
-            f"  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"
+            _msg(state.workspace_root, "confirmation", "workers_implementation_default")
         )
     else:
         roster = state.workers_override or ",".join(state.profile_workers) or "(profile default)"