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,68 @@
+# Antigravity Plugin Rules — wiki-superpowers
+
+본 디렉토리는 **Antigravity CLI 환경에 최적화된 rule split** 을 제공한다. **root `rules/` 가 여전히 SSOT 이며**, 본 폴더의 파일은 root rule 의 본문을 의미상 동일하게 유지하되 Antigravity 의 context window / 모델 instruction-following 한계를 고려해 작은 파일로 분할한 사본이다.
+
+## 왜 분할이 필요한가
+
+- [공식 권고 (HumanLayer)](https://www.humanlayer.dev/blog/writing-a-good-claude-md): *"< 300 lines is best, shorter is even better. Frontier thinking LLMs can follow ~150-200 instructions with reasonable consistency."*
+- [Anthropic Claude Code best practices](https://code.claude.com/docs/en/best-practices): 500줄 초과 파일은 대부분 무시됨.
+- root `rules/` 중 다음 3개가 임계 초과:
+  - `rules/reporting-standards.md` — 559줄 ❌
+  - `rules/advisory-depth.md` — 418줄 ❌
+  - `rules/diagram-standards.md` — 379줄 ❌
+- 나머지 root rules 는 300줄 미만 — 분할 불필요.
+
+## 작동 원칙
+
+1. **Root rules 는 변경되지 않는다.** 3개 모델 (Claude / Antigravity / Codex) 공유 SSOT.
+2. **Plugin 폴더 파일은 root 의 verbatim split**. 의미를 바꾸지 않는다. 단어를 추가하거나 룰을 약화시키지 않는다.
+3. **Antigravity-specific 메모는 각 sub-folder README 에만 추가**. 그 외 sub-file 은 root 본문 그대로.
+4. **충돌 시 root 가 우선**. 본 폴더의 내용이 root 와 어긋나면 root 가 진실.
+
+## 폴더 구조
+
+```
+.agents/plugins/wiki-superpowers/rules/
+  README.md                          ← 본 파일 (index + 운영 원칙)
+  reporting-standards/
+    README.md                        ← scope + Antigravity hook 메모 + sub-file index
+    output-split.md                  ← root §"Output Split Policy" 발췌
+    report-template.md               ← root §"Report Template" §0~§3 + §3-1 + §5~§8
+    findings-template.md             ← root §4 + §4-1
+    verification-rules.md            ← root §7
+  advisory-depth/
+    README.md                        ← scope + Antigravity 한계 (Stop hook 본문 미수신) 메모
+    contracts-1-causal-chain.md      ← Contract 1 + Why Assumption Surfacing
+    contracts-2-3-4-structure.md     ← Contract 2 (옵션 열거) + 3 (Plan Gap) + 4 (Direct-Response)
+    contracts-5-6-citation-grep.md   ← Contract 5 (Citation) + 6 (Self-Grep)
+    contract-7-forbidden-words.md    ← Contract 7 + Concept Organization Mode
+  diagram-standards/
+    README.md                        ← scope + tool 분리 reminder + 8항 self-check
+    principles.md                    ← §1 The Two Tests + §2 The Question
+    elements.md                      ← §3 Element Budget + §4 Component Label + §5 Edge Label + §6 Visual Hierarchy
+    structure.md                     ← §7 Boundary + §8 Callout + §9 Legend + §10 Header/Footer + §11 Source
+    mermaid.md                       ← §12 Sequence + §13 ER
+    anti-patterns.md                 ← §15 + §16
+```
+
+## Antigravity-specific 컨텍스트 (전역 메모)
+
+본 폴더의 sub-rule 을 따를 때 Antigravity 특수 컨텍스트:
+
+| 컨텍스트 | 영향 |
+|---|---|
+| `Stop` hook 이 `response_text` 미수신 | chat 본문 응답 enforce 불가 — 따라서 `reporting-standards/` 의 §7.1 self-grep 진실성, advisory-depth Contract 7 금지어 검사 등은 **agent self-check 단독 책임** |
+| PreToolUse hook `wiki_hard_gate.py` 가 `docs/superpowers/specs/*.md` write 만 가로챔 | G1~G4 만 강제 (§7.1 grep 명령 존재 / 금지어 / Verdict 산식 / §4-1 Adversarial Review 존재) |
+| 도구 이름 = `write_to_file`, `edit_file`, `run_command`, `bash` | 다른 write 도구 사용 시 hook 우회됨 — `str_replace_editor` 등 발견 시 matcher 확장 필요 |
+| Brain folder (`~/.gemini/antigravity-cli/brain/<uuid>/`) 휘발성 | implementation plan / task / scratch 파일은 영구 산출물 아님 — 최종 보고서는 반드시 `docs/superpowers/specs/` 에 |
+
+## 로딩 패턴 (skill 의 lazy-load 와 동일)
+
+- 작업 시작 시 본 폴더의 **README 와 적용 sub-rule 만 로드** (전체 모든 sub-rule 한꺼번에 로드 X).
+- 예: multi-doc 보고서 작성 → `reporting-standards/` 의 sub-rule 4개. diagram 그리는 작업 → `diagram-standards/`. 그 외는 로드 X.
+- 모호하면 root `rules/` 를 단일 파일로 로드해 통일된 본문 확인.
+
+## 충돌 / 의문 발생 시
+
+- 본 폴더 sub-file 과 root 가 다르면 **root 진실**. plugin 폴더 sub-file 의 오류로 간주 → 사용자에게 보고.
+- root 가 갱신되면 plugin 폴더 sub-file 도 같이 업데이트 필요 (현재 수동 동기화). 추후 자동화 후보.
@@ -0,0 +1,62 @@
+# advisory-depth (plugin split)
+
+Root SSOT: [`rules/advisory-depth.md`](../../../../../rules/advisory-depth.md) (418줄)
+
+본 폴더는 root rule 을 Antigravity 컨텍스트에서 lazy-load 하기 좋게 4개 sub-file 로 분할한 사본이다. 의미는 root 와 동일. 충돌 시 root 가 진실.
+
+## 적용 대상
+
+- Multi-file wiki 보고서 (research-lane, link-verifier, adversarial-reviewer)
+- Direct-response 답변 (subagent dispatch 없이 controller 가 직접 답할 때)
+- Brainstorming / design 대화 (wiki 구조, 문서 정책, taxonomy 결정)
+- 개념 설명 / "explain X" 질문 (특히 `wiki/concepts/` 추출 후보)
+- Plan gap reviews (`/ingest`, `/projectize`, `/interviewize`, `/blogify` 파이프라인)
+- 위 어떤 작업에서든 single-finding 권고
+
+## 핵심 메시지
+
+> The user does not use this CLI to hear "this looks fine" or "this is a good idea". They use it for **practical engineering advice they could not produce alone**. Shallow advice is a failure even when the facts are correct.
+
+## Sub-file index
+
+| Sub-file | 다루는 Contract | 필독 시점 |
+|---|---|---|
+| [`contracts-1-causal-chain.md`](contracts-1-causal-chain.md) | Contract 1: Goal → Assumption → Problem → Action 7-field 사슬 + Why Assumption Surfacing | 모든 finding 작성 시 |
+| [`contracts-2-3-4-structure.md`](contracts-2-3-4-structure.md) | Contract 2: 모든 옵션 열거 / 3: Plan Gap Detection / 4: Direct-Response Template | 비교·권고·plan 리뷰·direct answer 작성 시 |
+| [`contracts-5-6-citation-grep.md`](contracts-5-6-citation-grep.md) | Contract 5: Citation Discipline (verbatim + file:line) / 6: Self-Grep Verification (실제 sed/grep 실행) | 인용 또는 quote 가 들어가는 모든 finding 작성 시 |
+| [`contract-7-forbidden-words.md`](contract-7-forbidden-words.md) | Contract 7: 금지 마케팅 단어 + 외부 근거 요구 + Concept Organization Mode | 모든 advisory 응답 송신 직전 self-check |
+
+## Antigravity-specific 메모
+
+| 항목 | Antigravity 컨텍스트 |
+|---|---|
+| Contract 6 Self-Grep 실제 실행 여부 | hook 은 `$ sed -n` / `$ grep -nF` **문자열의 존재만** 검사. 진짜 실행됐는지는 검증 불가. agent 가 위조 출력을 적어도 hook 통과 — **진실성은 agent 자체 책임**. |
+| Contract 7 금지어 (verbatim quote 밖) | hook G2 가 `docs/superpowers/specs/*.md` write 시 자동 enforce. 그 외 경로 / chat 본문에서는 self-check 단독. |
+| Counterargument 존재 (Contract 1) | hook 미커버. agent self-check 단독. ≥1 Counterarg 없으면 finding `BLOCKED` 처리 자체가 agent 책임. |
+| Plan Gap Detection (Contract 3) | hook 미커버. plan review 시 "looks fine" 응답 자체가 자동 `BLOCKED` 이지만 enforcement 없음 — self-check 단독. |
+| Stop hook 한계 | chat 본문 응답은 어떤 검사도 받지 않음. Direct-Response Template (Contract 4) §1~§6 모두 self-check 로만 강제. |
+
+## Anti-Patterns
+
+| Pattern | Why fails | Replacement |
+|---|---|---|
+| "X를 추천합니다" without conditions | User cannot tell when X is wrong | Conditional recommendation: "If A → X, if B → Y" |
+| One option presented, no alternatives | User cannot tell what they are giving up | Exhaustive Option Enumeration (Contract 2) |
+| "성능이 떨어질 수 있다" / "고려가 필요하다" | Vague worry, not advice | Name the concrete failure mode and trigger condition |
+| Listing only the user's named ordering (1→2→3) | Hides 5 other orderings | List all `N!` permutations and discuss each |
+| Plan review returning "looks fine" | No advisory value | Contract 3 (gap matrix) |
+| Long mermaid diagram with no per-finding analysis | Decoration, not advice | Diagrams allowed only as supplement |
+| Finding without Original goal field | Cannot tell if critique or fabrication | Cite the spec/code line that states the original goal |
+| Bilingual mirror response | User reads it twice | One language, the user's |
+
+## Pre-Send Depth Check (essential 7 of 21)
+
+송신 직전 다음 7개 확인. 전체 21 항목은 root rule §"Pre-Send Depth Check" 참조.
+
+1. 모든 finding 이 Contract 1 의 7-field 사슬 (Original goal / Current state / Real-world assumptions / Gap / Required action / Why this action / Alternatives) 완비?
+2. 모든 Original goal / Current state 가 **verbatim quote + `<path>:<line>`** (paraphrase 아닌 byte-for-byte)?
+3. 모든 finding 이 최소 1개 실무 가정 + 무효 조건 + 사용자 검증 방법 포함?
+4. 권고가 **조건부** (`if A → α, if B → β`)? 평탄 "추천: X" 금지?
+5. 모든 finding 이 최소 1개 **Counterargument** + 검증 방법 포함? (0개면 자동 `BLOCKED`)
+6. **금지 단어** (`100%`, `완벽`, `극한`, `절대로`, `최강`, `역사상 가장`, `명품`) 가 verbatim quote 밖에 등장하지 않음?
+7. **Self-grep** 실제 실행 (Contract 6) — 모든 verbatim quote 에 대해 sed/grep 명령 실행 + 출력이 §7.1 에 기록됨? `V == 실제 명령 수` 일치?
@@ -0,0 +1,91 @@
+# Contract 7 — Forbidden Marketing Words + External Evidence (+ Concept Organization Mode)
+
+Root SSOT: [`rules/advisory-depth.md`](../../../../../rules/advisory-depth.md) §"Contract 7" + §"Concept Organization Mode"
+parent: [`README.md`](README.md)
+
+## Contract 7 — Forbidden Marketing Words & External Evidence
+
+Past failure: the agent's findings are mostly grounded, but the prose layered on top inflates them. Words like `"100%"`, `"완벽"`, `"극한"`, `"역사상 가장"` add no engineering meaning and signal that the agent is generating marketing copy on top of real analysis. Separately, claims of "well-known anti-pattern" or "industry standard practice" without an external citation are unverifiable appeals to authority.
+
+This contract bans marketing inflation and forces external citations for industry-norm claims.
+
+### Banned phrases in advisory text
+
+The following words and phrases are forbidden in §1 Executive Summary, §4 Per-File Findings, §5 Priority Recommendations, and Direct-Response answers. They are allowed only inside a verbatim quote (in which case they are accurately citing what the source actually said).
+
+**Marketing inflation:**
+
+- `100%`, `100점`, `0%` (as a perfection claim — `0 errors observed` is OK, `0%까지 완벽 보장` is not)
+- `완벽`, `완벽히`, `완벽한`, `완벽무결`, `완전무결`
+- `극한`, `극도`, `극단적`, `극심하게`, `극대화`
+- `절대`, `절대적`, `절대로` (when used as universal quantifiers — `절대로 일어나서는 안 된다` is OK as a normative statement, `절대로 일어나지 않는다` as a factual claim is not)
+- `최강`, `최고`, `최정상`
+- `역사상 가장`, `사상 최고`, `세계 최초`
+- `즉시`, `즉각` (when paired with hyperbolic claims like `즉시 다운`, `즉각 폭사`)
+- `폭사`, `사살`, `섬멸` (사용자 환경에 대한 비유적 과장)
+- `명품`, `초일류`, `엔터프라이즈급` (자기 평가)
+
+**Banned authority-appeals without citation:**
+
+- `well-known anti-pattern`, `standard practice`, `industry consensus`, `widely accepted`, `everybody knows`
+- `대기업에서는`, `현업에서는`, `실무에서는` — when used to authorize a claim without a specific source. (Acceptable when the agent's own experience/reasoning is what's offered, but then the claim is `INFERENCE`, not authority.)
+- `AWS/Google/Netflix가 이렇게 합니다` — without a specific public doc/talk URL or `CLAUDE.md` / `templates/<x>.md` cross-reference.
+
+### Replacement guidance
+
+| Banned | Replacement |
+|---|---|
+| `100% 무결한 멱등성 보장` | `중복 결제 케이스 N개 차단. 잔여 엣지 케이스: <list>` |
+| `완벽한 보안 격리` | `이 시나리오 하에서 격리됨. <Y> 시나리오는 별도 통제 필요` |
+| `극한으로 깎인 스켈레톤` | `현재 명세 기준 N개 결함 식별, M개는 자동 검증 가능` |
+| `즉시 폭사` | `<X초> 내에 응답 시간이 <Y배> 증가, 임계치 초과 시 알람` |
+| `well-known anti-pattern` | 외부 문서 URL 인용 + 한 문장 인용. 인용 불가 시 `INFERENCE` 라벨 |
+
+### External evidence requirement
+
+권고가 "이게 표준 / 업계 모범 / RFC / 공식 패턴이다" 라는 권위에 호소하면, 해당 권고는 다음 중 하나여야 한다.
+
+1. **외부 문서 인용**: RFC, AWS/GCP/Azure 공식 문서, 공식 프레임워크 reference docs (Spring, Django, Rails 등), OWASP, 또는 명확한 저자가 있는 기술 블로그를 인용. URL 또는 문서 명칭 (`RFC 8594`, `Spring Boot reference docs §6.4`, `OWASP Top 10 A03` 등) 명시. 본 wiki 의 `raw/official-docs/` 또는 `raw/company-tech-blogs/` 에 이미 발췌·보존된 자료라면 해당 raw 파일 wikilink + 원문 URL 동시 명시.
+2. **LLM Wiki CLAUDE.md / templates/* / 기존 wiki 문서 인용**: 본 저장소가 자체적으로 채택한 결정 또는 정책이라면 그 결정 라인을 verbatim quote 로 인용 (예: `CLAUDE.md §15 파이프라인 강제`, `templates/linking-rules.md §2 Mandatory Upward Link 표`).
+3. **INFERENCE 라벨**: 외부 근거가 없다면 권고를 `INFERENCE` 로 라벨링하고, "제가 reasoning 한 결과" 라고 명시. 자기 추론은 합법적이지만 권위 호소로 위장하면 안 된다.
+
+### Pre-send check (Contract 7)
+
+송신 직전 다음 점검. 위반 1건이라도 발견되면 draft `BLOCKED` 및 재작성.
+
+1. 금지 단어 grep: `egrep -oh '(100%|완벽|극한|극도|절대로|최강|역사상)' <draft.md>` 결과 비어 있음? (verbatim quote 내부 등장만 허용)
+2. `well-known/standard practice/industry consensus/대기업에서는/현업에서는` 등의 표현 등장한 곳마다 외부 문서 URL 또는 명세 인용 동반?
+3. 권위 호소 + 인용 없음 → 해당 finding `INFERENCE` 라벨링?
+
+## Concept Organization Mode
+
+When the user asks for a concept explanation, terminology clarification, or "교통 정리" of an area they have not thought through, the agent uses this expansion of the direct-response template:
+
+```markdown
+## 1. 개념 정의 / Concept definition
+- <짧고 정확한 정의>
+- 흔한 오해 / Common confusions: ...
+
+## 2. 구성 요소 / Components
+- <subcomponents or related sub-concepts, each defined once>
+
+## 3. 적용 / Where it applies
+- <real situations where the concept matters in this project>
+
+## 4. 대안 / Alternatives and adjacent concepts
+- <other ways to model the same problem, with one-line trade-offs>
+
+## 5. 이 wiki / 프로젝트에서의 적용 / How it applies here
+- <link to CLAUDE.md / templates/<x>.md / 기존 wiki/concepts/<...>.md / 관련 raw/branch-notes 등 본 개념이 이미 등장하는 파일>
+- <gaps in the current setup, if any>
+
+## 6. 추천 학습 순서 / Suggested order to internalize
+- <if the concept is layered, give the order to study its parts>
+```
+
+## Antigravity-specific 메모
+
+- Hook G2 가 `docs/superpowers/specs/*.md` write 시 자동 enforce — 금지어 ("100%", "완벽", "극한", "절대로", "최강", "역사상 가장", "명품") 가 verbatim quote / code fence / blockquote 밖에 있으면 deny.
+- **단 hook 은 7개 핵심 금지어만 검사**. `극도`, `극단적`, `극심하게`, `극대화`, `즉시`, `즉각`, `폭사`, `사살`, `섬멸`, `초일류`, `엔터프라이즈급`, `완벽무결`, `완전무결`, `절대`, `절대적`, `최고`, `최정상`, `사상 최고`, `세계 최초`, `well-known`, `standard practice`, `industry consensus`, `widely accepted`, `대기업에서는`, `현업에서는`, `실무에서는` 등은 hook 미커버 — agent self-check 단독.
+- chat 본문 응답 / `raw/` · `wiki/` 등 다른 경로 write 도 hook 미커버.
+- External evidence 요구 (INFERENCE 라벨링) 는 hook 미커버 — 권위 호소 + 인용 없음 자동 BLOCKED 정책은 agent self-check 단독.
@@ -0,0 +1,93 @@
+# Contract 1 — Goal → Assumption → Problem → Action Chain
+
+Root SSOT: [`rules/advisory-depth.md`](../../../../../rules/advisory-depth.md) §"Contract 1" + §"Why Assumption Surfacing matters"
+parent: [`README.md`](README.md)
+
+Every finding, recommendation, or critique must be expressed as a causal chain with **explicit real-world assumptions** between the source text and the critique. The chain has seven required fields. **None can be omitted.**
+
+## 7-Field Chain Template
+
+```text
+- **원래 목표 / Original goal:**
+  - 인용 / Verbatim quote: "<exact text, byte-for-byte from source>"
+  - 위치 / Source location: `<path>:<line>` (or `<path>:<startLine>-<endLine>` for ranges)
+  - 해석 / Interpretation: <agent's one-line restatement of what the quoted text intends>
+
+- **현재 상태 / Current state:**
+  - 인용 / Verbatim quote: "<exact text, byte-for-byte from source>"
+  - 위치 / Source location: `<path>:<line>`
+  - 또는 / Or: "해당 라인 없음 — 명세에 명시되지 않음" (only when the gap is the absence itself)
+
+- **실무 가정 / Real-world assumptions (REQUIRED):**
+  명시적 가정이 없으면 비판은 "에이전트가 상상한 구현"에 대한 비판이 되어 신뢰성을 잃는다.
+  최소 1개, 일반적으로 2~3개의 명시적 가정을 나열한다.
+
+  1. **가정 A:** <e.g., "implementation will be synchronous", "production scale > 1000 RPS", "team is using Kubernetes", "this branch will be implemented as-written">
+     - **무효 조건 / Falsifies if:** <under what concrete condition this assumption is false>
+     - **검증 방법 / How user can verify in their context:** <a specific check the user can run>
+  2. **가정 B:** ...
+  3. **가정 C:** ...
+
+- **간극 / Gap (given the assumptions hold):**
+  - **구체적 실패 모드 / Concrete failure mode:** <X 상황에서 Y가 발생하여 Z가 깨진다>
+  - **재현 조건 / Reproduction condition:** <the trigger that actually exposes this in practice>
+  - **이 finding이 무효화되는 시나리오 / When this finding doesn't apply:** <if assumption A or B is false, this gap disappears — be explicit about which assumption is load-bearing>
+
+- **필요 조치 / Required action:** <the specific action that closes the gap>
+
+- **조치 근거 / Why this action:** <why this specific action (not a generic one) is correct here, given the stated assumptions>
+
+- **대안 / Alternatives considered:** 3~5 enumerated per Contract 2 (see [`contracts-2-3-4-structure.md`](contracts-2-3-4-structure.md)).
+
+- **반대 논거 / Counterarguments (REQUIRED — minimum 1, typical 2~3):**
+  이 권고를 적용하지 말아야 하는 시나리오, 또는 이 비판이 과장된 케이스를 명시한다.
+  자기 권고에 대한 self-critique이며, falsification 가능성을 더 폭넓게 확보하는 단계다.
+
+  1. **반대 A:** <이 권고가 틀릴 수 있는 시나리오, 또는 권고 비용이 효익을 초과하는 케이스>
+     - **반대 근거:** <왜 이 시나리오에서는 권고가 부적절한가>
+     - **사용자가 자기 환경에서 이 반대를 검증하는 방법:** <한 줄 체크>
+  2. **반대 B:** <또 다른 falsification 시나리오>
+  3. **반대 C:** ...
+
+  반대 논거가 0개라면 finding은 자동 `BLOCKED`. 자기 권고에 반대할 시나리오를 단 하나도 떠올리지 못한다면, 그 권고는 충분히 검증되지 않은 것이다.
+```
+
+## 강제 규칙
+
+- A finding without a cited Original goal (verbatim + line) is `INFERENCE` and must be labeled as such.
+- A finding without a concrete failure mode in Gap is opinion, not advice.
+- **A finding without explicit Real-world assumptions is forbidden** — the agent must surface the implementation, scale, or context assumption that turns the spec text into a critique-worthy situation, so the user can immediately tell whether the assumption applies to their reality.
+- Bare findings like "성능이 떨어질 수 있다" or "고려가 필요하다" are forbidden. They must be expanded into a Gap with a named failure mode (for example, "스레드 풀 200 큐 + AbortPolicy → 큐 포화 시 RejectedExecutionException → outbox publish 손실").
+
+## Why Assumption Surfacing Matters
+
+When the source text is ambiguous, in-progress (e.g., "검토", "TBD"), or stated at one level (e.g., "decision" vs. "implementation note"), the agent often imagines the worst-case implementation and critiques that. The critique then targets an imagined implementation, not the actual spec.
+
+### Past failures this rule fixes
+
+**Example 1 — NTP drift:**
+- Spec says `"NTP drift > 5초 시 readiness fail 검토"` (line 116).
+- Agent imagines `"synchronous NTP query inside the readiness probe"` and critiques DoS risk.
+  - **Without assumption surfacing:** the critique sounds authoritative but targets an imagined naive implementation.
+  - **With assumption surfacing:** the agent must write `"가정: 검토 단계에서 동기 호출로 구현될 것"`. The user immediately sees: "no, my plan is async — this critique doesn't apply" or "yes, I had not thought about sync vs async — this critique stands".
+
+**Example 2 — management port:**
+- Spec says `"management port 9001 분리"` and does not specify SecurityFilterChain.
+- Agent imagines `"no filter chain configured, exposed to internet"`.
+  - **Without assumption surfacing:** "9001 포트가 무방비로 노출됨" — overconfident.
+  - **With assumption surfacing:** `"가정: 사용자가 management context를 위한 별도 SecurityFilterChain을 아직 구성하지 않았음"`. User: "아, 나 이미 구성했어" → critique no longer applies, no false alarm.
+
+### Rule purpose
+
+The rule is **not to weaken critiques** — it is to make critiques falsifiable. A critique whose assumption is wrong should be visibly rejectable in 5 seconds, not waste the user's time chasing a non-existent problem.
+
+## Antigravity-specific 메모
+
+Counterargument 존재는 hook 미커버. 본 Contract 의 모든 강제는 agent self-check 단독 책임이다. finding 작성 시 self-check 로 다음을 명시적으로 통과시킬 것:
+
+- 7-field 사슬 완비 ?
+- Original goal / Current state 가 byte-for-byte verbatim + workspace-relative path?
+- 실무 가정 최소 1개 + 무효 조건 + 사용자 검증 방법?
+- Counterargument 최소 1개?
+
+하나라도 미달 → finding 폐기 또는 `INFERENCE` 라벨.
@@ -0,0 +1,107 @@
+# Contracts 2, 3, 4 — Option Enumeration / Plan Gap / Direct-Response
+
+Root SSOT: [`rules/advisory-depth.md`](../../../../../rules/advisory-depth.md) §"Contract 2~4"
+parent: [`README.md`](README.md)
+
+## Contract 2 — Exhaustive Option Enumeration
+
+When the user mentions any ordering, comparison, design choice, or "how should I do X", the agent must enumerate the **full option space**, not only the option the user happens to have named.
+
+### Rule of thumb
+
+- If the user names 1 ordering of N items, enumerate all `N!` orderings.
+- If the user names 1 design approach, enumerate at least the canonical alternatives (typically 3–5).
+- If the user asks "which library", enumerate the realistic candidates with their distinct trade-offs.
+- If the user describes a workflow with N steps, list which steps can be reordered, which can be parallelized, which can be skipped, and which are blocking.
+
+### Per-option fields
+
+For each option in the enumeration:
+
+```text
+- **케이스 / Case:** <one-line label>
+- **적용 상황 / When it fits:** <the situations where this option is the right answer>
+- **고려사항 / Considerations:** <what must be true / what must be watched>
+- **장점 / Pros:** <concrete, not vague>
+- **단점 / Cons:** <concrete, not vague>
+- **비교 / Compared to others:** <how this differs from the other options in the same enumeration>
+```
+
+### Conditional recommendation (NOT flat)
+
+After enumerating, the agent provides a **conditional recommendation**:
+
+```text
+- If <situation A> → use <option α>, because <reason>.
+- If <situation B> → use <option β>, because <reason>.
+- If <situation C> → use <option γ>, because <reason>.
+```
+
+**Flat recommendations like "X를 추천합니다" are insufficient.** The agent always ties recommendations to situations.
+
+## Contract 3 — Plan Gap Detection
+
+When the user asks the agent to review, critique, or extend a plan document, the agent must explicitly identify:
+
+1. **Tasks that should be in the plan but are not.** For each:
+   - Why it should be there (tied to the spec or original goal).
+   - Where it should slot in the order (before / after which existing step).
+   - What breaks if it is omitted.
+2. **Tasks that are in the plan but should not be.** For each, the reason for removal and the impact.
+3. **Tasks whose ordering is wrong.** For each, the corrected ordering and why.
+4. **Implicit assumptions in the plan.** Surface them as explicit prerequisites.
+
+A plan review that returns only "the plan looks good" is treated as `BLOCKED`. The agent must surface gaps or explicitly declare "no gaps found, all N tasks needed match the spec" with the matrix of plan-task → spec-section to prove it.
+
+## Contract 4 — Direct-Response Template
+
+When the controller answers directly (no subagent dispatch), the response still uses a structured shape. The template scales with question size; sections can be tight one-liners for trivial questions, but they cannot be skipped.
+
+### Template
+
+```markdown
+## 1. 질문 이해 / Question understood
+- <한 줄 요약>
+- 함의된 목표 / Implied goal: <what the user is actually trying to achieve>
+- 함의된 제약 / Implied constraints: <budgets, deadlines, stack, scale; pulled from project context or asked if missing>
+
+## 2. 경우의 수 / Option space
+- <Option 1>
+- <Option 2>
+- <Option 3>
+- ... (exhaustive per Contract 2)
+
+## 3. 각 경우 분석 / Per-option analysis
+### Case 1: <label>
+- 적용 상황 / When it fits: ...
+- 고려사항 / Considerations: ...
+- 장점 / Pros: ...
+- 단점 / Cons: ...
+### Case 2: ...
+
+## 4. 비교 표 / Comparison matrix
+| Option | 적합 상황 | 주요 장점 | 주요 단점 | 비고 |
+| --- | --- | --- | --- | --- |
+
+(Required when there are 3+ options. Optional below that.)
+
+## 5. 권고 / Conditional recommendation
+- If <situation A> → <option α>, because ...
+- If <situation B> → <option β>, because ...
+(Flat "추천: X" is forbidden.)
+
+## 6. 다음 결정 / Next decisions
+- What the user must decide before the next step
+- What information is still missing
+- What questions the agent has for the user
+```
+
+### Trivial lookups
+
+For trivial single-fact questions (for example "이 메서드는 어디 있나요?"), the template collapses to §1 + a one-line answer with `file:line` citation, and §2~§6 are written as "해당 없음 / N/A — trivial lookup". **The agent still names what it skipped and why; it does not silently drop sections.**
+
+## Antigravity-specific 메모
+
+- Contract 4 의 §1~§6 은 chat 본문 응답에 적용. Stop hook 본문 미수신으로 자동 enforce 불가. agent self-check 단독.
+- Contract 3 plan review "looks fine" 자동 BLOCKED 는 정책 — runtime enforcement 없음. self-check 로 강제.
+- 사용자가 ordering / 비교를 물으면 (Contract 2 적용) full `N!` 또는 3~5 canonical alternatives 열거하지 않은 응답은 부족한 advisory 로 자동 폐기.
@@ -0,0 +1,128 @@
+# Contracts 5 & 6 — Citation Discipline + Self-Grep Verification
+
+Root SSOT: [`rules/advisory-depth.md`](../../../../../rules/advisory-depth.md) §"Contract 5" + §"Contract 6"
+parent: [`README.md`](README.md)
+관련: [`../reporting-standards/verification-rules.md`](../reporting-standards/verification-rules.md) §7.1 카운트 규칙
+
+## Contract 5 — Citation Discipline
+
+Every claim that names a specific number, setting, behavior, decision, or quotation must be backed by **verbatim quote + clickable file:line reference**. This applies to:
+
+- §1 Executive Summary claims
+- §2 Evidence Matrix "Extracted facts" column
+- §4 Per-File Findings (every field that references the spec)
+- §5 Priority Recommendations "근거 파일:라인" column
+- Direct-response answers that reference any file
+
+### Verbatim quote rules
+
+- **Byte-for-byte copy from source.** No paraphrasing, no normalization, no translation in the quote itself.
+- If the quote is too long to embed inline (>200 chars), use elided form: `"<beginning 60 chars>" [...] "<end 60 chars>"` with the `[...]` marker explicit.
+- If quoting Korean text from a source, keep it Korean. If quoting English, keep it English. Mixed-language sources are quoted as-is.
+- The quote must contain the specific content that supports the claim. Quoting a tangential line and then drawing an unrelated conclusion is `FILENAME_INFERENCE` adjacent and counts as a citation failure.
+
+### Source link rules
+
+- **Format:** `path/to/file.md:LINE` for a single line, `path/to/file.md:START-END` for a range.
+- Paths are relative to the workspace root, not absolute (`/home/donghyeon/...` paths are forbidden in citations).
+- IDE-clickable: `file:line` is the universal format that opens directly to the cited line in VS Code, IntelliJ, terminal grep results, GitHub, and most code review tools.
+- For sources outside the workspace (e.g., external docs the user pointed to), still use `file:line` and include the absolute path in a separate `## Source roots` block at the top of the report.
+
+### Banned citation patterns
+
+| Pattern | Why fails | Replacement |
+|---|---|---|
+| `근거: <file:line>` with no quote | User cannot tell if the cited line actually says what the agent claims | Always include verbatim quote alongside the line reference |
+| `(L67)` style citations without the file path | Ambiguous when multiple files are discussed | Always include path: `feature-X.md:67` |
+| Paraphrased "quote" rewritten in the agent's own words | Looks authoritative but is fabrication | Copy exact bytes from source. If clarity needed, add `해석:` field separately |
+| `*근거: 위 문서 본문*` / vague references | Untraceable; impossible to verify | Specific file:line + verbatim quote |
+| Quoting line N when the claim is about line M | Misdirection; the cited line doesn't actually support the claim | Quote the actual supporting line, or label as `INFERENCE` |
+| Citing a non-existent line | Pure fabrication | Verify the line exists before citing |
+
+### Pre-send check (Contract 5)
+
+송신 직전 자기 draft 점검. 하나라도 실패하면 draft `BLOCKED`.
+
+1. 모든 구체적 사실 주장에 verbatim quote 포함?
+2. 모든 verbatim quote 에 `<path>:<line>` 위치 표기?
+3. 인용된 텍스트가 실제로 그 file:line 에 존재? (grep 으로 검증 가능)
+4. 인용된 텍스트가 실제로 주장의 근거? (탄젠셜한 라인 인용 금지)
+5. 절대 경로 (`/home/...`) 가 아닌 워크스페이스 상대 경로?
+6. 외부 디렉토리 참조 시 §0 Source roots 블록에 절대 경로 명시?
+
+근거 부족 주장은 제거 또는 `INFERENCE` 라벨링.
+
+## Contract 6 — Self-Grep Verification
+
+The agent must **actually execute** a grep/sed command for every verbatim quote before sending. Pasting a quote inside backticks is not citation — running the command and observing a non-empty match is citation. Contract 5 defines the format; Contract 6 enforces the truth.
+
+### Why this contract exists
+
+Past failure: the agent learned that the format requires `<verbatim quote>` blocks, so it wrote text in quote format. But it did not actually copy from source — it paraphrased, fabricated, or cited the wrong line. Format compliance gave false confidence. Out of 7 spot-checked quotes from a single audit, 4 were either paraphrased, at a wrong line, or did not exist in the source at all.
+
+The fix is mechanical: before sending, the agent runs a verification command against each citation. If the command returns zero matches, the citation is fabrication and the finding is `BLOCKED`.
+
+### Verification procedure
+
+For every finding that includes a verbatim quote + `<path>:<line>` reference, the agent runs **one** of the following Bash commands and observes the output:
+
+```bash
+# Option A — verify quote exists at the cited line (preferred):
+sed -n '<LINE>p' '<absolute path to source>'
+# Output must contain the verbatim quote text.
+
+# Option B — verify quote exists anywhere in the source:
+grep -nF -- '<verbatim quote text>' '<absolute path to source>'
+# Output must show at least one matching line. If the line number differs, update the citation.
+
+# Option C — multi-line range verification:
+sed -n '<START>,<END>p' '<absolute path to source>'
+```
+
+Notes:
+
+- Quotes inside `grep -F` should be exact bytes from the agent's draft (no markdown backticks, no smart-quote conversion). Use single quotes around the pattern argument.
+- For Korean or non-ASCII text, ensure UTF-8 encoding.
+- For quotes containing single quotes inside, escape: `grep -nF -- "<pattern with 'inner quotes'>" '<file>'`.
+
+### Disposition matrix
+
+| sed/grep output | Disposition |
+|---|---|
+| Output contains the verbatim quote at the cited line | ✓ Citation passes. Keep finding. |
+| Output exists but at a different line (line drift) | ✗ Update `<path>:<line>` to actual matching line, keep finding. |
+| Output is empty (zero matches anywhere in the file) | ✗ Citation is fabrication. Finding `BLOCKED`. Rewrite quote to match file, re-verify. Paraphrases forbidden. |
+| Output exists but the quote is a paraphrase (close but not byte-for-byte) | ✗ Replace with actual file bytes, re-verify. |
+
+### Pre-send check (Contract 6)
+
+송신 직전 자기 draft 점검. 하나라도 실패하면 draft `BLOCKED`.
+
+1. 모든 verbatim quote 에 대해 실제로 `sed` 또는 `grep -F` 명령 실행 (Bash tool 호출에서 명시적으로 확인 가능)?
+2. 각 명령 출력이 cited line 에서 quote 와 일치? 불일치 시 finding 폐기 또는 line 정정?
+3. 정정 시 §3 Coverage Reconciliation 에 "라인 정정: X → Y" 기록?
+4. 남은 모든 verbatim quote 가 self-grep 통과 상태? 미통과 finding 이 §4 / §5 어디에도 안 남음?
+5. Verdict 산식의 `G` (self-grep 통과 finding 수) = `T` (전체 finding 수)? 불일치 시 `PARTIAL` 또는 `BLOCKED`.
+
+송신 시 "검증 완료" 같은 표현 금지 — §7 Verification 또는 §3 Coverage 에 실제로 실행한 grep 명령 중 대표 사례 1~3개를 결과와 함께 기록 (예: `grep -nF '<wiki>/feature-X.md' '<quote>'` → `116: ...`). 이것이 self-grep 을 했다는 유일한 증거.
+
+### Sampling honesty
+
+The agent is allowed to sample a subset of quotes, but §7.1 statistics MUST reflect what was actually verified:
+
+- `V` (검증한 quote 수) = **exact count of sed/grep commands written in §7.1**. Not "I ran more, I just didn't write them all." If the command isn't in §7.1, it isn't counted.
+- `P` (통과 수) ≤ `V`. Never `P > V`.
+- "통과 43" with only 2 sed commands in §7.1 is fabrication, draft `BLOCKED`.
+- Unverified quotes are reported as `U = N − V` and labeled `UNVERIFIED`. They are not "통과" and not "실패" — simply not yet tested.
+
+If the agent wants a high pass rate without writing 43 sed commands, reduce `V` by trimming quotes from §4 (i.e., trimming the report) or accept the lower verification ratio in §1.
+
+### When the agent cannot run grep
+
+If the execution environment or permissions prevent running self-grep, **all verbatim quote-based findings are `BLOCKED`**. Only findings without quotes (e.g., critique of absence) can ship, with Original goal labeled "해당 라인 없음 — 명세 자체에 누락".
+
+## Antigravity-specific 메모
+
+- Hook G1 (PreToolUse on `docs/superpowers/specs/*.md` write) 가 §7.1 에 `$ sed -n` / `$ grep -nF` 명령 존재 여부 검사. 없으면 deny.
+- **단 hook 은 형식 검사만**. 실제 sed/grep 이 실행됐는지, 출력이 진짜인지는 검증 못 한다. agent 가 위조 출력을 적어도 hook 통과 → **진실성은 agent 자체 책임**.
+- Disposition matrix 의 fabrication 케이스 ("Output is empty") 는 agent 가 의도적으로 위반하지 않는 한 self-detected. agent 가 grep 안 돌리고 fake 출력 적으면 hook 은 막지 못함.
@@ -0,0 +1,74 @@
+# diagram-standards (plugin split)
+
+Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) (379줄, v2 minimalist)
+
+본 폴더는 root rule 을 Antigravity 컨텍스트에서 lazy-load 하기 좋게 5개 sub-file 로 분할한 사본이다. 의미는 root 와 동일. 충돌 시 root 가 진실.
+
+## 핵심 원칙
+
+> **적을수록 좋다 (Less is more).**
+>
+> 컨퍼런스 발표 슬라이드 (Toss SLASH, Kakao if(dev), Naver DEVIEW) 수준 — 박스 5~8개, 화살표 5~7개, 핵심만. 정보를 다이어그램에 몰아넣으면 청중은 어디부터 봐야 할지 모르고 패닉한다.
+>
+> 본 표준은 **"포함해야 할 것"** 이 아니라 **"포함하지 말아야 할 것"** 중심이다.
+
+## 도구 분리 (필독)
+
+| 다이어그램 종류 | 도구 | 저장 위치 |
+|---|---|---|
+| **시스템 아키텍처 / 정적 구조** | **draw.io XML** (`.drawio`) | `raw/diagrams/<project-slug>/` |
+| **시퀀스 (시간축)** | **Mermaid `sequenceDiagram`** | 본문 inline |
+| **ER (데이터 모델, 선택)** | **Mermaid `erDiagram`** | 본문 inline |
+
+위반 시 자동 `BLOCKED`. Mermaid `graph TD/LR` 로 아키텍처 작성 → draw.io 로 이관 필요.
+
+## Sub-file index
+
+| Sub-file | 다루는 root section | 필독 시점 |
+|---|---|---|
+| [`principles.md`](principles.md) | §1 The Two Tests (5초·30초 룰) + §2 The Question (1 다이어그램 = 1 질문) | 다이어그램 설계 시작 직전 |
+| [`elements.md`](elements.md) | §3 Element Budget (vertex/edge/callout 상한) + §4 Component Label + §5 Edge Label + §6 Visual Hierarchy (색 / stroke / 화살표) | 박스·화살표·색 결정 시 |
+| [`structure.md`](structure.md) | §7 Boundary + §8 Callout + §9 Legend + §10 Header/Footer + §11 Source 인용 | 구조 요소 (boundary, callout, legend) 추가 시 |
+| [`mermaid.md`](mermaid.md) | §12 Mermaid Sequence + §13 Mermaid ER | Mermaid 시퀀스 / ER 다이어그램 작성 시 |
+| [`anti-patterns.md`](anti-patterns.md) | §15 Anti-patterns + §16 컨퍼런스급 사례 | 작성 후 self-review 시 |
+
+## §14 Self-check — 컨퍼런스급 (재작성, 8항만)
+
+다이어그램 작성 후 모두 ✓ 여야 발표 가능 수준.
+
+- [ ] **5초 룰** — 5초 안에 "무슨 시스템인가" + "진입점" 이해 가능?
+- [ ] **30초 룰** — 30초 발표로 흐름 + 핵심 결정 1개 전달 가능?
+- [ ] **요소 수 상한** — Vertex ≤ 10, Edge ≤ 8, Callout ≤ 1, Legend ≤ 6?
+- [ ] **단일 질문** — 다이어그램이 답하는 질문이 1개로 명확?
+- [ ] **박스 라벨 ≤ 2줄, 화살표 라벨 ≤ 5단어?**
+- [ ] **80% 회색/흑백 + 강조색 ≤ 2** ? (color salad 없음)
+- [ ] **Boundary 정보 있을 때만** (장식용 boundary 없음)?
+- [ ] **본문/캡션** 이 다이어그램을 보강 (다이어그램에 안 들어간 정보 본문에 있음)?
+
+8/8 ✓ → 컨퍼런스 발표 가능. 1개라도 미달 → 다이어그램이 너무 많은 일을 하려는 것 → 분할 또는 단순화.
+
+## §17 Quick Reference (작성 직전 빠른 체크)
+
+```
+□ 1 다이어그램 = 1 질문 (헤더에 명시)
+□ 박스 ≤ 10, 화살표 ≤ 8, callout ≤ 1, legend ≤ 6
+□ 박스 라벨 ≤ 2줄
+□ 화살표 라벨 ≤ 5단어
+□ 80% 회색/흑백, 강조색 ≤ 2개
+□ Boundary 는 정보 있을 때만
+□ 표준 컨벤션이면 legend 생략 (점선=외부, cylinder=DB)
+□ 다이어그램 외부 본문에 출처 wikilink + 디테일
+□ 5초 룰 + 30초 룰 통과
+□ 박스 / 화살표 / 색 / 라벨 모두 컨벤션 일관
+```
+
+## Antigravity-specific 메모
+
+| 항목 | 컨텍스트 |
+|---|---|
+| 도구 분리 (Mermaid `graph TD` 로 아키텍처 작성 → BLOCKED) | hook 미커버 — `.drawio` write 시 도구 검증 없음. agent self-check 단독. |
+| Element budget (Vertex ≤ 10 등) | hook 미커버. `wiki-diagram-reviewer` agent 가 dispatch 시 채점 (≥95/100 PASS). |
+| 컨퍼런스급 self-check 8항 | hook 미커버. 모든 다이어그램 작성 후 agent 자체 검증 + 사용자 리뷰. |
+| Source 인용 wikilink (§11) | hook 미커버. 다이어그램 안에 wikilink 욱여넣기 금지는 self-check 단독. |
+
+자세한 채점은 `wiki-diagram-reviewer` agent dispatch — `.agents/plugins/wiki-superpowers/agents/wiki-diagram-reviewer.md` 참조.
@@ -0,0 +1,35 @@
+# Diagram Anti-patterns + 컨퍼런스급 사례
+
+Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §15~§16
+parent: [`README.md`](README.md)
+
+## §15. Anti-patterns — 절대 금지
+
+| 안티패턴 | 증상 | 고치는 법 |
+|---|---|---|
+| **Kitchen sink** | 모든 정보를 다이어그램에 몰아넣음 (vertex 15+, edge 12+, callout 3+) | 분할 또는 본문으로 정보 이동 |
+| **Color salad** | 모든 박스에 색 칠함. 색이 의미를 잃음 | 80% 회색/흑백, 강조 1~2개만 |
+| **Legend bloat** | 사용된 모든 요소를 legend 에 → legend 가 다이어그램만큼 큼 | 표준 컨벤션은 legend 생략 |
+| **Component bloat** | 박스마다 5+줄 텍스트 → 청중이 박스 하나 읽는 데 5초+ | 박스 2줄, 나머지는 본문 |
+| **Edge label bloat** | 화살표마다 3줄 라벨 (QPS / latency / payload / step) | 1줄 5단어 이내 |
+| **Callout salad** | 3+ callout 박스 → 어느 게 중요한지 모름 | 1개 (가장 중요한 함정만), 나머지 본문으로 |
+| **Boundary nesting** | 3+ 중첩 boundary | 1~2 단계로 평면화 |
+| **Numbered everywhere** | 모든 화살표에 번호 (필요 없는데도) | 순서가 중요할 때만 번호 |
+| **Required-by-rule additions** | "표준이 시킨다고" 모든 칸 채움 → 필요 없는 정보 포함 | 표준의 목적은 *정보 전달*, 칸 채우기 X |
+| **Scale annotation everywhere** | 모든 화살표에 QPS·latency | 다이어그램의 질문이 *성능* 일 때만 |
+| **Mermaid `graph TD` 로 아키텍처** | 도구 선택 위반 | draw.io 사용 |
+| **draw.io 로 시퀀스** | 도구 선택 위반 | Mermaid `sequenceDiagram` |
+| **다이어그램이 본문 역할까지** | 다이어그램 안에 wikilink, 설명, 출처 다 들어감 | 다이어그램 = 시각 요약. 디테일·출처 = 본문 |
+
+## §16. 컨퍼런스급 사례 (참고)
+
+좋은 다이어그램의 공통점 (Toss SLASH / Kakao if(dev) / Naver DEVIEW 슬라이드 분석):
+
+- 박스 5~8개 (10 초과 드묾)
+- 박스 안 텍스트 1~2줄 (대부분 1줄)
+- 화살표 라벨 1~5단어
+- 색 2~3가지 (대부분 무채색 + 강조 1)
+- Legend 종종 없음 (관례면 충분)
+- **본문 / 발표자 설명이 다이어그램을 보강**
+
+다이어그램은 발표자의 보조 도구 — 발표자의 입을 대체하지 않는다.
@@ -0,0 +1,95 @@
+# Diagram Elements — Budget + Component / Edge Labels + Visual Hierarchy
+
+Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §3~§6
+parent: [`README.md`](README.md)
+
+## §3. Element Budget — 요소 수 상한 (HARD LIMITS)
+
+| 요소 | 권장 | 상한 | 초과 시 |
+|---|---|---|---|
+| **Vertex (박스)** | 5~7개 | **10개** | 분할 또는 비핵심 제거 |
+| **Edge (화살표)** | 4~6개 | **8개** | 시퀀스 다이어그램으로 분리 |
+| **Callout (주석 박스)** | 0~1개 | **1개** | 본문 텍스트로 옮김 |
+| **Boundary group** | 1~2개 | **3개** | 중첩 단계 축소 |
+| **Legend 항목** | 3~4개 | **6개** | 표준 컨벤션 사용 (legend 생략) |
+| **색상** | 2~3 가지 (회색/흑백 + 강조 1) | **4 가지** | 색 분류 축소 |
+
+상한을 초과하면 다이어그램이 잘못된 단위에 있다. 분할 또는 추상화 레벨 올리기.
+
+## §4. Component Label — 박스 안 텍스트 ≤ 2줄
+
+```
+┌─────────────────────────┐
+│  <Name>                 │  ← 1줄: 시스템 이름 (Bold)
+│  <Context 1줄>          │  ← 1줄: 역할 OR 기술. 둘 중 핵심만.
+└─────────────────────────┘
+```
+
+### 예시
+
+| Bad (v2 이전 스타일) | Good |
+|---|---|
+| `Spring Boot Resource Server`<br/>`Role: JWT 검증 + 비즈니스 API`<br/>`Stack: Spring Boot 3.4 / Java 21`<br/>`+ Spring Security 6.x`<br/>`Endpoint: localhost:8080`<br/>`Capacity: 1 instance`<br/>`Owner: 본인` (7줄) | `**Spring Boot RS**`<br/>`Spring Boot 3.4 · :8080` (2줄) |
+
+### 다이어그램에 안 들어가는 정보는 본문에
+
+- 컴포넌트 상세 (역할, 책임, owner, capacity) → project-note 의 §"컴포넌트 책임 분담" 표
+- 의존성 매트릭스 → 별도 §"외부 의존성" 표
+- 운영 SLO → 별도 §"비기능 요구사항"
+
+## §5. Edge Label — 화살표 라벨 ≤ 5단어
+
+```
+<step?> <verb/protocol> <object>
+```
+
+### 예시
+
+| Bad (v2 이전 스타일) | Good |
+|---|---|
+| `① HTTPS GET / (HTML/JS)`<br/>`   payload: ~50KB (initial SPA bundle)`<br/>`   p99: ~80ms (cold) / ~10ms (cache)` (3줄) | `① GET /` (1줄) |
+| `⑥ proxy_pass http://localhost:8080`<br/>`   Authorization header forward`<br/>`   (timeout: 30s, keepalive: 60s)` | `proxy_pass :8080` |
+
+### 스케일 어노테이션 (QPS, latency, payload size) — 다이어그램의 질문이 *그것* 일 때만
+
+- 일반 아키텍처 다이어그램: 화살표는 prototype + endpoint 만
+- 성능 다이어그램: QPS / latency 가 핵심 → 그 때만 라벨에
+
+번호 (①②③) 는 **순서가 중요할 때만**. 정적 토폴로지 다이어그램은 번호 불필요.
+
+## §6. Visual Hierarchy Through Restraint — 색은 강조용
+
+### 색 사용 비율
+
+- **80% 회색/흑백** — 본문 박스의 기본 fill / stroke
+- **15% 강조색 1개** — 다이어그램의 critical path 또는 primary system
+- **5% 위험 / 경고색 (빨강)** — error path, SPoF, 보안 위협 — 있을 때만
+
+### 표준 팔레트 (Minimal)
+
+| 용도 | Fill | Stroke | 비고 |
+|---|---|---|---|
+| 일반 컴포넌트 (기본) | `#FFFFFF` | `#57606A` (회색) | 80% 의 박스가 여기 |
+| **Critical path / 주인공** | `#FFFFFF` 또는 옅은 강조색 | **굵은 강조색** (`#1F6FEB` 파랑 또는 `#FB923C` 주황) | 다이어그램에서 가장 중요한 1~2개 박스만 |
+| Data store (DB) | `#FFFFFF` | `#57606A` + cylinder shape | 모양으로 구분 |
+| **External (점선)** | `#F6F8FA` | `#D0D7DE` (회색 점선) | 외부 시스템·3rd party |
+| **Warning / Error path** | `#FEF2F2` (옅은 빨강) | `#DC2626` (빨강) | 있을 때만, 1~2 요소 한정 |
+
+**금지**: 모든 박스에 색 칠하기. 색이 의미를 잃음 (color salad).
+
+### Stroke 굵기
+
+- 일반: 1~1.5px
+- Critical path / Primary: 2~3px (강조용)
+- Boundary: 1.5~2px
+
+### 화살표 종류
+
+| 종류 | 의미 |
+|---|---|
+| 실선 + 화살촉 | 동기 호출 (HTTP, RPC, JDBC) |
+| 점선 + 화살촉 | 비동기 / fire-and-forget (Kafka publish, async event) |
+| 굵은 실선 (2~3px, 강조색) | Critical path / hot path |
+| 빨간 점선 | Error path |
+
+화살표 종류는 **다이어그램 내 일관성** 이 핵심. 4종류 이상 섞지 말 것.
@@ -0,0 +1,49 @@
+# Mermaid — Sequence + ER
+
+Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §12~§13
+parent: [`README.md`](README.md)
+
+## §12. Mermaid Sequence — Minimal
+
+- **메시지 ≤ 8개** (초과 시 분할)
+- **`autonumber` 활성화**
+- **에러 경로 1개** (alt/else)
+- **트랜잭션 경계 1개** (Note over, 있을 때만)
+- **지연·QPS 어노테이션 금지** (시퀀스의 질문이 *성능* 일 때만)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant FE
+    participant API
+    participant DB
+
+    User->>FE: 로그인
+    FE->>API: POST /login
+    API->>DB: SELECT user
+    DB-->>API: row
+    alt 자격 증명 유효
+        API-->>FE: 200 + token
+    else 자격 증명 무효
+        API-->>FE: 401
+    end
+```
+
+이게 끝. `Note over` 도 비자명한 동작 1개에만.
+
+## §13. Mermaid ER — Minimal
+
+- **엔터티 ≤ 8개** (over-engineering 안 함)
+- **PK / FK 표시 필수**
+- **컬럼 ≤ 4개 per 엔터티** (모든 컬럼 X)
+- **카디널리티 정확** (`||--o{` 1:N, `}o--o{` M:N)
+- **관계 라벨 동사**
+
+전체 스키마는 별도 ERD 도구 (DBeaver, dbdiagram.io) 로. project-note 의 ER 은 **핵심 엔터티 + 관계** 만.
+
+## 도구 분리 reminder
+
+- **시스템 아키텍처 (정적 구조)** → draw.io **만** 사용. Mermaid `graph TD / LR` 로 아키텍처 작성 시 자동 `BLOCKED`.
+- **시퀀스 (시간축)** → Mermaid `sequenceDiagram`. draw.io 로 시퀀스 작성 시 자동 `BLOCKED`.
+- **ER (선택)** → Mermaid `erDiagram` 또는 별도 도구.
@@ -0,0 +1,51 @@
+# Diagram Principles — The Two Tests + The Question
+
+Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §1~§2
+parent: [`README.md`](README.md)
+
+## §1. The Two Tests — 5초·30초 룰
+
+다이어그램 1장은 두 시간 기준을 통과해야 한다.
+
+### 5초 룰
+
+청중이 슬라이드를 본 지 **5초 안에** 다음을 이해해야 한다:
+- **이게 무슨 시스템인가** (제목 + 시각적 게슈탈트)
+- **어디부터 봐야 하나** (진입점)
+
+5초 안에 위 두 가지를 답할 수 없으면 다이어그램이 너무 복잡한 것이다.
+
+### 30초 룰
+
+발표자가 다이어그램을 설명하는 30초 동안 청중이:
+- **데이터 흐름 + 핵심 결정 1개** 를 이해해야 한다
+
+30초가 부족하면 다이어그램에 정보가 너무 많은 것. 분할 또는 단순화.
+
+### 실패 신호
+
+- 청중이 다이어그램 자체를 읽느라 발표자 설명을 못 들음 → 정보 과잉
+- 청중이 "어디를 봐야 하나요?" 질문 → 진입점 불명확
+- 청중이 5초 안에 색·박스·화살표 의미를 추측해야 함 → 컨벤션 위반
+
+## §2. The Question — 1 다이어그램 = 1 질문
+
+모든 다이어그램은 **하나의 질문에만 답한다.**
+
+### 좋은 질문 (구체적·단일 초점)
+
+- "P3A 패턴에서 사용자 요청은 어떤 컴포넌트를 거치는가?"
+- "Outbox 패턴에서 DB와 broker 발행이 어떻게 원자적으로 분리되는가?"
+
+### 나쁜 질문
+
+- "전체 시스템 구조" — 범위 너무 큼. 다이어그램 분할 필요.
+
+**여러 질문이 있다 → 다이어그램을 분할한다.** 1 mega 다이어그램에 모든 걸 담는 건 부정직 (kitchen sink anti-pattern).
+
+다이어그램이 답하는 질문은 다이어그램 **헤더에 한 줄로 명시**한다:
+
+```
+<Title>
+<답하는 질문 1줄>  ← 이게 5초 룰의 핵심
+```
@@ -0,0 +1,92 @@
+# Diagram Structure — Boundary / Callout / Legend / Header-Footer / Source
+
+Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §7~§11
+parent: [`README.md`](README.md)
+
+## §7. Boundary — 정보 있을 때만 사용
+
+Boundary 는 **시각 장식이 아님.** 다음 중 하나일 때만 사용:
+
+- **Trust Boundary**: 인증·인가 영역 분리 (파란 실선, 옅은 파란 배경)
+- **Network Boundary**: VPC / 서브넷 / public-private (회색 점선)
+- **External**: 외부 시스템 영역 (회색 점선)
+
+### 금지
+
+- 모든 컴포넌트가 1개 boundary 안에 있음 → boundary 가 정보 0. 제거.
+- 3 단계 이상 중첩 boundary → 시각 복잡도 폭증
+- "팀 소유권" 같은 다이어그램 핵심이 아닌 분류 → 다이어그램 외부 본문 표로
+
+## §8. Callout — 1개만, 진짜 비자명한 것에만
+
+Callout 박스는 **다이어그램의 시각 요소로 표현 불가능한 핵심 1가지** 에만 사용.
+
+### 좋은 callout
+
+- 비자명한 함정 (e.g., "KC_HOSTNAME 미설정 시 JWT iss mismatch")
+- 핵심 결정의 이유 (e.g., "왜 BFF 대신 SPA-direct? — 학습 환경 단순성")
+- 보안 위협 영역 (e.g., "JWKS unknown kid → DoS 벡터")
+
+### 나쁜 callout (제거 대상)
+
+- 단순 부가 정보 (capacity, version 등) → 박스 라벨로
+- 컴포넌트 설명 → 본문 텍스트로
+- "참고로..." 식 비핵심 메모 → 본문으로
+
+**1개 이상의 callout → 다이어그램이 너무 많은 것을 말하려는 것. 분할.**
+
+## §9. Legend — 표준 컨벤션이면 생략
+
+Legend 는 **다이어그램 내 비표준 색·기호** 가 있을 때만.
+
+### 표준 컨벤션 (Legend 불필요)
+
+- 점선 = 외부 / 비동기
+- Cylinder = DB
+- Solid arrow = 동기 호출
+- Dashed arrow = 비동기 / 점선 응답
+
+### Legend 가 필요한 경우
+
+- 다이어그램 내 색이 [`elements.md`](elements.md) §6 표준 팔레트 **외** 인 경우
+- 특수 기호 사용 (예: ⚡ for circuit breaker)
+
+### Legend 작성 표준
+
+- ≤ 6 항목 (가능하면 ≤ 4)
+- 다이어그램 우하단 또는 본문 캡션
+- 표준 컨벤션 (점선=외부, cylinder=DB) 은 legend 에 안 적음
+
+## §10. Header / Footer — 미니멀
+
+### Header (다이어그램 상단)
+
+```
+<Title>
+<답하는 질문 1줄>  ← 옵션
+```
+
+`Project / branch / status` 같은 메타 정보는 **다이어그램에 안 들어감**. project-note frontmatter 와 §3 본문에 이미 있음.
+
+### Footer (다이어그램 하단)
+
+```
+v2 · 2026-05-26
+```
+
+작성자 / source wikilink / standard reference 같은 메타는 **다이어그램 외부**. project-note 의 frontmatter `diagrams:` 필드와 본문에서 참조.
+
+## §11. Source 인용 — 본문에서, 다이어그램 안 X
+
+핵심 사실의 출처 wikilink (`[[raw/official-docs/...]]`) 는 **다이어그램 옆 본문 또는 callout** 에 둔다. 화살표 라벨이나 박스 안에 wikilink 를 욱여넣지 말 것.
+
+```markdown
+![[architecture-p3a-...drawio]]
+
+> **출처**:
+> - KC_HOSTNAME 함정: [[raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch]]
+> - redirect_uri 함정: [[raw/branch-notes/feature-keycloak-docker-compose-stack]]
+> - OIDC PKCE: [[raw/official-docs/oauth2-rfc-7636-pkce]]
+```
+
+본문이 다이어그램을 보강한다. 다이어그램이 본문 역할까지 떠안지 말 것.
@@ -0,0 +1,58 @@
+# reporting-standards (plugin split)
+
+Root SSOT: [`rules/reporting-standards.md`](../../../../../rules/reporting-standards.md) (559줄)
+
+본 폴더는 root rule 을 Antigravity 컨텍스트에서 lazy-load 하기 좋게 4개 sub-file 로 분할한 사본이다. 의미는 root 와 동일. 충돌 시 root 가 진실.
+
+## 적용 대상
+
+- wiki research-lane 보고서, multi-file 문서 audit, raw → canonical 추출 권고, 링크 무결성 audit, 적대 리뷰 보고서, 멀티-파일 브레인스토밍, 1개 초과 wiki 파일을 다루는 모든 최종 응답.
+- 미적용: trivial 단일 파일 편집, 한 위치에서의 짧은 Q&A, 셸 명령 출력.
+
+## Sub-file index (필요 시점에 정독)
+
+| Sub-file | 다루는 root section | 필독 시점 |
+|---|---|---|
+| [`output-split.md`](output-split.md) | Output Split Policy | 멀티-파일 / 멀티-findings 작성 직전 |
+| [`report-template.md`](report-template.md) | §0 Source roots / §1 한눈 요약 / §2 Evidence Matrix / §3 Coverage / §3-1 Verdict 산식 / §5~§8 + Anti-Patterns | 보고서 본문 작성 직전 |
+| [`findings-template.md`](findings-template.md) | §4 Per-File Findings (deep template + single/zero-finding gates) + §4-1 Adversarial Review | per-file 분석 시 |
+| [`verification-rules.md`](verification-rules.md) | §7.1 self-grep 카운트 규칙 (V/P/C/D/G/U) + §7.2 실행 명령 + 통계 fabrication 차단 | verbatim quote 가 §4 에 있을 때 |
+
+## Language Contract (root 와 동일, 항상 적용)
+
+- 본문 산문은 사용자 언어. 한국어 사용자 → 한국어 본문. 영어 사용자 → 영어 본문.
+- 사용자 언어 무관 영어 유지: 섹션 필드명 (`Verdict`, `Evidence Matrix`, `Status` 등), Status 값 (`READ_FULL`, `READ_PARTIAL`, `NOT_READ`, `BLOCKED`), 명명된 실패 라벨 (`FACT`, `INFERENCE`, `FILENAME_INFERENCE`, `MEMORY_HALLUCINATION`, `CONFIDENCE_WITHOUT_READ`, `BATCH_ASSUMPTION`, `UNVERIFIED`), 파일 경로 / wikilink target / frontmatter 필드명.
+- bilingual mirroring 금지 — 한 본문, 한 언어.
+
+## Antigravity-specific 메모
+
+| 항목 | Antigravity 컨텍스트 |
+|---|---|
+| Hook G1 (verification-rules.md §7.1 의 형식 검사) | PreToolUse `wiki_hard_gate.py` 가 자동 enforce — `docs/superpowers/specs/*.md` write 시 §7.1 에 `$ sed -n` / `$ grep -nF` 명령이 0건이면 deny |
+| Hook G2 (Anti-Patterns + Contract 7) | 금지어 ("100%", "완벽" 등) 가 verbatim quote 밖에 있으면 deny |
+| Hook G3 (§3-1 Verdict 산식) | `Verdict: COMPLETE` 자가 라벨링 + `M==N AND P==R` 산식 부재 시 deny |
+| Hook G4 (findings-template.md §4-1 존재 검사) | ≥5 findings master report 인데 §4-1 Adversarial Review 부재 시 deny |
+| Stop hook 한계 | chat 본문 응답은 enforce 불가. specs/ 외 경로 (`raw/`, `wiki/`) 작성도 hook 미커버. agent self-check 단독. |
+
+자세한 hook 동작은 [`~/.gemini/antigravity-cli/hooks/README.md`](file:///home/donghyeon/.gemini/antigravity-cli/hooks/README.md) 참조.
+
+## Format Discipline (always)
+
+- One file = one §4 subsection. 파일 묶지 않음.
+- No "Pillar / Group / Theme" grouping in §4. 그룹화는 §2 매트릭스 위쪽이나 §5 에서만.
+- Every claim cites `<file:line>`. 단정적 사실 + `<file:line>` 근거 없으면 그 문장 삭제 또는 `INFERENCE` 라벨.
+- §5 priority table only references analyzed files.
+- No mermaid/diagram filler.
+- No bilingual mirroring.
+
+## Pre-Send Format Check (essential 7)
+
+송신 직전 다음 7개 확인. 하나라도 실패하면 draft 폐기. 전체 12 항목은 root rule §"Pre-Send Format Check" 참조.
+
+1. 본문 산문 언어가 사용자 언어와 일치?
+2. §1~§7 모두 존재 (해당 없으면 명시적 `N/A`)?
+3. §2 evidence matrix 행 수 = in-scope 파일 수? 불일치 시 §3 reconciliation 블록 있는가?
+4. §4 하위섹션 수 = §2 의 `READ_FULL` + `READ_PARTIAL` 행 수?
+5. §4 각 finding 이 verbatim quote + `<file:line>` 을 Original goal / Current state 에 포함?
+6. §5 priority 표의 모든 파일이 §4 에 하위섹션 보유?
+7. file:line 경로가 워크스페이스 상대 (또는 §0 alias) 형식? 절대 경로 `/home/...` 금지?
@@ -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`.
@@ -0,0 +1,89 @@
+# Output Split Policy
+
+Root SSOT: [`rules/reporting-standards.md`](../../../../../rules/reporting-standards.md) §"Output Split Policy"
+parent: [`README.md`](README.md)
+
+긴 보고서는 **파일에 분할 저장**, 터미널 dump 금지. 터미널은 네비게이션 레이어, 디스크는 깊이.
+
+## When to split
+
+다음 중 **하나라도 참** 이면 분할:
+
+- in-scope 파일 수 > 3
+- §4 Per-File Findings 하위섹션 수 ≥ 5
+- 전체 §1~§7 응답 추정 ~10,000자 초과
+- 사용자가 "save" / "저장" / "파일로" / "report" / "보고서" 라고 말함
+
+단일 파일 / 단순 lookup / 짧은 advisory 는 분할하지 않는다 — 전체 본문 터미널 유지.
+
+## What to save
+
+산출물 유형별 저장 경로 + CLAUDE.md §15 게이트:
+
+| 산출물 유형 | 저장 경로 | 게이트 |
+|---|---|---|
+| Multi-doc audit / research report | `docs/superpowers/specs/YYYY-MM-DD-<topic>-report.md` (+ per-file-findings) | — |
+| 신규 raw 문서 | `raw/<category>/<slug>.md` | `wiki-doc-author` 또는 `wiki-source-summarizer` agent dispatch |
+| Canonical 추출 (raw → wiki) | `wiki/concepts/<slug>.md` 또는 `wiki/projects/<project>/<topic>.md` | **`/ingest` 게이트만 허용** — agent 가 직접 `wiki/interview/` · `wiki/portfolio/` · `wiki/blog/` 에 작성 금지 |
+| Derived (interview / portfolio / blog) | `wiki/interview/[<cat>/]<slug>.md`, `wiki/portfolio/<slug>.md`, `wiki/blog/<slug>-YYYY-MM-DD.md` | **원천 canonical status ∈ {reviewed, verified, published-ready}** 필수. 미달 시 BLOCKED |
+| Adversarial review report | `docs/superpowers/specs/YYYY-MM-DD-<topic>-adversarial-review.md` | findings ≥ 5 시 권장 |
+
+메타 보고서의 경우 **두 파일**:
+
+1. **`<topic>-report.md`** (master) — §1 Executive Summary + §2 Evidence Matrix + §3 Coverage + §4 (한 줄 요약 + 링크) + §5 Priority + §6 Follow-Up + §7 Verification + §8 Artifacts
+2. **`<topic>-per-file-findings.md`** — expanded §4 (`READ_FULL` / `READ_PARTIAL` 파일당 하위섹션, deep 템플릿)
+
+Naming:
+- `YYYY-MM-DD` = 보고서 작성일
+- `<topic>` = 짧은 kebab-case slug. 예: `branch-notes-audit`, `link-integrity-audit`, `keycloak-canonical-extraction`
+- 동일 이름 존재 시 `-v2`, `-v3` 접미사. 명시적 사용자 지시 없는 덮어쓰기 금지.
+
+## Pipeline Gate Enforcement (CLAUDE.md §15)
+
+본 rule 은 다음을 hard rule 로 강제. 위반 시 draft `BLOCKED`:
+
+1. **`wiki/interview/` · `wiki/portfolio/` · `wiki/blog/` 직접 작성 금지** — 즉시 `NEEDS_CONTEXT` 반환. `/projectize` · `/interviewize` · `/blogify` 또는 수동 작성 전용.
+2. **derived 문서 작성 전 원천 canonical status 검증 강제** — `reviewed | verified | published-ready` 미만이면 BLOCKED. 응답에 `원천 <path> status: <value>` 명시 + status grep 출력 첨부.
+3. **`/ingest` 목적지는 `wiki/concepts/` 와 `wiki/projects/` 만** — 다른 wiki 하위 디렉토리 ingest 금지.
+4. **canonical 문서 Sources 필수** — `wiki/concepts/` · `wiki/projects/` 작성 시 외부 자료 (`raw/official-docs/` · `raw/company-tech-blogs/`) wikilink 1개 이상 없으면 BLOCKED.
+
+## What stays in the terminal
+
+터미널은 **네비게이션 레이어만**:
+
+```markdown
+# [작업명] 보고서 — 터미널 요약
+
+**일자:** YYYY-MM-DD
+**범위:** <N개 파일>
+**Verdict:** COMPLETE | PARTIAL | BLOCKED
+**전체 보고서:** `docs/superpowers/specs/YYYY-MM-DD-<topic>-report.md`
+**파일별 상세:** `docs/superpowers/specs/YYYY-MM-DD-<topic>-per-file-findings.md`
+
+## 1. 한눈 요약 (전체본)
+## 2. Evidence Matrix (전체본 — 행 수 많아도 매트릭스는 터미널 유지)
+## 5. 우선순위 권고 (전체본)
+## 6. 후속 작업 (전체본)
+## 7. 검증 (실행 명령 + 결과)
+```
+
+터미널에서 생략: §3 Coverage 상세, §4 Per-File Findings 본문 (요약 한 줄만), §8 Artifacts (위 frontmatter 링크로 대체).
+
+§4 본문을 터미널에 그대로 붙여넣어 출력을 부풀리지 않는다.
+
+## Link format
+
+저장 파일 경로는 워크스페이스 루트 기준 상대 경로. **절대 경로 금지**.
+
+✓ `docs/superpowers/specs/2026-05-23-branch-notes-audit-report.md`
+✗ `/home/donghyeon/Documents/LLM Wiki/docs/...`
+
+## Pre-send check (split-specific)
+
+송신 직전 다음 확인. 하나라도 실패하면 draft 폐기:
+
+1. 두 파일이 실제로 디스크에 쓰였는가? (Write 도구 실행 결과 확인)
+2. 터미널 본문에 두 파일의 상대 경로 링크 포함?
+3. 터미널 본문에 §4 Per-File Findings 상세 미포함? (요약 한 줄만 허용)
+4. 두 파일이 §1~§7 (master) / §4 expanded (per-file) 각자 자기 위치에서 완비?
+5. 두 파일 헤더 frontmatter (일자, 범위, Verdict) 서로 일치?
@@ -0,0 +1,158 @@
+# Report Template (§0~§3, §3-1 Verdict, §5~§8)
+
+Root SSOT: [`rules/reporting-standards.md`](../../../../../rules/reporting-standards.md) §"Report Template"
+parent: [`README.md`](README.md)
+
+§4 Per-File Findings + §4-1 Adversarial Review → [`findings-template.md`](findings-template.md)
+§7 Verification (self-grep 카운트 규칙) → [`verification-rules.md`](verification-rules.md)
+
+모든 covered 보고서는 본 섹션 순서를 따른다. 재정렬 / 병합 / 생략 금지. 빈 섹션은 `해당 없음 / N/A` 로 명시.
+
+## Frontmatter
+
+```markdown
+# [작업명] 보고서
+
+**일자 / Date:** YYYY-MM-DD
+**범위 / Scope:** <N개 파일 또는 영역>
+**Verdict:** COMPLETE | PARTIAL | BLOCKED
+**요청 언어 / User language:** ko | en | mixed
+```
+
+## §0. Source roots (외부 디렉토리 참조 시에만)
+
+| Alias | 절대 경로 |
+| --- | --- |
+| `<raw-branches>` | `/home/donghyeon/Documents/LLM Wiki/raw/branch-notes` |
+| `<raw-projects>` | `/home/donghyeon/Documents/LLM Wiki/raw/project-notes` |
+| `<wiki-concepts>` | `/home/donghyeon/Documents/LLM Wiki/wiki/concepts` |
+| `<wiki-projects>` | `/home/donghyeon/Documents/LLM Wiki/wiki/projects` |
+| `<ca-tmpl>` | `/home/donghyeon/workspace/ca-tmpl` (코드 컨텍스트 참조 시) |
+
+이후 인용 예: `<raw-branches>/feature-X.md:42`. 워크스페이스 안만 다루면 "해당 없음 / N/A".
+
+## §1. 한눈 요약 / Executive Summary
+
+3~6 문장. 무엇을 했는가 / 정독 파일 수 vs 전체 in-scope / 가장 중요한 발견 1~2 / 후속 조치 필요 항목 수.
+
+## §2. Evidence Matrix
+
+### Evidence Matrix Hard Format
+
+Rows must be mechanically countable by the hook. Use exactly:
+
+```text
+| Path | Status | Evidence | Extracted facts |
+| --- | --- | --- | --- |
+| raw/branch-notes/<file>.md | READ_FULL | lines x-y | <fact> |
+```
+
+Do not use filename-only paths (`feature-x.md`), `Status=raw`, or `READ_FULL=Yes`. Allowed status values are exactly `READ_FULL`, `READ_PARTIAL`, `NOT_READ`, `BLOCKED`.
+
+
+모든 in-scope 파일에 정확히 한 행. 누락 금지.
+
+| Path | Status | Evidence | Extracted facts |
+| --- | --- | --- | --- |
+| <path> | READ_FULL | <line range> | <facts in user language> |
+| <path> | NOT_READ | <reason> | UNVERIFIED |
+
+allowed Status: `READ_FULL`, `READ_PARTIAL`, `NOT_READ`, `BLOCKED`.
+
+## §3. 커버리지 정합성 / Coverage Reconciliation
+
+본 섹션은 자기 신고 아닌 **산식 영역**.
+
+| 항목 | 값 |
+| --- | --- |
+| (a) in-scope 파일 수 | <N> |
+| (b) §2 evidence matrix 총 행 수 | <M> |
+| (c) §2 의 `READ_FULL` + `READ_PARTIAL` 행 수 | <R> |
+| (d) §4 deep-template 충족 하위섹션 수 | <P> |
+| (e) (a − b) — 매트릭스 누락 | <a-b> |
+| (f) **(c − d) — 분석 깊이 미달** | **<c-d>** |
+
+### 분석 깊이 미달 파일 명세
+
+`(c − d) > 0` 이면 누락 파일 빠짐없이 나열. "없음" 적었으나 누락 있으면 자동 `BLOCKED`.
+
+| 파일 경로 | §2 Status | §4 분석 여부 | 누락 사유 |
+| --- | --- | --- | --- |
+
+(비어 있으면 명시: "분석 깊이 미달 없음 — (c − d) = 0".)
+
+### `NOT_READ` / `BLOCKED` 파일
+
+- `NOT_READ` 목록: <list 또는 "없음">
+- `BLOCKED` 목록 (사유): <list 또는 "없음">
+
+### 정직성 컨트랙트
+
+- 모든 사실 주장은 §2 매트릭스의 `READ_FULL` / `READ_PARTIAL` 행에서 나옴
+- §4 미다룸 파일은 §5 등장 불가
+- 매트릭스 vs §4 행 수 불일치 시 §5 에 §4 없는 파일 올리면 자동 `BLOCKED`
+
+## §3-1. Verdict 결정 알고리즘 / Verdict Calculation
+
+**산식이 라벨을 결정**. agent 가 자기 의지로 라벨링 X. 산식과 라벨 불일치 시 송신 불가.
+
+```text
+Let:
+  N = in-scope 파일 수
+  M = §2 evidence matrix 총 행 수
+  R = §2 의 READ_FULL + READ_PARTIAL 행 수
+  P = §4 deep-template 충족 하위섹션 수
+  G = self-grep 검증 (verification-rules.md) 통과 finding 수
+  T = 전체 finding 수
+
+Verdict =
+  COMPLETE  iff (M == N) AND (P == R) AND (G == T) AND (모든 §5 권고가 §4 파일을 가리킴)
+  PARTIAL   iff (M == N) AND ((P < R) OR (G < T))
+  BLOCKED   iff (M < N) OR (enumeration 불가) OR (필수 first reads 차단)
+```
+
+`COMPLETE` 적으려면 4개 조건 **전부 참**. 하나라도 거짓 → 자동 `PARTIAL` 또는 `BLOCKED`.
+
+Pre-send 시 §3 (a)~(f) 값을 실제 계산 → 산식 평가 → Verdict 라벨 채움. 산식 위반은 정직성 실패, draft 폐기.
+
+## §4 + §4-1
+
+→ [`findings-template.md`](findings-template.md) 별도 sub-file. Per-File Findings deep template + Single-finding gate + Zero-finding handling + Adversarial Review.
+
+## §5. 우선순위 권고 / Priority Recommendations
+
+| 우선순위 | 권고 액션 | 근거 파일:라인 | 원래 목표 | 현재 간극 | 조치 후 효과 |
+| --- | --- | --- | --- | --- | --- |
+| 1 (Critical) | ... | `<file:line>` | ... | ... | ... |
+| 2 (High) | ... | `<file:line>` | ... | ... | ... |
+
+각 행은 §4 의 한 Finding 과 **1:1 대응**. 단순화 / 축약 / 일반화 금지. 본 표 모든 파일은 §4 에 자기 하위섹션 보유 필수. §4 에 없는 파일을 본 표에 올리면 자동 `BLOCKED`.
+
+## §6. 후속 작업 / Follow-Up
+
+- 다음 라운드 정독 대상 파일
+- 미해결 위험
+- 추가 검증 필요한 가설
+- Out of scope: <slice 가 다루지 못한 인접 영역>
+
+## §7. 검증 / Verification
+
+→ [`verification-rules.md`](verification-rules.md) — §7.1 self-grep proof + §7.2 실행 명령 + 카운트 규칙.
+
+## §8. Generated Artifacts (분할 시에만)
+
+- 전체 보고서: `docs/superpowers/specs/YYYY-MM-DD-<topic>-report.md`
+- 파일별 상세: `docs/superpowers/specs/YYYY-MM-DD-<topic>-per-file-findings.md`
+- 작성 일자: YYYY-MM-DD
+- 작성 도구: Antigravity CLI / wiki-superpowers plugin
+
+## Anti-Patterns to Avoid
+
+| Pattern | Why fails | Replacement |
+| --- | --- | --- |
+| "Pillar A: 4 files" 묶음 비평 | 4개 중 어느 파일 어디서 나온 사실인지 추적 불가 | 파일당 §4 하위섹션 1개 |
+| GitHub `[!WARNING]` admonition만 | 출처 사라짐. 인용 라인 없음 | `<file:line>` 인용 + 한 줄 발췌 |
+| 영어 보고서 + 한국어 대화 | 사용자가 번역 강요됨 | 사용자 언어로 통일 |
+| Executive summary 없이 본론 | 핵심을 끝까지 읽어야 알 수 있음 | §1 3~6 문장 |
+| 우선순위 표에 정독 안 한 파일 | 추측을 권고로 둔갑 | §4 에 있는 파일만 §5 |
+| Verdict 없이 발견만 나열 | 통과/실패 판단 불가 | 상단 frontmatter Verdict 명시 |
@@ -0,0 +1,116 @@
+# §7 Verification Rules
+
+Root SSOT: [`rules/reporting-standards.md`](../../../../../rules/reporting-standards.md) §"7. 검증 / Verification"
+parent: [`README.md`](README.md)
+관련: [`../advisory-depth/contracts-5-6-citation-grep.md`](../advisory-depth/contracts-5-6-citation-grep.md) Contract 6 Self-Grep Verification
+
+## §7.1 Self-grep proof (MANDATORY when §4 contains verbatim quotes)
+
+송신 전에 실행한 grep/sed 명령과 관측 결과를 기록한다. **이것이 인용을 검증했다는 유일한 증거**.
+
+### 카운트 규칙 (엄격)
+
+`V`, `P`, `C`, `D`, `G` 값은 **§7.1 에 sed/grep 명령이 실제로 적힌 quote 만** 카운트. 명령이 없는 quote 는 자동 `미검증 (UNVERIFIED)`. 통계 일반화 금지.
+
+- `V` = §7.1 에 sed/grep 명령이 적힌 quote 수 (= 명령 블록 행 수)
+- `P` = 그중 출력이 quote 와 일치한 수
+- `C` = 그중 라인 정정이 필요했던 수
+- `D` = 그중 폐기된 finding 수
+- `G` = `P` ([`report-template.md`](report-template.md) §3-1 Verdict 산식 입력)
+- `U` = 미검증 quote 수 = (§4 전체 quote 수) − `V`
+
+§4 에 quote N개 있고 §7.1 에 sed 명령 K개 적었다면 `V = K`, `U = N − K`. **"통과 N" 이라 적으면 자동 `BLOCKED`** — `K` 외 quote 는 미검증이지 통과 아님.
+
+```bash
+# 검증한 모든 sed/grep 명령을 인라인으로 나열한다.
+sed -n '<line>p' '<absolute path>'
+# Observed: <actual output>
+
+sed -n '<line>p' '<absolute path>'
+# Observed: <actual output>
+
+grep -nF -- '<verbatim quote>' '<absolute path>'
+# Observed: <line>:<actual output>
+```
+
+### Sampling 권장량
+
+V 가 N 보다 작아도 괜찮다. 다만 V 가 작을수록 보고서 신뢰도 낮음. §1 Executive Summary 와 §3-1 Verdict 결정에 반영.
+
+- **V == N** (전부 검증) → `G = P`, Verdict 산식 그대로 반영
+- **V ≥ max(10, N×0.3)** (최소 10개 또는 30% 중 큰 값) → §1 에 "표본 검증" 명시, Verdict 자동 `PARTIAL` 강등
+- **V < max(10, N×0.3)** → Verdict `BLOCKED` (검증 표본 너무 작아 신뢰 불가)
+
+### 통계 정직성 블록 (필수 출력)
+
+§7.1 끝에 다음을 항상 적는다:
+
+- 검증한 verbatim quote 총 개수 `V`: <실제 §7.1 에 명령이 적힌 수>
+- 일치 (통과) `P`: <그중 출력 일치한 수>
+- 불일치로 finding 폐기 `D`: <그중 폐기된 수>
+- 라인 정정 `C`: <그중 라인 정정한 수>
+- §3-1 Verdict 산식의 `G` 값 (= P): <G>
+- **미검증 quote 수 `U` (= §4 전체 quote 수 − V)**: <U>
+- §4 전체 quote 수 `N`: <N>
+- 검증 비율 `V/N`: <백분율>
+
+`V = N` 아니면 §1 Executive Summary 에 `"표본 검증: V/N quote 검증 완료, 미검증 U개는 사용자가 직접 grep 확인 권장"` 명시. **"전수 검증" 같은 표현 금지**.
+
+### 통계 fabrication 차단
+
+다음은 모두 정직성 위반으로 자동 `BLOCKED`:
+
+- §7.1 에 sed/grep 명령 0건인데 `V > 0` 또는 `검증률 100%` 주장
+- "검증 비율 100%" 또는 "전수 검증" 표현 사용 (Contract 7 금지어 + 절대성 주장)
+- §4 에 quote 10개인데 §7.1 에 명령 3개만 적고 "통과 10" 으로 적힘
+- §7.1 의 sed 출력이 실제 source 파일 본문과 byte-for-byte 일치 안 함 (해당 finding 폐기 필수)
+- §7.1 의 grep 결과 line number 가 §4 finding 의 인용 위치와 다름 (라인 정정 필수)
+
+## §7.2 실행한 검증 명령
+
+본 섹션은 wiki 작업에 적용되는 자동 검증 명령을 기록. **코드 빌드 명령 (Gradle / npm 등) 금지** — 그건 ca-tmpl 영역. wiki 보고서에 빌드 명령 등장 시 자동 `BLOCKED`.
+
+- 실행한 명령:
+  - `<command>` → <결과>
+
+대표적인 wiki 검증 명령:
+
+```bash
+# Frontmatter 필수 필드 카운트
+grep -cE '^(title|source_type|status|tags|created):' '<file>'
+
+# Parent 섹션 확인
+grep -c '^## Parent' '<file>'
+
+# 본문 wikilink 추출 후 존재 확인
+grep -oE '\[\[[^]]+\]\]' '<file>' | sort -u
+ls 'raw/...' 'wiki/...'
+
+# Tag taxonomy 위반 검사
+grep -h '^tags:' raw/**/*.md wiki/**/*.md | grep -oE '\[.*\]' | tr ',' '\n' | sort -u
+```
+
+- 실행하지 못한 명령과 이유:
+  - <command> — <reason>
+- 본 응답에서 새로 작성된 wiki 파일 수: <N> / 수정된 파일 수: <M>
+
+## Hook enforcement 메모 (Antigravity-specific)
+
+본 워크스페이스의 PreToolUse hook (`~/.gemini/antigravity-cli/hooks/wiki_hard_gate.py`) 의 G1 check 가 §7.1 형식을 검사:
+
+- 응답에 `V/N` 비율 또는 "self-grep proof" 문구가 있는데
+- §7.1 에 `$ sed -n` 또는 `$ grep -nF` 명령 라인이 0개
+
+→ hook `decision: deny` 반환.
+
+**단 hook 은 형식만 검사**한다. sed/grep 의 실제 실행 진실성은 검증 못 한다. agent 가 위조 출력을 적어도 hook 통과. 진실성은 agent 자체 책임 — [`../advisory-depth/contracts-5-6-citation-grep.md`](../advisory-depth/contracts-5-6-citation-grep.md) Contract 6 참조.
+
+
+## Hard Gate Addendum — Real Output Only
+
+The hook rejects reconstructed verification. In particular:
+
+- Plain `sed -n '74,78p' file` output must not be shown with `74:` line prefixes. Use `grep -nF` or `nl -ba file | sed -n` if line numbers are required.
+- `sed-proofs.md` must not claim `100%`, `전수 검증`, or `fully verified` unless every finding has a command row and the command output is pasted.
+- Controller verification must count actual command rows, not prose claims.
+- A finding whose quote proves a different topic is `EVIDENCE_FINDING_MISMATCH` and cannot be counted as verified.