okstra 0.63.0 → 0.64.0

package/runtime/python/okstra_ctl/run.py

@@ -27,6 +27,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from okstra_project import project_json_path, upsert_project_json
+from okstra_project.state import slugify
 from .analysis_packet import build_analysis_packet
 from .clarification_items import (
     section_1_present_but_unparsed,
@@ -1271,22 +1272,47 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
     )
 
 
-def _reserve_implementation_stages(inp: PrepareInputs, ctx: dict, ctx_stage_map: list) -> None:
-    """implementation run 의 첫 ready stage 를 결정하고 stage 격리 worktree 를
-    발급해 ctx 의 EXECUTOR_WORKTREE_* 를 덮어쓴다. anchor base commit 을 1회
-    고정하고 그 stage 를 consumers.jsonl 에 started 로 append.
+@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
 
-    spec §2.3: 한 run = 한 stage. `_resolve_effective_stages` 는 backward
-    compat 로 batch 리스트를 반환하지만 첫 번째만 실행한다 — stage 마다 격리
-    worktree·branch 가 필요해 batch 가 의미를 잃기 때문(cost-aware-design 의
-    run-batch 와의 의도된 트레이드오프)."""
-    from .consumers import read_consumers, append_consumer
+
+def _select_and_provision_implementation_stage(
+    inp: PrepareInputs,
+    ctx_stage_map: list,
+    task_group_segment: str,
+    task_id_segment: str,
+    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
-    import datetime as _dt
 
-    ctx["parsed_stage_map"] = ctx_stage_map
     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)
     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"}
@@ -1298,46 +1324,24 @@ def _reserve_implementation_stages(inp: PrepareInputs, ctx: dict, ctx_stage_map:
         ctx_stage_map, done_stages, inp.stage,
         started_stages=started_stages, reserved_stages=reserved_stages,
     )
-    # stage 격리: 한 run = 한 stage. 첫 ready stage 만 실행.
     selected = batch[0]
-    ctx["effective_stages"] = [selected]
-    csv = str(selected)
-    ctx["EFFECTIVE_STAGES"] = csv
-    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)
 
     # spec §2.1 degradation: 주변 흐름이 non-git / nested-worktree 로 skipped 면
-    # stage 격리도 동일하게 degrade — consumers 만 기록 (기존 평면 동작 보존).
-    wt_status = ctx.get("EXECUTOR_WORKTREE_STATUS", "")
-    if wt_status.startswith("skipped"):
-        head_proc = _subprocess.run(
-            ["git", "rev-parse", "HEAD"],
-            cwd=inp.project_root, capture_output=True, text=True,
-        )
-        head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
-        now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-        append_consumer(
-            plan_run_root,
-            impl_task_key=ctx["TASK_KEY"],
+    # stage 격리도 동일하게 degrade — worktree 없이 project HEAD 만 기록.
+    if executor_worktree_status.startswith("skipped"):
+        head = _git_out(inp.project_root, "rev-parse", "HEAD")
+        return StageSelection(
             stage=selected,
-            status="started",
-            started_at=now,
-            head_commit=head_sha,
+            worktree_path="",
+            worktree_branch="",
+            worktree_base_ref="",
+            worktree_status=executor_worktree_status,
+            worktree_note="",
+            started_head_commit=head,
         )
-        return
 
     # anchor base commit 1회 고정 (task-key worktree HEAD 기준)
-    head_proc = _subprocess.run(
-        ["git", "rev-parse", "HEAD"],
-        cwd=inp.project_root, capture_output=True, text=True,
-    )
-    head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
+    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,
@@ -1356,11 +1360,11 @@ def _reserve_implementation_stages(inp: PrepareInputs, ctx: dict, ctx_stage_map:
         candidate_base=head_sha, project_root=Path(inp.project_root),
     )
     try:
-        provision = _worktree.provision_stage_worktree(
+        prov = _worktree.provision_stage_worktree(
             project_root=Path(inp.project_root),
             project_id=inp.project_id,
-            task_group_segment=ctx["TASK_GROUP_SEGMENT"],
-            task_id_segment=ctx["TASK_ID_SEGMENT"],
+            task_group_segment=task_group_segment,
+            task_id_segment=task_id_segment,
             work_category=inp.work_category,
             stage_number=selected,
             base_commit=stage_base,
@@ -1368,21 +1372,59 @@ def _reserve_implementation_stages(inp: PrepareInputs, ctx: dict, ctx_stage_map:
     except RuntimeError as exc:
         raise PrepareError(f"stage worktree provisioning failed: {exc}") from exc
 
-    ctx["EXECUTOR_WORKTREE_PATH"] = provision.path
-    ctx["EXECUTOR_WORKTREE_BRANCH"] = provision.branch
-    ctx["EXECUTOR_WORKTREE_BASE_REF"] = provision.base_ref
-    ctx["EXECUTOR_WORKTREE_STATUS"] = provision.status
-    ctx["EXECUTOR_WORKTREE_NOTE"] = provision.note
+    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,
+    )
+
+
+def _apply_implementation_stage(
+    inp: PrepareInputs,
+    ctx: dict,
+    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["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
 
-    # consumers append — stage worktree base 를 head_commit 으로
     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=selected,
+        stage=sel.stage,
         status="started",
         started_at=now,
-        head_commit=provision.base_ref,
+        head_commit=sel.started_head_commit,
     )
 
 
@@ -1413,10 +1455,13 @@ def _reserve_final_verification_target(
     """final-verification 의 검증 target 을 registry/consumers/git 에서
     해소하고 gate 를 강제한다. 위반 시 PrepareError. 결과를 ctx 의
     VERIFICATION_* 키로 주입한다."""
-    from .consumers import read_consumers
+    from .consumers import read_consumers, backfill_done_from_carry
     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 missing `done`
+    # rows before the whole-task gate checks every stage.
+    backfill_done_from_carry(plan_run_root)
     done_rows = [r for r in read_consumers(plan_run_root)
                  if r.get("status") == "done"]
 
@@ -1683,24 +1728,30 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # 한 seq 를 강제하는 user-knob 환경 변수.
     raw_override = os.environ.get("OKSTRA_RUN_SEQ_OVERRIDE", "").strip()
     run_seq_override = int(raw_override) if raw_override else None
-    ctx = compute_and_write_run_context(
-        workspace_root=workspace_root, project_root=project_root,
-        project_id=inp.project_id, task_group=inp.task_group, task_id=inp.task_id,
-        task_type=inp.task_type, run_seq_override=run_seq_override,
-    )
+
+    # Identity segments derived with the SAME slugify rule compute_run_paths
+    # uses, so they match ctx["TASK_GROUP_SEGMENT"]/["TASK_ID_SEGMENT"]
+    # byte-for-byte. We need them BEFORE run-path compute because
+    # implementation stage selection depends on the task-worktree degrade
+    # status, and the run path itself is stage-namespaced.
+    task_group_segment = slugify(inp.task_group)
+    task_id_segment = slugify(inp.task_id)
+    task_key = f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
 
     # ---- task worktree provisioning (every phase, every task-type) ----
     # One worktree per task-key: requirements-discovery, error-analysis,
     # implementation-planning and implementation phases of the same task
     # all share this directory and branch. The global registry handles
-    # reservation across concurrent runs.
+    # reservation across concurrent runs. Runs BEFORE run-path compute: its
+    # degrade status (skipped-*) feeds implementation stage selection, and
+    # the resolved stage namespaces the run path.
     try:
         worktree = provision_task_worktree(
             task_type=inp.task_type,
             project_root=project_root,
             project_id=inp.project_id,
-            task_group_segment=ctx["TASK_GROUP_SEGMENT"],
-            task_id_segment=ctx["TASK_ID_SEGMENT"],
+            task_group_segment=task_group_segment,
+            task_id_segment=task_id_segment,
             work_category=inp.work_category,
             base_ref=inp.base_ref,
             require_base_ref=True,
@@ -1708,6 +1759,28 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     except RuntimeError as exc:
         raise PrepareError(f"task worktree provisioning failed: {exc}") from exc
 
+    # ---- implementation stage selection (path-independent, reserves once) ----
+    # Resolve + provision the stage BEFORE run-path compute so RUN_DIR lands
+    # in runs/implementation/stage-<N>. The registry stage-key is reserved
+    # exactly once here (inside provision_stage_worktree). Non-implementation
+    # task-types skip this entirely → stage_arg stays None → identical paths.
+    if inp.task_type == "implementation":
+        impl_stage_selection = _select_and_provision_implementation_stage(
+            inp, ctx_stage_map, task_group_segment, task_id_segment,
+            task_key, worktree.status,
+        )
+        stage_arg = impl_stage_selection.stage
+    else:
+        impl_stage_selection = None
+        stage_arg = None
+
+    ctx = compute_and_write_run_context(
+        workspace_root=workspace_root, project_root=project_root,
+        project_id=inp.project_id, task_group=inp.task_group, task_id=inp.task_id,
+        task_type=inp.task_type, run_seq_override=run_seq_override,
+        stage=stage_arg,
+    )
+
     ctx.update({
         "EXECUTOR_WORKTREE_PATH": worktree.path,
         "EXECUTOR_WORKTREE_BRANCH": worktree.branch,
@@ -1723,6 +1796,15 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         ),
     })
 
+    # implementation: override the task-worktree fields with the resolved
+    # STAGE worktree and append the consumers.jsonl started row. Must run
+    # AFTER the task-worktree fields above (mirrors the original ordering
+    # where stage reservation overrode them post task-provision).
+    if inp.task_type == "implementation":
+        _apply_implementation_stage(
+            inp, ctx, ctx_stage_map, impl_stage_selection,
+        )
+
     if inp.render_only:
         # render-only entry path (e.g. okstra-run skill, in-session takeover):
         # the calling Claude session itself becomes the lead, so we must NOT
@@ -1803,9 +1885,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "OKSTRA_VERSION": installed_version(),
         **workflow_state,
     })
-    if inp.task_type == "implementation":
-        _reserve_implementation_stages(inp, ctx, ctx_stage_map)
-    elif inp.task_type == "final-verification":
+    if inp.task_type == "final-verification":
         _reserve_final_verification_target(inp, ctx, ctx_stage_map)
 
     # ---- prepare directories + cleanup ----

package/runtime/python/okstra_ctl/run_context.py

@@ -151,6 +151,7 @@ def compute_and_write_run_context(
     task_id: str,
     task_type: str,
     run_seq_override: Optional[int] = None,
+    stage: Optional[int] = None,
 ) -> dict:
     """task per-mutex 안에서 run paths 를 계산하고 디스크에 박는다.
 
@@ -174,6 +175,7 @@ def compute_and_write_run_context(
             task_id=task_id,
             task_type=task_type,
             run_seq_override=run_seq_override,
+            stage=stage,
         )
         ctx["RUN_TIMESTAMP_ISO"] = _now_iso()
         ctx["TASK_DATE"] = _now_task_date()

package/runtime/python/okstra_ctl/wizard.py

@@ -39,7 +39,9 @@ from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
     APPROVED_FRONTMATTER_PATTERN,
     _extract_frontmatter_block,
+    _load_final_report_data_if_present,
     _reject_blocking_plan_body_gate,
+    _set_data_json_approved_true_if_present,
     _validate_data_json_approval_consistency,
 )
 from okstra_ctl.workers import (
@@ -228,6 +230,7 @@ S_BASE_REF_PICK = "base_ref_pick"
 S_BASE_REF_TEXT = "base_ref_text"
 S_APPROVED_PLAN_PICK = "approved_plan_pick"
 S_APPROVED_PLAN = "approved_plan"
+S_APPROVE_PLAN_CONFIRM = "approve_plan_confirm"
 S_STAGE_PICK = "stage_pick"
 S_EXECUTOR = "executor"
 S_CRITIC_PICK = "critic_pick"
@@ -318,6 +321,9 @@ class WizardState:
     # impl extras
     approved_plan_path: str = ""
     approved_plan_pending_text: bool = False
+    # A plan that is approvable (gate ok, no blockers) but not yet `approved`.
+    # Set when the user selects such a plan; the approve-confirm step reads it.
+    approve_plan_candidate: str = ""
     selected_stage: str = "auto"
     executor: str = ""
     critic: str = ""
@@ -436,7 +442,31 @@ def _require_file(path_str: str, project_root: Path, label: str) -> Path:
     return p
 
 
-def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
+def _data_json_approved_state(plan_path: Path) -> Optional[bool]:
+    """`approved` flag of the sibling final-report data.json (the SSOT).
+
+    Returns the bool when present, or None when there is no data.json or the
+    flag is missing / non-bool (legacy report — markdown frontmatter governs)."""
+    loaded = _load_final_report_data_if_present(plan_path)
+    if loaded is None:
+        return None
+    frontmatter = loaded[1].get("frontmatter")
+    if not isinstance(frontmatter, dict) or "approved" not in frontmatter:
+        return None
+    value = frontmatter.get("approved")
+    return value if isinstance(value, bool) else None
+
+
+def _classify_approved_plan(path_str: str, project_root: Path) -> tuple[Path, bool]:
+    """Resolve the plan and classify it as fully-approved vs approvable.
+
+    Returns ``(resolved_path, already_fully_approved)``. Raises WizardError ONLY
+    for failures that approval cannot fix: missing frontmatter / `approved:`
+    field, a blocking plan-body gate, an unparseable §1, or unresolved
+    `Blocks=approval` rows. A plan that is merely not-yet-approved (markdown or
+    data.json `approved: false`, gate ok, no blockers) returns
+    ``already_fully_approved=False`` — the approve-confirm step offers to flip it.
+    """
     p = _require_file(path_str, project_root, "approved plan")
     body = p.read_text(encoding="utf-8", errors="replace")
     frontmatter = _extract_frontmatter_block(body)
@@ -449,19 +479,12 @@ def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
     if not m:
         raise WizardError(
             f"approved plan frontmatter has no `approved:` field: {p}\n"
-            "  expected `approved: true` (report-writer emits `approved: false` "
-            "by default; flip it once approved)."
-        )
-    if m.group(1).lower() != "true":
-        raise WizardError(
-            f"approved plan is not yet approved (frontmatter `approved: {m.group(1)}`): {p}\n"
-            "  edit the report and change the line to `approved: true`, or re-run "
-            "okstra with `--approve` to flip it from the CLI."
+            "  expected `approved: true` / `approved: false`. Re-render the "
+            "report if the field is missing."
         )
+    # A blocking gate or an open Blocks=approval row makes the plan UN-approvable
+    # — these raise regardless of the current flag value.
     _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
-    _validate_data_json_approval_consistency(p, markdown_approved=True)
-    # frontmatter approved == true 라도 §1 의 Blocks=approval 행이 미해결이면
-    # 승인이 무효 — prepare_task_bundle 의 _validate_approved_plan 과 동일 규약.
     blockers = unresolved_approval_blockers(body)
     if blockers is None and section_1_present_but_unparsed(body):
         raise WizardError(
@@ -472,14 +495,51 @@ def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
         )
     if blockers:
         lines = [
-            f"approved plan frontmatter has `approved: true` but §1 has {len(blockers)} "
-            f"unresolved `Blocks=approval` row(s); resolve them or mark them obsolete first:",
+            f"approved plan §1 has {len(blockers)} unresolved `Blocks=approval` "
+            "row(s); resolve them or mark them obsolete before approving:",
         ]
         for b in blockers:
             lines.append(f"  - {b.row_id} (Status={b.raw_status})")
         lines.append(f"  file: {p}")
         raise WizardError("\n".join(lines))
-    return p
+    markdown_approved = m.group(1).lower() == "true"
+    data_state = _data_json_approved_state(p)
+    fully_approved = markdown_approved and data_state is not False
+    return p, fully_approved
+
+
+def _approve_plan_in_place(plan_path: Path) -> None:
+    """Flip the plan to approved at the source of truth and re-render.
+
+    data.json present → `_set_data_json_approved_true_if_present` sets
+    `frontmatter.approved=true` there and re-renders the markdown from it (so
+    both agree). data.json absent (legacy) → flip the markdown frontmatter line."""
+    rendered = _set_data_json_approved_true_if_present(plan_path)
+    if rendered:
+        return
+    body = plan_path.read_text(encoding="utf-8", errors="replace")
+    flipped = APPROVED_FRONTMATTER_PATTERN.sub("approved: true", body, count=1)
+    if flipped == body:
+        raise WizardError(
+            f"approve-plan: could not flip the markdown `approved:` line: {plan_path}"
+        )
+    plan_path.write_text(flipped, encoding="utf-8")
+
+
+def _stage_plan_for_confirmation(
+    state: WizardState, path_str: str, *, suffix: str = ""
+) -> Optional[str]:
+    """Resolve + validate a selected plan, then stage it for the approve-confirm
+    step. Selection NEVER finalizes the plan — the confirm step always runs and
+    asks the user to proceed (approving the plan first if it is not yet approved).
+    `_classify_approved_plan` still raises for failures approval cannot fix."""
+    p, _ = _classify_approved_plan(path_str, Path(state.project_root))
+    state.approved_plan_pending_text = False
+    state.approved_plan_path = ""
+    state.approve_plan_candidate = str(p)
+    t = _p(state.workspace_root, "approve_plan_confirm", path=str(p))
+    msg = t["echo_variants"]["selected"].format(path=p)
+    return f"{msg} {suffix}".rstrip() if suffix else msg
 
 
 def _git_main_worktree(project_root: Path) -> Path:
@@ -1274,17 +1334,11 @@ def _submit_approved_plan_pick(state: WizardState, value: str) -> Optional[str]:
         default = _latest_implementation_planning_report(state)
         if default is None:
             raise WizardError(t["errors"]["default_not_found"])
-        p = _validate_approved_plan(str(default), Path(state.project_root))
-        state.approved_plan_path = str(p)
-        state.approved_plan_pending_text = False
-        return f"approved-plan: {p}"
+        return _stage_plan_for_confirmation(state, str(default))
     if value.startswith(_REPORT_PREFIX):
         rel = value[len(_REPORT_PREFIX):]
-        p = _validate_approved_plan(rel, Path(state.project_root))
-        state.approved_plan_path = str(p)
-        state.approved_plan_pending_text = False
-        suffix = t["echo_suffixes"]["other_report"]
-        return f"approved-plan: {p} {suffix}"
+        return _stage_plan_for_confirmation(
+            state, rel, suffix=t["echo_suffixes"]["other_report"])
     if value == PICK_OTHER:
         state.approved_plan_pending_text = True
         state.approved_plan_path = ""
@@ -1305,10 +1359,44 @@ def _build_approved_plan(state: WizardState) -> Prompt:
 
 
 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)
-    state.approved_plan_pending_text = False
-    return f"approved-plan: {p}"
+    return _stage_plan_for_confirmation(state, value)
+
+
+def _build_approve_plan_confirm(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "approve_plan_confirm",
+           path=state.approve_plan_candidate)
+    return Prompt(
+        step=S_APPROVE_PLAN_CONFIRM, kind="pick",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str]:
+    if value not in ("yes", "no"):
+        raise WizardError(f"expected 'yes' or 'no', got: {value!r}")
+    candidate = state.approve_plan_candidate
+    if not candidate:
+        raise WizardError("approve-plan: no candidate plan to approve")
+    t = _p(state.workspace_root, "approve_plan_confirm", path=candidate)
+    if value == "no":
+        # Declining leaves the candidate set so the confirm step re-prompts;
+        # implementation cannot proceed without choosing to proceed.
+        raise WizardError(t["errors"]["declined"])
+    p = Path(candidate)
+    resolved, fully_approved = _classify_approved_plan(
+        str(p), Path(state.project_root))
+    if not fully_approved:
+        # Not yet approved → flip data.json (SSOT) + re-render, then re-verify.
+        _approve_plan_in_place(p)
+        resolved, fully_approved = _classify_approved_plan(
+            str(p), Path(state.project_root))
+        if not fully_approved:
+            raise WizardError(t["errors"]["still_unapproved"].format(path=resolved))
+    state.approved_plan_path = str(resolved)
+    state.approve_plan_candidate = ""
+    return t["echo_variants"]["approved"].format(path=resolved)
 
 
 def _build_stage_pick(state: WizardState) -> Prompt:
@@ -1765,7 +1853,10 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_defaults_or_custom(state: WizardState) -> Prompt:
-    t = _p(state.workspace_root, "defaults_or_custom")
+    roster = (state.workers_override
+              or ",".join(state.profile_workers)
+              or "(profile default)")
+    t = _p(state.workspace_root, "defaults_or_custom", workers=roster)
     return Prompt(
         step=S_DEFAULTS_OR_CUSTOM, kind="pick",
         label=t["label"],
@@ -2202,6 +2293,13 @@ STEPS: list[Step] = [
                                  or _latest_implementation_planning_report(s) is None)),
          build=_build_approved_plan, submit=_submit_approved_plan,
          owns=("approved_plan_path", "approved_plan_pending_text")),
+    Step(S_APPROVE_PLAN_CONFIRM,
+         applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
+                            and bool(s.approve_plan_candidate)
+                            and not s.approved_plan_path
+                            and S_APPROVE_PLAN_CONFIRM not in s.answered),
+         build=_build_approve_plan_confirm, submit=_submit_approve_plan_confirm,
+         owns=("approve_plan_candidate",)),
     Step(S_STAGE_PICK,
          applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and bool(s.approved_plan_path)

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

@@ -273,6 +273,8 @@ Agent(
 - Agent Teams mode: Spawn within an existing team
 - Fallback mode: Spawn with `run_in_background: true` and no `team_name`
 
+**Completion detection per round (BLOCKING).** Each round dispatches a variable set (1..N) of reverify workers asynchronously; the `Agent(... team_name ...)` calls return `Spawned successfully` immediately, which is NOT completion. Lead MUST detect each round's completion via the self-scheduled polling protocol in [okstra-team-contract](../okstra-team-contract/SKILL.md) "Worker-completion detection (self-scheduled polling)", with the pending set reconstructed from that round's dispatched workers' Result Paths — do NOT restate the algorithm here. Lead MUST NOT treat the spawn ack as completion and MUST NOT end its turn with a prose "waiting" statement.
+
 ### Required reverify-prompt anchor headers (BLOCKING)
 
 Every reverify prompt MUST start with the same 5 anchor headers used in the initial Phase 4 dispatch — in this exact order, before any other content:
@@ -630,7 +632,7 @@ Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (
 
 ### Plan-item extraction (Round 0 equivalent)
 
-From the report-writer's draft of `## 5.5 Implementation Plan Deliverables`, lead extracts plan items with the following prefixes (see also `templates/reports/final-report.template.md` §5.5.9):
+From the report-writer's draft of `## 5.4 Implementation Plan Deliverables`, lead extracts plan items with the following prefixes (see also `templates/reports/final-report.template.md` §5.5.9):
 
 | Prefix | Source sub-section | One row per |
 |--------|--------------------|-------------|

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -62,6 +62,8 @@ The prompt MUST include, in this order at the top:
 11. For implementation-planning runs: a literal block listing the 8 required English section headings the validator scans for (`Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`). The writer must use these exact substrings as section headings (Korean translation in parentheses is allowed).
 12. An explicit instruction: `You are the author of TWO files: (a) the final-report data.json at <Result Path>, (b) the worker-results audit file at <Worker Result Path>. After writing the data.json, invoke "python3 scripts/okstra-render-final-report.py <Result Path>" via Bash so the markdown sibling is rendered before you return. Do not return the report inline. The validator fails the run when (a)'s schema validation fails, when the rendered markdown is absent, or when (b) is missing.`
 
+**Completion detection after dispatch (BLOCKING).** The `Agent(... team_name ...)` call returns `Spawned successfully` immediately; that ack is NOT completion. After dispatching the report-writer (async), Lead MUST detect its completion via the self-scheduled polling protocol in [okstra-team-contract](../okstra-team-contract/SKILL.md) "Worker-completion detection (self-scheduled polling)", polling for the appearance of the data.json (Result Path) and the worker-results file (Worker Result Path) — do NOT restate the algorithm here. Report-writer is a single worker, so the pending set has one entry; the SSOT protocol handles that naturally. Lead MUST NOT treat the `Spawned successfully` ack as completion and MUST NOT end its turn with a prose "waiting for the report" statement; that path stalls the run until the user manually nudges it.
+
 ### Resume-safe dispatch
 
 A resumed lead session can ALWAYS dispatch a fresh Report writer worker. The Agent tool does not require a previously created Team to be alive:

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

@@ -48,7 +48,7 @@ The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag
 
 The `branch_confirm` step (shown just before `confirm`) is a normal `pick` step and is rendered the same way — no special handling needed.
 
-Never invent additional questions. Never reorder. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
+Never invent additional questions. Never reorder. **Never drop, hide, or merge a `pick` / `pick_group` option** — render every `options[]` entry as its own selectable `AskUserQuestion` choice, including entries that carry a `(default)` / `(recommended)` suffix. Do NOT collapse a multi-option pick into a "recommended + 직접 입력 / Other" shortlist: the wizard's `options[]` array IS the complete, authoritative choice set. Example: the `executor` step always emits `claude` / `codex` / `gemini` — show all three, never just `claude`. The run-prompt recommendation rule (1–2 추천 + 직접 입력) applies ONLY to prompts this skill authors itself (e.g. the conformance-waiver picker), never to wizard-provided `options[]`. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
 
 ## Step 1: Verify okstra runtime + project setup
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -121,6 +121,43 @@ Terminal statuses that can be recorded for a worker:
 | `error` | Execution error, reason recorded; prompt history file must exist |
 | `not-run` | Not executed, reason recorded |
 
+## Worker-completion detection (self-scheduled polling)
+
+**SSOT.** This section is the single source of truth for how Lead detects worker completion across all phases and all worker kinds (Claude teammate, Codex / Gemini wrappers). Other documents (`agents/SKILL.md`, `okstra-report-writer`, `okstra-convergence`) reference this section by name; they MUST NOT restate the algorithm.
+
+Lead dispatches workers asynchronously: an `Agent` call carrying `team_name` returns `Spawned successfully` **immediately** — that ack is NOT a completion. Lead MUST NOT treat the spawn ack as completion, and MUST NOT end its turn with a prose "waiting for ..." statement (that path stalls the run — the Agent Teams idle-notification is experimental and can be dropped, leaving Lead parked until the user manually nudges it). Instead:
+
+1. Record the dispatched workers' Result Paths as the **pending set** (resolved to absolute from each launch prompt's `**Result Path:**` anchor header against `**Project Root:**`; the same paths recorded in run-manifest / team-state).
+2. Arm a SINGLE self-wakeup: one `Bash(run_in_background: true)` poll covering ALL dispatched workers (not one background task per worker):
+
+   ```bash
+   deadline=$((SECONDS + <per-worker-deadline-seconds>))
+   until [ -f "<result_A>" ] && [ -f "<result_B>" ]; do
+     [ $SECONDS -ge $deadline ] && { echo "POLL_TIMEOUT"; exit 1; }
+     sleep 5
+   done
+   echo "ALL_WORKERS_DONE"
+   ```
+
+   The `sleep 5` inside this `until` loop is legal ONLY because the poll runs under `run_in_background: true`. A foreground `sleep` of 5s or longer is blocked by the harness anti-circumvention rule (see the Codex / Gemini wrapper `BashOutput` polling contract above) — do NOT lift this loop into a foreground `Bash`.
+3. End the turn. The harness auto-resumes Lead when the background poll exits — on completion (`ALL_WORKERS_DONE`) OR timeout (`POLL_TIMEOUT`) — with no mailbox / idle-notification dependency and no user nudge.
+4. On resume, for every path still in the pending set: verify the file exists AND passes the standardized worker-result header check (see "Worker Result Header Standard" below). Move each passing worker to the **done set**.
+5. Termination:
+   - pending set empty → proceed to the next phase. The background task already self-terminated, so there is NO schedule to disarm — this self-terminating property is why a background poll is preferred over a cron schedule.
+   - the poll exited `POLL_TIMEOUT` for a worker past its deadline → record terminal status `timeout` for that worker, remove it from the pending set, then redispatch-once (per "Lead Redispatch Policy on Result-Missing" below) or proceed.
+   - any error / abort path → no zombie schedule exists, because the background task is self-terminating.
+6. **Per-worker soft timeout (BLOCKING).** Use 2× the task-type expected per-worker duration in the table below as `<per-worker-deadline-seconds>`. This supersedes the unimplemented "수정 B" in `agents/TODO.md` (Leader-side worker soft timeout): the background poll's `deadline` IS that safety net.
+
+| Task type | Expected per-worker | Deadline (2×) |
+|---|---|---|
+| requirements-discovery | 10 min | 20 min |
+| error-analysis | 15 min | 30 min |
+| implementation-planning | 20 min | 40 min |
+| implementation | 20 min | 40 min |
+| final-verification | 10 min | 20 min |
+
+Relationship to the Codex / Gemini wrapper polling contract: that contract (in the errors-sidecar section above) governs how a *wrapper subagent* waits on its own external CLI via `BashOutput`. This section governs how *Lead* waits on the worker subagents themselves. The two compose — Lead's background poll watches the result files; each wrapper independently watches its CLI — and neither imposes a timeout on the other (see "No external timeout on wrapper subagents").
+
 ## Lead Redispatch Policy on Result-Missing
 
 After each worker subagent returns (regardless of role), Lead MUST verify the canonical result file exists at the absolute path resolved from the `**Result Path:**` anchor header (against `**Project Root:**`). The check is identical for in-process workers (claude-worker) and CLI-wrapper workers (codex-worker / gemini-worker).