@rungs/cli 0.1.3 → 0.3.0

package/src/engines.ts

@@ -1,6 +1,10 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { matchAny, walk } from './glob.ts';
+import { parse as parseToml } from 'smol-toml';
+import { runSelfTests } from './selftest.ts';
+import { loadAllModules } from './manifest.ts';
+import { resolveParams, substitute } from './substitute.ts';
 import {
   computedClaim,
   crossReference,
@@ -11,7 +15,7 @@ import {
   renderFreshness,
   selfDeclaredClosure,
 } from './engines2.ts';
-import { gitState, mergeDriverCheck, rulePropagation, termOwnership } from './engines3.ts';
+import { boardReconcile, changelogFreshness, gitState, mergeDriverCheck, rulePropagation, termOwnership } from './engines3.ts';
 
 export interface Finding {
   file?: string;
@@ -70,7 +74,13 @@ const fileBudget: Engine = (t, root, files) => {
     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}` });
+    // "1358 lines" invites `wc -l`, which answered 1413 on the same file
+    // (hexguard-templates, 2026-08-16) because this counts what actually *loads*
+    // — frontmatter, HTML comments and blank lines stripped. Naming the measure
+    // is the difference between evidence and a number the reader disproves.
+    if (n > t.max_lines) {
+      findings.push({ file: rel, message: `${n} loaded lines (blank lines and comments excluded), budget ${t.max_lines}` });
+    }
   }
   return { findings, examined };
 };
@@ -86,7 +96,8 @@ const sections: Engine = (t, root, files) => {
       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]);
+      const matches = [...text.matchAll(/^(#{1,6})\s+(.+?)\s*$/gm)];
+      const heads = matches.map((m) => m[2]);
       for (const want of spec.required ?? []) {
         const idx = heads.findIndex((h) => h.toLowerCase().startsWith(String(want).toLowerCase()));
         if (idx === -1) {
@@ -94,8 +105,18 @@ const sections: Engine = (t, root, files) => {
           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();
+          // Content runs to the next heading of the **same or higher** level, so
+          // a section made of subsections is not empty. Splitting on any heading
+          // reported ADR-0002's `## Decision` as empty because a `### (a)`
+          // follows it immediately — the first finding this gate produced, and a
+          // false one (F-018). A section whose whole body is subsections is the
+          // normal shape for a long decision.
+          const level = matches[idx][1].length;
+          const after = text.slice(matches[idx].index! + matches[idx][0].length);
+          const body = after
+            .split(new RegExp(`^#{1,${level}}\\s+`, 'm'))[0]
+            .replace(/<!--[\s\S]*?-->/g, '')
+            .trim();
           if (!body) findings.push({ file: rel, message: `section '${want}' is empty` });
         }
       }
@@ -107,7 +128,7 @@ const sections: Engine = (t, root, files) => {
   return { findings, examined };
 };
 
-const frontmatterSchema: Engine = (t, root, files) => {
+export const frontmatterSchema: Engine = (t, root, files) => {
   const specs = Array.isArray(t) ? t : [t];
   const findings: Finding[] = [];
   let examined = 0;
@@ -126,22 +147,129 @@ const frontmatterSchema: Engine = (t, root, files) => {
         if (!keys.includes(req)) findings.push({ file: rel, message: `missing '${req}'` });
       }
       if (spec.allowed) {
+        // `extensions_allowed_from` names the manifest that may legalise a
+        // non-spec key. It was declared in the skills table and read nowhere
+        // (F-019), so an extension a module had deliberately opted into was
+        // indistinguishable from one somebody typed by mistake — and the
+        // portability cost the opt-in exists to record was attached to nothing.
+        const optedIn = spec.extensions_allowed_from ? optedInExtensions(rel, spec) : new Set<string>();
         for (const k of keys) {
-          if (!spec.allowed.includes(k)) findings.push({ file: rel, message: `non-spec key '${k}'` });
+          if (spec.allowed.includes(k) || optedIn.has(k)) continue;
+          findings.push({ file: rel, message: `non-spec key '${k}'` });
         }
       }
+      const field = (k: string) => m[1].match(new RegExp(`^${k}:\\s*(.+)$`, 'm'))?.[1].trim().replace(/^["']|["']$/g, '');
       for (const [key, values] of Object.entries(spec.enum ?? {})) {
-        const v = m[1].match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1].trim().replace(/^["']|["']$/g, '');
+        const v = field(key);
         if (v && !(values as string[]).map(String).includes(v)) {
           findings.push({ file: rel, message: `${key}='${v}' not one of ${(values as string[]).join(', ')}` });
         }
       }
+
+      // `[frontmatter_schema.reciprocal]` was configured in the `adr` table and
+      // implemented nowhere — the third instance of F-007's shape, and this one
+      // was found by *executing* a self-test rather than by reading (F-018).
+      // Its fail fixture is a `superseded` record with no `superseded_by`, which
+      // could never have failed while nothing read the rule.
+      //
+      // A one-way supersession leaves a reader on the stale record with no route
+      // to the live one, which is the whole point of recording it.
+      for (const pair of spec.reciprocal?.pairs ?? []) {
+        const from = field(pair.from);
+        if (!from) continue;
+        const target = expand(files, spec.scan).find((r) => r.includes(from.replace(/\.md$/, '')));
+        if (!target) {
+          findings.push({ file: rel, message: `${pair.from} names '${from}', which is not a record here` });
+          continue;
+        }
+        const back = read(root, target).match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '';
+        const id = field('id') ?? '';
+        if (!new RegExp(`^${pair.to}:\\s*.*${escapeRe(id)}`, 'm').test(back)) {
+          findings.push({ file: rel, message: `${pair.from} → ${from}, but it does not name this record back in '${pair.to}'` });
+        }
+      }
+      // A status that implies the pairing must actually carry it.
+      for (const [status, requires] of Object.entries(spec.reciprocal?.required_when ?? {})) {
+        if (field('status') === status && !field(String(requires))) {
+          findings.push({ file: rel, message: `status is '${status}' but '${requires}' is absent` });
+        }
+      }
     }
   }
   return { findings, examined };
 };
 
-const linkIntegrity: Engine = (t, root, files) => {
+/**
+ * Does a link target resolve, under any reading of it?
+ *
+ * `path/to/file.ts:387` is a code reference, not a broken link — it is the form
+ * `CLAUDE.md` mandates in this repo ("Reference code as `file_path:line_number`")
+ * and the form editors and terminals click. The engine resolved it literally and
+ * reported the file missing while the file sat exactly there.
+ *
+ * Measured 2026-08-16 on `rift-forge` via `doctor --explain`: **1,794 of 3,851
+ * link findings — 46.6% — were this**, every one a real file with a line number
+ * after it. Latent since WI-008 made link checking per-link; before that, one
+ * `{{token}}` anywhere in a file exempted every link in it, which hid it.
+ *
+ * Resolve as written first, and only then retry without a trailing `:line` or
+ * `:line:col`. Strip-and-retest rather than strip-and-assume: a link is called
+ * broken only when **no** reading of it resolves, so this can only ever remove
+ * findings. Stripping unconditionally would silence a genuinely missing
+ * `foo.ts:12` whenever an equally missing `foo.ts` explained it away.
+ */
+function resolvesHere(root: string, rel: string, href: string): boolean {
+  const from = dirname(rel);
+  const decoded = decodeURIComponent(href);
+  if (existsSync(resolve(root, from, decoded))) return true;
+  const stripped = decoded.replace(/:\d+(?::\d+)?$/, '');
+  return stripped !== decoded && existsSync(resolve(root, from, stripped));
+}
+
+/**
+ * A backticked path in an instruction file — `docs/backlog/BACKLOG.md` — that no
+ * longer exists. F-007: `backticked_paths` was named in the table's `check` list
+ * and implemented nowhere, so `gates-paths-exist` silently ran the markdown-link
+ * scan instead and reported every finding a second time.
+ *
+ * Resolved from the **repo root**, because that is what an instruction file's
+ * reader does with a path it is told to go and read. Skipped when the span is a
+ * glob, a template token, a URL, or has no path shape at all: prose is full of
+ * `identifiers`, and a gate that refuses every code span is one people delete.
+ */
+function backtickedPaths(rel: string, text: string, root: string, hints: string[]): Finding[] {
+  const out: Finding[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+    const raw = m[1].trim();
+    if (seen.has(raw) || !hints.some((h) => raw.includes(h))) continue;
+    seen.add(raw);
+
+    // Every exclusion below is a measured false positive from the first run of
+    // this check against this repo, 2026-08-16 — which produced ten findings,
+    // all ten wrong. The table's own instruction is that under-detection is the
+    // correct bias, so the shape is narrowed to the incident it was written for:
+    // hexguard's instruction files naming a **repo-relative file** that moved.
+    if (raw.startsWith('/')) continue; //            `/work-item` — a skill invocation
+    if (/[*?{}#\s]|^\w+:/.test(raw)) continue; //    globs, `WI-###` placeholders, prose, URLs
+    if (!raw.includes('/')) continue; //             `work-items.md` — a bare name, anchor unknown
+    if (!/\.[a-z0-9]{1,5}$/i.test(raw)) continue; // `.cursor/rules/` — a directory, often illustrative
+
+    // Two anchors, because instruction files use both: repo-root paths for "go
+    // read this", and `../` paths relative to the file itself.
+    const bare = raw.replace(/^\.\//, '');
+    if (!existsSync(join(root, bare)) && !existsSync(resolve(root, dirname(rel), bare))) {
+      out.push({ message: `stale path in a code span → ${raw}` });
+    }
+  }
+  return out;
+}
+
+export const linkIntegrity: Engine = (t, root, files) => {
+  // The table is now one entry per gate (F-007). The runner hands an array
+  // through when it selects by id; take the single entry it selected.
+  if (Array.isArray(t)) t = t[0] ?? {};
+  const checks: string[] = t.check ?? ['relative_markdown_links'];
   const scan = expand(files, t.scan, ['**/*.md']);  // link checks DO cover generated files
   const excluded = new Set(expand(files, t.exclude, []));
   const findings: Finding[] = [];
@@ -151,6 +279,10 @@ const linkIntegrity: Engine = (t, root, files) => {
     const text = read(root, rel);
     examined++;
     if (/path-ok:\s*\S/.test(text)) continue;
+    if (checks.includes('backticked_paths')) {
+      findings.push(...backtickedPaths(rel, text, root, t.path_hint ?? ['/']).map((f) => ({ ...f, file: rel })));
+    }
+    if (!checks.includes('relative_markdown_links')) continue;
     // A link written inside a code span is prose *quoting* a link — most often a document
     // explaining that some link is wrong. Blanked rather than removed, so every offset after it
     // is unchanged and the reported text still matches what the author sees.
@@ -163,8 +295,7 @@ const linkIntegrity: Engine = (t, root, files) => {
       // The case the file-level skip was written for — `modules/*/fragments/AGENTS.md` linking
       // `{{path}}/README.md` — is already excluded by path in `link_integrity.exclude` (WI-008).
       if (/\{\{[a-z_.]+\}\}/.test(m[1])) continue;
-      const target = resolve(root, dirname(rel), decodeURIComponent(m[1]));
-      if (!existsSync(target)) findings.push({ file: rel, message: `broken link → ${m[1]}` });
+      if (!resolvesHere(root, rel, m[1])) findings.push({ file: rel, message: `broken link → ${m[1]}` });
     }
   }
   return { findings, examined };
@@ -194,7 +325,17 @@ const filePopulation: Engine = (t, root, files) => {
   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]})` });
+    // The count is only re-derivable if the reader knows what was counted.
+    // `audit-output-is-rows` reported 275 on hexguard while the obvious
+    // one-pattern `find` answered 268 (2026-08-16) — the gate scans three
+    // patterns, and the message named none of them, so the correct number read
+    // as a wrong one.
+    const scanned = [t.scan ?? []].flat();
+    findings.push({
+      message:
+        `${hits.length} matching file(s), threshold ${failAt} (e.g. ${hits[0]})` +
+        (scanned.length ? ` — matched against ${scanned.join(', ')}` : ''),
+    });
   }
   return { findings, examined: hits.length };
 };
@@ -204,8 +345,11 @@ const filePopulation: Engine = (t, root, files) => {
  * 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) => {
+export const gateMeta: Engine = (_t, root) => {
   const findings: Finding[] = [];
+
+  let unrun = 0;
+
   const registry = join(root, '.ai', 'gates.toml');
   if (!existsSync(registry)) return { findings, examined: 0 };
   const text = readFileSync(registry, 'utf8');
@@ -228,12 +372,114 @@ const gateMeta: Engine = (_t, root) => {
         findings.push({ message: `gate '${id}' has no self-test expecting '${direction}'` });
       }
     }
+
+    // WI-045 / F-018: declaring is not asserting. Every fixture whose shape and
+    // engine can be reproduced faithfully is executed, and a disagreement is a
+    // finding of this gate.
+    //
+    // Turning this on found, in order: `adr`'s orphaned `[sections]` table, two
+    // fixtures labelled for a gate that checks something else, a `reciprocal`
+    // rule read by nothing, a `non_empty` check that called any section with
+    // subsections empty, three fixtures orphaned by a schema that moved modules,
+    // `session-sections-present` wired to an engine whose table it does not have
+    // (so it passed by examining nothing), `[register_schema.open]` read by
+    // nothing, and a table matcher loose enough that "resolve-open-findings" in
+    // a filename made a Closed section match the Open schema.
+    //
+    // None of it was visible while the fixtures were documentation.
+    const engine = entry.match(/^engine\s*=\s*"(.+)"/m)?.[1];
+    const parsed = parseTable(tablePath, table.split('/')[0]);
+    if (engine && parsed) {
+      const blocks = (Array.isArray(parsed.self_test) ? parsed.self_test : [])
+        .filter((b: any) => b?.gate === id)
+        .map((b: any) => ({ expect: String(b.expect), input: b.input, fixture: b.fixture }));
+      for (const r of runSelfTests(id, engine, parsed[tableKeyFor(engine)] ?? parsed, blocks)) {
+        if (r.outcome === 'mismatch') findings.push({ message: `self-test for '${id}' ${r.detail}` });
+        else if (r.outcome === 'unrun') unrun++;
+      }
+    }
   }
+
+  // Stated, never silent. Most fixtures still cannot be reproduced — their
+  // shapes need context the format does not carry — and reporting green while
+  // most of the suite never executed would be F-006 one level up. A note rather
+  // than a failure: an unbuildable fixture is not a defect in the gate.
+  if (unrun) console.error(`      ${unrun} self-test fixture(s) have no builder and did not run — not passes (F-018)`);
   return { findings, examined };
 };
 
+/**
+ * Which non-spec frontmatter keys are legal for this skill, because the module
+ * that ships it opted in.
+ *
+ * The skill's name is its directory — `.claude/skills/work-item/SKILL.md` — and
+ * the answer lives in whichever module declares `[skills.work-item]`. Read from
+ * the CLI's module set rather than from the repo, so a consumer cannot legalise
+ * an extension by editing a file: the opt-in belongs to the module that took the
+ * portability cost.
+ *
+ * `extensions_opted_in` overrides it, which is how a self-test fixture states
+ * the opt-in without needing a module on disk.
+ */
+function optedInExtensions(rel: string, spec: any): Set<string> {
+  if (Array.isArray(spec.extensions_opted_in)) return new Set(spec.extensions_opted_in.map(String));
+  const name = rel.split('/').slice(-2)[0];
+  if (!name) return new Set();
+  try {
+    const mods = loadAllModules(join(dirname(new URL(import.meta.url).pathname.slice(1)), '..', 'modules'));
+    const owner = mods.find((m) => m.skills?.[name]?.extensions);
+    return new Set(Object.keys(owner?.skills?.[name]?.extensions ?? {}));
+  } catch {
+    return new Set();
+  }
+}
+
 const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+/**
+ * A gate table, parsed. Substitution is deliberately *not* applied: a fixture's
+ * `{{token}}` is part of what it asserts, and the runner needs the table's raw
+ * shape rather than one repo's resolved parameters.
+ */
+function parseTable(path: string, module: string): any | null {
+  if (!existsSync(path)) return null;
+  try {
+    // Substituted with the module's **real defaults**, not a placeholder. Using
+    // `probe` turned the skills schema's scan into `probe/**/SKILL.md` while its
+    // fixture still wrote `.claude/skills/x/SKILL.md`, so the engine saw no file
+    // and the runner reported the gate broken — a mismatch entirely of the
+    // harness's making. A fixture and the table it tests must resolve against
+    // the same parameters or neither means anything.
+    const mods = loadAllModules(join(dirname(new URL(import.meta.url).pathname.slice(1)), '..', 'modules'));
+    const params = resolveParams(mods, {}, '.');
+    return parseToml(substitute(readFileSync(path, 'utf8'), module, params));
+  } catch {
+    return null;
+  }
+}
+
+/** Duplicated from `check.ts` rather than imported, to keep engines dependency-free of the runner. */
+const tableKeyFor = (engine: string) =>
+  ({
+    'file-budget': 'file_budget',
+    'frontmatter-schema': 'frontmatter_schema',
+    'link-integrity': 'link_integrity',
+    'file-population': 'file_population',
+    'render-freshness': 'render_freshness',
+    'register-schema': 'register_schema',
+    'self-declared-closure': 'self_declared_closure',
+    'filename-schema': 'filename_schema',
+    'cross-reference': 'cross_reference',
+    'git-status-reconcile': 'merged_status',
+    'computed-claim': 'computed_claim',
+    'term-ownership': 'term_ownership',
+    'rule-propagation': 'rule_propagation',
+    'git-state': 'git_state',
+    'merge-driver-check': 'merge_driver_check',
+    'board-reconcile': 'board_reconcile',
+    'changelog-freshness': 'changelog_freshness',
+  })[engine] ?? engine;
+
 export const ENGINES: Record<string, Engine> = {
   'file-budget': fileBudget,
   sections,
@@ -253,6 +499,8 @@ export const ENGINES: Record<string, Engine> = {
   'rule-propagation': rulePropagation,
   'git-state': gitState,
   'merge-driver-check': mergeDriverCheck,
+  'board-reconcile': boardReconcile,
+  'changelog-freshness': changelogFreshness,
 };
 
 /**

package/src/engines2.ts

@@ -121,12 +121,31 @@ export const renderFreshness: Engine = (t, root, files) => {
 export const registerSchema: Engine = (t, root, files) => {
   const findings: Finding[] = [];
   let examined = 0;
-  const targets = t.file ? [t.file] : expand(files, t.scan);
+
+  // A register file holds more than one table, and each gets its own spec —
+  // `[register_schema]` for Closed and `[register_schema.open]` for Open. Only
+  // the top-level one was ever read (F-018), so the Open table's rules —
+  // `non_empty = ["Sev", "Pri", "What", "Evidence"]` and the Sev/Pri enums —
+  // had never been enforced on any repo. Found because the fixture asserting
+  // them could not fire, once fixtures started running.
+  //
+  // A sub-spec is any nested object naming a `table`; `enum` and `min_words` are
+  // objects too and do not.
+  const specs = [t, ...Object.values(t).filter((v: any) => v && typeof v === 'object' && !Array.isArray(v) && v.table)];
+  for (const t of specs as any[]) {
+  const targets = t.file ?? specs[0].file ? [t.file ?? (specs[0] as any).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;
+      // The heading must **start with** the table's name, not merely contain it.
+      // A substring match sent every Closed row through the Open schema, because
+      // `## Closed — 2026-08-16 by [WI-044](archive/WI-044-resolve-open-findings.md)`
+      // contains "open" inside a filename. Latent until `[register_schema.open]`
+      // was read for the first time (F-018) — a loose matcher is invisible while
+      // only one spec exists to match.
+      const heading = sectionOf(text, table.headerLine).replace(/^#+\s*/, '').trim().toLowerCase();
+      if (t.table && !heading.startsWith(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()),
@@ -164,6 +183,7 @@ export const registerSchema: Engine = (t, root, files) => {
       }
     }
   }
+  }
   return { findings, examined };
 };
 
@@ -297,6 +317,48 @@ export const crossReference: Engine = (t, root, files) => {
 };
 
 /** A merged branch cannot still sit at a pre-review status. One-directional. */
+/**
+ * Did this branch actually land work, or is it a label pointing at a commit the
+ * base already had?
+ *
+ * `git branch --merged` answers "is the tip an ancestor", which is true of a
+ * branch cut five seconds ago and never committed to. F-001: reproduced
+ * 2026-08-15 on WI-001 and hit three more times on 2026-08-16 — every item
+ * worked through `/work-item` trips it in the window between `git switch -c`
+ * and the first commit. A gate that cries wolf on the happy path is one people
+ * learn to ignore, which is the failure it exists to prevent.
+ *
+ * The obvious fix — "has commits ahead of base" — is wrong, and measuring it
+ * proved so: **after any merge the branch is zero commits ahead**, so the gate
+ * would never fire again. That silently deletes the check while looking like a
+ * fix, which is worse than the false positive.
+ *
+ * What actually distinguishes them is the merge commit. This repo merges
+ * `--no-ff` (backlog README §4), so a branch that landed work leaves a commit in
+ * the base whose *second* parent is that branch's tip. A branch that landed
+ * nothing never appears as anyone's second parent.
+ *
+ * **Known gap, stated rather than hidden:** a fast-forward merge that keeps the
+ * branch produces no merge commit and no second parent, so this reads it as
+ * having landed nothing and stays quiet. That is a false negative on a workflow
+ * this repo does not use — it deletes branches on merge — and it is the
+ * direction to be wrong in, because the alternative is the daily false positive.
+ */
+function landedWork(root: string, branch: string, base: string): boolean {
+  const git = (cmd: string) => execSync(`git ${cmd}`, { cwd: root, stdio: 'pipe' }).toString().trim();
+  try {
+    const tip = git(`rev-parse ${branch}`);
+    if (tip === git(`rev-parse ${base}`)) return false;
+    return git(`log ${base} --merges --format=%P`)
+      .split('\n')
+      .some((line) => line.trim().split(/\s+/).slice(1).includes(tip));
+  } catch {
+    // Unreadable is not provably empty. Report, which fails loudly rather than
+    // silently — the same rule the runner applies to a missing engine.
+    return true;
+  }
+}
+
 export const gitStatusReconcile: Engine = (t, root, files) => {
   const findings: Finding[] = [];
   let merged: Set<string>;
@@ -323,7 +385,11 @@ export const gitStatusReconcile: Engine = (t, root, files) => {
     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)) {
+    if (
+      merged.has(branch) &&
+      (t.pre_review_statuses ?? []).includes(status) &&
+      landedWork(root, branch, t.integration_branch ?? 'main')
+    ) {
       findings.push({ file: rel, message: `branch ${branch} is merged but status is '${status}'` });
     }
   }
@@ -337,8 +403,17 @@ export const computedClaim: Engine = (t, root, files) => {
   let examined = 0;
   for (const spec of specs) {
     const values = new Map<string, string>();
+    // Which files share a version is the repo's judgement, not something to infer
+    // (F-023). The default sources glob `*/package.json`, which is right for a
+    // monorepo released in lockstep and wrong for a sibling that is deliberately
+    // versioned on its own — this repo's docs site sat at 0.0.1 beside a 0.2.0
+    // package, correctly, and installing the gate would have failed a healthy
+    // layout. So a repo states the exceptions rather than the engine guessing
+    // them, and `all-agree` keeps needing no opinion about which file is right.
+    const excluded = (rel: string) => (spec.exclude ?? []).some((p: string) => matchAny([rel], p).length > 0);
     for (const src of spec.sources ?? []) {
       for (const rel of matchAny(files, src.file)) {
+        if (excluded(rel)) continue;
         const text = read(root, rel);
         let v: string | undefined;
         if (src.path && rel.endsWith('.json')) {
@@ -358,8 +433,18 @@ export const computedClaim: Engine = (t, root, files) => {
     }
     const distinct = new Set(values.values());
     if (spec.rule === 'all-agree' && distinct.size > 1) {
+      // Name the file beside its value. The message used to list the distinct
+      // values and then say "run `{autofix}`" — which pointed at
+      // `rungs release sync-version`, a command that does not exist and never
+      // has. Telling someone to run a missing command is worse than telling
+      // them nothing, so the finding now carries what they actually need: which
+      // file says what. The hint is appended only if a real one is declared.
+      const where = [...values.entries()].map(([rel, v]) => `${rel}=${v}`).join(', ');
       findings.push({
-        message: `${spec.id} disagrees across ${values.size} locations: ${[...distinct].join(', ')} — run \`${spec.autofix}\``,
+        message:
+          `${spec.id} disagrees across ${values.size} locations: ${where}` +
+          (spec.autofix ? ` — run \`${spec.autofix}\`` : '') +
+          (spec.exclude?.length ? '' : '. If one of these is versioned independently, list it in `exclude`.'),
       });
     }
   }