@isonimus/stele 0.2.0 → 0.4.1

package/docs/releasing.md

@@ -0,0 +1,84 @@
+# Releasing
+
+How a version of `@isonimus/stele` reaches npm. A **live doc** (ADR-0010): update it in the
+same change as the procedure it describes.
+
+It exists because the steps below were previously done from memory, in the repo whose thesis
+is that a rule enforced by memory holds until the first busy afternoon (ADR-0003). Two things
+had already gone wrong by the time it was written: three published versions had **no git tags
+at all**, and a build tarball had been sitting in version control since 2026-07-27.
+
+## The order, and why it is this order
+
+```
+1.  npm run lint && npm test          the corpus is green and the suite passes
+2.  npm run index                     regenerate adr/INDEX.md; commit if it moved
+3.  edit package.json                 bump the version
+4.  commit                            the last commit before the tag
+5.  git tag -a vX.Y.Z -m "…"          on the commit being published (ADR-0026)
+6.  npm run changelog                 regenerate CHANGELOG.md from the new tag
+7.  commit                            "chore: changelog for vX.Y.Z"
+8.  git push && git push --tags       tag and history reach the remote together
+9.  npm publish                       irreversible: a version number is never reusable
+10. /init-method --update             in every installed repo, so the fix actually lands
+```
+
+**Why the tag comes before the changelog.** `scripts/build-changelog.mjs` reads tags and
+nothing else, so a tag that does not exist yet produces a changelog missing its own release.
+Tagging first is not a preference; it is the data dependency.
+
+**Why the changelog is a second commit, and why publish is one commit past the tag.** The
+changelog describes commits up to and including the tagged one, so it cannot live inside the
+object it is naming. `npm publish` therefore packs a tree one commit ahead of `vX.Y.Z` —
+identical to it but for `CHANGELOG.md`, which is the file that could not have been there. That
+skew is deliberate and bounded; anything else in the diff at step 9 means the release is not
+what the tag says it is.
+
+**Step 3 bumps the version, but step 5 tags the commit you are about to publish** — and on
+0.4.0 those were three commits apart, because work continued after the bump. `npm publish`
+packs the working tree, not the version-bump commit, so a tag left behind on the bump would
+name bytes nobody received. Bump last where you can; tag what ships where you cannot.
+
+**Why publish is last and by hand.** `npm publish` cannot be undone: a version number is burned
+even if the release is unpublished within the 72-hour window. Everything reversible happens
+first, so the irreversible step runs against a state already checked.
+
+**Why step 10 is part of the release.** The linter, the hook and the commands are *vendored*
+per repo (ADR-0006, ADR-0023). Publishing changes nothing in boxel or gamatar until
+`/init-method --update` runs there, so a release that stops at step 9 has shipped to the
+registry and to nobody.
+
+## Version numbers
+
+Pre-1.0, so the minor slot carries breaking changes:
+
+- **patch** — a fix that changes no vendored file's behaviour.
+- **minor** — a new linter rule, a change to a vendored command or to `docs/quality-bar.md`,
+  or any change to the installer's behaviour. A new rule makes commits fail that were green in
+  the previous version, which is breaking however small the diff.
+- **major** — reserved for 1.0.
+
+## What the changelog does and does not say
+
+It is generated from commit subjects between tags (ADR-0026). It therefore inherits exactly
+the quality of the commit messages, which is the argument for writing them properly rather
+than an argument for editing the changelog afterwards — **never hand-edit it**; the CI check
+will fail and the edit is lost at the next regeneration.
+
+It cannot say "you must run `--update` for this one". If a release needs that, say so in the
+release commit's subject, where the changelog will pick it up verbatim.
+
+## If something goes wrong
+
+- **Anything changed after tagging, including docs:** do not move the tag. Bump a patch
+  version, tag that, and publish it instead — the working tree is what `npm publish` packs, so
+  a tree that has moved past the tag is no longer the release the tag names. This happened on
+  the first run of this procedure: `v0.4.0` was tagged, a README update followed, and `0.4.1`
+  was published in its place. `v0.4.0` stays in the history as a tagged release that was never
+  published, which the changelog shows and which is the honest record (`0.2.1` is the same).
+- **Tagged the wrong commit, not yet pushed:** `git tag -d vX.Y.Z`, retag, regenerate.
+- **Tagged and pushed the wrong commit:** do not move the tag. Tag the correction as the next
+  patch version — a moved tag means two clones disagree about what a release was.
+- **Published a broken version:** publish the fix as a new version. Unpublishing is available
+  for 72 hours and is worse than a superseding release: it breaks every lockfile that already
+  pinned it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isonimus/stele",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "A linted, installable ADR workflow for git projects using Claude as an assistant",
   "keywords": [
@@ -29,9 +29,11 @@
   "files": [
     "scripts/",
     "templates/",
+    "docs/",
     ".claude/commands/",
     ".claude/hooks/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -41,7 +43,9 @@
     "test": "node --test test/*.test.mjs",
     "lint": "node scripts/lint-docs.mjs .",
     "index": "node scripts/build-index.mjs .",
+    "changelog": "node scripts/build-changelog.mjs .",
     "immutable": "node scripts/check-immutable.mjs",
+    "mutants": "node scripts/check-mutants.mjs",
     "scan": "node scripts/scan-legacy.mjs",
     "migrate": "node scripts/migrate-adrs.mjs",
     "init": "node scripts/init-method.mjs"

package/scripts/build-changelog.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// Builds CHANGELOG.md from annotated git tags (ADR-0026). Generated, never hand-edited.
+//
+//   node scripts/build-changelog.mjs [repo-root]           write CHANGELOG.md
+//   node scripts/build-changelog.mjs --check [repo-root]   fail if it is stale
+//
+// Tags are the only input, so the file changes when a release is tagged and at no other
+// time — which is what makes --check affordable in CI. Commits made after the newest tag
+// are deliberately absent until the next tag exists (ADR-0026).
+//
+// --check runs in CI only, and cannot move into the pre-commit hook: the hook checks the
+// commit by extracting a `git archive` of the staged tree into a temp directory (ADR-0018),
+// which has no `.git` and therefore no tags. Reading tags from the real repo instead would
+// check the working tree while claiming to check the commit, which is the exact confusion
+// ADR-0018 exists to prevent.
+
+import { writeFileSync, readFileSync, existsSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CHANGELOG = 'CHANGELOG.md';
+
+/** Conventional-commit types, in the order a reader cares about them. Anything else sorts
+ *  last under its own literal prefix rather than being dropped: a commit that escaped the
+ *  convention is still a change that shipped, and hiding it would make the file a claim
+ *  about the corpus instead of a rendering of it. */
+const TYPE_ORDER = ['feat', 'fix', 'perf', 'refactor', 'test', 'docs', 'chore'];
+
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+
+/** The type prefix of a conventional subject (`feat(x): …` → `feat`), or null. */
+export function commitType(subject) {
+  const match = /^([a-z]+)(\([^)]*\))?!?:/.exec(subject);
+  return match ? match[1] : null;
+}
+
+const typeRank = (subject) => {
+  const index = TYPE_ORDER.indexOf(commitType(subject));
+  return index === -1 ? TYPE_ORDER.length : index;
+};
+
+/**
+ * The tags, split into releases and everything this tool refuses to call one.
+ *
+ * A release is an **annotated** tag that dereferences to a **commit**, and both halves of
+ * that are load-bearing (ADR-0026, found by the ADR-0017 pass on this file):
+ *
+ * - `refs/tags` holds lightweight tags too — local bookmarks, bisect markers, CI leftovers —
+ *   and counting one as a release publishes a section for something nobody released.
+ * - An annotated tag may point at a blob or a tree. `git rev-list -n 1` then yields the empty
+ *   string, and the next git call inherits it as a ref and dies with a raw `fatal: ambiguous
+ *   argument ''` plus a stack trace.
+ *
+ * Both are read straight off `for-each-ref` rather than probed afterwards: `%(*objecttype)`
+ * and `%(*objectname)` are the peeled object, so one call answers both questions and there is
+ * no window where a tag is assumed to be something it is not.
+ *
+ * Releases come back oldest first, ordered by the tagged **commit's** date rather than the
+ * tag's own — this repo's first three tags were written retroactively in one sitting, so
+ * creation order carries no release information whatever.
+ */
+export function readTags(cwd) {
+  const lines = git(cwd, [
+    'for-each-ref',
+    '--format=%(refname:short)\t%(objecttype)\t%(*objecttype)\t%(*objectname)',
+    'refs/tags',
+  ]);
+  if (lines === '') return { releases: [], skipped: [] };
+
+  const releases = [];
+  const skipped = [];
+
+  for (const line of lines.split('\n')) {
+    const [name, objectType, peeledType, peeledCommit] = line.split('\t');
+    if (objectType !== 'tag') {
+      skipped.push({ name, why: 'lightweight — a release tag is annotated (git tag -a)' });
+      continue;
+    }
+    if (peeledType !== 'commit') {
+      skipped.push({ name, why: `annotated but points at a ${peeledType || 'non-commit object'}` });
+      continue;
+    }
+    // Full timestamp for ordering, short date for display: two releases on one day are
+    // ordinary, and a date-only sort would fall back to alphabetical refname order, which
+    // puts v0.10.0 before v0.9.0.
+    const [orderedBy, date] = git(cwd, ['log', '-1', '--format=%aI\t%ad', '--date=short', peeledCommit]).split('\t');
+    releases.push({ name, commit: peeledCommit, orderedBy, date });
+  }
+
+  releases.sort((a, b) => (a.orderedBy < b.orderedBy ? -1 : a.orderedBy > b.orderedBy ? 1 : 0));
+  return { releases, skipped };
+}
+
+/**
+ * Subject and short SHA of every commit reachable from `to` and from none of `alreadyShipped`,
+ * newest first.
+ *
+ * Excluding *every* earlier release rather than only the previous one is what keeps a commit
+ * in one section. A tagged branch that merges in later is reachable from both its own tag and
+ * the merge's tag, so a plain `previous..this` range reports it twice — once under the release
+ * that shipped it and again under the release that merged it (ADR-0017 pass on this file).
+ *
+ * Merges themselves are excluded: a merge commit's subject records an integration, not a
+ * change, and the commits it brings in are listed individually.
+ */
+export function commitsSince(cwd, alreadyShipped, to) {
+  const lines = git(cwd, ['log', '--no-merges', '--format=%h\t%s', to, '--not', ...alreadyShipped]);
+  if (lines === '') return [];
+
+  return lines.split('\n').map((line) => {
+    const separator = line.indexOf('\t');
+    return { sha: line.slice(0, separator), subject: line.slice(separator + 1) };
+  });
+}
+
+/** The document. Pure, so the shape is testable without a repo. */
+export function renderChangelog(releases) {
+  const head = `# Changelog
+
+Generated by \`scripts/build-changelog.mjs\` from annotated git tags — never hand-edited
+(ADR-0026). Run \`npm run changelog\` after tagging a release.
+
+Every entry is a commit subject verbatim. Work committed after the newest tag is absent by
+design and appears when the next release is tagged.
+`;
+
+  if (releases.length === 0) {
+    return `${head}\nNo tags yet, so no releases to describe.\n`;
+  }
+
+  const sections = [...releases].reverse().map(({ name, date, commits }) => {
+    const body = commits.length === 0
+      ? '\nNo commits between this tag and the previous one.\n'
+      : `\n${[...commits]
+          .sort((a, b) => typeRank(a.subject) - typeRank(b.subject))
+          .map(({ sha, subject }) => `- ${subject} (\`${sha}\`)`)
+          .join('\n')}\n`;
+    return `## ${name} — ${date}\n${body}`;
+  });
+
+  return `${head}\n${sections.join('\n')}`;
+}
+
+/** The document this repo's tags describe, and the tags that were not treated as releases. */
+export function buildChangelog(cwd) {
+  const { releases, skipped } = readTags(cwd);
+  return {
+    text: renderChangelog(
+      releases.map((release, index) => ({
+        ...release,
+        commits: commitsSince(cwd, releases.slice(0, index).map((earlier) => earlier.commit), release.commit),
+      })),
+    ),
+    skipped,
+  };
+}
+
+function main(argv) {
+  const check = argv.includes('--check');
+  const cwd = argv.find((arg) => !arg.startsWith('--')) ?? process.cwd();
+  const path = join(cwd, CHANGELOG);
+  const { text: wanted, skipped } = buildChangelog(cwd);
+
+  // Named rather than dropped in silence: a release tagged with a bare `git tag` produces a
+  // changelog missing that release, and the only symptom is an absence nobody looks for.
+  for (const { name, why } of skipped) {
+    console.error(`note: tag ${name} is not treated as a release — ${why}`);
+  }
+
+  if (!check) {
+    writeFileSync(path, wanted);
+    console.log(`wrote ${CHANGELOG}`);
+    return 0;
+  }
+
+  if (!existsSync(path)) {
+    console.error(`${CHANGELOG} is missing — run \`npm run changelog\`.`);
+    return 1;
+  }
+  if (readFileSync(path, 'utf8') !== wanted) {
+    console.error(`${CHANGELOG} does not match the tags — a release was tagged without regenerating it. Run \`npm run changelog\`.`);
+    return 1;
+  }
+  console.log(`${CHANGELOG} matches the tags`);
+  return 0;
+}
+
+// Resolved on both sides before comparing: a raw `file://${argv[1]}` check is false whenever
+// the script is reached through a symlink, and main() then silently never runs (ADR-0015
+// amendment, where that cost an install that exited 0 and did nothing).
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}

package/scripts/check-mutants.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// Mutation check over the linter's pure predicates (ADR-0004's probe idea, made standing).
+//
+//   node scripts/check-mutants.mjs [--quiet]
+//
+// Each mutant is a small, deliberate behaviour change. The suite is run against it: a
+// mutant that dies proves a test was watching, one that SURVIVES proves the behaviour is
+// unpinned and a refactor could reverse it in silence. Exit 1 if any non-exempt mutant
+// survives.
+//
+// Scope is deliberately narrow: the total, IO-free predicates in lint-docs.mjs and
+// check-immutable.mjs. Every subtle-logic defect this repo has had lived in that class.
+// init-method.mjs is excluded — its behaviour is pinned by real-filesystem fixtures, where
+// a mutant mostly proves the filesystem still works — and the hook is shell, not JS.
+//
+// What this does NOT buy, stated so a green run is not read as more than it is: none of the
+// three defects this repo has actually suffered would have been caught. Two were missing
+// inputs and one was a wrong specification; mutation testing perturbs code and asks whether
+// tests notice, so it is blind to a case nobody wrote and to a rule that was wrong from the
+// start. It measures regression durability, not correctness (LEDGER).
+
+import { cpSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const LINTER = 'scripts/lint-docs.mjs';
+const IMMUTABLE = 'scripts/check-immutable.mjs';
+
+/** ADR-0022 excluded init-method.mjs wholesale, reasoning that a mutant there mostly proves
+ *  the filesystem still works. `classifyVendored` (ADR-0023) is the first total, IO-free
+ *  predicate in that file, so it falls inside the scope ADR-0022 actually described rather
+ *  than the file it named. Recorded as a refinement, never a silent exception. */
+const INIT = 'scripts/init-method.mjs';
+
+/** The changelog's type classifier and its ordering are total and IO-free, so they fall in
+ *  the same scope as the linter's predicates — the git-reading half does not (ADR-0026). */
+const CHANGELOG = 'scripts/build-changelog.mjs';
+
+/**
+ * The curated mutant list. Each entry names one behaviour and the smallest edit that
+ * reverses it.
+ *
+ * Hand-picked rather than generated: a generator emits hundreds of mutants over these files
+ * and most are equivalent or trivial, so the triage cost — not the runtime — is what makes
+ * a framework a bad trade here. Curating is the work; the runner is twenty lines.
+ *
+ * `equivalent` marks a mutant that cannot be killed because the mutated code means the same
+ * thing. It is kept rather than deleted, so nobody re-adds it as a "gap", and it must carry
+ * the reason it is exempt.
+ */
+export const MUTANTS = [
+  {
+    label: 'normId: pad ids to 3 digits instead of 4',
+    file: LINTER,
+    find: "String(v).trim().padStart(4, '0')",
+    replace: "String(v).trim().padStart(3, '0')",
+  },
+  {
+    label: 'isCalendarDate: drop the round-trip check',
+    file: LINTER,
+    find: 'return parsed.toISOString().startsWith(text);',
+    replace: 'return true;',
+  },
+  {
+    label: 'citableText: stop stripping URLs before matching citations',
+    file: LINTER,
+    find: "text.replace(/\\]\\([^)]*\\)/g, ']()').replace(/\\S*:\\/\\/\\S*/g, '')",
+    replace: "text.replace(/\\]\\([^)]*\\)/g, ']()')",
+  },
+  {
+    label: 'inReadScope: drop the exact-match branch, keeping only the prefix',
+    file: LINTER,
+    find: 'rootRelative === entry || rootRelative.startsWith(`${entry}/`)',
+    replace: 'rootRelative.startsWith(`${entry}/`)',
+  },
+  {
+    label: 'withoutFences: stop blanking lines inside a code fence',
+    file: LINTER,
+    find: "return open === null ? line : '';",
+    replace: 'return line;',
+  },
+  {
+    label: 'sectionText: read to end of body instead of stopping at the next heading',
+    file: LINTER,
+    find: "(end === -1 ? rest : rest.slice(0, end)).join('\\n')",
+    replace: "rest.join('\\n')",
+  },
+  {
+    label: 'hasGherkinTriad: require any step kind rather than all three',
+    file: LINTER,
+    find: "steps.has('given') && steps.has('when') && steps.has('then')",
+    replace: "steps.has('given') || steps.has('when') || steps.has('then')",
+  },
+  {
+    label: 'R6: ignore a superseded_by list of exactly one target',
+    file: LINTER,
+    find: 'if (!isSuperseded && supersededBy.length > 0) {',
+    replace: 'if (!isSuperseded && supersededBy.length > 1) {',
+  },
+  {
+    label: 'classifyVendored: treat an unrecorded command as stale rather than unknown',
+    file: INIT,
+    find: "if (recordedDigest === undefined) return 'unknown';",
+    replace: "if (recordedDigest === undefined) return 'stale';",
+  },
+  {
+    label: 'classifyVendored: swap the stale/adapted verdict',
+    file: INIT,
+    find: "return digest(targetText) === recordedDigest ? 'stale' : 'adapted';",
+    replace: "return digest(targetText) === recordedDigest ? 'adapted' : 'stale';",
+  },
+  {
+    label: 'firstLostLine: weaken the exhausted-scan guard',
+    file: IMMUTABLE,
+    find: 'if (cursor === now.length) return i;',
+    replace: 'if (cursor > now.length) return i;',
+  },
+  {
+    label: 'commitType: accept a subject with no colon as conventional',
+    file: CHANGELOG,
+    find: "/^([a-z]+)(\\([^)]*\\))?!?:/",
+    replace: "/^([a-z]+)(\\([^)]*\\))?!?:?/",
+  },
+  {
+    label: 'typeRank: sort an unrecognised type first rather than last',
+    file: CHANGELOG,
+    find: 'return index === -1 ? TYPE_ORDER.length : index;',
+    replace: 'return index === -1 ? 0 : index;',
+  },
+  {
+    label: 'firstLostLine: compare body lines loosely',
+    file: IMMUTABLE,
+    find: 'while (cursor < now.length && now[cursor] !== was[i]) cursor++;',
+    replace: 'while (cursor < now.length && now[cursor] != was[i]) cursor++;',
+    equivalent: 'both operands are strings, so != and !== are the same comparison',
+  },
+];
+
+/**
+ * A disposable copy of the working tree. The check never edits the operator's files: a run
+ * interrupted midway would otherwise leave mutated source behind, and "my linter is subtly
+ * wrong and I do not know why" is an expensive afternoon.
+ *
+ * `.git` is copied with everything else, because the copy has to behave identically or the
+ * baseline below fails for reasons that have nothing to do with any mutant. `migrate-adrs`
+ * reads commit dates and falls back silently when git cannot answer, so a hollow `.git`
+ * changed its plan and failed five tests. At 3.2MB the copy is not worth being clever about.
+ */
+function scratchCopy() {
+  const dir = mkdtempSync(join(tmpdir(), 'stele-mutants-'));
+  cpSync(ROOT, dir, { recursive: true, filter: (src) => !src.endsWith('/node_modules') });
+  return dir;
+}
+
+/**
+ * `test/mutants.test.mjs` guards this script's own list by asserting every anchor matches
+ * exactly once. Applying a mutant is precisely what stops an anchor matching, so under a
+ * mutated tree that test fails — and every mutant would be scored as killed by the guard
+ * rather than by any regression test, including the equivalent one that cannot be killed
+ * at all. It runs in the ordinary suite, where it belongs, and is excluded here.
+ */
+const SELF_REFERENTIAL = 'mutants.test.mjs';
+
+/** The suite's files, expanded here rather than by a shell: `node --test test/` reads that
+ *  argument as a module path and dies, which is not a test failure but looks exactly like
+ *  one from the outside. */
+function testFiles(cwd) {
+  const dir = join(cwd, 'test');
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith('.test.mjs') && f !== SELF_REFERENTIAL)
+    .sort();
+  if (files.length === 0) throw new Error(`no test files under ${dir} — nothing to run mutants against`);
+  return files.map((f) => join('test', f));
+}
+
+/** True when the suite passes — i.e. the mutant went unnoticed. */
+function suitePasses(cwd, files) {
+  try {
+    execFileSync(process.execPath, ['--test', ...files], { cwd, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function checkMutants({ quiet = false } = {}) {
+  const dir = scratchCopy();
+  const survivors = [];
+  try {
+    const files = testFiles(dir);
+
+    // The load-bearing guard. Every verdict here is "the suite failed, so something was
+    // watching" — which is worthless if the suite fails for its own reasons, and reports a
+    // perfect score while testing nothing. The first draft of this script did exactly that:
+    // it ran `node --test test/`, which is not a directory glob, so all ten mutants "died"
+    // in 621ms against a suite that never started.
+    if (!suitePasses(dir, files)) {
+      throw new Error(
+        'the unmutated suite does not pass — every mutant would report as killed for the\n' +
+        'wrong reason. Fix the suite first, then re-run this check.',
+      );
+    }
+
+    for (const mutant of MUTANTS) {
+      const path = join(dir, mutant.file);
+      const pristine = readFileSync(path, 'utf8');
+
+      // A rotted anchor is a failure, never a skip. The alternative is a probe that quietly
+      // stops testing what it claims to — the exact false green this repo exists to remove.
+      const hits = pristine.split(mutant.find).length - 1;
+      if (hits !== 1) {
+        throw new Error(
+          `mutant anchor matched ${hits} times in ${mutant.file}, expected exactly 1:\n` +
+          `  ${mutant.label}\n` +
+          `  The code moved. Re-aim the mutant at the behaviour it was written for, or ` +
+          `delete it if that behaviour is gone.`,
+        );
+      }
+
+      writeFileSync(path, pristine.replace(mutant.find, mutant.replace));
+      const survived = suitePasses(dir, files);
+      writeFileSync(path, pristine);
+
+      // An equivalent mutant that dies is the canary, not a bonus. It cannot be detected by
+      // any honest test, so a kill means the suite failed for a reason unrelated to the
+      // mutation and every other verdict in this run is worthless. Both times this harness
+      // scored wrongly — the crashing test command, then the self-referential guard — this
+      // is the line that showed it.
+      if (mutant.equivalent && !survived) {
+        throw new Error(
+          `an equivalent mutant was killed, which cannot happen honestly:\n` +
+          `  ${mutant.label}\n` +
+          `  exempt because: ${mutant.equivalent}\n` +
+          `  The suite is failing for a reason unrelated to the mutation, so every other\n` +
+          `  verdict in this run is meaningless. Run the suite by hand and find out why.`,
+        );
+      }
+
+      if (survived && !mutant.equivalent) survivors.push(mutant);
+      if (!quiet) {
+        const verdict = mutant.equivalent ? 'exempt   (equivalent)' : (survived ? 'SURVIVED' : 'killed');
+        console.log(`  ${verdict.padEnd(24)} ${mutant.label}`);
+      }
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  return survivors;
+}
+
+function main(argv) {
+  const quiet = argv.includes('--quiet');
+  if (!quiet) console.log(`\n${ROOT} — ${MUTANTS.length} mutant(s)`);
+
+  const survivors = checkMutants({ quiet });
+  const exempt = MUTANTS.filter((m) => m.equivalent).length;
+
+  if (survivors.length === 0) {
+    console.log(`\nall ${MUTANTS.length - exempt} non-exempt mutant(s) killed, ${exempt} exempt`);
+    return 0;
+  }
+
+  console.log(`\n${survivors.length} mutant(s) survived — the behaviour below is unpinned:`);
+  for (const m of survivors) console.log(`  ${m.file}: ${m.label}`);
+  console.log(
+    '\nEach needs a regression test, or — if the mutated code genuinely means the same thing\n' +
+    '— an `equivalent` note on the mutant saying why it cannot be killed.',
+  );
+  return 1;
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}