staysfixed 0.7.2 → 0.9.0

package/src/v2/run.js

@@ -34,6 +34,7 @@ import {
   wobbleStorm,
 } from './observation.js';
 import { ensureStore, saveBuild, saveCapture, latestCapture, referenceFor, listBuilds } from './store.js';
+import { describeRuleChange } from './normalise.js';
 import { clusterDifferences } from './cluster.js';
 import { rankFindings } from './rank.js';
 
@@ -135,6 +136,10 @@ const VERSION = /** @type {{version?: string}} */ (require('../../package.json')
  * @property {string} [journey]
  * @property {string} [run]
  * @property {number} [count]
+ * @property {number} [steady]    Only on 'wobble'. Addresses this build answered the same
+ *                                way twice, counted rather than inferred by subtraction.
+ * @property {boolean} [measured] Only on 'wobble'. False when the wobble was never taken,
+ *                                which is not the same as a wobble of nothing.
  * @property {number} [durationMs]
  * @property {Verdict} [verdict]
  */
@@ -251,6 +256,11 @@ export async function runCheck(opts) {
     /** @type {string[]} */
     const steadyInReference = [];
     let referenceWobbleMeasured = true;
+    // One fact about one pair of rule sets, gathered here and said once at the end.
+    /** @type {Set<string>} */
+    const rulesMoved = new Set();
+    /** @type {string[]} */
+    const rulesMovedOn = [];
 
     for (const journey of journeys) {
       stop();
@@ -294,12 +304,22 @@ export async function runCheck(opts) {
           surface: journey.surface,
         });
       }
+      // ADDRESSES, not rows. This used to send `a.observations.length`, which counts every
+      // observation the adapter wrote down — and two observations at the SAME address are one
+      // address written down twice, not two addresses. Every other number on the page is
+      // counted by address: `foldCoverage` builds a Set, and the wobble arithmetic indexes by
+      // path. So a walk with two duplicate addresses put "18 addresses watched" in the header
+      // beside "14 addresses watched" in the coverage ledger and "18 answered the same way
+      // twice" for a build that only ever had 14 addresses to answer at. Three numbers about
+      // one run, disagreeing, on a page whose entire job is being believed. The duplicates
+      // themselves are not swallowed — `duplicateGaps` above reports each one.
+      const addresses = new Set(a.observations.map((o) => o.path)).size;
       say({
         type: 'journey:done',
         at: events.elapsed(),
         journey: journey.name,
-        count: a.observations.length,
-        message: `${a.observations.length} ${plural(a.observations.length, 'thing', 'things')} looked at, ${wobble.unstable.length} of which this build cannot answer the same way twice.`,
+        count: addresses,
+        message: `${addresses} ${plural(addresses, 'thing', 'things')} looked at, ${wobble.unstable.length} of which this build cannot answer the same way twice.`,
       });
 
       if (!reference) continue;
@@ -337,9 +357,8 @@ export async function runCheck(opts) {
         gaps.push({
           what: `The old build could not be walked for "${journey.describe || journey.name}", so this was not a paired comparison after all.`,
           why:
-            `${nameOf(reference)} was put back on this machine, and then there was nothing there to run: ${
-              wasA.observations[0]?.meta?.describe ?? 'the adapter could not open it'
-            }. This usually means the product is BUILT rather than committed — an APK, a .app, a packaged desktop app — and a checkout of the old commit does not contain one.`,
+            `${nameOf(reference)} was put back on this machine, and then there was nothing there to run: ${whyNothingRan(wasA)} ` +
+            'This usually means the product is BUILT rather than committed — an APK, a .app, a packaged desktop app — and a checkout of the old commit does not contain one.',
           unlockedBy:
             'Build the old commit before the run, or point the settings at a kept copy of the old build\'s artifact. Until then this journey falls back to the record the old build left last time.',
           surface: journey.surface,
@@ -383,20 +402,43 @@ export async function runCheck(opts) {
       // one normalised under another produces differences that are about the RULES — either a
       // wall of noise that reads like a regression, or, when the change was to add a rule,
       // quiet where there should not be any. Either way the reader has to be told.
-      if (stored.capture.rules && a.rules && stored.capture.rules !== a.rules) {
-        gaps.push({
-          what: `"${journey.describe || journey.name}" is being compared across a change to the normalisation rules.`,
-          why:
-            `The stored record of the old build was tidied up by rule set ${stored.capture.rules} and this run used ${a.rules}. ` +
-            'Some of what you see may be the rules changing rather than the product, and a rule that was added since could be covering something up.',
-          unlockedBy: 'Run a paired check, which walks the old build live under today\'s rules, or ship again to cut a fresh reference.',
-          surface: journey.surface,
-        });
+      //
+      // WHAT changed, not two hashes. This used to print "v1-fcf4b8000217 versus
+      // v1-29141a9ec069" and nothing else, which tells an agent nothing it can act on, so it
+      // acts on nothing. `describeRuleChange` owns the judgement — a rule that rewrites
+      // something differently makes the whole comparison suspect; a rule that merely reaches
+      // one more address makes only that address suspect and names it; and a record older
+      // than the scope stamp says so rather than reporting every glob as new.
+      //
+      // ONCE PER RUN, not once per journey. It is one fact about one pair of rule sets, and
+      // it was being written out again for every journey — four identical paragraphs in the
+      // coverage list on a four-journey project, on every run, saying the same thing. The
+      // coverage list is the one section that must never be skimmed, and nothing teaches a
+      // reader to skim it faster than a block that is always there and always the same.
+      const ruleChange = describeRuleChange(
+        { fingerprint: stored.capture.rules, scope: stored.capture.rulesScope },
+        { fingerprint: a.rules, scope: a.rulesScope },
+      );
+      if (!ruleChange.same) {
+        rulesMoved.add(ruleChange.say);
+        rulesMovedOn.push(journey.describe || journey.name);
       }
       if (stored.wobble) steadyInReference.push(...steadyPaths(stored.capture, stored.wobble));
       else referenceWobbleMeasured = false;
     }
 
+    if (rulesMovedOn.length > 0) {
+      const which =
+        rulesMovedOn.length === 1
+          ? `"${rulesMovedOn[0]}" is`
+          : `${rulesMovedOn.length} journeys are`;
+      gaps.push({
+        what: `${which} being compared across a change to the normalisation rules.`,
+        why: [...rulesMoved].join(' '),
+        unlockedBy: 'Run a paired check, which walks the old build live under today\'s rules, or ship again to cut a fresh reference.',
+      });
+    }
+
     stop();
     // Booting the old build is not the same as having walked it. When every live walk came
     // back holes-only — a built artifact that no checkout of the old commit contains — the
@@ -405,10 +447,19 @@ export async function runCheck(opts) {
     const walkedLive = liveWalks > 0;
     const mode = /** @type {'paired'|'stored-record'} */ (walkedLive ? 'paired' : 'stored-record');
     const wobble = wobbles.length > 0 ? mergeWobble(wobbles) : unmeasuredWobble(opts.candidate.id, '*');
+    // `steady` and `measured` are sent because they were MEASURED here, and nothing
+    // downstream can work them out. Anything drawing this event had to guess steady as
+    // "everything watched, minus the unstable ones" — a subtraction across two different
+    // populations, so it reported addresses as having answered the same way twice when the
+    // build had never been asked at them. And `measured: false` is the difference between a
+    // build that wobbled about nothing and a build whose wobble was never taken; two noughts
+    // cannot tell those apart, and only the first one is good news.
     say({
       type: 'wobble',
       at: events.elapsed(),
       count: wobble.unstable.length,
+      steady: wobble.steady,
+      measured: wobble.measured,
       message:
         wobble.unstable.length === 0
           ? 'This build gives the same answer twice, everywhere.'
@@ -599,6 +650,16 @@ export async function runCheck(opts) {
       cwd: opts.cwd,
       guards: opts.guards ?? [],
       touches: touchMap(walked),
+      // Where "your change" starts.
+      //
+      // Without this, "the change" means the working tree and nothing else — so the moment
+      // an agent commits its work, which is exactly what an agent does at the end of a task,
+      // the distance measure goes blind, the ranking loses its ordering, and every finding
+      // carries the sentence "nothing in the working tree has changed, so there is no edit
+      // to measure this against" over a change that is perfectly well known. The reference
+      // is a shipped build, which is a commit; the diff from there to here is the change,
+      // whether it has been committed or not.
+      since: reference?.gitSha ?? undefined,
     });
 
     const warning = modeWarning(mode, provedLive, reference);
@@ -920,6 +981,34 @@ const PROVEN_LIVE_WARNING =
 const NO_REFERENCE_WARNING =
   'Until you ship once with the reference hook in place there is nothing to compare against, so this run proves nothing about what still works.';
 
+/**
+ * Why the old build came back with nothing that could be walked.
+ *
+ * The adapter always says why. It says it in the observation's own sentence, which
+ * `observation()` in adapters/contract.js files under `meta.describe` — "there is no APK in
+ * the exported checkout", "the runtime this needs is not on this machine". Reading only
+ * `observations[0]` threw that away in the two cases that matter most: a capture that came
+ * back completely EMPTY has no observation nought to read, so the reader got the generic
+ * "the adapter could not open it" while the real reason sat in the capture's note; and a
+ * capture whose first observation happens to be one the adapter did cover names the wrong
+ * hole. So the first REFUSED observation is the one that answers the question, its reason
+ * category stands in when it has no sentence of its own, and the capture's note is read
+ * before anything generic is said.
+ *
+ * The sentence is also finished properly. The adapter's `says` is already a whole sentence,
+ * and the old template appended a full stop of its own — the same fault already fixed once
+ * in check.js's explain reply, which was giving agents "...real money..".
+ *
+ * @param {Capture} was   The walk of the old build that produced nothing usable.
+ * @returns {string}      One finished sentence.
+ */
+function whyNothingRan(was) {
+  const refused = was?.observations?.find((o) => o.meta?.refused === true);
+  const said = refused?.meta?.describe || refused?.meta?.refusedWhy || was?.note || 'the adapter could not open it';
+  const text = String(said).trim();
+  return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+
 /**
  * @param {'paired'|'stored-record'} mode
  * @param {boolean} provedLive

package/src/v2/sealed.js

@@ -295,26 +295,6 @@ export function classify(finding, opts = {}) {
   };
 }
 
-/**
- * The same answer as a plain class name, for callers that already work in `FindingClass`.
- *
- * @param {Finding} finding
- * @param {ClassifyOptions} [opts]
- * @returns {FindingClass}
- */
-export function sealedClassOf(finding, opts = {}) {
-  return classify(finding, opts)?.class ?? 'ordinary';
-}
-
-/**
- * @param {Finding} finding
- * @param {ClassifyOptions} [opts]
- * @returns {boolean}
- */
-export function isSealed(finding, opts = {}) {
-  return classify(finding, opts) !== null;
-}
-
 /**
  * The refusal, written out for whoever reads it — an agent that has just been told no, or a
  * person reading the closing summary.

package/src/v2/selfcheck.js

@@ -116,6 +116,49 @@ export const CASES = [
     }),
   },
 
+  {
+    // Nothing this product prints changes, deliberately. A server written straight on
+    // node:http registers nothing — there is no `app.get` for a reader to find — so before
+    // the request handler itself was read, the only honest answer here was silence, and
+    // silence is the one answer this corpus exists to make impossible.
+    name: 'a route quietly renamed in a server written by hand',
+    breaks: 'A server built straight on node:http had one of its routes renamed. Nothing it prints changes, so the only way to see it is to read the handler.',
+    expect: 'a finding',
+    mustSay: [/health/i],
+    build: (broken) => ({
+      'package.json': PKG,
+      'cli.js': [
+        "import http from 'node:http';",
+        '',
+        'const server = http.createServer((req, res) => {',
+        "  if (req.url === '/orders') {",
+        "    res.writeHead(200, { 'content-type': 'application/json' });",
+        '    res.end(\'{"orders":2}\');',
+        '    return;',
+        '  }',
+        broken
+          ? "  if (req.url === '/healthz') {"
+          : "  if (req.url === '/health') {",
+        '    res.writeHead(200);',
+        '    res.end(\'{"ok":true}\');',
+        '    return;',
+        '  }',
+        '  res.writeHead(404);',
+        "  res.end('not found');",
+        '});',
+        '',
+        "await new Promise((done) => server.listen(0, '127.0.0.1', done));",
+        'const address = server.address();',
+        "const port = typeof address === 'object' && address ? address.port : 0;",
+        'const reply = await fetch(`http://127.0.0.1:${port}/orders`);',
+        'console.log(`GET /orders -> ${reply.status}`);',
+        'console.log(await reply.text());',
+        'server.close();',
+        '',
+      ].join('\n'),
+    }),
+  },
+
   {
     name: 'a field dropped from a reply',
     breaks: 'A field quietly disappeared from a reply that everything downstream reads.',
@@ -425,6 +468,111 @@ export const CASES = [
         .join('\n'),
     }),
   },
+
+  {
+    name: "a break only the project's own tests can see",
+    breaks:
+      'A total stops rounding. The command-line program only ever adds whole pounds, so what it prints does not move by one character and every journey this tool can discover on its own stays silent. The project\'s own test adds pennies, and it is the only thing in the repository that notices.',
+    expect: 'a finding',
+    mustSay: [/pennies/i],
+    journeys: [
+      {
+        name: 'suite-test-total-test',
+        describe: 'run the 3 checks in test/total.test.js and watch what they touch',
+        source: 'suite',
+        surface: 'cli',
+        from: 'test/total.test.js',
+        channels: ['results', 'complaints', 'counters'],
+        steps: [
+          {
+            act: 'run-tests',
+            runner: 'node:test',
+            file: 'test/total.test.js',
+            // Named rather than given as a path, so this case runs on a machine whose Node
+            // lives somewhere else. `node` is on the path of any machine that got this far.
+            command: 'node',
+            argv: ['--test', '--test-reporter=tap', 'test/total.test.js'],
+            note: 'Run this exactly as it was harvested. A test file run a different way is a different journey.',
+          },
+        ],
+      },
+    ],
+    build: (broken) => ({
+      'package.json': JSON.stringify(
+        { name: 'widget', version: '1.0.0', type: 'module', bin: { widget: 'cli.js' }, scripts: { test: 'node --test' } },
+        null,
+        2,
+      ) + '\n',
+      'total.js': [
+        'export function total(items) {',
+        '  let sum = 0;',
+        '  for (const item of items) sum += item.price;',
+        broken ? '  return sum;' : '  return Math.round(sum * 100) / 100;',
+        '}',
+        '',
+      ].join('\n'),
+      'cli.js': [
+        "import { total } from './total.js';",
+        '// Whole pounds only, which is why running the product proves nothing here.',
+        'console.log(total([{ price: 2 }, { price: 3 }]));',
+        '',
+      ].join('\n'),
+      'test/total.test.js': [
+        "import { test } from 'node:test';",
+        "import assert from 'node:assert/strict';",
+        "import { total } from '../total.js';",
+        '',
+        "test('adds whole pounds', () => {",
+        '  assert.equal(total([{ price: 2 }, { price: 3 }]), 5);',
+        '});',
+        '',
+        "test('adds pennies without floating point dust', () => {",
+        '  assert.equal(total([{ price: 0.1 }, { price: 0.2 }]), 0.3);',
+        '});',
+        '',
+      ].join('\n'),
+    }),
+  },
+
+  {
+    name: 'a break behind an npm script',
+    breaks:
+      'A message changes, behind `npm run`. Nothing about the product is unusual — what this case really watches is the watcher: it rides inside the child, and until 2026-08-30 the proxy it put over the environment had no `set` trap, so npm wrote npm_lifecycle_event, read back nothing, and exited 1 without printing a word. Every product whose start command went through npm looked like a product that would not boot, on both builds equally, which is a silence rather than a finding.',
+    expect: 'a finding',
+    mustSay: [/two orders|three orders/i],
+    journeys: [
+      {
+        name: 'run-it',
+        describe: 'Run the product the way its own package.json says to run it.',
+        source: 'code',
+        surface: 'cli',
+        steps: [
+          {
+            act: 'run',
+            run: 'npm run --silent report',
+            note: 'through npm, because that is what `staysfixed init` writes by default',
+            env: {
+              // npm's own update check reaches for the registry, which is refused - and an
+              // attempt that happens on one run and not the next is noise this case would
+              // then have to argue about. Switched off rather than subtracted.
+              NO_UPDATE_NOTIFIER: '1',
+              npm_config_update_notifier: 'false',
+              npm_config_audit: 'false',
+              npm_config_fund: 'false',
+            },
+          },
+        ],
+      },
+    ],
+    build: (broken) => ({
+      'package.json': JSON.stringify(
+        { name: 'widget', version: '1.0.0', type: 'module', scripts: { report: 'node report.js' } },
+        null,
+        2,
+      ) + '\n',
+      'report.js': `console.log('${broken ? 'three' : 'two'} orders');\n`,
+    }),
+  },
 ];
 
 /**
@@ -477,22 +625,51 @@ async function makeStoreUnwritable(dir, working) {
     return { ready: false, why: `the warm-up run did not work: ${why(e)}` };
   }
 
-  /** @type {string[]} */
-  const shut = [];
-  for (const build of await fsp.readdir(builds, { withFileTypes: true })) {
-    if (!build.isDirectory()) continue;
-    const inside = path.join(builds, build.name);
-    for (const journey of await fsp.readdir(inside, { withFileTypes: true })) {
-      if (!journey.isDirectory()) continue;
-      const folder = path.join(inside, journey.name);
-      await fsp.chmod(folder, 0o555);
-      shut.push(folder);
-    }
-  }
-  if (shut.length === 0) return { ready: false, why: 'the warm-up run stored nothing, so there was nothing to make read-only' };
+  // Shut every folder under the store, not only the ones the captures land in.
+  //
+  // This walked two levels by hand — builds, then journeys — which left the build record
+  // itself writable. That is the wrong half: `openProject` writes the build record before a
+  // single journey runs, so a disk that has given out fails THERE first, and a case that
+  // only shuts the capture folders never exercises the path the real failure takes.
+  // Shutting the whole store is the mirror of `relax`, which is what puts it back.
+  const shut = await shutTight(path.join(dir, '.staysfixed', 'v2'));
+  if (shut === 0) return { ready: false, why: 'the warm-up run stored nothing, so there was nothing to make read-only' };
   return { ready: true, why: '' };
 }
 
+/**
+ * Make a folder and everything under it read-only, and say how many folders that was.
+ *
+ * The exact mirror of `relax`, which undoes it. Failures are ignored on purpose: a folder
+ * that will not change permissions is one this case cannot use, and the count tells the
+ * caller whether enough of the store was shut for the case to mean anything.
+ *
+ * @param {string} dir
+ * @returns {Promise<number>}
+ */
+async function shutTight(dir) {
+  /** @type {import('node:fs').Dirent[]} */
+  let inside = [];
+  try {
+    inside = await fsp.readdir(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let shut = 0;
+  for (const entry of inside) {
+    if (entry.isDirectory()) shut += await shutTight(path.join(dir, entry.name));
+  }
+  // The folder itself last: shut it first and its own children become unreachable.
+  try {
+    await fsp.chmod(dir, 0o555);
+    shut += 1;
+  } catch {
+    // Read-only already, or a filesystem that will not say no. Either way, not a reason
+    // to stop — `relax` will still walk it, and the count tells the caller what happened.
+  }
+  return shut;
+}
+
 // ---------------------------------------------------------------------------
 // Running it
 // ---------------------------------------------------------------------------

package/src/v2/ship.js

@@ -156,15 +156,29 @@ export async function onShip(opts = {}) {
     const store = openStore({ root });
     await ensureStore(store);
 
-    const build = await resolveBuild(store, product, release, opts.build);
+    /** @type {string[]} */
+    const unreadable = [];
+    const build = await resolveBuild(store, product, release, opts.build, (/** @type {string} */ why) => unreadable.push(String(why)));
+    if (unreadable.length > 0) {
+      // Said whether or not a build was found, because a damaged record changes what the
+      // answer is worth either way: if none was found it may be the reason, and if one was
+      // found it may not be the right one.
+      result.lines.push(
+        `${unreadable.length} stored ${unreadable.length === 1 ? 'record' : 'records'} of ${product} could not be read, so ${unreadable.length === 1 ? 'it was' : 'they were'} left out of this decision: ${unreadable.join('; ')}`,
+      );
+    }
     if (!build) {
       result.cut = false;
+      const because = unreadable.length > 0
+        ? ` ${unreadable.length} of its stored ${unreadable.length === 1 ? 'record' : 'records'} could not be read, which may be why.`
+        : '';
       result.lines = [
         `${product} ${release.describe}`,
-        `Stays Fixed has no record of this build, so it did not become the reference. Nothing about ${product} is being compared against anything yet.`,
+        `Stays Fixed has no record of this build, so it did not become the reference. Nothing about ${product} is being compared against anything yet.${because}`,
         'Run `staysfixed check` once before the next release and it will record itself from then on.',
+        ...(unreadable.length > 0 ? [`What could not be read: ${unreadable.join('; ')}`] : []),
       ];
-      result.summary = `${product} shipped ${release.what}, but Stays Fixed had never seen this build, so what "working" means has not moved. Run a check before the next release.`;
+      result.summary = `${product} shipped ${release.what}, but Stays Fixed had never seen this build, so what "working" means has not moved.${because} Run a check before the next release.`;
       return result;
     }
 
@@ -381,10 +395,20 @@ async function versionBump(root) {
  * @param {string} product
  * @param {Release} release
  * @param {string|BuildFingerprint} [told]
+ * @param {(why: string) => void} [onProblem]  Told about any stored record that would not open.
  * @returns {Promise<BuildFingerprint|null>}
  */
-async function resolveBuild(store, product, release, told) {
-  const builds = await listBuilds(store, { product });
+async function resolveBuild(store, product, release, told, onProblem) {
+  // A record nobody could read must never be silently absent here.
+  //
+  // This function decides which build becomes the definition of "working" for a whole
+  // product. `listBuilds` skips a damaged record rather than failing, which is right for a
+  // listing and wrong here twice over: a build whose record will not open looks exactly like
+  // a build that was never walked, so the answer is "Stays Fixed has never seen this build"
+  // when the truth is "it has, and the record is broken"; and where two builds share a
+  // commit, losing the clean one to a damaged record leaves the dirty one to be blessed in
+  // its place. Neither is a thing to work out from an empty list.
+  const builds = await listBuilds(store, { product, onProblem });
 
   if (told) {
     const id = typeof told === 'string' ? told : told.id;
@@ -393,6 +417,32 @@ async function resolveBuild(store, product, release, told) {
     return typeof told === 'string' ? { id: told, product } : told;
   }
 
+  // WHAT IS ACTUALLY HERE, before what the commit says is here.
+  //
+  // Matching on the commit alone blesses the wrong thing the moment the tree is dirty:
+  // several builds share one commit, this took the first of them, and that is usually an
+  // EARLIER build — one that was checked and came back clean. So editing a file and running
+  // `staysfixed ship` answered "was already the reference — nothing changed" and exited 0,
+  // about a tree nothing had ever looked at. Measured 2026-08-30 by deleting a button and
+  // shipping without a check.
+  //
+  // A dirty tree therefore has to match EXACTLY, on the fingerprint of what is on disk right
+  // now. If nothing on record is that tree, then this tree has not been checked, and the
+  // honest answer is the one the tool already knows how to give: no record of this build, so
+  // the reference does not move.
+  try {
+    const { fingerprintWorkingTree } = await import('./check.js');
+    const here = await fingerprintWorkingTree(store.root, product);
+    if (here?.id) {
+      const exact = builds.find((b) => b.fingerprint.id === here.id);
+      if (exact) return exact.fingerprint;
+      if (here.dirty) return null;
+    }
+  } catch {
+    // No git, or the tree could not be read. The joins below are all that is left, and they
+    // are better than refusing to record a release at all.
+  }
+
   const sha = release.gitSha;
   if (sha) {
     const sameCommit = builds.filter((b) => b.fingerprint.gitSha === sha);

package/src/v2/store.js

@@ -256,7 +256,7 @@ export async function saveCapture(store, capture) {
  * clears those up.
  *
  * @param {Store} store
- * @param {{build: BuildFingerprint, journey: string, run: CaptureRun, id?: string, source?: JourneySource, startedAt?: string, rules?: string}} opts
+ * @param {{build: BuildFingerprint, journey: string, run: CaptureRun, id?: string, source?: JourneySource, startedAt?: string, rules?: string, rulesScope?: Record<string, string[]>}} opts
  * @returns {Promise<{ref: CaptureRef, append: (o: Observation) => Promise<void>, close: (end?: {durationMs?: number, coverage?: Coverage, note?: string}) => Promise<CaptureRef>, abandon: () => Promise<void>}>}
  */
 export async function openCaptureWriter(store, opts) {
@@ -282,6 +282,7 @@ export async function openCaptureWriter(store, opts) {
   };
   if (opts.source) shell.source = opts.source;
   if (opts.rules) shell.rules = opts.rules;
+  if (opts.rulesScope) shell.rulesScope = opts.rulesScope;
   await handle.write(JSON.stringify(headerOf(shell)) + '\n');
 
   let open = true;
@@ -367,6 +368,16 @@ async function bumpBuild(store, capture) {
 }
 
 /**
+ * The first line of a capture file.
+ *
+ * The field list is written out rather than spread, so that what reaches disk is a decision
+ * somebody made. The cost of that is this: a field added to `Capture` and not added here is
+ * silently dropped, and everything downstream reads its absence as a fact about the run. It
+ * happened to `rulesScope` — stamped on every capture, written to none of them, and the
+ * feature that reads it took the "this record predates the stamp" branch forever. If you add
+ * a field to Capture that a later run needs, add it here and to the read in `loadCapture`,
+ * and prove it with a write-then-read test rather than a unit test on the stamping.
+ *
  * @param {Capture} capture
  * @returns {Record<string, unknown>}
  */
@@ -381,6 +392,7 @@ function headerOf(capture) {
     run: capture.run,
     startedAt: capture.startedAt,
     rules: capture.rules,
+    rulesScope: capture.rulesScope,
   };
 }
 
@@ -512,6 +524,7 @@ export async function loadCapture(store, where) {
   };
   if (header.source) capture.source = header.source;
   if (header.rules) capture.rules = header.rules;
+  if (header.rulesScope) capture.rulesScope = header.rulesScope;
   if (end?.coverage) capture.coverage = end.coverage;
 
   const notes = [];
@@ -824,6 +837,59 @@ export async function pruneBuild(store, buildId, opts = {}) {
   return { removed, kept };
 }
 
+/**
+ * Throw the whole of a build away: its record, its captures, its folder.
+ *
+ * The companion `pruneBuild` thins one build's captures down to the newest few, which is the
+ * right tool when a build is worth keeping and its hundred captures are not. It is the wrong
+ * tool for the growth anybody actually measures: one build FOLDER per check, forever, in a
+ * directory this tool asks people to commit. Nothing could remove a folder at all, so the only
+ * housekeeping that existed could not touch the thing that grows.
+ *
+ * The two refusals are the same two, for the same reason, and they are loud rather than quiet
+ * because deleting the evidence of what "working" means is not recoverable:
+ *
+ *   - A build any product points at as its reference is never removed. Its captures are the
+ *     only record of what working looked like, and once they are gone the next check has
+ *     nothing to compare against.
+ *   - A build whose own record cannot be read is never removed. An unreadable record is the
+ *     one state where we do not know what we would be deleting, and "I could not tell, so I
+ *     deleted it" is the wrong way round.
+ *
+ * WHAT TO KEEP IS NOT DECIDED HERE. This removes one build that has been named. Which builds
+ * are worth keeping — how many, how long, whether a `work-` build off a dirty tree is worth
+ * less than a `git-` one off a commit — is a policy about somebody's disk and their history,
+ * and it belongs where the run knows what it just did, not in the file that owns the folder.
+ *
+ * @param {Store} store
+ * @param {string} buildId
+ * @returns {Promise<{removed: true, captures: number}>}
+ */
+export async function removeBuild(store, buildId) {
+  const record = await loadBuild(store, buildId);
+  const references = await loadReferences(store);
+
+  // Asked of the POINTERS rather than of the build's own record, for the reason spelled out in
+  // pruneBuild: a build whose build.json is missing answers nothing, and reading it the other
+  // way round would skip the guard exactly when it matters most.
+  const pointedAt = Object.values(references).filter((p) => p?.buildId === buildId);
+  if (pointedAt.length > 0) {
+    throw new StaysFixedError(
+      `${buildId} is the reference for ${pointedAt.map((p) => p.product).join(', ')}, so it cannot be thrown away.`,
+      { hint: 'Point the reference at a newer build first, with setReference.' },
+    );
+  }
+  if (!record) {
+    throw new StaysFixedError(`Nothing here says what ${buildId} is, so it will not be thrown away.`, {
+      hint: 'Its build.json is missing. Deleting a build on the strength of a record nobody can read is how the evidence for "this used to work" disappears. Run a check against it to rewrite the record, or delete the folder deliberately.',
+    });
+  }
+
+  const captures = (await listCaptures(store, { buildId })).length;
+  await fsp.rm(buildDir(store, buildId), { recursive: true, force: true });
+  return { removed: true, captures };
+}
+
 /**
  * Delete `.part` files left behind by runs that died.
  *