@bongos/core 1.17.0

package/scripts/gds/fitness.js

@@ -0,0 +1,1446 @@
+#!/usr/bin/env node
+'use strict';
+// fitness.js — architecture fitness functions (Path C / ADR 0062 §9, task 1225).
+//
+// The ENFORCEMENT layer for the Cloud Bongos decoupling. A dependency-cruiser/ArchUnit-style gate that
+// keeps the architecture from silently rotting back together. Each check is a pure function over
+// the repo on disk returning { name, ok, hardFail, violations[], warnings[], note }. The CLI runs
+// them all, prints a report, and exits non-zero on any hard failure. tests/fitness.mjs asserts
+// each check passes, so the DB-free unit gate (run-unit-tests.js → the `unit` required check)
+// enforces them on every PR — no new workflow needed.
+//
+// RATCHET, not big-bang. The structural epics that physically separate the core (R51 entrypoint
+// #1190, R52 DB carve-out #1191, R54 module system #1193) are not built yet, so the codebase is
+// still fused (every src/bongos/*.js shares the game's pg Pool via require('../db')). These checks
+// therefore lock in the boundary DIRECTION now and fail only on NEW violations beyond a documented
+// grandfather list; as the epics land they SHRINK the grandfather list. Module-level boundary
+// enforcement (§4) tightens once R54 (#1193) gives us a module manifest to check against.
+//
+// Usage:
+//   node scripts/gds/fitness.js          # run all checks, print report, exit 1 on any hard failure
+//   node scripts/gds/fitness.js --json    # machine-readable report
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { checkRouteRanks } = require('../../src/bongos/route-rank-check');
+const genApiDocs = require('./gen-api-docs'); // R12 (#1999): reuse the route model (readsBody/validated) that drives the OpenAPI spec
+const { parseRoutineFrontmatter } = require('./run-routine'); // System 4 (ADR 0078): deterministic-routine boundary
+const { filenameViolation, stemCollisions, CORE_NS, INSTANCE_NS } = require('./migration-namespace'); // ADR 0108 §5: cross-repo migration namespacing
+const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+
+// ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — the guardrail walks TWO trees.
+// CORE code + core-owned docs (src/, server.js, scripts/, the src/bongos + scripts/gds nested docs)
+// live under the core PACKAGE; INSTANCE content (the root CLAUDE.md, the .claude/ methodology
+// surface, instance modules + migrations) lives under the host REPO. Modules ship from BOTH.
+// Today both resolve to the same checkout, so every walk below is byte-identical; once the core
+// installs from node_modules they diverge and each check inspects the CORRECT tree. A NEW
+// hardcoded `path.resolve(__dirname,'..','..')` here reintroduces the bug this check exists to stop.
+const CORE_ROOT = resolveCoreRoot();
+const INSTANCE_ROOT = resolveInstanceRoot();
+// REPO_ROOT retained as an alias to the core root for the many purely-core walks below (src/bongos,
+// KERNEL_FILES, scope map, …) — those keep their exact behavior. Instance-owned reads route
+// through INSTANCE_ROOT explicitly, and module reads through MODULE_ROOTS.
+const REPO_ROOT = CORE_ROOT;
+// Deduped module search roots — a module can ship from the core package OR the instance repo (the
+// loader errors on a cross-root key collision, so a key resolves to exactly one root). Deduped so
+// today's single checkout scans each module ONCE (no double-counting).
+const MODULE_ROOTS = [...new Set([CORE_ROOT, INSTANCE_ROOT])];
+
+// ---- shared fs helpers -----------------------------------------------------
+
+function walkJs(absRoot, out = []) {
+  let st;
+  try { st = fs.statSync(absRoot); } catch { return out; }
+  if (st.isFile()) { if (absRoot.endsWith('.js')) out.push(absRoot); return out; }
+  for (const ent of fs.readdirSync(absRoot, { withFileTypes: true })) {
+    if (ent.name === 'node_modules' || ent.name === '.git') continue;
+    walkJs(path.join(absRoot, ent.name), out);
+  }
+  return out;
+}
+// repo-relative POSIX path for an abs file under EITHER root (core or instance). The classifier
+// regexes throughout this file key on these relative strings, which are identical whichever tree
+// a file lives in — so only the WALK roots change under the split, not the classification.
+const rel = (abs) => {
+  for (const base of [CORE_ROOT, INSTANCE_ROOT]) {
+    const r = path.relative(base, abs);
+    if (r && !r.startsWith('..') && !path.isAbsolute(r)) return r.split(path.sep).join('/');
+  }
+  return path.relative(CORE_ROOT, abs).split(path.sep).join('/');
+};
+// Walk .js under `subpath` (e.g. 'modules') across ALL module roots, deduped by repo-relative
+// path so the same file is never scanned twice when the roots coincide (today).
+function walkJsAllRoots(subpath, roots = MODULE_ROOTS) {
+  const seen = new Set();
+  const out = [];
+  for (const root of roots) {
+    for (const abs of walkJs(path.join(root, subpath))) {
+      const r = rel(abs);
+      if (seen.has(r)) continue;
+      seen.add(r);
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+// ============================================================================
+// Check 1 — core ↔ host/game import boundary (ADR 0062 §1 cut-line)
+// ============================================================================
+//
+// The portable core (src/bongos/) must not import the HOST GAME runtime. After BV1.R49 the game
+// module lives in modules/game/ (rooms, world, db, seats, public, migrations). The only game-
+// related file that stays in src/ is src/preview-server.js (the game-only sandbox entrypoint).
+// Imports into scripts/ (build tooling / engine) are NOT host-game coupling.
+const HOST_GAME = [
+  /^modules\/game\//,           // everything in the game module (moved from src/ by BV1.R49)
+  /^src\/preview-server\.js$/,  // game-only sandbox entrypoint (stays in src/)
+];
+// Empty as of R52/#1191 — the core owns its pool (src/bongos/pool.js) and no longer imports the
+// game's db helper. The boundary now enforces with ZERO grandfathered exceptions.
+const GRANDFATHERED = new Set([]);
+const REQUIRE_RE = /require\(\s*['"](\.\.?\/[^'"]+)['"]\s*\)/g;
+
+function resolvesToHostGame(fromAbsFile, spec) {
+  const abs = path.resolve(path.dirname(fromAbsFile), spec);
+  const r = rel(abs);
+  for (const cand of [r, r + '.js', r.replace(/\/$/, '') + '/index.js']) {
+    if (GRANDFATHERED.has(cand)) return null; // allowed (and not a violation)
+    if (HOST_GAME.some((re) => re.test(cand))) return cand;
+  }
+  return null;
+}
+
+function checkCoreHostBoundary() {
+  const coreDir = path.join(REPO_ROOT, 'src', 'bongos');
+  const violations = [];
+  for (const abs of walkJs(coreDir)) {
+    // scan line-by-line, skipping comment lines so a require(...) quoted in a doc comment
+    // (e.g. explaining the boundary) is never mistaken for a real import.
+    for (const raw of fs.readFileSync(abs, 'utf8').split('\n')) {
+      const trimmed = raw.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+      let m;
+      REQUIRE_RE.lastIndex = 0;
+      while ((m = REQUIRE_RE.exec(raw))) {
+        const target = resolvesToHostGame(abs, m[1]);
+        if (target) violations.push(`${rel(abs)} → require('${m[1]}') reaches host-game code (${target}) — the core must not import the game runtime (ADR 0062 §1).`);
+      }
+    }
+  }
+  return {
+    name: 'core↔host import boundary',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `src/bongos/ must not import the host game runtime (grandfathered: ${[...GRANDFATHERED].join(', ') || 'none'} — severed by R52/#1191).`,
+  };
+}
+
+// ============================================================================
+// Check 2 — root CLAUDE.md size budget + charter presence (ADR 0061)
+// ============================================================================
+const ROOT_HARD_MAX = 300; // ceiling: the always-loaded file must never balloon past this. Ratcheted
+                           // 360→310 when task 1226 generated the §13 session-log index (was a ~58-line
+                           // hand-maintained list), then 310→300 when task 1283 trimmed the quick-nav
+                           // table + §2/§8/§9/§10/§12 verbose prose down to ~294 lines. Lower further as
+                           // more detail relocates to nested docs / ADRs (ADR 0061).
+const ROOT_TARGET = 200;   // the charter's stated aim; keep ratcheting toward it.
+
+// The line count is a structure/readability proxy; the cost paid EVERY session is
+// characters/tokens. A 600-char quick-nav row is one line but ~150 tokens, so
+// within-line bloat slips past ROOT_HARD_MAX entirely (exactly what task 1283
+// trimmed). Guard the real cost too (task 1286). Ratcheted just above the
+// post-1283 size (~39.5K chars / ~9.9K tok); lower alongside ROOT_HARD_MAX as
+// detail relocates to nested docs / ADRs.
+const ROOT_CHAR_HARD_MAX = 42000; // ~10.5K tokens — the always-loaded file must never balloon past this.
+const ROOT_CHAR_TARGET = 32000;   // ~8K tokens — aspirational, mirrors the ~200-line aim.
+const estTokens = (n) => Math.round(n / 4); // ~4 chars/token for markdown prose.
+
+function checkClaudeMdBudget(opts = {}) {
+  const p = path.join(INSTANCE_ROOT, 'CLAUDE.md'); // the root CLAUDE.md is INSTANCE content (materialized per instance; ADR 0108)
+  const text = opts.text != null ? opts.text : fs.readFileSync(p, 'utf8');
+  const lines = text.split('\n').length;
+  const violations = [];
+  const warnings = [];
+  if (lines > ROOT_HARD_MAX) {
+    violations.push(`CLAUDE.md is ${lines} lines — over the ${ROOT_HARD_MAX}-line hard ceiling. It loads in full every session; relocate detail to a nested CLAUDE.md / ADR / recipe (ADR 0061).`);
+  } else if (lines > ROOT_TARGET) {
+    warnings.push(`CLAUDE.md is ${lines} lines — over the ~${ROOT_TARGET}-line target (still under the ${ROOT_HARD_MAX} ceiling). Relocate more detail to nested CLAUDE.md / ADRs / recipes (ADR 0061), then lower ROOT_HARD_MAX as it shrinks.`);
+  }
+  const chars = text.length;
+  const tok = estTokens(chars);
+  if (chars > ROOT_CHAR_HARD_MAX) {
+    violations.push(`CLAUDE.md is ${chars} chars (~${tok} tokens) — over the ${ROOT_CHAR_HARD_MAX}-char (~${estTokens(ROOT_CHAR_HARD_MAX)}-token) hard ceiling. The line count may be fine, but the per-session token cost is not — trim verbose prose WITHIN lines (long quick-nav rows, restated rationale), not just whole lines (ADR 0061).`);
+  } else if (chars > ROOT_CHAR_TARGET) {
+    warnings.push(`CLAUDE.md is ${chars} chars (~${tok} tokens) — over the ~${ROOT_CHAR_TARGET}-char (~${estTokens(ROOT_CHAR_TARGET)}-token) target. This is the true per-session cost; within-line bloat (a 600-char table row is one line) escapes the line check. Trim prose, then lower ROOT_CHAR_HARD_MAX.`);
+  }
+  if (!text.includes('## Working with this file (content charter)')) {
+    violations.push('CLAUDE.md is missing the content-charter section (ADR 0061) — the per-line test + "what goes where" table must stay.');
+  }
+  return { name: 'root CLAUDE.md budget + charter', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings, note: `≤ ${ROOT_HARD_MAX} lines / ${ROOT_CHAR_HARD_MAX} chars (~${estTokens(ROOT_CHAR_HARD_MAX)} tok); targets ~${ROOT_TARGET} lines / ~${estTokens(ROOT_CHAR_TARGET)} tok; charter present.` };
+}
+
+// ============================================================================
+// Check 3 — nested per-module CLAUDE.md presence for high-traffic dirs (ADR 0061)
+// ============================================================================
+const HIGH_TRAFFIC = ['src/bongos', 'src/bongos/routes', 'scripts/gds'];
+
+function checkNestedDocsPresent() {
+  const violations = [];
+  for (const dir of HIGH_TRAFFIC) {
+    // HIGH_TRAFFIC dirs (src/bongos, src/bongos/routes, scripts/gds) are CORE-package dirs — resolve
+    // against the core root, not the instance repo (ADR 0108 §Consequences #4).
+    const doc = path.join(CORE_ROOT, dir, 'CLAUDE.md');
+    if (!fs.existsSync(doc)) violations.push(`${dir}/CLAUDE.md is missing — high-traffic dirs must carry a nested altitude map (ADR 0061).`);
+  }
+  return { name: 'nested CLAUDE.md presence', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings: [], note: `present for: ${HIGH_TRAFFIC.join(', ')}.` };
+}
+
+// ============================================================================
+// Check 4 — no route bypasses server-side rank checks (ADR 0016)  [reuses route-rank-check]
+// ============================================================================
+function checkRankGuards() {
+  const r = checkRouteRanks();
+  // hardFail = an ungated WRITE route or a downgraded privileged route. Unclassified read routes
+  // are 'concerns' (the Hacker adjudicates intent) — surfaced as warnings, not a hard failure.
+  const violations = r.findings.filter((f) => f.severity === 'blocker').map((f) => `${f.route} (${f.file}) — ${f.summary}`);
+  const warnings = r.findings.filter((f) => f.severity !== 'blocker').map((f) => `${f.route} (${f.file}) — ${f.summary}`);
+  return { name: 'route rank guards (ADR 0016)', ok: !r.hardFail, hardFail: r.hardFail, violations, warnings, note: `${r.routeCount} routes classify to a known rank; no ungated writes, no privileged downgrades.` };
+}
+
+// ============================================================================
+// Check 5 — generated artifacts are fresh (Path C enforces Path B; ADR 0063 + ADR 0062 §8)
+// ============================================================================
+// Deterministic file-reads with a `--check` mode (regenerate in-memory, diff, exit non-zero on
+// drift). This gate fails a PR that committed a stale artifact so the "generate, don't hand-maintain"
+// contract can't rot.
+// ADR 0110 (task 1926): docs/repo-map.md + docs/session-log-index.md are now GITIGNORED and
+// regenerated at deploy/box-fetch (the gen-atlas.js model), so parallel branches never collide on
+// them — and there is no committed copy to gate. Their generators are DUAL-DUTY, though: each also
+// refreshes a TRACKED embedded block (the nested CLAUDE.md symbol blocks; the CLAUDE.md §13 snippet).
+// Those blocks stay committed, so we gate the BLOCK bucket HARD via `--check-block`. A naive `--check`
+// here would false-fail every PR (the gitignored whole file is absent from a clean checkout, so it
+// always reads as "would change"); `--check-block` is the exact, non-noisy gate. (docs/file-map.md +
+// the OpenAPI docs are still fully committed and unchanged by ADR 0110 — they keep the plain --check.)
+function checkGeneratedArtifactsFresh() {
+  const violations = [];
+  try {
+    execFileSync(process.execPath, [path.join(__dirname, 'gen-repo-map.js'), '--check-block'], { cwd: REPO_ROOT, stdio: 'pipe' });
+  } catch {
+    violations.push('The tracked nested-doc symbol blocks (src/bongos/CLAUDE.md, src/bongos/routes/CLAUDE.md, scripts/gds/CLAUDE.md) are STALE — run `node scripts/gds/gen-repo-map.js` and commit (ADR 0063 / ADR 0110). NB docs/repo-map.md itself is gitignored + deploy-regenerated, not gated here.');
+  }
+  try {
+    execFileSync(process.execPath, [path.join(__dirname, 'gen-session-index.js'), '--check-block'], { cwd: REPO_ROOT, stdio: 'pipe' });
+  } catch {
+    violations.push('The tracked CLAUDE.md §13 recent-sessions snippet is STALE — run `node scripts/gds/gen-session-index.js` and commit (ADR 0062 §8 / ADR 0110). NB docs/session-log-index.md itself is gitignored + deploy-regenerated, not gated here.');
+  }
+  try {
+    execFileSync(process.execPath, [path.join(__dirname, 'gen-file-map.js'), '--check'], { cwd: REPO_ROOT, stdio: 'pipe' });
+  } catch {
+    violations.push('docs/file-map.md generated sections (.claude/skills/, .claude/scheduled-tasks/) are STALE or a skill/routine has no note in docs/file-map.notes.json — run `node scripts/gds/gen-file-map.js` and add any missing note, then commit (ADR 0066).');
+  }
+  try {
+    // Also structurally validates the spec (exit 1 on invalid OpenAPI 3.1) beyond the drift check (exit 2). Task 1918.
+    execFileSync(process.execPath, [path.join(__dirname, 'gen-api-docs.js'), '--check'], { cwd: REPO_ROOT, stdio: 'pipe' });
+  } catch {
+    violations.push('docs/api/openapi.json + docs/api-reference.md + docs/routes-permissions.md are STALE (or the spec is not valid OpenAPI 3.1) — run `node scripts/gds/gen-api-docs.js` and commit (task 1918).');
+  }
+  return { name: 'generated artifacts fresh', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings: [], note: 'Tracked generated content matches source: nested CLAUDE.md symbol blocks (code) + the CLAUDE.md §13 snippet (sessions) via --check-block, plus docs/file-map.md skills/scheduled-tasks sections and docs/api/openapi.json + api-reference.md (API). The gitignored docs/repo-map.md + docs/session-log-index.md are deploy-regenerated (ADR 0110), not gated here.' };
+}
+
+// ---- deterministic cron routine boundary (System 4 / ADR 0078) -------------
+//
+// A `mode: deterministic` routine runs as plain node via run-routine.js — NO
+// model session reads its SKILL body. So that body must not rot back into a
+// wrapped session: it may not instruct a model to mutate (Edit/Write/git
+// push/commit/deploy) or synthesize free text, and its documented commands must
+// not diverge from its declared steps. Keeps the markdown-graveyard pattern out.
+
+const SCHEDULED_TASKS_DIR = path.join(INSTANCE_ROOT, '.claude', 'scheduled-tasks'); // .claude/ is materialized INSTANCE content (ADR 0108 §3)
+
+// Judgment/mutation instructions illegal in a deterministic body. Negated
+// mentions ("never pushes", "does NOT edit") are descriptive boundaries — allowed.
+const JUDGMENT_PATTERNS = [
+  { re: /\bgit\s+(push|commit|add)\b/i, label: 'a git push/commit/add' },
+  { re: /deploy\.sh\b/i, label: 'a deploy.sh invocation' },
+  { re: /`(Edit|Write|MultiEdit|NotebookEdit)`/, label: 'an Edit/Write tool instruction' },
+  { re: /\bsynthesi[sz]e\b/i, label: 'free-text synthesis' },
+  { re: /\b(write|compose|draft)\s+(a|an|the)\s+(summary|report|analysis|narrative|note)\b/i, label: 'free-text synthesis' },
+];
+const NEGATION_RE = /\b(never|not|no|without|cannot|can't|don'?t|doesn'?t|won'?t)\b/i;
+
+// Pure: scan one routine's parsed (mode, steps, body). Returns violation strings.
+// Only inspects deterministic routines; others return []. Exported for tests.
+function scanDeterministicBody(name, { mode, steps, body }) {
+  if (mode !== 'deterministic') return [];
+  const violations = [];
+  if (!steps || steps.length === 0) {
+    violations.push(`${name}: mode: deterministic but no steps: — run-routine.js would launch nothing (ADR 0078).`);
+  }
+  const text = String(body == null ? '' : body);
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || NEGATION_RE.test(line)) continue; // skip blank + negated (boundary) lines
+    for (const p of JUDGMENT_PATTERNS) {
+      if (p.re.test(line)) {
+        violations.push(`${name}: deterministic SKILL body contains ${p.label} ("${line.slice(0, 70)}") — it runs as plain node with no model; move remediation/judgment to a separate claimed task (ADR 0078).`);
+      }
+    }
+  }
+  // Divergence: every `node …` command in a fenced code block must be a declared step.
+  const stepCmds = (steps || []).map((s) => String(s.command).replace(/\s+/g, ' ').trim());
+  for (const fence of text.match(/```[\s\S]*?```/g) || []) {
+    for (const fl of fence.split('\n')) {
+      const cmd = fl.trim().replace(/\s+/g, ' ');
+      if (!cmd.startsWith('node ')) continue;
+      if (!stepCmds.some((s) => cmd === s || cmd.startsWith(s) || s.startsWith(cmd))) {
+        violations.push(`${name}: deterministic SKILL body documents \`${cmd.slice(0, 70)}\` which is not in its steps: — prose and steps must not diverge (ADR 0078).`);
+      }
+    }
+  }
+  return violations;
+}
+
+function checkDeterministicRoutines() {
+  const violations = [];
+  let detCount = 0;
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(SCHEDULED_TASKS_DIR, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch (_) { /* no scheduled-tasks dir → nothing to check */ }
+  for (const name of dirs) {
+    let md;
+    try { md = fs.readFileSync(path.join(SCHEDULED_TASKS_DIR, name, 'SKILL.md'), 'utf8'); } catch (_) { continue; }
+    const { mode, steps } = parseRoutineFrontmatter(md);
+    if (mode !== 'deterministic') continue;
+    detCount += 1;
+    const body = md.replace(/^---\n[\s\S]*?\n---\n?/, ''); // strip frontmatter
+    violations.push(...scanDeterministicBody(name, { mode, steps, body }));
+  }
+  return {
+    name: 'deterministic cron routines (ADR 0078)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${detCount} mode:deterministic routine(s): steps declared, no judgment instructions, prose↔steps aligned.`,
+  };
+}
+
+// ============================================================================
+// Check 7/8 — module boundary (the one-way rule, ADR 0083 / design 04§3)
+// ============================================================================
+//
+// The module system's one-way rule: a module imports ONLY src/module-api.js (the
+// published doorway); the core NEVER imports a module; a module NEVER imports a
+// sibling module. These two checks enforce it.
+//
+// Both were GREEN through the strangler: dev-box + art-pipeline (the M07/M08
+// moves) import only the doorway, and the core imports neither. The boundary
+// shipped in WARN mode so a half-moved module mid-migration couldn't red the
+// build; BV1.R45 (task 1414) flips it to ENFORCING now that the first move
+// (dev-box, M07) proved clean — the monotonic ratchet (ADR 0062 §9 / design
+// 04§3). A NEW cross-boundary import is now a red build; warn-mode is gone.
+let MODULE_BOUNDARY_ENFORCING = true;
+const MODULE_API_REL = 'src/module-api.js';
+
+// If `spec` (a relative require) from `fromAbsFile` resolves into modules/<key>/,
+// return <key>; else null. Pure path math — no fs.
+function resolvesToModule(fromAbsFile, spec) {
+  const abs = path.resolve(path.dirname(fromAbsFile), spec);
+  const r = rel(abs);
+  const m = /^modules\/([^/]+)(\/|$)/.exec(r);
+  return m ? m[1] : null;
+}
+
+// The module a core/module file belongs to, or null if it isn't under modules/.
+function moduleOwnerOf(absFile) {
+  const m = /^modules\/([^/]+)\//.exec(rel(absFile));
+  return m ? m[1] : null;
+}
+
+// For a require `spec` inside a MODULE file, return a violation string or null.
+// Allowed: src/module-api.js (the doorway), intra-module relatives, and bare
+// (npm/node) specs. Forbidden: deep core imports + sibling-module imports.
+function moduleImportViolation(fromAbsFile, spec) {
+  const ownKey = moduleOwnerOf(fromAbsFile);
+  if (!ownKey) return null; // not a module file
+  const absTarget = path.resolve(path.dirname(fromAbsFile), spec);
+  const r = rel(absTarget);
+  // resolve possible file forms
+  const forms = [r, r + '.js', r.replace(/\/$/, '') + '/index.js'];
+  if (forms.includes(MODULE_API_REL)) return null; // the doorway — allowed
+  const otherKey = (() => { const m = /^modules\/([^/]+)(\/|$)/.exec(r); return m ? m[1] : null; })();
+  if (otherKey) {
+    if (otherKey === ownKey) return null; // intra-module — allowed
+    return `${rel(fromAbsFile)} → require('${spec}') reaches sibling module "${otherKey}" — modules must not import each other (use a kernel seam; ADR 0083).`;
+  }
+  if (/^src\//.test(r)) {
+    return `${rel(fromAbsFile)} → require('${spec}') reaches core internals (${r}) — a module may import only the published doorway src/module-api.js (ADR 0083).`;
+  }
+  return null; // outside the repo (node/npm) — not our concern
+}
+
+function checkCoreNeverImportsModule() {
+  const findings = [];
+  const roots = [path.join(REPO_ROOT, 'src'), path.join(REPO_ROOT, 'server.js')];
+  for (const root of roots) {
+    for (const abs of walkJs(root)) {
+      if (moduleOwnerOf(abs)) continue; // module files are scanned by the other check
+      if (HOST_GAME.some((re) => re.test(rel(abs)))) continue; // game-owned files that live in src/ (e.g. preview-server.js) may import game module
+      for (const raw of fs.readFileSync(abs, 'utf8').split('\n')) {
+        const t = raw.trim();
+        if (t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) continue;
+        let m; REQUIRE_RE.lastIndex = 0;
+        while ((m = REQUIRE_RE.exec(raw))) {
+          const key = resolvesToModule(abs, m[1]);
+          if (key) findings.push(`${rel(abs)} → require('${m[1]}') reaches module "${key}" — the core must never import a module (ADR 0083).`);
+        }
+      }
+    }
+  }
+  const enforcing = MODULE_BOUNDARY_ENFORCING;
+  return {
+    name: 'core never imports a module',
+    ok: findings.length === 0,
+    hardFail: enforcing && findings.length > 0,
+    violations: enforcing ? findings : [],
+    warnings: enforcing ? [] : findings,
+    note: `core (src/, server.js) must not require modules/* — ${enforcing ? 'ENFORCING' : 'warn-mode until BV1.R45'} (ADR 0083).`,
+  };
+}
+
+function checkModulesImportOnlyApi() {
+  const findings = [];
+  for (const abs of walkJsAllRoots('modules')) { // modules ship from BOTH roots (ADR 0108 §Consequences #4)
+    for (const raw of fs.readFileSync(abs, 'utf8').split('\n')) {
+      const t = raw.trim();
+      if (t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) continue;
+      let m; REQUIRE_RE.lastIndex = 0;
+      while ((m = REQUIRE_RE.exec(raw))) {
+        const v = moduleImportViolation(abs, m[1]);
+        if (v) findings.push(v);
+      }
+    }
+  }
+  const enforcing = MODULE_BOUNDARY_ENFORCING;
+  return {
+    name: 'modules import only the published API',
+    ok: findings.length === 0,
+    hardFail: enforcing && findings.length > 0,
+    violations: enforcing ? findings : [],
+    warnings: enforcing ? [] : findings,
+    note: `modules/** may require only src/module-api.js (no deep core, no sibling) — ${enforcing ? 'ENFORCING' : 'warn-mode until BV1.R45'} (ADR 0083).`,
+  };
+}
+
+// ============================================================================
+// Check 9 — the goal scope map imports PROTECTED_GLOBS, never re-declares it
+//           (ADR 0086 §7; the SEC #863 "second list that drifts" failure mode)
+// ============================================================================
+//
+// src/bongos/module-scope-map.js (BV1.R54) derives each module's `protected` flag
+// from PROTECTED_GLOBS. That derivation is only trustworthy if it reads the ONE
+// source (permission-path-check.js) — a hand-copied second list would silently
+// drift from the real protected set and quietly de-protect a module. This check
+// reds the build if the scope map stops importing PROTECTED_GLOBS, or copies it.
+const SCOPE_MAP_REL = 'src/bongos/module-scope-map.js';
+
+// Pure: scan the scope-map source for the import contract. Exported for the
+// "actually catches a violation" test (mirrors scanDeterministicBody).
+function scanScopeMapSource(src) {
+  const violations = [];
+  const text = String(src || '');
+  const importsFrom = /require\(\s*['"]\.\/permission-path-check['"]\s*\)/.test(text);
+  const namesIt = /\bPROTECTED_GLOBS\b/.test(text);
+  if (!importsFrom || !namesIt) {
+    violations.push(`${SCOPE_MAP_REL} must IMPORT PROTECTED_GLOBS from ./permission-path-check and derive \`protected\` from it — never hand-maintain a second protected list (ADR 0086 §7).`);
+  }
+  if (/\b(?:const|let|var)\s+PROTECTED_GLOBS\s*=/.test(text)) {
+    violations.push(`${SCOPE_MAP_REL} re-declares PROTECTED_GLOBS — it must import the single source from permission-path-check.js, not copy it (ADR 0086 §7; the SEC #863 second-list failure mode).`);
+  }
+  return violations;
+}
+
+function checkScopeMapImportsProtected() {
+  const abs = path.join(REPO_ROOT, SCOPE_MAP_REL);
+  let src = null;
+  try { src = fs.readFileSync(abs, 'utf8'); } catch (_) { /* absent → skip */ }
+  // Absent → clean pass: the scope map is a BV1.R54 deliverable; until it exists
+  // there is no import contract to enforce (its own unit test asserts existence).
+  const violations = src == null ? [] : scanScopeMapSource(src);
+  return {
+    name: 'scope map imports PROTECTED_GLOBS (ADR 0086)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: src == null
+      ? `${SCOPE_MAP_REL} absent — skipped (created by BV1.R54).`
+      : `${SCOPE_MAP_REL} derives \`protected\` from the imported PROTECTED_GLOBS (single source; no copied list).`,
+  };
+}
+
+// ============================================================================
+// Check 10 — core carries no module-specific code (ADR 0083 §Decision #4 / design 04§3)
+// ============================================================================
+//
+// The module-system MACHINERY (the doorway + loader + seam registry) must stay
+// module-AGNOSTIC: it discovers, validates, and mounts modules uniformly and may
+// never special-case one by name. The import checks (Check 7/8) stop a module's
+// CODE from being reached by `require`; this stops a module's IDENTITY from being
+// hardcoded into the kernel (`if (key === 'dev-box') …`, a copied module helper,
+// a registry entry that should have moved out). "No module-specific code" is
+// operationalized as the one drift-free signal — the kernel names no discovered
+// module KEY (the canonical id from modules/<key>/module.json). Domain terms are
+// deliberately NOT pattern-matched: they're non-deterministic and the doorway
+// legitimately re-exports capability accessors (getBuilderGeminiKeyRow, …); the
+// KEY is the precise thing a generic kernel never needs to write.
+//
+// Scope (BV1.R70 / ADR 0091 §1): the real ~3.5k-LOC TRUST KERNEL — the module-
+// system machinery PLUS the trust primitives + data substrate + config/identity
+// the rest of core depends on. This replaces the original 6-file machinery-only
+// roster (the kernel was unbounded before — the audit's finding). Deliberately
+// EXCLUDED: the still-fused monolith remnants (src/bongos/db.js, routes/me.js,
+// routes.js, server.js) still carry un-stranglered module seams by design
+// (lifecycle + tranche-2 domains leave later) — scanning them would red the
+// build on intentional state. Comment lines are skipped (a key named in a
+// doc/example comment is documentation, not code), and the scope-map registry is
+// exempt from the no-module-keys scan (see KERNEL_NAMES_MODULES_OK).
+const KERNEL_FILES = [
+  // module-system machinery (the original roster)
+  'src/module-api.js',                    // the published doorway
+  'src/modules.js',                       // the registry/resolver facade
+  'src/module-seams.js',                  // the seam registry (ports/events/contributions)
+  'src/module-loader/loader.js',          // the disk loader (discover → validate → mount)
+  'src/module-loader/manifest-schema.js', // the manifest validator
+  'src/module-loader/semver.js',          // coreVersion compatibility
+  'src/bongos/module-scope-map.js',          // the module→path registry (it NAMES every module — exempt below)
+  // trust primitives (ADR 0091 §1) — the authz boundary + data substrate
+  'src/bongos/auth.js',                      // authz gates (requireBuilder/requireRank, ADR 0016)
+  'src/bongos/route-rank-check.js',          // deterministic route→rank classification
+  'src/bongos/permission-path-check.js',     // protected-path matcher (PROTECTED_GLOBS, ADR 0043)
+  'src/bongos/goal-scope-check.js',          // goal create-gate scope wall (composes the 3 matchers above; ADR 0086 §3, BV1.R60)
+  'src/bongos/secret-box.js',                // AES-256-GCM per-builder secret box
+  'src/bongos/pool.js',                      // the singleton Postgres pool accessor
+  'src/bongos/db-kernel.js',                 // the kernel db slice — identity/audit/rank/withTx (BV1.R69)
+  'src/bongos/routes/_helpers.js',           // shared request validators the doorway re-exports
+  // config / identity (host context a module reads, never hardcodes)
+  'src/instance-config.js',
+  'src/branding.js',
+  'src/build-info.js',
+  // BV1.R86: the git-remote/slug + publish-target identity the doorway exposes
+  // (api.repoInfo) for the carved lifecycle github-push/conflict-resolve. It is
+  // KERNEL (already in the module-scope-map kernel key) and imports only the
+  // kernel (instance-config) + node built-ins, so it joins the roster cleanly.
+  'src/bongos/repo-info.js',
+];
+
+// Kernel files exempt from the no-module-keys scan (Check 10) because naming a
+// module is, for them, the JOB — they stay in KERNEL_FILES for the import check
+// (Check 12), which guards dependency *direction* (a much stronger guarantee than
+// "never write the string 'dev-box'"). Two legitimate reasons a kernel file names
+// a module:
+//   • the REGISTRY — module-scope-map.js IS the module→path map (and
+//     checkScopeMapImportsProtected already guards how it derives `protected`).
+//   • the TRUST BOUNDARY — auth.js carries the Discord OAuth account-LINK flow
+//     (core by design — see modules/discord/CLAUDE.md "NOT in this module"); and
+//     permission-path-check.js / route-rank-check.js MUST name module path
+//     subtrees ('modules/dev-box/', …) to protect + rank-gate them. Forbidding
+//     these the string would force the trust layer to stop protecting module
+//     surfaces — exactly backwards. The generic machinery + data + config files
+//     (module-api, the loader, db-kernel, secret-box, pool, _helpers, branding,
+//     instance-config, build-info) are NOT exempt and must stay module-agnostic.
+const KERNEL_NAMES_MODULES_OK = new Set([
+  'src/bongos/module-scope-map.js',      // the module→path registry
+  'src/bongos/auth.js',                  // Discord OAuth account-link flow (core by design)
+  'src/bongos/permission-path-check.js', // names module path subtrees to PROTECT them
+  'src/bongos/route-rank-check.js',      // names module route dirs to rank-gate them
+]);
+
+// The discovered module keys = the directory names under modules/ (a manifest's
+// `key` must equal its dir name — manifest-schema). Empty before any move. With no explicit
+// `modulesDir` it UNIONS every module root (core package + instance repo, ADR 0108 §Consequences
+// #4); an explicit dir keeps the old single-dir behavior (tests). Deduped — a key resolves to
+// exactly one root (the loader errors on a cross-root collision), and today the roots coincide.
+function _moduleKeysIn(modulesDir) {
+  try {
+    return fs.readdirSync(modulesDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch { return []; }
+}
+function discoveredModuleKeys(modulesDir) {
+  if (modulesDir) return _moduleKeysIn(modulesDir);
+  const keys = new Set();
+  for (const root of MODULE_ROOTS) for (const k of _moduleKeysIn(path.join(root, 'modules'))) keys.add(k);
+  return [...keys];
+}
+// Absolute path to a discovered module's dir, resolving WHICH root holds it (core package or
+// instance repo). Today both roots coincide → the single checkout.
+function moduleDir(key) {
+  for (const root of MODULE_ROOTS) {
+    const d = path.join(root, 'modules', key);
+    if (fs.existsSync(d)) return d;
+  }
+  return path.join(CORE_ROOT, 'modules', key);
+}
+
+// Match a module key as a DELIMITED token so `dev-box` hits in `'dev-box'` /
+// `mount('dev-box')` but never inside `dev-boxes` or `xdev-box`. Hyphens are
+// non-word chars, so the boundary guards against word-chars AND hyphens on both
+// sides (no lookbehind — portable on every node the unit gate runs).
+function keyTokenRe(key) {
+  const esc = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(^|[^\\w-])${esc}($|[^\\w-])`);
+}
+
+// Pure: scan kernel source text for any hardcoded module key, skipping comment
+// lines. Returns violation strings (one per hit). Exported for the negative test
+// (mirrors scanScopeMapSource / scanDeterministicBody).
+function scanKernelForModuleKeys(text, keys) {
+  const violations = [];
+  if (!keys || keys.length === 0) return violations;
+  const probes = keys.map((k) => ({ key: k, re: keyTokenRe(k) }));
+  String(text == null ? '' : text).split('\n').forEach((raw, i) => {
+    const t = raw.trim();
+    if (!t || t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) return;
+    for (const { key, re } of probes) {
+      if (re.test(raw)) {
+        violations.push(`names module "${key}" at line ${i + 1} — the kernel/module-system machinery must stay module-agnostic; no module key may be hardcoded in core (ADR 0083 §Decision #4).`);
+      }
+    }
+  });
+  return violations;
+}
+
+function checkCoreCarriesNoModuleCode() {
+  const keys = discoveredModuleKeys();
+  const violations = [];
+  for (const relFile of KERNEL_FILES) {
+    if (KERNEL_NAMES_MODULES_OK.has(relFile)) continue; // the registry legitimately names every module
+    let text;
+    try { text = fs.readFileSync(path.join(REPO_ROOT, relFile), 'utf8'); } catch { continue; }
+    for (const v of scanKernelForModuleKeys(text, keys)) violations.push(`${relFile} ${v}`);
+  }
+  return {
+    name: 'core carries no module code',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `kernel machinery (${KERNEL_FILES.length} files) names no discovered module key${keys.length ? ` (keys: ${keys.join(', ')})` : ' (none yet)'} (ADR 0083 §Decision #4).`,
+  };
+}
+
+// ============================================================================
+// Check 12 — the kernel imports no domain (ADR 0091 §1 / BV1.R70)
+// ============================================================================
+//
+// A bounded kernel is only real if it DEPENDS on nothing but itself. This check
+// walks every KERNEL_FILE's relative requires and flags any that reach a
+// non-kernel core file (a soon-to-be-module domain). Kernel→kernel is fine;
+// kernel→grandfathered-infra (the raw base pg pool, the pure path-match util) is
+// fine; a bare npm/node spec is fine. Everything else is a tracked leak.
+//
+// ENFORCING (ADR 0102): the tranche-2 ratchet reached zero, so this is now a hard
+// gate — the kernel imports only itself + grandfathered infra, and any NEW
+// kernel→domain import fails the build (violations). The last leaks cleared were
+// auth.js→db (carved to db-kernel), the doorway's Gemini-key re-exports (→ the
+// art-pipeline 'art.getBuilderGeminiKeyRow' port) and builderRollingAvgGrade (→ the
+// grading 'grade.builderRollingAvgGrade' port), plus reclassifying llm-cache /
+// llm-pricing as kernel-adjacent infra. Adding a leak back reds the build.
+
+// Grandfathered kernel-adjacent targets a KERNEL_FILE may import without it
+// counting as a domain leak. The still-fused src/bongos/db.js monolith is NOT here:
+// a kernel file reaching into it IS a real (tracked) leak until the identity/
+// session slices finish carving into db-kernel.js.
+const KERNEL_IMPORT_ALLOWLIST = new Set([
+  'src/db.js',             // the raw shared pg Pool (base infra; pool.js wraps it)
+  'src/bongos/path-match.js', // pure touches-overlap matcher (no domain logic)
+  // Cross-cutting LLM-cost infra (ADR 0102): a stateless token→USD pricing table
+  // (llm-pricing) + a best-effort content-addressed cache (llm-cache), consumed by
+  // core, the grading module, and the CLI cost tooling ALIKE — no domain logic and
+  // no domain state beyond a cache table. Same category as the pg pool / path-match,
+  // not a domain module core would have to depend on anyway. The doorway may import
+  // them; they never flip the kernel→domain leak.
+  'src/bongos/llm-cache.js',
+  'src/bongos/llm-pricing.js',
+]);
+
+// Pure: for relative require `spec` from kernel file `fromRel` (repo-relative),
+// return the offending non-kernel target relpath, or null if the import is clean
+// (kernel→kernel, kernel→allowlisted-infra, or a bare npm/node spec). Exported
+// for the "actually catches a leak" negative test (mirrors scanScopeMapSource).
+function kernelDomainImport(fromRel, spec, kernelSet = new Set(KERNEL_FILES), allow = KERNEL_IMPORT_ALLOWLIST) {
+  if (!/^\.\.?\//.test(spec)) return null; // bare npm/node spec — not our concern
+  const absTarget = path.resolve(path.dirname(path.join(REPO_ROOT, fromRel)), spec);
+  const r = rel(absTarget);
+  const forms = [r, r + '.js', r.replace(/\/$/, '') + '/index.js'];
+  if (forms.some((f) => kernelSet.has(f))) return null; // kernel → kernel
+  if (forms.some((f) => allow.has(f))) return null;      // grandfathered infra/util
+  if (!/^src\//.test(r)) return null;                    // only flag app-source targets
+  return r.endsWith('.js') || r.endsWith('.json') ? r : `${r}.js`; // name the real file
+}
+
+function checkKernelImportsNoDomain() {
+  const kernelSet = new Set(KERNEL_FILES);
+  const findings = [];
+  for (const relFile of KERNEL_FILES) {
+    let text;
+    try { text = fs.readFileSync(path.join(REPO_ROOT, relFile), 'utf8'); } catch { continue; }
+    for (const raw of text.split('\n')) {
+      const t = raw.trim();
+      if (t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) continue;
+      let m; REQUIRE_RE.lastIndex = 0;
+      while ((m = REQUIRE_RE.exec(raw))) {
+        const target = kernelDomainImport(relFile, m[1], kernelSet);
+        if (target) findings.push(`${relFile} → require('${m[1]}') reaches non-kernel core file ${target} — a kernel file must depend only on the kernel (ADR 0091 §1). Carve ${target}'s domain out (or promote it into the kernel) to clear this.`);
+      }
+    }
+  }
+  return {
+    name: 'kernel imports no domain',
+    ok: findings.length === 0,
+    hardFail: findings.length > 0, // ENFORCING (ADR 0102): the ratchet reached zero — any new kernel→domain import now reds the build
+    violations: findings,
+    warnings: [],
+    note: `every KERNEL_FILE (${KERNEL_FILES.length}) must import only the kernel + grandfathered infra — ENFORCING (ADR 0091 §1 / ADR 0102).${findings.length ? ` ${findings.length} leak(s).` : ' Boundary clean.'}`,
+  };
+}
+
+// ============================================================================
+// Check 11 — module migrations are additive + namespaced (ADR 0083 §Decision #5 / design 04§3)
+// ============================================================================
+//
+// A module owns its DB slice through migrations under modules/<key>/migrations/.
+// Two invariants keep that slice from clobbering core or a sibling:
+//   • ADDITIVE — no destructive DDL. "Disable a module" means "stop applying its
+//     migrations," never "drop its tables" (ADR 0083 §Module-owned migrations);
+//     there is no down path, so a DROP/TRUNCATE can only be an accident.
+//   • NAMESPACED — every object it CREATEs lives under the <key>_ prefix
+//     (dev-box → dev_box_), and it may only ALTER its own namespaced tables;
+//     core/sibling state is reached through the doorway/seams, never raw DDL.
+//
+// LEGACY_NAMESPACED: tables that predate the <key>_-prefix convention (created before the module
+// system existed). Grandfathered per-module to avoid requiring a rename migration for legacy prod
+// data. The fitness rule applies in full to any NEW migration a module ships.
+const LEGACY_NAMESPACED = {
+  // game module: world_events + players were created before the module system (V1 schema). The
+  // schema_migrations table is a core tracking table that every migration may re-create idempotently.
+  game: new Set(['world_events', 'players', 'schema_migrations']),
+};
+const DESTRUCTIVE_DDL = [
+  { re: /\bdrop\s+table\b/i, label: 'DROP TABLE' },
+  { re: /\balter\s+table\b[\s\S]*?\bdrop\s+(?:column|constraint)\b/i, label: 'ALTER TABLE … DROP COLUMN/CONSTRAINT' },
+  { re: /\bdrop\s+(?:column|constraint)\b/i, label: 'DROP COLUMN/CONSTRAINT' },
+  { re: /\bdrop\s+(?:index|type|view|sequence|schema|materialized\s+view)\b/i, label: 'DROP <object>' },
+  { re: /\btruncate\b/i, label: 'TRUNCATE' },
+];
+const CREATE_OBJ_RE = /\bcreate\s+(?:or\s+replace\s+)?(?:unique\s+)?(?:materialized\s+)?(table|view|sequence|type)\s+(?:if\s+not\s+exists\s+)?("?[\w.]+"?)/gi;
+const CREATE_INDEX_RE = /\bcreate\s+(?:unique\s+)?index\s+(?:concurrently\s+)?(?:if\s+not\s+exists\s+)?(?:"?[\w.]+"?)\s+on\s+(?:only\s+)?("?[\w.]+"?)/gi;
+const ALTER_TABLE_RE = /\balter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?("?[\w.]+"?)/gi;
+
+// SQL object-namespace prefix for a module key: dev-box → dev_box (SQL-safe).
+function moduleNamespace(key) { return key.replace(/-/g, '_'); }
+
+// strip SQL comments so a commented-out statement is never scanned
+function stripSqlComments(sql) {
+  return String(sql == null ? '' : sql)
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/--[^\n]*/g, ' ');
+}
+
+// is `rawName` (possibly quoted / schema-qualified) under the <ns>_ namespace?
+function inNamespace(rawName, ns, legacySet) {
+  const name = String(rawName).replace(/"/g, '').replace(/^[A-Za-z_]\w*\./, '');
+  return name.startsWith(ns + '_') || (legacySet && legacySet.has(name));
+}
+
+// A CHECK-enum WIDENING is additive-in-spirit: `DROP CONSTRAINT IF EXISTS <c>` PAIRED
+// with a re-`ADD CONSTRAINT <c>` (SAME name) in the SAME migration only PERMITS more
+// values — no existing row changes, no data is lost (task 1978: provisioning gains a
+// 'standalone' hosting_shape). Allow that exact pattern; a BARE `DROP CONSTRAINT` (no
+// re-add), or any DROP TABLE/COLUMN/TRUNCATE, stays destructive. PURE.
+function reAddedConstraintNames(sql) {
+  const names = new Set();
+  const re = /\badd\s+constraint\s+("?[\w.]+"?)/gi;
+  let m;
+  while ((m = re.exec(sql))) names.add(m[1].replace(/"/g, ''));
+  return names;
+}
+function isConstraintWidening(stmt, reAdded) {
+  const m = /\bdrop\s+constraint\s+(?:if\s+exists\s+)?("?[\w.]+"?)/i.exec(stmt);
+  if (!m) return false;                                  // not a DROP CONSTRAINT at all
+  // never let a DROP CONSTRAINT statement smuggle a table/column drop past the gate
+  if (/\bdrop\s+(?:table|column|index|type|view|sequence|schema|materialized\s+view)\b/i.test(stmt)) return false;
+  if (/\btruncate\b/i.test(stmt)) return false;
+  return reAdded.has(m[1].replace(/"/g, ''));            // re-added same-named constraint → widening
+}
+
+// Pure: violations for ONE module's migration SQL. Exported for the negative test.
+function moduleMigrationViolations(key, sql) {
+  const ns = moduleNamespace(key);
+  const legacy = LEGACY_NAMESPACED[key] || null;
+  const clean = stripSqlComments(sql);
+  const violations = [];
+  // additive — scan per statement so an ALTER…DROP never spans a `;`
+  const reAdded = reAddedConstraintNames(clean);
+  for (const stmt of clean.split(';')) {
+    if (isConstraintWidening(stmt, reAdded)) continue; // additive CHECK-enum widening (task 1978)
+    for (const d of DESTRUCTIVE_DDL) {
+      if (d.re.test(stmt)) {
+        violations.push(`module "${key}" migration uses destructive DDL (${d.label}) — module migrations must be ADDITIVE; disabling a module stops applying, it never drops (ADR 0083 §Decision #5).`);
+        break; // one destructive flag per statement is enough
+      }
+    }
+  }
+  // namespaced — CREATEd objects + ALTER targets must live under <ns>_ (or be grandfathered)
+  let m;
+  CREATE_OBJ_RE.lastIndex = 0;
+  while ((m = CREATE_OBJ_RE.exec(clean))) {
+    if (!inNamespace(m[2], ns, legacy)) {
+      violations.push(`module "${key}" migration creates ${m[1].toUpperCase()} ${m[2]} outside its namespace — module objects must be ${ns}_-prefixed (ADR 0083 §Decision #5).`);
+    }
+  }
+  CREATE_INDEX_RE.lastIndex = 0;
+  while ((m = CREATE_INDEX_RE.exec(clean))) {
+    if (!inNamespace(m[1], ns, legacy)) {
+      violations.push(`module "${key}" migration indexes a non-namespaced table ${m[1]} — a module migration may only touch its own ${ns}_ tables (ADR 0083 §Decision #5).`);
+    }
+  }
+  ALTER_TABLE_RE.lastIndex = 0;
+  while ((m = ALTER_TABLE_RE.exec(clean))) {
+    if (!inNamespace(m[1], ns, legacy)) {
+      violations.push(`module "${key}" migration alters a non-namespaced table ${m[1]} — a module migration may only touch its own ${ns}_ tables; reach core state through the doorway/seams, not DDL (ADR 0083 §Decision #5).`);
+    }
+  }
+  return violations;
+}
+
+function checkModuleMigrationsAdditive() {
+  const violations = [];
+  let scanned = 0;
+  for (const key of discoveredModuleKeys()) { // union across module roots (ADR 0108 §Consequences #4)
+    const migDir = path.join(moduleDir(key), 'migrations');
+    let files = [];
+    try { files = fs.readdirSync(migDir).filter((f) => f.endsWith('.sql')); } catch { continue; }
+    for (const f of files.sort()) {
+      scanned += 1;
+      const sql = fs.readFileSync(path.join(migDir, f), 'utf8');
+      for (const v of moduleMigrationViolations(key, sql)) {
+        violations.push(`modules/${key}/migrations/${f}: ${v}`);
+      }
+    }
+  }
+  return {
+    name: 'module migrations additive + namespaced',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} module migration file(s): additive (no destructive DDL) + <key>_-namespaced objects (ADR 0083 §Decision #5).`,
+  };
+}
+
+// ============================================================================
+// Check 11b — migration FILENAMES are namespaced + no cross-root stem collision
+//             (ADR 0108 §5; extends Check 11 to the cross-repo layer)
+// ============================================================================
+//
+// Check 11 (above) guards a module migration's OBJECTS (additive + <key>_-namespaced
+// tables). THIS check guards migration FILENAMES across all three roots — the
+// discipline that lets the core repo and the instance repo version independently
+// (ADR 0108) without their migrations colliding:
+//   • migrations/*.sql            (CORE)     → NEW files must be core_-prefixed
+//   • migrations/instance/*.sql   (INSTANCE) → stay bare (or instance_-prefixed)
+//   • modules/<key>/migrations/   (MODULE)   → NEW files must be <key>_-prefixed
+// Existing bare files are grandfathered (migration-namespace.js LEGACY_BARE_*). The
+// second invariant is the real bug guard: migrate.sh keys schema_migrations by
+// filename STEM, so two migrations from different sources sharing a stem would apply
+// ONCE and the other be SILENTLY SKIPPED (never applied). Single-root today; W6/task
+// 1886 makes the root resolution two-root-aware once the core installs from node_modules.
+function sqlFilesIn(absDir) {
+  try { return fs.readdirSync(absDir).filter((f) => f.endsWith('.sql')).sort(); }
+  catch { return []; } // dir absent (e.g. no migrations/instance in a vanilla instance) → nothing to scan
+}
+
+function checkMigrationNamespacing() {
+  const violations = [];
+  const files = []; // { source, moduleKey?, basename } — fed to the stem-collision scan
+
+  const coreFiles = sqlFilesIn(path.join(CORE_ROOT, 'migrations')); // core migrations ship in the core package
+  for (const f of coreFiles) {
+    const v = filenameViolation(CORE_NS, f);
+    if (v) violations.push(`migrations/${f}: ${v}`);
+    files.push({ source: CORE_NS, basename: f });
+  }
+
+  const instFiles = sqlFilesIn(path.join(INSTANCE_ROOT, 'migrations', 'instance')); // instance seeds live in the host repo
+  for (const f of instFiles) {
+    const v = filenameViolation(INSTANCE_NS, f);
+    if (v) violations.push(`migrations/instance/${f}: ${v}`);
+    files.push({ source: INSTANCE_NS, basename: f });
+  }
+
+  let moduleCount = 0;
+  for (const key of discoveredModuleKeys()) {
+    for (const f of sqlFilesIn(path.join(moduleDir(key), 'migrations'))) {
+      moduleCount += 1;
+      const v = filenameViolation('module', f, { moduleKey: key });
+      if (v) violations.push(`modules/${key}/migrations/${f}: ${v}`);
+      files.push({ source: 'module', moduleKey: key, basename: f });
+    }
+  }
+
+  for (const c of stemCollisions(files)) {
+    violations.push(`migration stem "${c.stem}" is produced by more than one source (${c.files.join(', ')}) — schema_migrations is stem-keyed, so one applies and the rest are SILENTLY SKIPPED; namespace them (ADR 0108 §5).`);
+  }
+
+  return {
+    name: 'migration filenames namespaced + no stem collision (ADR 0108 §5)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${coreFiles.length} core + ${instFiles.length} instance + ${moduleCount} module migration file(s): new core→core_, new module→<key>_, instance bare; no cross-root stem collision.`,
+  };
+}
+
+// ============================================================================
+// 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.
+const IDENTITY_SCAN_ROOTS = ['src/bongos', 'modules'];
+const IDENTITY_SCAN_EXTRA_FILES = ['scripts/gds/architect-audit.js'];
+const IDENTITY_SCAN_EXTS = new Set(['.js', '.html', '.css']);
+// 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']);
+
+// Strip comments so a rationale comment naming the old brand never trips the scan.
+// The JS // strip is `://`-safe (keeps the char before `//` unless it's `:`), so a
+// hardcoded "https://amazonprimea.com" URL is NOT truncated and still gets caught.
+function stripCommentsForIdentity(text, ext) {
+  let t = String(text == null ? '' : text);
+  if (ext === '.html') return t.replace(/<!--[\s\S]*?-->/g, '');
+  t = t.replace(/\/\*[\s\S]*?\*\//g, ''); // block comments (js + css)
+  if (ext === '.js') t = t.split('\n').map((l) => l.replace(/(^|[^:])\/\/.*$/, '$1')).join('\n');
+  return t;
+}
+
+// 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 }); }
+  }
+  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;
+    violations.push(...scanPromptIdentity(relFile, text));
+  }
+  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 (src/bongos/** + modules/** + kernel-prompt CLIs, minus the instance-1 product + generated dirs) — none may hardcode the host brand; identity comes from branding()/window.__BRANDING__ (ADR 0062 §3/§5).`,
+  };
+}
+
+// ---- 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',
+  };
+}
+
+// ============================================================================
+// Check — hall sections are registry-owned, not hardcoded (BV1.R75 / ADR 0062 §4)
+// ============================================================================
+// The builders'-hall widgets are now a REGISTRY (modules/hall-ui/public/dom-utils.js
+// contributeHallWidget; the core set in modules/hall-ui/public/hall-widgets.js, modules
+// via their own client script). The hall's <main> is filled by builders.js from that
+// registry. So no widget may be hardcoded as a literal <section class="scroll"> inside
+// <main> in index.html — that was the pre-R75 second copy this carve removed. This
+// gate fails if one creeps back, keeping the registry the single source of truth (so a
+// reskin/module-toggle reaches every widget). Self-contained: a pure scan of
+// index.html's <main>, no module/registry state needed. Exported for the unit test.
+// (The hall surface itself carved to modules/hall-ui/public/ in BV1.R85.)
+const HALL_INDEX = path.join(moduleDir('hall-ui'), 'public', 'index.html'); // hall-ui is a module — resolve its root (ADR 0108)
+
+function hallMainSlice(html) {
+  // Strip HTML comments first so a comment that merely MENTIONS <main> or a
+  // <section class="scroll"> (e.g. the carve's own explanatory note) never trips
+  // the scan — only real, rendered markup counts.
+  const stripped = html.replace(/<!--[\s\S]*?-->/g, '');
+  const open = stripped.indexOf('<main');
+  if (open === -1) return '';
+  const start = stripped.indexOf('>', open);
+  const close = stripped.indexOf('</main>', start === -1 ? open : start);
+  if (start === -1 || close === -1) return '';
+  return stripped.slice(start + 1, close);
+}
+
+function scanHallSectionRegistry(html) {
+  const main = hallMainSlice(html);
+  // A hall widget section carries class="scroll" (possibly with modifiers, e.g.
+  // "scroll scroll--welcome"). Catch any <section ... class="...scroll..."> in <main>.
+  const re = /<section\b[^>]*\bclass\s*=\s*"(?:[^"]*\b)?scroll\b[^"]*"/gi;
+  const hits = main.match(re) || [];
+  return hits.map((h) => h.replace(/\s+/g, ' ').trim());
+}
+
+function checkHallSectionRegistry() {
+  let html = '';
+  try { html = fs.readFileSync(HALL_INDEX, 'utf8'); }
+  catch { return { name: 'hall widgets are registry-owned (ADR 0062 §4)', ok: true, hardFail: false, violations: [], warnings: ['modules/hall-ui/public/index.html not found — skipped'], note: 'index.html absent.' }; }
+  const hardcoded = scanHallSectionRegistry(html);
+  const violations = hardcoded.map((s) =>
+    `modules/hall-ui/public/index.html <main> hardcodes a hall section "${s}" — register it via window.OTB.contributeHallWidget (modules/hall-ui/public/hall-widgets.js for core, a module's client script otherwise), don't inline the markup (BV1.R75 / ADR 0062 §4).`);
+  return {
+    name: 'hall widgets are registry-owned (ADR 0062 §4)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: 'modules/hall-ui/public/index.html <main> contains no hardcoded <section class="scroll"> — the hall-widget registry is the single source of truth.',
+  };
+}
+
+// ============================================================================
+// Check 16 — core code must not HARD-require an instance-excluded config/*.json
+// ============================================================================
+//
+// A vanilla self-host boot ships only the PUBLISHABLE tree (publish-manifest.js). An
+// instance-only config (config/devbox-app.json, config/bongos-cli.json, config/branding.json,
+// config/modules.json, …) is boundary-EXCLUDED, so a bare `require('../../config/<excluded>.json')`
+// in core code throws MODULE_NOT_FOUND and CRASHES the boot on a fresh instance — the exact
+// class that shipped in R88 (two hard-requires in src/bongos/serve-internal.js; task 1824). The
+// cure is to guard the read (tryRequireConfig / fs.existsSync → fail-to-vanilla), which also
+// makes the require a non-literal so it no longer matches here. Check 1 (core↔host) scans
+// code→code IMPORTS and misses this code→config class. Only an EXCLUDED config is a violation;
+// a publishable neutral.*/schema config (which ships with the core) is fine.
+const CONFIG_REQUIRE_RE = /require\(\s*['"]([^'"]*config\/[^'"]*\.json)['"]\s*\)/g;
+
+function checkCoreRequiresExcludedConfig() {
+  const { isPublishable } = require('./publish-manifest');
+  const violations = [];
+  // src/ + scripts/ are CORE; modules ship from BOTH roots (ADR 0108 §Consequences #4). Dedup by
+  // repo-relative path so a shared checkout scans each file once.
+  const seen = new Set();
+  const allAbs = [
+    ...['src', 'scripts'].flatMap((d) => walkJs(path.join(CORE_ROOT, d))),
+    ...walkJsAllRoots('modules'),
+  ];
+  for (const abs of allAbs) {
+    const relFile = rel(abs);
+    if (seen.has(relFile)) continue;
+    seen.add(relFile);
+    if (!isPublishable(relFile)) continue; // only CORE (publishable) code can crash a vanilla boot
+    for (const raw of fs.readFileSync(abs, 'utf8').split('\n')) {
+      const trimmed = raw.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+      let m;
+      CONFIG_REQUIRE_RE.lastIndex = 0;
+      while ((m = CONFIG_REQUIRE_RE.exec(raw))) {
+        const relCfg = rel(path.resolve(path.dirname(abs), m[1]));
+        if (!isPublishable(relCfg)) {
+          violations.push(`${relFile} → require('${m[1]}') hard-requires an instance-excluded config (${relCfg}) — guard the read (tryRequireConfig / fs.existsSync, fail-to-vanilla) so a fresh core boots (task 1824).`);
+        }
+      }
+    }
+  }
+  return {
+    name: 'core never hard-requires an excluded config (task 1824)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: "a publishable src/·scripts/·modules/ .js must not require('…config/X.json') when X.json is boundary-excluded — guard the read so a vanilla core boots.",
+  };
+}
+
+// ============================================================================
+// Check 17 — no route hand-rolls a FLAT error (BV1 R03 / task 1990 / ADR 0116)
+// ============================================================================
+//
+// The error-envelope contract (ADR 0116) says every failure is the ONE envelope
+// `{error:{code,message,details}}`, emitted via res.fail() or a thrown ApiError
+// (the R02 middleware, task 1989). A hand-rolled flat error —
+// `res.status(n).json({ error: 'x' })` or `.json({ error })` — breaks the
+// contract: the caller gets a bare string where the envelope should be.
+//
+// RATCHET, not big-bang. The R04 sweep (task 1991) migrates the ~562 existing
+// sites; until it finishes they'd all "fail" a strict check, so this HOLDS THE
+// LINE: it fails only when the count rises ABOVE the committed baseline (a NEW
+// hand-rolled flat error), and nudges the baseline DOWN as the sweep shrinks it.
+// When the sweep reaches 0, FLAT_ERROR_BASELINE is 0 and any new flat error
+// hard-fails immediately. Detector is shared with the sweep + its test.
+const FLAT_ERROR_BASELINE = 0; // R04 sweep (task 1991) landed the surface at 0 — the gate is now hard-zero: any new hand-rolled flat error fails the build immediately.
+// A flat error is a `.json({ … })` whose FIRST key is `error` with a value that
+// is NOT an object literal (a string/var/shorthand). The envelope's nested
+// `error: { … }` and `.json(envelope(…))` deliberately do NOT match.
+// The `(?!\s*\{)` lookahead is whitespace-aware: without the inner `\s*` the
+// preceding `\s*` backtracks to zero and the lookahead is tested at the space in
+// `error: {`, so the compliant nested envelope was wrongly flagged (task 2029).
+const FLAT_ERROR_VALUE_RE = /\.json\(\s*\{\s*error\s*:\s*(?!\s*\{)/g; // error: 'x' | error: code
+const FLAT_ERROR_SHORTHAND_RE = /\.json\(\s*\{\s*error\s*[,}]/g;   // { error } | { error, … }
+
+// Strip // line comments + /* */ block comments AND blank out string/template
+// contents (keeping the delimiters) so neither a DOC example of the anti-pattern
+// — e.g. the res.fail() usage note in middleware/error-envelope.js — nor a
+// pattern quoted inside a string literal is counted as a real flat error once
+// the gate is hard-zero (task 1991). Real flat errors are unaffected: in
+// `res.status(404).json({ error: 'x' })` the `.json({ error:` the detector keys
+// on is CODE (outside the string), so blanking the `'x'` content still matches.
+function stripCommentsForFlat(src) {
+  let out = '';
+  let i = 0;
+  let quote = null;
+  while (i < src.length) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (quote) {
+      // inside a string/template: drop content, keep only the closing delimiter
+      if (c === '\\') { i += 2; continue; }
+      if (c === quote) { out += c; quote = null; }
+      i++; continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i++; continue; }
+    if (c === '/' && d === '/') { while (i < src.length && src[i] !== '\n') i++; continue; }
+    if (c === '/' && d === '*') { i += 2; while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++; i += 2; continue; }
+    out += c; i++;
+  }
+  return out;
+}
+
+function countFlatErrors(text) {
+  const code = stripCommentsForFlat(text);
+  return (code.match(FLAT_ERROR_VALUE_RE) || []).length
+       + (code.match(FLAT_ERROR_SHORTHAND_RE) || []).length;
+}
+
+// scanFlatErrorSites() — per-file flat-error counts across the API surface
+// (core src/bongos + every module), skipping tests. Shared by the check below, the
+// R04 codemod, and tests/api_error_envelope_buildcheck.mjs.
+function scanFlatErrorSites() {
+  const seen = new Set();
+  const byFile = {};
+  let total = 0;
+  const files = [
+    ...walkJs(path.join(CORE_ROOT, 'src', 'bongos')),
+    ...walkJsAllRoots('modules'),
+  ];
+  for (const abs of files) {
+    const relFile = rel(abs);
+    if (seen.has(relFile)) continue;
+    seen.add(relFile);
+    if (relFile.includes('/tests/') || relFile.endsWith('.test.js')) continue;
+    const n = countFlatErrors(fs.readFileSync(abs, 'utf8'));
+    if (n) { byFile[relFile] = n; total += n; }
+  }
+  return { total, byFile };
+}
+
+function checkErrorEnvelope() {
+  const { total, byFile } = scanFlatErrorSites();
+  const violations = [];
+  const warnings = [];
+  if (total > FLAT_ERROR_BASELINE) {
+    const top = Object.entries(byFile).sort((a, b) => b[1] - a[1]).slice(0, 8)
+      .map(([f, n]) => `${f} (${n})`).join(', ');
+    violations.push(
+      `${total} hand-rolled flat-error sites — ABOVE the ${FLAT_ERROR_BASELINE} baseline. A new route emitted a flat \`res.status(n).json({error:'x'})\` instead of \`res.fail('x', n)\` / \`throw new ApiError('x')\` (ADR 0116). Top files: ${top}. Use the envelope helper (src/bongos/middleware/error-envelope.js).`
+    );
+  } else if (total < FLAT_ERROR_BASELINE) {
+    warnings.push(
+      `${total} flat-error sites — BELOW the ${FLAT_ERROR_BASELINE} baseline. The sweep tightened; lower FLAT_ERROR_BASELINE to ${total} in fitness.js so the ratchet can't slip back (BV1 R04 / task 1991).`
+    );
+  }
+  return {
+    name: 'no route hand-rolls a flat error (ADR 0116 / R03)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `≤ ${FLAT_ERROR_BASELINE} flat \`.json({error:'…'})\` sites (ratchet → 0 as the R04 sweep lands); currently ${total}. New failures must use res.fail()/ApiError (the R02 envelope).`,
+  };
+}
+
+// ============================================================================
+// 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
+]);
+
+function scanUnvalidatedWriteRoutes(model = genApiDocs.extractModel()) {
+  const unvalidated = [];
+  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;
+    if (WRITE_VALIDATION_EXEMPT.has(`${r.method} ${r.route}`)) continue;
+    unvalidated.push(`${r.method} ${r.route}  [${r.file}]`);
+  }
+  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); ${unvalidated.length} unvalidated.`,
+  };
+}
+
+// ---- runner ----------------------------------------------------------------
+
+const CHECKS = [
+  checkCoreHostBoundary,
+  checkClaudeMdBudget,
+  checkNestedDocsPresent,
+  checkRankGuards,
+  checkGeneratedArtifactsFresh,
+  checkDeterministicRoutines,
+  checkCoreNeverImportsModule,
+  checkModulesImportOnlyApi,
+  checkScopeMapImportsProtected,
+  checkCoreCarriesNoModuleCode,
+  checkKernelImportsNoDomain,
+  checkModuleMigrationsAdditive,
+  checkMigrationNamespacing, // Check 11b — ADR 0108 §5 cross-repo migration filenames + stem collision
+  checkDesignContract,
+  checkKernelPromptsNoHardcodedIdentity, // BV1.R76 — kernel prompts read identity from branding()
+  checkHallSectionRegistry,
+  checkCoreRequiresExcludedConfig, // task 1824 — core→instance-config require guard
+  checkErrorEnvelope, // Check 17 — BV1 R03 / task 1990: no route hand-rolls a flat error (ADR 0116)
+  checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
+];
+
+function runAll() {
+  return CHECKS.map((fn) => fn());
+}
+
+function main() {
+  const results = runAll();
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+  } else {
+    console.log('Architecture fitness functions (Path C / ADR 0062 §9)\n');
+    for (const r of results) {
+      const mark = r.hardFail ? '✗ FAIL' : (r.warnings.length ? '! WARN' : '✓ PASS');
+      console.log(`${mark}  ${r.name}`);
+      console.log(`        ${r.note}`);
+      for (const v of r.violations) console.log(`        ✗ ${v}`);
+      for (const w of r.warnings) console.log(`        ! ${w}`);
+    }
+    const failed = results.filter((r) => r.hardFail).length;
+    console.log(`\n${failed ? `${failed} check(s) FAILED` : 'all checks passed'}.`);
+  }
+  process.exit(results.some((r) => r.hardFail) ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  runAll,
+  resolvesToHostGame,
+  checkCoreHostBoundary,
+  checkClaudeMdBudget,
+  checkNestedDocsPresent,
+  checkRankGuards,
+  checkGeneratedArtifactsFresh,
+  checkDeterministicRoutines,
+  checkCoreNeverImportsModule,
+  checkModulesImportOnlyApi,
+  checkScopeMapImportsProtected,
+  checkCoreCarriesNoModuleCode,
+  checkKernelImportsNoDomain,
+  checkModuleMigrationsAdditive,
+  checkMigrationNamespacing, // Check 11b — ADR 0108 §5 cross-repo migration filenames
+  checkDesignContract,
+  checkKernelPromptsNoHardcodedIdentity, // BV1.R76 / task 1705
+  scanPromptIdentity,                    // BV1.R76 — negative-test hook
+  stripCommentsForIdentity,              // task 1705 — comment-strip helper (tested)
+  checkHallSectionRegistry,
+  scanHallSectionRegistry,
+  hallMainSlice,
+  checkErrorEnvelope,       // Check 17 — BV1 R03 / task 1990 (ADR 0116)
+  scanFlatErrorSites,       // shared with the R04 sweep + its test
+  countFlatErrors,          // per-text detector (tested)
+  FLAT_ERROR_BASELINE,
+  checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999 (ADR 0118)
+  scanUnvalidatedWriteRoutes, // shared with its test
+  WRITE_VALIDATION_EXEMPT,
+  scanScopeMapSource,
+  scanKernelForModuleKeys,
+  kernelDomainImport,
+  KERNEL_FILES,
+  discoveredModuleKeys,
+  moduleMigrationViolations,
+  moduleNamespace,
+  resolvesToModule,
+  moduleImportViolation,
+  moduleOwnerOf,
+  // test/ratchet hook: toggle the module boundary enforce flag. Default is now
+  // ENFORCING (BV1.R45 / task 1414); tests that need warn-mode restore the
+  // default in a finally.
+  _setModuleBoundaryEnforcing: (v) => { MODULE_BOUNDARY_ENFORCING = !!v; },
+  scanDeterministicBody,
+  HOST_GAME,
+  GRANDFATHERED,
+  LEGACY_NAMESPACED,
+  KERNEL_FILES,
+  ROOT_HARD_MAX,
+  ROOT_TARGET,
+  ROOT_CHAR_HARD_MAX,
+  ROOT_CHAR_TARGET,
+  HIGH_TRAFFIC,
+};