okstra 0.91.1 → 0.92.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.91.1",
+  "version": "0.92.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.91.1",
-  "builtAt": "2026-06-18T06:51:56.885Z",
+  "package": "0.92.1",
+  "builtAt": "2026-06-18T08:35:38.504Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/wizard/prompts.ko.json

@@ -358,7 +358,7 @@
       }
     },
     "defaults_or_custom": {
-      "label": "역할별 모델·실행 옵션 단계입니다 (참여 워커 구성을 바꾸는 게 아닙니다).\n이번 run 의 워커: {workers}\n· 기본값으로 진행 — 모든 역할을 추천 모델로 둡니다. 추천 기본값: lead·report-writer=opus, claude=opus, codex=gpt-5.5, antigravity=auto (실제 값은 runtime 기본값으로 해소). directive·관련 task 없이 바로 진행.\n· 커스터마이즈 — 역할별 모델을 직접 고르고, 추가 directive·관련 task 도 지정합니다.",
+      "label": "역할별 모델 선택 단계입니다 (참여 워커 구성을 바꾸는 게 아닙니다).\n이번 run 에서 모델을 고를 역할:\n{role_models}\n· 기본값으로 진행 — 위 추천 모델을 그대로 쓰고, directive·관련 task 없이 바로 넘어갑니다.\n· 커스터마이즈 — 위 역할별 모델을 직접 고르고, 추가 directive·관련 task 도 지정합니다.\n(추천 값은 runtime 기본값으로 해소됩니다. 분석에 참여하지 않는 역할은 위 목록에 나오지 않습니다 — 예: antigravity 는 implementation 의 executor 로 선택했을 때만 표시됩니다.)",
       "echo_template": "customize: {value}",
       "options": {
         "defaults": "기본값으로 진행 (역할별 추천 모델 그대로)",

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -0,0 +1,217 @@
+"""Implementation stage run orchestration.
+
+This module owns the lifecycle for one ``implementation`` stage run: recover
+consumer state, select an available Stage Map entry, provision the isolated
+stage worktree, and publish the selected stage into run context.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import stage_targets
+from .stage_reconcile import auto_reconcile_best_effort
+
+
+class ImplementationStageError(Exception):
+    """Implementation stage selection or provisioning failed."""
+
+
+@dataclass
+class StageSelection:
+    """Resolved implementation stage and its isolated worktree coordinates."""
+
+    stage: int
+    worktree_path: str
+    worktree_branch: str
+    worktree_base_ref: str
+    worktree_status: str
+    worktree_note: str
+    started_head_commit: str
+    concurrent_stages: list[int] = field(default_factory=list)
+
+
+def _git_out(cwd: str | Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(cwd), *args],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
+    if isinstance(exc, ImplementationStageError):
+        return exc
+    return ImplementationStageError(str(exc))
+
+
+def select_and_provision_implementation_stage(
+    inp: Any,
+    ctx_stage_map: list[dict[str, Any]],
+    task_group_segment: str,
+    task_id_segment: str,
+    task_key: str,
+    executor_worktree_status: str,
+) -> StageSelection:
+    """Select a ready implementation stage and provision its stage worktree.
+
+    The returned selection is path-independent with respect to run artifacts:
+    callers can compute stage-specific run paths after this function resolves
+    the selected stage.
+    """
+    del task_key  # The registry uses the split identity fields.
+
+    from .consumers import read_consumers, backfill_done_from_carry
+    from . import worktree as _worktree
+    from . import worktree_registry as _reg
+
+    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    backfill_done_from_carry(plan_run_root)
+    auto_reconcile_best_effort(inp, plan_run_root)
+    consumed = read_consumers(plan_run_root)
+    done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
+    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
+    reserved_stages = _reg.list_active_stage_numbers(
+        inp.project_id,
+        inp.task_group,
+        inp.task_id,
+    )
+
+    try:
+        batch = stage_targets.resolve_effective_stages(
+            ctx_stage_map,
+            done_stages,
+            inp.stage,
+            started_stages=started_stages,
+            reserved_stages=reserved_stages,
+        )
+    except stage_targets.StageTargetError as exc:
+        raise _as_implementation_stage_error(exc) from exc
+
+    selected = batch[0]
+    concurrent_stages = sorted(reserved_stages - done_stages - {selected})
+
+    if executor_worktree_status.startswith("skipped"):
+        head = _git_out(inp.project_root, "rev-parse", "HEAD")
+        return StageSelection(
+            stage=selected,
+            worktree_path="",
+            worktree_branch="",
+            worktree_base_ref="",
+            worktree_status=executor_worktree_status,
+            worktree_note="",
+            started_head_commit=head,
+            concurrent_stages=concurrent_stages,
+        )
+
+    head_sha = _git_out(inp.project_root, "rev-parse", "HEAD")
+    if head_sha:
+        _reg.set_implementation_base(
+            inp.project_id,
+            inp.task_group,
+            inp.task_id,
+            head_sha,
+        )
+    anchor = _reg.get_implementation_base(
+        inp.project_id,
+        inp.task_group,
+        inp.task_id,
+    ) or ""
+
+    selected_stage = next(
+        s for s in ctx_stage_map if s["stage_number"] == selected
+    )
+    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
+    try:
+        stage_base = stage_targets.resolve_stage_base_commit(
+            selected_stage,
+            consumer_done_rows,
+            anchor_base_commit=anchor,
+            candidate_base=head_sha,
+            project_root=Path(inp.project_root),
+            plan_run_root=plan_run_root,
+        )
+    except stage_targets.StageTargetError as exc:
+        raise _as_implementation_stage_error(exc) from exc
+
+    try:
+        prov = _worktree.provision_stage_worktree(
+            project_root=Path(inp.project_root),
+            project_id=inp.project_id,
+            task_group_segment=task_group_segment,
+            task_id_segment=task_id_segment,
+            work_category=inp.work_category,
+            stage_number=selected,
+            base_commit=stage_base,
+        )
+    except RuntimeError as exc:
+        from .git_reconcile import guidance
+
+        hint = guidance(
+            plan_run_root=plan_run_root,
+            project_id=inp.project_id,
+            task_group=inp.task_group,
+            task_id=inp.task_id,
+            work_category=inp.work_category,
+        )
+        raise ImplementationStageError(
+            f"stage worktree provisioning failed: {exc}\n{hint}"
+        ) from exc
+
+    return StageSelection(
+        stage=selected,
+        worktree_path=prov.path,
+        worktree_branch=prov.branch,
+        worktree_base_ref=prov.base_ref,
+        worktree_status=prov.status,
+        worktree_note=prov.note,
+        started_head_commit=prov.base_ref,
+        concurrent_stages=concurrent_stages,
+    )
+
+
+def apply_implementation_stage(
+    inp: Any,
+    ctx: dict[str, Any],
+    ctx_stage_map: list[dict[str, Any]],
+    sel: StageSelection,
+) -> None:
+    """Publish a selected stage into run context and ``consumers.jsonl``."""
+    from .consumers import append_consumer
+
+    ctx["parsed_stage_map"] = ctx_stage_map
+    ctx["effective_stages"] = [sel.stage]
+    csv = str(sel.stage)
+    ctx["EFFECTIVE_STAGES"] = csv
+    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
+    ctx["STAGE_BATCH_DIRECTIVE"] = (
+        f"- **Stage for this implementation run:** `{csv}`. "
+        "Execute exactly this Stage Map stage — this is the authoritative scope. "
+        "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
+        "and reserved this stage."
+    )
+    inp.stage = csv
+    print(f"selected stages: {csv}", file=sys.stdout)
+
+    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
+        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
+        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
+        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
+
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    append_consumer(
+        plan_run_root,
+        impl_task_key=ctx["TASK_KEY"],
+        stage=sel.stage,
+        status="started",
+        started_at=now,
+        head_commit=sel.started_head_commit,
+    )

package/runtime/python/okstra_ctl/run.py

@@ -89,6 +89,11 @@ from .workers import (
 )
 from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
+from . import stage_targets as _stage_targets
+from . import implementation_stage as _implementation_stage
+from .stage_reconcile import (
+    auto_reconcile_best_effort as _stage_auto_reconcile_best_effort,
+)
 from .worktree import (
     WorktreeProvision,
     okstra_clean_gate_excludes,
@@ -418,7 +423,12 @@ def _validate_stage_structure(plan_path: str) -> None:
         )
 
 
-RUN_STEP_BUDGET = 8
+RUN_STEP_BUDGET = _stage_targets.RUN_STEP_BUDGET
+_FVTarget = _stage_targets.FinalVerificationTarget
+
+
+def _stage_target_prepare_error(exc: _stage_targets.StageTargetError) -> PrepareError:
+    return PrepareError(str(exc))
 
 
 def _resolve_effective_stages(
@@ -429,98 +439,40 @@ def _resolve_effective_stages(
     started_stages: set = None,
     reserved_stages: set = None,
 ) -> list:
-    """Return the ordered list of stage numbers this run executes.
-
-    `requested` is "auto" or a decimal string. For "auto" the run batches all
-    ready stages (depends-on all done, itself neither done nor occupied) in
-    stage-number order up to `budget` effective steps. A numeric request is a
-    single forced stage. `started_stages`/`reserved_stages` are stages a
-    concurrent run already holds (consumers.jsonl `started` and the registry
-    stage reservations); they are excluded so two simultaneous runs never pick
-    the same stage. Raises PrepareError on rejection cases."""
-    started_stages = started_stages or set()
-    reserved_stages = reserved_stages or set()
-    occupied = done_stages | started_stages | reserved_stages
-    if requested != "auto":
-        try:
-            n = int(requested)
-        except ValueError:
-            raise PrepareError(
-                f"--stage must be 'auto' or an integer, got {requested!r}"
-            )
-        target = next((s for s in stages if s["stage_number"] == n), None)
-        if target is None:
-            raise PrepareError(
-                f"--stage {n} not in Stage Map "
-                f"(have {[s['stage_number'] for s in stages]})"
-            )
-        if n in done_stages:
-            raise PrepareError(
-                f"--stage {n} already completed (consumers.jsonl status:done exists)"
-            )
-        if n in started_stages or n in reserved_stages:
-            raise PrepareError(
-                f"--stage {n} already in progress or reserved by another run"
-            )
-        return [n]
-
-    ready = [
-        s for s in stages
-        if s["stage_number"] not in occupied
-        and all(d in done_stages for d in s["depends_on"])
-    ]
-    if not ready:
-        raise PrepareError(
-            "no stage is ready: every remaining stage has unsatisfied depends-on"
+    """Compatibility wrapper for the public stage-target policy module."""
+    try:
+        return _stage_targets.resolve_effective_stages(
+            stages,
+            done_stages,
+            requested,
+            budget=budget,
+            started_stages=started_stages,
+            reserved_stages=reserved_stages,
         )
-    batch: list = []
-    total = 0
-    for s in ready:
-        sc = s.get("step_count", 0) or 0
-        if batch and total + sc > budget:
-            break
-        batch.append(s["stage_number"])
-        total += sc
-    return batch
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _commit_is_ancestor(project_root, ancestor: str, descendant: str) -> bool:
-    """True iff `ancestor` is an ancestor of `descendant` in project_root's git
-    history (`git merge-base --is-ancestor`, exit 0). Used to detect whether a
-    predecessor stage's done commit has been merged into the task worktree HEAD."""
-    r = _subprocess.run(
-        ["git", "merge-base", "--is-ancestor", ancestor, descendant],
-        cwd=str(project_root), capture_output=True, text=True,
-    )
-    return r.returncode == 0
+    """Compatibility wrapper for tests and older internal callers."""
+    return _stage_targets.commit_is_ancestor(project_root, ancestor, descendant)
 
 
 def _check_multi_dep_merged(project_root, plan_run_root, latest,
                             pred_commits: dict, candidate_base: str,
                             stage_n: int) -> None:
-    """모든 선행 done commit 이 candidate 에 (내용 기준으로라도) 머지됐는지
-    검증. patch-equivalent 면 보정 row 를 자동 기록(다음 run 은 ancestor 로
-    바로 통과). 아니면 회복 안내를 담아 PrepareError."""
-    from .git_reconcile import content_merged, _record_reconciled
-    for d, head in pred_commits.items():
-        if _commit_is_ancestor(project_root, head, candidate_base):
-            continue
-        match = content_merged(project_root, head, candidate_base)
-        if match.status in ("ancestor", "patch-equivalent"):
-            if plan_run_root is not None:
-                _record_reconciled(
-                    plan_run_root,
-                    impl_task_key=(latest.get(d) or {}).get("impl_task_key", ""),
-                    stage=d, new_commit=match.matched_commit,
-                    replaced=head, reason="auto-patch-id")
-            continue
-        raise PrepareError(
-            f"multi-dependency stage {stage_n}: predecessor stage {d} "
-            f"({head[:8]}) is not merged into the task worktree "
-            f"({candidate_base[:8]}). Merge stage branches "
-            f"(e.g. the `-s{d}` branches) into the task worktree "
-            "(or into main, then refresh the worktree) and retry."
+    """Compatibility wrapper for the stage-target dependency gate."""
+    try:
+        _stage_targets.check_multi_dep_merged(
+            project_root,
+            plan_run_root,
+            latest,
+            pred_commits,
+            candidate_base,
+            stage_n,
         )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _resolve_stage_base_commit(
@@ -531,70 +483,18 @@ def _resolve_stage_base_commit(
     project_root=None,
     plan_run_root=None,
 ) -> str:
-    """Pick the git base commit a stage's isolated worktree branches from.
-
-    - 독립 (`depends-on (none)`): anchor (= implementation_base_commit fixed
-      at first stage entry).
-    - 단일 의존 (`depends-on X`): predecessor X 의 `done.head_commit`.
-    - 다중 의존 (`depends-on X,Y…`): spec §9 옵션 A 자동 감지. candidate_base
-      (= task-key worktree HEAD) 에 모든 선행 done commit 이 ancestor 면
-      candidate 를 반환(사용자가 선행을 머지함). 아니면 PrepareError.
-
-    Raises PrepareError on missing predecessor / anchor / unmerged predecessor."""
-    from .consumers import latest_done_by_stage
-    latest = latest_done_by_stage(consumer_done_rows)
-    deps = stage.get("depends_on") or []
-    if len(deps) >= 2:
-        n = stage["stage_number"]
-        # 1) 모든 선행의 done head_commit 수집
-        pred_commits = {}
-        for d in deps:
-            head = (latest.get(d) or {}).get("head_commit")
-            if not head:
-                raise PrepareError(
-                    f"predecessor stage {d} has no done row with head_commit "
-                    f"in consumers.jsonl; multi-dependency stage {n} cannot start"
-                )
-            pred_commits[d] = head
-        # 2) candidate (task-key worktree HEAD) 필요
-        if not candidate_base or project_root is None:
-            raise PrepareError(
-                f"candidate base missing for multi-dependency stage {n}; "
-                "task-key worktree HEAD could not be resolved"
-            )
-        # 3) 모든 선행 done 이 candidate 에 (ancestor 또는 patch-equivalent 로)
-        #    머지됐는지 — patch-equivalent 면 보정 row 를 자동 기록한다.
-        _check_multi_dep_merged(project_root, plan_run_root, latest,
-                                pred_commits, candidate_base, n)
-        return candidate_base
-    if not deps:
-        if not anchor_base_commit:
-            raise PrepareError(
-                f"anchor base commit missing for independent stage "
-                f"{stage['stage_number']}; first-stage prepare should have "
-                "fixed it via worktree_registry.set_implementation_base"
-            )
-        return anchor_base_commit
-    # 단일 의존
-    pred = deps[0]
-    head = (latest.get(pred) or {}).get("head_commit") or ""
-    if head:
-        return head
-    raise PrepareError(
-        f"predecessor stage {pred} has no done row with head_commit in "
-        "consumers.jsonl; cannot derive base for stage "
-        f"{stage['stage_number']}"
-    )
-
-
-@dataclass
-class _FVTarget:
-    scope: str            # "whole-task" | "single-stage"
-    base: str
-    head: str
-    worktree_path: str
-    stages: list          # list[int]
-    reports: list         # list[str], report_path 값(없으면 "")
+    """Compatibility wrapper for stage worktree base selection."""
+    try:
+        return _stage_targets.resolve_stage_base_commit(
+            stage,
+            consumer_done_rows,
+            anchor_base_commit,
+            candidate_base=candidate_base,
+            project_root=project_root,
+            plan_run_root=plan_run_root,
+        )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _resolve_whole_task_target(
@@ -602,66 +502,37 @@ def _resolve_whole_task_target(
     task_worktree_path: str, task_head: str, task_dirty: bool,
     merged: dict,
 ) -> "_FVTarget":
-    """전체-task 검증 target. 모든 Stage Map stage 가 done + HEAD 에 머지 +
-    worktree clean 이어야 한다. 위반 시 PrepareError."""
-    from .consumers import latest_done_by_stage
-    done_by_stage = latest_done_by_stage(done_rows)
-    for s in stage_map:
-        n = s["stage_number"]
-        if n not in done_by_stage:
-            raise PrepareError(
-                f"final-verification(whole-task): stage {n} not done — "
-                f"run implementation --stage {n} first"
-            )
-        if not merged.get(n, False):
-            sha = done_by_stage[n].get("head_commit", "")
-            raise PrepareError(
-                f"final-verification(whole-task): stage {n} done commit "
-                f"{sha} not merged into task worktree HEAD — merge stage "
-                "branches then retry"
-            )
-    if task_dirty:
-        raise PrepareError(
-            "final-verification: worktree has uncommitted source changes "
-            "(outside .okstra/) — commit or stash before verifying"
+    """Compatibility wrapper for whole-task verification target selection."""
+    try:
+        return _stage_targets.resolve_whole_task_target(
+            stage_map=stage_map,
+            done_rows=done_rows,
+            anchor_base=anchor_base,
+            task_worktree_path=task_worktree_path,
+            task_head=task_head,
+            task_dirty=task_dirty,
+            merged=merged,
         )
-    stages = [s["stage_number"] for s in stage_map]
-    reports = [done_by_stage[n].get("report_path", "") for n in stages]
-    return _FVTarget(
-        scope="whole-task", base=anchor_base, head=task_head,
-        worktree_path=task_worktree_path, stages=stages, reports=reports,
-    )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _resolve_single_stage_target(
     *, requested_stage: str, done_rows: list, stage_base: str,
     stage_worktree_path: str, stage_head: str, stage_dirty: bool,
 ) -> "_FVTarget":
-    """단독-stage 검증 target. stage N 만 done + stage worktree 존재 + clean.
-    다른 stage 의 done/머지 여부와 무관. 위반 시 PrepareError."""
-    from .consumers import latest_done_by_stage
-    n = int(requested_stage)
-    done_by_stage = latest_done_by_stage(done_rows)
-    if n not in done_by_stage:
-        raise PrepareError(
-            f"final-verification(single-stage): stage {n} not done — "
-            f"run implementation --stage {n} first"
-        )
-    if not stage_worktree_path:
-        raise PrepareError(
-            f"final-verification(single-stage): stage worktree not found for "
-            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
-        )
-    if stage_dirty:
-        raise PrepareError(
-            "final-verification: worktree has uncommitted source changes "
-            "(outside .okstra/) — commit or stash before verifying"
+    """Compatibility wrapper for single-stage verification target selection."""
+    try:
+        return _stage_targets.resolve_single_stage_target(
+            requested_stage=requested_stage,
+            done_rows=done_rows,
+            stage_base=stage_base,
+            stage_worktree_path=stage_worktree_path,
+            stage_head=stage_head,
+            stage_dirty=stage_dirty,
         )
-    return _FVTarget(
-        scope="single-stage", base=stage_base, head=stage_head,
-        worktree_path=stage_worktree_path, stages=[n],
-        reports=[done_by_stage[n].get("report_path", "")],
-    )
+    except _stage_targets.StageTargetError as exc:
+        raise _stage_target_prepare_error(exc) from exc
 
 
 def _parse_stage_map_into_ctx(plan_path: str) -> list:
@@ -1444,33 +1315,42 @@ class _ModelBindings:
     executor_model_meta: ModelAssignment
 
 
+def recommended_role_models() -> dict[str, str]:
+    """역할 → 추천 모델 display 값 (env override 반영). prepare 의 모델 해소와
+    wizard 의 안내 표기가 공유하는 단일 기준점."""
+    lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus")
+    return {
+        "lead": lead_default,
+        "claude": _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "opus"),
+        "codex": _default("OKSTRA_DEFAULT_CODEX_MODEL", "gpt-5.5"),
+        "antigravity": _default("OKSTRA_DEFAULT_ANTIGRAVITY_MODEL", "auto"),
+        "report-writer": _default("OKSTRA_DEFAULT_REPORT_WRITER_MODEL", lead_default),
+    }
+
+
 def _resolve_worker_models(inp: PrepareInputs) -> dict:
     """lead/claude/codex/antigravity/report-writer 모델을 alias → (display, execution) 로 해소."""
-    lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus")
-    claude_default = _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "opus")
-    codex_default = _default("OKSTRA_DEFAULT_CODEX_MODEL", "gpt-5.5")
-    antigravity_default = _default("OKSTRA_DEFAULT_ANTIGRAVITY_MODEL", "auto")
-    report_writer_default = _default("OKSTRA_DEFAULT_REPORT_WRITER_MODEL", lead_default)
+    rec = recommended_role_models()
     return {
         "lead": resolve_model_metadata(
             provider="claude", raw_value=inp.lead_model,
-            default_display=lead_default, default_execution=lead_default,
+            default_display=rec["lead"], default_execution=rec["lead"],
         ),
         "cw": resolve_model_metadata(
             provider="claude", raw_value=inp.claude_model,
-            default_display=claude_default, default_execution=claude_default,
+            default_display=rec["claude"], default_execution=rec["claude"],
         ),
         "co": resolve_model_metadata(
             provider="codex", raw_value=inp.codex_model,
-            default_display=codex_default, default_execution=codex_default,
+            default_display=rec["codex"], default_execution=rec["codex"],
         ),
         "ge": resolve_model_metadata(
             provider="antigravity", raw_value=inp.antigravity_model,
-            default_display=antigravity_default, default_execution=antigravity_default,
+            default_display=rec["antigravity"], default_execution=rec["antigravity"],
         ),
         "rw": resolve_model_metadata(
             provider="claude", raw_value=inp.report_writer_model,
-            default_display=report_writer_default, default_execution=report_writer_default,
+            default_display=rec["report-writer"], default_execution=rec["report-writer"],
         ),
     }
 
@@ -1511,23 +1391,13 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
     )
 
 
-@dataclass
-class StageSelection:
-    """Result of `_select_and_provision_implementation_stage`.
-
-    Path-independent: carries the chosen stage + its isolated worktree
-    coordinates, separated from any run-artifact path so the caller can
-    resolve run paths AFTER the stage is known. `worktree_*` are empty when
-    the surrounding flow degraded (non-git / nested worktree); in that case
-    `started_head_commit` is the project HEAD instead of the worktree base."""
-    stage: int
-    worktree_path: str
-    worktree_branch: str
-    worktree_base_ref: str
-    worktree_status: str
-    worktree_note: str
-    started_head_commit: str
-    concurrent_stages: list = field(default_factory=list)
+StageSelection = _implementation_stage.StageSelection
+
+
+def _implementation_stage_prepare_error(
+    exc: _implementation_stage.ImplementationStageError,
+) -> PrepareError:
+    return PrepareError(str(exc))
 
 
 def _select_and_provision_implementation_stage(
@@ -1538,102 +1408,18 @@ def _select_and_provision_implementation_stage(
     task_key: str,
     executor_worktree_status: str,
 ) -> StageSelection:
-    """Resolve the first ready implementation stage and provision its isolated
-    worktree, without touching any run-artifact path.
-
-    spec §2.3: 한 run = 한 stage. `_resolve_effective_stages` 가 backward compat
-    로 batch 를 반환하지만 첫 번째만 실행한다 — stage 마다 격리 worktree·branch
-    가 필요해 batch 가 의미를 잃기 때문. `executor_worktree_status` 가
-    "skipped*" 면 worktree 없이 degrade 하고 project HEAD 만 기록한다."""
-    from .consumers import read_consumers, backfill_done_from_carry
-    from . import worktree as _worktree
-    from . import worktree_registry as _reg
-
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    # carry sidecars are the SSOT for stage completion; recover any `done` rows
-    # the lead failed to append before the dependency gate reads them.
-    backfill_done_from_carry(plan_run_root)
-    _auto_reconcile_best_effort(inp, plan_run_root)
-    consumed = read_consumers(plan_run_root)
-    done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
-    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
-    reserved_stages = _reg.list_active_stage_numbers(
-        inp.project_id, inp.task_group, inp.task_id,
-    )
-
-    batch = _resolve_effective_stages(
-        ctx_stage_map, done_stages, inp.stage,
-        started_stages=started_stages, reserved_stages=reserved_stages,
-    )
-    selected = batch[0]
-    # done stage 는 동시 run 이 아니다 — done 기록 시 점유는 해제되지만
-    # (consumers._release_stage_reservation), crash·구버전 기록의 잔존
-    # 예약이 남을 수 있어 읽기에서도 차감한다.
-    concurrent_stages = sorted(reserved_stages - done_stages - {selected})
-
-    # spec §2.1 degradation: 주변 흐름이 non-git / nested-worktree 로 skipped 면
-    # stage 격리도 동일하게 degrade — worktree 없이 project HEAD 만 기록.
-    if executor_worktree_status.startswith("skipped"):
-        head = _git_out(inp.project_root, "rev-parse", "HEAD")
-        return StageSelection(
-            stage=selected,
-            worktree_path="",
-            worktree_branch="",
-            worktree_base_ref="",
-            worktree_status=executor_worktree_status,
-            worktree_note="",
-            started_head_commit=head,
-            concurrent_stages=concurrent_stages,
-        )
-
-    # anchor base commit 1회 고정 (task-key worktree HEAD 기준)
-    head_sha = _git_out(inp.project_root, "rev-parse", "HEAD")
-    if head_sha:
-        _reg.set_implementation_base(
-            inp.project_id, inp.task_group, inp.task_id, head_sha,
-        )
-    anchor = _reg.get_implementation_base(
-        inp.project_id, inp.task_group, inp.task_id,
-    ) or ""
-
-    # stage 격리 worktree 발급 — 의존 종류별 base 결정
-    selected_stage = next(
-        s for s in ctx_stage_map if s["stage_number"] == selected
-    )
-    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
-    stage_base = _resolve_stage_base_commit(
-        selected_stage, consumer_done_rows, anchor_base_commit=anchor,
-        candidate_base=head_sha, project_root=Path(inp.project_root),
-        plan_run_root=plan_run_root,
-    )
+    """Compatibility wrapper for implementation stage selection."""
     try:
-        prov = _worktree.provision_stage_worktree(
-            project_root=Path(inp.project_root),
-            project_id=inp.project_id,
-            task_group_segment=task_group_segment,
-            task_id_segment=task_id_segment,
-            work_category=inp.work_category,
-            stage_number=selected,
-            base_commit=stage_base,
+        return _implementation_stage.select_and_provision_implementation_stage(
+            inp,
+            ctx_stage_map,
+            task_group_segment,
+            task_id_segment,
+            task_key,
+            executor_worktree_status,
         )
-    except RuntimeError as exc:
-        from .git_reconcile import guidance
-        hint = guidance(plan_run_root=plan_run_root, project_id=inp.project_id,
-                        task_group=inp.task_group, task_id=inp.task_id,
-                        work_category=inp.work_category)
-        raise PrepareError(
-            f"stage worktree provisioning failed: {exc}\n{hint}") from exc
-
-    return StageSelection(
-        stage=selected,
-        worktree_path=prov.path,
-        worktree_branch=prov.branch,
-        worktree_base_ref=prov.base_ref,
-        worktree_status=prov.status,
-        worktree_note=prov.note,
-        started_head_commit=prov.base_ref,
-        concurrent_stages=concurrent_stages,
-    )
+    except _implementation_stage.ImplementationStageError as exc:
+        raise _implementation_stage_prepare_error(exc) from exc
 
 
 def _apply_implementation_stage(
@@ -1642,44 +1428,8 @@ def _apply_implementation_stage(
     ctx_stage_map: list,
     sel: StageSelection,
 ) -> None:
-    """Wire a resolved `StageSelection` into ctx + consumers.jsonl. ctx-dependent
-    counterpart to `_select_and_provision_implementation_stage`."""
-    from .consumers import append_consumer
-    import datetime as _dt
-
-    ctx["parsed_stage_map"] = ctx_stage_map
-    ctx["effective_stages"] = [sel.stage]
-    csv = str(sel.stage)
-    ctx["EFFECTIVE_STAGES"] = csv
-    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
-    ctx["STAGE_BATCH_DIRECTIVE"] = (
-        f"- **Stage for this implementation run:** `{csv}`. "
-        "Execute exactly this Stage Map stage — this is the authoritative scope. "
-        "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
-        "and reserved this stage."
-    )
-    inp.stage = csv
-    # Observable contract: callers (okstra.sh, e2e harness) scan stdout for the
-    # resolved stage. Keep this line — it is the run's stage-selection receipt.
-    print(f"selected stages: {csv}", file=sys.stdout)
-
-    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
-        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
-        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
-        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
-
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    append_consumer(
-        plan_run_root,
-        impl_task_key=ctx["TASK_KEY"],
-        stage=sel.stage,
-        status="started",
-        started_at=now,
-        head_commit=sel.started_head_commit,
-    )
+    """Compatibility wrapper for publishing implementation stage selection."""
+    _implementation_stage.apply_implementation_stage(inp, ctx, ctx_stage_map, sel)
 
 
 def _git_out(cwd, *args) -> str:
@@ -1689,17 +1439,7 @@ def _git_out(cwd, *args) -> str:
 
 
 def _auto_reconcile_best_effort(inp: "PrepareInputs", plan_run_root: Path) -> None:
-    try:
-        from .git_reconcile import auto_reconcile
-        for it in auto_reconcile(
-                project_root=Path(inp.project_root), plan_run_root=plan_run_root,
-                project_id=inp.project_id, task_group=inp.task_group,
-                task_id=inp.task_id, work_category=inp.work_category):
-            print(f"git-reconcile: stage {it.stage} done commit "
-                  f"{it.recorded[:8]} -> {it.suggested_commit[:8]} "
-                  "(patch-equivalent)", file=sys.stdout)
-    except Exception as exc:  # 화해는 부가 기능 — 실패 시 기존 gate 가 판정
-        print(f"git-reconcile skipped: {exc}", file=sys.stderr)
+    _stage_auto_reconcile_best_effort(inp, plan_run_root)
 
 
 def _is_ancestor(cwd, commit, head) -> bool:

package/runtime/python/okstra_ctl/stage_reconcile.py

@@ -0,0 +1,33 @@
+"""Best-effort git reconciliation shared by stage prepare flows."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def auto_reconcile_best_effort(inp: Any, plan_run_root: Path) -> None:
+    """Run patch-equivalence reconciliation without changing prepare outcome.
+
+    Reconciliation is advisory: failures are reported to stderr and the normal
+    dependency gates still make the authoritative decision.
+    """
+    try:
+        from .git_reconcile import auto_reconcile
+
+        for item in auto_reconcile(
+            project_root=Path(inp.project_root),
+            plan_run_root=plan_run_root,
+            project_id=inp.project_id,
+            task_group=inp.task_group,
+            task_id=inp.task_id,
+            work_category=inp.work_category,
+        ):
+            print(
+                f"git-reconcile: stage {item.stage} done commit "
+                f"{item.recorded[:8]} -> {item.suggested_commit[:8]} "
+                "(patch-equivalent)",
+                file=sys.stdout,
+            )
+    except Exception as exc:
+        print(f"git-reconcile skipped: {exc}", file=sys.stderr)

package/runtime/python/okstra_ctl/stage_targets.py

@@ -0,0 +1,277 @@
+"""Stage readiness and verification target rules.
+
+This module owns the policy that decides which Stage Map stage can run, which
+commit it branches from, and what final-verification should inspect. It keeps
+the stage lifecycle rules behind one interface instead of leaking raw
+``consumers.jsonl`` rows and git ancestry checks into prepare callers.
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+RUN_STEP_BUDGET = 8
+
+
+class StageTargetError(Exception):
+    """Stage target selection or verification precondition failed."""
+
+
+@dataclass
+class FinalVerificationTarget:
+    scope: str            # "whole-task" | "single-stage"
+    base: str
+    head: str
+    worktree_path: str
+    stages: list[int]
+    reports: list[str]
+
+
+def resolve_effective_stages(
+    stages: list[dict[str, Any]],
+    done_stages: set[int],
+    requested: str,
+    budget: int = RUN_STEP_BUDGET,
+    started_stages: set[int] | None = None,
+    reserved_stages: set[int] | None = None,
+) -> list[int]:
+    """Return ordered stage numbers this run should execute.
+
+    ``requested`` is ``"auto"`` or a decimal string. Auto selection returns all
+    ready stages within the step budget, excluding done/started/reserved stages.
+    Numeric selection returns one forced stage.
+    """
+    started_stages = started_stages or set()
+    reserved_stages = reserved_stages or set()
+    occupied = done_stages | started_stages | reserved_stages
+    if requested != "auto":
+        try:
+            n = int(requested)
+        except ValueError as exc:
+            raise StageTargetError(
+                f"--stage must be 'auto' or an integer, got {requested!r}"
+            ) from exc
+        target = next((s for s in stages if s["stage_number"] == n), None)
+        if target is None:
+            raise StageTargetError(
+                f"--stage {n} not in Stage Map "
+                f"(have {[s['stage_number'] for s in stages]})"
+            )
+        if n in done_stages:
+            raise StageTargetError(
+                f"--stage {n} already completed (consumers.jsonl status:done exists)"
+            )
+        if n in started_stages or n in reserved_stages:
+            raise StageTargetError(
+                f"--stage {n} already in progress or reserved by another run"
+            )
+        return [n]
+
+    ready = [
+        s for s in stages
+        if s["stage_number"] not in occupied
+        and all(d in done_stages for d in s["depends_on"])
+    ]
+    if not ready:
+        raise StageTargetError(
+            "no stage is ready: every remaining stage has unsatisfied depends-on"
+        )
+    batch: list[int] = []
+    total = 0
+    for stage in ready:
+        step_count = stage.get("step_count", 0) or 0
+        if batch and total + step_count > budget:
+            break
+        batch.append(stage["stage_number"])
+        total += step_count
+    return batch
+
+
+def commit_is_ancestor(project_root: Path, ancestor: str, descendant: str) -> bool:
+    """True iff ``ancestor`` is an ancestor of ``descendant`` in git history."""
+    result = subprocess.run(
+        ["git", "merge-base", "--is-ancestor", ancestor, descendant],
+        cwd=str(project_root),
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def check_multi_dep_merged(
+    project_root: Path,
+    plan_run_root: Path | None,
+    latest: dict[int, dict[str, Any]],
+    pred_commits: dict[int, str],
+    candidate_base: str,
+    stage_n: int,
+) -> None:
+    """Ensure all predecessor commits are merged into the candidate base."""
+    from .git_reconcile import content_merged, _record_reconciled
+
+    for dep_stage, head in pred_commits.items():
+        if commit_is_ancestor(project_root, head, candidate_base):
+            continue
+        match = content_merged(project_root, head, candidate_base)
+        if match.status in ("ancestor", "patch-equivalent"):
+            if plan_run_root is not None:
+                _record_reconciled(
+                    plan_run_root,
+                    impl_task_key=(latest.get(dep_stage) or {}).get("impl_task_key", ""),
+                    stage=dep_stage,
+                    new_commit=match.matched_commit,
+                    replaced=head,
+                    reason="auto-patch-id",
+                )
+            continue
+        raise StageTargetError(
+            f"multi-dependency stage {stage_n}: predecessor stage {dep_stage} "
+            f"({head[:8]}) is not merged into the task worktree "
+            f"({candidate_base[:8]}). Merge stage branches "
+            f"(e.g. the `-s{dep_stage}` branches) into the task worktree "
+            "(or into main, then refresh the worktree) and retry."
+        )
+
+
+def resolve_stage_base_commit(
+    stage: dict[str, Any],
+    consumer_done_rows: list[dict[str, Any]],
+    anchor_base_commit: str,
+    candidate_base: str = "",
+    project_root: Path | None = None,
+    plan_run_root: Path | None = None,
+) -> str:
+    """Pick the git base commit a stage's isolated worktree branches from."""
+    from .consumers import latest_done_by_stage
+
+    latest = latest_done_by_stage(consumer_done_rows)
+    deps = stage.get("depends_on") or []
+    if len(deps) >= 2:
+        stage_number = stage["stage_number"]
+        pred_commits: dict[int, str] = {}
+        for dep_stage in deps:
+            head = (latest.get(dep_stage) or {}).get("head_commit")
+            if not head:
+                raise StageTargetError(
+                    f"predecessor stage {dep_stage} has no done row with head_commit "
+                    f"in consumers.jsonl; multi-dependency stage {stage_number} cannot start"
+                )
+            pred_commits[dep_stage] = head
+        if not candidate_base or project_root is None:
+            raise StageTargetError(
+                f"candidate base missing for multi-dependency stage {stage_number}; "
+                "task-key worktree HEAD could not be resolved"
+            )
+        check_multi_dep_merged(
+            project_root,
+            plan_run_root,
+            latest,
+            pred_commits,
+            candidate_base,
+            stage_number,
+        )
+        return candidate_base
+    if not deps:
+        if not anchor_base_commit:
+            raise StageTargetError(
+                f"anchor base commit missing for independent stage "
+                f"{stage['stage_number']}; first-stage prepare should have "
+                "fixed it via worktree_registry.set_implementation_base"
+            )
+        return anchor_base_commit
+    pred = deps[0]
+    head = (latest.get(pred) or {}).get("head_commit") or ""
+    if head:
+        return head
+    raise StageTargetError(
+        f"predecessor stage {pred} has no done row with head_commit in "
+        "consumers.jsonl; cannot derive base for stage "
+        f"{stage['stage_number']}"
+    )
+
+
+def resolve_whole_task_target(
+    *,
+    stage_map: list[dict[str, Any]],
+    done_rows: list[dict[str, Any]],
+    anchor_base: str,
+    task_worktree_path: str,
+    task_head: str,
+    task_dirty: bool,
+    merged: dict[int, bool],
+) -> FinalVerificationTarget:
+    """Resolve whole-task final-verification target, enforcing all gates."""
+    from .consumers import latest_done_by_stage
+
+    done_by_stage = latest_done_by_stage(done_rows)
+    for stage in stage_map:
+        n = stage["stage_number"]
+        if n not in done_by_stage:
+            raise StageTargetError(
+                f"final-verification(whole-task): stage {n} not done — "
+                f"run implementation --stage {n} first"
+            )
+        if not merged.get(n, False):
+            sha = done_by_stage[n].get("head_commit", "")
+            raise StageTargetError(
+                f"final-verification(whole-task): stage {n} done commit "
+                f"{sha} not merged into task worktree HEAD — merge stage "
+                "branches then retry"
+            )
+    if task_dirty:
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    stages = [s["stage_number"] for s in stage_map]
+    reports = [done_by_stage[n].get("report_path", "") for n in stages]
+    return FinalVerificationTarget(
+        scope="whole-task",
+        base=anchor_base,
+        head=task_head,
+        worktree_path=task_worktree_path,
+        stages=stages,
+        reports=reports,
+    )
+
+
+def resolve_single_stage_target(
+    *,
+    requested_stage: str,
+    done_rows: list[dict[str, Any]],
+    stage_base: str,
+    stage_worktree_path: str,
+    stage_head: str,
+    stage_dirty: bool,
+) -> FinalVerificationTarget:
+    """Resolve single-stage final-verification target, enforcing all gates."""
+    from .consumers import latest_done_by_stage
+
+    n = int(requested_stage)
+    done_by_stage = latest_done_by_stage(done_rows)
+    if n not in done_by_stage:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage {n} not done — "
+            f"run implementation --stage {n} first"
+        )
+    if not stage_worktree_path:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage worktree not found for "
+            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
+        )
+    if stage_dirty:
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    return FinalVerificationTarget(
+        scope="single-stage",
+        base=stage_base,
+        head=stage_head,
+        worktree_path=stage_worktree_path,
+        stages=[n],
+        reports=[done_by_stage[n].get("report_path", "")],
+    )

package/runtime/python/okstra_ctl/wizard.py

@@ -44,6 +44,7 @@ from okstra_ctl.run import (
     _reject_blocking_plan_body_gate,
     _set_data_json_approved_true_if_present,
     _validate_data_json_approval_consistency,
+    recommended_role_models,
 )
 from okstra_ctl.user_response import (
     UserResponseApprovalRecord,
@@ -93,6 +94,15 @@ TASK_TYPE_VALUES = [tt for tt, _ in TASK_TYPES]
 
 EXECUTORS = ["claude", "codex", "antigravity"]
 
+# 역할 한 줄 설명 — defaults_or_custom 안내에서 각 역할이 무슨 일을 하는지 보여준다.
+ROLE_BLURBS = {
+    "lead": "Claude lead · 워커 dispatch·교차검증 수렴·최종 합성",
+    "claude": "독립 분석 워커 (Claude)",
+    "codex": "독립 분석 워커 (Codex)",
+    "antigravity": "독립 분석 워커 (Antigravity)",
+    "report-writer": "최종 리포트 작성 (분석은 하지 않음)",
+}
+
 # Task types that consume an approved plan and need a stage-scope pick:
 # implementation executes a stage, final-verification verifies a stage
 # (or the whole task via `auto`). Both gate the approved-plan + stage steps.
@@ -2357,11 +2367,34 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
             f"lead-model={state.lead_model or 'default'})")
 
 
+def _role_model_lines(state: WizardState) -> str:
+    """이번 run 에서 실제로 모델을 고르게 되는 역할만, 추천 모델과 함께 나열한다.
+    뒤따르는 *_model 단계의 등장 조건과 1:1 로 맞춰 안내와 실제 화면이 어긋나지
+    않게 한다 (그래서 분석에 참여하지 않는 antigravity 는 executor 일 때만 나온다)."""
+    rec = recommended_role_models()
+    roster = _resolved_roster(state)
+    impl = state.task_type == "implementation"
+
+    def line(role_label: str, blurb: str, model: str) -> str:
+        return f"  · {role_label} ({blurb}) — 추천 {model}"
+
+    lines = [line("lead", ROLE_BLURBS["lead"], rec["lead"])]
+    if impl:
+        ex = state.executor or "claude"
+        lines.append(line(f"executor={ex}", "코드 구현 실행자", rec.get(ex, "auto")))
+    else:
+        for w in ("claude", "codex", "antigravity"):
+            if w in roster:
+                lines.append(line(w, ROLE_BLURBS[w], rec[w]))
+    if impl or "report-writer" in roster:
+        lines.append(line("report-writer", ROLE_BLURBS["report-writer"],
+                          rec["report-writer"]))
+    return "\n".join(lines)
+
+
 def _build_defaults_or_custom(state: WizardState) -> Prompt:
-    roster = (state.workers_override
-              or ",".join(state.profile_workers)
-              or "(profile default)")
-    t = _p(state.workspace_root, "defaults_or_custom", workers=roster)
+    t = _p(state.workspace_root, "defaults_or_custom",
+           role_models=_role_model_lines(state))
     return Prompt(
         step=S_DEFAULTS_OR_CUSTOM, kind="pick",
         label=t["label"],
@@ -3306,11 +3339,16 @@ def _remaining_screens(state: WizardState) -> int:
     return screens
 
 
-def _screen_progress(state: WizardState) -> dict[str, int]:
+def _screen_progress(state: WizardState) -> dict[str, Any]:
     passed = _passed_screens(state)
     total = passed + _remaining_screens(state)
     index = passed + 1
-    return {"index": index, "total": total, "remaining": max(0, total - index)}
+    remaining = max(0, total - index)
+    suffix = "마지막 단계" if remaining == 0 else f"앞으로 {remaining} 스텝 남음"
+    return {
+        "index": index, "total": total, "remaining": remaining,
+        "label": f"Step {index}/{total} · {suffix}",
+    }
 
 
 def prompt_payload(state: WizardState, prompt: Prompt) -> dict[str, Any]:

package/runtime/skills/okstra-run/SKILL.md

@@ -32,7 +32,7 @@ Every wizard call returns JSON. The two shapes you'll see:
             "progress": { "index": 5, "total": 11, "remaining": 6 } } }
 ```
 
-Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). `index` is the 1-based number of the **current screen** (pick_group counts as one screen), `total` is the wizard's estimate of the full screen count, and `remaining` = `total − index`. The total is a forward estimate from the current answers, so it may grow by a few when the user opens a branch (e.g. choosing *Customize* adds the model screen). **Always suffix the rendered prompt with the progress marker** — see Step 3.
+Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). It holds `index` (1-based number of the **current screen**; pick_group counts as one screen), `total` (the wizard's forward estimate of the full screen count — may grow by a few when the user opens a branch, e.g. choosing *Customize* adds the model screen), `remaining` (`total − index`), and **`label`** — the ready-to-render Korean marker the wizard already composed (e.g. `Step 10/11 · 앞으로 1 스텝 남음`, or `Step 11/11 · 마지막 단계` on the final screen). **Always suffix the rendered prompt with `progress.label` verbatim** — see Step 3. Do not recompute the marker or decide "마지막 단계" yourself; only the wizard knows whether more screens follow.
 
 ```json
 { "ok": false, "error": "approved plan has no APPROVED marker: ...",
@@ -96,7 +96,7 @@ Output: the same `{ok, next}` JSON described above. The first `next` is always `
 
 Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How the wizard talks to you"):
 
-1. **Render** the prompt according to `kind` (and `multi` for pick). **Always append the progress marker to the rendered question label** (the `AskUserQuestion` question text, or the `text`-prompt message): suffix `label` with ` (Step <index>/<total> · 남은 <remaining>단계)`, using `next.progress`. When `remaining == 0` (the final `confirm` screen), use `(Step <index>/<total> · 마지막 단계)` instead. Example: `모델을 선택하세요 (Step 8/11 · 남은 3단계)`. Re-prompts after `ok: false` reuse `current.progress` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer.
+1. **Render** the prompt according to `kind` (and `multi` for pick). **Always append the progress marker to the rendered question label** (the `AskUserQuestion` question text, or the `text`-prompt message): suffix it with ` (<next.progress.label>)` — render `progress.label` exactly as the wizard sent it, never recompute it. Example: label `Step 8/11 · 앞으로 3 스텝 남음` → `모델을 선택하세요 (Step 8/11 · 앞으로 3 스텝 남음)`. Re-prompts after `ok: false` reuse `current.progress.label` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer.
    - `pick` + `multi: false` → `AskUserQuestion` with `multiSelect: false`, `label`, and `options`. The user's chosen option's `value` is the answer string.
    - `pick` + `multi: true` → `AskUserQuestion` with `multiSelect: true`, `label`, and `options`. Join the selected `value`s with `,` into a single literal CSV string (e.g. `"claude,codex,antigravity"`) and submit it as a single `--answer "claude,codex,antigravity"`. Empty selection submits `--answer ""` and the wizard re-prompts.
    - `pick_group` → one `AskUserQuestion` with one question per `questions[]` entry (tab). Map each tab's selected `value` back by `questions[].step`, assemble a JSON object, and submit it as a single literal `--answer '<json>'`.