trustwiki 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,87 @@
+# trustwiki
+
+**Knowledge bases your agent can maintain — without lying to you.**
+
+Every claim cited. Contradictions surfaced. Rot detected.
+
+```bash
+npx trustwiki lint ./your-vault
+```
+
+trustwiki is a provenance linter and an operating method for knowledge bases
+maintained by AI agents. It does **not** build your wiki. It makes sure that
+when your agent does, every claim can be traced to a source, disagreements
+stay visible instead of being silently rewritten, and decay is measured —
+not discovered two months later.
+
+- **12 mechanical checks** — citation grammar, citation targets, uncited-inference ratio, confidence floor, contradiction consistency, broken links, index drift, orphans, placeholders
+- **One config file** — `.trustwiki.json`; nothing configured, everything still runs
+- **Zero dependencies** — Node 18+, one command, JSON output for CI
+- **Proven in production** — [operating stats](proof/STATS.md) from an agent-maintained wiki running since 2026-05
+
+## Why
+
+Agents are already writing knowledge bases. Without a trust layer they
+produce fluent slop: unattributed claims, silent contradiction resolution,
+links that rot. trustwiki is the discipline layer — the linter, the schema,
+and the method.
+
+## Quick start
+
+```bash
+git clone https://github.com/QianJinGuo/trustwiki && cd trustwiki
+npx trustwiki lint templates/demo-vault
+```
+
+You get a report like this (exit code 1 — errors present):
+
+```
+notes/sloppy-page.md
+  L12   error citation.target-missing   citation target not found: sources/ghost.md
+  L14   warn  provenance.excess-inferred 3/5 prose paragraphs uncited (>0.3)
+  L16   warn  placeholder.present        placeholder text: TODO
+  ...
+Σ 3 errors, 5 warnings across 3 files
+```
+
+The eight findings are seeded in `templates/demo-vault` — a vault built to
+fail. `templates/starter-vault` is the same structure built to pass, and is
+the starting point for your own vault.
+
+## The schema
+
+The citation grammar (`^[path:42-58]`), provenance frontmatter, and
+contradiction marking are specified, versioned, and frozen at
+[schema/spec.md](schema/spec.md) (中文版: [spec.zh.md](schema/spec.zh.md)).
+Implementations other than this linter are welcome.
+
+## The method
+
+Four phases — **Ingest, Synthesize, Evolve, Gate** — as an installable agent
+skill: [SKILL.md](SKILL.md). Why each rule exists:
+[docs/method.md](docs/method.md) (中文版: [method.zh.md](docs/method.zh.md)).
+
+## Configuration
+
+Everything is optional. The two keys that matter:
+
+```json
+{
+  "roots": ["notes", "sources"],
+  "index": "index.md",
+  "sourceDir": "sources"
+}
+```
+
+Full reference in [schema/spec.md](schema/spec.md). Rule severities are
+`error | warn | off` per rule; exit codes are `0` clean, `1` errors,
+`2` usage/config.
+
+## Stats
+
+Numbers from the production vault, each with source and verification date:
+[proof/STATS.md](proof/STATS.md).
+
+## License
+
+MIT.

package/README.zh.md

@@ -0,0 +1,82 @@
+# trustwiki
+
+**你的 agent 可以维护的知识库——前提是它不对你撒谎。**
+
+每个论断有引用。矛盾自动现形。腐烂有仪器测。
+
+```bash
+npx trustwiki lint ./your-vault
+```
+
+trustwiki 是一个溯源 linter，加一套面向 agent 维护知识库的操作方法。
+它**不**替你长出 wiki。它保证的是：当你的 agent 动笔时，每个论断能
+追溯到来源，分歧保持可见而不是被悄悄改写，腐烂被仪器测出来——
+而不是两个月后被人撞见。
+
+- **12 条机械检查**——引用文法、引用目标、未引用推断占比、置信度下限、矛盾一致性、断链、索引漂移、孤页、占位符
+- **一个配置文件**——`.trustwiki.json`；什么都不配置也照常能跑
+- **零依赖**——Node 18+，一条命令，JSON 输出可直接进 CI
+- **生产验证**——运行自 2026-05 的 agent 维护知识库的[活体统计](proof/STATS.md)
+
+## 为什么
+
+agent 已经在替人写知识库了。没有信任层，它们产出的是流畅的 slop：
+无出处的论断、被静默抹平的矛盾、烂掉的链接。trustwiki 是纪律层——
+linter、schema、和方法。
+
+## 快速开始
+
+```bash
+git clone https://github.com/QianJinGuo/trustwiki && cd trustwiki
+npx trustwiki lint templates/demo-vault
+```
+
+你会得到这样一份报告（退出码 1——存在 error）：
+
+```
+notes/sloppy-page.md
+  L12   error citation.target-missing   citation target not found: sources/ghost.md
+  L14   warn  provenance.excess-inferred 3/5 prose paragraphs uncited (>0.3)
+  L16   warn  placeholder.present        placeholder text: TODO
+  ...
+Σ 3 errors, 5 warnings across 3 files
+```
+
+这 8 条 findings 是预埋在 `templates/demo-vault` 里的一座"造出来就是为了
+失败"的库。`templates/starter-vault` 是同样结构、造出来就是为了通过的库——
+也是你自己建库的起点。
+
+## 规范
+
+引用文法（`^[path:42-58]`）、provenance frontmatter、矛盾标记，全部
+有版本化的规范：[schema/spec.zh.md](schema/spec.zh.md)（English:
+[spec.md](schema/spec.md)）。欢迎 lint 之外的实现。
+
+## 方法
+
+四个阶段——**Ingest、Synthesize、Evolve、Gate**——封装为可安装的
+agent skill：[SKILL.md](SKILL.md)。每条规则为什么存在：
+[docs/method.zh.md](docs/method.zh.md)（English: [method.md](docs/method.md)）。
+
+## 配置
+
+一切可选。最重要的两个键：
+
+```json
+{
+  "roots": ["notes", "sources"],
+  "index": "index.md",
+  "sourceDir": "sources"
+}
+```
+
+完整参考见 [schema/spec.zh.md](schema/spec.zh.md)。规则级别为
+`error | warn | off`；退出码 `0` 干净、`1` 有 error、`2` 用法/配置错误。
+
+## 活体统计
+
+来自生产库的数字，每个都带来源和核实日期：[proof/STATS.md](proof/STATS.md)。
+
+## 许可
+
+MIT。

package/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: trustwiki
+description: Use when an agent creates or edits pages in a trustwiki-style
+  knowledge base — enforces claim-level citations, contradiction marking,
+  index hygiene, and pre-commit linting so agent-maintained knowledge stays
+  trustworthy. Covers the four-phase method (Ingest → Synthesize → Evolve → Gate).
+---
+
+# trustwiki — the discipline for agent-maintained knowledge bases
+
+## The one rule
+
+**Never write a claim your vault cannot trace.**
+
+Everything below is this rule made mechanical. If you remember only one
+line, remember that one.
+
+## Phase: Ingest
+
+Sources land before opinions do.
+
+1. Create a source page under the source directory (`type: source`) with
+   `source_url`, `ingested`, and `sha256` in frontmatter.
+2. The body holds the source's own words. Never paraphrase into the raw
+   page — the raw page is evidence, and evidence does not get edited.
+
+**Violation consequence:** without the capture-time `sha256`, a silently
+edited source is undetectable. You will cite a page whose claims changed
+under you, and no instrument can tell you.
+
+## Phase: Synthesize
+
+Every synthesized page:
+
+1. Carries at least two outbound wikilinks — pages that reference nothing
+   are orphaned islands, and islands rot first.
+2. Links back to the raw source page it was built from.
+3. Ends every prose paragraph with a citation (`^[path.md:42-58]`).
+4. Marks inference as inference — `provenance_state: inferred` and no fake
+   citations. A citation that does not trace is worse than no citation.
+
+**Violation consequence:** see `templates/demo-vault/notes/sloppy-page.md` —
+one page, eight findings. Fluent text with zero provenance is the failure
+mode this entire method exists to prevent.
+
+## Phase: Evolve
+
+1. Bump `updated` on every edit. Stale dates are lies about freshness.
+2. When two pages disagree, surface the conflict — body callout
+   `> [!contradiction]` **and** frontmatter `contradicted_by`. Never resolve
+   a contradiction by quietly rewriting one side.
+3. Keep the index in sync with the pages. Every page appears in the index;
+   every index entry resolves.
+
+**Violation consequence:** index drift is silent — the vault looks fine
+until someone follows a dead index entry into a page that no longer exists.
+
+## Phase: Gate
+
+Run the linter before declaring any vault operation complete:
+
+```bash
+npx trustwiki lint ./vault
+```
+
+- `exit 0` — done (warnings allowed, but list them).
+- `exit 1` — errors remain; fix them before continuing.
+- Re-run until clean. "It probably passes" is not a gate.
+
+## Config quick reference
+
+See `schema/spec.md` §Checking your vault. Minimum useful config:
+
+```json
+{ "roots": ["notes", "sources"], "index": "index.md", "sourceDir": "sources" }
+```

package/cli/bin.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { loadConfig } from './config.js';
+import { lintVault } from './engine.js';
+import { formatText, formatJson } from './report.js';
+
+function usage() {
+  console.error('usage: trustwiki lint <vault-path> [--json] [--config <file>]');
+}
+
+const args = process.argv.slice(2);
+if (args[0] !== 'lint' || !args[1] || args[1].startsWith('--')) {
+  usage(); process.exit(2);
+}
+const vault = args[1];
+let json = false, configFlag, bad;
+for (let i = 2; i < args.length; i++) {
+  if (args[i] === '--json') json = true;
+  else if (args[i] === '--config') {
+    if (i + 1 >= args.length) { bad = '--config requires a file argument'; break; }
+    configFlag = args[++i];
+  } else { bad = `unknown argument: ${args[i]}`; break; }
+}
+if (bad) { console.error(`trustwiki: ${bad}`); usage(); process.exit(2); }
+const { config, error } = await loadConfig(vault, configFlag);
+if (error) { console.error(`trustwiki: ${error.message}`); process.exit(2); }
+const findings = await lintVault(config.vaultPath, config);
+console.log(json ? formatJson(findings) : formatText(findings));
+// exitCode (not process.exit) so large stdout writes flush before teardown
+process.exitCode = findings.some(f => f.severity === 'error') ? 1 : 0;

package/cli/citations.js

@@ -0,0 +1,45 @@
+const CITATION_RE = /\^\[([^\]\n]*)\]/g;
+const RANGE_ANCHOR = /^(.+)#L(\d+)-L(\d+)$/;
+const RANGE_COLON = /^(.+?):(\d+)-(\d+)$/;
+
+export function parseCitation(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return { ok: false, reason: 'empty citation' };
+  const sources = [];
+  for (const part of trimmed.split(',').map(s => s.trim())) {
+    const s = parseSource(part);
+    if (!s.ok) return s;
+    sources.push(s.source);
+  }
+  return { ok: true, sources };
+}
+
+function parseSource(part) {
+  let m = part.match(RANGE_ANCHOR);
+  if (m) return finish(m[1], Number(m[2]), Number(m[3]), part);
+  m = part.match(RANGE_COLON);
+  if (m) return finish(m[1], Number(m[2]), Number(m[3]), part);
+  return finish(part, null, null, part);
+}
+
+function finish(path, start, end, part) {
+  path = path.trim();
+  if (!path || /\s/.test(path)) return { ok: false, reason: `bad source syntax: "${part}"` };
+  if (start !== null && (start < 1 || end < 1)) return { ok: false, reason: `line numbers must be positive in "${part}"` };
+  if (start !== null && start > end) return { ok: false, reason: `reversed line range in "${part}" (start > end)` };
+  return { ok: true, source: { path, start, end } };
+}
+
+export function findCitations(body, bodyStartLine) {
+  const citations = [], malformed = [];
+  const lines = body.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    for (const m of lines[i].matchAll(CITATION_RE)) {
+      const parsed = parseCitation(m[1]);
+      const at = { raw: m[0], line: bodyStartLine + i };
+      if (parsed.ok) citations.push({ ...at, sources: parsed.sources });
+      else malformed.push({ ...at, reason: parsed.reason });
+    }
+  }
+  return { citations, malformed };
+}

package/cli/config.js

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+export const RULE_IDS = [
+  'frontmatter.required', 'frontmatter.fields', 'placeholder.present',
+  'link.broken', 'link.index-missing', 'link.type-mismatch', 'page.orphan',
+  'citation.malformed', 'citation.target-missing',
+  'provenance.excess-inferred', 'provenance.low-confidence', 'provenance.contradicted',
+];
+
+const DEFAULT_SEVERITY = {
+  'frontmatter.required': 'error', 'frontmatter.fields': 'error', 'placeholder.present': 'warn',
+  'link.broken': 'error', 'link.index-missing': 'warn', 'link.type-mismatch': 'warn', 'page.orphan': 'warn',
+  'citation.malformed': 'error', 'citation.target-missing': 'error',
+  'provenance.excess-inferred': 'warn', 'provenance.low-confidence': 'warn', 'provenance.contradicted': 'warn',
+};
+
+export const DEFAULT_CONFIG = {
+  roots: ['.'],
+  index: null,
+  sourceDir: null,
+  typeByDir: {},
+  minOutboundLinks: 2,
+  inferredThreshold: 0.3,
+  confidenceFloor: 0.5,
+  inferredSkipTypes: ['source'],
+  rules: Object.fromEntries(RULE_IDS.map(id => [id, DEFAULT_SEVERITY[id]])),
+};
+
+const SEVERITIES = new Set(['error', 'warn', 'off']);
+
+export async function loadConfig(vaultPath, explicitPath) {
+  const configPath = explicitPath || join(vaultPath, '.trustwiki.json');
+  let user = {};
+  try {
+    user = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch (e) {
+    if (e.code !== 'ENOENT') return { error: { message: `invalid ${configPath}: ${e.message}` } };
+  }
+  const rules = { ...DEFAULT_CONFIG.rules, ...(user.rules || {}) };
+  const unknown = Object.keys(rules).filter(id => !RULE_IDS.includes(id));
+  if (unknown.length) return { error: { message: `unknown rule id(s): ${unknown.join(', ')}` } };
+  const badSev = Object.entries(rules).filter(([, s]) => !SEVERITIES.has(s));
+  if (badSev.length) return { error: { message: `bad severity for: ${badSev.map(([k]) => k).join(', ')} (use error|warn|off)` } };
+  const merged = { ...DEFAULT_CONFIG, ...user };
+  return { config: {
+    vaultPath: resolve(vaultPath), roots: merged.roots, index: merged.index, sourceDir: merged.sourceDir,
+    typeByDir: merged.typeByDir || {}, minOutboundLinks: merged.minOutboundLinks,
+    inferredThreshold: merged.inferredThreshold, confidenceFloor: merged.confidenceFloor,
+    inferredSkipTypes: merged.inferredSkipTypes || [], rules,
+  } };
+}

package/cli/engine.js

@@ -0,0 +1,99 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { walkVault } from './walk.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { extractWikilinks } from './links.js';
+import { findCitations } from './citations.js';
+import { RULES } from './rules/index.js';
+
+export function normalizeTarget(t) { return t.trim().replace(/\.md$/, ''); }
+
+// Mask fenced code blocks and inline code spans so their contents are never
+// treated as live citations/wikilinks. Character- and line-preserving: every
+// line number in the masked text matches the original file.
+export function maskCode(body) {
+  const lines = body.split('\n');
+  let inFence = false;
+  const masked = lines.map(line => {
+    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; return ''; }
+    if (inFence) return '';
+    return line.replace(/`[^`\n]*`/g, m => '`' + ' '.repeat(Math.max(0, m.length - 2)) + '`');
+  });
+  return masked.join('\n');
+}
+
+function proseParagraphs(masked, bodyStartLine) {
+  const out = [];
+  const countNL = s => (s ? s.split('\n').length - 1 : 0);
+  let offset = 0;
+  for (const part of masked.split(/(\n[ \t]*\n)/)) {
+    const start = offset;
+    offset += part.length; // separators are captured parts too
+    const trimmed = part.trim();
+    if (!trimmed || /^\n[ \t]*\n$/.test(part)) continue;
+    const isProse = !/^(#|>|-\s|\||```|\d+\.\s)/.test(trimmed.split('\n')[0]);
+    const lead = part.slice(0, part.indexOf(trimmed));
+    const startLine = bodyStartLine + countNL(masked.slice(0, start)) + countNL(lead);
+    const lastLine = trimmed.split('\n').pop();
+    out.push({ text: trimmed, startLine, isProse, lastLine });
+  }
+  return out;
+}
+
+export async function lintVault(vaultPath, config) {
+  const files = await walkVault(vaultPath, config.roots, config.index);
+  const model = { vaultPath, config, files: [], indexEntries: null, indexLines: null, degraded: [] };
+  model.filePaths = new Set(files);
+  let indexUnreadable = false;
+  if (config.index) {
+    try {
+      const raw = await readFile(join(vaultPath, config.index), 'utf8');
+      model.indexRaw = raw;
+      model.indexEntries = new Set();
+      model.indexLines = new Map();
+      const indexLines = raw.split('\n');
+      for (let i = 0; i < indexLines.length; i++) {
+        for (const m of indexLines[i].matchAll(/\[\[([^\]|\n]+)/g)) {
+          const norm = normalizeTarget(m[1]);
+          model.indexEntries.add(norm);
+          if (!model.indexLines.has(norm)) model.indexLines.set(norm, i + 1);
+        }
+      }
+    } catch {
+      model.indexEntries = null;
+      indexUnreadable = true; // configured but unreadable — reported, not silent
+    }
+  }
+  for (const rel of files) {
+    const raw = await readFile(join(vaultPath, rel), 'utf8');
+    const text = raw.replace(/\r\n/g, '\n'); // CRLF normalize; line count preserved
+    const fm = parseFrontmatter(text);
+    const bodyStartLine = fm.bodyStartLine;
+    const body = maskCode(fm.body);
+    model.files.push({
+      relPath: rel, text, fm, body: fm.body, bodyStartLine,
+      links: extractWikilinks(body, bodyStartLine),
+      ...findCitations(body, bodyStartLine),
+      paragraphs: proseParagraphs(body, bodyStartLine),
+    });
+  }
+  const findings = [];
+  for (const rule of RULES) {
+    const severity = config.rules[rule.id];
+    if (!severity || severity === 'off') continue;
+    if (rule.needs === 'index' && !model.indexEntries) { model.degraded.push(rule.id); continue; }
+    for (const f of rule.run(model)) {
+      findings.push({
+        severity, rule: rule.id,
+        file: f.file ?? '', line: f.line ?? 1,
+        message: f.message, hint: f.hint ?? '',
+      });
+    }
+  }
+  if (indexUnreadable) {
+    findings.push({ severity: 'warn', rule: 'config.index-unreadable', file: config.index, line: 1,
+      message: 'configured index could not be read; index rules disabled',
+      hint: 'check the path or remove the index key from .trustwiki.json' });
+  }
+  return findings;
+}

package/cli/frontmatter.js

@@ -0,0 +1,33 @@
+export function parseFrontmatter(text) {
+  if (!text.startsWith('---')) return { ok: false, reason: 'missing', body: text, bodyStartLine: 1 };
+  const lines = text.split('\n');
+  // closing --- must be on its own line, not the first
+  let endLine = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { endLine = i; break; } // 0-based index i => 1-based line i+1
+  }
+  if (endLine === -1) return { ok: false, reason: 'unterminated', body: text, bodyStartLine: 1 };
+  const fields = {};
+  let lastKey = null;
+  for (let i = 1; i < endLine; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const m = line.match(/^([A-Za-z0-9_-]+):\s?(.*)$/);
+    if (m && !line.startsWith(' ') && !line.startsWith('-')) {
+      const k = m[1].toLowerCase();
+      const v = m[2].trim();
+      if (v === '' || ['|', '|-', '|+', '>', '>-', '>+'].includes(v)) { fields[k] = ''; lastKey = k; }
+      else { fields[k] = v.replace(/^["']|["']$/g, ''); lastKey = null; }
+    } else if (lastKey && (line.startsWith(' ') || line.startsWith('- '))) {
+      fields[lastKey] = `${fields[lastKey]} ${line.replace(/^(\s+|- )/, '')}`.trim();
+    }
+  }
+  const body = lines.slice(endLine + 1).join('\n');
+  return { ok: true, fields, body, bodyStartLine: endLine + 2 };
+}
+
+export function parseList(value) {
+  if (!value) return [];
+  const inner = String(value).trim().replace(/^\[|\]$/g, '');
+  return inner ? inner.split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean) : [];
+}

package/cli/links.js

@@ -0,0 +1,12 @@
+const WIKILINK_RE = /\[\[([^\]|\n]+)(?:\|([^\]\n]*))?\]\]/g;
+
+export function extractWikilinks(body, bodyStartLine) {
+  const out = [];
+  const lines = body.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    for (const m of lines[i].matchAll(WIKILINK_RE)) {
+      out.push({ target: m[1].trim(), alias: m[2] ? m[2].trim() : null, line: bodyStartLine + i });
+    }
+  }
+  return out;
+}

package/cli/report.js

@@ -0,0 +1,24 @@
+const CONTROL = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+const clean = s => String(s).replace(CONTROL, '');
+
+export function formatText(findings) {
+  const lines = [];
+  const byFile = new Map();
+  for (const f of findings) {
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
+  }
+  for (const [file, fs] of [...byFile.entries()].sort()) {
+    lines.push(clean(file));
+    for (const f of fs.sort((a, b) => a.line - b.line)) {
+      lines.push(`  L${String(f.line).padEnd(4)} ${f.severity.padEnd(5)} ${clean(f.rule).padEnd(30)} ${clean(f.message)}`);
+      if (f.hint) lines.push(`      ↳ ${clean(f.hint)}`);
+    }
+  }
+  const errors = findings.filter(f => f.severity === 'error').length;
+  const warns = findings.filter(f => f.severity === 'warn').length;
+  lines.push(`Σ ${errors} error${errors === 1 ? '' : 's'}, ${warns} warning${warns === 1 ? '' : 's'} across ${byFile.size} file${byFile.size === 1 ? '' : 's'}`);
+  return lines.join('\n');
+}
+
+export function formatJson(findings) { return JSON.stringify(findings, null, 2); }

package/cli/resolve.js

@@ -0,0 +1,25 @@
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+
+export function normalizeTarget(t) { return t.trim().replace(/\.md$/, ''); }
+
+export function resolveTarget(t, cfg) {
+  const cands = [t, `${t}.md`];
+  if (cfg.sourceDir) cands.push(`${cfg.sourceDir}/${t}`, `${cfg.sourceDir}/${t}.md`);
+  for (const root of cfg.roots || []) {
+    if (!root || root === '.') continue;
+    cands.push(`${root}/${t}`, `${root}/${t}.md`);
+  }
+  return cands;
+}
+
+// Contained, regular-file existence check. Rejects `../` escapes, symlink
+// escapes, and directory hits — a citation/probe must never leave the vault.
+export function resolveInVault(vaultPath, cand) {
+  const vaultRoot = resolve(vaultPath);
+  const abs = resolve(vaultRoot, cand);
+  if (abs !== vaultRoot && !abs.startsWith(vaultRoot + sep)) return null;
+  if (!existsSync(abs)) return null;
+  try { if (!statSync(abs).isFile()) return null; } catch { return null; }
+  return abs;
+}

package/cli/rules/citation-malformed.js

@@ -0,0 +1,12 @@
+export const rule = {
+  id: 'citation.malformed',
+  run(model) {
+    const out = [];
+    for (const f of model.files) for (const m of f.malformed) {
+      out.push({ file: f.relPath, line: m.line,
+        message: `malformed citation ${m.raw} — ${m.reason}`,
+        hint: 'grammar: ^[path(:s-e)?(, path…)*] — see schema/spec.md' });
+    }
+    return out;
+  },
+};

package/cli/rules/citation-target-missing.js

@@ -0,0 +1,21 @@
+import { resolveInVault, resolveTarget } from '../resolve.js';
+
+export const rule = {
+  id: 'citation.target-missing',
+  run(model) {
+    const out = [];
+    for (const f of model.files) for (const c of f.citations) {
+      for (const s of c.sources) {
+        const hit = resolveTarget(s.path, model.config)
+          .map(cand => resolveInVault(model.vaultPath, cand))
+          .find(Boolean);
+        if (!hit) out.push({ file: f.relPath, line: c.line,
+          message: `citation target not found: ${s.path}`,
+          hint: model.config.sourceDir
+            ? `create under ${model.config.sourceDir}/ or fix the path`
+            : 'create the source file or fix the path' });
+      }
+    }
+    return out;
+  },
+};

package/cli/rules/frontmatter-fields.js

@@ -0,0 +1,39 @@
+const BASE = ['title', 'created', 'updated', 'type', 'tags'];
+const SOURCE = ['source_url', 'ingested', 'sha256'];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}/;
+const SHA_RE = /^[0-9a-f]{64}$/i;
+const STATES = new Set(['extracted', 'merged', 'inferred', 'ambiguous']);
+
+export const rule = {
+  id: 'frontmatter.fields',
+  run(model) {
+    const out = [];
+    for (const f of model.files) {
+      if (!f.fm.ok) continue;
+      const isSource = f.fm.fields.type === 'source'
+        || (model.config.sourceDir && f.relPath.startsWith(`${model.config.sourceDir}/`));
+      const missing = [...BASE, ...(isSource ? SOURCE : [])].filter(k => !f.fm.fields[k]);
+      if (missing.length) out.push({ file: f.relPath, line: 1,
+        message: `missing frontmatter field(s): ${missing.join(', ')}`,
+        hint: 'see schema/spec.md — Frontmatter' });
+      const bad = [];
+      for (const k of ['created', 'updated']) {
+        if (f.fm.fields[k] && !DATE_RE.test(f.fm.fields[k])) bad.push(`${k} is not an ISO date`);
+      }
+      if (f.fm.fields.provenance_state && !STATES.has(f.fm.fields.provenance_state)) {
+        bad.push(`provenance_state "${f.fm.fields.provenance_state}" is not one of extracted|merged|inferred|ambiguous`);
+      }
+      const conf = Number(f.fm.fields.confidence);
+      if (f.fm.fields.confidence && (Number.isNaN(conf) || conf < 0 || conf > 1)) {
+        bad.push('confidence must be a number between 0 and 1');
+      }
+      if (isSource && f.fm.fields.sha256 && !SHA_RE.test(f.fm.fields.sha256)) {
+        bad.push('sha256 must be 64 hex characters');
+      }
+      if (bad.length) out.push({ file: f.relPath, line: 1,
+        message: `invalid frontmatter value(s): ${bad.join('; ')}`,
+        hint: 'see schema/spec.md — Frontmatter' });
+    }
+    return out;
+  },
+};

package/cli/rules/frontmatter-required.js

@@ -0,0 +1,12 @@
+export const rule = {
+  id: 'frontmatter.required',
+  run(model) {
+    const out = [];
+    for (const f of model.files) {
+      if (!f.fm.ok) out.push({ file: f.relPath, line: 1,
+        message: 'missing or unreadable YAML frontmatter',
+        hint: 'add a --- block with title/created/updated/type/tags' });
+    }
+    return out;
+  },
+};