staysfixed 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -8,6 +8,137 @@ numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [0.9.1] — 2026-08-30
+
+Eleven more, from the same hunt that produced 0.9.0 — the findings it had already paid for.
+Every one of these was decided by reading the code rather than by building another product to
+reproduce it; the ones that genuinely need a Next.js app or a monorepo are written down and
+left, because guessing at them would be worse.
+
+### Fixed
+
+- **Every API shape change on every project was sealed as LOSING DATA**, permanently, and no
+  agent could wave any of it through. The classifier reads the words in a finding — and it
+  was reading the difference's *description*, which is the TOOL's sentence, identical on every
+  finding that channel makes: "a renamed or dropped field shows up on its own". `dropped` is
+  a data-loss word. A seal is decided by what the PRODUCT said now — its addresses, its
+  values, its journey names — never by vocabulary no user wrote and nobody can change. A real
+  deletion still seals.
+- **`ship` printed no coverage caveat at all**, in text or `--json`. It is the command that
+  decides what "working" MEANS from that moment on, which makes it the last place that should
+  stay quiet about what the check never walked. It says it now, in the same breath as the
+  good news, exactly as every other surface does.
+- **`init` said "Nothing is being left out."** from a survey of which SURFACES this machine
+  can drive — on a project the same run reported as five of six doors never opened. And
+  `getting-started` tells the agent to repeat that sentence to the person.
+- **The MCP server echoed an agent's own strings back unbounded and kept them for ever.** A
+  megabyte of summary came back as a megabyte of tool result. Capped, and the cut says so
+  rather than quietly keeping the first part.
+- **`check --journeys recorded` reported a missing FILE called "recorded".** `--help` offers
+  the word and the MCP surface answers it honestly — written, not wired into a run yet. The
+  same question gets the same answer on both surfaces now.
+- **Guard names that said nothing were accepted**: `a b c`, `1 2 3`, `TODO fix later` and
+  `AC-101 regression check` all passed every rule. That name is the sentence somebody reads
+  when the guard fails, six months from now. Refused now — and every name that actually says
+  something still passes.
+- **Every command-line check wrote two rows** to the log `ship` reads, so any count of how
+  many checks had run was doubled.
+- **`--only` printed "everything that worked still works"** about a slice, with five of six
+  guards filtered away and one of the five failing.
+- **`ship` blessed a build nothing had ever looked at** — it matched by git commit, so an
+  uncommitted edit resolved to an earlier build that had been checked and was clean.
+- `docs/running-it-in-ci.md` told you to copy `.github/workflows/staysfixed.yml` "as it is".
+  That file is not in the npm package. It is printed in full in the page now.
+- `docs/mcp.md` still told you to fill the project path in by hand; `doctor --json` has
+  filled it in since 0.8.0, and a path filled in wrongly fails silently.
+
+## [0.9.0] — 2026-08-30
+
+Found the same way as 0.8.0 and one better: the published build was installed as a stranger
+installs it and used on real throwaway products — a café API, a static site, a library, a
+server that spawns its own child — until it said something untrue. And this time the repo's
+own CI was read, which had been **red for ten releases** while every summary said the tests
+passed. It was red for two real reasons, both below.
+
+**The tool was breaking the products it was sent to protect**, and on some shapes it never
+came back at all. Those two are why this release exists.
+
+### Fixed — it broke the product, or itself
+
+- **Refusing a connection killed the program that made it.** The refusal was delivered by
+  emitting `'error'` on the socket; at that instant nothing is listening, and in Node an
+  `'error'` with no listener is a thrown exception. `http.get` on Node 22 — the floor this
+  package declares — and a bare `net.connect` on every version died with exit 1, and the run
+  then reported the user's product as broken. The refusal is real now rather than simulated,
+  so the operating system produces it through Node's own plumbing.
+- **`check` printed its whole answer and never exited.** A start command runs through a
+  shell, so the server is a grandchild; killing the shell left it alive holding the output
+  pipe, so the event loop never emptied. It also orphaned the server. The shell is started as
+  its own process group now and the whole group is signalled.
+- **Two agents shipping at once lost what "working" means.** Six ships, all reporting
+  success, four records, and the "already the reference" path never firing. The whole cut is
+  one at a time per product now.
+- **Every killed run left a whole copy of the project in the temporary folder, for ever** —
+  777 MB of them on an ordinary machine. Abandoned copies are reclaimed; a copy a live run
+  owns is never touched.
+
+### Fixed — it said things that were not true
+
+- **The agent was told "everything that worked before still works"** about a run that
+  compared nothing at all, while the terminal correctly called it no answer. The engine's
+  verdict is the floor for the machine surface now, so this class cannot come back one reason
+  at a time.
+- **A sealed money change reached the agent labelled `"ordinary"`** — the human text said
+  sealed, `waive` refused it, and the JSON said it was waivable.
+- **The seal that exists because somebody was burned before could never fire.** Guard names
+  were never passed to the decision, so that class was empty on every run this tool has ever
+  done. And a check on a project with a guard in `.staysfixed/guards` printed the word
+  "guard" zero times: not run, not counted, not mentioned.
+- **A guard that asks nothing was reported as holding.** An empty `run()` came back as
+  "still holds", and would have said so every day for ever.
+- **The library journey never imported anything.** `init` writes `module: "index.js"`; the
+  probe treated that as a package name, failed identically on both builds, and the check said
+  "Nothing that worked has changed" for ever.
+- **`ship` blessed a build nothing had looked at.** It matched by git commit, so an
+  uncommitted edit resolved to an earlier build that had been checked and was clean.
+- **`doctor` said a check "here" covers things in a folder where a check cannot run at all.**
+- **`--only` printed "everything that worked still works"** about a slice.
+- **`init` and `doctor` both offered `check --paired` as the way to record a reference.** It
+  cannot; only shipping cuts one, on purpose. `doctor` also marked it as something the agent
+  could do — the single thing an agent must never do.
+- **`status` said nothing had happened** one command after a check and a ship.
+- **It called the person's own browser "a separate application from the browser you use"**,
+  which is the one case where that sentence matters and the one case it was false.
+
+### Fixed — it could not see, or would not run
+
+- **Full Chrome was invisible on Linux and Windows.** Playwright and Puppeteer both unpack
+  into `chrome-linux64` and `chrome-win64`; only macOS uses the names this looked for. On
+  Linux, the very command this tool tells people to run left a browser it could not find.
+- **`status`, `walk`, `flake`, `approve`, `mark` and `trace` told a website it had no
+  screen** — they only knew version 1's `app:`, and `init` writes version 2's `web:`.
+- **The sign-in example `init` writes used two words the tool does not know**, and a step made
+  only of unknown words was skipped in silence — so the form was never filled, every page
+  behind the login photographed the login page, and the run came back clean.
+- **A browser's throwaway profile outlived an interrupted run.**
+
+### Fixed — it was noisy or unhelpful
+
+- **Renaming one heading came back as five findings**, none of them saying "renamed". A thing
+  addressed by its own words is now recognised when it is renamed, and its children travel
+  with it.
+- **`doctor` connected to every machine in your ssh config, unasked, on the first run.** Nine
+  connections on a brand-new scratch project. It is asked for now, and the machines are still
+  listed either way.
+- **Every command-line check wrote two rows** to the log `ship` reads.
+- **The `.gitignore` lines `init` writes matched nothing version 2 writes** — 151 untracked
+  files and 1.9 MB of run evidence in `git status` after nine checks.
+- `check --json` now carries `notChecked` and `doorsNeverOpened`, which the README had
+  promised and only the MCP reply had.
+- `init` no longer names `staysfixed check --product <name>`, which is not an option.
+- The docs said the self-check builds seventeen products; it builds twenty.
+- `process.alsoWatch` is documented.
+
 ## [0.8.0] — 2026-08-30
 
 The night this was pointed at itself. Everything below was found the same way:

package/README.md

@@ -808,7 +808,7 @@ A tool that reports "nothing changed" looks exactly like a tool that is broken,
 and there is no way to tell the two apart from the outside. So:
 
 **It has to prove it still catches things.** `staysfixed check --selfcheck`
-builds seventeen tiny products — each a real repository with a working commit and
+builds twenty tiny products — each a real repository with a working commit and
 an uncommitted change on top, which is the shape an agent actually points this
 tool at — and requires the engine to behave on every one.
 
@@ -843,7 +843,7 @@ a false accusation people learn to ignore. Measured on 2026-08-30: eleven of
 eleven, three times running, with the project's own suite running in parallel and
 the machine's load average between 227 and 334; then twelve of twelve after the
 second sweep of silences, three times running, with the suite in parallel again
-and the load average between 208 and 343; and finally **seventeen of seventeen**,
+and the load average between 208 and 343; and finally **twenty of twenty**,
 with the suite in parallel, at the end of the same day.
 
 **The unstable app.** `fixtures/unstable-app` is a page built to be impossible to

package/docs/getting-started.md

@@ -229,7 +229,7 @@ watch it notice. There is a built-in version of the same idea:
 staysfixed check --selfcheck
 ```
 
-which builds seventeen deliberately broken products and proves the engine still behaves on
+which builds twenty deliberately broken products and proves the engine still behaves on
 every one — twelve breaks it must catch, four clean pairs it must stay silent about, and one
 product so unsteady that the only correct answer is that the run says nothing at all. A case that
 misbehaves is built again and run again before that counts: fail twice and it is a real

package/docs/mcp.md

@@ -293,3 +293,16 @@ Nobody who wired that up has to change anything. Everything version 1's picture
 check did is also still reachable from the command line — `staysfixed check
 --pictures`, `staysfixed approve` — and pictures still require a person to
 approve them there, for the same reason they always did.
+
+---
+
+## You do not have to fill the path in yourself
+
+The blocks above show `/absolute/path/to/your/project` because a page cannot know where you
+are. `staysfixed doctor --json` can: its `wiring.mcp` carries the same block with `cwd`
+already set to this project, ready to paste. Ask for that rather than editing by hand — a
+path filled in wrongly fails silently, which is the worst way for this to go wrong.
+
+```sh
+npx staysfixed doctor --json | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.stringify(JSON.parse(s).wiring.mcp,null,2)))"
+```

package/docs/running-it-in-ci.md

@@ -17,7 +17,7 @@ Three files make that work:
 
 | | |
 | --- | --- |
-| `.github/workflows/staysfixed.yml` | The job. Copy it into your own project as it is. |
+| `.github/workflows/staysfixed.yml` | The job. It is printed in full at the bottom of this page, because it is not in the npm package. |
 | `src/v2/ci.js` | Works out what to compare against, runs the check, writes the report, exits with the code that decides the job. |
 | This file | What it can and cannot do up there, and why. |
 
@@ -304,3 +304,125 @@ What is **not** proved, and would only be settled by a real run:
 - How long a paired run takes on a real product. On a two-command scratch project it was
   about a second; a real project with a browser in it will be minutes, and the 30-minute
   timeout in the workflow is a guess.
+
+---
+
+## The workflow itself
+
+This file lives in the repository, not in the npm package — so if you installed Stays Fixed
+from npm you cannot copy it off disk, and the line above used to send you looking for it.
+Here it is in full. Save it as `.github/workflows/staysfixed.yml` in your own project.
+
+```yaml
+# Prove that nothing which already worked has changed — on every pull request.
+#
+# WHY A BUILD SERVER IS A GOOD PLACE FOR THIS, and not a compromise. Everything Stays Fixed
+# concludes rests on one claim: the difference was caused by the change and nothing else. A
+# fresh runner has the same fonts every time, the same operating system, nothing else
+# competing for a port, and no half-finished experiment left over from yesterday. It is a
+# better machine for this job than anybody's laptop.
+#
+# WHAT IT COMPARES AGAINST. On a pull request: the commit your branch forked from — put back
+# on this same runner with `git archive` and walked again, minutes apart. That is a full
+# paired run, and it needs nothing stored from a previous job. On a push it works down to the
+# last release, the last tag, or the commit before. Whichever it lands on is named in the job
+# summary, because they are not equally strong.
+#
+# THE ONE LINE YOU MUST NOT DELETE is `fetch-depth: 0`. A shallow checkout answers "what did
+# this branch fork from" with "this commit" — so the check would compare the build against
+# itself, find nothing, and go green. Stays Fixed catches that and refuses, but the run is
+# then worth nothing. Full history is what makes this work.
+
+name: Stays Fixed
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+# Nothing is published, released or tagged here, and no token is used for anything.
+permissions:
+  contents: read
+
+# Two runs of the same branch would be two builds on one machine fighting over ports and
+# user data directories. Sequential, never simultaneous, is a rule of the whole tool.
+concurrency:
+  group: staysfixed-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Has anything that worked changed?
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Read the paragraph above before changing this.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install
+        run: npm ci || npm install
+
+      # Only needed if anything you check is a web page. Delete these three lines for a
+      # command line tool or a library — the check will say what it could not look at either way.
+      - name: A browser to look at web pages with
+        run: npx playwright install chromium
+
+      - name: Is Stays Fixed set up in this project?
+        id: setup
+        run: |
+          # Two separate looks on purpose. One `ls` over both patterns fails whenever
+          # either of them matches nothing, which would report a configured project as
+          # unconfigured and quietly skip the whole check.
+          if ls staysfixed.config.* >/dev/null 2>&1 || ls .staysfixed/config.* >/dev/null 2>&1; then
+            echo "configured=yes" >> "$GITHUB_OUTPUT"
+          else
+            echo "configured=no" >> "$GITHUB_OUTPUT"
+            {
+              echo "## Stays Fixed"
+              echo
+              echo "This project has no Stays Fixed settings file, so **nothing was checked**."
+              echo "This job is green because nothing was claimed — not because anything was proved."
+              echo
+              echo 'Run `npx staysfixed init` in your project to set it up.'
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      # Works out what to compare against, runs the check, writes the plain-English report
+      # into the job summary, and exits with the code that decides this job:
+      #
+      #   0  nothing that already worked has changed
+      #   1  something changed that nobody accounted for
+      #   2  the check could not run, or there was nothing to compare against — which is
+      #      NOT a pass, and is why this step has no `continue-on-error`
+      - name: Check
+        if: steps.setup.outputs.configured == 'yes'
+        run: |
+          # In your own project Stays Fixed is a dependency. In the Stays Fixed repository
+          # itself it is the source you are looking at. Both paths are tried so this file
+          # can be copied straight out of one into the other.
+          if [ -f node_modules/staysfixed/src/v2/ci.js ]; then
+            node node_modules/staysfixed/src/v2/ci.js
+          else
+            node src/v2/ci.js
+          fi
+
+      # Every observation both builds produced, the verdict, and what it compared against.
+      # Kept even when the job fails — especially then.
+      - name: Keep the evidence
+        if: always() && steps.setup.outputs.configured == 'yes'
+        uses: actions/upload-artifact@v4
+        with:
+          name: staysfixed-${{ github.run_id }}
+          path: |
+            .staysfixed/ci
+            .staysfixed/v2
+          if-no-files-found: ignore
+          retention-days: 14
+```

package/docs/settings.md

@@ -61,6 +61,21 @@ twice, and subtracted. And there is nothing to approve: the build you say
 
 ---
 
+
+### `process.alsoWatch`
+
+A list of extra folders a command is allowed to touch, so that what it writes there is
+watched rather than counted as a surprise. The tool's own run output names this option, and
+until 2026-08-30 it appeared nowhere here — in a page whose promise is every option, per kind
+of product.
+
+```js
+process: {
+  commands: [{ name: 'build', run: 'npm run build' }],
+  alsoWatch: ['dist', '../shared/generated'],
+}
+```
+
 ## `product`
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/cli/status.js

@@ -2,11 +2,55 @@
  * `staysfixed status` — reads what is on disk and says it. Launches nothing.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+
 import { loadProject } from '../core/config.js';
 import { projectStatus } from '../run.js';
 import { printStatus } from '../report/console.js';
 import { EXIT } from '../core/errors.js';
 
+/**
+ * What version 2 has recorded here, if anything.
+ *
+ * `status` only ever counted version 1's things — approved pictures, screens, guards,
+ * markers — so on a project that had just been checked and shipped it said "Nothing has been
+ * checked here yet. Start with: staysfixed check". Measured on 2026-08-30, one command after
+ * a run that walked 36 addresses and a ship that cut the reference. The command whose whole
+ * promise is to say instantly what is going on here was the one saying nothing had happened.
+ *
+ * @param {string} root
+ * @returns {{at: string, verdict: string, reference: string|null, findings: number}|null}
+ */
+export function versionTwoState(root) {
+  try {
+    const file = path.join(root, '.staysfixed', 'v2', 'last-check.json');
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!raw || typeof raw.at !== 'string') return null;
+    // The reference is read from where it is KEPT, not from the last check's memory of it.
+    // A check writes what it compared against at the time; ship cuts a reference after
+    // that, so on the ordinary first-run order — check, then ship — the check's field still
+    // says "no-reference-yet" while a reference plainly exists.
+    let reference = null;
+    try {
+      const cuts = JSON.parse(fs.readFileSync(path.join(root, '.staysfixed', 'v2', 'reference-log.json'), 'utf8'));
+      const newest = Array.isArray(cuts) && cuts.length ? cuts[cuts.length - 1] : null;
+      if (newest && typeof newest.id === 'string') reference = newest.id;
+    } catch {
+      if (typeof raw.reference === 'string' && raw.reference !== 'no-reference-yet') reference = raw.reference;
+    }
+    return {
+      at: raw.at,
+      verdict: typeof raw.verdict === 'string' ? raw.verdict : 'ran',
+      reference,
+      findings: Array.isArray(raw.findings) ? raw.findings.length : 0,
+    };
+  } catch {
+    // Nothing recorded, or nothing readable. Either way there is nothing to add.
+    return null;
+  }
+}
+
 /**
  * @param {import('./index.js').CliContext} ctx
  * @returns {Promise<number>}
@@ -14,6 +58,6 @@ import { EXIT } from '../core/errors.js';
 export async function run(ctx) {
   const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
   const status = await projectStatus(project);
-  printStatus(/** @type {any} */ (status));
+  printStatus(/** @type {any} */ ({ ...status, v2: versionTwoState(project.paths?.root ?? ctx.cwd) }));
   return EXIT.ok;
 }

package/src/core/config.js

@@ -146,6 +146,27 @@ export function resolveConfig(raw, file = '(inline)') {
   }
   const c = /** @type {import('../types.js').StaysFixedConfig} */ (raw);
 
+  // Version 2's settings describe a website under `web:` and a desktop app under
+  // `electron:`. These commands are version 1's and only ever knew about `app:` — so on the
+  // settings file `staysfixed init` writes for a website, `status`, `walk` and `flake` all
+  // answered "these settings do not name anything to open", and then listed `process,
+  // source` as the shape of the project. `init` had said, one command earlier, "The website
+  // can be checked here now ... watched by opening it in a throwaway browser". Both about
+  // the same file, seconds apart, and `status` is the command whose whole promise is to say
+  // instantly what is set up here.
+  //
+  // Where the address is actually knowable, take it and let the command work. Booting is
+  // version 2's job and these commands cannot do it, so `web.start` alone is not enough —
+  // that case falls through to the message below, which now says so honestly.
+  if ((!c.app || typeof c.app !== 'object')) {
+    const v2 = /** @type {Record<string, any>} */ (/** @type {unknown} */ (c));
+    if (v2.web && typeof v2.web === 'object' && typeof v2.web.url === 'string' && v2.web.url) {
+      c.app = { kind: 'web', url: v2.web.url };
+    } else if (v2.electron && typeof v2.electron === 'object' && typeof v2.electron.binary === 'string' && v2.electron.binary) {
+      c.app = { kind: 'electron', binary: v2.electron.binary };
+    }
+  }
+
   if (!c.app || typeof c.app !== 'object') {
     // Every command that lands here — status, walk, approve, mark, trace, flake, and
     // `check --pictures` — works by OPENING something and photographing it. A settings
@@ -155,6 +176,16 @@ export function resolveConfig(raw, file = '(inline)') {
     // half of the tool needs it, and names the half that does not.
     const anything = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (c));
     const notVisual = ['process', 'http', 'source', 'android', 'ios', 'windows'].filter((k) => anything[k] && typeof anything[k] === 'object');
+    // A project that DOES have a screen, described the version 2 way, must never be told it
+    // has none. It is told the true thing instead: this half of the tool photographs an
+    // address you can point it at, and version 2 finds the address by booting the product,
+    // which is why `check` covers it and these do not.
+    const started = anything.web && typeof anything.web === 'object' && typeof (/** @type {any} */ (anything.web).start) === 'string';
+    if (started) {
+      throw new StaysFixedError('This project has a website, but these settings start it rather than name an address, and this command photographs an address.', {
+        hint: "`staysfixed check` covers it exactly as it is — it boots `web.start` and finds the address itself. These picture commands need one they can point at, so add `url: 'http://localhost:3000'` beside `start` in the `web` block if you want them too.",
+      });
+    }
     throw new StaysFixedError('These settings do not name anything to open, and this command works by opening your product and photographing it.', {
       hint: notVisual.length
         ? `That is the right shape for what this project is — ${notVisual.join(', ')} settings need nothing to open. Run \`staysfixed check\`, which covers it without a picture. If there IS a screen here too, add \`app: { kind: 'web', url: 'http://localhost:3000' }\` or \`app: { kind: 'electron', binary: '...' }\`.`

package/src/core/paths.js

@@ -139,4 +139,19 @@ export const GITIGNORE_LINES = [
   // Where one person dragged the watch panel on one screen. Nobody else's business,
   // and it would otherwise turn up in their commits.
   '.staysfixed/watch-window.json',
+  // Version 2's evidence, which none of the lines above match — they were all written for
+  // version 1's folders. Measured 2026-08-30 on a Next.js project: 151 untracked files and
+  // 1.9 MB of run evidence sitting in `git status` after nine checks, and every release then
+  // warning that it was made from a dirty tree. `builds/` is the bulk of it: one folder per
+  // build, holding what each run observed.
+  '.staysfixed/v2/builds/',
+  '.staysfixed/v2/last-check.json',
+  // The lock a run holds while it changes the record. Never anybody's to commit.
+  '.staysfixed/**/*.lock',
 ];
+
+/*
+ * Deliberately NOT ignored: `references.json` and `reference-log.json`. Those are the record
+ * of what this product calls working and which release said so — the one thing here a team
+ * genuinely shares, and the thing a new clone needs in order to compare against anything.
+ */

package/src/guard/name.js

@@ -26,6 +26,9 @@ export const NAME_RULE_EXPLAINER =
 const MAX_LENGTH = 120;
 
 /** Words that start a test name rather than describe the app. */
+/** Words that begin a note to yourself rather than a promise about the product. */
+const PLACEHOLDERS = new Set(['todo', 'fixme', 'wip', 'xxx', 'tbd', 'temp', 'placeholder', 'hack']);
+
 const TEST_SPEAK = new Set([
   'test',
   'tests',
@@ -100,7 +103,7 @@ const VERBS = new Set([
 ]);
 
 /**
- * @typedef {'empty'|'long'|'path'|'id'|'symbols'|'caps'|'identifier'|'testspeak'|'short'} RefusalKind
+ * @typedef {'empty'|'long'|'path'|'id'|'symbols'|'caps'|'identifier'|'testspeak'|'short'|'placeholder'|'not-a-sentence'|'mostly-numbers'|'ticket'} RefusalKind
  */
 
 /**
@@ -194,6 +197,43 @@ function refuse(name) {
     };
   }
 
+  // Three words is a shape, not a sentence. `a b c`, `1 2 3`, `TODO fix later` and
+  // `AC-101 regression check` all cleared every rule above, and each of them is a guard
+  // nobody will understand in six months — which is the entire job of this name.
+  if (PLACEHOLDERS.has(first)) {
+    return {
+      kind: 'placeholder',
+      why: `Starting with "${words[0]}" is a note to yourself, not a promise about the product. Say what should still be true, so the failure reads as that sentence.`,
+    };
+  }
+
+  // A ticket reference is not a behaviour, and this file already says so about "#" and "::".
+  // `AC-101 regression check` cleared every other rule and names nothing a person could act on.
+  const ticket = words.find((w) => /^[A-Za-z]{2,}[-_]\d+$/.test(w));
+  if (ticket) {
+    return {
+      kind: 'ticket',
+      why: `"${ticket}" is a ticket reference, not a behaviour. Put it in "link" and say here what should still be true.`,
+    };
+  }
+
+  const realWords = words.filter((w) => /[A-Za-z]{4,}/.test(w));
+  if (realWords.length < 2) {
+    return {
+      kind: 'not-a-sentence',
+      why: 'That does not read as a sentence about the product — there are almost no words in it. Write what should still be true, in the words you would say out loud, like "the sidebar still collapses".',
+    };
+  }
+
+  const letters = (text.match(/[A-Za-z]/g) ?? []).length;
+  const digits = (text.match(/\d/g) ?? []).length;
+  if (digits > letters) {
+    return {
+      kind: 'mostly-numbers',
+      why: 'That is mostly numbers. A guard name is the sentence somebody reads when it fails, so put the ticket number in "link" and say the behaviour here.',
+    };
+  }
+
   return null;
 }
 

package/src/guard/run.js

@@ -28,6 +28,7 @@ const FRESH_KEY = 'fresh';
 /**
  * @typedef {import('../types.js').GuardResult & {
  *   retriedToPass?: boolean,
+ *   assertedNothing?: boolean,
  *   checks?: import('../types.js').CheckStep[],
  * }} GuardRunResult
  */
@@ -136,10 +137,22 @@ export async function runGuards(project, app, guards, opts = {}) {
       if (opts.signal?.aborted) break;
     }
 
+    // A guard that asserted NOTHING has not held. It cannot hold, and it cannot fail — it is
+    // a name over an empty room. Measured on 2026-08-30: a guard called "the checkout total
+    // is never charged twice", whose `run()` was an empty function, came back as
+    // "ok ... still holds". That is a false all-clear wearing the friendliest face this tool
+    // has, and it would go on saying it every day for ever. The whole promise here is one
+    // plain-English rule per bug somebody already had; a rule that checks nothing is worse
+    // than no rule, because somebody believes it.
+    // Its OWN questions, not the runner's. Every guard gets a "fresh start" step from this
+    // file whether it asks anything or not, so counting the whole list would always find one.
+    const asked = checks.filter((c) => c.key !== FRESH_KEY && !String(c.key ?? '').endsWith(`-${FRESH_KEY}`));
+    const assertedNothing = outcome.ok && asked.length === 0;
+
     /** @type {GuardRunResult} */
     const result = {
       name: guard.name,
-      status: outcome.ok ? 'passed' : 'failed',
+      status: outcome.ok && !assertedNothing ? 'passed' : 'failed',
       file: guard.file,
       because: guard.because,
       durationMs: Date.now() - startedAt,
@@ -147,7 +160,13 @@ export async function runGuards(project, app, guards, opts = {}) {
     };
     if (checks.length > 0) result.checks = checks;
 
-    if (outcome.ok) {
+    if (assertedNothing) {
+      result.assertedNothing = true;
+      result.message =
+        `This guard checked nothing. Its \`run()\` finished without asking a single question, so it cannot fail ` +
+        `and it is not protecting anything — it would report "still holds" every day for ever. ` +
+        `Give it at least one \`expect(...)\`. ${guard.because ? `What it is meant to protect: ${guard.because}` : ''}`.trim();
+    } else if (outcome.ok) {
       // Passing only on the second go is not passing. The flake register picks
       // this up and condemns the guard, because a guard nobody trusts is worse
       // than no guard: people learn to re-run it until it goes green.