@nurix/etna 0.18.19 → 0.18.21

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

@@ -0,0 +1,26 @@
+// 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/phase-gate.mjs

@@ -0,0 +1,454 @@
+// 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';
+
+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'] };
+
+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) {
+  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.toLowerCase();
+}
+
+// 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 four-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 four-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;
+}
+
+// intake gate: a structurally sound design-tokens artifact sits at project root — both files parse, the dark
+// file agrees with the resolver, and the payload carries a legal schema/provenance/product. 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/v1') fail('intake', `payload schema is "${payload.schema || '(missing)'}", expected design-tokens/v1.`, ['Set schema: "design-tokens/v1" 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).']);
+  pass('intake', `design.tokens.json + design.resolver.json present and parsing; payload schema design-tokens/v1, provenance "${payload.provenance}"${namesDark ? ', dark set named and present' : ', light-only'}.`);
+}
+
+// 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 four-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 and its shell contains every declared state branch.
+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(', ')}`);
+  }
+  if (problems.length) {
+    fail('surfaces', `${problems.length} surface(s) not fully composed:`, [
+      ...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.',
+    ]);
+  }
+  pass('surfaces', `All ${blk.surfaces.length} surface(s) have a route dir with every declared state branch present.`);
+}
+
+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();