okstra 0.202.0 → 0.205.0

package/runtime/python/okstra_ctl/handoff.py

@@ -1,8 +1,8 @@
-"""release-handoff stage-group 모드의 강제 지점.
+"""release-handoff 의 강제 지점 — stage 하나가 PR 하나다.
 
-자격 판정(eligible) · 수집 브랜치 생성+머지(assemble) · verified/pr 행 기록을
+자격 판정(eligible) · stage 별 PR head/base 계산(pr-plan) · verified/pr 행 기록을
 단일 모듈로 강제한다. lead 는 `okstra handoff <sub>` 로 호출만 한다.
-설계: docs/superpowers/specs/2026-06-10-stage-group-handoff-design.md
+설계: .project-docs/specs/2026-09-24-release-handoff-per-stage-pr-design.md
 """
 
 from __future__ import annotations
@@ -10,13 +10,13 @@ from __future__ import annotations
 import json
 import subprocess
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional
 
 from . import consumers, stage_targets, worktree_registry
-from .final_report_paths import final_report_markdown_path, final_report_data_path
+from .final_report_paths import final_report_data_path
 from .handoff_verification import (
     VerificationEvidenceError, load_latest_verification,
-    require_finished_verification, verification_row_is_current,
+    verification_row_is_current,
 )
 from .paths import RunRef
 from .json_boundary import JsonBoundaryError, load_owned_object
@@ -25,11 +25,16 @@ from .release_gate import (
     release_handoff_allowed,
     verdict_token,
 )
+from .stage_integrate import (IntegrateError, MergeBranchConflict,
+                              ensure_stage_merge_branch)
 from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
-from .worktree import (compute_branch_name, compute_worktree_path,
-                       main_worktree_path, is_dirty_excluding_okstra,
-                       nested_worktree_excludes, is_ancestor, merge_branch,
-                       remove_worktree_force, MergeError, _git)
+from .worktree import (compute_branch_name, main_worktree_path,
+                       is_dirty_excluding_okstra, nested_worktree_excludes,
+                       is_ancestor, remove_worktree_force, _git)
+
+
+SINGLE_STAGE_SCOPE = "single-stage"
+WHOLE_TASK_SCOPE = "whole-task"
 
 
 class HandoffError(Exception):
@@ -37,7 +42,7 @@ class HandoffError(Exception):
 
 
 class HandoffConflict(Exception):
-    """stage 간 merge 충돌 — exit 2, 충돌 경로 동봉."""
+    """선행 stage 들 사이의 merge 충돌 — exit 2, 충돌 경로 동봉."""
 
     def __init__(self, stage: int, branch: str, paths: List[str]):
         self.stage = stage
@@ -48,18 +53,18 @@ class HandoffConflict(Exception):
             f"{', '.join(paths)}")
 
 
-def group_id_for(stages: List[int]) -> str:
-    return "g" + "-".join(str(n) for n in sorted(stages))
-
-
 def compute_eligibility(stage_map: List[Dict[str, Any]],
                         rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-    """stage 별 PR 가능 여부와 차단 사유. 의존 폐포는 선택 집합의 속성이라
-    여기서는 판정하지 않는다 (assemble 의 check_dependency_closure 가 담당)."""
+    """stage 별 PR 가능 여부와 차단 사유. 의존이 어느 브랜치로 내려앉는지는
+    선택 집합과 origin 의 상태가 정하므로 여기서는 판정하지 않는다
+    (`pr_plan` 의 base 해소가 담당)."""
     eligibility = stage_targets.stage_lifecycle_snapshot_from_rows(
         stage_map,
         rows,
     ).handoff_eligibility()
+    # 재구현된 stage 의 커밋 동일성은 `consumers.verified_accepted_stages` 가
+    # 이미 본다(`handoff_eligibility` 가 그 집합을 읽는다). 여기 남는 판정은
+    # "그 승인 행이 가리키는 검증 run 이 아직 최신인가" 하나다.
     last = {row["stage"]: row for row in rows if row.get("status") == "verified"}
     for item in eligibility:
         if item["eligible"] and not verification_row_is_current(last.get(item["stage"], {})):
@@ -68,50 +73,6 @@ def compute_eligibility(stage_map: List[Dict[str, Any]],
     return eligibility
 
 
-def latest_whole_task_fv_release_ready(project_root, project_id: str,
-                                       task_group: str, task_id: str) -> str:
-    """release-handoff 로 넘어가도 되는 whole-task 검증 보고서 경로. 없으면 ''.
-
-    최신 실행을 먼저 고르고 대상·보고서·완료 판정을 확인한다.
-    실패한 최신 실행을 건너뛰어 과거 통과 보고서를 사용하지 않는다."""
-    from okstra_project.state import find_task_root
-    root = find_task_root(Path(project_root),
-                          f"{project_id}:{task_group}:{task_id}")
-    if root is None:
-        return ""
-    try:
-        report, manifest, data = load_latest_verification(
-            RunRef.from_task_root(root, "final-verification").run_dir)
-        require_finished_verification(manifest, data)
-        if manifest.get("taskKey") != f"{project_id}:{task_group}:{task_id}":
-            return ""
-        return str(report)
-    except VerificationEvidenceError:
-        # expected-miss: 최신 검증 미완료·차단은 전체 인계 선택지가 없는 정상 분기다.
-        return ""
-
-
-def check_dependency_closure(
-    selected: List[int],
-    stage_map: List[Dict[str, Any]],
-    done_by_stage: Dict[int, Dict[str, Any]],
-    is_merged_to_base: Callable[[str], bool],
-) -> List[Tuple[int, int]]:
-    """선택 집합의 의존 폐포 위반 목록 [(stage, 미충족 선행)].
-    선행이 같은 그룹에 선택됐거나 이미 base 에 머지된 경우만 허용."""
-    sel = set(selected)
-    by_n = {s["stage_number"]: s for s in stage_map}
-    violations = []
-    for n in sorted(selected):
-        for d in by_n[n]["depends_on"]:
-            if d in sel:
-                continue
-            head = (done_by_stage.get(d) or {}).get("head_commit", "")
-            if not head or not is_merged_to_base(head):
-                violations.append((n, d))
-    return violations
-
-
 def _run_git(args: List[str], cwd, check: bool = True) -> subprocess.CompletedProcess:
     """worktree._git(공용 러너) 위에 check=True 시 HandoffError 변환만 얹는다."""
     r = _git(Path(cwd), *args)
@@ -131,128 +92,275 @@ def _require_eligible(stage_map, rows, stages) -> Dict[int, Dict[str, Any]]:
     return elig
 
 
-def _require_closure(stages, stage_map, done, project_root, base_branch) -> None:
-    def merged(commit: str) -> bool:
-        return is_ancestor(project_root, commit, f"origin/{base_branch}")
-    violations = check_dependency_closure(stages, stage_map, done, merged)
-    if violations:
-        lines = [
-            f"stage {n} depends on stage {d} which is neither selected nor "
-            f"merged into origin/{base_branch} — include stage {d} in the "
-            "group or PR-merge it first"
-            for n, d in violations
-        ]
-        raise HandoffError("dependency closure violated:\n" + "\n".join(lines))
+def _branch_exists(project_root, branch: str) -> bool:
+    return _git(Path(project_root), "rev-parse", "--verify", "--quiet",
+                f"refs/heads/{branch}").returncode == 0
 
 
-def _reuse_existing(entry, stages, done, project_root) -> Dict[str, Any]:
-    head = _run_git(["rev-parse", entry.branch], project_root).stdout.strip()
-    for n in stages:
-        h = (done.get(n) or {}).get("head_commit", "")
-        if not is_ancestor(project_root, h, head):
+def _stage_branch(work_category: str, task_id: str, stage: int) -> str:
+    return compute_branch_name(work_category=work_category,
+                               task_id_segment=task_id, stage_number=stage)
+
+
+def _done_head(done: Dict[int, Dict[str, Any]], stage: int) -> str:
+    head = (done.get(stage) or {}).get("head_commit", "")
+    if not head:
+        raise HandoffError(
+            f"stage {stage} has no done row with head_commit in "
+            "consumers.jsonl — finish that implementation stage first")
+    return head
+
+
+def _merge_base_for(*, project_root, project_id, task_group, task_id,
+                    work_category, heads, anchor_base):
+    """선행들을 담은 바닥 브랜치. 원시연산은 잠금 없이 돌므로 여기서 task-key
+    락을 잡는다 — implementation 경로는 이미 그 락 안에서 직접 부른다.
+    기존 브랜치에 빠진 commit 이 있으면 거부한다: 그 브랜치는 이미 열린 PR 의
+    base 일 수 있고, 말없이 옮기면 리뷰어가 본 diff 가 바뀐다."""
+    from okstra_project.dirs import okstra_home
+
+    from .locks import worktree_provision_mutex
+
+    try:
+        with worktree_provision_mutex(okstra_home(), project_id, task_group,
+                                      task_id):
+            return ensure_stage_merge_branch(
+                project_root=project_root, project_id=project_id,
+                task_group=task_group, task_id=task_id,
+                work_category=work_category, heads=heads,
+                anchor_base=anchor_base)
+    except MergeBranchConflict as exc:
+        raise HandoffConflict(stage=exc.stage, branch=exc.branch,
+                              paths=exc.paths) from exc
+    except IntegrateError as exc:
+        raise HandoffError(str(exc)) from exc
+
+
+def _resolve_stage_base(
+    *, stage: int, deps: List[int], selected: List[int], pr_covered: set,
+    done: Dict[int, Dict[str, Any]], project_root, base_branch: str,
+    work_category: str, task_id: str, project_id: str, task_group: str,
+    anchor_base: str,
+) -> Dict[str, Any]:
+    """한 stage 의 PR base. 이미 릴리스 base 에 들어간 선행은 base 를 올리지
+    않으므로 제외하고, 남은 선행의 개수가 모양을 정한다."""
+    live = [d for d in sorted(deps)
+            if not is_ancestor(project_root, _done_head(done, d),
+                               f"origin/{base_branch}")]
+    if not live:
+        commit = _run_git(["rev-parse", f"origin/{base_branch}"],
+                          project_root).stdout.strip()
+        return {"base_kind": "release-base", "base_branch": base_branch,
+                "base_commit": commit, "base_stages": []}
+
+    undelivered = [d for d in live if d not in selected and d not in pr_covered]
+    if undelivered:
+        raise HandoffError(
+            f"stage {stage} depends on stage(s) {undelivered}, which are "
+            f"neither selected in this run nor already PR'd nor merged into "
+            f"origin/{base_branch} — a stacked PR needs its base branch to "
+            "exist on origin, so include them in this handoff or merge them "
+            "first")
+
+    if len(live) == 1:
+        dep = live[0]
+        branch = _stage_branch(work_category, task_id, dep)
+        if not _branch_exists(project_root, branch):
             raise HandoffError(
-                f"collector branch {entry.branch} exists but stage {n} head "
-                f"{h} is not merged into it — remove the branch/worktree and "
-                "the registry group key, then retry")
-    return {"ok": True, "reused": True, "group_id": group_id_for(stages),
-            "branch": entry.branch, "worktree_path": entry.worktree_path,
-            "head": head, "stages": sorted(stages), "merge_commits": []}
-
-
-def _cleanup_group(project_root, wt_path, branch, project_id, task_group,
-                   task_id, gid) -> None:
-    remove_worktree_force(project_root, wt_path)
-    _run_git(["branch", "-D", branch], project_root, check=False)
-    worktree_registry.release(project_id, task_group, task_id, group_id=gid)
-
-
-def _merge_stages(wt_path, stages, work_category, task_id, project_root,
-                  project_id, task_group, gid, branch, done) -> List[str]:
-    """선택 stage 들을 수집 브랜치에 위상순 --no-ff 머지한다.
-
-    머지 대상은 `-sN` 브랜치 tip 이 아니라 기록된 done.head_commit 이다 —
-    consumers 의 done.head_commit 은 git-reconcile 로 브랜치 tip 과 다른 commit
-    일 수 있어, 브랜치 tip 을 머지하면 done 시점 이후의 갈라진 변경을 끌어들인다.
-    stage_branch 는 충돌 식별용으로만 산출한다(머지 대상 아님)."""
-    merge_commits = []
-    for n in sorted(stages):
-        stage_branch = compute_branch_name(
-            work_category=work_category, task_id_segment=task_id,
-            stage_number=n)
-        done_commit = (done.get(n) or {}).get("head_commit", "")
-        try:
-            conflicts = merge_branch(wt_path, done_commit, no_ff=False)
-        except MergeError as exc:
-            # cleanup 은 assemble 의 except Exception 이 수행한다(worktree-add
-            # 실패 경로와 동일 처리) — 여기서 직접 정리하지 않는다.
+                f"stage {stage} needs branch {branch} (stage {dep}) as its PR "
+                "base, but that branch no longer exists in this repository")
+        return {"base_kind": "stage", "base_branch": branch,
+                "base_commit": _done_head(done, dep), "base_stages": [dep]}
+
+    merged = _merge_base_for(
+        project_root=project_root, project_id=project_id,
+        task_group=task_group, task_id=task_id, work_category=work_category,
+        heads={n: _done_head(done, n) for n in live}, anchor_base=anchor_base)
+    return {"base_kind": "merge-base", "base_branch": merged.branch,
+            "base_commit": merged.commit, "base_stages": list(merged.stages),
+            "base_merge_commits": list(merged.merge_commits),
+            "base_branch_created": merged.created}
+
+
+def _local_tip(project_root, branch: str) -> str:
+    """로컬 브랜치의 현재 커밋. 없으면 빈 문자열."""
+    return _git(Path(project_root), "rev-parse", "--verify", "--quiet",
+                f"refs/heads/{branch}").stdout.strip()
+
+
+def _remote_tips(project_root, branches: List[str]) -> Dict[str, str]:
+    """origin 이 지금 가진 브랜치와 커밋. 없는 브랜치는 키가 없다.
+
+    `ls-remote` 로 묻는다 — 비교하려고 ref 를 쓰지 않고, 없는 브랜치를 fetch
+    하려다 실패하지도 않는다.
+    """
+    if not branches:
+        return {}
+    res = _git(Path(project_root), "ls-remote", "--heads", "origin", *branches)
+    if res.returncode != 0:
+        raise HandoffError(f"cannot read origin branch state: {res.stderr.strip()}")
+    tips: Dict[str, str] = {}
+    for line in res.stdout.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1].startswith("refs/heads/"):
+            tips[parts[1][len("refs/heads/"):]] = parts[0]
+    return tips
+
+
+def _branch_worktree(project_root, branch: str) -> Optional[Path]:
+    """그 브랜치를 체크아웃해 둔 워크트리. 없으면 None.
+
+    체크아웃된 브랜치는 `git branch -f` 로 옮길 수 없으므로, fast-forward 는 그
+    워크트리 안에서 해야 한다.
+    """
+    res = _git(Path(project_root), "worktree", "list", "--porcelain")
+    if res.returncode != 0:
+        return None
+    current: Optional[Path] = None
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            current = Path(line[len("worktree "):].strip())
+        elif line.strip() == f"branch refs/heads/{branch}":
+            return current
+    return None
+
+
+def _fast_forward_local(project_root, branch: str, remote_commit: str) -> None:
+    """로컬 브랜치를 origin 의 커밋으로 fast-forward 한다.
+
+    호출자가 조상 관계를 이미 확인했으므로 내용이 사라질 수 없다. 체크아웃
+    상태면 그 워크트리에서 `merge --ff-only` 로, 아니면 ref 를 옮긴다.
+    """
+    _run_git(["fetch", "origin", branch], project_root)
+    holder = _branch_worktree(project_root, branch)
+    if holder is None:
+        _run_git(["branch", "-f", branch, remote_commit], project_root)
+        return
+    if is_dirty_excluding_okstra(holder):
+        raise HandoffError(
+            f"branch {branch} is behind origin and is checked out in {holder}, "
+            "which has uncommitted changes — commit or stash them so the "
+            "branch can be fast-forwarded to origin")
+    _run_git(["merge", "--ff-only", remote_commit], holder)
+
+
+# 계획 행이 부르는 브랜치를 실제로 푸시할 순서. merge-base 는 그것을 base 로
+# 삼는 PR 보다 먼저 origin 에 있어야 한다(프로필 §"branch push" 와 같은 순서).
+def _plan_branch_order(planned: List[Dict[str, Any]]) -> List[tuple[str, str]]:
+    ordered: List[tuple[str, str]] = []
+    seen: set[str] = set()
+    for row in planned:
+        if row["base_kind"] == "merge-base" and row["base_branch"] not in seen:
+            seen.add(row["base_branch"])
+            ordered.append((row["base_branch"], row["base_commit"]))
+    for row in planned:
+        if row["head_branch"] not in seen:
+            seen.add(row["head_branch"])
+            ordered.append((row["head_branch"], row["head_commit"]))
+    return ordered
+
+
+def _reconcile_with_origin(
+    project_root, planned: List[Dict[str, Any]],
+) -> tuple[List[Dict[str, Any]], List[str]]:
+    """PR 이 올라앉을 브랜치를 origin 기준으로 맞춘다.
+
+    PR 의 head 와 base 는 GitHub 이 **이름으로 origin 에서** 찾는다. 계획이
+    로컬 ref 만 보고 짜이던 동안, origin 의 같은 이름이 다른 커밋에 있어도
+    계획은 그 사실을 몰랐다 — push 단계에서 거절되거나, PR 의 diff 가 계획서의
+    커밋과 달랐다.
+
+    네 가지 상태를 가른다. origin 에 없거나 뒤처져 있으면 push 가 해결하므로
+    무엇을 어떤 순서로 올려야 하는지만 계획에 싣는다. origin 이 앞서 있으면
+    로컬을 fast-forward 하고, 그 추가 커밋이 이 run 이 검증한 범위 밖이라는
+    사실을 경고로 남긴다. 갈라져 있으면 거절한다 — 그 상태를 push 로 넘기는
+    길은 force 뿐이고, 그건 열린 PR 의 리뷰 커밋을 지운다.
+    """
+    order = _plan_branch_order(planned)
+    tips = _remote_tips(project_root, [branch for branch, _ in order])
+    push_plan: List[Dict[str, Any]] = []
+    warnings: List[str] = []
+    for branch, recorded in order:
+        local = _local_tip(project_root, branch)
+        if not local:
             raise HandoffError(
-                f"stage {n} ({stage_branch}) 머지 실패(내용 충돌 아님): {exc}"
-            ) from exc
-        if conflicts is not None:
-            _cleanup_group(project_root, wt_path, branch, project_id,
-                           task_group, task_id, gid)
-            raise HandoffConflict(stage=n, branch=stage_branch, paths=conflicts)
-        merge_commits.append(
-            _run_git(["rev-parse", "HEAD"], wt_path).stdout.strip())
-    return merge_commits
-
-
-def assemble(*, project_root, plan_run_root, stage_map, stages, base_branch,
-             work_category, project_id, task_group, task_id) -> Dict[str, Any]:
-    """수집 브랜치를 만들고 선택 stage 브랜치들을 머지한다. 멱등."""
+                f"branch {branch} does not exist in this repository — there is "
+                "nothing to open a PR from")
+        # tip 이 기록된 커밋보다 앞선 것은 정상 상태다 — git-reconcile 이 done
+        # 이후의 커밋을 그 브랜치에 남긴다. 담기지 않은 것만 거절한다: 검증한
+        # 커밋이 브랜치에 없으면 그 PR 은 검증된 것을 나르지 않는다.
+        if recorded and local != recorded:
+            if not is_ancestor(project_root, recorded, local):
+                raise HandoffError(
+                    f"branch {branch} is at {local}, which does not contain the "
+                    f"commit this task's ledger verified for it ({recorded}) — "
+                    "the branch was rewritten, so its PR would not carry the "
+                    "verified work")
+            warnings.append(
+                f"branch {branch} is ahead of the commit this run verified "
+                f"({recorded} -> {local}); the commits it adds are outside the "
+                "verified scope")
+        remote = tips.get(branch)
+        if remote is None:
+            action = "create"
+        elif remote == local:
+            action = "up-to-date"
+        elif is_ancestor(project_root, remote, local):
+            action = "fast-forward"
+        elif is_ancestor(project_root, local, remote):
+            _fast_forward_local(project_root, branch, remote)
+            action = "up-to-date"
+            warnings.append(
+                f"branch {branch} was behind origin ({local} -> {remote}) and "
+                "was fast-forwarded to it; the commits origin adds are outside "
+                f"what this run verified ({recorded or local})")
+        else:
+            raise HandoffError(
+                f"branch {branch} and origin/{branch} have diverged (local "
+                f"{local}, origin {remote}) — only a force push could deliver "
+                "this branch, which would drop the commits origin holds")
+        push_plan.append({"branch": branch, "commit": local, "action": action})
+    return push_plan, warnings
+
+
+def pr_plan(*, project_root, plan_run_root, stage_map, stages, base_branch,
+            work_category, project_id, task_group, task_id) -> Dict[str, Any]:
+    """선택한 stage 각각의 PR head/base 를 정하고, 필요한 선행 머지 브랜치를
+    만든다. PR 은 stage 당 하나이고 head 는 그 stage 의 스택 브랜치다 — 커밋
+    히스토리를 접지 않으므로 이 경로는 stage 브랜치를 고쳐 쓰지 않는다."""
     stages = sorted(set(stages))
     rows = consumers.read_consumers(Path(plan_run_root))
     _require_eligible(stage_map, rows, stages)
     _run_git(["fetch", "origin", base_branch], project_root)
     done = consumers.latest_done_by_stage(rows)
-    _require_closure(stages, stage_map, done, project_root, base_branch)
+    pr_covered = consumers.pr_covered_stages(rows)
+    by_n = {s["stage_number"]: s for s in stage_map}
+    anchor_base = worktree_registry.get_implementation_base(
+        project_id, task_group, task_id) or ""
 
-    base_commit = worktree_registry.get_implementation_base(
-        project_id, task_group, task_id)
-    if not base_commit:
-        raise HandoffError(
-            "implementation_base_commit not recorded in worktree registry — "
-            "run at least one implementation stage first")
-
-    gid = group_id_for(stages)
-    existing = worktree_registry.lookup(
-        project_id, task_group, task_id, group_id=gid)
-    if existing and existing.status == "active":
-        return _reuse_existing(existing, stages, done, project_root)
-
-    branch = compute_branch_name(work_category=work_category,
-                                 task_id_segment=task_id, group_id=gid)
-    wt_path = compute_worktree_path(
-        project_id=project_id, task_group_segment=task_group,
-        task_id_segment=task_id, group_id=gid)
-    # reserve 충돌(이미 등록된 task-key/branch)은 RuntimeError 로 오는데, 이를
-    # HandoffError 로 감싸 main 의 envelope(JSON+exit1)로 흘려보낸다. 감싸지
-    # 않으면 raw traceback 으로 빠진다. cleanup 을 거는 worktree-add try 와
-    # 분리해 두어, 예약 생성 실패 시 자신이 만들지도 않은 예약을 되돌리지 않는다.
-    try:
-        worktree_registry.reserve(
-            project_id=project_id, task_group=task_group, task_id=task_id,
-            worktree_path=str(wt_path), branch=branch, base_ref=base_commit,
-            phase="release-handoff", group_id=gid, stages=stages)
-    except RuntimeError as exc:
-        raise HandoffError(str(exc))
-    try:
-        _run_git(["worktree", "add", "-b", branch, str(wt_path), base_commit],
-                 project_root)
-        merge_commits = _merge_stages(wt_path, stages, work_category, task_id,
-                                      project_root, project_id, task_group, gid,
-                                      branch, done)
-    except HandoffConflict:
-        raise  # _merge_stages 가 이미 _cleanup_group 으로 예약·worktree 를 되돌림
-    except Exception:
-        # worktree add 실패 등 비-충돌 경로 — 예약이 orphan 으로 남지 않도록 역전
-        _cleanup_group(project_root, wt_path, branch, project_id, task_group,
-                       task_id, gid)
-        raise
-    head = merge_commits[-1] if merge_commits else base_commit
-    return {"ok": True, "reused": False, "group_id": gid, "branch": branch,
-            "worktree_path": str(wt_path), "head": head, "stages": stages,
-            "merge_commits": merge_commits}
+    planned: List[Dict[str, Any]] = []
+    for n in stages:
+        head_branch = _stage_branch(work_category, task_id, n)
+        if not _branch_exists(project_root, head_branch):
+            raise HandoffError(
+                f"stage {n} branch {head_branch} does not exist in this "
+                "repository — it was deleted, so there is nothing to open a "
+                "PR from")
+        row = {
+            "stage": n,
+            "head_branch": head_branch,
+            "head_commit": _done_head(done, n),
+            **_resolve_stage_base(
+                stage=n, deps=list(by_n[n]["depends_on"]), selected=stages,
+                pr_covered=pr_covered, done=done, project_root=project_root,
+                base_branch=base_branch, work_category=work_category,
+                task_id=task_id, project_id=project_id, task_group=task_group,
+                anchor_base=anchor_base),
+        }
+        planned.append(row)
+    push_plan, warnings = _reconcile_with_origin(project_root, planned)
+    return {"ok": True, "release_base": base_branch, "stages": planned,
+            "push_plan": push_plan, "warnings": warnings}
 
 
 def _remove_task_worktree(main_wt, target: str) -> Optional[str]:
@@ -273,70 +381,17 @@ def _remove_task_worktree(main_wt, target: str) -> Optional[str]:
     return None
 
 
-def _runs_in_progress(project_root, task_group, task_id, *,
-                      exclude_task_type: str = "release-handoff") -> List[str]:
-    """이 task 에서 지금 실행 중인 run — run 매니페스트 `status == "in-progress"`.
+def _local_checkout_target(project_id, task_group, task_id,
+                           stage: int) -> tuple:
+    """Resolve (branch, worktree_path) for a stage's local checkout. The
+    returned path is "" only when the row carries no `worktree_path`; teardown
+    does not clear it, so a torn-down stage yields a stale path to a directory
+    that no longer exists. The caller must probe the path before acting on it.
 
-    `exclude_task_type` 의 run 은 세지 않는다: local checkout 을 부르는 것은
-    release-handoff run 의 리드 자신이므로 그 run 은 점유가 아니다. 읽을 수 없는
-    매니페스트는 판정을 열어 두지 않고 그대로 오류로 올린다 — 점유 여부를 모르는
-    채 워크트리를 지우는 것보다 한 번 더 묻는 편이 낫다.
-    """
-    from .paths import task_runs_dir
-
-    runs = task_runs_dir(Path(project_root), task_group, task_id)
-    if not runs.is_dir():
-        return []
-    live: List[str] = []
-    for manifest in sorted(runs.rglob("run-manifest-*.json")):
-        if manifest.parent.name != "manifests":
-            continue
-        try:
-            data = load_owned_object(manifest, artifact="run manifest")
-        except JsonBoundaryError as exc:
-            raise HandoffError(
-                f"run 매니페스트를 읽을 수 없어 점유 여부를 판정할 수 없습니다 "
-                f"({manifest}): {exc}") from exc
-        if not isinstance(data, dict) or data.get("status") != "in-progress":
-            continue
-        if data.get("taskType") == exclude_task_type:
-            continue
-        live.append(f"{data.get('taskType')} seq {manifest.stem.rsplit('-', 1)[-1]}")
-    return live
-
-
-def _local_checkout_target(project_root, project_id, task_group, task_id,
-                           stage: Optional[int]) -> Tuple[str, str]:
-    """Resolve (branch, worktree_path) for a local checkout. `stage` selects
-    the stage-key row; None selects the task-key row. The returned path is ""
-    only when the row carries no `worktree_path`; teardown does not clear it,
-    so a torn-down stage yields a stale path to a directory that no longer
-    exists. The caller must probe the path before acting on it.
-
-    Occupancy is judged differently for the two row kinds. A stage row's
-    `status == "active"` is a live reservation: done-time release flips it
-    (`consumers._release_stage_occupancy_keeping_branch`,
+    A stage row's `status == "active"` is a live reservation: done-time release
+    flips it (`consumers._release_stage_occupancy_keeping_branch`,
     `stage_integrate._teardown_stage`), and `list_active_stage_numbers` feeds the
-    stage resolver, so an active stage row means a run holds it. The task-key
-    row has no such lifecycle — `reserve` writes `active` when the worktree is
-    created and nothing but this checkout ever releases it (observed 2026-09-07,
-    fontsninja-v3-site dev-10626: the row stayed `active` from 09-02 through five
-    completed phases, so whole-task local checkout could never be reached and
-    its "retry after the run ends" message could never come true). For the
-    task-key row the occupancy question is therefore asked of the runs
-    themselves: another run of this task still `in-progress` refuses the
-    checkout; the release-handoff run that is asking does not count."""
-    if stage is None:
-        entry = worktree_registry.lookup(project_id, task_group, task_id)
-        if not entry or not entry.branch or not entry.worktree_path:
-            raise HandoffError(
-                "task-key worktree registry 엔트리가 없습니다 — local checkout 대상 없음")
-        live = _runs_in_progress(project_root, task_group, task_id)
-        if live:
-            raise HandoffError(
-                "task 워크트리를 다른 run 이 사용 중입니다 (in-progress: "
-                f"{', '.join(live)}) — 그 run 이 끝난 뒤 다시 시도하세요")
-        return entry.branch, entry.worktree_path
+    stage resolver, so an active stage row means a run holds it."""
     row = worktree_registry.get_stage_row(project_id, task_group, task_id, stage)
     if not row or not row.get("branch"):
         raise HandoffError(
@@ -350,13 +405,12 @@ def _local_checkout_target(project_root, project_id, task_group, task_id,
 
 
 def local_checkout(*, project_root, project_id, task_group, task_id,
-                   stage: Optional[int] = None) -> Dict[str, Any]:
-    """okstra 워크트리를 제거하고 대상 브랜치를 메인 워크트리에 checkout 한다
-    (브랜치 보존). stage 를 주면 그 stage 의 스택 브랜치가, 주지 않으면 whole-task
-    브랜치가 대상이다. 메인·대상 워크트리가 dirty 면 거부. base 브랜치는
+                   stage: int) -> Dict[str, Any]:
+    """그 stage 의 okstra 워크트리를 제거하고 stage 브랜치를 메인 워크트리에
+    checkout 한다(브랜치 보존). 메인·대상 워크트리가 dirty 면 거부. base 브랜치는
     건드리지 않는다."""
     branch, wt_path = _local_checkout_target(
-        project_root, project_id, task_group, task_id, stage)
+        project_id, task_group, task_id, stage)
     main_wt = main_worktree_path(Path(project_root))
     if is_dirty_excluding_okstra(main_wt):
         raise HandoffError(
@@ -407,26 +461,20 @@ def _impl_task_key_for(rows: List[Dict[str, Any]], stage: int) -> str:
     return row.get("impl_task_key", "")
 
 
-def _impl_task_key_for_any(rows: List[Dict[str, Any]], stages: List[int]) -> str:
-    """task 를 식별하는 키 — stages 중 done 행이 있는 아무 stage 에서나 승계한다.
-    PR 기록은 특정 stage 의 done 에 묶일 이유가 없으므로 최저 stage 가 비어도
-    다른 stage 의 done 으로 충족한다."""
-    done = consumers.latest_done_by_stage(rows)
-    for n in sorted(stages):
-        row = done.get(n)
-        if row:
-            return row.get("impl_task_key", "")
-    raise HandoffError(
-        f"none of stages {sorted(stages)} have a done row in consumers.jsonl — "
-        "finish at least one implementation stage first")
-
-
 def record_verified(*, plan_run_root, stage: int, report_path: str,
                     data_json) -> Dict[str, Any]:
-    """릴리스로 넘어갈 수 있는 단독-stage 판정만 기록. data.json 의
-    taskType/scope/verdict 를 검증해 lead 가 임의 보고서를 verified 로 올리는 것을
-    막는다. 통과 조건은 whole-task 와 같고(`release_gate`), 기록되는 verdict 는
-    보고서가 실제로 실은 토큰이다."""
+    """릴리스로 넘어갈 수 있는 검증 판정을 stage 별로 기록.
+
+    범위는 둘 다 받는다. 단독-stage 판정은 그 stage 만의 근거이고, 전체 task
+    판정은 자기 `stageReports` 에 실린 stage 들의 근거다 — 검증 대상이 tip
+    stage 의 브랜치이므로(설계 결정 7) 그 브랜치는 완료된 다른 stage 의 커밋을
+    담고 있고, 그 사실은 커밋 조상 관계로 확인한다. 전체 task 로 검증한 task 가
+    stage 별 자격을 얻을 길이 없던 동안, 모든 stage 를 검증해 놓고도 stage 마다
+    단독 검증을 다시 돌려야 PR 을 열 수 있었다(2026-09-24, dev-10860).
+
+    data.json 의 taskType/scope/verdict 를 검증해 lead 가 임의 보고서를
+    verified 로 올리는 것을 막는다. 기록되는 verdict 는 보고서가 실제로 실은
+    토큰이다."""
     try:
         data = load_owned_object(Path(data_json), artifact="final verification report")
     except JsonBoundaryError as exc:
@@ -434,10 +482,10 @@ def record_verified(*, plan_run_root, stage: int, report_path: str,
     if (data.get("header") or {}).get("taskType") != "final-verification":
         raise HandoffError("data.json is not a final-verification report")
     scope = data.get("verificationScope")
-    if scope != "single-stage":
+    if scope not in (SINGLE_STAGE_SCOPE, WHOLE_TASK_SCOPE):
         raise HandoffError(
-            f"record-verified requires verificationScope single-stage, "
-            f"got {scope!r}")
+            f"record-verified requires verificationScope "
+            f"{SINGLE_STAGE_SCOPE} or {WHOLE_TASK_SCOPE}, got {scope!r}")
     token = verdict_token(data)
     if not release_handoff_allowed(data):
         blocking = blocking_condition_ids(data)
@@ -450,17 +498,23 @@ def record_verified(*, plan_run_root, stage: int, report_path: str,
             f"condition declares `blocksReleaseHandoff: false` — {detail}")
     rows = consumers.read_consumers(Path(plan_run_root))
     key = _impl_task_key_for(rows, stage)
-    _record_verified_target(Path(plan_run_root), stage, key, report_path, Path(data_json), data)
+    _record_verified_target(Path(plan_run_root), stage, key, report_path,
+                            Path(data_json), data, rows)
     return {"ok": True, "stage": stage, "report_path": report_path}
 
 
 def _record_verified_target(plan_run_root: Path, stage: int, key: str,
-                            report_path: str, data_json: Path, data: dict) -> None:
+                            report_path: str, data_json: Path, data: dict,
+                            rows: List[Dict[str, Any]]) -> None:
     """검증한 실행과 커밋을 입증한 뒤 같은 원장 잠금 안에서 기록한다."""
     try:
         ref = RunRef.from_run_dir(Path(plan_run_root).resolve()).sibling("final-verification")
-        stage_ref = RunRef.from_task_root(ref.task_root, ref.task_type, stage=stage)
-        latest, manifest, verified_data = load_latest_verification(stage_ref.run_dir)
+        scope = str(data.get("verificationScope") or "")
+        # 전체 task 검증은 stage 범위 run 이 아니라 task 범위 run 에 산다.
+        verification_ref = RunRef.from_task_root(
+            ref.task_root, ref.task_type,
+            stage=stage if scope == SINGLE_STAGE_SCOPE else None)
+        latest, manifest, verified_data = load_latest_verification(verification_ref.run_dir)
         supplied = final_report_data_path(Path(data_json).resolve())
         report_arg = Path(report_path)
         if not report_arg.is_absolute():
@@ -468,25 +522,68 @@ def _record_verified_target(plan_run_root: Path, stage: int, key: str,
         if (latest != supplied or final_report_data_path(report_arg.resolve()) != latest
                 or manifest.get("taskKey") != key or verified_data != data):
             raise VerificationEvidenceError("report does not match latest verification of this task/stage")
+        captured = data["finalVerification"]["sourceImplementationReport"]["capturedHeadSha"]
+        extra: Dict[str, Any] = {}
+        head_commit = captured
+        if scope == WHOLE_TASK_SCOPE:
+            head_commit = _whole_task_stage_head(
+                rows, stage, captured,
+                Path(str(manifest.get("projectRoot") or "")), data)
+            extra = {"verification_scope": WHOLE_TASK_SCOPE,
+                     "verified_head_commit": captured}
         consumers.append_verified(
             Path(plan_run_root), impl_task_key=key, stage=stage, verdict=verdict_token(data),
             report_path=str(latest),
-            head_commit=data["finalVerification"]["sourceImplementationReport"]["capturedHeadSha"],
+            head_commit=head_commit,
             final_verdict=data["finalVerdict"],
+            **extra,
         )
     except ValueError as exc:
         raise HandoffError(str(exc)) from exc
 
 
-def record_pr(*, plan_run_root, stages: List[int], branch: str,
+def _whole_task_stage_head(rows: List[Dict[str, Any]], stage: int, captured: str,
+                           project_root: Path, data: dict) -> str:
+    """전체 task 검증이 이 stage 를 담았는지 확인하고, 원장에 적을 커밋을 낸다.
+
+    `stageReports` 는 보고서 자신의 주장이다. 그 stage 가 완료로 기록한 커밋이
+    검증된 head 안에 있는지까지 봐야 사실이 된다 — 검증 뒤에 갈라진 커밋은
+    검증되지 않았고, 조상 관계가 그것을 가른다.
+
+    원장에 적는 것은 검증된 head 가 아니라 이 stage 자신의 완료 커밋이다. 그
+    값이 `append_verified` 가 요구하는 "완료된 구현과 같은 커밋" 이고, PR head
+    도 그 커밋이다. 검증된 head 는 `verified_head_commit` 으로 따로 남는다.
+    """
+    reported = (data.get("finalVerification") or {}).get("stageReports") or ()
+    covered = sorted(
+        row.get("stage") for row in reported
+        if isinstance(row, dict) and isinstance(row.get("stage"), int)
+    )
+    if stage not in covered:
+        raise HandoffError(
+            f"whole-task verification does not report stage {stage} — "
+            f"it covers {covered}")
+    head = (consumers.latest_done_by_stage(rows).get(stage) or {}).get("head_commit") or ""
+    if not head:
+        raise HandoffError(
+            f"stage {stage} has no completed implementation commit to verify")
+    if head != captured and not is_ancestor(project_root, head, captured):
+        raise HandoffError(
+            f"stage {stage} completed at {head}, which the verified head "
+            f"{captured} does not contain — re-run final-verification on a "
+            "target that includes this stage")
+    return head
+
+
+def record_pr(*, plan_run_root, stage: int, branch: str, base: str,
               url: str) -> Dict[str, Any]:
-    if not stages:
-        raise HandoffError("record-pr requires at least one stage")
+    """한 stage 의 PR 기록. PR 은 stage 당 하나이므로 행도 stage 당 하나다."""
     rows = consumers.read_consumers(Path(plan_run_root))
-    key = _impl_task_key_for_any(rows, stages)
+    key = _impl_task_key_for(rows, stage)
     consumers.append_pr(Path(plan_run_root), impl_task_key=key,
-                        stages=stages, branch=branch, url=url)
-    return {"ok": True, "stages": sorted(stages), "branch": branch, "url": url}
+                        stages=[stage], branch=branch, base=base, url=url)
+    return {"ok": True, "stage": stage, "branch": branch, "base": base,
+            "url": url}
 
 
 def _parse_stages_csv(raw: str) -> List[int]:
@@ -503,19 +600,19 @@ _CLI_EPILOG = r"""JSON 출력.
 
 Usage:
   okstra handoff eligible --plan-run-root <dir> --approved-plan <md>
-  okstra handoff assemble --plan-run-root <dir> --approved-plan <md> \
+  okstra handoff pr-plan --plan-run-root <dir> --approved-plan <md> \
     --project-root <dir> --project-id <id> --task-group <g> --task-id <t> \
     --work-category <c> --stages 2,3 --base <branch>
   okstra handoff record-verified --plan-run-root <dir> --stage <N> \
-    --report-path <md> --data-json <json>
-  okstra handoff record-pr --plan-run-root <dir> --stages 2,3 \
-    --branch <b> --url <u>
+    --report-path <report> --data-json <json>
+  okstra handoff record-pr --plan-run-root <dir> --stage <N> \
+    --branch <b> --base <b> --url <u>
   okstra handoff local-checkout --project-root <dir> --project-id <id> \
-    --task-group <g> --task-id <t> [--stage <N>]
+    --task-group <g> --task-id <t> --stage <N>
 
-Exit codes: 0 ok / 1 자격·전제 위반 / 2 stage 간 merge 충돌(conflicts 동봉)
+Exit codes: 0 ok / 1 자격·전제 위반 / 2 선행 stage 간 merge 충돌(conflicts 동봉)
 """
-_CLI_DESCRIPTION = "Release-handoff stage-group \ubcf4\uc870 (\uc790\uaca9/\uc218\uc9d1/\uae30\ub85d)."
+_CLI_DESCRIPTION = "Release-handoff stage 단위 보조 (자격/PR 계획/기록)."
 
 
 def main(argv: Optional[list] = None) -> int:
@@ -536,7 +633,7 @@ def main(argv: Optional[list] = None) -> int:
     common(sp)
     sp.add_argument("--approved-plan", required=True)
 
-    sp = sub.add_parser("assemble")
+    sp = sub.add_parser("pr-plan")
     common(sp)
     sp.add_argument("--approved-plan", required=True)
     sp.add_argument("--project-root", default=".")
@@ -555,8 +652,9 @@ def main(argv: Optional[list] = None) -> int:
 
     sp = sub.add_parser("record-pr")
     common(sp)
-    sp.add_argument("--stages", required=True)
+    sp.add_argument("--stage", type=int, required=True)
     sp.add_argument("--branch", required=True)
+    sp.add_argument("--base", required=True)
     sp.add_argument("--url", required=True)
 
     sp = sub.add_parser("local-checkout")
@@ -565,7 +663,7 @@ def main(argv: Optional[list] = None) -> int:
     sp.add_argument("--project-id", required=True)
     sp.add_argument("--task-group", required=True)
     sp.add_argument("--task-id", required=True)
-    sp.add_argument("--stage", type=int, default=None)
+    sp.add_argument("--stage", type=int, required=True)
 
     a = p.parse_args(argv)
     try:
@@ -573,8 +671,8 @@ def main(argv: Optional[list] = None) -> int:
             stage_map = stage_map_records(parse_stage_map_file(Path(a.approved_plan)))
             rows = consumers.read_consumers(Path(a.plan_run_root))
             out = {"stages": compute_eligibility(stage_map, rows)}
-        elif a.cmd == "assemble":
-            out = assemble(
+        elif a.cmd == "pr-plan":
+            out = pr_plan(
                 project_root=Path(a.project_root).resolve(),
                 plan_run_root=Path(a.plan_run_root),
                 stage_map=stage_map_records(parse_stage_map_file(Path(a.approved_plan))),
@@ -592,8 +690,8 @@ def main(argv: Optional[list] = None) -> int:
                 task_id=a.task_id, stage=a.stage)
         else:
             out = record_pr(plan_run_root=Path(a.plan_run_root),
-                            stages=_parse_stages_csv(a.stages),
-                            branch=a.branch, url=a.url)
+                            stage=a.stage, branch=a.branch, base=a.base,
+                            url=a.url)
     except HandoffConflict as exc:
         print(json.dumps({"error": str(exc), "stage": exc.stage,
                           "branch": exc.branch, "conflicts": exc.paths},