@bongos/core 1.20.3 → 1.20.4

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.3",
-  "core_contract": "1.20.3",
-  "source_commit": "08c1ed047c5b8d898c41f3be382772312100c240",
+  "core_version": "1.20.4",
+  "core_contract": "1.20.4",
+  "source_commit": "cb1154ab6f5663fcf5ec4b1b2de9d59f4d53c0cf",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T03:02:28.909Z",
+  "built_at": "2026-09-30T03:24:03.992Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 554,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2609,
+    "functional_verbatim": 2611,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3189,
-  "tree_sha256": "b2f8df195cd671a690f009c403ebe37ab58c8f1a3237c20aafbbc28fb5a08cb3",
+  "file_count": 3191,
+  "tree_sha256": "979ab93ed2588479c67154f837a646ebb982d48e470267a63835464662744650",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -312,7 +312,7 @@
     {
       "path": "README.md",
       "mode": "0000644",
-      "sha256": "74e177ab9a2b3a6c2e2de5fdac803944053c249d9e5ad794a838e2cbc497d848"
+      "sha256": "9c9e99127efafe70d60e1d464f07815397e436e69dc0b82c2e67f41dbd8dc8d6"
     },
     {
       "path": "bin/bongos.js",
@@ -787,7 +787,7 @@
     {
       "path": "docs/adr/0073-secrets-scan-exclude-uri-detector.md",
       "mode": "0000644",
-      "sha256": "80b3539d259105ad7e5284f622857a1aa2889182e856026d56b4138c1cf1bda8"
+      "sha256": "05107d37f497f8f5d8d1ca4d2a8d19e688fc9258352d7b9bfe1976c4ab1fee79"
     },
     {
       "path": "docs/adr/0074-memory-map-stays-light.md",
@@ -2762,7 +2762,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b1141ad77bcd4d780bfb80787cce1fea081b764b377bd72c083aaef520e11f70"
+      "sha256": "fc86b2b7f4ff0f0825ddbef82d3d33286d642a86e5f4dcf6fb62d6ad2efe3558"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8822,12 +8822,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "09e758156a2344894e786908b8d30cfcdf39b7eee6e03a9bdb6671e08791e77a"
+      "sha256": "a2051b26efcb3819d5b8190bff59b4695bbd0cd69efed2f95a4af8717e6a1c38"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5059b19984a6fdd0997b4f6062001f43c537c9cc02b983039af1ea1f56a958e2"
+      "sha256": "895cf915952f0155ee5d26315afd456d0630e5ab39ce65c22fa10bc0fa5aa7ae"
     },
     {
       "path": "public-docs/index.html",
@@ -8847,7 +8847,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "42d334cbd78f69784c937c7b857aedfe54019ceaa072893b9a2a520c651a6703"
+      "sha256": "b0f0a951c309fec69d3e8c0a4b30516bf56b1fcb4ce24490d84a89bd14ed01a0"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9197,7 +9197,7 @@
     {
       "path": "scripts/gds/control-manifest.js",
       "mode": "0000644",
-      "sha256": "270101b46772cc8e280bc5a36f66cfae578a901f07b4b5e1f959c9a566ebb5fd"
+      "sha256": "063e4e14f040bf78de4a8212222405cc361520d2475453b1d516329a7ca9f070"
     },
     {
       "path": "scripts/gds/copy-apply.js",
@@ -9319,6 +9319,11 @@
       "mode": "0000644",
       "sha256": "17d0fbc570b6dea3dfcf2425058510cd70b23f066fdf1ed751072852713284a3"
     },
+    {
+      "path": "scripts/gds/doc-control-claims.js",
+      "mode": "0000644",
+      "sha256": "94c89c10620d3d6678fa3b1a8decebc6d338c0b0b2a3799880e49311d2cd2770"
+    },
     {
       "path": "scripts/gds/docs-entropy.js",
       "mode": "0000644",
@@ -9407,7 +9412,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "d1f22a1eb3b7ae5ac51b795e2392bff5c9e0a72aea7de4c1947351752510fa89"
+      "sha256": "dee3e8db3ad7fff3c1e30a59aa58bab00972cba9710bd463e10ab8a3edc71e38"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -10732,7 +10737,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "322900d024e3737b18c2341d408a7832c2b0dffc9c36ff510768cbca78236098"
+      "sha256": "cc78b33cc9d0fca6d217a7c6aaf66f64de9cbe1447a352fc769eb8556207a453"
     },
     {
       "path": "src/bongos/module-store.js",
@@ -10942,7 +10947,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "1961978ac4aca79f758766be8172a32e3bcbe9f447fa767d700689eaeec97542"
+      "sha256": "e3e6394ab165f0c08e998c0c43fe18d1ec92872a84490deb7a9a01712656c024"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12184,6 +12189,11 @@
       "mode": "0000644",
       "sha256": "f51d3c747fbb3201ed3388abb1386d0547c3a3be70d7ad7237b9a0f5fdd2347b"
     },
+    {
+      "path": "tests/doc_control_claims.mjs",
+      "mode": "0000644",
+      "sha256": "499d0436bc000e9d1749d99d3e1e9886cb1a4bdd4388f5a165bc099359c7132a"
+    },
     {
       "path": "tests/docs_entropy.mjs",
       "mode": "0000644",

package/README.md

@@ -48,28 +48,19 @@ When it finishes, open Claude Code and run `/builder-start` to see what tasks ar
 
 ## Secrets scanning
 
-We keep secrets (`.env` files, API keys, private keys) out of the repo with two layers. Both are **instance topology** — the git hooks (`.husky/`) and CI (`.github/`) are excluded from the published core artifact, and a secrets pre-commit hook is an instance addition (nothing provisions one automatically). This repo tracks `.husky/pre-push` — the ADR 0043 permission gate, a separate wall from secrets scanning. The pattern below is the recommended posture:
+We keep secrets (`.env` files, API keys, private keys) out of the repo with three layers. The CI and patrol layers are **instance topology**: `.github/` is excluded from the published core artifact, so an instance that wants them carries its own copies.
 
-- **Pre-commit hook** (`.husky/pre-commit`) — scans your *staged* changes before each commit and aborts if it finds a secret. On an instance that ships `.husky/`, activate it **once per clone**:
+- **Prevent — the secret-gate hook** (`.claude/hooks/secret-gate.js`, wired in `.claude/settings.json`). A Claude Code PreToolUse hook that refuses to write secret-shaped content (provider-prefixed tokens, PEM blocks) into the working tree or a shell. It is the cooperative layer: it fails open on any error, so the two gates below are what actually hold.
+- **Gate — the CI secret scan** (the `Secret scan` step in `.github/workflows/unit.yml`). Every PR runs a pinned, checksum-verified gitleaks over the checked-out tree against `.gitleaks.toml`. This must pass before merge. It scans current files, not history.
+- **Patrol — the weekly history scan** (`scripts/gds/redteam-patrol.js`, run by `.github/workflows/redteam-patrol.yml`). Scans the full git history with the same config, which is how a secret committed and later deleted is still caught.
 
-  ```sh
-  node scripts/gds/install-git-hooks.js
-  ```
+A local pre-commit hook is optional and an instance addition: this repo tracks `.husky/pre-push` (the ADR 0043 permission gate, a separate wall) but no secrets pre-commit hook. If your instance adds hooks under `.husky/`, activate them once per clone with `node scripts/gds/install-git-hooks.js` (it no-ops on a checkout without a `.husky/`; `node scripts/gds/doctor.js` reports which case you're in).
 
-  Prefer that over setting `core.hooksPath` by hand: it no-ops cleanly on a checkout without a `.husky/` (e.g. a scaffolded instance that hasn't added hooks), whereas pointing `core.hooksPath` at a directory that isn't there leaves git with a dangling hooks path and no gate. `node scripts/gds/doctor.js` reports which case you're in.
+### If a scan blocks you, here's how to investigate
 
-  It always runs a built-in guard (blocks `.env`, `*.pem`, credential files, obvious key patterns). If [TruffleHog](https://github.com/trufflesecurity/trufflehog) is installed (`brew install trufflehog` on macOS; `scoop install trufflehog` / `choco install trufflehog` or the GitHub release on Windows) it also runs a deep scan; if not, it warns and lets the commit through — CI is the real gate.
-
-  > **Windows:** git runs the `.husky/pre-commit` hook through the Git-Bash `sh` bundled with Git for Windows, so the hook works if you installed Git for Windows (the usual case). If you don't have a `sh` available, the local hook silently no-ops — CI's full-history TruffleHog scan is then your only gate (and it always runs regardless of platform).
-
-- **CI scan** (`.github/workflows/secrets-scan.yml`) — every PR to `main` runs TruffleHog over the **full git history**. This must pass before merge.
-
-### If a commit is blocked, here's how to investigate
-
-1. **Read the output.** The hook prints the offending file(s) and why.
-2. **Is it a real secret?** Then it must never be committed. Remove it from the commit (`git restore --staged <file>`), and move the value out of the repo — local secrets go in `.env.local` (gitignored; run `/builder-setup`); production secrets live in your instance's secret store, never in the tree. If it was *already committed in an earlier commit*, the history scan will keep failing until the history is scrubbed — flag this to the owner, since rewriting shared history needs care.
-3. **Is it a false positive?** (e.g. an example key in docs, a test fixture, a Stripe `pk_test_` publishable key.) Add a path regex — one per line — to `.husky/secrets-allowlist.txt` (created on first use). Both the hook and CI read that allowlist. Keep entries narrow and only add them after confirming the match is genuinely not a secret.
-4. **Genuine emergency commit** (you're sure it's clean and need to move now): `git commit --no-verify` skips the local hook — but CI will still scan the PR, so this only defers the check, it doesn't bypass it.
+1. **Read the output.** The hook and gitleaks both name the offending file and the rule that matched.
+2. **Is it a real secret?** Then it must never be committed. Remove it from the commit (`git restore --staged <file>`), and move the value out of the repo — local secrets go in `.env.local` (gitignored; run `/builder-setup`); production secrets live in your instance's secret store, never in the tree. If it was *already committed in an earlier commit*, the weekly history patrol will keep reporting it until the history is scrubbed — flag this to the owner, since rewriting shared history needs care.
+3. **Is it a false positive?** (e.g. an example key in docs, a test fixture, a Stripe `pk_test_` publishable key.) Add a narrow path to the `[allowlist]` in `.gitleaks.toml`, and the matching entry to the `ALLOWLIST` in `.claude/hooks/secret-gate.js` — the two lists are kept in step. Only add one after confirming the match is genuinely not a secret.
 
 ## If your CLI starts 401'ing
 

package/docs/adr/0073-secrets-scan-exclude-uri-detector.md

@@ -2,7 +2,7 @@
 
 **Date:** 2026-06-20
 **Context:** Secrets-scanning gate (`.github/workflows/secrets-scan.yml` + the `.husky/pre-commit` early-catch). Tasks [#1318](https://example.com/builders#/task/1318) and [#1320](https://example.com/builders#/task/1320). Relates to [ADR 0022](0022-secrets-policy.md) (secrets policy) and [ADR 0071](0071-box-confirm-before-destroyed-and-drift-reconcile.md) (dev-box teardown — the trigger).
-**Status:** Accepted.
+**Status:** Superseded — the TruffleHog gate this ADR tunes did not survive the core extraction; the live CI secret scan is gitleaks in the unit workflow against `.gitleaks.toml` (task 1003126, ADR 0022). Kept as the record of why the URI detector was excluded. Marked by task 1003418.
 **Track:** `internal` (development system / CI gates).
 
 ## Problem — a noisy detector turned a green gate red repo-wide

package/docs/module-api-changelog.md

@@ -2663,5 +2663,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.1 with no explicit bump. run 36660725673. (task 1002620)
   1.20.3 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.2 with no explicit bump. run 36662547009. (task 1002620)
+  1.20.4 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.3 with no explicit bump. run 36664167210. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.3",
+  "version": "1.20.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.3",
+      "version": "1.20.4",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.3",
+  "version": "1.20.4",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8058,5 +8058,11 @@
       "id": "1004073",
       "text": "Adopting a speciality now walks you through its skills one at a time: what each does, when you'd use it, and what it costs, and you choose on or off for each before seeing the next. Nothing is switched on unless you choose it."
     }
+  ],
+  "1.20.4": [
+    {
+      "id": "1003418",
+      "text": "The project's automatic checks now catch any document that describes a safety check which no longer exists. On its first run it found the README still telling people their code was scanned for leaked passwords by a tool that w"
+    }
   ]
 }

package/scripts/gds/control-manifest.js

@@ -141,6 +141,15 @@ const CONTROLS = [
     wiredIn: { file: 'scripts/gds/ship-flow.js', needle: 'ship-honesty' },
     alsoExists: ['tests/ship_cannot_lie.mjs'],
   },
+  {
+    // Task 1003418 (audit A14). The manifest's own blind spot: it covers the rows
+    // someone listed. This guard derives claims from the docs instead, so a
+    // described-but-absent control reds the gate with no row to add.
+    label: 'guard: a doc cannot describe a control that does not exist (A14)',
+    file: 'scripts/gds/doc-control-claims.js',
+    wiredIn: { file: 'scripts/gds/fitness.js', needle: 'doc-control-claims' },
+    alsoExists: ['tests/doc_control_claims.mjs'],
+  },
 ];
 
 // Pure evaluation — exported for the test. deps.exists/deps.read override fs.

package/scripts/gds/doc-control-claims.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// scripts/gds/doc-control-claims.js — prose cannot describe a control that does not
+// exist (task 1003418, audit ref A14 of the 2026-08-29 security audit, goal 1000084).
+//
+// WHY. control-manifest.js exists because ADR 0022 named three controls that had
+// silently stopped existing, and it works — for the 14 controls someone remembered
+// to list. Every phantom-control finding since (A6, A13, B31, B32, the row-8 patrol
+// that read green for months while never running) was the same failure one row
+// outside that list. A hand list only catches what a person already thought of, so
+// the manifest cannot be the whole answer. This check reads the claims FROM THE DOCS:
+// a doc sentence that says an enforcement artifact does something is a claim that
+// the artifact exists, and a claim whose artifact is gone reds the gate by
+// construction, with nobody having to add a row. The README's secrets section was
+// the proof on first run: it still sent readers to a TruffleHog workflow and a
+// pre-commit hook that had not existed since the core extraction — the ADR 0022
+// finding itself, one file over.
+//
+// WHAT COUNTS AS A CLAIM, deliberately narrow:
+//   · a backticked path to an ENFORCEMENT artifact — a hook, a workflow, a script
+//     under scripts/gds or a hooks dir (CONTROL_PATH_RE);
+//   · in a sentence that uses control vocabulary — enforce, gate, guard, block,
+//     refuse, scan, patrol, audit, fail the build (CONTROL_WORDS);
+//   · and does NOT speak of it in the past — removed, retired, replaced, used to,
+//     no longer (HISTORY_WORDS). An ADR recording what was deleted is history,
+//     which is not a claim; the same path in the present tense is.
+// Superseded / deprecated / rejected / withdrawn ADRs are skipped whole, and so are
+// the dated records (session logs, audits, limitations archives), which describe a
+// moment rather than the tree.
+//
+// WHAT IT DOES NOT PROVE: that an existing artifact is WIRED. That stays the
+// manifest's job (a file present but unhooked). The two halves are complementary:
+// this one scales to every doc and asks only "is it there"; the manifest asks
+// "is it connected" for the controls that matter most.
+//
+// ALLOWLIST. A true claim this scan cannot tell from history (an accepted ADR whose
+// design was later retired by a newer ADR) is listed in ALLOW with the reason. It
+// is shrink-only in practice: an entry that no longer matches anything is itself a
+// violation, so a fixed doc cannot leave a dead exception behind to hide the next.
+//
+// Its own file for the size-ratchet reason (the doc-cli-guard.js precedent);
+// fitness.js requires it in CHECKS, and control-manifest.js lists it, so this guard
+// cannot silently stop existing either.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { trackedMarkdown } = require('./doc-cli-guard.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'a doc cannot describe an enforcement control that does not exist (task 1003418)';
+
+// Two shapes: a script or workflow with its extension, OR a git hook by its bare
+// name. Hooks under .husky/, .githooks/ and scripts/hooks/ carry no extension by
+// convention, and `.husky/pre-commit` is exactly the artifact ADR 0022 lost. The
+// names are git's whole documented set (githooks(5)), not a curated few.
+const GIT_HOOK_NAMES = [
+  'applypatch-msg', 'pre-applypatch', 'post-applypatch', 'pre-commit', 'pre-merge-commit',
+  'prepare-commit-msg', 'commit-msg', 'post-commit', 'pre-rebase', 'post-checkout', 'post-merge',
+  'pre-push', 'pre-receive', 'update', 'proc-receive', 'post-receive', 'post-update',
+  'reference-transaction', 'push-to-checkout', 'pre-auto-gc', 'post-rewrite', 'sendemail-validate',
+  'fsmonitor-watchman', 'p4-changelist', 'p4-prepare-changelist', 'p4-post-changelist',
+  'p4-pre-submit', 'post-index-change',
+];
+const CONTROL_PATH_RE = new RegExp(
+  '`((?:\\.claude/hooks|\\.github/workflows|scripts/gds|scripts/hooks|\\.githooks|\\.husky)/[A-Za-z0-9_.\\-/]+?\\.(?:js|mjs|cjs|sh|yml|yaml|ps1)'
+  + `|(?:\\.husky|\\.githooks|scripts/hooks)/(?:${GIT_HOOK_NAMES.join('|')}))\``,
+  'g',
+);
+const CONTROL_WORDS = /\b(enforc\w*|gates?|gated|gating|guards?|guarded|blocks?|blocked|refuses?|refused|hard[- ]?fails?|fails? (?:the )?(?:build|ci|merge|gate)|compensating control|pre-commit|pre-push|scans?|scanned|patrol\w*|audits?)\b/i;
+const HISTORY_WORDS = /\b(removed|deleted|retired|superseded|no longer|used to|never existed|did not exist|never survived|dropped|replaced|gone|historical|legacy|formerly|renamed)\b/i;
+const INACTIVE_STATUS_RE = /^\s*\**\s*status\s*\**\s*:?\s*\**\s*:?\s*\**\s*(superseded|deprecated|rejected|withdrawn)/im;
+const SKIP_PREFIXES = ['docs/session-logs/', 'docs/audits/', 'limitations/'];
+
+// `${doc}::${artifact}` -> why this present-tense mention is not a phantom control.
+const ALLOW = new Map([
+  ['docs/adr/0025-structured-criterion-task-link.md::scripts/gds/seed-v3-tasks.js',
+    'describes the grep a session HAD to do before this ADR; a seed script, not a control'],
+  ['docs/adr/0042-builder-self-deploy-ci-auto-merge.md::.github/workflows/grade-gate.yml',
+    'the CI grader gate this ADR designed; it was armed in the grader-off variant its own Status line records, and grading runs server-side (scripts/gds/ci-grade.js)'],
+  ['docs/adr/0111-instance-hosting-provisioning-module.md::scripts/gds/box.js',
+    'the dev-box control-plane runner, retired with dev boxes by ADR 0346 (dev-box-guard.js keeps it out)'],
+  ['docs/adr/0150-box-first-boot-bringup-vendored-instances.md::scripts/gds/box.js',
+    'the dev-box control-plane runner, retired with dev boxes by ADR 0346 (dev-box-guard.js keeps it out)'],
+]);
+
+// Sentence-ish units: prose sentences, blank-line paragraphs, and list/table rows.
+function sentencesOf(src) {
+  return String(src).split(/(?<=[.!?])\s+|\n\s*\n|\n(?=\s*(?:[-*|]|\d+\.)\s)/);
+}
+
+// Pure over its deps: docs is a list of repo-relative .md paths.
+function findPhantomClaims(docs, { read, exists }) {
+  const claims = [];
+  for (const doc of docs) {
+    if (SKIP_PREFIXES.some((p) => doc.startsWith(p))) continue;
+    const src = read(doc);
+    if (src == null) continue;
+    if (INACTIVE_STATUS_RE.test(src.slice(0, 2000))) continue;
+    const seen = new Set();
+    for (const s of sentencesOf(src)) {
+      // Judge the WORDING with every code span blanked: a path's own name must not
+      // decide the tense (`gone.yml` reads as "gone", `guard.js` as "guard").
+      const prose = s.replace(/`[^`]*`/g, ' ');
+      for (const m of s.matchAll(CONTROL_PATH_RE)) {
+        const artifact = m[1];
+        if (seen.has(artifact) || exists(artifact)) continue;
+        if (!CONTROL_WORDS.test(prose) || HISTORY_WORDS.test(prose)) continue;
+        seen.add(artifact);
+        claims.push({ doc, artifact, sentence: s.replace(/\s+/g, ' ').trim().slice(0, 160) });
+      }
+    }
+  }
+  return claims;
+}
+
+function evaluate(docs, deps, allow = ALLOW) {
+  const claims = findPhantomClaims(docs, deps);
+  const hit = new Set();
+  const violations = [];
+  for (const c of claims) {
+    const key = `${c.doc}::${c.artifact}`;
+    if (allow.has(key)) { hit.add(key); continue; }
+    violations.push(`${c.doc}: names \`${c.artifact}\` as a live control, and it does not exist — "${c.sentence}"`);
+  }
+  for (const key of allow.keys()) {
+    if (!hit.has(key)) violations.push(`stale allowance: ${key} no longer matches a claim — delete it from ALLOW in scripts/gds/doc-control-claims.js`);
+  }
+  return { violations, claims };
+}
+
+const readRel = (rel) => { try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; } };
+const existsRel = (rel) => fs.existsSync(path.join(ROOT, rel));
+
+function checkDocControlClaims({ files = null } = {}) {
+  const docs = files || trackedMarkdown();
+  // A lint that reports on nothing is worse than one that fails (docs-entropy).
+  if (!docs.length) {
+    return { name: NAME, ok: false, hardFail: true, warnings: [],
+      violations: ['scan defect — enumerated 0 tracked markdown files; a broken enumeration, not a clean result.'],
+      note: 'static scan of enforcement artifacts named in docs.' };
+  }
+  const { violations, claims } = evaluate(docs, { read: readRel, exists: existsRel });
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: violations.length
+      ? 'restore the control, correct the doc to name what really enforces it, or (for an accepted ADR a newer one retired) add an ALLOW entry saying which'
+      : `${docs.length} tracked .md file(s) scanned; every enforcement artifact named in a present-tense control sentence exists (${claims.length} allowlisted, each with its reason).`,
+  };
+}
+
+function main() {
+  const r = checkDocControlClaims();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkDocControlClaims, findPhantomClaims, evaluate, sentencesOf,
+  ALLOW, GIT_HOOK_NAMES, CONTROL_PATH_RE, CONTROL_WORDS, HISTORY_WORDS, INACTIVE_STATUS_RE,
+};

package/scripts/gds/fitness.js

@@ -1342,6 +1342,7 @@ const CHECKS = [
   checkGovernmentRenameIdentity, checkPrelaunchVocabulary, // 19c task 1003120 (`X`→`X` rename arrow) + 19d task 1003152 ("stealth" is the product's word) — sharing a line: this file is AT the 1,500 budget (Check 23/24 precedent below; task 1003825 buys it back)
   checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
   require('./fitness-ratchets.js').checkQualityRatchets, // Check 20 — task 1003129: quality budgets only tighten (mechanics + knip CI step live in fitness-ratchets.js)
+  require('./doc-control-claims.js').checkDocControlClaims, // Check 37 — task 1003418 / audit A14: a doc cannot describe an enforcement control that does not exist (derived from the docs, not a hand list)
   require('./doc-cli-guard.js').checkDocNamesRealCli, // Check 22 — task 1003165 / G01: a doc that names a CLI invocation must match the real CLI
   require('./skill-preflight.js').checkOpsSkillsDeclareMachine, // Check 23 — task 1003167 / G03: an ops skill declares the machine it needs
   // Check 24 — task 1003166 / G02: no ops script hardcodes a version id. It landed

package/src/bongos/module-scope-map.js

@@ -435,7 +435,7 @@ const MODULE_GLOBS = {
     'scripts/gds/skill-lint.js', 'scripts/gds/run-routine.js',
     'scripts/gds/adr-namespace.js', 'scripts/gds/baseline-staleness.js',
     'scripts/gds/category-advisory-guard.js', 'scripts/gds/client-baseurl-guard.js',
-    'scripts/gds/doc-cli-guard.js', 'scripts/gds/doc-comment-coverage.js',
+    'scripts/gds/doc-cli-guard.js', 'scripts/gds/doc-control-claims.js', 'scripts/gds/doc-comment-coverage.js',
     'scripts/gds/exec-path-guard.js', 'scripts/gds/fitness-lib.js',
     'scripts/gds/fitness-checks-error-envelope.js', 'scripts/gds/fitness-checks-identity.js',
     'scripts/gds/fitness-checks-packaging.js', 'scripts/gds/fitness-checks-route-pins.js',

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.3'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.4'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/doc_control_claims.mjs

@@ -0,0 +1,133 @@
+// tests/doc_control_claims.mjs — a doc cannot describe an enforcement control that
+// does not exist (task 1003418). The check is itself a control, so this proves it
+// passes on the real tree AND that it can fail: each case below is a way a
+// phantom-control claim can be written, or a way an honest mention must not trip it.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const dcc = require(path.join(ROOT, 'scripts', 'gds', 'doc-control-claims.js'));
+
+// A fake tree: docs maps path -> text; `present` is the set of artifacts on disk.
+function run(docs, present = [], allow = new Map()) {
+  const have = new Set(present);
+  return dcc.evaluate(Object.keys(docs), {
+    read: (p) => (p in docs ? docs[p] : null),
+    exists: (p) => have.has(p),
+  }, allow);
+}
+
+test('the live tree passes', () => {
+  const r = dcc.checkDocControlClaims();
+  assert.equal(r.hardFail, false, `unexpected violations:\n  ${r.violations.join('\n  ')}`);
+});
+
+test('THE REPORTED CASE: the README sentence naming a deleted secrets workflow is caught', () => {
+  // Verbatim shape of the README line this task found (the ADR 0022 finding, one file over).
+  const r = run({ 'README.md': '- **CI scan** (`.github/workflows/secrets-scan.yml`) — every PR to `main` runs TruffleHog over the **full git history**. This must pass before merge.\n' });
+  // "This must pass before merge" is the next sentence; the claim sentence carries "scan".
+  assert.equal(r.violations.length, 1, r.violations.join('\n'));
+  assert.match(r.violations[0], /README\.md: names `\.github\/workflows\/secrets-scan\.yml`/);
+});
+
+test('the same sentence is clean once the artifact exists', () => {
+  const r = run({ 'README.md': 'The CI scan (`.github/workflows/unit.yml`) gates every PR.\n' }, ['.github/workflows/unit.yml']);
+  assert.deepEqual(r.violations, []);
+});
+
+test('each kind of enforcement artifact is recognised', () => {
+  for (const a of ['.claude/hooks/x-gate.js', '.github/workflows/x.yml', 'scripts/gds/x-guard.js', '.husky/x.sh', 'scripts/hooks/x.sh']) {
+    const r = run({ 'docs/x.md': `The \`${a}\` hook blocks every bad write.\n` });
+    assert.equal(r.violations.length, 1, `${a} should be a claim`);
+  }
+});
+
+test('a git hook named by its bare, extensionless name is recognised (the ADR 0022 artifact)', () => {
+  for (const a of ['.husky/pre-commit', '.husky/pre-push', '.githooks/commit-msg', 'scripts/hooks/pre-receive',
+    '.husky/pre-applypatch', '.githooks/push-to-checkout', '.husky/pre-merge-commit']) {
+    const r = run({ 'README.md': `- **Pre-commit hook** (\`${a}\`) — scans your staged changes and aborts on a secret.\n` });
+    assert.equal(r.violations.length, 1, `${a} should be a claim`);
+  }
+  // ...and an existing one is clean.
+  assert.deepEqual(run({ 'README.md': 'The `.husky/pre-push` hook blocks a raw push.\n' }, ['.husky/pre-push']).violations, []);
+  // A non-hook bare name under a hooks dir is not an artifact reference.
+  assert.deepEqual(run({ 'README.md': 'The `.husky/README` guards nothing.\n' }).violations, []);
+});
+
+test('an incidental "was" does not turn a present-tense claim into history', () => {
+  const r = run({ 'docs/x.md': 'The `.github/workflows/gone.yml` gate, which was rewritten last week, blocks every PR.\n' });
+  assert.equal(r.violations.length, 1);
+});
+
+test('history is not a claim: a sentence about what was removed does not trip it', () => {
+  const r = run({ 'docs/adr/0999-x.md': 'The `.github/workflows/secrets-scan.yml` gate was removed at the core extraction.\n' });
+  assert.deepEqual(r.violations, []);
+});
+
+test('a mention without control vocabulary is not a claim', () => {
+  const r = run({ 'docs/x.md': 'See `scripts/gds/old-seed.js` for the shape of a TASKS array.\n' });
+  assert.deepEqual(r.violations, []);
+});
+
+test('a path\'s own NAME never decides the wording, in either direction', () => {
+  // `x-guard.js` must not make a plain pointer read as a control claim...
+  assert.deepEqual(run({ 'docs/x.md': 'See `scripts/gds/x-guard.js` for the shape of a TASKS array.\n' }).violations, []);
+  // ...and `gone.yml` / `replaced.js` must not make a live claim read as history.
+  for (const a of ['.github/workflows/gone.yml', 'scripts/gds/replaced.js']) {
+    assert.equal(run({ 'docs/x.md': `The \`${a}\` gate blocks every PR.\n` }).violations.length, 1, a);
+  }
+});
+
+test('a superseded ADR is skipped whole', () => {
+  const r = run({ 'docs/adr/0998-x.md': '# ADR 0998\n\n**Status:** Superseded by ADR 0999.\n\nThe `.github/workflows/gone.yml` gate blocks every PR.\n' });
+  assert.deepEqual(r.violations, []);
+});
+
+test('an ACCEPTED ADR with the same sentence is checked', () => {
+  const r = run({ 'docs/adr/0997-x.md': '# ADR 0997\n\n**Status:** Accepted.\n\nThe `.github/workflows/gone.yml` gate blocks every PR.\n' });
+  assert.equal(r.violations.length, 1);
+});
+
+test('dated records describe a moment, not the tree, and are skipped', () => {
+  for (const doc of ['docs/session-logs/2026-01-01-x.md', 'docs/audits/x.md', 'limitations/v1-shipped.md']) {
+    const r = run({ [doc]: 'The `.github/workflows/gone.yml` gate blocks every PR.\n' });
+    assert.deepEqual(r.violations, [], doc);
+  }
+});
+
+test('an allowlisted claim passes, and says so by being counted', () => {
+  const docs = { 'docs/adr/0996-x.md': 'The `scripts/gds/box.js` runner gates every box.\n' };
+  const r = run(docs, [], new Map([['docs/adr/0996-x.md::scripts/gds/box.js', 'retired by a later ADR']]));
+  assert.deepEqual(r.violations, []);
+  assert.equal(r.claims.length, 1);
+});
+
+test('a STALE allowance is itself a violation, so a fixed doc cannot leave a dead exception', () => {
+  const r = run({ 'docs/x.md': 'Nothing here.\n' }, [], new Map([['docs/x.md::scripts/gds/box.js', 'was true once']]));
+  assert.equal(r.violations.length, 1);
+  assert.match(r.violations[0], /stale allowance/);
+});
+
+test('every live allowance still matches something (no dead rows in ALLOW today)', () => {
+  const r = dcc.checkDocControlClaims();
+  assert.ok(!r.violations.some((v) => /stale allowance/.test(v)));
+  for (const [key, why] of dcc.ALLOW) assert.ok(why && why.length > 20, `${key} must say why`);
+});
+
+test('an empty enumeration is a broken scan, not a clean result', () => {
+  const r = dcc.checkDocControlClaims({ files: [] });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations[0], /scan defect/);
+});
+
+test('the guard is wired: fitness runs it and the control manifest lists it', async () => {
+  const fs = await import('node:fs');
+  const fitness = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'fitness.js'), 'utf8');
+  assert.match(fitness, /require\('\.\/doc-control-claims\.js'\)\.checkDocControlClaims/);
+  const cm = require(path.join(ROOT, 'scripts', 'gds', 'control-manifest.js'));
+  assert.ok(cm.CONTROLS.some((c) => c.file === 'scripts/gds/doc-control-claims.js'), 'listed in the manifest');
+});