docs(gate): rest check-role-word's comment figures on invariants, not on the ledger's current size (#10044)

The two sample-output sites named in #9947 both stated the regenerated
baseline's size (43) — a figure `--update`, the gate's own sanctioned
remedy, invalidates. Refreshing such a number resets the clock rather
than fixing it, so neither is refreshed here.

Per-site, because they are different things:

- The quoted OLD green line is a FORMAT example. That line no longer
  exists in the program (removed by #9931), so no literal is checkable
  against anything the gate does — the number goes generic (`N`).
- The dead-scan ablation result is a MEASUREMENT. It now rests on the
  cardinality identity the ratchet-DOWN loop enforces — one problem per
  baseline entry, true at every ledger size — instead of a magnitude.
  No bound is stated in its place: a SHRINK-only ledger admits neither a
  durable floor (it rots on the first sanctioned ratchet-down) nor a
  durable ceiling (the same `--update` is also the baseline-EXPANDING
  path #8435 gates).

Two further sites found while measuring: the header listed the ledger's
legitimate contents as an inventory, one entry of which ("ARIA `role=`
in samples") already matches zero baselined files; it now names the
legitimate KINDS instead. And the self-test's scan fixtures are pinned
as synthetic, so nobody "refreshes" them into a figure the tree can
falsify.

Comment prose only: no verdict, exit code, population or threshold
moves. Every changed line is a comment, and the gate's output is
byte-identical before and after.


Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-steve

scripts/check-role-word.mjs

@@ -9,9 +9,14 @@
 // P1 rename wave (#2697 was identifier-driven).
 //
 // This is a RATCHET, not a ban-with-exceptions: existing occurrences are
-// frozen in scripts/role-word-baseline.json (many are legitimate — the
-// better-auth boundary, ARIA `role=` in samples, educational "formerly
-// roles" mentions — and untangling them file-by-file is incremental work).
+// frozen in scripts/role-word-baseline.json, and not all of them are bugs.
+// The legitimate KINDS — vocabulary owned upstream (better-auth's
+// `sys_member.role`), ARIA's `role=` attribute, quoted pre-rename history —
+// are named as KINDS and not as an inventory of the ledger: which of them it
+// actually holds changes with every `--update`, so the same list read as a
+// census goes wrong silently. Untangling the rest file-by-file is
+// incremental work.
+//
 // The check fails when:
 //   • a file NOT in the baseline contains the word, or
 //   • a baselined file's count INCREASES, or
@@ -130,7 +135,12 @@ function newUseMessage(file, count) {
 //
 // The green line used to be, in full:
 //
-//   check-role-word: OK (43 baselined file(s), no new occurrences).
+//   check-role-word: OK (N baselined file(s), no new occurrences).
+//
+// N is written generically because this line no longer exists in the program.
+// It can never print again, at any size, so no literal here would be checkable
+// against anything the gate does — and the next `--update` could only make one
+// wrong, never right again. The quote is carried for its SHAPE.
 //
 // Every number in it came from the LEDGER. `current` holds only the files that
 // still carry the word, and a green run is precisely the run where its key set
@@ -141,11 +151,21 @@ function newUseMessage(file, count) {
 // scan that reads nothing drops every baselined file out of `current`, and the
 // ratchet-DOWN branch below then reports one "clean/gone" problem per baselined
 // file. Measured on this tree — ROOTS pointed at two non-existent directories,
-// ledger untouched — `43 problem(s)`, exit 1. That protection is a side effect
-// of still owing debt, and it evaporates at the exact moment this ratchet
-// succeeds at its purpose: with the ledger empty, `current = {}` and
-// `baseline = {}` raise nothing in either direction, and the same ablation
-// printed
+// ledger untouched — exit 1, raising exactly one problem per baselined file.
+// The magnitude is deliberately not written down, and no bound stands in its
+// place: the ratchet-DOWN loop below walks `Object.entries(baseline)` and
+// raises one error for every entry missing from `current`, so a dead scan
+// raises as many problems as the ledger holds — an identity that survives
+// every `--update`, at any ledger size, including the empty one. A SHRINK-only
+// ledger admits no durable bound to state instead: a floor rots on the first
+// sanctioned ratchet-down (the very remedy this gate tells authors to run),
+// and a ceiling rots too, because the same `--update` is also the
+// baseline-EXPANDING path the #8435 marker above gates.
+//
+// That protection is a side effect of still owing debt, and it evaporates at
+// the exact moment this ratchet succeeds at its purpose: with the ledger
+// empty, `current = {}` and `baseline = {}` raise nothing in either direction,
+// and the same ablation printed
 //
 //   check-role-word: OK (0 baselined file(s), no new occurrences).   EXIT=0
 //
@@ -269,6 +289,12 @@ function selfTest() {
   //
   // Interpolated counts again, so the source proves nothing about the rendered
   // sentence — driven here instead, in the states that used to be identical.
+  //
+  // These counts are SYNTHETIC fixtures, not a reading of the tree: every
+  // assertion below closes over them, so they stay correct however the real
+  // corpus moves. ⛔ Do not "refresh" them to match a live scan — that would
+  // turn a closed fixture into a figure the tree can falsify, which is the
+  // very defect the comment sites above were cleaned of.
   const SCANNED = [{ root: 'content/docs', files: 179 }, { root: 'skills', files: 36 }];
   const DEAD_SCAN = [{ root: 'content/docs', files: 0 }, { root: 'skills', files: 0 }];
   const PAID_OFF = {};