llm-wiki/harness/source/skills/coverage.md

브랜치 노트 1개가 기준 문서가 요구하는 관심사를 빠짐없이 덮는지 점검합니다(완전성). /depth(깊이)의 짝 — 이쪽은 적어야 할 게 다 적혔나를 봅니다. (기준: rules/coverage-gate.md / 판정 위계: governing 문서 → 선례 브랜치 → ca-tmpl 코드)

인자: {{arguments}}

작업 절차 (브랜치 모드)

1. 인자 검증 — 비어 있으면 브랜치 이름 요청. --project 면 프로젝트 모드(아래)로. raw/branch-notes/<name>.md 로 해석(.md·feature- 누락은 관대히 보정).

2. 파일 존재 확인 — 없으면 경로만 안내하고 종료(생성은 /branch).

3. 1차 결정론 사전 검사 + 면제 판정 (스크립트 — LLM 인라인 grep 금지):

   python3 .claude/hooks/wiki_structure_lint.py --coverage-pre raw/branch-notes/<name>.md
   

   exit code 로 분기 — 0 PASS(WARN 포함 가능, 2차 진행) / 1 FAIL(NO_GOVERNING_DOC·GOVERNING_DOC_MISSING — 먼저 고치도록 안내하고 2차 보류) / 3 EXEMPT(coverage 면제, 예: keycloak 학습 노트 — 면제 사유만 보고하고 종료). NO_COVERAGE_SECTION 은 WARN(2차가 채울 칸).

4. 2차 의미 판정 (coverage-auditor 디스패치) — 1차 PASS(또는 WARN 사용자 인지)하면 coverage-auditor 서브에이전트에 브랜치 노트 경로 전달.

   • 감사기는 governing 문서·선례 브랜치·ca-tmpl 코드를 실제로 읽어 각 관심사를 covered-here / delegated / missing 으로 의미 판정.
   • 감사기 리포트(Verdict + Coverage 표 + 다음 행동)를 그대로 출력.

5. §Coverage 반영 (사용자 확인 후) — 감사기가 돌려준 Coverage 표를 노트의 ## Coverage 섹션에 기록할지 사용자에게 제안. 표는 생성물 — 손으로 유지하지 않음, coverage 실행 시마다 갱신.

6. 종합 판정 — 1차 exit code(0) + 2차 wiki-verdict 블록(blocking: 0)을 기계 합산해 Covered / Not-covered. missing(🔴) 0건이어야 Covered.

7. 루프 — missing 을 /branch-spec <name> 으로 되돌아가 결정으로 채운 뒤 /coverage <name> 재실행 → Covered 까지. (/branch-spec 이 끝에서 depth·coverage 를 자동 실행하므로 보통 그 흐름 안에서 닫힘.)

작업 절차 (프로젝트 모드 — /coverage --project)

1. coverage-auditor 를 --project 입력으로 디스패치.
2. 감사기가 전체 canonical 문서에서 관심사를 열거하고 각 브랜치 ## Coverage 와 cross-ref 해 owner-less 관심사(아무 브랜치도 안 맡음)를 Blocking 으로 식별.
3. 감사기가 돌려준 매트릭스를 wiki/projects/ca-tmpl/coverage-matrix.md 로 생성/덮어쓰기(생성물 — 손유지 금지). 사용자 확인 후 기록.
4. owner-less 관심사 목록을 요약 보고 — 각각 어느 브랜치(신규/기존)가 맡아야 하는지 한 줄씩.

규칙

• 검출·판정만(read-only). 1차 인라인 검사도 2차 감사기도 노트를 편집하지 않는다. §Coverage/matrix 기록은 사용자 확인 후 명령이 수행(생성물).
• 멱등: 같은 노트에 몇 번 돌려도 안전. §Coverage 는 매번 재생성.
• 추측 금지 — governing 문서·코드를 실제로 읽고 판정. owner 위임은 Blocking 아님(Should-fix).
• depth 와 분업 — 깊이는 /depth, 완전성은 /coverage. 서로의 영역을 중복 판정하지 않는다.
• 자동 채움 금지 — missing 갭은 /branch-spec 으로 채운다(본 명령은 검출만).
• wiki/log.md 기록 안 함(/depth·/branch-spec 와 동일 정책).

Proof Artifact Contract (HARD)

finding/인용 draft는 exact UTF-8 quote 전부를 포함한 proof-request/v1 JSON으로 조립한다. controller는 python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json을 실행한다. exit 0, schema_version: proof-runner-result/v1, status: PASS, manifest schema_version: proof-manifest/v1 확인 전에는 workflow 완료를 선언하지 않는다.

보고서에는 manifest_path, manifest_sha256, proof_count, pass_count, fail_count를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. fail_count != 0 또는 count 불일치면 완료 판정을 차단한다.