@nurix/etna 0.19.66 → 0.19.68

package/data/harnesses/apollo/skills/design/scripts/validate-design-md.mjs

@@ -1,1198 +0,0 @@
-// skills/design/scripts/validate-design-md.mjs - the design.md system's validator + token emitter (v2 schema)
-//
-// The entire mechanical apparatus of the design.md system (docs/features/design-skill/08 §The validator):
-// one stdlib-only script, three moments — library admission, build-time on the project fork, and the
-// ship gate's drift check. Vendors its own YAML-subset parser (frontmatter + the `yaml design-values`
-// block) and its own oklch → sRGB → WCAG-contrast math. FAIL closes; WARN never does.
-//
-// CLI:
-//   node validate-design-md.mjs <file|folder> [--mode admission|build|ship] [--json] [--emit]
-//
-//   <file>     validate one design.md.
-//   <folder>   validate every .md in the folder tree (skipping SCHEMA.md) plus index.csv integrity (dmv-07)
-//              and the tree-wide naming scan (dmv-09).
-//   --mode     admission and build run the same check set; ship additionally runs dmv-11 (drift:
-//              re-emit and byte-compare against a design.tokens.css sitting beside the input file).
-//              Default: build.
-//   --json     machine report to stdout: {file, fails:[{id,detail}], warns:[{id,detail}]}
-//              (an array of those objects in folder mode; folder-level checks attach to the folder path).
-//   --emit     compile the token artifact from the design-values block to stdout (byte-stable across
-//              runs; redirect to design.tokens.css). Requires a single file; validation runs first and
-//              any FAIL suppresses the artifact (report goes to stderr). Warns go to stderr.
-//
-// Exit codes: 0 pass (warns allowed), 1 any FAIL.
-//
-// FAIL checks (stable IDs, 08 §The validator):
-//   dmv-01  frontmatter parses (strict YAML subset: no tabs, no duplicate keys, fixed key set);
-//           schema: design-md/v2; required keys per tier; id matches filename.
-//   dmv-02  the 12 numbered sections present, in order, non-empty; one trailing `yaml design-values` block.
-//   dmv-03  the design-values block parses as YAML.
-//   dmv-04  coverage: all 36 color roles × both themes (values parseable); type ramp steps
-//           display/h1/h2/body/small/caption/data each with size+line+weight+family; register-scope;
-//           elevation (radius, hairline, shadow, dark-ladder); motion (duration, easing, entrance-never,
-//           identity-moments); iconography (set, stroke, grid); charts (categorical, sequential,
-//           diverging); layout (base).
-//   dmv-05  contrast on every declared pairing, both themes (pair table below).
-//   dmv-06  no image reference anywhere in the file (law 7 — the shipped skill carries no pixels).
-//   dmv-07  (folder mode) index.csv integrity, both directions: every row's file exists; every package
-//           file has exactly one row; no duplicate file column.
-//   dmv-08  font families use registered names ("Inter Variable", not "Inter" — known-bare-name table
-//           below) and each declares a fallback stack ending in a generic family.
-//   dmv-09  naming hygiene: no file named claude.md / CLAUDE.md (any case).
-//   dmv-10  (tier: project only) primitives present, exactly nurix|native; source-package present.
-//   dmv-11  (--mode ship) drift: the token artifact recompiled from the design.md byte-matches the
-//           design.tokens.css beside it.
-//
-// dmv-05 — the exact contrast pair table (both themes; WCAG 2.1 relative-luminance contrast; colors
-// resolved oklch → OKLab → linear sRGB, gamut-clipped to [0,1], gamma-encoded, then the WCAG formula;
-// alpha is ignored — pairs are assumed opaque):
-//   body-text pairs — FAIL below 4.5:1:
-//     foreground                 on background
-//     foreground                 on card
-//     foreground                 on muted
-//     card-foreground            on card
-//     popover-foreground         on popover
-//     secondary-foreground       on secondary
-//     muted-foreground           on muted
-//     sidebar-foreground         on sidebar
-//     sidebar-accent-foreground  on sidebar-accent
-//   UI/fill pairs — FAIL below 3.0:1, WARN below 4.5:1 (reported under dmv-05):
-//     primary-foreground         on primary
-//     accent-foreground          on accent
-//     destructive-foreground     on destructive
-//     sidebar-primary-foreground on sidebar-primary
-//
-// WARN checks (taste smells — flags for the eyes, thresholds inline from the 08 warn table):
-//   dmw-01  background inside the anti-cream band (L 0.84–0.97, C < 0.06, hue 40–100).
-//   dmw-02  neutral surfaces pure gray (C < 0.005) or over-tinted (C > 0.015); neutral set =
-//           background, card, popover, secondary, muted, border, input, surface-raised, surface-overlay;
-//           true white/black (L ≥ 0.99 or ≤ 0.03) exempt — chroma is unrepresentable at the gamut poles.
-//   dmw-03  any shadow color pure black (L < 0.1, C < 0.01) above 0.15 alpha (untinted).
-//   dmw-04  any entrance easing `ease-in` (keyword or ease-in-shaped cubic-bezier); any duration above
-//           its element-class budget (A6): press/tap 150ms, fade/enter 250ms, dialog/popover 300ms,
-//           page/route 350ms, panel/drawer 400ms, anything else 500ms.
-//   dmw-05  display family granted a data register (cells, buttons, labels, …) in register-scope.
-//   dmw-06  dark theme without a lightness ladder: surface-raised / surface-overlay not ≥ ~0.04 L
-//           (implemented as ≥ 0.035) above the surface below, or ladder hue drifting > 15° from
-//           background (checked only where chroma ≥ 0.01 — hue is noise near gray).
-//   dmw-07  accent chroma delta between themes > 0.06 (identity likely not held across themes).
-//
-// Emitted artifact shape (deterministic, byte-stable): a `:root, :root[data-theme="light"]` block and a
-// `:root[data-theme="dark"]` block (specificity armor — both selectors reach 0,2,0 via the attribute
-// form, so a component library's later bare `:root` cannot silently defeat a theme). The light block
-// carries the 36 roles as --<role> plus every theme-invariant group: --font-display/sans/mono (registered
-// names quoted, declared fallback stacks appended), --text-<step>-size/-line/-weight (+ -family/-tracking/
-// -features where authored), --radius-*, --shadow-*, --duration-*, --ease-*, and the layout vars
-// (--space-base, --sidebar-width[-collapsed], --topbar-height, --side-panel-width[-wide],
-// --content-max-width; unmapped keys emit as --layout-<key>). The dark block carries the 36 dark roles.
-
-import { readFileSync, existsSync, statSync, readdirSync } from "node:fs";
-import { join, resolve, basename, dirname, relative, sep } from "node:path";
-import { pathToFileURL } from "node:url";
-import process from "node:process";
-
-// ---------------------------------------------------------------------------
-// The v2 schema constants
-// ---------------------------------------------------------------------------
-
-// The 36-role roster, verbatim from 08 §The value block.
-export const COLOR_ROLES = [
-    "background", "foreground", "card", "card-foreground", "popover", "popover-foreground",
-    "primary", "primary-foreground", "secondary", "secondary-foreground", "muted", "muted-foreground",
-    "accent", "accent-foreground", "destructive", "destructive-foreground", "success", "warning",
-    "border", "input", "ring", "surface-raised", "surface-overlay",
-    "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",
-];
-
-const SECTIONS = [
-    "1 Visual Theme", "2 Color Roles", "3 Typography", "4 Component Stylings", "5 Layout",
-    "6 Depth", "7 Motion", "8 Iconography & Charts", "9 Voice", "10 Do's & Don'ts",
-    "11 Responsive", "12 Agent Prompt Guide",
-];
-
-const RAMP_STEPS = ["display", "h1", "h2", "body", "small", "caption", "data"];
-const FONT_SLOTS = ["display", "sans", "mono"];
-const THEMES = ["light", "dark"];
-const TIERS = ["default", "variant", "brand", "project"];
-const FRONT_KEYS_BASE = ["schema", "id", "tier", "segments", "keywords", "sourced", "sources", "license"];
-const FRONT_KEYS_PROJECT = ["primitives", "source-package"];
-
-const BODY_PAIRS = [
-    ["foreground", "background"], ["foreground", "card"], ["foreground", "muted"],
-    ["card-foreground", "card"], ["popover-foreground", "popover"],
-    ["secondary-foreground", "secondary"], ["muted-foreground", "muted"],
-    ["sidebar-foreground", "sidebar"], ["sidebar-accent-foreground", "sidebar-accent"],
-];
-const UI_PAIRS = [
-    ["primary-foreground", "primary"], ["accent-foreground", "accent"],
-    ["destructive-foreground", "destructive"], ["sidebar-primary-foreground", "sidebar-primary"],
-];
-
-const NEUTRAL_SURFACE_ROLES = [
-    "background", "card", "popover", "secondary", "muted", "border", "input",
-    "surface-raised", "surface-overlay",
-];
-
-// Bare name → registered family, for the variable-first families the skill derives from
-// @fontsource-variable/* (registered as "<Family> Variable"). Extend as the library grows.
-const BARE_FONT_NAMES = {
-    "inter": "Inter Variable", "fraunces": "Fraunces Variable", "manrope": "Manrope Variable",
-    "sora": "Sora Variable", "outfit": "Outfit Variable", "epilogue": "Epilogue Variable",
-    "karla": "Karla Variable", "lora": "Lora Variable", "newsreader": "Newsreader Variable",
-    "space grotesk": "Space Grotesk Variable", "work sans": "Work Sans Variable",
-    "instrument sans": "Instrument Sans Variable", "public sans": "Public Sans Variable",
-    "plus jakarta sans": "Plus Jakarta Sans Variable", "figtree": "Figtree Variable",
-    "schibsted grotesk": "Schibsted Grotesk Variable", "bricolage grotesque": "Bricolage Grotesque Variable",
-    "source sans 3": "Source Sans 3 Variable", "dm sans": "DM Sans Variable", "geist": "Geist Variable",
-};
-
-const GENERIC_FAMILIES = new Set([
-    "serif", "sans-serif", "monospace", "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace",
-    "ui-rounded", "cursive", "fantasy", "math", "emoji", "fangsong",
-]);
-
-// A6 element-class duration budgets (ms), matched against the duration's name; first hit wins.
-const DURATION_BUDGETS = [
-    [/press|tap|click|toggle|hover|instant/i, 150],
-    [/fade|arrive|appear|enter|reveal/i, 250],
-    [/panel|drawer|sheet|slide/i, 400],
-    [/dialog|modal|popover|overlay|menu|tooltip/i, 300],
-    [/page|route|view/i, 350],
-];
-const DURATION_BUDGET_DEFAULT = 500;
-
-const DATA_REGISTER_WORDS = new Set([
-    "data", "cell", "cells", "table", "tables", "row", "rows", "button", "buttons", "label", "labels",
-    "control", "controls", "chrome", "form", "forms", "input", "inputs", "id", "ids",
-    "timestamp", "timestamps", "numeral", "numerals", "badge", "badges", "chip", "chips",
-]);
-
-// --emit names for layout keys; arrays map positionally; unmapped keys fall back to --layout-<key>[-n].
-const LAYOUT_EMIT = {
-    "base": ["--space-base"],
-    "sidebar": ["--sidebar-width", "--sidebar-width-collapsed"],
-    "topbar": ["--topbar-height"],
-    "side-panel": ["--side-panel-width", "--side-panel-width-wide"],
-    "content-max": ["--content-max-width"],
-};
-
-// ---------------------------------------------------------------------------
-// Vendored YAML-subset parser (block maps/seqs by indentation; single-line flow
-// maps/seqs; double/single-quoted and plain scalars; comments; no anchors,
-// no multi-line scalars, no tabs, no duplicate keys)
-// ---------------------------------------------------------------------------
-
-class YamlError extends Error {}
-
-const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-
-export function parseYaml(src, label) {
-    const rawLines = src.split(/\r?\n/);
-    const lines = [];
-    for (let i = 0; i < rawLines.length; i++) {
-        const raw = rawLines[i];
-        if (/^\s*$/.test(raw) || /^\s*#/.test(raw)) continue;
-        if (/^ *\t/.test(raw)) throw new YamlError(`${label} line ${i + 1}: tabs are not allowed in indentation`);
-        const indent = raw.match(/^ */)[0].length;
-        lines.push({ indent, text: raw.slice(indent).replace(/\s+$/, ""), lineNo: i + 1 });
-    }
-    if (lines.length === 0) return {};
-    const ctx = { lines, pos: 0, label };
-    const value = parseBlock(ctx, lines[0].indent);
-    if (ctx.pos < lines.length) {
-        const l = ctx.lines[ctx.pos];
-        throw new YamlError(`${label} line ${l.lineNo}: unexpected content "${l.text}"`);
-    }
-    return value;
-}
-
-function parseBlock(ctx, indent) {
-    const first = ctx.lines[ctx.pos];
-    if (first.text === "-" || first.text.startsWith("- ")) return parseBlockSeq(ctx, indent);
-    return parseBlockMap(ctx, indent);
-}
-
-function parseBlockMap(ctx, indent) {
-    const obj = {};
-    while (ctx.pos < ctx.lines.length) {
-        const line = ctx.lines[ctx.pos];
-        if (line.indent < indent) break;
-        if (line.indent > indent) throw new YamlError(`${ctx.label} line ${line.lineNo}: unexpected indent`);
-        if (line.text === "-" || line.text.startsWith("- ")) break;
-        const m = matchKey(line.text);
-        if (!m) throw new YamlError(`${ctx.label} line ${line.lineNo}: expected "key: value"`);
-        if (Object.prototype.hasOwnProperty.call(obj, m.key)) {
-            throw new YamlError(`${ctx.label} line ${line.lineNo}: duplicate key "${m.key}"`);
-        }
-        ctx.pos++;
-        if (m.rest === "") {
-            const next = ctx.lines[ctx.pos];
-            obj[m.key] = next && next.indent > indent ? parseBlock(ctx, next.indent) : null;
-        } else {
-            obj[m.key] = parseInlineValue(m.rest, `${ctx.label} line ${line.lineNo}`);
-        }
-    }
-    return obj;
-}
-
-function parseBlockSeq(ctx, indent) {
-    const arr = [];
-    while (ctx.pos < ctx.lines.length) {
-        const line = ctx.lines[ctx.pos];
-        if (line.indent < indent) break;
-        if (line.indent > indent) throw new YamlError(`${ctx.label} line ${line.lineNo}: unexpected indent`);
-        if (!(line.text === "-" || line.text.startsWith("- "))) break;
-        const rest = line.text === "-" ? "" : line.text.slice(2).trim();
-        ctx.pos++;
-        if (rest === "") {
-            const next = ctx.lines[ctx.pos];
-            arr.push(next && next.indent > indent ? parseBlock(ctx, next.indent) : null);
-        } else {
-            arr.push(parseInlineValue(rest, `${ctx.label} line ${line.lineNo}`));
-        }
-    }
-    return arr;
-}
-
-// Splits "key: rest" at the first ':' followed by a space or end-of-line.
-function matchKey(text) {
-    let key, restStart;
-    if (text[0] === '"' || text[0] === "'") {
-        const q = readQuoted(text, 0, "key");
-        if (text[q.end] !== ":") return null;
-        key = q.value;
-        restStart = q.end + 1;
-    } else {
-        let idx = -1;
-        for (let i = 0; i < text.length; i++) {
-            if (text[i] === ":" && (i + 1 === text.length || text[i + 1] === " ")) { idx = i; break; }
-        }
-        if (idx === -1) return null;
-        key = text.slice(0, idx).trim();
-        restStart = idx + 1;
-    }
-    if (!key) return null;
-    return { key, rest: text.slice(restStart).trim() };
-}
-
-function parseInlineValue(str, where) {
-    const s = str.trim();
-    if (s === "") return null;
-    const c = s[0];
-    if (c === "{" || c === "[") {
-        const r = parseFlow(s, 0, where);
-        ensureOnlyCommentAfter(s, r.end, where);
-        return r.value;
-    }
-    if (c === '"' || c === "'") {
-        const q = readQuoted(s, 0, where);
-        ensureOnlyCommentAfter(s, q.end, where);
-        return q.value;
-    }
-    let cut = s.length;
-    for (let i = 1; i < s.length; i++) {
-        if (s[i] === "#" && /\s/.test(s[i - 1])) { cut = i; break; }
-    }
-    return convertScalar(s.slice(0, cut).trim());
-}
-
-function ensureOnlyCommentAfter(s, idx, where) {
-    const rest = s.slice(idx).trim();
-    if (rest !== "" && !rest.startsWith("#")) throw new YamlError(`${where}: unexpected trailing content "${rest}"`);
-}
-
-function readQuoted(s, pos, where) {
-    const q = s[pos];
-    let out = "";
-    let i = pos + 1;
-    while (i < s.length) {
-        const c = s[i];
-        if (q === '"' && c === "\\") {
-            const n = s[i + 1];
-            out += n === "n" ? "\n" : n === "t" ? "\t" : (n ?? "");
-            i += 2;
-            continue;
-        }
-        if (c === q) {
-            if (q === "'" && s[i + 1] === "'") { out += "'"; i += 2; continue; }
-            return { value: out, end: i + 1 };
-        }
-        out += c;
-        i++;
-    }
-    throw new YamlError(`${where}: unterminated quoted string`);
-}
-
-const skipWs = (s, pos) => { while (pos < s.length && s[pos] === " ") pos++; return pos; };
-
-function parseFlow(s, pos, where) {
-    pos = skipWs(s, pos);
-    const c = s[pos];
-    if (c === "{") {
-        const obj = {};
-        pos = skipWs(s, pos + 1);
-        if (s[pos] === "}") return { value: obj, end: pos + 1 };
-        for (;;) {
-            let key;
-            if (s[pos] === '"' || s[pos] === "'") {
-                const q = readQuoted(s, pos, where);
-                key = q.value;
-                pos = skipWs(s, q.end);
-            } else {
-                let j = pos;
-                while (j < s.length && s[j] !== ":") j++;
-                if (j >= s.length) throw new YamlError(`${where}: missing ":" in flow map`);
-                key = s.slice(pos, j).trim();
-                pos = j;
-            }
-            if (s[pos] !== ":") throw new YamlError(`${where}: expected ":" after flow key "${key}"`);
-            if (Object.prototype.hasOwnProperty.call(obj, key)) throw new YamlError(`${where}: duplicate key "${key}"`);
-            const r = parseFlowValue(s, pos + 1, where);
-            obj[key] = r.value;
-            pos = skipWs(s, r.end);
-            if (s[pos] === ",") { pos = skipWs(s, pos + 1); continue; }
-            if (s[pos] === "}") return { value: obj, end: pos + 1 };
-            throw new YamlError(`${where}: expected "," or "}" in flow map`);
-        }
-    }
-    if (c === "[") {
-        const arr = [];
-        pos = skipWs(s, pos + 1);
-        if (s[pos] === "]") return { value: arr, end: pos + 1 };
-        for (;;) {
-            const r = parseFlowValue(s, pos, where);
-            arr.push(r.value);
-            pos = skipWs(s, r.end);
-            if (s[pos] === ",") { pos = skipWs(s, pos + 1); continue; }
-            if (s[pos] === "]") return { value: arr, end: pos + 1 };
-            throw new YamlError(`${where}: expected "," or "]" in flow sequence`);
-        }
-    }
-    throw new YamlError(`${where}: expected a flow collection`);
-}
-
-function parseFlowValue(s, pos, where) {
-    pos = skipWs(s, pos);
-    const c = s[pos];
-    if (c === "{" || c === "[") return parseFlow(s, pos, where);
-    if (c === '"' || c === "'") return readQuoted(s, pos, where);
-    // Plain scalar in flow context: runs to the next , } ] outside parentheses,
-    // so unquoted oklch(…)/cubic-bezier(…) values survive intact.
-    let depth = 0;
-    let i = pos;
-    for (; i < s.length; i++) {
-        const ch = s[i];
-        if (ch === "(") depth++;
-        else if (ch === ")") depth = Math.max(0, depth - 1);
-        else if (depth === 0 && (ch === "," || ch === "}" || ch === "]")) break;
-    }
-    return { value: convertScalar(s.slice(pos, i).trim()), end: i };
-}
-
-function convertScalar(raw) {
-    if (raw === "" || raw === "null" || raw === "~") return null;
-    if (raw === "true") return true;
-    if (raw === "false") return false;
-    if (/^-?(\d+\.?\d*|\.\d+)$/.test(raw)) return Number(raw);
-    return raw;
-}
-
-// ---------------------------------------------------------------------------
-// Vendored color math: oklch → OKLab → linear sRGB (gamut-clipped) → WCAG contrast
-// ---------------------------------------------------------------------------
-
-function oklchToSrgb(L, C, Hdeg) {
-    const h = (Hdeg * Math.PI) / 180;
-    const a = C * Math.cos(h);
-    const b = C * Math.sin(h);
-    const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
-    const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
-    const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
-    const l = l_ ** 3;
-    const m = m_ ** 3;
-    const s = s_ ** 3;
-    const lin = [
-        4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
-        -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
-        -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
-    ];
-    return lin.map((ch) => {
-        const v = Math.min(1, Math.max(0, ch)); // gamut clip
-        return v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
-    });
-}
-
-function srgbToOklch(srgb) {
-    const [r, g, bl] = srgb.map((c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)));
-    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * bl);
-    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * bl);
-    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * bl);
-    const L = 0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s;
-    const a = 1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s;
-    const b = 0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s;
-    const C = Math.hypot(a, b);
-    let H = (Math.atan2(b, a) * 180) / Math.PI;
-    H = ((H % 360) + 360) % 360;
-    return { L, C, H };
-}
-
-// Parses an oklch(L C H [/ a]) or #hex color into { L, C, H, alpha, srgb }; null if unparseable.
-export function parseColor(str) {
-    if (typeof str !== "string") return null;
-    const s = str.trim();
-    let m = s.match(/^oklch\(\s*(\d*\.?\d+)(%)?\s+(\d*\.?\d+)\s+(-?\d*\.?\d+)(?:deg)?\s*(?:\/\s*(\d*\.?\d+)(%)?\s*)?\)$/i);
-    if (m) {
-        const L = parseFloat(m[1]) / (m[2] ? 100 : 1);
-        const C = parseFloat(m[3]);
-        const H = ((parseFloat(m[4]) % 360) + 360) % 360;
-        const alpha = m[5] == null ? 1 : parseFloat(m[5]) / (m[6] ? 100 : 1);
-        return { L, C, H, alpha, srgb: oklchToSrgb(L, C, H) };
-    }
-    m = s.match(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
-    if (m) {
-        let hex = m[1];
-        if (hex.length === 3) hex = hex.split("").map((c) => c + c).join("");
-        const srgb = [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
-        const alpha = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1;
-        const { L, C, H } = srgbToOklch(srgb);
-        return { L, C, H, alpha, srgb };
-    }
-    return null;
-}
-
-function relativeLuminance(srgb) {
-    const [r, g, b] = srgb.map((c) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)));
-    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-
-export function contrastRatio(c1, c2) {
-    const y1 = relativeLuminance(c1.srgb);
-    const y2 = relativeLuminance(c2.srgb);
-    const hi = Math.max(y1, y2);
-    const lo = Math.min(y1, y2);
-    return (hi + 0.05) / (lo + 0.05);
-}
-
-const hueDistance = (a, b) => { const d = Math.abs(a - b) % 360; return Math.min(d, 360 - d); };
-const fmtNum = (n) => String(Math.round(n * 10000) / 10000);
-
-// ---------------------------------------------------------------------------
-// Report plumbing
-// ---------------------------------------------------------------------------
-
-const fail = (report, id, detail) => report.fails.push({ id, detail });
-const warn = (report, id, detail) => report.warns.push({ id, detail });
-
-// ---------------------------------------------------------------------------
-// Checks
-// ---------------------------------------------------------------------------
-
-// dmv-06 — no image reference anywhere in the raw file.
-function checkNoImages(raw, report) {
-    const patterns = [
-        [/!\[/, 'markdown image syntax "!["'],
-        [/<img\b/i, "an <img> tag"],
-        [/data:image\//i, "a data:image URI"],
-        [/\b[\w./%-]+\.(png|jpe?g|gif|webp|avif|bmp|ico|tiff?|svg)\b/i, "an image file reference"],
-    ];
-    for (const [re, what] of patterns) {
-        const m = raw.match(re);
-        if (m) fail(report, "dmv-06", `file contains ${what} ("${m[0].slice(0, 60)}") — the shipped skill carries no pixels (law 7)`);
-    }
-}
-
-// Splits "---\n…\n---\n<body>"; null when the file has no leading frontmatter fence.
-function extractFrontmatter(raw) {
-    const lines = raw.split(/\r?\n/);
-    if (lines[0] !== "---") return null;
-    for (let i = 1; i < lines.length; i++) {
-        if (lines[i] === "---") {
-            return { yaml: lines.slice(1, i).join("\n"), body: lines.slice(i + 1).join("\n") };
-        }
-    }
-    return null;
-}
-
-// dmv-01 + dmv-10 — frontmatter schema, per-tier key set, id/filename match.
-function checkFrontmatter(front, filePath, report) {
-    if (!isObj(front)) { fail(report, "dmv-01", "frontmatter is not a mapping"); return; }
-    if (front.schema !== "design-md/v2") fail(report, "dmv-01", `schema must be "design-md/v2", got "${front.schema}"`);
-    const tier = front.tier;
-    if (!TIERS.includes(tier)) fail(report, "dmv-01", `tier must be one of ${TIERS.join("|")}, got "${tier}"`);
-    const expectedId = basename(filePath).replace(/\.md$/i, "");
-    if (typeof front.id !== "string" || !front.id.trim()) fail(report, "dmv-01", "id missing");
-    else if (front.id !== expectedId) fail(report, "dmv-01", `id "${front.id}" does not match filename "${expectedId}"`);
-    for (const k of ["segments", "keywords"]) {
-        if (!Array.isArray(front[k]) || front[k].length === 0) fail(report, "dmv-01", `${k} must be a non-empty list`);
-    }
-    if (typeof front.sourced !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(front.sourced)) {
-        fail(report, "dmv-01", `sourced must be a YYYY-MM-DD date, got "${front.sourced}"`);
-    }
-    if (typeof front.sources !== "string" || !front.sources.trim()) fail(report, "dmv-01", "sources missing");
-    if (front.license !== "open" && front.license !== "licensed") {
-        fail(report, "dmv-01", `license must be open|licensed, got "${front.license}"`);
-    }
-    const allowed = new Set(tier === "project" ? [...FRONT_KEYS_BASE, ...FRONT_KEYS_PROJECT] : FRONT_KEYS_BASE);
-    for (const k of Object.keys(front)) {
-        if (allowed.has(k)) continue;
-        fail(report, "dmv-01", FRONT_KEYS_PROJECT.includes(k)
-            ? `key "${k}" is allowed on tier: project only`
-            : `unknown frontmatter key "${k}"`);
-    }
-    if (tier === "project") {
-        if (front.primitives !== "nurix" && front.primitives !== "native") {
-            fail(report, "dmv-10", `primitives must be exactly "nurix" or "native", got "${front.primitives ?? "(missing)"}"`);
-        }
-        if (typeof front["source-package"] !== "string" || !front["source-package"].trim()) {
-            fail(report, "dmv-10", 'source-package missing (provenance; "authored" for escape-hatch one-offs)');
-        }
-    }
-}
-
-const normHeading = (s) => s.replace(/[‘’]/g, "'").replace(/\s+/g, " ").trim().toLowerCase();
-
-// dmv-02 — 12 sections in order, non-empty, plus exactly one trailing design-values block.
-// Returns { valueBlock } — the block's raw YAML text, or null.
-function checkSections(body, report) {
-    const lines = body.split(/\r?\n/);
-    const headings = [];
-    const dvBlocks = [];
-    let inFence = false;
-    let fenceIsDV = false;
-    let dvStart = -1;
-    let dvContent = [];
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const fence = line.match(/^```(.*)$/);
-        if (fence) {
-            if (!inFence) {
-                inFence = true;
-                fenceIsDV = /^\s*yaml\s+design-values\s*$/.test(fence[1]);
-                if (fenceIsDV) { dvStart = i; dvContent = []; }
-            } else {
-                if (fenceIsDV) dvBlocks.push({ start: dvStart, end: i, text: dvContent.join("\n") });
-                inFence = false;
-                fenceIsDV = false;
-            }
-            continue;
-        }
-        if (inFence) {
-            if (fenceIsDV) dvContent.push(line);
-            continue;
-        }
-        const h = line.match(/^##\s+(.*)$/);
-        if (h) headings.push({ title: h[1].trim(), idx: i });
-    }
-    if (inFence) fail(report, "dmv-02", "unclosed code fence");
-
-    const expected = SECTIONS.map(normHeading);
-    const found = headings.map((h) => normHeading(h.title));
-    for (let i = 0; i < expected.length; i++) {
-        if (i >= found.length) { fail(report, "dmv-02", `section "${SECTIONS[i]}" missing`); continue; }
-        if (found[i] !== expected[i]) {
-            fail(report, "dmv-02", `expected section "${SECTIONS[i]}" at position ${i + 1}, found "${headings[i].title}"`);
-        }
-    }
-    for (let i = expected.length; i < found.length; i++) {
-        fail(report, "dmv-02", `unexpected extra section "${headings[i].title}"`);
-    }
-
-    const dv = dvBlocks.length ? dvBlocks[dvBlocks.length - 1] : null;
-    for (let i = 0; i < headings.length && i < SECTIONS.length; i++) {
-        const start = headings[i].idx + 1;
-        let end = i + 1 < headings.length ? headings[i + 1].idx : lines.length;
-        if (dv && dv.start >= start && dv.start < end) end = dv.start;
-        if (!lines.slice(start, end).some((l) => /\S/.test(l))) {
-            fail(report, "dmv-02", `section "${headings[i].title}" is empty`);
-        }
-    }
-
-    if (dvBlocks.length === 0) {
-        fail(report, "dmv-02", "trailing `yaml design-values` block missing");
-        return { valueBlock: null };
-    }
-    if (dvBlocks.length > 1) fail(report, "dmv-02", `exactly one design-values block allowed, found ${dvBlocks.length}`);
-    if (lines.slice(dv.end + 1).some((l) => /\S/.test(l))) {
-        fail(report, "dmv-02", "design-values block must be the last content in the file");
-    }
-    if (headings.length >= SECTIONS.length && dv.start < headings[SECTIONS.length - 1].idx) {
-        fail(report, "dmv-02", "design-values block must come after section 12");
-    }
-    return { valueBlock: dv.text };
-}
-
-// dmv-04 — 100% coverage of the value block, mechanically.
-function checkCoverage(values, report) {
-    const missing = (path) => fail(report, "dmv-04", `${path} missing`);
-
-    const color = values.color;
-    if (!isObj(color)) missing("color");
-    else {
-        for (const theme of THEMES) {
-            const roles = color[theme];
-            if (!isObj(roles)) { missing(`color.${theme}`); continue; }
-            const absent = COLOR_ROLES.filter((r) => roles[r] == null);
-            if (absent.length) fail(report, "dmv-04", `color.${theme} missing ${absent.length}/36 roles: ${absent.join(", ")}`);
-            const bad = COLOR_ROLES.filter((r) => roles[r] != null && !parseColor(roles[r]));
-            if (bad.length) fail(report, "dmv-04", `color.${theme} unparseable color values: ${bad.join(", ")}`);
-        }
-    }
-
-    const typo = values.typography;
-    if (!isObj(typo)) missing("typography");
-    else {
-        for (const slot of FONT_SLOTS) if (!isObj(typo[slot])) missing(`typography.${slot}`);
-        if (!isObj(typo.ramp)) missing("typography.ramp");
-        else {
-            for (const step of RAMP_STEPS) {
-                const r = typo.ramp[step];
-                if (!isObj(r)) { missing(`typography.ramp.${step}`); continue; }
-                for (const k of ["size", "line", "weight"]) if (r[k] == null) missing(`typography.ramp.${step}.${k}`);
-                if (r.family == null) missing(`typography.ramp.${step}.family`);
-                else if (!FONT_SLOTS.includes(r.family)) {
-                    fail(report, "dmv-04", `typography.ramp.${step}.family must be one of ${FONT_SLOTS.join("|")}, got "${r.family}"`);
-                }
-            }
-        }
-        const scope = typo["register-scope"];
-        if (!isObj(scope) || Object.keys(scope).length === 0) missing("typography.register-scope");
-    }
-
-    const elev = values.elevation;
-    if (!isObj(elev)) missing("elevation");
-    else {
-        if (!isObj(elev.radius) || Object.keys(elev.radius).length === 0) missing("elevation.radius");
-        if (elev.hairline == null) missing("elevation.hairline");
-        if (!isObj(elev.shadow) || Object.keys(elev.shadow).length === 0) missing("elevation.shadow");
-        if (!isObj(elev["dark-ladder"]) || Object.keys(elev["dark-ladder"]).length === 0) missing("elevation.dark-ladder");
-    }
-
-    const motion = values.motion;
-    if (!isObj(motion)) missing("motion");
-    else {
-        if (!isObj(motion.duration) || Object.keys(motion.duration).length === 0) missing("motion.duration");
-        if (!isObj(motion.easing) || Object.keys(motion.easing).length === 0) missing("motion.easing");
-        if (motion["entrance-never"] == null) missing("motion.entrance-never");
-        if (!Array.isArray(motion["identity-moments"]) || motion["identity-moments"].length === 0) missing("motion.identity-moments");
-    }
-
-    const icon = values.iconography;
-    if (!isObj(icon)) missing("iconography");
-    else for (const k of ["set", "stroke", "grid"]) if (icon[k] == null) missing(`iconography.${k}`);
-
-    const charts = values.charts;
-    if (!isObj(charts)) missing("charts");
-    else {
-        if (!Array.isArray(charts.categorical) || charts.categorical.length === 0) missing("charts.categorical");
-        if (!isObj(charts.sequential)) missing("charts.sequential");
-        if (!isObj(charts.diverging)) missing("charts.diverging");
-    }
-
-    const layout = values.layout;
-    if (!isObj(layout) || Object.keys(layout).length === 0) missing("layout");
-    else if (layout.base == null) missing("layout.base");
-}
-
-// dmv-05 — contrast on every declared pairing, both themes (pair table in the header comment).
-function checkContrast(values, report) {
-    const color = isObj(values.color) ? values.color : {};
-    for (const theme of THEMES) {
-        const roles = isObj(color[theme]) ? color[theme] : null;
-        if (!roles) continue;
-        const get = (r) => (roles[r] != null ? parseColor(roles[r]) : null);
-        for (const [fg, bg] of BODY_PAIRS) {
-            const a = get(fg);
-            const b = get(bg);
-            if (!a || !b) continue; // dmv-04 already reported the gap
-            const ratio = contrastRatio(a, b);
-            if (ratio < 4.5) fail(report, "dmv-05", `${theme}: ${fg} on ${bg} = ${ratio.toFixed(2)}:1 (body text needs ≥ 4.5:1)`);
-        }
-        for (const [fg, bg] of UI_PAIRS) {
-            const a = get(fg);
-            const b = get(bg);
-            if (!a || !b) continue;
-            const ratio = contrastRatio(a, b);
-            if (ratio < 3) fail(report, "dmv-05", `${theme}: ${fg} on ${bg} = ${ratio.toFixed(2)}:1 (UI fill needs ≥ 3:1)`);
-            else if (ratio < 4.5) warn(report, "dmv-05", `${theme}: ${fg} on ${bg} = ${ratio.toFixed(2)}:1 — passes the 3:1 UI floor but sits below 4.5:1 body-text comfort`);
-        }
-    }
-}
-
-// dmv-08 — registered family names + fallback stacks.
-function checkFonts(values, report) {
-    const typo = isObj(values.typography) ? values.typography : {};
-    for (const slot of FONT_SLOTS) {
-        const f = typo[slot];
-        if (!isObj(f)) continue; // dmv-04 already reported the gap
-        if (typeof f.family !== "string" || !f.family.trim()) { fail(report, "dmv-08", `typography.${slot}: family missing`); continue; }
-        const registered = BARE_FONT_NAMES[f.family.trim().toLowerCase()];
-        if (registered) fail(report, "dmv-08", `typography.${slot}: "${f.family}" is the bare name — the registered family is "${registered}"`);
-        if (typeof f.fallback !== "string" || !f.fallback.trim()) { fail(report, "dmv-08", `typography.${slot}: fallback stack missing`); continue; }
-        const parts = f.fallback.split(",").map((p) => p.trim()).filter(Boolean);
-        const last = parts[parts.length - 1];
-        if (!last || !GENERIC_FAMILIES.has(last.toLowerCase())) {
-            fail(report, "dmv-08", `typography.${slot}: fallback stack must end in a generic family (serif, sans-serif, monospace, …), ends with "${last}"`);
-        }
-    }
-}
-
-// dmw-01..07 — the taste-smell warns.
-function runWarnChecks(values, report) {
-    const color = isObj(values.color) ? values.color : {};
-    const raw = {};
-    const parsed = {};
-    for (const t of THEMES) {
-        raw[t] = isObj(color[t]) ? color[t] : {};
-        parsed[t] = {};
-        for (const [k, v] of Object.entries(raw[t])) {
-            const c = parseColor(v);
-            if (c) parsed[t][k] = c;
-        }
-    }
-
-    // dmw-01 — the anti-cream band.
-    for (const t of THEMES) {
-        const bg = parsed[t].background;
-        if (bg && bg.L >= 0.84 && bg.L <= 0.97 && bg.C < 0.06 && bg.H >= 40 && bg.H <= 100) {
-            warn(report, "dmw-01", `${t} background ${raw[t].background} sits in the anti-cream band (L 0.84–0.97, C < 0.06, hue 40–100) — the AI-default tell`);
-        }
-    }
-
-    // dmw-02 — neutral chroma bounds (0.005–0.015 toward the brand hue).
-    for (const t of THEMES) {
-        const pure = [];
-        const over = [];
-        for (const role of NEUTRAL_SURFACE_ROLES) {
-            const c = parsed[t][role];
-            if (!c) continue;
-            if (c.L >= 0.99 || c.L <= 0.03) continue; // gamut poles: chroma unrepresentable at true white/black
-            if (c.C < 0.005) pure.push(`${role} (C ${fmtNum(c.C)})`);
-            else if (c.C > 0.015) over.push(`${role} (C ${fmtNum(c.C)})`);
-        }
-        if (pure.length) warn(report, "dmw-02", `${t} neutrals pure gray (C < 0.005; tint 0.005–0.015 toward the brand hue): ${pure.join(", ")}`);
-        if (over.length) warn(report, "dmw-02", `${t} neutrals over-tinted (C > 0.015): ${over.join(", ")}`);
-    }
-
-    // dmw-03 — pure-black shadows above 0.15 alpha.
-    const elev = isObj(values.elevation) ? values.elevation : {};
-    if (isObj(elev.shadow)) {
-        for (const [name, val] of Object.entries(elev.shadow)) {
-            if (typeof val !== "string") continue;
-            const colors = val.match(/oklch\([^)]*\)|rgba?\([^)]*\)|#[0-9a-f]{3,8}\b|\bblack\b/gi) || [];
-            for (const cstr of colors) {
-                let L, C, alpha;
-                if (/^black$/i.test(cstr)) { L = 0; C = 0; alpha = 1; }
-                else if (/^rgba?/i.test(cstr)) {
-                    const nums = (cstr.match(/[\d.]+%?/g) || []).map((n) => (n.endsWith("%") ? parseFloat(n) / 100 : parseFloat(n)));
-                    if (nums.length < 3) continue;
-                    const srgb = nums.slice(0, 3).map((n) => (n > 1 ? n / 255 : n));
-                    ({ L, C } = srgbToOklch(srgb));
-                    alpha = nums.length > 3 ? nums[3] : 1;
-                } else {
-                    const c = parseColor(cstr);
-                    if (!c) continue;
-                    ({ L, C, alpha } = c);
-                }
-                if (C < 0.01 && L < 0.1 && alpha > 0.15) {
-                    warn(report, "dmw-03", `shadow.${name} uses untinted black at alpha ${fmtNum(alpha)} (> 0.15) — tint the shadow toward the brand hue`);
-                }
-            }
-        }
-    }
-
-    // dmw-04 — ease-in entrances; durations over their element-class budgets.
-    const motion = isObj(values.motion) ? values.motion : {};
-    if (isObj(motion.duration)) {
-        for (const [name, val] of Object.entries(motion.duration)) {
-            if (typeof val !== "string" && typeof val !== "number") continue;
-            const m = String(val).match(/^(\d+(?:\.\d+)?)\s*(ms|s)?$/);
-            if (!m) continue;
-            const ms = parseFloat(m[1]) * (m[2] === "s" ? 1000 : 1);
-            let budget = DURATION_BUDGET_DEFAULT;
-            for (const [re, b] of DURATION_BUDGETS) if (re.test(name)) { budget = b; break; }
-            if (ms > budget) warn(report, "dmw-04", `duration.${name} = ${fmtNum(ms)}ms exceeds its element-class budget of ${budget}ms (A6)`);
-        }
-    }
-    if (isObj(motion.easing)) {
-        for (const [name, val] of Object.entries(motion.easing)) {
-            if (/exit|out|leave|dismiss|close/i.test(name)) continue; // exits may accelerate
-            if (typeof val !== "string") continue;
-            if (val.trim() === "ease-in") {
-                warn(report, "dmw-04", `easing.${name} is \`ease-in\` — entrances never ease-in`);
-                continue;
-            }
-            const bez = val.match(/cubic-bezier\(\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*\)/);
-            if (bez) {
-                const [x1, y1, x2, y2] = bez.slice(1, 5).map(Number);
-                if (y1 <= 0.05 && x1 >= 0.3 && x2 >= 0.9 && y2 >= 0.9) {
-                    warn(report, "dmw-04", `easing.${name} = ${val} is ease-in-shaped (accelerating) — entrances never ease-in`);
-                }
-            }
-        }
-    }
-
-    // dmw-05 — display face granted a data register.
-    const typo = isObj(values.typography) ? values.typography : {};
-    const scope = isObj(typo["register-scope"]) ? typo["register-scope"] : {};
-    if (Array.isArray(scope.display)) {
-        for (const grant of scope.display) {
-            const words = String(grant).toLowerCase().split(/[^a-z]+/).filter(Boolean);
-            if (words.some((w) => DATA_REGISTER_WORDS.has(w))) {
-                warn(report, "dmw-05", `register-scope grants the display face "${grant}" — a data register (display never touches cells, buttons, labels, or form chrome)`);
-            }
-        }
-    }
-
-    // dmw-06 — the dark lightness ladder.
-    const d = parsed.dark;
-    if (d.background && d["surface-raised"] && d["surface-overlay"]) {
-        const steps = [
-            ["surface-raised", "background", d.background, d["surface-raised"]],
-            ["surface-overlay", "surface-raised", d["surface-raised"], d["surface-overlay"]],
-        ];
-        for (const [name, belowName, below, above] of steps) {
-            const delta = above.L - below.L;
-            if (delta < 0.035) {
-                warn(report, "dmw-06", `dark ${name} is only ${fmtNum(delta)} L above ${belowName} — the dark ladder needs ≥ ~0.04 L per step`);
-            }
-        }
-        for (const name of ["surface-raised", "surface-overlay"]) {
-            const c = d[name];
-            if (c.C >= 0.01 && d.background.C >= 0.01) {
-                const drift = hueDistance(c.H, d.background.H);
-                if (drift > 15) warn(report, "dmw-06", `dark ${name} hue drifts ${fmtNum(drift)}° from background — hold the hue on the ladder`);
-            }
-        }
-    }
-
-    // dmw-07 — accent identity across themes.
-    const aL = parsed.light.accent;
-    const aD = parsed.dark.accent;
-    if (aL && aD) {
-        const delta = Math.abs(aL.C - aD.C);
-        if (delta > 0.06) warn(report, "dmw-07", `accent chroma delta between themes is ${fmtNum(delta)} (> 0.06) — identity likely not held across themes`);
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Emission — the derived token artifact (deterministic, byte-stable)
-// ---------------------------------------------------------------------------
-
-function req(values, path) {
-    let cur = values;
-    for (const k of path) {
-        if (cur == null || cur[k] == null) throw new Error(`cannot emit: ${path.join(".")} missing`);
-        cur = cur[k];
-    }
-    return cur;
-}
-
-const cssValue = (v) => String(v);
-
-export function emitTokens(front, values) {
-    const id = front && typeof front.id === "string" ? front.id : "unknown";
-    const out = [];
-    out.push(`/* design.tokens.css — compiled from ${id} (design-md/v2) by validate-design-md.mjs — derived artifact: edit the design.md, never this file */`);
-    out.push("");
-    out.push(':root, :root[data-theme="light"] {');
-    out.push("    /* color roles */");
-    for (const role of COLOR_ROLES) out.push(`    --${role}: ${cssValue(req(values, ["color", "light", role]))};`);
-    out.push("");
-    out.push("    /* typography */");
-    for (const slot of FONT_SLOTS) {
-        const f = req(values, ["typography", slot]);
-        if (f.family == null || f.fallback == null) throw new Error(`cannot emit: typography.${slot} family/fallback missing`);
-        out.push(`    --font-${slot}: "${f.family}", ${f.fallback};`);
-    }
-    for (const step of RAMP_STEPS) {
-        const r = req(values, ["typography", "ramp", step]);
-        out.push(`    --text-${step}-size: ${cssValue(req(r, ["size"]))};`);
-        out.push(`    --text-${step}-line: ${cssValue(req(r, ["line"]))};`);
-        out.push(`    --text-${step}-weight: ${cssValue(req(r, ["weight"]))};`);
-        if (r.family != null) out.push(`    --text-${step}-family: var(--font-${r.family});`);
-        if (r.tracking != null) out.push(`    --text-${step}-tracking: ${cssValue(r.tracking)};`);
-        if (Array.isArray(r.features) && r.features.length) {
-            out.push(`    --text-${step}-features: ${r.features.map((x) => `"${x}"`).join(", ")};`);
-        }
-    }
-    out.push("");
-    out.push("    /* elevation */");
-    for (const [k, v] of Object.entries(req(values, ["elevation", "radius"]))) out.push(`    --radius-${k}: ${cssValue(v)};`);
-    for (const [k, v] of Object.entries(req(values, ["elevation", "shadow"]))) out.push(`    --shadow-${k}: ${cssValue(v)};`);
-    out.push("");
-    out.push("    /* motion */");
-    for (const [k, v] of Object.entries(req(values, ["motion", "duration"]))) out.push(`    --duration-${k}: ${cssValue(v)};`);
-    for (const [k, v] of Object.entries(req(values, ["motion", "easing"]))) out.push(`    --ease-${k}: ${cssValue(v)};`);
-    out.push("");
-    out.push("    /* layout */");
-    for (const [k, v] of Object.entries(req(values, ["layout"]))) {
-        const names = LAYOUT_EMIT[k];
-        if (Array.isArray(v)) {
-            for (let i = 0; i < v.length; i++) {
-                out.push(`    ${(names && names[i]) || `--layout-${k}-${i + 1}`}: ${cssValue(v[i])};`);
-            }
-        } else {
-            out.push(`    ${(names && names[0]) || `--layout-${k}`}: ${cssValue(v)};`);
-        }
-    }
-    out.push("}");
-    out.push("");
-    out.push(':root[data-theme="dark"] {');
-    out.push("    /* color roles */");
-    for (const role of COLOR_ROLES) out.push(`    --${role}: ${cssValue(req(values, ["color", "dark", role]))};`);
-    out.push("}");
-    return out.join("\n") + "\n";
-}
-
-function firstDiff(a, b) {
-    const n = Math.min(a.length, b.length);
-    for (let i = 0; i < n; i++) if (a[i] !== b[i]) return i;
-    return n;
-}
-
-// ---------------------------------------------------------------------------
-// File / folder runners
-// ---------------------------------------------------------------------------
-
-export function validateFile(filePath, mode = "build", opts = {}) {
-    const report = { file: filePath, fails: [], warns: [] };
-    let raw;
-    try {
-        raw = readFileSync(filePath, "utf8");
-    } catch (e) {
-        fail(report, "dmv-01", `unreadable: ${e.message}`);
-        return report;
-    }
-
-    if (opts.checkOwnName !== false && basename(filePath).toLowerCase() === "claude.md") {
-        fail(report, "dmv-09", "file is named claude.md — an agent runtime auto-loads it as instructions (naming hygiene)");
-    }
-
-    checkNoImages(raw, report);
-
-    const fm = extractFrontmatter(raw);
-    let front = null;
-    if (!fm) {
-        fail(report, "dmv-01", "missing YAML frontmatter (--- … ---) at the top of the file");
-    } else {
-        try {
-            front = parseYaml(fm.yaml, "frontmatter");
-        } catch (e) {
-            fail(report, "dmv-01", e.message);
-        }
-        if (front) checkFrontmatter(front, filePath, report);
-    }
-
-    const body = fm ? fm.body : raw;
-    const { valueBlock } = checkSections(body, report);
-
-    let values = null;
-    if (valueBlock != null) {
-        try {
-            values = parseYaml(valueBlock, "design-values");
-            if (!isObj(values)) { fail(report, "dmv-03", "design-values block is not a mapping"); values = null; }
-        } catch (e) {
-            fail(report, "dmv-03", e.message);
-        }
-    }
-
-    if (values) {
-        checkCoverage(values, report);
-        checkContrast(values, report);
-        checkFonts(values, report);
-        runWarnChecks(values, report);
-        try {
-            report._artifact = emitTokens(front, values);
-        } catch {
-            report._artifact = null;
-        }
-    }
-
-    if (mode === "ship") {
-        const sibling = join(dirname(filePath), "design.tokens.css");
-        if (!report._artifact) {
-            fail(report, "dmv-11", "cannot recompile the token artifact (value block missing or incomplete)");
-        } else if (!existsSync(sibling)) {
-            fail(report, "dmv-11", `design.tokens.css not found beside ${basename(filePath)} — the derived artifact must ship with its source`);
-        } else {
-            const disk = readFileSync(sibling);
-            const fresh = Buffer.from(report._artifact, "utf8");
-            if (!disk.equals(fresh)) {
-                fail(report, "dmv-11", `drift: design.tokens.css does not byte-match the recompiled artifact (first divergence at byte ${firstDiff(disk, fresh)})`);
-            }
-        }
-    }
-
-    return report;
-}
-
-function walk(dir) {
-    const out = [];
-    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-    for (const e of entries) {
-        if (e.name.startsWith(".")) continue;
-        const p = join(dir, e.name);
-        if (e.isDirectory()) out.push(...walk(p));
-        else if (e.isFile()) out.push(p);
-    }
-    return out;
-}
-
-const toRel = (root, p) => relative(root, p).split(sep).join("/");
-
-// dmv-07 — index.csv integrity, both directions.
-function checkIndex(root, packageFiles, report) {
-    const indexPath = join(root, "index.csv");
-    if (!existsSync(indexPath)) {
-        fail(report, "dmv-07", "index.csv not found at the folder root");
-        return;
-    }
-    let rows;
-    try {
-        rows = parseCsv(readFileSync(indexPath, "utf8"));
-    } catch (e) {
-        fail(report, "dmv-07", `index.csv malformed: ${e.message}`);
-        return;
-    }
-    const HEADER = ["file", "tier", "segments", "keywords", "reads-as"];
-    if (!rows.length || rows[0].join(",") !== HEADER.join(",")) {
-        fail(report, "dmv-07", `index.csv header must be "${HEADER.join(",")}", got "${(rows[0] || []).join(",")}"`);
-        return;
-    }
-    const seen = new Map();
-    for (let n = 1; n < rows.length; n++) {
-        const row = rows[n];
-        if (row.length !== HEADER.length) {
-            fail(report, "dmv-07", `index.csv row ${n + 1}: expected ${HEADER.length} fields, got ${row.length}`);
-            continue;
-        }
-        const file = row[0];
-        if (seen.has(file)) fail(report, "dmv-07", `index.csv duplicate file "${file}" (rows ${seen.get(file) + 1} and ${n + 1})`);
-        else seen.set(file, n);
-        if (!existsSync(resolve(root, file))) fail(report, "dmv-07", `index.csv row ${n + 1}: file "${file}" does not exist`);
-    }
-    for (const rel of packageFiles) {
-        if (!seen.has(rel)) fail(report, "dmv-07", `package file "${rel}" has no index.csv row`);
-    }
-}
-
-function parseCsv(text) {
-    const rows = [];
-    let row = [];
-    let field = "";
-    let inQ = false;
-    let i = 0;
-    while (i < text.length) {
-        const c = text[i];
-        if (inQ) {
-            if (c === '"') {
-                if (text[i + 1] === '"') { field += '"'; i += 2; continue; }
-                inQ = false; i++; continue;
-            }
-            field += c; i++; continue;
-        }
-        if (c === '"') { inQ = true; i++; continue; }
-        if (c === ",") { row.push(field); field = ""; i++; continue; }
-        if (c === "\n" || c === "\r") {
-            if (c === "\r" && text[i + 1] === "\n") i++;
-            row.push(field); field = ""; rows.push(row); row = []; i++; continue;
-        }
-        field += c; i++;
-    }
-    if (inQ) throw new Error("unterminated quoted field");
-    if (field !== "" || row.length) { row.push(field); rows.push(row); }
-    return rows.filter((r) => !(r.length === 1 && r[0].trim() === ""));
-}
-
-export function validateFolder(root, mode = "build") {
-    const reports = [];
-    const allFiles = walk(root);
-    const mdFiles = allFiles.filter((f) => f.toLowerCase().endsWith(".md") && basename(f).toLowerCase() !== "schema.md");
-    for (const f of mdFiles) reports.push(validateFile(f, mode, { checkOwnName: false }));
-
-    const folderReport = { file: root, fails: [], warns: [] };
-    for (const f of allFiles) {
-        if (basename(f).toLowerCase() === "claude.md") {
-            fail(folderReport, "dmv-09", `"${toRel(root, f)}" is named claude.md — an agent runtime auto-loads it as instructions (naming hygiene)`);
-        }
-    }
-    checkIndex(root, mdFiles.map((f) => toRel(root, f)), folderReport);
-    reports.push(folderReport);
-    return reports;
-}
-
-// ---------------------------------------------------------------------------
-// CLI
-// ---------------------------------------------------------------------------
-
-function usage(stream) {
-    stream.write("usage: node validate-design-md.mjs <file|folder> [--mode admission|build|ship] [--json] [--emit]\n");
-}
-
-function printHuman(reports, stream) {
-    let fails = 0;
-    let warns = 0;
-    for (const r of reports) {
-        stream.write(`${r.file}\n`);
-        for (const f of r.fails) stream.write(`  FAIL ${f.id} — ${f.detail}\n`);
-        for (const w of r.warns) stream.write(`  WARN ${w.id} — ${w.detail}\n`);
-        if (!r.fails.length && !r.warns.length) stream.write("  ok\n");
-        fails += r.fails.length;
-        warns += r.warns.length;
-    }
-    stream.write(`\n${fails ? "FAIL" : "PASS"} — ${reports.length} target(s), ${fails} fail(s), ${warns} warn(s)\n`);
-}
-
-const toJsonReport = (r) => ({ file: r.file, fails: r.fails, warns: r.warns });
-
-function main() {
-    const args = process.argv.slice(2);
-    let target = null;
-    let mode = "build";
-    let json = false;
-    let emit = false;
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a === "--mode") {
-            mode = args[++i];
-        } else if (a === "--json") json = true;
-        else if (a === "--emit") emit = true;
-        else if (a === "--help" || a === "-h") { usage(process.stdout); process.exit(0); }
-        else if (!a.startsWith("--") && target === null) target = a;
-        else { process.stderr.write(`unknown argument: ${a}\n`); usage(process.stderr); process.exit(1); }
-    }
-    if (!target) { usage(process.stderr); process.exit(1); }
-    if (!["admission", "build", "ship"].includes(mode)) {
-        process.stderr.write(`--mode must be admission|build|ship, got "${mode}"\n`);
-        process.exit(1);
-    }
-    const abs = resolve(target);
-    if (!existsSync(abs)) { process.stderr.write(`no such file or folder: ${abs}\n`); process.exit(1); }
-    const isDir = statSync(abs).isDirectory();
-    if (emit && isDir) { process.stderr.write("--emit requires a single design.md file\n"); process.exit(1); }
-
-    const reports = isDir ? validateFolder(abs, mode) : [validateFile(abs, mode, { checkOwnName: true })];
-    const anyFail = reports.some((r) => r.fails.length > 0);
-
-    if (emit) {
-        if (anyFail || !reports[0]._artifact) {
-            printHuman(reports, process.stderr);
-            process.exit(1);
-        }
-        process.stdout.write(reports[0]._artifact);
-        if (reports[0].warns.length) printHuman(reports, process.stderr);
-        process.exit(0);
-    }
-
-    if (json) {
-        const payload = isDir ? reports.map(toJsonReport) : toJsonReport(reports[0]);
-        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-    } else {
-        printHuman(reports, process.stdout);
-    }
-    process.exit(anyFail ? 1 : 0);
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) main();