@nurix/etna 0.19.11 → 0.19.12

package/data/harnesses/code/skills/design/scripts/lib/golden.mjs

@@ -1,26 +0,0 @@
-// skills/design/scripts/lib/golden.mjs — golden-CSS comparison primitives: comment stripping + sha256 hashing for the byte-match regression oracle.
-
-import { createHash } from "node:crypto";
-
-// Remove every /* ... */ comment block (CSS has no other comment syntax; an unterminated comment strips to EOF) — no whitespace normalization, byte-exact otherwise.
-export function stripCssComments(css) {
-  let out = "";
-  let i = 0;
-  while (i < css.length) {
-    const open = css.indexOf("/*", i);
-    if (open === -1) {
-      out += css.slice(i);
-      break;
-    }
-    out += css.slice(i, open);
-    const close = css.indexOf("*/", open + 2);
-    if (close === -1) break; // unterminated comment: strip to EOF
-    i = close + 2;
-  }
-  return out;
-}
-
-// sha256 hex digest of stripCssComments(css) — the golden fingerprint of one emitted CSS file.
-export function goldenHash(css) {
-  return createHash("sha256").update(stripCssComments(css), "utf8").digest("hex");
-}

package/data/harnesses/code/skills/design/scripts/lib/vocabulary.mjs

@@ -1,65 +0,0 @@
-// skills/design/scripts/lib/vocabulary.mjs — single-source shared runtime vocabulary for the design skill's scripts: the delight-budget enum + file-header stamps, the surface-archetype budget defaults, the motion-moment class names, and the theme attribute convention. scaffold.mjs writes these strings; phase-gate.mjs reads them at the surfaces gate; the preship sweep and emission read them in later steps. One module so the stamp text, the enum, and the theme names never drift between the writer and its readers.
-
-// The two delight-budget values a surface can carry (references/structure.md, the delight budget).
-export const BUDGETS = ['baseline', 'brand-forward'];
-
-// The verbatim file-header comment scaffold.mjs writes at the top of each surface route file, keyed by budget.
-export const BUDGET_STAMPS = {
-  baseline: '// Surface: baseline',
-  'brand-forward': '// Surface: brand-forward (delight-allowing)',
-};
-
-// The stamp comment for a budget, or null when it is not one of BUDGETS.
-export function stampFor(budget) {
-  return Object.prototype.hasOwnProperty.call(BUDGET_STAMPS, budget) ? BUDGET_STAMPS[budget] : null;
-}
-
-// Matches any `// Surface:` header line, well-formed or not — gates count these to catch a malformed
-// or duplicated stamp against the well-formed matches below.
-export const BUDGET_STAMP_LOOSE_RE = /\/\/ Surface:.*/g;
-
-// Every well-formed budget stamp in a source blob, in order, as budget values ('baseline' | 'brand-forward').
-// Gates count occurrences (exactly one per route file) and read the stamped budget from this.
-export function findBudgetStamps(source) {
-  const re = /\/\/ Surface: (brand-forward \(delight-allowing\)|baseline)(?=\s|$)/g;
-  const found = [];
-  let m;
-  while ((m = re.exec(String(source))) !== null) {
-    found.push(m[1].startsWith('brand-forward') ? 'brand-forward' : 'baseline');
-  }
-  return found;
-}
-
-// Surface archetypes whose delight budget defaults to `baseline` — a `brand-forward` stamp on one of
-// these needs a recorded reason in the surface map (references/structure.md, the delight budget).
-export const BASELINE_DEFAULT_ARCHETYPES = ['list-detail', 'log-stream', 'command-center'];
-
-// Surface archetypes that are `brand-forward` *candidates* — granted when the look's delight is
-// expressive or the brief asks for presence, else baseline; no recorded reason needed either way.
-export const BRAND_FORWARD_CANDIDATE_ARCHETYPES = ['dashboard', 'entity-detail', 'create-edit'];
-
-// True when a `brand-forward` stamp on this archetype requires a recorded reason in the surface map.
-export function requiresBudgetReason(archetype, budget) {
-  return budget === 'brand-forward' && BASELINE_DEFAULT_ARCHETYPES.includes(String(archetype));
-}
-
-// Motion-moment CSS classes (references/structure.md the delight budget; data/combinations/motion.csv).
-// scaffold consumes them where the archetype calls: table rows ride motion-lift (hover feedback,
-// budget-free); card grids ride motion-stagger on brand-forward surfaces only — baseline-stamped
-// surfaces skip arrival cascades (mot-08). The render rung audits rendered stagger containers.
-export const MOTION_LIFT_CLASS = 'motion-lift';
-export const MOTION_STAGGER_CLASS = 'motion-stagger';
-// The derived custom property the stagger cascade reads; cap the staggered children at STAGGER_CHILD_CAP.
-export const STAGGER_DELAY_VAR = '--stagger-delay';
-export const STAGGER_CHILD_CAP = 8;
-
-// The theme runtime attribute: its name and the two legal rendered values. look.theme `both` boots
-// light with a working toggle, so the emitted default is always one of these two.
-export const THEME_ATTR = 'data-theme';
-export const THEME_VALUES = ['light', 'dark'];
-
-// Resolve a look.theme (light | dark | both) to the emitted default data-theme value (both → light);
-// anything unrecognized falls back to light.
-export function resolveThemeDefault(theme) {
-  return theme === 'dark' ? 'dark' : 'light';
-}

package/data/harnesses/code/skills/design/scripts/phase-gate.mjs

@@ -1,538 +0,0 @@
-// skills/design/scripts/phase-gate.mjs — create-phase precondition gates (D21/D23): validate the named phase's exit preconditions, printing the exact fix on failure; every gate also fires the machine-check engine (lib/checks.mjs — per-file catalog + manifest drift) over the project's whole UI tree and exits non-zero on either failure.
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname, resolve, relative } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
-import { runChecks, formatFindings, walkUiFiles } from './lib/checks.mjs';
-import { findBudgetStamps, BUDGET_STAMP_LOOSE_RE, requiresBudgetReason } from './lib/vocabulary.mjs';
-
-const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
-const PHASES = ['intake', 'structure', 'scaffold', 'tokens', 'fixtures', 'surfaces'];
-const ARCHETYPES = new Set(['list-detail', 'dashboard', 'entity-detail', 'create-edit', 'log-stream', 'command-center']);
-const PROVENANCE = new Set(['project', 'extracted', 'library', 'default']);
-const STATE_SYNONYMS = { loading: ['loading', 'skeleton'], empty: ['empty'], error: ['error'], partial: ['partial', 'degraded', 'stale'] };
-// The intake look block's enums (references/create.md, the look block). theme carries `both`; the emitted
-// data-theme value the attribute cascade uses is light|dark (both boots light) — that pair lives in vocabulary.mjs.
-const LOOK_THEMES = new Set(['light', 'dark', 'both']);
-const DELIGHT_LEVELS = new Set(['baseline', 'expressive']);
-const RESOLUTION_MODES = new Set(['confirmed', 'recorded']);
-// The resolution spine's legal shapes: project | library:<slug> | seed:<style-row>+<palette-row> | default.
-const RESOLUTION_RE = /^(project|default|library:.+|seed:.+\+.+)$/i;
-
-const useColor = process.stdout.isTTY;
-// Wrap a string in green/red when writing to a TTY, plain otherwise.
-const green = (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s);
-const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
-
-// Read a UTF-8 file, returning '' when it is absent.
-function readText(path) {
-  try { return readFileSync(path, 'utf8'); } catch { return ''; }
-}
-
-// Sentinel a gate throws (via fail) to abort its remaining precondition checks without exiting the process.
-class GateFailure extends Error {}
-
-// Report a passing gate as one green line (the process exit code is decided in main, after the source sweep).
-function pass(phase, msg) {
-  console.log(`${green(`PASS  phase-gate[${phase}]`)}  ${msg}`);
-}
-
-// Report a failing gate with the problem and the exact fix, then abort the gate.
-function fail(phase, problem, fixLines) {
-  console.error(`${red(`FAIL  phase-gate[${phase}]`)}  ${problem}`);
-  console.error('');
-  console.error('  Fix:');
-  for (const line of fixLines) {
-    if (line == null || line === '') continue;
-    for (const sub of String(line).split('\n')) console.error(`    ${sub}`);
-  }
-  throw new GateFailure(problem);
-}
-
-// Lowercase-kebab a display name for route-dir / fixture-module matching.
-function kebab(s) {
-  return String(s).trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-}
-
-// Return the first non-parameter path segment of a route (/tickets/:id -> tickets).
-function firstStaticSegment(route) {
-  for (const p of String(route).split('/').filter(Boolean)) {
-    if (!p.startsWith(':')) return kebab(p);
-  }
-  return null;
-}
-
-// Return the last non-parameter path segment of a route (/tickets/new -> new).
-function lastStaticSegment(route) {
-  const parts = String(route).split('/').filter(Boolean).filter((p) => !p.startsWith(':'));
-  return parts.length ? kebab(parts[parts.length - 1]) : null;
-}
-
-// Parse a JSON file into an object, or null when it is absent or malformed.
-function readJson(path) {
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    return parsed && typeof parsed === 'object' ? parsed : null;
-  } catch { return null; }
-}
-
-// Collect every token file the resolver references (set values plus all modifier-context overlays).
-function resolverNamedFiles(resolver) {
-  const named = [];
-  for (const set of Array.isArray(resolver.sets) ? resolver.sets : []) {
-    if (set && Array.isArray(set.values)) named.push(...set.values.filter((f) => typeof f === 'string'));
-  }
-  for (const mod of Array.isArray(resolver.modifiers) ? resolver.modifiers : []) {
-    const contexts = mod && mod.contexts && typeof mod.contexts === 'object' ? mod.contexts : {};
-    for (const files of Object.values(contexts)) {
-      if (Array.isArray(files)) named.push(...files.filter((f) => typeof f === 'string'));
-    }
-  }
-  return named;
-}
-
-// Split a `[a, b, c]` inline list into trimmed members.
-function parseBracketList(s) {
-  const m = String(s).match(/\[([^\]]*)\]/);
-  if (!m) return [];
-  return m[1].split(',').map((x) => x.trim()).filter(Boolean);
-}
-
-// Store one `key: value` pair onto a list-item object, parsing `states` into an array.
-function applyKV(obj, s) {
-  const idx = s.indexOf(':');
-  if (idx < 0) return;
-  const key = s.slice(0, idx).trim();
-  const value = s.slice(idx + 1).trim();
-  if (key === 'states') obj.states = parseBracketList(value);
-  else obj[key] = value;
-}
-
-// Parse the fenced ```yaml structure block into entities, surfaces, and temporal facts.
-function parseStructureBlock(md) {
-  const m = md.match(/```yaml structure\r?\n([\s\S]*?)```/);
-  if (!m) return null;
-  const result = { unitOfWork: null, coreLoop: null, entities: [], temporal: null, surfaces: [] };
-  let section = null;
-  let itemIndent = -1;
-  let current = null;
-  for (const raw of m[1].split(/\r?\n/)) {
-    if (!raw.trim() || raw.trim().startsWith('#')) continue;
-    const indent = raw.length - raw.trimStart().length;
-    const line = raw.trim();
-    if (indent === 0) {
-      current = null;
-      itemIndent = -1;
-      if (line.startsWith('unit-of-work:')) { result.unitOfWork = line.slice(line.indexOf(':') + 1).trim(); section = null; }
-      else if (line.startsWith('core-loop:')) { result.coreLoop = line.slice(line.indexOf(':') + 1).trim(); section = null; }
-      else if (line === 'entities:') section = 'entities';
-      else if (line === 'surfaces:') section = 'surfaces';
-      else if (line === 'temporal:') { section = 'temporal'; result.temporal = {}; }
-      else section = null;
-      continue;
-    }
-    if (section === 'entities' || section === 'surfaces') {
-      const list = section === 'entities' ? result.entities : result.surfaces;
-      if (line.startsWith('- ')) {
-        if (itemIndent === -1) itemIndent = indent;
-        if (indent === itemIndent) {
-          current = {};
-          list.push(current);
-          const rest = line.slice(2).trim();
-          if (rest && rest.includes(':')) applyKV(current, rest);
-        }
-      } else if (current && itemIndent !== -1 && indent > itemIndent) {
-        applyKV(current, line);
-      }
-    } else if (section === 'temporal') {
-      const idx = line.indexOf(':');
-      if (idx > 0) result.temporal[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
-    }
-  }
-  return result;
-}
-
-// Read and parse the structure map, or fail the gate with the structure-phase fix.
-function requireMap(phase, project) {
-  const p = join(project, 'docs/design/structure.md');
-  if (!existsSync(p)) {
-    fail(phase, `No entity/surface map at ${p} — this phase reads it.`, [
-      'Complete the structure phase first: derive docs/design/structure.md with a fenced ```yaml structure block (references/structure.md).',
-    ]);
-  }
-  const blk = parseStructureBlock(readText(p));
-  if (!blk) {
-    fail(phase, `${p} has no parseable "yaml structure" fenced block.`, [
-      'The block must open exactly with the fence info-string `yaml structure` and carry entities[], temporal, and surfaces[].',
-    ]);
-  }
-  return blk;
-}
-
-// Collect all .ts/.tsx source under a route directory into one lowercased blob.
-function routeSource(dir) {
-  return routeSourceRaw(dir).toLowerCase();
-}
-
-// Collect all .ts/.tsx source under a route directory, case preserved (the budget stamp is case-sensitive).
-function routeSourceRaw(dir) {
-  let out = '';
-  const stack = [dir];
-  while (stack.length) {
-    const cur = stack.pop();
-    let entries;
-    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { continue; }
-    for (const ent of entries) {
-      const full = join(cur, ent.name);
-      if (ent.isDirectory()) stack.push(full);
-      else if (/\.(tsx|ts)$/.test(ent.name)) out += `\n${readText(full)}`;
-    }
-  }
-  return out;
-}
-
-// Return the candidate route-dir slugs for a surface (name-kebab, route segments, archetype).
-function routeDirCandidates(s) {
-  const out = [];
-  if (s.name) out.push(kebab(s.name));
-  if (s.route) { const f = firstStaticSegment(s.route); if (f) out.push(f); const l = lastStaticSegment(s.route); if (l) out.push(l); }
-  if (s.archetype) out.push(s.archetype);
-  return [...new Set(out.filter(Boolean))];
-}
-
-// Resolve a surface's route directory to the first existing candidate, or null.
-function resolveRouteDir(s, routesDir) {
-  for (const c of routeDirCandidates(s)) {
-    const d = join(routesDir, c);
-    if (existsSync(d) && statSync(d).isDirectory()) return d;
-  }
-  return null;
-}
-
-// List the declared states whose branch is absent from a route's shell source.
-function missingStates(dir, states) {
-  const text = routeSource(dir);
-  return states.filter((st) => {
-    const words = STATE_SYNONYMS[st] || [st.toLowerCase()];
-    return !words.some((w) => text.includes(w));
-  });
-}
-
-// Validate the load-bearing five-step globals.css import order (Cascade Contract 2).
-function checkImportOrder(rawCss) {
-  const css = rawCss.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '');
-  const marks = [
-    ['@import "./personality.css"', css.indexOf('@import "./personality.css"')],
-    ['@import "tailwindcss"', css.indexOf('@import "tailwindcss"')],
-    ['@import "@nurix/components/styles.css"', css.indexOf('@import "@nurix/components/styles.css"')],
-    ['@theme inline', css.search(/^\s*@theme\s+inline\b/m)],
-  ];
-  const absent = marks.filter(([, i]) => i < 0).map(([n]) => n);
-  if (absent.length) {
-    return { problem: `globals.css is missing: ${absent.join(', ')}.`, fix: [
-      'Emit the five-step cascade order (references/personality.md §4, Cascade Contract 2):',
-      '@import "./personality.css"; -> @import "tailwindcss"; -> @import "@nurix/components/styles.css"; -> @theme inline { ... }',
-    ] };
-  }
-  const [p, t, l, th] = marks.map(([, i]) => i);
-  if (!(p < t && t < l && l < th)) {
-    return { problem: 'globals.css import order is wrong — personality -> tailwindcss -> library -> @theme is load-bearing.', fix: [
-      'Reorder so the consumer @theme inline comes AFTER the @nurix/components/styles.css import, or the library radius scale and token defaults win.',
-    ] };
-  }
-  return null;
-}
-
-// Validate the payload's mandatory look block (references/create.md, the look block): presence, the theme /
-// delight / resolution-mode enums, 2–3 named anchor strings, the resolution shape, and — when the
-// resolution was authorized autonomously (resolution-mode: recorded) — that the artifact root
-// $description carries a resolution record naming the runner-up. Fails the gate with the exact fix.
-function validateLookBlock(payload, tokens) {
-  const look = payload.look;
-  if (!look || typeof look !== 'object' || Array.isArray(look)) {
-    fail('intake', 'payload carries no look block (payload.look).', [
-      'Add the mandatory look block to the artifact payload (references/create.md, the look block):',
-      'look: { theme: light|dark|both, anchors: ["Product A", "Product B"], delight: baseline|expressive,',
-      '        resolution: project | library:<slug> | seed:<style>+<palette> | default, resolution-mode: confirmed|recorded }.',
-    ]);
-  }
-  if (!LOOK_THEMES.has(look.theme)) {
-    fail('intake', `look.theme is "${look.theme ?? '(missing)'}"; must be light | dark | both.`, [
-      'Set look.theme from the brief; it is binding when stated, default light (references/create.md, the look block).',
-    ]);
-  }
-  if (!DELIGHT_LEVELS.has(look.delight)) {
-    fail('intake', `look.delight is "${look.delight ?? '(missing)'}"; must be baseline | expressive.`, [
-      'Set look.delight — the global delight ceiling per-surface budgets refine (references/create.md the look block, references/structure.md the delight budget).',
-    ]);
-  }
-  const mode = look['resolution-mode'];
-  if (!RESOLUTION_MODES.has(mode)) {
-    fail('intake', `look.resolution-mode is "${mode ?? '(missing)'}"; must be confirmed | recorded.`, [
-      'Set look.resolution-mode: confirmed when a confirmer authorized the pick, recorded when it was resolved autonomously (references/create.md, Resolution).',
-    ]);
-  }
-  const anchors = look.anchors;
-  if (!Array.isArray(anchors) || anchors.length < 2 || anchors.length > 3 || !anchors.every((a) => typeof a === 'string' && a.trim())) {
-    fail('intake', `look.anchors must be 2–3 non-empty named strings; got ${JSON.stringify(anchors ?? null)}.`, [
-      'Name two or three real products (["Linear", "Stripe Dashboard"]); adjectives are not anchors —',
-      'convert an adjective to a named product by asking (interactive) or inferring-and-recording (autonomous) via the design-md resemblance lookup (references/create.md, the look block).',
-    ]);
-  }
-  if (typeof look.resolution !== 'string' || !RESOLUTION_RE.test(look.resolution.trim())) {
-    fail('intake', `look.resolution is "${look.resolution ?? '(missing)'}"; must match project | library:<slug> | seed:<style>+<palette> | default.`, [
-      'Set look.resolution to the resolved source from the precedence spine (references/create.md, Resolution).',
-    ]);
-  }
-  if (mode === 'recorded') {
-    const desc = tokens.$description;
-    if (typeof desc !== 'string' || !desc.trim() || !/runner-up/i.test(desc)) {
-      fail('intake', 'resolution-mode is recorded but the artifact root $description carries no resolution record naming the runner-up.', [
-        'Write the resolution record into the artifact root $description — winner, runner-up, and the deciding evidence, e.g.:',
-        'resolution: library:stripe (recorded; runner-up palettes.csv#3; brief phrase "Stripe-dashboard territory" matched product + fintech traits).',
-        'A recorded (autonomous) resolution is legitimate only once it is auditable (references/create.md, Resolution).',
-      ]);
-    }
-  }
-}
-
-// intake gate: a structurally sound design-tokens artifact sits at project root — both files parse, the dark
-// file agrees with the resolver, the payload carries a legal schema/provenance/product, and the mandatory
-// look block is present and well-formed. Light checks only; deep validation (coverage, aliases, parse-back)
-// is derive-personality.mjs --check at the tokens gate.
-function gateIntake(project) {
-  const tokensPath = join(project, 'design.tokens.json');
-  const resolverPath = join(project, 'design.resolver.json');
-  const absent = [tokensPath, resolverPath].filter((p) => !existsSync(p)).map((p) => relative(project, p));
-  if (absent.length) {
-    fail('intake', `Missing token-artifact file(s) at project root: ${absent.join(', ')}.`, [
-      'Write the design-tokens artifact against skills/design/data/design-tokens/SCHEMA.md:',
-      'design.tokens.json (base/light set + the $extensions["com.nurix.design"] payload) and design.resolver.json,',
-      'plus design.tokens.dark.json only when the look has dark values.',
-      'Resolve the look artifact-first: the project artifact wins, else a confirmed library entry, else the Nurix default.',
-    ]);
-  }
-  const tokens = readJson(tokensPath);
-  if (!tokens) fail('intake', 'design.tokens.json does not parse as JSON.', ['Fix the JSON before anything deeper runs (data/design-tokens/SCHEMA.md).']);
-  const resolver = readJson(resolverPath);
-  if (!resolver) fail('intake', 'design.resolver.json does not parse as JSON.', ['Fix the JSON (data/design-tokens/SCHEMA.md — the resolver section).']);
-  const namesDark = resolverNamedFiles(resolver).includes('design.tokens.dark.json');
-  const hasDark = existsSync(join(project, 'design.tokens.dark.json'));
-  if (namesDark && !hasDark) {
-    fail('intake', 'design.resolver.json names design.tokens.dark.json but the file is absent.', [
-      'Ship the dark modifier set beside the base file, or drop the dark context from the resolver —',
-      'the dark file exists exactly when the resolver names it (data/design-tokens/SCHEMA.md).',
-    ]);
-  }
-  if (!namesDark && hasDark) {
-    fail('intake', 'design.tokens.dark.json is present but the resolver names no dark context.', [
-      'Add "dark": ["design.tokens.dark.json"] to the theme modifier contexts, or remove the dark file —',
-      'the dark file exists exactly when the resolver names it (data/design-tokens/SCHEMA.md).',
-    ]);
-  }
-  const payload = tokens.$extensions && tokens.$extensions['com.nurix.design'];
-  if (!payload || typeof payload !== 'object') {
-    fail('intake', 'design.tokens.json carries no root $extensions["com.nurix.design"] payload.', [
-      'Add the file-level payload (schema, dtcg, product, provenance, sourced, lever-manifest, …) per data/design-tokens/SCHEMA.md.',
-    ]);
-  }
-  if (payload.schema !== 'design-tokens/v2') fail('intake', `payload schema is "${payload.schema || '(missing)'}", expected design-tokens/v2.`, ['Set schema: "design-tokens/v2" in the payload (data/design-tokens/SCHEMA.md).']);
-  if (!PROVENANCE.has(payload.provenance)) fail('intake', `payload provenance is "${payload.provenance || '(missing)'}"; must be one of project|extracted|library|default.`, ['Set provenance to one of: project | extracted | library | default (data/design-tokens/SCHEMA.md).']);
-  if (typeof payload.product !== 'string' || !payload.product.trim()) fail('intake', 'payload product is missing or empty.', ['Set product to the product name; slugified it becomes the data-style value (data/design-tokens/SCHEMA.md).']);
-  validateLookBlock(payload, tokens);
-  pass('intake', `design.tokens.json + design.resolver.json present and parsing; payload schema design-tokens/v2, provenance "${payload.provenance}"${namesDark ? ', dark set named and present' : ', light-only'}; look block valid (theme ${payload.look.theme}, delight ${payload.look.delight}, ${Array.isArray(payload.look.anchors) ? payload.look.anchors.length : 0} anchors, resolution-mode ${payload.look['resolution-mode']}).`);
-}
-
-// structure gate: the map parses, is populated, has a temporal block, and every surface archetype is one of the six.
-function gateStructure(project) {
-  const blk = requireMap('structure', project);
-  if (!blk.entities.length) fail('structure', 'The structure map has no entities — the object pass was skipped.', ['Populate entities[] from the domain nouns (references/structure.md -> object pass); a small brief earns a small pass, never a skipped one.']);
-  if (!blk.surfaces.length) fail('structure', 'The structure map has no surfaces.', ['Assign each surface an archetype from the closed six under surfaces[].']);
-  if (!blk.temporal || !Object.keys(blk.temporal).length) fail('structure', 'The structure map has no temporal block.', ['Add the temporal probe (intermediate-states, read-model-lag, deletion, failure-paths) — model facts, not later polish.']);
-  const bad = blk.surfaces.filter((s) => !ARCHETYPES.has(s.archetype));
-  if (bad.length) {
-    fail('structure', `${bad.length} surface(s) carry an archetype outside the closed six: ${bad.map((s) => `${s.name || '(unnamed)'}="${s.archetype || '(none)'}"`).join(', ')}.`, [
-      `Every surface's archetype must be one of: ${[...ARCHETYPES].join(', ')}.`,
-    ]);
-  }
-  pass('structure', `${blk.surfaces.length} surface(s), all archetypes valid; ${blk.entities.length} entit(ies) and a temporal block present.`);
-}
-
-// scaffold gate: the shell, per-surface route dirs + state-shells, router wiring, and globals.css import order are in place.
-function gateScaffold(project) {
-  const blk = requireMap('scaffold', project);
-  const shellFiles = ['index.html', 'src/main.tsx', 'src/App.tsx'];
-  const missing = shellFiles.filter((f) => !existsSync(join(project, f)));
-  if (missing.length) {
-    fail('scaffold', `Missing shell file(s): ${missing.join(', ')}.`, [
-      `Run scaffold.mjs docs/design/structure.md --out ${project} to emit index.html, src/main.tsx, src/App.tsx, route wiring, and state-shells.`,
-    ]);
-  }
-  const indexHtml = readText(join(project, 'index.html'));
-  if (!/<html[^>]*\bdata-style=/.test(indexHtml)) {
-    fail('scaffold', 'index.html <html> is missing the data-style attribute.', [
-      'Emit <html data-style="..." data-density="..." data-verbosity="..." data-feedback="..." data-theme="light"> (references/personality.md §5).',
-    ]);
-  }
-  const routesDir = join(project, 'src/routes');
-  const app = readText(join(project, 'src/App.tsx'));
-  const noRoute = [];
-  const noWire = [];
-  const noShell = [];
-  for (const s of blk.surfaces) {
-    const dir = resolveRouteDir(s, routesDir);
-    const name = s.name || s.route || '(unnamed)';
-    if (!dir) { noRoute.push(`${name} (expected src/routes/${routeDirCandidates(s).join(' or /')})`); continue; }
-    const seg = s.route ? firstStaticSegment(s.route) : null;
-    if (seg && !app.toLowerCase().includes(seg)) noWire.push(`${name} (route "${s.route}" not referenced in src/App.tsx)`);
-    const states = (s.states && s.states.length) ? s.states : ['loading', 'empty', 'error', 'partial'];
-    const miss = missingStates(dir, states);
-    if (miss.length) noShell.push(`${name} (no ${miss.join(', ')} shell)`);
-  }
-  if (noRoute.length) fail('scaffold', `No route directory for surface(s): ${noRoute.join('; ')}.`, ['scaffold.mjs owns route/nav wiring — emit src/routes/<surface>/ per surface from the map.']);
-  if (noWire.length) fail('scaffold', `Route(s) not wired into the router: ${noWire.join('; ')}.`, ['Every surface route must be registered in src/App.tsx (react-router-dom) — routes and nav derive from the map, never decorated on.']);
-  if (noShell.length) fail('scaffold', `Missing state-shell stubs: ${noShell.join('; ')}.`, ['Each surface needs its loading / empty / error / degraded shells wired (references/create.md -> scaffold).']);
-  const globals = join(project, 'src/styles/globals.css');
-  if (!existsSync(globals)) fail('scaffold', 'Missing src/styles/globals.css (Tailwind glue with the five-step import order).', ['Emit src/styles/globals.css with the Cascade Contract 2 import order (references/personality.md §4).']);
-  const orderErr = checkImportOrder(readText(globals));
-  if (orderErr) fail('scaffold', orderErr.problem, orderErr.fix);
-  pass('scaffold', `Shell, ${blk.surfaces.length} wired route dir(s) with state-shells, and globals.css import order all in place.`);
-}
-
-// tokens gate: the design-tokens artifact clears the coverage gate (derive-personality.mjs <project> --check) and both CSS files are emitted with the cascade order intact.
-function gateTokens(project) {
-  const tokensPath = join(project, 'design.tokens.json');
-  if (!existsSync(tokensPath)) fail('tokens', `No design.tokens.json at ${tokensPath}.`, ['Resolve and materialize the design-tokens artifact first (intake phase; data/design-tokens/SCHEMA.md).']);
-  const derive = join(SCRIPT_DIR, 'derive-personality.mjs');
-  if (!existsSync(derive)) fail('tokens', `Coverage-gate sibling not found: ${derive}.`, ['derive-personality.mjs must sit beside phase-gate.mjs in the scripts/ directory.']);
-  const res = spawnSync(process.execPath, [derive, project, '--check'], { encoding: 'utf8' });
-  if (res.status !== 0) {
-    const detail = `${res.stdout || ''}${res.stderr || ''}`.trim();
-    fail('tokens', `The token-artifact coverage gate failed (derive-personality.mjs --check exited ${res.status == null ? '(spawn error)' : res.status}).`, [
-      'Assign or hint every named token path below, then re-run this gate:',
-      detail,
-    ]);
-  }
-  const files = ['src/styles/personality.css', 'src/styles/globals.css'];
-  const miss = files.filter((f) => !existsSync(join(project, f)));
-  if (miss.length) {
-    fail('tokens', `Coverage gate passed but emitted CSS is missing: ${miss.join(', ')}.`, [
-      `Run derive-personality.mjs ${project} --emit ${project} to write src/styles/personality.css and src/styles/globals.css.`,
-    ]);
-  }
-  const orderErr = checkImportOrder(readText(join(project, 'src/styles/globals.css')));
-  if (orderErr) fail('tokens', orderErr.problem, orderErr.fix);
-  pass('tokens', 'Coverage gate green; personality.css + globals.css emitted with the cascade order intact.');
-}
-
-// fixtures gate: src/fixtures/ carries one seeded module per map entity.
-function gateFixtures(project) {
-  const blk = requireMap('fixtures', project);
-  const fdir = join(project, 'src/fixtures');
-  if (!existsSync(fdir)) {
-    fail('fixtures', 'No src/fixtures/ directory.', [
-      `Run generate-fixtures.mjs docs/design/structure.md --seed <n> --out ${join(project, 'src/fixtures/')} to write one seeded module per entity.`,
-    ]);
-  }
-  const bases = readdirSync(fdir).filter((f) => /\.(ts|tsx)$/.test(f)).map((f) => f.replace(/\.(ts|tsx)$/, '').toLowerCase());
-  const missing = [];
-  for (const e of blk.entities) {
-    if (!e.name) continue;
-    const base = e.name.toLowerCase();
-    const k = kebab(e.name);
-    const cands = new Set([base, k, `${base}s`, `${k}s`]);
-    if (/y$/.test(base)) { cands.add(`${base.slice(0, -1)}ies`); cands.add(`${k.slice(0, -1)}ies`); }
-    if (!bases.some((n) => cands.has(n))) missing.push(e.name);
-  }
-  if (missing.length) {
-    fail('fixtures', `No seeded fixture module for entity/ies: ${missing.join(', ')}.`, [
-      'Each map entity needs a seeded module in src/fixtures/ (fixture-before-surface). Re-run generate-fixtures.mjs.',
-    ]);
-  }
-  pass('fixtures', `Seeded fixture module present for all ${blk.entities.length} entit(ies).`);
-}
-
-// surfaces gate: every surface's route dir exists, its shell contains every declared state branch, and
-// it carries exactly one well-formed budget stamp — with a recorded budget-reason in the map when a
-// brand-forward stamp overrides a baseline-default archetype (references/structure.md, the delight budget). The
-// budget-gated vocabulary sweeps (display step typ-20, wash col-16) land with the rule catalog in a
-// later step; the stamp is parsed here via lib/vocabulary.mjs so those sweeps reuse the same reader.
-function gateSurfaces(project) {
-  const blk = requireMap('surfaces', project);
-  const routesDir = join(project, 'src/routes');
-  const problems = [];
-  for (const s of blk.surfaces) {
-    const name = s.name || s.route || '(unnamed)';
-    const dir = resolveRouteDir(s, routesDir);
-    if (!dir) { problems.push(`${name}: no route dir under src/routes/ (expected ${routeDirCandidates(s).join(' or ')})`); continue; }
-    const states = (s.states && s.states.length) ? s.states : ['loading', 'empty', 'error'];
-    const miss = missingStates(dir, states);
-    if (miss.length) problems.push(`${name}: shell missing state branch(es) ${miss.join(', ')}`);
-    const src = routeSourceRaw(dir);
-    const looseCount = (src.match(BUDGET_STAMP_LOOSE_RE) || []).length;
-    const stamps = findBudgetStamps(src);
-    if (looseCount === 0) {
-      problems.push(`${name}: no budget stamp at the top of the route file`);
-    } else if (stamps.length !== 1 || looseCount !== 1) {
-      problems.push(`${name}: expected exactly one well-formed budget stamp, found ${looseCount} "// Surface:" line(s) (${stamps.length} well-formed)`);
-    } else if (requiresBudgetReason(s.archetype, stamps[0]) && !(typeof s['budget-reason'] === 'string' && s['budget-reason'].trim())) {
-      problems.push(`${name}: brand-forward stamp on a ${s.archetype} surface (archetype defaults baseline) with no budget-reason in the surface map`);
-    }
-  }
-  if (problems.length) {
-    fail('surfaces', `${problems.length} surface(s) not fully composed. Handle these before finalizing:`, [
-      ...problems.map((p) => `- ${p}`),
-      'Fill every declared lifecycle state into its pre-created shell (references/create.md -> surfaces); states are composed with the surface, not bolted on.',
-      'Every surface route file carries exactly one stamp — "// Surface: baseline" or "// Surface: brand-forward (delight-allowing)"; scaffold.mjs writes it from the map budget, so re-classify by editing the surface budget in docs/design/structure.md and re-running scaffold.mjs.',
-      'A brand-forward stamp on a baseline-default archetype (list-detail / log-stream / command-center) needs a recorded budget-reason on that surface entry (references/structure.md, the delight budget).',
-    ]);
-  }
-  pass('surfaces', `All ${blk.surfaces.length} surface(s) have a route dir, every declared state branch, and exactly one legal budget stamp.`);
-}
-
-const GATES = { intake: gateIntake, structure: gateStructure, scaffold: gateScaffold, tokens: gateTokens, fixtures: gateFixtures, surfaces: gateSurfaces };
-
-// Fire the check engine over the project's whole UI tree (plus design.tokens.json manifest drift); print findings fix-or-classify style, return the violation count.
-function sourceSweep(project) {
-  const files = walkUiFiles(join(project, 'src'));
-  console.log('');
-  if (!files.length) {
-    console.log('source sweep: no src/**/*.{tsx,ts,css,html} files to scan.');
-    return 0;
-  }
-  const manifest = join(project, 'design.tokens.json');
-  const findings = runChecks(files, { manifestPath: existsSync(manifest) ? manifest : null })
-    .map((f) => ({ ...f, file: relative(project, f.file) || f.file }));
-  if (!findings.length) {
-    console.log(green(`source sweep: clean — ${files.length} file(s), no catalog or manifest-drift violations.`));
-    return 0;
-  }
-  console.log(formatFindings(findings, { color: useColor, label: 'source sweep' }));
-  return findings.length;
-}
-
-// Parse argv, resolve the project dir, dispatch to the named phase gate, then fire the whole-tree source sweep.
-function main() {
-  const args = process.argv.slice(2);
-  const phase = args[0];
-  let project = process.cwd();
-  for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--project') project = resolve(args[++i] || '.');
-    else if (args[i].startsWith('--project=')) project = resolve(args[i].slice('--project='.length));
-  }
-  if (!phase || !PHASES.includes(phase)) {
-    console.error(`usage: phase-gate.mjs <${PHASES.join('|')}> [--project <dir>]`);
-    process.exit(2);
-  }
-  let gateFailed = false;
-  try {
-    GATES[phase](project);
-  } catch (e) {
-    if (!(e instanceof GateFailure)) throw e;
-    gateFailed = true;
-  }
-  const sweepCount = sourceSweep(project);
-  process.exit(gateFailed || sweepCount > 0 ? 1 : 0);
-}
-
-main();