link-audit

name	link-audit
description	볼트 그래프 연결성 진단 — 고아 파일, 단절 군집, up 누락, 플랫폼 종속 단절 보고
allowed-tools	Read, Glob, Grep

링크 감사

목적

볼트 전체의 위키링크 연결 상태를 진단하고 문제를 보고한다. 파일을 수정하지 않는다.

절차

1. 위키링크 수집

• 모든 .md 파일에서 [[...]] 패턴을 추출한다.
• 코드펜스( )와 인라인 코드(`) 안의 [[ ]](예: bash [[ "$x" == ... ]])는 스캔에서 제외한다 — 위키링크가 아니라 오탐 원인이다.
• 파일별 발신 링크(outgoing)와 수신 링크(incoming) 수를 집계한다.

NFC 정규화 필수: macOS 파일시스템은 한글 파일명을 NFD(자모 분리)로 저장하지만 마크다운 본문의 링크 텍스트는 보통 NFC(완성형)다. 정규화 없이 바이트 비교하면 멀쩡한 한글 링크가 대량으로 "깨진 링크"로 오탐된다. 파일명 인덱스 구축 시와 링크 텍스트 비교 시 양쪽 모두 unicodedata.normalize('NFC', s)를 적용한다.

링크 대상 매칭 규칙:

• 확장자 유무 양쪽을 허용한다(파일.md ↔ 파일).
• [[경로/파일|별칭#헤딩]] 형태는 |(별칭) · #(헤딩) · 경로 · 이스케이프(\)를 제거한 뒤 basename만으로도 매칭을 시도한다.

import unicodedata, re
from pathlib import Path

def nfc(s: str) -> str:
    return unicodedata.normalize('NFC', s)

def strip_code(text: str) -> str:
    """코드펜스·인라인 코드 제거 후 위키링크만 스캔 대상으로 남긴다."""
    text = re.sub(r'```.*?```', '', text, flags=re.S)
    text = re.sub(r'`[^`\n]*`', '', text)
    return text

def link_basename(link: str) -> str:
    """[[경로/파일|별칭#헤딩]] -> 'file' (확장자·경로·별칭·헤딩 제거)"""
    target = link.split('|')[0].split('#')[0].strip().replace('\\', '')
    name = Path(target).name
    return nfc(name).removesuffix('.md')

# 파일명 인덱스: basename(확장자 제거) -> NFC 정규화
file_index = {nfc(p.stem): p for p in Path('.').rglob('*.md')}

# 링크 존재 여부 = basename 기준, 확장자 유무 무관
def link_exists(link: str) -> bool:
    return link_basename(link) in file_index

2. 고아 파일 탐지

outgoing = 0 AND incoming = 0인 파일을 목록화한다.

제외 대상: 템플릿(tpl-*), .claude/, .obsidian/, 05_library/seasons/2025-pre/

출력:

고아 파일	위치	추천 부모(map/MOC)

3. 단절 군집 탐지

같은 폴더에 3개 이상 파일이 있으면서 어떤 map/index 노트에도 연결되지 않은 군집을 찾는다.

예시:

_system/platform/Discord/ — 파일 4개, map 노트 없음 → "MAP-디스코드 필요"
01_ops/templates/ — 파일 6개, map 노트 없음 → "MAP-템플릿 필요"

4. up: 누락 탐지

frontmatter에 up: 필드가 없는 활성 문서(status: draft | live)를 목록화한다.

5. 플랫폼 종속 단절

_system/platform/ 하위 파일들이 해당 MOC 또는 map에서 링크되고 있는지 확인한다.

6. related: 누락 추천

아래 조건을 모두 충족하는 파일 쌍을 탐지하고 related: 추가를 권고한다:

• 두 파일이 같은 폴더 또는 같은 MOC 하위에 있다
• 둘 다 related: 필드가 없다
• 둘 중 하나가 다른 하나를 본문에서 위키링크로 언급한다

출력 예시:

related: 추가 권고
- 02_sessions/S01-*/plan.md ↔ 02_sessions/S01-*/record.md
- 01_ops/meetings/260312-* ↔ 01_ops/meetings/260313-*

판단 기준: related:는 "같은 주제의 보완 문서" 관계에 권장한다. 형제 세션(plan ↔ record), 연속 회의록, 같은 리서치 주제 문서가 전형적인 케이스다.

7. 허브 과부하 탐지

하나의 노트에 incoming 링크가 20개 이상이면 과부하 경고를 출력한다. 해당 노트를 하위 map으로 분할할 것을 제안한다.

8. 보고서 출력

## 링크 감사 보고

### 요약
- 전체 파일: N개
- 위키링크 사용 파일: N개 (N%)
- 고아 파일: N개
- up: 누락: N개
- 단절 군집: N개
- 허브 과부하: N개

### 고아 파일 (상세)
...

### 단절 군집 (상세)
...

### 권장 map 노트 생성 목록
...

결과 저장

_system/obsidian/audits/YYMMDD-link-audit.md 파일로 저장한다. frontmatter·섹션 구조는 [[_system/obsidian/audits/README|진단 감사 저장 규약]]을 따른다.

필수 필드:

• source_skill: link-audit
• kind: audit
• area: system
• up: "[[MAP-시스템]]"

본문 구조: 요약 → CRITICAL → WARNING → INFO → 이행 항목

주의사항

• 이 스킬은 진단만 한다. 파일 수정은 @graph-weaver 에이전트가 수행한다.
• 05_library/seasons/2025-pre/ 아카이브는 스캔에서 제외한다.