73 lines
4.7 KiB
Markdown
73 lines
4.7 KiB
Markdown
---
|
|
description: "문서 간 모순·동기화 검사 — 결정론 검사기 + 참조 엣지 의미 대조 + fix-plan"
|
|
---
|
|
|
|
사용자가 `/sync [--impact <slug>] [대상 경로, 비우면 전체]` 를 입력하면 아래 절차를 수행한다.
|
|
|
|
문서 간 모순·위임 동기화를 검사하고 수거합니다. (계약: `rules/consistency-contract.md` — Single-Owner + Reference-Only)
|
|
|
|
**대상:** [--impact <slug>] [대상 경로, 비우면 전체] (지정 안 하면 `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` subagent 실행**
|
|
|
|
- 입력: 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. **승인된 항목만 수정 적용**
|
|
|
|
- 재진술 수거 시 **기존 본문 의미 보존** — 세부 내용을 owner 로 이관했는지, 중복이라 삭제했는지 fix-plan 에 명시한 대로만.
|
|
- high 위험(본문 의미 변경·hub 갱신)은 절대 묶음 적용 금지 — 개별 승인.
|
|
- 적용 중 owner D-row 를 건드리면 게이트가 역참조 충격을 검증한다 — `--impact <slug>` 로 직접 확인 후 같은 세션에서 반영.
|
|
|
|
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:
|
|
|
|
```wiki-stats
|
|
agent: sync
|
|
found: <검출 findings 수>
|
|
processed: <적용 + 보류 수>
|
|
dropped: <제외 수 + 사유>
|
|
```
|
|
|
|
## 규칙
|
|
|
|
- **무단 자동 수정 금지.** fix-plan 의 *승인된 항목만* 적용하며 사용자 확인 없이 본문을 바꾸지 않는다.
|
|
- `/lint` 와의 경계: 단일 문서 품질(과장/stale/canonical 우회)은 `/lint`, **cross-doc 모순·위임 동기화는 `/sync`** — 서로 중복 검사하지 않는다.
|
|
- 검사기가 침묵하는 귀속 모호 케이스(인용자 자신의 DEM 에 있는 D-id)는 Layer 2 의미 대조가 판정한다 — 결정론 출력만으로 "깨끗하다" 단정 금지.
|