38 lines
4.3 KiB
Markdown
38 lines
4.3 KiB
Markdown
# 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` 스킬 레지스트리 등록 확인.
|