llm-wiki/.claude/commands/sync.md

---

description: 문서 간 모순·동기화 검사 — 결정론 검사기 + 참조 엣지 의미 대조 + fix-plan argument-hint: [--impact ] [대상 경로, 비우면 전체] disallowed-tools: NotebookEdit, WebSearch, WebFetch

문서 간 모순·위임 동기화를 검사하고 수거합니다. (계약: rules/consistency-contract.md — Single-Owner + Reference-Only)

대상: $ARGUMENTS (지정 안 하면 raw/branch-notes/ + raw/project-notes/ 전수)

작업 절차 — 결정론 선행 (LLM 수기 재연 금지)

1. 결정론 검사기 (필수 1단계)

   python3 .claude/hooks/wiki_consistency_check.py --all
   

   --impact <slug> 가 주어지면 대신 python3 .claude/hooks/wiki_consistency_check.py --impact <slug> (해당 노트의 결정을 참조하는 문서 역추적).

   • findings 를 그대로 흡수: DANGLING_DECISION_REF / DANGLING_SECTION_REF / DUAL_OWNERSHIP → CRITICAL, BARE_DECISION_REF / BARE_OWNER_REF → WARN.
   • 이 검사들을 LLM 이 수기로 재연하지 않는다 — 검사기 출력이 결정론 SSOT.

2. 팩킷 준비 (T0 결정론 발췌 — 0토큰, rules/extraction-tiering.md)

   python3 .claude/hooks/wiki_consistency_check.py --packets [slug] > /tmp/sync-packets.md
   

   참조 엣지 양쪽(citing ±2줄 / owner D-row)의 맥락을 결정론 추출. auditor 는 corpus 대신 이 팩킷 파일을 1차 입력으로 소비한다 — 판결이 모호한 엣지만 원문 해당 라인을 Read.

3. 의미 대조 — wiki-consistency-auditor dispatch

   • 입력: 1단계 검사기 출력 + 팩킷 파일 경로(/tmp/sync-packets.md) + 대조할 참조 엣지 목록 (엣지 = citing 문서 / owner 문서 / D-id·§-id + 양 노트 경로).
   • 기본 슬라이스: DANGLING / DUAL_OWNERSHIP 관련 엣지 + 사용자가 지정한 대상 경로의 엣지. 전수 대조는 엣지 수를 먼저 보고하고 사용자 확인 후에만.
   • 엣지 >20개면 슬라이스로 분할해 병렬 dispatch.
   • 출력: 엣지별 CONSISTENT / STALE_SUMMARY / CONTRADICTION / RESTATED_FOREIGN_DECISION verdict (+ wiki-verdict/wiki-stats 블록).

4. fix-plan 표 — /lint --fix-plan 과 동일 규율 (위험도·승인 필요·패치 범위):

   Finding	필요한 수정	대상 파일:line	위험	승인 필요?	패치 범위
   <실패 모드 + 한 줄>	<무엇을 어떻게 바꾸는가>	path:line	low / med / high	yes / no	<몇 줄 / 어느 섹션>

   • owner-우선 해소 원칙 (rules/consistency-contract.md §충돌 해소): 위임한 쪽(참조자)이 요약을 갱신한다. owner 본문을 참조자에 맞춰 고치지 않는다.
   • RESTATED_FOREIGN_DECISION → "참조 + 1줄 요약으로 교체" 제안 (세부 내용은 owner 로 이관 또는 삭제를 명시).
   • hub(project-note) vs branch 충돌은 항상 개별 승인 — 자동 적용 금지. 보통 branch 가 더 최신·구체 → "project-note 갱신 제안" 형태가 기본이나, 판정은 사용자 몫.
   • BARE_DECISION_REF / BARE_OWNER_REF 수정(wikilink 화)은 low 위험 — 묶음 승인 제안 가능.

5. 승인된 항목만 Edit

   • 재진술 수거 시 기존 본문 의미 보존 — 세부 내용을 owner 로 이관했는지, 중복이라 삭제했는지 fix-plan 에 명시한 대로만.
   • high 위험(본문 의미 변경·hub 갱신)은 절대 묶음 적용 금지 — 개별 승인.
   • 적용 중 owner D-row 를 건드리면 PostToolUse 훅(wiki_consistency_check.py --post)이 역참조 충격을 비차단 알림 — 같은 세션에서 반영.

6. 재검사 + 로그 + 요약

   • 적용 후 python3 .claude/hooks/wiki_consistency_check.py --all 재실행. 루프 천장 2회 — 2회 후 잔여 findings 는 보고 후 종료 (다음 /sync 로 이월).

   • wiki/log.md 한 줄: YYYY-MM-DD HH:mm /sync — <대상> → findings n (CRITICAL c / WARN w), 적용 a / 보류 b

   • 최종 요약 funnel:

     agent: sync
     found: <검출 findings 수>
     processed: <적용 + 보류 수>
     dropped: <제외 수 + 사유>
     

규칙

• 무단 자동 수정 금지. fix-plan 의 승인된 항목만 적용하며 사용자 확인 없이 본문을 바꾸지 않는다.
• /lint 와의 경계: 단일 문서 품질(과장/stale/canonical 우회)은 /lint, cross-doc 모순·위임 동기화는 /sync — 서로 중복 검사하지 않는다.
• 검사기가 침묵하는 귀속 모호 케이스(인용자 자신의 DEM 에 있는 D-id)는 Layer 2 의미 대조가 판정한다 — 결정론 출력만으로 "깨끗하다" 단정 금지.