okstra 0.54.0 → 0.56.0

package/bin/okstra

@@ -4,19 +4,36 @@ import { getPackageVersion } from "../src/version.mjs";
 const COMMANDS = new Map([
   ["paths", () => import("../src/paths.mjs").then((m) => m.run)],
   ["install", () => import("../src/install.mjs").then((m) => m.runInstall)],
-  ["ensure-installed", () => import("../src/install.mjs").then((m) => m.runEnsureInstalled)],
-  ["uninstall", () => import("../src/uninstall.mjs").then((m) => m.runUninstall)],
+  [
+    "ensure-installed",
+    () => import("../src/install.mjs").then((m) => m.runEnsureInstalled),
+  ],
+  [
+    "uninstall",
+    () => import("../src/uninstall.mjs").then((m) => m.runUninstall),
+  ],
   ["doctor", () => import("../src/doctor.mjs").then((m) => m.run)],
   ["setup", () => import("../src/setup.mjs").then((m) => m.run)],
-  ["check-project", () => import("../src/check-project.mjs").then((m) => m.run)],
+  [
+    "check-project",
+    () => import("../src/check-project.mjs").then((m) => m.run),
+  ],
   ["config", () => import("../src/config.mjs").then((m) => m.run)],
-  ["migrate", () => import("../src/migrate.mjs").then((m) => m.run)],
   ["task-list", () => import("../src/task-list.mjs").then((m) => m.run)],
   ["task-show", () => import("../src/task-show.mjs").then((m) => m.run)],
   ["context-cost", () => import("../src/context-cost.mjs").then((m) => m.run)],
-  ["worktree-lookup", () => import("../src/worktree-lookup.mjs").then((m) => m.run)],
-  ["plan-validate", () => import("../src/plan-validate.mjs").then((m) => m.run)],
-  ["render-bundle", () => import("../src/render-bundle.mjs").then((m) => m.run)],
+  [
+    "worktree-lookup",
+    () => import("../src/worktree-lookup.mjs").then((m) => m.run),
+  ],
+  [
+    "plan-validate",
+    () => import("../src/plan-validate.mjs").then((m) => m.run),
+  ],
+  [
+    "render-bundle",
+    () => import("../src/render-bundle.mjs").then((m) => m.run),
+  ],
   ["render-views", () => import("../src/render-views.mjs").then((m) => m.run)],
   ["wizard", () => import("../src/wizard.mjs").then((m) => m.run)],
   ["token-usage", () => import("../src/token-usage.mjs").then((m) => m.run)],

package/docs/project-structure-overview.md

@@ -137,7 +137,6 @@ So `runtime/` is not the only npm-published content. It is the install payload c
 | `setup` | `src/setup.mjs` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
 | `check-project` | `src/check-project.mjs` | Verify project registration |
 | `config` | `src/config.mjs` | Read/write project/global settings such as PR template path |
-| `migrate` | `src/migrate.mjs` | Move legacy `.project-docs/okstra/` state into `.okstra/` |
 | `task-list`, `task-show` | `src/task-list.mjs`, `src/task-show.mjs` | Task/run introspection for skills |
 | `context-cost` | `src/context-cost.mjs` | Estimate task bundle file/read context cost |
 | `worktree-lookup` | `src/worktree-lookup.mjs` | Look up a task-key's registered worktree |

package/docs/superpowers/plans/2026-05-25-okstra-project-root-rename.md

@@ -95,7 +95,6 @@
 - [ ] `MigrationPlan` 은 dataclass, JSON 직렬화 가능 (dry-run 출력에 그대로 사용).
 
 ### Task 3.2: 진입점 3개 (단일 코어 호출 보장)
-- [ ] Node CLI: `bin/commands/migrate.mjs` — argparse + Python 모듈 호출.
 - [ ] Bash 진입점: `scripts/lib/okstra-ctl/cmd-migrate.sh` — thin adapter.
 - [ ] `bin/okstra` dispatcher 에 `migrate` 서브커맨드 등록.
 - [ ] `--dry-run` 기본, `--apply` 로 실제 실행, `--quiet` 로 출력 최소화.

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

@@ -0,0 +1,275 @@
+# 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 생성)을 작성한다.

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

@@ -0,0 +1,282 @@
+# Stage Conformance QA — Phase 3 (validate-run 게이트) 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:** `validators/validate-run.py` 가 implementation/final-verification 리포트에 대해 run 의 `qa/` 디렉터리(conformance 매니페스트 + 결과 사이드카)를 읽어 Phase 2 의 `evaluate_conformance` 로 게이트를 적용한다. BLOCKING verdict 는 run 검증 실패로 만든다 — DEV-9184 의 "정적 OK, 미검증 → silent pass" 를 실제 FAIL 로 전환하는 강제 지점.
+
+**Architecture:** Phase 1(매니페스트 검증) + Phase 2(게이트 판정)의 순수 함수를 validate-run 에 wiring 한다. **매니페스트가 없으면 게이트는 inert**(early return) — 따라서 매니페스트를 생성하는 prompt 측(Phase 4)이 없어도 안전하게 단독 출하된다. SSOT: [`docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md`](../specs/2026-06-07-stage-conformance-qa-design.md) §6.
+
+**Tech Stack:** Python 3 (stdlib + pytest). validate-run.py 는 importlib 로 로드되는 standalone 스크립트.
+
+**전제:** Phase 1·2 완료 — `scripts/okstra_ctl/conformance.py` 에 `validate_conformance_manifest`, `evaluate_conformance`, `qa_result_from_dict`, `ConformanceVerdict` 존재.
+
+---
+
+## 결과 사이드카 계약 (이 Phase 에서 확정)
+
+- 매니페스트: `<run_dir>/qa/conformance-manifest.json` (run_dir = `report_path.parent.parent`, 기존 `validate_worker_results_audit` 의 `report_path.parent.parent / "worker-results"` 패턴과 동형).
+- 결과 사이드카(Phase 4 의 verifier 가 작성): `<run_dir>/qa/result-<stageKey>.json` = `{"stageKey","overall","ranAt","requirements"}`. 파일 부재 → 미실행(None) → BLOCKING.
+
+---
+
+## Task 1: conformance 게이트 함수 + 결과 로더
+
+**Files:**
+- Modify: `validators/validate-run.py`
+- Test: `tests/test_validate_run_conformance.py` (신규)
+
+- [ ] **Step 1: 실패 테스트 작성**
+
+```python
+# tests/test_validate_run_conformance.py
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+VALIDATOR_PATH = REPO_ROOT / "validators" / "validate-run.py"
+
+
+def _load_validator():
+    spec = importlib.util.spec_from_file_location("validate_run", VALIDATOR_PATH)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+def _make_run(tmp_path: Path, entries, results):
+    run_dir = tmp_path / "runs" / "implementation"
+    (run_dir / "reports").mkdir(parents=True)
+    qa = run_dir / "qa"
+    qa.mkdir()
+    (qa / "conformance-manifest.json").write_text(json.dumps({"entries": entries}))
+    for key, overall in results.items():
+        (qa / f"result-{key}.json").write_text(
+            json.dumps({"stageKey": key, "overall": overall, "requirements": {}})
+        )
+    report = run_dir / "reports" / "final-report-implementation-001.md"
+    report.write_text("# fixture\n")
+    return report
+
+
+def _entry(key, **over):
+    base = {"stageKey": key, "script": f"qa/{key}.ts", "runCommand": f"run {key}",
+            "requirementIds": ["R-001"], "requires": ["db"],
+            "passContract": "exit 0 = PASS", "exemption": None, "waiver": None}
+    base.update(over)
+    return base
+
+
+def test_no_manifest_is_inert(tmp_path):
+    v = _load_validator()
+    run_dir = tmp_path / "runs" / "implementation"
+    (run_dir / "reports").mkdir(parents=True)
+    report = run_dir / "reports" / "final-report-implementation-001.md"
+    report.write_text("# fixture\n")
+    failures: list[str] = []
+    v._validate_conformance(report, failures)
+    assert failures == []
+
+
+def test_passing_result_no_failure(tmp_path):
+    v = _load_validator()
+    report = _make_run(tmp_path, [_entry("t-stage-1")], {"t-stage-1": "PASS"})
+    failures: list[str] = []
+    v._validate_conformance(report, failures)
+    assert failures == []
+
+
+def test_missing_result_is_blocking(tmp_path):
+    v = _load_validator()
+    report = _make_run(tmp_path, [_entry("t-stage-1")], {})  # no result file
+    failures: list[str] = []
+    v._validate_conformance(report, failures)
+    assert any("BLOCKING" in f and "t-stage-1" in f for f in failures)
+
+
+def test_failing_result_is_blocking(tmp_path):
+    v = _load_validator()
+    report = _make_run(tmp_path, [_entry("t-stage-1")], {"t-stage-1": "FAIL"})
+    failures: list[str] = []
+    v._validate_conformance(report, failures)
+    assert any("BLOCKING" in f for f in failures)
+
+
+def test_exemption_passes(tmp_path):
+    v = _load_validator()
+    entry = _entry("t-stage-1", exemption={"reason": "doc", "declaredAt": "2026-06-07"})
+    report = _make_run(tmp_path, [entry], {})
+    failures: list[str] = []
+    v._validate_conformance(report, failures)
+    assert failures == []
+
+
+def test_waiver_passes_but_records_conditional(tmp_path):
+    v = _load_validator()
+    entry = _entry("t-stage-1", waiver={"acknowledgedBy": "user", "reason": "replica down",
+                                        "at": "2026-06-07", "scope": ["db"]})
+    report = _make_run(tmp_path, [entry], {})
+    failures: list[str] = []
+    v._validate_conformance(report, failures)
+    assert failures == []  # waiver = ok (conditional, not a failure)
+
+
+def test_malformed_manifest_reported(tmp_path):
+    v = _load_validator()
+    report = _make_run(tmp_path, [{"stageKey": ""}], {})  # invalid entry
+    failures: list[str] = []
+    v._validate_conformance(report, failures)
+    assert any("conformance manifest" in f for f in failures)
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_validate_run_conformance.py -q`
+Expected: FAIL — `module 'validate_run' has no attribute '_validate_conformance'`
+
+- [ ] **Step 3: 구현 추가**
+
+`validators/validate-run.py` 상단의 `from okstra_project.dirs import tasks_root as _okstra_tasks_root` (line 33 부근) 다음에 import 추가:
+
+```python
+from okstra_ctl.conformance import (  # noqa: E402
+    evaluate_conformance,
+    qa_result_from_dict,
+    validate_conformance_manifest,
+)
+```
+
+`validate_report` 함수 정의 바로 앞(`def validate_report(` 위)에 두 함수 추가:
+
+```python
+def _load_conformance_results(qa_dir: Path, manifest: dict) -> dict:
+    """매니페스트 각 entry 에 대응하는 `result-<stageKey>.json` 을 로드.
+    파일 부재/파손은 키를 비워 둬 미실행(None→BLOCKING)으로 흐르게 한다."""
+    results: dict = {}
+    for entry in manifest.get("entries", []):
+        key = entry.get("stageKey") if isinstance(entry, dict) else None
+        if not isinstance(key, str) or not key:
+            continue
+        sidecar = qa_dir / f"result-{key}.json"
+        if not sidecar.is_file():
+            continue
+        try:
+            results[key] = qa_result_from_dict(json.loads(sidecar.read_text()))
+        except (OSError, json.JSONDecodeError):
+            results[key] = qa_result_from_dict(None)  # → MISSING → BLOCKING
+    return results
+
+
+def _validate_conformance(report_path: Path, failures: list[str]) -> None:
+    """Tier 3 conformance 게이트(implementation / final-verification).
+
+    `<run_dir>/qa/conformance-manifest.json` 이 없으면 inert(선언된 conformance
+    가 없다는 뜻 — 선언을 강제하는 것은 planning 계약(Phase 4)의 몫). 매니페스트가
+    있으면 결과 사이드카와 함께 evaluate_conformance 로 판정하고 BLOCKING verdict
+    를 run 검증 실패로 승격한다. WAIVED(conditional)/EXEMPT 는 통과시킨다.
+    """
+    qa_dir = report_path.parent.parent / "qa"
+    manifest_path = qa_dir / "conformance-manifest.json"
+    if not manifest_path.is_file():
+        return
+    try:
+        manifest = json.loads(manifest_path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        failures.append(f"conformance manifest unreadable at {manifest_path}: {exc}")
+        return
+    schema_errors = validate_conformance_manifest(manifest)
+    if schema_errors:
+        failures.extend(f"conformance manifest: {e}" for e in schema_errors)
+        return
+    results = _load_conformance_results(qa_dir, manifest)
+    for verdict in evaluate_conformance(manifest, results):
+        if not verdict.ok:
+            failures.append(
+                f"conformance gate BLOCKING for stage {verdict.stage_key}: "
+                f"{verdict.message}. Run the stage's conformance script (or declare "
+                f"an exemption / user waiver) — see "
+                f"docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md."
+            )
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_validate_run_conformance.py -q`
+Expected: PASS (7 passed)
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add validators/validate-run.py tests/test_validate_run_conformance.py
+git commit -m "feat(validators): conformance Tier3 게이트 함수(_validate_conformance)"
+```
+
+## Task 2: 메인 dispatch 에 게이트 wiring
+
+**Files:**
+- Modify: `validators/validate-run.py`
+
+- [ ] **Step 1: dispatch 에 호출 추가**
+
+`validate-run.py` 의 메인 dispatch 에서 `validate_worker_results_audit` 호출 블록 다음, `if task_type == "improvement-discovery":` 앞에 추가:
+
+```python
+    if task_type in ("implementation", "final-verification"):
+        _validate_conformance(report_path, failures)
+```
+
+(찾을 앵커 — 현재 코드:)
+
+```python
+    if task_type:
+        validate_worker_results_audit(report_path, task_type, failures)
+    if task_type == "improvement-discovery":
+```
+
+- [ ] **Step 2: 기존 스위트 회귀 + workflow validator 확인**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: 전부 통과(신규 7 포함, 회귀 없음). validate-workflow 의 final-verification fixture 는 `qa/` 디렉터리가 없으므로 게이트는 inert → 영향 없음.
+
+Run: `bash validators/validate-workflow.sh`
+Expected: 마지막에 PASS (게이트 inert).
+
+- [ ] **Step 3: 코드 확인(수동)**
+
+`grep -n "_validate_conformance" validators/validate-run.py` → 정의 1 + 호출 1 = 2건.
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add validators/validate-run.py
+git commit -m "feat(validators): implementation/final-verification 에 conformance 게이트 연결"
+```
+
+---
+
+## Phase 3 Self-Review 체크
+
+- [ ] 매니페스트 부재 시 inert(early return) 확인 — 기존 run 들이 깨지지 않는가?
+- [ ] BLOCKING(미실행/MISSING/FAIL) → failures 추가, EXEMPT/WAIVED → 통과가 spec §6/§7 과 일치하는가?
+- [ ] run_dir 해석(`report_path.parent.parent`)이 기존 `validate_worker_results_audit` 와 동형인가?
+- [ ] 전체 pytest + workflow validator 통과(회귀 없음)?
+
+---
+
+## Phase 4 로 넘길 항목 + ⚠️ 미해결 설계 갬
+
+본 게이트는 매니페스트/결과가 존재할 때만 작동한다. 그것을 **생성·실행**하는 다음 작업들은 Phase 4 이며, 일부는 **계획 전 설계 확정이 필요**하다(추측 금지):
+
+1. **verifier 실행(prompt)**: `_implementation-verifier.md` 에 Tier 3 추가 — 각 entry 의 `runCommand` 실행 → `parse_qa_result` → `<run_dir>/qa/result-<stageKey>.json` 작성. (env/secret 접근, replica DB, mutation 가드 포함)
+2. **planning 생성(prompt)**: `implementation-planning.md` 가 stage 별 스크립트 + `conformance-manifest.json` + `Conformance exemption:` 라인 산출.
+3. **final-verification(prompt)**: 전 stage 합집합 실행.
+4. **우회 UX**: `--qa-waiver <stageKey>:"<reason>"` CLI(okstra.sh/cli.sh) + wizard picker → `run.py` 가 매니페스트 entry 의 `waiver` 채움.
+5. **env**: `project.json.qaEnv`(replicaDbDsn/appBaseUrl/envFile).
+
+**⚠️ 설계 확정 필요(Phase 4 계획 전 brainstorm 보강 권장):**
+- **매니페스트의 교차-phase 위치**: planning 이 만든 매니페스트/스크립트가 implementation run, 이어서 final-verification run 으로 어떻게 전달되는가? (task-key worktree vs stage worktree vs instruction-set 복사) — stage worktree isolation 과 정합해야 함.
+- **"diff 가 surface 를 건드렸는데 매니페스트 entry 자체가 없음"** (planning 누락) 강제: 본 게이트는 선언된 entry 만 강제한다. 누락 탐지는 planning 계약 + diff-surface 휴리스틱이 필요(spec §7.1 선언형 면제 surface 교차검증과 함께).
+- **env/secret 운영 모델**: replica DB·실행 env 를 누가 어떻게 주입하는가.