clearotron 0.3.0-beta.1 → 0.3.0-beta.2

package/scripts/plain-language-rules.mjs

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// plain-language-rules.mjs — the line rules a release note and the assembled changelog are both held to.
+//
+// ONE LIST, TWO READERS. `release-notes-lint.mjs` reads each note on the pull request that adds it, and
+// `changelog-plain-language.mjs` reads the assembled changelog for `release-version.mjs` after the merge.
+// They held two lists, and the release's refused any two words joined by a slash as a path, where the
+// lint's refused only a path into our tree. So a note CI passed turned main's Release red after it merged:
+// "a yes/no question", 2026-09-10. Every line rule both of them apply lives here, and a test feeds the
+// same notes to both.
+//
+// THE PATH RULE IS THE LINT'S, the narrow one, because that is the one ruled on (2026-09-05): what a reader
+// types or opens is allowed, our tree is not, and ordinary prose with a slash in it is not a path.
+import { readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// The four the issue names, plus the two spellings each of the -ise/-ize pair it names once. A word
+// list is checked whole: "implementation" is jargon, "implement" inside "implemented" is the same word,
+// but "complement" is not, which is why this is a boundary match and not a substring one.
+export const BANNED_WORDS = [
+  "refactor", "refactors", "refactored", "refactoring",
+  "implement", "implements", "implemented", "implementing", "implementation", "implementations",
+  "leverage", "leverages", "leveraged", "leveraging",
+  "optimise", "optimises", "optimised", "optimising", "optimisation",
+  "optimize", "optimizes", "optimized", "optimizing", "optimization",
+  "utilise", "utilises", "utilised", "utilising", "utilisation",
+  "utilize", "utilizes", "utilized", "utilizing", "utilization",
+];
+
+// A FILE NAME is the thing a reader cannot act on: they do not have the tree open. Matched by
+// extension, because a bare word with a dot in it is how every file name in this repository reads.
+const FILE_NAME_RE = /\b[\w.-]+\.(mjs|js|cjs|ts|tsx|jsx|json|yml|yaml|md|sh|txt)\b/g;
+// A FUNCTION NAME, in the two shapes this tree writes them: a call, and a bare camelCase identifier.
+const FUNCTION_RE = /\b[a-z][A-Za-z0-9_]*\(\)|\b[a-z]+[A-Z][A-Za-z0-9]*\b/g;
+// A candidate PATH: slash-joined segments, which may open with `~`, `/`, `./` or `../`. Whether it IS one
+// is decided below, by whose it is.
+const PATH_TOKEN_RE = /(?:^|[\s`(])((?:~|\.{1,2})?\/?[\w.~-]+(?:\/[\w.~-]+)+\/?)/g;
+const WORD_RE = new RegExp(`\\b(${BANNED_WORDS.join("|")})\\b`, "gi");
+
+/**
+ * The repository's own top-level source directories.
+ *
+ * A path whose first segment is one of these is a SOURCE-TREE path — `driver/test/…`, `scripts/…` — and
+ * means nothing to somebody who has never opened this repository. A path that starts at the reader's own
+ * home does not: `~/.config/clearotron/` is where THEIR settings are, and telling them is the note's job.
+ * Ruling 2026-09-05, narrowing the contract's flat ban on "file paths": what a reader types or
+ * opens is allowed; our tree is not.
+ *
+ * Derived from the tree rather than typed, so a directory added next month is covered without anybody
+ * remembering to add it here.
+ */
+export function sourceDirectories(root = ROOT) {
+  return new Set(readdirSync(root, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith(".") && d.name !== "node_modules")
+    .map((d) => d.name));
+}
+
+/** Everything the user documentation shows a reader, as one blob, for "is this documented" questions. */
+export function userDocs(root = ROOT) {
+  return readdirSync(root)
+    .filter((n) => n.endsWith(".md"))
+    .map((n) => readFileSync(join(root, n), "utf8"))
+    .join("\n");
+}
+
+/**
+ * Every line rule `raw` breaks, as `{kind, match}`, where `kind` is "jargon word", "file name", "path" or
+ * "function name". PURE apart from the defaults, which read the tree; callers pass them once per run.
+ *
+ * Code spans are exempt from the word, file-name and function-name rules: a line that says
+ * `` `clearotron framework <your-framework.md>` `` is telling a reader what to type, with a name of their
+ * own in it. A path is judged wherever it sits, by whose it is: `~/.config/clearotron/` in a code span is
+ * the reader's, and `driver/engine` is ours.
+ */
+export function lineFindings(raw, { sourceDirs = sourceDirectories(), docs = userDocs() } = {}) {
+  const out = [];
+  const spanless = String(raw).replace(/`[^`]*`/g, (m) => " ".repeat(m.length));
+  for (const m of spanless.matchAll(WORD_RE)) out.push({ kind: "jargon word", match: m[0] });
+  for (const m of spanless.matchAll(FILE_NAME_RE)) out.push({ kind: "file name", match: m[0] });
+  // A path, judged by WHOSE it is. The reader's own — `~/.config/clearotron/` — is the note's job to
+  // give them. Ours is not, and "ours" is wider than this repository's directory names: an absolute
+  // path into a server's filesystem is our deployment, not their machine.
+  //
+  // WHAT COUNTS AS A PATH AT ALL is deliberately narrow, because `and/or` is not one. A token qualifies
+  // when it opens with `~`, `/`, `./` or `../`, when its first segment is one of our own directories,
+  // or when a segment carries a dot. Ordinary prose with a slash in it does not.
+  for (const m of String(raw).matchAll(PATH_TOKEN_RE)) {
+    const path = m[1];
+    if (/^https?:/.test(path)) continue;
+    const segments = path.replace(/^[~./]+/, "").split("/").filter(Boolean);
+    const looksLikePath = /^[~./]/.test(path) || sourceDirs.has(segments[0]) || segments.some((x) => x.includes("."));
+    if (!looksLikePath) continue;
+    if (path.startsWith("~")) continue;                       // the reader's own home
+    if (docs.includes(path)) continue;                        // the user documentation shows it
+    out.push({ kind: "path", match: path });
+  }
+  for (const m of spanless.matchAll(FUNCTION_RE)) out.push({ kind: "function name", match: m[0] });
+  return out;
+}

package/scripts/release-note-required.mjs

@@ -52,6 +52,21 @@
 // for two changes is no evidence they are the right two — and it would push people to write filler to
 // reach a number, which is the failure this repository has already paid for once. The remaining half is
 // a person reading the diff and asking what a lawyer would want told.
+//
+// ── A DECLINATION ANSWERS FOR ITS OWN COMMIT, NOT FOR THE RANGE ──────────────────────────────────────
+//
+// This read one `Release-note: none` anywhere in the range as the answer for all of it, so a pack of
+// fifteen commits, fourteen internal and each honestly declining, carried the fifteenth, the one a client
+// would notice, through with no note. Measured on three packs merged 2026-09-09 and 2026-09-10: twelve
+// client-visible changes reached main that way. So the question is asked per COMMIT. A commit that ships
+// code is answered by a note the range adds, or by its own `Release-note: none` with its own reason. A
+// declination written by one commit says nothing about another.
+//
+// A `Release-note:` LINE WITH A SENTENCE IN IT IS REFUSED, unless the same commit adds a note. Every one of
+// the twelve was written by somebody who believed they had written a release note, and none of them had:
+// the releases page is built from `.changeset/*.md`, and a line in a commit message reaches no reader. A
+// line may instead NAME the note that answers for it, `Release-note: .changeset/<name>.md`, and that is read
+// as an answer, provided the range adds that note.
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -60,7 +75,9 @@ import { fileURLToPath } from "node:url";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
 /** The declaration a commit makes when the change genuinely has nothing to tell a reader. */
-export const NO_NOTE = /^\s*Release-note:\s*none\b\s*[—:-]?\s*(?<reason>.*\S)?\s*$/im;
+// Horizontal space only. `\s` crosses a line break, so a bare `none` with any line after it, a trailer or
+// another paragraph, read that line as its reason and passed as a declared decision.
+export const NO_NOTE = /^[ \t]*Release-note:[ \t]*none\b[ \t]*[—:.-]?[ \t]*(?<reason>.*\S)?[ \t]*$/im;
 
 /**
  * Does this path ship, per the package's own `files` list?
@@ -108,6 +125,65 @@ function matches(path, glob) {
 /** Paths that ship as code but say nothing to a reader on their own. */
 export const NEVER_A_NOTE = [/(^|\/)CHANGELOG\.md$/, /(^|\/)package(-lock)?\.json$/, /^\.changeset\//];
 
+/** Every `Release-note:` line in a message, as its value. */
+const NOTE_LINE = /^\s*Release-note:[ \t]*(?<value>.*?)[ \t]*$/gim;
+/** A note named in a `Release-note:` line: `.changeset/<name>.md`, or the bare `<name>.md`. */
+const NAMED_NOTE = /^(?:\.changeset\/)?(?<name>[\w.-]+\.md)$/;
+
+const isNotePath = (p) => p.startsWith(".changeset/") && p.endsWith(".md") && !p.endsWith("README.md");
+const shipped = (paths, files) => paths.filter((p) => !NEVER_A_NOTE.some((re) => re.test(p)) && shipsCode(p, files));
+
+// A NOTE COUNTS WHEN ITS COMMIT ADDS IT AND THE HEAD STILL HAS IT. A commit's paths come from `diff-tree`,
+// which lists what it deletes and edits beside what it adds. Read as notes, a range whose only note was
+// one it DELETED answered for every code commit in it, and a commit that edited another change's note was
+// taken as carrying its own. Neither reaches a reader of this range: the release assembles the notes the
+// head carries, and an edited note still describes the change that wrote it. Found in review, 2026-09-10,
+// by driving both shapes; the range-wide rule this replaced had the same gap.
+/**
+ * PURE. What each commit in a range owes, decided per commit (see the header).
+ *
+ * @param {object} o
+ * @param {Array<{sha:string, subject:string, message:string, paths:string[], added?:string[]}>} o.commits  non-merge,
+ *   oldest first; `added` is the paths the commit adds, when the caller read them
+ * @param {string[]} o.files  the package's own `files` list
+ * @param {string[]|null} [o.atHead]  every path the head carries under `.changeset/`, when the caller read it
+ * @returns {{visible:string[], notes:string[], declined:Array<{sha:string, subject:string, reason:string}>,
+ *   owed:Array<{sha:string, subject:string, why:"no-note"|"prose"|"bare-none"|"names-a-missing-note", paths?:string[], text?:string}>}}
+ */
+export function commitVerdicts({ commits = [], files = [], atHead = null } = {}) {
+  // `added` and `atHead` are what the command reads from git; a caller that passes neither keeps the older
+  // reading of every changed path, which is what a pure table of paths means.
+  const present = atHead ? new Set(atHead) : null;
+  const notesOf = (c) => (c.added ?? c.paths).filter((p) => isNotePath(p) && (!present || present.has(p)));
+  const notes = [...new Set(commits.flatMap(notesOf))];
+  const noteNames = new Set(notes.map((p) => p.split("/").pop()));
+  const visible = [...new Set(commits.flatMap((c) => shipped(c.paths, files)))];
+  const declined = [], owed = [];
+  for (const c of commits) {
+    const ships = shipped(c.paths, files);
+    if (!ships.length) continue;                              // nothing a reader could see in this commit
+    const addsNote = notesOf(c).length > 0;
+    const values = [...String(c.message ?? "").matchAll(NOTE_LINE)].map((m) => m.groups.value);
+    const named = values.map((v) => NAMED_NOTE.exec(v)?.groups.name).filter(Boolean);
+    const prose = values.filter((v) => !/^none\b/i.test(v) && !NAMED_NOTE.test(v));
+    const at = { sha: c.sha, subject: c.subject };
+    if (prose.length && !addsNote) { owed.push({ ...at, why: "prose", text: prose[0] }); continue; }
+    const none = NO_NOTE.exec(String(c.message ?? ""));
+    if (none) {
+      const reason = none.groups?.reason;
+      if (reason) declined.push({ ...at, reason }); else owed.push({ ...at, why: "bare-none" });
+      continue;
+    }
+    if (addsNote) continue;                                   // it carries its own note
+    const missing = named.filter((n) => !noteNames.has(n));
+    if (missing.length) { owed.push({ ...at, why: "names-a-missing-note", text: missing[0] }); continue; }
+    if (named.length) continue;                               // it names a note the range adds
+    if (notes.length) continue;                               // a note in the range answers for it
+    owed.push({ ...at, why: "no-note", paths: ships });
+  }
+  return { visible, notes, declined, owed };
+}
+
 const argAfter = (flag) => {
   const i = process.argv.indexOf(flag);
   return i === -1 ? null : process.argv[i + 1];
@@ -124,10 +200,26 @@ function main() {
   // have failed, and would have reported the acceptance met for the life of the branch.
   const head = argAfter("--head") || "HEAD";
   const git = (...a) => execFileSync("git", a, { encoding: "utf8", maxBuffer: 1 << 28 });
-  let changed, log;
+  let changed, commits, atHead;
   try {
     changed = git("diff", "--name-only", `${base}...${head}`).split("\n").filter(Boolean);
-    log = git("log", "--format=%B", `${base}..${head}`);
+    // THE BRANCH'S OWN COMMITS. On a pull request the range can reach commits main already carries, from
+    // main merged into the branch; each of those was asked when it merged, so it is not asked again here.
+    // Only when `--head` is not given: a named range is a replay, and asks about exactly what it names.
+    let exclude = [];
+    if (head === "HEAD") {
+      try { git("rev-parse", "--verify", "-q", "origin/main^{commit}"); exclude = ["--not", "origin/main"]; }
+      catch { /* no origin/main in this clone: the range as given */ }
+    }
+    const shas = git("rev-list", "--no-merges", "--reverse", `${base}..${head}`, ...exclude).split("\n").filter(Boolean);
+    commits = shas.map((sha) => ({
+      sha,
+      subject: git("log", "-1", "--format=%s", sha).trim(),
+      message: git("log", "-1", "--format=%B", sha),
+      paths: git("diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha).split("\n").filter(Boolean),
+      added: git("diff-tree", "--no-commit-id", "--name-only", "-r", "--root", "--diff-filter=A", sha).split("\n").filter(Boolean),
+    }));
+    atHead = git("ls-tree", "-r", "--name-only", head, "--", ".changeset/").split("\n").filter(Boolean);
   } catch (e) {
     // COULD NOT LOOK, never a pass — an unresolvable base is the shape this repository cares about.
     console.error(`release-note-required: cannot read the range against ${base}: ${e.message.split("\n")[0]}`);
@@ -139,33 +231,35 @@ function main() {
   catch (e) { console.error(`release-note-required: cannot read the shipped file list: ${e.message}`); process.exit(2); }
   if (!files.length) { console.error("release-note-required: package.json names no shipped files, so this cannot look"); process.exit(2); }
 
-  const visible = changed.filter((p) => !NEVER_A_NOTE.some((re) => re.test(p)) && shipsCode(p, files));
-  const notes = changed.filter((p) => p.startsWith(".changeset/") && p.endsWith(".md") && !p.endsWith("README.md"));
-  const declined = NO_NOTE.exec(log);
-
+  const { visible, notes, declined, owed } = commitVerdicts({ commits, files, atHead });
   console.log(`release-note-required: ${changed.length} changed file(s) against ${base}`
     + `${head === "HEAD" ? "" : ` (head ${head})`}; `
-    + `${visible.length} ship as code; ${notes.length} release note(s) in the range`);
+    + `${visible.length} ship as code; ${notes.length} release note(s) in the range; ${commits.length} commit(s) read`);
+  // PER COMMIT, SAID AS PER COMMIT. "no note, declared on purpose" read as a verdict on the range, and beside
+  // a range that carries a note it told a reader skimming the output that none went out. Found in review.
+  for (const d of declined) console.log(`  ${d.sha.slice(0, 7)} declines a note of its own, on purpose: ${d.reason}`);
+  if (!owed.length) return;
 
-  if (!visible.length) return;                              // nothing a reader could see
-  if (notes.length) return;                                 // asked and answered
-  if (declined) {
-    const reason = declined.groups?.reason;
-    if (!reason) {
-      console.error("\nA commit says `Release-note: none` and gives no reason. The reason is the whole "
-        + "point of the line — it is what a later reader uses to tell a considered decision from a\nskipped step. Write it on the same line.");
-      process.exit(1);
+  console.error(`\n${owed.length} commit(s) that ship as code owe a release note:\n`);
+  for (const o of owed) {
+    console.error(`  ${o.sha.slice(0, 7)} ${o.subject}`);
+    if (o.why === "no-note") {
+      for (const p of o.paths.slice(0, 6)) console.error(`      ${p}`);
+      if (o.paths.length > 6) console.error(`      … and ${o.paths.length - 6} more`);
+      console.error("      ships as code, this range adds no release note, and this commit does not decline one.");
+    } else if (o.why === "prose") {
+      console.error(`      says "Release-note: ${o.text.slice(0, 100)}". A sentence in a commit message reaches no`
+        + "\n      reader: the releases page is written from .changeset/*.md. Put it in a note, or decline here.");
+    } else if (o.why === "bare-none") {
+      console.error("      says `Release-note: none` and gives no reason. The reason is the whole point of the"
+        + "\n      line — it is what a later reader uses to tell a considered decision from a skipped step.");
+    } else {
+      console.error(`      names ${o.text} as its note, and this range adds no note by that name.`);
     }
-    console.log(`  no note, declared on purpose: ${reason}`);
-    return;
   }
-
-  console.error(`\n${visible.length} file(s) that ship as code changed, and this range adds no release note:\n`);
-  for (const p of visible.slice(0, 12)) console.error(`  ${p}`);
-  if (visible.length > 12) console.error(`  … and ${visible.length - 12} more`);
   console.error("\nSomebody installing Clearotron reads the releases page to decide whether to upgrade. Add a"
-    + "\nnote — `npx changeset`, one plain sentence about what is different for them — or, if this change"
-    + "\ngenuinely has nothing to tell them, say so in a commit message:"
+    + "\nnote — `npx changeset`, one plain sentence about what is different for them — or, if a commit"
+    + "\ngenuinely has nothing to tell them, say so in THAT commit's message:"
     + "\n\n    Release-note: none — <why a reader would see no difference>"
     + "\n\nThe contract and its examples are in .changeset/README.md.");
   process.exit(1);

package/scripts/release-notes-lint.mjs

@@ -21,6 +21,7 @@ import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+import { lineFindings, sourceDirectories, userDocs } from "./plain-language-rules.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -44,23 +45,17 @@ export const INTERNAL_WORDS = [
 /** Said instead of saying what happens. */
 export const EMPTY_PHRASES = ["now correctly", "as expected", "properly"];
 
-/**
- * The repository's own top-level source directories.
- *
- * A path whose first segment is one of these is a SOURCE-TREE path — `driver/test/…`, `scripts/…` — and
- * means nothing to somebody who has never opened this repository. A path that starts at the reader's own
- * home does not: `~/.config/clearotron/` is where THEIR settings are, and telling them is the note's job.
- * Ruling 2026-09-05, narrowing the contract's flat ban on "file paths": what a reader types or
- * opens is allowed; our tree is not.
- *
- * Derived from the tree rather than typed, so a directory added next month is covered without anybody
- * remembering to add it here.
- */
-export function sourceDirectories(root = ROOT) {
-  return new Set(readdirSync(root, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && !d.name.startsWith(".") && d.name !== "node_modules")
-    .map((d) => d.name));
-}
+// `sourceDirectories` moved to plain-language-rules.mjs with the path rule that reads it, and is
+// re-exported here, as `userDocs` is below, for the callers that import them from this file.
+export { sourceDirectories, userDocs } from "./plain-language-rules.mjs";
+
+/** What each shared line rule says to a note's author (see plain-language-rules.mjs). */
+const LINE_RULE = {
+  "file name": "a file name means nothing to somebody who has never opened this repository",
+  "path": "a file path that is ours rather than the reader's means nothing to somebody who has never opened this repository",
+  "jargon word": "the changelog refuses this word — say what changed for the reader instead",
+  "function name": "a function name means nothing to somebody who has never opened this repository",
+};
 
 /** Every command-line flag a ROOT DOCUMENT shows a user. The contract bans the ones that are not. */
 export function documentedFlags(root = ROOT) {
@@ -71,14 +66,6 @@ export function documentedFlags(root = ROOT) {
   return out;
 }
 
-/** Everything the user documentation shows a reader, as one blob, for "is this documented" questions. */
-export function userDocs(root = ROOT) {
-  return readdirSync(root)
-    .filter((n) => n.endsWith(".md"))
-    .map((n) => readFileSync(join(root, n), "utf8"))
-    .join("\n");
-}
-
 /**
  * Every package name `changeset version` will accept, read off the workspace list.
  *
@@ -185,26 +172,18 @@ export function findings(text, {
 
     if (/#\d+/.test(line)) add(i, "a reader has no issue tracker to look a number up in", /#\d+/.exec(line)[0]);
     if (/\btracker issue\b/i.test(line)) add(i, "a reader has no issue tracker to look a number up in", "tracker issue");
+    // A MODULE NAME OF OURS IS REFUSED EVEN IN A CODE SPAN here, which is stricter than the release: a
+    // note may show a reader a command to type, but never one of our own files to type it on.
+    const ours = new Set();
     for (const m of line.matchAll(/\b[\w.-]+\.(mjs|ts|tsx|json|yml|yaml)\b/g)) {
-      add(i, "a file name means nothing to somebody who has never opened this repository", m[0]);
+      ours.add(m[0]);
+      add(i, LINE_RULE["file name"], m[0]);
     }
-    // A path, judged by WHOSE it is. The reader's own — `~/.config/clearotron/` — is the note's job to
-    // give them. Ours is not, and "ours" is wider than this repository's directory names: an absolute
-    // path into a server's filesystem is our deployment, not their machine.
-    //
-    // WHAT COUNTS AS A PATH AT ALL is deliberately narrow, because `and/or` is not one. A token qualifies
-    // when it opens with `~`, `/`, `./` or `../`, when its first segment is one of our own directories,
-    // or when a segment carries a dot. Ordinary prose with a slash in it does not.
-    for (const m of line.matchAll(/(?:^|[\s`(])((?:~|\.{1,2})?\/?[\w.~-]+(?:\/[\w.~-]+)+\/?)/g)) {
-      const path = m[1];
-      if (/^https?:/.test(path)) continue;
-      const segments = path.replace(/^[~./]+/, "").split("/").filter(Boolean);
-      const looksLikePath = /^[~./]/.test(path) || sourceDirs.has(segments[0]) || segments.some((x) => x.includes("."));
-      if (!looksLikePath) continue;
-      if (path.startsWith("~")) continue;                       // the reader's own home
-      if (docs.includes(path)) continue;                        // the user documentation shows it
-      add(i, "a file path that is ours rather than the reader's means nothing to somebody who has never "
-        + "opened this repository", path);
+    // THE LINE RULES THE RELEASE HOLDS THE CHANGELOG TO, applied to the note that will become it: file
+    // names, paths into our tree, jargon and function names, from one list (plain-language-rules.mjs).
+    for (const f of lineFindings(line, { sourceDirs, docs })) {
+      if (f.kind === "file name" && ours.has(f.match)) continue;   // already refused just above
+      add(i, LINE_RULE[f.kind], f.match);
     }
     for (const m of line.matchAll(/--[a-z][a-z0-9-]+/g)) {
       if (!flags.has(m[0])) add(i, "a flag the user documentation never shows is a flag the reader cannot use", m[0]);

package/scripts/release-version.mjs

@@ -24,6 +24,7 @@ import { execFileSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { findings, sentences } from "./changelog-plain-language.mjs";
+import { tagsHere } from "./release-cut-decision.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -32,6 +33,30 @@ const GROUP = ["driver", "mcp-server", "portal-ui", "providers/oauth-mcp-bridge"
 export const GROUPS = ["New", "Fixed", "For operators"];
 const readJson = (p) => JSON.parse(readFileSync(p, "utf8"));
 
+/** PURE. Where `version` is already out: tagged in this checkout, published on the registry, both, or neither. */
+export function alreadyOut({ version, tags = [], published = false }) {
+  const where = [];
+  if (tags.includes(`v${version}`)) where.push(`tagged here as v${version}`);
+  if (published === true) where.push("published on the registry");
+  return where;
+}
+
+/**
+ * Whether the registry already carries `name@version`: true, false, or null when it could not be asked.
+ *
+ * npm answers a version it does not have with exit 1 and `E404`, "No match found for version", so that one
+ * failure is the answer no. Any other failure is a failure to look, and the caller refuses on it.
+ */
+export function registryHas(name, version, {
+  run = (args) => execFileSync("npm", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }),
+} = {}) {
+  try {
+    return String(run(["view", `${name}@${version}`, "version"]) ?? "").trim() === version;
+  } catch (e) {
+    return /\bE404\b|No match found for version/.test(`${e?.stderr ?? ""}${e?.message ?? ""}`) ? false : null;
+  }
+}
+
 /** The one version the fixed group now carries — and a refusal if they disagree. */
 export function groupVersion(root = ROOT) {
   const seen = new Map();
@@ -204,6 +229,40 @@ function main() {
 
   run("version", ...args);
   const version = groupVersion();
+
+  // ── A VERSION ALREADY OUT IS REFUSED HERE, BEFORE ANYTHING IS STAMPED ─────────────────────────────
+  //
+  // The pre-release line keeps no record of its last number. `.changeset/pre.json` holds its mode and tag
+  // and nothing else, and a stable release deletes it, so `changeset version` counts again from
+  // package.json. Measured 2026-09-10: entering beta on a tree at 0.2.4 computed 0.3.0-beta.0, which was
+  // already tagged and on the registry. A cut from there would stamp main with it, consume every pending
+  // note, and fail only at publish, leaving both to be unwound by hand. The tags and the registry are the
+  // record, so the number is checked against both, and a failure to read either is a refusal too.
+  const tags = tagsHere();
+  if (!tags.length) {
+    console.error(`release-version: this checkout has no tags, so whether ${version} is already out cannot `
+      + "be read. Refusing rather than stamping a number that may already be published.");
+    process.exitCode = 2;
+    return;
+  }
+  const name = readJson(join(ROOT, "package.json")).name;
+  const published = registryHas(name, version);
+  if (published === null) {
+    console.error(`release-version: the registry could not be asked whether ${name}@${version} exists. `
+      + "Refusing rather than stamping a number that may already be published.");
+    process.exitCode = 2;
+    return;
+  }
+  const out = alreadyOut({ version, tags, published });
+  if (out.length) {
+    console.error(`release-version: this cut computed ${version}, and that version is already out: `
+      + `${out.join(" and ")}. Publishing it would fail after main is stamped and the notes are consumed.\n`
+      + "  The pre-release line keeps no record of its last number: .changeset/pre.json holds only its mode "
+      + "and tag, and a stable release deletes it, so this was counted again from package.json. Put the "
+      + "line back where its last published version left it, then cut again.");
+    process.exitCode = 1;
+    return;
+  }
   const pkgPath = join(ROOT, "package.json");
   const pkg = readJson(pkgPath);
   const was = pkg.version;

package/scripts/revisit-render-check.mjs

@@ -68,6 +68,7 @@ import { spawn } from 'node:child_process'
 import { tmpdir } from 'node:os'
 import { reapOnExit } from '../shared/reap-on-exit.mjs' // — a detached group dies with this script
 import { browserRun } from "../shared/browser-temp-root.mjs";
+import { textDifference } from './text-difference.mjs' // — a text pair that differs says where, not only that
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const DIST = join(HERE, '..', 'portal-ui', 'dist')
@@ -345,8 +346,11 @@ const twice = async (name, enter, expectPath, away = 'Home') => {
   // otherwise sail through a count comparison as "identical".
   say((t1 || '').trim().length > 0, `${name}: visit 1 rendered text`)
   say((t2 || '').trim().length > 0, `${name}: visit 2 rendered text`)
-  say((t2 || '').trim().length > 0 && (t1 || '').trim().length > 0 && t1 === t2,
-    `${name}: the screen renders the same text on both visits`)
+  // On a FAIL this line carries where the two texts first differ and a window of each side, because a red
+  // that does not reproduce leaves nothing else to read. The ok line is unchanged, so two passing runs
+  // still diff to nothing.
+  const sameText = (t2 || '').trim().length > 0 && (t1 || '').trim().length > 0 && t1 === t2
+  say(sameText, `${name}: the screen renders the same text on both visits${sameText ? '' : ` — ${textDifference(t1, t2) ?? 'neither visit rendered any text'}`}`)
 
   // The unmount half. Equal counts mean the listener added on visit 1 was removed when the screen was
   // left, rather than accumulating one per visit.

package/scripts/text-difference.mjs

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+// Where two texts first differ, and a window of each side there, so a check that finds them unequal can
+// say how and not only that.
+//
+// A pair of lengths is not enough: two texts of one length that differ in one word would print alike.
+// Each window is JSON-quoted, so a newline or a trailing space in either shows on the one line printed.
+
+/**
+ * `null` when the texts are equal. Otherwise one line: the offset of the first differing character, both
+ * lengths, and up to `span` characters of each side starting `lead` characters before that offset.
+ */
+export function textDifference(a, b, { span = 48, lead = 16, labels = ['visit 1', 'visit 2'] } = {}) {
+  const x = String(a ?? '')
+  const y = String(b ?? '')
+  if (x === y) return null
+  let at = 0
+  while (at < x.length && at < y.length && x[at] === y[at]) at++
+  const from = Math.max(0, at - lead)
+  const window = (s) => JSON.stringify(`${from > 0 ? '…' : ''}${s.slice(from, from + span)}${from + span < s.length ? '…' : ''}`)
+  return `first differs at character ${at} (lengths ${x.length} and ${y.length}): ${labels[0]} ${window(x)} · ${labels[1]} ${window(y)}`
+}

package/shared/env-local.mjs

@@ -414,7 +414,7 @@ export function activeEnvPath({ repoRoot = REPO_ROOT, home = homedir(), location
  * logged: this file is where the credentials are.
  */
 export function loadEnvLocal({ env = process.env, repoRoot = REPO_ROOT, note = defaultNote,
-                              home = homedir(), location = ENV_LOCAL_LOCATION, file = null } = {}) {
+                              home = homedir(), location = ENV_LOCAL_LOCATION, file = null, demo = false } = {}) {
   // ── `file` NAMES A FILE OUTRIGHT, AND EXISTS BECAUSE A CALLER COULD NOT ────────────────────────────
   //
   // `readEnvFile(path)` in the wizard means "tell me what THIS file holds". It could only ask by handing
@@ -443,6 +443,12 @@ export function loadEnvLocal({ env = process.env, repoRoot = REPO_ROOT, note = d
   const path = file ?? activeEnvPath({ repoRoot, home, location });
   const fromLegacy = path !== inForce;
   if (optedOut(env)) return { path, applied: [], skipped: [], reason: "opted-out" };
+  // A DEMO TAKES NOTHING FROM IT (`isDemoEntry`, below). Said only when there is a file being left
+  // alone, so a reader with a real install can see the demo did not take its settings.
+  if (demo) {
+    if (existsSync(path)) note(`[env-local] not reading ${path}: \`clearotron demo\` runs on its own data and settings, never an install's\n`);
+    return { path, applied: [], skipped: [], reason: "demo" };
+  }
   if (serviceManaged(env)) {
     // Loud ONLY when there is a file to ignore. A service with no .env beside it is the normal case on
     // every box and says nothing; a service that HAS one is somebody's surprise waiting to happen, and
@@ -497,10 +503,27 @@ export function loadEnvLocal({ env = process.env, repoRoot = REPO_ROOT, note = d
 
 function defaultNote(line) { try { process.stderr.write(line); } catch { /* a closed stderr must never fail a run */ } }
 
+/**
+ * Is this process `clearotron demo`'s supervisor, `bin/start.mjs --demo`?
+ *
+ * THE ONE CLI ENTRY THAT MUST NOT READ THE FILE. What `.env` configures is the reader's real install:
+ * its config store, its pool, its grants. 0.3.0-beta.1's demo read it before `--demo` was parsed, so it
+ * served the real store's roster (no demo company, no Generic) and seeded its example reports into the
+ * real archive (measured on a reader's machine, 2026-09-10).
+ *
+ * `bin/clearotron.mjs` and `bin/example.mjs`, the two processes above it, are not CLI entries and read
+ * nothing, so this one is the whole of the gap. Its own children run with CLEAROTRON_NO_ENV_FILE=1.
+ */
+export function isDemoEntry(argv = process.argv, repoRoot = REPO_ROOT) {
+  if (!argv?.[1] || !argv.slice(2).includes("--demo")) return false;
+  const entry = realOrSelf(isAbsolute(argv[1]) ? argv[1] : resolve(process.cwd(), argv[1]));
+  return entry === realOrSelf(join(repoRoot, "bin", "start.mjs"));
+}
+
 // ── the gate ─────────────────────────────────────────────────────────────────────────────────────────
 // ESM caches by resolved URL, so this runs exactly once per process however many entries import it
 // (mcp-server/http-server.mjs imports mcp-server/server.mjs; both are entries).
-export const loaded = isCliEntry(process.argv[1]) ? loadEnvLocal() : null;
+export const loaded = isCliEntry(process.argv[1]) ? loadEnvLocal({ demo: isDemoEntry(process.argv) }) : null;
 
 /**
  * The env file THIS process took its configuration from, or null when it took none.

package/shared/names-in-force.mjs

@@ -171,6 +171,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_TURN_CAP",
   "CLEAROTRON_TURN_LOCK_POLL_MS",
   "CLEAROTRON_UNREACHABLE_SENIOR",
+  "CLEAROTRON_UPDATER_STAMP",
   "CLEAROTRON_WALL_RESCUE",
   "CLEAROTRON_WARM_RETRY",
   "CLEAROTRON_WATCH_",

package/shared/reap-on-exit.mjs

@@ -59,26 +59,39 @@ const groups = new Set();
 const dirs = new Set();
 let installed = false;
 
-function reapAll() {
-  for (const pid of groups) {
-    // The GROUP first — that is what detaching bought, and it is what reaches the child's children.
-    // Falling back to the bare pid keeps a non-detached caller honest rather than silently reaping
-    // nothing; both are best-effort, because a reaper that throws on the way out of a crashing script
-    // replaces one problem with a worse one.
-    try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ } }
-  }
-  groups.clear();
+// The GROUP first — that is what detaching bought, and it is what reaches the child's children.
+// Falling back to the bare pid keeps a non-detached caller honest rather than silently reaping
+// nothing; both are best-effort, because a reaper that throws on the way out of a crashing script
+// replaces one problem with a worse one.
+function killGroup(pid) {
+  try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ } }
+}
+function removeDir(dir) {
+  try { rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); } catch { /* a stray temp root is not worth failing an exit over */ }
+}
+
+/**
+ * Signal every watched group, then remove every watched directory — in that order, which is the whole
+ * point of this function (see the note above).
+ *
+ * THE TWO EFFECTS AND THE STATE ARE PARAMETERS so a test can record the order the calls HAPPEN in. The
+ * arm that held this before read the order the lines were written in, and passed on edits that reversed
+ * the effect while keeping the lines: a removal moved into a helper called above the kill, or a second
+ * removal added earlier. The defaults are the real calls and this module's own sets.
+ */
+export function reapAll({ kill = killGroup, remove = removeDir } = {}, state = { groups, dirs }) {
+  for (const pid of state.groups) kill(pid);
+  state.groups.clear();
   // ONLY NOW, with the groups signalled, is the temp root removable. See the note above.
-  for (const dir of dirs) {
-    try { rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); } catch { /* a stray temp root is not worth failing an exit over */ }
-  }
-  dirs.clear();
+  for (const dir of state.dirs) remove(dir);
+  state.dirs.clear();
 }
 
 function install() {
   if (installed) return;
   installed = true;
-  process.on("exit", reapAll);
+  // A wrapper, not the function: "exit" hands its listener the exit code, which reapAll would read as its options.
+  process.on("exit", () => reapAll());
   // 128 + signo is the shell's convention for "died by this signal", and preserving it matters: CI
   // reads the exit code to tell a cancellation from a failure, and a reaper that exits 0 on SIGTERM
   // would turn every cancelled job green.