okstra 0.70.0 → 0.71.1

package/runtime/python/okstra_ctl/wizard.py

@@ -52,8 +52,10 @@ from okstra_ctl.workers import (
 from okstra_ctl.workflow import PHASE_SEQUENCE
 from okstra_ctl import worktree_registry
 from okstra_ctl.worktree import (
+    compute_worktree_path,
     is_git_work_tree,
     main_worktree_path,
+    preview_stage_worktree_decision,
     preview_worktree_decision,
 )
 from okstra_ctl.paths import task_runs_dir
@@ -88,6 +90,13 @@ EXECUTORS = ["claude", "codex", "gemini"]
 # (or the whole task via `auto`). Both gate the approved-plan + stage steps.
 _STAGE_SCOPED_TASK_TYPES = ("implementation", "final-verification")
 
+# brief 는 entry phase 의 입력물(비개발자/타 팀의 아이디어·에러 초안)이다.
+# downstream phase 는 task manifest 의 taskBriefPath 를 자동 carry-in 하며
+# 위저드에서 brief 를 묻지 않는다 (release-handoff 는 prepare 가 검증 보고서
+# 인용 input 문서를 자동 생성하므로 brief 자체가 없다).
+_BRIEF_ENTRY_TASK_TYPES = ("requirements-discovery", "improvement-discovery",
+                           "error-analysis")
+
 CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
 BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
 
@@ -230,12 +239,14 @@ S_TASK_TYPE_TEXT = "task_type_text"
 S_BRIEF_KEEP = "brief_keep"
 S_BRIEF_PATH_PICK = "brief_path_pick"
 S_BRIEF_PATH = "brief_path"
+S_BRIEF_CARRY = "brief_carry"
 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_HANDOFF_STAGE_PICK = "handoff_stage_pick"
 S_EXECUTOR = "executor"
 S_CRITIC_PICK = "critic_pick"
 S_CRITIC_TEXT = "critic_text"
@@ -334,6 +345,11 @@ class WizardState:
     critic: str = ""
     critic_pending_text: bool = False
 
+    # release-handoff: PR 로 내보낼 범위. mode 는 stages 선택의 파생값이다 —
+    # whole-task = 빈 stages(whole-task 검증 기반 단일 PR), stage-group = csv.
+    handoff_mode: str = ""  # "" | "whole-task" | "stage-group"
+    handoff_stages: str = ""  # csv ("2,3"), whole-task 면 ""
+
     # resume: 직전 run-inputs 재사용 여부 (None=미응답, True=재사용, False=재입력)
     reuse_previous: Optional[bool] = None
 
@@ -767,6 +783,11 @@ def _base_ref_required(state: WizardState) -> bool:
     return state.task_type != "final-verification" and state.reuse_worktree is False
 
 
+def _brief_resolved(state: WizardState) -> bool:
+    """brief 입력이 끝났는가. release-handoff 는 brief 가 없는 phase 라 항상 True."""
+    return bool(state.brief_path) or state.task_type == "release-handoff"
+
+
 def _base_ref_ready(state: WizardState) -> bool:
     return not _base_ref_required(state) or S_BASE_REF_PICK in state.answered
 
@@ -1215,6 +1236,23 @@ def _build_task_type(state: WizardState) -> Prompt:
                   echo_template=t["echo_template"])
 
 
+def _carry_in_existing_brief(state: WizardState) -> str:
+    """downstream task-type 이 등록된 brief 를 자동 carry-in 한다. 주입한 경로(또는 '')."""
+    if state.task_type in _BRIEF_ENTRY_TASK_TYPES:
+        return ""
+    if state.task_type == "release-handoff":
+        return ""  # prepare 가 검증 보고서 인용 input 문서를 자동 생성한다
+    if state.brief_path or not state.existing_brief_path:
+        return ""
+    p = Path(state.existing_brief_path)
+    if not p.is_absolute():
+        p = Path(state.project_root) / p
+    if not p.is_file():
+        return ""  # manifest 경로가 깨졌으면 brief_carry 단계가 처리한다
+    state.brief_path = state.existing_brief_path
+    return state.brief_path
+
+
 def _apply_task_type(state: WizardState, value: str) -> str:
     if value not in TASK_TYPE_VALUES:
         raise WizardError(
@@ -1222,6 +1260,11 @@ def _apply_task_type(state: WizardState, value: str) -> str:
             f"(expected one of: {', '.join(TASK_TYPE_VALUES)})"
         )
     state.task_type = value
+    # brief_carry 의 "entry phase 로 전환" 이 task-type 을 리셋한 뒤 submit() 이
+    # brief_carry 를 answered 로 되돌려 놓는다 — task-type 을 다시 고르는 시점에
+    # 퍼지해야 downstream 재선택 시 carry 단계가 다시 나온다.
+    state.answered = [a for a in state.answered if a != S_BRIEF_CARRY]
+    carried = _carry_in_existing_brief(state)
     state.profile_workers = _load_profile_workers(
         Path(state.workspace_root), value
     )
@@ -1231,6 +1274,8 @@ def _apply_task_type(state: WizardState, value: str) -> str:
     # 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)
+    if carried:
+        return f"task-type: {value}\nbrief (carry-in): {carried}"
     return f"task-type: {value}"
 
 
@@ -1357,6 +1402,37 @@ def _submit_brief_path(state: WizardState, value: str) -> Optional[str]:
     return f"brief: {p}"
 
 
+BRIEF_CARRY_SWITCH_ENTRY = "__switch_entry__"
+BRIEF_CARRY_ABORT = "__abort__"
+
+
+def _build_brief_carry(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "brief_carry", task_type=state.task_type)
+    return Prompt(
+        step=S_BRIEF_CARRY, kind="pick",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items()],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_brief_carry(state: WizardState, value: str) -> Optional[str]:
+    t = _p(state.workspace_root, "brief_carry", task_type=state.task_type)
+    if value == BRIEF_CARRY_SWITCH_ENTRY:
+        _reset_from(state, S_TASK_TYPE)
+        return t["echo_variants"]["switch_entry"]
+    if value == PICK_TYPE_CUSTOM:
+        state.brief_path_pending_text = True
+        return None
+    if value == BRIEF_CARRY_ABORT:
+        state.aborted = True
+        return t["echo_variants"]["abort"]
+    raise WizardError(
+        f"expected '{BRIEF_CARRY_SWITCH_ENTRY}', {PICK_TYPE_CUSTOM!r}, "
+        f"or '{BRIEF_CARRY_ABORT}', got: {value!r}"
+    )
+
+
 def _build_base_ref_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "base_ref_pick")
     recommended_suffix = t["options"].get("_RECOMMENDED_SUFFIX", "")
@@ -1602,6 +1678,105 @@ def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
     return f"stage: {answer}"
 
 
+def _handoff_msgs(state: WizardState) -> dict:
+    """handoff_stage_pick 의 JSON 텍스트 묶음 (label 미사용 조회용)."""
+    return _p(state.workspace_root, "handoff_stage_pick", blocked="")
+
+
+def _resolve_handoff_plan(state: WizardState) -> Path:
+    """release-handoff 의 approved plan 을 질문 없이 자동 해소한다.
+
+    plan 미존재/미승인은 사용자가 고칠 대상이 아니라 라이프사이클 선행 단계
+    누락이므로 picker 대신 안내 메시지로 즉시 실패한다."""
+    if state.approved_plan_path:
+        return Path(state.approved_plan_path)
+    t = _handoff_msgs(state)
+    latest = _latest_implementation_planning_report(state)
+    if latest is None:
+        raise WizardError(t["errors"]["no_plan"])
+    p, fully_approved = _classify_approved_plan(
+        str(latest), Path(state.project_root))
+    if not fully_approved:
+        raise WizardError(t["errors"]["plan_not_approved"].format(plan=p))
+    state.approved_plan_path = str(p)
+    return p
+
+
+def _handoff_eligibility(state: WizardState) -> list:
+    """stage 별 PR 자격 — okstra_ctl.handoff 의 SSOT 판정을 그대로 재사용한다."""
+    from okstra_ctl.handoff import compute_eligibility
+    from okstra_ctl.run import _parse_stage_map_into_ctx
+    from okstra_ctl.consumers import read_consumers
+    plan = _resolve_handoff_plan(state)
+    stage_map = _parse_stage_map_into_ctx(str(plan))
+    if not stage_map:
+        raise WizardError(
+            _handoff_msgs(state)["errors"]["no_stage_map"].format(plan=plan))
+    rows = read_consumers(plan.resolve().parents[1])
+    return compute_eligibility(stage_map, rows)
+
+
+def _latest_whole_task_fv_accepted(state: WizardState) -> str:
+    """accepted whole-task final-verification 보고서 경로 — handoff 모듈 SSOT 위임."""
+    from okstra_ctl.handoff import latest_whole_task_fv_accepted
+    return latest_whole_task_fv_accepted(
+        state.project_root, state.project_id, state.task_group, state.task_id)
+
+
+def _build_handoff_stage_pick(state: WizardState) -> Prompt:
+    elig = _handoff_eligibility(state)
+    eligible = [e for e in elig if e["eligible"]]
+    blocked = [e for e in elig if not e["eligible"]]
+    whole_task_report = _latest_whole_task_fv_accepted(state)
+    msgs = _handoff_msgs(state)
+    blocked_summary = ("; ".join(
+        f"stage {e['stage']} ({', '.join(e['reasons'])})" for e in blocked)
+        or msgs["labels"]["blocked_none"])
+    if not eligible and not whole_task_report:
+        raise WizardError(
+            msgs["errors"]["nothing_eligible"].format(blocked=blocked_summary))
+    t = _p(state.workspace_root, "handoff_stage_pick", blocked=blocked_summary)
+    options: list[Option] = []
+    if whole_task_report:
+        options.append(_opt(WHOLE_TASK_STAGE, t["labels"]["whole_task"]))
+    stage_label = t["labels"]["stage"]
+    for e in eligible:
+        deps = ", ".join(str(d) for d in e["depends_on"]) or "-"
+        options.append(_opt(str(e["stage"]),
+                            stage_label.format(stage=e["stage"], deps=deps)))
+    return Prompt(
+        step=S_HANDOFF_STAGE_PICK, kind="pick", multi=True,
+        label=t["label"], options=options,
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_handoff_stage_pick(state: WizardState, value: str) -> Optional[str]:
+    t = _handoff_msgs(state)
+    picks = [v.strip() for v in (value or "").split(",") if v.strip()]
+    if not picks:
+        raise WizardError(t["errors"]["none_selected"])
+    if WHOLE_TASK_STAGE in picks:
+        if len(picks) > 1:
+            raise WizardError(t["errors"]["whole_task_exclusive"])
+        if not _latest_whole_task_fv_accepted(state):
+            raise WizardError(t["errors"]["whole_task_missing"])
+        state.handoff_mode = "whole-task"
+        state.handoff_stages = ""
+        return t["echo_variants"]["whole_task"]
+    eligible = {str(e["stage"]) for e in _handoff_eligibility(state)
+                if e["eligible"]}
+    bad = [p for p in picks if p not in eligible]
+    if bad:
+        raise WizardError(t["errors"]["not_eligible"].format(
+            bad=", ".join(bad), eligible=", ".join(sorted(eligible))))
+    nums = sorted({int(p) for p in picks})
+    state.handoff_mode = "stage-group"
+    state.handoff_stages = ",".join(str(n) for n in nums)
+    return t["echo_variants"]["stage_group"].format(
+        stages=state.handoff_stages)
+
+
 def _suggest_latest_final_report(state: WizardState) -> str:
     """task 의 모든 phase runs 디렉토리에서 가장 최근 final-report-*.md 의 relpath 를 반환.
 
@@ -2250,6 +2425,8 @@ def _submit_pr_template_scope(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_branch_confirm(state: WizardState) -> Prompt:
+    if state.task_type == "implementation":
+        return _build_branch_confirm_impl_stage(state)
     decision = preview_worktree_decision(
         project_root=Path(state.project_root),
         project_id=state.project_id,
@@ -2270,6 +2447,7 @@ def _build_branch_confirm(state: WizardState) -> Prompt:
         branch=decision.branch or "(none)",
         base_ref=decision.base_ref or "(HEAD)",
         path=decision.path,
+        task_key=f"{state.task_group}/{state.task_id}",
     )
     # Pass the computed label as `summary` so _p's placeholder interpolation works.
     t = _p(state.workspace_root, "branch_confirm", summary=label)
@@ -2282,6 +2460,43 @@ def _build_branch_confirm(state: WizardState) -> Prompt:
                   options=options, echo_template=t["echo_template"])
 
 
+def _build_branch_confirm_impl_stage(state: WizardState) -> Prompt:
+    """implementation 은 stage 격리로 동작하므로 task-key 디렉터리가 아니라
+    이번 run 이 실제로 사용할 stage worktree 관점으로 미리보기를 보여준다."""
+    raw = _load_wizard_root(state.workspace_root)["steps"]["branch_confirm"]
+    task_key = f"{state.task_group}/{state.task_id}"
+    stage = (state.selected_stage or "auto").strip()
+    if stage == "auto":
+        parent_dir = compute_worktree_path(
+            project_id=state.project_id, task_group_segment=state.task_group,
+            task_id_segment=state.task_id,
+        )
+        label = raw["labels"]["impl_stage_auto"].format(
+            task_key=task_key, path=str(parent_dir),
+        )
+        decision_status = "new"
+    else:
+        decision = preview_stage_worktree_decision(
+            project_id=state.project_id, task_group_segment=state.task_group,
+            task_id_segment=state.task_id, work_category="",
+            stage_number=int(stage),
+        )
+        key = "impl_stage_reuse" if decision.status == "reused" else "impl_stage_new"
+        label = raw["labels"][key].format(
+            stage=stage, path=decision.path, branch=decision.branch,
+            task_key=task_key,
+        )
+        decision_status = decision.status
+    t = _p(state.workspace_root, "branch_confirm", summary=label)
+    opts = t["options"]
+    options = [_opt("proceed", opts["proceed"])]
+    if decision_status == "new" and _base_ref_required(state):
+        options.append(_opt("edit", opts["edit"]))
+    options.append(_opt("abort", opts["abort"]))
+    return Prompt(step=S_BRANCH_CONFIRM, kind="pick", label=label,
+                  options=options, echo_template=t["echo_template"])
+
+
 def _submit_branch_confirm(state: WizardState, value: str) -> Optional[str]:
     if value == "edit":
         _reset_from(state, S_BASE_REF_PICK)
@@ -2364,16 +2579,40 @@ STEPS: list[Step] = [
                             and s.task_group_pending_text),
          build=_build_task_group_text, submit=_submit_task_group_text,
          owns=("task_group", "task_group_pending_text")),
+    # 신규 task 흐름 순서: task-group → task-type → (entry 면 brief) → task-id.
+    # brief 는 entry phase 전용 입력이므로 task-type 이 정해진 뒤에만 물을 수 있다.
+    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_group))
+                            and S_TASK_TYPE not in s.answered),
+         build=_build_task_type, submit=_submit_task_type,
+         owns=("task_type", "profile_workers", "profile_optional_workers",
+               "reuse_worktree")),
+    Step(S_TASK_TYPE_TEXT,
+         applies=lambda s: (S_TASK_TYPE in s.answered
+                            and not s.task_type
+                            and S_TASK_TYPE_TEXT not in s.answered),
+         build=_build_task_type_text, submit=_submit_task_type_text,
+         owns=("task_type", "profile_workers", "profile_optional_workers",
+               "reuse_worktree")),
+    Step(S_BRIEF_KEEP,
+         applies=lambda s: (not s.is_new_task
+                            and s.task_type in _BRIEF_ENTRY_TASK_TYPES
+                            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",)),
     Step(S_BRIEF_PATH_PICK,
          applies=lambda s: (
              not s.brief_path
              and not s.brief_path_pending_text
              and S_BRIEF_PATH_PICK not in s.answered
+             and S_TASK_TYPE in s.answered
+             and s.task_type in _BRIEF_ENTRY_TASK_TYPES
              and (
-                 (s.is_new_task is True and bool(s.task_group))
+                 s.is_new_task is True
                  or (s.is_new_task is False
-                     and S_TASK_TYPE in s.answered
-                     and bool(s.task_type)
                      and (s.keep_existing_brief is False
                           or not s.existing_brief_path))
              )
@@ -2385,49 +2624,39 @@ STEPS: list[Step] = [
                             and S_BRIEF_PATH not in s.answered,
          build=_build_brief_path, submit=_submit_brief_path,
          owns=("brief_path", "task_group_suggestion", "task_id_suggestion")),
+    # downstream task-type 인데 carry-in 할 brief 가 없을 때의 fallback.
+    # release-handoff 는 brief 자체가 없는 phase 라 대상에서 빠진다.
+    Step(S_BRIEF_CARRY,
+         applies=lambda s: (S_TASK_TYPE in s.answered
+                            and bool(s.task_type)
+                            and s.task_type not in _BRIEF_ENTRY_TASK_TYPES
+                            and s.task_type != "release-handoff"
+                            and not s.brief_path
+                            and not s.brief_path_pending_text),
+         build=_build_brief_carry, submit=_submit_brief_carry,
+         owns=("brief_path_pending_text",)),
     Step(S_TASK_ID,
          applies=lambda s: (bool(s.is_new_task)
-                            and bool(s.brief_path)
                             and bool(s.task_group)
+                            and _brief_resolved(s)
                             and not s.task_id
                             and not s.task_id_pending_text),
          build=_build_task_id, submit=_submit_task_id,
          owns=("task_id", "task_id_pending_text")),
     Step(S_TASK_ID_TEXT,
          applies=lambda s: (bool(s.is_new_task)
-                            and bool(s.brief_path)
                             and bool(s.task_group)
+                            and _brief_resolved(s)
                             and not s.task_id
                             and s.task_id_pending_text),
          build=_build_task_id_text, submit=_submit_task_id_text,
          owns=("task_id", "task_id_pending_text")),
-    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", "profile_optional_workers",
-               "reuse_worktree")),
-    Step(S_TASK_TYPE_TEXT,
-         applies=lambda s: (S_TASK_TYPE in s.answered
-                            and not s.task_type
-                            and S_TASK_TYPE_TEXT not in s.answered),
-         build=_build_task_type_text, submit=_submit_task_type_text,
-         owns=("task_type", "profile_workers", "profile_optional_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
-                            and bool(s.task_type)),
-         build=_build_brief_keep, submit=_submit_brief_keep,
-         owns=("keep_existing_brief",)),
     Step(S_BASE_REF_PICK,
          applies=lambda s: (S_TASK_TYPE in s.answered
                             and _base_ref_required(s)
                             and S_BASE_REF_PICK not in s.answered
-                            and bool(s.brief_path)),
+                            and _brief_resolved(s)
+                            and (not s.is_new_task or bool(s.task_id))),
          build=_build_base_ref_pick, submit=_submit_base_ref_pick,
          owns=("base_ref", "base_ref_pending_text")),
     Step(S_BASE_REF_TEXT,
@@ -2468,6 +2697,13 @@ STEPS: list[Step] = [
                             and S_STAGE_PICK not in s.answered),
          build=_build_stage_pick, submit=_submit_stage_pick,
          owns=("selected_stage",)),
+    Step(S_HANDOFF_STAGE_PICK,
+         applies=lambda s: (s.task_type == "release-handoff"
+                            and bool(s.task_group)
+                            and bool(s.task_id)
+                            and S_HANDOFF_STAGE_PICK not in s.answered),
+         build=_build_handoff_stage_pick, submit=_submit_handoff_stage_pick,
+         owns=("handoff_mode", "handoff_stages", "approved_plan_path")),
     Step(S_EXECUTOR,
          applies=lambda s: (s.task_type == "implementation"
                             and bool(s.approved_plan_path)
@@ -2644,7 +2880,8 @@ 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:
+    # release-handoff 는 brief 가 없다 — prepare 가 검증 보고서 인용 input 을 생성한다.
+    if not s.brief_path and s.task_type != "release-handoff":
         return False
     if _base_ref_required(s) and S_BASE_REF_PICK not in s.answered:
         return False
@@ -2656,6 +2893,9 @@ def _identity_ready(s: WizardState) -> bool:
     if s.task_type == "implementation":
         if not s.executor:
             return False
+    if (s.task_type == "release-handoff"
+            and S_HANDOFF_STAGE_PICK not in s.answered):
+        return False
     return True
 
 
@@ -2708,6 +2948,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "base_ref_pending_text": False, "approved_plan_path": "",
     "approved_plan_pending_text": False,
     "selected_stage": "auto",
+    "handoff_mode": "", "handoff_stages": "",
     "executor": "", "critic": "", "critic_pending_text": False,
     "reuse_previous": None,
     "use_defaults": None, "workers_override": "",
@@ -2873,6 +3114,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "critic": state.critic,
         "approved-plan": state.approved_plan_path,
         "stage": stage,
+        "stages": state.handoff_stages,
         "base-ref": base_ref,
         "workers": workers,
         "directive": state.directive,
@@ -2896,8 +3138,13 @@ def confirmation_block(state: WizardState) -> str:
     lines.append(f"  brief         : {state.brief_path or '(none)'}")
     if state.task_type == "final-verification":
         lines.append("  base-ref      : (selected stage worktree)")
+    elif state.task_type == "implementation" and state.reuse_worktree:
+        lines.append(_msg(state.workspace_root, "confirmation",
+                          "base_ref_stage_isolated"))
     elif state.reuse_worktree:
-        lines.append("  base-ref      : (reusing existing worktree)")
+        lines.append(_msg(state.workspace_root, "confirmation",
+                          "base_ref_reuse_task_dir",
+                          task_key=f"{state.task_group}/{state.task_id}"))
     else:
         lines.append(f"  base-ref      : {state.base_ref}")
     if state.task_type == "implementation":
@@ -2934,6 +3181,16 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  stage         : {stage}")
     if state.clarification_response_path:
         lines.append(f"  clarification : {state.clarification_response_path}")
+    if state.task_type == "release-handoff" and state.handoff_mode:
+        scope = (
+            _msg(state.workspace_root, "confirmation",
+                 "handoff_scope_whole_task")
+            if state.handoff_mode == "whole-task"
+            else _msg(state.workspace_root, "confirmation",
+                      "handoff_scope_stage_group",
+                      stages=state.handoff_stages)
+        )
+        lines.append(f"  handoff scope : {scope}")
     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)

package/runtime/python/okstra_ctl/worktree.py

@@ -195,6 +195,41 @@ def preview_worktree_decision(
     )
 
 
+def preview_stage_worktree_decision(
+    *,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    stage_number: int,
+) -> "WorktreeDecision":
+    """Side-effect-free: what provision_stage_worktree WOULD do (reuse vs new).
+
+    Mirrors provision_stage_worktree's registry-reuse branch exactly. A "new"
+    decision carries no base_ref — the stage base commit is resolved later by
+    the prepare flow from the stage's dependency anchors.
+    """
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    existing = worktree_registry.lookup(
+        safe_project, safe_group, safe_task, stage_number=stage_number)
+    if existing is not None and existing.status == "active":
+        return WorktreeDecision(
+            status="reused", path=existing.worktree_path,
+            branch=existing.branch, base_ref=existing.base_ref,
+        )
+    return WorktreeDecision(
+        status="new",
+        path=str(compute_worktree_path(
+            project_id=safe_project, task_group_segment=safe_group,
+            task_id_segment=safe_task, stage_number=stage_number)),
+        branch=compute_branch_name(
+            work_category=work_category, task_id_segment=safe_task,
+            stage_number=stage_number),
+    )
+
+
 def _safe_segment(value: str) -> str:
     """Sanitise a single path/branch segment.
 

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

@@ -47,7 +47,7 @@ The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag
 - `kind: "done"` → input collection finished; move to Step 5.
 - `kind: "aborted"` → the user picked 중단; the wizard is terminally cancelled. Tell the user on one short line that the run setup was aborted, delete the state file (`rm` with the literal path), and stop this skill — do NOT call `render-args` or `render-bundle` (the wizard rejects `render-args` on an aborted state).
 
-The `branch_confirm` step (shown just before `confirm`) is a normal `pick` step and is rendered the same way — no special handling needed. Its options always include `중단` (abort); `base-ref 다시 고르기` (edit) appears only when a new worktree would be created.
+The `branch_confirm` step (shown just before `confirm`) is a normal `pick` step and is rendered the same way — no special handling needed. Its options always include `중단` (abort); `base-ref 다시 고르기` (edit) appears only when a new branch would be created from the user-chosen base-ref. For `implementation` runs the wizard previews the **stage worktree** this run will actually use (not the task-key directory); render its label verbatim.
 
 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.
 
@@ -121,9 +121,10 @@ That is the entire interactive flow. The wizard handles:
 
 - new-vs-existing task split (남은 작업 — `workStatus != done` — 최신순 3개 추천 + 직접 입력), task-group / task-id slug validation (각각 최근 후보 3개 추천 + 직접 입력),
 - task-type pick (추천 3개 — `nextRecommendedPhase` recommended / 현재 phase 재실행 / 라이프사이클 다음 단계 — + 직접 입력; 직접 입력은 후속 `text` 단계에서 전체 task-type 화이트리스트로 검증),
-- brief path after task-group selection (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing tasks),
+- brief path — **entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 질문** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing entry tasks). downstream task-type 은 manifest 의 brief 를 자동 carry-in 하고, 등록 brief 가 없으면 `brief_carry` 3-옵션(entry 전환 추천 / 직접 입력 / 중단)이 뜬다. `release-handoff` 는 brief 단계가 아예 없다 — prepare 가 검증 보고서 인용 input 문서를 생성한다,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick,
+- `release-handoff`-only sub-flow: approved plan 자동 해소 후 `handoff_stage_pick` 멀티선택 — eligible stage 묶음(stage-group) 또는 전체 task(accepted whole-task 검증 보고서 존재 시) 선택; 결과는 render-args 의 `stages` 키(csv, whole-task 면 빈 값)로 나간다,
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
@@ -166,6 +167,7 @@ okstra render-bundle \
   --critic       "<args.critic>" \
   --approved-plan "<args.approved-plan>" \
   --stage        "<args.stage>" \
+  --stages       "<args.stages>" \
   --base-ref     "<args.base-ref>" \
   --workers      "<args.workers>" \
   --directive    "<args.directive>" \

package/runtime/templates/reports/release-handoff-input.template.md

@@ -25,11 +25,15 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Source Verification Report
 
-- Path (project-relative) to the `final-verification` final-report whose verdict authorises this handoff:
-- Verbatim quoted `Verdict Token` row from that report's `## 7. Final Verdict` table (MUST have value `accepted`):
-- Run timestamp of that final-verification run:
+- Mode: `{{HANDOFF_MODE}}`
+- Stages: `{{HANDOFF_STAGES}}`
+- Reports (one row per cited `final-verification` final-report; every Verdict Token MUST be `accepted`):
 
-> If this section is empty or cites a `Verdict Token` value other than `accepted`, the lead MUST end the run immediately and route back to `final-verification`. Release-handoff never operates on `conditional-accept` or `blocked` outcomes.
+| Stage | Report path (project-relative) | Verdict Token |
+|---|---|---|
+{{HANDOFF_SOURCE_REPORTS}}
+
+> This section is generated by `okstra render-bundle` from the consumers ledger (`verified` rows) / the latest accepted whole-task report — the lead re-confirms each cited report's `Verdict Token` and MUST end the run immediately (route back to `final-verification`) if any token is not `accepted`. Release-handoff never operates on `conditional-accept` or `blocked` outcomes.
 
 ## Working-Tree Snapshot (filled at run start)
 
@@ -83,5 +87,5 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Conversion Note
 
-- This input can be used as the release-handoff brief before creating `okstra-task-brief.md`.
-- Reuse the same `Task Group` and `Task ID` as the originating implementation / final-verification runs so the handoff stays attached to the same task history.
+- This document is generated by `okstra render-bundle --task-type release-handoff` and serves as the run's input in place of a task brief (briefs belong to entry phases only).
+- It reuses the same `Task Group` and `Task ID` as the originating implementation / final-verification runs so the handoff stays attached to the same task history.

package/src/render-bundle.mjs

@@ -18,7 +18,15 @@ Usage:
     [--gemini-model <m>] [--report-writer-model <m>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
-    [--pr-template-path <path>]   # release-handoff only
+    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>]
+
+  --stage             implementation / final-verification only
+  --stages            release-handoff only: PR stage bundle csv (empty = whole-task)
+  --pr-template-path  release-handoff only
+
+release-handoff takes NO --task-brief (briefs belong to entry phases) —
+prepare generates the run's input document from the cited verification
+reports instead.
 
 All flags pass through unchanged to \`python3 -m okstra_ctl.run\`. The
 shim auto-supplies \`--workspace-root\` (from \`okstra paths --field workspace\`)