okstra 0.51.0 → 0.53.0

package/docs/superpowers/plans/2026-06-06-stage-parallel-and-pending-fixes.md

@@ -0,0 +1,93 @@
+# stage 병렬 안전화 + 잔여 수정 작업 백로그
+
+> **성격:** 이 문서는 단일 기능 구현 계획이 아니라, `fontradar-v2-api:dev-9184` stage 병렬 실행 사고를 계기로 도출된 okstra 본체 수정 후보들의 **작업 목록 + 우선순위 + 착수 순서**다. 각 항목은 착수 시점에 개별 `*-design.md`(spec) / `*.md`(plan) 한 쌍으로 분화한다.
+
+**배경:** 사용자가 같은 task(`dev-9184`)의 stage2/stage3를 동시에 두 `implementation` run으로 띄웠고, 두 run이 **같은 task-key worktree·브랜치를 공유**해 커밋이 한 브랜치에 인터리브됐다. 코드 자체는 plan의 파일-서로소 설계대로 갈라져 있어 사후 cherry-pick으로 stage별 브랜치 분리에는 성공했으나, 이 사고는 아래 구조적 결함들을 드러냈다.
+
+**핵심 결정 (이 백로그의 전제):**
+- **C1 = (b)** — ADR(`.okstra/decisions/`)을 **git에 커밋하지 않는다.** okstra의 institutional memory는 로컬 `.okstra/` 안에만 둔다. 사용자의 `.okstra` gitignore 정책을 존중한다. (trade-off: ADR이 git/CI/타 머신에서 공유되지 않는다 — 의도된 선택.)
+
+---
+
+## 우선순위 / 착수 순서
+
+| 순위 | 항목 | 그룹 | 규모 | 착수 형태 |
+|---|---|---|---|---|
+| 1 | **A1** stage별 worktree 격리 | 병렬 안전 | 큼 | **spec 먼저** (이번에 착수) |
+| 2 | **A2** started-exclusion 구현 | 병렬 안전 | 중간 | A1 spec에 통합 |
+| 3 | **C1** ADR git 커밋 중단 | gitignore 존중 | 작음~중간 | 단독 plan |
+| 4 | **B1** okstra-run SKILL stage_pick 문서 | UX 일관성 | 작음 | 단독(즉시) |
+| 5 | **B2** `okstra.sh` `--stage` 패스스루 | UX 일관성 | 중간 | B1/A1과 묶음 |
+
+> 사용자 지시에 따라 **A1 spec부터** 착수한다. A2는 A1과 동일한 stage 예약·점유 경로를 건드리므로 A1 spec에 함께 설계한다.
+
+---
+
+## 그룹 A — stage 병렬을 안전하게
+
+### A1. stage별 worktree 격리 (핵심, 설계 변경)
+
+- **증상:** worktree가 **task-key 단위 1개**로 발급되어([worktree.py](../../../scripts/okstra_ctl/worktree.py)), 같은 task의 stage2/stage3 병렬 run이 같은 worktree·브랜치를 공유한다. 두 executor가 동일 디렉토리에서 파일을 편집하고 같은 브랜치에 커밋하면 충돌·덮어쓰기가 발생한다. dev-9184 사고의 근본 원인.
+- **현재 설계 위치:**
+  - worktree 발급/registry 예약: [worktree.py](../../../scripts/okstra_ctl/worktree.py)
+  - stage 예약(점유): `_reserve_implementation_stages` ([run.py:890](../../../scripts/okstra_ctl/run.py)), `_resolve_effective_stages` ([run.py:233](../../../scripts/okstra_ctl/run.py))
+  - executor의 stage batch 실행: [_implementation-executor.md:30](../../../prompts/profiles/_implementation-executor.md)
+- **방향(사용자 제안):** "의존 stage부터 worktree를 새로 나눈다."
+  - `depends-on (none)` stage끼리는 **공통 base**에서 각자 worktree를 떠 진짜 병렬.
+  - `depends-on`이 있는 stage는 **선행 stage의 done commit을 base**로 worktree를 분기 → carry-in(파일·커밋)이 성립.
+  - registry 예약 키를 현재 `task-id` 단위에서 `task-id/stage-N`(또는 ready-set batch) 단위로 확장. flock 직렬성은 유지.
+- **결정해야 할 설계 포인트(spec에서 다룸):**
+  1. worktree 격리 단위 = stage 단위인가, run-batch 단위인가? (A2의 batch 개념과 정합)
+  2. 병렬 stage의 PR/브랜치 네이밍 (현재 `task-<id>` 단일 → `task-<id>-stage-<N>`?)
+  3. 모든 stage done 이후 브랜치 합류(머지) 절차 — release-handoff와의 접점.
+  4. 기존 단일-worktree 흐름과의 관계(pre-1.0이므로 호환 shim 없음 — 단일 흐름을 대체할지).
+- **규모:** 큼. **이번에 spec(`docs/superpowers/specs/`)부터 작성.**
+
+### A2. started-exclusion 구현
+
+- **증상:** `auto` stage 선택 로직이 `consumers.jsonl`의 `done`만 보고 `started`를 무시한다([run.py:264](../../../scripts/okstra_ctl/run.py)). 따라서 stage2가 `started`(미완)인 상태에서 다른 run이 또 `auto`로 돌면 같은 ready-set을 중복 점유한다. dev-9184에서 stage2·stage3가 둘 다 `started`로 찍힌 직접 원인.
+- **기존 기록:** known gap으로 문서화돼 있음 — [stage-run-batching.md:13](2026-06-04-stage-run-batching.md), `tests/test_e2e_multi_stage_q1_q9.py::test_q7`가 현 동작을 박제.
+- **방향:** ready 집합 계산 시 `started`(미완) stage도 제외 + worktree registry의 stage-key 예약과 연동(A1과 동일 경로).
+- **규모:** 중간. **A1 spec에 통합 설계.**
+
+---
+
+## 그룹 B — stage 선택 UX 일관성
+
+### B1. okstra-run SKILL.md stage_pick 문서 누락
+
+- **증상:** implementation sub-flow 설명이 *"approved-plan path + executor pick"*만 적고 **stage_pick 단계를 누락**한다([SKILL.md:125](../../../skills/okstra-run/SKILL.md)). 실제 wizard에는 존재한다([wizard.py:1994](../../../scripts/okstra_ctl/wizard.py)). 문서만 보면 "stage 선택이 없다"고 오해하게 된다.
+- **수정 위치:** [skills/okstra-run/SKILL.md:125](../../../skills/okstra-run/SKILL.md) — sub-flow 목록에 stage_pick 한 줄 추가(approved-plan 직후, executor 직전).
+- **규모:** 작음(문서). **즉시 처리 가능.**
+
+### B2. `okstra.sh` / `cli.sh`에 `--stage` 플래그 부재
+
+- **증상:** `--stage`가 `run.py` argparse에만 정의돼 있고([run.py:1363](../../../scripts/okstra_ctl/run.py)), CLI 래퍼 [`okstra.sh`](../../../scripts/okstra.sh)·[`cli.sh`](../../../scripts/lib/okstra/cli.sh)는 파싱·전달하지 않는다. 결과적으로 CLI 래퍼로는 stage를 지정할 수 없고 인터랙티브 wizard 또는 `python -m okstra_ctl.run` 직접 호출로만 가능하다(단일 reference point 위반에 가까움).
+- **수정 위치:** [`scripts/okstra.sh`](../../../scripts/okstra.sh) PY_ARGS 빌더, [`scripts/lib/okstra/cli.sh`](../../../scripts/lib/okstra/cli.sh) 옵션 파서, (필요 시) `interactive.sh`.
+- **규모:** 중간. **A1(병렬 stage UX 정비) 또는 B1과 묶어 처리.**
+
+---
+
+## 그룹 C — ADR ↔ gitignore 충돌
+
+### C1. ADR을 git에 커밋하지 않도록 변경 — 결정: (b)
+
+- **증상:** okstra는 ADR을 **git에 커밋하길 의도**한다 — [implementation-planning.md:91](../../../prompts/profiles/implementation-planning.md) *"so the `implementation` run commits the file inside okstra's subtree"*. 그러나 사용자가 `.okstra` 전체를 gitignore하면, executor가 `git add -f`로 gitignore를 우회해 ADR만 추적 상태가 된다(매 run 반복). dev-9184에서 `0001-...md`가 git 추적된 원인.
+- **결정 (b):** ADR 파일은 `.okstra/decisions/<NNNN>-<slug>.md`에 **생성하되 git에 커밋하지 않는다.** institutional memory는 로컬 `.okstra/`에만 존재한다.
+- **수정 위치:**
+  - [implementation-planning.md:91](../../../prompts/profiles/implementation-planning.md) — "commits the file" 문구를 "creates the file (NOT git-committed; `.okstra` is gitignored local memory)"로 수정. stepwise step 문구도 "Create … (do NOT `git add`/commit)"로.
+  - [_implementation-executor.md:54](../../../prompts/profiles/_implementation-executor.md) — local git ops 절에 ".okstra/ 경로는 절대 `git add -f` 하지 않는다" 가드 1줄 추가.
+  - [_common-contract.md:76](../../../prompts/profiles/_common-contract.md) — "decision files land only at .okstra/decisions" 유지(위치는 맞음), "not tracked by git" 명시 추가.
+- **trade-off(수용):** ADR이 git/CI/타 머신에서 공유되지 않음. 필요해지면 사용자가 프로젝트 `.gitignore`에 `!.okstra/decisions/` 예외를 직접 두는 별도 경로로 전환 가능(현 결정의 비범위).
+- **규모:** 작음~중간. **단독 plan.**
+
+---
+
+## seed 규칙 준수
+
+모든 수정은 사용자 메모리 `feedback_okstra_fixes_target_end_users`에 따라 **seed/template/프로파일 파일**에 가한다 — `runtime/`(빌드 산출물)·개인 `.claude/`가 아니다. 각 항목 착수 시 `declaration vs enforcement`(okstra `CLAUDE.md` rule 3)를 점검한다: 프로파일의 MUST/금지 문구마다 validator·런타임 가드 등 실제 강제 지점을 함께 명시한다.
+
+## 다음 단계
+
+1. **A1 spec 착수** — `docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md`(가제)로 위 A1 설계 포인트 4개를 결정. A2를 같은 spec에 통합.
+2. 이후 C1 → B1 → B2 순으로 분화.

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

@@ -0,0 +1,447 @@
+# Stage Worktree 격리 P1 — registry/compute 빌딩블록 구현 계획
+
+> **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:** stage worktree 격리의 하위 빌딩블록 — worktree registry의 stage-key 예약, `implementation_base_commit` 1회 고정, `compute_worktree_path`/`compute_branch_name`의 stage 분기 — 를 순수 단위 테스트로 완결한다. provision/base 계산 조립은 P2.
+
+**Architecture:** 기존 `worktree_registry.py`의 `task_key`/`reserve`/`lookup`을 optional `stage_number`로 확장해 `<task-key>#stage-<N>` 키를 같은 flock·branches 충돌 검사 경로로 예약한다. `WorktreeEntry`에 `stage`·`implementation_base_commit` 필드를 더해 `_load`된 row가 `WorktreeEntry(**row)`로 안전하게 복원되게 한다. `compute_*`는 `stage_number=None`이면 기존 동작을 그대로 유지(다른 phase 호환).
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/worktree_registry.py`, `worktree.py`), pytest (`tests/`, conftest가 `OKSTRA_HOME`을 tmp로 격리).
+
+설계 문서: [docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md](../specs/2026-06-06-stage-worktree-isolation-design.md) §2.3, §3.1, §3.2
+
+---
+
+## File Structure
+
+- Modify: `scripts/okstra_ctl/worktree_registry.py`
+  - `WorktreeEntry` dataclass — `stage: Optional[int] = None`, `implementation_base_commit: str = ""` 추가 ([worktree_registry.py:57](../../../scripts/okstra_ctl/worktree_registry.py))
+  - `task_key()` — optional `stage_number` ([worktree_registry.py:46](../../../scripts/okstra_ctl/worktree_registry.py))
+  - `reserve()` / `lookup()` — optional `stage_number` ([worktree_registry.py:130](../../../scripts/okstra_ctl/worktree_registry.py), [:115](../../../scripts/okstra_ctl/worktree_registry.py))
+  - `set_implementation_base()` / `get_implementation_base()` — 신규 (멱등 고정/조회)
+- Modify: `scripts/okstra_ctl/worktree.py`
+  - `compute_worktree_path()` — optional `stage_number` ([worktree.py:489](../../../scripts/okstra_ctl/worktree.py))
+  - `compute_branch_name()` — optional `stage_number` ([worktree.py:511](../../../scripts/okstra_ctl/worktree.py))
+- Test: `tests/test_okstra_worktree_registry.py`, `tests/test_okstra_worktree.py` (기존 파일에 추가)
+
+각 task는 하나의 빌딩블록을 완결한다. provision/run.py 연결은 본 plan 범위 밖(P2).
+
+---
+
+### Task 1: registry `WorktreeEntry`·`task_key` stage 확장
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree_registry.py:57` (`WorktreeEntry`), `:46` (`task_key`)
+- Test: `tests/test_okstra_worktree_registry.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_okstra_worktree_registry.py 끝에 추가
+from okstra_ctl.worktree_registry import WorktreeEntry  # 상단 import 에 합쳐도 됨
+
+
+def test_task_key_with_stage_appends_stage_suffix():
+    from okstra_ctl.worktree_registry import task_key
+    assert task_key("proj", "grp", "tid") == "proj/grp/tid"
+    assert task_key("proj", "grp", "tid", stage_number=2) == "proj/grp/tid#stage-2"
+
+
+def test_worktree_entry_defaults_stage_none_and_empty_base_commit():
+    e = WorktreeEntry(
+        task_key="proj/grp/tid", project_id="proj", task_group="grp",
+        task_id="tid", worktree_path="/wt", branch="feat-tid",
+        base_ref="main", created_at="2026-06-06T00:00:00",
+    )
+    assert e.stage is None
+    assert e.implementation_base_commit == ""
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_registry.py::test_task_key_with_stage_appends_stage_suffix tests/test_okstra_worktree_registry.py::test_worktree_entry_defaults_stage_none_and_empty_base_commit -v`
+Expected: FAIL — `task_key() got an unexpected keyword argument 'stage_number'` / `WorktreeEntry` has no `stage`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# worktree_registry.py — task_key (기존 시그니처 교체)
+def task_key(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+) -> str:
+    """Canonical task-key. With stage_number, returns the stage-scoped
+    key `<proj>/<group>/<task>#stage-<N>` used to reserve a per-stage
+    worktree independently of the task-key entry."""
+    base = f"{project_id}/{task_group}/{task_id}"
+    if stage_number is not None:
+        return f"{base}#stage-{stage_number}"
+    return base
+```
+
+```python
+# worktree_registry.py — WorktreeEntry 에 두 필드 추가 (status 아래)
+@dataclass
+class WorktreeEntry:
+    task_key: str
+    project_id: str
+    task_group: str
+    task_id: str
+    worktree_path: str
+    branch: str
+    base_ref: str
+    created_at: str
+    last_phase: str = ""
+    status: str = "active"  # "active" | "released"
+    stage: Optional[int] = None
+    implementation_base_commit: str = ""
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_registry.py -v`
+Expected: PASS (신규 2개 + 기존 전부).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/worktree_registry.py tests/test_okstra_worktree_registry.py
+git commit -m "feat(worktree-registry): add stage-scoped task_key and entry fields"
+```
+
+---
+
+### Task 2: registry `reserve`/`lookup` stage-key 예약
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree_registry.py:130` (`reserve`), `:115` (`lookup`)
+- Test: `tests/test_okstra_worktree_registry.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_reserve_and_lookup_stage_key_independent_from_task_key():
+    from okstra_ctl.worktree_registry import reserve, lookup
+    # task-key 엔트리
+    reserve(project_id="p", task_group="g", task_id="t",
+            worktree_path="/wt/t", branch="feat-t", base_ref="main")
+    # stage-key 엔트리 (독립)
+    reserve(project_id="p", task_group="g", task_id="t", stage_number=2,
+            worktree_path="/wt/t/stage-2", branch="feat-t-s2", base_ref="abc123")
+
+    base = lookup("p", "g", "t")
+    s2 = lookup("p", "g", "t", stage_number=2)
+    assert base.worktree_path == "/wt/t" and base.stage is None
+    assert s2.worktree_path == "/wt/t/stage-2" and s2.stage == 2
+
+
+def test_reserve_same_stage_twice_raises():
+    from okstra_ctl.worktree_registry import reserve
+    reserve(project_id="p", task_group="g", task_id="t", stage_number=2,
+            worktree_path="/wt/t/stage-2", branch="feat-t-s2", base_ref="abc")
+    with pytest.raises(RuntimeError, match="already has a worktree registered"):
+        reserve(project_id="p", task_group="g", task_id="t", stage_number=2,
+                worktree_path="/wt/t/stage-2b", branch="feat-t-s2b", base_ref="def")
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_registry.py::test_reserve_and_lookup_stage_key_independent_from_task_key tests/test_okstra_worktree_registry.py::test_reserve_same_stage_twice_raises -v`
+Expected: FAIL — `reserve()`/`lookup()` got unexpected keyword `stage_number`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# worktree_registry.py — lookup (시그니처 + key 생성 + stage row)
+def lookup(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+) -> Optional[WorktreeEntry]:
+    key = task_key(project_id, task_group, task_id, stage_number)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return None
+        return WorktreeEntry(task_key=key, **row)
+```
+
+```python
+# worktree_registry.py — reserve (stage_number 추가; key 생성 + row 에 stage 기록)
+def reserve(
+    *,
+    project_id: str,
+    task_group: str,
+    task_id: str,
+    worktree_path: str,
+    branch: str,
+    base_ref: str,
+    phase: str = "",
+    stage_number: Optional[int] = None,
+) -> WorktreeEntry:
+    key = task_key(project_id, task_group, task_id, stage_number)
+    now = time.strftime("%Y-%m-%dT%H:%M:%S%z") or time.strftime("%Y-%m-%dT%H:%M:%S")
+    with _registry_lock():
+        data = _load()
+        if key in data["tasks"]:
+            existing = data["tasks"][key]
+            raise RuntimeError(
+                f"task-key already has a worktree registered: {key} → "
+                f"{existing['worktree_path']} (branch {existing['branch']}). "
+                "Use `lookup` to reuse it, or release it before reserving anew."
+            )
+        owner = data["branches"].get(branch)
+        if owner and owner != key:
+            raise RuntimeError(
+                f"branch {branch!r} is already registered to a different "
+                f"task-key: {owner}. Choose a different work-category or "
+                "release the conflicting task first."
+            )
+        row = {
+            "project_id": project_id,
+            "task_group": task_group,
+            "task_id": task_id,
+            "worktree_path": worktree_path,
+            "branch": branch,
+            "base_ref": base_ref,
+            "created_at": now,
+            "last_phase": phase,
+            "status": "active",
+            "stage": stage_number,
+        }
+        data["tasks"][key] = row
+        data["branches"][branch] = key
+        _save(data)
+        return WorktreeEntry(task_key=key, **row)
+```
+
+> 주의: `row`에 `stage` 키를 항상 넣으므로 `WorktreeEntry(task_key=key, **row)`가 `stage`를 받는다. 기존(stage 없는) registry 파일의 row는 `stage` 키가 없어 `WorktreeEntry`의 default `None`이 적용된다 — Task 1에서 default를 추가했기에 안전하다.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_registry.py -v`
+Expected: PASS (신규 + 기존 전부; 기존 `reserve`/`lookup` 호출은 `stage_number` 기본 None 으로 동일 동작).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/worktree_registry.py tests/test_okstra_worktree_registry.py
+git commit -m "feat(worktree-registry): reserve/lookup stage-scoped worktree entries"
+```
+
+---
+
+### Task 3: registry `implementation_base_commit` 멱등 고정/조회
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree_registry.py` (신규 함수 2개, `release` 위에 배치)
+- Test: `tests/test_okstra_worktree_registry.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_set_implementation_base_is_idempotent():
+    from okstra_ctl.worktree_registry import reserve, set_implementation_base, get_implementation_base
+    reserve(project_id="p", task_group="g", task_id="t",
+            worktree_path="/wt/t", branch="feat-t", base_ref="main")
+    first = set_implementation_base("p", "g", "t", "commit-AAA")
+    second = set_implementation_base("p", "g", "t", "commit-BBB")  # 무시됨
+    assert first == "commit-AAA"
+    assert second == "commit-AAA"          # 이미 고정된 값 반환 (멱등)
+    assert get_implementation_base("p", "g", "t") == "commit-AAA"
+
+
+def test_get_implementation_base_none_when_unset():
+    from okstra_ctl.worktree_registry import reserve, get_implementation_base
+    reserve(project_id="p", task_group="g", task_id="t",
+            worktree_path="/wt/t", branch="feat-t", base_ref="main")
+    assert get_implementation_base("p", "g", "t") is None
+
+
+def test_set_implementation_base_missing_task_key_raises():
+    from okstra_ctl.worktree_registry import set_implementation_base
+    with pytest.raises(RuntimeError, match="no task-key entry"):
+        set_implementation_base("p", "g", "missing", "commit-AAA")
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_registry.py -k implementation_base -v`
+Expected: FAIL — `cannot import name 'set_implementation_base'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# worktree_registry.py — release() 정의 바로 위에 추가
+def set_implementation_base(
+    project_id: str, task_group: str, task_id: str, commit: str,
+) -> str:
+    """Fix the shared base commit for this task's implementation stages,
+    once. Idempotent: if already set, the existing value is returned and
+    `commit` is ignored (so two concurrent first-stage runs converge).
+    Raises RuntimeError when the task-key entry does not exist."""
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if row is None:
+            raise RuntimeError(
+                f"no task-key entry to anchor implementation base: {key}"
+            )
+        already = row.get("implementation_base_commit")
+        if already:
+            return already
+        row["implementation_base_commit"] = commit
+        _save(data)
+        return commit
+
+
+def get_implementation_base(
+    project_id: str, task_group: str, task_id: str,
+) -> Optional[str]:
+    """Return the fixed implementation base commit, or None when unset /
+    task-key missing."""
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if row is None:
+            return None
+        return row.get("implementation_base_commit") or None
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree_registry.py -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/worktree_registry.py tests/test_okstra_worktree_registry.py
+git commit -m "feat(worktree-registry): idempotent implementation_base_commit anchor"
+```
+
+---
+
+### Task 4: `compute_worktree_path` / `compute_branch_name` stage 분기
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree.py:489` (`compute_worktree_path`), `:511` (`compute_branch_name`)
+- Test: `tests/test_okstra_worktree.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_okstra_worktree.py 끝에 추가
+def test_compute_worktree_path_appends_stage_segment(monkeypatch, tmp_path):
+    monkeypatch.setenv("OKSTRA_HOME", str(tmp_path))
+    from okstra_ctl.worktree import compute_worktree_path
+    base = compute_worktree_path(
+        project_id="proj", task_group_segment="grp", task_id_segment="tid")
+    staged = compute_worktree_path(
+        project_id="proj", task_group_segment="grp", task_id_segment="tid",
+        stage_number=2)
+    assert base.name == "tid"
+    assert staged.parent.name == "tid"
+    assert staged.name == "stage-2"
+
+
+def test_compute_branch_name_appends_stage_suffix():
+    from okstra_ctl.worktree import compute_branch_name
+    base = compute_branch_name(work_category="feature", task_id_segment="tid")
+    staged = compute_branch_name(
+        work_category="feature", task_id_segment="tid", stage_number=3)
+    assert base == "feat-tid"
+    assert staged == "feat-tid-s3"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree.py -k "stage_segment or stage_suffix" -v`
+Expected: FAIL — `compute_worktree_path()`/`compute_branch_name()` got unexpected keyword `stage_number`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# worktree.py — compute_worktree_path (시그니처 + stage segment)
+def compute_worktree_path(
+    *,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    stage_number: Optional[int] = None,
+) -> Path:
+    """Pure path computation. One worktree dir per task-key, or per
+    `<task-key>/stage-<N>` when stage_number is given (implementation
+    stage isolation). Uses `OKSTRA_HOME` when set (test hook), else
+    `~/.okstra`."""
+    okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
+    base = Path(okstra_home) if okstra_home else (Path.home() / ".okstra")
+    path = (
+        base / "worktrees"
+        / _safe_segment(project_id)
+        / _safe_segment(task_group_segment)
+        / _safe_segment(task_id_segment)
+    )
+    if stage_number is not None:
+        path = path / f"stage-{stage_number}"
+    return path
+```
+
+```python
+# worktree.py — compute_branch_name (시그니처 + stage suffix)
+def compute_branch_name(
+    *,
+    work_category: str,
+    task_id_segment: str,
+    stage_number: Optional[int] = None,
+) -> str:
+    """One branch per task-key, or `<prefix>-<task-id>-s<N>` for an
+    implementation stage worktree."""
+    name = f"{_work_category_prefix(work_category)}-{_safe_segment(task_id_segment)}"
+    if stage_number is not None:
+        name = f"{name}-s{stage_number}"
+    return name
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_worktree.py -v`
+Expected: PASS (신규 + 기존; 기존 호출은 `stage_number=None` 으로 동일 경로/브랜치).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/worktree.py tests/test_okstra_worktree.py
+git commit -m "feat(worktree): stage-scoped path and branch computation"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage (P1 범위):**
+- §3.1 worktree 키/브랜치 stage 분기 → Task 4 ✓
+- §3.2 registry stage-key 엔트리 → Task 1·2 ✓
+- §3.2 `implementationBaseCommit` 1회 고정(flock) → Task 3 ✓ (멱등으로 동시 첫 진입 수렴)
+- §2.3 stage-key 중복 예약 거부(런타임 강제) → Task 2 `test_reserve_same_stage_twice_raises` ✓
+- provision/base 계산/run.py 연결/CLI/프로파일 → **P2·P3 범위(본 plan 비포함, 의도된 경계)**
+
+**Placeholder scan:** 없음 — 모든 step에 실제 테스트·구현 코드.
+
+**Type consistency:** `stage_number` 파라미터명·`stage`/`implementation_base_commit` 필드명·`set_implementation_base`/`get_implementation_base` 함수명이 Task 1→4 전반 일관. `WorktreeEntry(**row)`가 Task 2의 `row["stage"]`와 Task 1의 `stage` 필드, Task 3의 `implementation_base_commit` 필드로 안전.
+
+**경계 확인:** P1은 어떤 호출자도 새 함수를 사용하지 않는다(빌딩블록만). 이는 YAGNI 위반이 아니라 **P2가 즉시 소비할 의존**이며, P1 단독으로도 registry/compute 단위 테스트가 green이다.
+
+## 검증 (P1 완료 기준)
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+python3 -m pytest tests/test_okstra_worktree_registry.py tests/test_okstra_worktree.py -v
+# 기대: 신규 + 기존 전부 PASS, 다른 phase 경로/브랜치 회귀 없음
+```