feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00
parent cfd84875bf
commit 58515ab0f3
251 changed files with 31470 additions and 109 deletions
@@ -0,0 +1,165 @@
+# Per-File Findings + Adversarial Review Template
+
+Root SSOT: [`rules/reporting-standards.md`](../../../../../rules/reporting-standards.md) §"4. 파일별 발견 사항" + §"4-1. 적대 리뷰 결과"
+parent: [`README.md`](README.md)
+
+§0~§3, §3-1 Verdict, §5~§8 → [`report-template.md`](report-template.md)
+§7.1 self-grep 카운트 규칙 → [`verification-rules.md`](verification-rules.md)
+
+## §4. 파일별 발견 사항 / Per-File Findings
+
+> **분할 시:** §4 상세는 `<topic>-per-file-findings.md` 파일에 들어간다. master report 의 §4 는 한 줄 요약 + 링크만.
+
+각 파일은 자기 하위섹션을 갖는다. "Pillar", "Group", "Theme" 등으로 묶지 않는다. 묶으면 누락 숨겨짐.
+
+각 발견 사항은 **Goal → Problem → Action 인과 사슬** 형식. 단순 의견("성능이 떨어질 수 있다", "고려가 필요하다") 금지. 자세한 컨트랙트는 [`../advisory-depth/contracts-1-causal-chain.md`](../advisory-depth/contracts-1-causal-chain.md) Contract 1 참조.
+
+### 한 파일에서의 finding 개수
+
+각 파일에 대해 분석이 surfacing 한 **모든 gap 을 finding 으로 등재**. 1 파일 = 1 finding 이 아니라 발견된 모든 결함·누락·모호점 빠짐없이 풀어쓴다. 보통 명세 1개 = 2~5 findings.
+
+### Single-finding Justification Gate
+
+파일당 finding 이 정확히 1개라면 §4 하위섹션 끝에 **반드시** 정당화 블록 첨부. 정당화 없이 1개로 끝낸 파일은 자동 `BLOCKED`.
+
+```markdown
+#### Single-finding justification (필수, finding이 1개일 때)
+
+다음 4개 중 1개 이상 해당:
+
+- [ ] **단순 명세:** 파일 총 라인 수 < 80, 또는 단일 정책 명세.
+       증거: `<file>` 총 <N>줄, 결정 사항 1건.
+- [ ] **전수 통과 + 1개 결함:** 검토 <K>개 항목 중 (K−1)개 PASS, 1개 FAIL.
+       검토 항목 리스트:
+       1. <item 1> — PASS
+       2. <item 2> — PASS
+       3. <item 3> — FAIL (위 finding)
+- [ ] **부분 분석 (PARTIAL):** 시간·범위 제약. §6 Follow-Up 에 추가 분석 대상 명시.
+       남은 대상: <list>
+- [ ] **단일 critical 차단:** finding 이 너무 critical 하여 다른 항목 분석에 앞서 처리되어야 함.
+       이유: <근거>
+```
+
+블록 없거나, 4개 중 어느 것도 체크 안 됐거나, "검토 항목" 비어 있으면 → 자동 `BLOCKED`. 정당화는 fluff 아닌 **사실 진술**.
+
+### Zero-finding 파일 처리
+
+진정 0-finding 인 `READ_FULL` 파일은 하위섹션을 생략하지 **않는다**. 명시:
+
+```markdown
+**0-finding 정당화 (필수):**
+이 파일은 명세 의도와 현재 상태가 일치하며, 검토 <N>개 항목 모두 통과.
+
+검토 항목:
+1. <item 1> — PASS — 근거: `<file:line>`
+2. <item 2> — PASS — 근거: `<file:line>`
+```
+
+`<N>개 항목`은 추상적 아닌 실제 목록. "검토 모두 통과" 한 줄만 → 자동 `BLOCKED`.
+
+### 4.1 `<filename>` (Status: READ_FULL | READ_PARTIAL)
+
+- **요지 / Gist:** <한 문장으로 이 파일이 무엇을 정의하는가>
+- **문서 원래 목표:** <이 파일이 정의하려 한 핵심 의도>. 근거: `<file:line>`
+- **검토 항목:** <N개 항목 리스트>
+- **Findings 요약:** N개 (Critical X · High Y · Medium Z · 통과 W)
+
+#### Finding 4.1.1: <짧은 라벨 — 이 finding 의 한 문장 정체성>
+
+- **심각도:** Critical | High | Medium | Low
+- **원래 목표 / Original goal:**
+  - **인용:** "<exact text from source, byte-for-byte>"
+  - **위치:** `<path>:<line>` (워크스페이스 상대 경로만)
+  - **해석:** <한 문장>
+- **현재 상태 / Current state:**
+  - **인용:** "<exact text>" (또는 "해당 라인 없음 — 명세 자체에 누락")
+  - **위치:** `<path>:<line>`
+- **실무 가정 / Real-world assumptions (REQUIRED — min 1, typical 2~3):**
+  비판이 성립하려면 어떤 실무 가정이 참이어야 하는가? 명시하지 않으면 비판은 "에이전트가 상상한 구현" 표적.
+  1. **가정 A:** <e.g., "구현이 동기식", "프로덕션 트래픽 > 1000 RPS", "K8s 환경">
+     - **무효 조건:** <이 가정이 거짓일 시나리오>
+     - **사용자 검증 방법:** <한 줄 체크>
+  2. **가정 B:** ...
+- **간극 / Gap (위 가정들이 모두 참일 때):**
+  - **구체적 실패 모드:** <X 상황에서 Y 발생 → Z 깨짐 — 1~3개>
+  - **재현 조건:** <실패가 일어나는 트리거>
+  - **이 finding 이 무효해지는 경우:** <어떤 가정이 거짓이면 비판 자체 사라지는가>
+- **필요 조치:** <구체 액션 — 추상 아닌 실행 가능 형태>
+- **조치 근거:** <왜 이 액션이 일반 대안보다 이 상황에 맞는가>
+- **대안 / Alternatives considered:** [`../advisory-depth/contracts-2-3-4-structure.md`](../advisory-depth/contracts-2-3-4-structure.md) Contract 2 — 가능한 모든 대안 열거 (3~5개)
+  - **대안 A:** <라벨> — 적용 상황 / 부적합 이유
+  - **대안 B:** ...
+  - **대안 C (채택):** <라벨> — 왜 이 상황에 가장 맞는가
+- **반대 논거 / Counterarguments (REQUIRED — min 1, typical 2~3):**
+  Contract 1 — 권고가 틀릴 수 있는 시나리오.
+  1. **반대 A:** <권고가 부적절·과잉인 시나리오>
+     - **반대 근거:** <왜 그 시나리오에서 부적절한가>
+     - **검증 방법:** <한 줄 체크>
+- **구현 단계:** <순서 있는 단계>
+  1. <단계 1 — 수정할 파일, 어디에 어떤 내용 들어가는지>
+  2. <단계 2>
+- **검증 방법:**
+  - **자동:** <self-grep / `wiki-link-verifier` / `/lint` / frontmatter grep / wikilink ls 등>
+  - **수동:** <Obsidian 그래프뷰 / 리뷰 시 확인 포인트 — 자동 부족 시에만>
+- **관련:**
+  - 다른 finding 과 결합: <같은 / 다른 파일 finding 과 함께 처리해야 효과>
+  - 상호 의존 파일: <영향 주고받는 명세/모듈>
+
+#### Finding 4.1.2: ...
+
+### 4.2 `<next filename>` ...
+
+`NOT_READ` 및 `BLOCKED` 파일은 본 섹션에 자기 하위섹션 X. 매트릭스와 §3 에만 등장.
+
+### Master report 에서의 §4 (분할 시)
+
+분할 시 master report 의 §4 는 한 줄 요약 표만:
+
+```markdown
+## 4. 파일별 발견 사항 (요약)
+
+> 상세: [<topic>-per-file-findings.md](./docs/superpowers/specs/<topic>-per-file-findings.md)
+
+| # | File | Findings | Critical | High | Medium | Low | 통과 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 4.1 | `feature-X.md` | 3 | 1 | 2 | 0 | 0 | N/A |
+```
+
+## §4-1. 적대 리뷰 결과 / Adversarial Review Results
+
+§4 findings 5개 이상 시 `wiki-adversarial-reviewer` 디스패치 **권장**. 5개 미만이면 적대 리뷰 없이 송신 가능.
+
+분할 시: 본 섹션은 **master report 에 들어간다**. per-file-findings 에는 들어가지 않는다.
+
+### 4-1.1 적대 리뷰 실행 여부
+
+| 항목 | 값 |
+| --- | --- |
+| 적대 리뷰 실행 | YES / NO |
+| 실행하지 않은 사유 (NO 시) | <e.g., findings < 5> |
+| 적대 리뷰 보고서 경로 | `docs/superpowers/specs/YYYY-MM-DD-<topic>-adversarial-review.md` |
+
+### 4-1.2 적대 리뷰 요약 표 (실행 시)
+
+| Finding ID | Original severity | Practicality | Overclaim | Assumption | Action |
+| --- | --- | --- | --- | --- | --- |
+| 4.1.1 | Critical | PASS | FAIL | PASS | DOWNGRADE → High |
+
+### 4-1.3 컨트롤러 판단 반영
+
+- **수용 (Accept)**: 권고대로 강등 또는 제거 적용.
+- **거부 (Override)**: 거부 사유 1~2줄 명시 필수.
+
+| Finding ID | 적대 권고 | 컨트롤러 결정 | 거부 사유 (Override 시) |
+| --- | --- | --- | --- |
+| 4.1.1 | DOWNGRADE → High | Accept | — |
+| 4.2.1 | REJECT | Override (KEEP at Medium) | 사용자 환경에서 실제 관측 사례 |
+
+### 4-1.4 결과 메트릭
+
+- KEEP: <n>
+- DOWNGRADE: <n>
+- REJECT: <n>
+- Override: <n>
+
+§1 Executive Summary 와 §5 Priority Recommendations 는 적대 리뷰 결과 **반영 후** 상태. 강등된 finding 이 §5 에 여전히 Critical 이면 자동 `BLOCKED`.