@bongos/core 1.19.394 → 1.19.395

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.394",
+  "version": "1.19.395",
   "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/copy-inventory.js

@@ -16,10 +16,12 @@
 // machine-readable registry and one human report. Same posture as gen-repo-map /
 // gen-api-docs: a command you run and commit.
 //
-// THE SURFACE MISMATCH, RECORDED RATHER THAN ASSUMED AWAY. docs/design-contract.md
-// says UI components live under `src/ui/<surface>/`, and that a surface directory is
-// the unit a design adapter targets. On this tree `src/ui/` contains only
-// `adapters/` — the real UI is modules/hall-ui/public and modules/status-ui/public.
+// THE SURFACE MISMATCH, RECORDED RATHER THAN ASSUMED AWAY. The design contract
+// (modules/ui-design/docs/design-contract.md) says UI components live under
+// `src/ui/<surface>/`, and that a surface directory is the unit a design adapter
+// targets. This tree has no `src/ui/` at all (the adapters moved to
+// modules/ui-design/adapters/ in task 1003324) — the real UI is modules/hall-ui/public
+// and modules/status-ui/public.
 // So this tool maps REAL paths onto contract-shaped surface ids and reports the
 // mismatch in its own output. Do not "fix" that by pretending the contract layout
 // exists.
@@ -76,7 +78,7 @@ const BLIND_SPOTS = [
   'Template literals containing a nested backtick: the literal scanner stops at the first closing backtick, so a nested template inside `${...}` truncates that one literal. Rare in this tree and cheap to spot (a row that ends mid-sentence); a real JS parser is the fix if it ever matters.',
   'Runtime-composed strings: anything assembled from fragments or interpolated at render time is captured only as its literal parts. A sentence that exists only once the browser runs cannot be inventoried by reading the tree.',
   'Generated pages: `docs/api-reference.md` and the OpenAPI surface are generated from route prose; that copy belongs to its generator, not to a designer.',
-  'The design-contract surface layout: `docs/design-contract.md` expects `src/ui/<surface>/`, which this tree does not use (`src/ui` holds only `adapters/`). Surface ids here are a MAPPING onto real paths, not evidence the contract layout exists.',
+  'The design-contract surface layout: `modules/ui-design/docs/design-contract.md` expects `src/ui/<surface>/`, which this tree does not use (there is no `src/ui/`; the adapters live in `modules/ui-design/adapters/`). Surface ids here are a MAPPING onto real paths, not evidence the contract layout exists.',
 ];
 
 // A stable id survives the string MOVING: it hashes surface + normalized text,

package/scripts/gds/design-sync.js

@@ -1,62 +1,12 @@
 #!/usr/bin/env node
-// Build a Claude Design token-preview bundle from the repo's design system.
+'use strict';
+// design-sync.js — thin shim: the Claude Design sync CLI lives in the ui-design
+// module at modules/ui-design/scripts/design-sync.js (task 1003324, ADR 0197).
 //
-// Usage:
-//   node scripts/gds/design-sync.js           — build bundle, print manifest JSON
+// WHY a shim rather than re-pointing every caller: `node scripts/gds/<x>.js` is
+// the form the skills and recipes use, and the form claude-materialize rewrites to
+// `bongos exec scripts/gds/<x>.js` when the core installs as a package — so this
+// path stays the stable, documented entry point. Flags pass straight through:
+//   node scripts/gds/design-sync.js                 — build the token-preview bundle, print the manifest
 //   node scripts/gds/design-sync.js --surface <id>  — limit to one surface
-//
-// Output (stdout, JSON):
-//   { bundlePath, files, surfaceIds, summary }
-//
-// The /design-sync skill calls this, then uses the DesignSync MCP tool
-// to push the bundle to a Claude Design project.
-
-const path = require('node:path');
-const fs = require('node:fs');
-const { resolveInstanceRoot } = require(path.resolve(__dirname, '..', '..', 'src', 'instance-config'));
-
-// ADR 0108 §1: the design system (src/ui/, config/design-tokens.json) is host
-// content. resolveInstanceRoot() returns the repo root today, so this is
-// byte-identical for the live instance.
-const REPO_ROOT = resolveInstanceRoot();
-
-function arg(flag, args) {
-  const i = args.indexOf(flag);
-  return i !== -1 ? args[i + 1] : null;
-}
-
-(async () => {
-  const args = process.argv.slice(2);
-  const targetSurface = arg('--surface', args) || undefined;
-
-  const adapter = require(path.join(REPO_ROOT, 'src', 'ui', 'adapters', 'claude-design', 'index.js'));
-
-  const result = await adapter.import({
-    repoRoot: REPO_ROOT,
-    ...(targetSurface ? { surfaces: [{ id: targetSurface, path: path.join(REPO_ROOT, 'src', 'ui', targetSurface) }] } : {}),
-  });
-
-  // Build the file list from the bundle dir for the skill to pass to finalize_plan
-  const { bundlePath, surfaceIds, summary } = result;
-  const files = collectFiles(bundlePath, bundlePath);
-
-  const manifest = { bundlePath, files, surfaceIds, summary };
-  process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
-})().catch(err => {
-  process.stderr.write(`design-sync: ${err.message}\n`);
-  process.exit(1);
-});
-
-function collectFiles(dir, root) {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  const out = [];
-  for (const e of entries) {
-    const full = path.join(dir, e.name);
-    if (e.isDirectory()) {
-      out.push(...collectFiles(full, root));
-    } else {
-      out.push(path.relative(root, full));
-    }
-  }
-  return out;
-}
+require('../../modules/ui-design/scripts/design-sync.js');

package/scripts/gds/doc-cli-guard.js

@@ -196,20 +196,26 @@ const NAME = 'a doc that names a CLI matches the real CLI (G01)';
 // a false alarm that pushes the next agent toward silencing the rule via
 // DOC_CLI_ALLOW, which is exactly the outcome the rule exists to prevent.
 //
-// One level of same-directory relative requires is enough (it is where a carve
-// puts things) and keeps the read bounded. A missing sibling is skipped: the
-// point is to find the flag, not to prove the require graph.
+// One level of relative requires is enough and keeps the read bounded — either a
+// same-directory sibling (where a carve puts things), or the module-hosted CLI a
+// scripts/gds/ SHIM forwards to: task 1003324 moved the design CLIs into
+// modules/ui-design/scripts/ and left `require('../../modules/ui-design/…')`
+// shims behind, so the flag a doc names is parsed in the module file. Nothing
+// else is followed — a require into src/ is not a CLI phase. A missing target is
+// skipped: the point is to find the flag, not to prove the require graph.
+const MODULE_CLI_RE = /^modules[\\/][^\\/]+[\\/]/;
 function readCliSource(rel) {
   const src = readFileOrNull(rel);
   if (src === null) return null;
   const dir = path.dirname(rel);
   const seen = new Set([rel]);
   const parts = [src];
-  const RE = /require\(\s*['"](\.\/[^'"]+)['"]\s*\)/g;
+  const RE = /require\(\s*['"](\.\.?\/[^'"]+)['"]\s*\)/g;
   let m;
   while ((m = RE.exec(src))) {
     let sib = path.join(dir, m[1]);
     if (!sib.endsWith('.js')) sib += '.js';
+    if (path.dirname(sib) !== path.normalize(dir) && !MODULE_CLI_RE.test(sib)) continue; // normalize: join() flips separators on Windows
     if (seen.has(sib)) continue;
     seen.add(sib);
     const sibSrc = readFileOrNull(sib);
@@ -255,6 +261,6 @@ function main() {
 if (require.main === module) main();
 
 module.exports = {
-  checkDocNamesRealCli, scanDocs, trackedMarkdown, scriptMentionsFlag, stripLineComments,
+  checkDocNamesRealCli, scanDocs, trackedMarkdown, scriptMentionsFlag, stripLineComments, readCliSource,
   DOC_CLI_ALLOW, DOC_CLI_RE, DOC_FLAG_RE, UNIVERSAL_FLAGS,
 };

package/scripts/gds/figma-design-sync.js

@@ -1,61 +1,11 @@
 #!/usr/bin/env node
-// Build a Figma push plan from the repo's design system (task 2048, redo of 1379).
+'use strict';
+// figma-design-sync.js — thin shim: the Figma push-plan CLI lives in the ui-design
+// module at modules/ui-design/scripts/figma-design-sync.js (task 1003324, ADR 0197).
 //
-// Usage:
-//   node scripts/gds/figma-design-sync.js               — build plan, print manifest JSON
-//   node scripts/gds/figma-design-sync.js --surface <id> — limit to one surface
-//
-// Output (stdout, JSON):
-//   { planPath, files, surfaceIds, summary }
-//
-// The figma-design-sync skill calls this, then executes the plan's frames
-// against the live Figma MCP tool.
-
-const path = require('node:path');
-const fs = require('node:fs');
-const { resolveInstanceRoot } = require(path.resolve(__dirname, '..', '..', 'src', 'instance-config'));
-
-// ADR 0108 §1: the design system (src/ui/, config/design-tokens.json) is host
-// content. resolveInstanceRoot() returns the repo root today, so this is
-// byte-identical for the live instance.
-const REPO_ROOT = resolveInstanceRoot();
-
-function arg(flag, args) {
-  const i = args.indexOf(flag);
-  return i !== -1 ? args[i + 1] : null;
-}
-
-(async () => {
-  const args = process.argv.slice(2);
-  const targetSurface = arg('--surface', args) || undefined;
-
-  const adapter = require(path.join(REPO_ROOT, 'src', 'ui', 'adapters', 'figma', 'index.js'));
-
-  const result = await adapter.import({
-    repoRoot: REPO_ROOT,
-    ...(targetSurface ? { surfaces: [{ id: targetSurface, path: path.join(REPO_ROOT, 'src', 'ui', targetSurface) }] } : {}),
-  });
-
-  const { planPath, surfaceIds, summary } = result;
-  const files = collectFiles(planPath, planPath);
-
-  const manifest = { planPath, files, surfaceIds, summary };
-  process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
-})().catch(err => {
-  process.stderr.write(`figma-design-sync: ${err.message}\n`);
-  process.exit(1);
-});
-
-function collectFiles(dir, root) {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  const out = [];
-  for (const e of entries) {
-    const full = path.join(dir, e.name);
-    if (e.isDirectory()) {
-      out.push(...collectFiles(full, root));
-    } else {
-      out.push(path.relative(root, full));
-    }
-  }
-  return out;
-}
+// Kept because `node scripts/gds/<x>.js` is the form the skills and recipes use and
+// the form claude-materialize rewrites to `bongos exec` for a packaged core. Flags
+// pass straight through:
+//   node scripts/gds/figma-design-sync.js                 — build the Figma push plan, print the manifest
+//   node scripts/gds/figma-design-sync.js --surface <id>  — limit to one surface
+require('../../modules/ui-design/scripts/figma-design-sync.js');

package/scripts/gds/fitness-checks-identity.js

@@ -274,8 +274,10 @@ function checkNeutralConfigsNoHostIdentity() {
 
 function checkDesignContract() {
   const { spawnSync } = require('node:child_process');
-  const validatorPath = path.join(REPO_ROOT, 'scripts', 'gds', 'validate-design.js');
-  const adaptersDir = path.join(REPO_ROOT, 'src', 'ui', 'adapters');
+  // The validator + adapters live in the ui-design module (task 1003324, ADR 0197);
+  // scripts/gds/validate-design.js is a shim over the module file spawned here.
+  const validatorPath = path.join(REPO_ROOT, 'modules', 'ui-design', 'scripts', 'validate-design.js');
+  const adaptersDir = path.join(REPO_ROOT, 'modules', 'ui-design', 'adapters');
   const hasAdapters = (() => {
     try { return fs.readdirSync(adaptersDir).some((e) => fs.statSync(path.join(adaptersDir, e)).isDirectory()); }
     catch { return false; }
@@ -290,7 +292,7 @@ function checkDesignContract() {
   }
 
   return {
-    name: 'design contract valid (docs/design-contract.md / ADR 0081)',
+    name: 'design contract valid (modules/ui-design/docs/design-contract.md / ADR 0081)',
     ok: report.ok,
     hardFail: !report.ok && hasAdapters,
     violations: report.errors || [],

package/scripts/gds/publish-manifest.js

@@ -63,6 +63,7 @@ const PUBLISH_ALLOWLIST = [
   'modules/security/',
   'modules/government/',     // the same machinery under its post-ADR-0174 name (goal 1000068, task 1003003). Added in lockstep with the protected-surfaces.json entry: publish_manifest asserts every PROTECTED_GLOB is either topology-excluded or publishable, so registering the glob as protected WITHOUT this line default-denies the module from the published core — the open-source methodology would silently lose its permission machinery at the next release.
   'modules/copy-desk/',      // the artist's loop over user-facing TEXT (goal 1000074, ADR 0178). default:true, so it MUST be here — and note the ASYMMETRY that makes omitting it worse than useless: its hall surface ships regardless, because modules/hall-ui/ is allowlisted as one subtree. A released core carrying the page and the nav entry but not the routes behind them puts a tab in every instance's hall whose every call 404s. The module and its page are only ever added or removed together; tests/publish_manifest.mjs holds that pair.
+  'modules/ui-design/',      // the design contract + its adapters/CLIs + the /design playbook (task 1003324, ADR 0197). default:true, so it MUST be here: a released core without it would materialize skills (design, design-sync, figma-design-sync) whose CLIs and adapters do not exist.
   'modules/hall-ui/',
   'modules/status-ui/',
   'modules/dev-box/',
@@ -105,7 +106,6 @@ const PUBLISH_ALLOWLIST = [
   'docs/modules-contract.md',
   'docs/branding-contract.md',
   'docs/branding-fill-prompt.md',
-  'docs/design-contract.md',
   // RUNTIME DATA that happens to live under docs/, not documentation (ADR 0178).
   // modules/copy-desk reads the registry on EVERY queue load, and nothing on a
   // deployed box regenerates it — copy-inventory.js is a commit-it generator run

package/scripts/gds/validate-design.js

@@ -1,254 +1,12 @@
 #!/usr/bin/env node
 'use strict';
-// validate-design.js — minimal validator for the neutral design contract (task 1377).
-// See docs/design-contract.md §6 for the full spec.
-//
-// Usage:
+// validate-design.js — thin shim: the design-contract validator lives in the
+// ui-design module at modules/ui-design/scripts/validate-design.js (task 1003324,
+// ADR 0197). fitness.js (checkDesignContract in fitness-checks-identity.js) spawns
+// the module file directly; this path is the documented CLI entry point, kept
+// because it is the form claude-materialize rewrites to `bongos exec` for a
+// packaged core. Flags pass straight through:
 //   node scripts/gds/validate-design.js           # exits 0 on pass, 1 on failure
 //   node scripts/gds/validate-design.js --json    # machine-readable { ok, errors, warnings }
 //   node scripts/gds/validate-design.js --strict  # treat warnings as errors
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-const ARGS = new Set(process.argv.slice(2));
-const JSON_MODE = ARGS.has('--json');
-const STRICT = ARGS.has('--strict');
-
-const NEUTRAL_TOKENS  = path.join(REPO_ROOT, 'config', 'design-tokens.neutral.json');
-const INSTANCE_TOKENS = path.join(REPO_ROOT, 'config', 'design-tokens.json');
-const TOKENS_SCHEMA   = path.join(REPO_ROOT, 'config', 'design-tokens.schema.json');
-const DESIGN_SOURCES  = path.join(REPO_ROOT, 'config', 'design-sources.json');
-const UI_SRC          = path.join(REPO_ROOT, 'src', 'ui');
-const UI_ASSETS       = path.join(REPO_ROOT, 'assets', 'ui');
-const ADAPTERS_DIR    = path.join(REPO_ROOT, 'src', 'ui', 'adapters');
-
-const TOOL_ENUM = new Set(['claude-design', 'figma', 'hand', 'asset']);
-const REQUIRED_COLORS = ['bg', 'bgCard', 'ink', 'accent'];
-const REQUIRED_FONTS  = ['display', 'body'];
-
-const errors   = [];
-const warnings = [];
-
-function err(msg)  { errors.push(msg); }
-function warn(msg) { warnings.push(msg); }
-
-// ── helpers ──────────────────────────────────────────────────────────────────
-
-function readJson(filePath, label) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (e) {
-    err(`${label}: cannot read/parse — ${e.message}`);
-    return null;
-  }
-}
-
-function deepMerge(base, override) {
-  if (!override) return base;
-  const out = { ...base };
-  for (const [k, v] of Object.entries(override)) {
-    if (v && typeof v === 'object' && !Array.isArray(v) && typeof out[k] === 'object') {
-      out[k] = deepMerge(out[k], v);
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-
-function isUri(s) {
-  try { new URL(s); return true; } catch { return false; }
-}
-
-function dirExists(p) {
-  try { return fs.statSync(p).isDirectory(); } catch { return false; }
-}
-
-function fileExists(p) {
-  try { return fs.statSync(p).isFile(); } catch { return false; }
-}
-
-function listDirs(p) {
-  if (!dirExists(p)) return [];
-  return fs.readdirSync(p, { withFileTypes: true })
-    .filter(e => e.isDirectory())
-    .map(e => e.name);
-}
-
-// ── Check 1: neutral tokens file exists + parses ─────────────────────────────
-
-const schema   = readJson(TOKENS_SCHEMA, 'config/design-tokens.schema.json');
-const neutral  = readJson(NEUTRAL_TOKENS, 'config/design-tokens.neutral.json');
-
-if (!neutral) {
-  err('config/design-tokens.neutral.json is missing — this is the required baseline');
-}
-
-// ── Check 2: instance tokens file, if present, parses ────────────────────────
-
-let instance = null;
-if (fileExists(INSTANCE_TOKENS)) {
-  instance = readJson(INSTANCE_TOKENS, 'config/design-tokens.json');
-}
-
-// ── Check 3: merged tokens satisfy required fields ───────────────────────────
-
-const merged = neutral ? deepMerge(neutral, instance) : null;
-
-if (merged) {
-  if (!merged.colors || typeof merged.colors !== 'object') {
-    err('merged tokens: "colors" group is missing');
-  } else {
-    for (const key of REQUIRED_COLORS) {
-      if (!merged.colors[key]) err(`merged tokens: colors.${key} is required but missing`);
-      else if (typeof merged.colors[key] !== 'string') err(`merged tokens: colors.${key} must be a string`);
-    }
-    for (const [key, val] of Object.entries(merged.colors)) {
-      if (typeof val !== 'string') err(`merged tokens: colors.${key} must be a string`);
-    }
-  }
-
-  if (!merged.fonts || typeof merged.fonts !== 'object') {
-    err('merged tokens: "fonts" group is missing');
-  } else {
-    for (const key of REQUIRED_FONTS) {
-      if (!merged.fonts[key]) err(`merged tokens: fonts.${key} is required but missing`);
-      else if (typeof merged.fonts[key] !== 'string') err(`merged tokens: fonts.${key} must be a string`);
-    }
-    if (merged.fonts.links !== undefined) {
-      if (!Array.isArray(merged.fonts.links)) {
-        err('merged tokens: fonts.links must be an array');
-      } else {
-        for (const link of merged.fonts.links) {
-          if (typeof link !== 'string' || !isUri(link)) {
-            err(`merged tokens: fonts.links entry is not a valid URI: ${link}`);
-          }
-        }
-      }
-    }
-  }
-
-  // Optional groups: check value types if present
-  if (merged.scale) {
-    for (const [k, v] of Object.entries(merged.scale)) {
-      if (typeof v !== 'string') err(`merged tokens: scale.${k} must be a string`);
-    }
-  }
-  if (merged.radius) {
-    for (const [k, v] of Object.entries(merged.radius)) {
-      if (typeof v !== 'string') err(`merged tokens: radius.${k} must be a string`);
-    }
-  }
-  if (merged.motion) {
-    for (const [k, v] of Object.entries(merged.motion)) {
-      if (typeof v !== 'string') err(`merged tokens: motion.${k} must be a string`);
-    }
-  }
-}
-
-// ── Check 4: design-sources.json is valid + entries have required fields ─────
-
-let sources = null;
-if (fileExists(DESIGN_SOURCES)) {
-  sources = readJson(DESIGN_SOURCES, 'config/design-sources.json');
-  if (sources) {
-    if (!sources.surfaces || typeof sources.surfaces !== 'object') {
-      err('config/design-sources.json: "surfaces" key must be an object');
-    } else {
-      for (const [surfaceId, entry] of Object.entries(sources.surfaces)) {
-        if (!entry || typeof entry !== 'object') {
-          err(`design-sources: surface "${surfaceId}" entry must be an object`);
-          continue;
-        }
-        if (!entry.tool) {
-          err(`design-sources: surface "${surfaceId}" is missing "tool" field`);
-        } else if (!TOOL_ENUM.has(entry.tool)) {
-          err(`design-sources: surface "${surfaceId}" tool "${entry.tool}" is not in allowed enum (${[...TOOL_ENUM].join(', ')})`);
-        }
-        if (entry.sourceUrl !== undefined) {
-          if (typeof entry.sourceUrl !== 'string' || !isUri(entry.sourceUrl)) {
-            err(`design-sources: surface "${surfaceId}" sourceUrl is not a valid URI`);
-          }
-        } else if (entry.tool && !['hand', 'asset'].includes(entry.tool)) {
-          warn(`design-sources: surface "${surfaceId}" tool "${entry.tool}" has no sourceUrl`);
-        }
-        if (entry.lastSyncedAt !== undefined) {
-          if (typeof entry.lastSyncedAt !== 'string' || isNaN(Date.parse(entry.lastSyncedAt))) {
-            err(`design-sources: surface "${surfaceId}" lastSyncedAt is not a valid ISO 8601 date`);
-          }
-        }
-      }
-    }
-  }
-} else {
-  warn('config/design-sources.json not found — this is optional until adapters are in use');
-}
-
-// ── Check 5: design-sources surface ids match directories (if dirs exist) ─────
-
-const hasUiSrc    = dirExists(UI_SRC);
-const hasUiAssets = dirExists(UI_ASSETS);
-
-if (sources && sources.surfaces) {
-  const uiSrcDirs    = hasUiSrc    ? new Set(listDirs(UI_SRC).filter(n => n !== 'adapters')) : new Set();
-  const uiAssetsDirs = hasUiAssets ? new Set(listDirs(UI_ASSETS)) : new Set();
-
-  for (const surfaceId of Object.keys(sources.surfaces)) {
-    const inSrc    = uiSrcDirs.has(surfaceId);
-    const inAssets = uiAssetsDirs.has(surfaceId);
-    if (!inSrc && !inAssets && (hasUiSrc || hasUiAssets)) {
-      warn(`design-sources: surface "${surfaceId}" has no matching directory in src/ui/ or assets/ui/`);
-    }
-  }
-}
-
-// ── Check 6: adapter directories have valid index.js ─────────────────────────
-
-if (dirExists(ADAPTERS_DIR)) {
-  for (const adapterName of listDirs(ADAPTERS_DIR)) {
-    const indexPath = path.join(ADAPTERS_DIR, adapterName, 'index.js');
-    if (!fileExists(indexPath)) {
-      err(`adapter "${adapterName}": missing index.js at src/ui/adapters/${adapterName}/index.js`);
-      continue;
-    }
-    let mod;
-    try {
-      mod = require(indexPath);
-    } catch (e) {
-      err(`adapter "${adapterName}": index.js threw on require — ${e.message}`);
-      continue;
-    }
-    if (typeof mod.id !== 'string' || !mod.id) {
-      err(`adapter "${adapterName}": index.js must export a non-empty string "id"`);
-    } else if (mod.id !== adapterName) {
-      warn(`adapter "${adapterName}": exported id "${mod.id}" does not match directory name`);
-    }
-    if (typeof mod.import !== 'function') {
-      err(`adapter "${adapterName}": index.js must export an "import" function`);
-    }
-    if (typeof mod.export !== 'function') {
-      err(`adapter "${adapterName}": index.js must export an "export" function`);
-    }
-  }
-}
-
-// ── Report ────────────────────────────────────────────────────────────────────
-
-const effectiveErrors = STRICT ? [...errors, ...warnings] : errors;
-const ok = effectiveErrors.length === 0;
-
-if (JSON_MODE) {
-  process.stdout.write(JSON.stringify({ ok, errors, warnings }, null, 2) + '\n');
-} else {
-  const label = ok ? '✓ design contract valid' : '✗ design contract invalid';
-  process.stdout.write(`${label}\n`);
-  for (const e of errors)   process.stdout.write(`  ERROR   ${e}\n`);
-  for (const w of warnings) process.stdout.write(`  WARNING ${w}\n`);
-  if (ok && !STRICT && warnings.length) {
-    process.stdout.write(`  (${warnings.length} warning(s); use --strict to fail on warnings)\n`);
-  }
-}
-
-process.exit(ok ? 0 : 1);
+require('../../modules/ui-design/scripts/validate-design.js');

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

@@ -208,6 +208,24 @@ const MODULE_GLOBS = {
   // than instance hosting, and the web-surface precedent (hall-ui/status-ui) is
   // one key per surface (task 1002690, goal 1000059).
   'public-landing': ['public-landing/'],
+  // --- the design capability (task 1003324, ADR 0197): the design contract, its
+  //     adapters + sync CLIs + validator, the /design playbook, and the reserved homes
+  //     for the kit / the vendored UI skills / the style library. default-on,
+  //     declaration-only (three skills, no routes/port/migrations). The three
+  //     scripts/gds/ shims are core-side entry points over the module's CLIs —
+  //     listed for task affinity (the memory/ideas precedent: a command travels with
+  //     its domain). The contributed skill dirs follow the devsecops note above
+  //     ('.claude/skills/' stays with whichever module ships the skill); the two
+  //     loop recipes are the module's how-tos. NOT here, deliberately: config/
+  //     design-tokens.* + design-sources.json (the host boundary, kernel 'config/')
+  //     and DESIGN.md (the instance's world); public-landing keeps its own key —
+  //     the front door is this module's first customer, not its owner. ---
+  'ui-design': [
+    'modules/ui-design/',
+    'scripts/gds/design-sync.js', 'scripts/gds/figma-design-sync.js', 'scripts/gds/validate-design.js',
+    '.claude/skills/design/', '.claude/skills/design-sync/', '.claude/skills/figma-design-sync/',
+    'docs/recipes/claude-design-loop.md', 'docs/recipes/figma-design-loop.md',
+  ],
   // --- feature modules ---
   // BV1.R49: game graduated to modules/game/ — src/rooms/, src/world/, src/seats.js,
   // src/db.js, migrations/game/, and public/ all moved there. src/preview-server.js

package/src/module-api.js

@@ -1228,8 +1228,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.392 with no explicit bump. run 33177136260. (task 1002620)
 //   1.19.394 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.393 with no explicit bump. run 33182535783. (task 1002620)
+//   1.19.395 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.394 with no explicit bump. run 33188021384. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.394'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.395'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/design_tokens_sync.mjs

@@ -58,7 +58,7 @@ test('the fonts the two files share are the same fonts', () => {
 
 test('the claude-design adapter falls back to the pack accent, never a brand literal of its own', () => {
   const source = fs.readFileSync(
-    path.join(REPO_ROOT, 'src', 'ui', 'adapters', 'claude-design', 'index.js'), 'utf8');
+    path.join(REPO_ROOT, 'modules', 'ui-design', 'adapters', 'claude-design', 'index.js'), 'utf8');
   const block = source.match(/const FALLBACK_ACCENT =[\s\S]*?\}\)\(\);/);
   assert.ok(block, 'the adapter declares one resolved fallback accent instead of inline literals');
   assert.match(block[0], /design-tokens\.neutral\.json/,

package/tests/doc_cli_guard.mjs

@@ -181,6 +181,25 @@ test('a flag present in real code produces NO warning', () => {
   assert.deepEqual(warnings, []);
 });
 
+test('a scripts/gds/ shim is read together with the module CLI it forwards to (task 1003324)', () => {
+  // scripts/gds/validate-design.js is `require('../../modules/ui-design/scripts/validate-design.js')`
+  // plus a usage banner; `--strict` is parsed in the module file. Read alone, the shim
+  // would only ever say "named in comments" for a flag that is genuinely honoured.
+  const src = g.readCliSource('scripts/gds/validate-design.js');
+  assert.ok(src, 'the shim exists');
+  assert.ok(g.scriptMentionsFlag(g.stripLineComments(src), 'strict'),
+    'the flag is found in CODE — the module CLI was followed, not just the shim banner');
+  const { violations, warnings } = g.scanDocs(['d.md'], {
+    readDoc: () => 'run `node scripts/gds/validate-design.js --strict`',
+    readScript: g.readCliSource, allow: new Map(),
+  });
+  assert.deepEqual(violations, []);
+  assert.deepEqual(warnings, [], 'no "only in comments" warning for a shim-forwarded flag');
+  // Bounded: a require into src/ is NOT followed (it is not a CLI phase).
+  assert.ok(!g.readCliSource('scripts/gds/fitness.js').includes('function requireBuilder'),
+    'a core internal the CLI requires is not concatenated into its source');
+});
+
 test('stripLineComments keeps code and drops both comment forms', () => {
   const out = g.stripLineComments("const a = '--keep'; // --dropped\n/* --alsodropped */\n");
   assert.ok(out.includes('--keep'));

package/tests/figma_adapter.mjs

@@ -16,7 +16,7 @@ import path from 'node:path';
 import os from 'node:os';
 
 const require = createRequire(import.meta.url);
-const adapter = require('../src/ui/adapters/figma/index.js');
+const adapter = require('../modules/ui-design/adapters/figma/index.js');
 
 const REPO_ROOT = path.resolve(process.cwd());
 const SURFACE_ID = `__test_figma_${process.pid}`;

package/tests/module_loader.mjs

@@ -176,6 +176,9 @@ test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49
   // off in enabledModules(). And copy-desk (task 1003113 / R02 of goal 1000074) —
   // the copy half of the design contract: the flag + the artist's queue over
   // user-facing text, default-on because every instance shows a person words.
+  // And ui-design (task 1003324 / ADR 0197) — the design contract, its adapters
+  // and the /design playbook as a platform capability: declaration-only (three
+  // skills, no routes/port), default-on because every instance has a face.
   // All are discovered; none has validation
   // errors or coreVersion mismatches. Order is the readdir sort.
   //
@@ -200,7 +203,7 @@ test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49
   // That is precisely how the agents regression reached an open PR (task 1002485).
   loader._reset();
   const snap = loader.loaderSnapshot();
-  assert.deepEqual(snap.loaded, ['agents', 'autonomy', 'builder-settings', 'copy-desk', 'dev-box', 'discord', 'economy', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'platform-identity', 'provisioning', 'security', 'sessions', 'status-ui']);
+  assert.deepEqual(snap.loaded, ['agents', 'autonomy', 'builder-settings', 'copy-desk', 'dev-box', 'discord', 'economy', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'platform-identity', 'provisioning', 'security', 'sessions', 'status-ui', 'ui-design']);
   assert.deepEqual(snap.errors, []);
   assert.deepEqual(snap.skipped, []);
   loader._reset();