---
title: rules / coverage-gate
source_type: reference
status: reviewed
tags: [rules, coverage, branch, ca-skeleton, quality-gate]
related_projects: [ca-skeleton]
last_reviewed: 2026-06-02
---

# coverage-gate — 브랜치 완전성 판정 기준

> 이 문서는 `/coverage` 명령(`.claude/commands/coverage.md`)과 `coverage-auditor` 서브에이전트(`.claude/agents/coverage-auditor.md`)의 **판정 기준 SSOT**다. `branch-depth-gate.md`(깊이)의 짝 — 이쪽은 **완전성(coverage)** 을 본다.

## Parent / 부모

- [[CLAUDE.md]] §11·§15 — 근거 없는 결정 금지, 근거 기반 구현 명세
- 짝 문서: [[rules/branch-depth-gate]] — 깊이 게이트

## 0. depth 와의 분업 (헷갈리지 말 것)

| 게이트 | 묻는 질문 | 비유 |
|---|---|---|
| `depth` (R1~R4) | 노트에 **적힌** 결정이 충분히 깊은가 | "네가 푼 문제는 잘 풀었나" |
| `coverage` (본 문서) | **적어야 할** 관심사가 다 적혔는가 | "안 푼 문제가 있나" |

→ coverage 는 *빠진 것*을 찾고, depth 는 *적은 것의 깊이*를 본다. 둘은 직교한다. 브랜치는 둘 다 통과해야 완성.

## 1. 기준의 출처 (reference standard 위계)

"무엇을 덮어야 하는가"는 **추측하지 않는다.** 다음 위계로만 판정:

1. **설계 문서 (1순위)** — 브랜치 frontmatter `governing_docs:` 가 가리키는 canonical 문서(`wiki/projects/ca-tmpl/<cluster>.md`). 이 문서가 열거하는 관심사가 "있어야 할 것"의 기준.
2. **선례(완성) 형제 브랜치** — 이미 구현된 브랜치들. 같은 관심사를 이미 누가 owner 인지 식별(겹치면 위임).
3. **ca-tmpl 실제 코드** — `/home/donghyeon/workspace/ca-tmpl/src` + `docs/registries`. 관심사가 말로만 있는지 실제 구현인지 ground truth.

`governing_docs` 가 없으면 기준 부재 → 판정 불가(`NO_GOVERNING_DOC`, 1차에서 차단). 외부 taxonomy(OWASP 등)는 기준으로 삼지 않는다 — 기준은 프로젝트 자체 문서.

## 2. 상태 3종

각 관심사는 정확히 하나:

| 상태 | 의미 |
|---|---|
| `covered-here` | 이 브랜치가 결정으로 다룸 (Decision ID 보유) |
| `delegated` | 이 브랜치 밖이지만 다른 owner 브랜치가 소유 (위임 링크 필요) |
| `missing` | 어느 브랜치에도 결정으로 없음 |

## 3. 판정 (3단계 심각도)

| 신호 | 의미 | 트리거 (실패 모드) |
|---|---|---|
| 🔴 Blocking | 진짜 빠짐 | `MISSING_CONCERN` — governing 문서가 요구하는 관심사가 이 브랜치에도, 다른 owner 에도 없음 |
| 🟡 Should-fix | 위임 링크 누락 | `UNLINKED_DELEGATION` — sibling owner 가 있으나 본 노트(§Audit/§Coverage)에 위임 링크 없음 |
| ⚪ Advisory | 있으면 좋음 | governing 문서가 권고하나 핵심 아님 / `MIS-SCOPED_GOVERNING_DOC`(governing_docs 가 주제와 안 맞아 보임 — 한 줄 코멘트) |
| — | 정합 깨짐 | `STALE_OWNER` — §Coverage 가 가리키는 owner 가 코드/노트 대조상 실제로 그 관심사를 안 가짐 → 심각도는 갭 성격에 따라 |

**Covered = Blocking 0건.** Should-fix 가 남아도 사용자 "감수" 선언 시 통과(리포트 기록) — depth 와 동일.

## 4. 명명된 실패 모드

- `MISSING_CONCERN` (Blocking): governing 문서 관심사가 어느 브랜치에도 결정으로 없음. **이게 coverage 의 핵심 산출.**
- `UNLINKED_DELEGATION` (Should-fix): owner sibling 있으나 위임 링크 누락.
- `STALE_OWNER`: §Coverage 가 가리키는 owner 가 실제로 그 관심사를 안 가짐(코드/노트 대조 불일치).
- `NO_GOVERNING_DOC` (1차 차단): `governing_docs` 미지정 → 기준 부재로 판정 불가.
- `MIS-SCOPED_GOVERNING_DOC` (Advisory): governing_docs 가 브랜치 주제와 안 맞아 보임 — 적정성 의심을 surface(추측 단정 금지).

## 5. 판정 원칙

- **추측 금지** — governing 문서·선례 브랜치·코드를 *실제로 읽고* 판정. 안 읽고 "빠졌다/덮였다" 단정 금지.
- **owner 위임은 Blocking 아님** — 다른 브랜치가 소유하면 false block 하지 않는다. 위임 링크만 요구(Should-fix).
- **코드 ground truth 우선** — 노트가 "구현됐다"고 해도 `src/` 에 없으면 `STALE_OWNER` 또는 `missing`.
- 모든 finding 4종 세트: `심각도 · 관심사 · 상태(+owner) · 채울 방법`. 근거 없는 지적 금지.
- 자동 수정 금지(read-only). 갭은 `/branch-spec` 으로 되돌아가 채운다.

## 6. 프로젝트 모드 (`/coverage --project`)

- 전체 canonical 문서에서 관심사를 열거 → 각 브랜치 `## Coverage` 와 cross-ref.
- **owner-less 관심사**(아무 브랜치도 안 맡음) = 프로젝트 레벨 Blocking.
- 결과를 `wiki/projects/ca-tmpl/coverage-matrix.md` 로 **생성**(손유지 금지 — 매 실행 재생성).

## 7. 면제

`governing_docs` 미지정 + `related_projects` 에 ca-skeleton/ca-tmpl 없는 브랜치(예: keycloak 학습 노트)는 coverage 면제. 1차 린터가 프로젝트 소속으로 판단.