simt-dev 0.2.0 → 0.2.1

package/src/commands/sync.mjs

@@ -16,16 +16,17 @@
 //     three `.mdc` rules would let a reader believe a repo is fully current when
 //     only the file they happened to open is.
 
-import { mkdir, symlink, unlink, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { mkdir, readFile, symlink, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { plan, checkTargets, checkTarget, provenanceDigest, loadRules, select, pointerTargets, pointerState } from '../projection/project.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { manifestDrift, readManifest, unrunnableGates } from '../projection/manifest.mjs';
+import { manifestDrift, readManifest, unrunnableGates, buildManifest, writeManifest, withGenerated, manifestText } from '../projection/manifest.mjs';
 import { readCapability } from '../hooks/capability.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
 import { CLI } from '../name.mjs';
-import { MANIFEST_FILE } from '../name.mjs';
+import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { assertVersionPin, packageVersion } from '../package-version.mjs';
 
 /** Findings `sync` reports and does not fail on.
  *
@@ -76,6 +77,28 @@ export async function syncCommand(positional, flags) {
 
   const result = await plan(root, flags);
 
+  // Before the rule branch, and named for what it is. An unknown surface id is a
+  // misspelling in the manifest's `surfaces` list; reporting it as an unprojectable
+  // `.mdc` rule sent the reader to a `simt-substitutions` block that has nothing to do
+  // with the thing they typed. `check` reported the same problem correctly the whole
+  // time, so this was a writer disagreeing with the gate about the same manifest.
+  if (result.surfaceProblems.length > 0) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: false,
+        command: 'sync',
+        root,
+        error: result.surfaceProblems[0],
+        problems: result.surfaceProblems,
+      });
+    }
+    for (const p of result.surfaceProblems) note(`PROBLEM ${p}`);
+    return fail(
+      `${result.surfaceProblems.length} surface(s) cannot be resolved (${result.surfaceProblems[0]})`,
+      EXIT.FAIL,
+      `fix the surface ids in the "surfaces" list of ${MANIFEST_FILE}, or remove the unknown one`,
+    );
+  }
 
   // A `.mdc` rule that cannot render is a defect in this build, not in the repo,
   // and projecting the rest would leave a family half-retired.
@@ -162,6 +185,40 @@ export async function syncCommand(positional, flags) {
   const changed = result.targets.filter((t) => t.action !== 'unchanged');
   const pointersAdded = pointerPlan.map((p) => p.path);
 
+  // The manifest is the second file this tool writes into a repository it does not own,
+  // and for two releases it was the only generated file with no path back to correct:
+  // `check` refused on a stale generated field and named `init --yes`, while `sync` -
+  // the command whose whole job is regenerating what this tool owns - reported
+  // "already current; nothing written". Both statements were true of the same
+  // repository, and all fourteen adopted repositories were in that state at once.
+  //
+  // One reason and one place, so `check`'s remedy and this plan cannot drift: the
+  // field set is `GENERATED_KEYS`, and the values come from the same `buildManifest`
+  // call `manifestDrift` compares against. A repair built from a second copy of
+  // either would pass its own test and leave the gate still red.
+  //
+  // `reformatted` is repaired too, and only when the repository has said the file is
+  // not prose: `simt.json` listed in `.prettierignore` is the repo stating that no
+  // formatter will take these bytes back.
+  //
+  // Without that condition there are two wrong answers. Repairing unconditionally
+  // means every `format` run rewrites a file the commit just wrote - a permanently
+  // dirty working tree. Never repairing means `init --yes` is the only way to put the
+  // bytes back, and `init` re-runs adoption: it tags, it switches branch, it asks every
+  // question again, to fix one file's formatting (ADR-050). The first repo routed in
+  // the estate roll-out hit this on its first commit, so both answers were live.
+  const manifestPlan = await planManifestRepair(root, result.stack, result.targets[0].sha);
+  if (manifestPlan) {
+    targets.push({
+      file: manifestPlan.file,
+      surface: 'manifest',
+      action: 'updated',
+      bytes: Buffer.byteLength(manifestPlan.text),
+      previousBytes: manifestPlan.previousBytes,
+    });
+  }
+  const manifestChanged = manifestPlan !== null;
+
   // Writes happen BEFORE output in every mode. An earlier build emitted `--json`
   // first and returned, so `upgrade --yes --json` reported a plan and changed
   // nothing — the exact combination automation reaches for.
@@ -178,6 +235,13 @@ export async function syncCommand(positional, flags) {
   // A comment that enumerates which commands follow a rule is a claim about code
   // this file does not own, and it was one commit out of date before anyone ran it.
   if (mode.apply) {
+    // The manifest first, with the rest: a gate that refuses on a stale stamp should
+    // not be able to read a half-finished write, and the manifest is the file every
+    // other write in this run is described by.
+    if (manifestPlan) {
+      await writeManifest(root, manifestPlan.manifest);
+      note(`wrote    ${manifestPlan.file} (generated field(s) ${manifestPlan.stale.join(', ')})`);
+    }
     for (const t of changed) {
       // Three of the four rule surfaces live in directories that do not exist yet in a
       // repository that has only ever been written to by hand. `init` grew its own
@@ -210,7 +274,7 @@ export async function syncCommand(positional, flags) {
         // `ok` follows the exit code, which now reports drift for a previewing run
         // too. Leaving it `true` here would break the invariant ADR-035 sets for
         // every command, and the contract table asserts it for this one.
-        ok: changed.length === 0 && pointersAdded.length === 0 ? true : mode.apply,
+        ok: changed.length === 0 && pointersAdded.length === 0 && !manifestChanged ? true : mode.apply,
         command: checkOnly ? 'sync --check' : 'sync',
         root,
         stack: result.stack,
@@ -220,7 +284,7 @@ export async function syncCommand(positional, flags) {
         sha: result.targets[0].sha,
         targets,
         pointers: pointersAdded,
-        written: mode.apply ? changed.length + pointersAdded.length : 0,
+        written: mode.apply ? changed.length + pointersAdded.length + (manifestChanged ? 1 : 0) : 0,
         dryRun: !mode.apply,
       },
       {},
@@ -233,12 +297,15 @@ export async function syncCommand(positional, flags) {
       surfacesLine({ ids: result.surfaces, source: result.surfaceSource }, 10),
       `sha       ${result.targets[0].sha}`,
       '',
-      ...result.targets.map(
+      // `targets`, not `result.targets`: the plan is the thing being reported, and a
+      // line the JSON payload carries but the text one drops is the reader of the
+      // terminal output finding out from the exit code what they were already told.
+      ...targets.map(
         (t) => `${t.file}  ${t.action}  ${t.previousBytes} -> ${t.bytes} bytes`,
       ),
       ...pointerPlan.map((p) => `${p.file}  added  pointer -> ${p.to}`),
     ];
-    if (changed.length === 0 && pointerPlan.length === 0) lines.push('already current; nothing written');
+    if (changed.length === 0 && pointerPlan.length === 0 && !manifestChanged) lines.push('already current; nothing written');
     else if (checkOnly) lines.push('would write; rerun without --check');
     else if (!mode.apply) {
       // The preview names the command that writes it. A preview that reports what
@@ -247,24 +314,91 @@ export async function syncCommand(positional, flags) {
       lines.push(
         flags.dryRun === true
           ? 'dry-run; nothing written'
-          : `would write ${changed.length + pointersAdded.length} file(s); apply with: ${CLI} sync --yes`,
+          : `would write ${changed.length + pointersAdded.length + (manifestChanged ? 1 : 0)} file(s); apply with: ${CLI} sync --yes`,
       );
     }
     emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
   }
 
-  if (checkOnly) return changed.length === 0 && pointerPlan.length === 0 ? EXIT.OK : EXIT.FAIL;
+  const idle = changed.length === 0 && pointerPlan.length === 0 && !manifestChanged;
+  if (checkOnly) return idle ? EXIT.OK : EXIT.FAIL;
   // A preview that found work is not a success: `simt-dev sync --yes` with no flags is a
   // check that also prints the plan, and a check that exits 0 while reporting drift
   // is the one-question-two-answers shape ADR-035 rules out. This is what lets a
   // caller run `sync` in place of `sync --check` and get the same verdict.
   if (!mode.apply) {
     if (flags.dryRun === true) note('dry-run  no files written');
-    return changed.length === 0 && pointerPlan.length === 0 ? EXIT.OK : EXIT.FAIL;
+    return idle ? EXIT.OK : EXIT.FAIL;
   }
   return EXIT.OK;
 }
 
+/**
+ * The manifest repair `sync` would make, or null when there is nothing to repair.
+ *
+ * Returns the parsed manifest to hand to `writeManifest` as well as the bytes, so the
+ * writer keeps owning the legacy-name move and the preview keeps showing the real
+ * count. `sha` is the same digest the regions were rendered from: the stamp and the
+ * text it describes have to agree, or the next `check` finds a region carrying a pin
+ * the manifest does not claim.
+ *
+ * @returns {Promise<{file: string, manifest: object, text: string,
+ *                    stale: string[], previousBytes: number}|null>}
+ */
+async function planManifestRepair(root, stack, sha) {
+  const drift = await manifestDrift(root, stack, sha);
+  if (drift === null) return null;
+  // A `reformatted` manifest is repaired only once the repository has declared that no
+  // formatter will take these bytes back. The declaration is read rather than assumed
+  // because a repo that runs no formatter should not need a `.prettierignore` to repair
+  // a manifest some other tool rewrote, and one that does must be believed only when it
+  // has said so.
+  if (drift.status === 'reformatted' && !(await formatterIgnoresManifest(root))) return null;
+
+  const { manifest } = await readManifest(root);
+  if (manifest === null) return null;
+  const expected = buildManifest({ root, stack, sha, version: packageVersion(), existing: manifest });
+  const patched = withGenerated(manifest, expected);
+  const stale = Object.keys(expected).filter(
+    (key) => JSON.stringify(manifest[key]) !== JSON.stringify(patched[key]),
+  );
+  return {
+    file: MANIFEST_FILE,
+    manifest: patched,
+    text: manifestText(patched),
+    stale,
+    previousBytes: Buffer.byteLength(manifestText(manifest)),
+  };
+}
+
+/**
+ * Whether this repository's `.prettierignore` excludes the manifest.
+ *
+ * Lines, `#` comments and blanks only. A glob is not evaluated: the question this
+ * answers is "did somebody deliberately write this file's name down", and an exact
+ * match is the only reading of that which cannot be wrong. A repository that ignores
+ * `*.json` has said something broader, and the honest answer there is that this tool
+ * cannot tell - so it declines to repair, which is the state that was already correct.
+ */
+async function formatterIgnoresManifest(root) {
+  // ENOENT only. A catch that answers "no" to every error is a catch that turns a
+  // typo in this function into a repository silently keeping its pre-commit gate's
+  // formatting — which is how the first version of it failed: `join` was not imported,
+  // the ReferenceError was swallowed, and every repository read as having declared
+  // nothing. Absence is absence; anything else is a fault worth seeing.
+  let text;
+  try {
+    text = await readFile(join(root, '.prettierignore'), 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return false;
+  }
+  return text
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line !== '' && !line.startsWith('#') && (line === MANIFEST_FILE || line === MANIFEST_LEGACY));
+}
+
 export async function checkCommand(positional, flags) {
   const root = flags.root ?? positional[0] ?? process.cwd();
   const findings = await checkTargets(root, flags);
@@ -288,6 +422,14 @@ export async function checkCommand(positional, flags) {
   // before anyone installs anything rather than after.
   const { manifest } = await readManifest(root);
   if (manifest) {
+    // The gate runs from whatever binary resolved it. For a repository without npm that
+    // is a global install, and the only thing that knows which version it should be is
+    // the pin the repo recorded at adoption. A stale binary would run a different gate
+    // than CI does, so the mismatch fails the gate rather than warning.
+    const mismatch = assertVersionPin(manifest);
+    if (mismatch) {
+      findings.push({ file: MANIFEST_FILE, status: 'version-mismatch', detail: mismatch, remedy: `run: ${CLI} upgrade --yes` });
+    }
     findings.push(...unrunnableGates(manifest, await readCapability(root)));
     // A manifest a formatter has rewritten is not wrong, and not editable-away by
     // hand either: the next `init` puts simt-dev's own bytes back and the formatter

package/src/compare/hooksstate.mjs

@@ -11,8 +11,9 @@ import { readFile, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { promisify } from 'node:util';
 
-import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, fileFor, renderShim } from '../hooks/shim.mjs';
+import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderShim } from '../hooks/shim.mjs';
 import { foreignHooks, resolveHooksDir } from '../hooks/where.mjs';
+import { packageVersion, hasNpm } from '../package-version.mjs';
 
 const exec = promisify(execFile);
 
@@ -30,7 +31,7 @@ const exec = promisify(execFile);
  * @param {string} path
  * @returns {Promise<{event:string, target:string}|null>}
  */
-export async function readChainedShim(path) {
+async function readChainedShim(path) {
   let content;
   try {
     content = await readFile(path, 'utf8');
@@ -49,6 +50,54 @@ async function isChainedShim(path) {
   return (await readChainedShim(path)) !== null;
 }
 
+/**
+ * Whether this file is a dispatcher shim this tool wrote, whatever version wrote it.
+ *
+ * Content, on the same argument as {@link readChainedShim}: the name is what git calls
+ * it and the path is where this tool happens to put its own, and neither of those is a
+ * statement about authorship. The banner is.
+ */
+async function isOurShim(path) {
+  try {
+    return (await readFile(path, 'utf8')).includes(SHIM_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/** Git event -> manifest gate list. Exported because the report prints from it too. */
+export const GATE_KEY = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
+
+/** Gates this manifest declares for an event. */
+export function gateCount(manifest, event) {
+  return (manifest?.gates?.[GATE_KEY[event]] ?? []).length;
+}
+
+/**
+ * Whether a missing shim for this event is a defect.
+ *
+ * A repo that declares no gate for an event has no reason to want a shim for it, so
+ * its absence is the correct end state. A repo with NO manifest is different: we do
+ * not know what it wants, so we cannot rule the shim out - absence of knowledge is
+ * not a decision.
+ *
+ * It lives here, not in the command that first needed it, because there are two
+ * callers and they were answering differently. `hooks install` asked this question;
+ * `compare` did not ask it at all and defaulted to "yes, a shim is wanted for every
+ * event", so a repository declaring only `prePush` gates was reported as
+ * `hooksComplete: false` for the pre-commit shim it correctly has no reason to write.
+ * Four estate repositories were in that state and no amount of running `hooks install`
+ * could clear it.
+ *
+ * @param {object|null} manifest the repository's manifest
+ * @param {boolean} exists whether a manifest was found at all
+ * @param {string} event
+ */
+export function wantsShim(manifest, exists, event) {
+  if (!exists) return true;
+  return gateCount(manifest, event) > 0;
+}
+
 /** `core.hooksPath`, or null when unset or the repo is not a git repo. */
 export async function readHooksPath(root) {
   try {
@@ -64,27 +113,40 @@ export async function readHooksPath(root) {
  * One shim's state. A shim that differs from what this simt-dev generates is
  * `stale`: the gates it enforces are from another version, so it cannot be
  * assumed to know about a gate added since.
+ *
+ * `ours` is reported rather than inferred from `stale`, because the two answer different
+ * questions and only one is the one `hooks install` has to ask. A shim this tool wrote can be
+ * current (identical bytes), or from an earlier release (stale), or a shell it left behind for
+ * an event with no gates - also stale, and the one thing here that is obsolete rather than out
+ * of date. A file a person wrote by hand is stale too, and it is the one thing install must
+ * never delete. Authorship is only on the file, which is the same argument {@link isOurShim}
+ * already records for the same reason.
+ *
+ * `root` is the repository the shim belongs to: the remedy a shim prints depends on
+ * the repo's kind (a devDependency where package.json exists, a pinned global install
+ * where there is none), so the comparison must render the shim the way THIS repo got it,
+ * or a non-npm repository would read as stale the moment this tool ships.
  */
-export async function describeShim(path) {
+async function describeShim(path, root) {
   let content;
   try {
     content = await readFile(path, 'utf8');
   } catch {
-    return { present: false, executable: false, stale: false };
+    return { present: false, executable: false, stale: false, ours: false };
   }
   let info;
   try {
     info = await stat(path);
   } catch {
-    return { present: false, executable: false, stale: false };
+    return { present: false, executable: false, stale: false, ours: false };
   }
   let stale = true;
   try {
-    stale = content !== renderShim(basename(path));
+    stale = content !== renderShim(basename(path), { npm: await hasNpm(root), version: packageVersion() });
   } catch {
     stale = true;
   }
-  return { present: true, executable: (info.mode & 0o111) !== 0, stale };
+  return { present: true, executable: (info.mode & 0o111) !== 0, stale, ours: content.includes(SHIM_MARKER) };
 }
 
 /**
@@ -100,7 +162,7 @@ export async function readHooksState(root, options = {}) {
   const current = await readHooksPath(root);
   const installed = [];
   for (const event of EVENTS) {
-    installed.push({ event, ...(await describeShim(join(root, fileFor(event)))) });
+    installed.push({ event, ...(await describeShim(join(root, fileFor(event)), root)) });
   }
 
   // What git runs right now, which is not the same question as "is a simt-dev
@@ -112,8 +174,10 @@ export async function readHooksState(root, options = {}) {
   // hand-written one. Only the bytes can.
   const foreign = [];
   const chained = [];
+  const staleOurs = [];
   for (const hook of live) {
-    if (EVENTS.includes(hook.event) && !(await describeShim(hook.path)).stale) continue;
+    const shim = EVENTS.includes(hook.event) ? await describeShim(hook.path, root) : { stale: true };
+    if (!shim.stale) continue;
     // A chained shim is ours too, and its name says nothing: `post-commit` is what the
     // repository called its own hook, and the shim exists under that name precisely so
     // git finds it. Reading it as foreign would make every re-install refuse with "this
@@ -124,6 +188,25 @@ export async function readHooksState(root, options = {}) {
       chained.push({ ...chain, path: hook.path });
       continue;
     }
+    // And so is a dispatcher shim from an EARLIER version of this tool, which is the
+    // ordinary state of every repository adopted before the last release.
+    //
+    // Reading it as foreign was wrong twice over. `compare` reported "not a simt-dev
+    // shim" about a file simt-dev wrote, and `hooks install --yes` then printed "stopped
+    // running <event> ... declare it in simt.json gates.commands to have the dispatcher
+    // run it" — advice that, followed, makes the dispatcher run the dispatcher. The file
+    // was also described as "still on disk, untouched" in the same breath as the install
+    // overwrote it. Both statements were false and both pointed a reader at a worse
+    // configuration; nine estate repositories were in exactly this state.
+    //
+    // What it actually needs is refreshing, which `installed` already reports as `stale`
+    // and `compare` already reports as "differs from this simt-dev; reinstall". Keeping
+    // it out of `foreign` also stops the takeover guard asking for consent the
+    // repository has already given: it routed through this tool once.
+    if (await isOurShim(hook.path)) {
+      staleOurs.push(hook);
+      continue;
+    }
     foreign.push(hook);
   }
 
@@ -146,6 +229,10 @@ export async function readHooksState(root, options = {}) {
     complete: current === HOOKS_DIR && problems.length === 0,
     installed,
     foreign,
+    // Dispatcher shims this tool wrote in an earlier version. Reported so a reader can
+    // tell an out-of-date shim - which `hooks install` refreshes - from one this tool
+    // has never heard of, which only a human may decide to replace.
+    staleOurs,
     // The chained shims this repo is already running, read back off disk. `install`
     // re-renders them from here so a second run keeps maintaining them rather than
     // quietly forgetting them; without this field the set of things install maintains

package/src/compare/row.mjs

@@ -17,11 +17,11 @@
 // reordered its columns would make every comparison between two runs unreadable.
 
 import { checkTargets, PRIMARY_TARGET } from '../projection/project.mjs';
-import { readManifest } from '../projection/manifest.mjs';
+import { manifestDrift, readManifest } from '../projection/manifest.mjs';
 import { loadRules, select } from '../projection/rules.mjs';
 import { knownGates } from '../hooks/resolve.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { readHooksState } from './hooksstate.mjs';
+import { readHooksState, wantsShim } from './hooksstate.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 
@@ -60,10 +60,21 @@ export async function buildRow(path, context) {
   const problems = [];
   const notes = [];
 
-  const [manifest, fp, hooks, findings] = await Promise.all([
-    readManifest(path),
+  // The manifest first, and on its own. The predicate below reads it, and a
+  // destructured binding in the same `Promise.all` array is still in its temporal dead
+  // zone when the array is evaluated - so this is the same defect ADR-045 records in
+  // this file one level up: a gate reading a field the line above has not set yet.
+  const manifest = await readManifest(path);
+
+  const [fp, hooks, findings] = await Promise.all([
     fingerprint(path),
-    readHooksState(path),
+    // The same predicate `hooks install` writes by. Without it this row defaulted to
+    // "a shim is wanted for every event", so a repository declaring only `prePush`
+    // gates was reported `hooksComplete: false` for the pre-commit shim it has no
+    // reason to write - and no number of runs of `hooks install` could clear it,
+    // because the command and the dashboard were answering different questions.
+    // Four estate repositories were in that state.
+    readHooksState(path, { declaresGate: (e) => wantsShim(manifest.manifest, manifest.exists, e) }),
     checkTargets(path),
   ]);
 
@@ -152,6 +163,24 @@ export async function buildRow(path, context) {
     problems.push(`${MANIFEST_FILE} ${manifest.error}`);
   }
 
+  // A generated field of the manifest is stale, and `check` refuses on it. This row
+  // said the repository was `current` anyway, in all fourteen adopted repositories at
+  // once, so a dashboard that reported `current: 14, problems: 0` was describing a
+  // green estate on which every gate exited 1.
+  //
+  // ADR-045 went the other way: `compare` counted a defect it had been hiding. This is
+  // the same defect from the far side — a refusal the dashboard does not count — and
+  // the acceptance criterion in the review that owns this ("compare reports current:
+  // 14") was satisfiable while `check` exited 1 in every row it covered.
+  //
+  // `drift.remedy` verbatim, for both statuses. The remedy is the repair command, and
+  // two commands answering one question with different instructions is ADR-050's
+  // subject; if `check` changes its mind, this row changes with it for free.
+  if (adoption === 'adopted') {
+    const drift = await manifestDrift(path, row.stack, context.expectedSha);
+    if (drift) problems.push(`${drift.file}: ${drift.detail}; ${drift.remedy}`);
+  }
+
   // --- region --------------------------------------------------------------
   // Only meaningful for an adopted repo. An unmanaged repo has no manifest, so
   // its `absent` region is a consequence of not having adopted, not a second

package/src/decisions/index.mjs

@@ -180,7 +180,7 @@ export function citations(text) {
  *
  * @returns {Promise<{ok: boolean, decisions: object[], errors: string[]}>}
  */
-export async function loadDecisions() {
+export async function loadDecisions({ all = false } = {}) {
   let names;
   try {
     names = (await readdir(DECISIONS_DIR)).filter((n) => /^ADR-\d{3}-.*\.md$/.test(n)).sort();
@@ -240,7 +240,7 @@ export async function loadDecisions() {
         (m) => `ADR-${m[1]}`,
       ),
       partial,
-      summary: summarise(text, partial),
+      summary: summarise(text, partial, { all }),
       bytes: Buffer.byteLength(text),
     });
   }
@@ -283,9 +283,12 @@ export function byId(decisions) {
  * @param {{ruling: number|null, kind: string, by: string|null}[]} partial the record's
  *   partial supersessions, so a ruling that is no longer in force can say so where it is
  *   printed rather than only in the status line above it
- * @returns {{ruled: string[], rulingNumbers: (number|null)[], rejected: string[], writtenAgainst: string[]}}
+ * @param {{all?: boolean}} [options] `all` keeps every ruling instead of the first two.
+ *   The cap exists for the common case, where a rule cites one record and two rulings
+ *   answer "why is this here"; the reader who needs the rest asks.
+ * @returns {{ruled: string[], rulingNumbers: (number|null)[], rulingCount: number, rejected: string[], writtenAgainst: string[]}}
  */
-function summarise(text, partial = []) {
+function summarise(text, partial = [], { all = false } = {}) {
   // A section ends at the next `## ` — but not at one inside a fenced code block.
 // ADR-007's entire ruling is a document skeleton in a fence whose headings are `##`,
 // so the old lookahead ended the section at the first line of the ruling itself. It
@@ -418,9 +421,21 @@ const section = (name) => {
   const ruled = units(section('Ruling') || section('Rulings'));
   const withLead = ruled.filter((p, i) => !p.text.endsWith(':') || i === ruled.length - 1);
 
-  const printed = withLead.slice(0, 2);
+  // Two by default, and every one of them on request. Fifty-five of the sixty records
+  // carry more than two rulings, so the default is an excerpt for almost every record —
+  // which is fine as a budget and wrong as a silence, and the count below says so.
+  //
+  // The full set is kept rather than discarded, because the command that names where the
+  // rest of it is has to be able to produce it. A remedy that cannot be followed is the
+  // defect this whole command exists to prevent, and the first version of this fix
+  // printed "the rest: simt rules show ADR-019", which exits 2: `rules show` takes a rule
+  // id. So `--all` is the command the excerpt points at, and this is what it reads.
+  const printed = all ? withLead : withLead.slice(0, 2);
   return {
     ruled: printed.map((p) => mark(sentence(redactCommand(p.text)), p.number)),
+    // How many rulings the record carries. Parallel to `ruled`: "two of eight" and "two"
+    // are different answers to the same question and only one of them is true.
+    rulingCount: withLead.length,
     // The number each printed ruling declares, parallel to `ruled`. It is the join
     // between a supersession and the text it applies to, so it is exported rather than
     // kept inside: a family that stopped numbering its rulings — `**One.**` losing the
@@ -493,7 +508,7 @@ export function redactEstate(text) {
  */
 const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|mcp|rules|skills|graph|--[a-z-]+)';
 
-export function redactCommand(text) {
+function redactCommand(text) {
   return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);
 }