okstra 0.51.0 → 0.53.0

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

@@ -0,0 +1,289 @@
+# Stage Worktree 격리 P2 — started-exclusion 순수 빌딩블록 구현 계획
+
+> **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:** A2(started-exclusion)의 순수 로직 — registry의 active stage 번호 조회 헬퍼와 `_resolve_effective_stages`의 `started`/`reserved` 제외 — 를 단위 테스트로 완결한다. worktree 발급·base 계산·`_reserve_implementation_stages` 연결은 P3.
+
+**Architecture:** [run.py:264 `_resolve_effective_stages`](../../../scripts/okstra_ctl/run.py)는 현재 ready 판정에서 `done`만 본다. 여기에 `started_stages`/`reserved_stages`(둘 다 default 빈 set) 파라미터를 더해, ready 집합과 `--stage N` 단일 요청 모두에서 이미 점유된 stage를 제외한다. 점유 출처는 둘 — `consumers.jsonl`의 `started`(관찰)와 registry의 active stage-key 예약(SSOT). registry 조회는 P1의 stage-key 엔트리를 읽는 `list_active_stage_numbers` 헬퍼로 추가한다. 두 함수 모두 순수/조회라 단위 테스트로 끝난다.
+
+**Tech Stack:** Python 3 (`scripts/okstra_ctl/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.3, §3.3
+
+---
+
+## File Structure
+
+- Modify: `scripts/okstra_ctl/worktree_registry.py`
+  - `list_active_stage_numbers()` — 신규 (P1의 stage-key 엔트리에서 active stage 번호 집합 조회)
+- Modify: `scripts/okstra_ctl/run.py`
+  - `_resolve_effective_stages()` — `started_stages`/`reserved_stages` 파라미터 추가 ([run.py:233](../../../scripts/okstra_ctl/run.py))
+- Test: `tests/test_okstra_worktree_registry.py`, `tests/test_okstra_run_stage_resolution.py` (신규 또는 기존 stage 테스트 파일)
+
+P3(별도 plan)이 이 둘을 `_reserve_implementation_stages`에서 소비하고 worktree 발급·base 계산을 연결한다. P2는 그 의존만 만든다.
+
+---
+
+### Task 1: registry `list_active_stage_numbers` 조회 헬퍼
+
+**Files:**
+- Modify: `scripts/okstra_ctl/worktree_registry.py` (신규 함수, `release` 위)
+- Test: `tests/test_okstra_worktree_registry.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_list_active_stage_numbers_returns_reserved_stages():
+    from okstra_ctl.worktree_registry import reserve, release, list_active_stage_numbers
+    # task-key 엔트리는 stage 가 아니므로 제외되어야 한다
+    reserve(project_id="p", task_group="g", task_id="t",
+            worktree_path="/wt/t", branch="feat-t", base_ref="main")
+    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="b")
+    reserve(project_id="p", task_group="g", task_id="t", stage_number=3,
+            worktree_path="/wt/t/stage-3", branch="feat-t-s3", base_ref="b")
+    assert list_active_stage_numbers("p", "g", "t") == {2, 3}
+
+
+def test_list_active_stage_numbers_excludes_released_and_other_tasks():
+    from okstra_ctl.worktree_registry import reserve, release, list_active_stage_numbers
+    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="b")
+    # 다른 task 의 stage 는 섞이면 안 된다
+    reserve(project_id="p", task_group="g", task_id="other", stage_number=2,
+            worktree_path="/wt/o/stage-2", branch="feat-other-s2", base_ref="b")
+    assert list_active_stage_numbers("p", "g", "t") == {2}
+
+
+def test_list_active_stage_numbers_empty_when_none():
+    from okstra_ctl.worktree_registry import list_active_stage_numbers
+    assert list_active_stage_numbers("p", "g", "nope") == set()
+```
+
+- [ ] **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 list_active_stage -v`
+Expected: FAIL — `cannot import name 'list_active_stage_numbers'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# worktree_registry.py — release() 정의 바로 위에 추가
+def list_active_stage_numbers(
+    project_id: str, task_group: str, task_id: str,
+) -> set:
+    """Return the set of stage numbers with an active stage-key reservation
+    for this task. Used by the stage resolver to exclude stages a concurrent
+    run already holds (the occupancy SSOT). Excludes the task-key entry
+    (stage is None) and released entries."""
+    prefix = task_key(project_id, task_group, task_id) + "#stage-"
+    with _registry_lock():
+        data = _load()
+        out = set()
+        for key, row in data["tasks"].items():
+            if (key.startswith(prefix)
+                    and row.get("status") == "active"
+                    and row.get("stage") is not None):
+                out.add(row["stage"])
+        return out
+```
+
+- [ ] **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): list active stage reservations for a task"
+```
+
+---
+
+### Task 2: `_resolve_effective_stages` started/reserved 제외 (A2)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py:233` (`_resolve_effective_stages`)
+- Test: `tests/test_okstra_run_stage_resolution.py` (신규 파일)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_okstra_run_stage_resolution.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_effective_stages, PrepareError
+
+# stages 는 _parse_stage_map_into_ctx 가 만드는 dict 모양과 동일:
+#   {"stage_number": int, "depends_on": list[int], "step_count": int}
+def _stage(n, deps, steps=3):
+    return {"stage_number": n, "depends_on": deps, "step_count": steps}
+
+
+def test_auto_raises_when_all_unfinished_stages_occupied():
+    stages = [_stage(1, []), _stage(2, []), _stage(3, [])]
+    # stage 1 done, stage 2 started(다른 run), stage 3 reserved(다른 run)
+    # → 잡을 ready 가 없음. P2 에서는 기존 raise 동작을 유지(호출자 의미 전환은 P3).
+    with pytest.raises(PrepareError, match="no stage is ready"):
+        _resolve_effective_stages(
+            stages, done_stages={1}, requested="auto",
+            started_stages={2}, reserved_stages={3},
+        )
+
+
+def test_auto_picks_only_unoccupied_ready_stage():
+    stages = [_stage(1, []), _stage(2, []), _stage(3, [])]
+    got = _resolve_effective_stages(
+        stages, done_stages=set(), requested="auto",
+        started_stages={1}, reserved_stages=set(),
+    )
+    assert got == [2, 3]  # 1 은 started 라 제외, 2·3 만 batch
+
+
+def test_numeric_stage_rejected_when_started():
+    stages = [_stage(2, [])]
+    with pytest.raises(PrepareError, match="already in progress or reserved"):
+        _resolve_effective_stages(
+            stages, done_stages=set(), requested="2",
+            started_stages={2}, reserved_stages=set(),
+        )
+
+
+def test_numeric_stage_rejected_when_reserved():
+    stages = [_stage(2, [])]
+    with pytest.raises(PrepareError, match="already in progress or reserved"):
+        _resolve_effective_stages(
+            stages, done_stages=set(), requested="2",
+            started_stages=set(), reserved_stages={2},
+        )
+
+
+def test_defaults_preserve_legacy_behavior():
+    # started/reserved 미지정 → 기존 동작 (done 만 고려)
+    stages = [_stage(1, []), _stage(2, [1])]
+    assert _resolve_effective_stages(stages, done_stages={1}, requested="auto") == [2]
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_run_stage_resolution.py -v`
+Expected: FAIL — `_resolve_effective_stages()` got unexpected keyword `started_stages` (그리고 numeric reject 메시지 불일치).
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# run.py — _resolve_effective_stages 교체 (시그니처 + 제외 로직)
+def _resolve_effective_stages(
+    stages: list,
+    done_stages: set,
+    requested: str,
+    budget: int = RUN_STEP_BUDGET,
+    started_stages: set = None,
+    reserved_stages: set = None,
+) -> list:
+    """Return the ordered list of stage numbers this run executes.
+
+    `requested` is "auto" or a decimal string. For "auto" the run batches all
+    ready stages (depends-on all done, itself neither done nor occupied) in
+    stage-number order up to `budget` effective steps. A numeric request is a
+    single forced stage. `started_stages`/`reserved_stages` are stages a
+    concurrent run already holds (consumers.jsonl `started` and the registry
+    stage reservations); they are excluded so two simultaneous runs never pick
+    the same stage. Raises PrepareError on rejection cases."""
+    started_stages = started_stages or set()
+    reserved_stages = reserved_stages or set()
+    occupied = done_stages | started_stages | reserved_stages
+    if requested != "auto":
+        try:
+            n = int(requested)
+        except ValueError:
+            raise PrepareError(
+                f"--stage must be 'auto' or an integer, got {requested!r}"
+            )
+        target = next((s for s in stages if s["stage_number"] == n), None)
+        if target is None:
+            raise PrepareError(
+                f"--stage {n} not in Stage Map "
+                f"(have {[s['stage_number'] for s in stages]})"
+            )
+        if n in done_stages:
+            raise PrepareError(
+                f"--stage {n} already completed (consumers.jsonl status:done exists)"
+            )
+        if n in started_stages or n in reserved_stages:
+            raise PrepareError(
+                f"--stage {n} already in progress or reserved by another run"
+            )
+        return [n]
+
+    ready = [
+        s for s in stages
+        if s["stage_number"] not in occupied
+        and all(d in done_stages for d in s["depends_on"])
+    ]
+    if not ready:
+        raise PrepareError(
+            "no stage is ready: every remaining stage has unsatisfied depends-on"
+        )
+    batch: list = []
+    total = 0
+    for s in ready:
+        sc = s.get("step_count", 0) or 0
+        if batch and total + sc > budget:
+            break
+        batch.append(s["stage_number"])
+        total += sc
+    return batch
+```
+
+> 변경점: 시그니처에 `started_stages`/`reserved_stages`를 더하고, ready 집합 계산과 `--stage N` numeric 경로 양쪽에서 `occupied`(= done ∪ started ∪ reserved)를 제외한다. **`if not ready: raise` 동작은 기존 그대로 유지** — backward compat를 위해 빈-리스트 의미 전환은 호출자(P3)와 함께 한다. P2 단계에서는 occupied로 ready가 비어도 기존과 동일하게 `PrepareError`가 난다(동시 병렬 둘째 run의 "정상 종료" 전환은 P3 호출자 레벨에서 점유 여부를 구분해 처리).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_run_stage_resolution.py -v`
+Expected: PASS (5개).
+
+- [ ] **Step 5: Run the broader suite for regressions**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/ -k "stage or resolve or reserve or multi_stage" -v`
+Expected: PASS — occupied 제외는 순수 추가다. 기존 호출자 `_reserve_implementation_stages`는 `started_stages`/`reserved_stages`를 전달하지 않아 default 빈 set으로 동일 동작하고, `if not ready: raise`도 그대로 유지되므로 `test_q7`/multi-stage e2e 회귀가 없어야 한다. 만약 회귀가 나면 **BLOCKED 보고**(임의로 기존 테스트를 고치지 말 것).
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+git add scripts/okstra_ctl/run.py tests/test_okstra_run_stage_resolution.py
+git commit -m "feat(run): exclude started/reserved stages from resolution (A2)"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage (P2 범위):**
+- §2.3 ready 집합 = depends-on done **+ started 없음 + registry 미예약** → Task 2 ✓ (점유 = done|started|reserved)
+- §2.3 registry 예약이 점유 SSOT → Task 1 `list_active_stage_numbers`가 그 조회면 ✓
+- §3.3 `--stage N` 점유 시 거부 → Task 2 numeric reject ✓
+- worktree 발급·base 계산·`_reserve_implementation_stages` 연결·CLI → **P3 범위(본 plan 비포함)**
+
+**Placeholder scan:** 없음 — 모든 step에 실제 코드.
+
+**Type consistency:** `started_stages`/`reserved_stages`(set), `list_active_stage_numbers`(→ set) 이 Task 1↔2 간 일치. `_resolve_effective_stages` 반환 타입 list 유지.
+
+**backward compat:** P2는 `_resolve_effective_stages`에 occupied 제외를 더하는 **순수 추가**다. `if not ready: raise`는 기존 그대로 유지하므로, `started_stages`/`reserved_stages`를 전달하지 않는 기존 호출자(`_reserve_implementation_stages`)는 default 빈 set으로 동일하게 동작한다. 동시 병렬 둘째 run의 "정상 종료" 의미 전환과 호출자 연결은 P3.
+
+## 검증 (P2 완료 기준)
+
+```bash
+cd /Volumes/Workspaces/workspace/projects/Okstra
+python3 -m pytest tests/test_okstra_worktree_registry.py tests/test_okstra_run_stage_resolution.py -v
+python3 -m pytest tests/ -q   # 전체 회귀
+```