@rungs/cli 0.3.1 → 0.4.0

package/src/engines2.ts

@@ -1,12 +1,16 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { resolveEmittedPath } from './emitted-path.ts';
 import { matchAny } from './glob.ts';
+import { readVersionSource } from './version-source.ts';
 import type { Engine, Finding } from './engines.ts';
+import { semanticText } from './text.ts';
 
 const read = (root: string, rel: string) => {
   try {
-    return readFileSync(join(root, rel), 'utf8');
+    return semanticText(readFileSync(join(root, rel), 'utf8'));
   } catch {
     return '';
   }
@@ -159,6 +163,12 @@ export const registerSchema: Engine = (t, root, files) => {
       }
       for (const row of table.rows) {
         if (Object.values(row).every((v) => !v || v === '—')) continue;
+        // An em dash in the identity column is an explicit no-record row. The
+        // generated findings register uses it to keep an empty table legible:
+        // `| — | | | *nothing open* | ... |`. Looking only for an entirely
+        // blank row made that label turn the placeholder into a malformed real
+        // finding on the first `rungs check` in a fresh tracked consumer.
+        if (strip(Object.values(row)[0]) === '—') continue;
         examined++;
         for (const [key, values] of Object.entries<any>(t.enum ?? {})) {
           const v = strip(row[key]);
@@ -360,6 +370,372 @@ export const crossReference: Engine = (t, root, files) => {
 const gitArgs = (root: string, args: string[]) =>
   execFileSync('git', args, { cwd: root, stdio: 'pipe' }).toString().trim();
 
+export const parseGitPathList = (output: string): string[] =>
+  output.split('\0').filter(Boolean);
+
+const gitPaths = (root: string, args: string[]) =>
+  parseGitPathList(execFileSync('git', args, { cwd: root, stdio: 'pipe' }).toString());
+
+const gitRefExists = (root: string, ref: string): boolean => {
+  try {
+    gitArgs(root, ['show-ref', '--verify', '--quiet', ref]);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export type IntegrationRefResolution =
+  | { ref: string; finding?: never }
+  | { ref?: never; finding: string };
+
+/**
+ * Resolve a configured branch name without Git's short-name DWIM rules.
+ *
+ * CI checkouts commonly have `origin/main` but no local `main`. Conversely, a
+ * developer checkout can carry both, temporarily at different commits. The
+ * precedence here is deliberate and stable as more remotes appear: local,
+ * exact `origin`, then a sole matching remote. More than one non-origin match
+ * is unknown, not permission to choose whichever ref Git happens to prefer.
+ */
+export function resolveIntegrationRef(root: string, branch: string): IntegrationRefResolution {
+  const local = `refs/heads/${branch}`;
+  if (gitRefExists(root, local)) return { ref: local };
+
+  const origin = `refs/remotes/origin/${branch}`;
+  if (gitRefExists(root, origin)) return { ref: origin };
+
+  const remotes = gitArgs(root, ['remote'])
+    .split('\n')
+    .map((remote) => remote.trim())
+    .filter((remote) => remote && remote !== 'origin');
+  const matches = remotes
+    .map((remote) => `refs/remotes/${remote}/${branch}`)
+    .filter((ref) => gitRefExists(root, ref))
+    .sort();
+
+  if (matches.length === 1) return { ref: matches[0] };
+  if (matches.length > 1) {
+    return {
+      finding: `integration branch '${branch}' is ambiguous across ${matches.join(', ')}`,
+    };
+  }
+  return {
+    finding: `integration branch '${branch}' has no local or remote-tracking ref`,
+  };
+}
+
+const matchesAny = (rel: string, patterns: string[] | undefined) =>
+  (patterns ?? []).some((pattern) => matchAny([rel], pattern).length > 0);
+
+const patternList = (value: unknown, allowEmpty = false): value is string[] =>
+  Array.isArray(value) && (allowEmpty || value.length > 0) &&
+  value.every((pattern) => typeof pattern === 'string' && pattern.trim().length > 0);
+
+type ExemptionWrapper = { kind: 'plain' | 'line' | 'block' | 'html' | 'quote'; close?: string };
+
+function wrapperCloseAt(reason: string, wrapper: ExemptionWrapper): number {
+  if (!wrapper.close) return -1;
+  if (wrapper.kind !== 'quote') return reason.indexOf(wrapper.close);
+  for (let index = 0; index < reason.length; index++) {
+    if (reason[index] === '\\') {
+      index++;
+    } else if (reason[index] === wrapper.close) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Extract substantive same-line reasons while retaining wrapper state across
+ * the whole document. A marker on the second line of a block, HTML comment or
+ * quoted string must still stop at that wrapper's close token; otherwise an
+ * adjacent code-only edit would be mistaken for a new reason.
+ */
+function exemptionEvidence(text: string, marker: string): string[] {
+  const evidence: string[] = [];
+  let wrapper: ExemptionWrapper = { kind: 'plain' };
+
+  for (let index = 0; index < text.length; index++) {
+    if (text.startsWith(marker, index)) {
+      const reasonAt = index + marker.length;
+      const cr = text.indexOf('\r', reasonAt);
+      const lf = text.indexOf('\n', reasonAt);
+      const lineEnd = cr < 0 ? (lf < 0 ? text.length : lf) :
+        (lf < 0 ? cr : Math.min(cr, lf));
+      const rawTail = text.slice(reasonAt, lineEnd);
+      const leading = rawTail.match(/^[ \t]*/)?.[0].length ?? 0;
+      if (/[\p{L}\p{N}]/u.test(rawTail[leading] ?? '')) {
+        let reason = rawTail.slice(leading);
+        const closeAt = wrapperCloseAt(reason, wrapper);
+        if (closeAt >= 0) reason = reason.slice(0, closeAt);
+        reason = reason.trimEnd();
+        if (reason) evidence.push(reason);
+      }
+    }
+
+    if (wrapper.kind === 'line') {
+      if (text[index] === '\r' || text[index] === '\n') wrapper = { kind: 'plain' };
+      continue;
+    }
+    if (wrapper.kind === 'block') {
+      if (text.startsWith('*/', index)) {
+        wrapper = { kind: 'plain' };
+        index++;
+      }
+      continue;
+    }
+    if (wrapper.kind === 'html') {
+      if (text.startsWith('-->', index)) {
+        wrapper = { kind: 'plain' };
+        index += 2;
+      }
+      continue;
+    }
+    if (wrapper.kind === 'quote') {
+      if (text[index] === '\\') {
+        index++;
+      } else if (text[index] === wrapper.close) {
+        wrapper = { kind: 'plain' };
+      }
+      continue;
+    }
+
+    if (text.startsWith('//', index)) {
+      wrapper = { kind: 'line' };
+      index++;
+    } else if (text.startsWith('/*', index)) {
+      wrapper = { kind: 'block', close: '*/' };
+      index++;
+    } else if (text.startsWith('<!--', index)) {
+      wrapper = { kind: 'html', close: '-->' };
+      index += 3;
+    } else if (text[index] === '"' || text[index] === "'" || text[index] === '`') {
+      wrapper = { kind: 'quote', close: text[index] };
+    }
+  }
+  return evidence;
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+
+type GitTreeEntry = { mode: string; type: string; oid: string };
+
+function gitTreeEntry(root: string, treeish: string, rel: string): GitTreeEntry | undefined {
+  const output = execFileSync(
+    'git',
+    ['--literal-pathspecs', 'ls-tree', '-z', treeish, '--', rel],
+    { cwd: root, stdio: 'pipe' },
+  );
+  if (!output.length) return undefined;
+  const records = output.toString('utf8').split('\0').filter(Boolean);
+  if (records.length !== 1) throw new Error(`unexpected tree entry count for ${rel}`);
+  const match = records[0].match(/^([0-7]{6}) ([a-z]+) ([0-9a-f]+)\t/);
+  if (!match) throw new Error(`cannot parse tree entry for ${rel}`);
+  return { mode: match[1], type: match[2], oid: match[3] };
+}
+
+function candidateGitModesAreRegular(root: string, rel: string): boolean {
+  const output = execFileSync(
+    'git',
+    ['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', rel],
+    { cwd: root, stdio: 'pipe' },
+  );
+  const entries = output.toString('utf8').split('\0').filter(Boolean).map((record) => {
+    const match = record.match(/^([0-7]{6}) [0-9a-f]+ ([0-3])\t/);
+    if (!match) throw new Error(`cannot parse index entry for ${rel}`);
+    return { mode: match[1], stage: match[2] };
+  });
+
+  // The index is the current proposed Git object when it has an entry. An
+  // absent entry is an untracked path whose canonical filesystem leaf was
+  // already proven regular above. HEAD is deliberately irrelevant here: its
+  // historical mode must not veto a staged conversion to an ordinary blob.
+  return entries.length === 0 ||
+    (entries.length === 1 && entries[0].stage === '0' &&
+      ['100644', '100755'].includes(entries[0].mode));
+}
+
+function candidateExemptionText(root: string, rel: string): string | undefined {
+  let resolved;
+  try {
+    resolved = resolveEmittedPath(root, 'release exemption evidence', rel);
+    if (resolved.leafAlias || !lstatSync(resolved.absolute).isFile()) return undefined;
+  } catch {
+    return undefined;
+  }
+  if (!candidateGitModesAreRegular(root, rel)) return undefined;
+
+  const attributes = execFileSync(
+    'git',
+    ['check-attr', '-z', 'diff', 'text', 'binary', '--', rel],
+    { cwd: root, stdio: 'pipe' },
+  ).toString().split('\0');
+  for (let index = 0; index + 2 < attributes.length; index += 3) {
+    const attribute = attributes[index + 1];
+    const value = attributes[index + 2];
+    if ((attribute === 'diff' && value === 'unset') || (attribute === 'binary' && value === 'set')) {
+      return undefined;
+    }
+  }
+
+  try {
+    const bytes = readFileSync(resolved.absolute);
+    if (bytes.includes(0)) return undefined;
+    return utf8.decode(bytes);
+  } catch {
+    return undefined;
+  }
+}
+
+function inheritedExemptionEvidence(root: string, mergeBase: string, marker: string): Set<string> {
+  let paths = Buffer.alloc(0);
+  try {
+    paths = execFileSync(
+      'git',
+      ['grep', '-I', '-l', '-z', '-F', '-e', marker, mergeBase, '--'],
+      { cwd: root, stdio: 'pipe' },
+    );
+  } catch (error: any) {
+    if (error?.status !== 1) throw error;
+    paths = Buffer.isBuffer(error?.stdout) ? error.stdout : Buffer.from(error?.stdout ?? '');
+  }
+
+  const prefix = `${mergeBase}:`;
+  const inherited = new Set<string>();
+  for (const named of utf8.decode(paths).split('\0').filter(Boolean)) {
+    if (!named.startsWith(prefix)) throw new Error('cannot parse historical exemption path');
+    const rel = named.slice(prefix.length);
+    const entry = gitTreeEntry(root, mergeBase, rel);
+    if (!entry || entry.type !== 'blob') throw new Error(`cannot resolve historical exemption blob for ${rel}`);
+    const bytes = execFileSync('git', ['cat-file', 'blob', entry.oid], { cwd: root, stdio: 'pipe' });
+    if (bytes.includes(0)) throw new Error(`historical exemption blob is not text: ${rel}`);
+    for (const reason of exemptionEvidence(utf8.decode(bytes), marker)) inherited.add(reason);
+  }
+  return inherited;
+}
+
+/**
+ * Return only exemption evidence introduced by the complete current delta.
+ *
+ * Current files are read only through a canonical, regular-file, UTF-8 text
+ * boundary. The caller's complete changed-path set already spans committed,
+ * staged, unstaged and non-ignored untracked work, so staging does not select a
+ * different evidence path.
+ *
+ * A reason must be novel relative to every marker/reason line in the merge-base
+ * tree. That conservative rule makes the otherwise unknowable copy-vs-coincidence
+ * case deterministic in every Git state: reuse or relocation requires rewording
+ * the reason to explain why this branch is safe.
+ */
+function hasBranchLocalExemption(
+  root: string,
+  mergeBase: string,
+  changed: string[],
+  marker: string,
+): boolean {
+  const inherited = inheritedExemptionEvidence(root, mergeBase, marker);
+
+  return changed.some((rel) => {
+    const text = candidateExemptionText(root, rel);
+    return text !== undefined && exemptionEvidence(text, marker)
+      .some((reason) => !inherited.has(reason));
+  });
+}
+
+/**
+ * Require a changed companion file when a branch changes a configured path.
+ *
+ * A fragment that merely exists is not evidence for this branch: inherited and
+ * deleted fragments must not discharge its release-note obligation. Git state
+ * is read as four explicit sets so the verdict is the same before and after a
+ * developer stages or commits the work.
+ */
+export const changeRequiresFile: Engine = (t, root) => {
+  if (!patternList(t.require_when_changed) || !patternList(t.requires_one_of)) {
+    return {
+      findings: [{
+        message: "change-requires-file requires non-empty 'require_when_changed' and 'requires_one_of' pattern arrays",
+      }],
+      examined: 0,
+    };
+  }
+  if (t.ignore_when_only !== undefined && !patternList(t.ignore_when_only, true)) {
+    return {
+      findings: [{ message: "change-requires-file 'ignore_when_only' must be an array of non-empty patterns" }],
+      examined: 0,
+    };
+  }
+  if (t.exempt_marker !== undefined &&
+      (typeof t.exempt_marker !== 'string' || !t.exempt_marker.trim())) {
+    return {
+      findings: [{ message: "change-requires-file 'exempt_marker' must be a non-empty string when configured" }],
+      examined: 0,
+    };
+  }
+
+  const baseName = String(t.base_branch ?? 'main');
+  let changed: string[];
+  let mergeBase: string;
+  let untracked: string[];
+  try {
+    const resolved = resolveIntegrationRef(root, baseName);
+    if (!resolved.ref) {
+      return {
+        findings: [{ message: `${resolved.finding}; required companion file not evaluated` }],
+        examined: 0,
+      };
+    }
+    mergeBase = gitArgs(root, ['merge-base', 'HEAD', resolved.ref]);
+    untracked = gitPaths(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+    changed = [...new Set([
+      ...gitPaths(root, ['diff', '--name-only', '--no-renames', '-z', mergeBase, 'HEAD']),
+      ...gitPaths(root, ['diff', '--cached', '--name-only', '--no-renames', '-z']),
+      ...gitPaths(root, ['diff', '--name-only', '--no-renames', '-z']),
+      ...untracked,
+    ])].sort();
+  } catch {
+    return {
+      findings: [{ message: `cannot read git changes against '${baseName}'; required companion file not evaluated` }],
+      examined: 0,
+    };
+  }
+
+  const examined = changed.length;
+  const ignore = t.ignore_when_only as string[] | undefined;
+  if (ignore?.length && changed.length && changed.every((rel) => matchesAny(rel, ignore))) {
+    return { findings: [], examined };
+  }
+
+  if (!changed.some((rel) => matchesAny(rel, t.require_when_changed))) {
+    return { findings: [], examined };
+  }
+
+  const companion = changed.find(
+    (rel) => matchesAny(rel, t.requires_one_of) && existsSync(join(root, rel)),
+  );
+  if (companion) return { findings: [], examined };
+
+  if (t.exempt_marker) {
+    try {
+      if (hasBranchLocalExemption(root, mergeBase, changed, t.exempt_marker)) {
+        return { findings: [], examined };
+      }
+    } catch {
+      return {
+        findings: [{ message: `cannot read git exemption provenance against '${baseName}'; required companion file not evaluated` }],
+        examined: 0,
+      };
+    }
+  }
+
+  return {
+    findings: [{ message: String(t.message ?? 'changed shipping code requires a companion file').trim() }],
+    examined,
+  };
+};
+
 function landedWork(root: string, branch: string, base: string): boolean {
   const git = (...args: string[]) => gitArgs(root, args);
   try {
@@ -378,9 +754,14 @@ function landedWork(root: string, branch: string, base: string): boolean {
 export const gitStatusReconcile: Engine = (t, root, files) => {
   const findings: Finding[] = [];
   let merged: Set<string>;
+  let integrationRef: string;
   try {
+    const integration = String(t.integration_branch ?? 'main');
+    const resolved = resolveIntegrationRef(root, integration);
+    if (!resolved.ref) return { findings: [{ message: `${resolved.finding}; status not reconciled` }], examined: 0 };
+    integrationRef = resolved.ref;
     merged = new Set(
-      gitArgs(root, ['branch', '--merged', t.integration_branch ?? 'main', '--format=%(refname:short)'])
+      gitArgs(root, ['branch', '--merged', integrationRef, '--format=%(refname:short)'])
         .split('\n')
         .map((s) => s.trim())
         .filter(Boolean),
@@ -400,7 +781,7 @@ export const gitStatusReconcile: Engine = (t, root, files) => {
     if (
       merged.has(branch) &&
       (t.pre_review_statuses ?? []).includes(status) &&
-      landedWork(root, branch, t.integration_branch ?? 'main')
+      landedWork(root, branch, integrationRef)
     ) {
       findings.push({ file: rel, message: `branch ${branch} is merged but status is '${status}'` });
     }
@@ -415,6 +796,7 @@ export const computedClaim: Engine = (t, root, files) => {
   let examined = 0;
   for (const spec of specs) {
     const values = new Map<string, string>();
+    let specExamined = 0;
     // 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
@@ -422,27 +804,28 @@ export const computedClaim: Engine = (t, root, files) => {
     // 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);
+    const excludePatterns = (spec.exclude ?? []).filter((pattern: unknown): pattern is string =>
+      typeof pattern === 'string' && pattern.trim().length > 0,
+    );
+    const excluded = (rel: string) => excludePatterns.some((pattern: string) => matchAny([rel], pattern).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')) {
-          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));
+        examined++;
+        specExamined++;
+        const result = readVersionSource(root, rel, src);
+        if (!result.ok) {
+          findings.push({ file: rel, message: `${spec.id} version source ${result.reason}` });
+          continue;
         }
+        values.set(rel, result.value);
       }
     }
+    if (specExamined === 0) {
+      findings.push({
+        message: `${spec.id} found no configured version sources; check the source globs and exclusions`,
+      });
+    }
     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
@@ -456,7 +839,7 @@ export const computedClaim: Engine = (t, root, files) => {
         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`.'),
+          (excludePatterns.length ? '' : '. If one of these is versioned independently, set `release.version_exclude`.'),
       });
     }
   }

package/src/engines3.ts

@@ -3,10 +3,12 @@ import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { matchAny } from './glob.ts';
 import type { Engine, Finding } from './engines.ts';
+import { readVersionSource } from './version-source.ts';
+import { semanticText } from './text.ts';
 
 const read = (root: string, rel: string) => {
   try {
-    return readFileSync(join(root, rel), 'utf8');
+    return semanticText(readFileSync(join(root, rel), 'utf8'));
   } catch {
     return '';
   }
@@ -34,10 +36,15 @@ export function versionCmp(a: number[], b: number[]): number {
  * `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.
+ * The repository also states the last version whose fragments were consumed.
+ * That boundary must equal the package version in a steady tree, and a fragment
+ * at or below it is stale. Equality is what closes F-025: after a release, the
+ * forgotten fragment and package version are equal, so comparing only those two
+ * values cannot tell preparation from already-consumed work.
+ *
+ * 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];
@@ -45,34 +52,119 @@ export const changelogFreshness: Engine = (t, root, files) => {
   let examined = 0;
 
   for (const spec of specs) {
-    const src = spec.version ?? {};
+    const sources = Array.isArray(spec.versions)
+      ? spec.versions
+      : [spec.version ?? { file: 'package.json', path: '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 */
+    let currentSource = '';
+    const versionProblems: Finding[] = [];
+    for (const source of sources) {
+      for (const rel of matchAny(files, source.file ?? 'package.json')) {
+        const result = readVersionSource(root, rel, source);
+        if (!result.ok) {
+          versionProblems.push({ file: rel, message: `release version source ${result.reason}` });
+          continue;
+        }
+        const parsed = versionParts(result.value);
+        if (!parsed) {
+          versionProblems.push({
+            file: rel,
+            message: `release version source must contain a three-part numeric version; found ${JSON.stringify(result.value)}`,
+          });
+          continue;
+        }
+        current = parsed;
+        if (current) {
+          currentSource = rel;
+          break;
+        }
       }
       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;
+    const marker = spec.consumed_through ?? 'changelog.d/CONSUMED_THROUGH';
+    const markerExists = existsSync(join(root, marker));
+    if (!markerExists) {
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker '${marker}' is missing — create it with 'none' if no release has consumed fragments, or the exact last consumed version`,
+      });
+      continue;
+    }
+
+    examined++;
+    const markerRaw = read(root, marker);
+    const markerValue = markerRaw.endsWith('\r\n')
+      ? markerRaw.slice(0, -2)
+      : markerRaw.endsWith('\n')
+        ? markerRaw.slice(0, -1)
+        : markerRaw;
+
+    if (markerValue === 'UNINITIALIZED') {
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker '${marker}' is UNINITIALIZED — replace it with 'none' if no release has consumed fragments, or the exact last consumed version`,
+      });
+      continue;
+    }
+
+    const firstRelease = markerValue === 'none';
+    // `versionParts` intentionally trims package metadata. The marker is a
+    // one-token schema, so validate its complete content before reusing that
+    // parser; whitespace, a BOM or a second newline must not become valid.
+    const consumed = firstRelease || !/^\d+\.\d+\.\d+$/.test(markerValue)
+      ? null
+      : versionParts(markerValue);
+    if (!firstRelease && !consumed) {
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker '${marker}' must contain exactly 'none' or a three-part numeric version; found ${JSON.stringify(markerValue)}`,
+      });
+      continue;
+    }
+
+    findings.push(...versionProblems);
+
+    // Without a package version there used to be no claim to make. A concrete
+    // consumption boundary changes that: its steady-state equality cannot be
+    // checked, so reporting green would make the new state assertion vacuous.
+    if (!current) {
+      if (consumed) {
+        findings.push({
+          file: sources[0]?.file ?? 'package.json',
+          message:
+            `cannot reconcile consumed-through ${markerValue} because none of the declared version sources contains a three-part numeric version`,
+        });
+      }
+      continue;
+    }
+
+    if (consumed && versionCmp(consumed, current) !== 0) {
+      const relation = versionCmp(consumed, current) < 0 ? 'below' : 'above';
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker names ${markerValue}, ${relation} version ${current.join('.')} in ${currentSource} — they must match in a steady tree; advance both during reversible release preparation`,
+      });
+    }
 
     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) {
+      const belowPackage = versionCmp(v, current) < 0;
+      const alreadyConsumed = consumed ? versionCmp(v, consumed) <= 0 : false;
+      if (belowPackage || alreadyConsumed) {
         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`,
+            (alreadyConsumed
+              ? `fragment names ${name}, at or below consumed-through ${markerValue} — it was already assembled and should have been deleted`
+              : `fragment names ${name}, below package version ${current.join('.')} — it belongs to an earlier release and should have been deleted`),
         });
       }
     }
@@ -339,4 +431,3 @@ export const boardReconcile: Engine = (t, root, _files) => {
 
   return { findings, examined };
 };
-

package/src/explain.ts

@@ -1,6 +1,7 @@
 import { ENGINES, type Finding } from './engines.ts';
-import { loadTable, tableKey } from './check.ts';
+import { loadTable } from './check.ts';
 import type { DetectResult, Manifest } from './types.ts';
+import { selectEngineTable } from './engine-table.ts';
 
 /**
  * `doctor` answers a *presence* question — which of our modules does this repo
@@ -138,12 +139,7 @@ export function explainWith(
       }
 
       try {
-        const key = tableKey(g.engine!);
-        let section = table[key] ?? table;
-        if (Array.isArray(section) && section.some((s: any) => s?.id)) {
-          const mine = section.filter((s: any) => !s.id || g.id.includes(s.id));
-          if (mine.length) section = mine;
-        }
+        const section = selectEngineTable(table, g.engine!, g.id);
         const r = engines[g.engine!](section, repoRoot, files);
         if (r.findings.length) {
           reported.push({ module: mod.name, gate: g.id, why: g.why, findings: r.findings, examined: r.examined });