@kybird/llm-wiki 0.2.0

package/lib/wiki-compile.js

@@ -0,0 +1,362 @@
+// wiki-compile — raw 로그에서 지식 추출/합성/비활성화 + index.md 재구축 + qmd 동기화.
+// 원본: TTSTextViewer/.agents/skills/wiki-compile/scripts/compile.js (2026-07-24 loose 파일 분류 + CRLF fix 포함,
+//       2026-08-21 list 판정 mtime→헤더 날짜 fix 역동기화)
+// 변경점:
+//   - __dirname '../../../../' → findDocRoot()
+//   - 하드코딩 qmdCli 경로 → findQmd()
+//   - "TTSTextViewer 프로젝트의..." 문자열 → config.projectName (null이면 제네릭 문구)
+//   - COLLECTION/ COLLECTION_RAW → config.collections
+//   - 2026-08-29 (개선계획 1-6): compile list/index가 --json 봉투를 지원.
+//     {schemaVersion: 1, kind: 'compile-list'|'compile-index', ...}
+//   - 2026-08-29 (사각지대 수정): 같은 날 append가 미컴파일로 감지되지 않던 결함을
+//     컴파일 상태 해시로 고친다. subagent 설계 리뷰(채택+수정 3건) 반영:
+//     ① list는 읽기전용 — 상태의 유일한 쓰기점은 compile index(전체 재생성, seed 특례 없음)
+//     ② lastCompiled 단조 가드(max) — 시계 오차 머신이 미래로 점프시키지 않게
+//     ③ 키 정렬 + LF 직렬화 — 머신 간 자동 머지 극대화. 충돌 해상도는 자명:
+//        아무 쪽이나 남기고 `compile index` 1회면 현재 raw로부터 결정적으로 재생성된다.
+//     날짜 절(date > lastCompiled)의 역할은 1차 탐지가 아니라 상태 유실 시의 안전망이다.
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { findDocRoot, loadConfig } = require('./find-doc-root');
+const { findQmd } = require('./find-qmd');
+
+const STATE_VERSION = 1;
+
+// 정규화+해시는 읽기(list)와 쓰기(index)가 반드시 이 헬퍼 하나만 쓴다 —
+// 구현 간 불일치로 인한 영구 오탐/누락을 원천 차단한다.
+function contentHash(content) {
+  return crypto.createHash('sha256').update(content.replace(/\r\n/g, '\n')).digest('hex');
+}
+
+function loadCompileState(wikiRoot) {
+  const p = path.join(wikiRoot, 'compile-state.json');
+  if (!fs.existsSync(p)) return null;
+  try {
+    const state = JSON.parse(fs.readFileSync(p, 'utf8').replace(/\r/g, ''));
+    if (!state || state.schemaVersion !== STATE_VERSION) return null;
+    return state;
+  } catch {
+    return null; // 깨진 상태는 없음 취급 — 날짜 규칙(안전망)으로 폴백
+  }
+}
+
+// 상태 재생성 — compile index 말미에서만 호출된다 (컴파일 완료 선언의 기록).
+function writeCompileState(wikiRoot, rawRoot, lastCompiled, previous) {
+  const files = {};
+  for (const f of fs.readdirSync(rawRoot).filter(f => f.endsWith('.md')).sort()) {
+    files[f] = contentHash(fs.readFileSync(path.join(rawRoot, f), 'utf8'));
+  }
+  const state = { schemaVersion: STATE_VERSION, lastCompiled, files };
+  fs.writeFileSync(path.join(wikiRoot, 'compile-state.json'), JSON.stringify(state, null, 2) + '\n');
+  if (!previous) {
+    console.log(`컴파일 상태를 생성했다 — 기존 ${Object.keys(files).length}개 파일을 컴파일된 것으로 간주 (lint가 의미 기반 백스톱).`);
+  }
+  return state;
+}
+
+// "새 로그" 데이터 수집 — 판정: 날짜(안전망) OR 해시 불일치(정밀).
+// 날짜 판정은 파일 mtime이 아니라 로그 헤더 날짜(# YYYY-MM-DD)로 한다 —
+// git checkout이 mtime을 머신마다 갈리는 문제(fd01a03) 재발 방지.
+function collectNewLogs(docRoot) {
+  const wikiRoot = path.join(docRoot, 'wiki');
+  const rawRoot = path.join(docRoot, 'raw');
+  const state = loadCompileState(wikiRoot);
+  const stateMissing = state === null;
+
+  let lastUpdated = '0000-00-00';
+  if (state) {
+    lastUpdated = state.lastCompiled;
+  } else {
+    const indexPath = path.join(wikiRoot, 'index.md');
+    if (fs.existsSync(indexPath)) {
+      const match = fs.readFileSync(indexPath, 'utf8').match(/Last updated: (\d{4}-\d{2}-\d{2})/);
+      if (match) lastUpdated = match[1];
+    }
+  }
+
+  const newLogs = [];
+  if (fs.existsSync(rawRoot)) {
+    for (const f of fs.readdirSync(rawRoot).filter(f => f.endsWith('.md')).sort()) {
+      const filePath = path.join(rawRoot, f);
+      const content = fs.readFileSync(filePath, 'utf8');
+      const header = content.match(/^#\s+(\d{4}-\d{2}-\d{2})/m);
+      const date = header ? header[1] : fs.statSync(filePath).mtime.toISOString().split('T')[0];
+
+      let reason = null;
+      if (date > lastUpdated) {
+        reason = 'new-date';
+      } else if (!stateMissing) {
+        const stored = state.files[f];
+        if (stored === undefined) reason = 'no-entry';
+        else if (stored !== contentHash(content)) reason = 'modified';
+      }
+      if (reason) newLogs.push({ name: f, date, reason });
+    }
+  }
+
+  newLogs.sort((a, b) => a.date.localeCompare(b.date) || a.name.localeCompare(b.name));
+  return { schemaVersion: 1, kind: 'compile-list', lastCompiled: lastUpdated, state: stateMissing ? 'missing' : 'ok', newLogs };
+}
+
+function renderList(data) {
+  console.log(`Last compiled date: ${data.lastCompiled}`);
+  if (data.state === 'missing') {
+    console.log('상태 파일 없음 — 날짜 규칙으로 판정한다 (compile index가 생성).');
+  }
+  console.log('Scanning for new raw logs...');
+
+  if (data.newLogs.length === 0) {
+    console.log('No new logs found.');
+    return;
+  }
+
+  console.log('\nNew/Modified logs to process:');
+  data.newLogs.forEach(f => console.log(`- ${f.name} (${f.date})${f.reason !== 'new-date' ? ` [${f.reason}]` : ''}`));
+}
+
+function rebuildIndex() {
+  const docRoot = findDocRoot();
+  const wikiRoot = path.join(docRoot, 'wiki');
+  const rawRoot = path.join(docRoot, 'raw');
+  const indexPath = path.join(wikiRoot, 'index.md');
+  const config = loadConfig(docRoot);
+
+  if (!fs.existsSync(wikiRoot)) {
+    console.error(`Wiki directory not found: ${wikiRoot}`);
+    process.exit(1);
+  }
+
+  console.log('Rebuilding Wiki Index...');
+
+  const conceptsDir = path.join(wikiRoot, 'concepts');
+  const patternsDir = path.join(wikiRoot, 'patterns');
+  const antipatternsDir = path.join(wikiRoot, 'antipatterns');
+  const answersDir = path.join(wikiRoot, 'answers');
+
+  // 서브디렉토리 분류는 디렉토리 자체가 분류 판정 (이미 물리적으로 정리됨).
+  let concepts = scanDirectory(conceptsDir);
+  let patterns = scanDirectory(patternsDir);
+  let antipatterns = scanDirectory(antipatternsDir);
+  // answers/ — 검색해서 종합한 유용한 답변의 아카이브 (개선계획 1-4).
+  let answers = scanDirectory(answersDir);
+
+  // loose 파일(루트 *.md)은 tags 기반으로 분류 — 파일 이동 없이 인덱스/검색에 반영.
+  // pattern 태그 → Patterns, anti-pattern 태그 → Anti-Patterns, 그 외 → Concepts.
+  // index.md, log.md는 메타 파일이므로 제외.
+  const looseFiles = fs.existsSync(wikiRoot)
+    ? fs.readdirSync(wikiRoot)
+        .filter(f => f.endsWith('.md') && f !== 'index.md' && f !== 'log.md')
+    : [];
+  const looseEntries = looseFiles.map(f => scanEntry(path.join(wikiRoot, f)));
+  looseEntries.forEach(e => {
+    const tagList = e.tags || [];
+    if (tagList.includes('anti-pattern') || tagList.includes('antipattern')) {
+      antipatterns.push(e);
+    } else if (tagList.includes('pattern')) {
+      patterns.push(e);
+    } else {
+      concepts.push(e);
+    }
+  });
+
+  // 알파벳 정렬로 인덱스 안정성 확보 (재실행마다 동일 순서).
+  const sortById = (a, b) => a.id.localeCompare(b.id);
+  concepts.sort(sortById);
+  patterns.sort(sortById);
+  antipatterns.sort(sortById);
+  answers.sort(sortById);
+
+  // index.md 헤더 — projectName이 설정되면 포함, 없으면 제네릭 문구.
+  const headerLine = config.projectName
+    ? `${config.projectName} 프로젝트의 구조화된 지식 베이스입니다. \`doc/raw/\` 로그에서 추출한 핵심 개념과 패턴을 정리했습니다.`
+    : `이 프로젝트의 구조화된 지식 베이스입니다. \`doc/raw/\` 로그에서 추출한 핵심 개념과 패턴을 정리했습니다.`;
+
+  let indexContent = `---\ntags: [index]\n\n# Wiki Index\n\n${headerLine}\n`;
+
+  indexContent = addSection(indexContent, 'Concepts', '개념', concepts);
+  indexContent = addSection(indexContent, 'Patterns', '패턴', patterns);
+  indexContent = addSection(indexContent, 'Anti-Patterns', '안티패턴', antipatterns);
+  indexContent = addSection(indexContent, 'Answers', '답변', answers);
+
+  indexContent += `\n---\n\n## Statistics\n\n`;
+  indexContent += `- Total concepts: ${concepts.length}\n`;
+  indexContent += `- Total patterns: ${patterns.length}\n`;
+  indexContent += `- Total anti-patterns: ${antipatterns.length}\n`;
+  indexContent += `- Total answers: ${answers.length}\n`;
+
+  // 컴파일 상태 — 여기가 유일한 쓰기점. lastCompiled 단조 가드(max)로 시계 오차
+  // 머신이 날짜를 미래로 점프시키지 않게 하고, index.md의 Last updated와 같은 값을 쓴다.
+  const previous = loadCompileState(wikiRoot);
+  const today = new Date().toISOString().split('T')[0];
+  const lastCompiled = previous && previous.lastCompiled > today ? previous.lastCompiled : today;
+  indexContent += `- Last updated: ${lastCompiled}\n`;
+
+  fs.writeFileSync(indexPath, indexContent);
+  console.log(`Index successfully rebuilt at ${indexPath}`);
+  writeCompileState(wikiRoot, rawRoot, lastCompiled, previous);
+
+  return { wikiRoot, rawRoot, config };
+}
+
+// 인덱스 섹션 표 하나. 별칭 열은 검색 어휘 그물 — frontmatter aliases가 여기 실려
+// index.md 전체가 grep/QMD 검색 대상이 된다 (개선계획 1-2).
+function addSection(indexContent, title, headerLabel, entries) {
+  indexContent += `\n---\n\n## ${title}\n\n| ${headerLabel} | 설명 | 별칭 |\n|------|------|------|\n`;
+  entries.forEach(e => {
+    indexContent += `| [[${e.id}]] | ${e.description} | ${(e.aliases || []).join(', ')} |\n`;
+  });
+  return indexContent;
+}
+
+// 첫 문장 추출 — inline code(백틱) 안의 마침표는 무시.
+// 끝 마침표 = 마침표 뒤에 공백+문자(다음 문장 시작)가 오거나, 마침표가 줄 끝.
+function firstSentence(line) {
+  let result = '';
+  let inBacktick = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '`') { inBacktick = !inBacktick; result += ch; continue; }
+    result += ch;
+    if (ch === '.' && !inBacktick) {
+      const rest = line.slice(i + 1);
+      if (/^\s+[A-Z가-힣]/.test(rest) || i === line.length - 1) {
+        return result.trim();
+      }
+    }
+  }
+  return result.trim();
+}
+
+function scanDirectory(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => scanEntry(path.join(dir, f)));
+}
+
+// 단일 파일에서 {id, description, tags, aliases} 추출.
+// description은 YAML description → blockquote 요약 → 첫 문장 순서로.
+// tags는 loose 파일 분류를 위해, aliases는 인덱스 별칭 열을 위해 frontmatter에서 파싱.
+function scanEntry(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const id = path.basename(filePath, '.md');
+  let description = 'No description available.';
+  let tags = [];
+  let aliases = [];
+
+  // YAML frontmatter 추출 (description + tags 모두 이 블록에서).
+  // CRLF 대응: \r?\n 으로 줄바꿈 매칭 (윈도우 체크아웃 시 파일이 CRLF).
+  const yamlMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/m);
+  if (yamlMatch) {
+    const yaml = yamlMatch[1];
+
+    // description (명시적이면 가장 정확)
+    const descMatch = yaml.match(/^description:\s*(.+?)\r?$/m);
+    if (descMatch) {
+      description = descMatch[1].trim().replace(/^["']|["']$/g, '');
+    } else {
+      // description이 없으면 title 다음 첫 paragraph/blockquote에서 첫 문장.
+      const lines = content.split('\n');
+      const titleIndex = lines.findIndex(l => l.startsWith('# '));
+      if (titleIndex !== -1) {
+        for (let i = titleIndex + 1; i < lines.length; i++) {
+          const line = lines[i].trim();
+          if (line.startsWith('> ')) {
+            description = firstSentence(line.slice(2).trim());
+            break;
+          }
+          if (line && !line.startsWith('#') && !line.startsWith('---')) {
+            description = firstSentence(line);
+            break;
+          }
+        }
+      }
+    }
+
+    // tags 파싱 — `[a, b, c]` 형태를 배열로.
+    const tagsMatch = yaml.match(/^tags:\s*\[(.*)\]\r?$/m);
+    if (tagsMatch) {
+      tags = tagsMatch[1].split(',').map(t => t.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    }
+
+    // aliases 파싱 — 같은 개념의 다른 이름들. 인덱스 표에 실려 grep/QMD 검색 어휘가 된다
+    // (쓸 때와 찾을 때 어휘가 달라 못 찾는 문제의 두 번째 그물, 개선계획 1-2).
+    const aliasesMatch = yaml.match(/^aliases:\s*\[(.*)\]\r?$/m);
+    if (aliasesMatch) {
+      aliases = aliasesMatch[1].split(',').map(t => t.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    }
+  }
+
+  return { id, description, tags, aliases };
+}
+
+function syncQmd(ctx) {
+  const { wikiRoot, rawRoot, config } = ctx;
+  const qmdCli = findQmd();
+
+  if (!qmdCli) {
+    console.log('QMD not found, skipping search index sync.');
+    console.log('(Optional) Install qmd for semantic search: npm i @tobilu/qmd');
+    return false;
+  }
+
+  try {
+    const listOutput = execSync(`node "${qmdCli}" collection list`, { encoding: 'utf8' });
+
+    // wiki 콜렉션: 컴파일된 위키. raw 콜렉션: 일일 raw 로그.
+    // search.js는 두 콜렉션을 모두 조회하므로, 둘 다 프로비저닝되어 있어야
+    // semantic search가 wiki + raw 양쪽을 커버함.
+    const collections = [
+      { name: config.collections.wiki, path: wikiRoot },
+      { name: config.collections.raw, path: rawRoot },
+    ];
+
+    for (const { name, path: collPath } of collections) {
+      if (!listOutput.includes(name)) {
+        console.log(`Creating QMD collection '${name}'...`);
+        execSync(`node "${qmdCli}" collection add "${collPath}" --name ${name}`, { encoding: 'utf8', stdio: 'inherit' });
+      }
+    }
+
+    console.log('Updating QMD index...');
+    execSync(`node "${qmdCli}" update`, { encoding: 'utf8', stdio: 'inherit' });
+
+    console.log('Refreshing QMD embeddings...');
+    execSync(`node "${qmdCli}" embed`, { encoding: 'utf8', stdio: 'inherit' });
+
+    console.log('✓ QMD search index synced.');
+    return true;
+  } catch (error) {
+    console.error('QMD sync failed:', error.message);
+    console.error('Wiki index rebuilt successfully, but search index may be stale.');
+    return false;
+  }
+}
+
+function compile(command, options = {}) {
+  if (command === 'list') {
+    const data = collectNewLogs(findDocRoot());
+    // json 모드에서는 텍스트 렌더를 하지 않는다 — 봉투만이 계약이다.
+    if (options.json) console.log(JSON.stringify(data, null, 2));
+    else renderList(data);
+  } else if (command === 'index') {
+    const ctx = rebuildIndex();
+    const qmdSynced = syncQmd(ctx);
+    if (options.json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        kind: 'compile-index',
+        indexPath: path.join(ctx.wikiRoot, 'index.md'),
+        qmdSynced,
+      }, null, 2));
+    }
+  } else {
+    console.log('Usage: llm-wiki compile <list|index>');
+    console.log('  list  - show raw logs modified since last compile');
+    console.log('  index - rebuild wiki index.md and sync QMD search index');
+  }
+}
+
+module.exports = { compile };

package/lib/wiki-lint.js

@@ -0,0 +1,272 @@
+// wiki-lint — 위키 무결성 검사 (broken links, missing metadata, staleness, status 집계,
+// 근거 역매칭, 미컴파일 개념).
+// 원본: TTSTextViewer/.agents/skills/wiki-lint/scripts/lint.js
+// 변경점:
+//   - __dirname '../../../../' → findDocRoot(). 나머지는 이미 범용.
+//   - 2026-08-29 (개선계획 1-1): 근거 역매칭 검증 — karpathy-llm-wiki check_evidence.py 방식.
+//     위키 페이지의 `hash:xxx`(7~40 hex)와 `### Error` 인용 줄을 doc/raw/ 전체에서
+//     문자 그대로 찾지 못하면 위반으로 보고한다. 구조화 필드라 file:line 추적 없이 가능.
+//     grounding 발행 비용을 늘리지 않는다(그들의 file:line 포기 교훈 존중).
+//   - 2026-08-29 (개선계획 1-3): raw 로그의 [[링크]] 빈도를 세어 N회 이상 언급됐는데
+//     위키 페이지가 없는 개념을 "Uncompiled knowledge"로 보고한다.
+//   - 2026-08-29 (개선계획 1-6): 수집과 렌더를 분리. --json이면
+//     {schemaVersion: 1, kind: 'lint-report', ...} 봉투로 출력.
+const fs = require('fs');
+const path = require('path');
+const { findDocRoot } = require('./find-doc-root');
+
+const VALID_STATUSES = new Set(['active', 'deprecated', 'draft', 'superseded', 'resolved']);
+const SIX_MONTHS_MS = 180 * 24 * 60 * 60 * 1000;
+// 이 횟수 이상 raw에서 언급됐는데 위키 페이지가 없으면 컴파일 대기 지식으로 본다.
+const UNCOMPILED_THRESHOLD = 2;
+// ### Error 인용 줄 중 이 길이 미만은 노이즈(헤더, 짧은 토큰)라 비교에서 제외.
+const MIN_QUOTE_LENGTH = 8;
+
+function lint(options = {}) {
+  const docRoot = findDocRoot();
+  const wikiRoot = path.join(docRoot, 'wiki');
+  const rawRoot = path.join(docRoot, 'raw');
+
+  if (!fs.existsSync(wikiRoot)) {
+    console.error(`Wiki directory not found: ${wikiRoot}`);
+    console.error('Run `llm-wiki init` first to scaffold doc/wiki/.');
+    process.exit(1);
+  }
+
+  const report = collectLintReport(wikiRoot, rawRoot);
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+  renderLintReport(report);
+  return report;
+}
+
+function collectLintReport(wikiRoot, rawRoot) {
+  const report = {
+    schemaVersion: 1,
+    kind: 'lint-report',
+    generatedAt: new Date().toISOString(),
+    brokenLinks: [],
+    missingMetadata: [],
+    staleness: [],
+    evidenceViolations: [],
+    uncompiledKnowledge: [],
+    stats: { active: 0, deprecated: 0, draft: 0, superseded: 0, resolved: 0, unknown: 0, concepts: 0, patterns: 0, antipatterns: 0 }
+  };
+
+  // raw 로그 전체를 하나의 문자열로 — 근거 역매칭의 비교 대상 코퍼스.
+  const rawFiles = fs.existsSync(rawRoot) ? getAllFiles(rawRoot).filter(f => f.endsWith('.md')) : [];
+  const rawCorpus = rawFiles.map(f => fs.readFileSync(f, 'utf8')).join('\n');
+
+  // 1. Scan Wiki
+  const allFiles = getAllFiles(wikiRoot).filter(f => f.endsWith('.md') && !f.endsWith('index.md'));
+  const fileMap = new Set(allFiles.map(f => normalizeLinkKey(path.basename(f, '.md'))));
+
+  allFiles.forEach(file => {
+    const content = fs.readFileSync(file, 'utf8');
+    const relPath = path.relative(wikiRoot, file);
+    const isConcept = relPath.includes('concepts');
+    // antipatterns가 'patterns' 부분문자열에 걸리지 않도록 먼저 판정한다.
+    const isPattern = !relPath.includes('antipatterns') && relPath.includes('patterns');
+    const isAntipattern = relPath.includes('antipatterns');
+
+    if (isConcept) report.stats.concepts++;
+    if (isPattern) report.stats.patterns++;
+    if (isAntipattern) report.stats.antipatterns++;
+
+    // Check Metadata
+    const yamlMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+    if (yamlMatch) {
+      const header = yamlMatch[1];
+      const statusMatch = header.match(/status:\s*(\w+)/);
+      const createdMatch = header.match(/created:\s*(\d{4}-\d{2}-\d{2})/);
+
+      if (statusMatch) {
+        const status = statusMatch[1];
+        if (VALID_STATUSES.has(status)) {
+          report.stats[status]++;
+        } else {
+          report.stats.unknown++;
+          report.missingMetadata.push(`${relPath} (unknown status: ${status})`);
+        }
+      } else {
+        report.missingMetadata.push(`${relPath} (missing status)`);
+      }
+
+      // Staleness (Time-based)
+      if (createdMatch) {
+        const createdDate = new Date(createdMatch[1]);
+        if (new Date() - createdDate > SIX_MONTHS_MS) {
+          report.staleness.push(`${relPath} (Created: ${createdMatch[1]}, > 180 days old)`);
+        }
+      }
+
+    } else {
+      report.missingMetadata.push(`${relPath} (missing YAML header)`);
+    }
+
+    // Check Links — handle Obsidian syntax: [[target]], [[target|display]], [[path/target#anchor|display]]
+    // 링크-파일명 대응은 정규화 키로 비교한다 — 에이전트가 [[Title Case]]와
+    // kebab-case 파일명을 섞어 쓰면 오탐이 나기 때문 (2026-08-29 실측).
+    const links = content.match(/\[\[(.+?)\]\]/g);
+    if (links) {
+      links.forEach(link => {
+        const raw = link.slice(2, -2);
+        // Strip display text after pipe: [[target|display]] → target
+        let target = raw.split('|')[0];
+        // Strip anchor after #: [[target#section]] → target
+        target = target.split('#')[0];
+        // Strip path prefix: [[doc/learn/xxx]] → basename
+        target = path.basename(target);
+
+        if (target && !fileMap.has(normalizeLinkKey(target)) && normalizeLinkKey(target) !== 'index') {
+          report.brokenLinks.push(`${relPath} -> [[${raw}]]`);
+        }
+      });
+    }
+
+    // 근거 역매칭 (개선계획 1-1) — raw 코퍼스가 있을 때만 검사.
+    if (rawCorpus) {
+      checkEvidence(content, relPath, rawCorpus, report);
+    }
+  });
+
+  // 미컴파일 개념 (개선계획 1-3) — raw [[링크]] 빈도 vs 위키 페이지 존재.
+  report.uncompiledKnowledge = findUncompiledKnowledge(rawFiles, fileMap);
+
+  return report;
+}
+
+function renderLintReport(report) {
+  console.log(`🩺 Wiki Health Report (${report.generatedAt.split('T')[0]})`);
+  console.log('===========================================');
+  console.log(`📊 Stats: Concepts=${report.stats.concepts}, Patterns=${report.stats.patterns}` +
+    (report.stats.antipatterns > 0 ? `, Anti-Patterns=${report.stats.antipatterns}` : ''));
+  console.log(`📊 Status: Active=${report.stats.active}, Deprecated=${report.stats.deprecated}, Draft=${report.stats.draft}` +
+    (report.stats.superseded > 0 ? `, Superseded=${report.stats.superseded}` : '') +
+    (report.stats.resolved > 0 ? `, Resolved=${report.stats.resolved}` : '') +
+    (report.stats.unknown > 0 ? `, Unknown=${report.stats.unknown}` : ''));
+  console.log('===========================================');
+
+  if (report.brokenLinks.length > 0) {
+    console.log(`\n⚠️  Broken Links (${report.brokenLinks.length}):`);
+    report.brokenLinks.forEach(l => console.log(`  - ${l}`));
+  } else {
+    console.log('\n✅ No broken links found.');
+  }
+
+  if (report.evidenceViolations.length > 0) {
+    console.log(`\n⚠️  Evidence Violations (${report.evidenceViolations.length}) — not found verbatim in doc/raw/:`);
+    report.evidenceViolations.forEach(v => console.log(`  - ${v}`));
+  } else {
+    console.log('\n✅ No evidence violations (all hash refs and Error quotes found in raw logs).');
+  }
+
+  if (report.uncompiledKnowledge.length > 0) {
+    console.log(`\n📝 Uncompiled Knowledge (${report.uncompiledKnowledge.length}) — mentioned ≥${UNCOMPILED_THRESHOLD}x in raw, no wiki page:`);
+    report.uncompiledKnowledge.forEach(u => console.log(`  - [[${u.name}]] (${u.count} mentions)`));
+  }
+
+  if (report.missingMetadata.length > 0) {
+    console.log(`\n⚠️  Missing/Invalid Metadata (${report.missingMetadata.length}):`);
+    report.missingMetadata.forEach(m => console.log(`  - ${m}`));
+  }
+
+  if (report.staleness.length > 0) {
+    console.log(`\n⏰ Stale Pages (> 180 days old, ${report.staleness.length}):`);
+    report.staleness.forEach(s => console.log(`  - ${s}`));
+  }
+}
+
+// 위키 페이지 한 장의 근거(해시 참조 + ### Error 인용)가 raw 코퍼스에
+// 문자 그대로 존재하는지 검사해 위반을 report에 쌓는다.
+function checkEvidence(content, relPath, rawCorpus, report) {
+  // (a) git hash 근거: `hash:fd01a03` 형태. 뒤집어서 raw에서 못 찾으면 유령 근거.
+  const hashRe = /hash:\s*`?([0-9a-fA-F]{7,40})`?/g;
+  let m;
+  while ((m = hashRe.exec(content)) !== null) {
+    const hex = m[1];
+    if (!rawCorpus.includes(hex)) {
+      report.evidenceViolations.push(`${relPath} — hash:${hex} not found in doc/raw/`);
+    }
+  }
+
+  // (b) ### Error 섹션의 인용 줄. 마크다운 장식을 벗긴 뒤 원문 일치를 본다 —
+  //     compile 때 요약으로 바뀌면 걸릴 문자열이 사라졌다는 신호가 된다.
+  for (const quote of extractErrorQuotes(content)) {
+    if (!rawCorpus.includes(quote)) {
+      report.evidenceViolations.push(`${relPath} — Error quote not in doc/raw/: "${truncate(quote, 80)}"`);
+    }
+  }
+}
+
+// ### Error 섹션 본문 줄들을 추출한다. 다음 ### 헤더에서 섹션이 끝난다.
+function extractErrorQuotes(content) {
+  const quotes = [];
+  let inError = false;
+  for (const line of content.split(/\r?\n/)) {
+    if (/^###\s+/.test(line)) {
+      inError = /^###\s+Error\s*$/.test(line.trim());
+      continue;
+    }
+    if (!inError) continue;
+    // 마크다운 장식(리스트 마커, 인용, 감싼 백틱)을 벗겨 원문만 남긴다.
+    const cleaned = line.trim()
+      .replace(/^[-*]\s+/, '')
+      .replace(/^>\s*/, '')
+      .replace(/^`/, '')
+      .replace(/`$/, '')
+      .trim();
+    if (cleaned.length >= MIN_QUOTE_LENGTH) quotes.push(cleaned);
+  }
+  return quotes;
+}
+
+// [[링크]] 대상과 파일명의 동일성을 비교할 때 쓰는 정규화 키.
+// 대소문자·공백/하이픈 차이는 에이전트 작성 드리프트라 같은 개념으로 본다.
+function normalizeLinkKey(name) {
+  return String(name).trim().toLowerCase().replace(/\s+/g, '-');
+}
+
+// raw 로그 전체에서 [[링크]] 빈도를 세고, 위키에 페이지가 없는 잦은 개념을 돌려준다.
+function findUncompiledKnowledge(rawFiles, fileMap) {
+  const linkCount = new Map();
+  for (const file of rawFiles) {
+    const content = fs.readFileSync(file, 'utf8');
+    const links = content.match(/\[\[(.+?)\]\]/g) || [];
+    for (const link of links) {
+      let target = link.slice(2, -2).split('|')[0].split('#')[0];
+      target = path.basename(target);
+      if (!target) continue;
+      const key = normalizeLinkKey(target);
+      linkCount.set(key, { name: target, count: (linkCount.get(key)?.count || 0) + 1 });
+    }
+  }
+  return [...linkCount.entries()]
+    .filter(([key, v]) => v.count >= UNCOMPILED_THRESHOLD && !fileMap.has(key) && key !== 'index')
+    .map(([, v]) => v)
+    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+
+function truncate(s, n) {
+  return s.length > n ? s.slice(0, n) + '…' : s;
+}
+
+function getAllFiles(dir) {
+  let results = [];
+  const list = fs.readdirSync(dir);
+  list.forEach(file => {
+    file = path.join(dir, file);
+    const stat = fs.statSync(file);
+    if (stat && stat.isDirectory()) {
+      if (!file.includes('.obsidian')) results = results.concat(getAllFiles(file));
+    } else {
+      results.push(file);
+    }
+  });
+  return results;
+}
+
+module.exports = { lint };