@bongos/core 1.21.179 → 1.21.181

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/bongos/package-core.js",
-  "core_version": "1.21.179",
-  "core_contract": "1.21.179",
-  "source_commit": "178a6fa539e3718e93bab31e4ced14262d1457a6",
+  "core_version": "1.21.181",
+  "core_contract": "1.21.181",
+  "source_commit": "677ee2b818cf829dddd5434301b158be3408fbd5",
   "source_ref": "HEAD",
-  "built_at": "2026-10-26T00:44:53.003Z",
+  "built_at": "2026-10-26T01:16:25.738Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 616,
     "agent_docs_stubbed": 29,
-    "functional_verbatim": 3537,
+    "functional_verbatim": 3539,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 4183,
-  "tree_sha256": "026997dfda1f061de2986ae1e869fbe88be80237fa31d02b7f1d2480dd9d51e4",
+  "file_count": 4185,
+  "tree_sha256": "e69b48d53a056c99114f3c5904e69828363e91f5f0df70b7b599e61e8e299d1d",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -472,7 +472,7 @@
     {
       "path": "docs/adr/0017-code-simplification-and-repo-cleanliness.md",
       "mode": "0000644",
-      "sha256": "6e57ab51a44f245f1691fb9f0de43d78aa05faa0465f12659c2eb89c088b5fb8"
+      "sha256": "d841dd656d9678981310f69cdc277fc259fde3dd37252a8ff4612f95e777de42"
     },
     {
       "path": "docs/adr/0018-three-rank-model-goes-live.md",
@@ -2927,7 +2927,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "ad8dd9b3c01736a49e3559a3dc0f5e37120ac1b4de4318a7bba07be3609aaf6b"
+      "sha256": "4e0a9cf41330f62ec1d2bacdc07a7071b4081517e60f6446fe66a33e44175ce9"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2937,7 +2937,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "5d9dd0fe4686c1dde4914b7b17f35d182ef0e931f4e4e3a682008df73364cc94"
+      "sha256": "4835f21d9d6cf7eaa82821e1bb5eb4c79493267300ef852ad1ca1c05b4a41e65"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4397,7 +4397,7 @@
     {
       "path": "modules/builder-settings/display-name.js",
       "mode": "0000644",
-      "sha256": "f959d06834da24a929e22f7159f8451a4e9578e4ffe32b20bfa9301bfd47fbed"
+      "sha256": "9414b08857cf2d1eba6bf43127436f86f04ed5df707a7a04027c556a9ce91a39"
     },
     {
       "path": "modules/builder-settings/event-sound-prefs.js",
@@ -7052,7 +7052,7 @@
     {
       "path": "modules/ideas/born-of.js",
       "mode": "0000644",
-      "sha256": "c7458b5d65de75d0eb6bafdbb0b61b156d0f7d7e25c9c82229794494338a6808"
+      "sha256": "bc7e3b1121d63fc0736e0a44894997710f872548cfd0ce66ae9903bb69910bc6"
     },
     {
       "path": "modules/ideas/completeness.js",
@@ -7932,7 +7932,7 @@
     {
       "path": "modules/lifecycle/task-classifier.js",
       "mode": "0000644",
-      "sha256": "95907661350fece131d9063b795a10139a2f8777a0a49f7f39c50e61a9568a1d"
+      "sha256": "ec331ba544e199ec80c3cbc08bc4eb6bb9f6fba1e4aa70f9bd02c1402647f7dc"
     },
     {
       "path": "modules/lifecycle/task-list-limits.js",
@@ -10342,7 +10342,7 @@
     {
       "path": "modules/specialities/db.js",
       "mode": "0000644",
-      "sha256": "c3ef28d95b6d93b0d302c2705522550b701931deb932016ee2134b03eadff358"
+      "sha256": "4badd0141e04154a73cf1e9bde4a1a794a756e0ea09f5b7d19c1c8dbcfa3fb0b"
     },
     {
       "path": "modules/specialities/migrations/specialities_001_specialities.sql",
@@ -10372,7 +10372,7 @@
     {
       "path": "modules/specialities/skills.js",
       "mode": "0000644",
-      "sha256": "be3948128b557774f65a02f5b12497979d4c38334552947b8c4ef9c47e8562a2"
+      "sha256": "eb1663db43e9e7a1b83313c3c1619ea4dabe011edbf86910d55e95bd3e1247c4"
     },
     {
       "path": "modules/specialities/specialities.js",
@@ -10827,12 +10827,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "a310406cb88d9fa7053aa0002367fc0d02e00f0fa3a566353e7ec4d93700ee0f"
+      "sha256": "4d3ecd3d1a0b7e6602da53e83e88c204ab82a45ca83ae3d24979746970f15ac9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "78692b77c9c7abc874c9237014f3953b714f1b4d90b7102b323a48cff93c41ed"
+      "sha256": "2a01fd05d918fc38ad18d1cc6305681129b6115a4eab33f7d1fa4d34b8da2e44"
     },
     {
       "path": "public-docs/index.html",
@@ -10852,7 +10852,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "9c2abac99e107bc56a08f65863cf2367ceeceb9c7a4823e41db7e9805c829e4c"
+      "sha256": "2a6e6fa89b09fd51aa8fae09c92eec30b6d0823dcdf3eaeda63826e7269a46ea"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -11397,7 +11397,7 @@
     {
       "path": "scripts/bongos/fitness-ratchets.js",
       "mode": "0000644",
-      "sha256": "15c1d62a515cf0ee1b651f33233e22f66144c88a20680bcb6b90ca3b73ddb81f"
+      "sha256": "29c8c99a1380a0df741338feef8cc0465e22b12c45ba7655584a6a24e48987ac"
     },
     {
       "path": "scripts/bongos/fitness.js",
@@ -11967,7 +11967,7 @@
     {
       "path": "scripts/bongos/pulse.js",
       "mode": "0000644",
-      "sha256": "c0ae5acf5576014c44c488e7f4c195cf69fbfab420311f4726424a8f9dec024e"
+      "sha256": "908648ffc796e4eecda652333a67626a2ec206dd394038dab4bf981c5a5272d5"
     },
     {
       "path": "scripts/bongos/push-main.js",
@@ -12052,7 +12052,7 @@
     {
       "path": "scripts/bongos/repo-metrics.js",
       "mode": "0000644",
-      "sha256": "b68dc127a8ef9eacd4abd7f90eef05ff4bfe788b6770ae2b517759b399c50dd3"
+      "sha256": "15dee800bf6fc5aca8a9d332854825b1d0081f2269ccdf69c2b5d3e1010009cb"
     },
     {
       "path": "scripts/bongos/retired-core-skills.json",
@@ -14422,7 +14422,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "93d9e5e91b4caf90bc2f1955be557fa7ba17105e5a8e3f1d94f9651ff4e1925c"
+      "sha256": "b9dd189b2035885f8ccb205de20d45409380f16f1110de50447acd9ff866f52a"
     },
     {
       "path": "src/bongos/module-store.js",
@@ -14677,7 +14677,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "622387442066f1d43a8f2514f706770b6c3fb6972e7bb60642da1a7b31117c4d"
+      "sha256": "c48862d3a5d62afff6c50b8de356b68ec2ef4f22ced0c0caa36a99d5f135747a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14972,7 +14972,7 @@
     {
       "path": "tests/applicant_profile_boundary.mjs",
       "mode": "0000644",
-      "sha256": "f7c94079d3c85cc6513dba591111f81fa45115e25d32469d67e949a8e7abee3d"
+      "sha256": "3bde3c999f6ef1b1cdcc3185450c7e8e03d819d621ee5684ebee94536299b0fd"
     },
     {
       "path": "tests/applicant_profile_read_bounds.mjs",
@@ -18009,6 +18009,11 @@
       "mode": "0000644",
       "sha256": "9448a42c0a10144d9e9cd96aa7ae894db6a2e30319be1ab5013c3b52d2ad7496"
     },
+    {
+      "path": "tests/knip_modules_scope.mjs",
+      "mode": "0000644",
+      "sha256": "6dadd33910d25806110296d916e5a0301c9e7bb4baa69103b71fdfea94ad3ac7"
+    },
     {
       "path": "tests/knip_ratchet_ambient.mjs",
       "mode": "0000644",
@@ -19599,6 +19604,11 @@
       "mode": "0000644",
       "sha256": "5c964c162b87f2e73f6dc3343b1c4be886b7d3e0d29c01d51280dc790fc218e7"
     },
+    {
+      "path": "tests/repo_metrics_dead_exports.mjs",
+      "mode": "0000644",
+      "sha256": "f98a3d9635557d050f428c5ad3258ff1ef7652bf0f4fba87830cc09481b76e9b"
+    },
     {
       "path": "tests/reward_gate.mjs",
       "mode": "0000644",

package/docs/adr/0017-code-simplification-and-repo-cleanliness.md

@@ -37,6 +37,7 @@ We will adopt **knip** (dev-only) as the one tool the substrate and janitor lean
 - **It targets the exact failure mode.** Unused exports and unreferenced files are the residue of AI over-writing — code written, then orphaned. Reliable dead-file/dead-export detection is genuinely hard to hand-roll (it requires building and walking the import graph); knip does it.
 - **Zero production cost.** knip is in `devDependencies`. The droplet deploy runs `npm ci --omit=dev`, so knip and its dependency tree never reach production. No runtime, no monthly cost — consistent with the $5K budget posture. (Its transitive dev-tree does carry npm-audit advisories; these are dev-only and are the concern of the dependency-scan task V3.R38, not prod.)
 - **Config lives in `package.json`, not a new file.** knip reads a `"knip"` key in `package.json`. Embedding it there — rather than adding a root `knip.json` — keeps the footprint minimal, which is the very ethos this ADR encodes. (The task description floated `knip.json`; the package.json key is the simpler in-scope choice and is what shipped.)
+  - **Amended 2026-10-25 (task 1004875):** the config moved to a root `knip.config.js`. Bringing `modules/` into scope needs entry points GENERATED from each `module.json` (routes, pollers, web surfaces) — the module loader finds those files by name, so a static JSON key would have to be a hand list that rots. The package.json key was removed so there is one config, not two.
 
 The committed config declares entry points (CLI scripts, tests, the browser `public/game/main.js`, the status/builders pages) and the project globs, and lists `phaser` + `colyseus.js` under `ignoreDependencies` because those are loaded as vendored browser globals via `<script>` tags (`public/index.html`), not statically imported — so knip would otherwise report them as unused. The config was trimmed to remove every pattern knip flagged as redundant; it now emits no configuration hints.
 

package/docs/file-map.md

@@ -14,6 +14,7 @@
 ├── .impeccable/                 ← impeccable skill artifacts: config.json (buildPath: code), surfaces/<route>.md (per-route briefs), mocks/world-assets/ (Higgsfield renders + prompt sidecars; the SOURCE of modules/public-landing/public/assets/world/), mocks/decision/ (A1 comps), design.json (DESIGN.md sidecar), review/ (finish captures)
 ├── .gitignore
 ├── package.json / package-lock.json
+├── knip.config.js               ← dead-code scanner config (task 1004875): modules/ entries GENERATED from each module.json + #! CLIs; scored by scripts/bongos/fitness-ratchets.js --knip
 ├── CODEOWNERS                   ← owner review on the merge-gate surfaces (real since task 1002611, ADR 0159); inert until branch protection is on (scripts/bongos/gating.js) — keep aligned with scripts/bongos/hard-floor.js HARD_FLOOR_GLOBS
 ├── server.js                    ← game boot: Express + Colyseus + the shared internal surface (mountInternalSurfaces), binds 127.0.0.1:3000
 │

package/docs/module-api-changelog.md

@@ -3195,5 +3195,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.177 with no explicit bump. run 40249608959. (task 1002620)
   1.21.179 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.178 with no explicit bump. run 40250732318. (task 1002620)
+  1.21.180 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.179 with no explicit bump. run 40251859318. (task 1002620)
+  1.21.181 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.180 with no explicit bump. run 40253320267. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/builder-settings/display-name.js

@@ -24,7 +24,6 @@
 // The longest display name we accept, in Unicode code points (so a multi-byte
 // character counts as one, matching how a human reads the limit).
 const MAX_LENGTH = 60;
-const MIN_LENGTH = 1; // after trimming — empty / whitespace-only is rejected
 
 // Count code points, not UTF-16 units, so an emoji or astral character is "1".
 function codePointLength(str) {
@@ -77,7 +76,6 @@ function validate(name) {
 
 module.exports = {
   MAX_LENGTH,
-  MIN_LENGTH,
   codePointLength,
   hasControlChar,
   validate,

package/modules/ideas/born-of.js

@@ -26,8 +26,6 @@
 const api = require('../../src/module-api');
 const { pool } = api;
 
-function emptyBorn() { return { goals: {}, criteria: {} }; }
-
 // readBornOf — the two reads, folded first-wins into plain objects keyed by the
 // born thing's id. deps.pool honours the test seam.
 async function readBornOf(deps = {}) {
@@ -52,4 +50,4 @@ async function readBornOf(deps = {}) {
   return { goals: firstWins(goals.rows, 'goal_id'), criteria: firstWins(criteria.rows, 'criterion_id') };
 }
 
-module.exports = { readBornOf, emptyBorn };
+module.exports = { readBornOf };

package/modules/lifecycle/task-classifier.js

@@ -71,7 +71,6 @@ function blockerVendorRule() {
   }
   return _blockerVendorRe;
 }
-const _resetVendorCacheForTests = () => { _blockerVendorRe = undefined; };
 
 function extractKindTag(description) {
   if (!description) return null;
@@ -549,7 +548,6 @@ module.exports = {
   classifyTaskKind,
   classifyTaskDiscipline,
   buildBlockerVendorRe,
-  _resetVendorCacheForTests,
   VALID_KINDS,
   VALID_DISCIPLINES,
   WRITABLE_DISCIPLINES,

package/modules/specialities/db.js

@@ -113,16 +113,6 @@ async function listDocuments(specialityId, executor) {
   return r.rows;
 }
 
-async function getDocument(specialityId, docId, executor) {
-  const q = exec(executor);
-  const r = await q(
-    `SELECT id, speciality_id, title, body_md, source, content_sha, created_at
-       FROM specialities_documents WHERE speciality_id = $1 AND id = $2`,
-    [specialityId, docId],
-  );
-  return r.rows[0] || null;
-}
-
 async function deleteDocument(specialityId, docId, executor) {
   const q = exec(executor);
   const r = await q(
@@ -286,7 +276,7 @@ async function listOffered({ builderId, projectIds = [], discipline = null }, ex
 module.exports = {
   UPDATABLE, taskDiscipline, setOffered, listOffered,
   createSpeciality, getSpeciality, listVisibleTo, updateSpeciality,
-  addDocument, listDocuments, getDocument, deleteDocument,
+  addDocument, listDocuments, deleteDocument,
   linkLearning, countTraining,
   adopt, abandon, deactivateCraft, activeForCraft, listAdoptions, setEnabledSkills,
 };

package/modules/specialities/skills.js

@@ -70,12 +70,6 @@ function readFrontmatter(skillMd) {
   try { return parseFrontmatter(fs.readFileSync(skillMd, 'utf8')); } catch { return {}; }
 }
 
-// The description a SKILL.md gives, for the adoption walkthrough (task 1004073).
-function readDescription(skillMd) {
-  const d = readFrontmatter(skillMd).description;
-  return typeof d === 'string' ? d : '';
-}
-
 // The optional PEOPLE-FACING fields (task 1004073). `description` is written to
 // be MATCHED by a model, so a skill's author may also say, for the person
 // deciding whether to turn it on: what it does (`plain`), when to reach for it
@@ -193,4 +187,4 @@ function installedSkillsCached(opts, now = Date.now()) {
 }
 function _resetCache() { cached = null; }
 
-module.exports = { SKILL_NAME_RE, installedSkills, installedSkillsCached, readDescription, parseFrontmatter, explainSkill, _resetCache };
+module.exports = { SKILL_NAME_RE, installedSkills, installedSkillsCached, parseFrontmatter, explainSkill, _resetCache };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.179",
+  "version": "1.21.181",
   "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

@@ -10350,5 +10350,17 @@
       "id": "1004877",
       "text": "The Work page no longer re-downloads the whole task list every 20 seconds: it updates within about a second when something actually changes, and an idle tab now asks 5 times in 10 minutes instead of 30."
     }
+  ],
+  "1.21.180": [
+    {
+      "id": "1004875",
+      "text": "The unused-code check now covers modules/, the largest part of the codebase, and fails the build when someone adds a dead file or an unused export there. Five dead exports were removed along the way."
+    }
+  ],
+  "1.21.181": [
+    {
+      "id": "1004892",
+      "text": "The repo health dashboard's dead-code number now counts the same way the CI check does, so it no longer jumps by about 1,800 false alarms from modules/."
+    }
   ]
 }

package/scripts/bongos/fitness-ratchets.js

@@ -240,6 +240,85 @@ function localKnipPath() {
 let knipSkipReason = null;
 function lastKnipSkipReason() { return knipSkipReason; }
 
+// ---- scoring knip's JSON (task 1004875) ----
+//
+// TWO THINGS THE OLD INLINE COUNT GOT WRONG, both found by putting modules/ in scope:
+//
+// 1. UNUSED FILES WERE NEVER COUNTED. It read a top-level `files` array; knip 6's
+//    JSON reporter has none — an unused file is an issue whose own `files` array is
+//    non-empty. So a brand-new dead file anywhere scored 0 and the ratchet waved it
+//    through. `files` is now one of the per-issue keys (the legacy top-level array is
+//    still read, for an older knip).
+//
+// 2. knip DOES NOT CREDIT A CommonJS NAMESPACE USE. Measured on a two-file repro:
+//    `const a = require('./a'); a.used()` leaves `used` reported as an unused export;
+//    only a destructured `const { used } = require('./a')` counts. src/ is mostly
+//    destructured (module-api.js says so), but modules/ is written the namespace way,
+//    so knip reports ~1,600 exports there that ARE used. Counting those would make
+//    every ordinary new export under modules/ red CI. So for a finding under
+//    modules/, an unused export counts only when its NAME appears in no other code
+//    file at all (a word match over .js/.mjs/.cjs/.html/.sh). That is the case knip
+//    is right about: exported, and nothing else even spells it. It under-counts (a
+//    name that happens to be spelled elsewhere hides) and never over-counts, which
+//    is the direction a gate that fails CI must err in. src/, scripts/ and tests/
+//    keep knip's own verdict, so their part of the baseline is unchanged.
+const KNIP_ISSUE_KEYS = ['files', 'dependencies', 'devDependencies', 'optionalPeerDependencies', 'unlisted', 'binaries', 'unresolved', 'exports', 'types', 'nsExports', 'nsTypes', 'duplicates'];
+const NAME_FILTERED_PREFIX = 'modules/';
+const WORD_SCAN_EXT_RE = /\.(m?js|cjs|html|sh)$/;
+const WORD_SCAN_SKIP = new Set(['node_modules', '.git', 'docs', 'public-docs', 'worktrees']);
+const WORD_RE = /[A-Za-z_$][\w$]*/g;
+
+// word -> the one repo-relative file that uses it, or true when 2+ files do.
+function codeWordIndex(root = ROOT) {
+  const index = new Map();
+  const walk = (dir) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (WORD_SCAN_SKIP.has(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) { walk(abs); continue; }
+      if (!WORD_SCAN_EXT_RE.test(e.name)) continue;
+      let text;
+      try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const rel = path.relative(root, abs).split(path.sep).join('/');
+      for (const w of new Set(text.match(WORD_RE) || [])) {
+        const seen = index.get(w);
+        if (seen === undefined) index.set(w, rel);
+        else if (seen !== true && seen !== rel) index.set(w, true);
+      }
+    }
+  };
+  walk(root);
+  return index;
+}
+
+function nameUsedOutside(index, name, file) {
+  const seen = index.get(name);
+  return seen === true || (seen !== undefined && seen !== file);
+}
+
+// knip JSON -> the integer the ratchet scores. `wordIndex` is built on demand, and
+// only when a modules/ export finding needs it.
+function countKnipFindings(json, { root = ROOT, wordIndex = null } = {}) {
+  let total = Array.isArray(json && json.files) ? json.files.length : 0;
+  let index = wordIndex;
+  for (const issue of (json && json.issues) || []) {
+    const filtered = typeof issue.file === 'string' && issue.file.startsWith(NAME_FILTERED_PREFIX);
+    for (const key of KNIP_ISSUE_KEYS) {
+      const v = issue[key];
+      if (!Array.isArray(v)) continue;
+      if (filtered && (key === 'exports' || key === 'types')) {
+        if (!index) index = codeWordIndex(root);
+        total += v.filter((e) => !(e && nameUsedOutside(index, e.name, issue.file))).length;
+      } else {
+        total += v.length;
+      }
+    }
+  }
+  return total;
+}
+
 function knipIssueCount() {
   knipSkipReason = null;
   if (!localKnipPath()) {
@@ -259,22 +338,14 @@ function knipIssueCount() {
     if (e && e.stdout) { raw = e.stdout.toString(); }
     else { knipSkipReason = `npx knip failed to run in ${ROOT}`; return null; }
   }
+  let j;
   try {
-    const j = JSON.parse(raw);
-    // knip's json reporter: { files: [...], issues: [{ file, owners, exports:[], types:[], ... }] }
-    const files = Array.isArray(j.files) ? j.files.length : 0;
-    let items = 0;
-    for (const issue of j.issues || []) {
-      for (const key of ['dependencies', 'devDependencies', 'optionalPeerDependencies', 'unlisted', 'binaries', 'unresolved', 'exports', 'types', 'nsExports', 'nsTypes', 'duplicates']) {
-        const v = issue[key];
-        items += Array.isArray(v) ? v.length : 0;
-      }
-    }
-    return files + items;
+    j = JSON.parse(raw);
   } catch {
     knipSkipReason = 'knip produced output this script could not parse as JSON';
     return null;
   }
+  return countKnipFindings(j);
 }
 
 // ---------- baseline + ratchet ----------
@@ -586,6 +657,8 @@ module.exports = {
   consoleCallCount,
   isServerPath,
   knipIssueCount,
+  countKnipFindings,
+  codeWordIndex,
   localKnipPath,
   lastKnipSkipReason,
   OVERSIZE_LINES,

package/scripts/bongos/pulse.js

@@ -71,12 +71,14 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 // droplet machine without Postgres reachable).
 function loadDeps() {
   // eslint-disable-next-line global-require
-  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  const { pool } = require('../../src/bongos/pool');
   // eslint-disable-next-line global-require
   // pulse.js (the lib) carved → modules/sessions/ (BV1.R82 / ADR 0093 §1); the CLI
   // shell stays here and requires the module lib directly (scripts are outside the
-  // kernel boundary, so a direct module require is fine).
-  const { sweepStaleClaims } = require(path.join(REPO_ROOT, 'modules/sessions/pulse'));
+  // kernel boundary, so a direct module require is fine). A LITERAL path, not
+  // path.join: the dead-code scanner (knip) cannot follow a computed require, and
+  // reported the lib as an unused file while this was its only caller (task 1004875).
+  const { sweepStaleClaims } = require('../../modules/sessions/pulse');
   return { pool, sweepStaleClaims };
 }
 

package/scripts/bongos/repo-metrics.js

@@ -37,6 +37,7 @@ const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const { hasFlag } = require('./cli-lib');
+const { countKnipFindings } = require('./fitness-ratchets');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const TOP_N_LARGEST = 15;
@@ -121,7 +122,9 @@ function scanDeadCode() {
     configured =
       !!pkg.knip ||
       fs.existsSync(path.join(REPO_ROOT, 'knip.json')) ||
-      fs.existsSync(path.join(REPO_ROOT, 'knip.jsonc'));
+      fs.existsSync(path.join(REPO_ROOT, 'knip.jsonc')) ||
+      // The config moved to a JS file so it can generate modules/ entries (task 1004875).
+      fs.existsSync(path.join(REPO_ROOT, 'knip.config.js'));
   } catch (_) {
     configured = false;
   }
@@ -149,35 +152,44 @@ function scanDeadCode() {
     return { dead_exports: null, dead_files: null, knip_status: 'unparseable' };
   }
 
-  // knip v6 JSON shape: { issues: [{ file, files (bool: whole file unused),
-  // exports:[...], types:[...], ... }] }. A top-level `files` array exists in
-  // some reporter modes; handle both. dead_exports sums unused exports+types
-  // across issues; dead_files counts issues whose whole file is unused.
-  let deadFiles = null;
+  const scored = scoreKnipReport(report);
+  if (!scored) return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+  return { ...scored, knip_status: 'ok' };
+}
+
+// knip JSON -> { dead_exports, dead_files }, or null on a shape we cannot read.
+//
+// dead_exports goes through the CI ratchet's own scorer, countKnipFindings, fed only
+// the exports/types findings (task 1004892). Counting knip's raw list instead put
+// ~1,800 exports under modules/ on the dashboard that ARE used: knip does not credit
+// a CommonJS namespace use (`lib.x`), and modules/ is written that way. The scorer's
+// name filter drops those, so this number and the ratchet's agree. `opts` passes
+// through to the scorer (a test injects `wordIndex`).
+//
+// COST: the scorer builds its word index once per call (codeWordIndex walks the
+// repo's .js/.mjs/.cjs/.html/.sh text) — measured ~2.3 s on this repo, beside a knip
+// run that already takes far longer. It is deliberately NOT fed from
+// gatherFileSizes()'s reads: that list is git-tracked .js/.mjs only, while the
+// ratchet's index also reads .cjs/.html/.sh and skips docs/ — a different file set
+// gives a different count, and matching CI's number is the whole point.
+function scoreKnipReport(report, opts = {}) {
+  if (!report || typeof report !== 'object') return null;
+  const hasIssues = Array.isArray(report.issues);
+  if (!hasIssues && !Array.isArray(report.files)) return null;
   let deadExports = null;
-  try {
-    if (Array.isArray(report.issues)) {
-      deadExports = report.issues.reduce((acc, issue) => {
-        const ex = Array.isArray(issue.exports) ? issue.exports.length : 0;
-        const ty = Array.isArray(issue.types) ? issue.types.length : 0;
-        return acc + ex + ty;
-      }, 0);
-      deadFiles = report.issues.reduce(
-        (acc, issue) => acc + (issue.files === true ? 1 : 0),
-        0
-      );
-    }
-    // Some reporter modes additionally surface a flat unused-file list.
-    if (Array.isArray(report.files)) {
-      deadFiles = (deadFiles ?? 0) + report.files.length;
-    }
-    if (deadExports == null && deadFiles == null) {
-      return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
-    }
-  } catch (_) {
-    return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+  let deadFiles = null;
+  if (hasIssues) {
+    const exportsOnly = report.issues.map((issue) => ({ file: issue.file, exports: issue.exports, types: issue.types }));
+    deadExports = countKnipFindings({ issues: exportsOnly }, opts);
+    deadFiles = report.issues.reduce(
+      // knip 6 gives an ARRAY here ([{ name }]), not a bool (task 1004875).
+      (acc, issue) => acc + (issue.files === true || (Array.isArray(issue.files) && issue.files.length) ? 1 : 0),
+      0
+    );
   }
-  return { dead_exports: deadExports, dead_files: deadFiles, knip_status: 'ok' };
+  // Some reporter modes additionally surface a flat unused-file list.
+  if (Array.isArray(report.files)) deadFiles = (deadFiles ?? 0) + report.files.length;
+  return { dead_exports: deadExports, dead_files: deadFiles };
 }
 
 // ---------- branch hygiene ----------
@@ -284,7 +296,7 @@ async function upsertSnapshot(pool, snap) {
 
 // ---------- main ----------
 
-(async () => {
+async function main() {
   const args = process.argv.slice(2);
   const asJson = hasFlag('--json', args);
   const noWrite = hasFlag('--no-write', args);
@@ -357,7 +369,15 @@ async function upsertSnapshot(pool, snap) {
   }
 
   process.exit(0);
-})().catch((err) => {
-  console.error('fatal:', err);
-  process.exit(1);
-});
+}
+
+module.exports = { scoreKnipReport };
+
+// CLI only when run directly, so a test can require this file without it
+// scanning the repo or writing to the DB (task 1004892).
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}

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

@@ -427,6 +427,9 @@ const MODULE_GLOBS = {
     // scanner config above (task 1004146).
     '.gitignore', '.env.local.example',
     'package.json', 'package-lock.json',
+    // The dead-code scanner's config, moved out of package.json's "knip" key so it
+    // can generate modules/ entries from each module.json (task 1004875).
+    'knip.config.js',
     'scripts/bongos/fitness.js', 'scripts/bongos/docs-entropy.js',
     'scripts/bongos/redteam-patrol.js', 'scripts/bongos/audit-gate.js',
     'scripts/bongos/fitness-ratchets.js', 'scripts/bongos/control-manifest.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.21.179'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.181'; // 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/applicant_profile_boundary.mjs

@@ -737,8 +737,14 @@ test('this proof runs in a lane that actually executes', () => {
   const listed = runners.some((f) => {
     try { return fs.readFileSync(path.join(process.cwd(), 'tests', f), 'utf8').includes(self); } catch { return false; }
   });
-  const globbed = fs.existsSync(path.join(process.cwd(), 'package.json'))
-    && /tests\/\*|tests\/\*\*|\*\.mjs/.test(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+  // `npm test` is scripts/bongos/run-unit-tests.js, which readdir()s EVERY
+  // tests/*.mjs into the unit or the integration lane — no allowlist. (This used to
+  // regex package.json for a tests/** glob, which only ever matched the knip
+  // config's entry list; task 1004875 moved that out and the check went red.)
+  let testScript = '';
+  try { testScript = (JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')).scripts || {}).test || ''; } catch { /* no package.json */ }
+  const globbed = /scripts\/bongos\/run-unit-tests\.js/.test(testScript)
+    && /readdirSync\(TESTS_DIR\)/.test(fs.readFileSync(path.join(process.cwd(), 'scripts/bongos/run-unit-tests.js'), 'utf8'));
   assert.ok(listed || globbed,
     `${self} is in no runner list and no glob — it would assert nothing forever (learning 1000218)`);
 });

package/tests/knip_modules_scope.mjs

@@ -0,0 +1,145 @@
+// tests/knip_modules_scope.mjs — the dead-code scanner covers modules/ (task 1004875).
+//
+// Three layers:
+//   1. the scorer (countKnipFindings) on synthetic knip JSON — hermetic;
+//   2. the generated entry list (knip.config.js) against the real modules/ tree —
+//      every route and poller a manifest declares is an entry, by the loader's rule;
+//   3. REAL knip on a throwaway fixture repo that uses the real config builder: a
+//      new unused file, and a new unused export, under modules/ each raise the score
+//      and the ratchet then fails. That layer needs knip in THIS checkout's
+//      node_modules (CI's `npm ci` provides it); without it, it skips and says why.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+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 fr = require(path.join(ROOT, 'scripts/bongos/fitness-ratchets.js'));
+const knipConfig = require(path.join(ROOT, 'knip.config.js'));
+
+const issue = (file, extra) => ({ file, files: [], exports: [], types: [], dependencies: [], unlisted: [], ...extra });
+
+test('scorer: an unused FILE counts (knip 6 reports it per issue, not top-level)', () => {
+  const json = { issues: [issue('modules/x/orphan.js', { files: [{ name: 'modules/x/orphan.js' }] })] };
+  assert.equal(fr.countKnipFindings(json, { wordIndex: new Map() }), 1);
+});
+
+test('scorer: a modules/ export named by no other code file counts; one named elsewhere does not', () => {
+  const wordIndex = new Map([
+    ['usedViaNamespace', true], // two+ files spell it
+    ['onlyHere', 'modules/x/lib.js'], // only its own file
+    ['spelledInConsumer', 'modules/y/consumer.js'], // one OTHER file
+  ]);
+  const json = {
+    issues: [issue('modules/x/lib.js', {
+      exports: [{ name: 'usedViaNamespace' }, { name: 'onlyHere' }, { name: 'spelledInConsumer' }, { name: 'neverSpelled' }],
+    })],
+  };
+  assert.equal(fr.countKnipFindings(json, { wordIndex }), 2);
+});
+
+test('scorer: src/ exports keep knip\'s own verdict (no name filter outside modules/)', () => {
+  const wordIndex = new Map([['usedViaNamespace', true]]);
+  const json = { issues: [issue('src/x.js', { exports: [{ name: 'usedViaNamespace' }] })] };
+  assert.equal(fr.countKnipFindings(json, { wordIndex }), 1);
+});
+
+test('config: every manifest-declared route and poller is an entry, and the file exists', () => {
+  const entries = new Set(knipConfig.generatedModuleEntries(ROOT));
+  const modulesDir = path.join(ROOT, 'modules');
+  let checked = 0;
+  for (const key of fs.readdirSync(modulesDir)) {
+    const mf = path.join(modulesDir, key, 'module.json');
+    if (!fs.existsSync(mf)) continue;
+    const c = JSON.parse(fs.readFileSync(mf, 'utf8')).contributes || {};
+    for (const [dir, list] of [['routes', c.routes], ['pollers', c.pollers]]) {
+      for (const k of list || []) {
+        const rel = `modules/${key}/${dir}/${k}.js`;
+        assert.ok(entries.has(rel), `${rel} is declared in ${key}/module.json but is not a knip entry`);
+        assert.ok(fs.existsSync(path.join(ROOT, rel)), `${rel} is declared but missing`);
+        checked++;
+      }
+    }
+  }
+  assert.ok(checked > 50, `expected the real tree's routes+pollers, saw ${checked}`);
+  assert.ok(knipConfig.project.includes('modules/**/*.{js,mjs}'), 'modules/ must be in knip "project"');
+  assert.ok(entries.has('modules/ui-design/kit/render.js'), 'a #! CLI under modules/ is an entry');
+});
+
+// ---------- real knip on a fixture ----------
+
+const KNIP_BIN = path.join(ROOT, 'node_modules', 'knip', 'bin', 'knip.js');
+const HAVE_KNIP = fs.existsSync(KNIP_BIN);
+
+function write(root, rel, text) {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, text);
+}
+
+function makeFixture() {
+  // realpath: on macOS os.tmpdir() is a /var -> /private/var symlink, and knip then
+  // resolves a require to a path outside its own project set and calls the target an
+  // unused file.
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'knip-modules-')));
+  write(dir, 'package.json', JSON.stringify({ name: 'knip-fixture', version: '1.0.0', private: true }));
+  // The fixture uses the REAL config builder, pointed at itself.
+  write(dir, 'knip.config.js',
+    `module.exports = require(${JSON.stringify(path.join(ROOT, 'knip.config.js'))}).buildConfig(__dirname);\n`);
+  write(dir, 'modules/demo/module.json', JSON.stringify({ key: 'demo', contributes: { routes: ['demo'] } }));
+  // The route requires the lib the namespace way — the shape knip is blind to.
+  write(dir, 'modules/demo/routes/demo.js',
+    "'use strict';\nconst lib = require('../lib');\nmodule.exports = function route() { return lib.hello(); };\n");
+  write(dir, 'modules/demo/lib.js',
+    "'use strict';\nfunction hello() { return 'hi'; }\nmodule.exports = { hello };\n");
+  return dir;
+}
+
+function score(dir) {
+  const raw = execFileSync(process.execPath, [KNIP_BIN, '--directory', dir, '--reporter', 'json', '--no-exit-code'], {
+    cwd: dir, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return fr.countKnipFindings(JSON.parse(raw), { root: dir });
+}
+
+const ratchetFails = (value, baseline) =>
+  fr.compareToBaselines({ knip_issue_count: value }, { knip_issue_count: baseline }).violations.length > 0;
+
+test('real knip: a new unused file or export under modules/ fails the ratchet; a namespace-used export does not',
+  { skip: HAVE_KNIP ? false : `no knip at ${KNIP_BIN} — run \`npm ci\` (CI always has it)` }, () => {
+    const dir = makeFixture();
+    try {
+      const baseline = score(dir);
+      assert.equal(baseline, 0, 'the clean fixture scores 0 — the route is a generated entry, lib.hello is namespace-used');
+      assert.equal(ratchetFails(baseline, baseline), false);
+
+      // A new export that the route uses through the namespace: knip alone flags it;
+      // the scorer must not, or every ordinary export under modules/ would red CI.
+      write(dir, 'modules/demo/lib.js',
+        "'use strict';\nfunction hello() { return 'hi'; }\nfunction greet() { return 'yo'; }\nmodule.exports = { hello, greet };\n");
+      write(dir, 'modules/demo/routes/demo.js',
+        "'use strict';\nconst lib = require('../lib');\nmodule.exports = function route() { return lib.hello() + lib.greet(); };\n");
+      assert.equal(score(dir), baseline, 'a namespace-used export is not a finding');
+
+      // A new unused EXPORT.
+      write(dir, 'modules/demo/lib.js',
+        "'use strict';\nfunction hello() { return 'hi'; }\nfunction greet() { return 'yo'; }\n"
+        + "function zzDeadExport() { return 0; }\nmodule.exports = { hello, greet, zzDeadExport };\n");
+      const withExport = score(dir);
+      assert.equal(withExport, baseline + 1);
+      assert.equal(ratchetFails(withExport, baseline), true, 'an unused export under modules/ must fail the ratchet');
+
+      // A new unused FILE.
+      write(dir, 'modules/demo/orphan.js', "'use strict';\nmodule.exports = { nobodyCalls() { return 1; } };\n");
+      const withFile = score(dir);
+      assert.equal(withFile, withExport + 1);
+      assert.equal(ratchetFails(withFile, withExport), true, 'an unused file under modules/ must fail the ratchet');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });

package/tests/repo_metrics_dead_exports.mjs

@@ -0,0 +1,57 @@
+// tests/repo_metrics_dead_exports.mjs — repo-metrics scores dead exports the way the
+// CI knip ratchet does (task 1004892).
+//
+// Once knip scanned modules/ (task 1004875), repo-metrics' raw export count jumped by
+// ~1,800: knip does not credit a CommonJS namespace use (`lib.x`), and modules/ is
+// written that way. The ratchet's scorer (countKnipFindings) filters those by name;
+// repo-metrics must use the same scorer, so the dashboard number matches CI's.
+// Hermetic: synthetic knip JSON and an injected word index, no knip run.
+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 rm = require(path.join(ROOT, 'scripts/bongos/repo-metrics.js'));
+const fr = require(path.join(ROOT, 'scripts/bongos/fitness-ratchets.js'));
+
+const issue = (file, extra) => ({ file, files: [], exports: [], types: [], dependencies: [], unlisted: [], ...extra });
+
+test('a modules/ export used through a namespace elsewhere is not a dead export', () => {
+  const wordIndex = new Map([
+    ['usedViaNamespace', true], // spelled in 2+ files
+    ['onlyHere', 'modules/x/lib.js'], // spelled only in its own file
+  ]);
+  const report = {
+    issues: [
+      issue('modules/x/lib.js', {
+        exports: [{ name: 'usedViaNamespace' }, { name: 'onlyHere' }],
+        types: [{ name: 'neverSpelled' }],
+      }),
+      issue('src/y.js', { exports: [{ name: 'usedViaNamespace' }] }), // outside modules/: knip's verdict stands
+    ],
+  };
+  const scored = rm.scoreKnipReport(report, { wordIndex });
+  assert.equal(scored.dead_exports, 3); // onlyHere + neverSpelled + the src/ one
+  // ...and that is exactly the ratchet scorer's count for the same export/type findings.
+  assert.equal(scored.dead_exports, fr.countKnipFindings(report, { wordIndex }));
+});
+
+test('non-export findings (deps, unlisted) do not leak into dead_exports; dead files still count', () => {
+  const report = {
+    issues: [
+      issue('src/a.js', { files: [{ name: 'src/a.js' }], dependencies: [{ name: 'left-pad' }], exports: [{ name: 'x' }] }),
+      issue('src/b.js', { unlisted: [{ name: 'chalk' }] }),
+    ],
+  };
+  const scored = rm.scoreKnipReport(report, { wordIndex: new Map() });
+  assert.equal(scored.dead_exports, 1);
+  assert.equal(scored.dead_files, 1);
+});
+
+test('a report with no issues list is an unexpected shape (null), not zero', () => {
+  assert.equal(rm.scoreKnipReport({}, { wordIndex: new Map() }), null);
+  assert.equal(rm.scoreKnipReport(null, { wordIndex: new Map() }), null);
+});