@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/fitness-checks-vocabulary.js

@@ -0,0 +1,392 @@
+// scripts/bongos/fitness-checks-vocabulary.js — Checks 19 and 19b: "role" names a
+// craft, never a rank (ADR 0174), and a membership is a membership_kind (ADR 0177).
+//
+// Carved out of scripts/bongos/fitness.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring that file under the 1,500-line ratchet. A STRUCTURAL
+// move: the lines below are fitness.js's originals unchanged, and fitness.js
+// imports every name straight back, so the CHECKS registry and the module's
+// public surface (which the tests read heavily) are untouched.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { CORE_ROOT, rel } = require('./fitness-lib.js');
+
+const VOCAB_ALLOW = [
+  {
+    file: 'modules/government/config.js',
+    match: 'roles',
+    why: 'the legacy INSTANCE-config key fallback. The core ships `ranks`, but an '
+       + 'external self-hosted instance may still have a config/government.json '
+       + 'authored as `roles`; reading it is what stops their templates vanishing '
+       + 'on upgrade. Removing this line would break them silently.',
+  },
+  {
+    file: 'modules/government/config.js',
+    match: 'governance_role_labels',
+    why: 'the legacy ENV-VAR fallback. <PREFIX>_GOVERNMENT_RANK_LABELS is the current '
+       + 'name, but an operator sets this in their own shell or env file, outside this '
+       + 'repo, so the old spelling is still read. Dropping it would silently stop '
+       + 'honouring a label override someone already configured.',
+  },
+  {
+    file: 'modules/government/board.js',
+    match: 'governancepasscredit',
+    why: 'the R02 pass-event contract (docs/specs/board-room-pass-event-contract.md, agreed '
+       + 'cross-goal 2026-08-17) names the economy-side award awardIdeaGovernancePassCredit, '
+       + 'matching the credit_log reason family idea.credit.governance_pass:<id> that streams '
+       + '1-3 share. The board calls the CONSUMER\'s agreed method name — renaming it here '
+       + 'would break the contract, and the reason strings are durable ledger rows. Scoped to '
+       + 'the method name, so a stray "governance" elsewhere in board.js still reds the build.',
+  },
+  {
+    file: 'modules/government/module.json',
+    match: 'role',
+    why: 'the manifest states the rule itself — "The word `role` is deliberately '
+       + 'absent here". Meta-commentary about the ban has to be able to name it.',
+  },
+];
+
+// A line CITING a durable artifact by its real name: an ADR filename, the
+// docs/governance/ evidence folder, one of the already-applied migrations, or
+// the cross-goal pass-event contract. These names are permanent (see the
+// header), so a reference to one is a citation, not drift.
+//
+// The migration family is `govern(ance|ment)_NNN` on purpose. government_001
+// RENAMED the governance_NNN family to government_NNN, so half the applied
+// migrations on disk carry each spelling and BOTH are permanent — and the
+// rename migration's own filename (`government_001_rename_from_governance.sql`)
+// says the banned word while matching neither half of the old regex. That is
+// not drift; it is the one filename that has to name what it renamed.
+//
+// docs/specs/board-room-pass-event-contract.md is here for the same reason a
+// migration filename is: it is the agreed cross-goal name of the economy-side
+// award (awardIdeaGovernancePassCredit) and the credit_log reason family
+// idea.credit.governance_pass:<id>. Those are durable ledger rows and another
+// goal's method signature — a line pointing at the contract is citing a name
+// this surface does not own and cannot rename.
+const VOCAB_HISTORICAL_REF = /docs\/adr\/|docs\/governance\/|docs\/session-logs\/|govern(?:ance|ment)_0\d\d|board-room-pass-event-contract/;
+
+// Naming the RULE stays legal — a line that cites ADR 0174 or the task that
+// built the wall is meta-commentary about the ban, and meta-commentary has to
+// be able to say the banned word. Same principle as check 19b's
+// GOAL_VOCAB_CITATION, and deliberately preferred over a per-file VOCAB_ALLOW
+// entry: the exemption belongs to the CITATION, not to whichever file happens
+// to hold it today. (Adding '.md' to VOCAB_EXTS brought the module's own
+// nested CLAUDE.md into scope — the file that TEACHES this rule, which states
+// it in the same breath. Three allowlist entries would have taken the cap of 5
+// to its limit for lines whose only sin is quoting the rule correctly.)
+const VOCAB_CITATION = /ADR 0174|task 1003008/;
+
+const VOCAB_SURFACE = [
+  'modules/government',
+  'modules/hall-ui/public/government.js',
+  'modules/hall-ui/public/government.html',
+  'modules/hall-ui/public/government.css',
+  // ADR 0266 carved the Board Room out of government.js onto its own page. The
+  // wall follows the SURFACE, not the filename — without these two rows the
+  // room's own files would have left the wall's scope, which is how a renamed
+  // file quietly drops an enforcement it used to be held to.
+  'modules/hall-ui/public/board-room.js',
+  'modules/hall-ui/public/board-room.html',
+  'modules/hall-ui/public/board-room.css',
+];
+// '.md' is load-bearing, not tidiness (task 1003120). A nested CLAUDE.md is
+// INSTRUCTION: it loads on demand for every agent working in the module, and
+// the agent that reads the wrong vocabulary there goes on to write it into the
+// code. Leaving markdown unscanned is how modules/government/CLAUDE.md came to
+// assert the INVERSE of ADR 0174 and survive a criterion review (task 1003118).
+// The doc surface is the higher-leverage one to guard, and it was the unguarded one.
+const VOCAB_EXTS = new Set(['.js', '.json', '.html', '.css', '.md']);
+const VOCAB_BANNED = [
+  { re: /\brole/i,       label: 'role',       hint: '"role" is reserved for the crafts (Artist / Ideator / Builder). On this surface the noun is RANK.' },
+  { re: /governance/i,    label: 'governance', hint: 'the pre-ADR-0174 name of this surface. It is the GOVERNMENT now.' },
+];
+
+function vocabFilesToScan() {
+  const out = [];
+  const walk = (abs, rel) => {
+    let st;
+    try { st = fs.statSync(abs); } catch { return; }
+    if (st.isDirectory()) {
+      // the historical migrations keep their names + bodies (see header)
+      if (rel.endsWith('/migrations')) return;
+      for (const e of fs.readdirSync(abs)) walk(path.join(abs, e), `${rel}/${e}`);
+      return;
+    }
+    if (VOCAB_EXTS.has(path.extname(abs))) out.push({ abs, rel });
+  };
+  for (const s of VOCAB_SURFACE) walk(path.join(CORE_ROOT, s), s);
+  return out;
+}
+
+// ── Check 19b — the FOURTH and FIFTH "role": a membership is not a craft either ─
+//
+// task 1003013 / ADR 0177. ADR 0174 reserved `role` for the three crafts and R07
+// (checkVocabularyWall above) enforces it on the GOVERNMENT surface — deliberately
+// only there, because `builders.system_role` is a core machine-identity column and
+// Discord's API owns its own "role" noun. Goal membership was a fourth,
+// independent use of the word (`goal_members.role` = 'lead' | 'member'), which is
+// exactly why it survived the rename: the rule was silent on it, as designed.
+//
+// So this is a SECOND narrow wall rather than a widened first one — same reason the
+// first was scoped: the honest unit is a SURFACE, not the repo. Two surfaces carry
+// a membership, and both now say `membership_kind`:
+//   • GOAL membership (`goal_members`, task 1003013) — the routes and pure gate that
+//     decide it, the hall page that renders it, and (line-scoped) the membership SQL
+//     in modules/lifecycle/db.js;
+//   • PROJECT membership on the hub (`platform_identity_project_memberships`, task
+//     1003090) — whose old VALUE 'builder' was itself a craft name. Its check-in
+//     route keeps reading a legacy `role` field for the cross-version federation
+//     window (other instances upgrade on their own schedule), so the lines that
+//     handle that legacy field cite the task and are exempt like any other citation.
+//
+// Naming the rule stays legal — a line that cites ADR 0174 / ADR 0177 / task
+// 1003013 is meta-commentary about the ban, the same principle as
+// VOCAB_HISTORICAL_REF above. `role="…"` is stripped first: that is HTML's ARIA
+// attribute, a different word spelled the same.
+const GOAL_VOCAB_SURFACE = [
+  'modules/lifecycle/routes/goals.js',
+  'modules/lifecycle/goal-authz.js',
+  'modules/lifecycle/routes/done-when.js',
+  'modules/hall-ui/public/goals-page.js',
+  'modules/hall-ui/public/goals.html',
+  'modules/hall-ui/public/goals.css',
+  // The FIFTH use (task 1003090): the hub's coarse project membership.
+  'modules/platform-identity/platform-identity.js',
+  'modules/platform-identity/routes/my-projects.js',
+];
+// modules/lifecycle/db.js is 5k+ lines and legitimately says "role" about ranks
+// (the rank-sync port, builders.system_role). Scanning it whole would need an
+// allowlist longer than the rule; scanning the LINES THAT NAME THE TABLE catches
+// the only thing that can regress here — a membership query reaching for the old
+// column — with no false positives to excuse.
+// task 1003204 (goal 1000079) split that 5k-line file into db.js (a re-export
+// facade) + twelve db-*.js units, so the membership SQL is no longer in db.js at
+// all. Enumerate the family from disk rather than naming one file: a line-scoped
+// scan costs nothing on the units that hold no membership SQL, and a future
+// re-carve cannot silently disarm the rule by moving the queries again.
+const LIFECYCLE_DB_FILES = (() => {
+  const dir = path.join(CORE_ROOT, 'modules', 'lifecycle');
+  try {
+    return fs.readdirSync(dir)
+      .filter((f) => f === 'db.js' || (f.startsWith('db-') && f.endsWith('.js')))
+      .sort()
+      .map((f) => `modules/lifecycle/${f}`);
+  } catch { return ['modules/lifecycle/db.js']; }
+})();
+const GOAL_VOCAB_LINE_SCOPED = [
+  ...LIFECYCLE_DB_FILES.map((file) => ({ file, mustMention: /goal_members/ })),
+  // sso.js is the federation surface: only the lines that name the membership table
+  // or its upsert are in scope, so the file's other server-to-server prose stays out.
+  { file: 'modules/platform-identity/routes/sso.js', mustMention: /project_memberships|upsertMembership/ },
+];
+const GOAL_VOCAB_CITATION = /ADR 017[47]|task 1003013|task 1003090/;
+
+function checkGoalMembershipVocabulary() {
+  const violations = [];
+  let scanned = 0;
+  const scanFile = (rel, lineFilter = null) => {
+    const abs = path.join(CORE_ROOT, rel);
+    let src;
+    try { src = fs.readFileSync(abs, 'utf8'); } catch { return; }
+    scanned += 1;
+    src.split('\n').forEach((line, i) => {
+      if (lineFilter && !lineFilter.test(line)) return;
+      const scanLine = line.replace(/\srole\s*=\s*("[^"]*"|'[^']*')/g, ' ');
+      if (!/\brole/i.test(scanLine)) return;
+      if (GOAL_VOCAB_CITATION.test(scanLine)) return;
+      violations.push(`${rel}:${i + 1}: "role" — a membership is a 'membership_kind' (ADR 0174 reserves "role" for the crafts; ADR 0177).  →  ${line.trim().slice(0, 90)}`);
+    });
+  };
+  for (const rel of GOAL_VOCAB_SURFACE) scanFile(rel);
+  for (const { file, mustMention } of GOAL_VOCAB_LINE_SCOPED) scanFile(file, mustMention);
+  return {
+    name: 'a membership is a "membership_kind", never a role (ADR 0177)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} membership-surface file(s) scanned (${GOAL_VOCAB_SURFACE.length} whole — goal + project membership — plus `
+        + `${GOAL_VOCAB_LINE_SCOPED.length} line-scoped to the lines naming the membership tables); no allowlist — `
+        + 'a line that CITES the rule is the only exemption.',
+  };
+}
+
+function checkVocabularyWall() {
+  const violations = [];
+  let scanned = 0;
+  for (const { abs, rel } of vocabFilesToScan()) {
+    scanned += 1;
+    const lines = fs.readFileSync(abs, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      // `role="…"` is HTML's own ARIA attribute — a different word that happens to
+      // be spelled the same. Strip attributes before matching rather than
+      // allowlisting each occurrence: this is a property of HTML, not of any one file.
+      const scanLine = line.replace(/\srole\s*=\s*("[^"]*"|'[^']*')/g, ' ');
+      for (const b of VOCAB_BANNED) {
+        if (!b.re.test(scanLine)) continue;
+        // A REFERENCE to a historical artifact by its real name is not a
+        // vocabulary violation — it is a citation. The artifacts themselves are
+        // excluded by construction (see the header); naming one has to be legal
+        // too, or the code could not point at the migration that created its own
+        // tables. Same principle, applied to the line rather than the file.
+        if (VOCAB_HISTORICAL_REF.test(scanLine)) continue;
+        // A line that CITES the rule is meta-commentary about the ban, not an
+        // instance of it. Costs no allowlist entry and travels with the sentence.
+        if (VOCAB_CITATION.test(scanLine)) continue;
+        const excused = VOCAB_ALLOW.some((a) => a.file === rel && scanLine.toLowerCase().includes(a.match));
+        if (excused) continue;
+        violations.push(`${rel}:${i + 1}: "${b.label}" — ${b.hint}  →  ${line.trim().slice(0, 90)}`);
+      }
+    });
+  }
+  return {
+    name: 'the word "role" means a craft, never a rank (ADR 0174)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} government-surface file(s) scanned for "role"/"governance" (${[...VOCAB_EXTS].sort().join(' ')}); `
+        + `${VOCAB_ALLOW.length} documented allowlist entr(y|ies), plus the citation rule. `
+        + 'Historical migrations + docs/adr are excluded by construction, not suppressed.',
+  };
+}
+
+// ── Check 19c — a rename sweep that ate its own arrow (task 1003120) ─────────
+//
+// THE HOLE CHECK 19 CANNOT SEE. Checks 19 and 19b grep for a BANNED WORD, so
+// they are structurally blind to the damage that actually happened in task
+// 1003118: a find-and-replace ran over a doc that was DESCRIBING the rename, and
+// swept BOTH sides of every rename pair. `governance` → `government` became
+// `government` → `government`. Not one banned word survives that edit, so the
+// wall passed — while the nested CLAUDE.md now taught the next agent that the
+// old name and the new name were the same word, and asserted the inverse of
+// ADR 0174 through a criterion review.
+//
+// An arrow between two identical names states nothing. It is only ever the
+// fossil of a sweep, so flagging the SHAPE catches the defect on the day it
+// lands, with no vocabulary to enumerate. Measured on the whole tree: the one
+// hit outside this surface is ADR 0194's `open` → `open`, a real mapping
+// sentence — which is why the check is scoped to the government surface (the
+// files the rename actually swept) rather than run repo-wide.
+const RENAME_IDENTITY_RE = /`([\w./-]+)` *(?:→|->) *`\1`/;
+
+function checkGovernmentRenameIdentity() {
+  const violations = [];
+  let scanned = 0;
+  for (const { abs, rel } of vocabFilesToScan()) {
+    scanned += 1;
+    fs.readFileSync(abs, 'utf8').split('\n').forEach((line, i) => {
+      const m = RENAME_IDENTITY_RE.exec(line);
+      if (!m) return;
+      violations.push(`${rel}:${i + 1}: \`${m[1]}\` → \`${m[1]}\` — a rename arrow between two IDENTICAL names states nothing. `
+        + 'A sweep ate one side of the pair (task 1003118); restore the name it renamed FROM.'
+        + `  →  ${line.trim().slice(0, 90)}`);
+    });
+  }
+  return {
+    name: 'a rename arrow names two different things (task 1003120)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} government-surface file(s) scanned for \`X\` → \`X\` pairs; no allowlist — `
+        + 'an arrow between identical names has no legitimate form to excuse.',
+  };
+}
+
+
+// ── Check 19d — "stealth" is the PRODUCT's word, not the gate's (task 1003152) ─
+//
+// The third vocabulary wall, and the same defect as ADR 0174's "role": one word,
+// two live meanings, close to OPPOSITE. `platform_identity_projects.visibility =
+// 'stealth'` is a project that IS on the public orbs map — anonymous, rendered as
+// a black hole, refusing applications, but published and visible; only its
+// identity is withheld. The pre-launch gate is the reverse: the whole instance is
+// UNREADABLE without a password. ADR 0182 locks the product sense to the orb
+// metaphor via goal 1000046's own criterion, so the PRODUCT keeps the word and
+// the INFRA half renamed (owner decision, 2026-09-09).
+//
+// SCOPED TO THE INFRA SURFACE, for the same reason check 19 is scoped to the
+// government surface: ~16 files carry the product sense legitimately, and a
+// repo-wide ban would have to allowlist every one of them — an allowlist longer
+// than the rule. The honest unit is a SURFACE.
+//
+// NO ALLOWLIST. Two exemptions, both properties of a line rather than a file:
+// a line naming one of the four documented COMPATIBILITY identifiers (the live
+// cookie, the HMAC label, the legacy submit path, the deprecated env var — see
+// prelaunch-gate.js's header for why each stayed), and a line CITING the rename
+// or the other meaning. Everything else is drift.
+// tests/prelaunch_gate.mjs is deliberately NOT here, the same way check 19's
+// mutation test sits outside the government surface: that file's job includes
+// PLANTING the banned word to prove the rule can fail, and a wall that forbids
+// its own negative test can only be satisfied by deleting the evidence.
+const PRELAUNCH_SURFACE = [
+  'src/bongos/prelaunch-gate.js',
+  'src/bongos/platform-visibility-gate.js',
+];
+// serve-internal.js is 1,500+ lines and mounts every surface on the instance;
+// scanning it whole would drag in prose about the product's visibility. The
+// lines that name the GATE are the only ones that can regress here.
+const PRELAUNCH_LINE_SCOPED = [
+  { file: 'src/bongos/serve-internal.js', mustMention: /prelaunch|PRE-LAUNCH/i },
+];
+const PRELAUNCH_COMPAT = /cb_stealth|stealth-v1|__stealth|STEALTH_PASSWORD/;
+const PRELAUNCH_CITATION = /task 1003152|ADR 0182|stealth-gate\.js|platform_identity_projects/;
+
+function checkPrelaunchVocabulary() {
+  const violations = [];
+  let scanned = 0;
+  const scanFile = (rel, lineFilter = null) => {
+    const abs = path.join(CORE_ROOT, rel);
+    let src;
+    try { src = fs.readFileSync(abs, 'utf8'); } catch { return; }
+    scanned += 1;
+    src.split('\n').forEach((line, i) => {
+      if (lineFilter && !lineFilter.test(line)) return;
+      if (!/stealth/i.test(line)) return;
+      if (PRELAUNCH_COMPAT.test(line)) return;
+      if (PRELAUNCH_CITATION.test(line)) return;
+      violations.push(`${rel}:${i + 1}: "stealth" — on the pre-launch surface the word is PRELAUNCH. `
+        + '"stealth" belongs to the PRODUCT\'s visibility axis (ADR 0182), which means almost the opposite.'
+        + `  →  ${line.trim().slice(0, 90)}`);
+    });
+  };
+  for (const rel of PRELAUNCH_SURFACE) scanFile(rel);
+  for (const { file, mustMention } of PRELAUNCH_LINE_SCOPED) scanFile(file, mustMention);
+  return {
+    name: 'the pre-launch gate is PRELAUNCH; "stealth" is the product\'s word (task 1003152)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} pre-launch-surface file(s) scanned (${PRELAUNCH_SURFACE.length} whole plus `
+        + `${PRELAUNCH_LINE_SCOPED.length} line-scoped to the lines naming the gate); no allowlist — `
+        + 'a documented compatibility identifier or a line CITING the rename are the only exemptions.',
+  };
+}
+
+module.exports = {
+  GOAL_VOCAB_CITATION,
+  GOAL_VOCAB_LINE_SCOPED,
+  GOAL_VOCAB_SURFACE,
+  LIFECYCLE_DB_FILES,
+  PRELAUNCH_CITATION,
+  PRELAUNCH_COMPAT,
+  PRELAUNCH_LINE_SCOPED,
+  PRELAUNCH_SURFACE,
+  RENAME_IDENTITY_RE,
+  VOCAB_ALLOW,
+  VOCAB_BANNED,
+  VOCAB_CITATION,
+  VOCAB_EXTS,
+  VOCAB_HISTORICAL_REF,
+  VOCAB_SURFACE,
+  checkGoalMembershipVocabulary,
+  checkGovernmentRenameIdentity,
+  checkPrelaunchVocabulary,
+  checkVocabularyWall,
+  vocabFilesToScan,
+};

package/scripts/bongos/fitness-checks-write-validation.js

@@ -0,0 +1,157 @@
+// scripts/bongos/fitness-checks-write-validation.js — Check 18 (BV1 R12 / task 1999,
+// ADR 0118): every body-reading write route validates its body.
+//
+// Carved out of scripts/bongos/fitness.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring that file under the 1,500-line ratchet. A STRUCTURAL
+// move: the lines below are fitness.js's originals unchanged, and fitness.js
+// imports every name straight back, so the CHECKS registry and the module's
+// public surface (which the tests read heavily) are untouched.
+
+'use strict';
+
+const genApiDocs = require('./gen-api-docs'); // R12 (#1999): reuse the route model (readsBody/validated) that drives the OpenAPI spec
+
+// ============================================================================
+// Check 18 — every write route validates its body (BV1 R12 / task 1999 / ADR 0118)
+// ============================================================================
+//
+// Criterion api-validation: "the build fails on an unvalidated write route." R11
+// (#1998) gave every body-reading write route a strict validateOrRespond schema
+// (code-first, spec-driven — ADR 0118); this LOCKS that in. Reusing the SAME
+// route model that generates the OpenAPI spec (gen-api-docs.extractModel —
+// readsBody + validated), a POST/PUT/PATCH/DELETE that reads req.body must carry
+// a validateOrRespond()/validate(req.body) schema. Hard-zero (no ratchet — the
+// R11 sweep already reached 100%): a NEW write route that reads a body but
+// declares no schema fails the build immediately, so unknown/typo'd fields can
+// never again be silently dropped.
+//
+// EXEMPT — the builder-settings /me/*-prefs routes. Their bodies are DYNAMIC-KEY
+// maps ({ "<skill|sound|event-id>": <value> }, or a single-key toggle) that a
+// FIXED field schema cannot express; they validate via their module lib's
+// validatePatch()/validate() (which already rejects unknown keys with a 422). A
+// fixed strict schema would wrongly reject the valid dynamic keys — so these are
+// validated-by-lib, not by validateOrRespond. Documented per-route below; see
+// learning #133 / ADR 0118. Adding a route here is a deliberate, reviewable act.
+const WRITE_VALIDATION_EXEMPT = new Set([
+  'PATCH /me/skill-prefs',        // { "<skill>": "<model>"|null } — dynamic keys; skillPrefs.validatePatch
+  'PATCH /me/sound-prefs',        // { "<sound>": <bool>|null }    — dynamic keys; soundPrefs.validatePatch
+  'PATCH /me/event-sound-prefs',  // { "<event>": "<variant>"|null } — dynamic keys; eventSoundPrefs.validatePatch
+  'PATCH /me/wandering',          // { wandering: 0..3|null }      — rank-capped; wanderingPrefs.validatePatch
+  'PATCH /me/interaction',        // interaction profile           — interactionPrefs.validatePatch
+  'PATCH /me/model-allocation',   // per-slot tiers                — modelAllocPrefs.validatePatch
+  'PATCH /me/render',             // { widgets: <bool>|null }      — renderPrefs.validatePatch
+  'PATCH /me/display-name',       // { display_name }              — displayName.validate
+  'PATCH /me/profile-nudge',      // { dismissed: <bool>|null }    — profileNudgePrefs.validatePatch
+  // Not a JSON body at all: the raw .docx bytes (task 1004320, ADR 0341 D12), capped by
+  // the route's own express.raw parser and read by docx.readUpload, which refuses
+  // anything that is not a bounded, readable Word file (not_a_docx / upload_too_large).
+  'POST /copy-desk/pages/:pageId/draft.docx',
+  // Not a JSON body either: the raw module tarball (task 1004271, ADR 0338 D1), capped by
+  // the route's express.raw parser and read by module-artifact.verifyModuleArtifact, which
+  // recomputes every hash and refuses anything that is not a well-formed module version.
+  'POST /store/modules/:key/versions',
+  // Not a JSON body: the raw UAT recording (task 1004392, ADR 0351), capped by the
+  // route's express.raw parser and read by criterion-uat.screenRecording, which
+  // refuses anything that is not a bounded mp4/webm whose bytes match its type.
+  'POST /done-when/:criterionId/uat/recording',
+]);
+
+// KNOWN GAPS, NOT EXEMPTIONS (task 1002551 / BV1.R109b → tracked by task 1002552).
+//
+// These three are NOT validated-by-lib and do NOT belong in WRITE_VALIDATION_EXEMPT
+// above — they are genuine ADR 0118 gaps that must grow a validateOrRespond schema.
+// They surface here only because R109b taught route discovery to see MULTI-LINE
+// `router.<method>(` declarations: this check reuses gen-api-docs.extractModel(), so
+// the same regex hole that hid them from the rank auditor hid them from Check 18 too.
+// They are pre-existing (never validated), not a regression.
+//
+// They are recorded rather than fixed because modules/*/routes/*.js was being migrated
+// concurrently by BV1.R105, so editing those files would have collided. This is the
+// Check-17 ratchet posture: a NAMED, non-growing baseline. The list may only ever
+// SHRINK — a new unvalidated write route is not on it and still hard-fails the build,
+// and a stale entry (one that HAS been fixed) also fails, so the list cannot rot.
+// Delete this constant when task 1002552 lands and Check 18 returns to hard-zero.
+// EMPTY as of BV1.R109c (task 1002552) — all three original entries now validate.
+// Kept (rather than deleted) as the ratchet itself: an empty named baseline states
+// the invariant is hard-zero, and any future entry has to be added deliberately.
+const WRITE_VALIDATION_BASELINE = new Set([]);
+
+function scanUnvalidatedWriteRoutes(model = genApiDocs.extractModel()) {
+  const unvalidated = [];
+  const baselineSeen = new Set();
+  for (const r of model) {
+    if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(r.method)) continue;
+    // Only routes that actually read a body have an input surface to validate;
+    // a write that ignores req.body has nothing to declare.
+    if (!r.body || !r.body.readsBody || r.body.validated) continue;
+    const key = `${r.method} ${r.route}`;
+    if (WRITE_VALIDATION_EXEMPT.has(key)) continue;
+    if (WRITE_VALIDATION_BASELINE.has(key)) { baselineSeen.add(key); continue; }
+    unvalidated.push(`${key}  [${r.file}]`);
+  }
+  // A baseline entry that no longer reports as unvalidated has been FIXED — it must be
+  // removed, or the list would quietly license a future regression on that same route.
+  for (const key of WRITE_VALIDATION_BASELINE) {
+    if (!baselineSeen.has(key)) {
+      unvalidated.push(`${key}  [STALE BASELINE — this route now validates; remove it from WRITE_VALIDATION_BASELINE in scripts/bongos/fitness.js]`);
+    }
+  }
+  return unvalidated;
+}
+
+function checkWriteRoutesValidated() {
+  const unvalidated = scanUnvalidatedWriteRoutes();
+  const violations = [];
+  if (unvalidated.length) {
+    violations.push(
+      `${unvalidated.length} write route(s) read req.body but declare NO validateOrRespond/validate schema (ADR 0118 / R11 requires one so unknown fields are rejected via the ADR-0116 envelope): ${unvalidated.join('; ')}. Add a strict validateOrRespond(req, res, { … }) listing every field the handler reads (see learning #133). A dynamic-key body validated by a module lib belongs in WRITE_VALIDATION_EXEMPT with a one-line reason.`
+    );
+  }
+  return {
+    name: 'every write route validates its body (ADR 0118 / R12)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `body-reading POST/PUT/PATCH/DELETE routes must call validateOrRespond/validate (${WRITE_VALIDATION_EXEMPT.size} dynamic-key prefs routes validate by lib; ${WRITE_VALIDATION_BASELINE.size} known gaps tracked by task 1002552, list may only shrink); ${unvalidated.length} unvalidated.`,
+  };
+}
+
+
+// ── Check 19 — the ADR 0174 vocabulary wall (goal 1000068 R07, task 1003008) ──
+//
+// "Role" means ONE thing in this codebase: a craft — Artist, Ideator, or Builder.
+// The permission system is the GOVERNMENT and the positions in it are RANKS.
+// Before ADR 0174 the same word named both, and goal 1000066 was about to claim
+// it for the crafts while modules/governance/ still used it for the ladder. This
+// check is what stops that collision reforming the first time someone copies an
+// old file.
+//
+// TWO RULES, both scoped to the GOVERNMENT SURFACE — not the whole repo. A repo-
+// wide ban would be wrong: `builders.system_role` is a core column for machine
+// identities, Discord's API owns its own "role" noun, and the crafts are supposed
+// to use the word.
+//
+//   1. no "role" under modules/government/ or on the Government hall page
+//   2. no "governance" there either — the old name of the same surface
+//
+// EXCLUDED BY CONSTRUCTION (not by allowlist):
+//   • modules/government/migrations/governance_*.sql — the already-applied
+//     migrations keep their filenames forever (schema_migrations is stem-keyed;
+//     renaming one re-runs it, and governance_002 is a seed/backfill). Their
+//     bodies necessarily name the pre-rename tables they created.
+//   • docs/adr/, docs/session-logs/, docs/governance/ — the historical record.
+//     An ADR describes a decision at a point in time; rewriting it to match
+//     today's vocabulary would erase the evidence that the words changed.
+//
+// The ALLOWLIST below is deliberately tiny and each entry carries its reason. A
+// rule that passes because everything is suppressed reads as evidence while
+// proving nothing — if this list grows, that is the signal to finish the rename,
+// not to add a line.
+
+module.exports = {
+  WRITE_VALIDATION_BASELINE,
+  WRITE_VALIDATION_EXEMPT,
+  checkWriteRoutesValidated,
+  scanUnvalidatedWriteRoutes,
+};