okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/phases/release_handoff/operations.py

@@ -0,0 +1,446 @@
+"""단계별 전달 자격, PR 계획, 원격 조정과 로컬 인계 정책."""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from okstra_ctl import consumers, stage_targets, worktree_registry
+from okstra_ctl.handoff_verification import verification_row_is_current
+from okstra_ctl.handoff_error import HandoffError
+from okstra_ctl.stage_integrate import (
+    IntegrateError, MergeBranchConflict, ensure_stage_merge_branch,
+)
+from okstra_ctl.worktree import (
+    compute_branch_name, main_worktree_path, is_dirty_excluding_okstra,
+    nested_worktree_excludes, is_ancestor, remove_worktree_force, _git,
+)
+
+
+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 okstra_ctl.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)
+
+
+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 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 = consumers.require_done_task_key(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

package/runtime/{prompts/profiles/release-handoff.md → python/okstra_ctl/phases/release_handoff/profile.md}

@@ -15,7 +15,7 @@
 - Pre-handoff entry gate (mandatory — refuse to start if any item fails):
   - the run's input document (`release-handoff-input.md`, generated by prepare in place of a task brief — briefs belong to entry phases only) carries a `## Source Verification Report` section with `Stages` and one table row per cited `final-verification` final-report. The run context exposes the same selection as `HANDOFF_STAGES` (csv, never empty — prepare defaults it to every eligible stage).
   - the lead opens each cited single-stage report and confirms its `verificationScope` is `single-stage` and its verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every **Conditional Acceptance Condition** row declaring `blocksReleaseHandoff: false`. The rule lives in `okstra_ctl.release_gate.release_handoff_allowed`; the lead reads the reports against it and does not invent a third case. Eligibility was already enforced at prepare time (`okstra_ctl.handoff.compute_eligibility`) and is re-enforced by `okstra handoff pr-plan` — the lead never hand-computes it.
-  - if any cited verdict is `blocked`, a `conditional-accept` carrying a condition that blocks release, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; Do NOT run any git command.
+  - Record each cited verdict and any blocking acceptance condition as entry-gate evidence. Read the `## release-handoff` section of `prompts/lead/phase-routing.md` before user questions or Git commands.
   - when a cited verdict is `conditional-accept`, the lead MUST carry that stage's **Conditional Acceptance Condition** rows into **that stage's** PR body under a heading naming them as unresolved — id, condition, and the evidence the reviewer would need. These conditions are the whole reason a non-`accepted` verdict was allowed through; a PR body that drops them turns a recorded condition into a silent one.
   - the lead MUST capture `git status --short` and confirm the working tree is clean. Dirty state aborts the run; release-handoff packages the commits produced by `implementation`, it does not stage or commit changes.
   - the lead MUST capture `git rev-parse --abbrev-ref HEAD` and record it as the run's current branch. It is evidence, not a PR head: every PR head comes from `okstra handoff pr-plan`. If the current branch is `main`, `master`, `prod`, `preprod`, `staging`, or `dev`, record it and do not push it — release-handoff never pushes a base branch.
@@ -97,9 +97,9 @@
     - `- Checked out <branch> (stage <N>) into <main worktree path>; okstra worktree <path> removed. Next: to run a local test and then open a PR, re-enter release-handoff via okstra-run → push + PR.`
     - `- Checked out <branch> (stage <N>) into <main worktree path>; no okstra worktree removed (already torn down — the branch survived). Next: to run a local test and then open a PR, re-enter release-handoff via okstra-run → push + PR.`
     - Pick between the two `Checked out` variants by the command's `removedWorktree` field: a non-empty path takes the first, an empty string takes the second. Never write a removal that did not happen.
-  - **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, or delivered only some of the selected stages, the recommendation MUST state which stages still need a PR and that re-entry into release-handoff is appropriate.
+  - **Routing recommendation**: record which selected stages were delivered, skipped, cancelled, or still need a PR. The lead chooses the next phase under `## release-handoff` in `prompts/lead/phase-routing.md`.
 - Self-review pass before finalising the report (the Okstra lead runs this):
-  1. **Entry-gate audit** — the report cites, for every stage it delivered, that stage's final-verification report path and the literal `Verdict Token` row with a release-ready value. If any is missing, or a `conditional-accept` stage's PR body omits its conditions, the run is invalid and MUST be re-routed to `final-verification`.
+  1. **Entry-gate audit** — record the final-verification report path and literal `Verdict Token` row for every delivered stage, and the conditions transcribed into each conditional-accept stage's PR body. Record any missing evidence for the lead's routing decision.
   2. **User-selection traceability** — every executed mutating command maps to a user selection captured in the report. Any mutating command without a corresponding user answer is a contract violation.
   3. **Forbidden-action audit** — scan the run's session transcripts (`git`, `gh` invocations) for every entry in the Forbidden actions list above. Any occurrence means the run has crossed into unsafe territory and MUST be flagged as `contract-violated`.
   4. **Push-target audit** — for every `git push` recorded, confirm the refspec resolves to a branch that appears in the pr-plan output, not to the release base branch.

package/runtime/python/okstra_ctl/{report_html/view_models/release_handoff.py → phases/release_handoff/report.py}

@@ -3,9 +3,9 @@ from __future__ import annotations
 
 from urllib.parse import urlparse
 
-from ..common import evidence_index
-from ..models import HumanReportView, VisualNode
-from ..visualizations import timeline_figure
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView, VisualNode
+from okstra_ctl.report_html.visualizations import timeline_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.

package/runtime/{templates/reports → python/okstra_ctl/phases/release_handoff/report_assets}/release-handoff-input.template.md

@@ -84,7 +84,7 @@ The user picks ONE release base for the whole run. Each stage's own PR base is t
 
 > The lead MUST NOT extend handoff actions into items listed here. If an excluded item should ship in this PR, edit this section before the run starts — do not silently fold it in.
 
-**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 ## Questions for Lead Drafting