okstra 0.102.1 → 0.102.3

package/docs/superpowers/plans/2026-06-06-stage-worktree-isolation-p5-multidep-base.md

@@ -1,387 +0,0 @@
-# Stage Worktree 격리 P5 — 다중 의존 stage 자동 base 감지 구현 계획
-
-> **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:** P3에서 `PrepareError`로 거부하던 다중 의존 stage(`depends-on X,Y…`)를 spec §9 옵션 A로 자동 처리한다 — task-key worktree HEAD를 candidate로 두고, 선행 stage들의 done commit이 모두 candidate의 ancestor면(=사용자가 머지함) candidate를 base로 발급, 아니면 머지 안내 `PrepareError`.
-
-**Architecture:** 새 pure 헬퍼 `_commit_is_ancestor(project_root, ancestor, descendant)`가 `git merge-base --is-ancestor`를 감싼다. `_resolve_stage_base_commit`의 다중 의존 분기를 거부 → ancestor 검증으로 교체하고, 검증에 필요한 `candidate_base`/`project_root`를 새 인자로 받는다. `_reserve_implementation_stages`는 이미 계산한 task-key worktree HEAD(`head_sha`)를 candidate로, `inp.project_root`를 함께 넘긴다.
-
-**Tech Stack:** Python 3 (`scripts/okstra_ctl/run.py`), pytest (real `git init` repos).
-
-설계 문서: [docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md](../specs/2026-06-06-stage-worktree-isolation-design.md) §2.2 / §9 #1
-
----
-
-## File Structure
-
-- Modify: `scripts/okstra_ctl/run.py`
-  - 신규 `_commit_is_ancestor()` (모듈 helper, `_resolve_stage_base_commit` 직전)
-  - `_resolve_stage_base_commit()` — 다중 의존 분기 교체 + 인자 2개 추가
-  - `_reserve_implementation_stages()` — `_resolve_stage_base_commit` 호출에 candidate/project_root 전달
-- Test:
-  - `tests/test_okstra_run_stage_base.py` (기존 — 다중 의존 케이스 교체 + ancestor 케이스 추가)
-  - `tests/test_okstra_run_reserve_implementation_stages.py` (기존 — 다중 의존 거부 테스트를 머지/미머지 두 케이스로)
-
----
-
-### Task 1: `_commit_is_ancestor` 헬퍼 + `_resolve_stage_base_commit` 다중 의존 자동 감지
-
-**Files:**
-- Modify: `scripts/okstra_ctl/run.py`
-- Test: `tests/test_okstra_run_stage_base.py`
-
-- [ ] **Step 1: Replace the multi-dependency tests in `test_okstra_run_stage_base.py`**
-
-기존 `test_multi_dependency_rejected_with_guidance` 함수를 삭제하고, 그 자리에 아래 4개를 넣는다. 파일 상단 import 에 `import subprocess` 와 `from pathlib import Path` 가 이미 있는지 확인하고 없으면 추가.
-
-```python
-def _init_repo_with_commits(repo: Path):
-    """3개 커밋 c0→c1→c2 선형 히스토리를 만들고 (c0, c1, c2) 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)
-    shas = []
-    for i in range(3):
-        (repo / f"f{i}").write_text(f"{i}\n")
-        subprocess.run(["git", "-C", str(repo), "add", "."], check=True)
-        subprocess.run(["git", "-C", str(repo), "commit", "-q", "-m", f"c{i}"], check=True)
-        shas.append(subprocess.run(
-            ["git", "-C", str(repo), "rev-parse", "HEAD"],
-            capture_output=True, text=True, check=True).stdout.strip())
-    return shas  # [c0, c1, c2]
-
-
-def test_multi_dependency_returns_candidate_when_all_predecessors_ancestors(tmp_path):
-    repo = tmp_path / "repo"
-    c0, c1, c2 = _init_repo_with_commits(repo)
-    stage = _stage(4, [2, 3])
-    # 선행 2,3 의 done commit 이 c0,c1 — candidate c2 의 ancestor (선형 히스토리)
-    rows = [
-        {"stage": 2, "status": "done", "head_commit": c0},
-        {"stage": 3, "status": "done", "head_commit": c1},
-    ]
-    got = _resolve_stage_base_commit(
-        stage, consumer_done_rows=rows, anchor_base_commit="unused",
-        candidate_base=c2, project_root=repo,
-    )
-    assert got == c2
-
-
-def test_multi_dependency_rejected_when_predecessor_not_merged(tmp_path):
-    repo = tmp_path / "repo"
-    c0, c1, c2 = _init_repo_with_commits(repo)
-    # 별도 분기 커밋 (candidate 의 ancestor 가 아님)
-    subprocess.run(["git", "-C", str(repo), "checkout", "-q", "-b", "side", c0], check=True)
-    (repo / "side").write_text("x\n")
-    subprocess.run(["git", "-C", str(repo), "add", "."], check=True)
-    subprocess.run(["git", "-C", str(repo), "commit", "-q", "-m", "side"], check=True)
-    side_sha = subprocess.run(
-        ["git", "-C", str(repo), "rev-parse", "HEAD"],
-        capture_output=True, text=True, check=True).stdout.strip()
-    stage = _stage(4, [2, 3])
-    rows = [
-        {"stage": 2, "status": "done", "head_commit": c1},      # ancestor of c2 ✓
-        {"stage": 3, "status": "done", "head_commit": side_sha},  # NOT ancestor of c2 ✗
-    ]
-    with pytest.raises(PrepareError, match="not merged into the task worktree"):
-        _resolve_stage_base_commit(
-            stage, consumer_done_rows=rows, anchor_base_commit="unused",
-            candidate_base=c2, project_root=repo,
-        )
-
-
-def test_multi_dependency_rejected_when_predecessor_not_done(tmp_path):
-    repo = tmp_path / "repo"
-    c0, c1, c2 = _init_repo_with_commits(repo)
-    stage = _stage(4, [2, 3])
-    rows = [{"stage": 2, "status": "done", "head_commit": c0}]  # stage 3 done 없음
-    with pytest.raises(PrepareError, match="predecessor stage 3 has no done"):
-        _resolve_stage_base_commit(
-            stage, consumer_done_rows=rows, anchor_base_commit="unused",
-            candidate_base=c2, project_root=repo,
-        )
-
-
-def test_multi_dependency_rejected_without_candidate(tmp_path):
-    repo = tmp_path / "repo"
-    c0, c1, c2 = _init_repo_with_commits(repo)
-    stage = _stage(4, [2, 3])
-    rows = [
-        {"stage": 2, "status": "done", "head_commit": c0},
-        {"stage": 3, "status": "done", "head_commit": c1},
-    ]
-    with pytest.raises(PrepareError, match="candidate base missing"):
-        _resolve_stage_base_commit(
-            stage, consumer_done_rows=rows, anchor_base_commit="unused",
-            candidate_base="", project_root=repo,
-        )
-```
-
-- [ ] **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: 신규 4개 FAIL — `_resolve_stage_base_commit()` got unexpected keyword `candidate_base` (현재 시그니처에 없음). 기존 독립/단일 의존 테스트는 PASS 유지.
-
-- [ ] **Step 3: Add `_commit_is_ancestor` helper + rewrite multi-dep branch**
-
-`run.py`에서 `_resolve_stage_base_commit` 정의 **바로 위**에 헬퍼 추가:
-
-```python
-def _commit_is_ancestor(project_root, ancestor: str, descendant: str) -> bool:
-    """True iff `ancestor` is an ancestor of `descendant` in project_root's git
-    history (`git merge-base --is-ancestor`, exit 0). Used to detect whether a
-    predecessor stage's done commit has been merged into the task worktree HEAD."""
-    r = _subprocess.run(
-        ["git", "merge-base", "--is-ancestor", ancestor, descendant],
-        cwd=str(project_root), capture_output=True, text=True,
-    )
-    return r.returncode == 0
-```
-
-그리고 `_resolve_stage_base_commit`를 아래로 교체 (시그니처 + 다중 의존 분기):
-
-```python
-def _resolve_stage_base_commit(
-    stage: dict,
-    consumer_done_rows: list,
-    anchor_base_commit: str,
-    candidate_base: str = "",
-    project_root=None,
-) -> 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).
-    - 단일 의존 (`depends-on X`): predecessor X 의 `done.head_commit`.
-    - 다중 의존 (`depends-on X,Y…`): spec §9 옵션 A 자동 감지. candidate_base
-      (= task-key worktree HEAD) 에 모든 선행 done commit 이 ancestor 면
-      candidate 를 반환(사용자가 선행을 머지함). 아니면 PrepareError.
-
-    Raises PrepareError on missing predecessor / anchor / unmerged predecessor."""
-    deps = stage.get("depends_on") or []
-    if len(deps) >= 2:
-        n = stage["stage_number"]
-        # 1) 모든 선행의 done head_commit 수집
-        pred_commits = {}
-        for d in deps:
-            head = next(
-                (r.get("head_commit") for r in consumer_done_rows
-                 if r.get("stage") == d and r.get("status") == "done"
-                 and r.get("head_commit")),
-                None,
-            )
-            if not head:
-                raise PrepareError(
-                    f"predecessor stage {d} has no done row with head_commit "
-                    f"in consumers.jsonl; multi-dependency stage {n} cannot start"
-                )
-            pred_commits[d] = head
-        # 2) candidate (task-key worktree HEAD) 필요
-        if not candidate_base or project_root is None:
-            raise PrepareError(
-                f"candidate base missing for multi-dependency stage {n}; "
-                "task-key worktree HEAD could not be resolved"
-            )
-        # 3) 모든 선행 done 이 candidate 의 ancestor 인지 (=사용자가 머지함)
-        for d, head in pred_commits.items():
-            if not _commit_is_ancestor(project_root, head, candidate_base):
-                raise PrepareError(
-                    f"multi-dependency stage {n}: predecessor stage {d} "
-                    f"({head[:8]}) is not merged into the task worktree "
-                    f"({candidate_base[:8]}). Merge stage branches "
-                    f"(e.g. the `-s{d}` branches) into the task worktree "
-                    "(or into main, then refresh the worktree) and retry."
-                )
-        return candidate_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 (독립/단일 기존 + 다중 의존 신규 4개).
-
-- [ ] **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): auto-detect multi-dependency stage base via ancestor check"
-```
-
----
-
-### Task 2: `_reserve_implementation_stages` — candidate/project_root 전달 + e2e
-
-**Files:**
-- Modify: `scripts/okstra_ctl/run.py` (`_reserve_implementation_stages`의 `_resolve_stage_base_commit` 호출)
-- Test: `tests/test_okstra_run_reserve_implementation_stages.py`
-
-- [ ] **Step 1: Replace the multi-dep e2e test with merged/unmerged cases**
-
-기존 `test_multi_dependency_stage_prepare_rejected` 함수를 삭제하고 아래 2개로 교체. (helper `_init_repo`, `_stage`, `_Inp`, `_consumers_dir` 는 그대로 사용.)
-
-```python
-def test_multi_dependency_starts_when_predecessors_merged(tmp_path):
-    """선행 2,3 의 done commit 이 task worktree HEAD 의 ancestor 면 다중 의존
-    stage 4 가 그 HEAD 를 base 로 발급된다."""
-    repo = tmp_path / "repo"
-    base_sha = _init_repo(repo)  # c0 (현재 HEAD)
-    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
-    from okstra_ctl.consumers import append_consumer
-    registry_reserve(
-        project_id="proj", task_group="grp", task_id="tid",
-        worktree_path=str(repo), branch="feat-tid", base_ref=base_sha,
-    )
-    # 선행 2,3 done — head_commit 을 base_sha(=현재 HEAD) 로 두면 HEAD 의 ancestor(자기 자신).
-    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=base_sha)
-    append_consumer(plan_run_root, impl_task_key="proj/grp/tid",
-                    stage=3, status="done", head_commit=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,
-        "EXECUTOR_WORKTREE_STATUS": "created",
-    }
-    stages = [_stage(2, []), _stage(3, []), _stage(4, [2, 3])]
-    _reserve_implementation_stages(
-        _Inp(project_root=repo, approved_plan_path=str(plan_path), stage="4"),
-        ctx, stages,
-    )
-    assert ctx["EXECUTOR_WORKTREE_BRANCH"] == "feat-tid-s4"
-    assert lookup("proj", "grp", "tid", stage_number=4) is not None
-
-
-def test_multi_dependency_rejected_when_not_merged(tmp_path):
-    """선행 done commit 이 task worktree HEAD 의 ancestor 가 아니면(미머지)
-    다중 의존 stage 가 PrepareError 로 거부된다."""
-    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
-    from okstra_ctl.consumers import append_consumer
-    registry_reserve(
-        project_id="proj", task_group="grp", task_id="tid",
-        worktree_path=str(repo), branch="feat-tid", base_ref=base_sha,
-    )
-    plan_run_root = Path(plan_path).resolve().parents[1]
-    # 존재하지 않는/분기된 commit sha → HEAD 의 ancestor 아님
-    append_consumer(plan_run_root, impl_task_key="proj/grp/tid",
-                    stage=2, status="done", head_commit=base_sha)
-    append_consumer(plan_run_root, impl_task_key="proj/grp/tid",
-                    stage=3, status="done",
-                    head_commit="0000000000000000000000000000000000000000")
-
-    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,
-        "EXECUTOR_WORKTREE_STATUS": "created",
-    }
-    stages = [_stage(2, []), _stage(3, []), _stage(4, [2, 3])]
-    with pytest.raises(PrepareError, match="not merged into the task worktree"):
-        _reserve_implementation_stages(
-            _Inp(project_root=repo, approved_plan_path=str(plan_path), stage="4"),
-            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: `test_multi_dependency_starts_when_predecessors_merged` FAILS (현재 `_reserve_implementation_stages`가 candidate/project_root 를 전달하지 않아 `_resolve_stage_base_commit`이 `candidate base missing` 으로 거부). `test_multi_dependency_rejected_when_not_merged` 는 이유는 다르지만(역시 candidate missing) 일단 raise 하므로 match 가 어긋나 FAIL 가능.
-
-- [ ] **Step 3: Pass candidate_base + project_root in the call**
-
-`_reserve_implementation_stages` 내부의 `_resolve_stage_base_commit(...)` 호출(현재):
-
-```python
-    stage_base = _resolve_stage_base_commit(
-        selected_stage, consumer_done_rows, anchor_base_commit=anchor,
-    )
-```
-
-를 아래로 교체 (이미 함수 안에서 `head_sha`= task-key worktree HEAD 를 계산해 둠 — 그것을 candidate 로):
-
-```python
-    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),
-    )
-```
-
-> 참고: `head_sha`는 anchor 고정 블록에서 `git rev-parse HEAD`(in `inp.project_root`)로 이미 계산된 변수다. 다중 의존 stage 시점에는 사용자가 선행 stage 들을 worktree 에 머지했다면 이 HEAD 가 선행 done 들을 ancestor 로 가진다. 독립/단일 의존 경로는 candidate 를 쓰지 않으므로 무영향.
-
-- [ ] **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 (기존 + 신규 2개).
-
-- [ ] **Step 5: Full regression**
-
-Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/ -q`
-Expected: PASS. 회귀 시 BLOCKED.
-
-- [ ] **Step 6: 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): wire multi-dependency base auto-detection into stage reservation"
-```
-
----
-
-## Self-Review
-
-**Spec coverage:**
-- §9 #1 자동 감지: candidate=task-key HEAD, 선행 done 모두 ancestor → candidate, 아니면 PrepareError → Task 1 (헬퍼+분기) + Task 2 (wire-up) ✓
-- §2.2 다중 의존 행 갱신 → 구현이 그 의미 ✓
-- 옵션 B(octopus) → 비범위 유지 ✓
-
-**Placeholder scan:** 없음 — 전 step 실제 코드.
-
-**Type consistency:** `_commit_is_ancestor(project_root, ancestor, descendant) -> bool`; `_resolve_stage_base_commit(..., candidate_base="", project_root=None)`; 호출부가 `candidate_base=head_sha, project_root=Path(inp.project_root)`. P3에서 단일 의존/독립이 candidate 를 안 쓰므로 그 경로 무영향.
-
-**위험 플래그(구현자 주의):**
-- Task 2 e2e 는 실제 `git init` repo 의 HEAD(`base_sha`)를 선행 done commit 으로도 쓴다 — commit 은 자기 자신의 ancestor 이므로(`git merge-base --is-ancestor X X` exit 0) "머지됨" 케이스가 성립한다. 미머지 케이스는 all-zero sha 로 ancestor 검증을 실패시킨다(`merge-base --is-ancestor` 가 비존재 sha 에 비0 반환).
-- `_resolve_stage_base_commit` 의 단일 의존/독립 분기는 **변경 금지** — 다중 의존 분기와 시그니처 인자 추가만.
-
-## 검증 (P5 완료 기준)
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-python3 -m pytest tests/test_okstra_run_stage_base.py tests/test_okstra_run_reserve_implementation_stages.py -v
-python3 -m pytest tests/ -q
-```

package/docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase2.md

@@ -1,275 +0,0 @@
-# Stage Conformance QA — Phase 2 (게이트 판정 코어) 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:** stage 별 conformance entry + 실행 결과를 받아 "PASS / WAIVED / EXEMPT / BLOCKING" 을 결정하는 **순수 판정 로직**을 `conformance.py` 에 추가한다(미실행·FAIL·MISSING = BLOCKING, 면제·waiver = 통과). 이게 DEV-9184 의 "silent mock-green" 을 막는 두뇌다.
-
-**Architecture:** Phase 1(매니페스트 검증 + `QA-RESULT` 파서)의 사이드카(부수효과 없는) 확장. wiring(verifier 가 결과 기록, validate-run 이 판정 적용, run.py 진입 검증, planning 이 스크립트 생성)은 **Phase 3** 로 분리한다. 본 Phase 는 외부 파일을 읽지 않는 순수 함수만 추가하므로 완전 TDD 가능하다. SSOT: [`docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md`](../specs/2026-06-07-stage-conformance-qa-design.md) §6(실행·판정), §7(우회).
-
-**Tech Stack:** Python 3 (stdlib + pytest).
-
-**전제:** Phase 1 완료 — `scripts/okstra_ctl/conformance.py` 에 `validate_conformance_manifest`, `parse_qa_result`, `QaResult`, `CAPABILITY_WHITELIST` 존재.
-
----
-
-## 판정 규칙 (spec §6, §7)
-
-단일 stage entry + 그 stage 의 실행 결과(`QaResult | None`)로부터:
-
-| 조건 | status | ok | conditional |
-|---|---|---|---|
-| `exemption` 있음 | EXEMPT | True | False |
-| `waiver` 있음 | WAIVED | True | **True** (conformance 미검증 — 사용자 확인) |
-| 결과 없음(`None`) | BLOCKING | False | False |
-| `overall == "MISSING"` (마커 없음) | BLOCKING | False | False |
-| `overall == "FAIL"` | BLOCKING | False | False |
-| `overall == "PASS"` | PASS | True | False |
-
-판정 우선순위: exemption → waiver → 결과 평가. (Phase 3 가 "면제 선언했지만 diff 가 실제 surface 를 건드림" 교차검증을 추가한다 — 본 Phase 는 선언을 신뢰한다.)
-
----
-
-## Task 1: 게이트 판정 (`decide_conformance_gate`)
-
-**Files:**
-- Modify: `scripts/okstra_ctl/conformance.py`
-- Test: `tests/test_okstra_ctl_conformance.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-```python
-# tests/test_okstra_ctl_conformance.py 의 import 에 추가
-from okstra_ctl.conformance import (  # noqa: E402
-    ConformanceVerdict,
-    QaResult,
-    decide_conformance_gate,
-)
-
-
-def _gate_entry(**over):
-    base = {"stageKey": "t-stage-1", "exemption": None, "waiver": None}
-    base.update(over)
-    return base
-
-
-def test_gate_pass_when_result_pass():
-    v = decide_conformance_gate(_gate_entry(), QaResult(overall="PASS", requirements={}))
-    assert isinstance(v, ConformanceVerdict)
-    assert v.status == "PASS" and v.ok is True and v.conditional is False
-
-
-def test_gate_blocking_when_no_result():
-    v = decide_conformance_gate(_gate_entry(), None)
-    assert v.status == "BLOCKING" and v.ok is False
-    assert "never ran" in v.message
-
-
-def test_gate_blocking_when_marker_missing():
-    v = decide_conformance_gate(_gate_entry(), QaResult(overall="MISSING", requirements={}))
-    assert v.status == "BLOCKING" and v.ok is False
-    assert "QA-RESULT" in v.message
-
-
-def test_gate_blocking_when_fail():
-    v = decide_conformance_gate(_gate_entry(), QaResult(overall="FAIL", requirements={}))
-    assert v.status == "BLOCKING" and v.ok is False
-
-
-def test_gate_exempt_passes_with_reason():
-    entry = _gate_entry(exemption={"reason": "doc-only", "declaredAt": "2026-06-07"})
-    v = decide_conformance_gate(entry, None)
-    assert v.status == "EXEMPT" and v.ok is True and v.conditional is False
-    assert "doc-only" in v.message
-
-
-def test_gate_waiver_is_conditional():
-    entry = _gate_entry(waiver={"acknowledgedBy": "user", "reason": "replica down",
-                                "at": "2026-06-07", "scope": ["db"]})
-    v = decide_conformance_gate(entry, None)
-    assert v.status == "WAIVED" and v.ok is True and v.conditional is True
-    assert "user" in v.message and "replica down" in v.message
-
-
-def test_gate_exemption_takes_priority_over_failing_result():
-    entry = _gate_entry(exemption={"reason": "n/a", "declaredAt": "2026-06-07"})
-    v = decide_conformance_gate(entry, QaResult(overall="FAIL", requirements={}))
-    assert v.status == "EXEMPT" and v.ok is True
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: FAIL — `cannot import name 'ConformanceVerdict'` / `decide_conformance_gate`
-
-- [ ] **Step 3: 구현 추가**
-
-`conformance.py` 의 `parse_qa_result` 정의 다음에 추가:
-
-```python
-@dataclass
-class ConformanceVerdict:
-    stage_key: str
-    status: str        # "PASS" | "BLOCKING" | "WAIVED" | "EXEMPT"
-    ok: bool           # 진행 허용 여부 (PASS/WAIVED/EXEMPT 면 True)
-    conditional: bool  # WAIVED 일 때만 True — conformance 미검증(사용자 확인)
-    message: str
-
-
-def decide_conformance_gate(entry: dict, result: object) -> ConformanceVerdict:
-    """단일 stage entry + 실행 결과(`QaResult | None`)로 게이트 판정.
-
-    우선순위: exemption → waiver → 결과 평가. 미실행/MISSING/FAIL 은 BLOCKING.
-    면제·waiver 의 형태 검증은 `validate_conformance_manifest` 가 이미 보장한다.
-    """
-    key = entry.get("stageKey", "<unknown>")
-    exemption = entry.get("exemption")
-    if exemption:
-        return ConformanceVerdict(
-            key, "EXEMPT", True, False,
-            f"conformance exempted: {exemption.get('reason', '')}",
-        )
-    waiver = entry.get("waiver")
-    if waiver:
-        return ConformanceVerdict(
-            key, "WAIVED", True, True,
-            f"conformance waived by {waiver.get('acknowledgedBy', '?')}: "
-            f"{waiver.get('reason', '')}",
-        )
-    overall = getattr(result, "overall", None) if result is not None else None
-    if overall == "PASS":
-        return ConformanceVerdict(key, "PASS", True, False, "conformance PASS")
-    if overall is None:
-        return ConformanceVerdict(
-            key, "BLOCKING", False, False,
-            "conformance script never ran (no result recorded)",
-        )
-    if overall == "MISSING":
-        return ConformanceVerdict(
-            key, "BLOCKING", False, False,
-            "conformance script ran but emitted no QA-RESULT marker",
-        )
-    return ConformanceVerdict(key, "BLOCKING", False, False, f"conformance {overall}")
-```
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: PASS (24 passed — 기존 17 + 신규 7)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/conformance.py tests/test_okstra_ctl_conformance.py
-git commit -m "feat(okstra_ctl/conformance): stage 게이트 판정(decide_conformance_gate)"
-```
-
-## Task 2: 사이드카 변환 + 매니페스트 일괄 평가
-
-**Files:**
-- Modify: `scripts/okstra_ctl/conformance.py`
-- Test: `tests/test_okstra_ctl_conformance.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-```python
-from okstra_ctl.conformance import (  # noqa: E402  (위 import 에 합쳐도 됨)
-    evaluate_conformance,
-    qa_result_from_dict,
-)
-
-
-def test_qa_result_from_dict_roundtrip():
-    r = qa_result_from_dict({"overall": "PASS", "requirements": {"R-001": {"status": "PASS"}}})
-    assert r.overall == "PASS" and r.requirements["R-001"]["status"] == "PASS"
-
-
-def test_qa_result_from_dict_defaults_to_missing():
-    assert qa_result_from_dict(None).overall == "MISSING"
-    assert qa_result_from_dict({"overall": "bogus"}).overall == "MISSING"
-    assert qa_result_from_dict({}).requirements == {}
-
-
-def test_evaluate_conformance_mixes_verdicts():
-    manifest = {"entries": [
-        {"stageKey": "t-stage-1", "exemption": None, "waiver": None},   # PASS
-        {"stageKey": "t-stage-2", "exemption": None, "waiver": None},   # BLOCKING (no result)
-        {"stageKey": "t-stage-3",
-         "exemption": {"reason": "doc", "declaredAt": "x"}, "waiver": None},  # EXEMPT
-    ]}
-    results = {"t-stage-1": QaResult(overall="PASS", requirements={})}
-    verdicts = evaluate_conformance(manifest, results)
-    by_key = {v.stage_key: v for v in verdicts}
-    assert by_key["t-stage-1"].status == "PASS"
-    assert by_key["t-stage-2"].status == "BLOCKING"
-    assert by_key["t-stage-3"].status == "EXEMPT"
-
-
-def test_evaluate_conformance_empty_manifest():
-    assert evaluate_conformance(None, {}) == []
-    assert evaluate_conformance({"entries": []}, {}) == []
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: FAIL — `cannot import name 'evaluate_conformance'` / `qa_result_from_dict`
-
-- [ ] **Step 3: 구현 추가**
-
-`conformance.py` 의 `decide_conformance_gate` 다음에 추가:
-
-```python
-def qa_result_from_dict(data: object) -> QaResult:
-    """결과 사이드카(JSON dict)를 `QaResult` 로 복원. Phase 3 의 verifier 가 쓴
-    `result-stage-<N>.json` 을 validate-run 이 로드할 때 쓴다. 형태가 깨졌으면
-    overall='MISSING'(=BLOCKING 취급)으로 안전하게 강등한다."""
-    if not isinstance(data, dict):
-        return QaResult(overall="MISSING", requirements={})
-    overall = data.get("overall")
-    if overall not in ("PASS", "FAIL", "MISSING"):
-        overall = "MISSING"
-    reqs = data.get("requirements")
-    return QaResult(overall=overall, requirements=reqs if isinstance(reqs, dict) else {})
-
-
-def evaluate_conformance(manifest: object, results_by_stage: object) -> list[ConformanceVerdict]:
-    """매니페스트 전 entry 에 대해 게이트 판정 목록을 반환.
-
-    `results_by_stage`: stageKey -> `QaResult`. 키가 없으면 미실행(None)으로 본다.
-    매니페스트 구조 검증은 호출 전에 `validate_conformance_manifest` 로 끝낸다는 전제.
-    """
-    entries = manifest.get("entries") if isinstance(manifest, dict) else None
-    if not isinstance(entries, list):
-        return []
-    results = results_by_stage if isinstance(results_by_stage, dict) else {}
-    verdicts: list[ConformanceVerdict] = []
-    for entry in entries:
-        if not isinstance(entry, dict):
-            continue
-        result = results.get(entry.get("stageKey"))
-        verdicts.append(decide_conformance_gate(entry, result))
-    return verdicts
-```
-
-- [ ] **Step 4: 통과 확인 + 전체 회귀**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q` → Expected: PASS (28 passed)
-Run: `python3 -m pytest tests/ -q` → Expected: 전부 통과(회귀 없음)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/conformance.py tests/test_okstra_ctl_conformance.py
-git commit -m "feat(okstra_ctl/conformance): 사이드카 변환 + evaluate_conformance 일괄 평가"
-```
-
----
-
-## Phase 2 Self-Review 체크
-
-- [ ] spec §6 의 미실행/MISSING/FAIL = BLOCKING, PASS = 통과가 모두 커버되는가?
-- [ ] spec §7 의 면제(EXEMPT) / waiver(WAIVED, conditional) 가 커버되는가?
-- [ ] Phase 3 가 의존할 공개 API(`decide_conformance_gate`, `evaluate_conformance`, `qa_result_from_dict`, `ConformanceVerdict`)가 노출되는가?
-- [ ] 순수 함수만 추가했는가(파일 I/O·외부 의존 없음)? — wiring 은 Phase 3.
-
-Phase 2 완료 후 Phase 3 계획(verifier 결과 기록 + validate-run 게이트 적용 + run.py 진입 검증 + planning 생성)을 작성한다.