donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
DongHyeonka
2026-07-29 18:05:17 +09:00
parent cfd84875bf
commit 58515ab0f3
251 changed files with 31470 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/plugins/wiki-superpowers/rules/advisory-depth/README.md
+62
View 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 == 실제 명령 수` 일치?
.agents/plugins/wiki-superpowers/rules/advisory-depth/contract-7-forbidden-words.md
+91
View File
@@ -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 단독.
.agents/plugins/wiki-superpowers/rules/advisory-depth/contracts-1-causal-chain.md
+93
View File
@@ -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` 라벨.
.agents/plugins/wiki-superpowers/rules/advisory-depth/contracts-2-3-4-structure.md
+107
View File
@@ -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 로 자동 폐기.
.agents/plugins/wiki-superpowers/rules/advisory-depth/contracts-5-6-citation-grep.md
+128
View File
@@ -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 은 막지 못함.