@bongos/core 1.19.1054 → 1.19.1055

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1054",
-  "core_contract": "1.19.1054",
-  "source_commit": "16cad90499c802cd308487cec2c824589b064b95",
+  "core_version": "1.19.1055",
+  "core_contract": "1.19.1055",
+  "source_commit": "dc38a2a4e86d707edd38427cf7df3c4437458758",
   "source_ref": "HEAD",
-  "built_at": "2026-09-28T04:35:28.546Z",
+  "built_at": "2026-09-28T05:05:07.855Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 542,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2509,
+    "functional_verbatim": 2511,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3078,
-  "tree_sha256": "b4fe4ba91ff03f9db59c7306f72e4f1898f4f5d0a168d05a228e0689c42765db",
+  "file_count": 3080,
+  "tree_sha256": "b6c500e72b0b49f4521c50a3282616cfdf968b85b827eace71deb76fca3f55dd",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "64d65a849596466c7fbafba381668129c2e305e88af805dc5eed06a5b06600bb"
+      "sha256": "fe02a043a43ec6c062efea669b07722ae08e5ef93555ca80e489504dbc0180ad"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2737,7 +2737,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "cd63efa0d5860b1d1e150d0472ea95cc8285e58526aae6696f05dc803ca7cfea"
+      "sha256": "5a093f82bbd86f7932a798a5e53f85609e08c7837ef64c2334a7a2b8efc401c1"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8462,12 +8462,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7a222030251e4f1975d78ef3b4bf78d212aa17b80d001b6858f0dcf92bbf0d90"
+      "sha256": "b60b03c560a09917e3383f0630839ff29ffade876f87f0079f1cb718dac762e6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b4cf0e08cfe3dc1e5980144ff698d22ac1800712e3939a663d67845232d0b95c"
+      "sha256": "21389dd422886a6fcf8088ac5be8dd63f39e76f6c28fd063f3cd72e9eadefc2c"
     },
     {
       "path": "public-docs/index.html",
@@ -8487,7 +8487,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "b4125b6b8f4b390e216f8686281a0a98da09c2a405f662beb8368ef6dee81ce3"
+      "sha256": "3631f0c336ffb1fa2da262932c3158a4cb79c640c52ffc04e08a21b23c8f4534"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9062,7 +9062,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "4e698cceb33eeea11fdab35cf6bf878b7f12bd1057f79c6ca8b0740d45e80e68"
+      "sha256": "6ea5ed4e24c83e50d3931e3a5a769b9f37d029627540d410e772200d5cc3652d"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -9384,6 +9384,11 @@
       "mode": "0000644",
       "sha256": "aa29af97270a614699e5480e0db5b7bf34034958cc28e92bee5a04f7c5c95bec"
     },
+    {
+      "path": "scripts/gds/page-inventory.js",
+      "mode": "0000644",
+      "sha256": "f4b676c3949015733bc3f1bcaf369c2ab1225583b0200f862c25a6f0f18d3873"
+    },
     {
       "path": "scripts/gds/paste-token.js",
       "mode": "0000644",
@@ -9842,7 +9847,7 @@
     {
       "path": "scripts/gds/ship-check.js",
       "mode": "0000644",
-      "sha256": "40322d95339d20fd0ab0dcf6bd528736b815d895b31ca6a54490fb31c769a480"
+      "sha256": "3ca2e32eaea17ef03a91606b3815551a8cfdd3987b6e182c08017c84c7947ee3"
     },
     {
       "path": "scripts/gds/ship-deploy-target.js",
@@ -10562,7 +10567,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b31a0374ebfe190599d53bfd40004328cc7bb1aa3906487c005a53718b990a21"
+      "sha256": "22a1cf07ea07585df430c3a395af379d9a6bb81b20d5bf647128272568b57580"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13629,6 +13634,11 @@
       "mode": "0000644",
       "sha256": "3b24dc37c492b248242568db7dd9d508e17e05aa746bb719952b8a06a58c395f"
     },
+    {
+      "path": "tests/page_inventory.mjs",
+      "mode": "0000644",
+      "sha256": "363855afde70c909be7b6392d36663848c823afed0131a8785286b7b93ca321b"
+    },
     {
       "path": "tests/parallel-load.mjs",
       "mode": "0000644",

package/docs/file-map.md

@@ -48,6 +48,8 @@
 │   ├── file-map.notes.json      ← ADR 0066 ([#1276](https://example.com/builders#/task/1276)): the sidecar of one-line notes for each skill/routine that gen-file-map.js renders into file-map.md; the ONE place to edit those notes — a new skill with no note here fails CI
 │   ├── copy-registry.json      ← GENERATED (scripts/gds/copy-inventory.js): the machine-readable copy registry — 1,096 user-facing strings with stable ids, render paths, and duplicates. R02's flag queue attaches to these ids; regenerate + commit, never hand-edit
 │   ├── copy-inventory.md       ← GENERATED twin of copy-registry.json: the human-readable copy report, including the "what this cannot see" section (server-side messages, skill prose, Discord copy, runtime-composed strings, and the src/ui-vs-reality surface mismatch)
+│   ├── page-inventory.json     ← GENERATED (scripts/gds/page-inventory.js, BV2.TW02 task 1004314): every page of every enabled web surface (builders hall, landing, status) with its stable id <surface>:<page>, title, portable url, the files that render it and its .states.json states. Tweak Mode keys page status, claims and pay on these ids; regenerate + commit, never hand-edit
+│   ├── page-inventory.md       ← GENERATED twin of page-inventory.json: the id rule, then one table per surface
 │   ├── handoff-template.md      ← session-end template + Definition of Done
 │   ├── module-api-changelog.md  ← the `CORE_VERSION` release ledger for the published doorway (ADR 0203, task 1003335). MOVED here out of src/module-api.js: the ADR 0161 CI carrier appends an entry on every release and pushes straight to main, which grew that .js file past the 1500-line oversized-file ratchet and turned `unit` red for main and every open PR. Markdown is exempt from the .js line budget. Written by scripts/gds/bump-version.js (entries oldest-first, each inserted above the closing divider); the CORE_VERSION literal itself stays in src/module-api.js
 │   ├── google-chat-broadcast.md ← team-chat integration plan
@@ -199,6 +201,7 @@
 │       ├── docs-entropy.js      ← ([#…] docs-entropy) markdown-corpus linter: broken internal links + cross-file duplicate-prose detector across every tracked `.md`; `--verbose` / `--file-ideas`
 │       ├── doc-comment-coverage.js ← ADR 0095 / task 1001654: the ADVISORY doc-comment nudge (fitness Check 28) — reports source files under src/·scripts/·modules/ that open with no module header. Never hard-fails: a doc-comment gate that blocks a ship buys filler prose, and making it blocking needs owner sign-off + its own ADR. CRLF-safe (unlike docs-entropy.js); an empty enumeration throws as a scan defect
 │       ├── copy-inventory.js  ← R01 of goal 1000074 (the artist's loop): the COPY REGISTRY — every user-facing string across the hall / status / landing surfaces, each row naming the render path that shows it (html-text · html-attr · js-markup · js-notice · js-text-assign) + a stable id that survives a move. Writes docs/copy-registry.json + docs/copy-inventory.md; `--check` fails on drift. Precision over recall: a JS literal with no render path is not listed
+│       ├── page-inventory.js  ← BV2.TW02 (task 1004314): the PAGE INVENTORY — surfaces from the loader's moduleWebSurfaces() over the ENABLED modules (no hardcoded list), pages from each surface's *.html, ids <surface>:<page> (page = body[data-page] else the file name). Writes docs/page-inventory.json + .md; `--check` (run by fitness.js + ship-check.js) fails on drift, a duplicate id or an empty surface
 │       ├── copy-apply.js     ← R03 of goal 1000074 (ADR 0233): lands a copy proposal as a REAL DIFF under a claim — the design half’s adapter.export() applied to text. Reads the fenced copy-proposal patch off a task (--task N; --dry-run, --patch-file), RE-DERIVES the string’s position by re-running copy-inventory’s own extractor over the working tree (the registry commits no offsets — they go stale, the id does not), re-injects the source’s own ${expr} into the proposal’s {…} holes, writes, regenerates the registry and verifies its own edit. Refuses BY NAME on target_gone / ambiguous_target / no_exact_span / placeholder_mismatch / path_outside_surface. The ONLY writer in the copy feature, and deliberately a command rather than a route
 │       ├── gen-role-responsibilities.js ← writes each role pack's written-responsibility block from src/role-responsibilities.js (task 1003732, ADR 0275). Targets come from the role registry, not a hardcoded list, so a renamed pack or a fourth craft needs no edit here; the block takes the pack's own line ending (the packs are CRLF on Windows, LF in CI). `--check` is the CI gate, run by role-pack-guard.js — never hand-edit a block
 │       ├── role-pack-guard.js   ← the fitness check over the role packs (task 1002990, ADR 0274): every registry entry resolves to a real pack, every pack fits its char budget, three crafts carry one, and each pack's responsibility block is current. HARD-fails because claim.js reads the registry fail-open, so a broken pack path is silent at runtime

package/docs/module-api-changelog.md

@@ -2595,5 +2595,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1052 with no explicit bump. run 36375859084. (task 1002620)
   1.19.1054 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1053 with no explicit bump. run 36378326588. (task 1002620)
+  1.19.1055 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1054 with no explicit bump. run 36380323033. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

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

@@ -7625,5 +7625,11 @@
       "id": "1004334",
       "text": "The platform can now apply a saved setting to its own site, not just to the projects it hosts. Turning the artist gate off on Cloud Bongos will actually reach cloudbongos.com: the platform updates its own settings file and res"
     }
+  ],
+  "1.19.1055": [
+    {
+      "id": "1004314",
+      "text": "Every page the project serves now has a name that stays put. A new generated list names all 37 pages across the builders hall (30), the landing site (5) and the status site (2). Each entry gives the page a short id such as bui"
+    }
   ]
 }

package/scripts/gds/fitness.js

@@ -243,9 +243,17 @@ function checkGeneratedArtifactsFresh() {
   } catch {
     violations.push('docs/copy-registry.json + docs/copy-inventory.md are STALE — every row carries a line number, so editing any scanned UI file shifts them. Run `node scripts/gds/copy-inventory.js` and commit (task 1003556).');
   }
+  try {
+    // task 1004314 (BV2.TW02): the page inventory is the key Tweak Mode's page status,
+    // claims and pay join on, so a page added, renamed or retitled without it would
+    // be a page the chain cannot see. --check also fails on a duplicate or malformed id.
+    execFileSync(process.execPath, [path.join(__dirname, 'page-inventory.js'), '--check'], { cwd: REPO_ROOT, stdio: 'pipe' });
+  } catch {
+    violations.push('docs/page-inventory.json + docs/page-inventory.md are STALE (or two pages claim one id) — a page was added, renamed, retitled or changed its scripts/states. Run `node scripts/gds/page-inventory.js` and commit (task 1004314).');
+  }
   // NB the role packs' responsibility blocks are generated too, but their freshness
   // is asserted by role-pack-guard.js — one check owns "the packs are correct".
-  return { name: 'generated artifacts fresh', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings: [], note: 'Tracked generated content matches source: nested CLAUDE.md symbol blocks (code) + the CLAUDE.md §13 snippet (sessions) via --check-block, plus the CLAUDE.md §2 interaction-posture block (the knob defaults), docs/file-map.md skills/scheduled-tasks sections, docs/api/openapi.json + api-reference.md (API) and docs/copy-registry.json + copy-inventory.md (the reader-facing copy, task 1003556). The gitignored docs/repo-map.md + docs/session-log-index.md are deploy-regenerated (ADR 0110), not gated here.' };
+  return { name: 'generated artifacts fresh', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings: [], note: 'Tracked generated content matches source: nested CLAUDE.md symbol blocks (code) + the CLAUDE.md §13 snippet (sessions) via --check-block, plus the CLAUDE.md §2 interaction-posture block (the knob defaults), docs/file-map.md skills/scheduled-tasks sections, docs/api/openapi.json + api-reference.md (API), docs/copy-registry.json + copy-inventory.md (the reader-facing copy, task 1003556) and docs/page-inventory.json + page-inventory.md (every page and its stable id, task 1004314). The gitignored docs/repo-map.md + docs/session-log-index.md are deploy-regenerated (ADR 0110), not gated here.' };
 }
 
 // ---- deterministic cron routine boundary (System 4 / ADR 0078) -------------

package/scripts/gds/page-inventory.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/page-inventory.js — the PAGE INVENTORY: every page of every web
+// surface an instance serves, each with a stable id (BV2.TW02, task 1004314;
+// goal 1000095, the Tweak Mode chain — docs/specs/bongos-v2-tweak-mode.md).
+//
+// WHY. Tweak Mode's unit is the PAGE: its status, claim, draft, changelog and pay
+// all key on a page id (spec, decision 1). Until now a page was implicit — a
+// body[data-page] attribute in the hall, a file name on the landing and status
+// surfaces — so nothing could say "these are the 42 pages, and this is the one you
+// hold". This generator makes the list explicit, and gives every page an id the
+// rest of the chain (TW03 the ADR, TW04 the page reader, TW05 statuses, TW06
+// claims) can store and join on.
+//
+// PORTABLE BY CONSTRUCTION. The surfaces are NOT a list in this file: they come
+// from the module loader's moduleWebSurfaces() over the modules THIS instance has
+// enabled (src/modules.js isModuleEnabled). An instance that disables its front
+// door has no landing pages here; a module that ships a new web surface appears
+// with no edit to this file. Same seam serve-internal.js and platform-server.js
+// route from, so the inventory and the router cannot disagree about what exists.
+//
+// THE ID RULE (also written into both artifacts' headers — it is the contract):
+//   <surface>:<page>
+//   surface = the web surface's Host prefix without its dot ("builders." ->
+//             "builders", "status." -> "status"); the apex-root surface is
+//             "landing" (ADR 0218 allows exactly one apex root per instance).
+//   page    = the page's own body[data-page] when it declares one (the hall's
+//             pages do), otherwise the html file's base name ("index.html" ->
+//             "index").
+//   Both halves are what a person already sees in an address or a file, so an id
+//   reads as a place: builders:studio, landing:index, status:explore. Ids are
+//   lowercase [a-z0-9-] on both sides; a page that would break that, or two pages
+//   sharing one id, fail the build by name rather than being renamed silently.
+//   An id changes ONLY when the host prefix, the data-page value or the file name
+//   changes — each a deliberate rename, and the ledger records keyed on the old id
+//   (TW05) must be carried across in the same change.
+//
+// DELIBERATELY IN THE gen-* FAMILY, modelled on copy-inventory.js: fs only (no DB,
+// no network, no clock), byte-deterministic on a given tree, a committed JSON twin
+// plus a human report, and a --check that fitness.js ("generated artifacts fresh")
+// and ship-check.js run so drift fails before it merges.
+//
+// Run:  node scripts/gds/page-inventory.js            (writes both artifacts)
+//       node scripts/gds/page-inventory.js --check    (exit 1 if stale or invalid)
+//       node scripts/gds/page-inventory.js --json     (inventory to stdout, no write)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+// Repo-relative paths inside the committed artifacts are joined with '/', never
+// path.join — a Windows run must write the same bytes CI compares against.
+const INVENTORY_REL = 'docs/page-inventory.json';
+const REPORT_REL = 'docs/page-inventory.md';
+
+const ID_RULE = [
+  'id = <surface>:<page>.',
+  'surface = the web surface Host prefix without its dot (builders., status.) or "landing" for the apex-root surface.',
+  'page = the page body[data-page] when declared, otherwise the html file base name.',
+  'Both halves are lowercase [a-z0-9-]; a duplicate or malformed id fails the generator by name.',
+  'An id changes only when the host prefix, the data-page value or the file name changes; that is a rename, and records keyed on the old id move with it.',
+];
+
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+
+// Locale-independent order (see copy-inventory.js: localeCompare depends on ICU).
+function cmp(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+function toPosix(p) { return p.split(path.sep).join('/'); }
+
+// The few entities hall titles actually use. Not a general decoder, on purpose.
+function decodeEntities(s) {
+  return String(s)
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ');
+}
+
+// The surface slug, derived from the loader's descriptor (see THE ID RULE).
+function surfaceSlug(ws) {
+  if (ws.apexRoot) return 'landing';
+  return String(ws.host || '').replace(/\.$/, '').toLowerCase();
+}
+
+// Where a surface answers, as a portable address template. {apex} is the
+// instance's own domain; the inventory never bakes one in.
+function surfaceOrigin(ws) {
+  return ws.apexRoot ? 'https://{apex}' : `https://${ws.host}{apex}`;
+}
+
+// The live path a page file is served at. Every surface resolves a bare slug to
+// <slug>.html (the hall's buildersHtmlName, express.static extensions:['html'] on
+// status, the landing routes), and index.html answers the root.
+function pagePath(base) {
+  return base === 'index' ? '/' : `/${base}`;
+}
+
+// Read the facts a page declares about itself, from its markup alone.
+function readPageMarkup(source) {
+  const body = source.match(/<body\b([^>]*)>/i);
+  const attrs = body ? body[1] : '';
+  const attr = (name) => {
+    const m = attrs.match(new RegExp(`(?:^|\\s)${name}\\s*=\\s*"([^"]*)"`, 'i'));
+    return m ? decodeEntities(m[1]).trim() : null;
+  };
+  const title = source.match(/<title>([^<]*)<\/title>/i);
+  return {
+    dataPage: attr('data-page'),
+    dataPageTitle: attr('data-page-title'),
+    documentTitle: title ? decodeEntities(title[1]).replace(/\s+/g, ' ').trim() : null,
+  };
+}
+
+// The local stylesheets and scripts a page pulls in, as repo-relative paths, in
+// document order. A reference is resolved against the surface dir first, then with
+// its first segment dropped (the hall addresses its assets as /builders/<file>),
+// then against the repo (/modules/<key>/public/<file>, the loader's module-asset
+// URL). Anything that does not resolve to a file on disk — a CDN, a font host, a
+// data: URI — is not a file that renders the page here, and is left out.
+function localAssets(source, surfaceDirAbs, { root = REPO_ROOT, fsImpl = fs } = {}) {
+  const refs = [];
+  const re = /<script\b[^>]*\bsrc\s*=\s*"([^"]+)"|<link\b[^>]*\brel\s*=\s*"stylesheet"[^>]*\bhref\s*=\s*"([^"]+)"|<link\b[^>]*\bhref\s*=\s*"([^"]+)"[^>]*\brel\s*=\s*"stylesheet"/gi;
+  let m;
+  while ((m = re.exec(source)) !== null) refs.push(m[1] || m[2] || m[3]);
+  const out = [];
+  for (const raw of refs) {
+    if (/^(?:[a-z]+:)?\/\//i.test(raw) || /^data:/i.test(raw)) continue;
+    const clean = raw.split(/[?#]/)[0];
+    if (!clean) continue;
+    const rel = clean.replace(/^\/+/, '');
+    const candidates = [
+      path.join(surfaceDirAbs, rel),
+      path.join(surfaceDirAbs, rel.split('/').slice(1).join('/')),
+      path.join(root, rel),
+    ];
+    const hit = candidates.find((c) => {
+      try { return fsImpl.statSync(c).isFile(); } catch { return false; }
+    });
+    if (!hit) continue;
+    const repoRel = toPosix(path.relative(root, hit));
+    if (!out.includes(repoRel)) out.push(repoRel);
+  }
+  return out;
+}
+
+// The .states.json sidecars for a page (the ui-design kit's convention:
+// <dir>/<page>.states.json). A VARIANT file <base>-<variant>.states.json belongs to
+// the page too — the landing's projects page keeps three — unless
+// <base>-<variant>.html is itself a page, in which case it is that page's own.
+function statesFor(base, names, surfaceDirAbs, surfaceRel) {
+  const pages = new Set(names.filter((n) => n.endsWith('.html')).map((n) => n.slice(0, -5)));
+  const files = names.filter((n) => n.endsWith('.states.json')).map((n) => n.slice(0, -'.states.json'.length))
+    .filter((stem) => {
+      if (stem === base) return true;
+      if (!stem.startsWith(`${base}-`)) return false;
+      if (pages.has(stem)) return false;
+      // The LONGEST page base that prefixes the stem owns it (a-b-c.states.json is
+      // a-b's, not a's, when a-b.html exists).
+      const owner = [...pages].filter((p) => stem === p || stem.startsWith(`${p}-`)).sort((x, y) => y.length - x.length)[0];
+      return owner === base;
+    })
+    .sort((a, b) => (a === base ? -1 : b === base ? 1 : cmp(a, b)));
+  return files.map((stem) => {
+    const abs = path.join(surfaceDirAbs, `${stem}.states.json`);
+    let parsed = null;
+    try { parsed = JSON.parse(fs.readFileSync(abs, 'utf8')); } catch (e) {
+      throw new Error(`page-inventory: ${surfaceRel}/${stem}.states.json is not valid JSON (${e.message})`);
+    }
+    const states = parsed && parsed.states && typeof parsed.states === 'object' ? Object.keys(parsed.states) : [];
+    return { file: `${surfaceRel}/${stem}.states.json`, page: typeof parsed.page === 'string' ? parsed.page : null, states };
+  });
+}
+
+// The enabled web surfaces, from the loader. Injected in tests.
+function enabledSurfaces() {
+  const { moduleWebSurfaces } = require('../../src/module-loader/loader');
+  const { isModuleEnabled } = require('../../src/modules');
+  return moduleWebSurfaces({ isEnabled: isModuleEnabled });
+}
+
+function buildInventory({ surfaces = enabledSurfaces(), root = REPO_ROOT } = {}) {
+  const errors = [];
+  const pages = [];
+  const surfaceRows = [];
+  const seen = new Map();
+  const described = surfaces.map((ws) => ({ ws, slug: surfaceSlug(ws) }))
+    .sort((a, b) => cmp(a.slug, b.slug) || cmp(a.ws.key, b.ws.key));
+  const slugOwner = new Map();
+  for (const { ws, slug } of described) {
+    const surfaceRel = toPosix(path.relative(root, ws.dir));
+    if (!SLUG.test(slug)) { errors.push(`surface "${ws.key}" (${surfaceRel}) derives the id prefix "${slug}", which is not [a-z0-9-]`); continue; }
+    if (slugOwner.has(slug)) { errors.push(`surfaces "${slugOwner.get(slug)}" and "${ws.key}" both derive the id prefix "${slug}"`); continue; }
+    slugOwner.set(slug, ws.key);
+    const names = fs.readdirSync(ws.dir).sort(cmp);
+    const htmls = names.filter((n) => n.endsWith('.html'));
+    let count = 0;
+    for (const name of htmls) {
+      const base = name.slice(0, -5);
+      const rel = `${surfaceRel}/${name}`;
+      const source = fs.readFileSync(path.join(ws.dir, name), 'utf8');
+      const markup = readPageMarkup(source);
+      const pageSlug = markup.dataPage || base;
+      const id = `${slug}:${pageSlug}`;
+      if (!SLUG.test(pageSlug)) { errors.push(`${rel}: page "${pageSlug}" is not [a-z0-9-] (from ${markup.dataPage ? 'body[data-page]' : 'the file name'})`); continue; }
+      if (seen.has(id)) { errors.push(`${rel} and ${seen.get(id)} both claim the page id "${id}"`); continue; }
+      seen.set(id, rel);
+      const states = statesFor(base, names, ws.dir, surfaceRel);
+      pages.push({
+        id,
+        surface: slug,
+        module: ws.key,
+        page: pageSlug,
+        id_from: markup.dataPage ? 'data-page' : 'file-name',
+        title: markup.dataPageTitle || markup.documentTitle || pageSlug,
+        document_title: markup.documentTitle,
+        path: pagePath(base),
+        url: `${surfaceOrigin(ws)}${pagePath(base)}`,
+        files: [rel, ...localAssets(source, ws.dir, { root })],
+        states_files: states.map((s) => s.file),
+        states: states.flatMap((s) => s.states),
+      });
+      count += 1;
+    }
+    // A scan breaks by quietly finding nothing, and an empty surface would read as
+    // a clean --check. Every surface the loader returns ships a directory it serves
+    // pages from, so zero pages there is a scan defect, not a quiet surface.
+    if (count === 0 && htmls.length === 0) errors.push(`surface "${ws.key}" (${surfaceRel}) has no .html pages — a web surface with nothing to serve is a scan defect`);
+    surfaceRows.push({
+      id: slug, module: ws.key, at: surfaceRel,
+      answers_at: ws.apexRoot ? 'apex root' : `host prefix ${ws.host}`,
+      origin: surfaceOrigin(ws), pages: count,
+    });
+  }
+  if (errors.length) {
+    const err = new Error(`page-inventory: ${errors.length} page id problem(s):\n  - ${errors.join('\n  - ')}`);
+    err.problems = errors;
+    throw err;
+  }
+  pages.sort((a, b) => cmp(a.id, b.id));
+  return {
+    schema: 1,
+    generator: 'scripts/gds/page-inventory.js',
+    task: 1004314,
+    id_rule: ID_RULE,
+    counts: {
+      pages: pages.length,
+      surfaces: surfaceRows.length,
+      with_states: pages.filter((p) => p.states_files.length).length,
+      states: pages.reduce((n, p) => n + p.states.length, 0),
+    },
+    surfaces: surfaceRows,
+    pages,
+  };
+}
+
+function renderReport(inv) {
+  const L = [];
+  const esc = (s) => String(s == null ? '' : s).replace(/\|/g, '\\|');
+  L.push('# Page inventory — every page of every surface, with its stable id');
+  L.push('');
+  L.push('> **Generated** by `node scripts/gds/page-inventory.js` (BV2.TW02, task 1004314) from the web surfaces of the modules this instance has enabled.');
+  L.push('> Deterministic on a given tree — regenerate and commit rather than hand-editing. Machine-readable twin: [`page-inventory.json`](page-inventory.json).');
+  L.push('');
+  L.push('## The id rule');
+  L.push('');
+  for (const r of inv.id_rule) L.push(`- ${r}`);
+  L.push('');
+  L.push(`**${inv.counts.pages} pages** across ${inv.counts.surfaces} surfaces · ${inv.counts.with_states} with a states file · ${inv.counts.states} states in all.`);
+  L.push('');
+  L.push('## Surfaces');
+  L.push('');
+  L.push('| surface | module | lives at | answers at | pages |');
+  L.push('|---|---|---|---|---|');
+  for (const s of inv.surfaces) L.push(`| \`${s.id}\` | \`${s.module}\` | \`${s.at}\` | ${esc(s.answers_at)} | ${s.pages} |`);
+  L.push('');
+  for (const s of inv.surfaces) {
+    const rows = inv.pages.filter((p) => p.surface === s.id);
+    L.push(`## \`${s.id}\` — ${rows.length} pages`);
+    L.push('');
+    L.push('| id | title | url | files | states |');
+    L.push('|---|---|---|---|---|');
+    for (const p of rows) {
+      L.push(`| \`${p.id}\` | ${esc(p.title)} | \`${esc(p.url)}\` | ${p.files.length} | ${p.states.length ? esc(p.states.join(', ')) : '—'} |`);
+    }
+    L.push('');
+  }
+  L.push('---');
+  L.push('');
+  L.push('`{apex}` is the instance\'s own domain, and a title may still carry a `{{token}}` the server fills from the branding pack. The page files column counts the html plus the local stylesheets and scripts it loads; the JSON lists them.');
+  L.push('');
+  return L.join('\n');
+}
+
+// A missing file is stale by definition (sameContent would coerce null to '').
+function matchesGenerated(have, want) {
+  if (have === null || have === undefined) return false;
+  return sameContent(have, want);
+}
+
+function write({ check = false, build = buildInventory } = {}) {
+  const inv = build();
+  const json = `${JSON.stringify(inv, null, 2)}\n`;
+  const md = renderReport(inv);
+  const targets = [[path.join(REPO_ROOT, INVENTORY_REL), json], [path.join(REPO_ROOT, REPORT_REL), md]];
+  if (check) {
+    const stale = [];
+    for (const [p, want] of targets) {
+      const have = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+      if (!matchesGenerated(have, want)) stale.push(toPosix(path.relative(REPO_ROOT, p)));
+    }
+    return { inv, stale };
+  }
+  for (const [p, content] of targets) fs.writeFileSync(p, content);
+  return { inv, written: [INVENTORY_REL, REPORT_REL] };
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  try {
+    if (args.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(buildInventory(), null, 2)}\n`);
+    } else if (args.includes('--check')) {
+      const { stale } = write({ check: true });
+      if (stale.length) {
+        console.error(`page-inventory: STALE — ${stale.join(', ')} do not match the tree. Run: node scripts/gds/page-inventory.js`);
+        process.exitCode = 1;
+      } else {
+        console.log('page-inventory: artifacts match the tree.');
+      }
+    } else {
+      const { inv, written } = write();
+      console.log(`page-inventory: ${inv.counts.pages} pages across ${inv.counts.surfaces} surfaces -> wrote ${written.join(', ')}`);
+    }
+  } catch (e) {
+    console.error(e.message);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  INVENTORY_REL, REPORT_REL, ID_RULE,
+  cmp, surfaceSlug, surfaceOrigin, pagePath, readPageMarkup, localAssets, statesFor,
+  enabledSurfaces, buildInventory, renderReport, matchesGenerated, write,
+};

package/scripts/gds/ship-check.js

@@ -34,6 +34,7 @@ const STEPS = [
   { 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: 'page-inventory', label: 'docs/page-inventory.json fresh (every page + its stable id)', argv: ['scripts/gds/page-inventory.js', '--check'], fix: 'node scripts/gds/page-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 },
   { key: 'skill-lint', label: 'SKILL.md frontmatter parses', argv: ['scripts/gds/skill-lint.js'], fix: 'fix the ✗ lines (description: >- block scalars)' },
   { key: 'render-fit', label: 'rendered text fit + sibling overlap on the pages this branch changed (advisory)', argv: ['scripts/gds/render-check.js'], fix: 'look at the shots it names; fix the element, or say in the ship notes why it is right', advisory: true, optional: true, skipWith: '--no-render', slow: 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.1054'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1055'; // 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/page_inventory.mjs

@@ -0,0 +1,166 @@
+// tests/page_inventory.mjs — the page inventory (BV2.TW02, task 1004314; the
+// Tweak Mode chain, goal 1000095).
+//
+// What these tests defend:
+//   1. COVERAGE. Every html page of every enabled web surface is listed — counted
+//      here from the tree independently of the generator, so a scanner that quietly
+//      finds less cannot pass.
+//   2. THE ID RULE. <surface>:<page>, where the page half is body[data-page] when
+//      declared and the file name otherwise. TW03–TW06 store these ids.
+//   3. DRIFT FAILS. --check reds on a stale artifact, on a duplicate id and on an
+//      empty surface — each by name.
+//   4. PORTABILITY. Surfaces come from the loader over the ENABLED modules, so a
+//      disabled module's pages are absent with no edit to the generator.
+//   5. DETERMINISM. The artifacts are committed; two runs give identical bytes.
+//
+// DB-free, network-free. Fixture surfaces are built in a fresh temp dir.
+// Run:  node --test tests/page_inventory.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { spawnSync } 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 inv = require(path.join(ROOT, 'scripts', 'gds', 'page-inventory.js'));
+const { moduleWebSurfaces } = require(path.join(ROOT, 'src', 'module-loader', 'loader.js'));
+const { isModuleEnabled } = require(path.join(ROOT, 'src', 'modules.js'));
+
+function fixtureRoot() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'page-inv-'));
+}
+function writeFiles(dir, files) {
+  for (const [name, body] of Object.entries(files)) {
+    const p = path.join(dir, name);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, body);
+  }
+}
+const page = ({ dataPage, dataTitle, title = 'T', head = '' } = {}) => `<!doctype html><html><head><title>${title}</title>${head}</head>`
+  + `<body${dataPage ? ` data-page="${dataPage}"` : ''}${dataTitle ? ` data-page-title="${dataTitle}"` : ''}><main>x</main></body></html>`;
+
+test('COVERAGE: every html page of every enabled web surface is listed, and the three surfaces are there', () => {
+  const surfaces = moduleWebSurfaces({ isEnabled: isModuleEnabled });
+  const built = inv.buildInventory();
+  // Counted from the tree here, not taken from the generator.
+  let expected = 0;
+  for (const s of surfaces) expected += fs.readdirSync(s.dir).filter((n) => n.endsWith('.html')).length;
+  assert.ok(expected > 0, 'the enabled surfaces ship pages — a zero here is a scan defect in the test');
+  assert.equal(built.pages.length, expected, 'one inventory row per html page');
+  const ids = new Set(built.surfaces.map((s) => s.id));
+  for (const want of ['builders', 'landing', 'status']) assert.ok(ids.has(want), `surface ${want} listed (have: ${[...ids].join(', ')})`);
+  for (const p of built.pages) {
+    assert.match(p.id, /^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*$/, p.id);
+    assert.ok(p.files.length >= 1 && p.files[0].endsWith('.html'), `${p.id} names its html first`);
+    for (const f of p.files) assert.ok(fs.existsSync(path.join(ROOT, f)), `${p.id}: ${f} exists`);
+    assert.ok(p.url.startsWith('https://') && p.url.includes('{apex}'), `${p.id}: a portable url, no baked-in domain`);
+  }
+});
+
+test('THE ID RULE: a hall page is builders:<body[data-page]>, landing and status are <surface>:<file name>', () => {
+  const built = inv.buildInventory();
+  const byFile = new Map(built.pages.map((p) => [p.files[0], p]));
+  const hall = path.join(ROOT, 'modules', 'hall-ui', 'public');
+  for (const name of fs.readdirSync(hall).filter((n) => n.endsWith('.html'))) {
+    const dataPage = fs.readFileSync(path.join(hall, name), 'utf8').match(/<body\b[^>]*\bdata-page="([^"]+)"/)[1];
+    const row = byFile.get(`modules/hall-ui/public/${name}`);
+    assert.ok(row, `${name} is listed`);
+    assert.equal(row.id, `builders:${dataPage}`);
+    assert.equal(row.id_from, 'data-page');
+  }
+  assert.equal(byFile.get('modules/hall-ui/public/index.html').path, '/', 'the index answers the root');
+  assert.equal(byFile.get('modules/hall-ui/public/studio.html').id, 'builders:studio');
+  assert.equal(byFile.get('modules/public-landing/public/index.html').id, 'landing:index');
+  assert.equal(byFile.get('modules/status-ui/public/explore.html').id, 'status:explore');
+  assert.equal(byFile.get('modules/status-ui/public/explore.html').url, 'https://status.{apex}/explore');
+  // The rule is written into the artifact itself.
+  assert.ok(built.id_rule.some((r) => r.includes('<surface>:<page>')));
+});
+
+test('STATES: a page carries its own .states.json and its <page>-<variant> files, never another page\'s', () => {
+  const root = fixtureRoot();
+  const dir = path.join(root, 'site');
+  writeFiles(dir, {
+    'a.html': page(), 'a-b.html': page(), 'c.html': page(),
+    'a.states.json': JSON.stringify({ page: '/a', states: { one: {}, two: {} } }),
+    'a-x.states.json': JSON.stringify({ page: '/a', states: { three: {} } }),
+    'a-b.states.json': JSON.stringify({ page: '/a-b', states: { own: {} } }),
+    'a-b-y.states.json': JSON.stringify({ page: '/a-b', states: { variant: {} } }),
+  });
+  const built = inv.buildInventory({ surfaces: [{ key: 'fx', host: 'fx.', dir }], root });
+  const get = (id) => built.pages.find((p) => p.id === id);
+  assert.deepEqual(get('fx:a').states, ['one', 'two', 'three']);
+  assert.deepEqual(get('fx:a').states_files, ['site/a.states.json', 'site/a-x.states.json']);
+  assert.deepEqual(get('fx:a-b').states, ['own', 'variant'], 'a-b-y belongs to a-b, the longest page prefix');
+  assert.deepEqual(get('fx:c').states, []);
+  assert.deepEqual(get('fx:c').states_files, []);
+});
+
+test('FILES: local stylesheets and scripts resolve (the hall\'s /builders/ prefix too); CDNs and data: URIs do not', () => {
+  const root = fixtureRoot();
+  const dir = path.join(root, 'site');
+  writeFiles(dir, {
+    'p.html': page({ head: '<link rel="stylesheet" href="/builders/style.css?v=1"><link rel="icon" href="data:x"><link rel="stylesheet" href="https://fonts.example/css">'
+      + '<script src="https://cdn.example/lib.js"></script><script src="/app.js"></script><script src="/app.js?v=2"></script><script src="/gone.js"></script>' }),
+    'style.css': '', 'app.js': '',
+  });
+  const built = inv.buildInventory({ surfaces: [{ key: 'fx', apexRoot: true, dir }], root });
+  assert.deepEqual(built.pages[0].files, ['site/p.html', 'site/style.css', 'site/app.js']);
+  assert.equal(built.pages[0].id, 'landing:p', 'the apex-root surface is "landing"');
+  assert.equal(built.pages[0].url, 'https://{apex}/p');
+});
+
+test('DRIFT FAILS: a duplicate id, a malformed id and an empty surface each fail by name', () => {
+  const root = fixtureRoot();
+  const dup = path.join(root, 'dup');
+  writeFiles(dup, { 'one.html': page({ dataPage: 'same' }), 'two.html': page({ dataPage: 'same' }) });
+  assert.throws(() => inv.buildInventory({ surfaces: [{ key: 'fx', host: 'fx.', dir: dup }], root }),
+    (e) => /dup\/two\.html and dup\/one\.html both claim the page id "fx:same"/.test(e.message));
+  const bad = path.join(root, 'bad');
+  writeFiles(bad, { 'x.html': page({ dataPage: 'Not A Slug' }) });
+  assert.throws(() => inv.buildInventory({ surfaces: [{ key: 'fx', host: 'fx.', dir: bad }], root }), /page "Not A Slug" is not \[a-z0-9-\]/);
+  const empty = path.join(root, 'empty');
+  fs.mkdirSync(empty);
+  assert.throws(() => inv.buildInventory({ surfaces: [{ key: 'fx', host: 'fx.', dir: empty }], root }), /surface "fx" \(empty\) has no \.html pages/);
+  const one = path.join(root, 'one');
+  writeFiles(one, { 'i.html': page() });
+  assert.throws(() => inv.buildInventory({ surfaces: [{ key: 'a', host: 'fx.', dir: one }, { key: 'b', host: 'fx.', dir: one }], root }),
+    /surfaces "a" and "b" both derive the id prefix "fx"/);
+});
+
+test('DRIFT FAILS: --check reports both artifacts stale when the tree says otherwise, and the committed pair is fresh', () => {
+  assert.deepEqual(inv.write({ check: true }).stale, [], 'the committed docs/page-inventory.{json,md} match this tree');
+  const real = inv.buildInventory();
+  const drifted = () => ({ ...real, pages: real.pages.map((p) => (p.id === 'builders:studio' ? { ...p, title: 'Studio, renamed' } : p)) });
+  assert.deepEqual(inv.write({ check: true, build: drifted }).stale, [inv.INVENTORY_REL, inv.REPORT_REL]);
+  assert.equal(inv.matchesGenerated(null, ''), false, 'a missing artifact is stale, never vacuously fresh');
+  assert.equal(inv.matchesGenerated('a\r\nb\n', 'a\nb\n'), true, 'CRLF checkouts are not drift');
+});
+
+test('DRIFT FAILS: the CLI --check exits 0 on this tree (the gate fitness.js and ship-check.js run)', () => {
+  const r = spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'gds', 'page-inventory.js'), '--check'], { cwd: ROOT, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  const fitness = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'fitness.js'), 'utf8');
+  const shipCheck = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship-check.js'), 'utf8');
+  assert.match(fitness, /'page-inventory\.js'\), '--check'\]/, 'fitness.js runs the --check');
+  assert.match(shipCheck, /'scripts\/gds\/page-inventory\.js', '--check'\]/, 'ship-check.js runs the --check');
+});
+
+test('PORTABILITY: a disabled module\'s surface and pages are absent, with no edit to the generator', () => {
+  const surfaces = moduleWebSurfaces({ isEnabled: (k) => isModuleEnabled(k) && k !== 'public-landing' });
+  const built = inv.buildInventory({ surfaces });
+  assert.ok(!built.surfaces.some((s) => s.id === 'landing'), 'no landing surface');
+  assert.ok(!built.pages.some((p) => p.surface === 'landing'), 'no landing pages');
+  assert.ok(built.pages.some((p) => p.surface === 'builders'), 'the rest stay');
+});
+
+test('DETERMINISM: two builds give identical bytes', () => {
+  const a = JSON.stringify(inv.buildInventory());
+  const b = JSON.stringify(inv.buildInventory());
+  assert.equal(a, b);
+  assert.equal(inv.renderReport(JSON.parse(a)), inv.renderReport(JSON.parse(b)));
+});