okstra 0.66.0 → 0.68.0

package/docs/superpowers/plans/2026-06-10-stage-group-handoff.md

@@ -0,0 +1,1572 @@
+# release-handoff stage-group 모드 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 한 task 안에서 단독-stage 검증 `accepted` 를 받은 stage 들을 골라 수집 브랜치로 머지하고 하나의 PR 로 내보내는 release-handoff stage-group 모드를 추가한다.
+
+**Architecture:** 자격 판정·수집 머지·기록은 새 Python 모듈 `scripts/okstra_ctl/handoff.py` 한 곳에서 강제한다(`PrepareError` 패턴의 fail-fast). consumers.jsonl 에 `verified`/`pr` 행을 신설해 자격의 SSOT 로 삼고, worktree registry 에 그룹 키(`<task-key>#group-<id>`)를 추가한다. lead 는 `okstra handoff <sub>` Node 셔틀로 헬퍼만 호출한다. 스펙: [2026-06-10-stage-group-handoff-design.md](../specs/2026-06-10-stage-group-handoff-design.md).
+
+**Tech Stack:** Python 3 (stdlib only — 기존 okstra_ctl 관례), Node ESM 셔틀(src/*.mjs), pytest, bash e2e.
+
+---
+
+## 파일 구조
+
+| 파일 | 책임 |
+|---|---|
+| Modify [scripts/okstra_ctl/consumers.py](../../../scripts/okstra_ctl/consumers.py) | `verified`/`pr` 행 append + 리더 (`verified_accepted_stages`, `pr_covered_stages`) |
+| Modify [scripts/okstra_ctl/worktree_registry.py](../../../scripts/okstra_ctl/worktree_registry.py) | 그룹 키 `#group-<id>` — `task_key`/`lookup`/`reserve`/`release` 확장, `WorktreeEntry.stages` |
+| Modify [scripts/okstra_ctl/worktree.py](../../../scripts/okstra_ctl/worktree.py) | `compute_worktree_path`/`compute_branch_name` 에 `group_id` 변형 |
+| Create `scripts/okstra_ctl/handoff.py` | 자격 판정(pure) + assemble(git) + record-verified/record-pr + argparse main |
+| Create `src/handoff.mjs`, Modify [bin/okstra](../../../bin/okstra) | `okstra handoff` Node 셔틀 + 디스패치/도움말 등록 |
+| Modify [validators/validate-run.py](../../../validators/validate-run.py) | single-stage → `release-handoff(stage-group)` 라우팅 허용 |
+| Modify [prompts/profiles/release-handoff.md](../../../prompts/profiles/release-handoff.md), [prompts/profiles/final-verification.md](../../../prompts/profiles/final-verification.md) | stage-group 모드 계약 / 라우팅·record-verified 의무 |
+| Modify 문서 3종 | isolation spec 비목표 주석, `docs/kr/architecture.md`, `CHANGES.md` |
+| Create `tests/test_consumers_verified_pr_rows.py`, `tests/test_worktree_registry_group_key.py`, `tests/test_handoff_eligibility.py`, `tests/test_handoff_assemble.py`, `tests/test_handoff_records.py` | 단위 테스트 |
+| Create `tests-e2e/scenario-13-stage-group-handoff.sh` | end-to-end 시나리오 |
+
+참고 사실(이미 확인됨):
+- consumers 행 식별자는 `(impl_task_key, stage, status)`, 허용 status 는 `started|done` ([consumers.py:50](../../../scripts/okstra_ctl/consumers.py:50)).
+- registry `reserve` 는 flock 안에서 task-key 중복·branch 소유 충돌을 RuntimeError 로 막는다 ([worktree_registry.py:132](../../../scripts/okstra_ctl/worktree_registry.py:132)). `release` 는 키 3-인자 고정 ([worktree_registry.py:283](../../../scripts/okstra_ctl/worktree_registry.py:283)).
+- stage map 은 `_parse_stage_map_into_ctx(plan_path)` 가 `{"stage_number": int, "depends_on": [int], ...}` 리스트로 반환 ([run.py:611](../../../scripts/okstra_ctl/run.py:611)).
+- branch/path 계산의 단일 참조점은 [worktree.py:489](../../../scripts/okstra_ctl/worktree.py:489) `compute_worktree_path` / [worktree.py:513](../../../scripts/okstra_ctl/worktree.py:513) `compute_branch_name`.
+- Node 셔틀 패턴은 [src/git-reconcile.mjs](../../../src/git-reconcile.mjs) (`runPythonModule`), 디스패치 테이블은 [bin/okstra:24](../../../bin/okstra:24).
+- 모든 pytest 는 conftest 가 `OKSTRA_HOME` 을 임시 디렉터리로 격리한다 ([tests/conftest.py:6](../../../tests/conftest.py:6)) — registry/worktree 가 사용자 홈을 오염시키지 않음.
+- 검증 라우팅 enforcement 는 [validate-run.py:1441](../../../validators/validate-run.py:1441) (`single-stage` → release-handoff 금지).
+
+커밋 메시지 규칙: Conventional Commits, 구체적 scope, **Claude trailer 금지** (`Co-Authored-By` / `🤖 Generated` 라인 넣지 말 것).
+
+---
+
+### Task 1: consumers — `verified` / `pr` 행
+
+**Files:**
+- Modify: `scripts/okstra_ctl/consumers.py`
+- Test: `tests/test_consumers_verified_pr_rows.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_consumers_verified_pr_rows.py` 생성:
+
+```python
+"""consumers.jsonl 의 verified / pr 행 계약.
+
+verified: 단독-stage final-verification accepted 기록. (key, stage, 'verified',
+report_path) 가 같으면 멱등, report_path 가 다르면 재검증으로 보고 append (last-wins).
+pr: handoff 가 PR 생성/재사용 시 기록. 같은 branch 의 pr 행이 있으면 멱등.
+"""
+from okstra_ctl import consumers
+
+KEY = "proj/group/task"
+
+
+def test_append_verified_roundtrip(tmp_path):
+    consumers.append_verified(
+        tmp_path, impl_task_key=KEY, stage=2,
+        verdict="accepted", report_path="reports/fv-2.md")
+    rows = consumers.read_consumers(tmp_path)
+    assert rows == [{
+        "impl_task_key": KEY, "stage": 2, "status": "verified",
+        "verdict": "accepted", "report_path": "reports/fv-2.md",
+    }]
+
+
+def test_append_verified_idempotent_same_report(tmp_path):
+    for _ in range(2):
+        consumers.append_verified(
+            tmp_path, impl_task_key=KEY, stage=2,
+            verdict="accepted", report_path="reports/fv-2.md")
+    assert len(consumers.read_consumers(tmp_path)) == 1
+
+
+def test_append_verified_reverification_appends(tmp_path):
+    consumers.append_verified(tmp_path, impl_task_key=KEY, stage=2,
+                              verdict="blocked", report_path="reports/fv-2a.md")
+    consumers.append_verified(tmp_path, impl_task_key=KEY, stage=2,
+                              verdict="accepted", report_path="reports/fv-2b.md")
+    assert len(consumers.read_consumers(tmp_path)) == 2
+
+
+def test_verified_accepted_stages_last_wins(tmp_path):
+    consumers.append_verified(tmp_path, impl_task_key=KEY, stage=2,
+                              verdict="accepted", report_path="a.md")
+    consumers.append_verified(tmp_path, impl_task_key=KEY, stage=3,
+                              verdict="blocked", report_path="b.md")
+    # stage 2 가 이후 재검증에서 blocked 로 뒤집힘 → 제외돼야 함
+    consumers.append_verified(tmp_path, impl_task_key=KEY, stage=2,
+                              verdict="blocked", report_path="c.md")
+    rows = consumers.read_consumers(tmp_path)
+    assert consumers.verified_accepted_stages(rows) == set()
+
+
+def test_append_pr_and_covered_stages(tmp_path):
+    consumers.append_pr(tmp_path, impl_task_key=KEY, stages=[3, 2],
+                        branch="feat-task-g2-3", url="https://example.com/pr/1")
+    rows = consumers.read_consumers(tmp_path)
+    assert rows[0]["stages"] == [2, 3]  # 정렬 저장
+    assert consumers.pr_covered_stages(rows) == {2, 3}
+
+
+def test_append_pr_idempotent_same_branch(tmp_path):
+    for _ in range(2):
+        consumers.append_pr(tmp_path, impl_task_key=KEY, stages=[2],
+                            branch="feat-task-g2", url="https://example.com/pr/1")
+    assert len(consumers.read_consumers(tmp_path)) == 1
+
+
+def test_append_consumer_still_rejects_unknown_status(tmp_path):
+    import pytest
+    with pytest.raises(ValueError):
+        consumers.append_consumer(tmp_path, impl_task_key=KEY, stage=1,
+                                  status="verified")
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_consumers_verified_pr_rows.py -v`
+Expected: FAIL — `AttributeError: module 'okstra_ctl.consumers' has no attribute 'append_verified'`
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/consumers.py` 의 `append_consumer` 바로 아래에 추가 (공용 write 경로를 `_append_row` 로 추출해 `append_consumer` 마지막 두 줄도 이를 쓰도록 변경):
+
+```python
+def _append_row(plan_run_root: Path, record: Dict[str, Any]) -> None:
+    with _path(plan_run_root).open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def append_verified(plan_run_root: Path, *, impl_task_key: str, stage: int,
+                    verdict: str, report_path: str) -> None:
+    """단독-stage final-verification 결과 기록. 같은 report_path 재기록은 멱등,
+    다른 report_path 는 재검증으로 append 한다 (읽기는 last-wins)."""
+    with consumers_mutex(plan_run_root):
+        for row in read_consumers(plan_run_root):
+            if (row.get("impl_task_key") == impl_task_key
+                    and row.get("stage") == stage
+                    and row.get("status") == "verified"
+                    and row.get("report_path") == report_path):
+                return
+        _append_row(plan_run_root, {
+            "impl_task_key": impl_task_key, "stage": stage,
+            "status": "verified", "verdict": verdict,
+            "report_path": report_path,
+        })
+
+
+def append_pr(plan_run_root: Path, *, impl_task_key: str, stages: List[int],
+              branch: str, url: str) -> None:
+    """handoff 의 PR 생성/재사용 기록. 같은 branch 의 pr 행이 이미 있으면 멱등."""
+    with consumers_mutex(plan_run_root):
+        for row in read_consumers(plan_run_root):
+            if row.get("status") == "pr" and row.get("branch") == branch:
+                return
+        _append_row(plan_run_root, {
+            "impl_task_key": impl_task_key, "stages": sorted(stages),
+            "status": "pr", "branch": branch, "url": url,
+        })
+
+
+def verified_accepted_stages(rows: List[Dict[str, Any]]) -> set:
+    """stage → 마지막 verified 행의 verdict 가 accepted 인 stage 집합 (last-wins)."""
+    last: Dict[int, str] = {}
+    for r in rows:
+        if r.get("status") == "verified" and isinstance(r.get("stage"), int):
+            last[r["stage"]] = (r.get("verdict") or "").strip().lower()
+    return {n for n, v in last.items() if v == "accepted"}
+
+
+def pr_covered_stages(rows: List[Dict[str, Any]]) -> set:
+    out: set = set()
+    for r in rows:
+        if r.get("status") == "pr":
+            out.update(n for n in (r.get("stages") or []) if isinstance(n, int))
+    return out
+```
+
+`append_consumer` 의 기존 파일-쓰기 두 줄(`with _path(...).open("a", ...)` 블록)은 `_append_row(plan_run_root, record)` 호출로 교체한다. `append_consumer` 의 `status not in ("started", "done")` 검증은 그대로 둔다 (started/done 전용 — verified/pr 는 전용 함수만 사용).
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_consumers_verified_pr_rows.py tests/test_consumers_jsonl.py tests/test_consumers_carry_backfill.py tests/test_consumers_report_path.py -v`
+Expected: 전부 PASS (기존 consumers 테스트 회귀 없음)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/consumers.py tests/test_consumers_verified_pr_rows.py
+git commit -m "feat(okstra-ctl): consumers 에 verified/pr 행 추가 — stage-group handoff 자격 SSOT"
+```
+
+---
+
+### Task 2: worktree_registry — 그룹 키
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree_registry.py`
+- Test: `tests/test_worktree_registry_group_key.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_worktree_registry_group_key.py` 생성:
+
+```python
+"""registry 의 #group-<id> 키 — stage-key 와 동형의 예약/해제, 상호배타 검증."""
+import pytest
+
+from okstra_ctl import worktree_registry as reg
+
+ARGS = dict(project_id="proj", task_group="grp", task_id="task")
+
+
+def test_task_key_group_suffix():
+    assert reg.task_key(*ARGS.values(), group_id="g2-3") == "proj/grp/task#group-g2-3"
+
+
+def test_task_key_stage_and_group_mutually_exclusive():
+    with pytest.raises(ValueError):
+        reg.task_key(*ARGS.values(), stage_number=2, group_id="g2-3")
+
+
+def test_reserve_lookup_release_group(tmp_path):
+    entry = reg.reserve(
+        **ARGS, worktree_path=str(tmp_path / "wt"), branch="feat-task-g2-3",
+        base_ref="abc123", phase="release-handoff",
+        group_id="g2-3", stages=[2, 3])
+    assert entry.task_key == "proj/grp/task#group-g2-3"
+    assert entry.stages == [2, 3]
+
+    found = reg.lookup(**ARGS, group_id="g2-3")
+    assert found is not None and found.branch == "feat-task-g2-3"
+
+    # 같은 그룹 키 재예약은 거부
+    with pytest.raises(RuntimeError):
+        reg.reserve(**ARGS, worktree_path=str(tmp_path / "wt2"),
+                    branch="feat-task-g2-3b", base_ref="abc123",
+                    group_id="g2-3", stages=[2, 3])
+
+    released = reg.release(**ARGS, group_id="g2-3")
+    assert released is not None and released.status == "released"
+    # 해제 후 branch 슬롯이 풀려 재예약 가능
+    reg.reserve(**ARGS, worktree_path=str(tmp_path / "wt3"),
+                branch="feat-task-g2-3", base_ref="abc123",
+                group_id="g2-3", stages=[2, 3])
+
+
+def test_group_key_does_not_collide_with_stage_key(tmp_path):
+    reg.reserve(**ARGS, worktree_path=str(tmp_path / "s2"), branch="feat-task-s2",
+                base_ref="abc", stage_number=2)
+    entry = reg.reserve(**ARGS, worktree_path=str(tmp_path / "g"), branch="feat-task-g2",
+                        base_ref="abc", group_id="g2", stages=[2])
+    assert entry.task_key.endswith("#group-g2")
+    assert reg.lookup(**ARGS, stage_number=2).task_key.endswith("#stage-2")
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_worktree_registry_group_key.py -v`
+Expected: FAIL — `TypeError: task_key() got an unexpected keyword argument 'group_id'`
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/worktree_registry.py` 수정 4곳:
+
+(a) `task_key` ([worktree_registry.py:46](../../../scripts/okstra_ctl/worktree_registry.py:46)) 교체:
+
+```python
+def task_key(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+) -> str:
+    """Canonical task-key. stage_number → `#stage-<N>` (per-stage worktree),
+    group_id → `#group-<id>` (stage-group collector worktree). 둘은 상호배타."""
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
+    base = f"{project_id}/{task_group}/{task_id}"
+    if stage_number is not None:
+        return f"{base}#stage-{stage_number}"
+    if group_id is not None:
+        return f"{base}#group-{group_id}"
+    return base
+```
+
+(b) `WorktreeEntry` ([worktree_registry.py:59](../../../scripts/okstra_ctl/worktree_registry.py:59)) 에 필드 추가 (기존 행에는 없는 키이므로 default 필수):
+
+```python
+    stages: Optional[list] = None
+```
+
+(c) `lookup` / `reserve` 시그니처에 `group_id: Optional[str] = None` 추가, `reserve` 에는 `stages: Optional[list] = None` 도 추가. 두 함수의 `task_key(...)` 호출에 `group_id=group_id` 전달. `reserve` 의 `row` dict 에 `"stages": stages,` 한 줄 추가 ([worktree_registry.py:166](../../../scripts/okstra_ctl/worktree_registry.py:166) row 구성부).
+
+(d) `release` ([worktree_registry.py:283](../../../scripts/okstra_ctl/worktree_registry.py:283)) 시그니처를 `release(project_id, task_group, task_id, stage_number=None, group_id=None)` 로 확장하고 `key = task_key(project_id, task_group, task_id, stage_number, group_id)` 로 변경.
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_worktree_registry_group_key.py tests/test_get_stage_row.py -v && python3 -m pytest tests/ -q -k "registry or worktree" `
+Expected: 전부 PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/worktree_registry.py tests/test_worktree_registry_group_key.py
+git commit -m "feat(okstra-ctl): worktree registry 에 stage-group 그룹 키 예약 추가"
+```
+
+---
+
+### Task 3: worktree.py — 그룹 경로/브랜치 계산
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree.py:489-524`
+- Test: `tests/test_handoff_eligibility.py` (이 task 에서는 compute 함수 테스트만 먼저 담는다)
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_handoff_eligibility.py` 생성 (Task 4 가 같은 파일에 자격 테스트를 추가한다):
+
+```python
+"""stage-group handoff — 경로/브랜치 계산과 자격 판정(pure)."""
+import pytest
+
+from okstra_ctl.worktree import compute_branch_name, compute_worktree_path
+
+
+def test_compute_branch_name_group():
+    assert compute_branch_name(
+        work_category="feature-development", task_id_segment="dev-9184",
+        group_id="g2-3",
+    ).endswith("-dev-9184-g2-3")
+
+
+def test_compute_worktree_path_group():
+    p = compute_worktree_path(
+        project_id="proj", task_group_segment="grp", task_id_segment="task",
+        group_id="g2-3",
+    )
+    assert p.parts[-1] == "group-g2-3"
+    assert p.parts[-2] == "task"
+
+
+def test_compute_stage_and_group_mutually_exclusive():
+    with pytest.raises(ValueError):
+        compute_branch_name(work_category="feature-development",
+                            task_id_segment="t", stage_number=2, group_id="g2")
+    with pytest.raises(ValueError):
+        compute_worktree_path(project_id="p", task_group_segment="g",
+                              task_id_segment="t", stage_number=2, group_id="g2")
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_handoff_eligibility.py -v`
+Expected: FAIL — `TypeError: ... unexpected keyword argument 'group_id'`
+
+- [ ] **Step 3: 구현**
+
+[worktree.py:489](../../../scripts/okstra_ctl/worktree.py:489) `compute_worktree_path` 와 [worktree.py:513](../../../scripts/okstra_ctl/worktree.py:513) `compute_branch_name` 에 `group_id: Optional[str] = None` 파라미터 추가. 양쪽 모두 함수 첫머리에:
+
+```python
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
+```
+
+`compute_worktree_path` 의 마지막 경로 결합부: `stage_number` 분기와 대칭으로 `group_id` 가 있으면 `/ f"group-{group_id}"` 세그먼트를 덧붙인다. `compute_branch_name` 은 `stage_number` 분기와 대칭으로:
+
+```python
+    if group_id is not None:
+        name = f"{name}-{group_id}"
+```
+
+(`group_id` 가 이미 `g2-3` 형태이므로 접두 `g` 를 다시 붙이지 않는다 — 브랜치는 `feat-dev-9184-g2-3`.)
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_handoff_eligibility.py -v && python3 -m pytest tests/ -q -k worktree`
+Expected: PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/worktree.py tests/test_handoff_eligibility.py
+git commit -m "feat(okstra-ctl): worktree 경로/브랜치 계산에 group_id 변형 추가"
+```
+
+---
+
+### Task 4: handoff.py — 자격 판정 (pure)
+
+**Files:**
+- Create: `scripts/okstra_ctl/handoff.py`
+- Test: `tests/test_handoff_eligibility.py` (추가)
+
+- [ ] **Step 1: 실패하는 테스트 추가**
+
+`tests/test_handoff_eligibility.py` 에 append:
+
+```python
+from okstra_ctl import handoff
+
+
+STAGE_MAP = [
+    {"stage_number": 1, "depends_on": []},
+    {"stage_number": 2, "depends_on": []},
+    {"stage_number": 3, "depends_on": [2]},
+]
+
+
+def _rows(*, done=(), verified=(), pr=()):
+    rows = []
+    for n in done:
+        rows.append({"impl_task_key": "k", "stage": n, "status": "done",
+                     "head_commit": f"head{n}"})
+    for n in verified:
+        rows.append({"impl_task_key": "k", "stage": n, "status": "verified",
+                     "verdict": "accepted", "report_path": f"fv-{n}.md"})
+    if pr:
+        rows.append({"impl_task_key": "k", "stages": list(pr), "status": "pr",
+                     "branch": "b", "url": "u"})
+    return rows
+
+
+def test_group_id_for_sorts():
+    assert handoff.group_id_for([3, 2]) == "g2-3"
+
+
+def test_eligibility_reasons():
+    rows = _rows(done=[1, 2], verified=[2], pr=[1])
+    by_stage = {e["stage"]: e for e in handoff.compute_eligibility(STAGE_MAP, rows)}
+    assert by_stage[2]["eligible"] is True
+    assert by_stage[1]["reasons"] == ["already-in-pr"]
+    assert set(by_stage[3]["reasons"]) == {"not-done", "not-verified-accepted"}
+    assert by_stage[2]["head_commit"] == "head2"
+
+
+def test_dependency_closure_blocks_unselected_unmerged_predecessor():
+    rows = _rows(done=[2, 3], verified=[2, 3])
+    done = {2: {"head_commit": "head2"}, 3: {"head_commit": "head3"}}
+    violations = handoff.check_dependency_closure(
+        [3], STAGE_MAP, done, is_merged_to_base=lambda c: False)
+    assert violations == [(3, 2)]
+    # 선행이 base 에 이미 머지됐으면 통과
+    assert handoff.check_dependency_closure(
+        [3], STAGE_MAP, done, is_merged_to_base=lambda c: True) == []
+    # 선행이 같은 그룹에 선택돼도 통과
+    assert handoff.check_dependency_closure(
+        [2, 3], STAGE_MAP, done, is_merged_to_base=lambda c: False) == []
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_handoff_eligibility.py -v`
+Expected: FAIL — `ImportError: cannot import name 'handoff'`
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/handoff.py` 생성:
+
+```python
+"""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 not in done:
+            reasons.append("not-done")
+        if n not in verified:
+            reasons.append("not-verified-accepted")
+        if n in in_pr:
+            reasons.append("already-in-pr")
+        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
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_handoff_eligibility.py -v`
+Expected: PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/handoff.py tests/test_handoff_eligibility.py
+git commit -m "feat(okstra-ctl): handoff 자격 판정·의존 폐포 검사 추가"
+```
+
+---
+
+### Task 5: handoff.py — assemble (수집 브랜치 생성 + 머지)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/handoff.py`
+- Test: `tests/test_handoff_assemble.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_handoff_assemble.py` 생성. 실제 임시 git repo(+bare origin)로 검증한다:
+
+```python
+"""handoff.assemble — 수집 브랜치 생성/머지/멱등/충돌/폐포의 git 실증."""
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from okstra_ctl import consumers, handoff, worktree_registry
+from okstra_ctl.worktree import compute_branch_name
+
+ARGS = dict(project_id="proj", task_group="grp", task_id="task")
+WC = "feature-development"
+
+
+def _stage_branch(n):
+    # 머지 대상 브랜치명은 assemble 과 동일한 단일 참조점으로 계산해야
+    # work-category prefix 가 바뀌어도 fixture 가 깨지지 않는다.
+    return compute_branch_name(work_category=WC, task_id_segment=ARGS["task_id"],
+                               stage_number=n)
+
+
+def _git(repo, *args):
+    r = subprocess.run(["git", *args], cwd=str(repo),
+                       capture_output=True, text=True)
+    assert r.returncode == 0, r.stderr
+    return r.stdout.strip()
+
+
+def _commit_file(repo, name, content, msg):
+    Path(repo, name).write_text(content)
+    _git(repo, "add", name)
+    _git(repo, "commit", "-m", msg)
+    return _git(repo, "rev-parse", "HEAD")
+
+
+@pytest.fixture
+def repo(tmp_path):
+    """base 커밋 1개 + 독립 stage 2/3 브랜치 + bare origin. 반환: (repo, base, heads)"""
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    _git(repo, "init", "-b", "main")
+    _git(repo, "config", "user.email", "t@t")
+    _git(repo, "config", "user.name", "t")
+    base = _commit_file(repo, "base.txt", "base\n", "base")
+    heads = {}
+    for n, fname in ((2, "s2.txt"), (3, "s3.txt")):
+        _git(repo, "checkout", "-b", _stage_branch(n), base)
+        heads[n] = _commit_file(repo, fname, f"stage{n}\n", f"stage {n}")
+    _git(repo, "checkout", "main")
+    origin = tmp_path / "origin.git"
+    subprocess.run(["git", "init", "--bare", str(origin)], check=True,
+                   capture_output=True)
+    _git(repo, "remote", "add", "origin", str(origin))
+    _git(repo, "push", "origin", "main")
+    worktree_registry.set_implementation_base(**ARGS, commit=base)
+    return repo, base, heads
+
+
+def _seed_rows(plan_root, heads, stages):
+    for n in stages:
+        consumers.append_consumer(plan_root, impl_task_key="k", stage=n,
+                                  status="done", head_commit=heads[n])
+        consumers.append_verified(plan_root, impl_task_key="k", stage=n,
+                                  verdict="accepted", report_path=f"fv-{n}.md")
+
+
+STAGE_MAP = [
+    {"stage_number": 2, "depends_on": []},
+    {"stage_number": 3, "depends_on": []},
+]
+
+
+def test_assemble_merges_selected_stages(repo, tmp_path):
+    repo_dir, base, heads = repo
+    plan_root = tmp_path / "plan"
+    plan_root.mkdir()
+    _seed_rows(plan_root, heads, [2, 3])
+
+    result = handoff.assemble(
+        project_root=repo_dir, plan_run_root=plan_root, stage_map=STAGE_MAP,
+        stages=[2, 3], base_branch="main", work_category=WC, **ARGS)
+
+    assert result["branch"].endswith("-task-g2-3")
+    assert result["reused"] is False
+    wt = Path(result["worktree_path"])
+    # 두 stage head 모두 수집 브랜치 HEAD 의 ancestor
+    for h in heads.values():
+        subprocess.run(["git", "merge-base", "--is-ancestor", h,
+                        result["head"]], cwd=str(wt), check=True)
+
+
+def test_assemble_is_idempotent(repo, tmp_path):
+    repo_dir, base, heads = repo
+    plan_root = tmp_path / "plan"
+    plan_root.mkdir()
+    _seed_rows(plan_root, heads, [2, 3])
+    first = handoff.assemble(
+        project_root=repo_dir, plan_run_root=plan_root, stage_map=STAGE_MAP,
+        stages=[2, 3], base_branch="main", work_category=WC, **ARGS)
+    second = handoff.assemble(
+        project_root=repo_dir, plan_run_root=plan_root, stage_map=STAGE_MAP,
+        stages=[2, 3], base_branch="main", work_category=WC, **ARGS)
+    assert second["reused"] is True
+    assert second["head"] == first["head"]
+
+
+def test_assemble_rejects_ineligible_stage(repo, tmp_path):
+    repo_dir, base, heads = repo
+    plan_root = tmp_path / "plan"
+    plan_root.mkdir()
+    _seed_rows(plan_root, heads, [2])  # stage 3 은 미검증
+    with pytest.raises(handoff.HandoffError, match="not eligible"):
+        handoff.assemble(
+            project_root=repo_dir, plan_run_root=plan_root, stage_map=STAGE_MAP,
+            stages=[2, 3], base_branch="main", work_category=WC, **ARGS)
+
+
+def test_assemble_conflict_aborts_and_cleans_up(repo, tmp_path):
+    repo_dir, base, heads = repo
+    # 같은 파일을 두 stage 가 다르게 수정 → 충돌
+    _git(repo_dir, "checkout", _stage_branch(2))
+    heads[2] = _commit_file(repo_dir, "shared.txt", "from s2\n", "s2 shared")
+    _git(repo_dir, "checkout", _stage_branch(3))
+    heads[3] = _commit_file(repo_dir, "shared.txt", "from s3\n", "s3 shared")
+    _git(repo_dir, "checkout", "main")
+    plan_root = tmp_path / "plan"
+    plan_root.mkdir()
+    _seed_rows(plan_root, heads, [2, 3])
+
+    with pytest.raises(handoff.HandoffConflict) as exc:
+        handoff.assemble(
+            project_root=repo_dir, plan_run_root=plan_root, stage_map=STAGE_MAP,
+            stages=[2, 3], base_branch="main", work_category=WC, **ARGS)
+    assert "shared.txt" in exc.value.paths
+    # 정리됨: 그룹 키 해제(또는 부재) + 브랜치 삭제
+    entry = worktree_registry.lookup(**ARGS, group_id="g2-3")
+    assert entry is None or entry.status == "released"
+    collector = compute_branch_name(work_category=WC,
+                                    task_id_segment=ARGS["task_id"],
+                                    group_id="g2-3")
+    r = subprocess.run(["git", "rev-parse", "--verify", "--quiet", collector],
+                       cwd=str(repo_dir), capture_output=True)
+    assert r.returncode != 0
+
+
+def test_assemble_dependency_closure_violation(repo, tmp_path):
+    repo_dir, base, heads = repo
+    stage_map = [{"stage_number": 2, "depends_on": []},
+                 {"stage_number": 3, "depends_on": [2]}]
+    plan_root = tmp_path / "plan"
+    plan_root.mkdir()
+    _seed_rows(plan_root, heads, [2, 3])
+    with pytest.raises(handoff.HandoffError, match="depends on stage 2"):
+        handoff.assemble(
+            project_root=repo_dir, plan_run_root=plan_root, stage_map=stage_map,
+            stages=[3], base_branch="main", work_category=WC, **ARGS)
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_handoff_assemble.py -v`
+Expected: FAIL — `AttributeError: ... no attribute 'assemble'`
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/handoff.py` 에 추가. 함수 50줄 상한을 지키기 위해 단계별 헬퍼로 분해한다:
+
+```python
+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)
+    _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)
+    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}
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_handoff_assemble.py tests/test_handoff_eligibility.py -v`
+Expected: PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/handoff.py tests/test_handoff_assemble.py
+git commit -m "feat(okstra-ctl): handoff assemble — 수집 브랜치 생성·머지·멱등·충돌 정리"
+```
+
+---
+
+### Task 6: handoff.py — record-verified / record-pr + CLI main
+
+**Files:**
+- Modify: `scripts/okstra_ctl/handoff.py`
+- Test: `tests/test_handoff_records.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`tests/test_handoff_records.py` 생성:
+
+```python
+"""record-verified / record-pr — data.json 게이트와 consumers 기록, CLI exit code."""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from okstra_ctl import consumers, handoff
+
+
+def _fv_data(tmp_path, *, scope="single-stage", token="accepted"):
+    p = tmp_path / "data.json"
+    p.write_text(json.dumps({
+        "header": {"taskType": "final-verification"},
+        "verificationScope": scope,
+        "finalVerdict": {"verdictToken": token},
+    }))
+    return p
+
+
+def _seed_done(plan_root, stage=2):
+    consumers.append_consumer(plan_root, impl_task_key="proj/grp/task",
+                              stage=stage, status="done", head_commit="h")
+
+
+def test_record_verified_accepts_single_stage_accepted(tmp_path):
+    plan = tmp_path / "plan"
+    plan.mkdir()
+    _seed_done(plan)
+    handoff.record_verified(plan_run_root=plan, stage=2,
+                            report_path="reports/fv-2.md",
+                            data_json=_fv_data(tmp_path))
+    rows = consumers.read_consumers(plan)
+    assert any(r["status"] == "verified" and r["stage"] == 2 for r in rows)
+    # impl_task_key 는 done 행에서 승계
+    vrow = [r for r in rows if r["status"] == "verified"][0]
+    assert vrow["impl_task_key"] == "proj/grp/task"
+
+
+@pytest.mark.parametrize("scope,token", [
+    ("whole-task", "accepted"),
+    ("single-stage", "blocked"),
+])
+def test_record_verified_rejects_wrong_scope_or_token(tmp_path, scope, token):
+    plan = tmp_path / "plan"
+    plan.mkdir()
+    _seed_done(plan)
+    with pytest.raises(handoff.HandoffError):
+        handoff.record_verified(plan_run_root=plan, stage=2,
+                                report_path="r.md",
+                                data_json=_fv_data(tmp_path, scope=scope,
+                                                   token=token))
+
+
+def test_record_verified_requires_done_row(tmp_path):
+    plan = tmp_path / "plan"
+    plan.mkdir()
+    with pytest.raises(handoff.HandoffError, match="no done row"):
+        handoff.record_verified(plan_run_root=plan, stage=2,
+                                report_path="r.md",
+                                data_json=_fv_data(tmp_path))
+
+
+def test_record_pr_writes_row(tmp_path):
+    plan = tmp_path / "plan"
+    plan.mkdir()
+    _seed_done(plan)
+    handoff.record_pr(plan_run_root=plan, stages=[2], branch="b",
+                      url="https://example.com/pr/9")
+    assert consumers.pr_covered_stages(consumers.read_consumers(plan)) == {2}
+
+
+def test_cli_eligible_json(tmp_path):
+    """CLI smoke — eligible 서브커맨드가 JSON 을 출력하고 exit 0."""
+    plan = tmp_path / "plan"
+    plan.mkdir()
+    approved = tmp_path / "plan.md"
+    approved.write_text(
+        "## 5.5 Stage Map\n\n"
+        "| Stage | Title | Depends-on | Effective Steps |\n"
+        "|---|---|---|---|\n"
+        "| 1 | one | (none) | 2 |\n")
+    r = subprocess.run(
+        [sys.executable, "-m", "okstra_ctl.handoff", "eligible",
+         "--plan-run-root", str(plan), "--approved-plan", str(approved)],
+        capture_output=True, text=True,
+        cwd=str(Path(__file__).resolve().parents[1] / "scripts"))
+    assert r.returncode == 0, r.stderr
+    payload = json.loads(r.stdout)
+    assert payload["stages"][0]["stage"] == 1
+    assert payload["stages"][0]["eligible"] is False
+```
+
+주의: CLI 테스트의 Stage Map 표 형식은 [validators/validate-implementation-plan-stages.py:55](../../../validators/validate-implementation-plan-stages.py:55) `_parse_stage_map` 이 실제로 파싱하는 형식을 따라야 한다. 구현 전에 그 파서의 기대 헤더(컬럼명·`(none)` 표기)를 열어 확인하고, 다르면 **테스트 fixture 를 파서에 맞춰 수정**한다 (파서를 바꾸지 말 것).
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_handoff_records.py -v`
+Expected: FAIL — `AttributeError: ... no attribute 'record_verified'`
+
+- [ ] **Step 3: 구현**
+
+`scripts/okstra_ctl/handoff.py` 에 추가:
+
+```python
+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]:
+    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}
+```
+
+argparse main (모듈 끝, [git_reconcile.py:237](../../../scripts/okstra_ctl/git_reconcile.py:237) 의 `main` 패턴):
+
+```python
+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())
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_handoff_records.py tests/test_handoff_assemble.py tests/test_handoff_eligibility.py -v`
+Expected: PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/handoff.py tests/test_handoff_records.py
+git commit -m "feat(okstra-ctl): handoff record-verified/record-pr + CLI main 추가"
+```
+
+---
+
+### Task 7: Node 셔틀 + bin/okstra 등록
+
+**Files:**
+- Create: `src/handoff.mjs`
+- Modify: `bin/okstra` (디스패치 테이블 [bin/okstra:24](../../../bin/okstra:24) 부근 + Admin commands 도움말 ~74행)
+
+- [ ] **Step 1: 셔틀 작성**
+
+`src/handoff.mjs` 생성 ([src/git-reconcile.mjs](../../../src/git-reconcile.mjs) 와 동일 패턴):
+
+```javascript
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra handoff — release-handoff stage-group 보조 (자격/수집/기록)
+
+A thin shim over \`python3 -m okstra_ctl.handoff\`. JSON 출력.
+
+Usage:
+  okstra handoff eligible --plan-run-root <dir> --approved-plan <md>
+  okstra handoff assemble --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>
+
+Exit codes: 0 ok / 1 자격·전제 위반 / 2 stage 간 merge 충돌(conflicts 동봉)
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.handoff",
+    args,
+  });
+  return code ?? 1;
+}
+```
+
+- [ ] **Step 2: bin/okstra 등록**
+
+디스패치 테이블의 `git-reconcile` 항목 아래에 추가:
+
+```javascript
+  ["handoff", () => import("../src/handoff.mjs").then((m) => m.run)],
+```
+
+Admin commands 도움말 블록(`git-reconcile` 설명 행 아래)에 추가:
+
+```
+  handoff                Stage-group release-handoff helpers (eligible/assemble/record)
+```
+
+- [ ] **Step 3: 스모크 확인**
+
+Run: `node bin/okstra handoff --help && node bin/okstra --version`
+Expected: USAGE 출력 + 버전 정상 출력 (exit 0)
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add src/handoff.mjs bin/okstra
+git commit -m "feat(cli): okstra handoff 서브커맨드 — okstra_ctl.handoff 셔틀"
+```
+
+---
+
+### Task 8: validate-run.py — stage-group 라우팅 허용
+
+**Files:**
+- Modify: `validators/validate-run.py:1441-1446`
+- Test: 기존 validator 테스트 파일 위치 확인 — `grep -rln "verificationScope" tests/` 결과의 파일에 케이스 추가 (없으면 `tests/test_validate_run_stage_group_routing.py` 신설)
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+먼저 기존 테스트 위치 확인: `grep -rln "single-stage cannot recommend\|verificationScope" tests/`. 기존 파일이 있으면 거기에, 없으면 `tests/test_validate_run_stage_group_routing.py` 를 만들어 다음 두 케이스를 추가한다 (validator 의 해당 함수를 직접 import 해 `failures` 리스트로 검증하는 기존 관례를 따른다 — 그 파일의 기존 테스트가 함수를 부르는 방식을 그대로 복제):
+
+```python
+def _fv_data(routing, scope="single-stage"):
+    return {
+        "header": {"taskType": "final-verification"},
+        "verificationScope": scope,
+        "finalVerdict": {"verdictToken": "accepted"},
+        "finalVerification": {
+            "acceptanceBlockers": [],
+            "routingRecommendation": routing,
+        },
+    }
+
+
+def test_single_stage_allows_stage_group_handoff_routing():
+    failures = []
+    validate_final_verification_consistency(_fv_data("release-handoff(stage-group)"), failures)
+    assert failures == []
+
+
+def test_single_stage_still_blocks_plain_handoff_routing():
+    failures = []
+    validate_final_verification_consistency(_fv_data("release-handoff"), failures)
+    assert any("single-stage" in f for f in failures)
+```
+
+(함수명 `validate_final_verification_consistency` 는 [validate-run.py:1397](../../../validators/validate-run.py:1397) 정의부를 열어 실제 이름으로 맞춘다.)
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest <해당 테스트 파일> -v`
+Expected: `test_single_stage_allows_stage_group_handoff_routing` FAIL
+
+- [ ] **Step 3: 구현**
+
+[validate-run.py:1441](../../../validators/validate-run.py:1441) 의 single-stage 검사 교체:
+
+```python
+    if (scope == "single-stage" and "release-handoff" in routing
+            and "release-handoff(stage-group)" not in routing):
+        failures.append(
+            "final-verification: verificationScope `single-stage` cannot recommend "
+            "plain release-handoff routing — a single-stage accepted verdict may "
+            "only route to `release-handoff(stage-group)` (partial-PR mode); "
+            "whole-task release-handoff requires whole-task verification."
+        )
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest <해당 테스트 파일> -v && python3 -m pytest tests/ -q -k "validate"`
+Expected: PASS
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add validators/validate-run.py tests/
+git commit -m "feat(validators): single-stage 검증의 release-handoff(stage-group) 라우팅 허용"
+```
+
+---
+
+### Task 9: 프로파일 계약 수정
+
+**Files:**
+- Modify: `prompts/profiles/release-handoff.md`
+- Modify: `prompts/profiles/final-verification.md`
+
+- [ ] **Step 1: final-verification.md 수정**
+
+(a) [final-verification.md:29](../../../prompts/profiles/final-verification.md:29) 의 문장 끝 `A single-stage run is a partial verification and MUST NOT recommend release-handoff.` 를 다음으로 교체:
+
+```
+A single-stage run is a partial verification: it MUST NOT recommend plain `release-handoff`, but MAY recommend `release-handoff(stage-group)` when the verdict is `accepted` — the stage becomes PR-eligible for a stage-group handoff.
+```
+
+(b) [final-verification.md:40](../../../prompts/profiles/final-verification.md:40) 의 마지막 문장(`a single-stage run is partial and routes to ...`)을 다음으로 교체:
+
+```
+a `single-stage` accepted run routes to `release-handoff(stage-group)` (or `implementation` / `done`); plain `release-handoff` remains whole-task-only. Enforcement: `validators/validate-run.py` rejects a `single-stage` report whose routing cites plain `release-handoff`.
+```
+
+(c) deliverable 목록(같은 파일의 Required deliverable 섹션)에 한 줄 추가:
+
+```
+  - **Verified-row recording** (single-stage scope only): when the Verdict Token is `accepted`, the lead MUST run `okstra handoff record-verified --plan-run-root <plan-run-root> --stage <N> --report-path <final-report.md path> --data-json <final-report data.json path>` and quote the command + exit code in the report. The helper re-validates taskType/scope/verdict from data.json, so a non-accepted or whole-task report is rejected at the tool layer.
+```
+
+- [ ] **Step 2: release-handoff.md 수정**
+
+(a) Purpose 줄([release-handoff.md:3](../../../prompts/profiles/release-handoff.md:3)) 끝에 추가: ` Two modes: **whole-task** (default — the verified task branch becomes one PR) and **stage-group** (a user-selected subset of verified stages is merged into a collector branch and becomes one PR).`
+
+(b) 진입 게이트([release-handoff.md:14](../../../prompts/profiles/release-handoff.md:14)) 의 단일-보고서 항목을 모드 분기로 교체:
+
+```
+  - **whole-task mode**: the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`; the lead confirms its `Verdict Token` is exactly `accepted` and its `verificationScope` is `whole-task`.
+  - **stage-group mode**: the brief cites N single-stage `final-verification` reports (one per candidate stage); the lead confirms each `Verdict Token` is `accepted`. Eligibility is re-enforced by `okstra handoff` — the lead never hand-computes it.
+```
+
+(c) User interaction protocol 에 stage-group 분기 추가 (기존 Q1 항목 아래):
+
+```
+  - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage selection, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
+  1g. **G2 — stage selection**: run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and present the returned stages (eligible ones selectable, blocked ones listed with their `reasons`) as a multi-select. At least one stage must be selected.
+  2g. **assemble**: run `okstra handoff assemble --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <csv> --base <chosen-base>`. Exit 2 means a stage-vs-stage merge conflict: show the `conflicts` paths and stop (route: reshape the group or resolve manually). Exit 1 means an eligibility/closure violation: show the error verbatim and re-ask G2. On success the returned `branch` is the PR head branch for every subsequent step.
+```
+
+(d) Allowed actions 에 추가:
+
+```
+  - stage-group helpers: `okstra handoff eligible`, `okstra handoff assemble`, `okstra handoff record-pr`. The assemble step is the ONLY path that may create commits (merge commits on the collector branch) in this phase.
+```
+
+(e) Forbidden actions 의 `local commit commands of any kind` 항목([release-handoff.md:57](../../../prompts/profiles/release-handoff.md:57))을 다음으로 교체:
+
+```
+  - local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` run by the lead. The single exception is the merge commits `okstra handoff assemble` itself creates on the collector branch — the lead never merges by hand.
+```
+
+(f) push/PR 단계: stage-group 모드에서는 push 대상·PR head 가 수집 브랜치임을 명시 (기존 `git push -u origin <current-branch>` 항목에 `(stage-group mode: the collector branch returned by assemble)` 보충). PR 생성 성공(또는 reuse 확인) 직후 의무 추가:
+
+```
+  - after `gh pr create` succeeds (or an existing PR is reused), the lead MUST run `okstra handoff record-pr --plan-run-root <...> --stages <csv> --branch <head branch> --url <pr url>` and quote the command + exit code in the final report. This applies to BOTH modes — whole-task runs record `--stages` as the full Stage Map list — so duplicate-PR prevention converges on one consumers record.
+```
+
+또한 Inline drafting rules 의 diff 범위 항목에 보충: stage-group 모드의 초안 근거는 `git log <implementation_base_commit>..<collector HEAD>` / `git diff <implementation_base_commit>..<collector HEAD> --stat` 이며, 소스 자료는 그룹 내 stage 별 implementation 보고서 + 단독 검증 보고서 N 개다.
+
+(g) Required deliverable shape 에 추가:
+
+```
+  - **Stage Group** (stage-group mode only): selected stages, each stage's single-stage verification report path + quoted `Verdict Token` row, collector branch name, merge commit SHAs from assemble, and the dependency-closure verdict (from the assemble output / error).
+```
+
+- [ ] **Step 3: 빌드 + 검증**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: 빌드 성공, validator 통과 (실패 시 메시지의 계약 위반 지점을 고친다)
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add prompts/profiles/release-handoff.md prompts/profiles/final-verification.md
+git commit -m "feat(profiles): release-handoff stage-group 모드 + 단독-stage 라우팅 완화 계약"
+```
+
+---
+
+### Task 10: 문서 반영
+
+**Files:**
+- Modify: `docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md` (비범위 절)
+- Modify: `docs/kr/architecture.md` (release-handoff 절)
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: isolation spec 비목표 주석**
+
+비범위 목록의 `**okstra 자동 머지 없음**` 항목 끝에 추가:
+
+```
+(2026-06-10 개정: release-handoff stage-group 모드의 수집 머지는 예외 — [2026-06-10-stage-group-handoff-design.md](2026-06-10-stage-group-handoff-design.md))
+```
+
+- [ ] **Step 2: architecture.md 갱신**
+
+`docs/kr/architecture.md` 의 release-handoff 절(목차에서 위치 확인)에 stage-group 모드 요약을 추가한다 — 모드 2종, G1→G2→assemble 순서, consumers `verified`/`pr` 행 계약, registry `#group-<id>` 키, `okstra handoff` 서브커맨드 4종. 형식은 그 문서의 인접 절 스타일(한국어, 표/리스트)을 따른다.
+
+- [ ] **Step 3: CHANGES.md 항목 추가**
+
+`head -30 CHANGES.md` 로 기존 항목 형식을 확인한 뒤 동일 형식으로 최신 항목을 추가한다. 내용:
+
+```
+- release-handoff 에 stage-group 모드 추가: 단독-stage 검증 accepted 를 받은 stage 들을 골라 수집 브랜치(`<prefix>-<task-id>-g2-3`)로 머지해 하나의 PR 로 내보낼 수 있다. `okstra handoff eligible/assemble/record-verified/record-pr` 신설.
+  사용자 영향: task 전체가 끝나기를 기다리지 않고 검증 완료된 stage 묶음 단위로 PR 을 낼 수 있다. 단독-stage final-verification 의 라우팅이 `release-handoff(stage-group)` 를 허용하도록 완화됐다.
+```
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md docs/kr/architecture.md CHANGES.md
+git commit -m "docs(kr): stage-group handoff 문서 반영 — architecture/CHANGES/isolation 비목표 개정"
+```
+
+---
+
+### Task 11: e2e 시나리오
+
+**Files:**
+- Create: `tests-e2e/scenario-13-stage-group-handoff.sh` (11 은 결번, 12 까지 존재 — 13 사용)
+
+- [ ] **Step 1: 시나리오 작성**
+
+```bash
+#!/usr/bin/env bash
+# scenario-13-stage-group-handoff
+#
+# Goal: 독립 stage 2/3 이 done + 단독검증 accepted 인 상태에서
+# handoff eligible → assemble → 수집 브랜치 머지 그래프 검증 →
+# record-pr → eligible 재실행 시 already-in-pr 로 제외되는지 확인.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE_ROOT="$(cd -P "$SCRIPT_DIR/.." && pwd)"
+
+SANDBOX_ROOT="$(mktemp -d -t okstra-e2e.XXXXXX)"
+cleanup() { rm -rf "$SANDBOX_ROOT"; }
+trap cleanup EXIT
+
+export OKSTRA_HOME="$SANDBOX_ROOT/okstra-home"
+export PYTHONPATH="$WORKSPACE_ROOT/scripts"
+mkdir -p "$OKSTRA_HOME"
+
+PROJECT_ID="okstra-e2e-s13"
+TASK_GROUP="grp"
+TASK_ID="task"
+WC="feature-development"
+
+REPO="$SANDBOX_ROOT/repo"
+ORIGIN="$SANDBOX_ROOT/origin.git"
+PLAN_ROOT="$SANDBOX_ROOT/plan-run"
+mkdir -p "$REPO" "$PLAN_ROOT"
+
+git -C "$REPO" init -q -b main
+git -C "$REPO" config user.email t@t
+git -C "$REPO" config user.name t
+echo base > "$REPO/base.txt"
+git -C "$REPO" add base.txt && git -C "$REPO" commit -qm base
+BASE_SHA="$(git -C "$REPO" rev-parse HEAD)"
+
+# stage 브랜치명은 assemble 과 동일한 단일 참조점(compute_branch_name)으로 계산
+stage_branch() {
+  python3 -c "from okstra_ctl.worktree import compute_branch_name; \
+print(compute_branch_name(work_category='$WC', task_id_segment='$TASK_ID', stage_number=$1))"
+}
+
+declare -A HEADS
+for N in 2 3; do
+  git -C "$REPO" checkout -qb "$(stage_branch "$N")" "$BASE_SHA"
+  echo "stage$N" > "$REPO/s$N.txt"
+  git -C "$REPO" add "s$N.txt" && git -C "$REPO" commit -qm "stage $N"
+  HEADS[$N]="$(git -C "$REPO" rev-parse HEAD)"
+done
+git -C "$REPO" checkout -q main
+git init -q --bare "$ORIGIN"
+git -C "$REPO" remote add origin "$ORIGIN"
+git -C "$REPO" push -q origin main
+
+# 승인 plan (Stage Map 만 필요). 컬럼 형식은
+# validators/validate-implementation-plan-stages.py 의 _parse_stage_map 기준.
+cat > "$SANDBOX_ROOT/approved-plan.md" <<'EOF'
+## 5.5 Stage Map
+
+| Stage | Title | Depends-on | Effective Steps |
+|---|---|---|---|
+| 2 | stage two | (none) | 2 |
+| 3 | stage three | (none) | 2 |
+EOF
+
+python3 - "$PLAN_ROOT" "${HEADS[2]}" "${HEADS[3]}" "$BASE_SHA" <<'EOF'
+import sys
+from pathlib import Path
+from okstra_ctl import consumers, worktree_registry
+
+plan, h2, h3, base = Path(sys.argv[1]), sys.argv[2], sys.argv[3], sys.argv[4]
+key = "okstra-e2e-s13/grp/task"
+for n, h in ((2, h2), (3, h3)):
+    consumers.append_consumer(plan, impl_task_key=key, stage=n,
+                              status="done", head_commit=h)
+    consumers.append_verified(plan, impl_task_key=key, stage=n,
+                              verdict="accepted", report_path=f"fv-{n}.md")
+worktree_registry.set_implementation_base(
+    project_id="okstra-e2e-s13", task_group="grp", task_id="task", commit=base)
+EOF
+
+ELIGIBLE_JSON="$(python3 -m okstra_ctl.handoff eligible \
+  --plan-run-root "$PLAN_ROOT" --approved-plan "$SANDBOX_ROOT/approved-plan.md")"
+echo "$ELIGIBLE_JSON" | python3 -c '
+import json, sys
+stages = {s["stage"]: s for s in json.load(sys.stdin)["stages"]}
+assert stages[2]["eligible"] and stages[3]["eligible"], stages
+'
+
+ASSEMBLE_JSON="$(python3 -m okstra_ctl.handoff assemble \
+  --plan-run-root "$PLAN_ROOT" --approved-plan "$SANDBOX_ROOT/approved-plan.md" \
+  --project-root "$REPO" --project-id "$PROJECT_ID" --task-group "$TASK_GROUP" \
+  --task-id "$TASK_ID" --work-category "$WC" --stages 2,3 --base main)"
+COLLECTOR_BRANCH="$(echo "$ASSEMBLE_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["branch"])')"
+COLLECTOR_HEAD="$(echo "$ASSEMBLE_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["head"])')"
+
+for N in 2 3; do
+  git -C "$REPO" merge-base --is-ancestor "${HEADS[$N]}" "$COLLECTOR_HEAD"
+done
+
+python3 -m okstra_ctl.handoff record-pr --plan-run-root "$PLAN_ROOT" \
+  --stages 2,3 --branch "$COLLECTOR_BRANCH" --url "https://example.com/pr/1" >/dev/null
+
+python3 -m okstra_ctl.handoff eligible \
+  --plan-run-root "$PLAN_ROOT" --approved-plan "$SANDBOX_ROOT/approved-plan.md" \
+  | python3 -c '
+import json, sys
+stages = {s["stage"]: s for s in json.load(sys.stdin)["stages"]}
+assert not stages[2]["eligible"] and "already-in-pr" in stages[2]["reasons"], stages
+assert not stages[3]["eligible"], stages
+'
+
+echo "scenario-13 OK"
+```
+
+작성 후 `chmod +x tests-e2e/scenario-13-stage-group-handoff.sh`. Stage Map 표 형식이 파서와 안 맞아 `eligible` 이 빈 목록을 내면, Task 6 Step 1 의 주의와 동일하게 **fixture 쪽을 파서 형식에 맞춘다**.
+
+- [ ] **Step 2: 실행 확인**
+
+Run: `bash tests-e2e/scenario-13-stage-group-handoff.sh`
+Expected: `scenario-13 OK` 출력, exit 0
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add tests-e2e/scenario-13-stage-group-handoff.sh
+git commit -m "test(e2e): stage-group handoff 시나리오 — eligible/assemble/record-pr 왕복"
+```
+
+---
+
+### Task 12: 전체 검증
+
+- [ ] **Step 1: 전체 단위 테스트**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: 전부 PASS
+
+- [ ] **Step 2: 빌드 + 워크플로 검증 + CLI 스모크**
+
+Run: `npm run build && bash validators/validate-workflow.sh && node bin/okstra doctor`
+Expected: 전부 성공
+
+- [ ] **Step 3: e2e 재확인**
+
+Run: `bash tests-e2e/scenario-13-stage-group-handoff.sh && bash tests-e2e/scenario-01-record-start-reconcile.sh`
+Expected: 둘 다 OK (기존 시나리오 회귀 없음)
+
+- [ ] **Step 4: 잔여 diff 리뷰 후 마무리 커밋**
+
+`git status` 로 누락 파일 확인. 미커밋 변경이 남았으면 해당 task 의 커밋에 맞춰 정리한다.