@bongos/core 1.24.56 → 1.24.57

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/bongos/package-core.js",
-  "core_version": "1.24.56",
-  "core_contract": "1.24.56",
-  "source_commit": "b301b90b209d27181527aad7387781baf8948fb5",
+  "core_version": "1.24.57",
+  "core_contract": "1.24.57",
+  "source_commit": "44d3648a8e5f49130f5b03eae054a58469a673b6",
   "source_ref": "HEAD",
-  "built_at": "2026-11-07T13:32:48.529Z",
+  "built_at": "2026-11-07T14:00:36.333Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 637,
     "agent_docs_stubbed": 32,
-    "functional_verbatim": 3894,
+    "functional_verbatim": 3899,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 4564,
-  "tree_sha256": "0a4b526c24767189ede807ca92148bfab49737f776fa48f3e1567a4ab76ea900",
+  "file_count": 4569,
+  "tree_sha256": "adb31b4e84d4eec610bda1bf4acabaea7bec731c264105eea81c5fbeb9a20728",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -3002,7 +3002,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "6c9886c818c06b89e72464ca0c30c74f8f228c5dbbdd73f9b21b8d12df73aaaa"
+      "sha256": "780027478174931510aba4ef73db541e20a10227b036f5edff87c43b3d2f47f6"
     },
     {
       "path": "docs/modules-contract.md",
@@ -11892,12 +11892,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "211020df9c415bec7b3202e2e2adf83e1156421747acb7d50d5146481b82f7bb"
+      "sha256": "37727eb36eab08c102913443e700669b003d0df27b2f9fcc092812ad49f63d65"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "a6d5ee484135d66f225d0b135d82ea3369743fa50d208601ef0851ecb8cb96f3"
+      "sha256": "62583c855b89326986ebc92dbc8c8747539c95544cdc1520156db7be2b42674a"
     },
     {
       "path": "public-docs/index.html",
@@ -11917,7 +11917,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "432bafc0cee051c7358d2a75e2f806549fb2cb3d24b9144e1f55aa301029fadf"
+      "sha256": "32c9fa02b48190ec780fcb6b24fca04cbb96a1d31c48256dface2f8d9c57ab22"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -12254,6 +12254,11 @@
       "mode": "0000644",
       "sha256": "d9d2e908d8c254ca62e497ebc403ddc7afb27558dfa3dcc317af1c2e29ca87a1"
     },
+    {
+      "path": "scripts/bongos/css-literal-scan.js",
+      "mode": "0000644",
+      "sha256": "8da46806402a840192f29f93d98afd6b5018715f6fd4ce6fbe060e23ffc977de"
+    },
     {
       "path": "scripts/bongos/cutover-codemod.js",
       "mode": "0000644",
@@ -12284,6 +12289,11 @@
       "mode": "0000755",
       "sha256": "3de9084b1c059adf6a28734dc65a1d2823a6b6efcfd5ef18faa9e38679137893"
     },
+    {
+      "path": "scripts/bongos/design-generators-fresh.js",
+      "mode": "0000644",
+      "sha256": "f417e0ffcc884b018748a7f17062f52a6f247b8364ea4471efc97dd476143db3"
+    },
     {
       "path": "scripts/bongos/design-sync.js",
       "mode": "0000644",
@@ -12442,12 +12452,12 @@
     {
       "path": "scripts/bongos/fitness-ratchets.js",
       "mode": "0000644",
-      "sha256": "29c8c99a1380a0df741338feef8cc0465e22b12c45ba7655584a6a24e48987ac"
+      "sha256": "be9e886a0fc9b2473c01667930cb6854b84d2b493a974ccb1682ae1c7f74c150"
     },
     {
       "path": "scripts/bongos/fitness.js",
       "mode": "0000644",
-      "sha256": "a29dbf55477243b0de3112c66802e05a8558b5a01a10f6012dce6e6f5e0877a4"
+      "sha256": "a23aac093727185157bb3b6fafae5f33258a2b73a0f63969754dc6326b8952e2"
     },
     {
       "path": "scripts/bongos/forwarder.js",
@@ -13934,6 +13944,11 @@
       "mode": "0000644",
       "sha256": "a56ec4614506eb7601aa097b04c74ed4ac1593f422c41936a2bce0f890c501e4"
     },
+    {
+      "path": "scripts/gds/css-literal-scan.js",
+      "mode": "0000644",
+      "sha256": "8ec8b350129f2f5084722331d92e15ceec1902868681d88c639fc1991c388749"
+    },
     {
       "path": "scripts/gds/cutover-codemod.js",
       "mode": "0000644",
@@ -13964,6 +13979,11 @@
       "mode": "0000755",
       "sha256": "d72b0c536684c020934095172288b44341a22af833073c0ff53b7205dc8e6c67"
     },
+    {
+      "path": "scripts/gds/design-generators-fresh.js",
+      "mode": "0000644",
+      "sha256": "c2a29ede8cc98a51321b1bf5ff0867cf6f9d83184631cbd15edbac05cc88d5a1"
+    },
     {
       "path": "scripts/gds/design-sync.js",
       "mode": "0000644",
@@ -15507,7 +15527,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "d6105d4513257ed6895937bae4e3d8d3ca22f37763ad0361871de575c5a44ba6"
+      "sha256": "d9116cce5cc12918469c44c99a721da789c54b011c2d461e2b2a662aa53e42fc"
     },
     {
       "path": "src/bongos/module-store.js",
@@ -15852,7 +15872,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "e0299fc4bd1f20a6e57b3e7447211ce655a8e645578e792bd816ddb39124a366"
+      "sha256": "8995b2b62fbd8e2b5104180a8deb25dd69963c37d66c1b27ceb41adf3c4a3d31"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -17379,6 +17399,11 @@
       "mode": "0000644",
       "sha256": "7a492f806c867e71e52a9d90b3c0b30d47327c83d95e989ad09377c958457dd5"
     },
+    {
+      "path": "tests/design_counts_ratchet.mjs",
+      "mode": "0000644",
+      "sha256": "99d6c3b98b6ec839fe4b4856ab081bc6b19e96a39b4db4be0c155eb2e09e4ed0"
+    },
     {
       "path": "tests/design_reference.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -3366,5 +3366,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.24.54 with no explicit bump. run 42375689581. (task 1002620)
   1.24.56 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.24.55 with no explicit bump. run 42377334765. (task 1002620)
+  1.24.57 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.24.56 with no explicit bump. run 42379442367. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

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

@@ -11307,5 +11307,11 @@
       "id": "1005087",
       "text": "The Studio, the thinking sky, the tweak editor, the city, approvals, the atlas and the welcome screen now take their colours and fonts from the project's own branding, so a re-branded project sees them in its own colours; the"
     }
+  ],
+  "1.24.57": [
+    {
+      "id": "1005093",
+      "text": "Stylesheets can no longer gain new typed-in colours, text sizes, corners, shadows or breakpoints without the build failing, and the public design reference must be regenerated whenever its sources change."
+    }
   ]
 }

package/scripts/bongos/css-literal-scan.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+'use strict';
+// css-literal-scan.js — the detector behind the per-stylesheet DESIGN COUNTS
+// ratchet in fitness-ratchets.js (task 1005093, goal 1000138 "one Cloud Bongos
+// design system"; DESIGN.md, the Fifteen Rule and the --ds-* scales).
+//
+// WHAT IT COUNTS, per tracked stylesheet, in five kinds:
+//   colours     — every typed-in colour: a hex (#abc, #aabbcc, #aabbccdd) or a
+//                 colour function (rgb/rgba/hsl/hsla/hwb/lab/lch/oklab/oklch).
+//                 Counted per OCCURRENCE. The one literal the Fifteen Rule allows
+//                 — black or white with alpha as a scrim/shadow/halo
+//                 (rgba(0,0,0,.4), rgb(255 255 255 / .2)) — is not counted.
+//                 Named colours (red, white…) are not detected.
+//   font_sizes  — font-size / font declarations whose value carries a typed-in
+//                 non-zero length (px, rem, em, pt, %, vw…) instead of a token.
+//   radii       — *-radius declarations with a typed-in non-zero length.
+//   shadows     — box-shadow / text-shadow declarations that are not none/inherit
+//                 and carry a typed-in length or colour.
+//   breakpoints — @media / @container rules with a typed-in length (a custom
+//                 property cannot be used in a media query, so these never become
+//                 tokens; the count stops the set of breakpoints sprawling).
+// Sizes, radii, shadows and breakpoints are counted per DECLARATION / RULE.
+//
+// WHAT IT DOES NOT COUNT. A custom-property declaration (`--x: #123`) is a token
+// DEFINITION — tokens.css and the hall's token block are exactly where literals
+// belong — so its value is skipped. Page-private palettes are guarded separately
+// (tests/hall_private_palettes.mjs). Custom-property NAMES are removed from a
+// value before it is read (so --ds-space-12 is not a "12"), and url(...) bodies
+// are emptied (a data URI is not a colour). A literal inside a var() fallback
+// DOES count: a fallback is a typed-in value.
+//
+// Scope: every tracked *.css outside docs/ (the design mocks there are not
+// served), node_modules and vendor/.
+//
+// Print the counts:  node scripts/bongos/css-literal-scan.js [--all]
+
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const KINDS = ['colours', 'font_sizes', 'radii', 'shadows', 'breakpoints'];
+
+const EXCLUDE_RE = /^docs\/|(^|\/)(node_modules|vendor)\//;
+const COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+const URL_RE = /url\(\s*(?:"[^"]*"|'[^']*'|[^)]*)\)/gi;
+const VAR_NAME_RE = /--[\w-]+/g;
+// A declaration: a property, a colon, and a value that ends at ; or } (a selector
+// such as `a:hover {` ends at `{`, so it never matches).
+const DECL_RE = /(?:^|[{;\s])(-?-?[a-zA-Z][\w-]*)\s*:\s*([^;{}]+)(?=[;}])/g;
+const AT_RULE_RE = /@(media|container)\b([^{;]*)\{/g;
+const HEX_RE = /#[0-9a-fA-F]{3,8}(?![\w-])/g;
+const COLOUR_FN_RE = /(?<![\w-])(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch)\(([^()]*)\)/gi;
+const LENGTH_RE = /(?<![\w.#-])(\d*\.?\d+)(px|rem|em|pt|vw|vh|vmin|vmax|ch|ex|%)(?![\w%])/g;
+const MEDIA_LENGTH_RE = /(?<![\w.-])\d*\.?\d+(px|em|rem)(?![\w])/;
+const NO_SHADOW_RE = /^\s*(none|inherit|initial|unset|revert)\s*(!important)?\s*$/i;
+
+/** True for black or white with alpha — the Fifteen Rule's one allowed literal. */
+function isScrim(args) {
+  const parts = args.split(/[\s,/]+/).filter(Boolean);
+  if (parts.length !== 4) return false;
+  const rgb = parts.slice(0, 3).map((p) => p.toLowerCase());
+  const black = rgb.every((p) => p === '0' || p === '0%');
+  const white = rgb.every((p) => p === '255' || p === '100%');
+  return black || white;
+}
+
+function colourCount(value) {
+  let n = (value.match(HEX_RE) || []).length;
+  COLOUR_FN_RE.lastIndex = 0;
+  let m;
+  while ((m = COLOUR_FN_RE.exec(value))) {
+    const fn = m[0].slice(0, m[0].indexOf('(')).toLowerCase();
+    if ((fn === 'rgb' || fn === 'rgba') && isScrim(m[1])) continue;
+    n += 1;
+  }
+  return n;
+}
+
+function hasLength(value) {
+  LENGTH_RE.lastIndex = 0;
+  let m;
+  while ((m = LENGTH_RE.exec(value))) if (Number(m[1]) !== 0) return true;
+  return false;
+}
+
+/** The five counts for one stylesheet's text. */
+function countSheet(text) {
+  const counts = Object.fromEntries(KINDS.map((k) => [k, 0]));
+  const css = String(text).replace(COMMENT_RE, ' ').replace(URL_RE, 'url()');
+  AT_RULE_RE.lastIndex = 0;
+  let m;
+  while ((m = AT_RULE_RE.exec(css))) if (MEDIA_LENGTH_RE.test(m[2])) counts.breakpoints += 1;
+  DECL_RE.lastIndex = 0;
+  while ((m = DECL_RE.exec(css))) {
+    const prop = m[1].toLowerCase();
+    if (prop.startsWith('--')) continue; // a token definition
+    const value = m[2].replace(VAR_NAME_RE, ' ');
+    counts.colours += colourCount(value);
+    if ((prop === 'font-size' || prop === 'font') && hasLength(value)) counts.font_sizes += 1;
+    else if (prop.endsWith('radius') && hasLength(value)) counts.radii += 1;
+    else if ((prop === 'box-shadow' || prop === 'text-shadow') && !NO_SHADOW_RE.test(value)
+      && (hasLength(value) || colourCount(value) > 0)) counts.shadows += 1;
+  }
+  return counts;
+}
+
+function trackedStylesheets(root = ROOT) {
+  const out = execFileSync('git', ['ls-files', '-z', '--', '*.css'], { cwd: root, encoding: 'utf8' });
+  return out.split('\0').filter((f) => f && !EXCLUDE_RE.test(f)).sort();
+}
+
+/**
+ * Counts for every tracked stylesheet: { sheets: { [path]: counts }, scanned }.
+ * Sheets whose five counts are all zero are omitted (a missing sheet reads as zero).
+ */
+function scanCssLiterals({ root = ROOT, files = null, read = null } = {}) {
+  const list = files || trackedStylesheets(root);
+  const reader = read || ((f) => fs.readFileSync(path.join(root, f), 'utf8'));
+  const sheets = {};
+  let scanned = 0;
+  for (const f of list) {
+    let text;
+    try { text = reader(f); } catch { continue; }
+    scanned += 1;
+    const c = countSheet(text);
+    if (KINDS.some((k) => c[k] > 0)) sheets[f] = c;
+  }
+  return { sheets, scanned };
+}
+
+if (require.main === module) {
+  const { sheets, scanned } = scanCssLiterals();
+  const totals = Object.fromEntries(KINDS.map((k) => [k, 0]));
+  for (const [f, c] of Object.entries(sheets)) {
+    for (const k of KINDS) totals[k] += c[k];
+    if (process.argv.includes('--all') || KINDS.some((k) => c[k] > 0)) {
+      process.stdout.write(`${f}  ${KINDS.map((k) => `${k}=${c[k]}`).join(' ')}\n`);
+    }
+  }
+  process.stdout.write(`\n${scanned} stylesheet(s) scanned · totals ${KINDS.map((k) => `${k}=${totals[k]}`).join(' ')}\n`);
+}
+
+module.exports = { scanCssLiterals, countSheet, KINDS };

package/scripts/bongos/design-generators-fresh.js

@@ -0,0 +1,32 @@
+'use strict';
+// design-generators-fresh.js — the design system's generated files are fresh
+// (task 1005093, goal 1000138). Part of fitness.js's "generated artifacts fresh"
+// check; kept in its own file because fitness.js sits at the 1,500-line budget.
+//
+// Both generated files read the shared token sheet (modules/ui-design/public/tokens.css) and the brand pack; the public
+// reference also reads the hall's sheets and DESIGN.md. A stylesheet edit without a
+// regeneration used to surface only as a failing unit test; this names it in fitness.
+// Skipped when the ui-design module is not in the checkout. `root` is injectable for
+// tests/design_counts_ratchet.mjs, which runs it against a copied tree.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { REPO_ROOT } = require('./fitness-lib.js');
+
+function checkDesignGeneratorsFresh(root = REPO_ROOT) {
+  const violations = [];
+  for (const [script, out, task] of [
+    ['gen-design-tokens.js', 'config/design-tokens.neutral.json', '1005082'],
+    ['gen-design-reference.js', 'modules/ui-design/public/brand.html (the public /brand page)', '1005083'],
+  ]) {
+    const gen = path.join(root, 'modules', 'ui-design', 'scripts', script);
+    if (!fs.existsSync(gen)) continue;
+    try { execFileSync(process.execPath, [gen, '--check'], { cwd: root, stdio: 'pipe' }); }
+    catch { violations.push(`${out} is STALE — a design source (the token sheet, the brand pack, a hall sheet or DESIGN.md) changed without a regeneration. Run \`node modules/ui-design/scripts/${script}\` and commit (task ${task}).`); }
+  }
+  return violations;
+}
+
+module.exports = { checkDesignGeneratorsFresh };

package/scripts/bongos/fitness-ratchets.js

@@ -27,6 +27,13 @@
 //     docs-entropy scanner's three counts, reused as a library
 //   source_text_only_tests — test files that only read source text and match
 //     its wording, never running the code (task 1004868)
+//   design counts — PER STYLESHEET, the typed-in colours, font sizes, radii,
+//     shadows and breakpoints (task 1005093, goal 1000138; detector:
+//     css-literal-scan.js). Kept in their own `design_counts` object rather than
+//     `metrics` — ~60 sheets × 5 kinds would drown the metric line — but with the
+//     same verdict: higher than baseline fails, lower nudges a ratchet-down. A
+//     sheet with no baseline row has a baseline of zero, so a NEW sheet starts on
+//     the --ds-* tokens.
 //
 // The knip dead-code ratchet needs node_modules + ~seconds, so it is NOT part
 // of the in-suite check: CI runs `node scripts/bongos/fitness-ratchets.js --knip`
@@ -535,6 +542,46 @@ function skillListingMetrics() {
   }
 }
 
+// ---------- design counts (task 1005093) ----------
+
+const DESIGN_HINT = ' — use a --ds-* scale token (modules/ui-design/public/tokens.css) or one of the fifteen colour '
+  + 'tokens instead of a typed-in value (DESIGN.md, the Fifteen Rule). Run '
+  + '`node scripts/bongos/css-literal-scan.js` to see every sheet\'s counts and the rule.';
+
+// Current per-sheet counts, or null when the scan found no stylesheet at all —
+// a collapsed enumeration is a scan defect, never a flattering all-zero tree.
+function designCounts() {
+  const { scanCssLiterals } = require('./css-literal-scan.js');
+  const { sheets, scanned } = scanCssLiterals();
+  if (!scanned) {
+    process.stderr.write('fitness-ratchets: design counts NOT MEASURED — the stylesheet scan enumerated ZERO files, which is a scan defect, not a clean tree\n');
+    return null;
+  }
+  return sheets;
+}
+
+// Pure verdict over { sheet: { kind: n } } maps. Keys starting with `_` are notes.
+function compareDesignCounts(current, baseline) {
+  const { KINDS } = require('./css-literal-scan.js');
+  const violations = [];
+  const warnings = [];
+  const sheets = new Set([...Object.keys(current || {}), ...Object.keys(baseline || {})].filter((k) => !k.startsWith('_')));
+  for (const sheet of [...sheets].sort()) {
+    const cur = (current || {})[sheet] || {};
+    const base = (baseline || {})[sheet] || {};
+    for (const kind of KINDS) {
+      const value = cur[kind] || 0;
+      const floor = base[kind] || 0;
+      if (value > floor) {
+        violations.push(`design count ${kind} in ${sheet} regressed: ${value} > baseline ${floor} — fix the regression; never raise the baseline to pass${DESIGN_HINT}`);
+      } else if (value < floor) {
+        warnings.push(`ratchet-down available: design count ${kind} in ${sheet} improved to ${value} (baseline ${floor}) — lower it in config/fitness-baselines.json design_counts`);
+      }
+    }
+  }
+  return { violations, warnings };
+}
+
 function computeMetrics({ withDocs = true } = {}) {
   const files = trackedJsFiles();
   const contents = new Map(files.map((f) => [f, readRepoFile(f)]));
@@ -560,15 +607,28 @@ function computeMetrics({ withDocs = true } = {}) {
 // computeMetrics() sweep — git ls-files plus every tracked .js plus the
 // docs-entropy scan, measured at 23.7s + 2.5s + 2.8s, i.e. ~29s of this file's
 // 29s runtime, which is what pushed it into the 90s timeout in the first place.
-function checkQualityRatchets({ baselinePath = BASELINE_PATH, metrics: injectedMetrics = null } = {}) {
+// `designCounts` (task 1005093) is injectable the same way; when a test injects
+// `metrics` alone, the stylesheet scan is skipped rather than run for real.
+function checkQualityRatchets({ baselinePath = BASELINE_PATH, metrics: injectedMetrics = null, designCounts: injectedDesign = null } = {}) {
   const metrics = injectedMetrics === null ? computeMetrics() : injectedMetrics;
-  const { metrics: baselines, error: baselineError } = readBaselines(baselinePath);
+  const { metrics: baselines, error: baselineError, parsed } = readBaselines(baselinePath);
   const { violations, warnings } = compareToBaselines(metrics, baselines);
+  const design = injectedDesign !== null ? injectedDesign : (injectedMetrics === null ? designCounts() : null);
+  if (design) {
+    const designBaseline = parsed && parsed.design_counts;
+    if (!baselineError && (!designBaseline || typeof designBaseline !== 'object')) {
+      violations.push('config/fitness-baselines.json has no "design_counts" object — the per-stylesheet design ratchet cannot verify anything, so it fails CLOSED. Bootstrap deliberately: node scripts/bongos/fitness-ratchets.js --update-baselines');
+    } else if (designBaseline) {
+      const d = compareDesignCounts(design, designBaseline);
+      violations.push(...d.violations);
+      warnings.push(...d.warnings);
+    }
+  }
   // task 1003227: an unreadable baseline file is a hard failure, not silence. Put it
   // FIRST so it is the headline rather than buried under per-metric noise.
   if (baselineError) violations.unshift(baselineError);
   return {
-    name: 'quality ratchets — size, duplication, cycles, console, doc entropy, legacy GDS literals, source-text-only tests only tighten (task 1003129)',
+    name: 'quality ratchets — size, duplication, cycles, console, doc entropy, legacy GDS literals, source-text-only tests, per-stylesheet design counts only tighten (task 1003129)',
     hardFail: violations.length > 0,
     violations,
     warnings,
@@ -598,6 +658,12 @@ function main() {
     // this file cannot be eaten by a refresh either.
     const preserved = existingFile && typeof existingFile === 'object' ? { ...existingFile } : {};
     delete preserved.metrics;
+    // design_counts is recomputed too (task 1005093), keeping its `_` notes.
+    const design = designCounts();
+    if (design) {
+      const notes = Object.fromEntries(Object.entries(preserved.design_counts || {}).filter(([k]) => k.startsWith('_')));
+      preserved.design_counts = { ...notes, ...design };
+    }
     if (!preserved._comment) {
       preserved._comment = 'fitness-ratchets baselines (task 1003129): quality debt recorded at gate-adoption. Shrink-only — lower a value when the metric improves; raising one to pass CI is out of policy.';
     }
@@ -647,6 +713,7 @@ module.exports = {
   readBaselines,
   computeMetrics,
   compareToBaselines,
+  compareDesignCounts,
   sourceTextTestMetrics,
   duplicateWindowCount,
   normalizeLines,

package/scripts/bongos/fitness.js

@@ -200,7 +200,7 @@ function checkNestedDocsPresent() {
 // here would false-fail every PR (the gitignored whole file is absent from a clean checkout, so it
 // always reads as "would change"); `--check-block` is the exact, non-noisy gate. (docs/file-map.md +
 // the OpenAPI docs are still fully committed and unchanged by ADR 0110 — they keep the plain --check.)
-function checkGeneratedArtifactsFresh() {
+function checkGeneratedArtifactsFresh({ designRoot = REPO_ROOT } = {}) { // designRoot: tests only (task 1005093)
   const violations = [];
   try {
     execFileSync(process.execPath, [path.join(__dirname, 'gen-repo-map.js'), '--check-block'], { cwd: REPO_ROOT, stdio: 'pipe' });
@@ -254,9 +254,10 @@ function checkGeneratedArtifactsFresh() {
   } 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/bongos/page-inventory.js` and commit (task 1004314).');
   }
+  violations.push(...require('./design-generators-fresh.js').checkDesignGeneratorsFresh(designRoot)); // task 1005093
   // 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, the API spec + typed client GENERATE from the routes (both gitignored, task 1004866), 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.' };
+  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, the API spec + typed client GENERATE from the routes (both gitignored, task 1004866), 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), and the design system config/design-tokens.neutral.json + public /brand reference (task 1005093). 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/css-literal-scan.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// scripts/gds/css-literal-scan.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/css-literal-scan.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'css-literal-scan.js');

package/scripts/gds/design-generators-fresh.js

@@ -0,0 +1,6 @@
+// scripts/gds/design-generators-fresh.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/design-generators-fresh.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'design-generators-fresh.js');

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

@@ -473,7 +473,7 @@ const MODULE_GLOBS = {
     'scripts/bongos/adr-namespace.js', 'scripts/bongos/baseline-staleness.js',
     'scripts/bongos/category-advisory-guard.js', 'scripts/bongos/client-baseurl-guard.js',
     'scripts/bongos/doc-cli-guard.js', 'scripts/bongos/doc-control-claims.js', 'scripts/bongos/doc-comment-coverage.js',
-    'scripts/bongos/exec-path-guard.js', 'scripts/bongos/fitness-lib.js',
+    'scripts/bongos/exec-path-guard.js', 'scripts/bongos/fitness-lib.js', 'scripts/bongos/design-generators-fresh.js',
     'scripts/bongos/fitness-checks-error-envelope.js', 'scripts/bongos/fitness-checks-identity.js',
     'scripts/bongos/fitness-checks-packaging.js', 'scripts/bongos/fitness-checks-route-pins.js',
     'scripts/bongos/fitness-checks-vocabulary.js', 'scripts/bongos/fitness-checks-write-validation.js',

package/src/module-api.js

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

package/tests/design_counts_ratchet.mjs

@@ -0,0 +1,134 @@
+// tests/design_counts_ratchet.mjs — design counts that can only go down, and the
+// design generators wired into the fitness freshness gate (task 1005093, goal 1000138).
+//
+// Done when: adding a new hard-coded font-size to a hall sheet fails fitness, and
+// editing the shared token sheet without regenerating fails the freshness gate.
+// Both are proved here on the real tree: the first by scanning the real sheets with
+// one extra declaration, the second by running the gate on a copied tree.
+//
+// Run:  node --test tests/design_counts_ratchet.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const scan = require(path.join(ROOT, 'scripts', 'bongos', 'css-literal-scan.js'));
+const ratchets = require(path.join(ROOT, 'scripts', 'bongos', 'fitness-ratchets.js'));
+const fitness = require(path.join(ROOT, 'scripts', 'bongos', 'fitness.js'));
+const { checkDesignGeneratorsFresh } = require(path.join(ROOT, 'scripts', 'bongos', 'design-generators-fresh.js'));
+
+const HALL_SHEET = 'modules/hall-ui/public/style.css';
+const readReal = (f) => fs.readFileSync(path.join(ROOT, f), 'utf8');
+
+test('the detector counts typed-in values and leaves tokens alone', () => {
+  const c = scan.countSheet(`
+    :root { --ds-x: 14px; --tone: #123456; }            /* token definitions: not counted */
+    .a { font-size: 13px; border-radius: 6px; color: #abc; }
+    .b { font-size: var(--ds-text-sm); border-radius: var(--ds-radius-tile); color: var(--ink); }
+    .c { box-shadow: 0 2px 4px rgba(0, 0, 0, .2); }      /* a shadow; the black scrim is allowed */
+    .d { box-shadow: none; background: url("data:image/svg+xml;fill='#fff'"); }
+    .e { background: color-mix(in srgb, var(--ink) 40%, rgb(12 34 56)); padding: 0; }
+    @media (max-width: 720px) { .f { border-radius: 0; } }
+    @media (prefers-reduced-motion: reduce) { .g { transition: none; } }
+  `);
+  assert.deepEqual(c, { colours: 2, font_sizes: 1, radii: 1, shadows: 1, breakpoints: 1 });
+});
+
+test('a selector with a colon is not read as a declaration', () => {
+  assert.equal(scan.countSheet('a:hover, b:focus-visible { color: var(--ink); }').colours, 0);
+});
+
+test('the real tree matches its committed design-count baselines', () => {
+  const { sheets, scanned } = scan.scanCssLiterals();
+  assert.ok(scanned > 40, `the scan should see the live stylesheets (saw ${scanned})`);
+  const r = ratchets.checkQualityRatchets({ metrics: {}, designCounts: sheets });
+  assert.deepEqual(r.violations, [], 'design counts regressed against config/fitness-baselines.json');
+});
+
+test('a NEW hard-coded font-size in a hall sheet fails fitness', () => {
+  const { sheets } = scan.scanCssLiterals({
+    read: (f) => readReal(f) + (f === HALL_SHEET ? '\n.planted { font-size: 13px; }\n' : ''),
+  });
+  const r = ratchets.checkQualityRatchets({ metrics: {}, designCounts: sheets });
+  assert.equal(r.hardFail, true);
+  assert.ok(r.violations.some((v) => v.includes(`font_sizes in ${HALL_SHEET} regressed`)), r.violations.join('\n'));
+});
+
+test('a new sheet starts at zero: any typed-in colour in it fails', () => {
+  const d = ratchets.compareDesignCounts({ 'modules/x/public/new.css': { colours: 1 } }, { _comment: 'note' });
+  assert.equal(d.violations.length, 1);
+  assert.match(d.violations[0], /colours in modules\/x\/public\/new\.css regressed: 1 > baseline 0/);
+});
+
+test('a lower count nudges a ratchet-down and does not fail', () => {
+  const d = ratchets.compareDesignCounts({ 'a.css': { radii: 2 } }, { 'a.css': { radii: 3 } });
+  assert.deepEqual(d.violations, []);
+  assert.match(d.warnings[0], /ratchet-down available: design count radii in a\.css improved to 2/);
+});
+
+test('a baseline file with no design_counts fails closed', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-counts-'));
+  const file = path.join(dir, 'baselines.json');
+  fs.writeFileSync(file, JSON.stringify({ metrics: {} }));
+  try {
+    const r = ratchets.checkQualityRatchets({ baselinePath: file, metrics: {}, designCounts: {} });
+    assert.equal(r.hardFail, true);
+    assert.match(r.violations[0], /no "design_counts" object/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// The generators resolve their sources from their own location, so a copy of the
+// files they read is a complete, isolated tree the gate can run against.
+const GENERATOR_SOURCES = [
+  'config/branding.neutral.json',
+  'config/design-tokens.neutral.json',
+  'modules/ui-design/public/tokens.css',
+  'modules/ui-design/public/brand.html',
+  'modules/ui-design/public/brand',
+  'modules/ui-design/scripts/gen-design-tokens.js',
+  'modules/ui-design/scripts/gen-design-reference.js',
+  'modules/hall-ui/public/style.css',
+  'modules/hall-ui/public/controls.css',
+  'modules/hall-ui/public/dom-utils.js',
+  'scripts/bongos/gen-brand.js',
+  'DESIGN.md',
+];
+
+function copiedTree() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-fresh-'));
+  for (const rel of GENERATOR_SOURCES) {
+    fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
+    fs.cpSync(path.join(ROOT, rel), path.join(dir, rel), { recursive: true });
+  }
+  return dir;
+}
+
+test('the freshness gate passes on a fresh tree and fails when the token sheet changes without a regeneration', () => {
+  const dir = copiedTree();
+  try {
+    assert.deepEqual(checkDesignGeneratorsFresh(dir), [], 'the copied tree should start fresh');
+    const sheet = path.join(dir, 'modules/ui-design/public/tokens.css');
+    const before = fs.readFileSync(sheet, 'utf8');
+    const after = before.replace(/--ds-space-xs:\s*[^;]+;/, '--ds-space-xs: 11px;');
+    assert.notEqual(after, before, 'the token sheet should declare --ds-space-xs');
+    fs.writeFileSync(sheet, after);
+    const v = checkDesignGeneratorsFresh(dir);
+    assert.ok(v.some((x) => x.startsWith('config/design-tokens.neutral.json is STALE')), v.join('\n'));
+    assert.ok(v.some((x) => x.startsWith('modules/ui-design/public/brand.html')), v.join('\n'));
+    // …and the registered fitness check carries that verdict, so the build goes red.
+    assert.ok(fitness.CHECKS.includes(fitness.checkGeneratedArtifactsFresh));
+    const gate = fitness.checkGeneratedArtifactsFresh({ designRoot: dir });
+    assert.equal(gate.hardFail, true);
+    assert.ok(gate.violations.some((x) => x.startsWith('config/design-tokens.neutral.json is STALE')), gate.violations.join('\n'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});