@rungs/cli 0.1.2 → 0.2.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}'` });
     }
   }

package/src/engines3.ts

@@ -15,6 +15,72 @@ 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, '\\$&');
 
+/** `1.2.3` → [1,2,3]; anything else → null. Deliberately not a semver parser. */
+export function versionParts(s: string): number[] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(s.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+export function versionCmp(a: number[], b: number[]): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+/**
+ * `changelog-freshness` — a consumed fragment that was never deleted.
+ *
+ * Fragments are consumed at release time, not archived: one left behind appears
+ * in the next release too, where it reads as unreleased work. `cut-release` §3
+ * has said so in prose since it was written, and prose did not hold it —
+ * `changelog.d/0.1.1.md` survived two releases and was still there at 0.2.0
+ * preparation (F-022). So the rule becomes mechanical.
+ *
+ * A fragment is stale when its filename names a version **below** the version
+ * being prepared. Files whose names are not versions are ignored rather than
+ * reported: the module's own fixtures use `42.feature.md`, and a gate that
+ * refuses a naming convention it was not asked about is a gate people disable.
+ */
+export const changelogFreshness: Engine = (t, root, files) => {
+  const specs = Array.isArray(t) ? t : [t];
+  const findings: Finding[] = [];
+  let examined = 0;
+
+  for (const spec of specs) {
+    const src = spec.version ?? {};
+    let current: number[] | null = null;
+    for (const rel of matchAny(files, src.file ?? 'package.json')) {
+      try {
+        const raw = (src.path ?? 'version')
+          .split('.')
+          .reduce((o: any, k: string) => o?.[k], JSON.parse(read(root, rel)));
+        current = versionParts(String(raw ?? ''));
+      } catch {
+        /* unparseable is not a stale fragment */
+      }
+      if (current) break;
+    }
+    // Without a version to compare against there is no claim to make. Saying
+    // nothing is right; passing loudly would not be.
+    if (!current) continue;
+
+    for (const rel of expand(files, spec.fragments, [])) {
+      const name = rel.split('/').pop()!.replace(/\.md$/, '');
+      const v = versionParts(name);
+      if (!v) continue;
+      examined++;
+      if (versionCmp(v, current) < 0) {
+        findings.push({
+          file: rel,
+          message:
+            spec.message?.trim() ||
+            `fragment names ${name}, below the ${current.join('.')} being prepared — it was consumed by an earlier release and should have been deleted`,
+        });
+      }
+    }
+  }
+
+  return { findings, examined };
+};
+
 /** 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);
@@ -192,3 +258,84 @@ export const mergeDriverCheck: Engine = (t, root) => {
   }
   return { findings, examined: declared.length };
 };
+
+/**
+ * The board's grouping must agree with each item's own `status` field.
+ *
+ * `git-status-reconcile` already reconciles a **branch** against that field, and
+ * this repo cites it constantly as proof that typed bookkeeping decays. Nothing
+ * reconciled the **board** — so on 2026-08-16 `BACKLOG.md` filed fourteen items
+ * under `Proposed` and `Planned` whose files all read `status: done`, nine of
+ * them linking into `archive/`. The board said *proposed* about a document in
+ * the directory for work that can no longer change.
+ *
+ * It was found by an outside reviewer asserting the framework research was done.
+ * They were right; the board would have told them otherwise. That is the same
+ * failure the whole module exists to prevent, one layer up, in the file every
+ * session opens first.
+ *
+ * Only table rows are read. The board's prose deliberately discusses finished
+ * work, and a paragraph is not a claim about status.
+ */
+export const boardReconcile: Engine = (t, root, _files) => {
+  const rel = t.file as string;
+  const text = read(root, rel);
+  if (!text) return { findings: [{ message: `board not found at ${rel}` }], examined: 0 };
+  if (exempted(text, t.exempt_marker)) return { findings: [], examined: 0 };
+
+  const groups: Record<string, string[]> = t.groups ?? {};
+  const dir = rel.split('/').slice(0, -1).join('/');
+  const findings: Finding[] = [];
+  let heading = '';
+  let examined = 0;
+
+  for (const line of text.split('\n')) {
+    const h = /^##\s+(.+?)\s*$/.exec(line);
+    if (h) {
+      heading = h[1];
+      continue;
+    }
+    if (!line.startsWith('|')) continue;
+
+    const link = /^\|\s*\[[^\]]+\]\(([^)]+)\)/.exec(line);
+    if (!link) continue; // separator, header, or an empty `| — |` placeholder
+
+    // An undeclared heading is narrative, not a status group. The board's later
+    // sections are prose with their own tables — "The first-user path", closed
+    // 2026-08-15, tabulates seven finished items and says so in the heading.
+    //
+    // Reporting those was this gate's first behaviour and it was wrong: measured
+    // 2026-08-16, it produced seven findings against a document that is correct.
+    // The plan's requirement that every undeclared heading be reported was aimed
+    // at a *typo* hiding rows from the check, and it caught legitimate prose
+    // instead. That case is covered exactly, below, by requiring each declared
+    // group to appear — a misspelled `Propsed` makes `Proposed` go missing.
+    if (!Object.hasOwn(groups, heading)) continue;
+
+    examined++;
+    const target = `${dir}/${link[1]}`.replace(/[^/]+\/\.\.\//g, '');
+    const item = read(root, target);
+    if (!item) {
+      findings.push({ file: rel, message: `row under '${heading}' links to a missing file: ${link[1]}` });
+      continue;
+    }
+    const status = /^status:\s*(\S+)/m.exec(item)?.[1] ?? '';
+    if (!groups[heading].includes(status)) {
+      findings.push({
+        file: rel,
+        message: `${link[1]} is under '${heading}' but its status is '${status}' (expected ${groups[heading].join(' | ')})`,
+      });
+    }
+  }
+
+  // Every declared group must actually appear. This is the typo check: a board
+  // whose `Proposed` heading is misspelled would otherwise drop those rows
+  // silently, which is exactly what the group map exists to prevent.
+  const seen = new Set([...text.matchAll(/^##\s+(.+?)\s*$/gm)].map((m) => m[1]));
+  for (const g of Object.keys(groups)) {
+    if (!seen.has(g)) findings.push({ file: rel, message: `declared group '${g}' has no heading in the board` });
+  }
+
+  return { findings, examined };
+};
+