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

fix: 하네스 제거 및 keycloak 문서 보강

Browse Source
This commit is contained in:
DongHyeonka
2026-07-25 12:53:13 +09:00
parent 6c53ded9cb
commit d71669eb59
2329 changed files with 138239 additions and 172816 deletions
Download Patch File Download Diff File Expand all files Collapse all files
rules/reporting-standards.md
-1
View File
@@ -1 +0,0 @@
../vault/00-system/rules/reporting-standards.md
rules/reporting-standards.md
+564
View File
@@ -0,0 +1,564 @@
# Reporting Standards Rule
This rule defines the **language and format contract** for every multi-file, audit, review, brainstorming, research, or evaluation report the agent produces in this workspace.
It applies to: wiki research-lane reports, multi-file document audits, raw → canonical extraction recommendations, link integrity audit reports, adversarial review reports, brainstorming summaries on documents, and any final response that touches more than one wiki file.
It does **not** apply to: trivial single-file edits, short Q&A on one location, or shell command outputs.
**Scope note:** 본 rule은 LLM Wiki 문서 작업의 보고서에 적용된다. 코드(Java/Clean Architecture) 작업의 보고서는 ca-tmpl `.agents/plugins/ca-superpowers/rules/reporting-standards.md` 를 따른다 — 본 rule과 90% 동일하지만 §0 alias, §4 Automated 검증, §7.2 빌드 명령이 코드 컨텍스트로 채워져 있다.
## Language Contract
The agent writes report prose in the **same language the user used in the current task**.
- If the user wrote the task in Korean, the report body is Korean.
- If the user wrote in English, the report body is English.
- If the user mixed languages, match the dominant language. If unclear, ask before writing.
**Always English regardless of user language:**
- Section field names in the template below (`Verdict`, `Evidence Matrix`, `Status`, etc.).
- Status values (`READ_FULL`, `READ_PARTIAL`, `NOT_READ`, `BLOCKED`).
- Named failure labels (`FACT`, `INFERENCE`, `FILENAME_INFERENCE`, `MEMORY_HALLUCINATION`, `CONFIDENCE_WITHOUT_READ`, `BATCH_ASSUMPTION`, `UNVERIFIED`).
- File paths and identifiers (`raw/branch-notes/<slug>.md`, `wiki/concepts/<slug>.md`, wikilink targets `[[...]]`, frontmatter field names).
The agent does **not** write the analysis body in one language and a parallel summary in another. One body, one language, the user's language.
If the agent finds itself writing the report in English when the user wrote in Korean (or vice versa), it stops, deletes the draft, and rewrites in the correct language. This is a hard rule, not a preference.
## Output Split Policy
Long reports must be **split across files**, not dumped into the terminal. The terminal carries the navigation layer; the disk carries the depth.
### When to split
The agent splits the response into disk artifacts + terminal summary whenever **any one** of the following is true:
- Report touches **more than 3 in-scope files** (per the user's stated scope or the evidence matrix).
- §4 Per-File Findings would contain **5 or more subsections**.
- The full §1~§7 response would exceed approximately **10,000 characters** (rough threshold; the agent estimates before sending).
- The user said "save", "저장", "파일로", "report", "보고서" with respect to a multi-file or multi-finding task.
For one-off single-file questions, trivial lookups, or short advisory answers, **do not split** — the full content stays in the terminal.
### What to save
산출물 유형별로 저장 경로가 다르다. **메타 보고서**(작업 자체에 대한 audit/research report)는 `docs/superpowers/specs/` 에, **wiki 산출물**(canonical 문서, derived 문서)은 `wiki/` 하위에 저장된다. CLAUDE.md §15 파이프라인 게이트가 강제됨:
| 산출물 유형 | 저장 경로 | 게이트 (rule이 강제) |
| --- | --- | --- |
| Multi-doc audit / research report (예: `branch-notes-audit`, `link-integrity-audit`) | `docs/superpowers/specs/YYYY-MM-DD-<topic>-report.md` (+ per-file-findings) | — |
| 신규 raw 문서 (URL 요약, branch-note 등) | `raw/<category>/<slug>.md` | `wiki-doc-author` 또는 `wiki-source-summarizer` agent dispatch |
| Canonical 추출 (raw → wiki/concepts 또는 raw → wiki/projects) | `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. **`docs/superpowers/specs/YYYY-MM-DD-<topic>-report.md`** — the master report.
- Contains §1 Executive Summary, §2 Evidence Matrix, §3 Coverage Reconciliation, §4 (one-line per-file summary with link to file 2), §5 Priority Recommendations, §6 Follow-Up, §7 Verification, §8 Generated Artifacts.
- This is the document anyone should be able to read top-to-bottom to understand the audit.
2. **`docs/superpowers/specs/YYYY-MM-DD-<topic>-per-file-findings.md`** — full per-file depth.
- Contains expanded §4 with one subsection per `READ_FULL` / `READ_PARTIAL` file.
- Each subsection follows the deep Per-File Finding template (Goal / Current / Gap / Action / Why / Alternatives / Implementation Steps / Verification Approach / Related).
- Multiple findings per file when the analysis surfaces multiple gaps. Do not artificially limit to one finding per file.
Naming rules:
- `YYYY-MM-DD` is today's date (the day the report is produced).
- `<topic>` is a short kebab-case slug. Examples: `branch-notes-audit`, `link-integrity-audit`, `keycloak-patterns-canonical-extraction`, `wiki-concepts-promotion-review`.
- If a file with the same name already exists, append `-v2`, `-v3`, etc. — never overwrite a prior report without an explicit user instruction.
### Pipeline Gate Enforcement (CLAUDE.md §15)
본 rule은 다음을 hard rule 로 강제한다. 위반 시 draft `BLOCKED`:
1. **`wiki/interview/`, `wiki/portfolio/`, `wiki/blog/` 에 직접 작성 금지** — agent가 이 경로에 새 파일을 쓰려 하면 즉시 멈추고 `NEEDS_CONTEXT` 반환. 이 경로는 `/projectize`, `/interviewize`, `/blogify` 슬래시 커맨드 또는 수동 작성 전용.
2. **derived 문서 작성 전 원천 canonical 문서의 status 확인 강제** — 원천 status가 `reviewed | verified | published-ready` 미만이면 BLOCKED. agent는 응답에 `원천 <canonical-path> status: <value>` 명시 + status 검증 grep 출력 첨부.
3. **`/ingest`의 목적지는 `wiki/concepts/` 와 `wiki/projects/` 만** — 다른 wiki 하위 디렉토리로의 ingest 금지. `raw/daily-notes/`, `raw/branch-notes/` 자체는 보존하고 항목 단위 추출만.
4. **canonical 문서의 Sources 필수** — `wiki/concepts/` 와 `wiki/projects/` 작성 시 외부 자료(`raw/official-docs/` 또는 `raw/company-tech-blogs/`) wikilink 1개 이상이 본문에 없으면 BLOCKED.
### What stays in the terminal
The terminal response carries **only** the navigation layer:
```markdown
# [작업명] 보고서 — 터미널 요약
**일자:** YYYY-MM-DD
**범위:** <N개 파일>
**Verdict:** COMPLETE | PARTIAL | BLOCKED
**전체 보고서:** [docs/superpowers/specs/YYYY-MM-DD-<topic>-report.md](./docs/superpowers/specs/...)
**파일별 상세:** [docs/superpowers/specs/YYYY-MM-DD-<topic>-per-file-findings.md](./docs/superpowers/specs/...)
## 1. 한눈 요약 / Executive Summary
(전체본)
## 2. Evidence Matrix
(전체본; 행 수가 많아도 매트릭스는 터미널에 그대로 둔다 — 검증 가능성이 핵심)
## 5. 우선순위 권고 / Priority Recommendations
(전체본; 표는 터미널에 그대로 둔다)
## 6. 후속 작업 / Follow-Up
(전체본)
## 7. 검증 / Verification
(실행한 명령 + 결과)
```
**터미널에서 생략하는 섹션:** §3 Coverage Reconciliation 상세, §4 Per-File Findings 본문(요약 한 줄만), §8 Generated Artifacts (위 frontmatter 링크로 대체).
§4 Per-File Findings를 터미널에 그대로 붙여넣어 출력을 부풀리지 않는다. 터미널은 사용자의 작업 흐름을 끊지 않을 분량을 유지한다.
### Link format
Saved file path는 워크스페이스 루트(저장소 최상단) 기준 상대 경로로 적는다. 절대 경로 금지.
예시:
```markdown
- 전체 보고서: `docs/superpowers/specs/2026-05-23-branch-notes-audit-report.md`
- 파일별 상세: `docs/superpowers/specs/2026-05-23-branch-notes-audit-per-file-findings.md`
```
### 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)가 서로 일치하는가?
## Report Template
Every covered report follows this exact section order. Sections cannot be reordered, merged, or omitted. Empty sections are written explicitly with `해당 없음 / N/A` rather than dropped.
```markdown
# [작업명] 보고서 (또는 [Task] Report - 사용자 언어 일치)
**일자 / Date:** YYYY-MM-DD
**범위 / Scope:** <N개 파일 또는 영역>
**Verdict:** COMPLETE | PARTIAL | BLOCKED
**요청 언어 / User language:** ko | en | mixed
## 0. Source roots (외부 디렉토리 참조 시에만)
본 보고서가 워크스페이스 밖의 파일을 인용하는 경우, 짧은 alias를 절대 경로에 매핑한다.
이후 §2~§7의 모든 인용은 alias 기반의 워크스페이스 상대 경로 또는 alias 표기를 사용한다.
| Alias | 절대 경로 |
| --- | --- |
| `<raw-branches>` | `<workspace-root>/raw/branch-notes` |
| `<raw-projects>` | `<workspace-root>/raw/project-notes` |
| `<wiki-concepts>` | `<workspace-root>/wiki/concepts` |
| `<wiki-projects>` | `<workspace-root>/wiki/projects` |
| `<external-code>` | `<사용자가 지정한 external root>` (코드 컨텍스트 참조 시) |
이후 인용 예: `<raw-branches>/feature-keycloak-oauth2-proxy-oidc-flow.md:42` 또는 `<wiki-concepts>/idempotency.md:18`.
(워크스페이스 안 파일만 다루는 보고서는 본 섹션을 "해당 없음 / N/A" 로 명시한다.)
## 1. 한눈 요약 / Executive Summary
3~6 문장. 다음을 포함한다:
- 무엇을 했는가
- 정독한 파일 수 / 전체 in-scope 파일 수
- 가장 중요한 발견 1~2가지
- 후속 조치가 필요한 항목 수
## 2. Evidence Matrix
모든 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
본 섹션은 자기 신고 영역이 아니라 **산식 영역**이다. 에이전트는 아래 값을 계산해서 채우고, 룰이 정의한 Verdict 결정 알고리즘에 따라 상단 Verdict 필드를 결정한다.
| 항목 | 값 |
| --- | --- |
| (a) 사용자가 명시한 파일 수 (또는 in-scope 파일 수) | <N> |
| (b) §2 evidence matrix 총 행 수 | <M> |
| (c) §2에서 Status가 `READ_FULL` 또는 `READ_PARTIAL`인 행 수 | <R> |
| (d) §4 파일별 분석 하위섹션 수 (deep 템플릿 충족) | <P> |
| (e) 차이 (a − b) — 매트릭스 누락 | <a-b> |
| (f) **분석 깊이 미달 파일 수 (c − d)** — 매트릭스엔 READ_FULL이나 §4 분석 없음 | **<c-d>** |
### 분석 깊이 미달 파일 명세
`(c − d) > 0` 인 경우, 아래에 누락된 파일들을 빠짐없이 나열한다. "차이 0" 또는 "없음"이라 적었으나 실제로 누락이 있으면 정직성 위반으로 자동 `BLOCKED`.
| 파일 경로 | §2 Status | §4 분석 여부 | 누락 사유 |
| --- | --- | --- | --- |
| `<raw-branches>/<slug>.md` | READ_FULL | ✗ 없음 | <시간 부족 / 분석 못 함 / 후속 처리 예정 등> |
| ... | ... | ... | ... |
(이 표가 비어 있다면 그 자체로 명시: "분석 깊이 미달 없음 — (c − d) = 0".)
### `NOT_READ` / `BLOCKED` 파일
- `NOT_READ` 파일 목록: <list 또는 "없음">
- `BLOCKED` 파일 목록 (사유 포함): <list 또는 "없음">
### 정직성 컨트랙트
- 본 보고서의 모든 사실 주장은 §2 매트릭스의 `READ_FULL` / `READ_PARTIAL` 행에서 나온다.
- §4에서 다루지 않은 파일에 대한 권고는 §5에 등장할 수 없다.
- 매트릭스 행 수가 §4 하위섹션 수와 다른 경우, §4에 없는 파일을 §5 우선순위 표에 올리면 자동 `BLOCKED`.
## 3-1. Verdict 결정 알고리즘 / Verdict Calculation
상단 frontmatter의 `Verdict` 필드는 다음 산식으로 결정된다. 에이전트가 자기 의지로 라벨을 정하지 않는다. 산식과 라벨이 어긋나면 보고서는 송신 불가.
```text
Let:
N = 사용자가 명시한 in-scope 파일 수 (또는 자동 enumerate 결과)
M = §2 evidence matrix 총 행 수
R = §2에서 Status가 READ_FULL 또는 READ_PARTIAL인 행 수
P = §4 deep-template 충족 하위섹션 수
G = self-grep 검증 (advisory-depth Contract 6) 통과 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)) — 매트릭스는 완비됐으나 §4 분석 또는 인용 검증이 부분적
BLOCKED iff (M < N) OR (in-scope 파일 enumeration 불가) OR (필수 first reads 차단)
```
`Verdict: COMPLETE`라고 적으려면 위 4개 조건이 **전부 참**이어야 한다. 한 조건이라도 거짓이면 라벨은 자동으로 `PARTIAL` 또는 `BLOCKED`로 강등된다. 에이전트는 산식 결과와 일치하지 않는 라벨을 적을 수 없다.
Pre-send 단계에서 §3의 (a)~(f) 값을 실제로 계산해 보고, 그 값으로 위 산식을 평가한 뒤 Verdict 라벨을 채운다. 산식 위반은 정직성 실패이며 draft는 폐기된다.
## 4. 파일별 발견 사항 / Per-File Findings
> **분할 시:** 본 §4의 상세는 `<topic>-per-file-findings.md` 파일에 들어간다. master report의 §4는 파일당 한 줄 요약 + 파일별 findings 문서 링크만 남긴다. 분할이 적용되지 않는 작은 보고서는 §4 상세가 master report에 그대로 포함된다.
각 파일은 자기 자신의 하위섹션을 갖는다. 파일을 "Pillar", "Group", "Theme" 등으로 묶지 않는다. 묶으면 누락이 숨겨진다.
각 발견 사항은 **Goal → Problem → Action 인과 사슬** 형식을 따른다. 단순 의견("성능이 떨어질 수 있다", "고려가 필요하다")은 금지. 자세한 컨트랙트는 `rules/advisory-depth.md` 의 Contract 1을 따른다.
### 한 파일에서의 finding 개수
각 파일에 대해 분석이 surfacing한 **모든 gap을 finding으로 등재한다.** 1개 파일 = 1개 finding이 아니라, 정독 결과 발견된 모든 결함·누락·모호점을 빠짐없이 풀어쓴다. 일반적으로 한 명세 파일에서 2~5개의 finding이 나오는 것이 정상이다.
### Single-finding Justification Gate
파일당 finding이 정확히 1개라면, 해당 §4 하위섹션 끝에 **반드시** 다음 정당화 블록을 첨부한다. 정당화 없이 1개로 끝낸 파일은 자동 `BLOCKED`.
```markdown
#### Single-finding justification (필수, finding이 1개일 때)
이 파일에서 단일 finding으로 종결한 이유를 다음 4개 중 1개 이상에 해당시켜 명시한다:
- [ ] **단순 명세:** 이 파일은 짧고 단일 결정만 다룬다 (파일 총 라인 수 < 80, 또는 단일 정책 명세).
증거: `<raw-branches>/<slug>.md` 총 <N>줄, 결정 사항 1건.
- [ ] **전수 통과 + 1개 결함:** 검토한 <K>개 항목 중 (K−1)개가 명세 의도와 일치하고, 1개만 결함.
검토 항목 리스트:
1. <item 1> — PASS
2. <item 2> — PASS
3. <item 3> — FAIL (위 finding)
...
- [ ] **부분 분석 (PARTIAL):** 시간·범위 제약으로 인해 1개만 분석했다. 추가 분석이 필요한 항목을 §6 Follow-Up에 명시했다.
남은 분석 대상: <list>
- [ ] **단일 critical 문제로 인한 차단:** 발견된 1개 finding이 너무 critical하여 다른 항목 분석에 앞서 우선 처리되어야 한다.
이유: <근거>
```
이 블록이 없거나, 4개 옵션 중 어느 것도 체크되지 않았거나, "검토 항목"이 비어 있는 경우 → 자동 `BLOCKED`. 정당화는 fluff가 아니라 **사실 진술**이어야 한다.
### Zero-finding 파일 처리
발견 사항이 진정 0개인 `READ_FULL` 파일은 하위섹션을 생략하지 않는다. 대신 명시한다:
```markdown
**0-finding 정당화 (필수):**
이 파일은 명세 의도(`Original goal`)와 현재 상태가 일치하며, 검토한 <N>개 항목 모두 통과. 추가 작업 불필요.
검토 항목:
1. <item 1> — PASS — 근거: `<file:line>`
2. <item 2> — PASS — 근거: `<file:line>`
...
```
`<N>개 항목`은 추상적이 아니라 실제 목록이어야 한다. "검토한 항목 모두 통과" 한 줄로 끝내면 자동 `BLOCKED`.
### 4.1 `<filename>` (Status: READ_FULL | READ_PARTIAL)
- **요지 / Gist:** <한 문장으로 이 파일이 무엇을 정의하는가>
- **문서 원래 목표 / Original goal of this file:** <이 파일이 정의하려 한 핵심 의도>. 근거: `<file:line>`
- **검토 항목 / Items reviewed:** <이 파일에서 점검한 N개 항목 리스트>
- **Findings 요약:** N개 (Critical X · High Y · Medium Z · 통과 W)
#### Finding 4.1.1: <짧은 라벨 — 이 finding의 한 문장 정체성>
- **심각도 / Severity:** Critical | High | Medium | Low
- **원래 목표 / Original goal:**
- 인용 / Verbatim quote: "<exact text from source, byte-for-byte>"
- 위치 / Source location: `<path>:<line>` (or `<path>:<start>-<end>` for ranges; workspace-relative paths only)
- 해석 / Interpretation: <한 문장으로 이 인용의 의도 해석>
- **현재 상태 / Current state:**
- 인용 / Verbatim quote: "<exact text from source>" (또는 "해당 라인 없음 — 명세 자체에 누락")
- 위치 / Source location: `<path>:<line>`
- **실무 가정 / Real-world assumptions (REQUIRED — minimum 1, typical 2~3):**
이 비판이 성립하려면 어떤 실무 가정이 참이어야 하는가? 명시하지 않으면 비판은 "에이전트가 상상한 구현"을 표적으로 삼게 됨.
1. **가정 A:** <e.g., "구현이 동기식일 것", "프로덕션 트래픽 > 1000 RPS", "K8s 환경", "사용자가 추가 구성 없이 디폴트만 적용함">
- **무효 조건 / Falsifies if:** <이 가정이 거짓일 구체적 시나리오>
- **사용자가 확인하는 방법 / How user verifies in their context:** <한 줄 체크>
2. **가정 B:** ...
3. **가정 C:** ...
- **간극 / Gap (위 가정들이 모두 참일 때):**
- **구체적 실패 모드 / Concrete failure mode:** <X 상황에서 Y가 발생하여 Z가 깨진다 — 1~3개 명시>
- **재현 조건 / Reproduction condition:** <이 실패가 실제로 일어나는 트리거>
- **이 finding이 무효해지는 경우 / When this finding doesn't apply:** <어떤 가정이 거짓이면 비판 자체가 사라지는가>
- **필요 조치 / Required action:** <구체 액션 — 추상적 권고 아닌 실행 가능한 형태>
- **조치 근거 / Why this action:** <왜 이 액션이 일반적 대안보다 이 상황에 맞는가, 위 가정 하에서>
- **대안 / Alternatives considered:** advisory-depth Contract 2에 따라 가능한 모든 정전 대안을 열거 (보통 3~5개)
- **대안 A:** <라벨> — 적용 상황 / 부적합 이유
- **대안 B:** <라벨> — 적용 상황 / 부적합 이유
- **대안 C (채택):** <라벨> — 왜 이 상황에 가장 맞는가
- **대안 D, E ...:** 가능한 경우 모두 열거
- **반대 논거 / Counterarguments (REQUIRED — minimum 1, typical 2~3):**
advisory-depth Contract 1에 따라, 이 권고가 틀릴 수 있는 시나리오를 명시한다.
1. **반대 A:** <이 권고가 부적절·과잉인 시나리오>
- **반대 근거:** <왜 그 시나리오에서는 권고가 부적절한가>
- **사용자가 검증하는 방법:** <한 줄 체크>
2. **반대 B:** ...
- **구현 단계 / Implementation steps:** <Required action을 실제로 적용하기 위한 순서 있는 단계>
1. <단계 1 — 수정할 파일, 어디에 어떤 코드/문장이 들어가는지>
2. <단계 2>
3. <단계 3>
- **검증 방법 / Verification approach:** <조치가 실제로 작동하는지 입증하는 방법>
- **자동 검증 / Automated:** <self-grep 명령 / `wiki-link-verifier` agent dispatch / `/lint` 슬래시 커맨드 / frontmatter 필드 grep / wikilink ls 검증 등>
- **수동 검증 / Manual:** <Obsidian 그래프뷰 확인 / 리뷰 시 확인할 포인트 (자동 검증으로 부족할 때만)>
- **관련 / Related:**
- **다른 finding과의 결합:** <같은 파일 또는 다른 파일의 finding과 함께 처리해야 효과가 나는 경우>
- **상호 의존 파일:** <이 조치가 영향을 주거나 받는 다른 명세/모듈>
#### Finding 4.1.2: ...
(반복)
### 4.2 `<next filename>` ...
`NOT_READ` 및 `BLOCKED` 파일은 본 섹션에 자기 하위섹션을 갖지 않는다. 매트릭스와 §3에만 등장한다.
### Master report에서의 §4 (분할 시)
분할이 적용된 경우, master report의 §4는 다음 형식의 한 줄 요약 표만 남긴다:
```markdown
## 4. 파일별 발견 사항 / Per-File Findings (요약)
> 상세: [<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.2 | `feature-Y.md` | 2 | 0 | 1 | 1 | 0 | N/A |
...
```
## 4-1. 적대 리뷰 결과 / Adversarial Review Results
본 섹션은 적대 리뷰 서브에이전트가 §4의 각 finding에 대해 수행한 falsification 검토 결과를 요약한다. wiki-superpowers 플러그인의 주 작업은 multi-doc audit / raw → canonical 추출 권고 / 링크 무결성 감사이며, findings 가 5개 이상일 때 `wiki-adversarial-reviewer` 디스패치를 권장한다. 5개 미만이면 적대 리뷰 없이 송신 가능. 코드(Java/CA) 작업의 적대 리뷰는 본 플러그인 범위 밖이며, ca-tmpl 코드 리뷰 체인(`ca-architect-sentinel` → `ca-spec-reviewer` → `ca-quality-reviewer`) 이 separation of concerns 를 제공한다.
분할 시: 본 섹션은 master report에 들어간다. per-file-findings 문서에는 들어가지 않는다.
### 4-1.1 적대 리뷰 실행 여부
| 항목 | 값 |
| --- | --- |
| 적대 리뷰 실행 여부 | YES / NO |
| 실행하지 않은 사유 (NO 시) | <e.g., findings 수 < 5라 oversight 불필요 / 빠른 turnaround 요구로 생략> |
| 적대 리뷰 보고서 경로 (실행 시) | `docs/superpowers/specs/YYYY-MM-DD-<topic>-adversarial-review.md` |
§4 findings가 5개 이상이거나 master report가 priority recommendation을 §5에 4개 이상 올린다면 적대 리뷰를 **권장**한다. 5개 미만의 작은 보고서는 적대 리뷰 없이도 무방.
### 4-1.2 적대 리뷰 요약 표 (실행 시)
| Finding ID | Original severity | Practicality | Overclaim | Assumption | Action |
| --- | --- | --- | --- | --- | --- | --- |
| 4.1.1 | Critical | PASS | FAIL | PASS | DOWNGRADE → High |
| ... | ... | ... | ... | ... | ... | ... |
### 4-1.3 컨트롤러 판단 반영
각 finding에 대해 컨트롤러가 적대 리뷰 권고를 수용·거부한 내역을 명시한다:
- **수용 (Accept)**: 적대 리뷰 권고대로 severity 강등 또는 finding 제거 적용.
- **거부 (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에 여전히 P0/Critical로 올라 있으면 자동 BLOCKED.
## 5. 우선순위 권고 / Priority Recommendations
| 우선순위 | 권고 액션 | 근거 파일:라인 | 원래 목표 | 현재 간극 | 조치 후 효과 |
| --- | --- | --- | --- | --- | --- |
| 1 (Critical) | ... | `<file:line>` | ... | ... | ... |
| 2 (High) | ... | `<file:line>` | ... | ... | ... |
각 행은 §4의 한 Finding과 1:1 대응되어야 한다. 행을 §4보다 단순화·축약·일반화하지 않는다.
본 표에 등장하는 모든 파일은 §4에 자기 하위섹션을 가진 `READ_FULL` 또는 `READ_PARTIAL` 파일이어야 한다.
§4에 없는 파일을 본 표에 올리면 자동으로 `BLOCKED`. 보고서를 송신하지 않는다.
## 6. 후속 작업 / Follow-Up
- 다음 라운드에서 정독해야 할 파일
- 미해결 위험
- 추가 검증이 필요한 가설
## 7. 검증 / Verification
### 7.0 Proof manifest v2 (신규 run의 SSOT)
신규 report run의 quote proof SSOT는 `proof-manifest/v1` JSON이다. schema와 실행 profile은 각각 [`harness/runtime/proof_manifest.py`](../harness/runtime/proof_manifest.py), [`harness/source/execution-profiles.json`](../harness/source/execution-profiles.json)에 두며, profile 선택 규칙은 [`rules/execution-profiles.md`](execution-profiles.md)를 따른다. 신규 run은 draft의 finding-role·source path·exact quote를 `proof-request/v1`으로 만든 뒤 `proof_runner.py`가 manifest와 compact summary를 함께 쓰는 경로를 사용한다.
```bash
python3 harness/runtime/proof_runner.py '<proof-request.json>' \
--repo-root . \
--output 'docs/superpowers/specs/<topic>/proof-manifest.json' \
--summary-output 'docs/superpowers/specs/<topic>/proof-summary.md'
```
- runner exit code가 `0`이고 stdout `proof-runner-result/v1.status`와 output의 `verification.status`가 모두 `PASS`인 proof만 `P`와 `G`에 포함한다. 실패 시 manifest와 summary를 쓰지 않으며 보고 완료 판정을 중단한다.
- §7.1 Markdown에는 generated `proof-summary.md`의 manifest 경로, proof/PASS/FAIL count, **persisted manifest bytes의 SHA-256**을 반영하고, hash를 실제 manifest bytes와 다시 대조한다.
- 본문에는 실패 proof·라인 정정·대표 PASS proof 1~3개만 펼친다. 나머지 PASS proof의 반복 stdout은 manifest가 소유한다.
- source 부재, source/stdout hash mismatch, line range 밖 quote, byte 불일치, duplicate finding-role, non-zero recorded exit, `exact_match=false`는 `quote_gate` FAIL이다.
- manifest는 quote evidence 형식의 SSOT일 뿐이다. audit의 scope/matrix/finding/adversarial/priority/link/language/artifact gate와 기존 verdict 산식을 대체하거나 완화하지 않는다.
### 7.1 Proof hard gate
신규 report는 다음 기계 결과를 기록한다. 성공 proof의 shell stdout 전체를 본문에 반복하지 않는다.
```text
Manifest: <repo 또는 run namespace 안의 path>
Manifest SHA-256: <sha256>
Manifest schema: proof-manifest/v1
Proof: <N>
PASS: <N>
FAIL: 0
Runner exit: 0
Hard-gate exit: 0
```
controller는 `proof_hard_gate.py`에 동일 path·hash·count를 넘긴다. hard gate가 path confinement, persisted bytes hash, schema, proof/PASS/FAIL count와 source bytes 재검증을 모두 통과한 finding만 `P`와 `G`에 포함한다. inline `sed`/`grep`은 디버깅 또는 대표 예시일 뿐 count SSOT가 아니다.
- `V` = manifest의 `proof_count`
- `P` = manifest의 `pass_count`
- `D` = runner가 manifest 발급 전에 제거한 proof 수
- `C` = line correction 수
- `G` = 필요한 proof role이 모두 PASS인 finding 수
- `U` = draft quote 수 − `V`; `U > 0`이면 완료 판정 차단
### 7.2 실행한 검증 명령
본 섹션은 wiki 작업에 적용되는 자동 검증 명령을 기록한다. 코드(Java/Gradle) 빌드 명령은 본 rule 범위 밖이며, 그런 명령이 등장하면 본 보고서가 ca-tmpl 영역으로 잘못 진입한 것이므로 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>
## 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
```
## Format Discipline
- **One file = one subsection in §4.** 파일을 묶지 않는다. 묶으면 누락이 보이지 않는다.
- **No "Pillar / Group / Theme" grouping in §4.** 그룹화는 §2 매트릭스 위쪽이나 §5에서만 허용. §4는 평면(flat) 파일별 구조 유지.
- **Every claim cites file:line.** 본문에 단정적 사실이 있는데 `<file:line>` 근거가 없으면 그 문장을 지우거나 `INFERENCE`로 라벨링한다.
- **Priority table only references analyzed files.** §5 행에 등장하는 파일은 §4에 반드시 하위섹션이 있어야 한다. 없으면 draft 폐기.
- **No mermaid/diagram filler.** 다이어그램은 본문 분석을 대체할 수 없다. 분석 없이 다이어그램만 있으면 `BLOCKED`.
- **No bilingual mirroring.** 한국어 본문과 영어 본문을 둘 다 쓰지 않는다. 사용자 언어 하나.
## Anti-Patterns to Avoid
| Pattern | Why it fails | Replacement |
| --- | --- | --- |
| "Pillar A: 4 files" + 묶음 비평 | 4개 중 어느 파일 어디서 나온 사실인지 추적 불가 | 파일당 §4 하위섹션 1개씩 |
| GitHub `[!WARNING]` admonition만 나열 | 출처가 사라짐. 인용 라인 없음 | `<file:line>` 인용 + 한 줄 발췌 |
| 영어 보고서 + 한국어 대화 | 사용자가 한 번 더 번역해야 함 | 사용자 언어로 통일 |
| Executive summary 없이 본론 바로 진입 | 사용자가 핵심을 알려면 끝까지 읽어야 함 | §1 한눈 요약 3~6 문장 |
| 우선순위 표에 정독하지 않은 파일 등장 | 추측을 권고로 둔갑 | §4에 있는 파일만 §5에 올림 |
| Verdict 없이 발견사항만 나열 | 사용자가 통과/실패 판단 불가 | 상단 frontmatter에 Verdict 명시 |
## Pre-Send Format Check
송신 직전, 에이전트는 자신의 draft에 대해 다음을 확인한다. 하나라도 실패하면 draft를 폐기하고 재작성한다.
1. 본문 산문 언어가 사용자 언어와 일치하는가?
2. §0 Source roots가 외부 디렉토리 참조 시 정의되어 있는가? 워크스페이스 내부만 다룬다면 "해당 없음 / N/A"이 명시되어 있는가?
3. §1~§7이 모두 존재하는가? (해당 없으면 명시적 "없음 / N/A")
4. §2 evidence matrix 행 수가 in-scope 파일 수와 일치하는가? 불일치면 §3에 reconciliation 블록이 있는가?
5. §4 파일별 하위섹션 수가 §2의 `READ_FULL` + `READ_PARTIAL` 행 수와 일치하는가?
6. §4의 각 finding이 **verbatim quote + 위치(file:line)** 를 Original goal과 Current state에 포함하는가?
7. §4의 각 finding이 **실무 가정 (Real-world assumptions)** 을 최소 1개, 각 가정에 무효 조건과 사용자 검증 방법을 포함하는가?
8. §4의 각 finding이 "이 finding이 무효해지는 경우" 명시를 포함하는가?
9. §5 우선순위 표의 모든 파일이 §4에 하위섹션을 가지고 있는가?
10. 본문의 모든 구체적 사실 주장이 verbatim quote + `<file:line>` 근거를 동반하는가? 단순 `(L67)` 형식 금지.
11. 모든 file:line 경로가 워크스페이스 상대 (또는 §0에 정의된 alias) 형식인가? 절대 경로 `/home/...` 금지.
12. 다이어그램/표가 분석을 대체하지 않고 보조만 하는가?
실패하면 사과로 채우지 않는다. 누락을 메우거나 명시적으로 `NOT_READ` 처리하고 다시 작성한다.
## No silent truncation (funnel 계약)
출력이 캡/슬라이스/top-N/skip 으로 coverage 를 bound 하면 **드롭한 수 + 이유**를 반드시 보고한다. funnel 은 균형해야 한다:
```
found = processed + dropped
```
- `found` = 식별한 총 항목. `processed` = 실제 판정한 수(결과 무관 — covered/missing/verified/promoted 모두 포함). `dropped` = 판정하지 않고 의도 제외(이유 필수).
- **agent 출력**은 `wiki-stats` 블록으로 보고한다(SubagentStop 이 균형·dropped_reason 검증 — `.claude/hooks/wiki_rules.py` `validate_stats_block`).
- **command 출력**은 `## Stats` 절로 보고한다.
- 침묵 누락은 "전부 다뤘다" 는 거짓 신호다 — 제3의 보고되지 않은 버킷을 두지 않는다.