@nurix/etna 0.18.20 → 0.18.21

package/data/harnesses/code/skills/design/scripts/{detector.mjs → lib/checks.mjs}

@@ -1,31 +1,44 @@
-#!/usr/bin/env node
-// skills/design/scripts/detector.mjs — per-edit source detector (beam 2, D19): every detector=source catalog rule as pure regex/token analysis over .tsx/.ts/.css/.html text, plus the lever-manifest drift check (cod-02, D10). Exit 1 on violations; --json emits [{rule,file,line,excerpt,fix}].
-import { readFileSync } from 'node:fs';
-import process from 'node:process';
+// skills/design/scripts/lib/checks.mjs — the machine-check engine (beam 2, D19): every detector=source catalog rule as pure regex/token analysis over .tsx/.ts/.css/.html text, plus the lever-manifest drift check (cod-02, D10) whose vocabulary is read from the project's design-tokens artifact (design.tokens.json). Pure library — no argv, no CLI banner, no process.exit; fired at structural boundaries by phase-gate.mjs, preship-sweep.mjs, and self-integrity.mjs. Findings are [{rule, file, line, excerpt, fix}].
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 
 // ---------------------------------------------------------------------------
-// CLI parse
+// File-type routing
 // ---------------------------------------------------------------------------
 
-// Split argv into the file list, an optional --manifest path, and the --json flag.
-function parseArgs(argv) {
-  const files = [];
-  let manifest = null;
-  let json = false;
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--json') json = true;
-    else if (a === '--manifest') manifest = argv[++i];
-    else if (a.startsWith('--manifest=')) manifest = a.slice('--manifest='.length);
-    else if (a === '--help' || a === '-h') { printUsage(); process.exit(0); }
-    else files.push(a);
-  }
-  return { files, manifest, json };
+export const CHECKABLE_EXTS = ['.tsx', '.ts', '.css', '.html'];
+
+// Detect the file's extension bucket, or null when it is not a checkable type.
+export function extOf(path) {
+  const m = path.toLowerCase().match(/\.(tsx|ts|css|html)$/);
+  return m ? m[1] : null;
 }
 
-// Print the one-line usage banner.
-function printUsage() {
-  process.stdout.write('usage: detector.mjs <file...> [--manifest design.md] [--json]\n');
+// Recursively collect checkable UI files under a dir, skipping node_modules and dotfiles.
+export function walkUiFiles(dir, acc = []) {
+  if (!existsSync(dir)) return acc;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
+  for (const ent of entries) {
+    if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) walkUiFiles(full, acc);
+    else if (CHECKABLE_EXTS.some((e) => ent.name.endsWith(e))) acc.push(full);
+  }
+  return acc;
+}
+
+// Read the passed files into check-ready docs, skipping unreadable and uncheckable ones.
+export function loadDocs(files) {
+  const docs = [];
+  for (const file of files) {
+    const ext = extOf(file);
+    if (!ext) continue;
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch { continue; }
+    docs.push({ file, ext, text, lines: text.split('\n') });
+  }
+  return docs;
 }
 
 // ---------------------------------------------------------------------------
@@ -134,7 +147,7 @@ function toPx(numStr, unit) {
 // ---------------------------------------------------------------------------
 
 // Build a findings collector that de-dupes on (rule, file, line, excerpt).
-function makeSink() {
+export function makeSink() {
   const seen = new Set();
   const list = [];
   return {
@@ -154,7 +167,7 @@ function makeSink() {
 // ---------------------------------------------------------------------------
 
 // Run every single-line source check against one line and record any violations.
-function checkLine(add, file, ext, lineNo, line, fileText) {
+export function checkLine(add, file, ext, lineNo, line, fileText) {
   const isJsx = ext === 'tsx' || ext === 'ts' || ext === 'html';
   const isCss = ext === 'css';
 
@@ -283,7 +296,7 @@ function checkLine(add, file, ext, lineNo, line, fileText) {
   // spc-06: corner radius off the fixed scale.
   for (const m of line.matchAll(/(?:border-radius\s*:\s*|rounded-\[)(\d*\.?\d+)(px|rem)?/g)) {
     const px = toPx(m[1], m[2] || 'px');
-    if (px != null && !RADIUS_SCALE.has(px)) add('spc-06', file, lineNo, m[0], `Corners land on the fixed radius scale (0/2/4/6/8/12/full); ${px}px is off-scale.`);
+    if (px != null && !RADIUS_SCALE.has(px)) add('spc-06', file, lineNo, m[0], `Corners land on the fixed radius scale (0/2/4/6/8/12/16/24/full); ${px}px is off-scale.`);
   }
   // spc-07: a button taller than the 28px dense-row cap sitting inside a table row.
   if (/<t[dh]\b/i.test(line) && /<[Bb]utton\b/.test(line)) {
@@ -440,7 +453,7 @@ function checkLine(add, file, ext, lineNo, line, fileText) {
 const RE_EMOJI = /[\u{1F300}-\u{1FAFF}\u{1F1E6}-\u{1F1FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE0F}]/u;
 
 // Blank out // line comments and /* */ (incl. JSX {/* */}) block comments, preserving line count, so copy checks skip commentary.
-function cleanComments(lines) {
+export function cleanComments(lines) {
   const out = [];
   let inBlock = false;
   for (let raw of lines) {
@@ -464,7 +477,7 @@ function cleanComments(lines) {
 }
 
 // Scan comment-stripped copy for em-dashes (typ-15) and three-period ellipses (typ-14).
-function checkCopy(add, file, cleaned) {
+export function checkCopy(add, file, cleaned) {
   cleaned.forEach((line, i) => {
     if (line.includes('—')) add('typ-15', file, i + 1, line.trim(), 'Zero em-dashes in UI copy; recast the sentence or use a colon/en-dash.');
     const el = line.match(/\.\.\.(?![\w$.([{])/);
@@ -477,7 +490,7 @@ function checkCopy(add, file, cleaned) {
 // ---------------------------------------------------------------------------
 
 // Run the file-scoped source checks over one file's full text.
-function checkFile(add, file, ext, text, lines) {
+export function checkFile(add, file, ext, text, lines) {
   const isJsx = ext === 'tsx' || ext === 'ts';
 
   // dep-02: more than one <h1> in a view.
@@ -597,7 +610,7 @@ const REQUIRED_TOKENS = [
 // ---------------------------------------------------------------------------
 
 // Run the checks that need the whole passed-in file set (token-set counts, distinct sizes).
-function checkCrossFile(add, docs) {
+export function checkCrossFile(add, docs) {
   // typ-06: more than two font families declared across the passed files.
   const families = new Set();
   const iconLibs = new Set();
@@ -653,7 +666,7 @@ function checkCrossFile(add, docs) {
       }
     }
   }
-  // spc-02 is checked with the same near-duplicate logic over explicit spacing (below).
+  // spc-02 is checked with the same near-duplicate logic over explicit spacing (checkSpacingScale).
 
   // col-08: a color family exceeding the 10-shade ceiling.
   for (const [hue, set] of hexByHue) {
@@ -675,7 +688,7 @@ function checkCrossFile(add, docs) {
 }
 
 // Run spc-02 over explicit spacing values collected across files.
-function checkSpacingScale(add, docs) {
+export function checkSpacingScale(add, docs) {
   const spacings = new Map();
   for (const d of docs) {
     d.lines.forEach((line, i) => {
@@ -719,61 +732,87 @@ function hexHueBucket(hex) {
 }
 
 // ---------------------------------------------------------------------------
-// cod-02 — lever-manifest drift check (D10)
+// cod-02 — lever-manifest drift check (D10), vocabulary from the design-tokens artifact
 // ---------------------------------------------------------------------------
 
-// Extract the fenced ```yaml lever-manifest block body from a design.md's text.
-function extractLeverManifest(text) {
-  const m = text.match(/```yaml\s+lever-manifest\s*\n([\s\S]*?)\n```/);
-  return m ? m[1] : null;
+// Resolve a manifest argument (a design.tokens.json path or a directory holding one) to the tokens file, or null.
+function resolveTokensFile(path) {
+  if (!path || !existsSync(path)) return null;
+  let st;
+  try { st = statSync(path); } catch { return null; }
+  if (st.isDirectory()) {
+    const candidate = join(path, 'design.tokens.json');
+    return existsSync(candidate) ? candidate : null;
+  }
+  return path;
 }
 
-// Tolerantly pull the allowed vocabulary (colors, scales, fonts) out of a lever-manifest body.
-function parseManifestVocab(body) {
-  const stripComment = (s) => s.replace(/\s+#.*$/, '');
+// Follow {path.to.token} alias strings within the artifact to the target token (hop-bounded against cycles).
+function resolveAlias(root, token) {
+  let cur = token;
+  for (let hops = 0; hops < 8 && cur && typeof cur.$value === 'string' && /^\{[^}]+\}$/.test(cur.$value.trim()); hops++) {
+    let node = root;
+    for (const seg of cur.$value.trim().slice(1, -1).split('.')) node = node && typeof node === 'object' ? node[seg] : undefined;
+    if (!node || typeof node !== 'object') return cur;
+    cur = node;
+  }
+  return cur;
+}
+
+// Pull a token's preserved source string from $extensions["com.nurix.design"].css, or null.
+function preservedCss(token) {
+  const css = token && token.$extensions && token.$extensions['com.nurix.design'] && token.$extensions['com.nurix.design'].css;
+  return typeof css === 'string' ? css : null;
+}
+
+// Load the drift-check vocabulary from a design-tokens artifact (a design.tokens.json path, or its directory):
+// scales come from the payload's lever-manifest; colors, font stacks, and icon stroke are read from the tokens
+// themselves (data/design-tokens/SCHEMA.md — token-valued allowlists are never restated in the manifest).
+// Each color enters in both spellings — the preserved .css string and the typed value's hex — so either passes
+// drift. Returns null when no parseable artifact is found; never runs the coverage gate.
+export function loadManifestVocab(manifestPath) {
+  const file = resolveTokensFile(manifestPath);
+  if (!file) return null;
+  let root;
+  try { root = JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+  if (!root || typeof root !== 'object') return null;
+  const payload = (root.$extensions && root.$extensions['com.nurix.design']) || {};
+  const manifest = payload['lever-manifest'] || {};
+
+  const numSet = (arr) => (Array.isArray(arr) ? new Set(arr.map(Number).filter((n) => !Number.isNaN(n))) : null);
+  const spacing = numSet(manifest['spacing-scale']);
+  const radius = numSet(manifest['radius-scale']);
+  const durations = numSet(manifest.motion && manifest.motion.durations);
+
   const colors = new Set();
-  const fonts = new Set();
-  // color-tokens region: from `color-tokens:` up to the next top-level (0-indent) key.
-  const ctStart = body.search(/^color-tokens\s*:/m);
-  if (ctStart >= 0) {
-    const rest = body.slice(ctStart).split('\n');
-    let region = [rest[0]];
-    for (let i = 1; i < rest.length; i++) {
-      if (/^\S/.test(rest[i]) && !/^\s/.test(rest[i])) break; // next top-level key
-      region.push(rest[i]);
-    }
-    for (const line of region) {
-      for (const c of stripComment(line).matchAll(RE_COLOR_LITERAL)) colors.add(normColor(c[0]));
-      for (const c of stripComment(line).matchAll(/"([^"]+)"|'([^']+)'/g)) {
-        const v = (c[1] || c[2]).trim();
-        if (RE_COLOR_LITERAL.test(v)) { RE_COLOR_LITERAL.lastIndex = 0; colors.add(normColor(v)); }
-        RE_COLOR_LITERAL.lastIndex = 0;
-      }
-    }
+  for (const token of Object.values(root.color || {})) {
+    if (!token || typeof token !== 'object') continue;
+    const resolved = resolveAlias(root, token);
+    const css = preservedCss(token) || preservedCss(resolved);
+    if (css) colors.add(normColor(css));
+    const value = resolved && resolved.$value;
+    if (value && typeof value === 'object' && typeof value.hex === 'string') colors.add(normColor(value.hex));
   }
-  // numeric scales
-  const numList = (key) => {
-    const mm = body.match(new RegExp(`^${key}\\s*:\\s*\\[([^\\]]*)\\]`, 'm'));
-    if (!mm) return null;
-    return new Set(mm[1].split(',').map((s) => parseFloat(s)).filter((n) => !Number.isNaN(n)));
+
+  const fonts = new Set();
+  // Add every family name in a fontFamily token's own stack (alias-valued tokens contribute nothing new).
+  const addStack = (token) => {
+    if (!token || !Array.isArray(token.$value)) return;
+    for (const fam of token.$value) if (typeof fam === 'string' && fam.trim()) fonts.add(fam.trim().toLowerCase());
   };
-  const spacing = numList('spacing-scale');
-  const radius = numList('radius-scale');
-  let durations = null;
-  const dm = body.match(/durations\s*:\s*\[([^\]]*)\]/);
-  if (dm) durations = new Set(dm[1].split(',').map((s) => parseFloat(s)).filter((n) => !Number.isNaN(n)));
-  // fonts (inline object)
-  const fm = body.match(/fonts\s*:\s*\{([^}]*)\}/);
-  if (fm) {
-    for (const p of fm[1].matchAll(/(?:sans|mono)\s*:\s*"([^"]+)"/g)) {
-      fonts.add(p[1].split(',')[0].replace(/["']/g, '').trim().toLowerCase());
-    }
-  }
-  return { colors, spacing, radius, durations, fonts };
+  const primitive = root.primitive || {};
+  addStack(primitive['font-sans']);
+  addStack(primitive['font-mono']);
+  for (const token of Object.values((root.typography && root.typography.family) || {})) addStack(token);
+
+  const strokeToken = primitive['icon-stroke'] ? resolveAlias(root, primitive['icon-stroke']) : null;
+  const iconStroke = strokeToken && typeof strokeToken.$value === 'number' ? strokeToken.$value : null;
+
+  return { colors, spacing, radius, durations, fonts, iconStroke };
 }
 
 // Flag any color/spacing/radius/duration/font literal in the diff files outside the manifest vocabulary (cod-02).
-function checkDrift(add, docs, vocab) {
+export function checkDrift(add, docs, vocab) {
   for (const d of docs) {
     if (d.ext === 'css' && vocab.colors.size) {
       // token-definition files legitimately hold the manifest's own literals; only flag component-side drift
@@ -783,7 +822,7 @@ function checkDrift(add, docs, vocab) {
       // colors
       if (vocab.colors.size) {
         for (const m of line.matchAll(RE_COLOR_LITERAL)) {
-          if (!vocab.colors.has(normColor(m[0]))) add('cod-02', d.file, i + 1, m[0], 'Value drifts from the lever manifest; use a color already in color-tokens, not a fresh literal.');
+          if (!vocab.colors.has(normColor(m[0]))) add('cod-02', d.file, i + 1, m[0], "Value drifts from the lever manifest; use a color already in the artifact's color tokens, not a fresh literal.");
         }
       }
       // spacing (explicit only)
@@ -819,59 +858,12 @@ function checkDrift(add, docs, vocab) {
 }
 
 // ---------------------------------------------------------------------------
-// Output
+// Orchestration + output formatting
 // ---------------------------------------------------------------------------
 
-// Print findings as the fix-or-classify directive (human) or a JSON array.
-function report(findings, json) {
-  if (json) {
-    process.stdout.write(JSON.stringify(findings, null, 2) + '\n');
-    return;
-  }
-  if (findings.length === 0) {
-    process.stdout.write('detector: clean — no source violations.\n');
-    return;
-  }
-  const useColor = process.stdout.isTTY;
-  const bold = (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s);
-  const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
-  const dim = (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s);
-  process.stdout.write(bold(red(`detector: ${findings.length} source violation${findings.length === 1 ? '' : 's'}\n\n`)));
-  for (const f of findings) {
-    process.stdout.write(`${bold(red('[' + f.rule + ']'))} ${f.file}:${f.line}\n`);
-    process.stdout.write(`  ${dim('offending:')} ${f.excerpt}\n`);
-    process.stdout.write(`  ${dim('fix:')}       ${f.fix}\n\n`);
-  }
-  process.stdout.write(bold('Fix each now, or classify why the rule does not apply and record that classification\n'));
-  process.stdout.write(bold('in the decay ledger (docs/memory/design-decay.md) — never ignore silently.\n'));
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-
-// Detect the file's extension bucket, or null when it is not a checkable type.
-function extOf(path) {
-  const m = path.toLowerCase().match(/\.(tsx|ts|css|html)$/);
-  return m ? m[1] : null;
-}
-
-// Entry point: read the passed files, run every source check, emit findings, exit 1 on any.
-function main() {
-  const { files, manifest, json } = parseArgs(process.argv.slice(2));
-  if (files.length === 0) { printUsage(); process.exit(2); }
-
+// Run the full engine (per-line, per-file, copy, cross-file, spacing, drift) over loaded docs; returns sorted findings.
+export function checkDocs(docs, { vocab = null } = {}) {
   const sink = makeSink();
-  const docs = [];
-  for (const file of files) {
-    const ext = extOf(file);
-    if (!ext) continue;
-    let text;
-    try { text = readFileSync(file, 'utf8'); } catch { continue; }
-    const lines = text.split('\n');
-    docs.push({ file, ext, text, lines });
-  }
-
   for (const d of docs) {
     d.lines.forEach((line, i) => checkLine(sink.add, d.file, d.ext, i + 1, line, d.text));
     checkFile(sink.add, d.file, d.ext, d.text, d.lines);
@@ -879,20 +871,33 @@ function main() {
   }
   checkCrossFile(sink.add, docs);
   checkSpacingScale(sink.add, docs);
-
-  if (manifest) {
-    let mtext;
-    try { mtext = readFileSync(manifest, 'utf8'); } catch { mtext = null; }
-    if (mtext) {
-      const body = extractLeverManifest(mtext);
-      if (body) checkDrift(sink.add, docs, parseManifestVocab(body));
-    }
-  }
-
+  if (vocab) checkDrift(sink.add, docs, vocab);
   // Stable sort: by file, then line, then rule id.
   sink.list.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.rule.localeCompare(b.rule));
-  report(sink.list, json);
-  process.exit(sink.list.length > 0 ? 1 : 0);
+  return sink.list;
+}
+
+// Convenience entry: read the passed file paths (and the optional design-tokens artifact) and run the full engine.
+export function runChecks(files, { manifestPath = null, vocab = null } = {}) {
+  const loaded = vocab || (manifestPath ? loadManifestVocab(manifestPath) : null);
+  return checkDocs(loadDocs(files), { vocab: loaded });
 }
 
-main();
+// Render findings as the fix-or-classify block (the caller prints it and decides the exit code).
+export function formatFindings(findings, { color = false, label = 'machine checks' } = {}) {
+  const bold = (s) => (color ? `\x1b[1m${s}\x1b[0m` : s);
+  const red = (s) => (color ? `\x1b[31m${s}\x1b[0m` : s);
+  const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
+  const out = [];
+  out.push(bold(red(`${label}: ${findings.length} source violation${findings.length === 1 ? '' : 's'}`)));
+  out.push('');
+  for (const f of findings) {
+    out.push(`${bold(red('[' + f.rule + ']'))} ${f.file}:${f.line}`);
+    out.push(`  ${dim('offending:')} ${f.excerpt}`);
+    out.push(`  ${dim('fix:')}       ${f.fix}`);
+    out.push('');
+  }
+  out.push(bold('Fix each now, or classify why the rule does not apply and record that classification'));
+  out.push(bold('in the decay ledger (docs/memory/design-decay.md) — never ignore silently.'));
+  return out.join('\n');
+}

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

@@ -1,8 +1,9 @@
-// skills/design/scripts/phase-gate.mjs — create-phase precondition gates (D21/D23): validate the named phase's exit preconditions, exit non-zero printing the exact fix, one green line on pass.
+// 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 } from 'node:path';
+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'];
@@ -20,13 +21,15 @@ function readText(path) {
   try { return readFileSync(path, 'utf8'); } catch { return ''; }
 }
 
-// Report a passing gate as one green line and exit 0.
+// 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}`);
-  process.exit(0);
 }
 
-// Report a failing gate with the problem and the exact fix, then exit 1.
+// 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('');
@@ -35,7 +38,7 @@ function fail(phase, problem, fixLines) {
     if (line == null || line === '') continue;
     for (const sub of String(line).split('\n')) console.error(`    ${sub}`);
   }
-  process.exit(1);
+  throw new GateFailure(problem);
 }
 
 // Lowercase-kebab a display name for route-dir / fixture-module matching.
@@ -57,17 +60,27 @@ function lastStaticSegment(route) {
   return parts.length ? kebab(parts[parts.length - 1]) : null;
 }
 
-// Parse leading YAML frontmatter into a flat key->value map, or null when absent.
-function parseFrontmatter(text) {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!m) return null;
-  const out = {};
-  for (const line of m[1].split(/\r?\n/)) {
-    const idx = line.indexOf(':');
-    if (idx < 0) continue;
-    out[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+// 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 out;
+  return named;
 }
 
 // Split a `[a, b, c]` inline list into trimmed members.
@@ -217,21 +230,49 @@ function checkImportOrder(rawCss) {
   return null;
 }
 
-// intake gate: a schema-valid design.md with a legal provenance sits at project root.
+// 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 p = join(project, 'design.md');
-  if (!existsSync(p)) {
-    fail('intake', `No design.md at project root (${p}).`, [
-      `Create ${p} against skills/design/data/design-md/SCHEMA.md.`,
-      'Frontmatter must set schema: design-md/v1 and provenance: project|extracted|library|default.',
-      'Resolve the look design.md-first: the project doc wins, else a confirmed library entry, else the Nurix default.',
+  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).',
     ]);
   }
-  const fm = parseFrontmatter(readText(p));
-  if (!fm) fail('intake', `${p} has no YAML frontmatter.`, ['Add a --- delimited frontmatter block with schema, product, provenance, sourced.']);
-  if (fm.schema !== 'design-md/v1') fail('intake', `design.md frontmatter schema is "${fm.schema || '(missing)'}", expected design-md/v1.`, ['Set schema: design-md/v1 in the frontmatter.']);
-  if (!PROVENANCE.has(fm.provenance)) fail('intake', `design.md provenance is "${fm.provenance || '(missing)'}"; must be one of project|extracted|library|default.`, ['Set provenance to one of: project | extracted | library | default (SCHEMA.md).']);
-  pass('intake', `design.md present with schema design-md/v1 and provenance "${fm.provenance}".`);
+  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.
@@ -290,17 +331,17 @@ function gateScaffold(project) {
   pass('scaffold', `Shell, ${blk.surfaces.length} wired route dir(s) with state-shells, and globals.css import order all in place.`);
 }
 
-// tokens gate: design.md clears the coverage gate (derive-personality.mjs --check) and both CSS files are emitted with the cascade order intact.
+// 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 dm = join(project, 'design.md');
-  if (!existsSync(dm)) fail('tokens', `No design.md at ${dm}.`, ['Resolve and materialize design.md first (intake phase).']);
+  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, dm, '--check'], { encoding: 'utf8' });
+  const res = spawnSync(process.execPath, [derive, project, '--check'], { encoding: 'utf8' });
   if (res.status !== 0) {
     const detail = `${res.stdout || ''}${res.stderr || ''}`.trim();
-    fail('tokens', `The design.md coverage gate failed (derive-personality.mjs --check exited ${res.status == null ? '(spawn error)' : res.status}).`, [
-      'Assign or hint every named primitive / dial / token below, then re-run this gate:',
+    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,
     ]);
   }
@@ -308,7 +349,7 @@ function gateTokens(project) {
   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 ${dm} --emit ${project} to write src/styles/personality.css and src/styles/globals.css.`,
+      `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')));
@@ -367,7 +408,26 @@ function gateSurfaces(project) {
 
 const GATES = { intake: gateIntake, structure: gateStructure, scaffold: gateScaffold, tokens: gateTokens, fixtures: gateFixtures, surfaces: gateSurfaces };
 
-// Parse argv, resolve the project dir, and dispatch to the named phase gate.
+// 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];
@@ -380,7 +440,15 @@ function main() {
     console.error(`usage: phase-gate.mjs <${PHASES.join('|')}> [--project <dir>]`);
     process.exit(2);
   }
-  GATES[phase](project);
+  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();