llm-wiki/docs/superpowers/specs/2026-06-10-consistency-layer-design.md

2026-06-10 — Consistency 계층 설계·구현 (문서 간 모순 탐지 + 동기화 자동검사)

• 의뢰: feature 브랜치 노트들이 구현 중 추가 조사·결정으로 진화하며, 위임(delegated)된 내용이 문서 간에 서로 달라지는 모순 발생. 문서 정리 시 일관성을 맞추는 체계 요구. 예: ca-skeleton-operational-contract(project note) → 브랜치 노트들의 세부 결정.
• 사용자 결정: 3층 풀스택 / 역참조 전파는 비차단 경고 / 재진술은 retro 수거 + 신규 경고.

§1. 진단 (실증)

모순은 탐지 문제이기 전에 복제 문제 — A 가 B 소유 결정을 풀어 쓰면 사본이 생기고, B 의 정당한 진화가 A 를 조용히 낡게 만든다. 실측 증거: 같은 파일 내 "D17 의 5개 rule" vs "4개 rule"(feature-boundary...:101 vs :278), 존재 불명 브랜치 cross-cite "(있다면)", 전파 의존을 prose 로만 기록("sibling 매핑이 바뀌면 ... 영향"), wikilink/bare 참조 혼용, 관심사 ID(C5b) ad-hoc.

§2. 구현 (3층)

층	산출물	내용
계약	rules/consistency-contract.md	Single-Owner(결정·관심사당 owner 1개: branch DEM D<n> 또는 project §<n>) + Reference-Only([[owner]] D<n> + 1줄 요약만, 세부 재진술 금지 RESTATED_FOREIGN_DECISION) + 참조 형식 표준(wikilink + 같은 줄 후방 100자) + 해소 우선순위(owner 우선 / hub-vs-branch 는 사용자 판정 / 항상 승인 후)
결정론	.claude/hooks/wiki_consistency_check.py (+테스트 18)	Decision Registry(표 행 첫 셀 D<n> 정의, 주석 부가 형태 수용) + 참조 추출. 검사 5종: DANGLING_DECISION_REF(--pre 차단) / BARE_DECISION_REF / BARE_OWNER_REF / DUAL_OWNERSHIP / DANGLING_SECTION_REF. --impact <slug> 역참조 목록. --post = 역참조 충격 알림(DEM 행 편집 감지 시 참조자 목록 비차단 전달) — "B 의 정당한 진화 + A 의 무통보" 를 끊는 동기화 트리거
의미	.claude/agents/wiki-consistency-auditor.md (opus, read-only, 4-플랫폼 변형)	참조 엣지 단위(전수 pairwise 금지) 양쪽 verbatim 대조 → CONSISTENT / STALE_SUMMARY / CONTRADICTION / RESTATED + owner-우선 해소 제안. wiki-verdict(blocking=CONTRADICTION 수)+wiki-stats 훅 검증, WIKI_AGENT_TYPES 등록
워크플로	/sync (+미러 2)	검사기 → auditor fan-out(엣지 >20 분할) → fix-plan(owner-우선, RESTATED→참조+1줄 교체, 승인 후 적용) → 재검사 천장 2회 + wiki-stats funnel

배선: 양 repo settings.json — wiki(PreToolUse --pre + PostToolUse --post), ca-tmpl(절대경로 동일 — cross-repo 쓰기도 게이트). CLAUDE.md(§1·§2·§14, 명령 23/미러 15) + SKILL.md tree/lanes + lint E군 경계.

§3. 파서 정밀도 (오탐 제거 이력 — 차단 훅의 전제)

반복	DANGLING	원인/수정
v1	28	DEM 첫 셀 D9 (2026-05-31 보강) 형태 미인식 → 첫 셀 시작-매칭으로 수정
v2	26	귀속 모호성: 외부 링크 후방 윈도의 D-id 가 인용자 자신의 결정인 경우("의존 — 우회(D13)") → 자기 DEM 보유 id 는 침묵(의미 귀속은 Layer 2)
v3	1 — 실모순	feature-repository-access-permission-contract.md:220 이 [[feature-rate-limit-idempotency-contract]] (D14) 로 오귀속 — D14 의 실제 owner 는 feature-application-port-usecase-contract(같은 파일 :250 이 올바른 귀속을 증명)

전수 dry-run 최종: 190 findings (BARE_DECISION_REF 129 · BARE_OWNER_REF 60 · DANGLING 1) — retro 수거는 /sync fix-plan 으로 점진 진행.

§4. 한계 (명시)

• 관심사 어휘 비정규 → DUAL_OWNERSHIP 은 정규화 exact-match 만 (fuzzy 는 Layer 2). coverage-matrix 를 관심사 레지스트리로 승격하면 정밀도 상승 (후속 후보).
• 귀속 모호 케이스(양쪽 모두 가진 D-id)는 결정론이 침묵 — auditor 가 엣지 판정 시 해소.
• 의미 모순(값·정책 충돌)은 Layer 2 LLM 판정 — /sync 실행 시점에만 (쓰기 시점 의미 대조는 비용상 제외).

검증: 테스트 5 suite OK (신규 18 포함) / settings ×2·agent.json·toml valid / 신규 파일 8종 실존 / /sync 스킬 레지스트리 등록 확인.