okstra 0.54.0 → 0.56.0

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

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

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

@@ -0,0 +1,169 @@
+# Stage 요구사항-부합 검증 (Tier 3 Conformance QA) 설계
+
+- 상태: 설계 승인됨 (구현 전)
+- 날짜: 2026-06-07
+- 관련 코드: [`scripts/okstra_ctl/qa_commands.py`](../../../scripts/okstra_ctl/qa_commands.py), [`prompts/profiles/_implementation-verifier.md`](../../../prompts/profiles/_implementation-verifier.md), [`prompts/profiles/implementation-planning.md`](../../../prompts/profiles/implementation-planning.md), [`prompts/profiles/final-verification.md`](../../../prompts/profiles/final-verification.md), [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py), [`validators/validate-run.py`](../../../validators/validate-run.py)
+
+## 1. 배경과 문제
+
+implementation run 은 정적 분석 + 모킹 유닛테스트 게이트를 통과해도, **실DB·프로젝트 엔드포인트·외부 API 같은 통합 표면**은 검증하지 못한 채 "정적 분석상 OK, 미검증(실행 안 함)"으로 남는 구조적 공백이 있다.
+
+근거 — DEV-9184 (`fontradar-v2-api`) Stage 3:
+
+- 1930 유닛테스트 green + tsc clean 으로 정적/모킹 게이트는 통과했으나 **종합 verdict 는 FAIL**.
+- 원인 ①: DB real-execution 게이트(G-2/V-5) — diff 가 DB/SQL 을 건드리는데 `db-test` 미선언 → `정적 분석상 OK, 미검증(실행 안 함)`.
+- 원인 ②: 모킹이 못 잡은 런타임 버그(Q-1, full-consensus). 실DB·실행 없이는 표면화 불가.
+- FU-002 의 처방이 정확히 이 기능의 형태였다: replica DB 에서 `SELECT COUNT(*) FROM LicenseVersionMinPrices WHERE idLicenseVersion=<DRAFT> > 0`, `GET /price/list` pre/post read↔publish parity 검증.
+
+핵심 통찰: 이 공백은 "검증 명령 부재"가 *조용히* PASS 로 흐른 데서 비롯됐다(silent mock-green). 따라서 해법은 (a) stage 별 통합 검증 스크립트를 1급 산출물로 만들고, (b) 그 스크립트가 없거나 못 돌 때 **조용히 통과시키지 않는 것**이다.
+
+## 2. 목표 / 비목표
+
+목표:
+
+- implementation 의 각 stage(및 final-verification)에 대해, **상위 요구사항(task brief → requirements-discovery / error-analysis / improvement-discovery → plan stage Acceptance)에 부합하는지**를 검증하는 실행 스크립트를 산출·실행·판정한다.
+- 유닛/모킹이 닿지 못하는 표면(실DB·엔드포인트·외부 API)을 커버한다.
+- 검증 미실행을 **silent pass 가 아니라 BLOCKING** 으로 만든다. 단, **명시적으로 확인된 우회 경로**를 감사 흔적과 함께 제공한다.
+
+비목표:
+
+- 유닛테스트 자체의 대체(executor 의 RED→GREEN TDD 루프는 그대로 유지). 이 기능은 그 위의 **통합/부합 게이트**다.
+- 사용자 repo 의 정식 테스트 스위트를 okstra 가 소유/관리하는 것(Approach C 기각). conformance 스크립트는 okstra artifact 로 `.okstra/` 하위에 둔다.
+- 정적·프로젝트 전역 `qaCommands` 베이스라인을 per-stage 데이터로 오염시키는 것(Approach B 기각).
+
+## 3. 데이터 모델 (무엇을 · 어디에)
+
+artifact-home 규칙에 따라 모든 산출물은 `.okstra/` 하위에 둔다.
+
+- 스크립트: `.okstra/tasks/<task-key>/runs/implementation/qa/stage-<N>.<ext>` (stage 당 1개 이상).
+- conformance 매니페스트: `.okstra/tasks/<task-key>/runs/implementation/qa/conformance-manifest.json`
+
+```json
+{
+  "entries": [
+    {
+      "stageKey": "<task-id>-stage-<N>",
+      "script": "qa/stage-3.ts",
+      "runCommand": "npx ts-node .okstra/.../qa/stage-3.ts",
+      "requirementIds": ["R-001", "GAP-1"],
+      "requires": ["db", "http"],
+      "passContract": "exit 0 = PASS, non-zero = FAIL",
+      "exemption": null,
+      "waiver": null
+    }
+  ]
+}
+```
+
+- 요구사항 추적성: 각 entry 의 `requirementIds` 는 plan §5.5.8 Requirement Coverage 의 `R-NNN`, 그리고 brief / requirements-discovery / error-analysis / improvement-discovery 에서 이월된 ID 를 가리킨다. "이 스크립트가 어떤 요구사항의 부합을 증명하는가"를 명시한다.
+- `requires`: capability 태그 화이트리스트 `["db", "io", "http", "external"]`. diff 가 건드린 표면과 대조해 게이트 강도를 결정한다.
+
+## 4. 표준 스크립트 계약 (`main → pass/fail`)
+
+- 진입점 `main()` 실행 → **exit code 0 = PASS / 비0 = FAIL**.
+- stdout 마지막 줄에 파싱용 마커: `QA-RESULT: PASS|FAIL`, 그리고 요구사항별 줄 `REQ <id>: PASS|FAIL: <근거>`.
+- 언어는 프로젝트 따라감(`qaCommands` 의 `language` 와 정합). 예: DEV-9184 는 TS 스크립트가 `GET /price/list` 호출 + replica DB 에 `SELECT COUNT(*) … WHERE idLicenseVersion=<DRAFT>` 실행 후 read↔publish parity 를 판정.
+- 스크립트는 기본적으로 black-box(HTTP/SQL 등 외부에서 관측)로 작성한다. 프로젝트 코드 import 가 필요한 경우는 예외로, 프로젝트 모듈 해석 경로에 맞춘 배치를 허용한다(엣지).
+
+## 5. 생성 시점 · 주체
+
+- implementation-planning 이 stage 별로:
+  1. plan 에 `### 5.5.x Stage Conformance Tests` 블록을 산출한다. 블록은 스크립트 본문 + 헤더(`stageKey` / `requirementIds` / `requires`)를 담는다.
+  2. 그 스크립트를 `.okstra/.../qa/` 에 파일로 기록하고 `conformance-manifest.json` 을 생성한다.
+- 근거: `Acceptance:` 라인이 이미 plan 의 1급 요소이므로, conformance 스크립트는 "Acceptance 를 실행 가능하게 만든 것"으로서 plan deliverable 의 자연스러운 확장이다(planning=설계 원칙과 정합 — 테스트 코드는 구현이 아니라 수용 기준의 실행형).
+
+## 6. 실행 · 판정 (verifier Tier 3 + final-verification)
+
+- verifier 의 명령 lookup 에 **Tier 3** 추가:
+  - Tier 1 = plan validation (pre/mid/post),
+  - Tier 2 = `project.json.qaCommands`,
+  - **Tier 3 = conformance 스크립트** (해당 stage 의 매니페스트 entry).
+- verifier 는 stage 의 스크립트를 worktree / replica env 에서 실행하고, exact runCommand + exit code + `QA-RESULT` 파싱 결과를 Read-only command log 와 증거에 기록한다.
+- final-verification: 전 stage 의 스크립트 합집합을 통합 state 에 대해 실행한다.
+- **핵심 불변식 — 미실행 = BLOCKING**: diff 가 `requires`(db/io/http/external) 표면을 건드리는데 스크립트 부재 / env 부재 / 미실행이면, DEV-9184 처럼 passive note 가 아니라 **verdict FAIL** 로 격상한다(silent mock-green 금지).
+
+## 7. 명시적 우회 경로
+
+"건너뛰려면 둘 중 하나가 반드시 있어야 하고, 둘 다 리포트에 감사 흔적으로 남는다." silent skip 은 불가.
+
+### 7.1 Planning 선언형 면제
+
+- stage 에 `Conformance exemption: <사유>` 라인을 선언(기존 `TDD exemption:` 패턴과 동형).
+- 용도: 테스트가 정말 불필요한 stage(doc / config / pure-rename, 또는 db/io/external 을 안 건드리고 유닛으로 충분).
+- 안전장치: diff 가 실제로 db/io/external 을 건드리면 선언형 면제는 **거부(BLOCKING)** — 면제 사유와 실제 surface 가 일치할 때만 허용. (면제로 실DB 변경을 숨기는 것 방지)
+- 기록: 매니페스트 entry 의 `exemption: { reason, declaredAt }`.
+
+### 7.2 Run-time 사용자 확인형 우회 (waiver)
+
+- conformance 가 필요한데(surface 건드림) 사용자가 의도적으로 건너뛰는 경우.
+- **사용자 명시 확인 필수**(lead / worker 자체 면제 불가):
+  - interactive(`okstra-run`): 명시적 확인 프롬프트(추천 picker, 마지막 옵션 "직접 입력").
+  - headless(`okstra.sh`): `--qa-waiver <stageKey>:"<사유>"` 명시 인자.
+- 기록: 매니페스트 / 리포트에 `waiver: { acknowledgedBy, reason, scope: ["db" | "http" | …], at }`. `reason` 은 **사용자 지시 원문 그대로**(artifact-home 규칙의 "사용자 지시 verbatim 인용"과 동형).
+- verdict 반영: waiver 가 적용된 run 은 clean PASS 가 아니라 **`conditional-accept` (conformance 미검증 — 사용자 확인)** 로 기록 → final-verification 에서 그 조건이 그대로 노출된다. `conditional-accept` 는 기존 final-verdict verdict token 을 재사용.
+- scope 단위: stage 전체 또는 capability 별(예: `db` 만 waive, `http` 는 그대로 실행) — allowlist 방식으로 좁게.
+
+## 8. env · 안전 모델
+
+- `project.json` 에 정적 `qaEnv` 블록 추가(예: `replicaDbDsn`, `appBaseUrl`, `envFile` 참조). per-stage 스크립트는 번들에, env 포인터는 `project.json` 에(정적 / 민감정보 분리). `qaEnv` 는 resolver 의 user-managed 보존 필드로 둔다(identity/timestamp 필드만 runtime-owned).
+- 안전: 기본 **replica / test env 전용**. mutation 을 일으키는 스크립트는 capability 태그로 명시한다. 기존 `qaCommands` 의 mutation deny-list 정신을 conformance 스크립트 실행 환경 가드에도 적용한다.
+- env / secret 부재 시 → §6 의 BLOCKING(절대 silent pass 아님). 단 §7.2 사용자 확인형 waiver 로만 우회 가능.
+
+## 9. 검증 · 강제 (이 기능 자체)
+
+- 매니페스트 스키마 validator: entry 필수 필드(`stageKey`, `script`, `runCommand`, `requirementIds`, `requires`, `passContract`), `requires` 화이트리스트, `exemption`/`waiver` 형태.
+- verifier Tier 3 lookup 단위테스트(스크립트 있음/없음/면제/waiver 분기).
+- 강제 케이스: "diff 가 `requires` 표면을 건드림 + 스크립트/결과/면제/waiver 모두 없음 → BLOCKING FAIL".
+- 선언형 면제 거부 케이스: "면제 선언했지만 diff 가 db/io/external 을 건드림 → BLOCKING".
+- `QA-RESULT` 파싱 테스트(PASS/FAIL/누락).
+- 우회 감사 흔적 테스트: waiver 시 리포트에 사용자 원문 인용 + `conditional-accept` 반영.
+
+## 10. 리스크 / 열린 질문
+
+- replica DB / 실행 env 준비는 프로젝트별 운영 부담. `qaEnv` 미설정 시 게이트가 항상 BLOCKING → 도입 초기에는 §7 우회로 점진 적용.
+- planning 이 실행 컨텍스트 없이 작성한 스크립트가 틀릴 수 있음 → 스크립트는 구현 전 RED(실패), 구현 후 GREEN(통과)으로 동작해야 하며, verifier 가 실제 실행으로 검증한다(정적 작성 ≠ 검증).
+- 동시 병렬 stage run(stage worktree isolation)에서 conformance 스크립트가 공유 replica DB 를 건드릴 때의 격리/오염 — 초기엔 직렬 실행 가정, 추후 stage 별 env 분리 고려.
+
+## 11. 롤아웃
+
+- pre-1.0 이므로 호환 shim 없음. `qaCommands` 부재 프로젝트는 기존처럼 Tier 2 미구성으로 동작하되, Tier 3 는 매니페스트가 있을 때만 활성.
+- 사용자 영향(`CHANGES.md`)에 `사용자 영향:` 라인으로 기록.
+- 산출물은 seed/template/runtime sync 경로를 통해 end user 에 전파(`npm run build`).
+
+## 12. Phase 4 addendum (2026-06-07) — 위치·생성·실행·강제 wiring 확정
+
+Phase 1~3(계약·판정·validate-run 게이트) 구현 중 드러난 설계 갭을 brainstorm 으로 해소한 결정. Phase 4 구현의 SSOT.
+
+### 12.1 산출물 위치 — task-level (확정)
+- conformance 매니페스트/스크립트/`result-<stageKey>.json` 은 **`<task_root>/qa/`** (task-level) 에 둔다. planning→implementation→final-verification 3개 task-type 이 공유해야 하므로 run-level(`runs/<task-type>/qa/`)로는 final-verification 이 implementation 산출물을 못 본다.
+- `scripts/okstra_ctl/paths.py` 에 `task_qa()` / `TASK_QA_PATH` 토큰을 추가해 단일 출처로 삼는다(run.py/prompt/validator 의 경로 재유도 drift 방지).
+- **Phase 3 게이트 경로 수정(잠복 결함)**: `validators/validate-run.py` 의 `_validate_conformance` 는 현재 `report_path.parent.parent/qa`(run-level)를 읽는다 — task-level 결정에 따라 `<task_root>/qa` 로 바꾼다. report_path 는 `task_root/runs/<task-type>/reports/final-report.md` 이므로 `run_dir = report_path.parent.parent` (=`runs/<task-type>`), `task_root = run_dir.parent.parent`, `qa_dir = task_root / "qa"`. (주의: `report_path.parent.parent.parent` 는 `runs/` 라 잘못됨 — 한 단계 더 올라가야 task_root.) Phase 3 테스트 fixture 도 task-level 로 갱신한다.
+- 병렬 stage run 안전성: stage 별 `result-<stageKey>.json` 파일명이 달라 동시 쓰기 충돌 없음. 매니페스트는 planning 이 1회 작성.
+
+### 12.2 planning 생성 + 선언 강제
+- `prompts/profiles/implementation-planning.md`: stage 마다 conformance entry(스크립트 + `<task_root>/qa/conformance-manifest.json` 갱신) **또는** `Conformance exemption: <사유>` 라인을 산출한다(기존 `TDD exemption:` 패턴과 동형).
+- `validators/validate-implementation-plan-stages.py` 에 새 검사(S11): 모든 stage 가 conformance entry 또는 exemption 을 가질 것 — 미선언 시 planning boundary 에서 BLOCKING.
+
+### 12.3 verifier 실행 (Tier 3)
+- `prompts/profiles/_implementation-verifier.md`: command lookup 을 Tier1(plan validation) → Tier2(`qaCommands`) → **Tier3(conformance)** 로 확장. 각 entry 의 `runCommand` 를 worktree cwd + `qaEnv` 로 실행 → `parse_qa_result` → `<task_root>/qa/result-<stageKey>.json` 작성(포맷 `{stageKey, overall, ranAt, requirements}` — 코드가 이미 고정).
+
+### 12.4 diff-surface 교차검증 (DEV-9184 자동 차단)
+- `scripts/okstra_ctl/conformance.py` 에 순수 함수 `detect_surfaces(file_paths) -> set[str]` 추가. 기본 패턴(`*.sql`·`migrations/`·`*repository*`·`*.entity.*` → `db`; `*controller*`·`*.routes.*` → `http`; 등), `project.json.qaEnv.surfacePatterns` 로 override.
+- `validators/validate-run.py`: **한 run = 한 stage** 이므로 그 run 의 Diff Summary 파일 목록에서 surface 를 감지하고, 해당 stage 의 선언(`requires` + exemption)이 그 surface 를 커버하지 못하면 BLOCKING. (순수 함수 → TDD 가능; validate-run 은 report 의 §5.7.3 Diff Summary 파일 경로를 입력으로 사용)
+
+### 12.5 env 모델
+- `project.json.qaEnv`: `replicaDbDsn` / `appBaseUrl` / `envFile`(+ 선택 `surfacePatterns`). `scripts/okstra_project/resolver.py` 는 비-identity 필드를 이미 자동 보존하므로 코드 변경 불필요 — 스키마/`skills/okstra-setup/SKILL.md`/verifier prompt 만 문서화.
+- 안전: replica/test 전용, mutation 스크립트는 capability 태그로 명시, 기존 `qaCommands` mutation deny-list 정신 유지.
+
+### 12.6 final-verification
+- `prompts/profiles/final-verification.md`: task-level `<task_root>/qa/` 에서 전 stage 스크립트 합집합을 통합 state 에 대해 실행, command lookup 에 Tier3 추가.
+
+### 12.7 우회 UX (spec §7.2 구체화)
+- `scripts/okstra.sh` / `scripts/lib/okstra/cli.sh` 에 `--qa-waiver <stageKey>:"<reason>"` 패스스루 → `scripts/okstra_ctl/run.py` 가 `<task_root>/qa/conformance-manifest.json` 의 해당 entry `waiver` 를 채움(`acknowledgedBy`/`reason`(원문)/`scope`/`at`). `okstra-run` wizard 는 사용자 확인 picker(추천 + "직접 입력").
+
+### 12.8 Phase 4 sub-plan 분해(구현 단위)
+1. **4a** — 위치 SSOT: `paths.py` TASK_QA 토큰 + Phase 3 게이트 경로/테스트 task-level 전환.
+2. **4b** — `detect_surfaces` (순수) + validate-run diff-surface 교차검증.
+3. **4c** — planning 생성 + S11 선언 강제(prompt + validator).
+4. **4d** — verifier Tier3 실행(prompt) + final-verification Tier3(prompt).
+5. **4e** — env(`qaEnv` 스키마/setup/문서) + 우회 UX(`--qa-waiver` CLI + wizard).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.54.0",
-  "builtAt": "2026-06-06T15:10:15.217Z",
+  "package": "0.56.0",
+  "builtAt": "2026-06-07T06:39:30.395Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -101,7 +101,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
 - For `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage.
-- When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes.
+- When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes. `improvement-discovery` is NOT in the data.json schema enum, so author its markdown directly (not via `okstra-render-final-report.py`). Immediately after writing the markdown, run (`Bash`): `python3 scripts/okstra-inject-report-index.py <markdown path> --report-language <en|ko>`. That adds the top-of-report Index plus `I-NNN` / `C-NNN` scroll anchors; the run validator fails the report when the Index anchor is absent.
 
 Write the data.json with your `Write` tool against the absolute `Result Path`. Then invoke the renderer (`Bash`): `python3 scripts/okstra-render-final-report.py <data.json path>`. Confirm both files exist and respond with a short status line: `data.json written to <abs path>; markdown rendered to <abs path>. Sections populated: <count>.`
 

package/runtime/bin/lib/okstra/cli.sh

@@ -99,6 +99,10 @@ while [[ $# -gt 0 ]]; do
       STAGE="$(require_option_value --stage "${2-}")"
       shift 2
       ;;
+    --qa-waiver)
+      QA_WAIVER="$(require_option_value --qa-waiver "${2-}")"
+      shift 2
+      ;;
     --task-type)
       TASK_TYPE="$(require_option_value --task-type "${2-}")"
       shift 2
@@ -189,7 +193,7 @@ while [[ $# -gt 0 ]]; do
           printf '  hint: did you mean --task-id?\n' >&2
           ;;
       esac
-      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve --implementation-option --stage --no-plan-verification -h|--help\n' >&2
+      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve --implementation-option --stage --qa-waiver --no-plan-verification -h|--help\n' >&2
       usage
       exit 1
       ;;

package/runtime/bin/lib/okstra/usage.sh

@@ -52,6 +52,11 @@ optional arguments:
                        --task-type=implementation. The runtime fills the approved-plan frontmatter
                        \`implementation-option:\` line with <name>. When omitted, the implementation run
                        falls back to the plan's \`Recommended Option\`.
+  --qa-waiver <stageKey>:<reason>
+                       Stage conformance gate 우회(사용자 확인형). Only meaningful with
+                       --task-type=implementation. prepare-time 에 task-level conformance 매니페스트의
+                       해당 stageKey entry.waiver 를 채운다(reason 은 사용자 지시 원문 그대로 기록).
+                       lead/worker 가 스스로 면제할 수 없으며 사용자가 명시할 때만 사용한다.
   --no-plan-verification
                        Disable the Phase 6 plan-body verification round that runs after the report-writer
                        authors the implementation-planning draft. Default: enabled. Only meaningful with