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순위) — 브랜치 frontmatter governing_docs: 가 가리키는 canonical 문서(wiki/projects/ca-tmpl/<cluster>.md). 이 문서가 열거하는 관심사가 "있어야 할 것"의 기준.
선례(완성) 형제 브랜치 — 이미 구현된 브랜치들. 같은 관심사를 이미 누가 owner 인지 식별(겹치면 위임).
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차 린터가 프로젝트 소속으로 판단.

5.0 KiB Raw Permalink Blame History