okstra 0.102.1 → 0.102.3

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

@@ -1,289 +0,0 @@
-# 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   # 전체 회귀
-```