okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/domain/write_policy.py

@@ -125,10 +125,11 @@ def validate_write_policy_payload(payload: Mapping[str, Any]) -> None:
     source = _mapping(payload.get("sourcePolicy"), "sourcePolicy")
     git = _mapping(payload.get("gitPolicy"), "gitPolicy")
     auxiliary = _mapping(payload.get("auxiliaryPolicy"), "auxiliaryPolicy")
-    if set(artifact) != {"allowedRoot", "allowedPaths"}:
+    if set(artifact) - {"preservedPaths"} != {"allowedRoot", "allowedPaths"}:
         raise WritePolicyError("artifactPolicy is incomplete")
     _absolute_text(artifact.get("allowedRoot"), "artifactPolicy.allowedRoot")
     _relative_paths(artifact.get("allowedPaths", ()))
+    _relative_paths(artifact.get("preservedPaths", ()))
     if source.get("mode") not in {"source-readonly", "project-mutation"}:
         raise WritePolicyError("sourcePolicy mode is invalid")
     if set(source) - {"plannedPathsDeclared"} != {

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -123,6 +123,7 @@ class MutationAuditResult:
     declared_out_of_plan_paths: tuple[str, ...] = ()
     unobserved_artifact_paths: tuple[str, ...] = ()
     external_workspace_changes: tuple[str, ...] = ()
+    violating_artifact_paths: tuple[str, ...] = ()
 
     def change_summary(self) -> dict[str, Any]:
         return {
@@ -140,6 +141,7 @@ class MutationAuditResult:
             "declaredOutOfPlanPaths": list(self.declared_out_of_plan_paths),
             "unobservedArtifactPaths": list(self.unobserved_artifact_paths),
             "externalWorkspaceChanges": list(self.external_workspace_changes),
+            "violatingArtifactPaths": list(self.violating_artifact_paths),
             "beforeDigest": self.before_digest,
             "afterDigest": self.after_digest,
         }
@@ -242,10 +244,11 @@ class ExecutionMutationAudit:
             rows,
             source_changes,
         )
-        artifact_failures, untracked_artifact_changes, switched, external = (
+        violating_artifacts, untracked_artifact_changes, switched, external = (
             _artifact_policy_failures(before, rows, artifact_changed, after=after)
         )
-        violations.extend(artifact_failures)
+        if violating_artifacts:
+            violations.append("artifact-root change exceeds batch policy union")
         worker_artifact_changes = {
             path for path in artifact_changed
             if path not in untracked_artifact_changes and path not in switched and path not in external
@@ -281,11 +284,13 @@ class ExecutionMutationAudit:
             + tuple(f"unattributed change outside assigned worktree and artifact paths: {path}"
                     for path in sorted(external))
             + _plan_change_warnings(rows, source_changes | untracked_changes,
-                                    artifact_changed, out_of_plan_edits, unobserved),
+                                    artifact_changed, out_of_plan_edits, unobserved)
+            + _linked_dependency_warnings(after.root),
             changed_artifact_paths=tuple(sorted(artifact_changed - external)),
             declared_out_of_plan_paths=tuple(out_of_plan_edits),
             unobserved_artifact_paths=tuple(sorted(unobserved)),
             external_workspace_changes=tuple(sorted(external)),
+            violating_artifact_paths=tuple(sorted(violating_artifacts)),
         )
 
 
@@ -370,6 +375,31 @@ def _audit_warnings(untracked_artifact_changes: set[str]) -> tuple[str, ...]:
     )
 
 
+def _linked_dependency_warnings(root: Path) -> tuple[str, ...]:
+    """worktree 밖을 가리키는 `node_modules` 링크를 알린다.
+
+    감사는 `node_modules` 를 보지 않으므로, 그 링크를 통한 패키지 설치가 메인
+    체크아웃의 의존성 트리를 덮어써도 흔적이 남지 않는다(2026-09-25 실측).
+    """
+    linked: list[str] = []
+    for current, directories, _ in os.walk(root, followlinks=False):
+        kept: list[str] = []
+        for name in directories:
+            path = Path(current) / name
+            if name == ".git":
+                continue
+            if name not in _INSTALLED_DEPENDENCY_DIRS:
+                kept.append(name)
+            elif path.is_symlink() and not _is_relative_to(path.resolve(), root.resolve()):
+                linked.append(f"{path.relative_to(root).as_posix()} -> {path.resolve()}")
+        directories[:] = kept
+    return tuple(
+        f"dependency tree links outside the assigned worktree: {row}; "
+        "a package install through it rewrites that target and this audit does not observe it"
+        for row in sorted(linked)
+    )
+
+
 def _branch_switch_warnings(
     before: MutationSnapshot, after: MutationSnapshot, switched: set[str],
 ) -> tuple[str, ...]:
@@ -758,8 +788,8 @@ def _artifact_policy_failures(
     changed: set[str],
     *,
     after: MutationSnapshot | None = None,
-) -> tuple[list[str], set[str], set[str], set[str]]:
-    """위반·비추적 파일·브랜치 전환·외부 작업공간 관측을 분리한다.
+) -> tuple[set[str], set[str], set[str], set[str]]:
+    """위반 경로·비추적 파일·브랜치 전환·외부 작업공간 관측을 분리한다.
 
     작업트리와 기본 체크아웃이 다르면 기본 체크아웃 소스의 변경 주체는
     전후 비교로 판단할 수 없다. 배정된 산출물 밖의 변경은 관측으로 남기고,
@@ -771,10 +801,18 @@ def _artifact_policy_failures(
         for value in snapshot.orchestrator_paths
         if _is_relative_to(Path(value), snapshot.artifact_root)
     }
+    preserved = {
+        path
+        for policy in policies
+        for path in policy.artifact_policy.get("preservedPaths", ())
+    }
     unauthorized = {
         path for path in changed
-        if not any(_is_within(path, item) for item in allowed)
-        and not any(_is_within(path, item) for item in orchestrator)
+        if path in preserved
+        or (
+            not any(_is_within(path, item) for item in allowed)
+            and not any(_is_within(path, item) for item in orchestrator)
+        )
     }
     if snapshot.artifact_root == snapshot.root:
         unauthorized = {path for path in unauthorized if _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)}
@@ -800,8 +838,7 @@ def _artifact_policy_failures(
         and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
     }
     violating = unauthorized - untracked_outside - switched - external
-    failures = ["artifact-root change exceeds batch policy union"] if violating else []
-    return failures, untracked_outside, switched, external
+    return violating, untracked_outside, switched, external
 
 
 def _branch_switch_paths(

package/runtime/python/okstra_ctl/handoff.py

@@ -1,464 +1,26 @@
-"""release-handoff 의 강제 지점 — stage 하나가 PR 하나다.
-
-자격 판정(eligible) · stage 별 PR head/base 계산(pr-plan) · verified/pr 행 기록을
-단일 모듈로 강제한다. lead 는 `okstra handoff <sub>` 로 호출만 한다.
-설계: .project-docs/specs/2026-09-24-release-handoff-per-stage-pr-design.md
-"""
-
+"""공통 검증 기록과 handoff 명령의 조립 진입점."""
 from __future__ import annotations
 
 import json
-import subprocess
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from . import consumers, stage_targets, worktree_registry
+from . import consumers
+from .handoff_error import HandoffError
 from .final_report_paths import final_report_data_path
-from .handoff_verification import (
-    VerificationEvidenceError, load_latest_verification,
-    verification_row_is_current,
-)
+from .handoff_verification import VerificationEvidenceError, load_latest_verification
 from .paths import RunRef
 from .json_boundary import JsonBoundaryError, load_owned_object
-from .release_gate import (
-    blocking_condition_ids,
-    release_handoff_allowed,
-    verdict_token,
-)
-from .stage_integrate import (IntegrateError, MergeBranchConflict,
-                              ensure_stage_merge_branch)
+from .release_gate import blocking_condition_ids, release_handoff_allowed, verdict_token
 from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
-from .worktree import (compute_branch_name, main_worktree_path,
-                       is_dirty_excluding_okstra, nested_worktree_excludes,
-                       is_ancestor, remove_worktree_force, _git)
+from .worktree import is_ancestor
 
 
 SINGLE_STAGE_SCOPE = "single-stage"
 WHOLE_TASK_SCOPE = "whole-task"
 
 
-class HandoffError(Exception):
-    """자격/전제 위반 — exit 1, actionable 메시지."""
-
-
-class HandoffConflict(Exception):
-    """선행 stage 들 사이의 merge 충돌 — exit 2, 충돌 경로 동봉."""
-
-    def __init__(self, stage: int, branch: str, paths: List[str]):
-        self.stage = stage
-        self.branch = branch
-        self.paths = paths
-        super().__init__(
-            f"merge conflict while merging stage {stage} ({branch}): "
-            f"{', '.join(paths)}")
-
-
-def compute_eligibility(stage_map: List[Dict[str, Any]],
-                        rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-    """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"], {})):
-            item["eligible"] = False
-            item["reasons"].append("verification-stale-or-unproven: re-run final-verification")
-    return eligibility
-
-
-def _run_git(args: List[str], cwd, check: bool = True) -> subprocess.CompletedProcess:
-    """worktree._git(공용 러너) 위에 check=True 시 HandoffError 변환만 얹는다."""
-    r = _git(Path(cwd), *args)
-    if check and r.returncode != 0:
-        raise HandoffError(f"git {' '.join(args)} failed: {r.stderr.strip()}")
-    return r
-
-
-def _require_eligible(stage_map, rows, stages) -> Dict[int, Dict[str, Any]]:
-    elig = {e["stage"]: e for e in compute_eligibility(stage_map, rows)}
-    unknown = [n for n in stages if n not in elig]
-    if unknown:
-        raise HandoffError(f"stages not in Stage Map: {unknown}")
-    bad = {n: elig[n]["reasons"] for n in stages if elig[n]["reasons"]}
-    if bad:
-        raise HandoffError(f"stages not eligible: {bad}")
-    return elig
-
 
-def _branch_exists(project_root, branch: str) -> bool:
-    return _git(Path(project_root), "rev-parse", "--verify", "--quiet",
-                f"refs/heads/{branch}").returncode == 0
-
-
-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 {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"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)
-    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 ""
-
-    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]:
-    """Remove an okstra worktree — task-key or stage — already confirmed clean
-    by the caller. No-op when it is already gone. Returns a human-readable
-    detail string on failure, None on success or absence.
-    Refuses while a nested worktree remains inside the target — a --force
-    removal would drop only the physical directory and leave git's and the
-    registry's stage-key admin entries orphaned."""
-    if not Path(target).exists():
-        return None  # 이미 teardown 됨 — checkout 으로 진행
-    nested = nested_worktree_excludes(target)
-    if nested:
-        return f"nested 워크트리가 남아있습니다: {', '.join(nested)}"
-    rm = remove_worktree_force(main_wt, target)
-    if rm.returncode != 0:
-        return rm.stderr.strip()
-    return None
-
-
-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."""
-    row = worktree_registry.get_stage_row(project_id, task_group, task_id, stage)
-    if not row or not row.get("branch"):
-        raise HandoffError(
-            f"stage {stage} 의 worktree registry 엔트리가 없습니다 — "
-            "local checkout 대상 없음")
-    if row.get("status") == "active":
-        raise HandoffError(
-            f"stage {stage} 를 실행 중인 런이 점유하고 있습니다 (status=active) — "
-            "그 런이 끝나 점유가 해제된 뒤 다시 시도하세요")
-    return row["branch"], row.get("worktree_path") or ""
-
-
-def local_checkout(*, project_root, project_id, task_group, task_id,
-                   stage: int) -> Dict[str, Any]:
-    """그 stage 의 okstra 워크트리를 제거하고 stage 브랜치를 메인 워크트리에
-    checkout 한다(브랜치 보존). 메인·대상 워크트리가 dirty 면 거부. base 브랜치는
-    건드리지 않는다."""
-    branch, wt_path = _local_checkout_target(
-        project_id, task_group, task_id, stage)
-    main_wt = main_worktree_path(Path(project_root))
-    if is_dirty_excluding_okstra(main_wt):
-        raise HandoffError(
-            f"메인 워크트리에 미커밋 변경이 있습니다 ({main_wt}) — "
-            "커밋/스태시 후 다시 시도하세요")
-    # 브랜치 부재는 어떤 변경 앞에서 잡는다. 종전에는 워크트리 제거·registry
-    # 해제 뒤에 `git checkout` 이 실패해(스택 브랜치를 사용자가 이미 지운 경우)
-    # 절반만 바뀐 상태가 남았다(2026-09-07 dev-10626 stage-1 실측).
-    probe = _git(Path(main_wt), "rev-parse", "--verify", "--quiet",
-                 f"refs/heads/{branch}")
-    if probe.returncode != 0:
-        raise HandoffError(
-            f"브랜치 {branch} 가 저장소에 없습니다(삭제됨) — checkout 대상이 없어 "
-            "워크트리와 registry 는 건드리지 않았습니다")
-    removed = ""
-    # The removal gate must inspect the okstra worktree being destroyed, not main.
-    # A torn-down stage leaves a stale path in its row, so probe the directory.
-    if wt_path and Path(wt_path).exists():
-        if is_dirty_excluding_okstra(wt_path):
-            raise HandoffError(
-                f"okstra 워크트리에 미커밋 변경이 있습니다 ({wt_path}) — "
-                "해당 워크트리에서 커밋/스태시 후 다시 시도하세요")
-        detail = _remove_task_worktree(main_wt, wt_path)
-        if detail is not None:
-            raise HandoffError(
-                f"워크트리 제거 실패 ({wt_path}): {detail} — "
-                "위 사유를 해소한 뒤 다시 시도하세요")
-        removed = wt_path
-    worktree_registry.release_status(project_id, task_group, task_id,
-                                     stage_number=stage)
-    co = _git(Path(main_wt), "checkout", branch)
-    if co.returncode != 0:
-        removal = f"워크트리는 제거됨({removed})" if removed else "제거된 워크트리 없음"
-        raise HandoffError(
-            f"git checkout {branch} 실패: {co.stderr.strip()} — {removal}; "
-            f"메인({main_wt})에서 수동 checkout 으로 복구하세요")
-    return {"ok": True, "branch": branch, "mainWorktreePath": str(main_wt),
-            "removedWorktree": removed, "status": "checked-out", "stage": stage}
-
-
-def _impl_task_key_for(rows: List[Dict[str, Any]], stage: int) -> str:
-    done = consumers.latest_done_by_stage(rows)
-    row = done.get(stage)
-    if not row:
-        raise HandoffError(
-            f"stage {stage} has no done row in consumers.jsonl — "
-            "finish the implementation stage first")
-    return row.get("impl_task_key", "")
 
 
 def record_verified(*, plan_run_root, stage: int, report_path: str,
@@ -497,7 +59,7 @@ def record_verified(*, plan_run_root, stage: int, report_path: str,
             "verdict must be `accepted`, or `conditional-accept` whose every "
             f"condition declares `blocksReleaseHandoff: false` — {detail}")
     rows = consumers.read_consumers(Path(plan_run_root))
-    key = _impl_task_key_for(rows, stage)
+    key = consumers.require_done_task_key(rows, stage)
     _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}
@@ -575,27 +137,6 @@ def _whole_task_stage_head(rows: List[Dict[str, Any]], stage: int, captured: str
     return head
 
 
-def record_pr(*, plan_run_root, stage: int, branch: str, base: str,
-              url: str) -> Dict[str, Any]:
-    """한 stage 의 PR 기록. PR 은 stage 당 하나이므로 행도 stage 당 하나다."""
-    rows = consumers.read_consumers(Path(plan_run_root))
-    key = _impl_task_key_for(rows, stage)
-    consumers.append_pr(Path(plan_run_root), impl_task_key=key,
-                        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]:
-    try:
-        out = sorted({int(x) for x in raw.split(",") if x.strip()})
-    except ValueError:
-        raise HandoffError(f"--stages must be a comma-separated int list, got {raw!r}")
-    if not out:
-        raise HandoffError("--stages must select at least one stage")
-    return out
-
-
 _CLI_EPILOG = r"""JSON 출력.
 
 Usage:
@@ -617,6 +158,10 @@ _CLI_DESCRIPTION = "Release-handoff stage 단위 보조 (자격/PR 계획/기록
 
 def main(argv: Optional[list] = None) -> int:
     import argparse
+    from .phases.release_handoff.operations import (
+        HandoffConflict, compute_eligibility, pr_plan, local_checkout,
+        record_pr, _parse_stages_csv,
+    )
 
     p = argparse.ArgumentParser(
         description=_CLI_DESCRIPTION,

package/runtime/python/okstra_ctl/handoff_error.py

@@ -0,0 +1,5 @@
+"""명령 조립부와 단계 정책이 공유하는 인계 오류."""
+
+
+class HandoffError(Exception):
+    """자격 또는 전제 위반으로 인계를 진행할 수 없다."""