@nurix/etna 0.18.18 → 0.18.20

package/data/harnesses/code/skills/design/scripts/detector.mjs

@@ -0,0 +1,898 @@
+#!/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';
+
+// ---------------------------------------------------------------------------
+// CLI parse
+// ---------------------------------------------------------------------------
+
+// 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 };
+}
+
+// Print the one-line usage banner.
+function printUsage() {
+  process.stdout.write('usage: detector.mjs <file...> [--manifest design.md] [--json]\n');
+}
+
+// ---------------------------------------------------------------------------
+// Color parsing (zero-dep): hex / rgb / hsl / oklch -> saturation signal
+// ---------------------------------------------------------------------------
+
+// Expand a 3- or 4-nibble hex to its 6/8-nibble form; return the lowercased hex digits.
+function expandHex(hex) {
+  let h = hex.replace('#', '').toLowerCase();
+  if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('');
+  return h;
+}
+
+// Convert an r/g/b triple (0-255) to HSL saturation and lightness (both 0-1).
+function rgbToSl(r, g, b) {
+  const rr = r / 255, gg = g / 255, bb = b / 255;
+  const max = Math.max(rr, gg, bb), min = Math.min(rr, gg, bb);
+  const l = (max + min) / 2;
+  const d = max - min;
+  const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
+  return { s, l };
+}
+
+// Parse one color literal into { sat, light } (HSL, 0-1) or { oklchChroma } or null.
+function parseColor(lit) {
+  const s = lit.trim().toLowerCase();
+  if (s.startsWith('#')) {
+    const h = expandHex(s.match(/#[0-9a-f]{3,8}/i)?.[0] || s);
+    if (h.length < 6) return null;
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    if ([r, g, b].some(Number.isNaN)) return null;
+    const { s: sat, l } = rgbToSl(r, g, b);
+    return { sat, light: l };
+  }
+  const rgb = s.match(/rgba?\(([^)]*)\)/);
+  if (rgb) {
+    const parts = rgb[1].split(/[\s,/]+/).filter(Boolean).slice(0, 3).map(Number);
+    if (parts.length < 3 || parts.some(Number.isNaN)) return null;
+    const { s: sat, l } = rgbToSl(parts[0], parts[1], parts[2]);
+    return { sat, light: l };
+  }
+  const hsl = s.match(/hsla?\(([^)]*)\)/);
+  if (hsl) {
+    const parts = hsl[1].split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 3) return null;
+    const sat = parseFloat(parts[1]) / 100;
+    const light = parseFloat(parts[2]) / 100;
+    if (Number.isNaN(sat) || Number.isNaN(light)) return null;
+    return { sat, light };
+  }
+  const okl = s.match(/oklch\(([^)]*)\)/);
+  if (okl) {
+    const parts = okl[1].split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 2) return null;
+    const chroma = parseFloat(parts[1]);
+    if (Number.isNaN(chroma)) return null;
+    return { oklchChroma: chroma };
+  }
+  return null;
+}
+
+// Decide whether a parsed color exceeds the accent saturation ceiling (col-02, <80%).
+function overAccentSaturation(parsed) {
+  if (!parsed) return false;
+  if (typeof parsed.oklchChroma === 'number') return parsed.oklchChroma > 0.37 * 0.8; // 0.296 heuristic
+  if (parsed.light == null || parsed.light < 0.12 || parsed.light > 0.92) return false; // sat is unstable near black/white
+  return parsed.sat >= 0.8;
+}
+
+// Normalize a color literal for set membership (drift compare): strip inner spaces, lowercase, expand short hex.
+function normColor(lit) {
+  let s = lit.trim().toLowerCase().replace(/\s+/g, '');
+  const hx = s.match(/^#[0-9a-f]{3,8}$/);
+  if (hx) return '#' + expandHex(s);
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// Value regexes shared by several rules
+// ---------------------------------------------------------------------------
+
+const RE_COLOR_LITERAL = /#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)|oklch\([^)]*\)/g;
+const TW_UTILITY = '(?:bg|text|border|ring|ring-offset|fill|stroke|from|via|to|outline|divide|decoration|caret|accent|placeholder|shadow)';
+const PALETTE_HUES = 'red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|grey|zinc|neutral|stone';
+const RE_PALETTE_CLASS = new RegExp(`\\b${TW_UTILITY}-(${PALETTE_HUES})-(\\d{2,3})\\b`, 'g');
+const STATUS_HUES = new Set(['red', 'rose', 'orange', 'amber', 'yellow', 'green', 'emerald', 'lime']);
+
+// A spacing value in px is on the 4/8 scale (or the dense 2px step) when it is 0, 2, or a multiple of 4.
+function spacingOnScale(px) { return px === 0 || px === 2 || px % 4 === 0; }
+const RADIUS_SCALE = new Set([0, 2, 4, 6, 8, 12, 16, 24, 9999]);
+const ZINDEX_SCALE = new Set([0, 10, 20, 40, 100, 1000]);
+
+// Convert a rem or px length token to px (16px root); return null when it is neither.
+function toPx(numStr, unit) {
+  const n = parseFloat(numStr);
+  if (Number.isNaN(n)) return null;
+  if (unit === 'rem') return n * 16;
+  if (unit === 'px' || unit === '') return n;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Findings sink
+// ---------------------------------------------------------------------------
+
+// Build a findings collector that de-dupes on (rule, file, line, excerpt).
+function makeSink() {
+  const seen = new Set();
+  const list = [];
+  return {
+    add(rule, file, line, excerpt, fix) {
+      const ex = (excerpt || '').trim().slice(0, 200);
+      const key = `${rule}|${file}|${line}|${ex}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      list.push({ rule, file, line, excerpt: ex, fix });
+    },
+    list,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-line checks (run once per source line)
+// ---------------------------------------------------------------------------
+
+// Run every single-line source check against one line and record any violations.
+function checkLine(add, file, ext, lineNo, line, fileText) {
+  const isJsx = ext === 'tsx' || ext === 'ts' || ext === 'html';
+  const isCss = ext === 'css';
+
+  // --- Color ---
+  if (isJsx) {
+    // col-05: literal palette classes, hex/rgb/oklch literals, and dark: prefixes in JSX.
+    for (const m of line.matchAll(RE_PALETTE_CLASS)) {
+      add('col-05', file, lineNo, m[0], 'Replace the literal palette class with a semantic token class (bg-primary, text-muted-foreground, border-border).');
+      if (STATUS_HUES.has(m[1])) add('col-04', file, lineNo, m[0], 'Route status color through a semantic token: --success, --warning, or --destructive (e.g. text-success), never a raw palette hue.');
+    }
+    if (/\bdark:/.test(line)) add('col-05', file, lineNo, (line.match(/\bdark:[\w[\]/.-]+/) || ['dark:'])[0], 'Drop the dark: prefix; light is the default theme and dark is opted in at the token layer, not per class.');
+    for (const m of line.matchAll(RE_COLOR_LITERAL)) {
+      add('col-05', file, lineNo, m[0], 'Move the color literal into a semantic token; components consume tokens (bg-card, text-foreground), never raw hex/rgb/oklch.');
+    }
+  }
+  // col-02: accent saturation ceiling. JSX: any literal; CSS: only accent-role token definitions.
+  if (isJsx) {
+    for (const m of line.matchAll(RE_COLOR_LITERAL)) {
+      if (overAccentSaturation(parseColor(m[0]))) add('col-02', file, lineNo, m[0], 'Desaturate the accent below the 80% saturation ceiling (or oklch chroma <= 0.30); reserve one restrained accent.');
+    }
+  } else if (isCss && /--(?:primary|accent|ring)\b/.test(line)) {
+    for (const m of line.matchAll(RE_COLOR_LITERAL)) {
+      if (overAccentSaturation(parseColor(m[0]))) add('col-02', file, lineNo, m[0], 'The accent/primary/ring token exceeds the 80% saturation ceiling (oklch chroma <= 0.30); pull it down a step.');
+    }
+  }
+  // col-06: pure black / pure white literals.
+  {
+    const pm = line.match(/#000000\b|#000\b|#ffffff\b|#fff\b|rgb\(\s*0\s*,\s*0\s*,\s*0\s*\)|rgb\(\s*255\s*,\s*255\s*,\s*255\s*\)/i);
+    if (pm) add('col-06', file, lineNo, pm[0], 'Never pure #000000/#ffffff; start near #111827/#1F2937 for ink and an off-white surface, declared as a token.');
+  }
+  // col-07: opacity- or rgba-fabricated shades (rgba/hsla with alpha, 8-digit hex).
+  {
+    const fm = line.match(/#[0-9a-fA-F]{8}\b|rgba\([^)]*\)|hsla\([^)]*\)/);
+    if (fm && !/\b(?:overlay|scrim|backdrop|modal)\b/i.test(line)) add('col-07', file, lineNo, fm[0], 'Do not fabricate a shade via alpha; declare the shade as an explicit hex/oklch token instead.');
+  }
+  // col-09: disabled-state opacity band (0.38-0.5).
+  for (const m of line.matchAll(/(?:disabled:opacity-|opacity-)(\d{1,3})\b/g)) {
+    if (!/disabled/.test(line)) continue;
+    const o = parseInt(m[1], 10) / 100;
+    if (o < 0.38 || o > 0.5) add('col-09', file, lineNo, m[0], 'Set the disabled opacity into the 0.38-0.5 muted band (Tailwind opacity-40/45).');
+  }
+  // col-10: modal scrim opacity band (40-60% black).
+  if (/\b(?:overlay|scrim|backdrop)\b/i.test(line)) {
+    for (const m of line.matchAll(/bg-black\/(\d{1,3})\b/g)) {
+      const p = parseInt(m[1], 10);
+      if (p < 40 || p > 60) add('col-10', file, lineNo, m[0], 'Put the modal scrim in the 40-60% black band (bg-black/50).');
+    }
+  }
+  // col-13: semantic status color used as a solid fill (never a fill).
+  {
+    const cm = line.match(/\bbg-(?:success|warning)\b|\bbg-(?:green|emerald|amber|yellow|orange|rose)-\d{2,3}\b/);
+    if (cm && !/\/\d/.test(cm[0])) add('col-13', file, lineNo, cm[0], 'Status/price color is text-only, never a solid fill; use the token as text/border (text-success) or a low-opacity tint on a badge.');
+  }
+
+  // --- Typography ---
+  // typ-02: any explicit font-size below 11px.
+  for (const m of line.matchAll(/(?:font-size\s*:\s*|text-\[)(\d*\.?\d+)(px|rem)?/g)) {
+    const px = toPx(m[1], m[2] || 'px');
+    if (px != null && px < 11) add('typ-02', file, lineNo, m[0], 'Never render below 11px; body sits at 14px+ on operator surfaces.');
+  }
+  // typ-03: input font-size below 16px, only on a touch/mobile surface (scope-guarded).
+  if (/<(?:input|textarea)\b/i.test(line) && /(?:touch|mobile|viewport-fit|maximum-scale)/i.test(fileText)) {
+    for (const m of line.matchAll(/text-\[(\d*\.?\d+)(px|rem)?\]/g)) {
+      const px = toPx(m[1], m[2] || 'px');
+      if (px != null && px < 16) add('typ-03', file, lineNo, m[0], 'Form inputs on touch/mobile surfaces are >= 16px to defeat iOS zoom.');
+    }
+  }
+  // typ-05: prose measure declared in ch, outside 45-75.
+  for (const m of line.matchAll(/(?:max-width\s*:\s*|max-w-\[)(\d+)ch/g)) {
+    const ch = parseInt(m[1], 10);
+    if (ch < 45 || ch > 75) add('typ-05', file, lineNo, m[0], 'Keep prose measure in the 45-75ch readable band (data tables are exempt).');
+  }
+  // typ-08: uppercase micro-label tracking and the negative tracking floor.
+  {
+    const neg = line.match(/(?:letter-spacing\s*:\s*|tracking-\[)(-?\d*\.?\d+)em/);
+    if (neg && parseFloat(neg[1]) < -0.04) add('typ-08', file, lineNo, neg[0], 'Letter-spacing never below the -0.04em floor.');
+    if (/tracking-tighter\b/.test(line)) add('typ-08', file, lineNo, 'tracking-tighter', 'tracking-tighter (-0.05em) is below the -0.04em floor; use tracking-tight at most.');
+    if (/\buppercase\b/.test(line) && !/tracking-(?:wide|wider|widest|\[)/.test(line)) add('typ-08', file, lineNo, 'uppercase', 'All-caps micro-labels carry positive tracking (>= 0.02em, caps band 0.05-0.12em); add tracking-wide.');
+  }
+  // typ-09: viewport-fluid font sizing.
+  {
+    const vm = line.match(/(?:font-size\s*:[^;]*|text-\[[^\]]*)(?:\d*\.?\d+(?:vw|vh)|clamp\()/);
+    if (vm) add('typ-09', file, lineNo, vm[0], 'Font sizes come from a fixed rem scale; ban vw/vh/clamp on font-size.');
+  }
+  // typ-11: UI font weight below 400.
+  {
+    const wm = line.match(/(?:font-weight\s*:\s*|font-\[)(\d{3})\]?/);
+    if (wm && parseInt(wm[1], 10) < 400) add('typ-11', file, lineNo, wm[0], 'No UI font weight below 400.');
+    if (/\bfont-(?:thin|extralight|light)\b/.test(line)) add('typ-11', file, lineNo, (line.match(/font-(?:thin|extralight|light)/) || [''])[0], 'No UI font weight below 400 (font-thin/extralight/light are 100-300).');
+  }
+  // typ-12: type sized in em.
+  {
+    const em = line.match(/(?:font-size\s*:\s*|text-\[)(\d*\.?\d+)em/);
+    if (em) add('typ-12', file, lineNo, em[0], 'Never size type in em (it compounds); use px or rem.');
+  }
+  // typ-16: serif font family (not sans-serif).
+  {
+    const sf = line.match(/font-?family\s*:\s*[^;}]*\bserif\b|font-serif\b/i);
+    if (sf && !/sans-serif/i.test(sf[0])) add('typ-16', file, lineNo, sf[0].trim(), 'Serif faces are banned in dashboards/software UIs; use the sans family.');
+  }
+  // typ-19: mono/code type sized below 16px.
+  if (/font-mono\b|font-family\s*:[^;]*monospace|<(?:code|pre)\b/i.test(line)) {
+    for (const m of line.matchAll(/text-\[(\d*\.?\d+)(px|rem)?\]|text-(xs|sm)\b/g)) {
+      if (m[3]) { add('typ-19', file, lineNo, m[0], 'Code/mono type is fixed at 16px; long lines scroll horizontally, never shrink.'); continue; }
+      const px = toPx(m[1], m[2] || 'px');
+      if (px != null && px < 16) add('typ-19', file, lineNo, m[0], 'Code/mono type is fixed at 16px; long lines scroll horizontally, never shrink.');
+    }
+  }
+
+  // --- Spatial ---
+  // spc-01: explicit (arbitrary/CSS) spacing value off the 4/8 scale.
+  for (const m of line.matchAll(/(?:[pm][trblxy]?|gap(?:-[xy])?|space-[xy]|inset)-\[(\d*\.?\d+)(px|rem)?\]/g)) {
+    const px = toPx(m[1], m[2] || 'px');
+    if (px != null && !spacingOnScale(px)) add('spc-01', file, lineNo, m[0], `Land the spacing on the 4/8 scale (nearest step to ${px}px); ${px}px is off-scale.`);
+  }
+  if (isCss) {
+    for (const m of line.matchAll(/(?:padding|margin|gap|top|left|right|bottom)\s*:\s*([^;]+);/g)) {
+      for (const v of m[1].matchAll(/(\d*\.?\d+)(px|rem)/g)) {
+        const px = toPx(v[1], v[2]);
+        if (px != null && px !== 1 && !spacingOnScale(px)) add('spc-01', file, lineNo, v[0], `Land the spacing on the 4/8 scale (nearest step to ${px}px); ${px}px is off-scale.`);
+      }
+    }
+  }
+  // spc-04: center-aligned data column.
+  if (/<t[dh]\b/i.test(line) && /\btext-center\b/.test(line)) add('spc-04', file, lineNo, 'text-center', 'Numeric columns right-align, text left-aligns; never center-align a data column.');
+  // 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.`);
+  }
+  // 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)) {
+    const bh = line.match(/\bh-(?:8|9|10|11|12|14|16|20)\b|\bh-\[(\d+)px\]|\bmin-h-\[(\d+)px\]/);
+    if (bh) {
+      const px = (bh[1] || bh[2]) ? parseInt(bh[1] || bh[2], 10) : 99;
+      if (px > 28) add('spc-07', file, lineNo, bh[0], 'Dense table rows compact their buttons to 28px (h-7); trim the control height and keep mono numerals on figures.');
+    }
+  }
+  // spc-08: full-viewport height via h-screen / 100vh instead of dvh.
+  {
+    const hm = line.match(/\b(?:min-)?h-screen\b|100vh|h-\[100vh\]/);
+    if (hm) add('spc-08', file, lineNo, hm[0], 'Full-viewport height uses min-h-[100dvh]; never h-screen or 100vh.');
+  }
+  // spc-09: calc-percentage layout arithmetic.
+  {
+    const cm = line.match(/calc\([^)]*%[^)]*\)/);
+    if (cm) add('spc-09', file, lineNo, cm[0], 'Ban calc-percentage layout arithmetic; use CSS Grid instead.');
+  }
+
+  // --- Depth ---
+  // dep-01: z-index off the declared scale, or the banned 999/9999.
+  for (const m of line.matchAll(/(?:z-index\s*:\s*|z-\[)(\d{1,4})/g)) {
+    const z = parseInt(m[1], 10);
+    if (z === 999 || z === 9999 || !ZINDEX_SCALE.has(z)) add('dep-01', file, lineNo, m[0], 'z-index only from the declared scale (0/10/20/40/100/1000); ban 999 and 9999.');
+  }
+  // dep-04: a border and a heavy elevation shadow doing the same separation job.
+  if (/\bborder(?:-[24]|-solid|-\w+-\d)?\b/.test(line) && /\bshadow-(?:lg|xl|2xl)\b/.test(line)) {
+    add('dep-04', file, lineNo, (line.match(/shadow-(?:lg|xl|2xl)/) || [''])[0], 'Border and shadow are doing the same separation job; keep one (a hairline border or a shadow), not both heavy.');
+  }
+
+  // --- Interaction ---
+  // int-12: a non-button clickable element without cursor:pointer.
+  if (/<(?:div|span|li)\b[^>]*\bonClick=/.test(line) && !/cursor-pointer/.test(line)) {
+    add('int-12', file, lineNo, (line.match(/<(?:div|span|li)\b[^>]*onClick=[^ >]*/) || ['onClick'])[0], 'cursor:pointer on every clickable element; add cursor-pointer (or use a real <button>).');
+  }
+  // int-03: a hover-revealed control with no keyboard/focus path.
+  if (/(?:group-hover|hover):(?:opacity-100|block|flex|visible)\b/.test(line) && !/(?:group-focus-within|focus-within|focus-visible|group-focus):/.test(fileText)) {
+    add('int-03', file, lineNo, (line.match(/(?:group-hover|hover):(?:opacity-100|block|flex|visible)/) || [''])[0], 'No pointer-only affordances; give the hover-revealed control a focus/keyboard path (group-focus-within:).');
+  }
+  // int-04: a modal built on a div role="dialog" instead of native <dialog>.
+  if (/<div\b[^>]*role=["']dialog["']/.test(line)) add('int-04', file, lineNo, 'role="dialog"', 'Modals use native <dialog> with inert focus containment; prefer a side panel before a modal.');
+  // int-08: placeholder-as-label on a non-search input.
+  if (/<input\b/i.test(line) && /placeholder=/.test(line) && !/aria-label|aria-labelledby|type=["']search["']/.test(line) && !/placeholder=["'][^"']*[Ss]earch/.test(line) && !/<label/i.test(fileText)) {
+    add('int-08', file, lineNo, (line.match(/placeholder=["'][^"']*["']/) || ['placeholder'])[0], 'Labels stay visible above the input; ban placeholder-as-label (errors render inline below).');
+  }
+  // int-09: a sortable header with no aria-sort.
+  if (/<th\b/i.test(line) && /(?:onClick=|cursor-pointer|sortable)/.test(line) && !/aria-sort/.test(line)) {
+    add('int-09', file, lineNo, '<th> sortable', 'Sortable headers carry aria-sort; give the sortable <th> an aria-sort state.');
+  }
+  // int-11: a button group with a sub-8px gap between targets.
+  {
+    const gm = line.match(/\b(?:gap|space-x)-\[(\d*\.?\d+)px\]|\b(?:gap|space-x)-0(?:\.5)?\b|gap-px\b/);
+    if (gm && /<button|role=["']button["']|<a\b/.test(line)) {
+      const n = gm[1] != null ? parseFloat(gm[1]) : 0;
+      if (n < 8) add('int-11', file, lineNo, gm[0], 'Target-to-target spacing clears the 8px minimum gap.');
+    }
+  }
+  // int-02: outline removed with no replacement focus style anywhere in the file.
+  if (/\boutline-none\b|outline\s*:\s*none/.test(line) && !/(?:focus-visible:|focus:ring|:focus-visible|ring-[12]|focus:outline-\[)/.test(fileText)) {
+    add('int-02', file, lineNo, (line.match(/outline-none|outline\s*:\s*none/) || [''])[0], 'Ban outline:none without a replacement; add a :focus-visible ring (focus-visible:ring-2).');
+  }
+  // int-14: a raw button styling hover but neither focus nor disabled states.
+  if (/<button\b/i.test(line) && /hover:/.test(line) && !/(?:focus-visible:|focus:)/.test(line) && !/disabled:/.test(line)) {
+    add('int-14', file, lineNo, '<button>', 'All five button states are required: default, hover, active, focus, disabled; this button is missing focus/disabled.');
+  }
+
+  // --- Motion ---
+  // mot-01: an animation/transition duration over the 500ms ceiling.
+  for (const m of line.matchAll(/duration-\[(\d+)ms\]|duration-(700|1000)\b|(?:transition|animation)(?:-duration)?\s*:[^;]*?(\d*\.?\d+)(ms|s)/g)) {
+    let ms = null;
+    if (m[1]) ms = parseInt(m[1], 10);
+    else if (m[2]) ms = parseInt(m[2], 10);
+    else if (m[3]) ms = m[4] === 's' ? parseFloat(m[3]) * 1000 : parseFloat(m[3]);
+    if (ms != null && ms > 500) add('mot-01', file, lineNo, m[0], `UI transitions hold under the 500ms ceiling; ${ms}ms is too long.`);
+  }
+  // mot-04: banned easing (spring/bounce on operator surfaces, linear everywhere).
+  {
+    const lm = line.match(/\bease-linear\b|transition-timing-function\s*:\s*linear|animation-timing-function\s*:\s*linear/);
+    if (lm) add('mot-04', file, lineNo, lm[0], 'Ban linear easing; use the token ease-out (cubic-bezier(0,0,0.2,1)).');
+    if (/cubic-bezier\(\s*-?\d/.test(line)) {
+      const cb = line.match(/cubic-bezier\([^)]*\)/)[0];
+      const nums = cb.match(/-?\d*\.?\d+/g).map(Number);
+      if (nums.some((n) => n < 0 || n > 1)) add('mot-04', file, lineNo, cb, 'Ban spring/bounce easing (control points outside 0-1) on operator surfaces; use the token ease-out.');
+    }
+    if (/\b(?:ease-spring|ease-bounce|spring\()/.test(line)) add('mot-04', file, lineNo, (line.match(/ease-spring|ease-bounce|spring\(/) || [''])[0], 'Ban spring/bounce easing on operator surfaces; use the token ease-out.');
+  }
+  // mot-05: animating a layout property instead of transform/opacity.
+  {
+    const am = line.match(/transition-(?:all|left|top|width|height|margin)\b|transition\s*:\s*[^;]*\b(?:left|top|width|height|margin)\b|animate-\[[^\]]*\b(?:left|top|width|height|margin)\b/);
+    if (am) add('mot-05', file, lineNo, am[0], 'Animate only transform and opacity, never top/left/width/height/margin (transition-all included).');
+  }
+  // mot-06: will-change on a layout property or left standing without an animation.
+  {
+    const wm = line.match(/will-change\s*:\s*([^;]+)|will-change-\[?([\w,-]+)/);
+    if (wm) {
+      const val = (wm[1] || wm[2] || '').toLowerCase();
+      if (/left|top|width|height|margin|auto|all|scroll/.test(val) || (!/transform|opacity/.test(val))) {
+        add('mot-06', file, lineNo, wm[0], 'will-change only rides an in-progress transform/opacity animation; never blanket, never on a layout property, never left dangling.');
+      }
+    }
+  }
+  // mot-07: a loading indicator delay outside the 150-300ms band.
+  if (/skeleton|spinner|loading/i.test(line)) {
+    for (const m of line.matchAll(/(?:animation-delay|transition-delay|delay-\[)\s*:?\s*(\d+)ms/g)) {
+      const d = parseInt(m[1], 10);
+      if (d > 0 && (d < 150 || d > 300)) add('mot-07', file, lineNo, m[0], 'Loading-indicator delay sits in the 150-300ms band (nothing appears under 500ms).');
+    }
+  }
+  // mot-09: scroll-event listener driving animation.
+  if (/addEventListener\(\s*["']scroll["']/.test(line)) add('mot-09', file, lineNo, 'addEventListener("scroll")', 'Ban scroll-event listeners for animation; use IntersectionObserver or scroll-linked scrubbing.');
+  // mot-10: useState fed by a continuous scroll/pointer value.
+  if (/set\w+\(/.test(line) && /on(?:Scroll|MouseMove|PointerMove)=/.test(line)) {
+    add('mot-10', file, lineNo, (line.match(/on(?:Scroll|MouseMove|PointerMove)=[^ >]*/) || [''])[0], 'Ban useState for continuous scroll/pointer values; drive them with motion values instead.');
+  }
+
+  // --- States ---
+  // sta-05: a toast duration outside the 3-5s band.
+  for (const m of line.matchAll(/duration\s*[:=]\s*\{?\s*(\d{3,5})/g)) {
+    if (!/toast|Toaster|sonner/i.test(line)) continue;
+    const d = parseInt(m[1], 10);
+    if (d < 3000 || d > 5000) add('sta-05', file, lineNo, m[0], 'Toasts auto-dismiss in the 3-5s band, announce politely (aria-live="polite"), and never steal focus.');
+  }
+
+  // --- Code & tokens ---
+  // cod-03: a raw color/spacing/radius/duration literal inside an inline style object.
+  if (isJsx && /style=\{\{/.test(line)) {
+    const sm = line.match(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|oklch\([^)]*\)|:\s*['"]?\d+px|:\s*['"]?\d+ms/);
+    if (sm) add('cod-03', file, lineNo, sm[0], 'Every color/spacing/radius/duration resolves to an emitted token; do not inline a raw literal in a style prop.');
+  }
+  // cod-04: elision comments and brevity markers.
+  {
+    const cm = line.match(/\/\/\s*\.\.\.|\/\/\s*(?:rest of|remaining|existing)\b|\{\s*\/\*\s*\.\.\.|\/\*\s*\.\.\.\s*\*\/|\bfor brevity\b|\/\/\s*TODO\b/i);
+    if (cm) add('cod-04', file, lineNo, cm[0], 'No elision/brevity/TODO comments; emit the whole file, compiling.');
+  }
+  // cod-05: fabricated names, placeholder companies, and fake round metrics.
+  {
+    const fm = line.match(/\bJohn Doe\b|\bJane Doe\b|\bAcme\b|\bLorem ipsum\b|\bBY THE NUMBERS\b|\b99\.9[89]%|\b100% (?:uptime|guaranteed)\b/i);
+    if (fm) add('cod-05', file, lineNo, fm[0], 'Anti-fabrication: no invented metrics or placeholder names; use real data, a [bracket] placeholder, or mark mock numbers.');
+  }
+  // cod-07: a Google Fonts <link>/@import in production.
+  if (/fonts\.googleapis\.com|fonts\.gstatic\.com/.test(line)) add('cod-07', file, lineNo, (line.match(/https?:\/\/fonts\.[^"'\s)]+/) || ['fonts.googleapis.com'])[0], 'Never a Google Fonts link in prod; self-host or use next/font with font-display: swap.');
+  // cod-08: an <img> hotlinked or without declared dimensions / lazy-load.
+  if (/<img\b/i.test(line)) {
+    if (!/\bwidth=|\bheight=/.test(line)) add('cod-08', file, lineNo, '<img>', 'Images declare width/height (avoid CLS); below-the-fold images add loading="lazy".');
+    const src = line.match(/src=["'](https?:\/\/[^"']+)["']/);
+    if (src && !/picsum\.photos\/seed\//.test(src[1])) add('cod-08', file, lineNo, src[1], 'Image placeholders are deterministic seeds (picsum.photos/seed/{seed}/{w}/{h}), never a live hotlink.');
+  }
+  // cod-06: emoji character in source.
+  if (RE_EMOJI.test(line)) add('cod-06', file, lineNo, (line.match(RE_EMOJI) || [''])[0], 'No emoji anywhere and no emoji-as-icons; use inline SVG from one icon family.');
+  RE_EMOJI.lastIndex = 0;
+}
+
+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) {
+  const out = [];
+  let inBlock = false;
+  for (let raw of lines) {
+    let s = raw;
+    if (inBlock) {
+      const end = s.indexOf('*/');
+      if (end < 0) { out.push(''); continue; }
+      s = ' '.repeat(end + 2) + s.slice(end + 2);
+      inBlock = false;
+    }
+    // strip inline /* ... */ occurrences
+    s = s.replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length));
+    const openBlock = s.indexOf('/*');
+    if (openBlock >= 0 && s.indexOf('*/', openBlock) < 0) { s = s.slice(0, openBlock); inBlock = true; }
+    // strip // line comment when not part of :// (a URL scheme)
+    const lc = s.match(/(^|[^:])\/\/.*$/);
+    if (lc) s = s.slice(0, lc.index + lc[1].length);
+    out.push(s);
+  }
+  return out;
+}
+
+// Scan comment-stripped copy for em-dashes (typ-15) and three-period ellipses (typ-14).
+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$.([{])/);
+    if (el) add('typ-14', file, i + 1, '...', 'Use the ellipsis glyph (or an explicit loading label), not three periods.');
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Whole-file checks (need more than one line of context)
+// ---------------------------------------------------------------------------
+
+// Run the file-scoped source checks over one file's full text.
+function checkFile(add, file, ext, text, lines) {
+  const isJsx = ext === 'tsx' || ext === 'ts';
+
+  // dep-02: more than one <h1> in a view.
+  const h1s = [...text.matchAll(/<h1\b/gi)];
+  if (h1s.length > 1) {
+    const idx = text.slice(0, h1s[1].index).split('\n').length;
+    add('dep-02', file, idx, `${h1s.length} <h1> elements`, 'One h1 per view; keep a single <h1> and never skip heading levels.');
+  }
+
+  // mot-03: an animation present with no prefers-reduced-motion guard.
+  const hasAnim = /@keyframes\b|\banimate-(?!none\b)[\w[\]-]+|\.animate\(|animation\s*:/i.test(text);
+  const hasGuard = /prefers-reduced-motion|motion-reduce:|useReducedMotion/i.test(text);
+  if (hasAnim && !hasGuard) {
+    const idx = (text.match(/@keyframes|animate-|animation\s*:/i) ? text.slice(0, text.search(/@keyframes|animate-|animation\s*:/i)).split('\n').length : 1);
+    add('mot-03', file, idx, 'animation without reduced-motion guard', 'Every animation is gated on prefers-reduced-motion (0.01ms reset / motion-reduce:).');
+  }
+
+  // typ-07: a numeric table context with no tabular figures anywhere in the file.
+  if (isJsx && /<td\b/i.test(text)) {
+    const numeric = /toLocaleString\(|toFixed\(|Intl\.NumberFormat|\$\{?[\w.]+\}?\s*(?:USD|amount|price|total)|\bformatCurrency\b/i.test(text);
+    const tabular = /tabular-nums|font-variant-numeric|lining-nums|slashed-zero|tnum/i.test(text);
+    if (numeric && !tabular) {
+      const idx = text.slice(0, text.search(/<td\b/i)).split('\n').length;
+      add('typ-07', file, idx, 'numeric table cells without tabular-nums', 'Tabular lining numerals (tabular-nums) on every numeric column, KPI, timer, and ID.');
+    }
+  }
+
+  // sta-01: a collection render with none of loading/empty/error handling.
+  // A module-local literal array (e.g. a static nav constant) is not a data
+  // surface — only collections that arrive as data (imports, props, hooks,
+  // fetches) demand lifecycle states.
+  if (isJsx && /\.map\(/.test(text)) {
+    const hasState = /length\s*===?\s*0|isEmpty|Empty|isLoading|\bloading\b|Skeleton|Spinner|isError|\berror\b|catch\b/i.test(text);
+    if (!hasState) {
+      const mapRe = /(\w+)(?:\.\w+)*\.map\(/g;
+      let m;
+      let firstDataMapIdx = -1;
+      while ((m = mapRe.exec(text)) !== null) {
+        const localLiteral = new RegExp(`const\\s+${m[1]}(?:\\s*:\\s*[^=]+)?=\\s*\\[`).test(text);
+        if (!localLiteral) { firstDataMapIdx = m.index; break; }
+      }
+      if (firstDataMapIdx !== -1) {
+        const idx = text.slice(0, firstDataMapIdx).split('\n').length;
+        add('sta-01', file, idx, 'collection render with no loading/empty/error state', 'Every data surface ships loading, empty, error, and partial/degraded states; none are present here.');
+      }
+    }
+  }
+  // sta-02: an empty state that dead-ends (literal no-data message) or carries >1 action.
+  if (isJsx && /(?:isEmpty|length\s*===?\s*0|Empty)/i.test(text)) {
+    const deadEnd = text.match(/>\s*(?:No data(?:\s+available)?|Nothing (?:here|to show)|No results found\.?)\s*</i);
+    if (deadEnd) add('sta-02', file, text.slice(0, deadEnd.index).split('\n').length, deadEnd[0].trim(), 'Empty states are text-first with a next step, never a literal no-data dead-end; 1-2 sentences and at most one action.');
+  }
+  // sta-03: an error-state render that dead-ends — no recovery affordance in the rendered error block.
+  // The three-part error copy (what / why / how) stays judged; this shell flags only the mechanical dead
+  // end that an error state offers the operator no way forward. Matches the canonical error-render forms
+  // (an early return, an inline &&/? render, or a catch that returns JSX) and looks for any recovery
+  // affordance (retry / reload / link / action / handler) in the block that follows.
+  if (isJsx) {
+    const errorRender = /if\s*\(\s*(?:isError|hasError|loadError)\b[^)]*\)\s*(?:\{[^}]*)?return|(?:isError|hasError|loadError)\s*(?:&&|\?)\s*\(?\s*<|if\s*\(\s*status\s*===?\s*['"](?:error|failed)['"][^)]*\)\s*(?:\{[^}]*)?return|\}\s*catch\s*(?:\([^)]*\))?\s*\{[^}]*return\s*[<(]/g;
+    const RECOVERY = /onClick|onRetry|onReload|onRefresh|href=|<a\b|<Button\b|<button\b|\bretry\b|\breload\b|\brefresh\b|\brefetch\b|try again|go back/i;
+    let em;
+    while ((em = errorRender.exec(text)) !== null) {
+      const windowText = text.slice(em.index, em.index + 600);
+      if (!RECOVERY.test(windowText)) {
+        add('sta-03', file, text.slice(0, em.index).split('\n').length, 'error state with no recovery affordance', 'Error states never dead-end: state what happened, why, and how to recover, and give a way forward (retry, reload, or a link out) — not a bare failure message.');
+        break;
+      }
+    }
+  }
+
+  // int-01: a :focus / :focus-visible CSS rule that removes the outline with no visible ring replacement.
+  if (ext === 'css') {
+    for (const m of text.matchAll(/:focus(?:-visible)?\s*\{([^}]*)\}/g)) {
+      const body = m[1];
+      const removesOutline = /outline\s*:\s*(?:none|0)\b/.test(body);
+      const hasRing = /box-shadow\s*:\s*[^;]*\d/.test(body) || /outline-width\s*:/.test(body) || /outline-offset\s*:/.test(body) || /outline\s*:\s*[^;]*(?:px|rem|em|solid|auto|\d)/i.test(body) || /border(?:-\w+)?\s*:\s*[^;]*(?:px|solid|\d)/i.test(body) || /\bring-/.test(body);
+      if (removesOutline && !hasRing) add('int-01', file, text.slice(0, m.index).split('\n').length, m[0].replace(/\s+/g, ' ').slice(0, 60), 'Every interactive element ships a visible :focus-visible ring (>= 2px with offset); add a ring, do not merely remove the outline.');
+    }
+  }
+
+  // int-10: live-updating status (polling) with no aria-live region present.
+  if (isJsx && /setInterval\(/.test(text) && !/aria-live|role=["'](?:status|alert)["']/.test(text)) {
+    add('int-10', file, text.slice(0, text.search(/setInterval\(/)).split('\n').length, 'polling status update without aria-live', 'An aria-live region is present wherever async status updates render; wrap the live status in role="status" / aria-live="polite".');
+  }
+
+  // cod-01: a token-defining CSS file that omits some of the 34 consumed tokens.
+  if (ext === 'css' && /--background\b/.test(text) && /--foreground\b/.test(text)) {
+    const missing = REQUIRED_TOKENS.filter((t) => !new RegExp(`--${t}\\s*:`).test(text));
+    if (missing.length) add('cod-01', file, 1, `missing tokens: ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? '…' : ''}`, 'Emitted CSS defines every token the substrate consumes; add the missing --token definitions.');
+  }
+
+  // cod-09: a component file well over the line ceiling.
+  if (isJsx && lines.length > 250) add('cod-09', file, lines.length, `${lines.length} lines`, 'Component line ceilings hold (< 120 ln table, < 80 ln section); split this file.');
+
+  // cod-11: an exported component that takes props with no typed Props.
+  if (ext === 'tsx') {
+    const untyped = text.match(/export\s+(?:default\s+)?function\s+[A-Z]\w*\(\s*\{[^}]*\}\s*\)(?!\s*:)/) ||
+      text.match(/export\s+(?:default\s+)?function\s+[A-Z]\w*\(\s*props\s*\)/);
+    const hasTypedProps = /interface\s+\w*Props\b|type\s+\w*Props\b|:\s*\w*Props\b|React\.FC</.test(text);
+    if (untyped && !hasTypedProps) {
+      add('cod-11', file, text.slice(0, untyped.index).split('\n').length, untyped[0].slice(0, 60), 'Every emitted component exports a typed Props interface; annotate the props.');
+    }
+  }
+}
+
+const REQUIRED_TOKENS = [
+  'background', 'foreground', 'card', 'card-foreground', 'muted', 'muted-foreground', 'border', 'input', 'ring',
+  'primary', 'primary-foreground', 'accent', 'accent-foreground', 'destructive', 'destructive-foreground', 'success', 'warning',
+  'popover', 'popover-foreground', 'secondary', 'secondary-foreground',
+  'chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5',
+  'sidebar', 'sidebar-foreground', 'sidebar-primary', 'sidebar-primary-foreground',
+  'sidebar-accent', 'sidebar-accent-foreground', 'sidebar-border', 'sidebar-ring',
+];
+
+// ---------------------------------------------------------------------------
+// Cross-file checks (aggregate over all files passed this invocation)
+// ---------------------------------------------------------------------------
+
+// Run the checks that need the whole passed-in file set (token-set counts, distinct sizes).
+function checkCrossFile(add, docs) {
+  // typ-06: more than two font families declared across the passed files.
+  const families = new Set();
+  const iconLibs = new Set();
+  const explicitSizes = new Map(); // px -> {file,line,text}
+  const hexByHue = new Map();      // hue bucket -> Set(normHex)
+  let sectionCount = 0;
+  let capsTrackCount = 0;
+  let capsTrackAnchor = null;
+
+  for (const d of docs) {
+    d.lines.forEach((line, i) => {
+      // font families from declarations / --font-* / font-[Family]
+      for (const m of line.matchAll(/font-family\s*:\s*([^;{}]+)[;}]?|--font-[\w-]+\s*:\s*([^;]+);|font-\[["']?([A-Za-z][\w\s-]+)["']?\]/g)) {
+        const raw = (m[1] || m[2] || m[3] || '').trim();
+        const first = raw.split(',')[0].replace(/["']/g, '').trim().toLowerCase();
+        if (first && !/^var\(/.test(first)) families.add(first);
+      }
+      // icon libraries from imports
+      const imp = line.match(/from\s+["'](lucide-react|@heroicons\/\w+|react-icons(?:\/\w+)?|@phosphor-icons\/\w+|phosphor-react)["']/);
+      if (imp) iconLibs.add(imp[1].split('/')[0]);
+      // explicit numeric font sizes (arbitrary tailwind or CSS), for typ-10
+      for (const m of line.matchAll(/text-\[(\d*\.?\d+)(px|rem)\]|font-size\s*:\s*(\d*\.?\d+)(px|rem)/g)) {
+        const px = m[1] ? toPx(m[1], m[2]) : toPx(m[3], m[4]);
+        if (px != null && !explicitSizes.has(px)) explicitSizes.set(px, { file: d.file, line: i + 1, text: (m[0]) });
+      }
+      // hex color families for col-08 over-count
+      for (const m of line.matchAll(/#[0-9a-fA-F]{6}\b/g)) {
+        const hue = hexHueBucket(m[0]);
+        if (!hexByHue.has(hue)) hexByHue.set(hue, new Set());
+        hexByHue.get(hue).add(normColor(m[0]));
+      }
+      // typ-18 section + caps-tracking tally
+      if (/<section\b/i.test(line)) sectionCount += (line.match(/<section\b/gi) || []).length;
+      if (/\buppercase\b/.test(line) && /tracking-(?:wide|wider|widest)/.test(line)) {
+        capsTrackCount++;
+        if (!capsTrackAnchor) capsTrackAnchor = { file: d.file, line: i + 1 };
+      }
+    });
+  }
+
+  if (families.size > 2) {
+    const d = docs[0];
+    add('typ-06', d.file, 1, `${families.size} font families: ${[...families].join(', ')}`, 'At most two font families per app (a sans and a mono); drop the extra family.');
+  }
+
+  // typ-10: adjacent explicitly-declared type-scale steps closer than 25%.
+  const sizes = [...explicitSizes.keys()].sort((a, b) => a - b);
+  if (sizes.length >= 3) {
+    for (let i = 1; i < sizes.length; i++) {
+      if (sizes[i] / sizes[i - 1] < 1.25) {
+        const anc = explicitSizes.get(sizes[i]);
+        add('typ-10', anc.file, anc.line, `${sizes[i - 1]}px and ${sizes[i]}px`, 'Adjacent type-scale steps stay >= 25% apart; merge these near-duplicate steps.');
+      }
+    }
+  }
+  // spc-02 is checked with the same near-duplicate logic over explicit spacing (below).
+
+  // col-08: a color family exceeding the 10-shade ceiling.
+  for (const [hue, set] of hexByHue) {
+    if (set.size > 10) {
+      const d = docs[0];
+      add('col-08', d.file, 1, `${set.size} ${hue} shades`, 'Shade counts stay bounded (greys 8-10, each accent family 5-10); this family exceeds 10.');
+    }
+  }
+
+  // typ-18: uppercase-tracking instances beyond ceil(sectionCount/3).
+  if (sectionCount > 0 && capsTrackCount > Math.ceil(sectionCount / 3) && capsTrackAnchor) {
+    add('typ-18', capsTrackAnchor.file, capsTrackAnchor.line, `${capsTrackCount} caps-tracked labels vs ${sectionCount} sections`, 'Ration eyebrow/micro-label uppercase-tracking against section count (<= ceil(sectionCount/3)).');
+  }
+
+  if (iconLibs.size > 1) {
+    const d = docs[0];
+    add('cod-06', d.file, 1, `icon families: ${[...iconLibs].join(', ')}`, 'One icon family per app; consolidate onto a single family (lucide).');
+  }
+}
+
+// Run spc-02 over explicit spacing values collected across files.
+function checkSpacingScale(add, docs) {
+  const spacings = new Map();
+  for (const d of docs) {
+    d.lines.forEach((line, i) => {
+      for (const m of line.matchAll(/(?:[pm][trblxy]?|gap(?:-[xy])?|space-[xy]|inset)-\[(\d*\.?\d+)(px|rem)\]/g)) {
+        const px = toPx(m[1], m[2]);
+        if (px != null && !spacings.has(px)) spacings.set(px, { file: d.file, line: i + 1 });
+      }
+    });
+  }
+  const vals = [...spacings.keys()].sort((a, b) => a - b);
+  if (vals.length >= 3) {
+    for (let i = 1; i < vals.length; i++) {
+      if (vals[i] / vals[i - 1] < 1.25) {
+        const anc = spacings.get(vals[i]);
+        add('spc-02', anc.file, anc.line, `${vals[i - 1]}px and ${vals[i]}px`, 'Adjacent spacing values stay >= 25% apart; these declared steps are too close.');
+      }
+    }
+  }
+}
+
+// Bucket a 6-digit hex into a coarse hue family name for shade counting.
+function hexHueBucket(hex) {
+  const h = expandHex(hex);
+  const r = parseInt(h.slice(0, 2), 16), g = parseInt(h.slice(2, 4), 16), b = parseInt(h.slice(4, 6), 16);
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  if (max - min < 24) return 'grey';
+  let hue;
+  const d = max - min;
+  if (max === r) hue = ((g - b) / d) % 6;
+  else if (max === g) hue = (b - r) / d + 2;
+  else hue = (r - g) / d + 4;
+  hue = (hue * 60 + 360) % 360;
+  if (hue < 20 || hue >= 340) return 'red';
+  if (hue < 45) return 'orange';
+  if (hue < 70) return 'yellow';
+  if (hue < 165) return 'green';
+  if (hue < 200) return 'teal';
+  if (hue < 255) return 'blue';
+  if (hue < 290) return 'violet';
+  return 'pink';
+}
+
+// ---------------------------------------------------------------------------
+// cod-02 — lever-manifest drift check (D10)
+// ---------------------------------------------------------------------------
+
+// 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;
+}
+
+// Tolerantly pull the allowed vocabulary (colors, scales, fonts) out of a lever-manifest body.
+function parseManifestVocab(body) {
+  const stripComment = (s) => s.replace(/\s+#.*$/, '');
+  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;
+      }
+    }
+  }
+  // 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 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 };
+}
+
+// Flag any color/spacing/radius/duration/font literal in the diff files outside the manifest vocabulary (cod-02).
+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
+    }
+    d.lines.forEach((line, i) => {
+      const isJsx = d.ext === 'tsx' || d.ext === 'ts' || d.ext === 'html';
+      // 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.');
+        }
+      }
+      // spacing (explicit only)
+      if (vocab.spacing && vocab.spacing.size) {
+        for (const m of line.matchAll(/(?:[pm][trblxy]?|gap(?:-[xy])?|space-[xy]|inset)-\[(\d*\.?\d+)(px|rem)\]/g)) {
+          const px = toPx(m[1], m[2]);
+          if (px != null && !vocab.spacing.has(px)) add('cod-02', d.file, i + 1, m[0], `Spacing ${px}px is off the manifest spacing-scale; snap to a listed step.`);
+        }
+      }
+      // radius (explicit only)
+      if (vocab.radius && vocab.radius.size) {
+        for (const m of line.matchAll(/rounded-\[(\d*\.?\d+)(px|rem)?\]|border-radius\s*:\s*(\d*\.?\d+)(px|rem)/g)) {
+          const px = m[1] ? toPx(m[1], m[2] || 'px') : toPx(m[3], m[4]);
+          if (px != null && !vocab.radius.has(px)) add('cod-02', d.file, i + 1, m[0], `Radius ${px}px is off the manifest radius-scale; use a listed radius.`);
+        }
+      }
+      // durations (explicit only)
+      if (vocab.durations && vocab.durations.size) {
+        for (const m of line.matchAll(/duration-\[(\d+)ms\]|duration-(\d{2,4})\b/g)) {
+          const ms = m[1] ? parseInt(m[1], 10) : parseInt(m[2], 10);
+          if (!vocab.durations.has(ms)) add('cod-02', d.file, i + 1, m[0], `Duration ${ms}ms is off the manifest motion.durations; use a listed duration.`);
+        }
+      }
+      // fonts (declared families)
+      if (isJsx && vocab.fonts.size) {
+        for (const m of line.matchAll(/font-\[["']?([A-Za-z][\w\s-]+)["']?\]/g)) {
+          const fam = m[1].split(',')[0].replace(/["']/g, '').trim().toLowerCase();
+          if (!vocab.fonts.has(fam)) add('cod-02', d.file, i + 1, m[0], `Font "${m[1]}" is not in the manifest fonts; use the declared sans/mono.`);
+        }
+      }
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+
+// 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); }
+
+  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);
+    checkCopy(sink.add, d.file, cleanComments(d.lines));
+  }
+  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));
+    }
+  }
+
+  // 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);
+}
+
+main();