okstra 0.22.0 → 0.24.0

package/runtime/python/okstra_ctl/wizard.py

@@ -0,0 +1,1249 @@
+"""okstra-run wizard — state machine for interactive task setup.
+
+The okstra-run skill used to encode the full input-collection flow in prose,
+which drifted into seven internal inconsistencies (executor placement,
+free-text-via-AskUserQuestion, missing clarification prompt for impl, etc.).
+This module owns the flow as code so the skill becomes a thin loop.
+
+Public surface:
+- ``WizardState``   - serializable dataclass; one state file per run.
+- ``Prompt``        - what the skill should ask next.
+- ``init_state()``  - seed from project-root / project-id / workspace-root.
+- ``next_prompt()`` - deterministic; pure read on state.
+- ``submit()``      - validate + advance.
+- ``render_args()`` - final args for ``okstra render-bundle``.
+
+The skill calls these via the ``okstra wizard`` CLI subcommand; it never
+imports this module directly.
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.models import (
+    PROVIDER_MAPPINGS,
+    UnknownModelError,
+    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.workers import (
+    ALLOWED_WORKERS,
+    WorkersError,
+    normalize_workers,
+    resolve_profile_workers,
+    validate_workers_against_profile,
+)
+from okstra_ctl import worktree_registry
+from okstra_project.state import (
+    list_project_tasks,
+    read_latest_task,
+    read_task_manifest,
+    find_task_root,
+)
+
+
+# ---- Constants -----------------------------------------------------------
+
+TASK_TYPES: list[tuple[str, str]] = [
+    ("requirements-discovery", "Classify request and route to next safe phase"),
+    ("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"),
+]
+TASK_TYPE_VALUES = [tt for tt, _ in TASK_TYPES]
+
+EXECUTORS = ["claude", "codex", "gemini"]
+
+CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
+BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
+
+CLAUDE_MODEL_OPTIONS = ["default", "opus", "sonnet", "haiku"]
+CODEX_MODEL_OPTIONS = ["default", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini"]
+GEMINI_MODEL_OPTIONS = ["default", "gemini-3-pro-preview", "gemini-3-flash-preview", "auto"]
+
+# special pick value: start a brand-new task
+TASK_PICK_NEW_TOKEN = "__new__"
+
+
+# ---- Step IDs ------------------------------------------------------------
+
+S_TASK_PICK = "task_pick"
+S_TASK_GROUP = "task_group"
+S_TASK_ID = "task_id"
+S_TASK_TYPE = "task_type"
+S_BRIEF_KEEP = "brief_keep"
+S_BRIEF_PATH = "brief_path"
+S_BASE_REF_PICK = "base_ref_pick"
+S_BASE_REF_TEXT = "base_ref_text"
+S_APPROVED_PLAN = "approved_plan"
+S_EXECUTOR = "executor"
+S_DEFAULTS_OR_CUSTOM = "defaults_or_custom"
+S_WORKERS_OVERRIDE = "workers_override"
+S_LEAD_MODEL = "lead_model"
+S_EXECUTOR_MODEL = "executor_model"
+S_CLAUDE_MODEL = "claude_model"
+S_CODEX_MODEL = "codex_model"
+S_GEMINI_MODEL = "gemini_model"
+S_REPORT_WRITER_MODEL = "report_writer_model"
+S_DIRECTIVE = "directive"
+S_RELATED_TASKS = "related_tasks"
+S_CLARIFICATION = "clarification"
+S_PR_TEMPLATE = "pr_template"
+S_PR_TEMPLATE_SCOPE = "pr_template_scope"
+S_CONFIRM = "confirm"
+S_EDIT_TARGET = "edit_target"
+S_DONE = "done"
+
+
+# ---- Data types ----------------------------------------------------------
+
+@dataclass
+class WizardState:
+    # bootstrap
+    workspace_root: str = ""
+    project_root: str = ""
+    project_id: str = ""
+
+    # task identity
+    is_new_task: Optional[bool] = None
+    task_group: str = ""
+    task_id: str = ""
+    existing_brief_path: str = ""
+
+    # task-type + dependents
+    task_type: str = ""
+    profile_workers: list[str] = field(default_factory=list)
+
+    # brief
+    keep_existing_brief: Optional[bool] = None
+    brief_path: str = ""
+
+    # worktree
+    reuse_worktree: Optional[bool] = None
+    base_ref: str = ""
+    base_ref_pending_text: bool = False
+
+    # impl extras
+    approved_plan_path: str = ""
+    executor: str = ""
+
+    # customize
+    use_defaults: Optional[bool] = None
+    workers_override: str = ""
+    lead_model: str = ""
+    claude_model: str = ""
+    codex_model: str = ""
+    gemini_model: str = ""
+    report_writer_model: str = ""
+    directive: str = ""
+    related_tasks_raw: str = ""
+    clarification_response_path: str = ""
+    pr_template_path: str = ""
+    pr_template_scope: str = ""  # "once" | "project" | "global"
+
+    # confirm / edit
+    confirmed: Optional[bool] = None
+    edit_target: str = ""
+
+    # bookkeeping
+    answered: list[str] = field(default_factory=list)
+
+    def to_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "WizardState":
+        return cls(**d)
+
+
+@dataclass
+class Option:
+    value: str
+    label: str
+    description: str = ""
+
+
+@dataclass
+class Prompt:
+    step: str
+    kind: str  # "pick" | "text" | "done"
+    label: str = ""
+    options: list[Option] = field(default_factory=list)
+    help: str = ""
+    echo_template: str = ""  # e.g. "task-group: {value}"
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "step": self.step,
+            "kind": self.kind,
+            "label": self.label,
+            "options": [asdict(o) for o in self.options],
+            "help": self.help,
+            "echoTemplate": self.echo_template,
+        }
+
+
+class WizardError(Exception):
+    """validation failure surfaced to user."""
+
+
+# ---- Validation helpers --------------------------------------------------
+
+_SLUG_OK = re.compile(r"[a-z0-9]")
+
+
+def _slug_or_die(value: str, field_name: str) -> str:
+    slug = slugify_task_segment(value or "")
+    if not slug or not _SLUG_OK.search(slug):
+        raise WizardError(
+            f"{field_name} must contain at least one alphanumeric character "
+            f"(got: {value!r})"
+        )
+    return slug
+
+
+def _resolve_path(path_str: str, project_root: Path) -> Path:
+    p = Path(path_str).expanduser()
+    return p if p.is_absolute() else (project_root / p).resolve()
+
+
+def _require_file(path_str: str, project_root: Path, label: str) -> Path:
+    if not (path_str or "").strip():
+        raise WizardError(f"{label}: empty path")
+    p = _resolve_path(path_str, project_root)
+    if not p.is_file():
+        raise WizardError(f"{label}: file not found: {p}")
+    return p
+
+
+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):
+        raise WizardError(
+            f"approved plan has no APPROVED marker: {p}\n"
+            '  canonical form (top of report): "- [x] Approved"'
+        )
+    return p
+
+
+def _git_main_worktree(project_root: Path) -> Path:
+    try:
+        common = subprocess.check_output(
+            ["git", "-C", str(project_root), "rev-parse",
+             "--path-format=absolute", "--git-common-dir"],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+        raise WizardError(f"git unavailable in {project_root}: {exc}")
+    return Path(common).parent
+
+
+def _validate_base_ref(ref: str, project_root: Path) -> str:
+    ref = (ref or "").strip()
+    if not ref:
+        raise WizardError("base ref is empty")
+    main_wt = _git_main_worktree(project_root)
+    rc = subprocess.call(
+        ["git", "-C", str(main_wt), "rev-parse",
+         "--verify", "--quiet", f"{ref}^{{commit}}"],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+    if rc != 0:
+        raise WizardError(f"base ref not found in repository: {ref}")
+    return ref
+
+
+def _validate_model(provider: str, raw: str) -> str:
+    """Empty / 'default' → '' (use phase default).
+    Known alias → canonical option (passed verbatim to render-bundle).
+    Unknown → WizardError.
+    """
+    raw = (raw or "").strip()
+    if raw == "" or raw.lower() == "default":
+        return ""
+    try:
+        resolve_model_metadata(
+            provider=provider, raw_value=raw,
+            default_display="x", default_execution="x",
+        )
+    except UnknownModelError as exc:
+        raise WizardError(str(exc))
+    return raw
+
+
+def _executor_model_field(executor: str) -> str:
+    return {"claude": "claude_model",
+            "codex": "codex_model",
+            "gemini": "gemini_model"}[executor]
+
+
+def _executor_model_options(executor: str) -> list[str]:
+    return {"claude": CLAUDE_MODEL_OPTIONS,
+            "codex": CODEX_MODEL_OPTIONS,
+            "gemini": GEMINI_MODEL_OPTIONS}[executor]
+
+
+# ---- Roster / profile helpers -------------------------------------------
+
+def _profile_path(workspace_root: Path, task_type: str) -> Path:
+    return workspace_root / "prompts" / "profiles" / f"{task_type}.md"
+
+
+def _load_profile_workers(workspace_root: Path, task_type: str) -> list[str]:
+    return resolve_profile_workers(_profile_path(workspace_root, task_type))
+
+
+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."""
+    if state.task_type == "implementation":
+        return list(state.profile_workers)
+    if state.workers_override.strip():
+        return normalize_workers(state.workers_override)
+    return list(state.profile_workers)
+
+
+# ---- Worktree resolution ------------------------------------------------
+
+def _resolve_reuse_worktree(state: WizardState) -> bool:
+    """For a finalized task identity, is there an active worktree to reuse?
+    New tasks always answer False (no entry possible)."""
+    if state.is_new_task:
+        return False
+    if not (state.project_id and state.task_group and state.task_id):
+        return False
+    entry = worktree_registry.lookup(state.project_id,
+                                     state.task_group, state.task_id)
+    return bool(entry and entry.status == "active")
+
+
+def _existing_task_brief(project_root: Path, task_key: str) -> str:
+    """Read taskBriefPath from manifest for an existing task. Empty if none."""
+    root = find_task_root(project_root, task_key)
+    if root is None:
+        return ""
+    manifest = read_task_manifest(root) or {}
+    val = manifest.get("taskBriefPath") or ""
+    return val if isinstance(val, str) else ""
+
+
+# ---- Step descriptors ---------------------------------------------------
+
+@dataclass
+class Step:
+    id: str
+    applies: Callable[[WizardState], bool]
+    build: Callable[[WizardState], Prompt]
+    submit: Callable[[WizardState, str], Optional[str]]
+    # Field names this step owns; resetting the step clears them.
+    owns: tuple[str, ...] = ()
+
+
+def _opt(value: str, label: str = "", description: str = "") -> Option:
+    return Option(value=value, label=label or value, description=description)
+
+
+# --- builders ---
+
+def _build_task_pick(state: WizardState) -> Prompt:
+    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 ""
+    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 ""
+        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"))
+    return Prompt(step=S_TASK_PICK, kind="pick",
+                  label="어느 task?", options=options,
+                  echo_template="task: {value}")
+
+
+def _submit_task_pick(state: WizardState, value: str) -> Optional[str]:
+    value = value.strip()
+    if value == TASK_PICK_NEW_TOKEN:
+        state.is_new_task = True
+        state.task_group = ""
+        state.task_id = ""
+        state.existing_brief_path = ""
+        state.task_type = ""
+        return "task: (brand-new)"
+    # parse "<project-id>:<task-group>:<task-id>"
+    parts = value.split(":")
+    if len(parts) != 3 or not all(parts):
+        raise WizardError(
+            f"invalid task-key: {value!r} (expected project-id:task-group:task-id)"
+        )
+    pid, tg, tid = parts
+    if pid != state.project_id:
+        raise WizardError(
+            f"task-key project-id {pid!r} does not match current project {state.project_id!r}"
+        )
+    state.is_new_task = False
+    state.task_group = tg
+    state.task_id = tid
+    state.existing_brief_path = _existing_task_brief(
+        Path(state.project_root), value
+    )
+    # task_type seeded from manifest's nextRecommendedPhase as the recommended default
+    root = find_task_root(Path(state.project_root), value)
+    manifest = (read_task_manifest(root) or {}) if root else {}
+    workflow = manifest.get("workflow") or {}
+    state.task_type = workflow.get("nextRecommendedPhase") or ""
+    return f"task: {value}"
+
+
+def _build_task_group(state: WizardState) -> Prompt:
+    return Prompt(step=S_TASK_GROUP, kind="text",
+                  label="Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)",
+                  echo_template="task-group: {value}")
+
+
+def _submit_task_group(state: WizardState, value: str) -> Optional[str]:
+    state.task_group = _slug_or_die(value, "task_group")
+    return f"task-group: {state.task_group}"
+
+
+def _build_task_id(state: WizardState) -> Prompt:
+    return Prompt(step=S_TASK_ID, kind="text",
+                  label="Task id 를 알려주세요 (예: login-error-analysis, dev-9043)",
+                  echo_template="task-id: {value}")
+
+
+def _submit_task_id(state: WizardState, value: str) -> Optional[str]:
+    state.task_id = _slug_or_die(value, "task_id")
+    return f"task-id: {state.task_id}"
+
+
+def _build_task_type(state: WizardState) -> Prompt:
+    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))
+        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}")
+
+
+def _submit_task_type(state: WizardState, value: str) -> Optional[str]:
+    if value not in TASK_TYPE_VALUES:
+        raise WizardError(f"unknown task-type: {value!r}")
+    state.task_type = value
+    state.profile_workers = _load_profile_workers(
+        Path(state.workspace_root), value
+    )
+    # Reuse-worktree is decided once identity is final. Recompute here so
+    # subsequent base-ref step knows whether to apply.
+    state.reuse_worktree = _resolve_reuse_worktree(state)
+    return f"task-type: {value}"
+
+
+def _build_brief_keep(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_BRIEF_KEEP, kind="pick",
+        label=f"기존 brief 경로 [{state.existing_brief_path}] 를 유지할까요?",
+        options=[_opt("keep", "유지"), _opt("change", "변경")],
+        echo_template="brief: {value}",
+    )
+
+
+def _submit_brief_keep(state: WizardState, value: str) -> Optional[str]:
+    if value not in ("keep", "change"):
+        raise WizardError(f"expected 'keep' or 'change', got: {value!r}")
+    state.keep_existing_brief = value == "keep"
+    if state.keep_existing_brief:
+        state.brief_path = state.existing_brief_path
+        return f"brief: {state.brief_path} (유지)"
+    return None  # next prompt is S_BRIEF_PATH
+
+
+def _build_brief_path(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_BRIEF_PATH, kind="text",
+        label="task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)",
+        echo_template="brief: {value}",
+    )
+
+
+def _submit_brief_path(state: WizardState, value: str) -> Optional[str]:
+    p = _require_file(value, Path(state.project_root), "task brief")
+    state.brief_path = str(p)
+    return f"brief: {p}"
+
+
+def _build_base_ref_pick(state: WizardState) -> Prompt:
+    options = [_opt(r, "main (recommended)" if r == "main" else r)
+               for r in CANONICAL_BASE_REFS]
+    options.append(_opt(BASE_REF_FREE_INPUT_TOKEN, "직접 입력"))
+    return Prompt(
+        step=S_BASE_REF_PICK, kind="pick",
+        label="이 task worktree 의 base branch?",
+        options=options,
+        echo_template="base-ref: {value}",
+    )
+
+
+def _submit_base_ref_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == BASE_REF_FREE_INPUT_TOKEN:
+        state.base_ref_pending_text = True
+        state.base_ref = ""
+        return None
+    state.base_ref_pending_text = False
+    ref = _validate_base_ref(value, Path(state.project_root))
+    state.base_ref = ref
+    return f"base-ref: {ref}"
+
+
+def _build_base_ref_text(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_BASE_REF_TEXT, kind="text",
+        label="base ref 를 입력해주세요 (branch, tag, 또는 short/full SHA)",
+        echo_template="base-ref: {value}",
+    )
+
+
+def _submit_base_ref_text(state: WizardState, value: str) -> Optional[str]:
+    ref = _validate_base_ref(value, Path(state.project_root))
+    state.base_ref = ref
+    state.base_ref_pending_text = False
+    return f"base-ref: {ref}"
+
+
+def _build_approved_plan(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_APPROVED_PLAN, kind="text",
+        label="approved final-report.md 의 경로를 알려주세요 (APPROVED 마커 필수)",
+        echo_template="approved-plan: {value}",
+    )
+
+
+def _submit_approved_plan(state: WizardState, value: str) -> Optional[str]:
+    p = _validate_approved_plan(value, Path(state.project_root))
+    state.approved_plan_path = str(p)
+    return f"approved-plan: {p}"
+
+
+def _build_executor(state: WizardState) -> Prompt:
+    options = [_opt(e, e + (" (default)" if e == "claude" else ""))
+               for e in EXECUTORS]
+    return Prompt(
+        step=S_EXECUTOR, kind="pick",
+        label="실행자 (executor)?",
+        options=options,
+        echo_template="executor: {value}",
+    )
+
+
+def _submit_executor(state: WizardState, value: str) -> Optional[str]:
+    if value not in EXECUTORS:
+        raise WizardError(f"executor must be one of {EXECUTORS}, got: {value!r}")
+    state.executor = value
+    return f"executor: {value}"
+
+
+def _build_defaults_or_custom(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_DEFAULTS_OR_CUSTOM, kind="pick",
+        label="기본 워커/모델로 진행할까요, 아니면 커스터마이즈할까요?",
+        options=[_opt("defaults", "Use defaults"),
+                 _opt("customize", "Customize")],
+        echo_template="customize: {value}",
+    )
+
+
+def _submit_defaults_or_custom(state: WizardState, value: str) -> Optional[str]:
+    if value not in ("defaults", "customize"):
+        raise WizardError(f"expected 'defaults' or 'customize', got: {value!r}")
+    state.use_defaults = value == "defaults"
+    return f"customize: {'no' if state.use_defaults else 'yes'}"
+
+
+def _build_workers_override(state: WizardState) -> Prompt:
+    csv = ",".join(state.profile_workers)
+    return Prompt(
+        step=S_WORKERS_OVERRIDE, kind="text",
+        label=(f"참여 워커 목록을 쉼표로 구분해서 적어주세요. "
+               f"빈 줄이면 프로필 기본값 [{csv}] 을 그대로 씁니다. "
+               f"사용 가능한 워커: {csv}"),
+        echo_template="workers: {value}",
+    )
+
+
+def _submit_workers_override(state: WizardState, value: str) -> Optional[str]:
+    if not (value or "").strip():
+        state.workers_override = ""
+        return f"workers: (profile default: {','.join(state.profile_workers)})"
+    try:
+        chosen = normalize_workers(value)
+        validate_workers_against_profile(chosen, state.profile_workers)
+    except WorkersError as exc:
+        raise WizardError(str(exc))
+    state.workers_override = ",".join(chosen)
+    return f"workers: {state.workers_override}"
+
+
+def _model_pick(step: str, label: str, options: list[str], echo: str) -> Prompt:
+    opts = [_opt(o, o) for o in options]
+    return Prompt(step=step, kind="pick", label=label,
+                  options=opts, echo_template=echo)
+
+
+def _build_lead_model(state: WizardState) -> Prompt:
+    return _model_pick(S_LEAD_MODEL, "리더(Claude lead) 모델?",
+                       CLAUDE_MODEL_OPTIONS, "lead-model: {value}")
+
+
+def _submit_lead_model(state: WizardState, value: str) -> Optional[str]:
+    state.lead_model = _validate_model("claude", value)
+    return f"lead-model: {state.lead_model or 'default'}"
+
+
+def _build_executor_model(state: WizardState) -> Prompt:
+    return _model_pick(
+        S_EXECUTOR_MODEL,
+        f"실행자({state.executor}) 모델?",
+        _executor_model_options(state.executor),
+        f"{state.executor}-model: {{value}}",
+    )
+
+
+def _submit_executor_model(state: WizardState, value: str) -> Optional[str]:
+    resolved = _validate_model(state.executor, value)
+    setattr(state, _executor_model_field(state.executor), resolved)
+    return f"{state.executor}-model: {resolved or 'default'}"
+
+
+def _build_claude_model(state: WizardState) -> Prompt:
+    return _model_pick(S_CLAUDE_MODEL, "claude 워커 모델?",
+                       CLAUDE_MODEL_OPTIONS, "claude-model: {value}")
+
+
+def _submit_claude_model(state: WizardState, value: str) -> Optional[str]:
+    state.claude_model = _validate_model("claude", value)
+    return f"claude-model: {state.claude_model or 'default'}"
+
+
+def _build_codex_model(state: WizardState) -> Prompt:
+    return _model_pick(S_CODEX_MODEL, "codex 워커 모델?",
+                       CODEX_MODEL_OPTIONS, "codex-model: {value}")
+
+
+def _submit_codex_model(state: WizardState, value: str) -> Optional[str]:
+    state.codex_model = _validate_model("codex", value)
+    return f"codex-model: {state.codex_model or 'default'}"
+
+
+def _build_gemini_model(state: WizardState) -> Prompt:
+    return _model_pick(S_GEMINI_MODEL, "gemini 워커 모델?",
+                       GEMINI_MODEL_OPTIONS, "gemini-model: {value}")
+
+
+def _submit_gemini_model(state: WizardState, value: str) -> Optional[str]:
+    state.gemini_model = _validate_model("gemini", value)
+    return f"gemini-model: {state.gemini_model or 'default'}"
+
+
+def _build_report_writer_model(state: WizardState) -> Prompt:
+    return _model_pick(S_REPORT_WRITER_MODEL,
+                       "리포트 작성자(report-writer) 모델?",
+                       CLAUDE_MODEL_OPTIONS,
+                       "report-writer-model: {value}")
+
+
+def _submit_report_writer_model(state: WizardState, value: str) -> Optional[str]:
+    state.report_writer_model = _validate_model("claude", value)
+    return f"report-writer-model: {state.report_writer_model or 'default'}"
+
+
+def _build_directive(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_DIRECTIVE, kind="text",
+        label="추가 directive 가 있으면 적어주세요 (없으면 빈 줄)",
+        echo_template="directive: {value}",
+    )
+
+
+def _submit_directive(state: WizardState, value: str) -> Optional[str]:
+    state.directive = (value or "").strip()
+    return f"directive: {state.directive or '(none)'}"
+
+
+def _build_related_tasks(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_RELATED_TASKS, kind="text",
+        label="관련 task id 목록을 쉼표로 구분해서 적어주세요 (없으면 빈 줄)",
+        echo_template="related-tasks: {value}",
+    )
+
+
+def _submit_related_tasks(state: WizardState, value: str) -> Optional[str]:
+    state.related_tasks_raw = (value or "").strip()
+    return f"related-tasks: {state.related_tasks_raw or '(none)'}"
+
+
+def _build_clarification(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_CLARIFICATION, kind="text",
+        label="clarification-response 파일 경로 (follow-up 시에만, 없으면 빈 줄)",
+        echo_template="clarification: {value}",
+    )
+
+
+def _submit_clarification(state: WizardState, value: str) -> Optional[str]:
+    val = (value or "").strip()
+    if not val:
+        state.clarification_response_path = ""
+        return "clarification: (none)"
+    p = _require_file(val, Path(state.project_root), "clarification-response")
+    state.clarification_response_path = str(p)
+    return f"clarification: {p}"
+
+
+def _build_pr_template(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_PR_TEMPLATE, kind="text",
+        label=("PR 본문 템플릿 경로 1회성 override (빈 줄이면 project.json → "
+               "~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)"),
+        echo_template="pr-template: {value}",
+    )
+
+
+def _submit_pr_template(state: WizardState, value: str) -> Optional[str]:
+    val = (value or "").strip()
+    if not val:
+        state.pr_template_path = ""
+        state.pr_template_scope = ""
+        return "pr-template: (auto-resolve)"
+    # Validate by re-using resolve_pr_template_path with override.
+    try:
+        resolved = resolve_pr_template_path(
+            Path(state.project_root), override_path=val
+        )
+    except PrTemplateError as exc:
+        raise WizardError(str(exc))
+    state.pr_template_path = str(resolved.path)
+    return f"pr-template: {resolved.path}"
+
+
+def _build_pr_template_scope(state: WizardState) -> Prompt:
+    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}",
+    )
+
+
+def _submit_pr_template_scope(state: WizardState, value: str) -> Optional[str]:
+    if value not in ("once", "project", "global"):
+        raise WizardError(
+            f"expected 'once' / 'project' / 'global', got: {value!r}"
+        )
+    state.pr_template_scope = value
+    return f"pr-template-scope: {value}"
+
+
+def _build_confirm(state: WizardState) -> Prompt:
+    return Prompt(
+        step=S_CONFIRM, kind="pick",
+        label="이대로 진행할까요?",
+        options=[_opt("proceed", "Proceed"), _opt("edit", "Edit")],
+        echo_template="confirm: {value}",
+    )
+
+
+def _submit_confirm(state: WizardState, value: str) -> Optional[str]:
+    if value not in ("proceed", "edit"):
+        raise WizardError(f"expected 'proceed' or 'edit', got: {value!r}")
+    state.confirmed = value == "proceed"
+    return f"confirm: {value}"
+
+
+def _build_edit_target(state: WizardState) -> Prompt:
+    # offer every step that has been answered.
+    options: list[Option] = []
+    for sid in state.answered:
+        if sid in (S_CONFIRM, S_EDIT_TARGET):
+            continue
+        options.append(_opt(sid, sid))
+    return Prompt(
+        step=S_EDIT_TARGET, kind="pick",
+        label="어느 step 으로 돌아갈까요?",
+        options=options,
+        echo_template="edit-target: {value}",
+    )
+
+
+def _submit_edit_target(state: WizardState, value: str) -> Optional[str]:
+    if not any(s.id == value for s in STEPS):
+        raise WizardError(f"unknown step: {value!r}")
+    state.edit_target = value
+    _reset_from(state, value)
+    state.confirmed = None
+    state.edit_target = ""
+    return f"edit-target: {value} (rewinding)"
+
+
+# --- step registry ---
+
+STEPS: list[Step] = [
+    Step(S_TASK_PICK,
+         applies=lambda s: s.is_new_task is None,
+         build=_build_task_pick, submit=_submit_task_pick,
+         owns=("is_new_task", "task_group", "task_id", "task_type",
+               "existing_brief_path", "profile_workers")),
+    Step(S_TASK_GROUP,
+         applies=lambda s: bool(s.is_new_task) and not s.task_group,
+         build=_build_task_group, submit=_submit_task_group,
+         owns=("task_group",)),
+    Step(S_TASK_ID,
+         applies=lambda s: bool(s.is_new_task) and bool(s.task_group) and not s.task_id,
+         build=_build_task_id, submit=_submit_task_id,
+         owns=("task_id",)),
+    Step(S_TASK_TYPE,
+         applies=lambda s: (s.is_new_task is not None
+                            and (s.is_new_task is False or bool(s.task_id))
+                            and S_TASK_TYPE not in s.answered),
+         build=_build_task_type, submit=_submit_task_type,
+         owns=("task_type", "profile_workers", "reuse_worktree")),
+    Step(S_BRIEF_KEEP,
+         applies=lambda s: (not s.is_new_task
+                            and bool(s.existing_brief_path)
+                            and s.keep_existing_brief is None
+                            and S_TASK_TYPE in s.answered),
+         build=_build_brief_keep, submit=_submit_brief_keep,
+         owns=("keep_existing_brief", "brief_path")),
+    Step(S_BRIEF_PATH,
+         applies=lambda s: (S_TASK_TYPE in s.answered
+                            and not s.brief_path
+                            and (s.is_new_task
+                                 or s.keep_existing_brief is False
+                                 or (not s.is_new_task and not s.existing_brief_path))),
+         build=_build_brief_path, submit=_submit_brief_path,
+         owns=("brief_path",)),
+    Step(S_BASE_REF_PICK,
+         applies=lambda s: (S_TASK_TYPE in s.answered
+                            and s.reuse_worktree is False
+                            and S_BASE_REF_PICK not in s.answered
+                            and bool(s.brief_path)),
+         build=_build_base_ref_pick, submit=_submit_base_ref_pick,
+         owns=("base_ref", "base_ref_pending_text")),
+    Step(S_BASE_REF_TEXT,
+         applies=lambda s: s.base_ref_pending_text,
+         build=_build_base_ref_text, submit=_submit_base_ref_text,
+         owns=("base_ref", "base_ref_pending_text")),
+    Step(S_APPROVED_PLAN,
+         applies=lambda s: (s.task_type == "implementation"
+                            and not s.approved_plan_path
+                            and bool(s.brief_path)
+                            and (s.reuse_worktree is True
+                                 or S_BASE_REF_PICK in s.answered)
+                            and not s.base_ref_pending_text),
+         build=_build_approved_plan, submit=_submit_approved_plan,
+         owns=("approved_plan_path",)),
+    Step(S_EXECUTOR,
+         applies=lambda s: (s.task_type == "implementation"
+                            and bool(s.approved_plan_path)
+                            and not s.executor),
+         build=_build_executor, submit=_submit_executor,
+         owns=("executor",)),
+    Step(S_DEFAULTS_OR_CUSTOM,
+         applies=lambda s: (_identity_ready(s)
+                            and s.use_defaults is None),
+         build=_build_defaults_or_custom, submit=_submit_defaults_or_custom,
+         owns=("use_defaults",)),
+    # Customize branch — workers override only when non-empty profile + not impl.
+    Step(S_WORKERS_OVERRIDE,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type != "implementation"
+                            and bool(s.profile_workers)
+                            and S_WORKERS_OVERRIDE not in s.answered),
+         build=_build_workers_override, submit=_submit_workers_override,
+         owns=("workers_override",)),
+    Step(S_LEAD_MODEL,
+         applies=lambda s: (s.use_defaults is False
+                            and S_LEAD_MODEL not in s.answered),
+         build=_build_lead_model, submit=_submit_lead_model,
+         owns=("lead_model",)),
+    Step(S_EXECUTOR_MODEL,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type == "implementation"
+                            and S_EXECUTOR_MODEL not in s.answered),
+         build=_build_executor_model, submit=_submit_executor_model,
+         owns=("claude_model", "codex_model", "gemini_model")),
+    Step(S_CLAUDE_MODEL,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type != "implementation"
+                            and "claude" in _resolved_roster(s)
+                            and S_CLAUDE_MODEL not in s.answered),
+         build=_build_claude_model, submit=_submit_claude_model,
+         owns=("claude_model",)),
+    Step(S_CODEX_MODEL,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type != "implementation"
+                            and "codex" in _resolved_roster(s)
+                            and S_CODEX_MODEL not in s.answered),
+         build=_build_codex_model, submit=_submit_codex_model,
+         owns=("codex_model",)),
+    Step(S_GEMINI_MODEL,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type != "implementation"
+                            and "gemini" in _resolved_roster(s)
+                            and S_GEMINI_MODEL not in s.answered),
+         build=_build_gemini_model, submit=_submit_gemini_model,
+         owns=("gemini_model",)),
+    Step(S_REPORT_WRITER_MODEL,
+         applies=lambda s: (s.use_defaults is False
+                            and (s.task_type == "implementation"
+                                 or "report-writer" in _resolved_roster(s))
+                            and S_REPORT_WRITER_MODEL not in s.answered),
+         build=_build_report_writer_model, submit=_submit_report_writer_model,
+         owns=("report_writer_model",)),
+    Step(S_DIRECTIVE,
+         applies=lambda s: (s.use_defaults is False
+                            and S_DIRECTIVE not in s.answered),
+         build=_build_directive, submit=_submit_directive,
+         owns=("directive",)),
+    Step(S_RELATED_TASKS,
+         applies=lambda s: (s.use_defaults is False
+                            and S_RELATED_TASKS not in s.answered),
+         build=_build_related_tasks, submit=_submit_related_tasks,
+         owns=("related_tasks_raw",)),
+    Step(S_CLARIFICATION,
+         applies=lambda s: (s.use_defaults is False
+                            and S_CLARIFICATION not in s.answered),
+         build=_build_clarification, submit=_submit_clarification,
+         owns=("clarification_response_path",)),
+    Step(S_PR_TEMPLATE,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type == "release-handoff"
+                            and S_PR_TEMPLATE not in s.answered),
+         build=_build_pr_template, submit=_submit_pr_template,
+         owns=("pr_template_path", "pr_template_scope")),
+    Step(S_PR_TEMPLATE_SCOPE,
+         applies=lambda s: (s.use_defaults is False
+                            and s.task_type == "release-handoff"
+                            and bool(s.pr_template_path)
+                            and S_PR_TEMPLATE_SCOPE not in s.answered),
+         build=_build_pr_template_scope, submit=_submit_pr_template_scope,
+         owns=("pr_template_scope",)),
+    Step(S_CONFIRM,
+         applies=lambda s: _ready_for_confirm(s) and s.confirmed is None,
+         build=_build_confirm, submit=_submit_confirm,
+         owns=("confirmed", "edit_target")),
+    Step(S_EDIT_TARGET,
+         applies=lambda s: s.confirmed is False and not s.edit_target,
+         build=_build_edit_target, submit=_submit_edit_target,
+         owns=()),
+]
+
+STEP_BY_ID = {s.id: s for s in STEPS}
+
+
+def _identity_ready(s: WizardState) -> bool:
+    """All identity questions (task pick → executor for impl) answered."""
+    if not s.task_type:
+        return False
+    if not s.brief_path:
+        return False
+    if s.reuse_worktree is False and S_BASE_REF_PICK not in s.answered:
+        return False
+    if s.base_ref_pending_text:
+        return False
+    if s.task_type == "implementation":
+        if not s.approved_plan_path or not s.executor:
+            return False
+    return True
+
+
+def _ready_for_confirm(s: WizardState) -> bool:
+    if s.use_defaults is None:
+        return False
+    if s.use_defaults:
+        return True
+    # customize: every customize-branch step must be answered or not-applicable.
+    custom_ids = [S_WORKERS_OVERRIDE, S_LEAD_MODEL, S_EXECUTOR_MODEL,
+                  S_CLAUDE_MODEL, S_CODEX_MODEL, S_GEMINI_MODEL,
+                  S_REPORT_WRITER_MODEL, S_DIRECTIVE, S_RELATED_TASKS,
+                  S_CLARIFICATION, S_PR_TEMPLATE, S_PR_TEMPLATE_SCOPE]
+    for sid in custom_ids:
+        step = STEP_BY_ID[sid]
+        if step.applies(s):
+            return False
+    return True
+
+
+def _reset_from(state: WizardState, target_step: str) -> None:
+    """Clear state owned by target_step and all later steps; remove their
+    entries from `answered`. Used when the user picks Edit."""
+    idx = next((i for i, s in enumerate(STEPS) if s.id == target_step), -1)
+    if idx < 0:
+        return
+    cleared_ids: set[str] = set()
+    for step in STEPS[idx:]:
+        cleared_ids.add(step.id)
+        for fname in step.owns:
+            _reset_field(state, fname)
+    state.answered = [a for a in state.answered if a not in cleared_ids]
+
+
+_FIELD_DEFAULTS: dict[str, Any] = {
+    "is_new_task": None, "task_group": "", "task_id": "",
+    "existing_brief_path": "", "task_type": "",
+    "profile_workers": [], "keep_existing_brief": None,
+    "brief_path": "", "reuse_worktree": None, "base_ref": "",
+    "base_ref_pending_text": False, "approved_plan_path": "",
+    "executor": "", "use_defaults": None, "workers_override": "",
+    "lead_model": "", "claude_model": "", "codex_model": "",
+    "gemini_model": "", "report_writer_model": "", "directive": "",
+    "related_tasks_raw": "", "clarification_response_path": "",
+    "pr_template_path": "", "pr_template_scope": "",
+    "confirmed": None, "edit_target": "",
+}
+
+
+def _reset_field(state: WizardState, fname: str) -> None:
+    if fname in _FIELD_DEFAULTS:
+        default = _FIELD_DEFAULTS[fname]
+        # copy mutable defaults
+        if isinstance(default, list):
+            setattr(state, fname, [])
+        else:
+            setattr(state, fname, default)
+
+
+# ---- Public API ---------------------------------------------------------
+
+def init_state(
+    *, workspace_root: str, project_root: str, project_id: str
+) -> WizardState:
+    """Bootstrap a new wizard state."""
+    return WizardState(
+        workspace_root=workspace_root,
+        project_root=project_root,
+        project_id=project_id,
+    )
+
+
+def next_prompt(state: WizardState) -> Prompt:
+    if state.confirmed:
+        return Prompt(step=S_DONE, kind="done")
+    for step in STEPS:
+        if step.id in state.answered:
+            continue
+        if step.applies(state):
+            return step.build(state)
+    return Prompt(step=S_DONE, kind="done")
+
+
+def submit(state: WizardState, value: str) -> dict[str, Any]:
+    """Validate the answer for the *currently active* step and advance.
+
+    Returns {"echo": "...", "next": <Prompt JSON>}. Raises WizardError on
+    validation failure (caller may re-prompt).
+    """
+    prompt = next_prompt(state)
+    if prompt.kind == "done":
+        return {"echo": "", "next": prompt.to_json()}
+    step = STEP_BY_ID[prompt.step]
+    echo = step.submit(state, value or "")
+    if prompt.step not in state.answered:
+        state.answered.append(prompt.step)
+    nxt = next_prompt(state)
+    return {"echo": echo or "", "next": nxt.to_json()}
+
+
+def render_args(state: WizardState) -> dict[str, str]:
+    """Convert finalized state into ``okstra render-bundle`` argument map."""
+    workers = state.workers_override.strip()
+    if state.task_type == "implementation":
+        workers = ""  # profile-default roster is mandatory for impl
+    base_ref = "" if state.reuse_worktree else state.base_ref
+    pr_template = (
+        state.pr_template_path
+        if state.task_type == "release-handoff"
+        else ""
+    )
+    return {
+        "project-root": state.project_root,
+        "project-id": state.project_id,
+        "task-group": state.task_group,
+        "task-id": state.task_id,
+        "task-type": state.task_type,
+        "task-brief": state.brief_path,
+        "executor": state.executor,
+        "approved-plan": state.approved_plan_path,
+        "base-ref": base_ref,
+        "workers": workers,
+        "directive": state.directive,
+        "lead-model": state.lead_model,
+        "claude-model": state.claude_model,
+        "codex-model": state.codex_model,
+        "gemini-model": state.gemini_model,
+        "report-writer-model": state.report_writer_model,
+        "related-tasks": state.related_tasks_raw,
+        "clarification-response": state.clarification_response_path,
+        "pr-template-path": pr_template,
+    }
+
+
+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}")
+    lines.append(f"  task-key      : {state.task_group}/{state.task_id}")
+    if state.reuse_worktree:
+        lines.append("  base-ref      : (reusing existing worktree)")
+    else:
+        lines.append(f"  base-ref      : {state.base_ref}")
+    if state.task_type == "implementation":
+        lines.append(f"  executor      : {state.executor or '(default)'}")
+        lines.append(
+            f"  workers       : (프로필 기본 — executor + verifier 2 + report-writer)"
+        )
+    else:
+        roster = state.workers_override or ",".join(state.profile_workers) or "(profile default)"
+        lines.append(f"  workers       : {roster}")
+    lines.append(f"  lead-model    : {state.lead_model or 'default'}")
+    if state.claude_model:
+        lines.append(f"  claude-model  : {state.claude_model}")
+    if state.codex_model:
+        lines.append(f"  codex-model   : {state.codex_model}")
+    if state.gemini_model:
+        lines.append(f"  gemini-model  : {state.gemini_model}")
+    if state.report_writer_model:
+        lines.append(f"  report-writer : {state.report_writer_model}")
+    lines.append(f"  directive     : {state.directive or '(none)'}")
+    if state.task_type == "implementation":
+        lines.append(f"  approved-plan : {state.approved_plan_path}")
+    if state.clarification_response_path:
+        lines.append(f"  clarification : {state.clarification_response_path}")
+    if state.task_type == "release-handoff" and state.pr_template_path:
+        lines.append(f"  pr-template   : {state.pr_template_path} ({state.pr_template_scope or 'once'})")
+    return "\n".join(lines)
+
+
+# ---- File I/O helpers (used by CLI) -------------------------------------
+
+def load_state_file(path: Path) -> WizardState:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    return WizardState.from_json(data)
+
+
+def save_state_file(path: Path, state: WizardState) -> None:
+    Path(path).write_text(
+        json.dumps(state.to_json(), indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+
+
+# ---- CLI entrypoint -----------------------------------------------------
+
+def _cli(argv: list[str]) -> int:
+    """``python3 -m okstra_ctl.wizard <subcmd>`` driver.
+
+    Subcommands:
+      init  --state-file PATH --workspace-root P --project-root P --project-id ID
+      step  --state-file PATH [--answer VALUE]
+      render-args --state-file PATH
+      confirmation --state-file PATH
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="okstra_ctl.wizard")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init")
+    p_init.add_argument("--state-file", required=True)
+    p_init.add_argument("--workspace-root", required=True)
+    p_init.add_argument("--project-root", required=True)
+    p_init.add_argument("--project-id", required=True)
+
+    p_step = sub.add_parser("step")
+    p_step.add_argument("--state-file", required=True)
+    p_step.add_argument("--answer", default=None)
+
+    p_render = sub.add_parser("render-args")
+    p_render.add_argument("--state-file", required=True)
+
+    p_conf = sub.add_parser("confirmation")
+    p_conf.add_argument("--state-file", required=True)
+
+    args = parser.parse_args(argv)
+    state_path = Path(args.state_file)
+
+    if args.cmd == "init":
+        state = init_state(
+            workspace_root=args.workspace_root,
+            project_root=args.project_root,
+            project_id=args.project_id,
+        )
+        save_state_file(state_path, state)
+        first = next_prompt(state)
+        print(json.dumps({"ok": True, "next": first.to_json()},
+                         ensure_ascii=False, indent=2))
+        return 0
+
+    if args.cmd == "step":
+        state = load_state_file(state_path)
+        try:
+            if args.answer is None:
+                result = {"echo": "", "next": next_prompt(state).to_json()}
+            else:
+                result = submit(state, args.answer)
+        except WizardError as exc:
+            save_state_file(state_path, state)
+            print(json.dumps({"ok": False, "error": str(exc),
+                              "current": next_prompt(state).to_json()},
+                             ensure_ascii=False, indent=2))
+            return 0
+        save_state_file(state_path, state)
+        print(json.dumps({"ok": True, **result}, ensure_ascii=False, indent=2))
+        return 0
+
+    if args.cmd == "render-args":
+        state = load_state_file(state_path)
+        print(json.dumps({"ok": True, "args": render_args(state)},
+                         ensure_ascii=False, indent=2))
+        return 0
+
+    if args.cmd == "confirmation":
+        state = load_state_file(state_path)
+        print(json.dumps({"ok": True, "text": confirmation_block(state)},
+                         ensure_ascii=False, indent=2))
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    import sys
+    raise SystemExit(_cli(sys.argv[1:]))