okstra 0.51.0 → 0.53.0

package/docs/superpowers/plans/2026-06-06-final-verification-whole-task-gate.md

@@ -0,0 +1,993 @@
+# final-verification 전체-task 게이트 + 단독-stage 모드 구현 계획
+
+> **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:** final-verification 이 multi-stage 작업을 (A) 전체-task 모드(모든 stage done+머지 후 한 번) 또는 (B) 단독-stage 모드(`--stage N`)로 검증하고, 검증 target 과 entry gate 를 Python prep 에서 자동 해소·강제하게 한다.
+
+**Architecture:** 검증 target(base/HEAD/worktree/stage 목록) 해소와 gate 검사(done·merge·clean)를 [run.py](../../../scripts/okstra_ctl/run.py) 의 bundle prep 단계로 단일화한다. 결정 로직은 git/registry IO 와 분리된 순수 함수 2개(`_resolve_whole_task_target` / `_resolve_single_stage_target`)로 두어 TDD 하고, 얇은 IO 래퍼가 facts 를 모아 디스패치한다. 해소된 snapshot 은 `{{VERIFICATION_TARGET}}` 으로 launch 템플릿에 주입한다. 설계: [2026-06-06-final-verification-whole-task-gate-design.md](../specs/2026-06-06-final-verification-whole-task-gate-design.md).
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/run.py`, `worktree_registry.py`, `consumers.py`), pytest + e2e bash, jinja2 launch 템플릿, markdown 프로파일, JSON Schema + `validators/validate-run.py`, Node 빌드(`npm run build`).
+
+---
+
+## 파일 구조
+
+| 파일 | 책임 | 작업 |
+|---|---|---|
+| `scripts/okstra_ctl/worktree_registry.py` | stage-key row 조회 getter | 수정 (`get_stage_row`) |
+| `scripts/okstra_ctl/run.py` | target 해소 순수 함수 + IO 래퍼 + prepare 분기 + ctx 주입 | 수정 |
+| `scripts/okstra_ctl/consumers.py` | done 행 `report_path` round-trip (이미 `**fields` 지원) | 테스트만 |
+| `tests/test_final_verification_target.py` | 순수 함수 유닛 (U1–U6) | 신규 |
+| `tests/test_get_stage_row.py` | registry getter 유닛 | 신규 |
+| `tests/test_reserve_final_verification.py` | IO 래퍼 통합 (tmp git repo) | 신규 |
+| `prompts/launch.template.md` | `{{VERIFICATION_TARGET}}` 주입 지점 | 수정 |
+| `prompts/profiles/final-verification.md` | entry gate 두 모드, Source Implementation Report 목록, routing 제약 | 수정 |
+| `prompts/profiles/_implementation-deliverable.md` | lead post-stage done 행에 `report_path` 포함 | 수정 |
+| `scripts/okstra_ctl/wizard.py` | final-verification 서브플로우 stage picker + approved-plan + emit | 수정 |
+| `validators/validate-run.py` | `verificationScope` + routing 규칙 + Source Implementation Report 다중 | 수정 |
+| `templates/reports/final-verification-input.template.md` | 입력 템플릿 갱신 | 수정 |
+| `tests-e2e/scenario-<id>-final-verification-modes.sh` | E1/E2/E3 | 신규 |
+
+`runtime/` 는 build output — 커밋 제외. profile/template/wizard 변경 후 `npm run build` 로 동기화.
+
+---
+
+## Task 1: registry `get_stage_row` getter (TDD)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree_registry.py`
+- Test: `tests/test_get_stage_row.py`
+
+stage-key row(`<task-key>#stage-N`)의 `worktree_path` / `base_ref` 를 단독-stage 모드가 읽어야 한다. 기존 `get_implementation_base` 패턴과 동일한 read-only getter 를 추가한다.
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+Create `tests/test_get_stage_row.py`:
+
+```python
+"""Unit coverage for worktree_registry.get_stage_row.
+
+conftest.py 의 autouse fixture 가 OKSTRA_HOME 을 임시 디렉터리로 격리하므로
+registry write 가 사용자 ~/.okstra 를 오염시키지 않는다."""
+import sys
+from pathlib import Path
+
+LIB_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl import worktree_registry as reg
+
+
+def test_get_stage_row_returns_reserved_row():
+    reg.reserve(
+        project_id="p", task_group="g", task_id="t",
+        worktree_path="/wt/stage-2", branch="fix-t-s2",
+        base_ref="abc123", stage_number=2,
+    )
+    row = reg.get_stage_row("p", "g", "t", 2)
+    assert row is not None
+    assert row["worktree_path"] == "/wt/stage-2"
+    assert row["base_ref"] == "abc123"
+
+
+def test_get_stage_row_missing_returns_none():
+    assert reg.get_stage_row("p", "g", "t", 9) is None
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_get_stage_row.py -v`
+Expected: FAIL — `AttributeError: module ... has no attribute 'get_stage_row'`
+
+- [ ] **Step 3: getter 구현**
+
+In `scripts/okstra_ctl/worktree_registry.py`, 추가 (after `get_implementation_base`, around line 233):
+
+```python
+def get_stage_row(
+    project_id: str, task_group: str, task_id: str, stage: int,
+) -> Optional[dict]:
+    """Return the stage-key registry row (worktree_path / base_ref / branch)
+    for `<task-key>#stage-<stage>`, or None when no such reservation exists."""
+    key = task_key(project_id, task_group, task_id, stage)
+    with _registry_lock():
+        data = _load()
+        return data["tasks"].get(key)
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_get_stage_row.py -v`
+Expected: PASS (2 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/worktree_registry.py tests/test_get_stage_row.py
+git commit -m "feat(run): worktree_registry.get_stage_row 조회 getter"
+```
+
+---
+
+## Task 2: 전체-task target 순수 함수 (TDD)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py`
+- Test: `tests/test_final_verification_target.py`
+
+전체-task 모드의 결정 로직: 모든 Stage Map stage 가 done, 모든 done stage 가 HEAD ancestor, worktree clean(.okstra 제외) 이면 target 반환, 아니면 PrepareError. git/registry IO 는 인자로 주입받는 순수 함수.
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+Create `tests/test_final_verification_target.py`:
+
+```python
+"""Unit coverage for run._resolve_whole_task_target / _resolve_single_stage_target."""
+import sys
+from pathlib import Path
+
+import pytest
+
+LIB_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl import run            # run._resolve_*, run.PrepareError, run._FVTarget
+
+PrepareError = run.PrepareError
+
+STAGE_MAP = [{"stage_number": 1}, {"stage_number": 2}]
+
+
+def _done(stage, head, report="r{}.md"):
+    return {"stage": stage, "status": "done", "head_commit": head,
+            "report_path": report.format(stage)}
+
+
+def test_whole_task_ok():
+    target = run._resolve_whole_task_target(
+        stage_map=STAGE_MAP,
+        done_rows=[_done(1, "c1"), _done(2, "c2")],
+        anchor_base="base0",
+        task_worktree_path="/wt",
+        task_head="HEAD9",
+        task_dirty=False,
+        merged={1: True, 2: True},
+    )
+    assert target.scope == "whole-task"
+    assert target.base == "base0"
+    assert target.head == "HEAD9"
+    assert target.worktree_path == "/wt"
+    assert sorted(target.stages) == [1, 2]
+    assert sorted(target.reports) == ["r1.md", "r2.md"]
+
+
+def test_whole_task_blocks_incomplete_stage():
+    with pytest.raises(PrepareError, match="stage 2 not done"):
+        run._resolve_whole_task_target(
+            stage_map=STAGE_MAP, done_rows=[_done(1, "c1")],
+            anchor_base="base0", task_worktree_path="/wt",
+            task_head="HEAD9", task_dirty=False, merged={1: True},
+        )
+
+
+def test_whole_task_blocks_unmerged_stage():
+    with pytest.raises(PrepareError, match="not merged"):
+        run._resolve_whole_task_target(
+            stage_map=STAGE_MAP,
+            done_rows=[_done(1, "c1"), _done(2, "c2")],
+            anchor_base="base0", task_worktree_path="/wt",
+            task_head="HEAD9", task_dirty=False,
+            merged={1: True, 2: False},
+        )
+
+
+def test_whole_task_blocks_dirty():
+    with pytest.raises(PrepareError, match="uncommitted source changes"):
+        run._resolve_whole_task_target(
+            stage_map=STAGE_MAP,
+            done_rows=[_done(1, "c1"), _done(2, "c2")],
+            anchor_base="base0", task_worktree_path="/wt",
+            task_head="HEAD9", task_dirty=True,
+            merged={1: True, 2: True},
+        )
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_final_verification_target.py -v`
+Expected: FAIL — `AttributeError: ... has no attribute '_resolve_whole_task_target'`
+
+- [ ] **Step 3: 순수 함수 + 데이터클래스 구현**
+
+In `scripts/okstra_ctl/run.py`, 추가 (after `_resolve_stage_base_commit`, around line 378). 먼저 파일 상단 import 영역에 `from dataclasses import dataclass, field` 가 이미 있는지 확인하고 없으면 추가. 그다음:
+
+```python
+@dataclass
+class _FVTarget:
+    scope: str            # "whole-task" | "single-stage"
+    base: str
+    head: str
+    worktree_path: str
+    stages: list          # list[int]
+    reports: list         # list[str], report_path 값(없으면 "")
+
+
+def _resolve_whole_task_target(
+    *, stage_map: list, done_rows: list, anchor_base: str,
+    task_worktree_path: str, task_head: str, task_dirty: bool,
+    merged: dict,
+) -> "_FVTarget":
+    """전체-task 검증 target. 모든 Stage Map stage 가 done + HEAD 에 머지 +
+    worktree clean 이어야 한다. 위반 시 PrepareError."""
+    done_by_stage = {r["stage"]: r for r in done_rows}
+    for s in stage_map:
+        n = s["stage_number"]
+        if n not in done_by_stage:
+            raise PrepareError(
+                f"final-verification(whole-task): stage {n} not done — "
+                f"run implementation --stage {n} first"
+            )
+        if not merged.get(n, False):
+            sha = done_by_stage[n].get("head_commit", "")
+            raise PrepareError(
+                f"final-verification(whole-task): stage {n} done commit "
+                f"{sha} not merged into task worktree HEAD — merge stage "
+                "branches then retry"
+            )
+    if task_dirty:
+        raise PrepareError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    stages = [s["stage_number"] for s in stage_map]
+    reports = [done_by_stage[n].get("report_path", "") for n in stages]
+    return _FVTarget(
+        scope="whole-task", base=anchor_base, head=task_head,
+        worktree_path=task_worktree_path, stages=stages, reports=reports,
+    )
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_final_verification_target.py -v`
+Expected: PASS (4 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/run.py tests/test_final_verification_target.py
+git commit -m "feat(run): 전체-task final-verification target 순수 함수"
+```
+
+---
+
+## Task 3: 단독-stage target 순수 함수 (TDD)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py`
+- Test: `tests/test_final_verification_target.py` (append)
+
+단독-stage 모드: stage N 이 done 이고 stage worktree 가 존재하고 clean 이면 target 반환. 다른 stage 무관.
+
+- [ ] **Step 1: 실패 테스트 추가**
+
+Append to `tests/test_final_verification_target.py`:
+
+```python
+def test_single_stage_ok():
+    target = run._resolve_single_stage_target(
+        requested_stage="2",
+        done_rows=[_done(1, "c1"), _done(2, "c2")],
+        stage_base="base2",
+        stage_worktree_path="/wt/stage-2",
+        stage_head="c2",
+        stage_dirty=False,
+    )
+    assert target.scope == "single-stage"
+    assert target.base == "base2"
+    assert target.head == "c2"
+    assert target.worktree_path == "/wt/stage-2"
+    assert target.stages == [2]
+    assert target.reports == ["r2.md"]
+
+
+def test_single_stage_blocks_not_done():
+    with pytest.raises(PrepareError, match="stage 3 not done"):
+        run._resolve_single_stage_target(
+            requested_stage="3", done_rows=[_done(1, "c1")],
+            stage_base="x", stage_worktree_path="/wt/stage-3",
+            stage_head="x", stage_dirty=False,
+        )
+
+
+def test_single_stage_blocks_missing_worktree():
+    with pytest.raises(PrepareError, match="stage worktree not found"):
+        run._resolve_single_stage_target(
+            requested_stage="2", done_rows=[_done(2, "c2")],
+            stage_base="base2", stage_worktree_path="",
+            stage_head="c2", stage_dirty=False,
+        )
+
+
+def test_single_stage_blocks_dirty():
+    with pytest.raises(PrepareError, match="uncommitted source changes"):
+        run._resolve_single_stage_target(
+            requested_stage="2", done_rows=[_done(2, "c2")],
+            stage_base="base2", stage_worktree_path="/wt/stage-2",
+            stage_head="c2", stage_dirty=True,
+        )
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_final_verification_target.py -k single_stage -v`
+Expected: FAIL — `AttributeError: ... has no attribute '_resolve_single_stage_target'`
+
+- [ ] **Step 3: 순수 함수 구현**
+
+In `scripts/okstra_ctl/run.py`, 추가 (after `_resolve_whole_task_target`):
+
+```python
+def _resolve_single_stage_target(
+    *, requested_stage: str, done_rows: list, stage_base: str,
+    stage_worktree_path: str, stage_head: str, stage_dirty: bool,
+) -> "_FVTarget":
+    """단독-stage 검증 target. stage N 만 done + stage worktree 존재 + clean.
+    다른 stage 의 done/머지 여부와 무관. 위반 시 PrepareError."""
+    n = int(requested_stage)
+    done_by_stage = {r["stage"]: r for r in done_rows}
+    if n not in done_by_stage:
+        raise PrepareError(
+            f"final-verification(single-stage): stage {n} not done — "
+            f"run implementation --stage {n} first"
+        )
+    if not stage_worktree_path:
+        raise PrepareError(
+            f"final-verification(single-stage): stage worktree not found for "
+            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
+        )
+    if stage_dirty:
+        raise PrepareError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    return _FVTarget(
+        scope="single-stage", base=stage_base, head=stage_head,
+        worktree_path=stage_worktree_path, stages=[n],
+        reports=[done_by_stage[n].get("report_path", "")],
+    )
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_final_verification_target.py -v`
+Expected: PASS (8 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/run.py tests/test_final_verification_target.py
+git commit -m "feat(run): 단독-stage final-verification target 순수 함수"
+```
+
+---
+
+## Task 4: IO 래퍼 + prepare 분기 + ctx 주입 (통합 테스트)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py`
+- Test: `tests/test_reserve_final_verification.py`
+
+facts(registry/consumers/git)를 모아 순수 함수로 디스패치하는 얇은 래퍼 `_reserve_final_verification_target` 를 만들고, `prepare_task_bundle` 의 task_type 분기에 연결한다. ctx 에 `VERIFICATION_TARGET` 블록을 채운다.
+
+- [ ] **Step 1: 실패 테스트 작성 (tmp git repo + monkeypatch)**
+
+Create `tests/test_reserve_final_verification.py`:
+
+```python
+"""Integration coverage for run._reserve_final_verification_target.
+
+conftest.py 가 OKSTRA_HOME 을 격리하므로 registry 예약은 임시 home 에 쓰인다."""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+LIB_DIR = REPO / "scripts"
+if str(LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl import run
+from okstra_ctl import worktree_registry as reg
+
+
+def _git(cwd, *args):
+    subprocess.run(["git", *args], cwd=cwd, check=True,
+                   capture_output=True, text=True)
+
+
+def _commit(cwd, name):
+    (Path(cwd) / name).write_text("x", encoding="utf-8")
+    _git(cwd, "add", name)
+    _git(cwd, "commit", "-m", name)
+    r = subprocess.run(["git", "rev-parse", "HEAD"], cwd=cwd,
+                       capture_output=True, text=True, check=True)
+    return r.stdout.strip()
+
+
+def test_whole_task_target_ctx(tmp_path):
+    # task worktree git repo: base → stage1 commit → stage2 commit (선형 머지)
+    wt = tmp_path / "wt"
+    wt.mkdir()
+    _git(wt, "init", "-q")
+    _git(wt, "config", "user.email", "t@t")
+    _git(wt, "config", "user.name", "t")
+    base = _commit(wt, "base.txt")
+    c1 = _commit(wt, "s1.txt")
+    c2 = _commit(wt, "s2.txt")
+
+    # consumers.jsonl: stage 1,2 done
+    plan_run_root = tmp_path / "planrun"
+    plan_run_root.mkdir()
+    rows = [
+        {"impl_task_key": "k", "stage": 1, "status": "done",
+         "head_commit": c1, "report_path": "r1.md"},
+        {"impl_task_key": "k", "stage": 2, "status": "done",
+         "head_commit": c2, "report_path": "r2.md"},
+    ]
+    (plan_run_root / "consumers.jsonl").write_text(
+        "\n".join(json.dumps(r) for r in rows) + "\n", encoding="utf-8")
+
+    reg.reserve(project_id="p", task_group="g", task_id="t",
+                worktree_path=str(wt), branch="fix-t", base_ref=base)
+    reg.set_implementation_base("p", "g", "t", base)
+
+    ctx = {"EXECUTOR_WORKTREE_PATH": str(wt)}
+    inp = run.PrepareInputs(
+        workspace_root=REPO, project_root=wt, project_id="p",
+        task_group="g", task_id="t", task_type="final-verification",
+        brief_path=tmp_path / "brief.md",
+        approved_plan_path=str(plan_run_root / "reports" / "plan.md"),
+        stage="auto",
+    )
+    stage_map = [{"stage_number": 1}, {"stage_number": 2}]
+    run._reserve_final_verification_target(inp, ctx, stage_map)
+
+    block = ctx["VERIFICATION_TARGET"]
+    assert "whole-task" in block
+    assert base in block          # base ref injected
+    assert c2 in block            # head SHA injected
+    assert "stage 2" in block.lower()
+```
+
+참고: `approved_plan_path` 의 `parents[1]` 가 `plan_run_root` 가 되도록 `<plan_run_root>/reports/plan.md` 로 둔다 ([run.py:1002](../../../scripts/okstra_ctl/run.py:1002) 의 `Path(approved_plan_path).resolve().parents[1]` 규칙).
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_reserve_final_verification.py -v`
+Expected: FAIL — `AttributeError: ... has no attribute '_reserve_final_verification_target'`
+
+- [ ] **Step 3: IO 래퍼 구현**
+
+In `scripts/okstra_ctl/run.py`, 추가 (after `_reserve_implementation_stages`, around line 1099):
+
+```python
+def _git_out(cwd, *args) -> str:
+    r = _subprocess.run(["git", "-C", str(cwd), *args],
+                        capture_output=True, text=True)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def _is_ancestor(cwd, commit, head) -> bool:
+    if not commit or not head:
+        return False
+    r = _subprocess.run(
+        ["git", "-C", str(cwd), "merge-base", "--is-ancestor", commit, head],
+        capture_output=True, text=True,
+    )
+    return r.returncode == 0
+
+
+def _is_dirty_excluding_okstra(cwd) -> bool:
+    out = _git_out(cwd, "status", "--short", "--", ".", ":(exclude).okstra")
+    return bool(out.strip())
+
+
+def _reserve_final_verification_target(
+    inp: "PrepareInputs", ctx: dict, ctx_stage_map: list,
+) -> None:
+    """final-verification 의 검증 target 을 registry/consumers/git 에서
+    해소하고 gate 를 강제한다. 위반 시 PrepareError. 결과를 ctx 의
+    VERIFICATION_* 키로 주입한다."""
+    from .consumers import read_consumers
+    from . import worktree_registry as _reg
+
+    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    done_rows = [r for r in read_consumers(plan_run_root)
+                 if r.get("status") == "done"]
+
+    if inp.stage and inp.stage != "auto":
+        n = int(inp.stage)
+        row = _reg.get_stage_row(inp.project_id, inp.task_group, inp.task_id, n)
+        wt_path = (row or {}).get("worktree_path", "")
+        stage_base = (row or {}).get("base_ref", "")
+        head = _git_out(wt_path, "rev-parse", "HEAD") if wt_path else ""
+        target = _resolve_single_stage_target(
+            requested_stage=inp.stage, done_rows=done_rows,
+            stage_base=stage_base, stage_worktree_path=wt_path,
+            stage_head=head,
+            stage_dirty=_is_dirty_excluding_okstra(wt_path) if wt_path else False,
+        )
+        ctx["EXECUTOR_WORKTREE_PATH"] = wt_path
+    else:
+        wt_path = ctx["EXECUTOR_WORKTREE_PATH"]
+        anchor = _reg.get_implementation_base(
+            inp.project_id, inp.task_group, inp.task_id) or ""
+        head = _git_out(wt_path, "rev-parse", "HEAD")
+        merged = {r["stage"]: _is_ancestor(wt_path, r.get("head_commit", ""), head)
+                  for r in done_rows}
+        target = _resolve_whole_task_target(
+            stage_map=ctx_stage_map, done_rows=done_rows, anchor_base=anchor,
+            task_worktree_path=wt_path, task_head=head,
+            task_dirty=_is_dirty_excluding_okstra(wt_path), merged=merged,
+        )
+
+    diff_stat = _git_out(target.worktree_path, "diff", "--stat",
+                         f"{target.base}..{target.head}")
+    reports = "\n".join(
+        f"  - stage {s}: `{rp or '(report_path 미기록)'}`"
+        for s, rp in zip(target.stages, target.reports)
+    )
+    ctx["VERIFICATION_TARGET"] = (
+        f"- **Verification scope:** `{target.scope}`\n"
+        f"- **Worktree:** `{target.worktree_path}`\n"
+        f"- **Verification base ref:** `{target.base}`\n"
+        f"- **Verification head SHA:** `{target.head}`\n"
+        f"- **Stages under verification:** {target.stages}\n"
+        f"- **Source implementation reports:**\n{reports}\n"
+        f"- **Verification diff stat:**\n```\n{diff_stat}\n```"
+    )
+```
+
+참고: `_subprocess` 는 run.py 가 이미 `import subprocess as _subprocess` 로 보유 (`_reserve_implementation_stages` 에서 사용 중 — [run.py:1032](../../../scripts/okstra_ctl/run.py:1032)).
+
+- [ ] **Step 4: prepare 분기 + stage_map 파싱 연결**
+
+In `scripts/okstra_ctl/run.py`, [run.py:1442](../../../scripts/okstra_ctl/run.py:1442) 의 분기를 확장:
+
+```python
+    if inp.task_type == "implementation":
+        _reserve_implementation_stages(inp, ctx, ctx_stage_map)
+    elif inp.task_type == "final-verification":
+        _reserve_final_verification_target(inp, ctx, ctx_stage_map)
+```
+
+그리고 [run.py:817](../../../scripts/okstra_ctl/run.py:817) 부근에서 `ctx_stage_map` 이 implementation 에서만 파싱되므로, final-verification 도 (전체-task 모드의 Stage Map 열거용) 파싱하도록 조건 확장. 해당 `if inp.task_type == "implementation":` 블록의 plan 검증/파싱 중 **stage map 파싱만** final-verification 에도 적용:
+
+```python
+    if inp.task_type in ("implementation", "final-verification"):
+        if not inp.approved_plan_path:
+            raise PrepareError(
+                f"--approved-plan is required for {inp.task_type}")
+        _validate_approved_plan(inp.approved_plan_path)
+        _validate_stage_structure(inp.approved_plan_path)
+        ctx_stage_map = _parse_stage_map_into_ctx(inp.approved_plan_path)
+```
+
+주의: 기존 implementation 전용 로직(`_apply_cli_approval`, `implementation_option` frontmatter 주입, `_validate_stage` 의 `inp.stage != "auto"` 등 [run.py:798-836](../../../scripts/okstra_ctl/run.py:798))은 implementation 분기에 그대로 남기고, 위 공통화는 plan 존재·stage map 파싱에 한정한다. 실제 구현 시 해당 블록을 읽고 implementation-only 부분과 공통 부분을 분리할 것.
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_reserve_final_verification.py -v`
+Expected: PASS
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/run.py tests/test_reserve_final_verification.py
+git commit -m "feat(run): final-verification target IO 래퍼 + prepare 분기 + ctx 주입"
+```
+
+---
+
+## Task 5: consumers `report_path` round-trip + lead 계약
+
+**Files:**
+- Test: `tests/test_consumers_report_path.py` (신규)
+- Modify: `prompts/profiles/_implementation-deliverable.md`
+
+`append_consumer` 는 이미 `**fields` 로 임의 필드를 저장하므로 ([consumers.py:35](../../../scripts/okstra_ctl/consumers.py:35)) Python 변경은 없다. round-trip 회귀 테스트로 계약을 고정하고, lead 가 done 행에 `report_path` 를 넣도록 프로파일 계약을 갱신한다.
+
+- [ ] **Step 1: round-trip 테스트 작성**
+
+Create `tests/test_consumers_report_path.py`:
+
+```python
+"""report_path 필드가 consumers done 행에 round-trip 되는지 회귀 고정."""
+import sys
+from pathlib import Path
+
+LIB_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl import consumers as cons
+
+
+def test_report_path_round_trips(tmp_path):
+    cons.append_consumer(
+        tmp_path, impl_task_key="k", stage=1, status="done",
+        head_commit="c1", report_path="runs/k/reports/final-report-1.md",
+    )
+    rows = cons.read_consumers(tmp_path)
+    assert rows[0]["report_path"] == "runs/k/reports/final-report-1.md"
+```
+
+- [ ] **Step 2: 테스트 통과 확인 (이미 지원하므로 바로 PASS)**
+
+Run: `python3 -m pytest tests/test_consumers_report_path.py -v`
+Expected: PASS (1 passed) — `**fields` 가 이미 동작함을 고정.
+
+- [ ] **Step 3: lead 계약 갱신**
+
+In `prompts/profiles/_implementation-deliverable.md`, [_implementation-deliverable.md:52](../../../prompts/profiles/_implementation-deliverable.md:52) 의 done 행 append 항목에 `report_path` 추가. 기존:
+
+```
+- For EACH stage in this run's batch: append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, and the SHA of HEAD. Use the okstra runtime's `consumers_mutex` helper (NOT a raw filesystem write) to honour the lock.
+```
+
+변경 후:
+
+```
+- For EACH stage in this run's batch: append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, `report_path` (this run's final-report path relative to the run root), and the SHA of HEAD. Use the okstra runtime's `consumers_mutex` helper (NOT a raw filesystem write) to honour the lock. `report_path` lets `final-verification` cite each stage's originating report when assembling its Source Implementation Report list.
+```
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add tests/test_consumers_report_path.py prompts/profiles/_implementation-deliverable.md
+git commit -m "feat(profiles): consumers done 행에 report_path + round-trip 회귀 테스트"
+```
+
+---
+
+## Task 6: launch 템플릿 `{{VERIFICATION_TARGET}}` 주입
+
+**Files:**
+- Modify: `prompts/launch.template.md`
+
+final-verification run 의 launch 프롬프트에 검증 target snapshot 을 주입한다. implementation 의 `{{STAGE_BATCH_DIRECTIVE}}` 와 대칭 ([launch.template.md:18](../../../prompts/launch.template.md:18)).
+
+- [ ] **Step 1: 주입 토큰 추가**
+
+In `prompts/launch.template.md`, [launch.template.md:18](../../../prompts/launch.template.md:18) 의 `{{STAGE_BATCH_DIRECTIVE}}` 줄 바로 다음에 추가:
+
+```
+{{VERIFICATION_TARGET}}
+```
+
+- [ ] **Step 2: 빈 값 기본 처리 확인**
+
+implementation/기타 phase 에서는 `VERIFICATION_TARGET` 이 ctx 에 없을 수 있다. 렌더러가 미정의 토큰을 빈 문자열로 치환하는지(기존 `STAGE_BATCH_DIRECTIVE` 가 implementation 외 phase 에서 빈 값으로 처리되는 방식과 동일한지) 확인하고, 그렇지 않으면 `_reserve_final_verification_target` 미호출 경로(다른 task_type)에서 `ctx.setdefault("VERIFICATION_TARGET", "")` 를 prepare 공통부에 추가.
+
+Run: `grep -n "STAGE_BATCH_DIRECTIVE\|setdefault\|VERIFICATION_TARGET" scripts/okstra_ctl/run.py`
+Expected: `STAGE_BATCH_DIRECTIVE` 의 빈값 기본 처리 패턴을 찾아 동일하게 적용.
+
+- [ ] **Step 3: 렌더 스모크**
+
+Run: `node bin/okstra --version`
+Expected: 정상 출력 (템플릿 파싱 오류 없음). 더해 `python3 -m pytest tests/ -k "template or render" -q` 가 깨지지 않는지 확인.
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add prompts/launch.template.md scripts/okstra_ctl/run.py
+git commit -m "feat(launch): final-verification 에 VERIFICATION_TARGET 주입"
+```
+
+---
+
+## Task 7: final-verification 프로파일 재작성 (두 모드)
+
+**Files:**
+- Modify: `prompts/profiles/final-verification.md`
+
+entry gate 를 "단일 report" 전제에서 "Python prep 이 해소·강제하는 두 모드" 로 재작성하고, Source Implementation Report 를 목록으로, routing 을 모드별로 제약한다.
+
+- [ ] **Step 1: entry gate 재작성**
+
+In `prompts/profiles/final-verification.md`, `Pre-verification entry gate` 블록([final-verification.md:25](../../../prompts/profiles/final-verification.md:25))을 교체:
+
+```
+- Pre-verification entry gate (resolved & enforced by `okstra render-bundle` prep — the lead does NOT recompute it):
+  - the verification target (scope / worktree / base / head / stages / source reports / diff stat) is injected as the `VERIFICATION_TARGET` block. The lead MUST treat it as authoritative and MUST NOT re-pick a target from the brief.
+  - **whole-task scope** (`--stage auto`, default): prep has already verified every Stage Map stage is `status:done` in `consumers.jsonl`, every done stage's `head_commit` is an ancestor of the task worktree HEAD (all stage branches merged), and the worktree is clean outside `.okstra/`. If any check failed the run never started (PrepareError); a started whole-task run is therefore a fully-merged, clean target.
+  - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification and MUST NOT recommend `release-handoff`.
+  - the lead still captures `git rev-parse HEAD` / `git status --short` from the injected worktree to confirm the analysis ran against the injected head; a mismatch is a `tool-failure`, not a silent proceed.
+```
+
+- [ ] **Step 2: Source Implementation Report 를 목록으로**
+
+[final-verification.md:31](../../../prompts/profiles/final-verification.md:31) 의 `Source Implementation Report` deliverable 항목을 교체:
+
+```
+  - **Source Implementation Report(s)**: the `VERIFICATION_TARGET` snapshot verbatim — verification scope, worktree path, base/head SHAs, the list of stages under verification, and one row per stage citing its originating implementation final-report (`report_path` from `consumers.jsonl`; render `(report_path unrecorded)` when absent). The lead injects this same snapshot into every analyser prompt (`**Verification scope:** / **Worktree:** / **Verification base ref:** / **Verification head SHA:** / **Verification diff stat:**`); a worker that cannot confirm its analysis ran against that exact head MUST record a `tool-failure`.
+```
+
+- [ ] **Step 3: routing 제약 추가**
+
+[final-verification.md:38](../../../prompts/profiles/final-verification.md:38) 의 `Routing recommendation` 항목 끝에 한 문장 추가:
+
+```
+`release-handoff` is additionally allowed ONLY when the verification scope (the `Verification scope:` line of the injected `VERIFICATION_TARGET` block, recorded as the report's `verificationScope` field) is `whole-task`; a `single-stage` run is partial and routes to `implementation` / `done` even on an `accepted` verdict.
+```
+
+- [ ] **Step 4: 토큰 일관성 grep**
+
+Run: `grep -rn "VERIFICATION_TARGET\|verificationScope\|whole-task\|single-stage" prompts/ scripts/okstra_ctl/run.py validators/validate-run.py`
+Expected: `VERIFICATION_TARGET` 는 run.py(주입)·launch.template(치환)·profile(소비) 에서 일치; `verificationScope` 는 profile·validate-run·스키마 에서 일치; scope 값은 `whole-task`/`single-stage` 두 가지로만 등장.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add prompts/profiles/final-verification.md
+git commit -m "feat(profiles/final-verification): 두 모드 entry gate + Source Implementation Report 목록 + routing 제약"
+```
+
+---
+
+## Task 8: wizard final-verification 서브플로우 (TDD)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py`
+- Test: `tests/test_wizard_final_verification_stage.py` (신규)
+
+final-verification 에 approved-plan picker 와 stage 3-옵션 picker(추천=전체 `auto` / 특정 stage / 직접 입력)를 노출하고, `selected_stage` 를 final-verification 에서도 render-args 로 emit 한다.
+
+- [ ] **Step 1: 현재 wizard 흐름 확인**
+
+Run: `grep -n "selected_stage\|_render_stage_picker\|approved_plan\|task_type ==\|task_type in\|render_args\|\"stage\"" scripts/okstra_ctl/wizard.py`
+Expected: implementation 전용 stage/approved-plan 단계 위치 파악. 특히 [wizard.py:2353](../../../scripts/okstra_ctl/wizard.py:2353) `"stage": ... if state.task_type == "implementation" else ""` 와 stage picker step 의 `applies=` 조건.
+
+- [ ] **Step 2: 실패 테스트 작성**
+
+Create `tests/test_wizard_final_verification_stage.py`:
+
+```python
+"""final-verification 이 render-args 에 selected_stage 를 emit 하는지."""
+import sys
+from pathlib import Path
+
+LIB_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(LIB_DIR))
+
+from okstra_ctl import wizard as wiz
+
+
+def test_final_verification_emits_stage():
+    state = wiz.WizardState()
+    state.task_type = "final-verification"
+    state.selected_stage = "2"
+    args = wiz.render_args(state)   # [wizard.py:2332] render_args(state) -> dict
+    assert args["stage"] == "2"
+
+
+def test_implementation_still_emits_stage():
+    state = wiz.WizardState()
+    state.task_type = "implementation"
+    state.selected_stage = "auto"
+    args = wiz._render_args(state)
+    assert args["stage"] == "auto"
+```
+
+- [ ] **Step 3: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_final_verification_stage.py -v`
+Expected: FAIL — final-verification 의 `stage` 가 `""` 로 emit 됨.
+
+- [ ] **Step 4: emit 조건 확장**
+
+In `scripts/okstra_ctl/wizard.py`, [wizard.py:2353](../../../scripts/okstra_ctl/wizard.py:2353):
+
+```python
+        "stage": (state.selected_stage or "auto") if state.task_type in ("implementation", "final-verification") else "",
+```
+
+그리고 stage picker step 과 approved-plan step 의 `applies=` 람다([wizard.py:2007](../../../scripts/okstra_ctl/wizard.py:2007) 인근 그룹)를 final-verification 도 포함하도록 확장. stage picker 추천 라벨은 전체-task 기준으로 `auto` = "전체 task (모든 stage 머지 후 한 번)" 로 문구를 맞추고, 마지막 옵션은 항상 "직접 입력" 유지(피드백 규칙: 3-옵션 picker).
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_wizard_final_verification_stage.py -v`
+Expected: PASS (2 passed)
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_final_verification_stage.py
+git commit -m "feat(wizard): final-verification 에 stage 3-옵션 picker + approved-plan"
+```
+
+---
+
+## Task 9: validate-run 모드/라우팅 검증 (TDD)
+
+**Files:**
+- Modify: `validators/validate-run.py`
+- Test: `tests/test_validate_run.py` (append; 파일 존재 위치는 Step 1 에서 확인)
+
+`verificationScope` 필드를 인식하고, `release-handoff` routing 추천은 `whole-task` 일 때만 허용한다.
+
+- [ ] **Step 1: 기존 final-verification 검증 블록 확인**
+
+Run: `grep -n "_validate_final_verification_consistency\|verdictToken\|routingRecommendation\|failures.append" validators/validate-run.py`
+Expected: 강제 함수는 `_validate_final_verification_consistency(data, failures)` ([validate-run.py:1066](../../../validators/validate-run.py:1066)) — `failures` 리스트에 메시지를 append 하는 방식. data dict 의 final-verification 필드명(`verdictToken` / `routingRecommendation` 등)을 정확히 확인.
+
+- [ ] **Step 2: 실패 테스트 작성**
+
+Append to `tests/test_validate_run.py` (없으면 신규 생성, import 는 기존 테스트 패턴을 따름):
+
+```python
+# vr = 기존 test_validate_run.py 가 validate-run.py 를 로드하는 방식 그대로 재사용
+# (파일명에 하이픈이 있어 importlib.spec_from_file_location 로 로드 — 기존 패턴 따름).
+# valid_fv_data() 는 기존 테스트의 final-verification 유효 data dict 빌더를 재사용하거나,
+# 없으면 Step 1 에서 확인한 필수 필드로 최소 유효 dict 를 만드는 헬퍼로 추가.
+
+def test_single_stage_cannot_route_release_handoff():
+    data = valid_fv_data()
+    data["verificationScope"] = "single-stage"
+    data["routingRecommendation"] = "release-handoff"
+    failures = []
+    vr._validate_final_verification_consistency(data, failures)
+    assert any("single-stage" in f for f in failures)
+
+
+def test_whole_task_may_route_release_handoff():
+    data = valid_fv_data()
+    data["verificationScope"] = "whole-task"
+    data["verdictToken"] = "accepted"
+    data["routingRecommendation"] = "release-handoff"
+    failures = []
+    vr._validate_final_verification_consistency(data, failures)
+    assert not any("single-stage" in f for f in failures)
+```
+
+주: `vr` 모듈 핸들과 `valid_fv_data` 빌더는 기존 `tests/test_validate_run.py` 의 final-verification 테스트에서 쓰는 로더/빌더를 그대로 재사용한다(Step 1 에서 위치·이름 확인). 이 validator 파일은 하이픈 파일명이라 package import 가 불가하므로 importlib 로드가 맞다(run.py/wizard 와 다름).
+
+- [ ] **Step 3: 테스트 실패 확인**
+
+Run: `python3 -m pytest tests/test_validate_run.py -k "scope or release_handoff" -v`
+Expected: FAIL (규칙 미구현).
+
+- [ ] **Step 4: 검증 규칙 구현**
+
+In `validators/validate-run.py`, `_validate_final_verification_consistency(data, failures)` ([validate-run.py:1066](../../../validators/validate-run.py:1066)) 본문 끝에 추가:
+
+```python
+    scope = data.get("verificationScope", "whole-task")
+    if scope not in ("whole-task", "single-stage"):
+        failures.append(
+            f"verificationScope must be whole-task|single-stage, got {scope!r}")
+    routing = data.get("routingRecommendation", "")
+    if scope == "single-stage" and routing == "release-handoff":
+        failures.append(
+            "verificationScope=single-stage cannot recommend release-handoff "
+            "(partial verification)"
+        )
+```
+
+(data dict 의 routing 필드명이 `routingRecommendation` 이 아니면 Step 1 에서 확인한 실제 키로 맞춘다.)
+
+- [ ] **Step 5: 테스트 통과 + 워크플로 검증**
+
+Run: `python3 -m pytest tests/test_validate_run.py -v && bash validators/validate-workflow.sh`
+Expected: PASS / OK.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add validators/validate-run.py tests/test_validate_run.py
+git commit -m "feat(validators): final-verification verificationScope + release-handoff routing 제약"
+```
+
+---
+
+## Task 10: 입력 템플릿 + 스키마 필드
+
+**Files:**
+- Modify: `templates/reports/final-verification-input.template.md`
+- Modify: report data.json 스키마 (Step 1 에서 위치 확인)
+
+`verificationScope` 와 stage 목록을 report data.json 스키마에 추가하고, 입력 템플릿이 두 모드를 안내하도록 갱신한다.
+
+- [ ] **Step 1: 스키마 위치 확인**
+
+Run: `grep -rn "verdictToken\|routingRecommendation\|final-verification" templates/ | grep -i "schema\|json"`
+Expected: final-verification report data.json 스키마 파일 경로 파악.
+
+- [ ] **Step 2: 스키마에 `verificationScope` 추가**
+
+해당 스키마의 properties 에 추가 (정확한 들여쓰기는 파일에 맞춤):
+
+```json
+"verificationScope": { "type": "string", "enum": ["whole-task", "single-stage"] }
+```
+
+required 목록에 `verificationScope` 포함 여부는 기존 required 정책에 맞춘다(신규 필드라 pre-1.0 정책상 required 로 추가 가능).
+
+- [ ] **Step 3: 입력 템플릿 갱신**
+
+In `templates/reports/final-verification-input.template.md`, brief 가 worktree/base 를 수동 기입하던 안내가 있으면 제거하고, 다음 안내를 추가:
+
+```
+## 검증 모드
+
+- 기본은 **전체-task** 검증입니다(`--stage auto`). 모든 Stage Map stage 가 구현·머지된 뒤 한 번 실행하세요.
+- 특정 stage 만 격리 검증하려면 `--stage N` 으로 단독-stage 모드를 쓰세요(release-handoff 진입 불가).
+- worktree / base / head 는 okstra 가 registry 와 consumers.jsonl 에서 자동 해소하므로 수동 기입하지 않습니다.
+```
+
+- [ ] **Step 4: 렌더 회귀**
+
+Run: `python3 -m pytest tests/ -k "template or render" -q`
+Expected: PASS (golden 갱신이 필요하면 빌드로 재생성 후 diff 검토).
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add templates/
+git commit -m "feat(templates): final-verification verificationScope 스키마 + 입력 안내 두 모드"
+```
+
+---
+
+## Task 11: e2e 시나리오 + 빌드 + 전체 스위트
+
+**Files:**
+- Create: `tests-e2e/scenario-<id>-final-verification-modes.sh`
+
+기존 e2e 패턴(`tests-e2e/scenario-<id>-<name>.sh`, `mktemp -d` OKSTRA_HOME, `trap` cleanup)을 따른다.
+
+- [ ] **Step 1: 시나리오 작성 (E1/E2/E3)**
+
+Create `tests-e2e/scenario-<id>-final-verification-modes.sh`. 기존 `tests-e2e/scenario-01-record-start-reconcile.sh` 의 골격(임시 OKSTRA_HOME, 임시 git project, render-bundle 호출)을 복제하고 다음 3 케이스를 검증:
+
+- **E1 (whole-task pass):** 2-stage plan, stage 1·2 를 implementation 으로 돌려 consumers done 2줄 + 두 stage 브랜치를 task worktree 에 머지 → `render-bundle --task-type final-verification --stage auto` 가 성공하고 출력 bundle 에 `VERIFICATION_SCOPE=whole-task` 가 보일 것.
+- **E2 (whole-task block):** stage 1 done+머지, stage 2 done 이지만 미머지 → `--stage auto` 가 PrepareError(`not merged`)로 비정상 종료(exit≠0)할 것.
+- **E3 (single-stage pass):** stage 1 구현 직후 머지 전 → `--stage 1` 이 성공하고 `VERIFICATION_SCOPE=single-stage` 일 것.
+
+각 케이스는 `render-bundle` 종료코드와 stdout grep 으로 단언한다(실제 worker 실행은 e2e 범위 밖).
+
+- [ ] **Step 2: e2e 실행**
+
+Run: `bash tests-e2e/scenario-<id>-final-verification-modes.sh`
+Expected: 3 케이스 모두 통과 출력.
+
+- [ ] **Step 3: 빌드 동기화**
+
+Run: `npm run build`
+Expected: 성공. `runtime/` 갱신은 커밋하지 않는다.
+
+- [ ] **Step 4: 전체 스위트**
+
+Run: `python3 -m pytest tests/ -q && bash validators/validate-workflow.sh`
+Expected: 전부 PASS / OK.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add tests-e2e/scenario-<id>-final-verification-modes.sh
+git commit -m "test(e2e): final-verification 전체-task/단독-stage 모드 시나리오"
+```
+
+---
+
+## 미해결 / 구현 중 확정 항목
+
+- **`plan_run_root` 해소** (spec §10): 본 계획은 final-verification 이 implementation 과 동일하게 `--approved-plan` 을 받아 `Path(approved_plan_path).parents[1]` 로 plan_run_root 를 도출하는 방식으로 확정했다(Task 4). wizard 가 final-verification 에서 approved-plan 을 반드시 받도록 Task 8 에서 강제한다.
+- **stage worktree teardown** (spec §10): 단독-stage 모드에서 stage worktree 가 정리된 경우 `get_stage_row` 가 None → `worktree_path=""` → `_resolve_single_stage_target` 이 "stage worktree not found … use whole-task mode" PrepareError(Task 3 에서 커버).
+- **golden 렌더 fixture**: Task 6/10 에서 렌더 결과 golden md 가 깨지면 `npm run build` 후 렌더러로 재생성하고 diff 를 검토해 갱신한다(수작업 전사 금지).
+```