rules/branch-depth-gate — 브랜치 노트 구현 착수 깊이 게이트

rules/ 의 방법론 규칙. branch-note 1개가 코딩 착수해도 되묻지 않을 만큼 깊은가를 판정한다. 이 문서는 "전체 계약"이 아니다 — 전체 계약은 raw/project-notes/ca-skeleton-operational-contract.md. feature-implementation-readiness-scorecard(스켈레톤 adoption 거시 게이트)와 다른 층·다른 범위로 공존한다. 본 게이트는 브랜치 노트 1개의 깊이 미시 게이트.

적용

대상: raw/branch-notes/feature-*.md (구현 착수 전).
실행: /depth <branch> →
1. 1차 결정론 검사 .claude/hooks/wiki_structure_lint.py (구조·링크 문법 — 싸고 빠름)
2. 2차 의미 판정 branch-depth-auditor (아래 4축 — 소스를 읽고 의미로 판정)
본 게이트는 read-only. 브랜치 노트를 편집하지 않으며 판정을 노트에 박지도 않는다.

역할 분담 (결정론 vs 의미)

	1차 린터(결정론)	2차 감사기(LLM 의미)
R1 조사 깊이	링크 깨짐·앵커 부재만	claim 이 L0(존재)인지 L1+(메커니즘)인지
R2 결정 조건	`선택 조건` 셀 비었는지	선택 조건이 말이 되는지
R3 구체 detail	섹션/라벨 존재	detail 이 충분한지
R4 엣지·실패·의존	섹션 존재	실패 경로가 적절한지, 암시된 의존 포착

→ 2차 감사기는 의미만 본다(구조 존재는 1차가 이미 확인).

4축 (R1~R4)

축 라벨은 R1~R4. branch-note 의 Decision Evidence Map 이 D1,D2 를 Decision ID 로 쓰므로 D* 와 구분.

축	Pass 조건	Blocking(Not ready) 트리거
R1. 조사 깊이	각 Decision 의 Supporting Claim 이 깊이 사다리 충족 — 의존 메커니즘 L1+, 분기 조건 L2+	결정 근거 claim 이 순수 L0(존재만)뿐
R2. 결정 조건	각 Decision 이 "어떤 조건일 때 A, 아니면 B"의 선택 기준 명시	`검토한 대안`은 있는데 언제 그 대안을 고르는지 기준 부재
R3. 구체 detail	`## 구현 가이드` 의 각 in-scope 항목이 명명·경로·메커니즘·API/테스트명 구체화 또는 `UNSUPPORTED_IMPL_DECISION` 라벨 + trade-off 한 줄	in-scope 항목인데 구현 detail 도 UNSUPPORTED 라벨도 없음
R4. 엣지·실패·의존	실패/엣지 경로 열거 + 다른 contract 의존을 대상 브랜치 + 그 Decision ID 로 링크	정상 경로만 / 다른 계약 의존이 암시되는데 링크 안 됨

R1 클레임 깊이 사다리

깊이의 단위는 문서 개수가 아니라 결정별 종결. 얕은 문서 10개 < 결정을 닫는 문서 1개.

레벨	클레임이 답하는 것	판정
L0 존재	"X 가 있다 / 권장한다"	단독 불충분
L1 메커니즘	어떻게 동작 / 언제 발생	메커니즘 의존 결정의 최소선
L2 조건·경계	언제 적용/제외, 실패 시 어떻게	분기 조건 있는 결정의 최소선
L3 검증	확인 방법·수치·반례	가산점

출처 타입 적정성 (개수 기준 대체):

스펙/표준이 정의한 동작 → official-standard/official-vendor-doc 1개로 충분.
"대기업은 보통 이렇게 한다" 운영 패턴 추론 → 회사 블로그 1개는 "공식" 불가. 독립 사례 2개+ 또는 official 1개 병행.

조사는 결정-주도(top-down): 내려야 할 결정·미지수를 먼저 나열하고 각각을 닫을 때까지 조사. 조사 완료 = 모든 결정 종결 = 착수 가능.

판정 규칙

심각도 3단계: Blocking(Not ready) · Should-fix(권고) · Advisory(참고).
Ready = Blocking 0건. Should-fix 가 남아도 사용자가 "감수" 선언 시 착수 가능(리포트에 기록).
모든 finding 은 4종 세트로 근거화: 심각도 · 위치(섹션/행) · 예상 의구심("구현 중 여기서 ___를 되묻게 됨") · 채울 방법. 근거 없는 지적 금지.

명명된 실패 모드

EXISTENCE_ONLY (R1): 결정 근거가 L0 뿐.
NO_SELECTION_CRITERION (R2): 대안은 있으나 선택 조건 없음/무의미.
IMPL_UNDERSPECIFIED (R3): in-scope 항목에 구현 detail·UNSUPPORTED 라벨 둘 다 없거나 불충분.
HAPPY_PATH_ONLY (R4): 실패/엣지 경로 미열거.
IMPLICIT_DEPENDENCY (R4): 다른 계약 의존이 암시되나 대상 브랜치/Decision ID 링크 없음.

4.5 KiB Raw Blame History