@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/gating.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// scripts/bongos/gating.js — owner kill-switch for main-branch merge gating.
+//
+// What "gating" means here — TWO independent levers, both toggled together:
+//   1. GitHub branch protection on `main`: required status checks ONLY — no
+//      review requirement of any kind (ADR 0162, task 1002635: the owner
+//      retired the code-owner/human-approval layer after it stranded graded
+//      work; gates are rank-consistent CI checks, and the normalization in
+//      cmdOn keeps a pre-retirement snapshot from resurrecting it). The
+//      required contexts are ONLY checks that exist and can pass today —
+//      currently `unit` (the suite + fitness lane, task 1002610). The planned
+//      `secret-scan` and `gate-review` contexts (ADR 0058 phase 3;
+//      CORE_EXPECTED_CHECKS in adopt-preflight.js) join DEFAULT_PROTECTION
+//      when their workflows ship — requiring a context nothing reports blocks
+//      every merge indefinitely (D-12, ADR 0159).
+//   2. The application-layer trust gates that run on every PR — the gate-review
+//      and grade-gate CI workflows (ADR 0058 phases 1-3; NOT YET IN THE TREE —
+//      workflowState() reports them 'absent' and the toggles below no-op until
+//      they ship). Once live they post their own status checks and the ship /
+//      auto-merge pipeline refuses to land a PR while gate-review is red
+//      (it escalates gate-surface changes — infra/, migrations/, CODEOWNERS,
+//      scripts/bongos plumbing — to owner approval). Branch protection alone does
+//      NOT neutralize these, which is why `off` also `gh workflow disable`s them.
+// With gating ON, every PR — gate-surface or not — merges on the required
+// status checks alone; no human approval is ever required (ADR 0162).
+// With gating OFF, ordinary `gh pr merge N` (and every builder / autonomous
+// session) merges with no checks and no approval. `unit` keeps running either
+// way — a real safety net that forces no approval.
+//
+// It is REVERSIBLE by construction: `off` snapshots the live protection to a
+// replay-ready file, then deletes protection; `on` PUTs the snapshot back,
+// byte-for-byte. If the snapshot is missing, `on` falls back to a baked-in
+// known-good config (printed loudly) so you can never get permanently stuck.
+//
+// ⚠ While OFF, ANY merge to `main` reaches prod with no checks and no review —
+//   yours, any builder's, any autonomous session's. This is a deliberate,
+//   owner-only, temporary posture. Flip it back with `on` when done.
+//
+// Usage:
+//   node scripts/bongos/gating.js status     # show current protection + snapshot state
+//   node scripts/bongos/gating.js off         # snapshot, then remove all protection
+//   node scripts/bongos/gating.js on          # restore protection from the snapshot
+//
+// Auth: uses the `gh` CLI, which must be authenticated as a repo admin (the
+// owner). This is a trust-boundary surface (ADR 0016/0043) — owner-gated in
+// CODEOWNERS so a builder cannot weaken the gate by editing this file.
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const BRANCH = 'main';
+const SNAPSHOT = require('../../src/instance-config').configPath('gating-snapshot.json');
+
+// The application-layer trust gates that run on every PR and force owner
+// approval / --admin on gate-surface changes. Branch protection alone does NOT
+// neutralize these — they post their own status checks and the auto-merge /
+// ship pipeline refuses to land a PR while gate-review is red. So the kill-switch
+// also disables/enables these workflows. PLANNED, not yet in the tree (ADR 0058
+// phases 1-3): while absent, workflowState() reports 'absent' and both toggles
+// no-op — the names stay here so the switch covers them the moment they ship.
+// `unit` is deliberately left running — a real safety net that forces no approval.
+const GATE_WORKFLOWS = ['gate-review.yml', 'grade-gate.yml'];
+
+// Baked-in known-good config. Used only as a restore fallback when no snapshot
+// exists, so `on` can never be stuck. Requires ONLY contexts that exist and can
+// pass today (ADR 0159 — D-12: a required context nothing reports blocks every
+// merge indefinitely, and a required context that is red on every PR does the
+// same). When the secret-scan / gate-review workflows ship (ADR 0058), add
+// their contexts back here — those names are the contract (adopt-preflight.js
+// CORE_EXPECTED_CHECKS, init.js), tool-agnostic on purpose.
+const DEFAULT_PROTECTION = {
+  required_status_checks: {
+    strict: false,
+    checks: [
+      { context: 'unit', app_id: 15368 },
+      // Stated intent, not yet requirable — uncomment as each workflow ships:
+      // { context: 'secret-scan', app_id: 15368 },  // secret scanning (ADR 0058)
+      // { context: 'gate-review', app_id: 15368 },  // gate-surface review (ADR 0058 phase 3)
+    ],
+  },
+  enforce_admins: false,
+  // ADR 0162 (task 1002635): review gates are RETIRED — the owner chose
+  // rank-consistent CI checks over human-approval gates after the code-owner
+  // requirement stranded graded-PASS work (PR 28). Never reintroduce a
+  // required_pull_request_reviews block here; cmdOn also normalizes snapshots.
+  required_pull_request_reviews: null,
+  restrictions: null,
+};
+
+function gh(args, opts = {}) {
+  return execFileSync('gh', args, {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    ...opts,
+  });
+}
+
+function repoSlug() {
+  try {
+    return gh(['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner']).trim();
+  } catch (e) {
+    fail('could not resolve the repo via `gh repo view` — is gh installed and run inside the repo?', e);
+  }
+}
+
+// GET protection. Returns the parsed object, or null if protection is OFF
+// (GitHub returns 404 "Branch not protected").
+function getProtection(repo) {
+  try {
+    const out = gh(['api', `repos/${repo}/branches/${BRANCH}/protection`]);
+    return JSON.parse(out);
+  } catch (e) {
+    const msg = `${e.stderr || ''}${e.stdout || ''}`;
+    if (/Branch not protected|Not Found|HTTP 404/i.test(msg)) return null;
+    fail('failed to read branch protection', e);
+  }
+}
+
+// Transform a GET-protection response into a valid PUT body (the two shapes
+// differ — GET nests booleans under {enabled}, PUT wants flat values).
+function toPutBody(p) {
+  const body = {
+    required_status_checks: null,
+    enforce_admins: !!(p.enforce_admins && p.enforce_admins.enabled),
+    required_pull_request_reviews: null,
+    restrictions: null,
+  };
+  if (p.required_status_checks) {
+    const rsc = p.required_status_checks;
+    body.required_status_checks = { strict: !!rsc.strict };
+    if (Array.isArray(rsc.checks) && rsc.checks.length) {
+      body.required_status_checks.checks = rsc.checks.map((c) => ({
+        context: c.context,
+        app_id: c.app_id ?? null,
+      }));
+    } else {
+      body.required_status_checks.contexts = rsc.contexts || [];
+    }
+  }
+  if (p.required_pull_request_reviews) {
+    const r = p.required_pull_request_reviews;
+    const rb = {
+      dismiss_stale_reviews: !!r.dismiss_stale_reviews,
+      require_code_owner_reviews: !!r.require_code_owner_reviews,
+      required_approving_review_count: r.required_approving_review_count ?? 0,
+    };
+    if (typeof r.require_last_push_approval === 'boolean') {
+      rb.require_last_push_approval = r.require_last_push_approval;
+    }
+    body.required_pull_request_reviews = rb;
+  }
+  if (p.restrictions) {
+    body.restrictions = {
+      users: (p.restrictions.users || []).map((u) => u.login),
+      teams: (p.restrictions.teams || []).map((t) => t.slug),
+      apps: (p.restrictions.apps || []).map((a) => a.slug),
+    };
+  }
+  for (const key of [
+    'required_linear_history',
+    'allow_force_pushes',
+    'allow_deletions',
+    'block_creations',
+    'required_conversation_resolution',
+    'lock_branch',
+    'allow_fork_syncing',
+  ]) {
+    if (p[key] && typeof p[key].enabled === 'boolean') body[key] = p[key].enabled;
+  }
+  return body;
+}
+
+function putProtection(repo, putBody) {
+  gh(['api', '-X', 'PUT', `repos/${repo}/branches/${BRANCH}/protection`, '--input', '-'], {
+    input: JSON.stringify(putBody),
+  });
+}
+
+function deleteProtection(repo) {
+  gh(['api', '-X', 'DELETE', `repos/${repo}/branches/${BRANCH}/protection`]);
+}
+
+// --- gate CI workflows ('active' | 'disabled_manually' | 'disabled_inactivity') ---
+function workflowState(repo, wf) {
+  try {
+    return gh(['api', `repos/${repo}/actions/workflows/${wf}`, '-q', '.state']).trim();
+  } catch {
+    return 'absent'; // not on the default branch / never registered
+  }
+}
+
+function setWorkflow(repo, wf, enable) {
+  // `gh workflow enable/disable` resolves the workflow from the repo context.
+  gh(['workflow', enable ? 'enable' : 'disable', wf]);
+}
+
+function readSnapshot() {
+  try {
+    return JSON.parse(fs.readFileSync(SNAPSHOT, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSnapshot(obj) {
+  fs.mkdirSync(path.dirname(SNAPSHOT), { recursive: true });
+  fs.writeFileSync(SNAPSHOT, JSON.stringify(obj, null, 2));
+}
+
+function fail(msg, err) {
+  console.error(`\n✗ gating: ${msg}`);
+  if (err && (err.stderr || err.message)) console.error(`  ${(err.stderr || err.message).trim()}`);
+  process.exit(1);
+}
+
+function summarize(putBody) {
+  const checks =
+    putBody.required_status_checks
+      ? (putBody.required_status_checks.checks || putBody.required_status_checks.contexts || [])
+          .map((c) => c.context || c)
+          .join(', ') || '(none)'
+      : '(none)';
+  const review =
+    putBody.required_pull_request_reviews?.require_code_owner_reviews
+      ? 'code-owner review required'
+      : putBody.required_pull_request_reviews
+        ? `${putBody.required_pull_request_reviews.required_approving_review_count || 0} approving review(s)`
+        : 'no PR review required';
+  return { checks, review };
+}
+
+function cmdStatus(repo) {
+  const live = getProtection(repo);
+  const snap = readSnapshot();
+  const wf = GATE_WORKFLOWS.map((w) => ({ w, state: workflowState(repo, w) }));
+  const wfActive = wf.filter((x) => x.state === 'active');
+  console.log(`repo: ${repo}   branch: ${BRANCH}\n`);
+
+  // Lever 1 — branch protection.
+  if (live) {
+    const { checks, review } = summarize(toPutBody(live));
+    console.log('branch protection : 🟢 ON');
+    console.log(`  required checks : ${checks}`);
+    console.log(`  pr review       : ${review}`);
+    console.log(`  enforce_admins  : ${!!(live.enforce_admins && live.enforce_admins.enabled)} (owner can --admin merge when false)`);
+  } else {
+    console.log('branch protection : 🔴 OFF — `main` is UNPROTECTED.');
+  }
+
+  // Lever 2 — gate CI workflows.
+  console.log(`\ngate CI workflows : ${wfActive.length ? '🟢 ON' : '🔴 OFF'}`);
+  for (const x of wf) console.log(`  ${x.w.padEnd(16)}: ${x.state}`);
+
+  const fullyOff = !live && wfActive.length === 0;
+  const fullyOn = !!live && wfActive.length === GATE_WORKFLOWS.length;
+  console.log(`\ngating: ${fullyOff ? '🔴 fully OFF — merges sail through, no checks/approval' : fullyOn ? '🟢 fully ON' : '🟡 PARTIAL — run `off` or `on` to make it consistent'}`);
+  console.log(`snapshot: ${snap ? SNAPSHOT : '(none yet — `off` will create it; `on` would use the baked-in default)'}`);
+}
+
+function cmdOff(repo) {
+  // Lever 1 — branch protection (idempotent).
+  const live = getProtection(repo);
+  if (live) {
+    const putBody = toPutBody(live);
+    writeSnapshot({ saved_at_branch: BRANCH, repo, raw: live, put_body: putBody });
+    const { checks, review } = summarize(putBody);
+    console.log('branch protection: removing.');
+    console.log(`  was: checks [${checks}] + ${review}`);
+    console.log(`  snapshot saved: ${SNAPSHOT}`);
+    deleteProtection(repo);
+  } else {
+    console.log('branch protection: already off.');
+  }
+
+  // Lever 2 — gate CI workflows (idempotent).
+  for (const w of GATE_WORKFLOWS) {
+    const state = workflowState(repo, w);
+    if (state === 'active') {
+      setWorkflow(repo, w, false);
+      console.log(`gate workflow ${w}: disabled.`);
+    } else {
+      console.log(`gate workflow ${w}: already ${state}.`);
+    }
+  }
+
+  console.log('\n🔴 gating OFF. `main` is UNPROTECTED and the gate-review/grade CI gates no longer');
+  console.log('   run — ordinary `gh pr merge N` (and every builder / autonomous session) merges');
+  console.log('   with no checks and no approval. (unit still runs.)');
+  console.log('   ↩  restore everything: node scripts/bongos/gating.js on');
+}
+
+function cmdOn(repo) {
+  // Lever 1 — branch protection (idempotent).
+  const live = getProtection(repo);
+  if (!live) {
+    const snap = readSnapshot();
+    let putBody;
+    if (snap?.put_body) {
+      putBody = snap.put_body;
+      console.log(`branch protection: restoring from snapshot ${SNAPSHOT}`);
+    } else {
+      putBody = DEFAULT_PROTECTION;
+      console.log('⚠ branch protection: no snapshot — restoring the baked-in known-good default.');
+    }
+    // ADR 0162 (task 1002635): review gates are retired. Normalize BOTH restore
+    // paths — a snapshot taken while the code-owner requirement was live would
+    // otherwise silently resurrect it on the next off/on cycle.
+    putBody = { ...putBody, required_pull_request_reviews: null };
+    putProtection(repo, putBody);
+    const after = getProtection(repo);
+    if (!after) fail('PUT returned but protection still reads as OFF — check `gh` auth / admin rights');
+    const { checks, review } = summarize(toPutBody(after));
+    console.log(`  restored: checks [${checks}] + ${review}`);
+  } else {
+    console.log('branch protection: already on.');
+  }
+
+  // Lever 2 — gate CI workflows (idempotent).
+  for (const w of GATE_WORKFLOWS) {
+    const state = workflowState(repo, w);
+    if (state !== 'active' && state !== 'absent') {
+      setWorkflow(repo, w, true);
+      console.log(`gate workflow ${w}: re-enabled.`);
+    } else {
+      console.log(`gate workflow ${w}: already ${state}.`);
+    }
+  }
+
+  console.log('\n🟢 gating ON. Branch protection + the gate-review/grade CI gates are back.');
+}
+
+function main() {
+  const cmd = (process.argv[2] || 'status').toLowerCase();
+  if (!['status', 'off', 'on'].includes(cmd)) {
+    console.error('usage: node scripts/bongos/gating.js <status|off|on>');
+    process.exit(2);
+  }
+  const repo = repoSlug();
+  if (cmd === 'status') cmdStatus(repo);
+  else if (cmd === 'off') cmdOff(repo);
+  else if (cmd === 'on') cmdOn(repo);
+}
+
+main();

package/scripts/{gds → bongos}/gds-db-backup.service

@@ -1,12 +1,12 @@
 # TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
 # substituted at install time; a provisioned instance gets a correct per-instance
-# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# unit pair generated by scripts/bongos/provision.js (task 2213) and never needs this
 # file. Substitute:
 #   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
 #   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
-#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
-#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
-#                          full clone: <instance-root>/scripts/gds
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/bongos dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/bongos
+#                          full clone: <instance-root>/scripts/bongos
 #   __CONFIG_DIR__       the instance config dir name (offsite unit only)
 # One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]
@@ -33,8 +33,8 @@ Group=__SERVICE_USER__
 #
 # EDIT THIS PATH when installing — it must point at the deployed core scripts
 # dir for THIS instance, which differs by layout:
-#   vendored/standalone: /home/<user>/<instance>/node_modules/@bongos/core/scripts/gds/db-backup-nightly.sh
-#   full clone:          /home/<user>/<repo>/scripts/gds/db-backup-nightly.sh
+#   vendored/standalone: /home/<user>/<instance>/node_modules/@bongos/core/scripts/bongos/db-backup-nightly.sh
+#   full clone:          /home/<user>/<repo>/scripts/bongos/db-backup-nightly.sh
 # See docs/recipes/gds-db-backup.md.
 ExecStart=/usr/bin/env bash __CORE_SCRIPTS_DIR__/db-backup-nightly.sh
 # Modest hardening — the script only needs read on the socket + write on

package/scripts/{gds → bongos}/gds-db-backup.timer

@@ -1,12 +1,12 @@
 # TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
 # substituted at install time; a provisioned instance gets a correct per-instance
-# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# unit pair generated by scripts/bongos/provision.js (task 2213) and never needs this
 # file. Substitute:
 #   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
 #   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
-#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
-#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
-#                          full clone: <instance-root>/scripts/gds
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/bongos dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/bongos
+#                          full clone: <instance-root>/scripts/bongos
 #   __CONFIG_DIR__       the instance config dir name (offsite unit only)
 # One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]

package/scripts/{gds → bongos}/gds-db-offsite.service

@@ -1,12 +1,12 @@
 # TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
 # substituted at install time; a provisioned instance gets a correct per-instance
-# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# unit pair generated by scripts/bongos/provision.js (task 2213) and never needs this
 # file. Substitute:
 #   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
 #   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
-#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
-#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
-#                          full clone: <instance-root>/scripts/gds
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/bongos dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/bongos
+#                          full clone: <instance-root>/scripts/bongos
 #   __CONFIG_DIR__       the instance config dir name (offsite unit only)
 # One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]

package/scripts/{gds → bongos}/gds-db-offsite.timer

@@ -1,12 +1,12 @@
 # TEMPLATE — not installable as-is (task 1002757). The __TOKENS__ below MUST be
 # substituted at install time; a provisioned instance gets a correct per-instance
-# unit pair generated by scripts/gds/provision.js (task 2213) and never needs this
+# unit pair generated by scripts/bongos/provision.js (task 2213) and never needs this
 # file. Substitute:
 #   __SERVICE_USER__     the unix user that owns the instance + its Postgres role
 #   __INSTANCE_ROOT__    the instance checkout root (docs live under it)
-#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/gds dir:
-#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/gds
-#                          full clone: <instance-root>/scripts/gds
+#   __CORE_SCRIPTS_DIR__ the deployed core's scripts/bongos dir:
+#                          standalone: <instance-root>/node_modules/@bongos/core/scripts/bongos
+#                          full clone: <instance-root>/scripts/bongos
 #   __CONFIG_DIR__       the instance config dir name (offsite unit only)
 # One-liner: sed -e 's|__SERVICE_USER__|<user>|g' -e … gds-db-backup.service | sudo tee /etc/systemd/system/…
 [Unit]

package/scripts/bongos/gds-literal-scan.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+'use strict';
+// gds-literal-scan.js — the detector behind the GDS→Bongos rename ratchet
+// (criterion C5 of goal 1000073, "the rename cannot come back"; task 1003669).
+//
+// WHY THIS EXISTS. The rename is landing criterion by criterion, and the goal's
+// own sequencing says the ratchet lands SECOND — immediately after the prose
+// pass — because "a rename without a ratchet reappears within a release, which
+// is exactly how this term survived this long". This module is the measurement;
+// the gate is the `legacy_gds_literals` metric in fitness-ratchets.js, which
+// fails the build when the count RISES.
+//
+// WHY A COUNT AND NOT ZERO. Measured after C1 shipped (2026-09-06) there are
+// still ~1,400 GDS literals outside the historical record: the `GDS_*` env
+// names and the `scripts/bongos/` + `/api/gds` paths are criterion C2's job, and
+// C2 deliberately lands BEHIND this ratchet because it is the risky one (hooks,
+// cron routines, .service files and CI all name those paths). A zero-tolerance
+// check could not be landed today and would red every unrelated ship. So this
+// holds the line instead: the number may fall, never rise.
+//
+// WHAT IS NEVER COUNTED. Four kinds of thing, for four different reasons:
+//
+//   1. THE FROZEN RECORD (path-excluded). ADRs, session logs, audits, shipped
+//      scope archives. The goal's rule is "rename what the project says about
+//      itself going forward; leave what it recorded about its past" — an ADR
+//      rewritten to today's vocabulary destroys the evidence that the words
+//      changed.
+//   2. APPLIED MIGRATION FILENAMES (path-excluded). schema_migrations is keyed
+//      by filename stem, so renaming an applied migration makes it look
+//      unapplied and RE-RUNS it. This one is an outage, not an aesthetic.
+//   3. VERSION IDS (token-excluded). `GDS-V3` / `GDS-V4` are row keys in the
+//      versions table, not vocabulary. They are stripped from every line before
+//      counting, so they stay legal even inside a file that is otherwise
+//      counted.
+//
+// Usage:
+//   node scripts/bongos/gds-literal-scan.js            # count + the top offending files
+//   node scripts/bongos/gds-literal-scan.js --files    # every file with its count
+//   node scripts/bongos/gds-literal-scan.js --json
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// The frozen record + applied migration filenames. Matched against the
+// repo-relative path, at any depth, so an instance's own migrations/ and a
+// module-owned migrations/ are covered by the same rule as the core's.
+const GDS_EXCLUDED_PATHS = [
+  /(^|\/)docs\/adr\//,
+  /(^|\/)docs\/session-logs\//,
+  /(^|\/)docs\/audits\//,
+  /(^|\/)limitations\//,
+  /(^|\/)migrations\//,
+];
+
+// Vendored / generated / third-party trees the budgets must not count — the
+// same exclusion fitness-ratchets.js applies to its own metrics.
+const GDS_EXCLUDED_TREES = /(^|\/)(node_modules|public-docs)\/|\.min\.js$|(^|\/)vendor\//;
+
+// The files that STATE the rule. Meta-commentary about a banned word has to be
+// able to name it, or the gate cannot explain itself — the same principle as
+// VOCAB_ALLOW's "the manifest states the rule itself" entry in
+// fitness-checks-vocabulary.js. Without this the detector counts its own
+// explanation, and improving a comment here would red the build.
+const GDS_RULE_FILES = new Set([
+  'scripts/bongos/gds-literal-scan.js',      // this file
+  'scripts/bongos/fitness-ratchets.js',      // the gate: names the metric and carries the builder-facing hint
+  'tests/fitness_gds_ratchet.mjs',        // its test, which must write the literal to prove the gate fires
+  'config/fitness-baselines.json',        // the baseline's own _comment explains what is counted
+  // The RESTRAINT half of the same rename (task 1003697, criterion C5). It fails
+  // the build when the old name is ERASED from the frozen record, so it has to
+  // name both the literal and the version ids it pins — the same reason this
+  // file is exempt. A gate that cannot state its own rule cannot explain itself.
+  'scripts/bongos/rename-history-check.js',
+  'tests/rename_history_restraint.mjs',
+  'config/rename-history-baseline.json',
+  // The LEDGER pass (task 1003698, criterion C4). It has to spell out every
+  // identifier it protects and every phrase shape it rewrites, so it names the
+  // literal more often than any other file in the tree — and its test names it
+  // once per case. Same exemption, same reason.
+  'scripts/bongos/rename-ledger-prose.js',
+  'tests/rename_ledger_prose.mjs',
+]);
+
+// A version id is a row key, not vocabulary. Stripped before matching so it is
+// legal on any line in any counted file.
+const GDS_VERSION_ID_RE = /GDS-V\d+/g;
+
+// An opaque encoded payload is not vocabulary. A committed design mock carries
+// its own content as a base64'd bundle (docs/design/mocks/ideator-surface/
+// ideator-surface.html embeds one in a <script type="__bundler/manifest">), and
+// a three-letter run turns up inside any large base64 blob by chance — five did,
+// which is enough to red the ratchet on a change that introduced no literal at
+// all. The blob cannot be edited to remove them, and the page cannot be
+// committed without it: the manifest IS the page content.
+//
+// So: an unbroken base64-shaped run of 200+ characters is stripped before
+// matching, exactly the way a version id is. The threshold is what makes this
+// safe. The acronym is a WORD wherever it is vocabulary, so it always sits
+// against a boundary — whitespace, punctuation, a case change, an underscore.
+// No line of prose or code reaches 200 unbroken base64 characters, and the
+// blobs that do carry nothing to rename. This is deliberately narrower than a
+// path exclusion on the mocks tree: that tree still counts, so a real literal
+// in a mock's own comment (docs/design/mocks/landing/v1.html:345) is still
+// caught.
+const GDS_ENCODED_BLOB_RE = /[A-Za-z0-9+/=]{200,}/g;
+
+// The literal itself: case-sensitive, so the lowercase path/env spellings that
+// criterion C2 owns (`scripts/bongos/`, `/api/gds`, `gds_session`) are counted
+// only where they appear in their SHOUTING form. Case-sensitivity is the point
+// — `GDS` is the acronym a newcomer trips over.
+const GDS_LITERAL_RE = /GDS/g;
+
+function isExcludedPath(relPath) {
+  if (GDS_RULE_FILES.has(relPath)) return true;
+  if (GDS_EXCLUDED_TREES.test(relPath)) return true;
+  return GDS_EXCLUDED_PATHS.some((re) => re.test(relPath));
+}
+
+// countInText — occurrences of the literal in one file's text, with version ids
+// removed first. Exported so the test and any future sweep share ONE detector
+// (the checkErrorEnvelope precedent: a gate whose detector drifts from its
+// sweep is worse than no gate).
+function countInText(text) {
+  const stripped = text
+    .replace(GDS_ENCODED_BLOB_RE, '')
+    .replace(GDS_VERSION_ID_RE, '');
+  return (stripped.match(GDS_LITERAL_RE) || []).length;
+}
+
+function trackedFiles() {
+  const out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+// scanGdsLiterals — { total, byFile } across every tracked, countable file.
+// Unreadable and binary files are skipped rather than guessed at: a NUL byte
+// means the "occurrences" would be meaningless anyway.
+//
+// `files` and `readFile` are both injectable so the test can exercise the real
+// aggregation — exclusions, counting, per-file totals — WITHOUT writing to the
+// repo. That is not tidiness: the unit lane runs test files in parallel, and an
+// earlier version of the test proved the point by temporarily editing
+// docs/architecture.md and breaking whichever suite happened to be scanning the
+// tree at that moment.
+function scanGdsLiterals({ files = null, readFile = null } = {}) {
+  const read = readFile || ((relPath) => fs.readFileSync(path.join(ROOT, relPath), 'utf8'));
+  const byFile = {};
+  let total = 0;
+  for (const relPath of files || trackedFiles()) {
+    if (isExcludedPath(relPath)) continue;
+    let text;
+    try {
+      text = read(relPath);
+    } catch {
+      continue;
+    }
+    if (text.includes(String.fromCharCode(0))) continue; // binary (a NUL byte)
+    const n = countInText(text);
+    if (n) {
+      byFile[relPath] = n;
+      total += n;
+    }
+  }
+  return { total, byFile };
+}
+
+function main() {
+  const { total, byFile } = scanGdsLiterals();
+  const ranked = Object.entries(byFile).sort((a, b) => b[1] - a[1]);
+  if (process.argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify({ total, byFile }, null, 2)}\n`);
+    return;
+  }
+  const show = process.argv.includes('--files') ? ranked : ranked.slice(0, 20);
+  console.log(`legacy GDS literals: ${total} across ${ranked.length} file(s)`);
+  console.log('(version ids GDS-V## are not counted; docs/adr, docs/session-logs, docs/audits, limitations and migrations are excluded by construction)');
+  console.log('');
+  for (const [f, n] of show) console.log(`  ${String(n).padStart(5)}  ${f}`);
+  if (show.length < ranked.length) console.log(`  … and ${ranked.length - show.length} more file(s) — pass --files for all`);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  GDS_EXCLUDED_PATHS,
+  GDS_RULE_FILES,
+  GDS_EXCLUDED_TREES,
+  GDS_LITERAL_RE,
+  GDS_VERSION_ID_RE,
+  countInText,
+  isExcludedPath,
+  scanGdsLiterals,
+};