simt-dev 0.6.3 → 0.7.1

package/src/decisions/dir.mjs

@@ -0,0 +1,84 @@
+// The one answer to "where are this repository's decision records" (review 0003 Q55).
+//
+// Before this, every reader hard-coded `docs/decisions` while detection already
+// knew four spellings (`docs/decisions`, `docs/adr`, `docs/adrs`, `adr`), so a
+// repository that kept its records under `docs/adr/` was fingerprinted correctly
+// and then unread by every command. One resolution, every reader.
+//
+// Precedence is declaration first. A manifest `decisions.dir` names the directory
+// relative to the repository root; without one, the first existing candidate
+// wins; without any, the default is `docs/decisions`. The cutoff below answers
+// the companion question — which records predate structured frontmatter — and it
+// lives in the same config (`decisions.historicalCutoff`), never in code.
+
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readManifest } from '../projection/manifest.mjs';
+
+/** Directory spellings a repository's decision records live under, in priority order. */
+const DECISION_DIR_CANDIDATES = ['docs/decisions', 'docs/adr', 'docs/adrs', 'adr'];
+
+/** The default when nothing is declared and nothing exists yet. */
+const DEFAULT_DECISIONS_DIR = 'docs/decisions';
+
+/**
+ * The repository's own `decisions` manifest key, or null.
+ *
+ * Read with the manifest loader (so the legacy name resolves the same way for
+ * this as for every other reader) and returned as-is: validation belongs to
+ * the caller that knows what it needs.
+ */
+async function manifestDecisions(root) {
+  try {
+    const { manifest } = await readManifest(root);
+    const decisions = manifest?.decisions;
+    return decisions !== null && typeof decisions === 'object' && !Array.isArray(decisions) ? decisions : null;
+  } catch {
+    // An unreadable manifest is not evidence either way; detection decides.
+    return null;
+  }
+}
+
+async function isDir(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The relative decisions directory for this repository.
+ *
+ * @param {string} root repository root
+ * @returns {Promise<string>} e.g. `docs/decisions`
+ */
+export async function decisionsDir(root) {
+  const declared = await manifestDecisions(root);
+  if (typeof declared?.dir === 'string' && declared.dir.trim() !== '') {
+    return declared.dir.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  }
+  for (const candidate of DECISION_DIR_CANDIDATES) {
+    if (await isDir(join(root, candidate))) return candidate;
+  }
+  return DEFAULT_DECISIONS_DIR;
+}
+
+/**
+ * How many leading records predate structured frontmatter and are exempt from it.
+ *
+ * The package's own history is the only corpus with such records, and even it
+ * declares the number in its own manifest rather than in code: a number in code
+ * is a second answer the next record silently moves. Any other repository gets
+ * zero unless it declares otherwise.
+ *
+ * @param {string} root repository root
+ * @returns {Promise<number>}
+ */
+export async function decisionsCutoff(root) {
+  const declared = await manifestDecisions(root);
+  const value = declared?.historicalCutoff;
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return Math.floor(value);
+  return 0;
+}

package/src/decisions/index-doc.mjs

@@ -0,0 +1,46 @@
+// The decisions index document, rendered from the records (review 0003 Q91).
+//
+// The file was 590 hand-written lines: a table of every ADR kept in step by whoever
+// remembered. It agreed with the records until it did not, and nothing read it, so
+// nothing noticed - the failure the generated rule regions exist to prevent, one
+// directory over. The table is output now: this module renders it, `simt rules
+// decisions --yes` writes it, and test/decisions-index.test.mjs fails on drift.
+//
+// The narrative that trailed the table moved to docs/architecture/history.md: prose a
+// reader consults is not prose a command rewrites.
+
+const HEADER = `# Decisions
+
+Architecture decision records for the SIMT development ecosystem. One canonical home per
+decision; nothing here is duplicated into a repo's \`AGENTS.md\`.
+
+A decision is superseded by writing a new ADR with a higher number and editing the old
+record's status line — never by editing the ruling in place.
+
+This table is generated from the records: \`simt rules decisions --yes\` writes it, and
+\`test/decisions-index.test.mjs\` fails when it drifts. The history behind the numbers is
+in [architecture/history.md](architecture/history.md).
+
+| ADR | Decision | Status |
+|---|---|---|
+`;
+
+/**
+ * The index document, from the records.
+ *
+ * Ordered by number, not by filename: the number IS the order, and a directory listing
+ * is not (`ADR-100` sorts before `ADR-99` as text).
+ *
+ * @param {{id: string, title: string, status: string, file: string}[]} rows
+ * @returns {string}
+ */
+export function renderDecisionsIndex(rows) {
+  const ordered = [...rows].sort((a, b) => number(a.id) - number(b.id));
+  const lines = ordered.map((row) => `| [${number(row.id)}](decisions/${row.file}) | ${row.title} | ${row.status} |`);
+  return `${HEADER}${lines.join('\n')}\n`;
+}
+
+/** `ADR-007` -> `007`, the number the table and the ordering both use. */
+function number(id) {
+  return id.replace(/^ADR-/i, '').padStart(3, '0');
+}

package/src/decisions/index.mjs

@@ -14,13 +14,20 @@
 // such, because "no decision behind this" is exactly what a reviewer needs to
 // see and exactly what an empty output would hide.
 
-import { readFile, readdir } from 'node:fs/promises';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MANIFEST_FILE } from '../name.mjs';
 import { CLI } from '../name.mjs';
 import { PREFIX_ARGUING, TOOL_WORDS } from '../toolwords.mjs';
+import { LOCAL_DIR } from '../state.mjs';
+import { packageVersion } from '../package-version.mjs';
+// Q55: read lazily (see commandVerbs). The registry imports the `decide`
+// command, which imports this module, so touching COMMANDS during module
+// evaluation would read an initialising binding on one of the two load
+// orders. Every use below happens at runtime, when both sides are loaded.
+import { COMMANDS } from '../commands/index.mjs';
 import { PARTIAL_CLAUSE, parseDecisionFrontmatter, splitFrontmatter } from '../memory/decide.mjs';
 import { affectsTokens } from '../index/govern.mjs';
 
@@ -82,7 +89,16 @@ export function redactInternalPaths(text) {
   return String(text ?? '').replace(internalPathPattern(), 'a file in this tool');
 }
 
-const ADR_IN_TEXT = /\bADR-(\d{3})\b/g;
+// Q55: four digits and more are real record numbers, not a typo. The old `\d{3}`
+// silently dropped every citation past ADR-999, and lexical sorting put ADR-1000
+// before ADR-999 in every listing that trusted string order.
+const ADR_IN_TEXT = /\bADR-(\d{3,})\b/g;
+
+/** Numeric sort for record ids: ADR-1000 follows ADR-999, not ADR-100. */
+function compareAdrIds(a, b) {
+  const num = (id) => Number(id.replace(/^ADR-/i, ''));
+  return num(a) - num(b) || (a < b ? -1 : a > b ? 1 : 0);
+}
 
 /**
  * A line that begins one of the record's other front-matter fields.
@@ -159,7 +175,7 @@ export function citations(text) {
   for (const match of String(text ?? '').matchAll(ADR_IN_TEXT)) {
     found.add(`ADR-${match[1]}`);
   }
-  return [...found].sort();
+  return [...found].sort(compareAdrIds);
 }
 
 /**
@@ -252,7 +268,11 @@ export function parseDecision(file, text, { all = false } = {}) {
 export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   let names;
   try {
-    names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/.test(n)).sort();
+    // Numeric, so the first record `byId` keeps under a duplicate is deterministic
+    // (lint flags the collision; the load does not guess between two files).
+    names = (await readdir(dir))
+      .filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n))
+      .sort((a, b) => compareAdrIds(adrIdOf(a) ?? a, adrIdOf(b) ?? b));
   } catch (error) {
     return { ok: false, decisions: [], errors: [`${dir}: unreadable (${error.message})`] };
   }
@@ -300,11 +320,72 @@ export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   return { ok: errors.length === 0, decisions, errors };
 }
 
+/** The record id a filename claims, or null when it claims none. */
+function adrIdOf(file) {
+  return /^ADR-(\d{3,})/i.exec(file)?.[0]?.toUpperCase() ?? null;
+}
+
 /** Index by id, for a lookup per cited ADR. */
 export function byId(decisions) {
   return new Map(decisions.map((d) => [d.id, d]));
 }
 
+/** The command verbs a record may quote, derived from the dispatch registry. */
+export function decisionVerbs() {
+  return commandVerbs();
+}
+
+/** One file's cache identity: name, size and mtime. Any write changes one of them. */
+async function fileSignature(dir, name) {
+  const st = await stat(join(dir, name));
+  return { name, size: st.size, mtimeMs: st.mtimeMs };
+}
+
+/**
+ * Load the records, reusing a machine-local cache when the tree is unchanged.
+ *
+ * Every call used to re-parse every record (`rules why` 44 ms; part of
+ * `resources/list` 771 ms). The cache lives under `.simt/local/` — machine
+ * state, never committed — and is keyed on the directory, the `all` flag, the
+ * running version and one signature per file, so an edit, an add or an upgrade
+ * all miss honestly. Best-effort throughout: any cache failure loads fresh.
+ *
+ * @param {{root: string, dir: string, all?: boolean}} input `dir` is absolute;
+ *   callers resolve it with `decisionsDir(root)` (or the package directory for
+ *   shipped records) so this loader never guesses whose records these are.
+ */
+export async function loadDecisionsCached({ root, dir, all = false } = {}) {
+  const cachePath = root ? join(root, LOCAL_DIR, 'decisions.index.json') : null;
+  let files = null;
+  try {
+    const names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n));
+    files = [];
+    for (const name of names) files.push(await fileSignature(dir, name));
+    files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  } catch {
+    return loadDecisions({ all, dir });
+  }
+  const key = { v: 1, tool: packageVersion(), dir, all, files };
+  if (cachePath) {
+    try {
+      const cached = JSON.parse(await readFile(cachePath, 'utf8'));
+      if (JSON.stringify(cached.key) === JSON.stringify(key)) return cached.result;
+    } catch {
+      // A missing or corrupt cache is a miss, never an error.
+    }
+  }
+  const fresh = await loadDecisions({ all, dir });
+  if (cachePath) {
+    try {
+      await mkdir(join(root, LOCAL_DIR), { recursive: true });
+      await writeFile(cachePath, JSON.stringify({ key, result: fresh }), 'utf8');
+    } catch {
+      // A read-only checkout keeps working uncached.
+    }
+  }
+  return fresh;
+}
+
 /**
  * What the decision actually says, in the reader's terms.
  *
@@ -506,7 +587,7 @@ const section = (name) => {
     // A record whose subject is the prefix is arguing rather than citing, so it names none.
     writtenAgainst: PREFIX_ARGUING.has(file)
       ? []
-      : [...new Set((text.match(ESTATE) ?? []).filter((name) => !TOOL_WORDS.has(name)))].sort(),
+      : [...new Set((text.match(ESTATE) ?? []).filter((name) => !TOOL_WORDS.has(name.toLowerCase())))].sort(),
   };
 }
 
@@ -545,8 +626,11 @@ const section = (name) => {
  * them - which is what this file used to do. Detection of those now depends on a name
  * never being written into shipped text, rather than on a check.
  */
-export const ESTATE_NAME =
-  /\b(?:simt-(?!dev\b)[\w-]+|repo-\d{2})\b/;
+// Q55: one shape, two flags. The estate-name pattern used to be written out twice
+// (`ESTATE_NAME` and `ESTATE`), so a shape fixed in one kept matching in the other.
+const ESTATE_SOURCE = '\\b(?:simt-(?!dev\\b)[\\w-]+|repo-\\d{2})\\b';
+
+export const ESTATE_NAME = new RegExp(ESTATE_SOURCE);
 
 /** Replace estate repository names with a phrase a reader who does not have them can use. */
 export function redactEstate(text) {
@@ -554,7 +638,7 @@ export function redactEstate(text) {
     // The tool's own names are left where they are. Redacting them turned a ruling about
     // `simt-priority` into a sentence about `a repository`, which is how a reader learned
     // that the record had surveyed something and not what it said (ADR-080).
-    TOOL_WORDS.has(name) ? name : 'a repository',
+    TOOL_WORDS.has(name.toLowerCase()) ? name : 'a repository',
   );
 }
 
@@ -575,10 +659,24 @@ export function redactEstate(text) {
  * Only a real verb follows, which is what keeps `simt-dev.json`, `simt-dev-check.yml` and
  * `simt-dev's` untouched - those are the project's artefacts and the project keeps its name.
  */
-const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|agent-hook|agent-hooks|mcp|rules|skills|graph|tokens|harness|bench|shared|evidence|index|map|tests|why|gate|impact|lessons|decide|brief|plan|--[a-z-]+)';
+// Q55: the verbs a record may quote are the commands this binary dispatches,
+// not a hand list. The list used to miss `pack`, `plugin` and `lease`, so a record
+// quoting one read as prose instead of a runnable command.
+let verbAlternation = null;
+function commandVerbs() {
+  if (verbAlternation === null) {
+    const words = new Set();
+    for (const path of COMMANDS) {
+      const first = path.split(' ')[0];
+      if (first) words.add(first.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    }
+    verbAlternation = `(?:${[...words].sort().join('|')}|--[a-z-]+)`;
+  }
+  return verbAlternation;
+}
 
 function redactCommand(text) {
-  return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);
+  return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${commandVerbs()})\\b`, 'g'), `${CLI} `);
 }
 
 /**
@@ -590,7 +688,7 @@ function redactCommand(text) {
  * enumerating the names here put the portfolio in every adopting repository. The records
  * themselves now carry `repo-NN` labels, so that is what this matches in practice.
  */
-const ESTATE = /\b(?:simt-(?!dev\b)[\w-]+|repo-\d{2})\b/gi;
+const ESTATE = new RegExp(ESTATE_SOURCE, 'gi');
 
 /** Trim to whole sentences within a budget, never leaving a stub fragment. */
 function sentence(text, limit = 260) {

package/src/diff.mjs

@@ -49,7 +49,7 @@ export async function readBefore(path) {
 export function emitDiffs(pairs, flags) {
   if (isJson(flags)) return;
   const text = renderDiffs(pairs);
-  if (text !== '') emit(text, { maxBytes: flags.maxBytes ?? 0 });
+  if (text !== '') emit(text);
 }
 
 /** The `--diff` bytes for a JSON payload: absent entirely without the flag, so

package/src/distill/distill.mjs

@@ -34,7 +34,10 @@ import {
 } from './engine.mjs';
 
 export const DEFAULT_BUDGET = 2048;
-const DISTILL_DIR = '.simt/distilled';
+import { LOCAL_DIR } from '../state.mjs';
+import { commandRoot } from '../repo-root.mjs';
+
+const DISTILL_DIR = join(LOCAL_DIR, 'distilled');
 
 /**
  * The row's acceptance metric, stated where a caller reads results (ADR-076):
@@ -173,7 +176,7 @@ export async function distillTarget(args, flags) {
     );
   }
 
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const source = await resolveTarget(target, root, flags);
   if (source.exit !== undefined) return source.exit;
 
@@ -190,6 +193,16 @@ export async function distillTarget(args, flags) {
   const cached = flags.refresh === true ? null : await readFile(absProposal, 'utf8').catch(() => null);
   if (cached !== null) {
     const fields = parseExistingFrontmatter(cached);
+    let faults = [];
+    if (typeof fields.faults === 'string') {
+      try {
+        const parsedFaults = JSON.parse(fields.faults);
+        if (Array.isArray(parsedFaults)) faults = parsedFaults.map(String);
+      } catch {
+        // A malformed faults line is not a reason to refuse the proposal; the proposal
+        // still says it is unverified, and `--refresh` re-derives the list.
+      }
+    }
     return {
       ok: true,
       command: 'distill',
@@ -199,6 +212,7 @@ export async function distillTarget(args, flags) {
       budget: Number(fields.budget ?? budget),
       citations: countCitations(cached),
       verified: fields.verified !== 'false',
+      faults,
       metric: { note: METRIC_NOTE },
       proposal: { path: relProposal, state: 'cached', bytes: Buffer.byteLength(cached, 'utf8') },
     };
@@ -225,6 +239,7 @@ export async function distillTarget(args, flags) {
       engine: provenance,
       budget,
       verified: faults.length === 0,
+      faults,
     }) + `\n${outcome.body}\n`;
 
   await mkdir(join(root, DISTILL_DIR), { recursive: true });

package/src/distill/engine.mjs

@@ -167,7 +167,7 @@ export function verifyCitations(body, sourceLineCount) {
 }
 
 /** The proposal file's frontmatter. No wall-clock value here: byte-stable (P4). */
-export function proposalFrontmatter({ source, digest, engine, budget, prompt, verified, verdict, advisory }) {
+export function proposalFrontmatter({ source, digest, engine, budget, prompt, verified, verdict, advisory, faults = [] }) {
   return [
     '---',
     `source: ${source}`,
@@ -178,6 +178,10 @@ export function proposalFrontmatter({ source, digest, engine, budget, prompt, ve
     verdict ? `verdict: ${verdict}` : null,
     advisory ? 'advisory: true' : null,
     verified === false ? 'verified: false' : 'verified: true',
+    // The faults belong to the proposal, not only to the report that wrote it: a cached
+    // proposal re-read without them reported `verified:false` and nothing to fix
+    // (review 0003 Q52).
+    Array.isArray(faults) && faults.length > 0 ? `faults: ${JSON.stringify(faults)}` : null,
     'status: proposal',
     '---',
     '',

package/src/ecosystem/node-runner.mjs

@@ -0,0 +1,144 @@
+// The one Node runner resolver every consumer reads (review 0003 Q31).
+//
+// Before this, four tables answered "how does this repo run a script" and
+// disagreed: the card printed `npm run`, the dispatcher spawned `npm run`,
+// the manifest remedies named `npm run`, and CI installed with `npm ci` — in a
+// repository whose lockfile and `packageManager` said pnpm. A pnpm adoption
+// then failed on its first pull request, and a docs-only or Go repo got
+// remedies proposing npm gates it could never run.
+//
+// One data table, one resolver, every consumer. The table is records, not
+// code, so the Q70 ecosystem work can adopt it without a second answer: a
+// future `ecosystems/<id>.json` row carries the same fields and this resolver
+// stays the shape of the lookup.
+//
+// Precedence is committed evidence first. A lockfile on disk names the manager
+// the repo actually installs with; `packageManager` names the one it declares.
+// Where the two disagree `checkToolchain` already reports `mismatched`, and the
+// runner follows the lockfile — the install step must restore the tree CI
+// checks out, not the field. With no lockfile the declared field wins over the
+// npm default, so a fresh `pnpm init` names pnpm before its first install.
+
+export const NODE_MANAGERS = [
+  {
+    id: 'pnpm',
+    lockfiles: ['pnpm-lock.yaml'],
+    fact: 'has-pnpm-lock',
+    run: 'pnpm',
+    install: 'pnpm install --frozen-lockfile',
+    installFallback: 'pnpm install',
+    addDev: 'pnpm add -D',
+    silent: true,
+    setupNode: true,
+  },
+  {
+    id: 'yarn',
+    lockfiles: ['yarn.lock'],
+    fact: 'has-yarn-lock',
+    run: 'yarn',
+    install: 'yarn install --frozen-lockfile',
+    installFallback: 'yarn install',
+    addDev: 'yarn add -D',
+    silent: true,
+    setupNode: true,
+  },
+  {
+    id: 'bun',
+    lockfiles: ['bun.lock', 'bun.lockb'],
+    fact: 'has-bun-lock',
+    run: 'bun',
+    install: 'bun install --frozen-lockfile',
+    installFallback: 'bun install',
+    addDev: 'bun add -d',
+    silent: false,
+    setupNode: false,
+  },
+  {
+    id: 'npm',
+    lockfiles: ['package-lock.json'],
+    fact: 'has-package-lock',
+    run: 'npm',
+    install: 'npm ci',
+    installFallback: 'npm install',
+    addDev: 'npm i -D',
+    silent: true,
+    setupNode: true,
+  },
+];
+
+const BY_ID = new Map(NODE_MANAGERS.map((row) => [row.id, row]));
+const BY_LOCKFILE = new Map();
+for (const row of NODE_MANAGERS) {
+  for (const file of row.lockfiles) BY_LOCKFILE.set(file, row);
+}
+const BY_FACT = new Map(NODE_MANAGERS.map((row) => [row.fact, row]));
+
+/** The npm row. Exported so callers never spell a default twice. */
+export function npmManager() {
+  return BY_ID.get('npm');
+}
+
+/**
+ * Name the manager a `packageManager` field declares, or null.
+ *
+ * `packageManager` is `manager@version`; only the manager names the runner.
+ * Unknown managers and non-strings are null, never a guess.
+ */
+export function managerFromPackageField(value) {
+  if (typeof value !== 'string') return null;
+  const id = value.split('@')[0].trim();
+  return BY_ID.has(id) ? id : null;
+}
+
+/**
+ * Resolve the one Node runner for a repository.
+ *
+ * @param {{facts?: string[]|Set<string>, lockfiles?: string[], packageManager?: string|null}} input
+ * @returns {object} the NODE_MANAGERS row that owns this repo
+ */
+export function resolveNodeRunner({ facts = [], lockfiles = [], packageManager = null } = {}) {
+  const present = facts instanceof Set ? facts : new Set(facts);
+  for (const row of NODE_MANAGERS) {
+    if (present.has(row.fact)) return row;
+    for (const file of row.lockfiles) {
+      if (lockfiles.includes(file)) return row;
+    }
+  }
+  const declared = managerFromPackageField(packageManager);
+  if (declared) return BY_ID.get(declared);
+  return npmManager();
+}
+
+/** Whether this runner id spells gates as `<run> run <script>`. */
+export function isNodeRunner(runner) {
+  return BY_ID.has(runner);
+}
+
+/** The command that runs one script: `pnpm run lint`, `bun run lint`. */
+export function runScript(manager, script) {
+  const id = typeof manager === 'string' ? manager : manager?.id ?? 'npm';
+  const run = BY_ID.get(id)?.run ?? 'npm';
+  return `${run} run ${script}`;
+}
+
+/** The argv the dispatcher spawns for one script gate. */
+export function runScriptArgv(manager, script) {
+  const id = typeof manager === 'string' ? manager : manager?.id ?? 'npm';
+  const row = BY_ID.get(id) ?? npmManager();
+  if (row.silent) return [row.run, 'run', '--silent', script];
+  return [row.run, 'run', script];
+}
+
+/** Install step for CI: the frozen command plus its fallback. */
+export function installCommands(manager) {
+  const row = typeof manager === 'string' ? (BY_ID.get(manager) ?? npmManager()) : (manager ?? npmManager());
+  return { install: row.install, fallback: row.installFallback, setupNode: row.setupNode };
+}
+
+/** Look up a manager record by lockfile name, fact, or id. */
+export function lookupNodeManager({ lockfile = null, fact = null, id = null } = {}) {
+  if (id && BY_ID.has(id)) return BY_ID.get(id);
+  if (lockfile && BY_LOCKFILE.has(lockfile)) return BY_LOCKFILE.get(lockfile);
+  if (fact && BY_FACT.has(fact)) return BY_FACT.get(fact);
+  return null;
+}

package/src/explain.mjs

@@ -59,8 +59,8 @@ export const EXPLAIN_CODES = {
   },
   'file-lines': {
     what: 'A file exceeds the 1000-line hard ceiling: it fails the gate.',
-    why: 'ADR-005: 400 lines is a review trigger, 1000 is a hard ceiling, and generated files are exempt. The ceiling is a default a repository can narrow, never a number an agent negotiates at write time.',
-    fix: 'Split the file, or narrow the ceiling deliberately in the rule that declares it — not by editing the generated line.',
+    why: 'ADR-005: 400 lines is a review trigger, 1000 is a hard ceiling, and excluded files are exempt. The ceiling is a default a repository can narrow, never a number an agent negotiates at write time.',
+    fix: 'Split the file, or name it in limits.fileLines.exclude — not by editing the generated line.',
     example: 'A 1240-line module with no exemption: FILE-LINES names the file and the count.',
   },
   'file-lines-warn': {
@@ -94,10 +94,10 @@ export const EXPLAIN_CODES = {
     example: 'gates.cwd.test set to "../shared" in a monorepo member.',
   },
   inconsistent: {
-    what: 'The TypeScript base config disagrees with this tool\u2019s floor in a way no flag explains: the project\u2019s tsconfig and the shipped base describe different compilers.',
-    why: 'ADR-025 and ADR-026: the base file is owned here and pointed at there, so a disagreement is a real fork in what the typechecker enforces — not a formatting choice. A repo that edited the owned bytes is not drift, but a repo whose config contradicts them is.',
-    fix: 'Re-align the project tsconfig with the shipped base, or record why the fork is deliberate.',
-    example: 'A project tsconfig setting strict false under a base that requires it.',
+    what: 'The project\u2019s tsconfig spells `moduleResolution` in a form the TypeScript parser accepts but the documentation does not, so it compiles and quietly disagrees with every repository that spells it the documented way.',
+    why: 'The parser is case-insensitive, which is the whole reason a workspace drifts on this key: both spellings work, so nothing ever said the other one did not. Consistency with the documentation is the only spelling checkable in one repository at a time \u2014 consistency with the other repositories would need a workspace, and `check` runs in a repository on its own.',
+    fix: 'Use the documented spelling the finding names; it compiles identically.',
+    example: '"moduleResolution": "Bundler" where the documentation writes "bundler".',
   },
   inert: {
     what: 'The TypeScript base config is present but inert: nothing in the repository reads it, so it constrains no file.',
@@ -117,6 +117,12 @@ export const EXPLAIN_CODES = {
     fix: 'Fix the simt-supersedes entry to [{ adr: "ADR-NNN", ruling: N }], with a real record and ruling number.',
     example: 'simt-supersedes: [{ adr: "ADR-999", ruling: 1 }] when no ADR-999 exists.',
   },
+  'duplicate-decision-id': {
+    what: 'Two decision records claim one number: the index only sees the first, so the second is a record no provenance answer can reach.',
+    why: 'Review 0003 Q55: byId keeps one silently, and a reader of the other gets a decision the tooling cannot resolve. Failing names both files while the collision is still a rename, not a rewrite of history.',
+    fix: 'Renumber the newer record to a free number, then rerun the check.',
+    example: 'ADR-002-first.md and ADR-002-second.md: DUPLICATE-DECISION-ID names both.',
+  },
   'lock-absent': {
     what: 'No lock is recorded: the projection was never locked, so there is nothing `--frozen` can compare against.',
     why: 'ADR-086: the lock is the byte-identical contract across machines, and `--frozen` without one would compare the projection against nothing and call it current. Reported only under --frozen, because a repository that never locked is not drift.',
@@ -243,6 +249,12 @@ export const EXPLAIN_CODES = {
     fix: 'Read the detail (it carries the OS error): fix permissions, remove the broken link, then re-run.',
     example: 'AGENTS.md unreadable (EACCES): UNREADABLE with the errno, not ABSENT.',
   },
+  unresolvable: {
+    what: 'The checked-in gate workflow cannot resolve simt-dev by any path its locator tries: no pinned devDependency, no release binary, no simt on PATH.',
+    why: 'Review 0003 Q31: a green tick from a check that never ran is the one outcome worse than a red one. The workflow installs whatever the repo pins, so a repo that pins nothing gates nothing — reported here instead of failing open in CI.',
+    fix: 'Run the install the finding names (the repo manager\u2019s add-dev command) so CI restores the pinned dependency.',
+    example: 'A pnpm repo whose workflow says npm ci with no simt-dev dependency: UNRESOLVABLE names pnpm add -D.',
+  },
   unrunnable: {
     what: 'A declared gate cannot run here: the command it needs is not on PATH, or its runner is missing.',
     why: 'ADR-017: a gate that cannot run fails closed on every commit once hooks are installed — after the reader committed, which is the wrong order. check reports it before anyone installs anything, with the probe result that proved it.',