@bongos/core 1.19.909 → 1.19.911

package/modules/ideas/routes/inbox.js

@@ -52,6 +52,10 @@ const { completenessScore, weakestSectionPayload, scoreFieldValues } = require('
 // The trusted tier, spelled once (task 1003197 (D)) — routing.js owns METIC_PLUS
 // and already names 'criterion-proposal' in NEVER_ROUTE_KINDS.
 const { mayProposeCriterion, METIC_PLUS } = require('../routing');
+// "Gravity" — the landing verdict read BEFORE the write (task 1004083, BV2.R02).
+// Read-only and never-throwing; it calls the same matrix the capture calls so the
+// composer can state the outcome instead of implying one. See ../landing-preview.js.
+const { previewLanding } = require('../landing-preview');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('ideas');
 const { validateOrRespond, LIMITS, parseId } = api;
@@ -514,6 +518,49 @@ module.exports = function buildInboxRouter() {
     const { score, fields } = scoreFieldValues(req.body.field_values, templateKey ? { templateKey } : undefined);
     return res.json({ score, fields, template_key: templateKey || null });
   }, { errorCode: 'score_failed' }));
+  // POST /inbox/preview-landing — GRAVITY, MADE VISIBLE (task 1004083, BV2.R02).
+  //
+  // What pressing "File it" would do, without doing it. The composer draws one
+  // line from this so a filer can see which goal will catch the thought, change
+  // it, or deliberately let it float — the criterion's done-when, read literally.
+  //
+  // A DRY RUN IN THE SHAPE OF /inbox/score DIRECTLY ABOVE: same POST-with-a-body
+  // reason (the draft is the input, not an id), same "a half-formed draft is a
+  // legal state" contract. It differs in one way worth naming, because the file
+  // header above claims /score is pure: this one READS (the goal row, the
+  // building version). It still WRITES NOTHING — see ../landing-preview.js, which
+  // calls `currentBuildingVersionId` and deliberately never `ensureMaintenanceGoal`,
+  // so previewing a homeless bug cannot mint a goal as a side effect of typing.
+  //
+  // THE RANK AND THE VECTOR ARE NOT READ FROM THE BODY, exactly as POST /inbox
+  // refuses to read them: the rank comes off the authenticated builder and the
+  // vector is hardcoded to 'api'. A preview is only worth having if it is the
+  // same question the capture will be asked — one that answered a rank the filer
+  // does not hold would teach them a landing they cannot have.
+  //
+  // NEVER A 4xx FOR A DRAFT. Only the input SHAPE is validated; an unknown kind,
+  // an absent title, a goal that vanished all come back as `outcome: null`
+  // ("nothing to say yet"), because a composer redrawing on every keystroke must
+  // degrade to silence rather than to a red error under a half-typed thought.
+  //
+  // rank: any-builder — it answers only about the caller's own prospective
+  // filing, and filing itself is open to every rank.
+  router.post('/inbox/preview-landing', api.requireBuilder, api.asyncHandler('POST /inbox/preview-landing', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      goal_id: { type: 'integer', min: 1 },
+      kind: { type: 'string', maxLength: 64 },
+      grade: { type: 'string', maxLength: 16 },
+    })) return;
+    const body = req.body || {};
+    const verdict = await previewLanding({
+      goalId: body.goal_id ?? null,
+      kind: body.kind ?? null,
+      grade: body.grade ?? null,
+      filerRank: req.builder?.rank ?? null,
+      vector: 'api',
+    });
+    return res.json(verdict);
+  }, { errorCode: 'preview_landing_failed' }));
   // GET /inbox/sparks — THE SPARK QUEUE (task 1002921 / BV1.R145, goal 1000062).
   //
   // Big Idea Sparks awaiting development: the ideator craft's pickup surface,

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.909",
+  "version": "1.19.911",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.909",
+      "version": "1.19.911",
       "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.911",
   "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/api-alias-caller-scan.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+'use strict';
+// api-alias-caller-scan.js — the detector behind the lowercase `/api/gds` CALLER ratchet
+// (task 1004064, from idea 1001030; the sibling of gds-literal-scan.js).
+//
+// WHY THIS EXISTS. Task 1003707 (criterion C3e of goal 1000073) moved 665 in-repo callers off the
+// permanent `/api/gds` alias onto the canonical `/api/bongos`. The ratchet that already guards the
+// rename, `legacy_gds_literals`, is CASE-SENSITIVE on the shouting acronym — deliberately, because
+// `GDS` is the word a newcomer trips over. So that metric read 1135 before the sweep and 1135
+// after it, and it was right to: the alias is spelled in lowercase.
+//
+// The consequence is the gap this file closes. The lowercase spelling is invisible to CI in BOTH
+// directions: the 665-caller sweep earned no credit, and — the half that matters — a caller written
+// against `/api/gds` tomorrow moves no number and reds no build. 1003707's own session log says it
+// plainly: "the 665 will quietly grow back". `tests/api_alias_exceptions.mjs` pins the callers that
+// were deliberately LEFT behind and why, but it polices the exceptions, not new offenders. That is
+// a ratchet's job.
+//
+// WHY A COUNT AND NOT ZERO. Every remaining occurrence has a reason, and most of them are reasons
+// that will never expire — the OAuth callbacks are registered in GitHub's and Discord's app
+// settings, the uptime poller is the one production caller proving the alias still answers, and
+// tests are what keep it exercised in CI. A zero-rule would demand deleting things that must not be
+// deleted. So this holds the line the same way its sibling does: the number may fall, never rise.
+//
+// WHAT IS NEVER COUNTED, and why each one. The exclusion list is not invented here — it is
+// 1003707's own worked-out list, transcribed from docs/session-logs/2026-09-16-task-1003707-api-gds-callers.md
+// so that a future move has to argue with a stated reason rather than with a leftover:
+//
+//   1. THE ALIAS CONTRACT (path-excluded). api-prefix.js and api-path-404.js ARE the alias; they
+//      cannot name it less often than they do.
+//   2. THE PINNED OAUTH CALLBACKS (path-excluded). routes/auth.js, provisioning.js and the scripts
+//      + skills that register the same callback for a new instance. These paths live in the GitHub
+//      and Discord app settings; a repo-only change silently breaks sign-in.
+//   3. THE LIVE PROOF (path-excluded). uptime-poller.js and smoke-gds.js exercise the alias on
+//      purpose — if nothing calls it, its eventual breakage is found by a user rather than by us.
+//      Note fitness-ratchets.js belongs here too: it is the GATE, and its builder-facing hint has
+//      to spell the alias out to tell anyone what they tripped over.
+//   4. THE RENAME GUARDRAILS (path-excluded). rename-history-check.js, rename-ledger-prose.js,
+//      gds-literal-scan.js, codemod-rename-src-gds.js, fitness-ratchets.js and THIS FILE name the
+//      old path because that is what they are for. Same principle as GDS_RULE_FILES next door: a
+//      gate that cannot state its own rule cannot explain itself.
+//   5. tests/ (path-excluded). Tests are what keeps the alias exercised in CI. Moving them off it
+//      would retire the alias by accident.
+//   6. docs/ (path-excluded) — a DELIBERATE SCOPE CALL, not an oversight. It is the largest
+//      remaining bucket (~320) and it is where rename-history-check's per-file floors live, so a
+//      docs pass has to separate the record of what we used to call it from instructions that
+//      still teach the old spelling. 1004064's own brief says to treat docs as out of scope and
+//      file it rather than widen the task; filed as the follow-up named in that task's session log.
+//   7. MIGRATIONS + THE FROZEN RECORD (path-excluded). Same rule as the sibling detector: an
+//      applied migration renamed is an applied migration re-run, and a rewritten ADR destroys the
+//      evidence that the words changed.
+//   8. A LINE THAT IS ABOUT THE ALIAS (line-excluded). Any line that ALSO names `/api/bongos`, or
+//      carries the words alias / legacy / permanent / forever, is commentary on the alias rather
+//      than a caller of it. This is the same rule 1003707's codemod used to decide what to leave,
+//      so the ratchet and the sweep agree by construction.
+//   9. CAPTURED FIXTURES (path-excluded). scripts/hall-preview/fixtures/*.json are snapshots of
+//      real API responses; rewriting one would make the fixture misreport what the server returned.
+//
+// Usage:
+//   node scripts/gds/api-alias-caller-scan.js            # count + the top offending files
+//   node scripts/gds/api-alias-caller-scan.js --files    # every file with its count
+//   node scripts/gds/api-alias-caller-scan.js --json
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// The alias, lowercase — the whole point of this detector, since its sibling is case-sensitive on
+// the shouting form and therefore blind to exactly this spelling.
+const ALIAS = '/api/gds';
+const ALIAS_RE = /\/api\/gds/g;
+
+// The canonical prefix. A line naming BOTH is commentary on the alias, not a caller of it.
+const CANONICAL = '/api/bongos';
+
+// Path exclusions, matched against the repo-relative path (forward slashes), at any depth.
+// Every entry maps to a numbered reason in the header above — keep them in step.
+const ALIAS_EXCLUDED_PATHS = [
+  // 1. the alias contract
+  /^src\/bongos\/api-prefix\.js$/,
+  /^src\/bongos\/api-path-404\.js$/,
+  // 2. the pinned OAuth callbacks + everything that registers them for a new instance
+  /^src\/bongos\/routes\/auth\.js$/,
+  /^modules\/provisioning\/provisioning\.js$/,
+  /^scripts\/gds\/(onboard|provision-net|dev|login)\.js$/,
+  /^modules\/lifecycle\/kickoff-checklist\.js$/,
+  /^modules\/public-landing\/public\/projects\.html$/,
+  /^\.claude\/skills\/new-project\/SKILL\.md$/,
+  // 3. the live proof that the alias still answers
+  /^src\/bongos\/uptime-poller\.js$/,
+  /^scripts\/gds\/smoke-gds\.js$/,
+  // 4. the rename guardrails — they name the old path on purpose
+  /^scripts\/gds\/(rename-history-check|rename-ledger-prose|gds-literal-scan|codemod-rename-src-gds|api-alias-caller-scan|fitness-ratchets)\.js$/,
+  /^config\/(fitness-baselines|rename-history-baseline)\.json$/,
+  // 5. tests keep the alias exercised in CI — the repo's own two spellings, `tests/` at the root
+  //    and a module's `tests/` or `test/` dir. Deliberately NOT a blanket `\.mjs$`: three .mjs
+  //    files are not tests (clients/bongos-client/index.mjs and its example, scripts/status-probe.mjs)
+  //    and the client is exactly the kind of caller this ratchet exists to police.
+  /(^|\/)tests?\//,
+  // 6. docs are a separate pass (scope call, see the header)
+  /(^|\/)docs\//,
+  // 7. migrations + the frozen record
+  /(^|\/)migrations\//,
+  /(^|\/)limitations\//,
+  // 9. captured API-response fixtures
+  /(^|\/)fixtures\//,
+];
+
+// Vendored / generated / third-party trees — the same exclusion the sibling detector applies.
+const ALIAS_EXCLUDED_TREES = /(^|\/)(node_modules|public-docs)\/|\.min\.js$|(^|\/)vendor\//;
+
+// A line that is ABOUT the alias rather than a caller of it. Rule 8 above.
+const ALIAS_COMMENTARY_RE = /\balias\b|\blegacy\b|\bpermanent\b|\bforever\b/i;
+
+function isExcludedPath(relPath) {
+  const p = relPath.replace(/\\/g, '/');
+  if (ALIAS_EXCLUDED_TREES.test(p)) return true;
+  return ALIAS_EXCLUDED_PATHS.some((re) => re.test(p));
+}
+
+// isCountedLine — a line naming the alias that is a CALLER rather than commentary. Exported so the
+// test and any future sweep share ONE decision (the gds-literal-scan precedent: a gate whose
+// detector drifts from its sweep is worse than no gate).
+function isCountedLine(line) {
+  if (!line.includes(ALIAS)) return false;
+  if (line.includes(CANONICAL)) return false;
+  if (ALIAS_COMMENTARY_RE.test(line)) return false;
+  return true;
+}
+
+// countInText — alias occurrences on counted lines only. A line can legitimately carry more than
+// one (two fetches, a usage banner), so occurrences are counted rather than lines: that is what
+// makes the number fall when a caller is actually moved.
+function countInText(text) {
+  let n = 0;
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!isCountedLine(line)) continue;
+    n += (line.match(ALIAS_RE) || []).length;
+  }
+  return n;
+}
+
+function trackedFiles() {
+  const out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+// scanAliasCallers — { total, byFile, scanned } across every tracked, countable file.
+//
+// `scanned` is the NON-VACUITY channel, and it is the whole reason this function returns it. A
+// static scan breaks by finding nothing, and a green run looks identical to a working one: if
+// `git ls-files` returns nothing, or every path is excluded, this reports total 0 and a caller
+// that reads only `total` cannot tell a clean tree from a broken scanner. The ratchet and the test
+// both assert `scanned > 0`, so an enumeration that collapses fails LOUDLY instead of passing.
+//
+// `files` and `readFile` are injectable for tests, so the real aggregation — exclusions, the
+// commentary rule, per-file totals — is exercised without writing into the repo. The unit lane runs
+// test files in parallel; a test that edited a tracked file would break whichever suite happened to
+// be scanning the tree at that moment.
+function scanAliasCallers({ files = null, readFile = null } = {}) {
+  const read = readFile || ((relPath) => fs.readFileSync(path.join(ROOT, relPath), 'utf8'));
+  const byFile = {};
+  let total = 0;
+  let scanned = 0;
+  for (const relPath of files || trackedFiles()) {
+    if (isExcludedPath(relPath)) continue;
+    let text;
+    try {
+      text = read(relPath);
+    } catch {
+      continue;
+    }
+    if (text.includes(String.fromCharCode(0))) continue; // binary (a NUL byte)
+    scanned += 1;
+    const n = countInText(text);
+    if (n) {
+      byFile[relPath] = n;
+      total += n;
+    }
+  }
+  return { total, byFile, scanned };
+}
+
+function main() {
+  const { total, byFile, scanned } = scanAliasCallers();
+  const ranked = Object.entries(byFile).sort((a, b) => b[1] - a[1]);
+  if (process.argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify({ total, byFile, scanned }, null, 2)}\n`);
+    return;
+  }
+  const show = process.argv.includes('--files') ? ranked : ranked.slice(0, 20);
+  console.log(`in-repo /api/gds callers: ${total} across ${ranked.length} file(s) (${scanned} file(s) scanned)`);
+  console.log('(the alias contract, the pinned OAuth callbacks, the uptime poller + smoke, the rename guardrails,');
+  console.log(' tests/, docs/, migrations/ and captured fixtures are excluded by construction; so is any line that');
+  console.log(' also names /api/bongos or carries the words alias / legacy / permanent / forever)');
+  console.log('');
+  for (const [f, n] of show) console.log(`  ${String(n).padStart(5)}  ${f}`);
+  if (show.length < ranked.length) console.log(`  … and ${ranked.length - show.length} more file(s) — pass --files for all`);
+}
+
+if (require.main === module) main();
+
+// Only what a consumer actually calls. The constants above stay module-private on purpose: an
+// export nobody imports reads as dead code to knip and costs a ratchet point for nothing, and the
+// rules are meant to be read here rather than re-implemented by a caller.
+module.exports = {
+  isExcludedPath,
+  isCountedLine,
+  countInText,
+  scanAliasCallers,
+};

package/scripts/gds/fitness-ratchets.js

@@ -347,6 +347,15 @@ const METRIC_HINTS = {
     + 'Write Bongos instead. Run `node scripts/gds/gds-literal-scan.js` to see every counted file. '
     + 'Version ids (GDS-V##), docs/adr, docs/session-logs, docs/audits, limitations and migrations '
     + 'are excluded by construction — if your literal is history, it belongs in one of those.',
+  legacy_api_gds_callers:
+    ' — a NEW in-repo caller was written against the permanent `/api/gds` alias (task 1004064, '
+    + 'idea 1001030). Ask for `/api/bongos` instead: the alias exists for callers we CANNOT update '
+    + '(shipped Dev Box binaries, live dev boxes), not for code in this repo. Run '
+    + '`node scripts/gds/api-alias-caller-scan.js --files` to see every counted line. The alias '
+    + 'contract, the pinned OAuth callbacks, the uptime poller + smoke, the rename guardrails, '
+    + 'tests/, docs/, migrations/ and captured fixtures are excluded by construction — and so is '
+    + 'any line that also names /api/bongos or carries the words alias / legacy / permanent / forever, '
+    + 'so if your line is ABOUT the alias rather than a call to it, say so on the line.',
 };
 
 function compareToBaselines(metrics, baselines) {
@@ -379,6 +388,27 @@ function gdsMetrics() {
   return { legacy_gds_literals: scanGdsLiterals().total };
 }
 
+// legacy_api_gds_callers — the LOWERCASE half of the same rename (task 1004064, idea 1001030).
+// `legacy_gds_literals` above is case-sensitive on the shouting acronym, so it read 1135 both
+// before and after task 1003707 moved 665 in-repo callers off `/api/gds` — correct for what it
+// measures, and exactly why a caller written against the alias tomorrow moves no number and reds
+// no build. This counts that spelling instead. Detector + the reason for every exclusion:
+// scripts/gds/api-alias-caller-scan.js.
+//
+// It FAILS CLOSED on a collapsed enumeration. A static scan breaks by finding nothing, and a
+// green run looks identical to a working one — so if the scanner scanned no files at all, the
+// metric is OMITTED with a reason on stderr rather than reported as a flattering 0 that would
+// invite someone to ratchet the baseline down to it.
+function apiAliasCallerMetrics() {
+  const { scanAliasCallers } = require('./api-alias-caller-scan.js');
+  const { total, scanned } = scanAliasCallers();
+  if (!scanned) {
+    process.stderr.write('fitness-ratchets: legacy_api_gds_callers NOT MEASURED — the caller scan enumerated ZERO files, which is a scan defect, not a clean tree\n');
+    return {};
+  }
+  return { legacy_api_gds_callers: total };
+}
+
 // skill_listing_chars — the resident cost of the skill listing (every name +
 // description, both skill homes). Ratcheted rather than merely warned about
 // because this number has now been trimmed three times (tasks 1003548, 1003587,
@@ -411,6 +441,7 @@ function computeMetrics({ withDocs = true } = {}) {
     require_cycle_count: countCycles(requireGraph(contents)),
     console_call_count: consoleCallCount(contents),
     ...gdsMetrics(),
+    ...apiAliasCallerMetrics(),
     ...skillListingMetrics(),
     ...(withDocs ? docMetrics() : {}),
   };

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/scripts/hall-preview/server.js

@@ -231,7 +231,20 @@ app.use((req, res, next) => {
     return res.end(png);
   }
 
-  if (req.method !== 'GET') {
+  // READ-SHAPED POSTS. A handful of routes are POSTs only because the INPUT is a
+  // draft rather than an id — they write nothing. Serving them the 501 below made
+  // their surfaces permanently un-demoable here: the page renders its degraded
+  // state forever, which is the "a page that only ever renders its empty state
+  // cannot be redesigned by looking" trap modules/hall-ui/CLAUDE.md names. They
+  // fall through to the ordinary fixture lookup instead.
+  //
+  // AN ALLOWLIST, and it stays short. Anything absent is still refused, so a real
+  // write cannot reach the harness by growing a comment — adding a member means
+  // asserting that route writes nothing, which is checkable at its handler.
+  const READ_SHAPED_POSTS = new Set([
+    'inbox/preview-landing', // the landing verdict for a draft (task 1004083)
+  ]);
+  if (req.method !== 'GET' && !READ_SHAPED_POSTS.has(apiPath)) {
     return res.status(501).json({ error: { code: 'preview_readonly', message: 'the preview harness serves fixtures; writes are not wired' } });
   }
   // Your own account wins over the checked-in snapshot; a me-scoped read that

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.911'; // 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');