okstra 0.102.1 → 0.102.3

package/docs/superpowers/plans/2026-06-09-implementation-run-artifact-stage-isolation.md

@@ -1,320 +0,0 @@
-# implementation run-산출물 stage 격리 — 활성화 Implementation Plan
-
-> **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:** `implementation` run 의 산출물을 `runs/implementation/stage-<N>/` 로 격리해, 같은 task 의 독립 stage 를 동시 실행해도 보고서·state·worker-results 가 섞이지 않게 한다.
-
-**Architecture:** foundation(`paths.py`/`run_context.py` 의 `stage` 파라미터, 이미 커밋 `baafa40`)은 `stage` 인자가 오면 `RUN_DIR=runs/implementation/stage-<N>` 를 만든다(현재 무동작). 본 plan 은 `prepare_task_bundle` 의 **stage 선택을 경로 계산 앞으로 옮겨** 그 stage 를 `compute_and_write_run_context` 에 전달해 활성화한다. 동시성 불변(`select == registry flock 예약` 원자성)을 보존하기 위해, stage 선택+base 결정+stage-worktree 예약(=registry flock)을 **하나의 함수로 묶어 경로 계산 전에 1회** 호출한다. `consumers.jsonl` 은 approved-plan 경로 기준이라 격리 대상이 아니다(공유 유지).
-
-**Tech Stack:** Python (okstra_ctl), pytest(+ 실 git/flock 기반 e2e), okstra build(`npm run build`).
-
-설계 근거: [docs/superpowers/specs/2026-06-09-implementation-run-artifact-stage-isolation-design.md](../specs/2026-06-09-implementation-run-artifact-stage-isolation-design.md)
-
----
-
-## File Structure
-
-- Modify: `scripts/okstra_ctl/run.py` — `_reserve_implementation_stages` 를 (a) 경로-무관 **선택+예약+provision** 부분과 (b) `ctx` 의존 **wiring(EXECUTOR_WORKTREE_* 세팅 + consumers append)** 부분으로 분리. `prepare_task_bundle` 에서 (a)를 `compute_and_write_run_context` 앞으로 이동하고 selected stage 를 전달.
-- Modify: `scripts/okstra_ctl/run_context.py` — (foundation 에서 이미 `stage` param 수용) 변경 없음 예상. 확인만.
-- Test: `tests/test_e2e_impl_stage_artifact_isolation.py` (신규) — 동시 stage-1/stage-2 가 분리된 `stage-<N>/` 산출물 트리 + 분리 `lead-pane.id` + 공유 `consumers.jsonl` 을 갖는지.
-- Test: `tests/test_okstra_ctl_paths.py` (기존 있으면 확장; 없으면 신규) — `compute_run_paths(task_type="implementation", stage=N)` 가 `runs/implementation/stage-N/...` 를 반환, `stage=None`/비-impl 은 불변.
-- Modify(필요 시): `validators/validate-run.py`, `scripts/okstra_ctl/{render.py,report_views.py,context_cost.py,index.py,reconcile.py,backfill.py}` — `runs/implementation` hard-coded 경로가 있으면 stage-aware 로. (대부분 ctx/path-dict 경유라 무변경; Task 5 에서 grep 로 확정.)
-- Modify: `CHANGES.md`, `docs/kr/architecture.md` — 사용자 영향 + 팀 lifecycle 절.
-
-`runtime/` 는 빌드 출력 — source 수정 후 `npm run build`.
-
----
-
-## Task 1: paths 단위 테스트로 foundation 동작 고정
-
-**Files:**
-- Test: `tests/test_okstra_ctl_paths.py`
-
-- [ ] **Step 1: 실패/통과 테스트 작성**
-
-`tests/test_okstra_ctl_paths.py` 에 추가(파일 없으면 신규 생성, 상단에 `from okstra_ctl.paths import compute_run_paths` + `from pathlib import Path`):
-
-```python
-def _common(**over):
-    base = dict(
-        project_root=Path("/tmp/proj"), workspace_root=Path("/tmp/ws"),
-        project_id="p", task_group="g", task_id="t",
-        task_type="implementation", run_seq_override=1,
-    )
-    base.update(over)
-    return base
-
-
-def test_implementation_stage_namespaces_run_dir():
-    ctx = compute_run_paths(stage=3, **_common())
-    assert ctx["RUN_DIR"].endswith("/runs/implementation/stage-3")
-    assert ctx["RUN_REPORTS_DIR"].endswith("/runs/implementation/stage-3/reports")
-    assert ctx["RUN_STATE_DIR"].endswith("/runs/implementation/stage-3/state")
-    assert ctx["RUN_STAGE"] == "3"
-
-
-def test_implementation_without_stage_is_flat():
-    ctx = compute_run_paths(stage=None, **_common())
-    assert ctx["RUN_DIR"].endswith("/runs/implementation")
-    assert ctx["RUN_STAGE"] == ""
-
-
-def test_non_implementation_ignores_stage():
-    ctx = compute_run_paths(stage=3, **_common(task_type="final-verification"))
-    assert ctx["RUN_DIR"].endswith("/runs/final-verification")
-    assert "stage-3" not in ctx["RUN_DIR"]
-```
-
-- [ ] **Step 2: 실행해서 통과 확인** (foundation 이 이미 land 됨)
-
-Run: `python3 -m pytest tests/test_okstra_ctl_paths.py -v`
-Expected: 3개 PASS. 실패하면 foundation(`paths.py` stage 분기) 회귀이므로 먼저 수정.
-
-- [ ] **Step 3: 커밋**
-
-```bash
-git add tests/test_okstra_ctl_paths.py
-git commit -m "test(paths): pin implementation stage-namespaced RUN_DIR"
-```
-
----
-
-## Task 2: `_reserve_implementation_stages` 를 선택/예약 vs wiring 으로 분리
-
-**Files:**
-- Modify: `scripts/okstra_ctl/run.py` (`_reserve_implementation_stages` 1274–1386 영역)
-
-현재 함수는 한 덩어리로 (1) consumers/registry 읽기 → `_resolve_effective_stages` 선택, (2) base anchor + `_resolve_stage_base_commit` + `provision_stage_worktree`(registry 원자 예약), (3) `ctx["EXECUTOR_WORKTREE_*"]` 세팅 + `append_consumer(started)` 를 한다. (1)+(2)는 run-경로와 무관하지만 (3)은 `ctx` 가 필요하다.
-
-- [ ] **Step 1: 선택+예약+provision 을 반환 객체로 추출**
-
-`scripts/okstra_ctl/run.py` 에 신규 헬퍼 추가(`_reserve_implementation_stages` 위). `ctx` 대신 segment 값을 인자로 받아 **경로-무관**하게 만든다. (segment 는 `slugify_task_segment(inp.task_group/task_id)` 로 직접 도출 — `ctx` 불필요.)
-
-```python
-from dataclasses import dataclass
-
-@dataclass
-class StageSelection:
-    stage: int
-    worktree_path: str
-    worktree_branch: str
-    worktree_base_ref: str
-    worktree_status: str
-    worktree_note: str
-    started_head_commit: str  # consumers append 용 (degrade 경로는 HEAD sha)
-
-
-def _select_and_provision_implementation_stage(
-    inp: "PrepareInputs", ctx_stage_map: list,
-    task_group_segment: str, task_id_segment: str, task_key: str,
-    executor_worktree_status: str,
-) -> StageSelection:
-    """run 경로 계산 전에 호출: ready stage 1개 선택 → (degrade 가 아니면)
-    base 결정 + stage worktree 발급(registry flock 으로 stage-key 원자 예약).
-    선택과 예약이 한 호출에 묶여 동시성 불변(spec §2.3)을 보존한다.
-    consumers append 는 호출자가 ctx 확정 후 수행한다(반환값 사용)."""
-    from .consumers import read_consumers
-    from . import worktree as _worktree
-    from . import worktree_registry as _reg
-
-    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,
-    )
-    selected = batch[0]
-
-    # degradation(non-git / nested-worktree): worktree 미발급, consumers 만.
-    if executor_worktree_status.startswith("skipped"):
-        head = _git_out(inp.project_root, "rev-parse", "HEAD")
-        return StageSelection(selected, "", "", "", executor_worktree_status, "", head)
-
-    head_sha = _git_out(inp.project_root, "rev-parse", "HEAD")
-    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 ""
-    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,
-        candidate_base=head_sha, project_root=Path(inp.project_root),
-    )
-    try:
-        prov = _worktree.provision_stage_worktree(
-            project_root=Path(inp.project_root), project_id=inp.project_id,
-            task_group_segment=task_group_segment, task_id_segment=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
-    return StageSelection(
-        selected, prov.path, prov.branch, prov.base_ref, prov.status, prov.note, prov.base_ref,
-    )
-```
-
-- [ ] **Step 2: wiring 헬퍼로 교체** — `_reserve_implementation_stages` 본문을 selection 결과를 ctx 에 반영 + consumers append 로 축소:
-
-```python
-def _apply_implementation_stage(
-    inp: "PrepareInputs", ctx: dict, ctx_stage_map: list, sel: "StageSelection",
-) -> None:
-    """이미 선택·예약된 stage(sel)를 ctx 에 반영하고 consumers 에 started 기록."""
-    from .consumers import append_consumer
-    import datetime as _dt
-    ctx["parsed_stage_map"] = ctx_stage_map
-    ctx["effective_stages"] = [sel.stage]
-    ctx["EFFECTIVE_STAGES"] = str(sel.stage)
-    ctx["STAGE_BATCH_DIRECTIVE"] = (
-        f"- **Stage for this implementation run:** `{sel.stage}`. "
-        "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 = str(sel.stage)
-    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
-        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
-        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
-        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-    append_consumer(
-        plan_run_root, impl_task_key=ctx["TASK_KEY"], stage=sel.stage,
-        status="started", started_at=now, head_commit=sel.started_head_commit,
-    )
-```
-
-- [ ] **Step 3: 정적 검사**
-
-Run: `python3 -c "import ast; ast.parse(open('scripts/okstra_ctl/run.py').read()); print('ok')"`
-Expected: `ok`
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add scripts/okstra_ctl/run.py
-git commit -m "refactor(run): split impl stage select+reserve (path-independent) from ctx wiring"
-```
-
----
-
-## Task 3: `prepare_task_bundle` reorder — stage 를 경로 계산 전에 선택
-
-**Files:**
-- Modify: `scripts/okstra_ctl/run.py` (`prepare_task_bundle` 1651–1810)
-
-- [ ] **Step 1: 현재 흐름 확인** — `compute_and_write_run_context`(1686) 호출 직전에 `ctx_stage_map` 와 `inp.task_type == "implementation"` 가용한지, `EXECUTOR_WORKTREE_STATUS` 의 초기값(task worktree provision 결과)을 어디서 얻는지 read 로 확인. (degrade 신호가 task-worktree provision 에서 오면, stage select 는 그 신호가 필요 → task worktree provision 을 stage select 보다 먼저 두거나, stage select 안에서 자체 degrade 판정.)
-
-- [ ] **Step 2: reorder 적용** — implementation 분기에서:
-  1. `compute_and_write_run_context` **앞에서** `sel = _select_and_provision_implementation_stage(...)` 호출(`executor_worktree_status` 는 task-worktree provision 결과 또는 `provision_task_worktree` 의 사전 판정값 전달).
-  2. `compute_and_write_run_context(..., stage=sel.stage)` 호출 → stage-namespaced ctx.
-  3. ctx 생성 후 `_apply_implementation_stage(inp, ctx, ctx_stage_map, sel)` 로 wiring.
-  4. 기존 `_reserve_implementation_stages(inp, ctx, ctx_stage_map)` 호출(1807) **제거**(위 1~3 이 대체). 비-implementation 경로는 불변.
-
-  > 핵심 불변: registry stage-key 예약은 `provision_stage_worktree`(sel 단계) **1회**만. 재선택/재예약 없음.
-
-- [ ] **Step 3: 전체 단위 테스트**
-
-Run: `python3 -m pytest tests/ -q`
-Expected: 전부 PASS(2 skip 허용). 특히 `tests/test_e2e_multi_stage_q1_q9.py`, `tests/test_okstra_ctl_rerun_*` 회귀 없을 것. 실패 시 reorder 의 ctx_stage_map/worktree-status 전달 누락 점검.
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add scripts/okstra_ctl/run.py
-git commit -m "feat(run): resolve implementation stage before run-path compute (activate stage isolation)"
-```
-
----
-
-## Task 4: 동시 stage 격리 e2e
-
-**Files:**
-- Test: `tests/test_e2e_impl_stage_artifact_isolation.py` (신규)
-
-- [ ] **Step 1: e2e 작성** — 기존 `tests/test_e2e_multi_stage_q1_q9.py` 의 픽스처(임시 git project + approved plan with ≥2 독립 stage)를 재사용/모사. 두 `prepare_task_bundle` 를 **순차 호출**(동시성은 flock 으로 직렬화되므로 순차 2회가 동치)해 각각 다른 ready stage 를 잡게 한 뒤:
-
-```python
-def test_two_runs_isolate_stage_artifacts(tmp_impl_project):
-    out1 = prepare_task_bundle(tmp_impl_project.inputs(stage="auto"))
-    out2 = prepare_task_bundle(tmp_impl_project.inputs(stage="auto"))
-    d1, d2 = Path(out1.ctx["RUN_DIR"]), Path(out2.ctx["RUN_DIR"])
-    # 서로 다른 stage-<N> 트리
-    assert d1 != d2
-    assert d1.name.startswith("stage-") and d2.name.startswith("stage-")
-    # lead-pane.id 가 분리(부모 공유 아님)
-    assert d1.parent == d2.parent == (tmp_impl_project.task_root / "runs" / "implementation")
-    # consumers.jsonl 은 공유(plan-run-root 1개)
-    cons = tmp_impl_project.plan_run_root / "consumers.jsonl"
-    rows = [json.loads(l) for l in cons.read_text().splitlines() if l.strip()]
-    stages = sorted(r["stage"] for r in rows if r["status"] == "started")
-    assert stages == [out1.ctx["RUN_STAGE"] and int(out1.ctx["RUN_STAGE"]),
-                      int(out2.ctx["RUN_STAGE"])] or len(set(stages)) == 2
-```
-
-(픽스처 정확한 형태는 기존 e2e 의 헬퍼에 맞춰 작성 — 실행 시 `tests/test_e2e_multi_stage_q1_q9.py` 의 setup 함수를 import/모방.)
-
-- [ ] **Step 2: 실행**
-
-Run: `python3 -m pytest tests/test_e2e_impl_stage_artifact_isolation.py -v`
-Expected: PASS. tmux/flock 불가 환경이면 skip 마커. 실패 시 두 run 이 같은 `RUN_DIR` 를 잡는지(=stage select 가 reorder 에서 실제 적용됐는지) 확인.
-
-- [ ] **Step 3: 커밋**
-
-```bash
-git add tests/test_e2e_impl_stage_artifact_isolation.py
-git commit -m "test(e2e): concurrent implementation stages isolate run artifacts"
-```
-
----
-
-## Task 5: reader/validator sweep + 문서 + 빌드
-
-**Files:**
-- Modify(조건부): `validators/validate-run.py`, `scripts/okstra_ctl/{render.py,report_views.py,context_cost.py,index.py,reconcile.py,backfill.py,workflow.py}`
-- Modify: `CHANGES.md`, `docs/kr/architecture.md`
-
-- [ ] **Step 1: hard-coded 경로 grep**
-
-Run: `grep -rn "runs/implementation\|/runs/\" *+\|task_type_segment *== *.implementation" scripts/okstra_ctl/ validators/`
-점검: `runs/implementation` 를 **stage 없이 직접** 조립/스캔하는 곳을 찾는다. ctx/path-dict(`RUN_DIR`, `RUN_REPORTS_DIR` 등) 경유면 자동 흡수되어 무변경. 직접 조립이면 stage-aware 로 수정(예: timeline/index 가 `runs/<type>/reports/*` 글롭이면 `runs/<type>/**/reports/*` 로).
-
-- [ ] **Step 2: 발견 건 수정 + 회귀 테스트** — 수정한 모듈별로 해당 테스트 재실행. 없으면 Step 1 결과를 `없음(모두 ctx 경유)` 으로 기록.
-
-- [ ] **Step 3: 문서 + 빌드**
-
-`CHANGES.md` 최상단:
-```
-## 2026-06-09 — implementation 산출물 stage 격리
-- 변경: implementation run 산출물이 `runs/implementation/stage-<N>/` 로 stage 별 격리. stage 선택을 경로 계산 전에 수행하고 registry flock 으로 1회 예약.
-- 사용자 영향: 같은 task 의 여러 stage 를 동시 실행해도 보고서·state·worker-results 가 섞이지 않는다. (무호환: 이전 `runs/implementation/` 루트 산출물은 자동 인식 안 됨 — 재실행 권장.)
-```
-
-`docs/kr/architecture.md` 의 stage worktree 절에 "run-산출물도 `runs/implementation/stage-<N>/` 로 격리; consumers.jsonl·registry 는 공유" 1문장 추가.
-
-Run: `cd <repo> && npm run build && python3 -m pytest tests/ -q && bash validators/validate-workflow.sh`
-Expected: 빌드 24/24, 테스트 PASS, validator exit 0.
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add -A
-git commit -m "docs(changes,architecture): implementation run-artifact stage isolation; reader sweep"
-```
-
----
-
-## Self-Review (작성자 체크)
-
-- **Spec coverage**: D1(stage-namespace RUN_DIR)=Task1+foundation, D2(seq in stage dir)=foundation(자동), D3(consumers 공유)=Task2/3 가 plan_run_root 유지 + Task4 e2e 가드, D4(lead-pane.id 격리)=Task4 e2e(부모 분리 확인), D5(degrade fallback)=Task2 `executor_worktree_status.startswith("skipped")` 분기. 전 D 매핑됨.
-- **동시성 불변**: registry stage-key 예약은 `provision_stage_worktree` 1회만 — Task2 추출 + Task3 가 기존 `_reserve_implementation_stages` 호출 제거로 이중예약 차단.
-- **Placeholder scan**: TBD/TODO 없음. Task4 픽스처는 기존 e2e 헬퍼 재사용 명시(코드 형태 제시).
-- **식별자 일관성**: `StageSelection`, `_select_and_provision_implementation_stage`, `_apply_implementation_stage`, `stage` param 이 Task2/3/4 에서 동일.
-- **알려진 한계**: 무호환(이전 루트 산출물), consumers/registry 공유는 spec 에 명시.