@bongos/core 1.19.396 → 1.19.398

package/scripts/gds/claude-materialize.js

@@ -139,27 +139,109 @@ function rebrandText(text, rules) {
 
 function readJsonSafe(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } }
 
-// Skills owned by a module that is DISABLED in the TARGET instance (task 2103b).
-// Each module.json declares `contributes.skills`; a module is enabled when the
-// target's config/modules.json says so, else by its own `default`. A skill owned
-// by NO module is core and is never skipped. PURE-ish (reads the fs) + exported.
-function disabledModuleSkills({ coreRoot, instanceDir }) {
-  const skip = new Set();
+// Every module that declares `contributes.skills`, with whether the TARGET instance
+// enables it: the target's config/modules.json wins, else the module's own `default`.
+// The one place that rule lives — disabledModuleSkills and moduleSkillSources both
+// read it. PURE-ish (reads the fs) + exported.
+function moduleSkillRoster({ coreRoot, instanceDir }) {
+  const roster = [];
   const modulesDir = path.join(coreRoot, 'modules');
-  if (!fs.existsSync(modulesDir)) return skip;
+  if (!fs.existsSync(modulesDir)) return roster;
   const targetCfg = readJsonSafe(path.join(instanceDir, 'config', 'modules.json')) || {};
   const enabledMap = (targetCfg.modules && typeof targetCfg.modules === 'object') ? targetCfg.modules : {};
   for (const dir of fs.readdirSync(modulesDir)) {
     const mj = readJsonSafe(path.join(modulesDir, dir, 'module.json'));
     const skills = mj && mj.contributes && mj.contributes.skills;
     if (!Array.isArray(skills)) continue;
-    const explicit = enabledMap[mj.key || dir];
+    const key = mj.key || dir;
+    const explicit = enabledMap[key];
     const enabled = explicit === undefined ? mj.default === true : explicit === true;
-    if (!enabled) for (const s of skills) skip.add(s);
+    roster.push({ key, dir: path.join(modulesDir, dir), enabled, skills });
   }
+  return roster;
+}
+
+// Skills owned by a module that is DISABLED in the TARGET instance (task 2103b).
+// A skill owned by NO module is core and is never skipped.
+function disabledModuleSkills(opts) {
+  const skip = new Set();
+  for (const m of moduleSkillRoster(opts)) if (!m.enabled) for (const s of m.skills) skip.add(s);
   return skip;
 }
 
+// A declared skill name is a path segment the materialiser WRITES under
+// .claude/skills/, so it is allowlisted before it ever reaches path.join: lowercase
+// slug only, no dots, no separators. A manifest carrying "../x" names nothing.
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// The vendoring gate a THIRD-PARTY skill must pass at copy time, not only in CI
+// (ADR 0198 §1–3): a PROVENANCE.md sidecar whose frontmatter names a licence on the
+// allowlist and a scan verdict that may land. The module's own skills/policy.json
+// (the ui-design shape) is the source of both lists when present; these defaults
+// are the same five licences and two verdicts otherwise. A gate that cannot read
+// the sidecar refuses — an unvetted copy never lands because a file was missing.
+const VENDOR_DEFAULT_POLICY = Object.freeze({
+  licenceAllowlist: ['Apache-2.0', 'MIT', 'BSD-2-Clause', 'BSD-3-Clause', 'CC-BY-4.0'],
+  verdictsThatMayLand: ['clean', 'caution'],
+});
+
+function sidecarFrontmatter(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; }
+  const m = text.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) out[kv[1]] = kv[2].replace(/^["']|["']$/g, '').trim();
+  }
+  return out;
+}
+
+// → { ok: true } or { ok: false, reason } for one vendored skill dir. Exported for the test.
+function vendoredSkillGate(dir, policy = VENDOR_DEFAULT_POLICY) {
+  const fm = sidecarFrontmatter(path.join(dir, 'PROVENANCE.md'));
+  if (!fm) return { ok: false, reason: 'no PROVENANCE.md sidecar (or no frontmatter)' };
+  const licences = Array.isArray(policy.licenceAllowlist) ? policy.licenceAllowlist : VENDOR_DEFAULT_POLICY.licenceAllowlist;
+  const verdicts = Array.isArray(policy.verdictsThatMayLand) ? policy.verdictsThatMayLand : VENDOR_DEFAULT_POLICY.verdictsThatMayLand;
+  if (!licences.includes(fm.licence)) return { ok: false, reason: `licence "${fm.licence || ''}" is not on the allowlist` };
+  if (!verdicts.includes(fm.scanVerdict)) return { ok: false, reason: `scan verdict "${fm.scanVerdict || ''}" may not land` };
+  return { ok: true };
+}
+
+// Skills a module ships from its OWN tree instead of .claude/skills/ (task 1003321,
+// ADR 0198): modules/<key>/skills/<name>/ for a skill the module authors, or
+// modules/<key>/skills/vendor/<name>/ for a third-party skill carried with its
+// PROVENANCE.md sidecar (the `vendor/` segment is the one fitness-ratchets exempts
+// from the first-party line budgets). Only a name the module DECLARES in
+// contributes.skills resolves — the manifest stays the single declaration — a name
+// that fails SKILL_NAME_RE is refused before any path is built, a dir with no
+// SKILL.md is not a skill, and a vendored dir must pass vendoredSkillGate. Refusals
+// come back in `refused[]` so the caller can log them. Accepts a precomputed
+// `roster` so materializeClaude walks modules/ once. PURE-ish (reads the fs) + exported.
+function moduleSkillSources(opts) {
+  const out = [];
+  const refused = [];
+  const roster = (opts && opts.roster) || moduleSkillRoster(opts);
+  for (const m of roster) {
+    const policy = readJsonSafe(path.join(m.dir, 'skills', 'policy.json')) || VENDOR_DEFAULT_POLICY;
+    for (const name of m.skills) {
+      if (typeof name !== 'string' || !SKILL_NAME_RE.test(name)) { refused.push({ name: String(name), module: m.key, reason: 'name is not a lowercase slug' }); continue; }
+      const own = path.join(m.dir, 'skills', name);
+      const vendored = path.join(m.dir, 'skills', 'vendor', name);
+      const src = [own, vendored].find((p) => fs.existsSync(path.join(p, 'SKILL.md')));
+      if (!src) continue;
+      if (src === vendored) {
+        const gate = vendoredSkillGate(src, policy);
+        if (!gate.ok) { refused.push({ name, module: m.key, reason: gate.reason }); continue; }
+      }
+      out.push({ name, module: m.key, dir: src, enabled: m.enabled, vendored: src === vendored });
+    }
+  }
+  out.refused = refused;
+  return out;
+}
+
 // ---- I/O: copy a tree, transforming text files through bongosify ----------
 
 const TEXT_EXT = new Set(['.md', '.txt', '.sh']); // command-bearing text we rewrite (skills are SKILL.md)
@@ -231,7 +313,7 @@ function transformSettings(srcPath) {
 const HOOK_TEXT_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.sh', '.md', '.txt']); // hooks are .js — rebrand them too
 
 function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
-  const summary = { skipped: false, skills: 0, settings: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], rebrandRules: 0, claudeMd: false, notes: [] };
+  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], rebrandRules: 0, claudeMd: false, notes: [] };
   if (path.resolve(instanceDir) === path.resolve(coreRoot)) {
     summary.skipped = true;
     summary.notes.push('instance dir is the core root — nothing to materialize (byte-identical no-op).');
@@ -253,8 +335,11 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   summary.rebrandRules = rebrandRules.length;
   if (rebrandRules.length) log(`  • rebranding ${rebrandRules.length} founder literal(s) in the copied .claude/ → this instance's identity.`);
 
-  // Drop skills owned by a module this instance hasn't enabled (task 2103b).
-  const skipSkills = disabledModuleSkills({ coreRoot, instanceDir });
+  // Drop skills owned by a module this instance hasn't enabled (task 2103b). One
+  // walk of modules/ serves both this skip and step 1b's module-owned sources.
+  const roster = moduleSkillRoster({ coreRoot, instanceDir });
+  const skipSkills = new Set();
+  for (const m of roster) if (!m.enabled) for (const s of m.skills) skipSkills.add(s);
   const skillSkip = (rel) => skipSkills.has(String(rel).split(/[\\/]/)[0]);
 
   // 1. skills — ship in the core package; copy, rewrite invocations→bongos, rebrand
@@ -270,6 +355,30 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   if (summary.excludedSkills.length) log(`  • excluded ${summary.excludedSkills.length} skill(s) owned by disabled module(s): ${summary.excludedSkills.join(', ')}`);
   log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${skillsRes.files} skill file(s) → .claude/skills/ (invocations→bongos, identity rebranded)${left((skillsRes.skipped || []).length)}`);
 
+  // 1b. module-owned skills — shipped from modules/<key>/skills/ (own) or
+  //     modules/<key>/skills/vendor/ (third-party + PROVENANCE.md) and landed in the
+  //     SAME .claude/skills/<name>/ the builder's harness reads (task 1003321, ADR
+  //     0198). Same transforms as step 1; a disabled module's are excluded by the same
+  //     rule; a name the core's own .claude/skills/ already carries keeps the core copy;
+  //     a name that is not a slug, or a vendored dir that fails the sidecar gate, is
+  //     REFUSED here at copy time — the CI test is the second line, not the only one.
+  const sources = moduleSkillSources({ roster });
+  for (const r of sources.refused) {
+    summary.notes.push(`module skill "${r.name}" (${r.module}) refused: ${r.reason}.`);
+    log(`  ✗ refused module skill "${r.name}" (${r.module}): ${r.reason}`);
+  }
+  for (const s of sources) {
+    if (!s.enabled) { if (!summary.excludedSkills.includes(s.name)) summary.excludedSkills.push(s.name); continue; }
+    if (fs.existsSync(path.join(skillsSrc, s.name))) {
+      summary.notes.push(`module skill "${s.name}" (${s.module}) also exists under the core's .claude/skills/ — the core copy was materialized, the module copy ignored.`);
+      continue;
+    }
+    const r = copyTreeTransformed(s.dir, path.join(destClaude, 'skills', s.name), { dryRun, overwrite, transform: (t) => rebrand(bongosify(t)) });
+    summary.moduleSkills += r.files;
+    for (const rel of r.skipped || []) summary.skippedFiles.push(`skills/${s.name}/${rel}`);
+  }
+  if (summary.moduleSkills) log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${summary.moduleSkills} module-owned skill file(s) → .claude/skills/ (from modules/<key>/skills/)`);
+
   // 2. settings.json — topology; present in the checkout/core repo, absent in a package-only install.
   const settingsSrc = path.join(srcClaude, 'settings.json');
   if (fs.existsSync(settingsSrc)) {
@@ -343,4 +452,4 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   return summary;
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills };
+module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/scripts/gds/ui-kit-transform.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// ui-kit-transform.js — the instance's serving transforms as a command (task
+// 1003320, ADR 0197). Reads one surface page and prints it transformed exactly as
+// serve-internal.js / platform-server.js serve it: the apex-only strip, the
+// brand-token stamp, the pack's theme injection — with the instance's own
+// branding pack.
+//
+// WHY a script: the ui-design kit's stub (modules/ui-design/kit/serve.js) must
+// serve a page through the REAL code path, and a module may not require core
+// (ADR 0083), while the doorway may not import the serving domain (fitness Check
+// 12, ADR 0091 §1). A command under scripts/gds/ is outside both walls — the
+// memory / ideas / sessions precedent: a command travels with its domain but
+// stays under scripts/. The stub spawns this per page and memoises the answer.
+//
+//   node scripts/gds/ui-kit-transform.js <page.html> [--child] [--json]
+//     --child   the child-instance shape (apex-only regions removed)
+//     --json    { html, brand, publicOrigin, hallOrigin } instead of the bare HTML
+//
+// Exit 2 on usage; the transformed page on stdout, nothing else.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = process.argv.slice(2);
+const file = args.find((a) => !a.startsWith('--'));
+if (!file) { process.stderr.write('usage: node scripts/gds/ui-kit-transform.js <page.html> [--child] [--json]\n'); process.exit(2); }
+const child = args.includes('--child');
+
+const { injectBrandingGlobal, applyBrandTokens } = require('../../src/bongos/serve-internal');
+const { stripApexOnly } = require('../../src/platform-server');
+const branding = require('../../src/branding');
+
+const brand = branding.clientBranding();
+let domains = {};
+try { domains = (typeof branding.branding === 'function' ? branding.branding() : {}).domains || {}; } catch { domains = {}; }
+const publicOrigin = domains.publicOrigin || '';
+const hallOrigin = child ? '' : (domains.buildersOrigin || '');
+
+const raw = fs.readFileSync(path.resolve(file), 'utf8');
+// platform-server's order for the landing: strip, then inject; the token stamp is
+// what the hall/status surfaces get on the way through serve-internal.
+const html = injectBrandingGlobal(applyBrandTokens(stripApexOnly(raw, !child), brand, publicOrigin, hallOrigin, '', ''), brand);
+process.stdout.write(args.includes('--json') ? JSON.stringify({ html, brand, publicOrigin, hallOrigin }) : html);

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

@@ -223,6 +223,7 @@ const MODULE_GLOBS = {
   'ui-design': [
     'modules/ui-design/',
     'scripts/gds/design-sync.js', 'scripts/gds/figma-design-sync.js', 'scripts/gds/validate-design.js',
+    'scripts/gds/ui-kit-transform.js', // the kit's stub reaches the real serving transforms through this command (task 1003320)
     '.claude/skills/design/', '.claude/skills/design-sync/', '.claude/skills/figma-design-sync/',
     'docs/recipes/claude-design-loop.md', 'docs/recipes/figma-design-loop.md',
   ],

package/src/module-api.js

@@ -1232,8 +1232,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.394 with no explicit bump. run 33188021384. (task 1002620)
 //   1.19.396 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.395 with no explicit bump. run 33188525568. (task 1002620)
+//   1.19.397 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.396 with no explicit bump. run 33193365480. (task 1002620)
+//   1.19.398 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.397 with no explicit bump. run 33199474439. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.396'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.398'; // 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/claude_materialize.mjs

@@ -241,6 +241,89 @@ t('disabledModuleSkills: only skills of DISABLED modules are collected (default
   rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true });
 });
 
+// ---- module-owned skills (task 1003321 / ADR 0198) ---------------------------
+// A module ships a skill from modules/<key>/skills/<name>/ (its own) or
+// modules/<key>/skills/vendor/<name>/ (third-party + PROVENANCE.md); only a DECLARED
+// name resolves, and it lands in .claude/skills/<name>/ like any core skill — or is
+// excluded by the same disabled-module rule.
+t('moduleSkillSources: declared names resolve from skills/<name> or skills/vendor/<name>; undeclared and SKILL.md-less dirs do not', () => {
+  const core = mkdtempSync(join(tmpdir(), 'rb-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'rb-inst-'));
+  const modDir = join(core, 'modules', 'foo');
+  mkdirSync(join(modDir, 'skills', 'own'), { recursive: true });
+  mkdirSync(join(modDir, 'skills', 'vendor', 'third'), { recursive: true });
+  mkdirSync(join(modDir, 'skills', 'vendor', 'undeclared'), { recursive: true });
+  mkdirSync(join(modDir, 'skills', 'noskill'), { recursive: true });
+  writeFileSync(join(modDir, 'module.json'), JSON.stringify({ key: 'foo', default: true, contributes: { skills: ['own', 'third', 'noskill', 'missing'] } }));
+  writeFileSync(join(modDir, 'skills', 'own', 'SKILL.md'), '---\nname: own\n---\nrun node scripts/gds/ship.js 1\n');
+  writeFileSync(join(modDir, 'skills', 'vendor', 'third', 'SKILL.md'), '---\nname: third\n---\nbody\n');
+  writeFileSync(join(modDir, 'skills', 'vendor', 'third', 'PROVENANCE.md'), '---\nlicence: MIT\nscanVerdict: caution\n---\n');
+  writeFileSync(join(modDir, 'skills', 'vendor', 'undeclared', 'SKILL.md'), '---\nname: undeclared\n---\n');
+  const srcs = m.moduleSkillSources({ coreRoot: core, instanceDir: inst });
+  assert.deepEqual(srcs.map((s) => [s.name, s.vendored, s.enabled]), [['own', false, true], ['third', true, true]]);
+  assert.deepEqual(srcs.refused, []);
+
+  // materialize: both land under .claude/skills/<name>/, sidecar included, SKILL.md bongosified
+  mkdirSync(join(core, '.claude', 'skills'), { recursive: true });
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.equal(res.moduleSkills, 3);
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'own', 'SKILL.md')));
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'third', 'SKILL.md')));
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'third', 'PROVENANCE.md')), 'the provenance sidecar travels with the skill');
+  assert.ok(!existsSync(join(inst, '.claude', 'skills', 'undeclared')), 'an undeclared dir never materializes');
+  assert.match(readFileSync(join(inst, '.claude', 'skills', 'own', 'SKILL.md'), 'utf8'), /bongos ship 1/);
+
+  // disabled in the target → neither lands, both are reported excluded
+  const inst2 = mkdtempSync(join(tmpdir(), 'rb-inst-'));
+  mkdirSync(join(inst2, 'config'), { recursive: true });
+  writeFileSync(join(inst2, 'config', 'modules.json'), JSON.stringify({ modules: { foo: false } }));
+  const res2 = m.materializeClaude({ coreRoot: core, instanceDir: inst2, dryRun: false });
+  assert.equal(res2.moduleSkills, 0);
+  assert.ok(!existsSync(join(inst2, '.claude', 'skills', 'third')));
+  assert.deepEqual(res2.excludedSkills.sort(), ['own', 'third']);
+  for (const d of [core, inst, inst2]) rmSync(d, { recursive: true, force: true });
+});
+
+// The copy-time gate (ADR 0198 §1–3): a declared name is a path segment, so it is a
+// slug or nothing; a vendored dir lands only with a sidecar whose licence is on the
+// allowlist and whose verdict may land. Refusals are reported, never silently skipped.
+t('moduleSkillSources: a non-slug name never reaches path.join; a vendored dir with no sidecar, an off-list licence or a dangerous verdict is refused at copy time', () => {
+  const core = mkdtempSync(join(tmpdir(), 'rb-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'rb-inst-'));
+  const modDir = join(core, 'modules', 'foo');
+  const vendor = (name, sidecar) => {
+    mkdirSync(join(modDir, 'skills', 'vendor', name), { recursive: true });
+    writeFileSync(join(modDir, 'skills', 'vendor', name, 'SKILL.md'), `---\nname: ${name}\n---\n`);
+    if (sidecar != null) writeFileSync(join(modDir, 'skills', 'vendor', name, 'PROVENANCE.md'), sidecar);
+  };
+  vendor('nosidecar', null);
+  vendor('badlicence', '---\nlicence: GPL-3.0\nscanVerdict: clean\n---\n');
+  vendor('dangerous', '---\nlicence: MIT\nscanVerdict: dangerous\n---\n');
+  vendor('good', '---\nlicence: Apache-2.0\nscanVerdict: clean\n---\n');
+  mkdirSync(join(modDir, 'skills', 'evil'), { recursive: true });
+  writeFileSync(join(modDir, 'module.json'), JSON.stringify({ key: 'foo', default: true, contributes: { skills: ['../evil', 'Bad.Name', 'nosidecar', 'badlicence', 'dangerous', 'good'] } }));
+  const srcs = m.moduleSkillSources({ coreRoot: core, instanceDir: inst });
+  assert.deepEqual(srcs.map((s) => s.name), ['good']);
+  assert.deepEqual(srcs.refused.map((r) => r.name).sort(), ['../evil', 'Bad.Name', 'badlicence', 'dangerous', 'nosidecar']);
+  assert.ok(srcs.refused.find((r) => r.name === 'dangerous').reason.includes('may not land'));
+  assert.ok(srcs.refused.find((r) => r.name === 'badlicence').reason.includes('allowlist'));
+  // the gate is the exported function the ui-design test pins too
+  assert.equal(m.vendoredSkillGate(join(modDir, 'skills', 'vendor', 'good')).ok, true);
+  assert.equal(m.vendoredSkillGate(join(modDir, 'skills', 'vendor', 'dangerous')).ok, false);
+  // a module's own skills/policy.json narrows the lists
+  writeFileSync(join(modDir, 'skills', 'policy.json'), JSON.stringify({ licenceAllowlist: ['MIT'], verdictsThatMayLand: ['clean'] }));
+  assert.deepEqual(m.moduleSkillSources({ coreRoot: core, instanceDir: inst }).map((s) => s.name), [], 'Apache-2.0 is off this module\'s narrower list');
+  // and materializeClaude reports every refusal, lands only the good one
+  rmSync(join(modDir, 'skills', 'policy.json'));
+  mkdirSync(join(core, '.claude', 'skills'), { recursive: true });
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.equal(res.moduleSkills, 2);
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'good', 'PROVENANCE.md')));
+  for (const bad of ['nosidecar', 'badlicence', 'dangerous', 'evil']) assert.ok(!existsSync(join(inst, '.claude', 'skills', bad)), `${bad} never lands`);
+  assert.equal(res.notes.filter((n) => n.includes('refused')).length, 5);
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
 // ---- materializeClaude end-to-end: rebrand + skill-exclude (from the REAL repo) --
 t('materializeClaude: copied hooks carry NO founder origin/config-dir; a disabled-module skill is excluded', () => {
   if (!existsSync(join(ROOT, '.claude', 'hooks'))) return;

package/tests/ui_design_kit.mjs

@@ -0,0 +1,217 @@
+// tests/ui_design_kit.mjs — the ui-design kit (task 1003320, ADR 0197): the platform
+// floors are a pinned contract; a states/probes file has a shape the kit refuses to
+// guess at; the pure audit names what a bad render did; the mock checker keeps the
+// platform's rules apart from an instance's taste bans; the instance's own pack
+// clears the floor; every CLI exits with its documented code on a bad input; and the
+// stub serves a surface through the doorway's real transforms. DB-free and
+// browser-free — the renders themselves are the recipe's job, not CI's.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KIT = path.join(ROOT, 'modules', 'ui-design', 'kit');
+const lib = require(path.join(KIT, 'lib.js'));
+const mock = require(path.join(KIT, 'check-mock.js'));
+const contrast = require(path.join(KIT, 'contrast.js'));
+
+const run = (file, args, env = {}) => spawnSync(process.execPath, [path.join(KIT, file), ...args], { encoding: 'utf8', env: { ...process.env, ...env }, timeout: 60000 });
+const tmp = (name, text) => { const p = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ui-kit-test-')), name); fs.writeFileSync(p, text); return p; };
+const readJson = (rel) => JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8'));
+
+// ── the contract ──────────────────────────────────────────────────────────────
+test('the platform floors are a pinned list — a floor cannot vanish quietly', () => {
+  assert.deepEqual([...lib.FLOORS], ['console-errors', 'failed-requests', 'horizontal-overflow', 'one-header-main-h1', 'controls-24px', 'top-bar-80px', 'reduced-motion']);
+  assert.deepEqual(lib.EXIT, { CLEAN: 0, PROBLEMS: 1, USAGE: 2, NO_BROWSER: 3 });
+  assert.deepEqual(Object.keys(lib.SIZES), ['320', '390', '1440']);
+});
+
+test('the shipped states files validate and sit beside the page they name', () => {
+  for (const rel of ['public-landing/projects.states.json', 'public-landing/index.states.json', 'modules/hall-ui/public/ranks.states.json']) {
+    const json = readJson(rel);
+    const v = lib.validateStatesFile(json);
+    assert.deepEqual(v.errors, [], `${rel}: ${v.errors.join('; ')}`);
+    assert.equal(path.basename(rel), `${lib.pageName(json.page)}.states.json`, `${rel} is named for its page`);
+  }
+});
+
+test('the shipped probes files validate', () => {
+  for (const rel of ['public-landing/projects.probes.json', 'public-landing/index.probes.json']) {
+    const v = lib.validateProbesFile(readJson(rel));
+    assert.deepEqual(v.errors, [], `${rel}: ${v.errors.join('; ')}`);
+  }
+});
+
+test('a states file that breaks the contract is refused with the reason named', () => {
+  assert.equal(lib.validateStatesFile(null).ok, false);
+  const v = lib.validateStatesFile({});
+  assert.ok(v.errors.some((e) => e.startsWith('page: required')));
+  assert.ok(v.errors.some((e) => e.startsWith('states: required')));
+  const bad = lib.validateStatesFile({ page: '/x', states: { 'Bad Name': { actions: [['teleport', '#a']], expect: { glow: true } }, ok: { auth: 'yes' } } });
+  assert.ok(bad.errors.some((e) => /kebab-case/.test(e)));
+  assert.ok(bad.errors.some((e) => /unknown action "teleport"/.test(e)));
+  assert.ok(bad.errors.some((e) => /unknown expectation/.test(e) && /glow/.test(e)));
+  assert.ok(bad.errors.some((e) => /states\.ok\.auth/.test(e)));
+  const stub = lib.validateStatesFile({ page: '/x', stub: { prefix: 'builders' }, states: { a: {} } });
+  assert.ok(stub.errors.some((e) => /stub\.prefix/.test(e)));
+});
+
+test('a probes file needs a name and an expectation per probe, and cannot continue from nothing', () => {
+  const v = lib.validateProbesFile({ page: '/x', probes: [{ continue: true, steps: [] }, { name: 'n', steps: [['wait', 1]] }] });
+  assert.ok(v.errors.some((e) => /probes\[0\]\.name: required/.test(e)));
+  assert.ok(v.errors.some((e) => /probes\[0\]\.continue: the first probe/.test(e)));
+  assert.ok(v.errors.some((e) => /probes\[1\]\.expect: required/.test(e)));
+  assert.ok(lib.validateProbesFile({ page: '/x', probes: [{ name: 'n', steps: [], expect: { dialog: false } }] }).ok);
+});
+
+// ── the pure audit ────────────────────────────────────────────────────────────
+const clean = () => ({ scrollWidth: 1440, clientWidth: 1440, mode: 'dark', headers: 1, mains: 1, h1s: 1, smallControls: [], bar: { h: 64, top: 0 }, expanded: [], dialog: false, running: 0, activeId: '', activeText: '', sel: {} });
+
+test('auditFloors names each floor a render breaks, and says nothing about a clean one', () => {
+  assert.deepEqual(lib.auditFloors(clean(), { width: 1440, mode: 'dark' }), []);
+  const p = lib.auditFloors({ ...clean(), scrollWidth: 1500, h1s: 3, smallControls: ['a.x "Docs" 40x17'], bar: { h: 96 }, mode: 'light' }, { width: 1440, mode: 'dark' });
+  assert.ok(p.some((x) => x.startsWith('horizontal-overflow')));
+  assert.ok(p.some((x) => x.startsWith('one-header-main-h1') && /h1 3/.test(x)));
+  assert.ok(p.some((x) => x.startsWith('controls-24px') && /40x17/.test(x)));
+  assert.ok(p.some((x) => x.startsWith('top-bar-80px') && /96px/.test(x)));
+  assert.ok(p.some((x) => /data-mode "light" under a dark scheme/.test(x)));
+  assert.deepEqual(lib.auditFloors({ ...clean(), mode: null }, { mode: 'dark' }), [], 'a page that sets no data-mode is not held to one');
+});
+
+test('expectProblems compares every expectation the vocabulary allows', () => {
+  const facts = { ...clean(), expanded: ['projTrig'], dialog: true, sel: { '#a': true, '#b': false }, activeId: 'x', activeText: 'Sky', param: { view: 'mine' }, attr: ['dark'], text: ['Table'], href: ['/docs'], count: [3], checked: false, value: ['demo'], hasClass: [true] };
+  assert.deepEqual(lib.expectProblems(facts, { expanded: true, dialog: true, visible: ['#a'], hidden: ['#b'], open: '#a', closed: '#b', activeId: 'x', activeText: 'Sky', expandedIds: ['projTrig'], param: { view: 'mine' }, attr: [['html', 'data-mode', 'dark']], text: [['h1', 'Table']], href: [['a', '/docs']], count: [['li', 3]], value: [['#q', 'demo']], hasClass: [['#w', 'is-open']] }), []);
+  const p = lib.expectProblems(facts, { expanded: false, dialog: false, visible: ['#b'], hidden: ['#a'], activeText: 'Table', param: { view: null }, count: [['li', 5]], checked: '#c', hasClass: [['#w', 'is-open', false]], noOverflow: true });
+  for (const needle of ['expected no expanded trigger', 'expected no visible dialog', 'expected visible: #b', 'expected hidden: #a', 'active text "Sky", expected "Table"', '?view=mine, expected null', '3 × li, expected 5', '#c is not checked', 'still has class "is-open"']) {
+    assert.ok(p.some((x) => x.includes(needle)), `missing: ${needle} in ${p.join(' | ')}`);
+  }
+});
+
+test('reducedMotionProblems: a running animation or a rAF loop is a floor break', () => {
+  assert.deepEqual(lib.reducedMotionProblems({ running: [], frames: 1 }), []);
+  const p = lib.reducedMotionProblems({ running: ['breath'], frames: 40 });
+  assert.equal(p.length, 2);
+  assert.match(p[0], /breath/); assert.match(p[1], /requestAnimationFrame loop/);
+});
+
+test('the page argument survives Git Bash path conversion of a bare slash', () => {
+  assert.equal(lib.normalizePageArg('C:/Program Files/Git/'), '/');
+  assert.equal(lib.normalizePageArg('/projects'), '/projects');
+  assert.equal(lib.pageName('/'), 'index'); assert.equal(lib.pageName('/builders/ranks'), 'ranks'); assert.equal(lib.pageName('/projects?view=mine'), 'projects');
+});
+
+// ── the mock checker: platform rules vs the instance's taste ──────────────────
+const GOOD_MOCK = `<!doctype html><html><head><style>
+body{--pad:8px;color:var(--ink);background:var(--bg)}
+:root[data-mode="dark"] body{--pad:9px}
+@media (prefers-color-scheme: dark){:root:not([data-mode="light"]) body{--pad:9px}}
+.a{transition:opacity 200ms}
+</style></head><body><!-- THESIS: a mock that says what it claims, so the reviewer can check the render against the words -->
+<a class="skip" href="#main">Skip</a><header><button aria-expanded="false" aria-controls="m">Menu</button></header>
+<main id="main"><h1>Title</h1><p>Plain copy.</p><div id="m" hidden></div></main>
+<script>const state = new URLSearchParams(location.search).get('state');</script></body></html>`;
+const fails = (results) => results.filter((r) => r[0] === 'FAIL').map((r) => r[1]);
+
+test('checkMock: a mock inside the contract passes every platform rule', () => {
+  assert.deepEqual(fails(mock.checkMock(GOOD_MOCK)), []);
+});
+
+test('checkMock: the platform rules catch a page :root, a literal colour, a pinned pack colour, JS motion', () => {
+  const f1 = fails(mock.checkMock(GOOD_MOCK.replace('<style>', '<style>:root{--x:1}')));
+  assert.ok(f1.some((r) => r.startsWith('no page-local :root')), f1.join(' | '));
+  const f2 = fails(mock.checkMock(GOOD_MOCK.replace('color:var(--ink)', 'color:#ff0000')));
+  assert.ok(f2.some((r) => r.startsWith('no literal hex colour')), f2.join(' | '));
+  const f3 = fails(mock.checkMock(GOOD_MOCK.replace('color:var(--ink)', 'color:#fb9569'), { packColors: { accent: '#fb9569' } }));
+  assert.ok(f3.some((r) => r.startsWith('no pack colour pinned')), f3.join(' | '));
+  const f4 = fails(mock.checkMock(GOOD_MOCK.replace('<script>', '<script>requestAnimationFrame(() => {});')));
+  assert.ok(f4.some((r) => r.startsWith('no motion in JavaScript')), f4.join(' | '));
+  const f5 = fails(mock.checkMock(GOOD_MOCK.replace(':root[data-mode="dark"] body{--pad:9px}', ':root[data-mode="dark"] body{--pad:10px}')));
+  assert.ok(f5.some((r) => r.startsWith('every dark rule written twice')), f5.join(' | '));
+});
+
+test('checkMock: a taste ban applies only when the instance declared it', () => {
+  const dashed = GOOD_MOCK.replace('Plain copy.', 'Plain — copy.');
+  const withBan = mock.checkMock(dashed, { bans: new Set(['em-dash']) });
+  assert.ok(fails(withBan).some((r) => r.startsWith('taste: no em/en dash')));
+  const withoutBan = mock.checkMock(dashed, { bans: new Set() });
+  assert.deepEqual(fails(withoutBan), []);
+  assert.ok(!withoutBan.some((r) => r[1].startsWith('taste:')), 'no taste rule is even evaluated without a ban');
+});
+
+test('readDesignBans reads the Don\'t section — the live DESIGN.md declares the five, an empty file none', () => {
+  const live = mock.readDesignBans(fs.readFileSync(path.join(ROOT, 'DESIGN.md'), 'utf8'));
+  for (const k of ['em-dash', 'emoji', 'gradient-text', 'text-glow', 'box-shadow']) assert.ok(live.has(k), `live DESIGN.md bans ${k}`);
+  assert.equal(mock.readDesignBans('').size, 0);
+  assert.deepEqual([...mock.readDesignBans("## Do's and Don'ts\n\n### Do\n- Do use an em dash.\n\n### Don't\n- Don't use emoji.\n\n## Next\n")], ['emoji'], 'only the Don\'t section counts');
+});
+
+// ── the pack ──────────────────────────────────────────────────────────────────
+test('the neutral pack clears the text floor on its own grounds (both pack shapes)', () => {
+  const filePack = readJson('config/branding.neutral.json');
+  const rows = contrast.packContrast(filePack);
+  const onGrounds = rows.filter((r) => r.bg === 'bg' || r.bg === 'bgCard');
+  assert.ok(onGrounds.length >= 6);
+  for (const r of onGrounds) assert.equal(r.ok, true, `${r.fg} on ${r.bg}: ${r.ratio} (need ${r.need})`);
+  const clientShape = { theme: filePack.theme.ui };
+  assert.deepEqual(contrast.packContrast(clientShape), rows, 'clientBranding() flattens theme.ui onto theme; same answer');
+});
+
+test('the WCAG maths: black on white is 21:1, alpha composites before it is measured', () => {
+  assert.equal(+lib.contrastRatio(lib.parseColor('#000'), lib.parseColor('#ffffff')).toFixed(1), 21);
+  const half = lib.composite(lib.parseColor('rgba(0,0,0,0.5)'), lib.parseColor('#fff'));
+  assert.ok(Math.abs(half[0] - 127.5) < 0.01);
+  assert.equal(lib.parseColor('nope'), null);
+});
+
+// ── the CLIs: exit codes are the contract a caller can script against ───────────
+test('render.js: usage and a broken states file exit 2 with the reason, before any browser', () => {
+  const noArgs = run('render.js', []);
+  assert.equal(noArgs.status, lib.EXIT.USAGE); assert.match(noArgs.stderr, /--page/);
+  const missing = run('render.js', ['--states', path.join(os.tmpdir(), 'no-such.states.json')]);
+  assert.equal(missing.status, lib.EXIT.USAGE); assert.match(missing.stderr, /not found/);
+  const bad = run('render.js', ['--states', tmp('x.states.json', JSON.stringify({ page: 'projects', states: { a: { actions: [['fly']] } } }))]);
+  assert.equal(bad.status, lib.EXIT.USAGE);
+  assert.match(bad.stderr, /page: required/); assert.match(bad.stderr, /unknown action "fly"/);
+  const noSidecar = run('render.js', ['--page', '/nowhere']);
+  assert.equal(noSidecar.status, lib.EXIT.USAGE); assert.match(noSidecar.stderr, /no states file beside the surface/);
+});
+
+test('probe.js and check-mock.js: the same discipline', () => {
+  const bad = run('probe.js', ['--probes', tmp('x.probes.json', JSON.stringify({ page: '/', probes: [{ name: 'n', steps: [] }] }))]);
+  assert.equal(bad.status, lib.EXIT.USAGE); assert.match(bad.stderr, /expect: required/);
+  assert.equal(run('check-mock.js', []).status, lib.EXIT.USAGE);
+  const failing = run('check-mock.js', ['--file', tmp('m.html', GOOD_MOCK.replace('<style>', '<style>:root{--x:1}')), '--no-taste']);
+  assert.equal(failing.status, lib.EXIT.PROBLEMS); assert.match(failing.stdout, /FAIL no page-local :root/);
+  const passing = run('check-mock.js', ['--file', tmp('m.html', GOOD_MOCK), '--no-taste']);
+  assert.equal(passing.status, lib.EXIT.CLEAN, passing.stdout); assert.match(passing.stdout, /ALL RULES PASS/);
+});
+
+test('serve.js refuses a surface that does not resolve, and serves one through the doorway transforms', async () => {
+  const bad = run('serve.js', [], { SURFACE: 'no-such-surface', STUB_PORT: '0' });
+  assert.equal(bad.status, lib.EXIT.USAGE); assert.match(bad.stderr, /neither a directory/);
+  for (const auth of [false, true]) {
+    const s = await lib.startStub({ surface: 'public-landing', auth });
+    try {
+      const html = await (await fetch(s.base + '/')).text();
+      assert.ok(html.includes('window.__BRANDING__'), 'the pack is injected');
+      assert.ok(/:root\s*\{/.test(html), 'the theme :root is spliced');
+      assert.ok(/\?v=[0-9a-f]{8}/.test(html), 'assets are content-stamped');
+      const me = await fetch(s.base + '/api/bongos/me');
+      assert.equal(me.status, auth ? 200 : 401);
+      if (auth) { const body = await me.json(); assert.ok(body.builder && body.builder.github_login, 'the real { builder } shape'); assert.match(body.builder.avatar_url, /^http:\/\/127\.0\.0\.1:\d+\/__kit\/avatar\.svg$/); }
+      assert.equal((await fetch(s.base + '/api/gds/public/progress')).status, 200, 'the public feed answers from a fixture');
+      assert.equal((await fetch(s.base + '/api/gds/nope')).status, 404);
+    } finally { s.stop(); }
+  }
+  const child = await lib.startStub({ surface: 'public-landing', child: true });
+  try {
+    const html = await (await fetch(child.base + '/')).text();
+    assert.equal((html.match(/<!--apex-only:start-->/g) || []).length, 0, 'the child shape strips the apex-only regions');
+  } finally { child.stop(); }
+});