@nurix/etna 0.20.14 → 0.20.16

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

@@ -6,19 +6,37 @@
 // 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]
+//   node validate-design-md.mjs (<file|folder> | --project [dir]) [--mode admission|build|ship] [--json]
+//                               [--emit] [--emit-personality] [--write] [--lib <folder>]
 //
 //   <file>     validate one design.md.
+//   --project [dir]
+//              validate the project's own fork, located by the repo's shape and never by search: a
+//              multi-package workspace (pnpm-workspace.yaml, or package.json `workspaces`) keeps it at
+//              packages/common/design.md, a single-package repo at src/common/design.md. dir defaults
+//              to the cwd. Fails closed when the file is absent, naming the expected path and any copy
+//              found at the other conventional spot or at the repo base.
+//   --write    with --emit / --emit-personality: write the artifact beside the design.md
+//              (design.tokens.css / personality.css) instead of printing it.
 //   <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).
+//              re-emit and byte-compare against a design.tokens.css sitting beside the input file) and
+//              dmv-12's drift half (the same for personality.css when a personality block is declared).
 //              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.
+//   --emit-personality
+//              compile the personality artifact to stdout (redirect to personality.css): the design.md's
+//              `personality:` traits handed to @nurix/components' own compiler (`compileToCss` from
+//              `@nurix/components/lib/personality`, primitives: nurix only). Same gating as --emit.
+//   --lib <folder>
+//              where @nurix/components is installed, when the resolver cannot tell: it walks up from the
+//              design.md, then one and two levels into the workspace (packages/<app>); a pnpm root hoists
+//              nothing, and several installed versions is an ambiguity only the app package resolves.
 //
 // Exit codes: 0 pass (warns allowed), 1 any FAIL.
 //
@@ -27,7 +45,8 @@
 //           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
+//   dmv-04  coverage: all 36 color roles × both themes (values parseable), plus the optional `info` role
+//           declared in both themes or neither; 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,
@@ -42,6 +61,15 @@
 //   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-12  the personality block (primitives: nurix): a mapping over the six closed-vocabulary traits
+//           density|pace|edge|depth|texture|tone (pace a number 0..1); absent under native. In --mode
+//           ship, personality.css beside the design.md byte-matches the recompiled artifact, and no
+//           personality.css exists without a block (a hand-authored layer).
+//
+// WARN checks (never close): dmw-01 anti-cream backgrounds · dmw-02 neutral tint · dmw-03 untinted shadows ·
+//   dmw-04 motion budgets · dmw-05 personality block absent on a nurix project (the library's neutral
+//   traits ship) · dmw-06 `info` role undeclared on a nurix project (--tone-info falls back to the
+//   library's own hue).
 //
 // 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;
@@ -77,8 +105,8 @@
 //           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
+// Emitted artifact shape (deterministic, byte-stable): a `:root:not(.dark)` block and a
+// `:root.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/
@@ -86,9 +114,9 @@
 // (--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, realpathSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, statSync, readdirSync, realpathSync } from "node:fs";
 import { join, resolve, basename, dirname, relative, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import process from "node:process";
 
 // ---------------------------------------------------------------------------
@@ -114,6 +142,20 @@ const SECTIONS = [
 
 const RAMP_STEPS = ["display", "h1", "h2", "body", "small", "caption", "data"];
 const FONT_SLOTS = ["display", "sans", "mono"];
+// Optional color roles: emitted only when declared (both themes or neither). `info` completes the
+// success/warning/info trio @nurix/components' status dots read through --tone-*.
+const OPTIONAL_COLOR_ROLES = ["info"];
+// The personality block — six closed-vocabulary traits @nurix/components compiles into the token
+// families its components read (lib/personality). The library owns the vocabulary; this mirrors it.
+const PERSONALITY_ORDER = ["density", "pace", "edge", "depth", "texture", "tone"];
+const PERSONALITY_TRAITS = {
+    density: ["compact", "regular", "airy"],
+    pace: null, // the one scalar: 0 still · 0.5 the library's neutral timing · 1 lively
+    edge: ["sharp", "regular", "soft"],
+    depth: ["flat", "layered", "elevated"],
+    texture: ["clean", "grainy"],
+    tone: ["neutral", "expressive"],
+};
 const THEMES = ["light", "dark"];
 const TIERS = ["default", "variant", "brand", "project"];
 const FRONT_KEYS_BASE = ["schema", "id", "tier", "segments", "keywords", "sourced", "sources", "license"];
@@ -695,6 +737,48 @@ function checkCoverage(values, report) {
     else if (layout.base == null) missing("layout.base");
 }
 
+// dmv-12 — the personality block, and the two nurix-project warns (dmw-05 block absent, dmw-06 info absent).
+function checkPersonality(front, values, report) {
+    const isNurixProject = !!front && front.tier === "project" && front.primitives === "nurix";
+    const p = values.personality;
+    if (p === undefined) {
+        if (isNurixProject) {
+            warn(report, "dmw-05", "personality block absent — @nurix/components ships its neutral traits (regular · pace 0.5 · regular · layered · grainy · neutral); declare the traits §4–§7 imply so density, motion, radius and depth reach the components");
+        }
+    } else if (!isObj(p)) {
+        fail(report, "dmv-12", "personality must be a mapping of traits");
+    } else {
+        if (!(front && front.primitives === "nurix")) {
+            fail(report, "dmv-12", "personality is compiled by @nurix/components — under primitives: native nothing reads it; drop the block or switch primitives");
+        }
+        for (const [k, v] of Object.entries(p)) {
+            if (!(k in PERSONALITY_TRAITS)) {
+                fail(report, "dmv-12", `personality.${k} is not a trait (${PERSONALITY_ORDER.join("|")})`);
+            } else if (k === "pace") {
+                const n = typeof v === "number" ? v : Number(v);
+                if (typeof v === "boolean" || !Number.isFinite(n) || n < 0 || n > 1) {
+                    fail(report, "dmv-12", `personality.pace must be a number 0..1 (0 still · 0.5 neutral · 1 lively), got "${v}"`);
+                }
+            } else if (!PERSONALITY_TRAITS[k].includes(v)) {
+                fail(report, "dmv-12", `personality.${k} must be one of ${PERSONALITY_TRAITS[k].join("|")}, got "${v}"`);
+            }
+        }
+    }
+
+    const color = isObj(values.color) ? values.color : {};
+    for (const role of OPTIONAL_COLOR_ROLES) {
+        const declared = THEMES.map((t) => isObj(color[t]) && color[t][role] != null);
+        if (declared[0] !== declared[1]) {
+            fail(report, "dmv-04", `color.${role} is declared in one theme only — a role is declared in both themes or neither`);
+        } else if (declared[0]) {
+            const bad = THEMES.filter((t) => !parseColor(color[t][role]));
+            if (bad.length) fail(report, "dmv-04", `color.${role} unparseable in ${bad.join(", ")}`);
+        } else if (isNurixProject) {
+            warn(report, "dmw-06", `color.${role} undeclared — @nurix/components' --tone-${role} falls back to the library's own hue beside your success/warning; declare it in both themes`);
+        }
+    }
+}
+
 // 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 : {};
@@ -891,14 +975,35 @@ function req(values, path) {
 
 const cssValue = (v) => String(v);
 
+// The project fork's one path, decided by the repo's shape and never by search: a multi-package
+// workspace (pnpm-workspace.yaml, or package.json `workspaces`) keeps it at packages/common/design.md;
+// a single-package repo at src/common/design.md. `path` is null when absent; `misplaced` lists copies
+// at the other conventional spot or the repo base, so the caller can name what to move.
+export function resolveProjectDesignMd(root) {
+    const abs = resolve(root);
+    let hasWorkspaces = existsSync(join(abs, "pnpm-workspace.yaml"));
+    if (!hasWorkspaces && existsSync(join(abs, "package.json"))) {
+        try { hasWorkspaces = JSON.parse(readFileSync(join(abs, "package.json"), "utf8")).workspaces != null; } catch { /* an unreadable manifest reads as single-package */ }
+    }
+    const shape = hasWorkspaces ? "multi-package" : "single-package";
+    const expected = join(abs, hasWorkspaces ? "packages/common/design.md" : "src/common/design.md");
+    const other = join(abs, hasWorkspaces ? "src/common/design.md" : "packages/common/design.md");
+    const misplaced = [join(abs, "design.md"), other].filter((f) => existsSync(f));
+    return { path: existsSync(expected) ? expected : null, expected, shape, misplaced };
+}
+
 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(':root:not(.dark) {');
     out.push("    /* color roles */");
     for (const role of COLOR_ROLES) out.push(`    --${role}: ${cssValue(req(values, ["color", "light", role]))};`);
+    for (const role of OPTIONAL_COLOR_ROLES) {
+        const v = values.color.light[role];
+        if (v != null) out.push(`    --${role}: ${cssValue(v)};`);
+    }
     out.push("");
     out.push("    /* typography */");
     for (const slot of FONT_SLOTS) {
@@ -939,13 +1044,135 @@ export function emitTokens(front, values) {
     }
     out.push("}");
     out.push("");
-    out.push(':root[data-theme="dark"] {');
+    out.push(':root.dark {');
     out.push("    /* color roles */");
     for (const role of COLOR_ROLES) out.push(`    --${role}: ${cssValue(req(values, ["color", "dark", role]))};`);
+    for (const role of OPTIONAL_COLOR_ROLES) {
+        const v = values.color.dark[role];
+        if (v != null) out.push(`    --${role}: ${cssValue(v)};`);
+    }
     out.push("}");
     return out.join("\n") + "\n";
 }
 
+// The personality spec exactly as the library's compiler takes it: version 1 plus the declared traits,
+// in trait order, pace numeric. Null when the design.md declares no block.
+export function personalitySpec(values) {
+    const p = values && isObj(values.personality) ? values.personality : null;
+    if (!p) return null;
+    const spec = { version: 1 };
+    for (const k of PERSONALITY_ORDER) {
+        if (p[k] === undefined) continue;
+        spec[k] = k === "pace" ? Number(p[k]) : p[k];
+    }
+    return spec;
+}
+
+// Every @nurix/components install a design.md can see: the upward walk from `fromDir` (a plain install,
+// or an app package inside a workspace), then one and two levels down into the workspace (packages/<app>)
+// — a pnpm root hoists nothing, so a repo-base design.md sees the library only through its packages.
+// Deduped by real path; distinct versions surface as an ambiguity for --lib.
+function findLibraryInstalls(fromDir) {
+    const found = new Map();
+    const consider = (dir) => {
+        const pkgPath = join(dir, "package.json");
+        if (!existsSync(pkgPath)) return;
+        let real;
+        try { real = realpathSync(dir); } catch { return; }
+        if (found.has(real)) return;
+        found.set(real, { dir: real, pkg: JSON.parse(readFileSync(pkgPath, "utf8")) });
+    };
+    const roots = []; // every package/workspace root passed on the way up, nearest first
+    let dir = fromDir;
+    for (;;) {
+        consider(join(dir, "node_modules", "@nurix", "components"));
+        if (found.size) return [...found.values()];
+        if (existsSync(join(dir, "package.json")) || existsSync(join(dir, "pnpm-workspace.yaml"))) roots.push(dir);
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    const children = (base) => {
+        try { return readdirSync(base).filter((n) => !n.startsWith(".") && n !== "node_modules" && statSync(join(base, n)).isDirectory()); }
+        catch { return []; }
+    };
+    for (const root of roots) {
+        for (const a of children(root)) {
+            consider(join(root, a, "node_modules", "@nurix", "components"));
+            for (const b of children(join(root, a))) consider(join(root, a, b, "node_modules", "@nurix", "components"));
+        }
+        if (found.size) break;
+    }
+    return [...found.values()];
+}
+
+// Resolve @nurix/components' personality compiler from the project that owns the design.md — the
+// library owns the spec and the compiler; this script only carries the traits to it. Follows the
+// package's ./lib/personality export; returns the module and the library version it came from.
+async function loadPersonalityCompiler(fromDir, libDir) {
+    const installs = findLibraryInstalls(libDir || fromDir);
+    if (!installs.length) {
+        throw new Error(`@nurix/components is not installed above or below ${libDir || fromDir} — the personality artifact needs the library's compiler (primitives: nurix); pass --lib <app package folder> if it lives elsewhere`);
+    }
+    const versions = [...new Set(installs.map((i) => i.pkg.version))];
+    if (versions.length > 1) {
+        throw new Error(`several @nurix/components versions are installed under ${libDir || fromDir} (${versions.join(", ")}) — pass --lib <app package folder> to name the one the app builds with`);
+    }
+    const { dir, pkg } = installs[0];
+    const entry = pkg.exports && pkg.exports["./lib/personality"];
+    const rel = typeof entry === "string" ? entry : entry && (entry.import || entry.default);
+    if (!rel) throw new Error(`@nurix/components at ${dir} exports no ./lib/personality`);
+    const mod = await import(pathToFileURL(join(dir, rel)).href);
+    if (typeof mod.compileToCss !== "function") throw new Error("@nurix/components/lib/personality exports no compileToCss");
+    return { mod, version: pkg.version };
+}
+
+// The personality artifact: the library's compileToCss over the design.md's traits, behind one header
+// line naming the source. Null when no block is declared; throws when the library rejects the spec or
+// cannot be resolved.
+export async function compilePersonalityArtifact(filePath, front, values, opts = {}) {
+    const spec = personalitySpec(values);
+    if (!spec) return null;
+    const { mod: lib, version } = await loadPersonalityCompiler(dirname(filePath), opts.lib);
+    if (typeof lib.validatePersonality === "function") {
+        const verdict = lib.validatePersonality(spec);
+        if (verdict && verdict.ok === false) {
+            const issues = (verdict.issues || []).map((i) => `${i.path} ${i.message}`).join("; ");
+            throw new Error(`personality rejected by @nurix/components: ${issues}`);
+        }
+    }
+    const id = front && typeof front.id === "string" ? front.id : "unknown";
+    return `/* personality.css — compiled from ${id} (design-md/v2) by @nurix/components@${version} compileToCss via validate-design-md.mjs --emit-personality — derived artifact: edit the design.md, never this file */\n` + lib.compileToCss(spec);
+}
+
+// dmv-12's drift half (--mode ship, single file): personality.css beside the design.md byte-matches the
+// recompiled artifact; an artifact with no block is a hand-authored layer and fails too.
+async function checkPersonalityDrift(filePath, report, opts = {}) {
+    const sibling = join(dirname(filePath), "personality.css");
+    const values = report._values;
+    const declared = !!(values && isObj(values.personality));
+    if (!declared) {
+        if (existsSync(sibling)) fail(report, "dmv-12", "personality.css sits beside the design.md but no personality block is declared — the artifact is derived from the design.md, never authored");
+        return;
+    }
+    let fresh;
+    try {
+        fresh = await compilePersonalityArtifact(filePath, report._front, values, opts);
+    } catch (e) {
+        fail(report, "dmv-12", `cannot recompile personality.css: ${e.message}`);
+        return;
+    }
+    if (!existsSync(sibling)) {
+        fail(report, "dmv-12", `personality.css not found beside ${basename(filePath)} — emit it with --emit-personality and commit it`);
+        return;
+    }
+    const disk = readFileSync(sibling);
+    const want = Buffer.from(fresh, "utf8");
+    if (!disk.equals(want)) {
+        fail(report, "dmv-12", `drift: personality.css does not byte-match the recompiled artifact (first divergence at byte ${firstDiff(disk, want)})`);
+    }
+}
+
 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;
@@ -984,6 +1211,7 @@ export function validateFile(filePath, mode = "build", opts = {}) {
         }
         if (front) checkFrontmatter(front, filePath, report);
     }
+    report._front = front;
 
     const body = fm ? fm.body : raw;
     const { valueBlock } = checkSections(body, report);
@@ -998,8 +1226,10 @@ export function validateFile(filePath, mode = "build", opts = {}) {
         }
     }
 
+    report._values = values;
     if (values) {
         checkCoverage(values, report);
+        checkPersonality(front, values, report);
         checkContrast(values, report);
         checkFonts(values, report);
         runWarnChecks(values, report);
@@ -1128,7 +1358,7 @@ export function validateFolder(root, mode = "build") {
 // ---------------------------------------------------------------------------
 
 function usage(stream) {
-    stream.write("usage: node validate-design-md.mjs <file|folder> [--mode admission|build|ship] [--json] [--emit]\n");
+    stream.write("usage: node validate-design-md.mjs (<file|folder> | --project [dir]) [--mode admission|build|ship] [--json] [--emit] [--emit-personality] [--write] [--lib <folder>]\n");
 }
 
 function printHuman(reports, stream) {
@@ -1147,22 +1377,41 @@ function printHuman(reports, stream) {
 
 const toJsonReport = (r) => ({ file: r.file, fails: r.fails, warns: r.warns });
 
-function main() {
+async function main() {
     const args = process.argv.slice(2);
     let target = null;
     let mode = "build";
     let json = false;
     let emit = false;
+    let emitPersonality = false;
+    let write = false;
+    let lib = null;
+    let project = null;
     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 === "--emit-personality") emitPersonality = true;
+        else if (a === "--write") write = true;
+        else if (a === "--lib") lib = resolve(args[++i] || "");
+        else if (a === "--project") project = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : ".";
         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 (project !== null && target !== null) { process.stderr.write("--project resolves the design.md itself — drop the positional path\n"); process.exit(1); }
+    if (project !== null) {
+        const found = resolveProjectDesignMd(project);
+        if (!found.path) {
+            process.stderr.write(`no project design.md at ${found.expected} (${found.shape} repo: ${found.shape === "multi-package" ? "packages/common/" : "src/common/"} holds the design files)\n`);
+            for (const stray of found.misplaced) process.stderr.write(`  found ${stray} — move it to ${found.expected}\n`);
+            process.exit(1);
+        }
+        target = found.path;
+    }
+    if (write && !emit && !emitPersonality) { process.stderr.write("--write needs --emit or --emit-personality\n"); 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`);
@@ -1171,17 +1420,45 @@ function main() {
     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); }
+    if ((emit || emitPersonality) && isDir) { process.stderr.write("--emit / --emit-personality require a single design.md file\n"); process.exit(1); }
 
     const reports = isDir ? validateFolder(abs, mode) : [validateFile(abs, mode, { checkOwnName: true })];
+    if (mode === "ship" && !isDir) await checkPersonalityDrift(abs, reports[0], { lib });
     const anyFail = reports.some((r) => r.fails.length > 0);
 
+    if (emitPersonality) {
+        if (anyFail) { printHuman(reports, process.stderr); process.exit(1); }
+        let css = null;
+        try {
+            css = await compilePersonalityArtifact(abs, reports[0]._front, reports[0]._values, { lib });
+        } catch (e) {
+            process.stderr.write(`${e.message}\n`);
+            process.exit(1);
+        }
+        if (css == null) { process.stderr.write("no personality block in the design-values block — nothing to emit\n"); process.exit(1); }
+        if (write) {
+            const out = join(dirname(abs), "personality.css");
+            writeFileSync(out, css);
+            process.stdout.write(`wrote ${out}\n`);
+        } else {
+            process.stdout.write(css);
+        }
+        if (reports[0].warns.length) printHuman(reports, process.stderr);
+        process.exit(0);
+    }
+
     if (emit) {
         if (anyFail || !reports[0]._artifact) {
             printHuman(reports, process.stderr);
             process.exit(1);
         }
-        process.stdout.write(reports[0]._artifact);
+        if (write) {
+            const out = join(dirname(abs), "design.tokens.css");
+            writeFileSync(out, reports[0]._artifact);
+            process.stdout.write(`wrote ${out}\n`);
+        } else {
+            process.stdout.write(reports[0]._artifact);
+        }
         if (reports[0].warns.length) printHuman(reports, process.stderr);
         process.exit(0);
     }
@@ -1197,4 +1474,6 @@ function main() {
 
 // realpath both sides: argv[1] keeps the invoking symlink (e.g. a ~/.claude/skills link),
 // while import.meta.url is the resolved file — a plain path compare silently skips main().
-if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) main();
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+    main().catch((e) => { process.stderr.write(`${e.message}\n`); process.exit(1); });
+}

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -11,6 +11,26 @@ Document contracts and architecture, not implementation details. Show function s
 
 ---
 
+## Where a file's documentation lives
+
+**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the shape is the harness's `CLAUDE.md` § File Structure, which is canonical and is not restated here. What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
+
+**Cutting a comment is a move, not a deletion.** A claim taken out of a source file is owed one of two things before the cut is done, and the choice is per claim, not per file:
+
+| The claim is | What it earns |
+| --- | --- |
+| Worth keeping, and its doc does not state it | A section in the **owning feature doc** (the ownership index resolves which), carrying the claim and the argument for why the codebase is worse without it — never the comment's wording, which was written for a reader holding the code |
+| Already stated in its doc | Nothing — but you **open that doc and find the sentence** before saying so. An assumed duplicate is how a claim is lost |
+| History, a ticket or decision-record reference, a dated note, a divider, or narration of code that no longer exists | Nothing, and no record. A record lives in `docs/history/`; these are not claims about the present |
+
+**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so a drop nobody accounted for is visible as a number rather than as a feeling. [`scripts/comment-strip.mjs`](scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
+
+**The mechanical half of the shape is checked, not remembered.** [`scripts/source-lint.mjs`](scripts/source-lint.mjs) `--changed` reports a header that names another path or none, a change whose added lines are over a quarter comments, and the four shapes the convention deletes outright — narration, ALL-CAPS emphasis, an over-long header, a comment block that has become a document. Block-severity findings must be fixed; the escape hatch is a `source-lint-disable: <id>` comment with the reason in a second comment beside it, and the only finding that legitimately takes one is a booby trap. The harness detector raises a bookkeeping row for the same condition, so an unfixed breach outlives the session that wrote it.
+
+**Never convert a booby trap into a one-liner.** A comment whose subject is a danger on an edge that looks safe — a pinned dependency's limitation, a measurement that justifies a narrow allowlist, a two-clock interaction — is load-bearing where it sits, because the reader who needs it is mid-edit and will not go looking. Compress it if it rambles; do not relocate it. The tell is that the comment names a version, a measurement, or a condition under which it expires.
+
+---
+
 ## Present tense, always
 
 **A document states what is — never how it got there, and never how far along it is.** Write as if the current design had always been the plan. This is the most-violated rule in the skill, so it sits at the top; it applies to every document written or edited through this skill, whatever the template.
@@ -24,6 +44,12 @@ Document contracts and architecture, not implementation details. Show function s
 
 The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
 
+**A date in a truth document is a defect, and the list of exceptions is closed.** Not a softened preference: a truth document carries no dated line at all, because a date answers *when did this happen*, which is a record's question, and a reader who needs the answer is reading the wrong file. The four exceptions, and there are no others: the frontmatter's tooling keys (`last-reviewed:`, `last-updated:`, `rev:` — written by tooling, never by you), an Architecture Decision's **Decision Changelog** tail, `docs/structure.md`'s **Health Log** tail, and a dated path inside a link or code span, which is a *citation* of a record rather than a claim about the present.
+
+**Cite a record by what it is, never by when it was.** `the dev reset runbook` links to the file; "the 2026-09-13 reset" states a date the reader must now keep in their head and that goes stale as soon as a second reset happens. The link carries the date in its path, where it belongs, and the prose stays true forever.
+
+**A verification stamp is a record, not a status line.** "Driven 2026-09-13 · PASS" in a behavioural checklist is the clearest instance of this defect: it reads as documentation and is actually a dated event. The section states what must be true and which suite test guards it; *that* somebody drove it on a Tuesday belongs to the changelog entry of the unit that drove it, and staleness is then visible from something that re-checks itself — a pin that runs in CI — rather than from a date nobody re-stamped. A section with no automated guard says so in its trace, which is a stronger signal than an old date, because it cannot silently become wrong.
+
 The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch. Two invocation traps: the disable comment takes **bare rule ids only** — prose inside the comment silently breaks the parse, so put the reason in a second comment beside it — and the script grades truth-vs-record scope by matching `docs/(history|research|memory)/` against **the path string it is given**, so always hand it a repo-root-relative path; linting a record from inside its own folder grades it as a truth document.
 
 ---
@@ -155,3 +181,5 @@ update, and the `maintenance` agent's baseline pass, route there.
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |
 | `scripts/doc-lint.mjs` | Mechanical checks over written docs (tense narration, dates, stubs, redirects) — run over changed docs before finishing |
+| `scripts/source-lint.mjs` | Mechanical checks over source **comments** (header path identity, the added-line comment ratio, narration, shouting) — run `--changed` before finishing any change that writes source |
+| `scripts/comment-strip.mjs` | The proof a comment sweep changed no executable code: strips comments from two revisions and diffs what is left. Exit 0 is the claim; exit 1 names the file and the first diverging line |