@rungs/cli 0.1.0

package/src/engines.ts

@@ -0,0 +1,260 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { matchAny, walk } from './glob.ts';
+import {
+  computedClaim,
+  crossReference,
+  filenameSchema,
+  gitStatusReconcile,
+  idIntegrity,
+  registerSchema,
+  renderFreshness,
+} from './engines2.ts';
+import { gitState, mergeDriverCheck, rulePropagation, termOwnership } from './engines3.ts';
+
+export interface Finding {
+  file?: string;
+  message: string;
+}
+export interface EngineResult {
+  findings: Finding[];
+  /** What the engine looked at. A gate that examined nothing is not a passing gate. */
+  examined: number;
+}
+export type Engine = (table: any, repoRoot: string, files: string[]) => EngineResult;
+
+const read = (root: string, rel: string) => {
+  try {
+    return readFileSync(join(root, rel), 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+/**
+ * `expand` also drops anything the CLI generated.
+ *
+ * Without it a gate fires on its own tool's output: `render` degrades a
+ * path-scoped rule into a nested `docs/plans/AGENTS.md` for harnesses with no
+ * glob scoping, and the `workflows` gate — which scans `docs/plans/**` for plan
+ * documents — then reported that file for having no plan frontmatter. The
+ * render pipeline and the gate scopes collide by construction, so the exclusion
+ * is global rather than per-table: **a gate must never fire on a file rungs
+ * wrote.**
+ */
+const GENERATED = 'Generated by `rungs';
+
+const expand = (files: string[], patterns: string[] | undefined, fallback: string[] = []) =>
+  [...new Set((patterns ?? fallback).flatMap((p) => matchAny(files, p)))];
+
+function dropGenerated(root: string, rels: string[]): string[] {
+  return rels.filter((rel) => !read(root, rel).slice(0, 600).includes(GENERATED));
+}
+
+/** Lines that actually load: HTML comments are stripped by at least one harness. */
+function loadedLines(text: string): number {
+  return text
+    .replace(/^---\n[\s\S]*?\n---\n/, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .split('\n')
+    .filter((l) => l.trim()).length;
+}
+
+const fileBudget: Engine = (t, root, files) => {
+  const targets = dropGenerated(root, t.file ? [t.file] : expand(files, t.scan));
+  const excluded = new Set(expand(files, t.exclude, []));
+  const findings: Finding[] = [];
+  let examined = 0;
+  for (const rel of targets) {
+    if (excluded.has(rel) || !existsSync(join(root, rel))) continue;
+    examined++;
+    const n = loadedLines(read(root, rel));
+    if (n > t.max_lines) findings.push({ file: rel, message: `${n} lines, budget ${t.max_lines}` });
+  }
+  return { findings, examined };
+};
+
+const sections: Engine = (t, root, files) => {
+  const specs = Array.isArray(t) ? t : [t];
+  const findings: Finding[] = [];
+  let examined = 0;
+  for (const spec of specs) {
+    const targets = dropGenerated(root, spec.file ? [spec.file] : expand(files, spec.scan));
+    const excluded = new Set(expand(files, spec.exclude, []));
+    for (const rel of targets) {
+      if (excluded.has(rel) || !existsSync(join(root, rel))) continue;
+      examined++;
+      const text = read(root, rel);
+      const heads = [...text.matchAll(/^#{1,6}\s+(.+?)\s*$/gm)].map((m) => m[1]);
+      for (const want of spec.required ?? []) {
+        const idx = heads.findIndex((h) => h.toLowerCase().startsWith(String(want).toLowerCase()));
+        if (idx === -1) {
+          findings.push({ file: rel, message: `missing section '${want}'` });
+          continue;
+        }
+        if (spec.non_empty) {
+          const after = text.split(new RegExp(`^#{1,6}\\s+${escapeRe(heads[idx])}\\s*$`, 'm'))[1] ?? '';
+          const body = after.split(/^#{1,6}\s+/m)[0].replace(/<!--[\s\S]*?-->/g, '').trim();
+          if (!body) findings.push({ file: rel, message: `section '${want}' is empty` });
+        }
+      }
+      for (const open of spec.requires_opening ?? []) {
+        if (!text.slice(0, 400).includes(open)) findings.push({ file: rel, message: `does not open with ${open}` });
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+const frontmatterSchema: Engine = (t, root, files) => {
+  const specs = Array.isArray(t) ? t : [t];
+  const findings: Finding[] = [];
+  let examined = 0;
+  for (const spec of specs) {
+    for (const rel of dropGenerated(root, expand(files, spec.scan))) {
+      if (new Set(expand(files, spec.exclude, [])).has(rel)) continue;
+      const text = read(root, rel);
+      const m = text.match(/^---\n([\s\S]*?)\n---/);
+      if (!m) {
+        findings.push({ file: rel, message: 'no frontmatter' });
+        continue;
+      }
+      examined++;
+      const keys = [...m[1].matchAll(/^([a-zA-Z0-9_-]+):/gm)].map((k) => k[1]);
+      for (const req of spec.required ?? []) {
+        if (!keys.includes(req)) findings.push({ file: rel, message: `missing '${req}'` });
+      }
+      if (spec.allowed) {
+        for (const k of keys) {
+          if (!spec.allowed.includes(k)) findings.push({ file: rel, message: `non-spec key '${k}'` });
+        }
+      }
+      for (const [key, values] of Object.entries(spec.enum ?? {})) {
+        const v = m[1].match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1].trim().replace(/^["']|["']$/g, '');
+        if (v && !(values as string[]).map(String).includes(v)) {
+          findings.push({ file: rel, message: `${key}='${v}' not one of ${(values as string[]).join(', ')}` });
+        }
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+const linkIntegrity: Engine = (t, root, files) => {
+  const scan = expand(files, t.scan, ['**/*.md']);  // link checks DO cover generated files
+  const excluded = new Set(expand(files, t.exclude, []));
+  const findings: Finding[] = [];
+  let examined = 0;
+  for (const rel of scan) {
+    if (excluded.has(rel)) continue;
+    const text = read(root, rel);
+    // A file with unsubstituted placeholders is a **template**, and its links
+    // resolve only once installed. Found by running this against the rungs repo
+    // itself, where `modules/*/fragments/AGENTS.md` was reported for a broken
+    // link to `{{path}}/README.md` — a path that is not meant to exist here.
+    if (/\{\{[a-z_.]+\}\}/.test(text)) continue;
+    examined++;
+    if (/path-ok:\s*\S/.test(text)) continue;
+    for (const m of text.matchAll(/\]\((?!https?:|#|mailto:)([^)\s#]+)/g)) {
+      const target = resolve(root, dirname(rel), decodeURIComponent(m[1]));
+      if (!existsSync(target)) findings.push({ file: rel, message: `broken link → ${m[1]}` });
+    }
+  }
+  return { findings, examined };
+};
+
+const filePopulation: Engine = (t, root, files) => {
+  let hits = dropGenerated(root, expand(files, t.scan)).filter((f) => !new Set(expand(files, t.exclude, [])).has(f));
+
+  // A `detect` narrows the population to files matching a shape. Without it the
+  // gate counted *every scanned file* — so the redirect-stub check reported
+  // "12 matching files, threshold 1" against a repo with no stubs at all, which
+  // is a confidently wrong number rather than a finding.
+  if (t.detect === 'body_is_only_a_pointer') {
+    hits = hits.filter((rel) => {
+      const body = read(root, rel)
+        .replace(/^---\n[\s\S]*?\n---\n/, '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/^#.*$/gm, '')
+        .trim();
+      const words = body.split(/\s+/).filter(Boolean).length;
+      const links = (body.match(/\]\(/g) ?? []).length;
+      // Short *and* mostly a link. Short alone is a stub-shaped index page.
+      return words > 0 && words <= (t.max_body_words ?? 40) && links >= 1;
+    });
+  }
+
+  const findings: Finding[] = [];
+  const failAt = t.fail_at ?? Infinity;
+  if (hits.length >= failAt) {
+    findings.push({ message: `${hits.length} matching file(s), threshold ${failAt} (e.g. ${hits[0]})` });
+  }
+  return { findings, examined: hits.length };
+};
+
+/**
+ * The meta-gate: every declared gate must carry a self-test expecting `pass`
+ * and one expecting `fail`. A gate whose rules are all currently satisfied is
+ * indistinguishable from a gate that matches nothing.
+ */
+const gateMeta: Engine = (_t, root) => {
+  const findings: Finding[] = [];
+  const registry = join(root, '.ai', 'gates.toml');
+  if (!existsSync(registry)) return { findings, examined: 0 };
+  const text = readFileSync(registry, 'utf8');
+  const entries = [...text.matchAll(/\[\[gates\]\][\s\S]*?(?=\n\[\[gates\]\]|\n# rungs:end|$)/g)].map((m) => m[0]);
+  let examined = 0;
+  for (const entry of entries) {
+    const id = entry.match(/^id\s*=\s*"(.+)"/m)?.[1];
+    const kind = entry.match(/^kind\s*=\s*"(.+)"/m)?.[1];
+    const table = entry.match(/^table\s*=\s*"(.+)"/m)?.[1];
+    if (!id || kind !== 'declared' || !table) continue;
+    examined++;
+    // Tables live in the CLI, not the repo, so read them from the module set.
+    const tablePath = join(dirname(new URL(import.meta.url).pathname.slice(1)), '..', 'modules', dirname(table), 'gates', table.split('/').pop()!);
+    const src = existsSync(tablePath) ? readFileSync(tablePath, 'utf8') : '';
+    const forGate = [...src.matchAll(/\[\[self_test\]\][\s\S]*?(?=\n\[\[|\n\[|$)/g)]
+      .map((m) => m[0])
+      .filter((b) => b.includes(`gate   = "${id}"`) || b.includes(`gate    = "${id}"`) || b.includes(`gate = "${id}"`));
+    for (const direction of ['pass', 'fail']) {
+      if (!forGate.some((b) => new RegExp(`expect\\s*=\\s*"${direction}"`).test(b))) {
+        findings.push({ message: `gate '${id}' has no self-test expecting '${direction}'` });
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export const ENGINES: Record<string, Engine> = {
+  'file-budget': fileBudget,
+  sections,
+  'frontmatter-schema': frontmatterSchema,
+  'link-integrity': linkIntegrity,
+  'file-population': filePopulation,
+  'gate-meta': gateMeta,
+  'id-integrity': idIntegrity,
+  'render-freshness': renderFreshness,
+  'register-schema': registerSchema,
+  'filename-schema': filenameSchema,
+  'cross-reference': crossReference,
+  'git-status-reconcile': gitStatusReconcile,
+  'computed-claim': computedClaim,
+  'term-ownership': termOwnership,
+  'rule-propagation': rulePropagation,
+  'git-state': gitState,
+  'merge-driver-check': mergeDriverCheck,
+};
+
+/**
+ * Engines named in a gate table but not implemented here. Reported by name and
+ * treated as blocking — never as a pass.
+ *
+ * This is the single most dangerous failure this tool could have: a registry of
+ * 31 gates reporting green because 25 of them do nothing. rift-forge's rule
+ * generalises exactly — *we do not land on an unknown.*
+ */
+export function isImplemented(engine: string): boolean {
+  return engine in ENGINES;
+}

package/src/engines2.ts

@@ -0,0 +1,297 @@
+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)))];
+
+/** An exemption marker is ignored unless it states a reason. */
+const exempted = (text: string, marker?: string) =>
+  !!marker && new RegExp(`${marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\S`).test(text);
+
+/**
+ * Ids: uniqueness across the declared sources, citations that resolve, and the
+ * stale-blocker rule — a document may not say it waits on work that has finished.
+ */
+export const idIntegrity: Engine = (t, root, files) => {
+  const findings: Finding[] = [];
+  let examined = 0;
+  const known = new Set<string>();
+
+  for (const [, kind] of Object.entries<any>(t.kinds ?? {})) {
+    const re = new RegExp(`^\\s*id:\\s*(${kind.format})`, 'm');
+    const seen = new Map<string, string>();
+    for (const rel of expand(files, kind.sources)) {
+      examined++;
+      const text = read(root, rel);
+      const id = text.match(re)?.[1] ?? rel.match(new RegExp(kind.format))?.[0];
+      if (!id) continue;
+      known.add(id);
+      const prior = seen.get(id);
+      if (prior) findings.push({ file: rel, message: `id ${id} also claimed by ${prior}` });
+      else seen.set(id, rel);
+    }
+    // The marker must not name an id that is already spent.
+    if (kind.marker?.file) {
+      const m = read(root, kind.marker.file).match(new RegExp(kind.marker.pattern));
+      if (m?.[1] && seen.has(m[1])) {
+        findings.push({ file: kind.marker.file, message: `NEXT marker points at ${m[1]}, already taken` });
+      }
+    }
+  }
+
+  // Stale blockers. Vocabulary is narrow on purpose: a first draft that matched
+  // `until <id>` hit 29 lines of true history in one repo's own voice.
+  const sb = t.stale_blocker;
+  if (sb?.phrases?.length && known.size) {
+    const scope = expand(files, ['docs/**/*.md', 'AGENTS.md', 'CLAUDE.md']).filter(
+      (f) => !expand(files, sb.scope_exclude, []).includes(f),
+    );
+    const past = (sb.past_tense_ok ?? []).map((p: string) => p.toLowerCase());
+    for (const rel of scope) {
+      const text = read(root, rel);
+      if (exempted(text, sb.exempt_marker)) continue;
+      for (const phrase of sb.phrases) {
+        const re = new RegExp(`(.{0,${sb.negation_window ?? 60}})\\b${phrase}\\b\\s+([A-Z]{1,6}-\\d{1,4})`, 'gi');
+        for (const m of text.matchAll(re)) {
+          const lead = m[1].toLowerCase();
+          if (past.some((p: string) => lead.includes(p.split(' ')[0]) && lead.includes('was'))) continue;
+          if (/\bnot\b|\bnever\b|\bno longer\b/.test(lead.slice(-30))) continue;
+          if (isDone(root, m[2], files)) {
+            findings.push({ file: rel, message: `claims to be ${phrase} ${m[2]}, which is done` });
+          }
+        }
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+function isDone(root: string, id: string, files: string[]): boolean {
+  const hit = files.find((f) => f.includes(id) && f.endsWith('.md'));
+  if (!hit) return false;
+  const s = read(root, hit).match(/^status:\s*(\S+)/m)?.[1];
+  return s === 'done' || hit.includes('/archive/');
+}
+
+/** Generated output that no longer matches what its producer would emit now. */
+export const renderFreshness: Engine = (t, root, files) => {
+  const specs = Array.isArray(t) ? t : [t];
+  const findings: Finding[] = [];
+  let examined = 0;
+  for (const spec of specs) {
+    if (spec.block?.file) {
+      examined++;
+      const text = read(root, spec.block.file);
+      const re = new RegExp(`rungs:begin ${spec.block.marker}[\\s\\S]*?rungs:end ${spec.block.marker}`);
+      if (!re.test(text)) {
+        findings.push({ file: spec.block.file, message: `no '${spec.block.marker}' block — run \`${spec.command}\`` });
+      }
+      continue;
+    }
+    const excluded = new Set(expand(files, spec.exclude, []));
+    const sources = expand(files, spec.sources).filter((s) => !excluded.has(s));
+    const targets = expand(files, spec.targets);
+    // Only harnesses this repo actually emits for are checked; a missing
+    // `.cursor/rules` in a repo that never asked for Cursor is not staleness.
+    const live = new Set(targets.map((x) => x.split('/')[0]));
+    for (const src of sources) {
+      examined++;
+      const stem = src.split('/').pop()!.replace(/\.md$/, '');
+      for (const dir of live) {
+        if (!targets.some((x) => x.startsWith(dir) && x.includes(stem))) {
+          findings.push({ file: src, message: `no rendering under ${dir}/ — run \`${spec.command}\`` });
+        }
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+/** Markdown-table registers: required columns, enums, and conditional rules. */
+export const registerSchema: Engine = (t, root, files) => {
+  const findings: Finding[] = [];
+  let examined = 0;
+  const targets = t.file ? [t.file] : expand(files, t.scan);
+  for (const rel of targets) {
+    const text = read(root, rel);
+    if (!text) continue;
+    for (const table of parseTables(text)) {
+      if (t.table && !sectionOf(text, table.headerLine).toLowerCase().includes(String(t.table).toLowerCase())) continue;
+      const cols = t.required_cols ?? t.table_columns ?? [];
+      const present = cols.filter((c: string) =>
+        table.headers.some((h) => h.toLowerCase() === String(c).toLowerCase()),
+      );
+      // Recognition before validation: a file may hold several tables and only
+      // some are registers. Demanding every one carry the columns reported a
+      // spec index for not being a story table.
+      if (cols.length && present.length < Math.max(2, Math.ceil(cols.length / 2))) continue;
+      for (const c of cols) {
+        if (!present.includes(c)) findings.push({ file: rel, message: `register table missing column '${c}'` });
+      }
+      for (const row of table.rows) {
+        if (Object.values(row).every((v) => !v || v === '—')) continue;
+        examined++;
+        for (const [key, values] of Object.entries<any>(t.enum ?? {})) {
+          const v = strip(row[key]);
+          if (v && !values.map(String).includes(v)) {
+            findings.push({ file: rel, message: `${key}='${v}' not one of ${values.join(', ')}` });
+          }
+        }
+        for (const c of t.non_empty ?? []) {
+          if (!strip(row[c])) findings.push({ file: rel, message: `row ${firstCell(row)}: '${c}' is empty` });
+        }
+        for (const cond of t.conditional ?? []) {
+          const matches = Object.entries<any>(cond.when ?? {}).every(([k, v]) => strip(row[k]) === String(v));
+          if (!matches) continue;
+          for (const c of cond.non_empty ?? []) {
+            const v = strip(row[c]);
+            if (!v) findings.push({ file: rel, message: `row ${firstCell(row)}: '${c}' required when ${JSON.stringify(cond.when)}` });
+            else if (cond.min_words?.[c] && v.split(/\s+/).length < cond.min_words[c]) {
+              findings.push({ file: rel, message: `row ${firstCell(row)}: '${c}' is too thin to be a reason` });
+            }
+          }
+        }
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+const strip = (v?: string) => (v ?? '').replace(/[`*\[\]]/g, '').split('(')[0].trim();
+const firstCell = (row: Record<string, string>) => strip(Object.values(row)[0]) || '?';
+
+function parseTables(text: string) {
+  const out: { headers: string[]; rows: Record<string, string>[]; headerLine: number }[] = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*\|/.test(lines[i]) || !/^\s*\|[\s:|-]+\|/.test(lines[i + 1] ?? '')) continue;
+    const headers = cells(lines[i]);
+    const rows: Record<string, string>[] = [];
+    let j = i + 2;
+    for (; j < lines.length && /^\s*\|/.test(lines[j]); j++) {
+      const c = cells(lines[j]);
+      rows.push(Object.fromEntries(headers.map((h, k) => [h, c[k] ?? ''])));
+    }
+    out.push({ headers, rows, headerLine: i });
+    i = j;
+  }
+  return out;
+}
+const cells = (line: string) => line.trim().replace(/^\||\|$/g, '').split('|').map((s) => s.trim());
+const sectionOf = (text: string, line: number) => {
+  const before = text.split('\n').slice(0, line);
+  for (let i = before.length - 1; i >= 0; i--) if (/^#{1,6}\s/.test(before[i])) return before[i];
+  return '';
+};
+
+export const filenameSchema: Engine = (t, root, files) => {
+  const re = new RegExp(t.pattern);
+  const excluded = new Set(expand(files, t.exclude, []));
+  const findings: Finding[] = [];
+  let examined = 0;
+  for (const rel of expand(files, t.scan)) {
+    if (excluded.has(rel)) continue;
+    examined++;
+    const base = rel.split('/').pop()!;
+    if (!re.test(base)) findings.push({ file: rel, message: 'filename does not say what closed and what came next' });
+  }
+  return { findings, examined };
+};
+
+/** Skills naming their neighbours — only past the threshold where it matters. */
+export const crossReference: Engine = (t, root, files) => {
+  const skills = expand(files, t.scan);
+  if (skills.length < (t.min_skills ?? 6)) return { findings: [], examined: skills.length };
+  const names = skills.map((s) => s.split('/').slice(-2)[0]);
+  const findings: Finding[] = [];
+  for (const rel of skills) {
+    const text = read(root, rel);
+    if (exempted(text, t.exempt_marker)) continue;
+    const desc = text.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '';
+    const self = rel.split('/').slice(-2)[0];
+    if (!names.some((n) => n !== self && desc.includes(n))) {
+      findings.push({ file: rel, message: `names no neighbouring skill (${skills.length} in this repo)` });
+    }
+  }
+  return { findings, examined: skills.length };
+};
+
+/** A merged branch cannot still sit at a pre-review status. One-directional. */
+export const gitStatusReconcile: Engine = (t, root, files) => {
+  const findings: Finding[] = [];
+  let merged: Set<string>;
+  try {
+    merged = new Set(
+      execSync(`git branch --merged ${t.integration_branch ?? 'main'} --format=%(refname:short)`, {
+        cwd: root,
+        stdio: 'pipe',
+      })
+        .toString()
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean),
+    );
+  } catch {
+    // No git, or no such branch. Not a pass and not a failure — an unknown.
+    return { findings: [{ message: 'cannot read git branches; status not reconciled' }], examined: 0 };
+  }
+  let examined = 0;
+  for (const rel of expand(files, ['docs/**/items/**/*.md'])) {
+    const text = read(root, rel);
+    if (exempted(text, t.exempt_marker)) continue;
+    const branch = text.match(new RegExp(`^${t.branch_field ?? 'branch'}:\\s*(\\S+)`, 'm'))?.[1];
+    const status = text.match(new RegExp(`^${t.status_field ?? 'status'}:\\s*(\\S+)`, 'm'))?.[1];
+    if (!branch || !status) continue;
+    examined++;
+    if (merged.has(branch) && (t.pre_review_statuses ?? []).includes(status)) {
+      findings.push({ file: rel, message: `branch ${branch} is merged but status is '${status}'` });
+    }
+  }
+  return { findings, examined };
+};
+
+/** A number a machine can compute is never typed by a human. */
+export const computedClaim: Engine = (t, root, files) => {
+  const specs = Array.isArray(t) ? t : [t];
+  const findings: Finding[] = [];
+  let examined = 0;
+  for (const spec of specs) {
+    const values = new Map<string, string>();
+    for (const src of spec.sources ?? []) {
+      for (const rel of matchAny(files, src.file)) {
+        const text = read(root, rel);
+        let v: string | undefined;
+        if (src.path && rel.endsWith('.json')) {
+          try {
+            v = src.path.split('.').reduce((o: any, k: string) => o?.[k], JSON.parse(text));
+          } catch {
+            /* unparseable is not a disagreement */
+          }
+        } else if (src.xpath) {
+          v = text.match(new RegExp(`<${src.xpath.split('//')[1]}>(.*?)<`))?.[1];
+        }
+        if (v) {
+          examined++;
+          values.set(rel, String(v));
+        }
+      }
+    }
+    const distinct = new Set(values.values());
+    if (spec.rule === 'all-agree' && distinct.size > 1) {
+      findings.push({
+        message: `${spec.id} disagrees across ${values.size} locations: ${[...distinct].join(', ')} — run \`${spec.autofix}\``,
+      });
+    }
+  }
+  return { findings, examined };
+};