@bongos/core 1.19.332 → 1.19.334

package/scripts/gds/fitness-checks-identity.js

@@ -0,0 +1,320 @@
+// scripts/gds/fitness-checks-identity.js — the checks that keep the portable core
+// free of any one host's identity: kernel prompts (BV1.R76), the neutral config
+// packs (BV1.R102) and the design contract.
+//
+// Carved out of scripts/gds/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, MODULE_ROOTS, REPO_ROOT, rel } = require('./fitness-lib.js');
+
+// ============================================================================
+// Check 13 — portable code carries no hardcoded host-brand identity (BV1.R76 + task 1705)
+// ============================================================================
+//
+// The portable core (src/bongos/**) and every feature MODULE (modules/**) must read
+// the instance's product/world name + domains from branding() / window.__BRANDING__,
+// never a baked-in "Off the Boats" / "Amazonprimea" / apex domain (ADR 0062 §3/§5;
+// the branding contract). R76 shipped this as an 8-FILE allowlist over the kernel
+// LLM-prompt headers; task 1705 WIDENS it to a directory-wide scan, so ANY new brand
+// leak in portable code reds the build — not just the nine files someone remembered
+// to list. (The 2026-07-02 separation audit found five leaks the old allowlist missed:
+// the rank/graduation broadcasts, the auth error-page title, the apex-origin default,
+// and ~124 served-UI strings.) Comments are stripped first (block /* */, HTML
+// <!-- -->, and JS // line comments via a `://`-safe strip so a URL is never
+// truncated) because the de-brand rationale legitimately names the old literals in
+// prose. Instance-injected placeholders ({{worldName}} etc.) carry no literal, so
+// they pass untouched.
+//
+// EXCLUDED — the small instance-1 / ops allowlist (task 1705):
+//   - modules/game/**  — the INSTANCE'S OWN PRODUCT. A product's identity is
+//     instance-specific by definition (a vanilla instance ships a different product,
+//     or none); it is not portable-platform code the branding pack can neutralize.
+//     A documented carve-out, not an oversight.
+//   - generated / build-output dirs (no authored source).
+const PROMPT_IDENTITY_LITERALS = [
+  /off the boats/i,
+  /amazonprimea/i,
+];
+// Scan roots (recursive) + kernel-prompt CLIs that live outside them.
+// scripts/gds joined at task 1002427: the builder CLI was UNSCANNED, which is how
+// paste-token.js kept a hardcoded 'https://amazonprimea.com' long after the task
+// 1002201 sweep replaced that literal everywhere else. The straggler surfaced as a
+// 401 that locked a builder out of re-authenticating — a valid token verified
+// against the wrong host — and nothing in CI could see it (idea 1000564).
+// Widened scripts/gds → ALL of scripts/ at task 1002756: migrate.sh's hardcoded
+// founder DB default (task 1002755) survived every gate because the detector never
+// saw the file — a gate that cannot see the file class the bug lives in is worse
+// than no gate, because it is trusted.
+const IDENTITY_SCAN_ROOTS = ['src/bongos', 'modules', 'scripts'];
+const IDENTITY_SCAN_EXTRA_FILES = [];
+// PERMANENT, COUNTED carve-outs for the scripts/gds root — {file: allowed hits}.
+//
+// Widening the root (task 1002427) surfaced 23 files. Task 1002428 swept them:
+// every one whose literal was a real runtime bug is FIXED (a wrong instance URL
+// printed to a builder, an `amazonprimea-*` User-Agent that should come from
+// branding().userAgent(), a hardcoded product name in user-facing copy). What is
+// left below is NOT a backlog — each entry is a literal that is CORRECT as
+// written, so this list is permanent rather than a ratchet-to-zero.
+//
+// The COUNT is still enforced, which is the point: an entry may not grow. A file
+// here that gains a NEW hardcoded host fails the build exactly like an unlisted
+// one, and any file NOT listed must have zero hits. Getting better never fails.
+//
+// Why each is legitimate:
+//   * box.js — REAL Cloudflare/DNS zone names for the operator plane
+//     (`dev.<host>`, the terminal zone). These are infrastructure identifiers,
+//     not an instance URL; routing them through branding would be wrong. (Its
+//     two genuine API-base defaults WERE fixed in 1002428.)
+//   * publish-manifest.js — the literal FILENAMES of two real committed docs
+//     (docs/recipes/amazonprimea-decouple-*.md). Renaming the strings without
+//     renaming the files would break the publish manifest.
+//   * backfill-sessions.js / version-close.js — one-time operator runbook text
+//     naming the actual prod DB + a historical local directory. Describing what
+//     an operator must literally type is the correct content.
+//   * seed-*.js — the hits are PROSE INSIDE seeded task descriptions: historical
+//     records of what those tasks said when they were filed. Rewriting them would
+//     falsify the record; deleting the files would destroy it. They are inert
+//     (idempotent on source_ref) and referenced only by generated manifests.
+//   * the four *.sh entries — surfaced when `.sh` joined the extension set (task
+//     1002567). Each is a HOST-PINNED OPS script, not portable code: they name the
+//     live box's actual Postgres database/role and its actual /etc secrets dir, and
+//     every one of those literals is already only the DEFAULT behind an env override
+//     (GDS_BACKUP_DB, PROD_DB/STAGING_DB, PG_SOCKET). Same rationale as box.js's real
+//     DNS zones — an infrastructure identifier, not an instance URL, and the systemd
+//     units on that box invoke these by path. Re-pointing an instance's backups is
+//     deployment work, not a branding read. Their COUNT is still frozen here, so a
+//     NEW literal in any of them fails exactly like one in an unlisted file.
+//   * fitness-checks-identity.js / package-core.js — THE DETECTORS THEMSELVES: Check 13's regexes
+//     and package-core's PRIOR_INSTANCE_FLOOR name the brand because hunting it is
+//     their job. * seed-v3-tasks.js — the seeded-task-prose rationale above. All
+//     three passed pre-1002756 only by the old stripper's accidents (phantom
+//     blocks + regex-blindness); now they are seen and counted.
+const IDENTITY_SCAN_ALLOWED = {
+  // task 1003206 moved Check 13's own regexes out of fitness.js into THIS file
+  // when the monolith was split, so the detector's self-carve-out moved with them.
+  'scripts/gds/fitness-checks-identity.js': 2,
+  'scripts/gds/package-core.js': 1,
+  'scripts/gds/seed-v3-tasks.js': 14,
+  // audit-replay.sh + db-backup-{nightly,offsite}.sh were carved out here as
+  // "host-pinned ops"; task 1002757 RETIRED that justification for them — each
+  // now resolves its database from the branding pack (the migrate.sh pattern) and
+  // fails loudly rather than defaulting, so their counts ratcheted to zero and the
+  // entries are gone. seed-staging.sh keeps its carve-out on the OPPOSITE
+  // rationale: its literal is a fail-CLOSED safety interlock (the script wipes
+  // STAGING_DB and refuses unless the name matches exactly), so on any other
+  // instance it declines to run instead of destroying the wrong database.
+  'scripts/gds/seed-staging.sh': 4,
+  'scripts/gds/backfill-sessions.js': 2,
+  'scripts/gds/box.js': 3,
+  'scripts/gds/publish-manifest.js': 2,
+  'scripts/gds/seed-bongos-coreB-tranche1-tasks.js': 1,
+  'scripts/gds/seed-bongos-coreB-tranche2-tasks.js': 1,
+  'scripts/gds/seed-bongos-goal-hierarchy-tasks.js': 1,
+  'scripts/gds/seed-bongos-tasks.js': 1,
+  'scripts/gds/seed-gds-v4-tasks.js': 1,
+  'scripts/gds/seed-medusa-tasks.js': 7,
+  'scripts/gds/seed-module-upstreaming.js': 1,
+  'scripts/gds/seed-productization-tasks.js': 6,
+  'scripts/gds/seed-provisioning-tasks.js': 2,
+  'scripts/gds/version-close.js': 1,
+};
+// `.sh` joined at task 1002567: the extension set was `.js/.html/.css`, so NO shell
+// script had ever been scanned — which is how scripts/gds/lib.sh kept a hardcoded
+// founder host as its API-base default (and a hardcoded ~/.config/otb token path)
+// through the entire task 1002201 sweep, leaving all five bash smokes dead on any
+// instance with a different configDir. The guard could not see the file class the
+// bug lived in.
+const IDENTITY_SCAN_EXTS = new Set(['.js', '.html', '.css', '.sh']);
+// Path-prefix carve-outs (see the header note). Kept SMALL and documented.
+const IDENTITY_SCAN_EXCLUDE = ['modules/game/'];
+// Directories with no authored source to gate.
+const IDENTITY_SCAN_SKIP_DIRS = new Set(['node_modules', '.git', 'generated', 'iterations', 'references']);
+
+// Comment stripping lives in identity-strip.js (task 1002756: extracted + replaced
+// the two-regex JS strip, which a `/*` inside a `//` comment could OPEN — it
+// silently hid ~330 provision.js lines from this gate). Re-exported for the tests.
+const { stripCommentsForIdentity } = require('./identity-strip');
+
+// Pure: scan one file's comment-stripped source for a hardcoded host-brand literal.
+// Returns violation strings. Exported for the "actually catches a re-hardcode" test.
+function scanPromptIdentity(relFile, text, ext = path.extname(relFile)) {
+  const violations = [];
+  stripCommentsForIdentity(text, ext).split('\n').forEach((raw, i) => {
+    if (!raw.trim()) return;
+    for (const re of PROMPT_IDENTITY_LITERALS) {
+      const m = raw.match(re);
+      if (m) {
+        violations.push(`${relFile}:${i + 1} hardcodes the host-brand identity "${m[0]}" — read it from branding()/window.__BRANDING__ (identity/domains/currency), or use a {{worldName}}-style token, so a non-OTB instance renders ITS OWN brand (ADR 0062 §3/§5; BV1.R76 / task 1705).`);
+        break; // one hit per line is enough
+      }
+    }
+  });
+  return violations;
+}
+
+// Recursively collect scannable files under one root, honoring the skip-dir + carve-out lists.
+function collectIdentityFiles(absRoot, relRoot) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(absRoot, { withFileTypes: true }); }
+  catch { return out; }
+  for (const e of entries) {
+    const rel = relRoot ? `${relRoot}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      if (IDENTITY_SCAN_SKIP_DIRS.has(e.name)) continue;
+      if (IDENTITY_SCAN_EXCLUDE.some((p) => `${rel}/`.startsWith(p))) continue;
+      out.push(...collectIdentityFiles(path.join(absRoot, e.name), rel));
+    } else if (IDENTITY_SCAN_EXTS.has(path.extname(e.name))
+               && !IDENTITY_SCAN_EXCLUDE.some((p) => rel.startsWith(p))) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+function checkKernelPromptsNoHardcodedIdentity() {
+  const violations = [];
+  let scanned = 0;
+  // Collect {abs, rel}: src/bongos is CORE; modules ship from BOTH roots (ADR 0108 §Consequences #4).
+  // Dedup by repo-relative path so a shared checkout never scans a file twice, and read each file
+  // from the root it was actually found under (a module may live in the instance repo post-split).
+  const seen = new Set();
+  const entries = [];
+  const addFrom = (rootAbs, sub) => {
+    for (const relFromRoot of collectIdentityFiles(path.join(rootAbs, sub), sub)) {
+      if (seen.has(relFromRoot)) continue;
+      seen.add(relFromRoot);
+      entries.push({ abs: path.join(rootAbs, relFromRoot), rel: relFromRoot });
+    }
+  };
+  for (const root of IDENTITY_SCAN_ROOTS) {
+    for (const rootAbs of (root === 'modules' ? MODULE_ROOTS : [CORE_ROOT])) addFrom(rootAbs, root);
+  }
+  for (const extra of IDENTITY_SCAN_EXTRA_FILES) {
+    if (!seen.has(extra)) { seen.add(extra); entries.push({ abs: path.join(CORE_ROOT, extra), rel: extra }); }
+  }
+  let ratcheted = 0;
+  for (const { abs, rel: relFile } of entries) {
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); }
+    catch { continue; } // a file moved/carved away is not a failure of this gate
+    scanned += 1;
+    const found = scanPromptIdentity(relFile, text);
+    // Permanently allowed at a COUNT (task 1002428): the listed literals are
+    // correct as written, but an entry may not GROW — a new hardcode in one of
+    // these files fails exactly like one in an unlisted file.
+    const allowed = IDENTITY_SCAN_ALLOWED[relFile];
+    if (allowed !== undefined) {
+      if (found.length > allowed) {
+        violations.push(
+          `${relFile} now hardcodes the host-brand identity ${found.length} time(s), above its allowed ${allowed} — ` +
+          `the carve-out covers the EXISTING literals (see IDENTITY_SCAN_ALLOWED), not new ones. ` +
+          `Read the host from branding()/window.__BRANDING__ instead (task 1002428).`
+        );
+      } else {
+        ratcheted += 1;
+      }
+      continue;
+    }
+    violations.push(...found);
+  }
+  return {
+    name: 'portable code carries no hardcoded host identity (BV1.R76 / task 1705)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} portable source file(s) scanned (.js/.html/.css/.sh under src/bongos/** + modules/** + scripts/** (whole root, task 1002756), minus the instance-1 product + generated dirs) — none may hardcode the host brand; identity comes from branding()/window.__BRANDING__ (ADR 0062 §3/§5). ${ratcheted} scripts/gds file(s) hold documented permanent carve-outs (real DNS zones, real doc filenames, operator runbook text, historical seeded prose) capped at a count they may not exceed — task 1002428.`,
+  };
+}
+
+// ============================================================================
+// Check 15b — core-shipped NEUTRAL config packs carry no host identity (BV1.R102)
+// ============================================================================
+//
+// Sibling of Check 15 for the CONFIG class. IDENTITY_SCAN_EXTS is js/html/css, so
+// the scan above never opens a .json — yet config/*.neutral.json is precisely what
+// a vanilla instance boots from (branding R76, governance R96). A host name leaking
+// into a neutral pack ships one instance's brand to EVERY fresh instance, and until
+// this check nothing in CI could see it.
+//
+// Only the NEUTRAL packs are scanned, deliberately: an instance pack (config/
+// branding.json, config/government.json) is host content that legitimately names
+// its host, and is boundary-excluded from the published core anyway.
+function checkNeutralConfigsNoHostIdentity() {
+  const violations = [];
+  const dir = path.join(CORE_ROOT, 'config');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.neutral.json')).sort(); }
+  catch { /* no config/ dir in this root — nothing to gate */ }
+  for (const name of names) {
+    const relFile = `config/${name}`;
+    let text;
+    try { text = fs.readFileSync(path.join(dir, name), 'utf8'); }
+    catch { continue; } // a pack that moved away is not a failure of this gate
+    violations.push(...scanPromptIdentity(relFile, text, '.json'));
+  }
+  return {
+    name: 'neutral config packs carry no host identity (BV1.R102)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${names.length} core-shipped config/*.neutral.json pack(s) scanned — a vanilla instance boots from these alone, so none may name a host brand. Instance packs (config/<name>.json) are host content and are deliberately NOT scanned.`,
+  };
+}
+
+// ---- design contract (ADR 0081 / task 1377) --------------------------------
+
+function checkDesignContract() {
+  const { spawnSync } = require('node:child_process');
+  const validatorPath = path.join(REPO_ROOT, 'scripts', 'gds', 'validate-design.js');
+  const adaptersDir = path.join(REPO_ROOT, 'src', 'ui', 'adapters');
+  const hasAdapters = (() => {
+    try { return fs.readdirSync(adaptersDir).some((e) => fs.statSync(path.join(adaptersDir, e)).isDirectory()); }
+    catch { return false; }
+  })();
+
+  const result = spawnSync(process.execPath, [validatorPath, '--json'], { encoding: 'utf8' });
+  let report = { ok: true, errors: [], warnings: [] };
+  try { report = JSON.parse(result.stdout || '{}'); } catch { /* fall through with defaults */ }
+  if (result.status !== 0 && !report.errors.length) {
+    report.errors.push(result.stderr ? result.stderr.trim() : 'validate-design.js exited non-zero');
+    report.ok = false;
+  }
+
+  return {
+    name: 'design contract valid (docs/design-contract.md / ADR 0081)',
+    ok: report.ok,
+    hardFail: !report.ok && hasAdapters,
+    violations: report.errors || [],
+    warnings: report.warnings || [],
+    note: hasAdapters
+      ? 'Hard-fail: adapters present — contract must be valid. Run: node scripts/gds/validate-design.js'
+      : 'Warn-only until first adapter lands (task 1378 / task 1379). Run: node scripts/gds/validate-design.js',
+  };
+}
+
+
+module.exports = {
+  IDENTITY_SCAN_ALLOWED,
+  IDENTITY_SCAN_EXCLUDE,
+  IDENTITY_SCAN_EXTRA_FILES,
+  IDENTITY_SCAN_EXTS,
+  IDENTITY_SCAN_ROOTS,
+  IDENTITY_SCAN_SKIP_DIRS,
+  PROMPT_IDENTITY_LITERALS,
+  checkDesignContract,
+  checkKernelPromptsNoHardcodedIdentity,
+  checkNeutralConfigsNoHostIdentity,
+  collectIdentityFiles,
+  scanPromptIdentity,
+  stripCommentsForIdentity,
+};

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

@@ -0,0 +1,230 @@
+// scripts/gds/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/gds/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 historical artifact by its real name: an ADR filename, the
+// docs/governance/ evidence folder, or one of the already-applied
+// governance_NNN migrations. These names are permanent (see the header), so a
+// reference to one is a citation, not drift.
+const VOCAB_HISTORICAL_REF = /docs\/adr\/|docs\/governance\/|docs\/session-logs\/|governance_0\d\d/;
+
+const VOCAB_SURFACE = [
+  'modules/government',
+  'modules/hall-ui/public/government.js',
+  'modules/hall-ui/public/government.html',
+  'modules/hall-ui/public/government.css',
+];
+const VOCAB_EXTS = new Set(['.js', '.json', '.html', '.css']);
+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/hall-ui/public/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;
+        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_ALLOW.length} documented allowlist entr(y|ies). Historical migrations + docs/adr are excluded by construction, not suppressed.`,
+  };
+}
+
+
+module.exports = {
+  GOAL_VOCAB_CITATION,
+  GOAL_VOCAB_LINE_SCOPED,
+  GOAL_VOCAB_SURFACE,
+  LIFECYCLE_DB_FILES,
+  VOCAB_ALLOW,
+  VOCAB_BANNED,
+  VOCAB_EXTS,
+  VOCAB_HISTORICAL_REF,
+  VOCAB_SURFACE,
+  checkGoalMembershipVocabulary,
+  checkVocabularyWall,
+  vocabFilesToScan,
+};