okstra 0.102.1 → 0.102.3

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

@@ -1,282 +0,0 @@
-# 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 를 누가 어떻게 주입하는가.

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

@@ -1,147 +0,0 @@
-# Stage Conformance QA — Phase 4a (위치 SSOT + 게이트 task-level 전환) 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 산출물의 단일 출처를 task-level `<task_root>/qa/` 로 확정한다 — `paths.py` 에 `TASK_QA_PATH` 토큰을 추가하고, Phase 3 게이트(`_validate_conformance`)가 run-level 대신 task-level `qa/` 를 읽도록 고친다(Phase 3 의 final-verification 잠복 결함 해소).
-
-**Architecture:** 순수 경로/검증 변경. SSOT: [`docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md`](../specs/2026-06-07-stage-conformance-qa-design.md) §12.1.
-
-**Tech Stack:** Python 3 (stdlib + pytest).
-
-**전제:** Phase 1~3 완료. `validators/validate-run.py` 에 `_validate_conformance` 존재, `tests/test_validate_run_conformance.py` 존재.
-
-**경로 사실(확정):** 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 1: `paths.py` 에 TASK_QA_PATH 토큰 추가
-
-**Files:**
-- Modify: `scripts/okstra_ctl/paths.py`
-- Test: `tests/test_task_path_ssot.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-`tests/test_task_path_ssot.py` 끝에 추가:
-
-```python
-def test_task_qa_path_under_task_root():
-    root = Path("/tmp/proj")
-    ctx = compute_run_paths(
-        workspace_root=Path("/ws"),
-        project_root=root,
-        project_id="p",
-        task_group="My Group",
-        task_id="Task ID 01",
-        task_type="implementation",
-        run_seq_override=1,
-    )
-    assert ctx["TASK_QA_PATH"] == str(Path(ctx["TASK_ROOT"]) / "qa")
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/test_task_path_ssot.py -q`
-Expected: FAIL — `KeyError: 'TASK_QA_PATH'`
-
-- [ ] **Step 3: 구현**
-
-`scripts/okstra_ctl/paths.py` 의 `analysis_packet = instruction_set / "analysis-packet.md"` (line 119 부근) 다음 줄에 추가:
-
-```python
-    task_qa = task_root / "qa"
-```
-
-같은 함수의 `abs_paths` 딕셔너리에서 `"ANALYSIS_PACKET_PATH": str(analysis_packet),` 다음 줄에 추가:
-
-```python
-        "TASK_QA_PATH": str(task_qa),
-```
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/test_task_path_ssot.py -q`
-Expected: PASS
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/paths.py tests/test_task_path_ssot.py
-git commit -m "feat(okstra_ctl/paths): conformance task-level qa 경로 토큰(TASK_QA_PATH)"
-```
-
-## Task 2: 게이트를 task-level `qa/` 로 전환
-
-**Files:**
-- Modify: `validators/validate-run.py`
-- Test: `tests/test_validate_run_conformance.py`
-
-- [ ] **Step 1: 테스트 fixture 를 task-level 로 갱신(먼저 실패 유도)**
-
-`tests/test_validate_run_conformance.py` 의 `_make_run` 에서 qa 디렉터리를 task_root(=`tmp_path`) 아래로 옮긴다. 현재:
-
-```python
-    run_dir = tmp_path / "runs" / "implementation"
-    (run_dir / "reports").mkdir(parents=True)
-    qa = run_dir / "qa"
-    qa.mkdir()
-```
-
-로 바꾼다:
-
-```python
-    run_dir = tmp_path / "runs" / "implementation"
-    (run_dir / "reports").mkdir(parents=True)
-    qa = tmp_path / "qa"   # task-level: <task_root>/qa (task_root = tmp_path)
-    qa.mkdir()
-```
-
-(`test_no_manifest_is_inert` 는 qa 를 만들지 않으므로 그대로 inert — 변경 불필요.)
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/test_validate_run_conformance.py -q`
-Expected: FAIL — 게이트가 아직 run-level(`run_dir/qa`)을 읽어 매니페스트를 못 찾고 inert 처리 → `test_missing_result_is_blocking`/`test_failing_result_is_blocking`/`test_malformed_manifest_reported` 가 기대 실패를 못 내고 FAIL.
-
-- [ ] **Step 3: 구현 — 게이트 경로 수정**
-
-`validators/validate-run.py` 의 `_validate_conformance` 에서:
-
-```python
-    qa_dir = report_path.parent.parent / "qa"
-```
-
-를 다음으로 바꾼다:
-
-```python
-    # conformance 산출물은 task-level(<task_root>/qa)에 있어 planning/
-    # implementation/final-verification 가 공유한다. report_path 는
-    # task_root/runs/<task-type>/reports/final-report.md 이므로 task_root 는
-    # run_dir(=report_path.parent.parent)에서 두 단계 위.
-    run_dir = report_path.parent.parent
-    qa_dir = run_dir.parent.parent / "qa"
-```
-
-- [ ] **Step 4: 통과 확인 + 전체 회귀 + workflow validator**
-
-Run: `python3 -m pytest tests/test_validate_run_conformance.py -q` → Expected: PASS (7 passed)
-Run: `python3 -m pytest tests/ -q` → Expected: 전부 통과
-Run: `bash validators/validate-workflow.sh` → Expected: PASS (fixture 에 `<task_root>/qa` 없음 → inert)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add validators/validate-run.py tests/test_validate_run_conformance.py
-git commit -m "fix(validators): conformance 게이트를 task-level qa 로 전환(final-verification 공유)"
-```
-
----
-
-## Phase 4a Self-Review 체크
-
-- [ ] `TASK_QA_PATH == <task_root>/qa` 인가?
-- [ ] 게이트가 task_root/qa 를 읽어 implementation·final-verification 가 같은 위치를 보는가?
-- [ ] inert(매니페스트 부재) 동작 유지 — 기존 run/ workflow validator 무영향?
-- [ ] 전체 pytest + workflow validator 통과?
-
-Phase 4a 완료 후 Phase 4b(`detect_surfaces` + diff-surface 교차검증) 계획을 작성한다.