clearotron 0.2.2 → 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/staff-domain.mjs

@@ -0,0 +1,154 @@
+// 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
+// staff-domain.mjs — what a staff-domain rule ADMITS, decided before one is written.
+//
+// `PORTAL_STAFF_DOMAINS` is a list of email domains, and every address at a listed domain that gets
+// past this instance's sign-in door is staff: it sees every brand owner on the instance
+// (driver/portal-access.mjs). That is a rule about a set of people, not about one person.
+//
+// The install used to build that rule by taking everything after the last `@` of the one address it
+// was given. On a laptop that address is `<account>@localhost` and the rule admits the one identity
+// that can sign in, which is why it was safe and why nobody looked at it again. Given a real address
+// the same line turns a person into their whole employer, or into every customer of a webmail
+// provider, with nothing said to the operator and nothing to undo. A stranger's install granted a
+// documentation domain that way, read its own settings page back, and reported it as a back door.
+//
+// So the derivation is classified before it is used, and there are three answers:
+//
+//   "narrow"    the domain cannot name a second person on this machine — `localhost`, or any bare
+//               hostname with no dot. Deriving a rule from it is what it always was: safe, silent.
+//   "public"    a webmail or shared provider. Never a staff rule: it would admit strangers, and no
+//               deployment can want it. Refused outright, and the refusal names the domain.
+//   "reserved"  a domain reserved for documentation and testing (RFC 2606). Nobody's real mail lives
+//               there, so a rule built from one is always an address somebody typed as a placeholder.
+//               Refused for the same reason, with a different sentence, because the remedy differs.
+//   "wide"      an ordinary routable domain. It may well be the right rule — it is how a firm admits
+//               its own lawyers — but it admits people the operator has not met, so it is stated in
+//               the words the settings page will use and confirmed before it is written. It is never
+//               derived silently from one address.
+//
+// FAIL-CLOSED, in the direction of a smaller grant. A domain wrongly classified `public` refuses, and
+// the operator sets `PORTAL_STAFF_DOMAINS` themselves in one line — an explicit decision, recorded
+// where the settings page can name it. A domain wrongly classified `wide` asks a question. Neither
+// outcome grants anything, which is why the lists below are allowed to be short and stay short: the
+// `wide` branch is what actually protects an operator, and the lists only decide whether the product
+// asks a question or refuses to ask one.
+
+/** Last-@ semantics, matching driver/portal-access.mjs and shared/scope.mjs `isFirmDomain`. */
+export function domainOfEmail(email) {
+  const e = String(email ?? "").trim().toLowerCase();
+  const at = e.lastIndexOf("@");
+  return at > 0 ? e.slice(at + 1) : "";
+}
+
+/**
+ * Webmail and shared mailbox providers, exactly.
+ *
+ * Not a census of the internet, and deliberately not growing into one: an unlisted provider still
+ * lands in `wide`, where it is stated and confirmed rather than written silently. What this list buys
+ * is that the commonest addresses a person types — their own personal mail — are refused with a
+ * sentence about why, instead of being offered as a rule somebody might say yes to.
+ */
+export const PUBLIC_EMAIL_DOMAINS = Object.freeze(new Set([
+  "gmail.com", "googlemail.com", "icloud.com", "me.com", "mac.com",
+  "aol.com", "mail.com", "gmx.com", "gmx.de", "gmx.net", "web.de", "t-online.de",
+  "proton.me", "protonmail.com", "protonmail.ch", "pm.me", "tuta.io", "tutanota.com",
+  "fastmail.com", "fastmail.fm", "hey.com", "zoho.com", "hushmail.com",
+  "mail.ru", "inbox.ru", "list.ru", "bk.ru", "rambler.ru",
+  "qq.com", "163.com", "126.com", "sina.com", "naver.com", "daum.net",
+  "seznam.cz", "wp.pl", "o2.pl", "interia.pl", "libero.it", "virgilio.it", "tiscali.it",
+  "free.fr", "orange.fr", "wanadoo.fr", "laposte.net", "sfr.fr", "bbox.fr",
+  "comcast.net", "verizon.net", "att.net", "sbcglobal.net", "bellsouth.net", "cox.net",
+  "btinternet.com", "sky.com", "virginmedia.com", "ntlworld.com", "talktalk.net",
+  "bigpond.com", "optusnet.com.au", "shaw.ca", "sympatico.ca", "rogers.com",
+  "xs4all.nl", "ziggo.nl", "telenet.be", "uol.com.br", "bol.com.br", "terra.com.br",
+  "rediffmail.com", "yandex.com", "yandex.ru", "ya.ru",
+]));
+
+/**
+ * Providers that sell the same mailbox under a per-country domain.
+ *
+ * Matched on the FIRST label, so `yahoo.co.uk` and `yahoo.fr` are covered without listing every
+ * country. Kept to names that are a provider and nothing else — a first label like `free` or `orange`
+ * is a real company's name somewhere, so those stay in the exact list above.
+ */
+export const PUBLIC_EMAIL_FAMILIES = Object.freeze(new Set([
+  "yahoo", "ymail", "rocketmail", "hotmail", "outlook", "live", "msn", "gmx", "yandex", "googlemail",
+]));
+
+/**
+ * Reserved for documentation and testing — RFC 2606 §2 and §3.
+ *
+ * `example.com`, `example.net`, `example.org` and everything under them, plus the whole of the
+ * `.example`, `.invalid`, `.test` and `.localhost` top-level names. Real mail is never delivered to
+ * any of them, so an address at one is a placeholder somebody typed — which is exactly what happened.
+ *
+ * `localhost` ITSELF IS NOT HERE. A bare `localhost` is the local-account default and is classified
+ * `narrow` below; only `something.localhost` reaches this test.
+ */
+function isReservedDomain(domain) {
+  if (/^example\.(com|net|org)$/.test(domain)) return true;
+  if (/\.example\.(com|net|org)$/.test(domain)) return true;
+  const tld = domain.slice(domain.lastIndexOf(".") + 1);
+  return domain.includes(".") && ["example", "invalid", "test", "localhost"].includes(tld);
+}
+
+/** A domain that cannot name a second person on this machine: `localhost`, or any dotless hostname. */
+function isNarrowDomain(domain) {
+  return domain === "localhost" || domain === "localhost.localdomain" || !domain.includes(".");
+}
+
+/**
+ * What a staff rule built from this domain would admit.
+ *
+ * @param {string} domain a bare domain, already lowercased — `domainOfEmail` produces one.
+ * @returns {"narrow"|"public"|"reserved"|"wide"|""}  "" only when there is no domain to classify.
+ */
+export function classifyStaffDomain(domain) {
+  const d = String(domain ?? "").trim().toLowerCase();
+  if (!d) return "";
+  if (isNarrowDomain(d)) return "narrow";
+  if (isReservedDomain(d)) return "reserved";
+  if (PUBLIC_EMAIL_DOMAINS.has(d)) return "public";
+  if (PUBLIC_EMAIL_FAMILIES.has(d.slice(0, d.indexOf(".")))) return "public";
+  return "wide";
+}
+
+/**
+ * The rule in the words the settings page uses, so the operator recognises what they agreed to.
+ *
+ * ONE COMPOSER FOR BOTH SURFACES. The People & access screen renders "Anyone at <domain>" under a
+ * heading that calls it a config rule rather than a person, and describes staff as capable of seeing
+ * every brand owner. A consent prompt phrased any other way asks about one thing and shows another.
+ */
+export function staffGrantSentence(domain, { staffLabel = "Staff" } = {}) {
+  return `Anyone at ${domain} — a rule, not a person. ${staffLabel}: capable to see every brand owner `
+    + "on this instance.";
+}
+
+/**
+ * Why this domain cannot become a staff rule, and what to do instead.
+ *
+ * Returns null for a domain that CAN — `narrow` and `wide` are not refusals, and `wide` is answered by
+ * the confirmation the caller runs, not by this function.
+ */
+export function staffDomainRefusal(domain, { variable = "PORTAL_STAFF_DOMAINS" } = {}) {
+  const d = String(domain ?? "").trim().toLowerCase();
+  const verdict = classifyStaffDomain(d);
+  if (verdict === "public") {
+    return `${d} is a public email provider, so a staff rule built from it would admit anyone with an `
+      + `address there — not your colleagues. Refusing to write one.\n`
+      + `  Use an address at a domain your organisation controls, or set ${variable} yourself to the `
+      + "domain you mean.\n"
+      + "  If this machine is only yours, the local-account form takes no rule at all: leave the "
+      + "address as <account>@localhost.";
+  }
+  if (verdict === "reserved") {
+    return `${d} is reserved for documentation and receives no real mail (RFC 2606), so it is an `
+      + "address somebody typed as a placeholder rather than one that signs in. Refusing to build a "
+      + "staff rule from it.\n"
+      + "  Use the address you actually sign in with, or the local-account form <account>@localhost "
+      + "if this machine is only yours.";
+  }
+  return null;
+}

package/shared/store-in-repo.mjs

@@ -38,13 +38,34 @@
 // that does not exist yet is still misconfigured if it names another tree — the service would create it
 // and then fail every commit — so the lexical judgment stands where the filesystem cannot overturn it.
 
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, relative, isAbsolute } from "node:path";
 import { realpathSync } from "node:fs";
 
 /** `resolve`, then the symlink-resolved form when the path exists — null when it cannot be read. */
 const real = (p) => { try { return realpathSync(resolve(p)); } catch { return null; } };
 
-const within = (dir, root) => dir === root || dir.startsWith(root.endsWith("/") ? root : root + "/");
+// CONTAINMENT IS ASKED OF THE PATH LIBRARY, NOT OF THE STRING.
+//
+// This was `dir.startsWith(root + "/")`, with the separator written in. On Windows `resolve()` returns
+// backslashes, so `C:\…\config\recipes` does not start with `C:\…\config/` and a folder plainly inside
+// its parent read as OUTSIDE — an operator on a correct install was told their recipe store was outside
+// the repository root, and the saved-search door refused. Measured on his paths.
+//
+// The posix control passed throughout, which is why it survived: the string test is right on the platform
+// it was written on and wrong on the one nobody here runs.
+//
+// `relative` also settles two cases a prefix test gets wrong on Windows even with the separator fixed: a
+// different drive letter yields an absolute path rather than a `..` walk, and path comparison there is
+// case-insensitive in a way `startsWith` is not. A sibling directory whose name merely begins with the
+// root's — `config` and `configXX` — is still outside, which the old `+ "/"` also got right and any
+// replacement had to keep.
+// `impl` is the path module to ask, injected ONLY so a check can drive the Windows behaviour from a
+// Linux runner. That matters here more than usual: this defect was invisible on the platform every one
+// of us runs, and a guard that can only be exercised on Windows is a guard nobody will ever see fail.
+export const within = (dir, root, impl = { relative, isAbsolute }) => {
+  const rel = impl.relative(root, dir);
+  return rel === "" || (!rel.startsWith("..") && !impl.isAbsolute(rel));
+};
 
 /**
  * Is `storeDir` somewhere `git -C repoRoot add` could stage it?

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*$/;