llm-wiki-kit 0.1.4 → 0.1.6

package/src/templates.js

@@ -1,15 +1,98 @@
 import { runtimeVersion } from './version.js';
 
 export function rootAgentsPolicy() {
-  return `\n<!-- llm-wiki-kit:start -->\n## LLM Wiki Policy\n\nThis repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex and Claude Code.\n\n- This block supersedes older OMX/OMC/\`omx_wiki/\` LLM Wiki instructions for this repository.\n- Treat chat memory as temporary; durable project knowledge belongs in \`llm-wiki/\`.\n- \`llm-wiki/raw/\` stores immutable or redacted source material. Do not edit raw source files.\n- \`llm-wiki/wiki/\` stores LLM-maintained knowledge pages such as decisions, architecture, debugging, context, concepts, and queries.\n- Before non-trivial work, use the injected LLM Wiki context and consult \`llm-wiki/wiki/index.md\` when present.\n- Capture reusable decisions, debugging findings, verification commands, and open questions into the wiki.\n- Preserve useful work context, but do not store raw authentication values such as tokens, passwords, or private keys.\n- Mark inference explicitly and preserve contradictions instead of silently overwriting them.\n\n<!-- llm-wiki-kit:end -->\n`;
+  return `\n<!-- llm-wiki-kit:start -->\n## LLM Wiki Policy\n\nThis repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex and Claude Code.\n\n- This block supersedes older OMX/OMC/\`omx_wiki/\` LLM Wiki instructions for this repository.\n- Treat chat memory as temporary; durable project knowledge belongs in \`llm-wiki/\`.\n- \`llm-wiki/raw/\` stores immutable or redacted source material. Do not edit raw source files.\n- \`llm-wiki/wiki/\` stores LLM-maintained knowledge pages such as decisions, architecture, debugging, context, concepts, and queries.\n- \`llm-wiki/wiki/memory.md\` is the short hot index for the most reusable current facts; keep it concise and link to deeper pages.\n- Before non-trivial work, use the injected LLM Wiki context and consult \`llm-wiki/wiki/memory.md\` and \`llm-wiki/wiki/index.md\` when present.\n- Capture reusable decisions, debugging findings, verification commands, and open questions into the wiki.\n- Preserve useful work context, but do not store raw authentication values such as tokens, passwords, or private keys.\n- Mark inference explicitly and preserve contradictions instead of silently overwriting them.\n\n<!-- llm-wiki-kit:end -->\n`;
 }
 
 export function llmWikiAgents() {
-  return `# LLM Wiki Agent Rules\n\nGenerated by llm-wiki-kit ${runtimeVersion()}.\n\n## Purpose\nMaintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.\nThese rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.\n\n## Directories\n- \`raw/\`: immutable or redacted source material. Never edit original source captures.\n- \`wiki/\`: AI-maintained knowledge pages.\n- \`outputs/\`: live Q&A summaries, reports, and generated briefs.\n- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.\n\n## Core Rules\n- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.\n- Do not state unsupported claims as facts.\n- Mark inference explicitly.\n- Add \`source_ids\` or file references for important claims.\n- Update \`wiki/index.md\` and \`wiki/log.md\` whenever new durable knowledge is created.\n- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.\n- Preserve useful work context and redact authentication values before writing durable notes.\n\n## Page Format\nUse YAML frontmatter when creating wiki pages:\n\n\`\`\`yaml\n---\ntitle: \"\"\ntype: \"source | concept | entity | decision | architecture | debugging | context | query | session-log | convention\"\nsource_ids: []\nstatus: \"draft | reviewed | stale\"\nlast_updated: \"YYYY-MM-DD\"\nconfidence: \"high | medium | low\"\n---\n\`\`\`\n\n## Operations\n- ingest: read new raw files, create or update wiki pages, then update \`wiki/index.md\` and \`wiki/log.md\`.\n- query: start from \`wiki/index.md\`, read relevant wiki pages, answer with source references, and save reusable answers.\n- lint: find stale pages, orphan pages, broken wiki links, missing sources, duplicate concepts, contradictions, and missing links.\n`;
+  return `# LLM Wiki Agent Rules
+
+Generated by llm-wiki-kit ${runtimeVersion()}.
+
+## Purpose
+Maintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.
+These rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.
+
+## Directories
+- \`raw/\`: immutable or redacted source material. Never edit original source captures.
+- \`wiki/\`: AI-maintained knowledge pages. \`wiki/memory.md\` is the short hot index injected into hook context.
+- \`outputs/\`: live Q&A summaries, reports, and generated briefs.
+- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.
+
+## Core Rules
+- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.
+- Do not state unsupported claims as facts.
+- Mark inference explicitly.
+- Add \`source_ids\` or file references for important claims.
+- Update \`wiki/memory.md\`, \`wiki/index.md\`, and \`wiki/log.md\` whenever new durable knowledge changes the active project map.
+- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.
+- Preserve useful work context and redact authentication values before writing durable notes.
+
+## Page Format
+Use YAML frontmatter when creating wiki pages:
+
+\`\`\`yaml
+---
+title: ""
+type: "source | concept | entity | decision | architecture | debugging | context | query | session-log | convention"
+source_ids: []
+status: "draft | reviewed | stale"
+last_updated: "YYYY-MM-DD"
+confidence: "high | medium | low"
+memory_type: "semantic | episodic | procedural"
+importance: 1
+last_verified: "YYYY-MM-DD | unknown"
+supersedes: []
+superseded_by: []
+---
+\`\`\`
+
+## Operations
+- ingest: read \`wiki/memory.md\` and \`wiki/index.md\`, ingest new raw files, create or update wiki pages, then update the active map and \`wiki/log.md\`.
+- query: start from \`llm-wiki context "<query>"\` or \`wiki/memory.md\`, read relevant wiki pages, answer with source references, and save reusable answers.
+- lint: run \`llm-wiki lint --workspace <project>\` to find stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts, contradictions, and missing links.
+- consolidate: run \`llm-wiki consolidate --workspace <project>\` after meaningful wiki growth to refresh generated memory/index blocks without overwriting hand-written notes. Default query/context/session-log pages are excluded unless explicitly durable.
+`;
 }
 
 export function indexPage() {
-  return `# LLM Wiki Index\n\nGenerated by llm-wiki-kit.\n\n## Overview\n\nThis is the navigation map for the project living wiki. Keep it short and useful.\n\n## Main Areas\n\n- [Sources](sources/) - source summaries and source IDs.\n- [Concepts](concepts/) - reusable concepts and terminology.\n- [Entities](entities/) - people, systems, modules, vendors, services, and tools.\n- [Decisions](decisions/) - decisions and rationale.\n- [Architecture](architecture/) - system structure and data/control flow.\n- [Debugging](debugging/) - root causes, fixes, verification evidence.\n- [Context](context/) - session continuity and project memory.\n- [Queries](queries/) - durable answers to useful questions.\n\n## Operating Notes\n\n- Start from this index before broad project questions.\n- Read 3-7 relevant pages first; inspect raw sources only when precision matters.\n- Add links using \`[[page-or-topic]]\` when pages become related.\n`;
+  return `# LLM Wiki Index\n\nGenerated by llm-wiki-kit.\n\n## Overview\n\nThis is the navigation map for the project living wiki. Keep it short and useful.\n\n## Main Areas\n\n- [Memory](memory.md) - short hot index and durable entry points.\n- [Sources](sources/) - source summaries and source IDs.\n- [Concepts](concepts/) - reusable concepts and terminology.\n- [Entities](entities/) - people, systems, modules, vendors, services, and tools.\n- [Decisions](decisions/) - decisions and rationale.\n- [Architecture](architecture/) - system structure and data/control flow.\n- [Debugging](debugging/) - root causes, fixes, verification evidence.\n- [Context](context/) - session continuity and project memory.\n- [Queries](queries/) - durable answers to useful questions.\n\n## Operating Notes\n\n- Start from memory and this index before broad project questions.\n- Read 3-7 relevant pages first; inspect raw sources only when precision matters.\n- Add links using \`[[page-or-topic]]\` when pages become related.\n\n<!-- llm-wiki-kit:index-start -->\n## Generated Page Map\n\nRun \`llm-wiki consolidate --workspace <project>\` to refresh this generated block.\n<!-- llm-wiki-kit:index-end -->\n`;
+}
+
+export function memoryPage() {
+  return `---
+title: "LLM Wiki Memory"
+type: "context"
+source_ids: []
+status: "draft"
+last_updated: "unknown"
+confidence: "medium"
+memory_type: "semantic"
+importance: 5
+last_verified: "unknown"
+supersedes: []
+superseded_by: []
+---
+
+# LLM Wiki Memory
+
+Short hot index for project memory. Keep this page compact enough for hook context. Link to deeper pages instead of copying long notes.
+
+## Current Focus
+
+- Add the current project focus here when it becomes durable.
+
+## Durable Entry Points
+
+- [Index](index.md)
+- [Log](log.md)
+
+<!-- llm-wiki-kit:memory-start -->
+## Generated Memory Map
+
+Run \`llm-wiki consolidate --workspace <project>\` to refresh this generated block.
+<!-- llm-wiki-kit:memory-end -->
+`;
 }
 
 export function logPage() {
@@ -18,10 +101,10 @@ export function logPage() {
 
 export function procedure(name) {
   const procedures = {
-    'ingest.md': `# Ingest Procedure\n\n1. Read \`wiki/index.md\` first.\n2. Inspect new material under \`raw/inbox/\` or \`raw/sources/\`.\n3. Create or update \`wiki/sources/<slug>.md\` for each source.\n4. Update related concept, entity, decision, architecture, debugging, or context pages.\n5. Prefer updating existing pages over creating duplicates.\n6. Add source references and confidence.\n7. Update \`wiki/index.md\` and append to \`wiki/log.md\`.\n`,
-    'query.md': `# Query Procedure\n\n1. Start from \`wiki/index.md\`.\n2. Search \`wiki/\` for relevant pages.\n3. Read the smallest useful set of pages first.\n4. Use raw sources only when exact evidence matters.\n5. Separate verified facts from inference.\n6. Save reusable answers into \`wiki/queries/\` and link them from related pages.\n`,
-    'lint.md': `# Lint Procedure\n\nCheck for stale pages, orphan pages, broken wiki links, missing sources, duplicate concepts, unsupported claims, and unresolved contradictions. Prefer producing a review report before automatic edits.\n`,
-    'security.md': `# Security Procedure\n\n- Preserve useful work context for the local project wiki.\n- Do not block reads or tool calls only because they look sensitive.\n- Redact authentication values such as tokens, passwords, and private keys before writing hook payloads or summaries.\n- Full raw transcript capture is disabled by default and must be explicitly enabled by project policy.\n`,
+    'ingest.md': `# Ingest Procedure\n\n1. Read \`wiki/memory.md\` and \`wiki/index.md\` first.\n2. Inspect new material under \`raw/inbox/\` or \`raw/sources/\`.\n3. Create or update \`wiki/sources/<slug>.md\` for each source.\n4. Update related concept, entity, decision, architecture, debugging, or context pages.\n5. Prefer updating existing pages over creating duplicates.\n6. Add source references, confidence, memory type, importance, and verification status.\n7. Update \`wiki/memory.md\` or run \`llm-wiki consolidate\` when durable entry points change.\n8. Update \`wiki/index.md\` and append to \`wiki/log.md\`.\n`,
+    'query.md': `# Query Procedure\n\n1. Start from \`llm-wiki context \"<query>\"\` or read \`wiki/memory.md\` and \`wiki/index.md\`.\n2. Use \`--limit\` or \`--no-expand\` when you need a narrower context pack.\n3. Search \`wiki/\` for relevant pages.\n4. Read the smallest useful set of pages first.\n5. Use raw sources only when exact evidence matters.\n6. Separate verified facts from inference.\n7. Save reusable answers into \`wiki/queries/\` and link them from related pages.\n`,
+    'lint.md': `# Lint Procedure\n\nRun \`llm-wiki lint --workspace <project>\` to check for stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts, unsupported claims, and unresolved contradictions. Prefer producing a review report before automatic edits.\n`,
+    'security.md': `# Security Procedure\n\n- Preserve useful work context for the local project wiki.\n- Do not block reads or tool calls only because they look sensitive.\n- Redact authentication values such as tokens, passwords, bearer credentials, and private keys before writing hook payloads, summaries, or context packs.\n- Run \`llm-wiki lint --workspace <project>\` when sensitive material might have entered wiki pages; secret-like content is reported as an error.\n- Full raw transcript capture is disabled by default and must be explicitly enabled by project policy.\n`,
   };
   return procedures[name] || '';
 }

package/src/update.js

@@ -1,6 +1,7 @@
 import { spawnSync } from 'child_process';
-import { resolve } from 'path';
-import { appendWikiLog, bootstrapProject } from './project.js';
+import { join, resolve } from 'path';
+import { exists } from './fs-utils.js';
+import { appendWikiLog } from './project.js';
 import { install } from './install.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { knownProjectRoots } from './projects.js';
@@ -34,6 +35,10 @@ function assertCommandOk(result, label) {
   throw new Error(`${label} failed: ${detail}`);
 }
 
+async function hasProjectWiki(projectRoot) {
+  return exists(join(projectRoot, 'llm-wiki', 'wiki'));
+}
+
 export function parseRegistryVersion(output) {
   return String(output || '').trim().split(/\s+/).at(-1) || '';
 }
@@ -60,6 +65,7 @@ export async function postUpdate(options = {}) {
     ...options,
     workspace,
     replaceHooks: true,
+    noProject: true,
   });
 
   if (options.all) {
@@ -69,7 +75,7 @@ export async function postUpdate(options = {}) {
       const projectResult = options.noProject
         ? null
         : await applyProjectTemplateUpdate(projectRoot);
-      if (!options.noProject) {
+      if (!options.noProject && await hasProjectWiki(projectRoot)) {
         await appendWikiLog(projectRoot, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
       }
       projects.push({
@@ -89,7 +95,7 @@ export async function postUpdate(options = {}) {
     ? null
     : await applyProjectTemplateUpdate(workspace);
 
-  if (!options.noProject) {
+  if (!options.noProject && await hasProjectWiki(workspace)) {
     await appendWikiLog(workspace, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
   }
 

package/src/wiki-lint.js

@@ -0,0 +1,271 @@
+import { readdir } from 'fs/promises';
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'path';
+import { exists, readText } from './fs-utils.js';
+import { hasSecretLikeText } from './redaction.js';
+import {
+  buildAliasMap,
+  buildWikiGraph,
+  collectWikiPages,
+  normalizeTarget,
+  resolveWikiLink,
+  wikiRoot,
+} from './wiki-model.js';
+
+const VALID_TYPES = new Set([
+  'source',
+  'concept',
+  'entity',
+  'decision',
+  'architecture',
+  'debugging',
+  'context',
+  'query',
+  'session-log',
+  'convention',
+]);
+const VALID_STATUS = new Set(['draft', 'reviewed', 'stale']);
+const VALID_CONFIDENCE = new Set(['high', 'medium', 'low']);
+const VALID_MEMORY_TYPES = new Set(['semantic', 'episodic', 'procedural']);
+const CORE_PAGES = new Set(['wiki/index.md', 'wiki/log.md', 'wiki/memory.md']);
+
+function issue(severity, code, path, message) {
+  return { severity, code, path, message };
+}
+
+function isDateLike(value) {
+  return value === 'unknown' || /^\d{4}-\d{2}-\d{2}$/.test(String(value || ''));
+}
+
+function relativeMarkdownTarget(page, link) {
+  return resolve(dirname(page.absolutePath), link.path);
+}
+
+function isOutsideProject(projectRoot, absolutePath) {
+  const root = resolve(projectRoot);
+  const target = resolve(absolutePath);
+  const rel = relative(root, target);
+  return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+
+function invalidSourceId(sourceId) {
+  const id = String(sourceId || '').trim().replace(/\\/g, '/');
+  if (!id) return true;
+  if (id.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(id)) return true;
+  return id.split('/').includes('..');
+}
+
+function sourceCandidates(projectRoot, sourceId) {
+  const id = String(sourceId || '').trim();
+  if (!id) return [];
+  const rawSources = join(projectRoot, 'llm-wiki', 'raw', 'sources');
+  const rawInbox = join(projectRoot, 'llm-wiki', 'raw', 'inbox');
+  const wikiSources = join(projectRoot, 'llm-wiki', 'wiki', 'sources');
+  const candidates = [
+    join(rawSources, id),
+    join(rawSources, `${id}.md`),
+    join(rawSources, `${id}.txt`),
+    join(rawInbox, id),
+    join(rawInbox, `${id}.md`),
+    join(wikiSources, id),
+    join(wikiSources, `${id}.md`),
+  ];
+  if (id.includes('/') || id.includes('\\')) {
+    candidates.push(join(projectRoot, id));
+    candidates.push(join(projectRoot, 'llm-wiki', id));
+  }
+  return candidates.map((candidate) => resolve(candidate))
+    .filter((candidate) => !isOutsideProject(projectRoot, candidate));
+}
+
+async function sourceExists(projectRoot, sourceId) {
+  for (const candidate of sourceCandidates(projectRoot, sourceId)) {
+    if (await pathExistsNormalized(candidate)) return true;
+  }
+  return false;
+}
+
+function titleKey(page) {
+  return normalizeTarget(page.title);
+}
+
+function isOrphanCandidate(page) {
+  if (CORE_PAGES.has(page.rel)) return false;
+  if (page.rel.startsWith('wiki/queries/')) return false;
+  if (page.rel.startsWith('wiki/context/')) return false;
+  return true;
+}
+
+async function pathExistsNormalized(absolutePath) {
+  if (await exists(absolutePath)) return true;
+  const target = resolve(absolutePath);
+  const parsed = parse(target);
+  const segments = target.slice(parsed.root.length).split(sep).filter(Boolean);
+  let current = parsed.root || sep;
+  for (const segment of segments) {
+    let entries = [];
+    try {
+      entries = await readdir(current);
+    } catch {
+      return false;
+    }
+    const match = entries.find((entry) => entry.normalize('NFC') === segment.normalize('NFC'));
+    if (!match) return false;
+    current = join(current, match);
+  }
+  return true;
+}
+
+export async function runLint(projectRoot, options = {}) {
+  const issues = [];
+  const root = wikiRoot(projectRoot);
+  if (!(await exists(root))) {
+    issues.push(issue('error', 'missing-wiki', 'llm-wiki/wiki', 'wiki directory does not exist'));
+    return lintResult(projectRoot, [], issues);
+  }
+
+  const pages = await collectWikiPages(projectRoot, {
+    maxFiles: options.maxFiles || 1000,
+    maxChars: options.maxChars || 75000,
+  });
+  const byRel = new Map(pages.map((page) => [page.rel, page]));
+  const aliasMap = buildAliasMap(pages);
+  const graph = buildWikiGraph(pages);
+
+  for (const rel of ['wiki/index.md', 'wiki/log.md', 'wiki/memory.md']) {
+    if (!byRel.has(rel)) {
+      issues.push(issue(rel === 'wiki/memory.md' ? 'warning' : 'error', 'missing-core-page', rel, 'core wiki page is missing'));
+    }
+  }
+
+  for (const [alias, matches] of aliasMap.entries()) {
+    if (matches.length > 1 && alias.length > 0) {
+      issues.push(issue('warning', 'duplicate-alias', matches.join(', '), `alias "${alias}" maps to multiple pages`));
+    }
+  }
+
+  const titles = new Map();
+  for (const page of pages) {
+    const key = titleKey(page);
+    if (!key) continue;
+    if (!titles.has(key)) titles.set(key, []);
+    titles.get(key).push(page.rel);
+  }
+  for (const [key, matches] of titles.entries()) {
+    if (matches.length > 1) {
+      issues.push(issue('warning', 'duplicate-title', matches.join(', '), `title "${key}" appears on multiple pages`));
+    }
+  }
+
+  for (const page of pages) {
+    if (hasSecretLikeText(page.content)) {
+      issues.push(issue('error', 'secret-like-content', page.rel, 'page contains token, credential, private-key, or secret-like text'));
+    }
+
+    if (!CORE_PAGES.has(page.rel) && !page.hasFrontmatter) {
+      issues.push(issue('warning', 'missing-frontmatter', page.rel, 'curated wiki page should have YAML frontmatter'));
+      continue;
+    }
+
+    if (page.hasFrontmatter) {
+      if (!page.type) issues.push(issue('warning', 'missing-type', page.rel, 'frontmatter is missing type'));
+      if (page.type && !VALID_TYPES.has(page.type)) issues.push(issue('error', 'invalid-type', page.rel, `invalid type: ${page.type}`));
+      if (!page.status) issues.push(issue('warning', 'missing-status', page.rel, 'frontmatter is missing status'));
+      if (page.status && !VALID_STATUS.has(page.status)) issues.push(issue('error', 'invalid-status', page.rel, `invalid status: ${page.status}`));
+      if (!page.confidence) issues.push(issue('warning', 'missing-confidence', page.rel, 'frontmatter is missing confidence'));
+      if (page.confidence && !VALID_CONFIDENCE.has(page.confidence)) issues.push(issue('error', 'invalid-confidence', page.rel, `invalid confidence: ${page.confidence}`));
+      if (page.frontmatter.memory_type && !VALID_MEMORY_TYPES.has(page.frontmatter.memory_type)) {
+        issues.push(issue('error', 'invalid-memory-type', page.rel, `invalid memory_type: ${page.frontmatter.memory_type}`));
+      }
+      if (page.frontmatter.importance !== undefined) {
+        const importance = Number(page.frontmatter.importance);
+        if (!Number.isInteger(importance) || importance < 1 || importance > 5) {
+          issues.push(issue('error', 'invalid-importance', page.rel, 'importance must be an integer from 1 to 5'));
+        }
+      }
+      if (page.frontmatter.last_updated && !isDateLike(page.frontmatter.last_updated)) {
+        issues.push(issue('warning', 'invalid-last-updated', page.rel, `last_updated should be YYYY-MM-DD or unknown: ${page.frontmatter.last_updated}`));
+      }
+      if (page.frontmatter.last_verified && !isDateLike(page.frontmatter.last_verified)) {
+        issues.push(issue('warning', 'invalid-last-verified', page.rel, `last_verified should be YYYY-MM-DD or unknown: ${page.frontmatter.last_verified}`));
+      }
+      if (page.status === 'stale') {
+        issues.push(issue('warning', 'stale-page', page.rel, 'page is marked stale'));
+      }
+    }
+
+    for (const link of page.wikilinks) {
+      const resolved = resolveWikiLink(aliasMap, link.raw, page);
+      const matches = aliasMap.get(normalizeTarget(link.target)) || [];
+      if (!resolved && matches.length === 0) {
+        issues.push(issue('error', 'broken-wikilink', page.rel, `unresolved wikilink: [[${link.raw}]]`));
+      } else if (!resolved && matches.length > 1) {
+        issues.push(issue('error', 'ambiguous-wikilink', page.rel, `ambiguous wikilink: [[${link.raw}]] -> ${matches.join(', ')}`));
+      }
+    }
+
+    for (const link of page.markdownLinks) {
+      const target = relativeMarkdownTarget(page, link);
+      if (isOutsideProject(projectRoot, target)) {
+        issues.push(issue('warning', 'outside-project-link', page.rel, `markdown link points outside project: ${link.raw}`));
+      } else if (!(await pathExistsNormalized(target))) {
+        issues.push(issue('error', 'broken-markdown-link', page.rel, `missing markdown link target: ${link.raw}`));
+      }
+    }
+
+    for (const sourceId of page.sourceIds) {
+      if (invalidSourceId(sourceId)) {
+        issues.push(issue('error', 'invalid-source-id', page.rel, 'source_id points outside the project or uses unsupported syntax'));
+        continue;
+      }
+      if (!(await sourceExists(projectRoot, sourceId))) {
+        issues.push(issue('warning', 'missing-source', page.rel, `source_id has no matching raw/wiki source file: ${sourceId}`));
+      }
+    }
+  }
+
+  const memoryText = await readText(join(projectRoot, 'llm-wiki', 'wiki', 'memory.md'), '');
+  if (Buffer.byteLength(memoryText, 'utf8') > 25000) {
+    issues.push(issue('warning', 'memory-too-large', 'wiki/memory.md', 'memory.md is larger than the hook excerpt budget'));
+  }
+  for (const page of pages.filter(isOrphanCandidate)) {
+    const backlinks = graph.backlinks.get(page.rel);
+    if (!backlinks || backlinks.size === 0) {
+      issues.push(issue('warning', 'orphan-page', page.rel, 'page is not linked from memory/index and has no backlinks'));
+    }
+  }
+
+  return lintResult(projectRoot, pages, issues);
+}
+
+function lintResult(projectRoot, pages, issues) {
+  const errorCount = issues.filter((item) => item.severity === 'error').length;
+  const warningCount = issues.filter((item) => item.severity === 'warning').length;
+  return {
+    workspace: projectRoot,
+    ok: errorCount === 0,
+    pages: pages.length,
+    issueCount: issues.length,
+    errorCount,
+    warningCount,
+    issues,
+  };
+}
+
+export function formatLintResult(result) {
+  const lines = [
+    'llm-wiki lint',
+    `- workspace: ${result.workspace}`,
+    `- pages: ${result.pages}`,
+    `- errors: ${result.errorCount}`,
+    `- warnings: ${result.warningCount}`,
+  ];
+  if (result.issues.length === 0) {
+    lines.push('- result: ok');
+    return lines.join('\n');
+  }
+  lines.push('', 'Issues:');
+  for (const item of result.issues) {
+    lines.push(`- ${item.severity} ${item.code} ${item.path}: ${item.message}`);
+  }
+  return lines.join('\n');
+}