clearotron 0.2.3 → 0.2.4

package/shared/reference-guard-classes.mjs

@@ -0,0 +1,351 @@
+// 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
+//
+// WHAT A PUBLIC TREE MUST NOT ACQUIRE, AS ONE TABLE.
+//
+// `scripts/added-reference-check.mjs` refuses these in a diff, so a pull request cannot add one. The
+// floor beside `driver/test/fixtures/public-residue-backlog.json` counts what is already here, so the
+// standing population can only fall. Two readers, one table: a class the diff guard refuses and the
+// census does not count is a class whose number nobody can act on, and the reverse is a number nobody
+// can hold.
+//
+// ── WHY THE TABLE CAN BE PUBLISHED AT ALL ────────────────────────────────────────────────────────
+//
+// A guard is a list of what it looks for, and this file ships in the tree it protects. So the test for
+// every entry is whether SPELLING IT DISCLOSES ANYTHING. Generic account names, role words and the
+// repository's own retired names disclose nobody. A person's name and the names given to working
+// sessions do, and they are not here: those stay in the private table that
+// `shared/identifier-sentinels.mjs` describes, reached through `CLEAROTRON_IDENTIFIER_BLOCKLIST`, and
+// this file does not restate them under another heading.
+//
+// That split is a real limit and it is stated rather than papered over: public CI cannot refuse a name
+// it is not allowed to know. What it can refuse is every class below, which is what let the last set
+// through.
+//
+// QUOTING A BAD LINE IS STILL WRITING IT, and there is no exemption for backticks. Both comments in
+// this file that once showed a banned token as an example were refused by the guard they describe, and
+// the answer was to reword them rather than to excuse a span. An exemption for quoted text would be a
+// hole in exactly the classes that need none: an account name inside backticks is as published as one
+// outside them, and any author could quote their way past. Where a bad input genuinely has to be
+// SHOWN, it goes in a test arm as a string literal — which this guard does not read, by the same rule
+// that keeps it away from CSS and composite keys.
+//
+// ── WHAT IS DELIBERATELY NOT HERE ────────────────────────────────────────────────────────────────
+//
+// PRODUCT VOCABULARY. `lane`, `round`, `box`, `ruling`, `prelim`, `knockout`, `seat` and `jx` are this
+// product's own nouns. A guard refusing them fires thousands of times, and a guard that fires on
+// correct prose is one whose next reader deletes from the workflow.
+//
+// `deploy` IS A SKILL NAME AND IS NOT BANNED, for the same reason. It is an ordinary English word and a
+// paragraph about deploying would be refused line by line.
+//
+// `clawdi` IS NOT BANNED, and this one was measured rather than reasoned. It reads like an internal
+// name and it is the product's own default agent id: `CLEAROTRON_DEFAULT_AGENT=clawdi` is in
+// INSTALL.md, in the configuration reference and in the operations runbook, and it is a path segment in
+// every run directory. 49 lines carry it in that sense and none carries it as a reference to the other
+// product, which is the class that would have been worth refusing. Banning it would refuse the install
+// instructions a stranger reads first.
+
+import { execFileSync } from "node:child_process";
+import { CUT_RECORD_PRESENT, isWithheld } from "./withheld-paths-access.mjs";
+
+// ── A COLOUR IS NOT A CITATION, AND ONE PROPERTY LIST SETTLES BOTH READINGS ──────────────────────
+//
+// A three-digit hex colour and a three-digit reference are the same characters, and the digits cannot
+// tell you which one you are looking at. The SITE settles it: a value whose property is a colour is a
+// colour.
+//
+// TWO RULES FROM ONE LIST, and they are not interchangeable — this is the split
+// `shared/identifier-scan.mjs` had to learn after a line-scoped exemption quietly cleared every other
+// name on the line beside the one that earned it.
+//
+//   TOKEN-SCOPED (`COLOUR_PROPERTY`) — anchored at the end of the text BEFORE a token, so it exempts
+//   that token and nothing else. This is what the diff guard uses: a stylesheet line may hold a colour
+//   and a citation, and only the colour is excused.
+//
+//   LINE-SCOPED (`COLOUR_SITE`) — true anywhere on the line. Correct only where the whole line is a
+//   declaration and there is nothing else on it to miss, which is how
+//   `driver/test/prompt-payload-names-no-tracker-issue.test.mjs` reads a stylesheet.
+//
+// Lifted here from that test so the two stop being separate spellings of one rule.
+const COLOUR_PROPERTIES = "color|background|background-color|border|border-color|fill|stroke|outline|box-shadow|text-shadow";
+
+/** Anchored: true when the text immediately before a token is a colour property awaiting its value. */
+export const COLOUR_PROPERTY = new RegExp(`(?:^|[;{\\s(,])(?:${COLOUR_PROPERTIES})\\s*:\\s*$`, "i");
+
+/** Unanchored: true when the line is a colour declaration at all. */
+export const COLOUR_SITE = new RegExp(`(?:^|[;{\\s])(?:${COLOUR_PROPERTIES})\\s*:`, "i");
+
+const HEX_COLOUR = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/g;
+
+/** Strip hex colours, so what remains is only tokens that could be a reference. */
+export const withoutColourValues = (line) => String(line).replace(HEX_COLOUR, (m, offset, whole) => {
+  if (/[a-fA-F]/.test(m.slice(1))) return "";                              // letters ⇒ not a decimal number
+  return COLOUR_PROPERTY.test(whole.slice(0, offset)) ? "" : m;            // all digits ⇒ the property decides
+});
+
+/** Strip the spans where a `#NNN` is an address rather than a reference. */
+export const withoutLinkTargets = (line) => String(line)
+  .replace(/\]\([^)]*\)/g, "]()")                 // markdown link targets, anchors included
+  .replace(/https?:\/\/\S+/g, "")                  // bare URLs and their fragments
+  .replace(/<[^>]*>/g, "");                        // angle-bracket autolinks
+
+// A `#` COMMENT IS A COMMENT WHEREVER THE FILE FORMAT SAYS SO, not only in YAML. Extensionless is
+// deliberate: a systemd unit or a dotfile often has no extension worth matching, so the KNOWN
+// `#`-comment names are listed and everything else keeps the source rule.
+const HASH_COMMENT = /(^|\/)(\.env[^/]*|[^/]*\.(ya?ml|sh|bash|service|timer|path|socket|conf|ini|toml|properties)|Dockerfile[^/]*|Makefile|\.gitignore|\.gitattributes)$/;
+
+/** Is this line one the guard reads at all? Comments in source, everything in markdown. */
+export const isProse = (path, line) => {
+  if (/\.mde?$/.test(path) || path.endsWith(".md")) return true;
+  const t = String(line).trim();
+  if (HASH_COMMENT.test(path)) return t.startsWith("#");
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+};
+
+// ── THE TWO TREES THIS GUARD DOES NOT READ ──────────────────────────────────────────────────────
+//
+// `demo/**` is recorded public-register data and the run artifacts replayed from it. The names in it
+// are real trademark owners on a real register, which is what the demo is for; a guard reading it
+// would refuse the product's own worked example.
+//
+// `driver/skills/**` is the engine's instruction text, and it has its own stricter guard next door in
+// `driver/test/prompt-payload-names-no-tracker-issue.test.mjs` — which refuses a citation there in any
+// form, prose line or not. Reading it here as well would put one tree under two rules that disagree
+// about what a comment is.
+const UNREAD_TREES = [/^demo\//, /^driver\/skills\//];
+
+/** Does the guard read this path at all? */
+export const isScannable = (path) => !UNREAD_TREES.some((re) => re.test(path));
+
+// ── THE CLASSES ─────────────────────────────────────────────────────────────────────────────────
+//
+// Each is `{ id, pattern, why }`. The id is what the census counts under and what a floor entry names,
+// so it is stable text: renaming one re-mints the fixture and the diff says so.
+//
+// `pattern` carries no `g` flag. A shared `g`-flagged regex carries `lastIndex` between `test` and
+// `exec` calls, so the same instance answers differently on its second use — the kind of defect that
+// shows up as one arm in ten failing. `EVERY_MATCH` below adds the flag for the one operation that
+// needs it, and `String.prototype.matchAll` iterates a clone rather than the original (asserted in
+// driver/test/the-public-residue-is-a-floor.test.mjs, because it is a property of the runtime and not
+// of this file).
+
+/** @type {{id: string, pattern: RegExp, why: string}[]} */
+export const CLASSES = [
+  {
+    id: "bare-reference",
+    pattern: /#[0-9]{3,}/,
+    // THE REMEDY MOVED WITH THE CLASS BELOW. This used to read "write `tracker issue NNN`", which is
+    // now the next entry in this table — a guard telling authors to write the form it refuses two
+    // lines later. The remedy is not another spelling of the address; it is to drop the address.
+    why: "a bare #NNN reference — GitHub links it into whichever repository renders it, which is not "
+      + "the one the number belongs to, and it lives on in public history. Say why the code is as it "
+      + "is; the citation belongs in the commit message or the pull request body.",
+  },
+  {
+    // THE SPELLED FORM WAS THE REMEDY AND IS NOW THE CLASS. `tracker issue NNN` was what this guard
+    // told authors to write instead of `#NNN`, because it carries no `#` and GitHub cannot linkify it.
+    // That was right about the linkifying and wrong about the address: the tree carries the reason for
+    // a decision, never its address, and a reader outside this project cannot open the number either
+    // way. So the citation moves to the commit message and the pull request body, where it belongs,
+    // and the code says why rather than where.
+    id: "spelled-citation",
+    pattern: /\btracker\s+issues?\s+[0-9]+/i,
+    why: "a spelled tracker citation — the reason for a decision belongs in the tree, its address does "
+      + "not. A reader outside this project cannot open the number. Say why the code is as it is; put "
+      + "the citation in the commit message or the pull request body.",
+  },
+  {
+    id: "login",
+    pattern: /\b(?:testuser|azureuser|devuser)[0-9]*\b/i,
+    why: "an account name from the machines this is built on. Say what the account is for — 'the "
+      + "account the timer runs as' — not what it is called.",
+  },
+  {
+    // THE PLACEHOLDER IS THE POINT OF THE NARROW LIST. `/home/you/trademark/pool` is what INSTALL.md
+    // and docs/E2E.md tell a reader to write, and it is the first thing a stranger copies. A
+    // `/home/<anything>/` rule would refuse the install instructions, so the accounts are named.
+    id: "home-path",
+    pattern: /\/home\/(?:testuser|azureuser|devuser|clearotron)[0-9]*\b/i,
+    why: "a home directory on one of the machines this is built on. Use the placeholder the install "
+      + "documentation uses, or name the setting rather than the path.",
+  },
+  {
+    // ── DECLARED HERE, SPELLED ELSEWHERE, AND THE REASON IS THIS ENTRY'S OWN SENTENCE ──────────────
+    //
+    // This class had a pattern naming two private repositories as literals, and it shipped in the tree
+    // it protects — so the guard published exactly what it exists to refuse. Its own `why` says it: a
+    // public tree naming one publishes it, and the name outlives every link to it.
+    //
+    // THE SPLIT AT THE TOP OF THIS FILE ALREADY HAD THE ANSWER and this entry was on the wrong side of
+    // it. A generic account name discloses nobody, which is why the logins are spelled out. A
+    // repository name is not a generic word: it is a unique identifier of a private asset, and it
+    // belongs with the personal names in the private table rather than here.
+    //
+    // FOUND BY A REVIEWER, AND DEMONSTRATED RATHER THAN ARGUED. The private scan refused their review
+    // on its first pass, because reporting the defect meant quoting the pattern. A class whose literals
+    // cannot be discussed in a public review without tripping a guard does not belong in a public file
+    // — which is this file's own no-exemption-for-quoting rule, arriving from the other side.
+    //
+    // WHAT IS LOST, SAID PLAINLY RATHER THAN LEFT AS AN ABSENCE. Commit bodies are covered: the private
+    // merge scan refuses this class today. What this entry would have added is FILE coverage, and
+    // public CI cannot have it without the literals. So the class is declared with no pattern, skipped
+    // here, and populated only where the roster is. A guard that cannot spell what it looks for says so
+    // rather than looking clean.
+    id: "private-repo-name",
+    pattern: null,
+    why: "a private repository name. A public tree naming one publishes it, and the name outlives "
+      + "every link to it. Refused in commit bodies by the private merge scan; not spellable here.",
+  },
+  {
+    // THE FOUR ARE SPELLED OUT RATHER THAN `role-\w+`. `role-shaping` is a real phrase in
+    // driver/portal-service.mjs about what the report does with a party's role, and a prefix rule
+    // refuses it — the first false positive would land on product prose, which is how a guard loses
+    // its `&&`.
+    // AND ONE OF THEM IS A REGISTERED MARK, which matters in this product and nowhere else. The bare
+    // word in the pattern below — the one that is not prefixed `role-` — is banned because 20 files
+    // carry it as our own word for a role, and no current use of it as a mark is in this tree today. But the corpus this product searches is MARKS, and that is
+    // a well-known registered one — so the first false positive here will be a fixture, a worked example
+    // or a doctrine line that names it legitimately. That is the same defect this codebase has met three
+    // times in a different costume: a check that cannot tell a mark from its own vocabulary. When it
+    // arrives, the fix is a site rule that exempts the mark where a mark belongs — not a widened pattern,
+    // and not deleting the class, which would put 20 real leaks back.
+    id: "role-name",
+    pattern: /\brole-(?:dev|e2e|design|overwatch)\b|\boverwatch\b|\bclearance-runs\b/i,
+    why: "our own word for how this is built, not the reader's. Say what was done and how it was "
+      + "verified; a stranger cannot use the organisation chart and should not have to meet it.",
+  },
+  {
+    id: "agent-trailer",
+    // The comment leader is matched so the trailer is recognised at the start of a comment, and
+    // CAPTURED OUT of the report: a reader told that the offending token includes the comment leader
+    // has been handed the syntax around the finding as though it were part of it.
+    pattern: /^[\s*/#]*(Agent:\s*role-\w+)/,
+    why: "the agent trailer, which belongs on private surfaces only. On a public surface the "
+      + "attribution is the commit author and nothing else.",
+  },
+  {
+    // WORSE THAN THE CLASS ABOVE BECAUSE NOBODY READS IT AS PROSE. This one arrives in a template,
+    // survives review by looking like machinery, and a commit message cannot be amended once pushed.
+    // The same class is refused in commit bodies by the merge scan; nothing refused it inside a FILE
+    // until this, and a file is the surface that stays.
+    id: "machine-trailer",
+    pattern: /Co-Authored-By:\s*Claude|Claude-Session:|Generated with \[Claude|claude\.ai\/code\/session/,
+    why: "a machine-written attribution trailer or session link. On a public surface the attribution "
+      + "is the commit author and nothing else.",
+  },
+];
+
+/**
+ * Every class this line offends, as `{ id, token, why }`. Empty when the line is not read, is not
+ * prose, or is clean.
+ *
+ * Colour values and link targets are stripped once, before any class sees the line, so a class cannot
+ * be written in a way that reintroduces either exclusion by accident.
+ */
+// EVERY OCCURRENCE, NOT THE FIRST. This was one-per-class-per-line until the census arm planted two
+// citations on one line and read back 1. For the diff guard the difference is cosmetic — the reader is
+// shown the line either way — but the backlog is a COUNT, and a count that stops at the first hit lets
+// a floored line quietly gain a second one. The permissive half of a gate is the dangerous half.
+const EVERY_MATCH = new Map(CLASSES.filter((c) => c.pattern).map((c) => [c.id, new RegExp(c.pattern.source, c.pattern.flags + "g")]));
+
+export function offendingClasses(path, line) {
+  if (!isScannable(path) || !isProse(path, line)) return [];
+  const text = withoutColourValues(withoutLinkTargets(line));
+  const out = [];
+  for (const c of CLASSES) {
+    // A CLASS WITH NO PATTERN IS ONE THIS TREE CANNOT SPELL, not one with nothing to find. It stays in
+    // the table so the census keeps its column and a reader meets the limit where the rule is, rather
+    // than inferring it from an absence.
+    const re = EVERY_MATCH.get(c.id);
+    if (!re) continue;
+    // A capture group, where a class has one, is the offending text with its surroundings dropped.
+    for (const m of text.matchAll(re)) out.push({ id: c.id, token: m[1] ?? m[0], why: c.why });
+  }
+  return out;
+}
+
+/**
+ * The standing population, per file, as `{ total, files: { path: number[] } }` — one count per class,
+ * in `CLASSES` order, for every file carrying at least one.
+ *
+ * A file with no hit is absent rather than zero-filled, so the fixture shrinks as the tree is repaired
+ * instead of recording a growing list of clean files.
+ *
+ * @param {string[]} files repo-relative paths
+ * @param {(path: string) => string} read
+ */
+const COLUMN = new Map(CLASSES.map((c, i) => [c.id, i]));
+
+// ── THE CENSUS IS A STATEMENT ABOUT THE PUBLISHED TREE, AND IT CAN BE RUN OVER A BIGGER ONE ──────
+//
+// The withheld corpus is laid back over this tree at its pre-cut paths to run the suite with it. Under
+// that overlay `git ls-files` returns 110 files that are not in the published repository, and measured
+// before this existed they carry 360 hits — 299 of them the one class this floor holds at ZERO. So the
+// arms would have gone red on files the committed fixture cannot record: writing them into it would
+// publish the withheld path list, which is the thing the cut exists to prevent.
+//
+// `isWithheld` is the instrument for that question and this is its THIRD reader — corrected 2026-09-09
+// from "sixth", which counted three readers that do not exist. Its own file states
+// the condition a new caller must meet — the fallback has to make the caller STRICTER, never looser —
+// and this one does: with no cut record it answers false for everything, nothing is skipped, and the
+// census counts the whole tree.
+//
+// AND IT IS INERT TODAY, WHICH IS SAID HERE RATHER THAN LEFT TO BE DISCOVERED. Measured: neither the
+// published repository nor the one the overlay lays from carries `shared/withheld-paths.mjs`, so
+// `CUT_RECORD_PRESENT` is false in both and this skip has never yet excluded a path. It stays because
+// it is the right question and costs nothing the day a record exists. What actually separates the two
+// populations today is the caller's business, and the floor test does it by asking which files are in
+// HEAD: the overlay stages what it lays and never commits it, so a laid path is in the index and not
+// in the published tree. An armed-but-blind guard is worth having only while it says which it is.
+//
+// THE COUNT IS RETURNED, NOT SWALLOWED. A skip nobody can see is how an exclusion becomes an outage:
+// a predicate that started answering true for everything would report a clean, empty census, and that
+// reads exactly like a repaired tree. The arms assert on `skipped` in both directions.
+export function censusOf(files, read) {
+  const out = { total: 0, files: {}, skipped: 0, cutRecord: CUT_RECORD_PRESENT };
+  for (const path of files) {
+    if (!isScannable(path)) continue;
+    if (isWithheld(path)) { out.skipped++; continue; }
+    let text;
+    try { text = read(path); } catch { continue; }
+    if (text.includes("\0")) continue;                       // a binary blob is not prose
+    const counts = CLASSES.map(() => 0);
+    for (const line of text.split("\n")) {
+      for (const { id } of offendingClasses(path, line)) counts[COLUMN.get(id)]++;
+    }
+    const sum = counts.reduce((a, b) => a + b, 0);
+    if (sum) { out.files[path] = counts; out.total += sum; }
+  }
+  return out;
+}
+
+/**
+ * The files this checkout PUBLISHES, out of the ones it tracks.
+ *
+ * The suite is also run over a bigger tree: the withheld corpus is laid back over a clone at its
+ * pre-cut paths so our own arms can run against it. That overlay stages what it lays and never commits
+ * it, so a laid path is in the index and not in HEAD — which is the whole discriminator, and it is
+ * exact rather than a heuristic about paths.
+ *
+ * The backlog is a statement about the published repository, so both the floor and the mint read this
+ * and not the raw tracked list. Two spellings of "the population" is one population and one guess.
+ *
+ * @param {string[]} trackedList what `trackedFiles` returned — enumerated there so the loud
+ *   no-checkout skip and the corpus marker stay in one place
+ * @param {string} root
+ * @returns {{files: string[], laid: number} | {error: string}}
+ */
+export function publishedOf(trackedList, root) {
+  let head;
+  try {
+    head = new Set(execFileSync("git", ["-C", root, "ls-tree", "-r", "HEAD", "--name-only"],
+      { encoding: "utf8", maxBuffer: 1 << 28 }).split("\n").filter(Boolean));
+  } catch (e) {
+    // A tree with no HEAD cannot say what it published, and that is a could-not-look. It must not
+    // become "nothing is laid here", which is the permissive reading and the one that passes.
+    return { error: `could not read HEAD in ${root}: ${String(e.message).split("\n")[0]}` };
+  }
+  const files = trackedList.filter((f) => head.has(f));
+  return { files, laid: trackedList.length - files.length };
+}

package/shared/suite-census.mjs

@@ -38,7 +38,7 @@ export const CENSUS_WORKSPACES = Object.freeze([
 
 // ── — THE FOURTH POPULATION, AND WHY IT IS NOT A FOURTH WORKSPACE ROW ───────────────────────
 //
-// MEASURED (eggie/Jerry, 2026-08-24): `npm run test:providers` on the control tree ran 59 files / 624
+// MEASURED (in testing, 2026-08-24): `npm run test:providers` on the control tree ran 59 files / 624
 // tests; on the cut tree, 47 files / 426 tests. **198 tests disappeared and the command exited 0.** No
 // failure, no warning, no line saying a file was not picked up.
 //
@@ -62,6 +62,13 @@ export const CENSUS_ROOT_SCRIPTS = Object.freeze([
   Object.freeze({
     script: "test:providers",
     globs: Object.freeze(["providers/_shared/test/*.test.mjs", "providers/*/test/*.test.mjs"]),
+    // THE COMMAND NO LONGER SPELLS THOSE GLOBS; it reaches them through this file, which builds the
+    // list in code so the corpus has one definition and two entry points. The literals above stay
+    // exactly as they were — they are this module's EXPECTATION, and deleting them in favour of the
+    // resolved list would leave two derived sides with nothing to disagree about, which is the defect
+    // the block above this table exists to record. What changes is only how the measurement is taken:
+    // the resolved list is asked whether it still reaches each glob.
+    resolvedBy: "scripts/test-full.mjs",
   }),
 ]);
 
@@ -74,7 +81,7 @@ export const CENSUS_ROOT_SCRIPTS = Object.freeze([
  *
  * PURE: `readManifest` is injected, so the canary drives every branch over a planted manifest.
  */
-export function rootScriptDisagreements(readManifest, declared = CENSUS_ROOT_SCRIPTS) {
+export function rootScriptDisagreements(readManifest, declared = CENSUS_ROOT_SCRIPTS, resolveFiles = null) {
   const root = readManifest("package.json");
   if (!root) return ["the root package.json could not be read, so what the root scripts collect is unknown"];
   const scripts = root.scripts ?? {};
@@ -86,8 +93,23 @@ export function rootScriptDisagreements(readManifest, declared = CENSUS_ROOT_SCR
       continue;
     }
     for (const g of globs) {
-      if (!line.includes(g)) {
+      if (line.includes(g)) continue;
+      // THE COMMAND DOES NOT SPELL THIS GLOB. That is a disagreement unless the script says it
+      // resolves the corpus elsewhere AND the resolved list is available to be checked. A declared
+      // `resolvedBy` with no resolver in hand is a could-not-look, never a pass: it would let an
+      // entry opt out of the whole check by naming a file.
+      const via = declared.find((d) => d.script === script)?.resolvedBy;
+      if (!via) {
         out.push(`\`${script}\` is censused as collecting ${g} and its command is: ${line.trim()}`);
+      } else if (!line.includes(via)) {
+        out.push(`\`${script}\` is censused as resolving its corpus through ${via}, and its command `
+          + `does not name it: ${line.trim()}`);
+      } else if (typeof resolveFiles !== "function") {
+        out.push(`\`${script}\` resolves its corpus through ${via} and no resolver was supplied, so `
+          + `what it collects could not be read — which is not the same as it being right`);
+      } else if (!resolveFiles(script).some((f) => globMatches(g, f))) {
+        out.push(`\`${script}\` is censused as collecting ${g}; ${via} resolves a corpus that `
+          + `reaches no such file`);
       }
     }
   }
@@ -117,6 +139,12 @@ export function rootScriptDisagreements(readManifest, declared = CENSUS_ROOT_SCR
 // PURE AND INJECTABLE. `readManifest` is passed in, so the canary drives every branch over planted
 // manifests without touching the tree — the same rule the rest of this module follows.
 
+/** Does one `*`-style glob match this path? `*` stops at a separator, as a shell's does. */
+export function globMatches(glob, path) {
+  const re = new RegExp("^" + glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*") + "$");
+  return re.test(path);
+}
+
 /** `npm run <name>` inside a script, so an indirection resolves within its own manifest. */
 const NPM_RUN = /^\s*npm\s+run\s+([A-Za-z0-9:_-]+)\s*$/;
 

package/shared/withheld-paths-access.mjs

@@ -8,33 +8,50 @@
 // private." `shared/withheld-paths.mjs` STAYS BEHIND. The reading where it ships with a rewritten
 // header is dead and must not be revived.
 //
-// Five files read that record and are wanted on the public tree: `scripts/citation-line-check.mjs`,
-// `scripts/mint-suite-census.mjs`, and the arms `no-caveat-repair`,
-// `signa-mock-lane-is-unreachable-from-a-run` and `the-providers-suite-is-censused`. A static import of
-// a module that is not there throws before anything runs — for a test that means its cases VANISH FROM
-// THE COUNT rather than failing, which is the 354-to-279 shape already records. This
-// module is how they degrade on purpose instead.
+// THREE files read that record, and all three are in this repository:
+// `scripts/citation-line-check.mjs`, `scripts/mint-suite-census.mjs` and
+// `shared/reference-guard-classes.mjs`. A static import of a module that is not there throws before
+// anything runs, and for a test that means its cases VANISH FROM THE COUNT rather than failing. This
+// module is how those three degrade on purpose instead.
+//
+// The list above was wrong in both directions and is corrected here (measured 2026-09-09): it said
+// five, naming three tests that exist in this repository under no path, and it omitted
+// `shared/reference-guard-classes.mjs`, which had already recorded itself as a reader in its own file.
 //
 // ── WHY DEGRADING IS SAFE HERE, WHICH IS THE WHOLE ARGUMENT ──────────────────────────────────────
 //
-// Every one of the five asks the record ONE question: is this file absent because it was deliberately
+// Every one of the three asks the record ONE question: is this file absent because it was deliberately
 // withheld, or absent because something broke? On the public tree nothing was withheld FROM that tree,
 // so the honest answer is "nothing is withheld" — and each caller then becomes STRICTER, never weaker:
 //
 //   citation-line-check   every file crosses the cut, so every citation must resolve
 //   mint-suite-census     no exemption, so a removed test file is a LOSS
-//   the three arms        an absence is damage, never a stated consequence
+//   reference-guard-classes  nothing is skipped, so the whole tree is counted
+//
+// MEASURED, not argued (2026-09-09): `censusOf` was run twice over one file list. With no record it
+// counted four files and skipped none; with a record naming two of them it counted two and skipped
+// two. Absent, the record cannot hide a defect.
 //
 // A fallback that can only tighten is one that cannot hide a defect. That is the property that makes
 // this safe to do without a flag, and it is the property to re-check before adding a sixth caller: if a
 // new caller would be LOOSER without the record, it does not belong here.
 //
-// ── AND IT ANNOUNCES, SO IT CANNOT FIRE UNNOTICED WHERE IT MUST NOT ──────────────────────────────
+// ── NO TREE CARRIES THE RECORD TODAY, AND THE MODE LINE SAYS WHICH WAY THAT LEANS ───────────────
+//
+// This block used to say the record exists here and that losing it "would quietly relax five checks".
+// Both halves were false, and the second contradicted the paragraph above it. Measured 2026-09-09:
+// `CUT_RECORD_PRESENT` is false here and false in the larger tree the suite is also run against — the
+// record exists in neither, so every reader has always run in fallback, and fallback is the strict side.
+//
+// The mode is still announced once to stderr, the way `announceBlocklistMode` does for the identifier
+// roster. What the line may NOT do is call itself an alarm: this module can see whether the record is
+// present, and cannot see whether it ought to be. So it states the mode and what that means for the
+// three readers, and leaves the judgement to a reader who knows which tree they are looking at.
 //
-// On our tree the record exists and behaviour is unchanged. If it ever went missing here, the fallback
-// would quietly relax five checks — the exact silent-pass this repository keeps paying for. So the mode
-// is announced once to stderr, the way `announceBlocklistMode` does for the identifier roster, and an
-// arm pins that the announcement happens.
+// NOTHING PINS THIS ANNOUNCEMENT, and this block used to claim something did. Measured 2026-09-09: no
+// test in either repository imports `announceWithheldMode` or asserts its line, so the wording above is
+// held by nothing and a silent removal of it would pass. That gap is filed rather than fixed here,
+// because closing it adds a test file and this change is comment text only.
 
 let record = null;
 try {
@@ -59,15 +76,16 @@ export const isWithheld = (relPath) => (record ? record.isWithheld(relPath) : fa
 
 let announced = false;
 /**
- * Say which mode this process is in, once, to stderr. A green run in fallback mode on a tree that
- * SHOULD carry the record is five checks quietly relaxed, and the only thing standing between that and
- * silence is this line.
+ * Say which mode this process is in, once, to stderr. Fallback is the strict side, so this line is a
+ * statement of fact rather than a warning: it reports what the three readers will do, and whether that
+ * is right depends on the tree, which this module cannot see.
  */
 export function announceWithheldMode() {
   const line = CUT_RECORD_PRESENT
     ? `[repo-guard] cut record present — ${WITHHELD.length} withheld entry/entries; absences they cover are stated consequences`
-    : "[repo-guard] NO cut record in this tree — nothing counts as withheld, so every absence is damage "
-      + "and every citation must resolve. This is correct on the published tree and an ALARM anywhere else.";
+    : "[repo-guard] no cut record in this tree — nothing counts as withheld, so every absence is damage "
+      + "and every citation must resolve. This is the STRICTER of the two modes: it cannot hide a defect, "
+      + "and it is the expected mode wherever nothing was withheld from the tree in hand.";
   if (!announced) { announced = true; console.error(line); }
   return line;
 }