okstra 0.52.0 → 0.54.0

package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p3.md

@@ -0,0 +1,774 @@
+# Stage Worktree 격리 P3 — 통합 (run.py + provision) 구현 계획
+
+> **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:** P1/P2 빌딩블록을 결합해 `implementation` run이 실제로 stage 격리 worktree에서 실행되도록 한다 — base 계산 + stage worktree 발급 + `_reserve_implementation_stages` 통합. CLI 패스스루(B2)와 프로파일/release-handoff 문구는 P4.
+
+**Architecture:** 새 pure 헬퍼 `_resolve_stage_base_commit(...)`가 stage 종류(독립/단일 의존/다중 의존)에 따라 base commit을 결정한다. 다중 의존은 first cut에서 명시적 `PrepareError`로 거부([spec §9 #1](../specs/2026-06-06-stage-worktree-isolation-design.md)). 새 함수 `provision_stage_worktree(...)`는 `worktree_registry.reserve(stage_number=...)`(P1)을 사용해 `<task-id>/stage-<N>` 격리 worktree를 발급한다. `_reserve_implementation_stages`(현 [run.py:890](../../../scripts/okstra_ctl/run.py))는 P2 occupied set을 전달하고, batch 의 첫 stage 로 stage worktree 를 발급해 `ctx["EXECUTOR_WORKTREE_*"]` 를 덮어쓰며, batch 의 모든 stage 를 그 stage-key 로 registry 에 reserve 한다.
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/worktree.py`, `worktree_registry.py`, `run.py`), pytest.
+
+설계 문서: [docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md](../specs/2026-06-06-stage-worktree-isolation-design.md) §2.2 / §3 / §4 / §9 #1
+
+---
+
+## File Structure
+
+- Modify: `scripts/okstra_ctl/run.py`
+  - 신규 pure 헬퍼 `_resolve_stage_base_commit()` (모듈 최상단의 helper 군 근처)
+  - `_reserve_implementation_stages()` 통합 갱신 ([run.py:890](../../../scripts/okstra_ctl/run.py))
+- Modify: `scripts/okstra_ctl/worktree.py`
+  - 신규 `provision_stage_worktree()` (기존 `provision_task_worktree` 아래)
+- Test:
+  - `tests/test_okstra_run_stage_base.py` (신규)
+  - `tests/test_okstra_worktree_stage_provision.py` (신규)
+  - `tests/test_okstra_run_reserve_implementation_stages.py` (신규 또는 기존 인접 파일에 추가)
+
+각 task는 위 한 빌딩블록을 완결한다. P4가 프로파일 문구·CLI·release-handoff 를 다룬다.
+
+---
+
+### Task 1: pure 헬퍼 `_resolve_stage_base_commit` — base 계산 + 다중 의존 거부
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py` (신규 모듈 함수, `_resolve_effective_stages` 직후)
+- Test: `tests/test_okstra_run_stage_base.py` (신규)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_okstra_run_stage_base.py (신규)
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+import pytest
+
+from okstra_ctl.run import _resolve_stage_base_commit, PrepareError
+
+
+def _stage(n, deps):
+    return {"stage_number": n, "depends_on": deps, "step_count": 1}
+
+
+def test_independent_stage_uses_anchor_base_commit():
+    stage = _stage(1, [])
+    got = _resolve_stage_base_commit(
+        stage, consumer_done_rows=[],
+        anchor_base_commit="commit-AAA",
+    )
+    assert got == "commit-AAA"
+
+
+def test_single_dependency_uses_predecessor_done_head_commit():
+    stage = _stage(3, [1])
+    consumer_done = [
+        {"stage": 1, "status": "done", "head_commit": "commit-S1-done"},
+        {"stage": 1, "status": "started", "head_commit": "ignored"},
+    ]
+    got = _resolve_stage_base_commit(
+        stage, consumer_done_rows=consumer_done,
+        anchor_base_commit="commit-AAA",
+    )
+    assert got == "commit-S1-done"
+
+
+def test_single_dependency_without_predecessor_done_raises():
+    stage = _stage(3, [1])
+    # stage 1 이 consumers 에 done 으로 없음 — depends-on 미충족
+    with pytest.raises(PrepareError, match="predecessor stage 1 has no done"):
+        _resolve_stage_base_commit(
+            stage, consumer_done_rows=[],
+            anchor_base_commit="commit-AAA",
+        )
+
+
+def test_multi_dependency_rejected_with_guidance():
+    stage = _stage(4, [2, 3])
+    with pytest.raises(PrepareError, match="multi-dependency stage"):
+        _resolve_stage_base_commit(
+            stage, consumer_done_rows=[
+                {"stage": 2, "status": "done", "head_commit": "c2"},
+                {"stage": 3, "status": "done", "head_commit": "c3"},
+            ],
+            anchor_base_commit="commit-AAA",
+        )
+
+
+def test_independent_stage_without_anchor_raises():
+    stage = _stage(1, [])
+    with pytest.raises(PrepareError, match="anchor base commit missing"):
+        _resolve_stage_base_commit(
+            stage, consumer_done_rows=[],
+            anchor_base_commit="",
+        )
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_run_stage_base.py -v`
+Expected: FAIL — `cannot import name '_resolve_stage_base_commit'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# run.py — _resolve_effective_stages 정의 바로 아래에 추가
+def _resolve_stage_base_commit(
+    stage: dict,
+    consumer_done_rows: list,
+    anchor_base_commit: str,
+) -> str:
+    """Pick the git base commit a stage's isolated worktree branches from.
+
+    - 독립 (`depends-on (none)`): anchor (= implementation_base_commit fixed
+      at first stage entry). Caller is responsible for supplying it.
+    - 단일 의존 (`depends-on X`): predecessor X 의 `done.head_commit` from
+      `consumers.jsonl`.
+    - 다중 의존 (`depends-on X,Y…`): first cut 미지원. PrepareError with
+      guidance to merge predecessor branches first (spec §9 #1).
+
+    Raises PrepareError on missing predecessor / missing anchor."""
+    deps = stage.get("depends_on") or []
+    if len(deps) >= 2:
+        raise PrepareError(
+            f"multi-dependency stage {stage['stage_number']} (depends-on "
+            f"{deps}) is not supported in the first stage-isolation cut; "
+            "merge predecessor stage branches first, then start a fresh "
+            "task targeting the merged base"
+        )
+    if not deps:
+        if not anchor_base_commit:
+            raise PrepareError(
+                f"anchor base commit missing for independent stage "
+                f"{stage['stage_number']}; first-stage prepare should have "
+                "fixed it via worktree_registry.set_implementation_base"
+            )
+        return anchor_base_commit
+    # 단일 의존
+    pred = deps[0]
+    for row in consumer_done_rows:
+        if row.get("stage") == pred and row.get("status") == "done":
+            head = row.get("head_commit") or ""
+            if head:
+                return head
+    raise PrepareError(
+        f"predecessor stage {pred} has no done row with head_commit in "
+        "consumers.jsonl; cannot derive base for stage "
+        f"{stage['stage_number']}"
+    )
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_run_stage_base.py -v`
+Expected: PASS (5개).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/run.py tests/test_okstra_run_stage_base.py
+git commit -m "feat(run): resolve stage base commit and reject multi-dependency stages"
+```
+
+---
+
+### Task 2: `provision_stage_worktree` — stage 격리 worktree 발급
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree.py` (신규 함수, `provision_task_worktree` 정의 직후)
+- Test: `tests/test_okstra_worktree_stage_provision.py` (신규)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_okstra_worktree_stage_provision.py (신규)
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+import pytest
+
+
+def _init_repo(repo: Path) -> str:
+    """tmp 디렉터리에 빈 git repo 를 만들고 첫 커밋 sha 를 반환한다."""
+    subprocess.run(["git", "init", "-q", str(repo)], check=True)
+    subprocess.run(["git", "-C", str(repo), "config", "user.email", "t@e"], check=True)
+    subprocess.run(["git", "-C", str(repo), "config", "user.name", "t"], check=True)
+    (repo / "README").write_text("seed\n")
+    subprocess.run(["git", "-C", str(repo), "add", "."], check=True)
+    subprocess.run(["git", "-C", str(repo), "commit", "-q", "-m", "init"], check=True)
+    return subprocess.run(
+        ["git", "-C", str(repo), "rev-parse", "HEAD"],
+        capture_output=True, text=True, check=True,
+    ).stdout.strip()
+
+
+def test_provision_stage_worktree_creates_dir_branch_and_registry_entry(tmp_path):
+    repo = tmp_path / "repo"
+    base_sha = _init_repo(repo)
+    from okstra_ctl.worktree import provision_stage_worktree
+    from okstra_ctl.worktree_registry import lookup
+
+    res = provision_stage_worktree(
+        project_root=repo, project_id="proj",
+        task_group_segment="grp", task_id_segment="tid",
+        work_category="feature",
+        stage_number=2, base_commit=base_sha,
+    )
+    assert res.status == "created"
+    assert Path(res.path).name == "stage-2"
+    assert res.branch == "feat-tid-s2"
+    # registry stage-key 가 active 로 reserve 됐는지
+    entry = lookup("proj", "grp", "tid", stage_number=2)
+    assert entry is not None and entry.stage == 2 and entry.status == "active"
+    assert entry.branch == "feat-tid-s2"
+
+
+def test_provision_stage_worktree_reuses_existing_registry_entry(tmp_path):
+    repo = tmp_path / "repo"
+    base_sha = _init_repo(repo)
+    from okstra_ctl.worktree import provision_stage_worktree
+
+    first = provision_stage_worktree(
+        project_root=repo, project_id="proj",
+        task_group_segment="grp", task_id_segment="tid",
+        work_category="feature",
+        stage_number=2, base_commit=base_sha,
+    )
+    second = provision_stage_worktree(
+        project_root=repo, project_id="proj",
+        task_group_segment="grp", task_id_segment="tid",
+        work_category="feature",
+        stage_number=2, base_commit=base_sha,
+    )
+    assert second.status == "reused"
+    assert second.path == first.path
+    assert second.branch == first.branch
+
+
+def test_provision_stage_worktree_rolls_back_on_registry_conflict(tmp_path):
+    """registry stage-key 충돌 시 worktree 디렉터리/브랜치도 정리되어야 한다."""
+    repo = tmp_path / "repo"
+    base_sha = _init_repo(repo)
+    from okstra_ctl.worktree import provision_stage_worktree
+    from okstra_ctl.worktree_registry import reserve
+
+    # 미리 stage-2 branch 이름을 다른 task-key 에 등록 (branch 충돌 유도)
+    reserve(project_id="proj", task_group="grp", task_id="other",
+            worktree_path="/wt/other", branch="feat-tid-s2", base_ref=base_sha)
+
+    with pytest.raises(RuntimeError, match="branch .* is already registered"):
+        provision_stage_worktree(
+            project_root=repo, project_id="proj",
+            task_group_segment="grp", task_id_segment="tid",
+            work_category="feature",
+            stage_number=2, base_commit=base_sha,
+        )
+    # worktree 디렉터리·branch 가 롤백됐는지
+    expected_wt = Path(tmp_path / ".okstra-isolated" / "worktrees" / "proj" / "grp" / "tid" / "stage-2")
+    # OKSTRA_HOME 은 conftest 가 isolated 경로로 set, 정확한 경로는 시스템에 따라 다르므로
+    # 핵심 단언은 "git 브랜치가 만들어졌다 사라졌다" 여부
+    res = subprocess.run(
+        ["git", "-C", str(repo), "rev-parse", "--verify", "--quiet", "feat-tid-s2"],
+        capture_output=True, text=True,
+    )
+    assert res.returncode != 0, "rollback 후 브랜치가 남아있으면 안 됨"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_stage_provision.py -v`
+Expected: FAIL — `cannot import name 'provision_stage_worktree'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# worktree.py — provision_task_worktree 정의 바로 아래에 추가
+def provision_stage_worktree(
+    *,
+    project_root: Path,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    stage_number: int,
+    base_commit: str,
+) -> WorktreeProvision:
+    """Materialise an isolated worktree for one implementation stage.
+
+    Unlike `provision_task_worktree` (one worktree per task-key shared
+    across phases), this provisions a per-stage worktree branched from
+    `base_commit` at `<task-key>/stage-<N>/` on branch `<prefix>-<task>-s<N>`.
+    The stage-key (`<task-key>#stage-<N>`) is reserved atomically through
+    `worktree_registry`; re-entry of the same stage-key returns the
+    existing entry. Branch / on-disk conflicts roll back the worktree
+    before re-raising so a retry is not blocked.
+    """
+    if not base_commit:
+        raise RuntimeError("provision_stage_worktree requires a base_commit")
+
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    worktree_path = compute_worktree_path(
+        project_id=safe_project, task_group_segment=safe_group,
+        task_id_segment=safe_task, stage_number=stage_number,
+    )
+    branch = compute_branch_name(
+        work_category=work_category, task_id_segment=safe_task,
+        stage_number=stage_number,
+    )
+
+    existing = worktree_registry.lookup(
+        safe_project, safe_group, safe_task, stage_number=stage_number)
+    if existing is not None and existing.status == "active":
+        return WorktreeProvision(
+            status="reused", path=existing.worktree_path,
+            branch=existing.branch, base_ref=existing.base_ref,
+            note=(
+                f"stage {stage_number} worktree reused at "
+                f"{existing.worktree_path} on branch {existing.branch} "
+                f"(base {existing.base_ref[:12]})"
+            ),
+        )
+
+    if worktree_path.exists():
+        raise RuntimeError(
+            f"stage worktree path already exists but is not in the registry: "
+            f"{worktree_path}. Remove it before retrying."
+        )
+    if _branch_exists(project_root, branch):
+        raise RuntimeError(
+            f"stage worktree branch already exists: {branch}. "
+            "Delete it (`git branch -D <branch>`) before retrying."
+        )
+
+    main_root = main_worktree_path(project_root)
+    resolved_sha = _resolve_commit_sha(main_root, base_commit)
+    if not resolved_sha:
+        raise RuntimeError(
+            f"could not resolve base_commit `{base_commit}` in main worktree "
+            f"({main_root}); ensure the commit exists locally"
+        )
+
+    worktree_path.parent.mkdir(parents=True, exist_ok=True)
+    res = _git(
+        main_root,
+        "worktree", "add", "-b", branch, str(worktree_path), resolved_sha,
+    )
+    if res.returncode != 0:
+        raise RuntimeError(
+            f"`git worktree add` failed (exit={res.returncode}): "
+            f"{(res.stderr or res.stdout).strip()}"
+        )
+
+    _link_sync_dirs(main_root, worktree_path)
+    _link_sync_files(main_root, worktree_path)
+    _copy_snapshot_files(main_root, worktree_path)
+
+    try:
+        worktree_registry.reserve(
+            project_id=safe_project,
+            task_group=safe_group,
+            task_id=safe_task,
+            worktree_path=str(worktree_path),
+            branch=branch,
+            base_ref=resolved_sha,
+            phase="implementation",
+            stage_number=stage_number,
+        )
+    except RuntimeError:
+        _git(main_root, "worktree", "remove", "--force", str(worktree_path))
+        _git(main_root, "branch", "-D", branch)
+        raise
+
+    _seed_worktree_settings_symlink(worktree_path)
+
+    return WorktreeProvision(
+        status="created", path=str(worktree_path),
+        branch=branch, base_ref=resolved_sha,
+        note=(
+            f"stage {stage_number} worktree created at {worktree_path} "
+            f"on branch {branch} (base {resolved_sha[:12]})"
+        ),
+    )
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_stage_provision.py -v`
+Expected: PASS (3개).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/worktree.py tests/test_okstra_worktree_stage_provision.py
+git commit -m "feat(worktree): provision per-stage isolated worktree"
+```
+
+---
+
+### Task 3: `_reserve_implementation_stages` — P1/P2 + Task 1/2 통합
+
+이 task가 가장 무겁다. 한 함수 안에서 (a) anchor base commit 고정, (b) occupied 검출, (c) ready 해소, (d) stage worktree 발급, (e) ctx EXECUTOR_WORKTREE_* 덮어쓰기, (f) consumers append 까지 묶는다. step을 잘게 쪼개 각 step 의 실패 신호를 분명히 한다.
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py:890` (`_reserve_implementation_stages`)
+- Test: `tests/test_okstra_run_reserve_implementation_stages.py` (신규)
+
+- [ ] **Step 1: Write the integration test**
+
+```python
+# tests/test_okstra_run_reserve_implementation_stages.py (신규)
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+import pytest
+
+
+def _init_repo(repo: Path) -> str:
+    subprocess.run(["git", "init", "-q", str(repo)], check=True)
+    subprocess.run(["git", "-C", str(repo), "config", "user.email", "t@e"], check=True)
+    subprocess.run(["git", "-C", str(repo), "config", "user.name", "t"], check=True)
+    (repo / "README").write_text("seed\n")
+    subprocess.run(["git", "-C", str(repo), "add", "."], check=True)
+    subprocess.run(["git", "-C", str(repo), "commit", "-q", "-m", "init"], check=True)
+    return subprocess.run(
+        ["git", "-C", str(repo), "rev-parse", "HEAD"],
+        capture_output=True, text=True, check=True,
+    ).stdout.strip()
+
+
+def _stage(n, deps, steps=2):
+    return {"stage_number": n, "depends_on": deps, "step_count": steps,
+            "title": f"S{n}", "exit_contract_summary": ""}
+
+
+class _Inp:
+    """_reserve_implementation_stages 가 읽는 PrepareInputs 필드만 흉내."""
+    def __init__(self, *, project_root, approved_plan_path, stage,
+                 project_id="proj", task_group="grp", task_id="tid",
+                 work_category="feature"):
+        self.project_root = project_root
+        self.approved_plan_path = approved_plan_path
+        self.stage = stage
+        self.project_id = project_id
+        self.task_group = task_group
+        self.task_id = task_id
+        self.work_category = work_category
+
+
+def _consumers_dir(tmp: Path) -> Path:
+    """consumers.jsonl 이 사는 plan_run_root 모양. read_consumers 가 그 경로의
+    consumers.jsonl 을 찾는다."""
+    d = tmp / "planning" / "reports"
+    d.mkdir(parents=True)
+    plan = d / "final-report.md"
+    plan.write_text("dummy\n")
+    return plan
+
+
+def test_first_stage_run_fixes_anchor_and_provisions_stage_worktree(tmp_path, monkeypatch):
+    repo = tmp_path / "repo"
+    base_sha = _init_repo(repo)
+    plan_path = _consumers_dir(tmp_path)
+
+    from okstra_ctl.run import _reserve_implementation_stages
+    from okstra_ctl.worktree_registry import (
+        reserve as registry_reserve, get_implementation_base, lookup,
+    )
+    # task-key 엔트리 사전 등록 (provision_task_worktree 가 일반 phase 에서 만들었다고 가정)
+    registry_reserve(
+        project_id="proj", task_group="grp", task_id="tid",
+        worktree_path=str(repo), branch="feat-tid", base_ref=base_sha,
+    )
+
+    ctx = {
+        "TASK_KEY": "proj/grp/tid",
+        "TASK_GROUP_SEGMENT": "grp", "TASK_ID_SEGMENT": "tid",
+        "EXECUTOR_WORKTREE_PATH": str(repo),
+        "EXECUTOR_WORKTREE_BRANCH": "feat-tid",
+        "EXECUTOR_WORKTREE_BASE_REF": base_sha,
+    }
+    inp = _Inp(project_root=repo, approved_plan_path=str(plan_path), stage="auto")
+    stages = [_stage(1, [])]
+
+    _reserve_implementation_stages(inp, ctx, stages)
+
+    # anchor 가 고정됐고
+    assert get_implementation_base("proj", "grp", "tid") == base_sha
+    # stage worktree 가 발급되어 ctx 가 덮어쓰여졌고
+    assert ctx["EXECUTOR_WORKTREE_PATH"].endswith("/stage-1")
+    assert ctx["EXECUTOR_WORKTREE_BRANCH"] == "feat-tid-s1"
+    # registry 에 stage-key 가 active
+    entry = lookup("proj", "grp", "tid", stage_number=1)
+    assert entry is not None and entry.status == "active"
+
+
+def test_concurrent_second_run_skips_reserved_stage(tmp_path):
+    """첫 run 이 stage 1 을 reserve 한 뒤, 두번째 run 이 auto 로 와도 stage 1 은
+    잡지 않고 ready 면 다음 stage 를 잡는다 (P2 occupied 통합 검증)."""
+    repo = tmp_path / "repo"
+    base_sha = _init_repo(repo)
+    plan_path = _consumers_dir(tmp_path)
+
+    from okstra_ctl.run import _reserve_implementation_stages
+    from okstra_ctl.worktree_registry import reserve as registry_reserve, lookup
+    registry_reserve(
+        project_id="proj", task_group="grp", task_id="tid",
+        worktree_path=str(repo), branch="feat-tid", base_ref=base_sha,
+    )
+
+    # 첫 run: stage 1 (독립) 예약
+    ctx1 = {
+        "TASK_KEY": "proj/grp/tid",
+        "TASK_GROUP_SEGMENT": "grp", "TASK_ID_SEGMENT": "tid",
+        "EXECUTOR_WORKTREE_PATH": str(repo),
+        "EXECUTOR_WORKTREE_BRANCH": "feat-tid",
+        "EXECUTOR_WORKTREE_BASE_REF": base_sha,
+    }
+    stages = [_stage(1, []), _stage(2, [])]
+    _reserve_implementation_stages(
+        _Inp(project_root=repo, approved_plan_path=str(plan_path), stage="auto"),
+        ctx1, stages,
+    )
+    assert lookup("proj", "grp", "tid", stage_number=1) is not None
+
+    # 두번째 run: auto — stage 1 reserved, stage 2 ready (독립) → stage 2 잡아야 함
+    ctx2 = {
+        "TASK_KEY": "proj/grp/tid",
+        "TASK_GROUP_SEGMENT": "grp", "TASK_ID_SEGMENT": "tid",
+        "EXECUTOR_WORKTREE_PATH": str(repo),
+        "EXECUTOR_WORKTREE_BRANCH": "feat-tid",
+        "EXECUTOR_WORKTREE_BASE_REF": base_sha,
+    }
+    _reserve_implementation_stages(
+        _Inp(project_root=repo, approved_plan_path=str(plan_path), stage="auto"),
+        ctx2, stages,
+    )
+    assert ctx2["EXECUTOR_WORKTREE_BRANCH"] == "feat-tid-s2"
+    assert lookup("proj", "grp", "tid", stage_number=2) is not None
+
+
+def test_multi_dependency_stage_prepare_rejected(tmp_path):
+    repo = tmp_path / "repo"
+    base_sha = _init_repo(repo)
+    plan_path = _consumers_dir(tmp_path)
+
+    from okstra_ctl.run import _reserve_implementation_stages, PrepareError
+    from okstra_ctl.worktree_registry import reserve as registry_reserve
+    registry_reserve(
+        project_id="proj", task_group="grp", task_id="tid",
+        worktree_path=str(repo), branch="feat-tid", base_ref=base_sha,
+    )
+
+    # consumers 에 stage 2, 3 done 으로 미리 기록해 ready 가 stage 4 다중 의존이 되게
+    from okstra_ctl.consumers import append_consumer
+    plan_run_root = Path(plan_path).resolve().parents[1]
+    append_consumer(plan_run_root, impl_task_key="proj/grp/tid",
+                    stage=2, status="done", head_commit="c2")
+    append_consumer(plan_run_root, impl_task_key="proj/grp/tid",
+                    stage=3, status="done", head_commit="c3")
+
+    ctx = {
+        "TASK_KEY": "proj/grp/tid",
+        "TASK_GROUP_SEGMENT": "grp", "TASK_ID_SEGMENT": "tid",
+        "EXECUTOR_WORKTREE_PATH": str(repo),
+        "EXECUTOR_WORKTREE_BRANCH": "feat-tid",
+        "EXECUTOR_WORKTREE_BASE_REF": base_sha,
+    }
+    stages = [_stage(2, []), _stage(3, []), _stage(4, [2, 3])]
+
+    with pytest.raises(PrepareError, match="multi-dependency stage"):
+        _reserve_implementation_stages(
+            _Inp(project_root=repo, approved_plan_path=str(plan_path), stage="auto"),
+            ctx, stages,
+        )
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_run_reserve_implementation_stages.py -v`
+Expected: FAIL — 세 테스트 모두 다른 이유로 실패해야 한다 (anchor 고정 안 됨 / ctx 덮어쓰기 안 됨 / 다중 의존 거부 안 됨).
+
+- [ ] **Step 3: Replace `_reserve_implementation_stages` body**
+
+> **수정 (2026-06-06):** 초기 plan 은 batch 의 모든 stage 를 같은 branch 로 reserve 하려 했으나, P1 registry 의 branch-uniqueness 불변식과 충돌한다(같은 branch 가 두 stage-key 에 등록될 수 없음). spec §2.3 에 명시된 "한 run = 한 stage" 원칙에 맞춰, `_resolve_effective_stages` 가 반환한 batch 의 **첫 번째 stage 만** 실행한다. batch 의 나머지는 자동으로 다음 run 의 ready 가 된다. cost-aware-design 의 batch 는 격리 모델에서 의미를 잃는다.
+
+[run.py:890](../../../scripts/okstra_ctl/run.py) 의 함수 전체를 아래로 치환:
+
+```python
+def _reserve_implementation_stages(inp: PrepareInputs, ctx: dict, ctx_stage_map: list) -> None:
+    """implementation run 의 첫 ready stage 를 결정하고 stage 격리 worktree 를
+    발급해 ctx 의 EXECUTOR_WORKTREE_* 를 덮어쓴다. anchor base commit 을 1회
+    고정하고 그 stage 를 consumers.jsonl 에 started 로 append.
+
+    spec §2.3: 한 run = 한 stage. `_resolve_effective_stages` 는 backward
+    compat 로 batch 리스트를 반환하지만 첫 번째만 실행한다 — stage 마다 격리
+    worktree·branch 가 필요해 batch 가 의미를 잃기 때문(cost-aware-design 의
+    run-batch 와의 의도된 트레이드오프)."""
+    from .consumers import read_consumers, append_consumer
+    from . import worktree as _worktree
+    from . import worktree_registry as _reg
+    import datetime as _dt
+
+    ctx["parsed_stage_map"] = ctx_stage_map
+    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
+    consumed = read_consumers(plan_run_root)
+    done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
+    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
+    reserved_stages = _reg.list_active_stage_numbers(
+        inp.project_id, inp.task_group, inp.task_id,
+    )
+
+    batch = _resolve_effective_stages(
+        ctx_stage_map, done_stages, inp.stage,
+        started_stages=started_stages, reserved_stages=reserved_stages,
+    )
+    # stage 격리: 한 run = 한 stage. 첫 ready stage 만 실행.
+    selected = batch[0]
+    ctx["effective_stages"] = [selected]
+    csv = str(selected)
+    ctx["EFFECTIVE_STAGES"] = csv
+    ctx["STAGE_BATCH_DIRECTIVE"] = (
+        f"- **Stage for this implementation run:** `{csv}`. "
+        "Execute exactly this Stage Map stage — this is the authoritative scope. "
+        "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
+        "and reserved this stage."
+    )
+    inp.stage = csv
+    print(f"selected stages: {csv}", file=sys.stdout)
+
+    # spec §2.1 degradation: 주변 흐름이 non-git / nested-worktree 로 skipped 면
+    # stage 격리도 동일하게 degrade — consumers 만 기록 (기존 평면 동작 보존).
+    wt_status = ctx.get("EXECUTOR_WORKTREE_STATUS", "")
+    if wt_status.startswith("skipped"):
+        head_proc = _subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=inp.project_root, capture_output=True, text=True,
+        )
+        head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
+        now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+        append_consumer(
+            plan_run_root,
+            impl_task_key=ctx["TASK_KEY"],
+            stage=selected,
+            status="started",
+            started_at=now,
+            head_commit=head_sha,
+        )
+        return
+
+    # anchor base commit 1회 고정 (task-key worktree HEAD 기준)
+    head_proc = _subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=inp.project_root, capture_output=True, text=True,
+    )
+    head_sha = head_proc.stdout.strip() if head_proc.returncode == 0 else ""
+    if head_sha:
+        _reg.set_implementation_base(
+            inp.project_id, inp.task_group, inp.task_id, head_sha,
+        )
+    anchor = _reg.get_implementation_base(
+        inp.project_id, inp.task_group, inp.task_id,
+    ) or ""
+
+    # stage 격리 worktree 발급 — 의존 종류별 base 결정
+    selected_stage = next(
+        s for s in ctx_stage_map if s["stage_number"] == selected
+    )
+    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
+    stage_base = _resolve_stage_base_commit(
+        selected_stage, consumer_done_rows, anchor_base_commit=anchor,
+    )
+    try:
+        provision = _worktree.provision_stage_worktree(
+            project_root=Path(inp.project_root),
+            project_id=inp.project_id,
+            task_group_segment=ctx["TASK_GROUP_SEGMENT"],
+            task_id_segment=ctx["TASK_ID_SEGMENT"],
+            work_category=inp.work_category,
+            stage_number=selected,
+            base_commit=stage_base,
+        )
+    except RuntimeError as exc:
+        raise PrepareError(f"stage worktree provisioning failed: {exc}") from exc
+
+    ctx["EXECUTOR_WORKTREE_PATH"] = provision.path
+    ctx["EXECUTOR_WORKTREE_BRANCH"] = provision.branch
+    ctx["EXECUTOR_WORKTREE_BASE_REF"] = provision.base_ref
+    ctx["EXECUTOR_WORKTREE_STATUS"] = provision.status
+    ctx["EXECUTOR_WORKTREE_NOTE"] = provision.note
+
+    # consumers append — stage worktree base 를 head_commit 으로
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    append_consumer(
+        plan_run_root,
+        impl_task_key=ctx["TASK_KEY"],
+        stage=selected,
+        status="started",
+        started_at=now,
+        head_commit=provision.base_ref,
+    )
+```
+
+- [ ] **Step 4: Run target tests**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_run_reserve_implementation_stages.py -v`
+Expected: PASS (3개).
+
+- [ ] **Step 5: Regression — multi-stage / consumers / stage 관련 기존 테스트**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/ -k "multi_stage or consumers or stage or reserve" -v`
+Expected: 모두 PASS. 만약 e2e 가 `EXECUTOR_WORKTREE_*` 의 task-key 경로를 단언하는 게 있다면 그 단언은 **스토리상 stage-N 경로로 바뀌는 것이 정상**이지만, 임의 수정은 안 된다 — 깨지면 BLOCKED 보고. ([spec §2.1](../specs/2026-06-06-stage-worktree-isolation-design.md) 그대로의 의미 변경)
+
+- [ ] **Step 6: Full regression**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/ -q`
+Expected: PASS. 회귀 발견 시 BLOCKED.
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/run.py tests/test_okstra_run_reserve_implementation_stages.py
+git commit -m "feat(run): provision stage-isolated worktree in _reserve_implementation_stages"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage (P3 범위):**
+- §2.1 implementation 에서만 stage worktree → Task 3 `_reserve_implementation_stages` 만 stage 발급 ✓
+- §2.2 base 결정 (독립/단일 의존/다중 의존) → Task 1 `_resolve_stage_base_commit` ✓
+- §2.3 점유 SSOT = registry → Task 3 가 P2 의 `list_active_stage_numbers` 를 occupied 로 전달 ✓
+- §3.1 stage 경로/브랜치 → P1 `compute_*` 를 Task 2 `provision_stage_worktree` 가 사용 ✓
+- §3.2 anchor base commit 고정(멱등) → Task 3 가 P1 `set_implementation_base` 호출 ✓
+- §3.3 ready 식 → P2 가 강제, Task 3 가 인자 전달 ✓
+- §9 #1 다중 의존 first-cut 미지원 → Task 1 + Task 3 의 e2e 가 거부 검증 ✓
+- 프로파일 문구·CLI `--stage` 패스스루(B2)·release-handoff → **P4 범위**
+
+**Placeholder scan:** 없음. 모든 step 에 실제 코드/테스트.
+
+**Type consistency:** `stage_number: int`, `base_commit: str`, `consumer_done_rows: list[dict]` 모두 Task 1↔2↔3 일관. `provision_stage_worktree`/`provision_task_worktree` 둘 다 `WorktreeProvision` 반환.
+
+**위험 플래그(구현자 주의):**
+- Task 3 의 e2e 테스트는 `_Inp` 보조 클래스로 `PrepareInputs` 의 실제 구조에 의존한다. `_reserve_implementation_stages` 가 읽는 attribute(`project_root`, `project_id`, `task_group`, `task_id`, `work_category`, `approved_plan_path`, `stage`) 만 흉내내면 충분하다 — 추가 필드가 필요해지면 BLOCKED 보고.
+- `provision_stage_worktree` 가 `_link_sync_dirs`/`_link_sync_files`/`_copy_snapshot_files` 를 호출하지만 sync dir 미존재면 no-op 이라 무해. snapshot 파일이 정의된 프로젝트는 별도지만 stage 격리 시 동일하게 작동해야 한다 (기존 패턴 답습).
+
+## 검증 (P3 완료 기준)
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+python3 -m pytest tests/test_okstra_run_stage_base.py tests/test_okstra_worktree_stage_provision.py tests/test_okstra_run_reserve_implementation_stages.py -v
+python3 -m pytest tests/ -q
+```