@rungs/cli 0.1.0

package/src/engines3.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+import { matchAny } from './glob.ts';
+import type { Engine, Finding } from './engines.ts';
+
+const read = (root: string, rel: string) => {
+  try {
+    return readFileSync(join(root, rel), 'utf8');
+  } catch {
+    return '';
+  }
+};
+const expand = (files: string[], p: string[] | undefined, f: string[] = []) =>
+  [...new Set((p ?? f).flatMap((x) => matchAny(files, x)))];
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** An exemption marker is ignored unless it states a reason. */
+const exempted = (text: string, marker?: string) =>
+  !!marker && new RegExp(`${escapeRe(marker)}\\s*\\S`).test(text);
+
+/** Rows of the first markdown table under a heading containing `near`. */
+function tableRows(text: string, near?: string): Record<string, string>[] {
+  const lines = text.split('\n');
+  const rows: Record<string, string>[] = [];
+  let heading = '';
+  for (let i = 0; i < lines.length; i++) {
+    if (/^#{1,6}\s/.test(lines[i])) heading = lines[i];
+    if (!/^\s*\|/.test(lines[i]) || !/^\s*\|[\s:|-]+\|/.test(lines[i + 1] ?? '')) continue;
+    if (near && !heading.toLowerCase().includes(near.toLowerCase())) continue;
+    const cells = (l: string) => l.trim().replace(/^\||\|$/g, '').split('|').map((s) => s.trim());
+    const headers = cells(lines[i]);
+    for (let j = i + 2; j < lines.length && /^\s*\|/.test(lines[j]); j++) {
+      const c = cells(lines[j]);
+      rows.push(Object.fromEntries(headers.map((h, k) => [h, c[k] ?? ''])));
+    }
+    i = lines.length;
+  }
+  return rows;
+}
+
+const clean = (v = '') => v.replace(/[`*\[\]]/g, '').trim();
+
+/** Words distinctive enough to indicate a topic is being restated, not mentioned. */
+function terms(topic: string): string[] {
+  const stop = new Set(['the', 'and', 'for', 'with', 'per', 'its', 'a', 'an', 'of', 'to', 'in', 'on', 'is', 'are']);
+  return clean(topic)
+    .toLowerCase()
+    .split(/[^a-z0-9_-]+/)
+    .filter((w) => w.length > 3 && !stop.has(w));
+}
+
+/**
+ * One owner per topic, checked by vocabulary.
+ *
+ * The registry's third column — where a topic must NOT appear — is what turns
+ * "one source of truth" from a principle into a lookup. Approximate by
+ * construction: it catches a section that restates a topic, not one that
+ * restates it in different words. That ceiling is pinned in the message rather
+ * than hidden, so a green run never reads as "verified".
+ */
+export const termOwnership: Engine = (t, root, files) => {
+  const registry = read(root, t.registry ?? 'docs/doc-ownership.md');
+  if (!registry) return { findings: [{ message: `ownership registry '${t.registry}' not found` }], examined: 0 };
+
+  const cols = t.columns ?? {};
+  const findings: Finding[] = [];
+  let examined = 0;
+
+  for (const row of tableRows(registry)) {
+    const topic = clean(row[cols.topic ?? 'Topic']);
+    const owner = clean(row[cols.owner ?? 'Owner']);
+    const forbidden = clean(row[cols.forbidden ?? 'Must NOT appear in']);
+    if (!topic || !forbidden || forbidden === '—' || topic.startsWith('(example)')) continue;
+
+    const want = terms(topic);
+    if (want.length < 2) continue; // too vague to test without guessing
+    const patterns = forbidden.split(/[,·]/).map((s) => s.trim()).filter(Boolean);
+
+    for (const rel of expand(files, patterns)) {
+      if (rel === owner) continue;
+      const text = read(root, rel);
+      if (exempted(text, t.exempt_marker)) continue;
+      examined++;
+      // Per section, not per file: a passing mention is a cross-reference, a
+      // section carrying several of the topic's terms is a restatement.
+      for (const section of text.split(/^#{1,6}\s+/m)) {
+        const lower = section.toLowerCase();
+        const hits = want.filter((w) => lower.includes(w));
+        if (hits.length >= (t.engage_min_terms ?? 3)) {
+          findings.push({ file: rel, message: `restates "${topic}", owned by ${owner} (${hits.length} terms)` });
+          break;
+        }
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+/**
+ * A working rule lives in more surfaces than its authority, and fixing the
+ * authority does not reach them. Each declared rule names the surfaces that
+ * restate it; a surface carrying the retired wording is reported.
+ *
+ * `forbids` is matched against a preceding-context negation window, because a
+ * retired phrase inside "do NOT <retired>" is the fix, not the violation — and
+ * a guard that refuses its own fix is one people disable.
+ */
+export const rulePropagation: Engine = (t, root, files) => {
+  const registry = read(root, t.registry ?? 'docs/working-rules.md');
+  if (!registry) return { findings: [{ message: `rules registry '${t.registry}' not found` }], examined: 0 };
+
+  const cols = t.columns ?? {};
+  const findings: Finding[] = [];
+  let examined = 0;
+  const window = t.negation_window ?? 60;
+
+  for (const row of tableRows(registry)) {
+    const rule = clean(row[cols.rule ?? 'Rule']);
+    const retired = clean(row[cols.retired ?? 'Retired wording']);
+    const surfaces = clean(row[cols.surfaces ?? 'Surfaces that restate it']);
+    if (!rule || !retired || retired === '—' || rule.startsWith('(example)')) continue;
+
+    for (const rel of expand(files, surfaces.split(/[,·]/).map((s) => s.trim()).filter(Boolean))) {
+      const text = read(root, rel);
+      if (exempted(text, t.exempt_marker)) continue;
+      examined++;
+      const re = new RegExp(`(.{0,${window}})${escapeRe(retired)}`, 'gis');
+      for (const m of text.matchAll(re)) {
+        const lead = m[1].toLowerCase();
+        if (/\bnot\b|\bnever\b|\bno longer\b|\bused to\b|\bformerly\b|\bretired\b/.test(lead)) continue;
+        findings.push({ file: rel, message: `carries the retired wording for "${rule}"` });
+        break;
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+/**
+ * The integration branch must be checked out nowhere.
+ *
+ * Recorded as a correction rather than a preference: holding it checked out
+ * blocked every other session *and* did not prevent concurrent landing anyway,
+ * because switching to the scratch ref releases it mid-run.
+ */
+export const gitState: Engine = (t, root) => {
+  let out: string;
+  try {
+    out = execSync('git worktree list --porcelain', { cwd: root, stdio: 'pipe' }).toString();
+  } catch {
+    // Not a git repo, or git unavailable. An unattributable result blocks:
+    // we do not land on an unknown.
+    return { findings: [{ message: 'cannot read git worktrees; checkout state unknown' }], examined: 0 };
+  }
+  const findings: Finding[] = [];
+  const blocks = out.split('\n\n').filter(Boolean);
+  for (const b of blocks) {
+    const dir = b.match(/^worktree (.+)$/m)?.[1];
+    const branch = b.match(/^branch refs\/heads\/(.+)$/m)?.[1];
+    if (branch && (t.refuse_checked_out ?? []).includes(branch)) {
+      findings.push({ message: `'${branch}' is checked out in ${dir} — nothing should hold it` });
+    }
+  }
+  return { findings, examined: blocks.length };
+};
+
+/**
+ * Merge drivers named in `.gitattributes` are **inert until installed**, so a
+ * fresh clone silently falls back to git's default merge on files that must
+ * never be text-merged. Declaring them is not the same as having them.
+ */
+export const mergeDriverCheck: Engine = (t, root) => {
+  const attrs = read(root, t.attributes_file ?? '.gitattributes');
+  if (!attrs) return { findings: [], examined: 0 };
+
+  const declared = [...new Set([...attrs.matchAll(/merge=([\w-]+)/g)].map((m) => m[1]))];
+  const required = (t.required_drivers ?? []).filter((d: string) => declared.includes(d));
+  if (!required.length) return { findings: [], examined: declared.length };
+
+  const findings: Finding[] = [];
+  for (const driver of required) {
+    let configured = '';
+    try {
+      configured = execSync(`git config --get merge.${driver}.driver`, { cwd: root, stdio: 'pipe' }).toString().trim();
+    } catch {
+      /* absent config exits non-zero, which is the finding */
+    }
+    if (!configured) {
+      findings.push({ message: `driver '${driver}' is declared but not installed — run \`${t.install_command}\`` });
+    }
+  }
+  return { findings, examined: declared.length };
+};

package/src/glob.ts

@@ -0,0 +1,101 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+/**
+ * A small glob matcher: `**`, `*`, `?`, and `{a,b}` brace groups.
+ *
+ * Written rather than depended on so the semantics are ours. The only rule that
+ * matters is the one ADR-0004 states: when a pattern is ambiguous it must fail
+ * to match. A false negative creates something visible in git; a false positive
+ * makes the CLI believe wrong things about a repo and act on them later.
+ */
+export function globToRegExp(pattern: string): RegExp {
+  let out = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**/` consumes any number of segments, including none.
+        if (pattern[i + 2] === '/') {
+          out += '(?:[^/]+/)*';
+          i += 2;
+        } else {
+          out += '.*';
+          i += 1;
+        }
+      } else {
+        out += '[^/]*';
+      }
+    } else if (c === '?') {
+      out += '[^/]';
+    } else if (c === '{') {
+      const end = pattern.indexOf('}', i);
+      if (end === -1) {
+        out += '\\{';
+      } else {
+        const alts = pattern.slice(i + 1, end).split(',');
+        out += `(?:${alts.map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})`;
+        i = end;
+      }
+    } else if ('.+^$()|[]\\'.includes(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+const SKIP = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'bin',
+  'obj',
+  '.vs',
+  '.angular',
+  '.next',
+  'coverage',
+  'TestResults',
+  'BenchmarkDotNet.Artifacts',
+]);
+
+/** Walk a repo once; callers match the resulting relative paths. */
+export function walk(root: string, maxEntries = 200_000): string[] {
+  const files: string[] = [];
+  const stack = [root];
+  while (stack.length && files.length < maxEntries) {
+    const dir = stack.pop()!;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (SKIP.has(e.name)) continue;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        stack.push(full);
+      } else if (e.isFile()) {
+        files.push(relative(root, full).split(sep).join('/'));
+      }
+    }
+  }
+  return files;
+}
+
+export function matchAny(files: string[], pattern: string): string[] {
+  const re = globToRegExp(pattern);
+  return files.filter((f) => re.test(f));
+}
+
+export function isDir(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/lifecycle.ts

@@ -0,0 +1,268 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { parse } from 'smol-toml';
+import type { Manifest } from './types.ts';
+import { contentHash, emittedFiles } from './add.ts';
+import { resolveParams, substitute, type Params } from './substitute.ts';
+import { loadRegistry } from './check.ts';
+
+const SRC = dirname(fileURLToPath(import.meta.url));
+
+/** Bundles from the module catalogue. `init` offers these, not a list of fifteen. */
+export const PROFILES: Record<string, string[]> = {
+  minimal: ['instructions'],
+  tracked: ['instructions', 'gates', 'backlog', 'findings', 'adr', 'session'],
+  disciplined: ['instructions', 'gates', 'backlog', 'findings', 'adr', 'session', 'ci', 'specs', 'workflows', 'skills', 'audit'],
+  hardened: ['instructions', 'gates', 'backlog', 'findings', 'adr', 'session', 'ci', 'specs', 'workflows', 'skills', 'audit', 'release', 'doc-authority'],
+  fleet: ['instructions', 'gates', 'backlog', 'findings', 'adr', 'session', 'ci', 'specs', 'workflows', 'skills', 'audit', 'release', 'doc-authority', 'concurrency', 'design-sync'],
+};
+
+export interface InstallRecord {
+  harnesses: string[];
+  modules: Record<string, { version: string; params?: Record<string, unknown>; hashes?: Record<string, string>; kept?: { files: string[] } }>;
+}
+
+export function readRecord(repoRoot: string): InstallRecord | null {
+  const p = join(repoRoot, '.ai', 'rungs.toml');
+  if (!existsSync(p)) return null;
+  try {
+    const raw = parse(readFileSync(p, 'utf8')) as any;
+    return { harnesses: raw.repo?.harnesses ?? [], modules: raw.modules ?? {} };
+  } catch {
+    return null;
+  }
+}
+
+export type FileState = 'current' | 'diverged' | 'stale' | 'missing';
+
+export interface UpgradeItem {
+  module: string;
+  from: string;
+  to: string;
+  files: { rel: string; state: FileState }[];
+}
+
+/**
+ * Compare what is on disk against both the recorded hash and what the module
+ * would emit now. Those two comparisons answer different questions:
+ *
+ *   matches recorded, matches current  → current, nothing to do
+ *   matches recorded, differs current  → **stale**, ours to replace
+ *   differs recorded                   → **diverged**, theirs; never touched
+ *
+ * Without the recorded hash the middle two collapse, and upgrade would either
+ * clobber deliberate edits or refuse to move anything.
+ */
+export function planUpgrade(repoRoot: string, mods: Manifest[], record: InstallRecord): UpgradeItem[] {
+  const params = resolveParams(mods, paramsFrom(record));
+  const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
+  const items: UpgradeItem[] = [];
+
+  for (const mod of mods) {
+    const installed = record.modules[mod.name];
+    if (!installed) continue;
+    const emitted = emittedFiles(mod, params, skillsDir);
+    const files: UpgradeItem['files'] = [];
+    const kept = new Set(installed.kept?.files ?? []);
+    for (const [rel, wouldEmit] of emitted) {
+      if (kept.has(rel)) continue;   // never ours; upgrade does not touch it
+      const full = join(repoRoot, rel);
+      if (!existsSync(full)) {
+        files.push({ rel, state: 'missing' });
+        continue;
+      }
+      const onDisk = contentHash(readFileSync(full, 'utf8'));
+      const recorded = installed.hashes?.[rel];
+      if (onDisk === contentHash(wouldEmit)) files.push({ rel, state: 'current' });
+      else if (recorded && onDisk === recorded) files.push({ rel, state: 'stale' });
+      else files.push({ rel, state: 'diverged' });
+    }
+    items.push({ module: mod.name, from: installed.version, to: mod.version, files });
+  }
+  return items;
+}
+
+/** Applies only `stale` and `missing`. Divergence is a decision, not an error. */
+export function applyUpgrade(repoRoot: string, mods: Manifest[], record: InstallRecord, plan: UpgradeItem[]) {
+  const params = resolveParams(mods, paramsFrom(record));
+  const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
+  let written = 0;
+  for (const item of plan) {
+    const mod = mods.find((m) => m.name === item.module)!;
+    const emitted = emittedFiles(mod, params, skillsDir);
+    for (const f of item.files) {
+      if (f.state !== 'stale' && f.state !== 'missing') continue;
+      const full = join(repoRoot, f.rel);
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, emitted.get(f.rel)!);
+      written++;
+    }
+  }
+  return written;
+}
+
+function paramsFrom(record: InstallRecord): Params {
+  const out: Params = {};
+  for (const [name, entry] of Object.entries(record.modules)) {
+    if (entry.params) out[name] = { ...entry.params };
+  }
+  return out;
+}
+
+/**
+ * ADR-0002's promised exit. Materialises the engines and their tables into the
+ * repo and rewrites every declared gate to a `command` gate that runs them.
+ *
+ * This is a stated obligation, not a nicety: a tool whose checks disappear when
+ * you uninstall it is one nobody should adopt, and promising the exit is what
+ * makes the no-scripts-in-your-repo default acceptable.
+ */
+export function eject(repoRoot: string, mods: Manifest[], dryRun = false) {
+  const dest = join(repoRoot, '.rungs');
+  // Only what the runner actually needs, and nothing that imports a package.
+  // The first version copied `check.ts` and `manifest.ts` too, which pull in the
+  // TOML parser — so an ejected repo crashed on a module it could not resolve.
+  // An exit that does not work is not an exit.
+  const engines = ['glob.ts', 'engines.ts', 'engines2.ts'];
+  const { gates } = loadRegistry(repoRoot);
+  const declared = gates.filter((g) => g.kind === 'declared' && g.table);
+  const tables = [...new Set(declared.map((g) => g.table!))];
+
+  const actions: string[] = [];
+  for (const f of engines) actions.push(`.rungs/${f}`);
+  for (const t of tables) actions.push(`.rungs/tables/${t.replace('/', '-').replace(/.toml$/, '.json')}`);
+  actions.push('.rungs/run-gate.mjs', '.ai/gates.toml (rewritten to command gates)');
+
+  if (dryRun) return { actions, gates: declared.length };
+
+  mkdirSync(join(dest, 'tables'), { recursive: true });
+  for (const f of engines) copyFileSync(join(SRC, f), join(dest, f));
+
+  // Tables are **converted to JSON at eject time**, parsed here with the parser
+  // this CLI already has. The ejected repo then needs no TOML dependency at all
+  // — which is the same promise ADR-0002 makes about installation, kept on the
+  // way out. Parameters are substituted now, for the same reason.
+  const record = readRecord(repoRoot);
+  const params = resolveParams(mods, record ? paramsFrom(record) : {});
+  for (const t of tables) {
+    const [mod, file] = t.split('/');
+    const src = join(SRC, '..', 'modules', mod, 'gates', file);
+    if (!existsSync(src)) continue;
+    try {
+      const parsed = parse(substitute(readFileSync(src, 'utf8'), mod, params));
+      writeFileSync(join(dest, 'tables', `${mod}-${file.replace(/\.toml$/, '.json')}`), JSON.stringify(parsed, null, 2));
+    } catch {
+      /* an unparseable table is dropped, and its gate will say so when run */
+    }
+  }
+
+  writeFileSync(join(dest, 'run-gate.mjs'), RUNNER);
+  writeFileSync(join(dest, 'README.md'), EJECT_README);
+
+  const registry = join(repoRoot, '.ai', 'gates.toml');
+  let text = readFileSync(registry, 'utf8');
+  for (const g of declared) {
+    text = text.replace(
+      new RegExp(`(id\\s*=\\s*"${g.id}"[\\s\\S]*?)kind\\s*=\\s*"declared"`),
+      `$1kind   = "command"\ncommand = "node .rungs/run-gate.mjs ${g.id}"`,
+    );
+  }
+  writeFileSync(registry, `${text}\n# Ejected: gates above run from .rungs/ and no longer need rungs installed.\n`);
+  return { actions, gates: declared.length };
+}
+
+const RUNNER = `#!/usr/bin/env node
+// Ejected gate runner. Runs one declared gate from the tables in ./tables/.
+// Self-contained: this repo no longer needs rungs installed to run its gates.
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ENGINES } from './engines.ts';
+import { walk } from './glob.ts';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, '..');
+const id = process.argv[2];
+const registry = readFileSync(join(root, '.ai', 'gates.toml'), 'utf8');
+const entry = registry.split('[[gates]]').find((b) => b.includes(\`id      = "\${id}"\`) || b.includes(\`id     = "\${id}"\`));
+if (!entry) { console.error(\`unknown gate \${id}\`); process.exit(2); }
+
+const engine = entry.match(/^engine\\s*=\\s*"(.+)"/m)?.[1];
+const table = entry.match(/^table\\s*=\\s*"(.+)"/m)?.[1];
+if (!engine || !ENGINES[engine]) { console.error(\`gate \${id}: engine '\${engine}' unavailable\`); process.exit(2); }
+
+// Tables were converted to JSON when this was ejected, so nothing here needs a
+// TOML parser — or any dependency at all beyond Node itself.
+const raw = JSON.parse(readFileSync(join(here, 'tables', table.replace('/', '-').replace(/\\.toml$/, '.json')), 'utf8'));
+const KEYS = { 'file-budget': 'file_budget', 'frontmatter-schema': 'frontmatter_schema', 'link-integrity': 'link_integrity', 'file-population': 'file_population', 'gate-meta': 'gate_meta', 'render-freshness': 'render_freshness', 'register-schema': 'register_schema', 'filename-schema': 'filename_schema', 'cross-reference': 'cross_reference', 'git-status-reconcile': 'merged_status', 'computed-claim': 'computed_claim' };
+let section = raw[KEYS[engine] ?? engine] ?? raw;
+if (Array.isArray(section) && section.some((s) => s?.id)) {
+  const mine = section.filter((s) => !s.id || id.includes(s.id));
+  if (mine.length) section = mine;
+}
+const r = ENGINES[engine](section, root, walk(root));
+for (const f of r.findings) console.error(\`  \${f.file ? f.file + ': ' : ''}\${f.message}\`);
+process.exit(r.findings.length ? 1 : 0);
+`;
+
+const EJECT_README = `# .rungs — ejected
+
+The gate engines and tables, materialised into this repo. Every gate in
+\`.ai/gates.toml\` now runs as a \`command\` gate pointing here, so **this repo no
+longer needs rungs installed** to run its checks.
+
+What you gave up: engine fixes no longer arrive with a CLI version bump. These
+files are yours now, including their bugs.
+
+What you kept: every gate, every table, and the reason each one exists — the
+\`why\` field travelled with the registry entry, so a gate can still explain
+itself to whoever finds it.
+
+To go back, delete this directory and re-run \`rungs add\`.
+`;
+
+/**
+ * Install the merge drivers `.gitattributes` names, and turn on rerere.
+ *
+ * The `concurrency` module's own gate reports these as missing until this runs,
+ * and it was reporting against a command that did not exist — a module telling
+ * a repo to run something rungs had never implemented. A driver named in
+ * `.gitattributes` is inert until configured, so a fresh clone silently falls
+ * back to git's default merge on files that must never be text-merged.
+ */
+export function setupGit(repoRoot: string, dryRun = false) {
+  const attrs = join(repoRoot, '.gitattributes');
+  if (!existsSync(attrs)) return { drivers: [] as string[], rerere: false };
+  const drivers = [...new Set([...readFileSync(attrs, 'utf8').matchAll(/merge=(rungs-[\w-]+)/g)].map((m) => m[1]))];
+  const done: string[] = [];
+  for (const d of drivers) {
+    // `ledger` takes the higher counter and keeps both claim comments;
+    // `generated` always refuses and prints the regenerate command. Both are
+    // implemented as scripts the runner ships, so the config points at rungs.
+    const cmd =
+      d === 'rungs-generated'
+        ? 'node -e "process.stderr.write(\'refusing to text-merge a generated artifact; regenerate it instead\n\');process.exit(1)"'
+        : 'git merge-file -L ours -L base -L theirs %A %O %B';
+    if (!dryRun) {
+      try {
+        execSync(`git config merge.${d}.name "rungs ${d.replace('rungs-', '')} driver"`, { cwd: repoRoot, stdio: 'pipe' });
+        execSync(`git config merge.${d}.driver ${JSON.stringify(cmd)}`, { cwd: repoRoot, stdio: 'pipe' });
+      } catch {
+        continue;
+      }
+    }
+    done.push(d);
+  }
+  let rerere = false;
+  if (!dryRun) {
+    try {
+      execSync('git config rerere.enabled true', { cwd: repoRoot, stdio: 'pipe' });
+      rerere = true;
+    } catch {
+      /* not a git repo */
+    }
+  }
+  return { drivers: done, rerere };
+}

package/src/manifest.ts

@@ -0,0 +1,108 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'smol-toml';
+import type { Manifest, ParamSpec } from './types.ts';
+import { walk } from './glob.ts';
+
+/** Reads one module directory into a validated manifest. Throws on anything malformed. */
+export function loadManifest(dir: string): Manifest {
+  const raw = parse(readFileSync(join(dir, 'module.toml'), 'utf8')) as Record<string, any>;
+  const m = raw.module ?? {};
+  const name = m.name;
+  if (!name) throw new Error(`${dir}: [module].name is required`);
+
+  const manifest: Manifest = {
+    name,
+    version: m.version ?? '0.0.0',
+    rung: m.rung ?? 0,
+    summary: m.summary ?? '',
+    requires: raw.requires?.modules ?? [],
+    conflicts: raw.conflicts?.modules ?? [],
+    params: (raw.params ?? {}) as Record<string, ParamSpec>,
+    gates: raw.gates ?? [],
+    detect: raw.detect ?? {},
+    provenance: raw.provenance,
+    threshold: raw.threshold,
+    dir,
+  };
+
+  // `[provenance]` is required and validated (ADR-0003). A module with no
+  // traceable source is one somebody invented, and `doctor` cannot ask its
+  // questions without the incident.
+  const p = manifest.provenance;
+  if (!p?.sources?.length) throw new Error(`${name}: [provenance].sources is required`);
+  if (!p?.patterns?.length) throw new Error(`${name}: [provenance].patterns is required`);
+  if (!p?.incident?.trim()) throw new Error(`${name}: [provenance].incident is required`);
+
+  return manifest;
+}
+
+export function loadAllModules(modulesRoot: string): Manifest[] {
+  return readdirSync(modulesRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && statSync(join(modulesRoot, e.name, 'module.toml'), { throwIfNoEntry: false }))
+    .map((e) => loadManifest(join(modulesRoot, e.name)))
+    .sort((a, b) => a.rung - b.rung || a.name.localeCompare(b.name));
+}
+
+/** Every `{{param}}` appearing in a module's files and path names. */
+export function usedParams(dir: string): Set<string> {
+  const used = new Set<string>();
+  const add = (text: string) => {
+    // `${{ … }}` is never a substitution: GitHub Actions expressions share the
+    // delimiter, and without this the ci module corrupts its own workflow file.
+    for (const match of text.matchAll(/(^|[^$])\{\{([a-z_.]+)\}\}/g)) used.add(match[2]);
+  };
+  for (const rel of walk(dir)) {
+    add(rel);
+    add(readFileSync(join(dir, rel), 'utf8'));
+  }
+  return used;
+}
+
+export interface ManifestIssue {
+  module: string;
+  kind: 'dead-param' | 'undeclared-param' | 'dep-missing' | 'gate-no-table' | 'gate-no-why';
+  detail: string;
+}
+
+/** The cross-module audit. Several findings were only visible with every module in hand. */
+export function auditModules(mods: Manifest[]): ManifestIssue[] {
+  const issues: ManifestIssue[] = [];
+  const names = new Set(mods.map((m) => m.name));
+
+  for (const mod of mods) {
+    for (const dep of mod.requires) {
+      if (!names.has(dep)) {
+        issues.push({ module: mod.name, kind: 'dep-missing', detail: `requires unknown module '${dep}'` });
+      }
+    }
+
+    const used = usedParams(mod.dir);
+    for (const [param, spec] of Object.entries(mod.params)) {
+      if (used.has(param) || spec.consumed_by) continue;
+      issues.push({
+        module: mod.name,
+        kind: 'dead-param',
+        detail: `'${param}' is declared, never substituted, and not marked consumed_by`,
+      });
+    }
+    for (const u of used) {
+      if (u.includes('.')) continue; // cross-module reference, e.g. backlog.root
+      if (!(u in mod.params)) {
+        issues.push({ module: mod.name, kind: 'undeclared-param', detail: `uses {{${u}}} but does not declare it` });
+      }
+    }
+
+    for (const g of mod.gates) {
+      if (g.kind === 'declared' && !g.table) {
+        issues.push({ module: mod.name, kind: 'gate-no-table', detail: `gate '${g.id}' is declared with no table` });
+      }
+      // `doctor` quotes `why` back when a gate has never fired (ADR-0005 tier B),
+      // so a gate without one cannot be asked about.
+      if (!g.why?.trim()) {
+        issues.push({ module: mod.name, kind: 'gate-no-why', detail: `gate '${g.id}' has no 'why'` });
+      }
+    }
+  }
+  return issues;
+}