@bongos/core 1.19.909 → 1.19.910

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.909",
-  "core_contract": "1.19.909",
-  "source_commit": "a378172e3f20f9432a63ee723274cb46acd87e5d",
+  "core_version": "1.19.910",
+  "core_contract": "1.19.910",
+  "source_commit": "ab1d1de5cfa5ac30120e07b1974440f17945eefa",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T14:45:23.165Z",
+  "built_at": "2026-09-20T15:29:42.443Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 503,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2812,
-  "tree_sha256": "8f49b63378d69ecb4c8d7d3d6b4ad472ba735ba1ca96922843be33ff8d475d89",
+  "tree_sha256": "40fde6b52d1d23e9b6eba83c0721d3584999cbfd55401262111678a035e8f07b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2627,7 +2627,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "6949109a5db028219bf76b4483ac3b160f5996586a4c4a0d903fd42c28e1ff79"
+      "sha256": "8f386030b89f390fe4fece85308f87177e487c373d9bf7ba6758cb80febfa8df"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2637,7 +2637,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "9acd2adf3d2f21d23fcc9cc626a26ca331972eb6980c5e0c9f8b883c9094b40f"
+      "sha256": "01618cef9838c895da164b81675efd8db38b97151ea2e3b6882f08a03009bd8f"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7787,12 +7787,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "97fdcfbc606ed913875732b87e7cfa0cf105349b9a25a8c1831fd9d59f5d0b76"
+      "sha256": "adc1e3888e98381ca917459b11366a25c6da5e00e72411b1bc3e22aad10c4f69"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f060d07f1520e822ce6bc8294d6970fa66f87ae4c23aa6bdf2e7f64197aeec60"
+      "sha256": "09320d2a344a74fcb4db29bb52b658f61df23191bdf4247916c017277c31b25d"
     },
     {
       "path": "public-docs/index.html",
@@ -8372,7 +8372,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "5f96e59cb4c27e20c6acaabf8f97b94dc69875b5fb5770fb37e4fb838128b189"
+      "sha256": "b05634f4916387ed35b33774e8b27176a1d3ce14c8ea6cb98485f289395afc6b"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -8432,7 +8432,7 @@
     {
       "path": "scripts/gds/gen-file-map.js",
       "mode": "0000644",
-      "sha256": "620188a2edcd4aec580193b3d97f0c4e19871db4d31af27cb0b7e0571457a73a"
+      "sha256": "a8531787384fc528eb75dde142ca8d24982e47e226c934d6e692c53e6e738a0a"
     },
     {
       "path": "scripts/gds/gen-freshness.js",
@@ -9102,7 +9102,7 @@
     {
       "path": "scripts/gds/ship-check.js",
       "mode": "0000644",
-      "sha256": "07fd20f374bdd512a54e55af6c4582a86da606d5c560fa44bb0ddec5024867d4"
+      "sha256": "24e94cd822d5d9e75d2596ac85af854a6d965eb94a7859996792ddfd0f83e898"
     },
     {
       "path": "scripts/gds/ship-deploy-target.js",
@@ -9787,7 +9787,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "22cc35de1bea324e4016468dcd0c95e1fa859c2d467127fa3acef7dc18432dbd"
+      "sha256": "fef1ab161dad460d5e2e95cfea66403745c0658e4551a90528a1318b9525ad7f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11037,7 +11037,7 @@
     {
       "path": "tests/file_map.mjs",
       "mode": "0000644",
-      "sha256": "b44f040f21d1dbb978add1a96e392a0f3c1b5a46302c10616b2304505ca66097"
+      "sha256": "e426eea6852d2ea63b79d27e17b71c53031ca65ee22644192eb4807df26f7482"
     },
     {
       "path": "tests/filing_abuse_matrix.mjs",

package/docs/file-map.md

@@ -140,6 +140,9 @@
 │   ├── ui-design/               ← CORE-DOMAIN module (task 1003324 / ADR 0197, default-on): the design capability every builder on every instance gets — ships METHOD, never a world. Absorbs ADR 0081's layer: adapters/{claude-design,figma}/index.js (moved from src/ui/adapters/), scripts/{design-sync,figma-design-sync,validate-design}.js (moved from scripts/gds/, which keeps thin shims), docs/design-contract.md (moved from docs/). Declaration-only: contributes.skills design (the /design playbook, new) + design-sync + figma-design-sync; no routes/port/migrations, so disabling it touches no served surface. CLAUDE.md separates the platform FLOORS (the Fifteen Rule, the dark twins, no page :root, the 24px floor, AA in both modes, the kill switch) from the instance's WORLD (its packs + DESIGN.md). kit/ (task 1003320) is the look-before-you-ship kit: lib.js (the floors, the states/probes contracts, the action + expectation vocabularies, the WCAG maths, the stub spawner), serve.js (any surface through the doorway's real transforms + fixtures/), render.js (states × 1440/390/320 × dark/light, audited), probe.js (PASS/FAIL contracts), check-mock.js (platform rules + the instance's DESIGN.md taste bans, then the detector), tells.js (task 1003329 / ADR 0223: the anti-pattern detector as two tiers — floors FAIL, craft tells WARN, kit-ignore waivers per file; the rendered twins live in lib.js factsInPage), contrast.js + png.js; a page's <page>.states.json / <page>.probes.json sit BESIDE the surface (modules/public-landing/public/, modules/hall-ui/public/). Recipe: docs/recipes/ui-look-before-you-ship.md. skills/ (task 1003321 / ADR 0198) is the vendoring policy: policy.json (licence allowlist, verdicts that may land, sidecar fields, preamble markers), PREAMBLE.md (the platform preamble every vendored SKILL.md opens with), README.md (the roster — both origins scanned dangerous on 2026-08-28, landed as rebuild specs; nothing vendored — and the landing recipe); a landable copy goes under skills/vendor/<name>/ with PROVENANCE.md + LICENSE and is materialised into an instance's .claude/skills/ by claude-materialize.js step 1b. skills/<name>/ (task 1003325 / ADR 0220) are the in-house rebuilds from the specs, first-party and counted: design-taste-frontend (the default taste skill), design-taste-frontend-v1 (the earlier generation, kept distinct), high-end-visual-design (the polish pass), redesign-existing-projects (the in-place upgrade); each opens with the same preamble and carries a "Rebuilt from" section instead of a sidecar. impeccable/ (task 1003326 / ADR 0221) is the design-craft method as ONE skill with sub-commands: SKILL.md (the router, the menu, the craft floor, the bounded finish) + reference/<sub-command>.md (eighteen playbooks, one loaded per request); no hooks, no bypass agent, no telemetry, no live server. minimalist-ui/, industrial-brutalist-ui/, gpt-taste/, stitch-design-taste/ (task 1003327 / ADR 0230) are the four looks, composition grammars with no colours of their own: the palette is the instance's pack and the texture is a named entry in styles/; a substrate is an archetype that still ships both modes, gpt-taste's selection is derived from the route rather than rolled, and stitch-design-taste writes a DESIGN.md-shaped contract document whose thirteen are transcribed from the pack. image-to-code/, imagegen-frontend-web/, imagegen-frontend-mobile/, brandkit/ (task 1003328 / ADR 0222) are the image family under the hero-only rule: plates and hero objects only, the pair (JPEG dark plate + WebP alpha cutout) with a <file>.json sidecar beside each, through the instance's art pipeline key; the grove specimen's styles/grove/assets/ is the worked example. style/ (task 1003475 / ADR 0231) is the module's first FIRST-PARTY skill (no upstream, so a `## First party` section instead of `## Rebuilt from`): the /style session in which an owner authors their own look in four bounded steps, rendering the nearest library entries before asking, drafting inside the contract, retuning by measurement, and handing over the one-step adoption without ever writing config/branding.json. styles/ (task 1003323 / ADR 0219) is the style library: <name>/pack.json (the theme.ui overlay, exactly the fifteen) + DESIGN.md (the look's derived recipes, thirteen in lockstep with the pack) + mock.html (the specimen); chrome-world (pinned to the neutral pack), expedition, grove, blueprint (the first cool look, authored through /style at task 1003475); STYLE=<name> on the kit lays a look over the instance's pack through GDS_BRANDING_FILE; tests/ui_design_styles.mjs runs the world/cosmos/hall token suites once per alternate (UI_DESIGN_PACK). config/design-tokens.* + design-sources.json STAY in config/ as the host boundary; public-landing keeps its own key (first customer, not owner).
 │   ├── character-anim/          ← consistent-character generative animation (ADR 0088) — graded painterly frame sets + manifest, the otb-character-review skill. CLAUDE.md, module.json.
 │   ├── provisioning/            ← stands up + operates a Cloud Bongos instance's own infra (server/DB/domain/DNS/TLS) via the API (ADR 0111); web-tier request+state only, no cloud tokens — a separate control-plane runner drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute workloads. CLAUDE.md, module.json.
+│   ├── government/              ← CORE-DOMAIN module (ADR 0151 / BV1 goal 1000030, renamed governance→government by ADR 0174, default-on): Discord-style configurable ranks + permissions. The PERMISSION is the atomic authority unit and the four ranks (xenos/thetes/metic/archon) are the positions in the government; the module owns the code-defined permission catalog — each key flagged `system` (trust-boundary), `substrate` (enforced out of band) or operational (delegable) — plus the compatibility seed that reproduces the old rank thresholds exactly. ADR 0016 is preserved: authority is still resolved server-side, per request, uncached. The word `role` is deliberately absent — it is reserved for the crafts. CLAUDE.md, module.json, catalog.js, ranks.js, resolver.js, config.js, db.js, board.js + board-membership.js + membership-predicate.js, session-scopes.{js,json}, protected-surfaces.{js,json}, routes/ (government + rank-sync), pollers/ (board-expiry), migrations/.
+│   ├── specialities/            ← CORE-DOMAIN module (task 1003855 / ADR 0296, default-on): role SUB-SPECIALITIES — a named bundle of knowledge, skills and an interaction contract sitting UNDER a craft. A craft says HOW you work (engineer/ideator/artist/ui); a speciality says WHAT you work on, and how a subject-matter expert wants to be engaged inside it. Deliberately thin over three surfaces that already exist — discipline-modes.json for craft→playbook, behavior_prefs.interaction for the per-session contract (a speciality contract rides the SAME GET /me → Conductor path rather than adding a second one), and the ADR 0083 manifest for declared skills; the only new machinery is the knowledge bundle. Training is two-fold: documents the builder supplied, plus learnings captured from sessions worked in the speciality (pointing at existing `learnings` rows, never a second corpus). Owned per-builder OR per-project, each carrying its owner's sharing decision (private/project/public) and a sellable flag that records INTENT only — ADR 0107 defers the marketplace, so there is nothing to list on. CLAUDE.md, module.json, specialities.js, db.js, routes/, migrations/.
+│   ├── agents/                  ← declarative agent registry (BV1 goal 1000038 Phase 1) — the one module that ships `default:false`, so shipped is not enabled and an instance opts in per ADR 0083. `.claude/agents/*.md` are reconciled at deploy into `agents_definitions` plus the per-fire `agents_runs` ledger; files-are-source (an instance-authored DB row is never clobbered), and `author_rank` is stamped from the author's LIVE DB rank because a committed file cannot grant authority (ADR 0016). Spawns consume the EXISTING read-only `grade` port, so v1 agents are observe-and-report only — no write principals — and every fire bills through the shared LLM cost cache. `spend.requiresPayer` (task 1003884): a fire spends real money for whoever called it, so the core REFUSES to enable the module on an instance whose join door is `open` with no payer configured — an account created seconds ago would otherwise spend the instance's money with nobody to bill. lib/spend-ceiling.js is the per-payer monthly ceiling, failing closed when it is exhausted OR unreadable; lib/fire-budget.js is the separate RATE ceiling. CLAUDE.md, module.json, spawn.js, lib/, routes/, pollers/ (event-router), migrations/.
 │   └── demo/                    ← BV1.R52 acceptance-proof module: one rank-gated write route + one namespaced migration proving the loader mounts a scaffolded module with zero core edits. CLAUDE.md, module.json.
 │
 ├── scripts/

package/docs/module-api-changelog.md

@@ -2292,5 +2292,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.907 with no explicit bump. run 35516559010. (task 1002620)
   1.19.909 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.908 with no explicit bump. run 35517426559. (task 1002620)
+  1.19.910 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.909 with no explicit bump. run 35519713709. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.909",
+  "version": "1.19.910",
   "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/scripts/gds/fitness.js

@@ -225,7 +225,7 @@ function checkGeneratedArtifactsFresh() {
   try {
     execFileSync(process.execPath, [path.join(__dirname, 'gen-file-map.js'), '--check'], { cwd: REPO_ROOT, stdio: 'pipe' });
   } catch {
-    violations.push('docs/file-map.md generated sections (.claude/skills/, .claude/scheduled-tasks/) are STALE or a skill/routine has no note in docs/file-map.notes.json — run `node scripts/gds/gen-file-map.js` and add any missing note, then commit (ADR 0066).');
+    violations.push('docs/file-map.md generated sections (.claude/skills/, .claude/scheduled-tasks/) are STALE, a skill/routine has no note in docs/file-map.notes.json, or a directory under modules/ has no file-map entry at all — run `node scripts/gds/gen-file-map.js --check` for the exact list, then fix and commit (ADR 0066; module coverage: task 1004066).');
   }
   try {
     // Also structurally validates the spec (exit 1 on invalid OpenAPI 3.1) beyond the drift check (exit 2). Task 1918.

package/scripts/gds/gen-file-map.js

@@ -16,6 +16,16 @@
 //   • every skill/routine dir on disk MUST have a note  → a new skill can't land undescribed;
 //   • every note MUST map to a dir that exists           → the map can't carry ghosts;
 //   • the rendered block MUST match what's committed      → no stale tree.
+// MODULE COVERAGE (task 1004066). The same honor system that let a skill land unmapped let a whole
+// MODULE land unmapped: `modules/agents`, `modules/government` and `modules/specialities` were all
+// on disk with nothing in the map, and the two that got fixed before this got fixed BY HAND — which
+// is the point, since hand-patching a drifting map does not stop the drift. The modules/ block is
+// not generated (each entry is a paragraph of prose no directory walk could write, and generating
+// the fenced repo tree is the expensive option this task ruled out), so what is enforced is the
+// cheap half: a set comparison asserting every directory under modules/ is documented SOMEWHERE in
+// the map — either a `modules/<key>/…` path reference or a `<key>/` entry inside the modules block.
+// A new module now fails --check until someone writes its line.
+//
 // scripts/gds/ is deliberately NOT generated: it is a curated highlight reel of ~20 of ~70 files
 // (generating it would bloat it with low-signal entries), and it sits mid-tree inside the big
 // fenced repo tree where HTML-comment markers can't live cleanly. It stays hand-curated.
@@ -51,6 +61,13 @@ const SECTIONS = [
   { id: 'scheduled-tasks', dir: '.claude/scheduled-tasks', notesKey: 'scheduled-tasks' },
 ];
 
+// modules/ is NOT generated (task 1004066): each entry is a paragraph of prose no directory walk
+// could write, and generating it would force the whole fenced repo tree through a generator —
+// explicitly out of scope. What IS enforceable is COVERAGE: every module on disk must be documented
+// somewhere in the map. That set comparison is the cheap half of the same contract the skills
+// section already carries, and it is what stops a whole vertical slice landing unmapped.
+const MODULES_DIR = 'modules';
+
 const begin = (id) => `<!-- BEGIN GENERATED FILE-MAP ${id} (scripts/gds/gen-file-map.js — do not hand-edit; notes live in docs/file-map.notes.json) -->`;
 const end = (id) => `<!-- END GENERATED FILE-MAP ${id} -->`;
 
@@ -107,6 +124,72 @@ function buildModel() {
   return SECTIONS.map((s) => buildSection(s, notes));
 }
 
+// ── module coverage (task 1004066) ────────────────────────────────────────────
+// A module counts as documented when the map either references its PATH (`modules/<key>/…`
+// anywhere) or carries a `<key>/` entry line inside the `modules/` tree block. Both forms are in
+// use today, so the check accepts both rather than inventing a third the map would fail on.
+
+// Both matchers CAPTURE the whole path segment rather than testing for a given key. That is what
+// makes the prefix hazard structural instead of something a lookahead has to remember: a mention of
+// `modules/agents-extra` yields the key `agents-extra`, so it can never vouch for `agents`. It also
+// means the map is scanned ONCE per run instead of twice per module.
+const PATH_REF_RE = /modules\/([A-Za-z0-9_.-]+)/g;
+const ENTRY_RE = /[├└]──\s+([A-Za-z0-9_.-]+)\//g;
+
+// The slice of the fenced repo tree between the `├── modules/` header and the next sibling at the
+// same depth. Scoping the entry search here matters: `.claude/skills/` lists dirs in the same
+// `├── name/` shape, so an unscoped match would let a SKILL named after a module vouch for it.
+function modulesBlock(mapText) {
+  const lines = String(mapText).split(/\r?\n/);
+  const start = lines.findIndex((l) => new RegExp(`^[├└]── ${MODULES_DIR}/`).test(l));
+  if (start === -1) return '';
+  let stop = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^[├└]── /.test(lines[i])) { stop = i; break; }
+  }
+  return lines.slice(start, stop).join('\n');
+}
+
+// Every module key the map documents: any `modules/<key>` path reference anywhere, plus any
+// `<key>/` entry line inside the modules block. Both forms are in use today, so both count.
+function documentedModuleKeys(mapText, block) {
+  const keys = new Set();
+  for (const m of String(mapText).matchAll(PATH_REF_RE)) keys.add(m[1]);
+  for (const m of String(block).matchAll(ENTRY_RE)) keys.add(m[1]);
+  return keys;
+}
+
+// The single-key form — the readable one to assert against.
+function isModuleDocumented(mapText, block, key) {
+  return documentedModuleKeys(mapText, block).has(key);
+}
+
+// Every immediate subdirectory of modules/, or [] when the tree carries no modules/ at all (a
+// consumer instance that enabled none — nothing to document).
+function listModules() {
+  return listSubdirs(path.join(REPO_ROOT, MODULES_DIR));
+}
+
+// The set comparison. Returns { onDisk, undocumented, defects } — `defects` is the non-vacuity
+// channel: this check breaks by comparing two empty sets and reporting nothing, so a state that
+// makes the comparison meaningless (modules on disk but no readable map, or no modules/ block to
+// read entries out of) is reported as a SCAN DEFECT rather than passing quietly.
+function moduleCoverage(mapText) {
+  const onDisk = listModules();
+  const defects = [];
+  if (!onDisk.length) return { onDisk, undocumented: [], defects };
+  const text = typeof mapText === 'string' ? mapText : (fs.existsSync(MAP_PATH) ? fs.readFileSync(MAP_PATH, 'utf8') : '');
+  if (!text.trim()) {
+    defects.push(`${onDisk.length} module(s) on disk but docs/file-map.md is missing or empty — the module-coverage check cannot run`);
+    return { onDisk, undocumented: [], defects };
+  }
+  const block = modulesBlock(text);
+  if (!block) defects.push('docs/file-map.md has no `modules/` block in its repo tree — module entries cannot be read (path references are still checked)');
+  const documented = documentedModuleKeys(text, block);
+  const undocumented = onDisk.filter((key) => !documented.has(key));
+  return { onDisk, undocumented, defects };
+}
+
 // Render one section's fenced tree block (the bytes that live between its markers). Arrows are
 // column-aligned to the longest label, matching the hand-formatted look of the rest of the map.
 function renderSection(model) {
@@ -144,6 +227,7 @@ function computeWrites() {
   const stale = model.flatMap((m) => m.stale);
   const writes = [];
   let markersMissing = [];
+  let mapText = '';
   if (fs.existsSync(MAP_PATH)) {
     let cur = fs.readFileSync(MAP_PATH, 'utf8');
     let next = cur;
@@ -152,8 +236,10 @@ function computeWrites() {
       next = injectSection(next, m);
     }
     if (!sameContent(next, cur)) writes.push({ full: MAP_PATH, content: next, rel: 'docs/file-map.md' });
+    mapText = next; // coverage reads the POST-generation text, so a regen never changes the verdict
   }
-  return { model, writes, missing, stale, markersMissing };
+  const modules = moduleCoverage(mapText);
+  return { model, writes, missing, stale, markersMissing, modules };
 }
 
 function main() {
@@ -162,7 +248,7 @@ function main() {
     process.stdout.write(JSON.stringify(buildModel(), null, 2) + '\n');
     return;
   }
-  const { writes, missing, stale, markersMissing } = computeWrites();
+  const { writes, missing, stale, markersMissing, modules } = computeWrites();
 
   // A missing note (dir without a note) or a stale note (note without a dir) is a hard failure in
   // BOTH modes: in --check it fails CI; in write mode we still report it (and render a visible
@@ -171,6 +257,8 @@ function main() {
   if (missing.length) problems.push(`notes MISSING for: ${missing.join(', ')} — add a one-line note to docs/file-map.notes.json`);
   if (stale.length) problems.push(`notes are STALE (no such dir) — remove from docs/file-map.notes.json: ${stale.join(', ')}`);
   if (markersMissing.length) problems.push(`docs/file-map.md is missing generated markers for: ${markersMissing.join(', ')}`);
+  if (modules.undocumented.length) problems.push(`modules with NO docs/file-map.md entry: ${modules.undocumented.map((k) => `${MODULES_DIR}/${k}`).join(', ')} — add an entry to the modules/ block of docs/file-map.md (task 1004066)`);
+  for (const d of modules.defects) problems.push(`module-coverage SCAN DEFECT — ${d}`);
 
   if (checkOnly) {
     if (writes.length || problems.length) {
@@ -197,6 +285,12 @@ if (require.main === module) main();
 module.exports = {
   materializedNames,
   SECTIONS,
+  MODULES_DIR,
+  listModules,
+  modulesBlock,
+  documentedModuleKeys,
+  isModuleDocumented,
+  moduleCoverage,
   begin,
   end,
   buildModel,

package/scripts/gds/ship-check.js

@@ -27,7 +27,7 @@ const STEPS = [
   { key: 'fitness', label: 'fitness.js (architecture + budgets + freshness gate)', argv: ['scripts/gds/fitness.js'], fix: 'read the ✗ lines above; each names its fix' },
   { key: 'repo-map', label: 'nested CLAUDE.md symbol blocks fresh', argv: ['scripts/gds/gen-repo-map.js', '--check-block'], fix: 'node scripts/gds/gen-repo-map.js' },
   { key: 'session-index', label: 'CLAUDE.md §13 session snippet fresh', argv: ['scripts/gds/gen-session-index.js', '--check-block'], fix: 'node scripts/gds/gen-session-index.js' },
-  { key: 'file-map', label: 'docs/file-map.md skills/routines sections fresh', argv: ['scripts/gds/gen-file-map.js', '--check'], fix: 'node scripts/gds/gen-file-map.js (+ a note in docs/file-map.notes.json for a new skill)' },
+  { key: 'file-map', label: 'docs/file-map.md skills/routines sections fresh + every module documented', argv: ['scripts/gds/gen-file-map.js', '--check'], fix: 'node scripts/gds/gen-file-map.js (+ a note in docs/file-map.notes.json for a new skill, or a modules/ entry in docs/file-map.md for a new module)' },
   { key: 'api-docs', label: 'docs/api/openapi.json + api-reference fresh', argv: ['scripts/gds/gen-api-docs.js', '--check'], fix: 'node scripts/gds/gen-api-docs.js' },
   { key: 'copy-registry', label: 'docs/copy-registry.json fresh', argv: ['scripts/gds/copy-inventory.js', '--check'], fix: 'node scripts/gds/copy-inventory.js', optional: true },
   { key: 'linkify', label: 'no bare #NNN task refs in committed markdown', argv: ['scripts/gds/linkify-refs.js', '--check'], fix: 'node scripts/gds/linkify-refs.js', optional: true },

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.909'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.910'; // 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('dev-box'); log.info('mounted');

package/tests/file_map.mjs

@@ -93,6 +93,65 @@ test('generation is deterministic + idempotent (a second run is a no-op)', () =>
   assert.match(r2.stdout, /already current/);
 });
 
+// ── module coverage (task 1004066) ────────────────────────────────────────────
+// The check is a set comparison over a directory listing, and a set comparison breaks by
+// comparing two empty sets and passing. Every case below is written so that a matcher which
+// vouches for everything, or a scan which enumerates nothing, FAILS here.
+
+test('every dir under modules/ is documented in file-map.md — and the set being compared is not empty', () => {
+  const cov = gen.moduleCoverage();
+  assert.ok(cov.onDisk.length > 0, 'modules/ enumerated to nothing — the coverage check would be vacuous');
+  assert.deepEqual(cov.defects, [], `module-coverage scan defects: ${cov.defects.join('; ')}`);
+  assert.deepEqual(cov.undocumented, [], `modules with no file-map entry: ${cov.undocumented.join(', ')}`);
+});
+
+test('--check FAILS (exit 2) on a module with no file-map entry — the trap case', () => {
+  const probe = path.join(ROOT, 'modules', '__filemap_probe__');
+  try {
+    mkdirSync(probe, { recursive: true });
+    writeFileSync(path.join(probe, 'module.json'), '{"key":"__filemap_probe__"}\n');
+    const cov = gen.moduleCoverage();
+    assert.ok(cov.onDisk.includes('__filemap_probe__'), 'the probe module must be enumerated');
+    assert.deepEqual(cov.undocumented, ['__filemap_probe__'], 'an undocumented module must be the ONLY finding');
+    const r = run(['--check']);
+    assert.equal(r.code, 2, 'an undocumented module must fail the gate');
+    assert.match(r.stderr, /modules with NO docs\/file-map\.md entry/);
+    assert.match(r.stderr, /__filemap_probe__/);
+  } finally {
+    rmSync(probe, { recursive: true, force: true });
+  }
+  // Asserted on the module finding rather than the exit code: --check reports every problem class
+  // at once, and a checkout carrying unrelated local noise (materialised module skills with no
+  // note) would otherwise make this read as "the probe is still there".
+  const after = run(['--check']);
+  assert.equal(gen.moduleCoverage().undocumented.length, 0, 'coverage is clean once the probe module is removed');
+  assert.doesNotMatch(after.stderr || '', /modules with NO docs\/file-map\.md entry/);
+});
+
+test('the matcher discriminates: a real module passes, an absent one does not, and a prefix cannot vouch', () => {
+  const md = readFileSync(path.join(ROOT, 'docs', 'file-map.md'), 'utf8');
+  const block = gen.modulesBlock(md);
+  assert.ok(block.length > 0, 'the modules/ tree block must be findable — an empty block would make entries unreadable');
+  assert.ok(gen.isModuleDocumented(md, block, 'government'), 'a documented module reads as documented');
+  assert.equal(gen.isModuleDocumented(md, block, '__no_such_module__'), false, 'an absent module must NOT read as documented');
+  // A bare substring test would let `modules/agents-extra` vouch for `agents`.
+  assert.equal(
+    gen.isModuleDocumented('see modules/agents-extra/thing.js', '', 'agents'),
+    false,
+    'a longer path sharing the prefix must not count as an entry',
+  );
+  // A skill dir listed in the same `├── name/` shape elsewhere in the map must not vouch either:
+  // the entry search is scoped to the modules/ block.
+  assert.equal(gen.modulesBlock('├── .claude/skills/\n├── recall/  ← a skill\n'), '', 'no modules/ block → no block to read entries from');
+});
+
+test('module coverage reports a SCAN DEFECT rather than passing when the map cannot be read', () => {
+  const cov = gen.moduleCoverage('');
+  assert.ok(cov.onDisk.length > 0);
+  assert.equal(cov.defects.length, 1, 'an unreadable map is a defect, not a pass');
+  assert.match(cov.defects[0], /cannot run/);
+});
+
 test('every note maps to a real skill/routine (sidecar has no dangling keys)', () => {
   const notes = JSON.parse(readFileSync(path.join(ROOT, 'docs', 'file-map.notes.json'), 'utf8'));
   for (const section of gen.SECTIONS) {