@ticket-gate/engine 0.0.0 → 0.1.0-rc.1

package/checks/assertions.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/**
+ * The assertion ratchet in engine shape: counts the configured needles per spec,
+ * sums them per area (a spec counts toward every area in its line-1 header), and compares with the
+ * configured baseline file. Every project value (paths, counters, areas, commands, messages) comes
+ * from the config passed to `assertions(cfg)`; this module names none.
+ *
+ * - A drop in an area fails unless the mutation registry covers it: the receipt is green and
+ *   complete for this tree, and every dropped spec is named by the `from` of a live entry of that
+ *   ticket (`unguarded` included).
+ * - Any other change (a rise, a new or changed spec) is `stale`; the update command fixes it.
+ * Never edit the baseline by hand.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { listFiles, readText } from '../graph/js.mjs';
+import {
+  entriesDigest,
+  entriesFor,
+  loadRegistry,
+  ticketTreeHash,
+} from '../mutations/registry.mjs';
+
+const count = (text, needle) => text.split(needle).length - 1;
+
+/** @param {object} cfg the assertions config @param {string} root repo root */
+function countSpecs(cfg, root) {
+  const { dir, match, header } = cfg.specs;
+  const out = {};
+  const files = listFiles(root, dir, (p) => match.test(p)).map((p) =>
+    p.slice(dir.length + 1),
+  );
+  for (const name of files) {
+    const text = readText(root, `${dir}/${name}`) ?? '';
+    const m = header.exec(text.split('\n', 1)[0].replace(/\r$/, ''));
+    const entry = { areas: m ? m[1] : '' };
+    for (const k of Object.keys(cfg.counters))
+      entry[k] = count(text, cfg.counters[k]);
+    out[name] = entry;
+  }
+  return out;
+}
+
+function areaTotals(cfg, specs) {
+  const out = {};
+  for (const a of cfg.areas)
+    out[a] = Object.fromEntries(Object.keys(cfg.counters).map((k) => [k, 0]));
+  for (const s of Object.values(specs)) {
+    for (const a of s.areas.split(', ')) {
+      if (!out[a]) continue;
+      for (const k of Object.keys(cfg.counters)) out[a][k] += s[k];
+    }
+  }
+  return out;
+}
+
+function compare(cfg, baseline, specs) {
+  const prev = baseline.areas ?? {};
+  const nowAreas = areaTotals(cfg, specs);
+  const drops = [];
+  const rises = [];
+  for (const area of cfg.areas) {
+    for (const counter of Object.keys(cfg.counters)) {
+      const was = prev[area]?.[counter] ?? 0;
+      const now = nowAreas[area][counter];
+      if (now < was) drops.push({ area, counter, was, now });
+      if (now > was) rises.push({ area, counter, was, now });
+    }
+  }
+  const specChanges = [];
+  const old = baseline.specs ?? {};
+  for (const name of Object.keys({ ...old, ...specs }).sort()) {
+    if (JSON.stringify(old[name]) !== JSON.stringify(specs[name]))
+      specChanges.push(name);
+  }
+  return { drops, rises, specChanges };
+}
+
+/** Baseline specs in a dropped area that are gone or have a lower counter. */
+function culpritsOf(cfg, baseline, specs, drops) {
+  const areas = new Set(drops.map((d) => d.area));
+  const out = [];
+  for (const [name, b] of Object.entries(baseline.specs ?? {})) {
+    if (!b.areas.split(', ').some((a) => areas.has(a))) continue;
+    const now = specs[name];
+    const lostArea = b.areas
+      .split(', ')
+      .some((a) => areas.has(a) && !now?.areas.split(', ').includes(a));
+    if (
+      !now ||
+      lostArea ||
+      Object.keys(cfg.counters).some((k) => now[k] < b[k])
+    )
+      out.push(`${cfg.from}${name}`);
+  }
+  return out;
+}
+
+function receiptProblem(cfg, receipt, io) {
+  if (receipt === null) return `no mutation receipt (${cfg.receipt})`;
+  if (receipt.ok !== true) return 'receipt not green';
+  if (receipt.partial !== false) return 'receipt is partial';
+  if (receipt.source !== 'registry') return 'receipt is from a --file run';
+  if (receipt.treeHash !== io.treeHash()) return 'receipt is for another tree';
+  const own = entriesFor(loadRegistry(io.root, io.setup), receipt.ticket);
+  if (entriesDigest(own) !== receipt.entriesDigest) return 'mutations changed';
+  return { own };
+}
+
+function coverage(cfg, baseline, specs, receipt, io) {
+  const { drops } = compare(cfg, baseline, specs);
+  const culprits = culpritsOf(cfg, baseline, specs, drops);
+  const r = receiptProblem(cfg, receipt, io);
+  if (typeof r === 'string')
+    return { covered: false, why: r, missing: culprits };
+  const named = new Set();
+  for (const [, e] of r.own) if (!e.retired && e.from) named.add(e.from);
+  const missing = culprits.filter((spec) => !named.has(spec));
+  if (missing.length > 0)
+    return {
+      covered: false,
+      why: 'no mutation names the dropped spec',
+      missing,
+    };
+  return { covered: true, why: null, missing: [] };
+}
+
+function readBaseline(path) {
+  if (!existsSync(path)) return { baseline: null };
+  try {
+    const b = JSON.parse(readFileSync(path, 'utf8'));
+    if (!b || typeof b !== 'object' || !b.areas || !b.specs)
+      throw new Error('missing areas or specs');
+    return { baseline: b };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+function readReceipt(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const dropLine = (d) => `  ${d.area} ${d.counter}: was ${d.was}, now ${d.now}`;
+
+/**
+ * @param {object} cfg
+ * @param {string} root
+ * @param {{ baselinePath?: string, receiptPath?: string, treeHash?: () => string, update?: boolean }} [opts]
+ * @returns {{ code: 0 | 1 | 2, lines: string[], wrote: boolean }}
+ */
+function checkE2eAssertions(cfg, root, opts = {}) {
+  const { name, commands } = cfg;
+  const baselinePath = opts.baselinePath ?? join(root, cfg.baseline);
+  const receiptPath = opts.receiptPath ?? join(root, cfg.receipt);
+  const io = {
+    root,
+    treeHash: opts.treeHash ?? (() => ticketTreeHash(cfg.setup)),
+    setup: cfg.setup,
+  };
+  const specs = countSpecs(cfg, root);
+  const write = () => {
+    const doc = {
+      comment: cfg.comment,
+      areas: areaTotals(cfg, specs),
+      specs,
+    };
+    mkdirSync(dirname(baselinePath), { recursive: true });
+    writeFileSync(baselinePath, `${JSON.stringify(doc, null, 2)}\n`);
+    return true;
+  };
+  const refuseUpdate = (cov) => ({
+    code: 1,
+    wrote: false,
+    lines: [
+      `${name}: --update refused, the drop is not covered: ${cov.why}`,
+      ...cov.missing.map((m) => `  missing: ${m}`),
+      `Run ${commands.mutate} green on this tree with a mutation from field (or "unguarded") for each spec above, then retry.`,
+    ],
+  });
+
+  const { baseline, error } = readBaseline(baselinePath);
+  if (error)
+    return {
+      code: 2,
+      wrote: false,
+      lines: [
+        `${name}: unreadable baseline ${baselinePath}: ${error}`,
+        `Restore it with git checkout -- ${cfg.baseline}, or delete it and run ${commands.update}.`,
+      ],
+    };
+  if (baseline === null) {
+    if (opts.update) {
+      write();
+      return {
+        code: 0,
+        wrote: true,
+        lines: [`${name}: baseline written (none existed)`],
+      };
+    }
+    return {
+      code: 2,
+      wrote: false,
+      lines: [
+        `${name}: no baseline at ${baselinePath}. Run ${commands.update}.`,
+      ],
+    };
+  }
+
+  const { drops, rises, specChanges } = compare(cfg, baseline, specs);
+  const equal =
+    drops.length === 0 && rises.length === 0 && specChanges.length === 0;
+  if (equal)
+    return {
+      code: 0,
+      wrote: false,
+      lines: [
+        `${name}: ${Object.keys(specs).length} specs, ${cfg.areas.length} areas match the baseline`,
+      ],
+    };
+
+  if (drops.length > 0) {
+    const cov = coverage(cfg, baseline, specs, readReceipt(receiptPath), io);
+    if (opts.update) {
+      if (!cov.covered) return refuseUpdate(cov);
+      write();
+      return {
+        code: 0,
+        wrote: true,
+        lines: [`${name}: baseline updated (drop covered)`],
+      };
+    }
+    if (cov.covered)
+      return {
+        code: 0,
+        wrote: false,
+        lines: [
+          `${name}: assertion drop`,
+          ...drops.map(dropLine),
+          `covered by the mutation receipt; run ${commands.update}`,
+        ],
+      };
+    return {
+      code: 1,
+      wrote: false,
+      lines: [
+        `${name}: assertion drop not covered`,
+        ...drops.map(dropLine),
+        `why: ${cov.why}`,
+        ...cov.missing.map((m) => `  missing: ${m}`),
+        `Fix: add a mutation with a from field (or an "unguarded" entry) for each missing spec in the registry (${cfg.registry}), run ${commands.mutate} green on this tree, then ${commands.update}.`,
+      ],
+    };
+  }
+
+  if (opts.update) {
+    write();
+    return {
+      code: 0,
+      wrote: true,
+      lines: [`${name}: baseline updated`],
+    };
+  }
+  return {
+    code: 1,
+    wrote: false,
+    lines: [
+      `${name}: stale baseline (assertions or specs changed with no drop)`,
+      ...rises.map(dropLine),
+      ...specChanges.map((n) => `  spec changed: ${n}`),
+      `Fix: ${commands.update} (no receipt needed), then commit ${cfg.baseline}.`,
+    ],
+  };
+}
+
+/**
+ * @param {object} cfg
+ * @param {{ root: string, args: string[] }} opts
+ * @returns {{ code: 0 | 1 | 2, lines: string[], out: string[], err: string[] }}
+ */
+function checkArgs(cfg, { root, args }) {
+  const opts = { update: false };
+  let bad = null;
+  for (const a of args) {
+    if (a === '--update') opts.update = true;
+    else if (a.startsWith('--baseline=')) opts.baselinePath = a.slice(11);
+    else if (a.startsWith('--receipt=')) opts.receiptPath = a.slice(10);
+    else bad = a;
+  }
+  if (bad) {
+    const err = [
+      `${cfg.name}: unknown argument ${bad}. Usage: ${cfg.commands.usage} [--update] [--baseline=<path>] [--receipt=<path>]`,
+    ];
+    return { code: 2, lines: err, out: [], err };
+  }
+  const r = checkE2eAssertions(cfg, root, opts);
+  const out = r.code === 0 ? [r.lines.join('\n')] : [];
+  const err = r.code === 0 ? [] : [r.lines.join('\n')];
+  return { code: r.code, lines: [...out, ...err], out, err };
+}
+
+/** @param {AssertionsConfig} cfg @returns {Assertions} */
+export function assertions(cfg) {
+  return {
+    COUNTERS: cfg.counters,
+    countSpecs: (root) => countSpecs(cfg, root),
+    areaTotals: (specs) => areaTotals(cfg, specs),
+    compare: (baseline, specs) => compare(cfg, baseline, specs),
+    coverage: (baseline, specs, receipt, io) =>
+      coverage(cfg, baseline, specs, receipt, io),
+    checkE2eAssertions: (root, opts) => checkE2eAssertions(cfg, root, opts),
+    check: (args) => checkArgs(cfg, args),
+  };
+}

package/checks/cache-report.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+// Prompt-cache usage for one Claude Code session and every subagent it spawned,
+// read from the transcripts Claude Code writes under ~/.claude/projects/<slug>/.
+//
+//   cache-report                  latest session of this repo
+//   cache-report <session-id>     that session
+//   cache-report <path.jsonl>     a transcript anywhere
+//   add --json for machine-readable output
+//
+// Every cache write is put in one of three buckets:
+//   spawn    the first request of an agent (system prompt, agent definition, task);
+//   growth   the turn's new messages appended to an already-cached prefix;
+//   rebuild  a request that read back less than half of the previous request's
+//            context, so it rewrote it: the cache expired (subagents get a
+//            5-minute TTL) or the prefix changed. That is the waste worth chasing.
+// Cost is in input-token units, priced relative to an uncached input token:
+// a cache read is 0.1, a 5-minute write 1.25, a 1-hour write 2.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export const WEIGHT = { uncached: 1, write5m: 1.25, write1h: 2, read: 0.1 };
+const REBUILD_SHARE = 0.5;
+
+/** ~/.claude/projects/<slug> for a working directory: every non-alphanumeric becomes `-`. */
+export function projectDir(cwd = process.cwd(), home = homedir()) {
+  return join(home, '.claude', 'projects', cwd.replace(/[^a-zA-Z0-9]/g, '-'));
+}
+
+/** Path of the most recently modified top-level session transcript in a project dir. */
+export function latestSession(dir) {
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith('.jsonl'))
+    .map((f) => join(dir, f));
+  if (!files.length) throw new Error(`no session transcripts in ${dir}`);
+  return files.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+}
+
+/**
+ * Collapse a transcript into one usage record per API request. Streaming logs
+ * the same message id several times with a growing output count; the last copy
+ * holds the final usage, the first copy the time the request was answered.
+ */
+export function requests(text) {
+  const byId = new Map();
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const msg = rec.message;
+    if (msg?.role !== 'assistant' || !msg.usage) continue;
+    const id = msg.id ?? rec.uuid;
+    const prev = byId.get(id);
+    byId.set(id, {
+      at: prev?.at ?? Date.parse(rec.timestamp),
+      model: msg.model,
+      usage: msg.usage,
+    });
+  }
+  return [...byId.values()];
+}
+
+/** Token totals, write buckets and rebuild events for one agent's requests. */
+export function summarize(reqs) {
+  const s = {
+    requests: reqs.length,
+    uncached: 0,
+    write5m: 0,
+    write1h: 0,
+    read: 0,
+    output: 0,
+    spawn: 0,
+    growth: 0,
+    rebuild: 0,
+    rebuilds: [],
+    models: new Set(),
+  };
+  let prevContext = 0;
+  let prevAt = NaN;
+  reqs.forEach((r, i) => {
+    const u = r.usage;
+    const write = u.cache_creation_input_tokens ?? 0;
+    const w1h = u.cache_creation?.ephemeral_1h_input_tokens ?? 0;
+    s.uncached += u.input_tokens ?? 0;
+    s.write1h += w1h;
+    s.write5m += write - w1h;
+    s.read += u.cache_read_input_tokens ?? 0;
+    s.output += u.output_tokens ?? 0;
+    if (r.model && r.model !== '<synthetic>') s.models.add(r.model);
+    if (i === 0) s.spawn += write;
+    else if ((u.cache_read_input_tokens ?? 0) < REBUILD_SHARE * prevContext) {
+      s.rebuild += write;
+      s.rebuilds.push({
+        tokens: write,
+        gapSec: Math.round((r.at - prevAt) / 1000),
+      });
+    } else s.growth += write;
+    prevContext =
+      (u.input_tokens ?? 0) + write + (u.cache_read_input_tokens ?? 0);
+    prevAt = r.at;
+  });
+  return s;
+}
+
+/** Input cost of a summary, in uncached-input-token units. */
+export function cost(s) {
+  return (
+    s.uncached * WEIGHT.uncached +
+    s.write5m * WEIGHT.write5m +
+    s.write1h * WEIGHT.write1h +
+    s.read * WEIGHT.read
+  );
+}
+
+/** Cost of the rebuild writes alone, priced at the TTL each agent wrote at. */
+export function rebuildCost(s) {
+  const writes = s.write5m + s.write1h;
+  if (!writes) return 0;
+  const rate =
+    (s.write5m * WEIGHT.write5m + s.write1h * WEIGHT.write1h) / writes;
+  return s.rebuild * rate;
+}
+
+function label(file) {
+  const meta = file.replace(/\.jsonl$/, '.meta.json');
+  if (existsSync(meta)) {
+    try {
+      const m = JSON.parse(readFileSync(meta, 'utf8'));
+      return [m.agentType, m.description].filter(Boolean).join(': ');
+    } catch {
+      // fall through to the file name
+    }
+  }
+  return basename(file, '.jsonl');
+}
+
+/** Every `subagents/workflows/<wfId>/agent-*.jsonl` (a review-round run's agents). */
+function workflowAgents(subDir) {
+  const root = join(subDir, 'workflows');
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const workflow of readdirSync(root).sort()) {
+    const dir = join(root, workflow);
+    if (!statSync(dir).isDirectory()) continue;
+    for (const f of readdirSync(dir).sort())
+      if (/^agent-.*\.jsonl$/.test(f))
+        out.push({ file: join(dir, f), workflow });
+  }
+  return out;
+}
+
+/**
+ * One row per transcript: the session itself, each subagent in start order,
+ * then each workflow run's agents grouped under its wf id (groups by earliest
+ * start, rows within a group by start).
+ */
+export function report(sessionFile) {
+  const files = [sessionFile];
+  const sub = join(sessionFile.replace(/\.jsonl$/, ''), 'subagents');
+  if (existsSync(sub))
+    for (const f of readdirSync(sub))
+      if (f.endsWith('.jsonl')) files.push(join(sub, f));
+  const rows = [];
+  for (const file of files) {
+    const reqs = requests(readFileSync(file, 'utf8'));
+    if (!reqs.length) continue;
+    const s = summarize(reqs);
+    rows.push({
+      agent: file === sessionFile ? 'orchestrator (session)' : label(file),
+      start: reqs[0].at,
+      ...s,
+    });
+  }
+  const [head, ...rest] = rows;
+  const ordered = head
+    ? [head, ...rest.sort((a, b) => a.start - b.start)]
+    : rest;
+  const wfFiles = workflowAgents(sub);
+  const groups = new Map();
+  for (const { file, workflow } of wfFiles) {
+    const reqs = requests(readFileSync(file, 'utf8'));
+    if (!reqs.length) continue;
+    const row = {
+      agent: `${workflow}/${label(file)}`,
+      workflow,
+      start: reqs[0].at,
+      ...summarize(reqs),
+    };
+    groups.set(workflow, [...(groups.get(workflow) ?? []), row]);
+  }
+  const sorted = [...groups.values()]
+    .map((g) => g.sort((a, b) => a.start - b.start))
+    .sort((a, b) => a[0].start - b[0].start);
+  return [...ordered, ...sorted.flat()];
+}
+
+const KEYS = [
+  'requests',
+  'uncached',
+  'write5m',
+  'write1h',
+  'read',
+  'output',
+  'spawn',
+  'growth',
+  'rebuild',
+];
+
+export function total(rows) {
+  const t = Object.fromEntries(KEYS.map((k) => [k, 0]));
+  t.rebuilds = [];
+  t.costUnits = 0;
+  t.rebuildUnits = 0;
+  for (const r of rows) {
+    for (const k of KEYS) t[k] += r[k];
+    t.rebuilds.push(...r.rebuilds);
+    t.costUnits += cost(r);
+    t.rebuildUnits += rebuildCost(r);
+  }
+  return t;
+}
+
+const k = (n) =>
+  n >= 1e6
+    ? `${(n / 1e6).toFixed(1)}M`
+    : n >= 1e3
+      ? `${Math.round(n / 1e3)}k`
+      : String(n);
+const pct = (a, b) => (b ? `${((100 * a) / b).toFixed(1)}%` : '-');
+
+export function format(rows, sessionFile) {
+  const out = [`cache report: ${sessionFile}`, ''];
+  const head = [
+    'agent',
+    'reqs',
+    'hit%',
+    'read',
+    'write',
+    'rebuild',
+    'n',
+    'max gap',
+    'model',
+  ];
+  const lines = rows.map((r) => {
+    const input = r.uncached + r.write5m + r.write1h + r.read;
+    const maxGap = r.rebuilds.reduce((m, e) => Math.max(m, e.gapSec), 0);
+    return [
+      r.agent.slice(0, 40),
+      String(r.requests),
+      pct(r.read, input),
+      k(r.read),
+      k(r.write5m + r.write1h),
+      k(r.rebuild),
+      String(r.rebuilds.length),
+      maxGap ? `${maxGap}s` : '-',
+      [...r.models].map((m) => m.replace(/^claude-/, '')).join(','),
+    ];
+  });
+  const width = head.map((h, i) =>
+    Math.max(h.length, ...lines.map((l) => l[i].length)),
+  );
+  const row = (cells) =>
+    cells
+      .map((c, i) =>
+        i === 0 || i === 8 ? c.padEnd(width[i]) : c.padStart(width[i]),
+      )
+      .join('  ');
+  out.push(row(head), ...lines.map(row), '');
+  const t = total(rows);
+  const writes = t.write5m + t.write1h;
+  out.push(
+    `agents ${rows.length}, requests ${t.requests}, hit rate ${pct(t.read, t.uncached + writes + t.read)}`,
+    `writes ${k(writes)}: spawn ${k(t.spawn)} (${pct(t.spawn, writes)}), growth ${k(t.growth)} (${pct(t.growth, writes)}), rebuild ${k(t.rebuild)} (${pct(t.rebuild, writes)}) in ${t.rebuilds.length} events`,
+    `input cost ${k(Math.round(t.costUnits))} units; rebuilds ${pct(t.rebuildUnits, t.costUnits)} of it`,
+  );
+  return out.join('\n');
+}
+
+/**
+ * The report for the CLI arguments: { code, lines }. code 0 prints lines to stdout, code 1 (no
+ * transcript) one line to stderr. The caller sets the exit code; this never exits.
+ */
+export function runCacheReport({ root, args }) {
+  const json = args.includes('--json');
+  const target = args.find((a) => !a.startsWith('--'));
+  const dir = projectDir(root);
+  const file = !target
+    ? latestSession(dir)
+    : target.endsWith('.jsonl')
+      ? target
+      : join(dir, `${target}.jsonl`);
+  if (!existsSync(file))
+    return { code: 1, lines: [`cache-report: no transcript at ${file}`] };
+  const rows = report(file);
+  if (json) {
+    const plain = rows.map((r) => ({ ...r, models: [...r.models] }));
+    return {
+      code: 0,
+      lines: [
+        JSON.stringify(
+          { session: file, rows: plain, total: total(rows) },
+          null,
+          2,
+        ),
+      ],
+    };
+  }
+  return { code: 0, lines: [format(rows, file)] };
+}

package/checks/docs-stale.mjs

@@ -0,0 +1,69 @@
+// Which pages of a docs folder describe code that has changed since they were last checked. Each
+// page starts with a comment:
+//
+//   guide-sources: <path> <path> ...
+//   checked-at: <commit>
+//
+// docsStale() lists, per page, the files under its sources that changed between `checked-at` and
+// HEAD. Pages with no changes are listed as current. Read-only; it never edits a page.
+//
+// docsStale({ root, dirs, ext, exclude }) -> { code: 0, lines }. Pages are the files of each dir
+// ending ext and not in exclude, labelled relative to dirs[0] and sorted. git runs in root.
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, posix, relative } from 'node:path';
+
+export function docsStale({
+  root,
+  dirs,
+  ext = '.html',
+  exclude = ['index.html'],
+}) {
+  const git = (args) =>
+    execFileSync('git', args, { encoding: 'utf8', cwd: root }).trim();
+
+  function readStamp(file) {
+    const head = readFileSync(join(root, dirs[0], file), 'utf8').slice(0, 2000);
+    const sources = /guide-sources:\s*([^\n]+)/
+      .exec(head)?.[1]
+      .trim()
+      .split(/\s+/);
+    const checkedAt = /checked-at:\s*(\S+)/.exec(head)?.[1];
+    return { sources, checkedAt };
+  }
+
+  // The top-level pages first, then each further dir's pages (labelled with their sub path).
+  const pages = dirs.flatMap((dir) => {
+    const sub = relative(dirs[0], dir).split('\\').join('/');
+    const prefix = sub === '' ? '' : `${sub}/`;
+    return readdirSync(join(root, dir))
+      .filter((f) => f.endsWith(ext) && !exclude.includes(f))
+      .map((f) => posix.join(prefix, f));
+  });
+  const lines = [];
+  let stale = 0;
+  for (const page of pages.sort()) {
+    const { sources, checkedAt } = readStamp(page);
+    if (!sources || !checkedAt) {
+      lines.push(`${page}: no guide-sources / checked-at stamp`);
+      stale += 1;
+      continue;
+    }
+    const changed = git([
+      'diff',
+      '--stat=120',
+      `${checkedAt}..HEAD`,
+      '--',
+      ...sources,
+    ]);
+    if (changed === '') {
+      lines.push(`${page}: current (checked at ${checkedAt})`);
+    } else {
+      stale += 1;
+      lines.push(`${page}: STALE since ${checkedAt}`);
+      lines.push(changed.replace(/^/gm, '    '));
+    }
+  }
+  lines.push('', `${stale} of ${pages.length} pages to review`);
+  return { code: 0, lines };
+}