okstra 0.102.1 → 0.102.3

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

@@ -1,250 +0,0 @@
-# Stage Conformance QA — Phase 4e (env + 우회 UX = 완성) 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:** conformance QA 기능을 완성한다 — (a) `--qa-waiver <stageKey>:"<reason>"` 로 사용자 확인형 우회를 매니페스트 entry 의 `waiver` 에 기록, (b) `project.json.qaEnv.surfacePatterns` 를 diff-surface 교차검증에 반영, (c) `qaEnv`(replicaDbDsn/appBaseUrl/envFile/surfacePatterns) 를 setup 문서/wizard 에 명문화.
-
-**Architecture:** 순수 헬퍼(`conformance.py`) + run.py prepare-time I/O + CLI 패스스루(bash) + validate-run surfacePatterns 배선 + 문서. SSOT: [`docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md`](../specs/2026-06-07-stage-conformance-qa-design.md) §7.2, §8, §12.5, §12.7.
-
-**Tech Stack:** Python 3 (pytest), Bash, markdown.
-
-**전제:** Phase 1~4d 완료. `detect_surfaces(file_paths, patterns)` 이미 override param 보유. `task_dir(project_root, task_group, task_id)` 존재([paths.py:39](../../../scripts/okstra_ctl/paths.py)).
-
----
-
-## Task 1: waiver 헬퍼(순수)
-
-**Files:** Modify `scripts/okstra_ctl/conformance.py`; Test `tests/test_okstra_ctl_conformance.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-```python
-from okstra_ctl.conformance import apply_qa_waiver, parse_qa_waiver_arg  # noqa: E402
-
-
-def test_parse_qa_waiver_arg_splits_on_first_colon():
-    assert parse_qa_waiver_arg('t-stage-1:replica down: skip') == ("t-stage-1", "replica down: skip")
-    assert parse_qa_waiver_arg("nope") is None
-    assert parse_qa_waiver_arg("") is None
-
-
-def test_apply_qa_waiver_sets_entry_waiver():
-    manifest = {"entries": [{"stageKey": "t-stage-1", "waiver": None}]}
-    assert apply_qa_waiver(manifest, "t-stage-1", "replica down", at="2026-06-07T00:00:00Z") is True
-    w = manifest["entries"][0]["waiver"]
-    assert w["acknowledgedBy"] == "user" and w["reason"] == "replica down"
-    assert w["scope"] == [] and w["at"] == "2026-06-07T00:00:00Z"
-
-
-def test_apply_qa_waiver_unknown_stage_returns_false():
-    manifest = {"entries": [{"stageKey": "t-stage-1"}]}
-    assert apply_qa_waiver(manifest, "t-stage-9", "x", at="t") is False
-```
-
-- [ ] **Step 2: 실패 확인** — `python3 -m pytest tests/test_okstra_ctl_conformance.py -q` → FAIL(import 없음)
-
-- [ ] **Step 3: 구현 추가** (`conformance.py` 끝)
-
-```python
-def parse_qa_waiver_arg(arg: object) -> tuple[str, str] | None:
-    """`--qa-waiver` 값 `<stageKey>:<reason>` 를 (stageKey, reason) 로 분해.
-    형식이 아니거나 비면 None."""
-    if not isinstance(arg, str) or ":" not in arg:
-        return None
-    key, reason = arg.split(":", 1)
-    key, reason = key.strip(), reason.strip()
-    if not key or not reason:
-        return None
-    return key, reason
-
-
-def apply_qa_waiver(manifest: object, stage_key: str, reason: str, *, at: str,
-                    acknowledged_by: str = "user") -> bool:
-    """매니페스트에서 stage_key entry 의 `waiver` 를 채운다(in place). 찾으면 True.
-    사용자 확인형 우회(spec §7.2) — reason 은 사용자 지시 원문."""
-    entries = manifest.get("entries") if isinstance(manifest, dict) else None
-    if not isinstance(entries, list):
-        return False
-    for entry in entries:
-        if isinstance(entry, dict) and entry.get("stageKey") == stage_key:
-            entry["waiver"] = {"acknowledgedBy": acknowledged_by, "reason": reason,
-                               "scope": [], "at": at}
-            return True
-    return False
-```
-
-- [ ] **Step 4: 통과** — `python3 -m pytest tests/test_okstra_ctl_conformance.py -q` → PASS
-- [ ] **Step 5: 커밋** — `git commit -m "feat(okstra_ctl/conformance): qa waiver 파싱/적용 헬퍼"`
-
-## Task 2: run.py — `--qa-waiver` prepare-time 적용
-
-**Files:** Modify `scripts/okstra_ctl/run.py`; Test `tests/test_okstra_run_qa_waiver.py` (신규)
-
-- [ ] **Step 1: argparse + PrepareInputs 필드 추가**
-
-`scripts/okstra_ctl/run.py` 의 argparse 에 `--approved-plan` 근처(line 1862 부근)에:
-
-```python
-    p.add_argument("--qa-waiver", default="", dest="qa_waiver",
-                   help='Stage conformance 우회: "<stageKey>:<reason>" (사용자 확인형, 매니페스트 entry.waiver 기록)')
-```
-
-`PrepareInputs`(line 258, `approved_plan_path` 근처)에 `qa_waiver: str = ""` 추가. argv→PrepareInputs 매핑 지점에도 `qa_waiver=args.qa_waiver` 전달.
-
-- [ ] **Step 2: implementation prepare gate 에 waiver 적용**
-
-`run.py` 의 implementation 진입 게이트(qaCommands 검증 블록, `if inp.task_type == "implementation":` 부근 line 1112)에 이어, waiver 적용 헬퍼를 추가하고 호출:
-
-```python
-def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
-    """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다."""
-    if not inp.qa_waiver:
-        return
-    from .conformance import apply_qa_waiver, parse_qa_waiver_arg
-    from .paths import task_dir
-    parsed = parse_qa_waiver_arg(inp.qa_waiver)
-    if parsed is None:
-        raise PrepareError(
-            f'--qa-waiver must be "<stageKey>:<reason>", got {inp.qa_waiver!r}'
-        )
-    stage_key, reason = parsed
-    manifest_path = task_dir(project_root, inp.task_group, inp.task_id) / "qa" / "conformance-manifest.json"
-    if not manifest_path.is_file():
-        raise PrepareError(f"--qa-waiver: conformance manifest not found at {manifest_path}")
-    manifest = json.loads(manifest_path.read_text())
-    when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-    if not apply_qa_waiver(manifest, stage_key, reason, at=when):
-        raise PrepareError(f"--qa-waiver: stageKey {stage_key!r} not in manifest {manifest_path}")
-    manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
-```
-
-게이트 블록에서 `if inp.task_type == "implementation":` 안, qaCommands 검증 다음에 `_apply_qa_waiver_if_requested(inp, project_root)` 호출. (`datetime`/`timezone` import 가 없으면 상단에 `from datetime import datetime, timezone` 추가.)
-
-- [ ] **Step 3: 테스트(신규 파일)**
-
-```python
-# tests/test_okstra_run_qa_waiver.py
-import json, sys
-from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
-from okstra_ctl.run import _apply_qa_waiver_if_requested, PrepareInputs, PrepareError
-from okstra_ctl.paths import task_dir
-import pytest
-
-
-def _inp(**o):
-    base = dict(task_type="implementation", task_group="g", task_id="t", qa_waiver="")
-    base.update(o)
-    return PrepareInputs(**{k: v for k, v in base.items() if k in PrepareInputs.__dataclass_fields__})
-
-
-def test_waiver_fills_manifest(tmp_path):
-    qa = task_dir(tmp_path, "g", "t") / "qa"; qa.mkdir(parents=True)
-    (qa / "conformance-manifest.json").write_text(json.dumps(
-        {"entries": [{"stageKey": "t-stage-1", "waiver": None}]}))
-    _apply_qa_waiver_if_requested(_inp(qa_waiver="t-stage-1:replica down"), tmp_path)
-    m = json.loads((qa / "conformance-manifest.json").read_text())
-    assert m["entries"][0]["waiver"]["reason"] == "replica down"
-
-
-def test_waiver_unknown_stage_raises(tmp_path):
-    qa = task_dir(tmp_path, "g", "t") / "qa"; qa.mkdir(parents=True)
-    (qa / "conformance-manifest.json").write_text(json.dumps({"entries": []}))
-    with pytest.raises(PrepareError):
-        _apply_qa_waiver_if_requested(_inp(qa_waiver="t-stage-1:x"), tmp_path)
-
-
-def test_no_waiver_noop(tmp_path):
-    _apply_qa_waiver_if_requested(_inp(qa_waiver=""), tmp_path)  # no manifest, no error
-```
-
-(주의: `PrepareInputs` 필수 필드가 더 있으면 `_inp` 헬퍼를 실제 필드에 맞춰 보강 — 구현자가 dataclass 확인.)
-
-- [ ] **Step 4: 통과 + 전체** — `python3 -m pytest tests/test_okstra_run_qa_waiver.py tests/ -q`
-- [ ] **Step 5: 커밋** — `git commit -m "feat(okstra_ctl/run): --qa-waiver 로 매니페스트 entry waiver 기록"`
-
-## Task 3: CLI 패스스루(bash)
-
-**Files:** Modify `scripts/okstra.sh`, `scripts/lib/okstra/cli.sh`; Test `tests/test_okstra_sh_qa_waiver_passthrough.py`
-
-- [ ] **Step 1: cli.sh 옵션 파싱** — `--stage)` 케이스(line 98) 근처에 추가:
-
-```bash
-    --qa-waiver)
-      QA_WAIVER="$(require_option_value --qa-waiver "${2-}")"
-      shift 2
-      ;;
-```
-
-help 문자열(line 192)의 옵션 목록에 `--qa-waiver` 추가.
-
-- [ ] **Step 2: okstra.sh 전달** — line 125(`--stage`) 근처에:
-
-```bash
-[[ -n "${QA_WAIVER-}" ]] && PY_ARGS+=(--qa-waiver "$QA_WAIVER")
-```
-
-- [ ] **Step 3: 테스트** — `tests/test_okstra_sh_stage_passthrough.py` 를 모델로 `--qa-waiver foo:bar` 가 `python -m okstra_ctl.run` 인자까지 전달되는지 검증(스테이지 테스트의 인자-캡처 패턴 재사용).
-
-- [ ] **Step 4: 통과 + 커밋** — `git commit -m "feat(cli): --qa-waiver 패스스루(okstra.sh/cli.sh)"`
-
-## Task 4: surfacePatterns 배선(validate-run)
-
-**Files:** Modify `validators/validate-run.py`; Test `tests/test_validate_run_conformance.py`
-
-- [ ] **Step 1: `_validate_conformance` 에 surface_patterns 주입**
-
-`_validate_conformance(report_path, failures)` 시그니처에 `surface_patterns: object = None` 추가. 내부 diff-surface 호출을 `detect_surfaces(changed_files, surface_patterns)` 로 바꾼다. 메인 dispatch 에서 호출 시 project.json 의 `qaEnv.surfacePatterns` 를 읽어 전달:
-
-```python
-        if task_type in ("implementation", "final-verification"):
-            _sp = None
-            _pj = project_json_path(project_root)
-            if _pj.is_file():
-                try:
-                    _sp = (json.loads(_pj.read_text()).get("qaEnv") or {}).get("surfacePatterns")
-                except (OSError, json.JSONDecodeError):
-                    _sp = None
-            _validate_conformance(report_path, failures, surface_patterns=_sp)
-```
-
-`project_json_path` import 추가(`from okstra_project import project_json_path` 또는 기존 import 라인 확장 — 실제 export 확인).
-
-- [ ] **Step 2: 테스트 추가** — `tests/test_validate_run_conformance.py` 에: 커스텀 패턴으로 `.xyz` 를 db 로 매핑해 미선언 시 BLOCKING 되는지(직접 `_validate_conformance(report, failures, surface_patterns={"db": ["*.xyz"]})` 호출).
-
-- [ ] **Step 3: 통과 + 전체 + workflow** — `python3 -m pytest tests/ -q` + `bash validators/validate-workflow.sh`
-- [ ] **Step 4: 커밋** — `git commit -m "feat(validators): qaEnv.surfacePatterns 를 diff-surface 교차검증에 반영"`
-
-## Task 5: qaEnv 문서 + wizard picker(prescriptive)
-
-**Files:** Modify `skills/okstra-setup/SKILL.md`, `skills/okstra-run/SKILL.md` (wizard); 그리고 surfacePatterns 기본 over-broad 주의 노트
-
-- [ ] **Step 1: setup 문서** — `skills/okstra-setup/SKILL.md` 의 `qaCommands` 설명 근처에 `qaEnv` 블록 문서 추가:
-
-```json
-"qaEnv": {
-  "replicaDbDsn": "<replica/test DB DSN — never shared/staging/prod>",
-  "appBaseUrl": "http://localhost:3000",
-  "envFile": ".okstra/qa.env",
-  "surfacePatterns": { "db": ["*.sql", "*repository*"], "http": ["*controller*"] }
-}
-```
-
-설명: verifier Tier3 conformance 스크립트가 replica DB·endpoint 에 닿는 통로(replica 전용). `surfacePatterns` 는 diff-surface 교차검증의 프로젝트별 override(기본 `*router*`/`*storage*` 패턴은 프론트엔드 파일을 넓게 잡으므로 프론트 중심 repo 는 override 권장 — Phase 4b 리뷰 노트).
-
-- [ ] **Step 2: wizard picker** — `skills/okstra-run/SKILL.md` 의 implementation 입력 흐름에, conformance BLOCKING 이 예상되고 사용자가 우회를 원할 때 `--qa-waiver <stageKey>:"<reason>"` 를 안내하는 추천형 picker 한 단계 추가(추천 + "직접 입력", 마지막 옵션 "직접 입력"). lead/worker 자체 면제 금지 — 사용자 입력만.
-
-- [ ] **Step 3: build + 검증** — `npm run build` + `bash validators/validate-workflow.sh` + `python3 -m pytest tests/ -q`
-- [ ] **Step 4: 커밋** — `git commit -m "docs(skills): qaEnv(replica/surfacePatterns) 문서 + qa-waiver wizard 안내"`
-
----
-
-## Phase 4e Self-Review 체크
-
-- [ ] `--qa-waiver` 가 매니페스트 entry.waiver 를 채우고(원문 reason), 미지 stageKey/형식오류는 PrepareError?
-- [ ] CLI 패스스루(okstra.sh→run)가 동작?
-- [ ] qaEnv.surfacePatterns 가 detect_surfaces 에 반영?
-- [ ] setup 문서/wizard 에 qaEnv·waiver 명문화?
-- [ ] 전체 pytest + workflow validator + build 통과?
-
-Phase 4e 완료 = conformance QA 기능 전체 완성. 완료 후 `CHANGES.md` 에 `사용자 영향:` 엔트리 추가 + 전체 회귀 최종 확인.

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

@@ -1,409 +0,0 @@
-# Stage Conformance QA (Tier 3) 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/final-verification 의 각 stage 가 상위 요구사항에 부합하는지 실DB·엔드포인트·외부 API 수준에서 검증하는 Tier 3 conformance 게이트를 추가하고, 미검증을 silent pass 가 아닌 BLOCKING 으로 만들되 명시적 우회(선언형 면제 / 사용자 확인형 waiver)를 감사한다.
-
-**Architecture:** 모든 산출물이 의존하는 결정론적 코어(매니페스트 검증 + `QA-RESULT` 파서)를 먼저 만들고(Phase 1), 그 위에 강제(Phase 2) → 생성/실행 wiring(Phase 3) → 우회 UX/env(Phase 4)를 얹는다. 설계 SSOT: [`docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md`](../specs/2026-06-07-stage-conformance-qa-design.md).
-
-**Tech Stack:** Python 3 (stdlib + pytest), markdown prompt profiles, Node CLI (`bin/`, `scripts/lib/okstra/`), project.json.
-
----
-
-## 단계 분해 (Phase Roadmap)
-
-이 기능은 분리 가능한 4개 슬라이스다. **본 문서는 Phase 1 을 bite-sized TDD 로 완전히 기술**하고, Phase 2~4 는 각자 독립 계획으로 확장한다(Phase 1 이 데이터 계약을 락인하므로 그 뒤가 안정적). 각 phase 는 그 자체로 테스트 가능하다.
-
-| Phase | 슬라이스 | 핵심 산출물 | 의존 |
-|---|---|---|---|
-| 1 | 계약 & 검증 코어 | `scripts/okstra_ctl/conformance.py` + 단위테스트 | 없음 |
-| 2 | 강제(load-bearing) | `validators/validate-run.py` Tier3 BLOCKING + `run.py` 진입 게이트 | 1 |
-| 3 | 생성·실행 wiring | `implementation-planning.md`/`_implementation-verifier.md`/`final-verification.md` prompt | 1,2 |
-| 4 | 우회 UX & env | `--qa-waiver` CLI + wizard + `project.json.qaEnv` | 1,2 |
-
-Phase 2~4 요약(각자 별도 계획으로 작성):
-
-- **Phase 2** — `validators/validate-run.py` 에 conformance 게이트 추가: implementation/final-verification diff 가 `requires`(db/io/http/external) 표면을 건드리는데 매니페스트 entry 가 없거나 결과가 FAIL/MISSING 이고 면제·waiver 도 없으면 BLOCKING. 선언형 면제가 실제 surface 와 불일치하면 BLOCKING. `run.py` 의 implementation 진입 게이트(현 [`run.py:1110`](../../../scripts/okstra_ctl/run.py:1110) qaCommands 패턴 모방)에서 `validate_conformance_manifest` 호출. surface 추정은 implementation report 의 Diff Summary(파일 경로/확장자/SQL 키워드) 기반 휴리스틱 + 명시 `requires` 우선.
-- **Phase 3** — `prompts/profiles/implementation-planning.md` 에 stage 별 `### 5.5.x Stage Conformance Tests` 산출 + `.okstra/.../qa/` 스크립트·매니페스트 기록 지시(`Acceptance:` 의 실행형). `_implementation-verifier.md` 의 two-tier lookup 에 **Tier 3** 추가(스크립트 실행 → `parse_qa_result` 결과를 Read-only command log 에 기록). `final-verification.md` 는 전 stage 합집합 실행.
-- **Phase 4** — `scripts/okstra.sh`/`scripts/lib/okstra/cli.sh` 에 `--qa-waiver <stageKey>:"<reason>"` 패스스루(→ `run.py` 가 매니페스트 entry 의 `waiver` 채움), `okstra-run` wizard 에 사용자 확인 picker, `project.json.qaEnv`(replicaDbDsn/appBaseUrl/envFile) 문서화(resolver 는 비-identity 필드를 이미 보존하므로 코드 변경 불필요 — [`resolver.py:120`](../../../scripts/okstra_project/resolver.py:120) 확인).
-
----
-
-## Phase 1 — 계약 & 검증 코어
-
-새 모듈 [`scripts/okstra_ctl/qa_commands.py`](../../../scripts/okstra_ctl/qa_commands.py) 와 동형의 sibling `conformance.py` 를 만든다. 런타임 검증/파싱 전용(순수 함수, 부수효과 없음).
-
-### Task 1: 매니페스트 구조 검증 (`validate_conformance_manifest`)
-
-**Files:**
-- Create: `scripts/okstra_ctl/conformance.py`
-- Test: `tests/test_okstra_ctl_conformance.py`
-
-- [ ] **Step 1: 실패 테스트 작성**
-
-```python
-# tests/test_okstra_ctl_conformance.py
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-_REPO_ROOT = Path(__file__).resolve().parent.parent
-sys.path.insert(0, str(_REPO_ROOT / "scripts"))
-
-from okstra_ctl.conformance import (  # noqa: E402
-    CAPABILITY_WHITELIST,
-    validate_conformance_manifest,
-)
-
-
-def _entry(**over):
-    base = {
-        "stageKey": "dev-9184-stage-3",
-        "script": "qa/stage-3.ts",
-        "runCommand": "npx ts-node .okstra/qa/stage-3.ts",
-        "requirementIds": ["R-001"],
-        "requires": ["db", "http"],
-        "passContract": "exit 0 = PASS",
-        "exemption": None,
-        "waiver": None,
-    }
-    base.update(over)
-    return base
-
-
-def test_valid_manifest_has_no_errors():
-    manifest = {"entries": [_entry()]}
-    assert validate_conformance_manifest(manifest) == []
-
-
-def test_absent_manifest_is_legal():
-    assert validate_conformance_manifest(None) == []
-
-
-def test_non_object_manifest_rejected():
-    assert validate_conformance_manifest([]) != []
-
-
-def test_entries_must_be_array():
-    assert any("entries" in e for e in validate_conformance_manifest({"entries": {}}))
-
-
-def test_missing_required_string_fields_reported():
-    errs = validate_conformance_manifest({"entries": [_entry(stageKey="")]})
-    assert any("stageKey" in e for e in errs)
-
-
-def test_requirement_ids_must_be_non_empty_list():
-    errs = validate_conformance_manifest({"entries": [_entry(requirementIds=[])]})
-    assert any("requirementIds" in e for e in errs)
-
-
-def test_unknown_capability_rejected():
-    errs = validate_conformance_manifest({"entries": [_entry(requires=["db", "gpu"])]})
-    assert any("gpu" in e for e in errs)
-
-
-def test_capability_whitelist_value():
-    assert CAPABILITY_WHITELIST == ("db", "io", "http", "external")
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: FAIL — `ModuleNotFoundError: No module named 'okstra_ctl.conformance'`
-
-- [ ] **Step 3: 최소 구현**
-
-```python
-# scripts/okstra_ctl/conformance.py
-"""Stage conformance(Tier 3) 매니페스트 검증 + `QA-RESULT` 파서.
-
-implementation/final-verification 의 verifier 는 stage 별 conformance 스크립트를
-실행해 상위 요구사항 부합을 검증한다. 본 모듈은 그 검증/파싱의 결정론적 코어다.
-
-1. `conformance-manifest.json` 구조 검증 (`validate_conformance_manifest`).
-2. 스크립트 stdout 의 `QA-RESULT` 마커 파싱 (`parse_qa_result`).
-
-스크립트 실행/게이트 강제는 verifier prompt 와 validators/validate-run.py 가 담당한다.
-"""
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-# diff 가 건드린 표면과 대조할 capability 태그 화이트리스트.
-CAPABILITY_WHITELIST: tuple[str, ...] = ("db", "io", "http", "external")
-
-
-class ConformanceError(ValueError):
-    """conformance 매니페스트가 계약을 어긴 경우."""
-
-
-def _check_nonempty_str(value: object, path: str, errors: list[str]) -> bool:
-    if not isinstance(value, str) or not value.strip():
-        errors.append(f"{path} must be a non-empty string")
-        return False
-    return True
-
-
-def _check_capabilities(value: object, path: str, errors: list[str]) -> None:
-    if not isinstance(value, list):
-        errors.append(f"{path} must be an array")
-        return
-    for cap in value:
-        if cap not in CAPABILITY_WHITELIST:
-            errors.append(
-                f"{path}: unknown capability {cap!r} "
-                f"(allowed: {', '.join(CAPABILITY_WHITELIST)})"
-            )
-
-
-def _check_entry(entry: object, idx: int, errors: list[str]) -> None:
-    path = f"entries[{idx}]"
-    if not isinstance(entry, dict):
-        errors.append(f"{path} must be an object")
-        return
-    _check_nonempty_str(entry.get("stageKey"), f"{path}.stageKey", errors)
-    _check_nonempty_str(entry.get("script"), f"{path}.script", errors)
-    _check_nonempty_str(entry.get("runCommand"), f"{path}.runCommand", errors)
-    _check_nonempty_str(entry.get("passContract"), f"{path}.passContract", errors)
-    req_ids = entry.get("requirementIds")
-    if (
-        not isinstance(req_ids, list)
-        or not req_ids
-        or not all(isinstance(r, str) and r.strip() for r in req_ids)
-    ):
-        errors.append(f"{path}.requirementIds must be a non-empty array of strings")
-    _check_capabilities(entry.get("requires", []), f"{path}.requires", errors)
-
-
-def validate_conformance_manifest(manifest: object) -> list[str]:
-    """conformance-manifest 전체 검증. 위반 메시지 리스트 반환(비면 안전).
-
-    매니페스트 부재(None)는 합법 — 스크립트 없는 task 가 있을 수 있고, 게이트
-    강제(diff surface 대조)는 validators/validate-run.py 가 판정한다.
-    """
-    if manifest is None:
-        return []
-    if not isinstance(manifest, dict):
-        return [f"conformance manifest must be an object, got {type(manifest).__name__}"]
-    entries = manifest.get("entries")
-    if not isinstance(entries, list):
-        return ["conformance manifest .entries must be an array"]
-    errors: list[str] = []
-    for idx, entry in enumerate(entries):
-        _check_entry(entry, idx, errors)
-    return errors
-```
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: PASS (8 passed)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/conformance.py tests/test_okstra_ctl_conformance.py
-git commit -m "feat(okstra_ctl/conformance): conformance 매니페스트 구조 검증"
-```
-
-### Task 2: 면제/waiver 형태 검증 + stageKey 중복
-
-**Files:**
-- Modify: `scripts/okstra_ctl/conformance.py`
-- Test: `tests/test_okstra_ctl_conformance.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-```python
-def test_exemption_requires_reason_and_declared_at():
-    bad = _entry(exemption={"reason": ""})
-    errs = validate_conformance_manifest({"entries": [bad]})
-    assert any("exemption.reason" in e for e in errs)
-    assert any("exemption.declaredAt" in e for e in errs)
-
-
-def test_valid_exemption_passes():
-    ok = _entry(exemption={"reason": "doc-only stage", "declaredAt": "2026-06-07"})
-    assert validate_conformance_manifest({"entries": [ok]}) == []
-
-
-def test_waiver_requires_fields_and_scope_whitelist():
-    bad = _entry(waiver={"acknowledgedBy": "user", "reason": "env down",
-                         "at": "2026-06-07", "scope": ["db", "gpu"]})
-    errs = validate_conformance_manifest({"entries": [bad]})
-    assert any("waiver.scope" in e and "gpu" in e for e in errs)
-
-
-def test_valid_waiver_passes():
-    ok = _entry(waiver={"acknowledgedBy": "user", "reason": "replica down — skip db",
-                        "at": "2026-06-07T10:00:00Z", "scope": ["db"]})
-    assert validate_conformance_manifest({"entries": [ok]}) == []
-
-
-def test_duplicate_stage_key_reported():
-    errs = validate_conformance_manifest({"entries": [_entry(), _entry()]})
-    assert any("duplicate" in e for e in errs)
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: FAIL — 면제/waiver 미검증, 중복 미검출
-
-- [ ] **Step 3: 구현 추가**
-
-`conformance.py` 의 `_check_entry` 끝(`_check_capabilities(... "requires" ...)` 다음 줄)에 추가:
-
-```python
-    _check_exemption(entry.get("exemption"), f"{path}.exemption", errors)
-    _check_waiver(entry.get("waiver"), f"{path}.waiver", errors)
-```
-
-`_check_capabilities` 정의 다음에 두 헬퍼 추가:
-
-```python
-def _check_exemption(value: object, path: str, errors: list[str]) -> None:
-    if value is None:
-        return
-    if not isinstance(value, dict):
-        errors.append(f"{path} must be an object or null")
-        return
-    _check_nonempty_str(value.get("reason"), f"{path}.reason", errors)
-    _check_nonempty_str(value.get("declaredAt"), f"{path}.declaredAt", errors)
-
-
-def _check_waiver(value: object, path: str, errors: list[str]) -> None:
-    if value is None:
-        return
-    if not isinstance(value, dict):
-        errors.append(f"{path} must be an object or null")
-        return
-    _check_nonempty_str(value.get("acknowledgedBy"), f"{path}.acknowledgedBy", errors)
-    _check_nonempty_str(value.get("reason"), f"{path}.reason", errors)
-    _check_nonempty_str(value.get("at"), f"{path}.at", errors)
-    _check_capabilities(value.get("scope", []), f"{path}.scope", errors)
-```
-
-`validate_conformance_manifest` 의 루프를 중복 검출로 교체:
-
-```python
-    errors: list[str] = []
-    seen: set[str] = set()
-    for idx, entry in enumerate(entries):
-        _check_entry(entry, idx, errors)
-        key = entry.get("stageKey") if isinstance(entry, dict) else None
-        if isinstance(key, str) and key:
-            if key in seen:
-                errors.append(f"entries[{idx}].stageKey duplicate: {key!r}")
-            seen.add(key)
-    return errors
-```
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: PASS (13 passed)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/conformance.py tests/test_okstra_ctl_conformance.py
-git commit -m "feat(okstra_ctl/conformance): 면제/waiver 형태 + stageKey 중복 검증"
-```
-
-### Task 3: `QA-RESULT` stdout 파서 (`parse_qa_result`)
-
-**Files:**
-- Modify: `scripts/okstra_ctl/conformance.py`
-- Test: `tests/test_okstra_ctl_conformance.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-```python
-from okstra_ctl.conformance import parse_qa_result  # noqa: E402  (파일 상단 import 에 합쳐도 됨)
-
-
-def test_parse_pass_with_requirements():
-    out = "running...\nREQ R-001: PASS: row count 3 > 0\nQA-RESULT: PASS\n"
-    res = parse_qa_result(out)
-    assert res.overall == "PASS"
-    assert res.requirements["R-001"]["status"] == "PASS"
-    assert "row count" in res.requirements["R-001"]["reason"]
-
-
-def test_parse_fail():
-    res = parse_qa_result("REQ R-001: FAIL: parity mismatch\nQA-RESULT: FAIL\n")
-    assert res.overall == "FAIL"
-    assert res.requirements["R-001"]["status"] == "FAIL"
-
-
-def test_missing_marker_is_missing():
-    assert parse_qa_result("no marker here").overall == "MISSING"
-    assert parse_qa_result("").overall == "MISSING"
-
-
-def test_last_marker_wins():
-    assert parse_qa_result("QA-RESULT: PASS\nQA-RESULT: FAIL\n").overall == "FAIL"
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: FAIL — `cannot import name 'parse_qa_result'`
-
-- [ ] **Step 3: 구현 추가**
-
-`conformance.py` 끝에 추가:
-
-```python
-_QA_RESULT_RE = re.compile(r"^QA-RESULT:\s*(PASS|FAIL)\s*$", re.MULTILINE)
-_REQ_LINE_RE = re.compile(r"^REQ\s+(\S+):\s*(PASS|FAIL):\s*(.*)$", re.MULTILINE)
-
-
-@dataclass
-class QaResult:
-    overall: str  # "PASS" | "FAIL" | "MISSING"
-    requirements: dict  # id -> {"status": "PASS"|"FAIL", "reason": str}
-
-
-def parse_qa_result(stdout: str) -> QaResult:
-    """스크립트 stdout 에서 `QA-RESULT` 마커 + `REQ` 줄 파싱.
-
-    마커가 없으면 overall='MISSING' — 스크립트가 계약을 안 지킨 것이므로 게이트는
-    FAIL 로 취급한다. 마커가 여럿이면 마지막 것을 채택한다.
-    """
-    text = stdout or ""
-    markers = _QA_RESULT_RE.findall(text)
-    overall = markers[-1] if markers else "MISSING"
-    requirements: dict = {}
-    for rid, status, reason in _REQ_LINE_RE.findall(text):
-        requirements[rid] = {"status": status, "reason": reason.strip()}
-    return QaResult(overall=overall, requirements=requirements)
-```
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/test_okstra_ctl_conformance.py -q`
-Expected: PASS (17 passed)
-
-- [ ] **Step 5: 전체 스위트 회귀 확인 + 커밋**
-
-```bash
-python3 -m pytest tests/ -q
-git add scripts/okstra_ctl/conformance.py tests/test_okstra_ctl_conformance.py
-git commit -m "feat(okstra_ctl/conformance): QA-RESULT stdout 파서"
-```
-
----
-
-## Phase 1 Self-Review 체크
-
-- [ ] spec §3(데이터 모델) 의 모든 entry 필드(stageKey/script/runCommand/requirementIds/requires/passContract/exemption/waiver)가 `validate_conformance_manifest` 로 커버되는가?
-- [ ] spec §4(스크립트 계약)의 `QA-RESULT`/`REQ` 마커가 `parse_qa_result` 로 커버되는가?
-- [ ] capability 화이트리스트가 spec §3 의 `["db","io","http","external"]` 와 일치하는가?
-- [ ] Phase 2 가 의존하는 공개 API(`validate_conformance_manifest`, `parse_qa_result`, `CAPABILITY_WHITELIST`, `QaResult`)가 안정적으로 노출되는가?
-
-Phase 1 완료 후 Phase 2 계획(`docs/superpowers/plans/2026-06-07-stage-conformance-qa-phase2.md`)을 작성한다.