okstra 0.67.0 → 0.69.0

package/runtime/python/okstra_ctl/git_reconcile.py

@@ -0,0 +1,322 @@
+"""Stale git SHA 감지·화해·보정 (3단 방어)의 단일 reference point.
+
+저장된 SHA(anchor / done.head_commit)가 okstra 밖의 히스토리 재작성으로
+stale 해졌을 때 — patch-id 로 내용 동일성이 증명되면 자동 화해(auto),
+내용이 바뀌었으면 사용자 확인 보정(confirm). 설계상 소비자는 prepare
+경로(run.py), `okstra git-reconcile` subcommand, okstra-run 스킬 —
+셋 모두 이 모듈 하나를 통해야 한다. 설계:
+docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from .worktree import _resolve_commit_sha
+
+
+def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", "-C", str(cwd), *args],
+                          capture_output=True, text=True)
+
+
+@dataclass
+class MatchResult:
+    status: str            # "ancestor" | "patch-equivalent" | "not-merged" | "unresolvable"
+    matched_commit: str = ""
+
+
+def _patch_ids_of_range(cwd: Path, base: str, head: str) -> List[Tuple[str, str]]:
+    """base..head 각 커밋의 (patch-id, sha). diff 없는 커밋은 제외된다."""
+    log = _git(cwd, "log", "-p", "--no-merges", f"{base}..{head}")
+    if log.returncode != 0:
+        return []
+    pid = subprocess.run(["git", "-C", str(cwd), "patch-id", "--stable"],
+                         input=log.stdout, capture_output=True, text=True)
+    out = []
+    for line in pid.stdout.splitlines():
+        parts = line.split()
+        if len(parts) == 2:
+            out.append((parts[0], parts[1]))
+    return out
+
+
+def _patch_id_of_diff(cwd: Path, base: str, head: str) -> str:
+    """base→head 전체를 한 diff 로 본 patch-id (squash 동등성용)."""
+    diff = _git(cwd, "diff", base, head)
+    if diff.returncode != 0 or not diff.stdout.strip():
+        return ""
+    pid = subprocess.run(["git", "-C", str(cwd), "patch-id", "--stable"],
+                         input=diff.stdout + "\n", capture_output=True, text=True)
+    parts = pid.stdout.split()
+    return parts[0] if parts else ""
+
+
+def content_merged(project_root: Path, commit: str, candidate: str,
+                   base: str = "") -> MatchResult:
+    """commit 의 내용이 candidate 히스토리에 포함되는가.
+
+    1) ancestor 면 그대로 통과. 2) patch-id fallback 두 granularity:
+    커밋 단위(rebase/cherry-pick — base..commit 의 *모든* 커밋이 매칭돼야 함)
+    + 범위 합산(squash — base..commit 전체 diff 가 한 커밋과 매칭).
+    증명 실패는 not-merged — 자동 진행 금지는 호출자 계약이다."""
+    resolved = _resolve_commit_sha(project_root, commit)
+    cand = _resolve_commit_sha(project_root, candidate)
+    if not resolved or not cand:
+        return MatchResult("unresolvable")
+    if _git(project_root, "merge-base", "--is-ancestor", resolved, cand).returncode == 0:
+        return MatchResult("ancestor", matched_commit=resolved)
+    mb = _git(project_root, "merge-base", resolved, cand).stdout.strip()
+    if not mb:
+        return MatchResult("not-merged")
+    range_base = _resolve_commit_sha(project_root, base) or mb
+    cand_ids: Dict[str, str] = dict(_patch_ids_of_range(project_root, mb, cand))
+    stage_ids = _patch_ids_of_range(project_root, range_base, resolved)
+    if stage_ids and all(pid in cand_ids for pid, _ in stage_ids):
+        # git log 는 최신 커밋부터 출력 → stage_ids[0] 이 tip. matched_commit
+        # 은 재기록 대상이므로 tip 의 매칭 SHA 여야 한다.
+        return MatchResult("patch-equivalent",
+                           matched_commit=cand_ids[stage_ids[0][0]])
+    whole = _patch_id_of_diff(project_root, range_base, resolved)
+    if whole and whole in cand_ids:
+        return MatchResult("patch-equivalent", matched_commit=cand_ids[whole])
+    return MatchResult("not-merged")
+
+
+@dataclass
+class StaleItem:
+    kind: str                  # "anchor" | "done"
+    stage: Optional[int]
+    recorded: str
+    classification: str        # "ok" | "auto" | "confirm"
+    reason: str
+    suggested_commit: str = "" # auto 일 때 재기록 대상
+    impl_task_key: str = ""
+
+
+def _classify_done_row(project_root: Path, stage: int, row: dict,
+                       branch: str, stage_base: str) -> StaleItem:
+    recorded = row.get("head_commit", "")
+    item = StaleItem(kind="done", stage=stage, recorded=recorded,
+                     classification="ok", reason="",
+                     impl_task_key=row.get("impl_task_key", ""))
+    if not _resolve_commit_sha(project_root, recorded):
+        item.classification, item.reason = "confirm", "recorded SHA unresolvable"
+        return item
+    tip = _resolve_commit_sha(project_root, branch)
+    if not tip or tip == recorded:
+        return item  # branch 없음(히스토리 intact) 또는 일치
+    if _git(project_root, "merge-base", "--is-ancestor",
+            recorded, tip).returncode == 0:
+        return item  # 커밋이 단순히 더 쌓임 — stale 아님
+    match = content_merged(project_root, recorded, tip, base=stage_base)
+    if match.status in ("ancestor", "patch-equivalent"):
+        item.classification = "auto"
+        item.reason = f"branch {branch} rewritten, patch-equivalent"
+        item.suggested_commit = tip
+    else:
+        item.classification = "confirm"
+        item.reason = f"branch {branch} rewritten with content changes"
+    return item
+
+
+def classify_task(*, project_root: Path, plan_run_root: Path,
+                  project_id: str, task_group: str, task_id: str,
+                  work_category: str) -> List[StaleItem]:
+    """task 의 anchor + 최신 done row 들을 ok/auto/confirm 으로 분류한다.
+    다중 의존 gate(spec §3.2 표 5-6행)는 candidate 가 필요한 prepare 경로에서
+    content_merged 로 직접 평가된다 — 여기서 중복 평가하지 않는다."""
+    from . import worktree_registry as _reg
+    from .consumers import read_consumers, latest_done_by_stage
+    from .worktree import compute_branch_name
+
+    items: List[StaleItem] = []
+    anchor = _reg.get_implementation_base(project_id, task_group, task_id) or ""
+    if anchor:
+        ok = bool(_resolve_commit_sha(project_root, anchor))
+        items.append(StaleItem(
+            kind="anchor", stage=None, recorded=anchor,
+            classification="ok" if ok else "confirm",
+            reason="" if ok else "anchor SHA unresolvable",
+        ))
+    latest = latest_done_by_stage(read_consumers(plan_run_root))
+    for stage in sorted(latest):
+        row = latest[stage]
+        branch = compute_branch_name(
+            work_category=work_category, task_id_segment=task_id,
+            stage_number=stage,
+        )
+        srow = _reg.get_stage_row(project_id, task_group, task_id, stage) or {}
+        items.append(_classify_done_row(
+            project_root, stage, row, branch, srow.get("base_ref", "")))
+    return items
+
+
+class ReconcileError(Exception):
+    pass
+
+
+def _record_reconciled(plan_run_root: Path, *, impl_task_key: str, stage: int,
+                       new_commit: str, replaced: str, reason: str) -> None:
+    from .consumers import append_consumer
+    append_consumer(
+        plan_run_root, impl_task_key=impl_task_key, stage=stage,
+        status="done", force_reappend=True, head_commit=new_commit,
+        reconciled=True, reconcile_reason=reason, replaced_commit=replaced,
+    )
+
+
+def auto_reconcile(*, project_root: Path, plan_run_root: Path,
+                   project_id: str, task_group: str, task_id: str,
+                   work_category: str) -> List[StaleItem]:
+    """classify 의 auto 항목만 보정 row 로 재기록한다 — patch-id 증명이
+    있으므로 확인 불필요(설계 §2 결정). confirm 은 건드리지 않는다."""
+    applied = []
+    items = classify_task(
+        project_root=project_root, plan_run_root=plan_run_root,
+        project_id=project_id, task_group=task_group, task_id=task_id,
+        work_category=work_category)
+    for item in items:
+        if item.classification != "auto" or item.kind != "done":
+            continue
+        _record_reconciled(plan_run_root, impl_task_key=item.impl_task_key,
+                           stage=item.stage, new_commit=item.suggested_commit,
+                           replaced=item.recorded, reason="auto-patch-id")
+        applied.append(item)
+    return applied
+
+
+def guidance(*, plan_run_root: Path, project_id: str, task_group: str,
+             task_id: str, work_category: str) -> str:
+    """PrepareError 에 첨부하는 회복 안내 (명령 예시 포함)."""
+    base = (f"okstra git-reconcile --plan-run-root {plan_run_root} "
+            f"--project-id {project_id} --task-group {task_group} "
+            f"--task-id {task_id} --work-category {work_category}")
+    return ("Recorded stage SHAs no longer match the git history "
+            "(external rebase/squash/amend?). Inspect and reconcile:\n"
+            f"  {base} --check --json\n"
+            f"  {base} --apply --stage <N> --use-ref <branch|sha>")
+
+
+def _apply_user_ref(project_root: Path, plan_run_root: Path,
+                    latest: Dict[int, dict], stage: Optional[int],
+                    use_ref: str) -> dict:
+    if stage is None:
+        raise ReconcileError("--use-ref requires --stage")
+    sha = _resolve_commit_sha(project_root, use_ref)
+    if not sha:
+        raise ReconcileError(f"could not resolve ref `{use_ref}`")
+    row = latest.get(stage)
+    if not row:
+        raise ReconcileError(f"stage {stage} has no done row to reconcile")
+    _record_reconciled(plan_run_root, impl_task_key=row.get("impl_task_key", ""),
+                       stage=stage, new_commit=sha,
+                       replaced=row.get("head_commit", ""), reason="user-ref")
+    return {"stage": stage, "new_commit": sha}
+
+
+def apply_reconcile(*, project_root: Path, plan_run_root: Path,
+                    project_id: str, task_group: str, task_id: str,
+                    work_category: str, stage: Optional[int] = None,
+                    use_ref: str = "", reset_anchor: str = "") -> dict:
+    """auto 항목 일괄 보정 + (옵션) confirm 항목 1건 보정 + (옵션) anchor 재고정.
+
+    enforcement(spec §3.6): confirm 항목은 `use_ref` 가 명시된 그 stage 만
+    보정된다 — 어떤 경로로도 무확인 자동 보정되지 않는다.
+
+    classify 와 보정 append 사이는 원자적이지 않다 — 동시 run 이 활발한
+    시점이 아니라 사용자 보정(수동) 시점에 호출되는 것을 전제한다."""
+    from . import worktree_registry as _reg
+    from .consumers import read_consumers, latest_done_by_stage
+
+    applied: List[dict] = []
+    if reset_anchor:
+        sha = _resolve_commit_sha(project_root, reset_anchor)
+        if not sha:
+            raise ReconcileError(f"could not resolve ref `{reset_anchor}`")
+        _reg.reset_implementation_base(project_id, task_group, task_id, sha)
+        applied.append({"anchor": sha})
+    if use_ref:
+        latest = latest_done_by_stage(read_consumers(plan_run_root))
+        applied.append(_apply_user_ref(
+            project_root, plan_run_root, latest, stage, use_ref))
+    items = classify_task(
+        project_root=project_root, plan_run_root=plan_run_root,
+        project_id=project_id, task_group=task_group, task_id=task_id,
+        work_category=work_category)
+    for item in items:
+        if item.classification != "auto":
+            continue
+        if use_ref and item.stage == stage:
+            continue  # 사용자가 명시 보정한 stage 는 auto 가 덮지 않는다
+        _record_reconciled(plan_run_root, impl_task_key=item.impl_task_key,
+                           stage=item.stage, new_commit=item.suggested_commit,
+                           replaced=item.recorded, reason="auto-patch-id")
+        applied.append({"stage": item.stage, "new_commit": item.suggested_commit})
+    remaining = [i for i in items if i.classification == "confirm"
+                 and not (use_ref and i.stage == stage)]
+    return {"applied": applied, "remaining_confirm": remaining}
+
+
+def _items_as_json(items: List[StaleItem]) -> list:
+    return [{"kind": i.kind, "stage": i.stage, "recorded": i.recorded,
+             "classification": i.classification, "reason": i.reason,
+             "suggested_commit": i.suggested_commit} for i in items]
+
+
+def main(argv: Optional[list] = None) -> int:
+    import argparse
+    import json as _json
+
+    p = argparse.ArgumentParser(
+        prog="okstra git-reconcile",
+        epilog="exit codes: 0 = clean/applied, 2 = confirm items remain, 1 = error")
+    p.add_argument("--project-root", default=".")
+    p.add_argument("--plan-run-root", required=True,
+                   help="consumers.jsonl 이 있는 runs/implementation-planning/ 경로")
+    p.add_argument("--project-id", required=True)
+    p.add_argument("--task-group", required=True)
+    p.add_argument("--task-id", required=True)
+    p.add_argument("--work-category", required=True)
+    p.add_argument("--check", action="store_true",
+                   help="stale 검사만 (기본 동작과 동일 — 명시용)")
+    p.add_argument("--apply", action="store_true",
+                   help="auto 항목 일괄 보정 (+ --stage/--use-ref, --reset-anchor)")
+    p.add_argument("--stage", type=int)
+    p.add_argument("--use-ref", default="")
+    p.add_argument("--reset-anchor", default="")
+    p.add_argument("--json", action="store_true")
+    a = p.parse_args(argv)
+    if a.check and a.apply:
+        p.error("--check and --apply are mutually exclusive")
+    if a.apply and a.stage is not None and not a.use_ref:
+        p.error("--stage requires --use-ref (confirm 항목은 명시 ref 로만 보정된다)")
+
+    kw = dict(project_root=Path(a.project_root).resolve(),
+              plan_run_root=Path(a.plan_run_root).resolve(),
+              project_id=a.project_id, task_group=a.task_group,
+              task_id=a.task_id, work_category=a.work_category)
+    try:
+        if a.apply:
+            result = apply_reconcile(**kw, stage=a.stage, use_ref=a.use_ref,
+                                     reset_anchor=a.reset_anchor)
+            out = {"applied": result["applied"],
+                   "remaining_confirm": _items_as_json(result["remaining_confirm"])}
+            print(_json.dumps(out, ensure_ascii=False,
+                              indent=None if a.json else 2))
+            return 2 if result["remaining_confirm"] else 0
+        items = classify_task(**kw)
+        stale = [i for i in items if i.classification != "ok"]
+        print(_json.dumps({"items": _items_as_json(stale)}, ensure_ascii=False,
+                          indent=None if a.json else 2))
+        return 2 if any(i.classification == "confirm" for i in stale) else 0
+    except ReconcileError as exc:
+        print(_json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False,
+                          indent=None if a.json else 2))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/handoff.py

@@ -0,0 +1,348 @@
+"""release-handoff stage-group 모드의 강제 지점.
+
+자격 판정(eligible) · 수집 브랜치 생성+머지(assemble) · verified/pr 행 기록을
+단일 모듈로 강제한다. lead 는 `okstra handoff <sub>` 로 호출만 한다.
+설계: docs/superpowers/specs/2026-06-10-stage-group-handoff-design.md
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from . import consumers, worktree_registry
+from .worktree import compute_branch_name, compute_worktree_path
+
+
+class HandoffError(Exception):
+    """자격/전제 위반 — exit 1, actionable 메시지."""
+
+
+class HandoffConflict(Exception):
+    """stage 간 merge 충돌 — exit 2, 충돌 경로 동봉."""
+
+    def __init__(self, stage: int, paths: List[str]):
+        self.stage = stage
+        self.paths = paths
+        super().__init__(
+            f"merge conflict while merging stage {stage}: {', '.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 가 담당)."""
+    done = consumers.latest_done_by_stage(rows)
+    verified = consumers.verified_accepted_stages(rows)
+    in_pr = consumers.pr_covered_stages(rows)
+    out = []
+    for s in stage_map:
+        n = s["stage_number"]
+        reasons = []
+        if n in in_pr:
+            reasons.append("already-in-pr")
+        else:
+            if n not in done:
+                reasons.append("not-done")
+            if n not in verified:
+                reasons.append("not-verified-accepted")
+        out.append({
+            "stage": n,
+            "depends_on": list(s["depends_on"]),
+            "eligible": not reasons,
+            "reasons": reasons,
+            "head_commit": (done.get(n) or {}).get("head_commit", ""),
+        })
+    return out
+
+
+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:
+    r = subprocess.run(["git", *args], cwd=str(cwd),
+                       capture_output=True, text=True)
+    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 _require_closure(stages, stage_map, done, project_root, base_branch) -> None:
+    def merged(commit: str) -> bool:
+        return _run_git(["merge-base", "--is-ancestor", commit,
+                         f"origin/{base_branch}"], project_root,
+                        check=False).returncode == 0
+    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 _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 _run_git(["merge-base", "--is-ancestor", h, head], project_root,
+                    check=False).returncode != 0:
+            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:
+    _run_git(["worktree", "remove", "--force", str(wt_path)], project_root,
+             check=False)
+    _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) -> List[str]:
+    merge_commits = []
+    for n in sorted(stages):
+        stage_branch = compute_branch_name(
+            work_category=work_category, task_id_segment=task_id,
+            stage_number=n)
+        r = _run_git(["merge", "--no-edit", stage_branch], wt_path, check=False)
+        if r.returncode != 0:
+            paths = _run_git(["diff", "--name-only", "--diff-filter=U"],
+                             wt_path).stdout.split()
+            _run_git(["merge", "--abort"], wt_path, check=False)
+            _cleanup_group(project_root, wt_path, branch, project_id,
+                           task_group, task_id, gid)
+            raise HandoffConflict(stage=n, paths=paths)
+        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 브랜치들을 머지한다. 멱등."""
+    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)
+
+    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)
+    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)
+    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)
+    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}
+
+
+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,
+                    data_json) -> Dict[str, Any]:
+    """단독-stage accepted 만 기록. data.json 의 taskType/scope/verdict 를 검증해
+    lead 가 임의 보고서를 verified 로 올리는 것을 막는다."""
+    try:
+        data = json.loads(Path(data_json).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise HandoffError(f"cannot read final-report data.json: {exc}")
+    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":
+        raise HandoffError(
+            f"record-verified requires verificationScope single-stage, "
+            f"got {scope!r}")
+    token = ((data.get("finalVerdict") or {}).get("verdictToken")
+             or "").strip().lower()
+    if token != "accepted":
+        raise HandoffError(f"verdict token must be `accepted`, got {token!r}")
+    rows = consumers.read_consumers(Path(plan_run_root))
+    key = _impl_task_key_for(rows, stage)
+    consumers.append_verified(Path(plan_run_root), impl_task_key=key,
+                              stage=stage, verdict="accepted",
+                              report_path=report_path)
+    return {"ok": True, "stage": stage, "report_path": report_path}
+
+
+def record_pr(*, plan_run_root, stages: List[int], branch: str,
+              url: str) -> Dict[str, Any]:
+    if not stages:
+        raise HandoffError("record-pr requires at least one stage")
+    rows = consumers.read_consumers(Path(plan_run_root))
+    key = _impl_task_key_for(rows, sorted(stages)[0])
+    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}
+
+
+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
+
+
+def main(argv: Optional[list] = None) -> int:
+    import argparse
+
+    from .run import _parse_stage_map_into_ctx
+
+    p = argparse.ArgumentParser(prog="okstra handoff")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp, *, plan=True):
+        if plan:
+            sp.add_argument("--plan-run-root", required=True)
+
+    sp = sub.add_parser("eligible")
+    common(sp)
+    sp.add_argument("--approved-plan", required=True)
+
+    sp = sub.add_parser("assemble")
+    common(sp)
+    sp.add_argument("--approved-plan", required=True)
+    sp.add_argument("--project-root", default=".")
+    sp.add_argument("--project-id", required=True)
+    sp.add_argument("--task-group", required=True)
+    sp.add_argument("--task-id", required=True)
+    sp.add_argument("--work-category", required=True)
+    sp.add_argument("--stages", required=True)
+    sp.add_argument("--base", required=True)
+
+    sp = sub.add_parser("record-verified")
+    common(sp)
+    sp.add_argument("--stage", type=int, required=True)
+    sp.add_argument("--report-path", required=True)
+    sp.add_argument("--data-json", required=True)
+
+    sp = sub.add_parser("record-pr")
+    common(sp)
+    sp.add_argument("--stages", required=True)
+    sp.add_argument("--branch", required=True)
+    sp.add_argument("--url", required=True)
+
+    a = p.parse_args(argv)
+    try:
+        if a.cmd == "eligible":
+            stage_map = _parse_stage_map_into_ctx(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(
+                project_root=Path(a.project_root).resolve(),
+                plan_run_root=Path(a.plan_run_root),
+                stage_map=_parse_stage_map_into_ctx(a.approved_plan),
+                stages=_parse_stages_csv(a.stages), base_branch=a.base,
+                work_category=a.work_category, project_id=a.project_id,
+                task_group=a.task_group, task_id=a.task_id)
+        elif a.cmd == "record-verified":
+            out = record_verified(plan_run_root=Path(a.plan_run_root),
+                                  stage=a.stage, report_path=a.report_path,
+                                  data_json=a.data_json)
+        else:
+            out = record_pr(plan_run_root=Path(a.plan_run_root),
+                            stages=_parse_stages_csv(a.stages),
+                            branch=a.branch, url=a.url)
+    except HandoffConflict as exc:
+        print(json.dumps({"error": str(exc), "stage": exc.stage,
+                          "conflicts": exc.paths}, ensure_ascii=False))
+        return 2
+    except HandoffError as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False))
+        return 1
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    import sys as _sys
+
+    _sys.exit(main())