staysfixed 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -8,6 +8,50 @@ 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.9.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/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/v2/check.js

@@ -1916,6 +1916,18 @@ async function gatherJourneys({ root, config, options }) {
 
   const named =
     options.journeys && !['code', 'config', 'suite'].includes(options.journeys) ? options.journeys : null;
+  // `recorded` is a word this tool knows and `check --help` offers it — it is simply not
+  // wired into a run yet. The MCP surface says exactly that; the command line fell through to
+  // the branch above, treated the word as a FILE PATH, and answered that a file called
+  // "recorded" was missing. The same question has to get the same answer on both.
+  if (options.journeys === 'recorded') {
+    throw new StaysFixedError(
+      'Replaying a recorded session is written and not wired into a run yet, so nothing was checked.',
+      {
+        hint: 'Leave --journeys out to use the steps each adapter reads from your source, pass `suite` to walk your own test suite, or pass the path to a journeys file.',
+      },
+    );
+  }
   if (named) journeys.push(...(await readJourneyFile(path.resolve(root, named))));
 
   // The project's own test suite, when somebody asked for it in those words and never

package/src/v2/init.js

@@ -1579,7 +1579,14 @@ function whatItCovers(readiness) {
   else parts.push('Right now a check here covers nothing in full.');
   if (waiting.length > 0) parts.push(`${plainList(waiting, true)} ${waiting.length === 1 ? 'is' : 'are'} not covered yet, and the list below says exactly what is in the way and who has to do it.`);
   if (notCovered.length > 0) parts.push(`${plainList(notCovered, true)} ${notCovered.length === 1 ? 'is' : 'are'} not checked at all, so a clean result says nothing whatever about ${notCovered.length === 1 ? 'it' : 'them'}.`);
-  if (partly.length === 0 && notCovered.length === 0 && covered.length > 0) parts.push('Nothing is being left out.');
+  // "on this machine", because that is the only thing this sentence knows. It is built from
+  // SURFACES — which kinds of product can be watched here — and says nothing whatever about
+  // how much of this project a run actually walks. Unqualified, it read as a coverage
+  // promise, and `getting-started` tells the agent to repeat it to the person: measured
+  // 2026-08-30 on a project the same run reported as five of six doors never opened.
+  if (partly.length === 0 && notCovered.length === 0 && covered.length > 0) {
+    parts.push('Nothing is being left out on this machine — though how much of the project a run actually walks is a separate question, and every check answers it.');
+  }
 
   // The hole that never closes, named with the language that causes it. "Not covered yet"
   // reads as a job somebody will get to; this one is nobody's job and saying so is the

package/src/v2/mcp/tools.js

@@ -1661,7 +1661,14 @@ function problem(message) {
 function text(v) {
   if (typeof v !== 'string') return null;
   const s = v.trim();
-  return s === '' ? null : s;
+  if (s === '') return null;
+  // Capped, because every one of these is a string an AGENT chose and several of them are
+  // echoed straight back in the reply and then written into the store for ever. A megabyte
+  // of summary came back as a megabyte of tool result and stayed there. Nothing legitimate
+  // here is long: a reason, a finding id, a surface name. Cutting says so out loud rather
+  // than quietly keeping the first part.
+  const MOST = 4000;
+  return s.length <= MOST ? s : `${s.slice(0, MOST)} … (cut here: this was ${s.length} characters, and nothing this tool asks for is that long)`;
 }
 
 /**

package/src/v2/sealed.js

@@ -358,7 +358,13 @@ function readFinding(finding) {
   const differences = finding.differences ?? [];
   for (const d of differences) {
     add(d.path, d.path);
-    add(d.describe, d.path);
+    // NOT `d.describe`. That sentence is the TOOL's, not the product's — it explains what a
+    // channel watches and is the same on every finding that channel ever produces. The API
+    // shape channel's says "a renamed or dropped field shows up on its own", and `dropped`
+    // is a data-loss word, so every API shape change on every project was sealed as losing
+    // data, permanently, and no agent could wave any of it through. A seal has to be decided
+    // by what the PRODUCT said — its addresses, its values, its journey names — never by the
+    // tool's own vocabulary, which no user wrote and nobody can change.
     add(faceOf(d.reference), d.path);
     add(faceOf(d.candidate), d.path);
     add(d.journey, `the ${d.journey} journey`);

package/src/v2/ship.js

@@ -211,10 +211,13 @@ export async function onShip(opts = {}) {
     result.cut = cut.unchanged !== true;
     result.unchanged = cut.unchanged === true;
 
+    const missed = await whatTheCheckMissed(store);
+
     if (cut.unchanged) {
       result.lines = [
         `${product} ${release.describe}`,
         `That build was already what ${product} calls working, so nothing moved and no waivers were retired. Recording a release twice is safe.`,
+        ...(missed ? [missed] : []),
       ];
       result.summary = `${product} ${release.what} was already the reference — nothing changed.`;
       return result;
@@ -228,6 +231,8 @@ export async function onShip(opts = {}) {
       // ran only once, so part of this reference has no steadiness record behind it.
       ...(cut.stability.measuredJourneys < cut.stability.journeys ? [cut.stability.note] : []),
       'Nobody has to approve anything. The next check compares against this.',
+      // Said in the same breath as the good news, exactly as every other surface says it.
+      ...(missed ? [missed] : []),
     ];
     result.summary = cut.summary;
     return result;
@@ -247,6 +252,33 @@ export async function onShip(opts = {}) {
 
 // ---------------------------------------------------------------------------
 // What just shipped?
+/**
+ * What the last check did NOT look at, said here too.
+ *
+ * `ship` is the one command that decides what "working" MEANS from now on, and it printed no
+ * coverage caveat at all — not in the text, not in `--json`. Every other surface says it, in
+ * the same breath as the good news, because a green result on a product with doors nobody has
+ * ever opened is true and is not what it looks like. The command that turns that result into
+ * the standard is the last place that should stay quiet about it.
+ *
+ * @param {Store} store
+ * @returns {Promise<string|null>}
+ */
+async function whatTheCheckMissed(store) {
+  try {
+    const raw = JSON.parse(await fsp.readFile(path.join(store.dir, 'last-check.json'), 'utf8'));
+    const coverage = raw?.result?.coverage ?? null;
+    if (!coverage) return null;
+    const { whatWasNotChecked } = await import('./check.js');
+    const said = whatWasNotChecked(coverage);
+    return typeof said === 'string' && said.trim() ? said.trim() : null;
+  } catch {
+    // No record, or unreadable. Saying nothing is right here — inventing a caveat would be
+    // its own kind of lie.
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 
 /**