docgov-cli 0.2.0

package/core/config.js

@@ -0,0 +1,162 @@
+import path from 'node:path';
+import * as yaml from './yaml.js';
+import { TYPES, MODES, VISIBILITY_PATHS, GENERATED_PATHS } from './taxonomy.js';
+import { read, exists, write, merge, DocGovError, findRepoRoot } from './util.js';
+
+export const CONFIG_PATH = '.docgov/config.yaml';
+
+/**
+ * Enforcement profiles per project mode (PRD §9).
+ * `block` lists check ids that may fail a write or CI; everything else warns.
+ * Over-enforcement is the product's main failure mode, so solo blocks almost nothing.
+ */
+export const MODE_PROFILES = {
+  solo: {
+    block: ['generated-edit', 'duplicate-id', 'invalid-yaml'],
+    require_owner: false, require_review: false, classify_new_files: true,
+  },
+  team: {
+    block: ['generated-edit', 'duplicate-id', 'invalid-yaml', 'missing-frontmatter',
+      'unknown-reference', 'broken-link', 'wrong-location'],
+    require_owner: true, require_review: true, classify_new_files: true,
+  },
+  enterprise: {
+    block: ['generated-edit', 'duplicate-id', 'invalid-yaml', 'missing-frontmatter',
+      'unknown-reference', 'broken-link', 'wrong-location', 'visibility-path',
+      'missing-sections', 'hard-limit', 'frozen-edit', 'missing-visibility'],
+    require_owner: true, require_review: true, classify_new_files: true,
+  },
+  'open-source': {
+    block: ['generated-edit', 'duplicate-id', 'invalid-yaml', 'broken-link', 'visibility-path'],
+    require_owner: false, require_review: true, classify_new_files: true,
+  },
+};
+
+function defaultLimits() {
+  const limits = {};
+  for (const [id, t] of Object.entries(TYPES)) {
+    if (t.soft || t.hard) limits[id] = { soft_lines: t.soft, hard_lines: t.hard };
+  }
+  return limits;
+}
+
+function defaultQuality() {
+  const q = {};
+  for (const [id, t] of Object.entries(TYPES)) if (t.quality) q[id] = t.quality;
+  return q;
+}
+
+export function defaults() {
+  return {
+    version: 1,
+    project: { name: null, mode: 'solo', visibility: 'internal', layout: 'compact' },
+    documentation: {
+      root: 'docs',
+      include: ['**/*.md', '**/*.mdx'],
+      // Agent infrastructure is instructions, not documentation. Governing it would
+      // make DocGov police the files that configure DocGov.
+      exclude: ['.claude/**', '.docgov/**', '**/node_modules/**', '**/SKILL.md',
+        '.github/ISSUE_TEMPLATE/**', '**/PULL_REQUEST_TEMPLATE.md', '**/CHANGELOG_UNRELEASED.md'],
+      // Documents governed from here instead of from frontmatter in the file. GitHub renders
+      // YAML frontmatter in Markdown as a table, so the files it surfaces on a project's
+      // front page — README, CONTRIBUTING, SECURITY, CHANGELOG — should not carry any.
+      // path -> the same keys a `docgov:` block would hold.
+      registrations: {},
+    },
+    governance: {
+      canonical_changes_require_review: true,
+      prevent_duplicate_domains: true,
+      enforce: null,            // null = derive from mode profile
+      warn_only: false,
+      max_new_root_docs: 0,     // new top-level *.md beyond the allowlist below
+      // Project-level artifacts that legitimately live at the repository root. A repository
+      // whose own specification is a root document should say so here rather than be nagged
+      // about it on every check.
+      allowed_root_docs: ['README.md', 'CONTRIBUTING.md', 'SECURITY.md', 'CHANGELOG.md',
+        'CLAUDE.md', 'AGENTS.md', 'SUPPORT.md', 'CODE_OF_CONDUCT.md', 'LICENSE.md'],
+    },
+    limits: defaultLimits(),
+    quality: defaultQuality(),
+    visibility_paths: VISIBILITY_PATHS,
+    generated_paths: GENERATED_PATHS,
+    drift: { enabled: true, stale_threshold: 60, lookback: '30 days ago' },
+    generated: { allow_manual_edit: false },
+    contracts: { openapi: ['openapi/**/*.{yaml,yml,json}', 'api/**/openapi.{yaml,yml,json}'] },
+    domains: {},                // domain -> { paths: [...], docs: [...], owner }
+    policy_packs: [],           // V3: paths or file: URLs merged over defaults
+    suppressions_file: '.docgov/suppressions.yaml',
+  };
+}
+
+/** @returns {{root:string, raw:object, cfg:object, initialized:boolean}} */
+export function load(cwd = process.cwd()) {
+  const root = findRepoRoot(cwd);
+  const file = path.join(root, CONFIG_PATH);
+  let raw = {};
+  const initialized = exists(file);
+  if (initialized) {
+    try { raw = yaml.parse(read(file)) || {}; }
+    catch (e) { throw new DocGovError(`${CONFIG_PATH} is not valid: ${e.message}`); }
+  }
+  let cfg = merge(defaults(), raw);
+  // Excludes are a deny-list, so they accumulate rather than replace. Adding one entry
+  // should not silently re-enable governance over agent infrastructure.
+  if (raw.documentation?.exclude) {
+    cfg.documentation.exclude = [...new Set([...defaults().documentation.exclude, ...raw.documentation.exclude])];
+  }
+
+  for (const p of cfg.policy_packs || []) {
+    const abs = path.isAbsolute(p) ? p : path.join(root, p);
+    const packFile = exists(path.join(abs, 'policy.yaml')) ? path.join(abs, 'policy.yaml') : abs;
+    if (!exists(packFile)) throw new DocGovError(`policy pack not found: ${p}`);
+    let pack;
+    try { pack = yaml.parse(read(packFile)) || {}; }
+    catch (e) { throw new DocGovError(`policy pack ${p} is not valid: ${e.message}`); }
+    // Packs layer under local config: org sets the floor, repo keeps the last word.
+    cfg = merge(merge(cfg, pack), raw);
+  }
+
+  if (!MODES.includes(cfg.project.mode))
+    throw new DocGovError(`project.mode must be one of ${MODES.join(', ')} (got ${cfg.project.mode})`);
+
+  // A Claude Code plugin's own components are payload, not documentation. Governing them
+  // would make DocGov police the skills, agents and templates that implement DocGov.
+  if (exists(path.join(root, '.claude-plugin', 'plugin.json'))) {
+    const payload = ['skills/**', 'agents/**', 'hooks/**', 'templates/**', 'lenses/**',
+      'rules/**', 'policy/**', 'commands/**', 'output-styles/**', 'workflows/**'];
+    const ex = cfg.documentation.exclude || [];
+    cfg.documentation.exclude = [...new Set([...ex, ...payload])];
+  }
+
+  const profile = MODE_PROFILES[cfg.project.mode];
+  cfg.governance.enforce = cfg.governance.enforce || profile.block;
+  cfg.profile = profile;
+  return { root, raw, cfg, initialized, file };
+}
+
+export function save(root, raw) {
+  return write(path.join(root, CONFIG_PATH), yaml.stringify(raw));
+}
+
+/** Does this check id block, given mode + warn_only? */
+export function blocks(cfg, checkId) {
+  if (cfg.governance.warn_only) return false;
+  return (cfg.governance.enforce || []).includes(checkId);
+}
+
+export function limitFor(cfg, type) {
+  const l = (cfg.limits || {})[type] || {};
+  const t = TYPES[type] || {};
+  return { soft: l.soft_lines ?? t.soft ?? 0, hard: l.hard_lines ?? t.hard ?? 0 };
+}
+
+export function qualityFor(cfg, type) {
+  return (cfg.quality || {})[type] ?? (TYPES[type] || {}).quality ?? 0;
+}
+
+/** Canonical directory or file for a type under the active layout. */
+export function locationFor(cfg, type) {
+  const t = TYPES[type] || TYPES.unknown;
+  const loc = cfg.project.layout === 'full' ? t.full : (t.compact || t.full);
+  return loc;
+}

package/core/context.js

@@ -0,0 +1,144 @@
+import { AUTHORITY, typeDef } from './taxonomy.js';
+import { collect as collectInvariants, applicable } from './invariants.js';
+
+/**
+ * Context packs (PRD §33).
+ *
+ * A skill injects this with `!`-prefix command substitution, so the pack is the
+ * only documentation tokens the agent pays for. Authority order is the point:
+ * the agent reads the constitution before the guide, never the other way round.
+ */
+
+const DEFAULT_BUDGET = 12000;   // characters, ~3k tokens
+
+/**
+ * @param {{cfg:object, docs:any[], graph:any, topic:string, budget?:number, include?:string[]}} args
+ */
+export function pack({ cfg, docs, graph, topic, budget = DEFAULT_BUDGET, include = null }) {
+  const needle = String(topic || '').toLowerCase();
+  const byId = new Map(docs.map((d) => [d.id, d]));
+
+  const scored = docs.map((d) => ({ doc: d, score: relevance(d, needle, cfg) }))
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  const seedIds = scored.slice(0, 6).map((x) => x.doc.id);
+  // Pull in what the seeds depend on — a TRD without its canonical domain is a trap.
+  const pulled = graph.reach(seedIds, { direction: 'out', rels: ['depends_on', 'derived_from', 'implements', 'generated_from'], maxDepth: 2 });
+
+  const selected = [];
+  const seen = new Set();
+  const push = (doc, why) => {
+    if (!doc || seen.has(doc.id)) return;
+    seen.add(doc.id);
+    selected.push({ doc, why });
+  };
+
+  // Constitution always travels with the pack: it is short and it governs everything.
+  for (const d of docs) if (AUTHORITY[d.authority]?.rank === 0) push(d, 'project constitution');
+  for (const x of scored.slice(0, 8)) push(x.doc, `matches "${topic}"`);
+  for (const [id, info] of pulled) push(byId.get(id), `${info.via} of a matched document`);
+  if (include) for (const id of include) push(byId.get(id), 'explicitly requested');
+
+  selected.sort((a, b) => (AUTHORITY[a.doc.authority]?.rank ?? 9) - (AUTHORITY[b.doc.authority]?.rank ?? 9));
+
+  const invSet = collectInvariants(docs, cfg);
+  const domainPaths = cfg.domains?.[needle]?.paths || [];
+  const invariants = domainPaths.length
+    ? applicable(invSet, domainPaths.map((g) => g.replace(/\*+/g, 'x')), cfg)
+    : invSet.invariants.filter((i) => (i.domain || '').includes(needle) || i.id.toLowerCase().includes(needle));
+
+  const contracts = [...graph.nodes.values()].filter((n) => n.kind === 'contract' &&
+    (n.path.toLowerCase().includes(needle) || seen.has(n.id)));
+
+  return render({ topic, selected, invariants, contracts, budget, cfg });
+}
+
+function relevance(d, needle, cfg) {
+  if (!needle) return 1;
+  let s = 0;
+  if (d.domain && d.domain.toLowerCase() === needle) s += 60;
+  if (d.id.toLowerCase().includes(needle)) s += 40;
+  if (d.path.toLowerCase().includes(needle)) s += 30;
+  if ((d.title || '').toLowerCase().includes(needle)) s += 25;
+  const body = d.body.toLowerCase();
+  const hits = body.split(needle).length - 1;
+  if (hits) s += Math.min(25, 4 + hits * 2);
+  // Authority bonus so the canonical spec outranks a blog-flavoured guide on ties.
+  s += Math.max(0, 8 - (AUTHORITY[d.authority]?.rank ?? 9));
+  return s;
+}
+
+/**
+ * Pack rendering: full body while the budget lasts, then headings-only so the
+ * agent still knows the document exists and can read it on demand.
+ */
+function render({ topic, selected, invariants, contracts, budget }) {
+  const L = [];
+  L.push(`# DocGov context pack: ${topic}`);
+  L.push('');
+  L.push('Authoritative documents for this topic, most authoritative first. A lower-authority');
+  L.push('document may not contradict a higher one. If something here is wrong, fix the document,');
+  L.push('do not work around it.');
+  L.push('');
+
+  if (invariants.length) {
+    L.push('## Invariants in force');
+    L.push('');
+    for (const i of invariants) L.push(`- **${i.id}** ${i.statement}  _(${i.source})_`);
+    L.push('');
+  }
+
+  if (contracts.length) {
+    L.push('## Machine contracts (authoritative over prose)');
+    L.push('');
+    for (const c of contracts) L.push(`- \`${c.path}\` (${c.type})`);
+    L.push('');
+  }
+
+  let used = L.join('\n').length;
+  const truncated = [];
+  for (const { doc, why } of selected) {
+    const header = `## ${doc.title}\n\n\`${doc.path}\` · ${AUTHORITY[doc.authority]?.label || doc.authority} · ${doc.type} · included because it ${why}\n\n`;
+    const bodyText = doc.body.trim();
+    if (used + header.length + bodyText.length < budget) {
+      L.push(header.trimEnd());
+      L.push('');
+      L.push(bodyText);
+      L.push('');
+      used += header.length + bodyText.length;
+    } else {
+      truncated.push(doc);
+    }
+  }
+
+  if (truncated.length) {
+    L.push('## Not included in full (read on demand)');
+    L.push('');
+    for (const doc of truncated) {
+      const heads = doc.sections.slice(0, 8).map((s) => s.title).join(', ');
+      L.push(`- \`${doc.path}\` — ${AUTHORITY[doc.authority]?.label || doc.authority}${heads ? `: ${heads}` : ''}`);
+    }
+    L.push('');
+  }
+
+  L.push('---');
+  L.push(`${selected.length} document(s) considered, ${selected.length - truncated.length} included in full, ${invariants.length} invariant(s).`);
+  return L.join('\n');
+}
+
+/** The agent lens (PRD §11): is this document safe for another agent to act on? */
+export function agentReadiness(doc) {
+  const issues = [];
+  if (!doc.registered) issues.push('no docgov.id — an agent cannot cite or update it reliably');
+  if (doc.type === 'unknown') issues.push('unclassified — an agent cannot tell what authority it carries');
+  if (doc.status === 'draft') issues.push('marked draft but contains no warning in the body');
+  if (!/\n/.test(doc.body.trim())) issues.push('effectively empty');
+  const def = typeDef(doc.type);
+  const missing = doc.missingSections();
+  if (missing.length) issues.push(`missing required sections: ${missing.join(', ')}`);
+  if (/\b(TBD|TODO|FIXME|\?\?\?)\b/.test(doc.body)) issues.push('contains TBD/TODO an agent may read as fact');
+  if (doc.lines > 1200) issues.push('too long to fit a focused agent context without truncation');
+  if (!doc.relationships || Object.keys(doc.relationships).length === 0) issues.push('no relationships — invisible to impact analysis');
+  return { path: doc.path, ready: issues.length === 0, issues };
+}

package/core/document.js

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import * as fm from './frontmatter.js';
+import { TYPES, AUTHORITY, typeDef } from './taxonomy.js';
+import { read, sha, slug, titleCase, toPosix } from './util.js';
+
+/**
+ * A governed document. Built from disk once and passed around; no module
+ * re-reads a file after this point, so the whole engine sees one consistent
+ * snapshot per run.
+ */
+export class Document {
+  /**
+   * @param {string} root
+   * @param {string} rel
+   * @param {string} [source]
+   * @param {object} [externalMeta] registration from config, for files that must not carry
+   *   frontmatter. GitHub renders YAML frontmatter in Markdown as a table, so README,
+   *   CONTRIBUTING, SECURITY and CHANGELOG are governed from the registry instead.
+   */
+  constructor(root, rel, source, externalMeta) {
+    this.root = root;
+    this.path = toPosix(rel);
+    this.source = source ?? read(path.join(root, rel));
+    this.error = null;
+    let parsed;
+    try { parsed = fm.parse(this.source); }
+    catch (e) { this.error = e.message; parsed = { data: {}, body: this.source, hasFrontmatter: true }; }
+    this.frontmatter = parsed.data;
+    this.body = parsed.body;
+    this.hasFrontmatter = parsed.hasFrontmatter;
+    this.meta = this.frontmatter.docgov || externalMeta || {};
+    this.externallyRegistered = !this.frontmatter.docgov && Boolean(externalMeta);
+    this.registered = Boolean(this.meta.id);
+    this.lines = this.source.split('\n').length;
+    this.bodyLines = this.body.split('\n').length;
+    this.hash = sha(this.source);
+    this.sections = fm.sections(this.body);
+    this.title = this.frontmatter.title || fm.firstHeading(this.body) || titleCase(path.basename(rel, path.extname(rel)));
+  }
+
+  get id() { return this.meta.id || slug(this.path.replace(/\.mdx?$/, '').replace(/\//g, '-')); }
+  get type() { return this.meta.type && TYPES[this.meta.type] ? this.meta.type : (this.meta.type || 'unknown'); }
+  get def() { return typeDef(this.type); }
+  get authority() { return this.meta.authority || this.def.authority; }
+  get tier() { return (AUTHORITY[this.authority] || AUTHORITY.historical).tier; }
+  get visibility() { return this.meta.visibility || this.def.visibility || 'internal'; }
+  get status() { return this.meta.status || 'active'; }
+  get domain() { return this.meta.domain || null; }
+  get owner() { return this.meta.owner || null; }
+  get lens() { return this.meta.lens || this.def.lens || 'developer'; }
+  get generationMode() { return (this.meta.generation || {}).mode || (this.def.generated ? 'generated' : 'human-maintained'); }
+  get isGenerated() { return this.generationMode === 'generated'; }
+
+  /** @returns {Record<string,string[]>} */
+  get relationships() {
+    const r = this.meta.relationships || {};
+    const out = {};
+    for (const [k, v] of Object.entries(r)) out[k] = Array.isArray(v) ? v.map(String) : (v == null ? [] : [String(v)]);
+    return out;
+  }
+
+  /** Section titles present, normalized for comparison against required sections. */
+  sectionTitles() { return this.sections.map((s) => normalizeHeading(s.title)); }
+
+  missingSections() {
+    const have = this.sectionTitles();
+    return (this.def.sections || []).filter((req) => {
+      const n = normalizeHeading(req);
+      return !have.some((h) => h === n || h.startsWith(n) || n.startsWith(h));
+    });
+  }
+
+  /** Markdown links, split into internal file refs and external URLs. */
+  links() {
+    const out = { internal: [], external: [], anchors: [] };
+    const re = /\[(?:[^\]\\]|\\.)*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    let m;
+    const body = this.body.replace(/```[\s\S]*?```/g, '').replace(/`[^`\n]*`/g, '');
+    while ((m = re.exec(body))) {
+      const target = m[1];
+      if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//')) out.external.push(target);
+      else if (target.startsWith('#')) out.anchors.push(target);
+      else out.internal.push(target.split('#')[0]);
+    }
+    return out;
+  }
+
+  /** Words for tf-idf similarity. Code fences and frontmatter excluded. */
+  tokens() {
+    if (this._tokens) return this._tokens;
+    const text = this.body.replace(/```[\s\S]*?```/g, ' ').toLowerCase();
+    this._tokens = text.match(/[a-z][a-z0-9_-]{2,}/g) || [];
+    return this._tokens;
+  }
+
+  toRegistryEntry() {
+    const e = { path: this.path, type: this.type, authority: this.authority, visibility: this.visibility };
+    if (this.externallyRegistered) e.registered_in = 'config';
+    if (this.title) e.title = this.title;
+    if (this.domain) e.domain = this.domain;
+    if (this.owner) e.owner = this.owner;
+    if (this.status !== 'active') e.status = this.status;
+    if (this.isGenerated) e.generated = true;
+    e.hash = this.hash;
+    e.lines = this.lines;
+    const rel = this.relationships;
+    if (Object.keys(rel).length) e.relationships = rel;
+    return e;
+  }
+}
+
+/**
+ * Normalize a heading for comparison: drop an ordinal prefix ("1.", "2.1", "Step 3 —",
+ * "IV. Context") and any punctuation. Numbered headings are common enough that not
+ * handling them would make the required-sections gate fire on documents that pass.
+ *
+ * Roman numerals are only stripped when a separator follows them. Without that guard,
+ * `[ivxlc]+` eats the first letter of ordinary words — "Verdict" becomes "erdict",
+ * "Install" becomes "nstall", "Context" becomes "ontext" — and every required section
+ * starting with one of those letters silently stops matching.
+ */
+export function normalizeHeading(title) {
+  let t = String(title).trim();
+  t = t.replace(/^(?:step|phase|part|section)\s+(?:\d+|[ivxlc]+)\b[\s).:\-\u2013\u2014]*/i, '');
+  t = t.replace(/^\d+(?:\.\d+)*[\s).:\-\u2013\u2014]+/, '');
+  t = t.replace(/^[ivxlc]+[.)][\s\-\u2013\u2014]*/i, '');
+  return t.toLowerCase().replace(/[^a-z0-9 ]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+export function loadDocuments(root, relPaths) {
+  return relPaths.map((rel) => new Document(root, rel));
+}

package/core/drift.js

@@ -0,0 +1,225 @@
+import { changedFiles, lastCommitDate, commitsSince, isRepo, diffFor } from './git.js';
+import { codeNodesFor } from './graph.js';
+import { matchAny } from './util.js';
+import { AUTHORITY } from './taxonomy.js';
+import { parseFrom as parseInvariants } from './invariants.js';
+import { MD_RE, CONTRACT_RE, isMappable } from './paths.js';
+
+/**
+ * Drift engine (PRD §22, §23, §30).
+ *
+ * Everything here is deterministic: it answers "which documents are now
+ * unverified?" from the diff and the graph. It never claims to know that a
+ * document's *prose* contradicts the code — that judgement is handed to the
+ * drift-reviewer agent, on the narrowed list this module produces
+ * (FEASIBILITY §3.4). Keeping that line sharp is the product's credibility.
+ */
+
+export const SEVERITY = ['critical', 'high', 'medium', 'low'];
+
+
+/**
+ * @param {{root:string, cfg:object, docs:import('./document.js').Document[], graph:import('./graph.js').Graph, base?:string}} ctx
+ */
+export function analyze({ root, cfg, docs, graph, base = 'HEAD' }) {
+  const findings = [];
+  if (!isRepo(root)) {
+    return { findings, changed: [], usable: false,
+      note: 'not a git repository — drift analysis needs git history' };
+  }
+
+  const changed = changedFiles(root, base);
+  const changedPaths = changed.map((c) => c.path);
+  const changedDocs = new Set(changed.filter((c) => MD_RE.test(c.path)).map((c) => c.path));
+  const byPath = new Map(docs.map((d) => [d.path, d]));
+
+  // ---- Forward drift: implementation moved, its documentation did not.
+  // Every changed non-documentation file is a candidate. Whether it matters is decided by
+  // the graph — if no document claims it, the lookup below finds nothing and costs nothing.
+  const codeChanges = changed.filter((c) => isMappable(c.path) && c.status !== 'D');
+  const impactedByDoc = new Map();
+  for (const c of codeChanges) {
+    for (const node of codeNodesFor(graph, c.path)) {
+      for (const e of graph.in(node.id, 'documents')) {
+        const docNode = graph.nodes.get(e.from);
+        if (!docNode) continue;
+        if (!impactedByDoc.has(docNode.path)) impactedByDoc.set(docNode.path, { docNode, files: [] });
+        impactedByDoc.get(docNode.path).files.push(c.path);
+      }
+    }
+  }
+  for (const [docPath, { docNode, files }] of impactedByDoc) {
+    if (changedDocs.has(docPath)) continue;                     // moved together: no drift
+    const doc = byPath.get(docPath);
+    findings.push({
+      id: null, kind: 'forward', severity: severityFor(docNode.authority, files.length),
+      document: docPath, documentId: docNode.id, documentAuthority: docNode.authority,
+      implementation: files.slice(0, 6), implementationCount: files.length,
+      // The invariants this document states are the part of it that can be objectively
+      // falsified by a code change, so the reviewer agent gets them up front.
+      invariants: doc ? parseInvariants(doc).map((i) => `${i.id} ${i.statement}`).slice(0, 5) : [],
+      why: `${files.length} file(s) this document claims to describe changed; the document did not`,
+      action: `Review ${docPath} against the implementation change, then record the review`,
+      reviewable: true,
+    });
+  }
+
+  // ---- Reverse drift: specification moved, implementation did not.
+  for (const c of changed) {
+    if (!MD_RE.test(c.path)) continue;
+    const doc = byPath.get(c.path);
+    if (!doc) continue;
+    const rank = AUTHORITY[doc.authority]?.rank ?? 9;
+    if (rank > 2) continue;                                      // only intent documents can be ahead of code
+    const globs = [].concat(doc.meta.documents || [], cfg.domains?.[doc.domain]?.paths || []).map(String);
+    if (!globs.length) continue;
+    const codeTouched = changedPaths.some((p) => isMappable(p) && matchAny(p, globs));
+    const testsTouched = changedPaths.some((p) => /(^|\/)(test|tests|spec|__tests__)\//.test(p) || /\.(test|spec)\./.test(p));
+    if (codeTouched) continue;
+    findings.push({
+      id: null, kind: 'reverse', severity: doc.authority === 'constitution' ? 'high' : 'medium',
+      document: c.path, documentId: doc.id, documentAuthority: doc.authority,
+      implementation: globs, implementationCount: 0,
+      why: `specification changed but no implementation change was detected in ${globs.join(', ')}`,
+      action: testsTouched
+        ? 'Tests changed but implementation did not — confirm the change is complete'
+        : 'Implement the specification change, or mark it as planned-only',
+      reviewable: true,
+    });
+  }
+
+  // ---- Contract drift: machine contract moved, derived documentation did not.
+  for (const c of changed) {
+    if (!CONTRACT_RE.test(c.path) || c.status === 'D') continue;
+    const contractNode = [...graph.nodes.values()].find((n) => n.path === c.path);
+    const derived = contractNode
+      ? graph.in(contractNode.id, 'generated_from').concat(graph.in(contractNode.id, 'derived_from'))
+      : [];
+    const stale = derived.map((e) => graph.nodes.get(e.from)).filter((n) => n && !changedDocs.has(n.path));
+    findings.push({
+      id: null, kind: 'contract', severity: stale.length ? 'high' : 'medium',
+      document: stale.length ? stale.map((n) => n.path).join(', ') : '(no derived documentation registered)',
+      documentId: stale[0]?.id ?? null, documentAuthority: 'generated',
+      implementation: [c.path], implementationCount: 1,
+      why: stale.length
+        ? 'machine contract changed; documentation derived from it did not'
+        : 'machine contract changed and nothing is registered as derived from it',
+      action: stale.length ? 'Regenerate derived documentation' : `Register a document with generated_from: [${contractIdOf(c.path)}]`,
+      reviewable: true,
+    });
+  }
+
+  // ---- Dependency drift: a document's declared dependency moved ahead of it.
+  for (const d of docs) {
+    for (const dep of d.relationships.depends_on || []) {
+      const depNode = graph.nodes.get(dep);
+      if (!depNode || !changedDocs.has(depNode.path) || changedDocs.has(d.path)) continue;
+      findings.push({
+        id: null, kind: 'dependency', severity: 'low',
+        document: d.path, documentId: d.id, documentAuthority: d.authority,
+        implementation: [depNode.path], implementationCount: 1,
+        why: `depends_on ${dep}, which changed in this diff`,
+        action: `Check ${d.path} still agrees with ${depNode.path}`,
+        reviewable: true,
+      });
+    }
+  }
+
+  assignIds(findings);
+  findings.sort((a, b) => SEVERITY.indexOf(a.severity) - SEVERITY.indexOf(b.severity) || a.document.localeCompare(b.document));
+  return { findings, changed, usable: true };
+}
+
+function contractIdOf(p) { return p.replace(/\.[^.]+$/, '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toLowerCase(); }
+
+function severityFor(authority, fileCount) {
+  const rank = AUTHORITY[authority]?.rank ?? 9;
+  if (rank <= 1) return fileCount >= 3 ? 'critical' : 'high';
+  if (rank <= 2) return fileCount >= 5 ? 'high' : 'medium';
+  if (rank === 5) return 'high';            // generated docs falling behind is mechanical and always fixable
+  return fileCount >= 5 ? 'medium' : 'low';
+}
+
+/** Stable ids so suppressions survive re-runs. */
+function assignIds(findings) {
+  for (const f of findings) {
+    const basis = `${f.kind}:${f.document}:${(f.implementation || []).join(',')}`;
+    let h = 0;
+    for (let i = 0; i < basis.length; i++) h = (h * 31 + basis.charCodeAt(i)) >>> 0;
+    f.id = `DRIFT-${String(h % 100000).padStart(5, '0')}`;
+  }
+}
+
+/**
+ * Semantic staleness (PRD §30). Not "last edited > 90 days" — a correct document
+ * can sit untouched for years. Risk accrues from things that changed *around* it.
+ */
+export function staleness({ root, cfg, docs, graph, since = '180 days ago' }) {
+  const out = [];
+  if (!isRepo(root)) return out;
+  for (const d of docs) {
+    const signals = [];
+    let risk = 0;
+    const docCommits = commitsSince(root, d.path, since).length;
+    const docLast = lastCommitDate(root, d.path);
+
+    const globs = [].concat(d.meta.documents || [], cfg.domains?.[d.domain]?.paths || []).map(String);
+    let codeCommits = 0;
+    for (const g of globs) {
+      codeCommits += commitsSince(root, globToPathspec(g), since).length;
+    }
+    if (codeCommits > 0 && docCommits === 0) {
+      risk += Math.min(55, 10 + codeCommits * 5);
+      signals.push(`${codeCommits} implementation commits since last documentation change`);
+    }
+
+    for (const dep of d.relationships.depends_on || []) {
+      const n = graph.nodes.get(dep);
+      if (!n) continue;
+      const depLast = lastCommitDate(root, n.path);
+      if (depLast && docLast && depLast > docLast) { risk += 12; signals.push(`dependency ${dep} is newer`); }
+    }
+    for (const src of d.relationships.generated_from || []) {
+      const n = graph.nodes.get(src);
+      if (!n) continue;
+      const srcLast = lastCommitDate(root, n.path);
+      if (srcLast && docLast && srcLast > docLast) { risk += 25; signals.push(`source contract ${src} is newer`); }
+    }
+    if (d.status === 'draft') { risk += 10; signals.push('still marked draft'); }
+    const cadence = d.meta.review?.cadence;
+    if (cadence && docLast) {
+      const days = parseCadence(cadence);
+      if (days && daysSince(docLast) > days) {
+        risk += 20;
+        signals.push(`review cadence ${cadence} elapsed (${daysSince(docLast)} days since last change)`);
+      }
+    }
+    if (risk > 0) out.push({ path: d.path, id: d.id, risk: Math.min(100, risk), signals, lastChanged: docLast });
+  }
+  return out.sort((a, b) => b.risk - a.risk);
+}
+
+function globToPathspec(g) { return g.replace(/\*\*\/?$/, '').replace(/\/$/, '') || '.'; }
+function parseCadence(c) {
+  const m = /^(\d+)\s*([dwmy])/i.exec(String(c));
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return { d: n, w: n * 7, m: n * 30, y: n * 365 }[m[2].toLowerCase()];
+}
+function daysSince(isoDate) {
+  return Math.floor((Date.now() - new Date(isoDate).getTime()) / 86400000);
+}
+
+/**
+ * Narrow the review surface for the drift-reviewer agent and hand it the exact
+ * diff hunks it needs — so the model reads kilobytes, not the repository.
+ */
+export function reviewPackets({ root, findings, base = 'HEAD', limit = 12 }) {
+  return findings.filter((f) => f.reviewable).slice(0, limit).map((f) => ({
+    id: f.id, kind: f.kind, severity: f.severity, document: f.document,
+    why: f.why,
+    diffs: (f.implementation || []).slice(0, 3).map((p) => ({ path: p, diff: truncate(diffFor(root, p, base), 3000) })),
+  }));
+}
+
+function truncate(s, n) { return s.length <= n ? s : `${s.slice(0, n)}\n... (${s.length - n} more characters)`; }