okstra 0.69.0 → 0.71.0

package/runtime/python/okstra_ctl/wizard.py

@@ -88,6 +88,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 +237,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 +343,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 +781,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
 
@@ -779,6 +798,54 @@ def _stage_auto_allowed(state: WizardState) -> bool:
     return state.task_type == "implementation"
 
 
+def _parse_stage_objects(state: WizardState) -> list:
+    """승인 plan 의 Stage Map stage 객체 목록. validator 의 _parse_stage_map 재사용.
+    `_build_stage_pick` 과 `_whole_task_allowed` 가 공유한다."""
+    import importlib.util as _ilu
+    import sys as _sys
+    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
+    validator_path = (Path(state.workspace_root) / "validators"
+                      / "validate-implementation-plan-stages.py")
+    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
+    if spec is None or spec.loader is None:
+        raise WizardError(f"cannot load stage validator at {validator_path}")
+    mod = _ilu.module_from_spec(spec)
+    _sys.modules["_ip_stage_v_wizard"] = mod
+    try:
+        spec.loader.exec_module(mod)
+        stages, _errs = mod._parse_stage_map(plan_text)
+    finally:
+        _sys.modules.pop("_ip_stage_v_wizard", None)
+    return stages
+
+
+def _done_stage_numbers(state: WizardState) -> set:
+    """approved plan 을 소비한 implementation run 들의 consumers.jsonl 에서
+    done 처리된 stage 번호 집합. git 호출 없음 — 파일 읽기만(prepare 와 동일 SSOT)."""
+    if not state.approved_plan_path:
+        return set()
+    from .consumers import (read_consumers, backfill_done_from_carry,
+                            latest_done_by_stage)
+    plan_run_root = Path(state.approved_plan_path).resolve().parents[1]
+    backfill_done_from_carry(plan_run_root)
+    rows = read_consumers(plan_run_root)
+    return set(latest_done_by_stage(rows).keys())
+
+
+def _whole_task_allowed(state: WizardState) -> bool:
+    """final-verification 이고 Stage Map 의 모든 stage 가 done 일 때만 True.
+    위저드는 done 만 본다 — 머지/clean/active 는 prepare 게이트가 강제한다."""
+    if state.task_type != "final-verification":
+        return False
+    if not state.approved_plan_path:
+        return False
+    stages = _parse_stage_objects(state)
+    if not stages:
+        return False
+    done = _done_stage_numbers(state)
+    return all(s.stage_number in done for s in stages)
+
+
 def _existing_task_brief(project_root: Path, task_key: str) -> str:
     """Read taskBriefPath from manifest for an existing task. Empty if none."""
     root = find_task_root(project_root, task_key)
@@ -1167,6 +1234,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(
@@ -1174,6 +1258,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
     )
@@ -1183,6 +1272,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}"
 
 
@@ -1309,6 +1400,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", "")
@@ -1358,6 +1480,7 @@ _REUSE_LAST_TOKEN = "__reuse_last__"
 _SIBLINGS_TOKEN = "__siblings__"
 _LATEST_REPORT_TOKEN = "__latest_report__"
 _PROJECT_DEFAULT_TOKEN = "__project_default__"
+WHOLE_TASK_STAGE = "__whole_task__"
 
 
 def _list_implementation_planning_reports(
@@ -1493,37 +1616,31 @@ def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str
 
 def _build_stage_pick(state: WizardState) -> Prompt:
     """Parse the Stage Map from the approved plan and build the stage picker."""
-    import importlib.util as _ilu
-    import sys as _sys
     t = _p(state.workspace_root, "stage_pick")
-    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
-    validator_path = (
-        Path(state.workspace_root) / "validators"
-        / "validate-implementation-plan-stages.py"
-    )
-    spec = _ilu.spec_from_file_location("_ip_stage_v_wizard", str(validator_path))
-    if spec is None or spec.loader is None:
-        raise WizardError(f"cannot load stage validator at {validator_path}")
-    mod = _ilu.module_from_spec(spec)
-    _sys.modules["_ip_stage_v_wizard"] = mod
-    try:
-        spec.loader.exec_module(mod)
-        stages, _errs = mod._parse_stage_map(plan_text)
-    finally:
-        _sys.modules.pop("_ip_stage_v_wizard", None)
+    stages = _parse_stage_objects(state)
+    is_fv = state.task_type == "final-verification"
     label = (
         t.get("label_final_verification", t["label"])
-        if state.task_type == "final-verification"
-        else t["label"]
+        if is_fv else t["label"]
     )
+    done = _done_stage_numbers(state) if is_fv else set()
     options = []
     if _stage_auto_allowed(state):
         options.append(_opt("auto", t["options"]["auto"]))
+    if _whole_task_allowed(state):
+        options.append(_opt(WHOLE_TASK_STAGE, t["options"]["whole_task"]))
     for s in stages:
         depends = ",".join(map(str, s.depends_on)) or "(none)"
+        suffix = ""
+        if is_fv:
+            mark = (t["options"]["done_mark"]
+                    if s.stage_number in done
+                    else t["options"]["undone_mark"])
+            suffix = f"  {mark}"
         options.append(_opt(
             str(s.stage_number),
-            f"{s.stage_number}: {s.title}  [depends-on: {depends} | steps: {s.step_count}]",
+            f"{s.stage_number}: {s.title}  "
+            f"[depends-on: {depends} | steps: {s.step_count}]{suffix}",
         ))
     return Prompt(
         step=S_STAGE_PICK, kind="pick",
@@ -1541,17 +1658,123 @@ def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
             raise WizardError(
                 "final-verification requires an explicit stage number"
             )
+    elif answer == WHOLE_TASK_STAGE:
+        if not _whole_task_allowed(state):
+            raise WizardError(
+                "whole-task verification requires final-verification "
+                "with all stages done"
+            )
     else:
         try:
             int(answer)
         except ValueError:
             raise WizardError(
-                f"answer must be 'auto' or a stage number, got {answer!r}"
+                f"answer must be 'auto', whole-task, or a stage number, "
+                f"got {answer!r}"
             )
     state.selected_stage = answer
     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 를 반환.
 
@@ -2314,16 +2537,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))
              )
@@ -2335,49 +2582,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,
@@ -2418,6 +2655,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)
@@ -2594,7 +2838,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
@@ -2606,6 +2851,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
 
 
@@ -2658,6 +2906,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": "",
@@ -2797,11 +3046,14 @@ def render_args(state: WizardState) -> dict[str, str]:
     if state.task_type == "implementation":
         stage = state.selected_stage or "auto"
     elif state.task_type == "final-verification":
-        if not state.selected_stage or state.selected_stage == "auto":
+        if state.selected_stage == WHOLE_TASK_STAGE:
+            stage = ""  # prepare 가 빈 stage 를 whole-task 로 해석
+        elif not state.selected_stage or state.selected_stage == "auto":
             raise WizardError(
                 "final-verification requires an explicit stage number"
             )
-        stage = state.selected_stage
+        else:
+            stage = state.selected_stage
     else:
         stage = ""
     pr_template = (
@@ -2820,6 +3072,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,
@@ -2872,12 +3125,25 @@ def confirmation_block(state: WizardState) -> str:
     if state.task_type in _STAGE_SCOPED_TASK_TYPES:
         lines.append(f"  approved-plan : {state.approved_plan_path}")
         stage = (
-            state.selected_stage
-            or ("auto" if state.task_type == "implementation" else "(not selected)")
+            _msg(state.workspace_root, "confirmation", "stage_whole_task")
+            if state.selected_stage == WHOLE_TASK_STAGE
+            else (state.selected_stage
+                  or ("auto" if state.task_type == "implementation"
+                      else "(not selected)"))
         )
         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/skills/okstra-convergence/SKILL.md

@@ -572,7 +572,7 @@ Promoted blockers enter `## 5.8 Acceptance Blockers`; since `accepted` requires
 
 ### State
 
-Critic output lives at `runs/final-verification/worker-results/<provider>-critic-final-verification-<seq>.md`. The convergence state `config.critic` summary (see §"Coverage critic pass") records `mode: "acceptance-devils-advocate"`, `candidatesProposed`, `confirmedBlockers`, `downgradedToResidual` (optional v1.2 fields; readers treat absence as null).
+Critic output lives in the run's `worker-results/` directory (`runs/final-verification/worker-results/` for whole-task verification, `runs/final-verification/stage-<N>/worker-results/` for single-stage), filename `<provider>-critic-final-verification-<seq>.md`. The convergence state `config.critic` summary (see §"Coverage critic pass") records `mode: "acceptance-devils-advocate"`, `candidatesProposed`, `confirmedBlockers`, `downgradedToResidual` (optional v1.2 fields; readers treat absence as null).
 
 ## Output
 

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

@@ -299,7 +299,7 @@ B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / t
 
 C. **`timeline.json` (specific run):** for a specific date or run, read `.okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
 
-D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
+D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Stage-isolated runs (`implementation`, single-stage `final-verification`) keep their reports one level deeper at `runs/<task-type-segment>/stage-<N>/reports/` — scan those subdirectories too; seq is independent per stage. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
 
 ### report.2 — Confirm existence
 

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

@@ -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\`)