docgov-cli 0.2.0

package/core/invariants.js

@@ -0,0 +1,126 @@
+import { matchAny } from './util.js';
+
+/**
+ * Invariants as first-class objects (PRD §24).
+ *
+ * This is the highest-value, cheapest feature in the product: a deterministic
+ * path lookup that tells an agent "the code you are about to edit is bound by
+ * these three rules" before it writes a line. No model call; the whole hook,
+ * node startup included, measures around 95 ms on a small repository.
+ */
+
+const ID = /^([A-Z][A-Z0-9]*-[A-Z][A-Z0-9]*-\d{3,4})\b[:.\s-]*(.*)$/;
+
+/**
+ * Parse invariants out of any document. Two accepted forms:
+ *   - a list item or heading starting with an ID: `INV-LIC-001 License belongs to one org.`
+ *   - an explicit frontmatter `invariants:` block
+ * @param {import('./document.js').Document} doc
+ */
+export function parseFrom(doc) {
+  const out = [];
+  const declared = doc.meta.invariants;
+  if (Array.isArray(declared)) {
+    for (const entry of declared) {
+      if (typeof entry === 'string') {
+        const m = ID.exec(entry.trim());
+        if (m) out.push({ id: m[1], statement: m[2].trim(), source: doc.path, paths: [], docId: doc.id });
+      } else if (entry && entry.id) {
+        out.push({ id: String(entry.id), statement: String(entry.statement || entry.text || '').trim(),
+          source: doc.path, paths: toList(entry.paths), docId: doc.id, severity: entry.severity || 'high' });
+      }
+    }
+  }
+
+  const lines = doc.body.split('\n');
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^\s*(```|~~~)/.test(l)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    // unwrap emphasis around a leading ID: "- **INV-LIC-002**: ..." -> "INV-LIC-002: ..."
+    const stripped = l
+      .replace(/^\s*(?:[-*+]\s+|#{1,6}\s+|\d+\.\s+)?/, '')
+      .replace(/^(\*\*|__|\*|_|`)(.+?)\1/, '$2')
+      .trim();
+    const m = ID.exec(stripped);
+    if (!m) continue;
+    if (out.some((o) => o.id === m[1])) continue;
+    let statement = m[2].trim();
+    // A bare ID on its own line takes the next non-empty line as its statement.
+    if (!statement) {
+      for (let j = i + 1; j < Math.min(i + 4, lines.length); j++) {
+        const n = lines[j].trim();
+        if (n) { statement = n.replace(/^[-*+]\s+/, ''); break; }
+      }
+    }
+    out.push({ id: m[1], statement, source: doc.path, paths: [], docId: doc.id, severity: 'high', line: i + 1 });
+  }
+  return out;
+}
+
+/**
+ * Build the global invariant set, attaching the code paths each one governs.
+ * Paths come from the owning document's `documents:` globs or from the matching
+ * config domain, so an invariant is reachable from a changed file.
+ */
+export function collect(docs, cfg) {
+  const all = [];
+  for (const d of docs) {
+    const docPaths = toList(d.meta.documents);
+    const domainPaths = d.domain ? toList(cfg.domains?.[d.domain]?.paths) : [];
+    for (const inv of parseFrom(d)) {
+      inv.paths = inv.paths.length ? inv.paths : [...docPaths, ...domainPaths];
+      inv.domain = d.domain || domainFromId(inv.id);
+      all.push(inv);
+    }
+  }
+  const byId = new Map();
+  const duplicates = [];
+  for (const inv of all) {
+    if (byId.has(inv.id)) duplicates.push({ id: inv.id, sources: [byId.get(inv.id).source, inv.source] });
+    else byId.set(inv.id, inv);
+  }
+  return { invariants: [...byId.values()], duplicates };
+}
+
+function domainFromId(id) {
+  const parts = id.split('-');
+  return parts.length >= 3 ? parts[1].toLowerCase() : null;
+}
+
+function toList(v) { return v == null ? [] : (Array.isArray(v) ? v.map(String) : [String(v)]); }
+
+/**
+ * Invariants that apply to a set of changed files. This is what the PreToolUse
+ * hook injects as additionalContext.
+ * @param {{invariants:object[]}} set
+ * @param {string[]} changedPaths
+ * @param {object} cfg
+ */
+export function applicable(set, changedPaths, cfg) {
+  const out = [];
+  for (const inv of set.invariants) {
+    const globs = inv.paths.length ? inv.paths : domainGlobs(cfg, inv.domain);
+    if (!globs.length) continue;
+    const hit = changedPaths.find((p) => matchAny(p, globs));
+    if (hit) out.push({ ...inv, matched: hit });
+  }
+  return out;
+}
+
+function domainGlobs(cfg, domain) {
+  if (!domain) return [];
+  return toList(cfg.domains?.[domain]?.paths);
+}
+
+export function render(list) {
+  if (!list.length) return '';
+  const lines = ['Invariants that constrain the code you are editing:'];
+  for (const inv of list) {
+    lines.push(`  ${inv.id}  ${inv.statement}`);
+    lines.push(`      source: ${inv.source}${inv.line ? `:${inv.line}` : ''}  (matched ${inv.matched})`);
+  }
+  lines.push('Breaking one of these requires changing its source document in the same change.');
+  return lines.join('\n');
+}

package/core/inventory.js

@@ -0,0 +1,167 @@
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { walk, exists, read, matchAny, matchGlob, toPosix } from './util.js';
+import { Document } from './document.js';
+import { TYPES } from './taxonomy.js';
+import { classify } from './classify.js';
+
+/** Repository signals DocGov reads to infer what documentation *should* exist (PRD §16). */
+const STACK_PROBES = [
+  { id: 'kubernetes', files: ['k8s/**', 'kubernetes/**', '**/*.deployment.yaml', 'helm/**', 'charts/**'], expects: ['operations.deployment', 'operations.infrastructure'] },
+  { id: 'terraform', files: ['**/*.tf', 'terraform/**', 'infra/**/*.tf'], expects: ['operations.infrastructure', 'operations.disaster-recovery'] },
+  { id: 'docker', files: ['Dockerfile', '**/Dockerfile', 'docker-compose*.yml', 'compose.yaml'], expects: ['operations.deployment', 'engineering.development'] },
+  { id: 'openapi', files: ['openapi/**', '**/openapi.{yaml,yml,json}', '**/swagger.{yaml,yml,json}', 'api/**/*.{yaml,yml}'], expects: ['user.reference', 'architecture.integration'] },
+  { id: 'graphql', files: ['**/*.graphql', '**/schema.gql'], expects: ['user.reference'] },
+  { id: 'protobuf', files: ['**/*.proto'], expects: ['user.reference', 'architecture.integration'] },
+  { id: 'db-migrations', files: ['migrations/**', 'db/migrate/**', '**/migrations/*.sql', 'prisma/schema.prisma', 'alembic/**'], expects: ['architecture.data', 'release.migration'] },
+  { id: 'prometheus', files: ['**/prometheus*.y*ml', '**/grafana/**', '**/*dashboard*.json'], expects: ['operations.observability'] },
+  { id: 'ci', files: ['.github/workflows/**', '.gitlab-ci.yml', 'Jenkinsfile', '.circleci/**'], expects: ['operations.deployment', 'engineering.testing'] },
+  { id: 'tests', files: ['test/**', 'tests/**', '**/*.test.*', '**/*_test.go', '**/*_spec.rb', 'spec/**'], expects: ['engineering.testing'] },
+  { id: 'auth', files: ['**/auth/**', '**/authentication/**', '**/session*.{ts,js,py,go,rb}'], expects: ['security.architecture', 'security.authorization', 'security.threat-model'] },
+  { id: 'iac-secrets', files: ['**/*.env.example', '**/secrets*.y*ml', '**/vault/**'], expects: ['security.data-classification', 'operations.configuration'] },
+  { id: 'mobile', files: ['ios/**', 'android/**', '**/*.xcodeproj/**', 'pubspec.yaml'], expects: ['operations.deployment', 'user.getting-started'] },
+  { id: 'monorepo', files: ['pnpm-workspace.yaml', 'turbo.json', 'lerna.json', 'nx.json', 'Cargo.toml'], expects: ['engineering.conventions', 'architecture.overview'] },
+];
+
+const MANIFESTS = ['package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', 'requirements.txt',
+  'Gemfile', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'composer.json', 'mix.exs', 'Package.swift'];
+
+const AGENT_INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.cursorrules', '.windsurfrules',
+  '.claude/rules', '.github/copilot-instructions.md'];
+
+const MD = /\.mdx?$/i;
+
+/**
+ * Full repository sweep. One filesystem walk, everything derived from it.
+ * @param {string} root
+ * @param {object} cfg
+ */
+export function inventory(root, cfg) {
+  const all = walk(root);
+  const include = cfg.documentation.include || ['**/*.md'];
+  const exclude = cfg.documentation.exclude || [];
+
+  const mdPaths = all.filter((p) => MD.test(p) && matchAny(p, include) && !matchAny(p, exclude));
+  const registrations = cfg.documentation?.registrations || {};
+  const documents = mdPaths.map((p) => new Document(root, p, undefined, registrations[p]));
+
+  const contracts = [];
+  for (const glob of (cfg.contracts?.openapi || [])) {
+    for (const p of all) if (matchGlob(p, glob)) contracts.push({ path: p, kind: 'openapi' });
+  }
+  for (const p of all) {
+    if (/\.proto$/.test(p)) contracts.push({ path: p, kind: 'protobuf' });
+    else if (/\.graphql$|\.gql$/.test(p)) contracts.push({ path: p, kind: 'graphql' });
+    else if (/(^|\/)schemas?\/.*\.json$/.test(p)) contracts.push({ path: p, kind: 'json-schema' });
+    else if (/prisma\/schema\.prisma$/.test(p)) contracts.push({ path: p, kind: 'prisma' });
+  }
+
+  const stack = [];
+  for (const probe of STACK_PROBES) {
+    const hits = all.filter((p) => matchAny(p, probe.files));
+    if (hits.length) stack.push({ id: probe.id, evidence: hits.slice(0, 4), count: hits.length, expects: probe.expects });
+  }
+
+  const manifests = MANIFESTS.filter((m) => exists(path.join(root, m)));
+  const agentInstructions = AGENT_INSTRUCTION_FILES.filter((f) => exists(path.join(root, f)));
+
+  const codePaths = all.filter((p) => /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|kt|swift|cs|php|ex|scala|c|cc|cpp|h|hpp)$/.test(p));
+
+  return {
+    root, all, documents, contracts, stack, manifests, agentInstructions, codePaths,
+    counts: {
+      files: all.length, documents: documents.length, contracts: contracts.length,
+      code: codePaths.length, markdownLines: documents.reduce((a, d) => a + d.lines, 0),
+    },
+  };
+}
+
+/**
+ * Documentation the repository's stack implies but which no document covers (PRD §16).
+ *
+ * Uses the *inferred* class, not only the declared one: before `docgov review` runs nothing is
+ * annotated, and reporting an existing README as a missing README would make the first
+ * health score anyone ever sees wrong.
+ */
+export function coverageGaps(inv) {
+  const present = new Set();
+  for (const d of inv.documents) {
+    if (d.type !== 'unknown') { present.add(d.type); continue; }
+    const c = classify(d);
+    if (c.type !== 'unknown' && !c.needsReview) present.add(c.type);
+  }
+  const gaps = [];
+  const seen = new Set();
+  for (const s of inv.stack) {
+    for (const type of s.expects) {
+      if (present.has(type) || seen.has(type)) continue;
+      seen.add(type);
+      gaps.push({ type, label: (TYPES[type] || {}).label || type, because: s.id, evidence: s.evidence[0] });
+    }
+  }
+  // Baseline documents every repository should have regardless of stack.
+  for (const type of ['user.readme', 'architecture.overview', 'engineering.development']) {
+    if (!present.has(type) && !seen.has(type)) {
+      seen.add(type);
+      gaps.push({ type, label: TYPES[type].label, because: 'baseline', evidence: null });
+    }
+  }
+  return gaps;
+}
+
+/** Detected third-party capabilities DocGov should delegate to (PRD §17). */
+export function capabilities(root, pluginNames = []) {
+  const hasBin = (bin) => {
+    try { execFileSync('/bin/sh', ['-c', `command -v ${bin}`], { stdio: 'ignore' }); return true; }
+    catch { return false; }
+  };
+  return discoverCapabilities(root, hasBin, pluginNames);
+}
+
+/**
+ * Capability registry. Normalizes whatever is installed into capability names so
+ * skills ask "who can draw a diagram?" rather than "is mermaid-skill installed?".
+ * @param {string} root
+ * @param {(bin:string)=>boolean} hasBin
+ * @param {string[]} [pluginNames]
+ */
+export function discoverCapabilities(root, hasBin, pluginNames = []) {
+  const caps = {};
+  const add = (cap, provider) => { (caps[cap] ||= []).push(provider); };
+
+  const bins = [
+    ['lychee', 'links.external'], ['markdownlint-cli2', 'markdown.style'], ['markdownlint', 'markdown.style'],
+    ['vale', 'prose.style'], ['spectral', 'openapi.lint'], ['redocly', 'openapi.lint'],
+    ['oasdiff', 'openapi.diff'], ['gh', 'github'], ['git', 'git'], ['jq', 'json'],
+    ['mmdc', 'diagram.mermaid'], ['plantuml', 'diagram.plantuml'], ['typedoc', 'reference.typescript'],
+    ['sphinx-build', 'reference.python'], ['cargo', 'reference.rust'], ['openapi-generator', 'reference.openapi'],
+  ];
+  for (const [bin, cap] of bins) if (hasBin(bin)) add(cap, `bin:${bin}`);
+
+  const configProbes = [
+    ['.vale.ini', 'prose.style', 'vale'], ['.markdownlint.json', 'markdown.style', 'markdownlint'],
+    ['.markdownlint-cli2.jsonc', 'markdown.style', 'markdownlint'],
+    ['.spectral.yaml', 'openapi.lint', 'spectral'], ['lychee.toml', 'links.external', 'lychee'],
+    ['mkdocs.yml', 'site.mkdocs', 'mkdocs'], ['docusaurus.config.js', 'site.docusaurus', 'docusaurus'],
+    ['docs/.vitepress/config.ts', 'site.vitepress', 'vitepress'], ['mint.json', 'site.mintlify', 'mintlify'],
+  ];
+  for (const [f, cap, provider] of configProbes) if (exists(path.join(root, f))) add(cap, `config:${provider}`);
+
+  // Claude Code surface: MCP servers and skills visible from the repo.
+  const mcpFile = path.join(root, '.mcp.json');
+  if (exists(mcpFile)) {
+    try {
+      const servers = Object.keys(JSON.parse(read(mcpFile)).mcpServers || {});
+      for (const s of servers) add('mcp', `mcp:${s}`);
+    } catch { /* malformed .mcp.json is the user's problem, not a DocGov failure */ }
+  }
+  for (const dir of [path.join(root, '.claude', 'skills'), path.join(root, '.claude', 'agents')]) {
+    if (!exists(dir)) continue;
+    for (const name of walk(dir, { maxDepth: 1, includeDirs: true })) {
+      if (!name.includes('/')) add(dir.endsWith('agents') ? 'agent' : 'skill', `local:${name}`);
+    }
+  }
+  for (const p of pluginNames) add('plugin', `plugin:${p}`);
+
+  return caps;
+}

package/core/links.js

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { exists, toPosix } from './util.js';
+import { resolveLink } from './graph.js';
+
+/**
+ * Internal link integrity and repair.
+ *
+ * External link rot is lychee's job when lychee is installed (PRD §42). Internal
+ * links are DocGov's job because they *are* the graph.
+ */
+
+/**
+ * @param {import('./document.js').Document[]} docs
+ * @param {string} root
+ * @param {Set<string>} [allFiles] repo-relative paths that exist
+ */
+export function brokenLinks(docs, root, allFiles) {
+  const out = [];
+  for (const d of docs) {
+    for (const target of d.links().internal) {
+      if (target === '' || target.startsWith('mailto:')) continue;
+      const resolved = resolveLink(d.path, target);
+      const ok = allFiles ? allFiles.has(resolved) : exists(path.join(root, resolved));
+      if (!ok) out.push({ path: d.path, target, resolved });
+    }
+  }
+  return out;
+}
+
+/** Anchors referenced within a document that have no matching heading. */
+export function brokenAnchors(docs) {
+  const out = [];
+  for (const d of docs) {
+    const slugs = new Set(headingSlugs(d.body));
+    for (const a of d.links().anchors) {
+      const s = a.slice(1).toLowerCase();
+      if (s && !slugs.has(s)) out.push({ path: d.path, anchor: a });
+    }
+  }
+  return out;
+}
+
+export function headingSlugs(body) {
+  const out = [];
+  for (const m of body.matchAll(/^#{1,6}[ \t]+(.+?)[ \t]*$/gm)) {
+    out.push(m[1].toLowerCase().replace(/[^\w\s-]/g, '').trim().replace(/\s+/g, '-'));
+  }
+  return out;
+}
+
+/**
+ * Rewrite every internal link that pointed at a moved file.
+ * @param {string} source document text
+ * @param {string} fromDocPath the document's path BEFORE the move set applied
+ * @param {string} toDocPath   the document's path AFTER
+ * @param {Map<string,string>} moves old repo-relative path -> new repo-relative path
+ */
+export function rewriteLinks(source, fromDocPath, toDocPath, moves) {
+  return source.replace(/(\[(?:[^\]\\]|\\.)*\]\()([^)\s]+)((?:\s+"[^"]*")?\))/g, (full, open, target, close) => {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//') || target.startsWith('#')) return full;
+    const [file, hash] = target.split(/(?=#)/);
+    const absOld = resolveLink(fromDocPath, file);
+    const absNew = moves.get(absOld) || absOld;
+    const rel = path.posix.relative(path.posix.dirname(toDocPath), absNew) || path.posix.basename(absNew);
+    const out = rel.startsWith('.') ? rel : (absNew.includes('/') || toDocPath.includes('/') ? rel : rel);
+    return `${open}${toPosix(out)}${hash || ''}${close}`;
+  });
+}
+
+/** Count of inbound internal links per document, for discoverability scoring. */
+export function inboundCounts(docs) {
+  const counts = new Map(docs.map((d) => [d.path, 0]));
+  for (const d of docs) {
+    for (const t of d.links().internal) {
+      const r = resolveLink(d.path, t);
+      if (counts.has(r)) counts.set(r, counts.get(r) + 1);
+    }
+  }
+  return counts;
+}

package/core/migrate.js

@@ -0,0 +1,158 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import * as git from './git.js';
+import * as fm from './frontmatter.js';
+import { rewriteLinks } from './links.js';
+import { frontmatterFor } from './templates.js';
+import { read, write, exists, DocGovError, EXIT } from './util.js';
+import { classify } from './classify.js';
+import { PLAN_DATA_PATH } from './onboard.js';
+
+/**
+ * Transactional migration (PRD §41).
+ *
+ * Two guarantees, both enforced here rather than promised in prose:
+ *   1. nothing runs unless git can revert it;
+ *   2. every internal link is repaired in the same operation as the move, so the
+ *      repository is never left in a half-migrated state.
+ *
+ * Only mechanical actions run. SPLIT, MERGE and EXTRACT rewrite prose, so they
+ * belong to an agent with a human in the loop — not to a file mover.
+ */
+
+const MECHANICAL = new Set(['MOVE', 'ANNOTATE', 'ARCHIVE', 'CREATE']);
+
+/**
+ * @param {{root:string, cfg:object, docs:any[], planData:object, dryRun?:boolean,
+ *          include?:string[], branch?:string|null, useGit?:boolean}} args
+ */
+export function migrate({ root, cfg, docs, planData, dryRun = false, include = [], branch = null, useGit = true }) {
+  const kinds = new Set([...MECHANICAL, ...include.map((k) => k.toUpperCase())]);
+  const actions = planData.actions.filter((a) => kinds.has(a.kind));
+  const ops = [];
+
+  if (useGit && !dryRun) {
+    if (!git.isRepo(root)) throw new DocGovError(
+      'migrate needs a git repository — without it a migration is not revertible. Run `git init` first, or pass --no-git to accept that risk.',
+      EXIT.CONFIG);
+    if (!git.isClean(root)) throw new DocGovError(
+      ['the working tree has uncommitted changes, so a migration would not be separable from them:',
+        ...git.dirtyPaths(root).slice(0, 10).map((p) => `  ${p}`),
+        'Commit or stash these first — `git add -A && git commit -m "chore: adopt DocGov"` is usually what is wanted.',
+      ].join('\n'),
+      EXIT.CONFIG);
+  }
+
+  // ---- plan the file operations
+  const moves = new Map();                        // old rel -> new rel
+  for (const a of actions) {
+    if ((a.kind === 'MOVE' || a.kind === 'ARCHIVE') && a.to && a.to !== a.path) moves.set(a.path, a.to);
+  }
+  // A destination collision would silently destroy a document. Refuse instead.
+  const dests = new Map();
+  for (const [from, to] of moves) {
+    if (dests.has(to)) throw new DocGovError(
+      `migration would put two documents at ${to} (${dests.get(to)} and ${from}). Edit ${PLAN_DATA_PATH} to disambiguate.`);
+    if (exists(path.join(root, to)) && !moves.has(to)) throw new DocGovError(
+      `migration destination ${to} already exists and is not itself being moved.`);
+    dests.set(to, from);
+  }
+
+  const annotate = new Map();
+  for (const a of actions) if (a.kind === 'ANNOTATE') annotate.set(a.path, a);
+
+  const byPath = new Map(docs.map((d) => [d.path, d]));
+
+  // ---- rewrite every document's content once: links + frontmatter together
+  for (const d of docs) {
+    const finalPath = moves.get(d.path) || d.path;
+    let content = d.source;
+
+    const linked = rewriteLinks(content, d.path, finalPath, moves);
+    const linksChanged = linked !== content;
+    content = linked;
+
+    let metaChanged = false;
+    const ann = annotate.get(d.path);
+    if (ann) {
+      const c = classify(d);
+      const type = ann.type && ann.type !== 'unknown' ? ann.type : c.type;
+      if (type !== 'unknown') {
+        const meta = frontmatterFor({
+          type, id: d.meta.id || suggestId(finalPath), title: d.title, cfg,
+          domain: d.domain, visibility: d.meta.visibility, owner: d.owner || ann.owner,
+        });
+        content = fm.patchDocgov(content, meta);
+        metaChanged = true;
+      }
+    }
+
+    if (finalPath !== d.path) {
+      ops.push({ op: 'move', from: d.path, to: finalPath, rewroteLinks: linksChanged, annotated: metaChanged });
+    } else if (linksChanged || metaChanged) {
+      ops.push({ op: 'edit', path: d.path, rewroteLinks: linksChanged, annotated: metaChanged });
+    }
+
+    if (!dryRun) {
+      if (finalPath !== d.path) {
+        if (useGit && git.isRepo(root)) git.move(root, d.path, finalPath);
+        else {
+          fs.mkdirSync(path.dirname(path.join(root, finalPath)), { recursive: true });
+          fs.renameSync(path.join(root, d.path), path.join(root, finalPath));
+        }
+      }
+      if (content !== d.source) write(path.join(root, finalPath), content);
+    }
+  }
+
+  // ---- namespace directories for the chosen layout, so empty namespaces exist on purpose
+  for (const a of actions.filter((x) => x.kind === 'CREATE')) {
+    const dir = a.to.endsWith('/') ? a.to : path.dirname(a.to);
+    ops.push({ op: 'mkdir', path: dir, reason: a.reason, type: a.type });
+    if (!dryRun) fs.mkdirSync(path.join(root, dir), { recursive: true });
+  }
+
+  const deferred = planData.actions.filter((a) => !kinds.has(a.kind));
+
+  return {
+    dryRun, ops, deferred,
+    moved: ops.filter((o) => o.op === 'move').length,
+    edited: ops.filter((o) => o.op === 'edit').length,
+    linksRepaired: ops.filter((o) => o.rewroteLinks).length,
+    annotated: ops.filter((o) => o.annotated).length,
+    branch: branch || null,
+  };
+}
+
+function suggestId(relPath) {
+  return relPath.replace(/\.mdx?$/, '').replace(/^(docs|documentation)\//, '')
+    .replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toLowerCase().slice(0, 60);
+}
+
+/** Verify a migration left the repository coherent. Run immediately after. */
+export function verify({ root, docs, inv }) {
+  const problems = [];
+  const files = new Set(inv.all);
+  for (const d of docs) {
+    for (const t of d.links().internal) {
+      const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(d.path), t));
+      if (!files.has(resolved) && !exists(path.join(root, resolved))) {
+        problems.push({ kind: 'broken-link', path: d.path, target: t });
+      }
+    }
+  }
+  const ids = new Map();
+  for (const d of docs) {
+    if (!d.meta.id) continue;
+    if (ids.has(d.meta.id)) problems.push({ kind: 'duplicate-id', path: d.path, other: ids.get(d.meta.id), id: d.meta.id });
+    else ids.set(d.meta.id, d.path);
+  }
+  return problems;
+}
+
+/** Abort: undo a migration that has not been committed. */
+export function abort(root) {
+  if (!git.isRepo(root)) throw new DocGovError('cannot abort without git');
+  git.resetHard(root, 'HEAD');
+  return true;
+}