@syncerauk/test-rules 1.0.5 → 1.0.7

package/README.md

@@ -26,7 +26,8 @@ npm run gate:test-rules -- --base origin/main --list
 | 2 | A bad command line |
 | 3 | The check could not run (no config, unreadable JSON, not a git worktree) |
 
-`--list` prints one JSON object: `{ v, breaches: [{ file, rule, line, say }], listed, stale }`.
+`--list` prints one JSON object: `{ v, breaches: [{ file, rule, line, say }], listed, stale,
+relisted: [{ file, rule, at }] }`.
 
 ## The rules
 
@@ -36,6 +37,7 @@ npm run gate:test-rules -- --base origin/main --list
 | `T1:hub` | A file listed as over the line limit grew against the base |
 | `R7:lines` | A test file over 1,500 lines |
 | `T4:source-text` | A test reads a source file as text |
+| `T4:pin` | A `pins` entry that does not hold (judged on the config, never listed) |
 | `T6:timer` | A real wait, with no fake timers in the file |
 | `T6:clock` | The wall clock, with no fake timers in the file |
 | `T6:outside` | The home folder, a path that climbs out of the repo, a real host |
@@ -51,6 +53,7 @@ Both in the repo's `scripts/test-rules/`:
   `ignore` (which files are test files), `fixtures` (folders a test may read), `wording` (the
   one list of what a person reads), `style_contract` (`{ "<test file>": ["<.css or .scss path or
   glob>"] }`: the one test that may read those stylesheets; style rules are checked there, once),
+  `pins` (the kept pins, below),
   `reads` (the reads register: `"comment"`, or
   `{ "json": "<path>" }` for the map under `"tests"` in that file, `"key": "<name>"` for another
   key, `"key": null` when the file itself is the map). The defaults are `CONFIG_DEFAULTS` in the
@@ -59,6 +62,28 @@ Both in the repo's `scripts/test-rules/`:
   `test-rules --init`. An optional `moved` map, `{ "<new test file>": "<old test file>" }`,
   says where a split or a rename took a listed file.
 
+## Kept pins
+
+R4 allows a pin (a test that asserts on source text, a prompt or a document) only as a guard
+with a recorded mutation that turns it red, one per rule (Bernardo Cunha, 6 Nov 2026). The
+config registers each kept pin in `pins`:
+
+```json
+"pins": [
+  { "file": "<test file>", "rule": "<the rule it guards>",
+    "mutation": "<the change that turns it red>", "red_before": "<where that red is recorded>" }
+]
+```
+
+- A test file on `pins` is not a `T4:source-text` breach. It excuses T4 only, and only in that
+  file.
+- An entry fails the check (`T4:pin`, on the config) when it names no file or one that is not a
+  test file here, names no rule, names a rule another entry already pins (one pin per rule),
+  records no mutation or no `red_before`, or carries a key not above. An entry that fails
+  excuses nothing.
+- `T4:pin` is never listed. Registering a listed file makes its `T4:source-text` entry stale:
+  delete that line in the same change.
+
 ## The list only shrinks
 
 - A breach on the list passes. A breach off the list fails.
@@ -71,8 +96,49 @@ Both in the repo's `scripts/test-rules/`:
 
 A repo starts with `"fail": false`: breaches are printed and the exit is 0. One line turns it on.
 
+## Bumping the version: re-listed once per version
+
+A newer version can find breaches an older one missed, in files nobody touched (Bernardo Cunha,
+6 Nov 2026: re-list once per version). The PR that bumps the pin may add those entries to
+`listed.json`, and only those:
+
+- the PR raises the installed version: the base's is lower, and the version running is the one
+  installed (the lockfile, else an exact pin in `package.json`, read at the base through git);
+- the breach is found only by a detection newer than the base's version: the check runs a
+  second time as the base's version (the `DETECTORS` table in `test-rules.mjs` says which version
+  first found what) and only what that run does not find counts;
+- the PR does not change the file.
+
+Any other new entry is still `list:grew`. Allowed growth is printed (`re-listed at 1.0.6: N
+entries`, one `relisted` line each). Do not edit the list by hand: after the bump and
+`npm install`, run
+
+```bash
+npm run gate:test-rules -- --relist
+```
+
+It writes exactly the allowed entries into `listed.json` (keeping `moved`) and refuses (exit 2)
+when the PR does not raise the version.
+
+| Version | Detections it added |
+|---|---|
+| 1.0.0 | every rule: `T1:name`, `T1:hub`, `R7:lines`, `T4:source-text` (a declared read, a raw import, a source path built from the test's place), `T6:timer`, `T6:clock`, `T6:outside`, `T6:env` |
+| 1.0.1, 1.0.4, 1.0.5, 1.0.6 | none |
+| 1.0.2 | `T4:source-text`: a path that starts with a dot-folder; a JSON register that is the whole file |
+| 1.0.3 | `T4:source-text`: the built-path scan under a JSON register |
+| 1.0.7 | `T4:pin`: a `pins` entry that does not hold (never listed, so never re-listed) |
+
 ## Versions
 
+- **1.0.7** — Kept pins: the config's `pins` list registers each pin R4 allows, with the rule it
+  guards and its recorded mutation; a file on it is not a `T4:source-text` breach, and an entry
+  that does not hold is `T4:pin`. Nothing changes for a repo that does not set it; an older
+  version refuses a config with `pins` (unknown key), so bump before you register one.
+
+- **1.0.6** — Re-listed once per version: a PR that raises the installed version may add the
+  entries a newer detection finds in files it does not change; `--relist` writes them.
+  `--list` carries `relisted`. Nothing new is found.
+
 - **1.0.5** — A split or rename carries its listed breaches: `listed.json` may hold
   `"moved": { "<new test file>": "<old test file>" }`, and a new file's entry is not
   `list:grew` when the base listed the same rule on the old file and the old file is gone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncerauk/test-rules",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "The static check of Syncera's test-writing rules (T1, T4, T6 and the line limit of R7). One file, no dependency. Published to npm by the orchestrator's publish-test-rules workflow; each repo pins an exact version.",
   "type": "module",
   "license": "UNLICENSED",

package/test-rules.mjs

@@ -4,18 +4,21 @@
 // of R7; docs/test-review/2026-11-05/RULES.md, adopted by Bernardo Cunha on 5 Nov 2026).
 //
 //   npm run gate:test-rules [-- --base <ref>] [--list]
-//   node scripts/test-rules.mjs [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init]
+//   node scripts/test-rules.mjs [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init | --relist]
 //
 // One implementation for the six repos (R8): one file, no dependency, no build; it imports
 // nothing from this repo and reads only the worktree and git, so another repo can run this same
 // file. Exit 0 clean, 1 a breach, 2 a bad command line, 3 the check itself could not run (no
 // config, unreadable JSON, not a git worktree, a --base that does not resolve).
 // `--list` prints one JSON object on one line and nothing else:
-//   { v: 1, breaches: [{ file, rule, line, say }], listed: <n>, stale: [{ file, rule }] }
-// `breaches` are the breaches that are not on the list; `listed` counts the ones that are.
+//   { v: 1, breaches: [{ file, rule, line, say }], listed: <n>, stale: [{ file, rule }],
+//     relisted: [{ file, rule, at }] }
+// `breaches` are the breaches that are not on the list; `listed` counts the ones that are;
+// `relisted` is the growth a version bump may bring (below).
 //
 // Per repo, two files:
-//   scripts/test-rules/config.json   what differs between repos (CONFIG_DEFAULTS below)
+//   scripts/test-rules/config.json   what differs between repos (CONFIG_DEFAULTS below); its
+//                                    `pins` list registers the kept pins (1.0.7, below)
 //   scripts/test-rules/listed.json   { v: 1, entries: { "<test file>": ["<rule id>", …] },
 //                                      moved: { "<new test file>": "<old test file>" } }
 // `moved` is optional: it says where a split or a rename took a listed file (1.0.5).
@@ -30,6 +33,17 @@
 // `list:grew` when `moved` names its old file, the base listed that same rule on the old file,
 // and the old file is no longer a test file. A `moved` line is never stale and never a breach;
 // it may be deleted at any time.
+// Re-listed once per version (Bernardo Cunha, 6 Nov 2026, 1.0.6): a newer version can find
+// breaches an older one missed, in files nobody touched. An entry the base does not hold is not
+// `list:grew` when all three hold: (a) this change raises the installed version (the base's is
+// lower than the one running, and the one running is the one installed); (b) the breach is found
+// only by a detection newer than the base's version (DETECTORS below: the check is run a second
+// time as the base's version, and only what that run does not find counts); (c) the change does
+// not edit the file. Allowed growth is printed ("re-listed at <version>: N entries"), never
+// silent. `--relist` writes exactly those entries into the list, so nobody edits it by hand.
+// The version installed is read from the lockfile, else an exact pin in package.json (in the
+// folder that holds node_modules/@syncerauk/test-rules, then the repo root), else, in the
+// orchestrator, which runs this file itself, from scripts/test-rules-package/package.json.
 // `"fail": false` in the config is report only: everything is printed, the exit is 0.
 //
 // The rules (RULES below) and how each is seen:
@@ -47,6 +61,10 @@
 //                   A JSON register is what a test says it reads; it does not stop the code
 //                   being read for what it does read (1.0.3). A stylesheet named for a test in
 //                   `style_contract` is not a breach in that test, and only in that test (1.0.4).
+//                   A test on the config's `pins` list is a kept pin (R4) and not a breach (1.0.7).
+//   T4:pin          a `pins` entry that does not hold: no test file, or one that is not a test
+//                   file here; no rule it guards, or a rule another entry already pins (one pin
+//                   per rule); no recorded mutation, or no record of its red-before (1.0.7)
 //   T6:timer        setTimeout( / setInterval( / sleep( / timers/promises with no fake timers in the file
 //   T6:clock        Date.now( / new Date() / performance.now( with no fake timers in the file
 //   T6:outside      homedir(), process.env.HOME, a relative path that climbs out of the repo,
@@ -55,12 +73,13 @@
 //   T6:env          process.env.<NAME> read and never set in that file
 // Comments are never read; code patterns are never matched inside a string.
 // The config and the list are read by the command line only, and the check runs on every small
-// gate, so no test declares them.
+// gate, so no test declares them. Its own version is read from its manifest:
+// reads: scripts/test-rules-package/package.json
 // =============================================================================
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { dirname, join, posix, resolve } from 'node:path';
+import { dirname, join, posix, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const VERSION = 1;
@@ -68,7 +87,10 @@ export const EXIT = Object.freeze({ CLEAN: 0, BREACH: 1, USAGE: 2, FAILED: 3 });
 export const CONFIG_FILE = 'scripts/test-rules/config.json';
 export const LISTED_FILE = 'scripts/test-rules/listed.json';
 export const DEFAULT_BASE = 'origin/main';
-const USAGE = 'usage: test-rules [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init]';
+export const PACKAGE = '@syncerauk/test-rules';
+/** The package's manifest in the orchestrator, the repo that runs this file itself. */
+export const SOURCE_MANIFEST = 'scripts/test-rules-package/package.json';
+const USAGE = 'usage: test-rules [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init | --relist]';
 
 /** What a repo's scripts/test-rules/config.json may set; anything it leaves out is this. */
 export const CONFIG_DEFAULTS = Object.freeze({
@@ -79,6 +101,7 @@ export const CONFIG_DEFAULTS = Object.freeze({
   fixtures: [], // folders a test may read: `a/fixtures/`
   wording: [], // the one list of what a person reads (a built page, a legal text): files, globs, folders
   style_contract: {}, // { "<test file>": ["<.css/.scss path or glob>", …] }: the one test that may read those stylesheets
+  pins: [], // [{ file, rule, mutation, red_before }]: the kept pins (R4), one per rule, each with the mutation that turns it red
   reads: null, // the reads register: null, "comment" (`// reads:` lines) or { json: "<path>", key: "tests" } (key null: the file itself is the map)
   source_ext: ['mjs', 'cjs', 'js', 'jsx', 'ts', 'tsx', 'mts', 'cts', 'sql', 'css', 'scss', 'html', 'sh', 'yml', 'yaml', 'md', 'mdx'],
   max_lines: 1500,
@@ -93,6 +116,7 @@ export const RULES = Object.freeze({
   'T1:hub': 'this file is listed as over the line limit and it grew: the new test goes in a new file, by topic',
   'R7:lines': 'over the line limit: split the file by topic',
   'T4:source-text': 'a test does not open a source file and search it: run the code and assert on what it did (wording is checked once, from the wording list)',
+  'T4:pin': 'a kept pin (R4) is the guard of one rule: its `pins` entry names the test file, the rule, the mutation that turns it red and where that red-before is recorded',
   'T6:timer': 'no real wait in a gated test: use the fake clock or fake timers',
   'T6:clock': 'no wall clock in a gated test: pass a fixed time in, or use fake timers',
   'T6:outside': 'nothing outside the commit: no home folder, machine path, path out of the repo or real host',
@@ -100,7 +124,43 @@ export const RULES = Object.freeze({
   'list:grew': 'the list only shrinks: fix the breach, do not list it',
 });
 /** The rules a listed.json entry can never excuse. */
-export const NEVER_LISTED = Object.freeze(['T1:hub', 'list:grew']);
+export const NEVER_LISTED = Object.freeze(['T1:hub', 'T4:pin', 'list:grew']);
+
+/**
+ * Each way the check finds a breach: the rule it reports and the version that first found it,
+ * from the git history of this file. `breachesOf({ as })` runs only the ones a version had, so a
+ * re-list can tell what a bump newly finds from what was there all along. A version that changes
+ * how a breach is found adds a row here, with its own `since`, and keeps the old behaviour
+ * behind it. 1.0.1 (the same file as 1.0.0), 1.0.4 (`style_contract`: it narrows T4 and finds
+ * nothing new), 1.0.5 (`moved`) and 1.0.6 (the re-list) add none. 1.0.7 adds T4:pin, which is
+ * judged on the config and never listed, so a re-list never carries it.
+ */
+export const DETECTORS = Object.freeze({
+  'T1:name': { rule: 'T1:name', since: '1.0.0' }, // the file named by task
+  'T1:hub': { rule: 'T1:hub', since: '1.0.0' }, // a listed long file grew (judged against the base, never listed)
+  'R7:lines': { rule: 'R7:lines', since: '1.0.0' }, // over max_lines
+  'T4:declared': { rule: 'T4:source-text', since: '1.0.0' }, // a declared read (comment lines or the JSON register) of a source file, folder or glob
+  'T4:raw': { rule: 'T4:source-text', since: '1.0.0' }, // a `?raw` import or a raw import.meta.glob
+  'T4:built': { rule: 'T4:source-text', since: '1.0.0' }, // a source path built from the test's own place, undeclared, with no JSON register
+  'T4:dot-folder': { rule: 'T4:source-text', since: '1.0.2' }, // that path starting with a dot-folder (.github/…) is a repo path, not one beside the test
+  'T4:whole-register': { rule: 'T4:source-text', since: '1.0.2' }, // a JSON register that is the whole file ("key": null) is read, not taken as empty
+  'T4:built-under-json': { rule: 'T4:source-text', since: '1.0.3' }, // the built-path scan runs under a JSON register too
+  'T4:pin': { rule: 'T4:pin', since: '1.0.7' }, // a `pins` entry that does not hold (judged on the config, never listed)
+  'T6:timer': { rule: 'T6:timer', since: '1.0.0' },
+  'T6:clock': { rule: 'T6:clock', since: '1.0.0' },
+  'T6:outside': { rule: 'T6:outside', since: '1.0.0' },
+  'T6:env': { rule: 'T6:env', since: '1.0.0' },
+});
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/** -1, 0 or 1 for two x.y.z versions. */
+export function compareVersions(a, b) {
+  const x = String(a).split('.').map(Number);
+  const y = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+/** Whether version `as` had detector `id` (no `as`: this version, every detector). */
+export const detects = (id, as = null) => !as || compareVersions(DETECTORS[id].since, as) <= 0;
 
 const fail = (code, message) => Object.assign(new Error(message), { exit: code });
 
@@ -279,7 +339,8 @@ function envLine({ code, bare }, allowed) {
 }
 
 /** T4: the line of the first read of a source file as text, or 0. */
-function sourceTextLine({ path, text, code, bare, strings }, { config, register, tracked }) {
+function sourceTextLine({ path, text, code, bare, strings }, { config, register, tracked, as }) {
+  const on = (id) => detects(id, as);
   const isSource = (p) => config.source_ext.includes(String(p).split('.').pop().toLowerCase());
   // A style contract is the one test that may read the stylesheets it names: style rules are
   // checked once, there, the way wording is checked once from the wording list.
@@ -288,23 +349,25 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
   const offends = (p) => !allowed(p) && (isFolderOrGlob(p) || isSource(p));
 
   const declared = declaredIn(text);
-  if (register && typeof register === 'object') {
+  const json = register && typeof register === 'object';
+  if (on('T4:declared') && json) {
     if ((register[path] ?? []).some(offends)) return 1;
-  } else if (config.reads === 'comment') {
+  } else if (on('T4:declared') && config.reads === 'comment') {
     const hit = declared.reads.find((r) => offends(r.pattern));
     if (hit) return hit.line;
   }
-  for (const m of bare.matchAll(RAW_IMPORT)) {
+  for (const m of on('T4:raw') ? bare.matchAll(RAW_IMPORT) : []) {
     if (code[m.index] === ' ') continue; // the words are inside a string, not an import
     if (!allowed(posix.normalize(posix.join(posix.dirname(path), m[1])))) return lineOf(bare, m.index);
   }
-  for (const m of code.matchAll(RAW_GLOB)) {
+  for (const m of on('T4:raw') ? code.matchAll(RAW_GLOB) : []) {
     const call = bare.slice(m.index, m.index + 300).split(')')[0];
     if (/\?raw|as\s*:\s*['"]raw['"]/.test(call)) return lineOf(code, m.index);
   }
   // A source file whose path the test builds from its own place, in a test that reads the file
   // system, that the test does not declare: `// runs:` when it is only run. A JSON register does
-  // not silence this: a register can miss a read, and a source file it names returned above.
+  // not silence this (1.0.3): a register can miss a read, and a source file it names returned above.
+  if (!on('T4:built') || (json && !on('T4:built-under-json'))) return 0;
   if (!FS_READ.test(code) || !tracked) return 0;
   const said = [...declared.reads, ...declared.runs].map((r) => r.pattern);
   for (const s of strings) {
@@ -312,9 +375,11 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
     if (/[\s*?$]/.test(v) || !isSource(v)) continue;
     const before = code.slice(code.lastIndexOf('\n', s.start) + 1, s.start - 1);
     if (IMPORT_BEFORE.test(before) || !BUILT_HERE.test(before)) continue;
-    // `./x` and `../x` are relative to the test; `.github/x` is a repo path like any other.
+    // `./x` and `../x` are relative to the test; `.github/x` is a repo path like any other (1.0.2;
+    // before it, any leading dot was read as beside the test).
     const here = posix.normalize(posix.join(posix.dirname(path), v));
-    const target = v.startsWith('./') || v.startsWith('../') || !tracked.has(v) ? here : v;
+    const besideTest = on('T4:dot-folder') ? v.startsWith('./') || v.startsWith('../') : v.startsWith('.');
+    const target = besideTest || !tracked.has(v) ? here : v;
     if (target === path || !tracked.has(target) || allowed(target)) continue;
     if (said.some((p) => globRe(p).test(target))) continue;
     return lineOf(code, s.start);
@@ -322,30 +387,65 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
   return 0;
 }
 
+/**
+ * The pins register (1.0.7; R4, Bernardo Cunha, 6 Nov 2026: a pin is allowed only as a guard with
+ * a recorded mutation that turns it red, one per rule). `pins`: the config's list; `testPaths`: a
+ * Set of the repo's test files. → { pinned: Set of the test files a sound entry names, problems:
+ * [why each entry does not hold] }. An entry that does not hold excuses nothing, so a second entry
+ * for a rule that has its pin leaves its test a T4 breach.
+ */
+export function pinsOf(pins, testPaths) {
+  const pinned = new Set();
+  const problems = [];
+  const byRule = new Map();
+  const said = (v) => typeof v === 'string' && v.trim().length > 0;
+  (pins ?? []).forEach((pin, i) => {
+    const at = `pins[${i}]${said(pin.file) ? ` (${pin.file})` : ''}`;
+    const why = [];
+    if (!said(pin.file)) why.push('names no test file');
+    else if (!testPaths.has(pin.file)) why.push(`${pin.file} is not a test file in this repo`);
+    if (!said(pin.rule)) why.push('names no rule it guards');
+    else if (byRule.has(pin.rule.trim())) why.push(`"${pin.rule.trim()}" is already pinned by ${byRule.get(pin.rule.trim())}: one pin per rule`);
+    if (!said(pin.mutation)) why.push('records no mutation that turns it red');
+    if (!said(pin.red_before)) why.push('says not where its red-before is recorded');
+    const unknown = Object.keys(pin).filter((k) => !['file', 'rule', 'mutation', 'red_before'].includes(k));
+    if (unknown.length) why.push(`unknown key ${unknown.join(', ')}`);
+    if (said(pin.rule) && !byRule.has(pin.rule.trim())) byRule.set(pin.rule.trim(), at);
+    if (why.length) problems.push(`${at} ${why.join('; ')}`);
+    else pinned.add(pin.file);
+  });
+  return { pinned, problems };
+}
+
 /**
  * Every breach in `files` (the repo's test files as { path, text }), one per file and rule, at
- * its first line: [{ file, rule, line, say }], sorted. Pure: no disk, no git.
+ * its first line: [{ file, rule, line, say }], sorted. Pure: no disk, no git. `as`: a version
+ * (x.y.z) to run only the detectors it had (DETECTORS), for the re-list; null runs them all.
  */
-export function breachesOf({ files, config, register = null, tracked = null }) {
+export function breachesOf({ files, config, register = null, tracked = null, as = null }) {
   const out = [];
   const add = (file, rule, line) => out.push({ file, rule, line, say: RULES[rule] });
+  const on = (id) => detects(id, as);
   const names = config.task_names.map((s) => new RegExp(s, 'i'));
   const fakes = config.fake_timers.map((s) => new RegExp(s));
+  // A kept pin is not a T4 breach; an entry that does not hold is one T4:pin on the config.
+  const pins = pinsOf(config.pins, new Set(files.map((f) => f.path)));
+  if (on('T4:pin') && pins.problems.length) out.push({ file: CONFIG_FILE, rule: 'T4:pin', line: 1, say: `${RULES['T4:pin']} (${pins.problems.join(' · ')})` });
   for (const { path, text } of files) {
     const view = { path, text, ...scan(text) };
     const base = path.split('/').pop();
-    if (names.some((re) => re.test(base))) add(path, 'T1:name', 1);
-    if (countLines(text) > config.max_lines) add(path, 'R7:lines', config.max_lines + 1);
-    const t4 = sourceTextLine(view, { config, register, tracked });
-    if (t4) add(path, 'T4:source-text', t4);
+    if (on('T1:name') && names.some((re) => re.test(base))) add(path, 'T1:name', 1);
+    if (on('R7:lines') && countLines(text) > config.max_lines) add(path, 'R7:lines', config.max_lines + 1);
+    const t4 = sourceTextLine(view, { config, register, tracked, as });
+    if (t4 && !pins.pinned.has(path)) add(path, 'T4:source-text', t4);
     const faked = fakes.some((re) => re.test(view.bare));
-    const timer = faked ? 0 : timerLine(view);
+    const timer = faked || !on('T6:timer') ? 0 : timerLine(view);
     if (timer) add(path, 'T6:timer', timer);
-    const clock = faked ? 0 : clockLine(view);
+    const clock = faked || !on('T6:clock') ? 0 : clockLine(view);
     if (clock) add(path, 'T6:clock', clock);
-    const outside = outsideLine(view);
+    const outside = on('T6:outside') ? outsideLine(view) : 0;
     if (outside) add(path, 'T6:outside', outside);
-    const env = envLine(view, config.env_allowed);
+    const env = on('T6:env') ? envLine(view, config.env_allowed) : 0;
     if (env) add(path, 'T6:env', env);
   }
   return out.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
@@ -358,9 +458,13 @@ export function breachesOf({ files, config, register = null, tracked = null }) {
  * `moved`: { new file: old file } from the head's list. `present`: a Set of the head's test
  * files, or null (then nothing is carried). An entry the base does not hold is carried, not
  * `list:grew`, when its old file is gone and the base listed the same rule on it.
- * → { breaches (off the list, plus T1:hub and list:grew), listed (count on the list), stale }.
+ * `relist`: null, or { from, at, allowed: Set of "file\nrule", changed: Set of files } from
+ * relistable (a version bump): an entry the base does not hold and `allowed` has is re-listed,
+ * not `list:grew`.
+ * → { breaches (off the list, plus T1:hub and list:grew), listed (count on the list), stale,
+ *     relisted: [{ file, rule, at }] }.
  */
-export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved = {}, present = null }) {
+export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved = {}, present = null, relist = null }) {
   const on = (file, rule) => (listed[file] ?? []).includes(rule) && !NEVER_LISTED.includes(rule);
   const breaches = all.filter((b) => !on(b.file, b.rule));
   const hits = all.filter((b) => on(b.file, b.rule));
@@ -373,10 +477,16 @@ export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved
     const old = Object.hasOwn(moved, file) ? moved[file] : null;
     return typeof old === 'string' && present !== null && !present.has(old) && (base.listed?.[old] ?? []).includes(rule);
   };
+  const relisted = [];
+  const why = (file) => !relist ? ''
+    : relist.changed.has(file) ? ` (a re-list at ${relist.at} never covers a file this change edits)`
+      : ` (a re-list at ${relist.at} covers only what ${relist.at} finds and ${relist.from} did not)`;
   if (base) {
     for (const file of Object.keys(listed).sort()) {
       for (const rule of [...listed[file]].sort()) {
-        if (base.listed && !(base.listed[file] ?? []).includes(rule) && !carried(file, rule)) breaches.push({ file, rule: 'list:grew', line: 1, say: `${rule}: ${RULES['list:grew']}` });
+        if (!base.listed || (base.listed[file] ?? []).includes(rule) || carried(file, rule)) continue;
+        if (relist?.allowed.has(`${file}\n${rule}`)) relisted.push({ file, rule, at: relist.at });
+        else breaches.push({ file, rule: 'list:grew', line: 1, say: `${rule}: ${RULES['list:grew']}${why(file)}` });
       }
       const was = base.lines?.[file];
       if (listed[file].includes('R7:lines') && Number.isFinite(was) && lineCounts[file] > was) {
@@ -385,7 +495,33 @@ export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved
     }
   }
   breaches.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
-  return { breaches, listed: hits.length, stale };
+  return { breaches, listed: hits.length, stale, relisted };
+}
+
+/**
+ * Whether this change may re-list, from the versions: `from` the base's installed version,
+ * `installed` the worktree's, `running` this file's own. → { open, from, at, why }: open only
+ * when all three are known, the one running is the one installed, and it is newer than the base's.
+ */
+export function relistGate({ from, installed, running }) {
+  const shut = (why) => ({ open: false, from, at: running, why });
+  if (!running) return shut(`this file's own version cannot be read`);
+  if (!from) return shut(`the base's ${PACKAGE} version cannot be read`);
+  if (!installed) return shut(`the installed ${PACKAGE} version cannot be read`);
+  if (installed !== running) return shut(`${running} is running but ${installed} is installed`);
+  if (compareVersions(from, running) >= 0) return shut(`the version did not go up (${from} at the base, ${running} here)`);
+  return { open: true, from, at: running, why: '' };
+}
+
+/**
+ * The entries a bump may re-list: "file\nrule" for each breach in `all` (this version's) that
+ * `asBase` (the same files, run as the base's version) does not hold, on a file `changed` (the
+ * files this change touches) does not hold. Pure.
+ */
+export function relistable({ all, asBase, changed }) {
+  const key = (b) => `${b.file}\n${b.rule}`;
+  const before = new Set(asBase.map(key));
+  return new Set(all.filter((b) => !NEVER_LISTED.includes(b.rule) && !changed.has(b.file) && !before.has(key(b))).map(key));
 }
 
 /** The entries a first list holds for these breaches: { file: [rule, …] }, sorted. */
@@ -395,10 +531,24 @@ export function entriesFor(all) {
   for (const k of Object.keys(entries)) entries[k].sort();
   return Object.fromEntries(Object.keys(entries).sort().map((k) => [k, entries[k]]));
 }
-export const listedText = (entries) => {
-  const rows = Object.keys(entries).map((k) => `    ${JSON.stringify(k)}: ${JSON.stringify(entries[k])}`);
-  return `{\n  "v": ${VERSION},\n  "entries": {${rows.length ? `\n${rows.join(',\n')}\n  ` : ''}}\n}\n`;
+/** The list as written: one line per file; `moved`, when it has lines, after the entries. */
+export const listedText = (entries, moved = {}) => {
+  const block = (map) => {
+    const rows = Object.keys(map).map((k) => `    ${JSON.stringify(k)}: ${JSON.stringify(map[k])}`);
+    return `{${rows.length ? `\n${rows.join(',\n')}\n  ` : ''}}`;
+  };
+  return `{\n  "v": ${VERSION},\n  "entries": ${block(entries)}${Object.keys(moved).length ? `,\n  "moved": ${block(moved)}` : ''}\n}\n`;
 };
+/** `entries` with each "file\nrule" of `keys` added, sorted as the first list is. */
+export function withEntries(entries, keys) {
+  const out = Object.fromEntries(Object.entries(entries).map(([f, r]) => [f, [...r]]));
+  for (const k of keys) {
+    const [file, rule] = k.split('\n');
+    if (!(out[file] ??= []).includes(rule)) out[file].push(rule);
+  }
+  for (const f of Object.keys(out)) out[f].sort();
+  return Object.fromEntries(Object.keys(out).sort().map((f) => [f, out[f]]));
+}
 export function countLines(text) {
   return text.length ? text.split('\n').length - (text.endsWith('\n') ? 1 : 0) : 0;
 }
@@ -419,6 +569,9 @@ export function withDefaults(raw) {
   if (!sc || typeof sc !== 'object' || Array.isArray(sc) || Object.values(sc).some((v) => !Array.isArray(v) || !v.length || !v.every(styleOnly))) {
     throw fail(EXIT.FAILED, `${CONFIG_FILE}: style_contract must be { "<test file>": ["<path or glob ending .css or .scss>", …] }`);
   }
+  if (!Array.isArray(config.pins) || config.pins.some((p) => !p || typeof p !== 'object' || Array.isArray(p))) {
+    throw fail(EXIT.FAILED, `${CONFIG_FILE}: pins must be [{ "file": "<test file>", "rule": "<the rule it guards>", "mutation": "<what turns it red>", "red_before": "<where that red is recorded>" }, …]`);
+  }
   const r = config.reads;
   const json = r && typeof r === 'object' && !Array.isArray(r) && typeof r.json === 'string'
     && Object.keys(r).every((k) => k === 'json' || k === 'key') && (r.key === undefined || r.key === null || typeof r.key === 'string');
@@ -431,7 +584,9 @@ export function withDefaults(raw) {
  * named), or the whole file when the key is null or empty. No map there cannot run (exit 3): an
  * empty register would read as "no test reads anything".
  */
-export function registerOf(file, reads) {
+export function registerOf(file, reads, as = null) {
+  // Before 1.0.2 a key of null or "" fell back to "tests", and no map there read as empty.
+  if (!detects('T4:whole-register', as)) return file?.[reads.key ?? 'tests'] ?? {};
   const key = reads.key === undefined ? 'tests' : reads.key;
   const whole = key === null || key === '';
   const map = whole ? file : file?.[key];
@@ -444,11 +599,12 @@ export function registerOf(file, reads) {
 // The command line: the only part that touches disk and git.
 // ---------------------------------------------------------------------------------------------
 export function parseArgs(argv) {
-  const o = { dir: null, base: null, noBase: false, list: false, init: false, help: false };
+  const o = { dir: null, base: null, noBase: false, list: false, init: false, relist: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--list') o.list = true;
     else if (a === '--init') o.init = true;
+    else if (a === '--relist') o.relist = true;
     else if (a === '--no-base') o.noBase = true;
     else if (a === '--help' || a === '-h') o.help = true;
     else if (a === '--dir' || a === '--base') {
@@ -458,9 +614,50 @@ export function parseArgs(argv) {
     } else throw fail(EXIT.USAGE, `unknown argument ${a}`);
   }
   if (o.base && o.noBase) throw fail(EXIT.USAGE, '--base and --no-base together');
+  if (o.relist && o.init) throw fail(EXIT.USAGE, '--relist and --init together');
+  if (o.relist && o.noBase) throw fail(EXIT.USAGE, '--relist needs a base: it re-lists against the base\'s version');
   return o;
 }
 
+// ---------------------------------------------------------------------------------------------
+// Versions. `read(rel)` gives a file's text, or null: at the base through git, here from disk.
+// ---------------------------------------------------------------------------------------------
+const jsonOrNull = (text) => { if (text == null) return null; try { return JSON.parse(text); } catch { return null; } };
+const exact = (v) => (typeof v === 'string' && SEMVER.test(v) ? v : null);
+/**
+ * The installed version of the package: for each folder in `prefixes` ('' is the repo root), its
+ * package-lock.json, else an exact pin in its package.json; else the orchestrator's own manifest
+ * (SOURCE_MANIFEST). null when none says.
+ */
+export function installedVersion(read, prefixes = ['']) {
+  for (const p of prefixes) {
+    const lock = jsonOrNull(read(`${p}package-lock.json`));
+    const locked = exact(lock?.packages?.[`node_modules/${PACKAGE}`]?.version) ?? exact(lock?.dependencies?.[PACKAGE]?.version);
+    if (locked) return locked;
+    const manifest = jsonOrNull(read(`${p}package.json`));
+    const pinned = exact(manifest?.devDependencies?.[PACKAGE]) ?? exact(manifest?.dependencies?.[PACKAGE]);
+    if (pinned) return pinned;
+  }
+  const own = jsonOrNull(read(SOURCE_MANIFEST));
+  return own?.name === PACKAGE ? exact(own.version) : null;
+}
+/** The folders to read the installed version from: the one that holds node_modules/<PACKAGE> when this file runs from there, then the root. */
+export function installPrefixes(dir, modulePath) {
+  const rel = relative(real(dir), real(modulePath)).split(sep).join('/');
+  const at = rel.startsWith('../') ? -1 : rel.indexOf(`node_modules/${PACKAGE}/`);
+  return at > 0 ? [rel.slice(0, at), ''] : [''];
+}
+/** This file's own version: the manifest beside it (as published), else the orchestrator's package folder. */
+export function ownVersion(modulePath = fileURLToPath(import.meta.url)) {
+  for (const rel of ['package.json', 'test-rules-package/package.json']) {
+    let manifest = null;
+    try { manifest = jsonOrNull(readFileSync(join(dirname(modulePath), rel), 'utf8')); } catch { /* not there */ }
+    if (manifest?.name === PACKAGE && exact(manifest.version)) return manifest.version;
+  }
+  return null;
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return p; } };
 const git = (dir, args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
 const gitOr = (dir, args) => { try { return git(dir, args); } catch { return null; } };
 function readJson(dir, rel) {
@@ -485,7 +682,11 @@ export function movedOf(obj, where) {
   return m;
 }
 
-export function main(argv = [], { log = console.log, error = console.error } = {}) {
+/**
+ * The command line. `running`: this file's version (default: read from its manifest); `modulePath`:
+ * where this file is, to find the folder it is installed in. Both are for tests.
+ */
+export function main(argv = [], { log = console.log, error = console.error, running = undefined, modulePath = fileURLToPath(import.meta.url) } = {}) {
   try {
     const opts = parseArgs(argv);
     if (opts.help) { log(USAGE); return EXIT.CLEAN; }
@@ -497,7 +698,8 @@ export function main(argv = [], { log = console.log, error = console.error } = {
     const tracked = new Set(present);
     const testPaths = present.filter((p) => !p.split('/').includes('node_modules') && matches(config.tests, p) && !matches(config.ignore, p)).sort();
     const files = testPaths.map((path) => ({ path, text: readFileSync(join(dir, path), 'utf8') }));
-    const register = config.reads && typeof config.reads === 'object' ? registerOf(readJson(dir, config.reads.json), config.reads) : null;
+    const registerFile = config.reads && typeof config.reads === 'object' ? readJson(dir, config.reads.json) : null;
+    const register = registerFile ? registerOf(registerFile, config.reads) : null;
     const all = breachesOf({ files, config, register, tracked });
 
     if (opts.init) {
@@ -513,6 +715,8 @@ export function main(argv = [], { log = console.log, error = console.error } = {
     const moved = listedJson ? movedOf(listedJson, LISTED_FILE) : {};
     let base = null;
     let baseNote = 'no base';
+    let relist = null;
+    let gate = null;
     if (!opts.noBase) {
       const ref = opts.base ?? DEFAULT_BASE;
       const mb = gitOr(dir, ['merge-base', ref, 'HEAD'])?.trim();
@@ -533,16 +737,53 @@ export function main(argv = [], { log = console.log, error = console.error } = {
         }
         base = { listed: baseListed, lines };
         baseNote = `base ${mb.slice(0, 12)}${baseListed ? '' : ' (no list there)'}`;
+
+        // Re-listed once per version: only when this change raises the installed version.
+        const prefixes = installPrefixes(dir, modulePath);
+        gate = relistGate({
+          from: installedVersion((rel) => gitOr(dir, ['show', `${mb}:${rel}`]), prefixes),
+          installed: installedVersion((rel) => { try { return readFileSync(join(dir, rel), 'utf8'); } catch { return null; } }, prefixes),
+          running: running === undefined ? ownVersion(modulePath) : running,
+        });
+        if (gate.open) {
+          const changed = new Set([
+            ...git(dir, ['diff', '--name-only', '--no-renames', '-z', mb]).split('\0'),
+            ...git(dir, ['ls-files', '-o', '--exclude-standard', '-z']).split('\0'),
+          ].filter(Boolean));
+          const asBase = breachesOf({ files, config, register: registerFile ? registerOf(registerFile, config.reads, gate.from) : null, tracked, as: gate.from });
+          relist = { from: gate.from, at: gate.at, changed, allowed: relistable({ all, asBase, changed }) };
+          baseNote += `; ${PACKAGE} ${gate.from} → ${gate.at}`;
+        } else if (gate.from && gate.from !== gate.at) baseNote += `; no re-list (${gate.why})`;
       } else baseNote = `no base (${ref} does not resolve)`;
     }
+
+    if (opts.relist) {
+      if (!base) throw fail(EXIT.USAGE, `--relist needs a base: ${baseNote}`);
+      if (!base.listed) throw fail(EXIT.USAGE, `the base has no ${LISTED_FILE}: write the first list with --init`);
+      if (!relist) throw fail(EXIT.USAGE, `nothing may be re-listed: ${gate.why}`);
+      const on = (b) => (listed[b.file] ?? []).includes(b.rule);
+      const add = all.filter((b) => !on(b) && relist.allowed.has(`${b.file}\n${b.rule}`)).map((b) => `${b.file}\n${b.rule}`);
+      if (!add.length) {
+        log(`test-rules: nothing to re-list at ${relist.at} (the base ran ${relist.from})`);
+        return EXIT.CLEAN;
+      }
+      mkdirSync(dirname(join(dir, LISTED_FILE)), { recursive: true });
+      writeFileSync(join(dir, LISTED_FILE), listedText(withEntries(listed, add), moved));
+      for (const k of add) log(`relisted ${k.replace('\n', ' ')}`);
+      log(`test-rules: re-listed at ${relist.at}: ${add.length} entries, written to ${LISTED_FILE} (the base ran ${relist.from})`);
+      return EXIT.CLEAN;
+    }
+
     const lineCounts = Object.fromEntries(files.map((f) => [f.path, countLines(f.text)]));
-    const v = verdict({ all, listed, base, lineCounts, moved, present: new Set(testPaths) });
+    const v = verdict({ all, listed, base, lineCounts, moved, present: new Set(testPaths), relist });
 
     if (opts.list) {
-      log(JSON.stringify({ v: VERSION, breaches: v.breaches, listed: v.listed, stale: v.stale }));
+      log(JSON.stringify({ v: VERSION, breaches: v.breaches, listed: v.listed, stale: v.stale, relisted: v.relisted }));
     } else {
       for (const b of v.breaches) log(`${b.rule} ${b.file}:${b.line} — ${b.say}`);
       for (const s of v.stale) log(`stale ${s.file} ${s.rule} — the breach is gone: delete it from ${LISTED_FILE}`);
+      for (const r of v.relisted) log(`relisted ${r.file} ${r.rule} — a detection newer than the base's ${relist.from} finds it`);
+      if (v.relisted.length) log(`test-rules: re-listed at ${relist.at}: ${v.relisted.length} entries`);
       log(`test-rules: ${files.length} test files, ${v.breaches.length} breach(es), ${v.listed} listed, ${v.stale.length} stale; ${baseNote}${config.fail ? '' : '; report only ("fail": false)'}`);
     }
     return config.fail && (v.breaches.length || v.stale.length) ? EXIT.BREACH : EXIT.CLEAN;
@@ -554,5 +795,4 @@ export function main(argv = [], { log = console.log, error = console.error } = {
   }
 }
 
-const real = (p) => { try { return realpathSync(p); } catch { return p; } };
 if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url))) process.exitCode = main(process.argv.slice(2));