okstra 0.201.3 → 0.204.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,12 @@ 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)
 
 
 class HandoffError(Exception):
@@ -37,7 +38,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,14 +49,11 @@ 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,
@@ -68,50 +66,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 +85,132 @@ 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):
-            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
-            # 실패 경로와 동일 처리) — 여기서 직접 정리하지 않는다.
+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"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"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 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)
+    return {"ok": True, "release_base": base_branch, "stages": planned}
 
 
 def _remove_task_worktree(main_wt, target: str) -> Optional[str]:
@@ -273,70 +231,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"`.
-
-    `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`,
+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.
+
+    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 +255,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 +311,11 @@ 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 는
-    보고서가 실제로 실은 토큰이다."""
+    막는다. 기록되는 verdict 는 보고서가 실제로 실은 토큰이다."""
     try:
         data = load_owned_object(Path(data_json), artifact="final verification report")
     except JsonBoundaryError as exc:
@@ -478,15 +367,15 @@ def _record_verified_target(plan_run_root: Path, stage: int, key: str,
         raise HandoffError(str(exc)) from exc
 
 
-def record_pr(*, plan_run_root, stages: List[int], branch: str,
+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 +392,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>
+  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 +425,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 +444,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 +455,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 +463,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 +482,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},

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -177,6 +177,15 @@ def claim_implementation_stage_run(
             candidate_base=head_sha,
             project_root=Path(task_worktree_path),
             plan_run_root=plan_run_root,
+            # 선행이 둘 이상인 stage 는 그 선행들만 담은 브랜치에서 시작한다.
+            # 그 브랜치를 만들 수 있는 것은 이 경로뿐이고, run.py 가 이미 task-key
+            # provision 락을 쥐고 있어 원시연산은 락을 다시 잡지 않는다.
+            identity=stage_targets.StageWorktreeIdentity(
+                project_id=inp.project_id,
+                task_group=task_group_segment,
+                task_id=task_id_segment,
+                work_category=inp.work_category,
+            ),
         )
     except stage_targets.StageTargetError as exc:
         raise _as_implementation_stage_error(exc) from exc