roast-my-design-system 8.6.2 → 8.8.0

package/README.md

@@ -8,7 +8,7 @@
 
 ## Your AI can write the UI. This makes sure it writes *your* UI.
 
-A free CLI tool, and a Claude Code plugin with two skills and a bundled local MCP server, that roasts your repo's design system with real data, reviews what you change against it, and generates the rules that keep your AI agent on-system.
+A free CLI tool, and a Claude Code plugin with two skills, a bundled local MCP server and an edit hook, that roasts your repo's design system with real data, reviews what you change against it, and generates the rules that keep your AI agent on-system.
 
 > **New in 8.0: support for the four big component kits.**
 >
@@ -97,6 +97,7 @@ These need an agent.
 |---|---|
 | <code>...&nbsp;--notes&nbsp;&lt;file.md&gt;</code> | The agent's read of this scan, embedded in the report as **"What the numbers mean"**: which findings matter, which good numbers are accidents, what to fix first. Labelled as written by AI and kept apart from the measured numbers. The Claude Code skill writes and passes it automatically; the flag is here so any agent can |
 | <code>...&nbsp;--section&nbsp;"Title"&nbsp;&lt;file.md&gt;</code> | A further agent-written chapter after the notes, same styling, same label, sub-headings allowed. Repeatable, so analysis that outgrows the notes still lives inside the report instead of a hand-built page |
+| `... --hook` | The check the Claude Code plugin runs after every edit, for hand-installed setups: reads the hook event on stdin, checks the one file that changed, prints only the findings the edit added as JSON. Always exits 0 |
 | `... --mcp` | The scan as a local MCP server: 5 tools your agent calls while writing UI, from "is there a Button already?" to "review my changes", plus the `roast-fix` prompt that serves the top fix from a fresh scan. See [Live answers over MCP](#live-answers-over-mcp) |
 | <code>/roast-my-design-system</code> (in&nbsp;Claude&nbsp;Code) | The full experience: the roast in chat *and* embedded in the report as "What the numbers mean", the rules offer, and the fix loop with Claude on your own numbers |
 
@@ -179,6 +180,8 @@ The report and the rules file describe the repo as it was at scan time. `--mcp`
 
 The loop: context before building, find while building, validate before saving, review before finishing.
 
+Charts get their own rule, because a chart needs several colours that differ from each other and most design systems never name them. In a repo that keeps a chart palette (its own `--chart-*` or `--series-*` tokens, a `chartColors` entry in the theme, or shadcn's `--chart-1` to `--chart-5` when a chart actually reads them), a colour written by hand in a chart file is a finding that names the palette. In a repo that has charts but no palette, a new chart that paints by hand gets one warning that names the existing chart doing the same and asks for the palette once. The first chart in a repo gets one warning asking for a name. The report never counted chart colours; the live checks now agree with it.
+
 The server reads the repo the way the report does. On a product built on MUI, Mantine, Chakra UI or Ant Design, the context names the theme file and the kit's own way of reading it, `roast_find_token` answers in spacing steps (`12px` is `p: 3` on a 4px MUI theme), and `roast_validate` and `roast_review` flag a colour or a pixel size written onto a kit component where the theme has a value. On a Tailwind theme or a shadcn repo they flag a palette class such as `text-gray-500` or `ring-green-500` where the theme names a colour of that kind.
 
 ### What a session looks like
@@ -221,7 +224,7 @@ It writes a first draft anyway and runs `roast_validate` before saving:
 Second draft: `color: 'text.secondary'`, `p: 1.5`, the radius read from the theme. `roast_validate` again:
 
 ```
-No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing, off-scale radii, font sizes and shadows, typefaces outside the system, arbitrary bracket values, static inline style blocks, !important, duplicate component definitions, new colour tokens that twin an existing token, imports of a duplicate the canonical copy replaces, colours and pixel sizes written onto kit components where the theme has a value.
+No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing, off-scale radii, font sizes and shadows, typefaces outside the system, arbitrary bracket values, static inline style blocks, !important, duplicate component definitions, new colour tokens that twin an existing token, imports of a duplicate the canonical copy replaces, chart colours against the chart palette, colours and pixel sizes written onto kit components where the theme has a value.
 ```
 
 Four calls, under 800 tokens in total, and the new component reads the theme instead of adding colour number 44. `roast_review` then checks the whole diff the same way before the agent says it is done.
@@ -285,7 +288,7 @@ Run it inside any repo. Same scanner, same report, straight from npm. The Claude
 /plugin install roast-my-design-system@roast-my-design-system
 ```
 
-What it installs: two skills and one local MCP server, nothing else. **roast** (`/roast-my-design-system`, or "roast my design system") scans the whole repo and writes the report with Claude's read of the numbers inside it, then walks the fixes with you. **review** (`/roast-my-design-system:review`, or "review my UI changes") checks only what changed, in about a second. The bundled server gives your agent five read-only tools while it writes UI. Local, no network, no telemetry.
+What it installs: two skills, one local MCP server and one edit hook, nothing else. **roast** (`/roast-my-design-system`, or "roast my design system") scans the whole repo and writes the report with Claude's read of the numbers inside it, then walks the fixes with you. **review** (`/roast-my-design-system:review`, or "review my UI changes") checks only what changed, in about a second. The bundled server gives your agent five read-only tools while it writes UI. The hook runs after every file the agent edits and hands back the findings that edit added, so the check happens whether or not the agent thought to ask; a file with nothing new gets no message. Local, no network, no telemetry.
 
 If those commands error, your Claude Code is likely older than the plugin marketplace feature. Update Claude Code and retry, or use the manual route below: it works everywhere and installs the same skill.
 

package/cli/roast.mjs

@@ -90,6 +90,8 @@ Run it yourself
                   number of files it removed, so a scoped scan says so
   --json          print the scan summary as JSON on stdout (implies --no-open)
   --check         check the working tree's changed files (git diff + untracked)
+  --hook          Claude Code edit hook: reads the PostToolUse event on stdin,
+                  checks the one file that changed, answers with findings
                   against the design system and print the findings; exits 1
                   when something is over the line, so it composes with scripts
 
@@ -123,6 +125,20 @@ if (argv.includes('--mcp')) {
   // the server owns the process now; readline keeps it alive until the client
   // closes stdin, and nothing below (the report pipeline) may run
   await new Promise(() => {});
+} else if (argv.includes('--hook')) {
+  // Claude Code's PostToolUse hook: the event arrives as JSON on stdin, the
+  // findings leave as JSON on stdout. Exit 0 whatever happens — a hook that
+  // fails must never stop the agent editing; it only loses one check.
+  let raw = '';
+  try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  try {
+    const { hookResult } = await import(pathToFileURL(join(SCRIPTS, 'mcp/hook.mjs')).href);
+    const r = hookResult(raw.trim() ? JSON.parse(raw) : {});
+    if (r) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: r.text } }));
+  } catch (e) {
+    console.error(`roast-my-design-system --hook: ${e.message}`);
+  }
+  process.exit(0);
 } else if (argv.includes('--check')) {
   argv.splice(argv.indexOf('--check'), 1);
   const root = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "8.6.2",
+  "version": "8.8.0",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 112 public repos, reads React and web components (Stencil, Lit), hands you a copy-paste fix prompt for each top finding, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [

package/skills/roast-my-design-system/scripts/lib/charts.mjs

@@ -0,0 +1,146 @@
+/**
+ * Chart colours. A chart needs several colours that differ from each other,
+ * and most design systems never name them. Probe over the 126 benchmark
+ * repos (2026-09-25): charts in three quarters of them, a named chart palette
+ * in a quarter, and the biggest group (43) is charts painting their series
+ * by hand with no palette to point at. The report leaves chart colours out
+ * (a picture, not paint); the live checks counted every one, so the same
+ * file got two verdicts depending on the door. One rule now, three tiers:
+ *
+ *   1. The repo keeps a chart palette: its own names, or shadcn's default
+ *      --chart-1..5 when a chart actually reads them. A colour written by
+ *      hand in a chart is drift, and the finding names the palette.
+ *   2. No palette, but a chart already paints by hand. The new chart follows
+ *      a precedent rather than breaking a rule: one warning per file that
+ *      names the precedent and asks for the palette, once.
+ *   3. No palette, no chart: the first chart. One warning, so the colours
+ *      get a name before the second chart copies them.
+ *
+ * shadcn's --chart-1..5 arrive with the install whether or not any chart
+ * uses them (6 of the 126 repos), so they count as a palette only when a
+ * chart reads them; otherwise the repo is tier 2 with the fix ready-made.
+ */
+import { basename } from 'node:path';
+import { parseColor } from './color.mjs';
+
+// chart libraries only: a map or an editor is a renderer too, but its
+// colours are never a series (lib/kitpaint.mjs keeps the wider list)
+export const CHART_IMPORT_RE = /from\s+['"](?:recharts|chart\.js|react-chartjs-2|echarts|echarts-for-react|d3|d3-[\w-]+|@nivo\/[\w-]+|victory|apexcharts|react-apexcharts|highcharts|highcharts-react-official|plotly\.js[\w-]*|react-plotly\.js|@visx\/[\w-]+|@antv\/[\w-]+|@mui\/x-charts|@mantine\/charts|@tremor\/react|lightweight-charts|uplot|uplot-react|frappe-charts|@ant-design\/(?:plots|charts)|chartist|billboard\.js|vega|vega-lite|@observablehq\/plot|@carbon\/charts[\w-]*|react-vis)['"\/]/;
+// a file named for a chart; "graphql" is not a graph, "flowchart" is a diagram
+const CHART_NAME_RE = /(^|[^a-z])(chart|graph(?!ql)|sparkline|donut|histogram|heatmap)/i;
+// an icon, an illustration, a story or a build is not a chart, whatever it
+// imports (likec4's icon set, twenty's storybook, a committed Next chunk)
+const NOT_CHART_RE = /(^|\/)(icons?|illustrations?|__stories__|stories|storybook|\.storybook|static\/chunks|dist|build|out)\/|\.stories\.[jt]sx?$/i;
+const CHART_TOKEN_RE = /(--(?:chart|charts|series|graph|graphs|viz|dataviz|data-viz|visuali[sz]ation)[\w-]*)\s*:\s*([^;{}]+)[;}]/gi;
+// a key in a theme, tokens or palette file: chartColors, charts: {…}, series: […]
+const THEME_FILE_RE = /(^|\/)[\w.-]*(theme|palette|colou?rs?|tokens?|foundations?)[\w.-]*(\/|\.[jt]sx?$)/i;
+const CHART_KEY_RE = /\b((?:chart|charts|series|graph|dataviz|dataViz|visuali[sz]ation)(?:Colou?rs|Palette|colou?rs|palette)?)\s*:\s*[{[]/g;
+const COLOUR_LITERAL_RE = /(['"`])(#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgba?|hsla?|oklch|oklab)\([^)'"`]*\))\1/g;
+const SHADCN_DEFAULT_RE = /^--chart-[1-5]$/;
+
+// a token value that is a colour: hex, rgb(), hsl(), oklch(), or shadcn's
+// bare "220 70% 50%" triplet. "--chart-help: 'Pick a range'" is not one.
+const isColourValue = (v) => {
+  const s = v.trim();
+  if (parseColor(s)) return true;
+  return /^(oklch|oklab|color|lab|lch)\(/.test(s) || /^\d+(?:\.\d+)?\s+\d+(?:\.\d+)?%\s+\d+(?:\.\d+)?%$/.test(s);
+};
+
+/** A chart file: imports a chart library, or is named for one. */
+export function isChartFile(file, text) {
+  if (file && NOT_CHART_RE.test(file)) return false;
+  if (text && CHART_IMPORT_RE.test(text)) return true;
+  return !!file && CHART_NAME_RE.test(basename(file));
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// how a chart would read a palette entry: var(--chart-1) or the class chart-1
+// for a CSS name, the key itself for a theme key
+const refRe = (name) => name.startsWith('--')
+  ? new RegExp(`(?:var\\(\\s*${escapeRe(name)}\\b|(?:^|[^\\w-])${escapeRe(name.slice(2))}(?![\\w-]))`)
+  : new RegExp(`\\b${escapeRe(name)}\\b`);
+
+/**
+ * What the repo already knows about charts, from the same file set the rest
+ * of the knowledge reads.
+ * @returns { palette: { names, file, shadcnDefault, referenced } | null,
+ *            precedents: [{ file, count, sample }], chartFiles }
+ */
+export function chartSystemOf(files, read) {
+  const names = [], where = new Map();
+  const noteToken = (name, file) => { if (!where.has(name)) { names.push(name); where.set(name, file); } };
+  for (const f of files.styles ?? []) {
+    const text = read(f); if (text === null) continue;
+    for (const m of text.matchAll(CHART_TOKEN_RE)) if (isColourValue(m[2])) noteToken(m[1], f);
+  }
+  const chartTexts = [];
+  for (const f of files.code ?? []) {
+    const text = read(f); if (text === null) continue;
+    // a CSS-in-JS theme or a Tailwind @theme inside a .ts file defines
+    // custom properties too
+    for (const m of text.matchAll(CHART_TOKEN_RE)) if (isColourValue(m[2])) noteToken(m[1], f);
+    if (THEME_FILE_RE.test(f)) {
+      for (const m of text.matchAll(CHART_KEY_RE)) {
+        if (COLOUR_LITERAL_RE.test(text.slice(m.index, m.index + 600))) noteToken(m[1], f);
+      }
+    }
+    if (isChartFile(f, text)) chartTexts.push({ f, text });
+  }
+  const palette = names.length ? { names, file: where.get(names[0]), shadcnDefault: names.every((n) => SHADCN_DEFAULT_RE.test(n)), referenced: false } : null;
+  const precedents = [];
+  for (const { f, text } of chartTexts) {
+    if (palette && !palette.referenced && palette.names.some((n) => refRe(n).test(text))) palette.referenced = true;
+    const literals = [...new Set([...text.matchAll(COLOUR_LITERAL_RE)].map((m) => m[2].toLowerCase()))];
+    if (literals.length >= 2) precedents.push({ file: f, count: literals.length, sample: literals.slice(0, 3) });
+  }
+  precedents.sort((a, b) => b.count - a.count);
+  return { palette, precedents, chartFiles: chartTexts.length };
+}
+
+/** 1: a palette to use; 2: a precedent and a gap; 3: the first chart. */
+export function chartTier(charts) {
+  if (!charts) return 3;
+  if (charts.palette && (!charts.palette.shadcnDefault || charts.palette.referenced)) return 1;
+  if (charts.precedents.length || charts.palette) return 2;
+  return 3;
+}
+
+const list = (values, max = 6) => `${values.slice(0, max).join(', ')}${values.length > max ? ` and ${values.length - max} more` : ''}`;
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+/**
+ * The findings for the colours a chart file writes by hand.
+ * @param colours [{ value, index }] the non-token colour literals in the file
+ */
+export function chartFindings({ file, colours, charts, tokenFile = null }) {
+  if (!colours?.length) return [];
+  const tier = chartTier(charts);
+  const distinct = [...new Set(colours.map((c) => c.value))];
+  const first = colours[0].index;
+  if (tier === 1) {
+    const { names, file: pf } = charts.palette;
+    const example = names[0].startsWith('--') ? `var(${names[0]})` : `${names[0]}[0]`;
+    return colours.map((c) => ({
+      rule: 'chart-colour', severity: 'violation', index: c.index,
+      message: `Chart colour ${c.value} written by hand; this repo keeps a chart palette (${list(names, 5)} in ${pf}).`,
+      fix: `Read the series colour from the palette (${example}). A series that needs a colour the palette lacks gets a new entry there, once.`,
+    }));
+  }
+  const where = tokenFile ?? 'the theme';
+  if (tier === 2) {
+    const prec = charts.precedents.find((p) => p.file !== file) ?? null;
+    const shadcn = charts.palette?.shadcnDefault ? charts.palette : null;
+    return [{
+      rule: 'chart-palette', severity: 'warning', index: first,
+      message: `This chart paints its ${plural(distinct.length, 'series colour')} by hand (${list(distinct)}); the repo has no chart palette${prec ? `, and ${prec.file} already does the same with ${prec.count}` : ''}.`,
+      fix: shadcn
+        ? `The theme already defines --chart-1 to --chart-5 in ${shadcn.file} and no chart reads them. Read them here (var(--chart-1))${prec ? ` and point ${prec.file} at them too` : ''}.`
+        : `Name these once as chart tokens (--chart-1, --chart-2 … in ${where}) and read them here${prec ? ` and in ${prec.file}` : ''}, so every chart draws from one set.`,
+    }];
+  }
+  return [{
+    rule: 'chart-palette', severity: 'warning', index: first,
+    message: `First chart in this repo: ${plural(distinct.length, 'series colour')} written by hand (${list(distinct)}) and no chart palette exists yet.`,
+    fix: `Name them once as chart tokens (--chart-1, --chart-2 … in ${where}) so the next chart reads the same set instead of copying these.`,
+  }];
+}

package/skills/roast-my-design-system/scripts/lib/guard-api.mjs

@@ -11,6 +11,7 @@
  */
 import { extname, join } from 'node:path';
 import { walkRepo, readSource, profileRepo } from '../harvest/walk.mjs';
+import { chartSystemOf } from './charts.mjs';
 import { decideProfile, profileOf, installedDirs } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { kitPaintFindings } from './kitpaint.mjs';
@@ -59,6 +60,7 @@ export { kitPaintFindings };
 // Same words as roast_validate, roast_review and --check.
 export { tokenTwinFindings, tokenDefsOf } from './tokentwins.mjs';
 export { avoidedImportFindings, canonicalCopy } from './avoidedimports.mjs';
+export { isChartFile, chartSystemOf, chartTier, chartFindings } from './charts.mjs';
 
 // Radius, font size, shadow and typeface: the patterns, so both checkers agree
 // on what a declaration is and what counts as a disciplined value.
@@ -90,6 +92,7 @@ export const isStyleFile = (p) => STYLE_EXTS.has(extname(p));
  *   tailwind,         // { colors, spacing, radii, textSizes, arbitrary }
  *   components,       // [{ name, file, usageCount, isPage }] the ledger
  *   tokenDefs,        // [{ name, file, value, canon, darkValue?, darkCanon? }] colour tokens
+ *   charts,           // { palette, precedents, chartFiles } the chart palette or its absence
  *   duplicates,       // Map<name, { copies: [{ file, usageCount }], strays }>
  *   files,            // { styles: n, code: n } — how much was read
  * }
@@ -152,6 +155,8 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
     // every colour token each stylesheet defines, light and dark: the
     // `others` tokenTwinFindings compares a new token with (8.6.1)
     tokenDefs: repoTokenDefs(files.styles, read),
+    // the chart palette, or the charts painting by hand without one (lib/charts.mjs)
+    charts: chartSystemOf(files, read),
     // each duplicated name's copies, their usage and the colours each
     // non-canonical copy hard-codes: the `dupes` avoidedImportFindings reads
     duplicates: dupeCopiesOf(hardDupes, ledger, read),

package/skills/roast-my-design-system/scripts/lib/version.mjs

@@ -1,7 +1,7 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '8.6.2';
+export const VERSION = '8.8.0';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

package/skills/roast-my-design-system/scripts/mcp/engine.mjs

@@ -22,6 +22,7 @@ import { TAILWIND_DEFAULTS } from '../profiles/tailwind-defaults.mjs';
 import { oklab } from '../lib/color.mjs';
 import { tokenTwinFindings } from '../lib/tokentwins.mjs';
 import { avoidedImportFindings } from '../lib/avoidedimports.mjs';
+import { isChartFile, chartFindings } from '../lib/charts.mjs';
 
 // What this engine measures — shipped with every result, clean or not.
 export const CHECKS = [
@@ -36,6 +37,7 @@ export const CHECKS = [
   'duplicate component definitions',
   'new colour tokens that twin an existing token',
   'imports of a duplicate the canonical copy replaces',
+  'chart colours against the chart palette',
 ];
 // What a kit or a Tailwind theme adds to the list, so a clean result on an
 // MUI repo says the kit check ran.
@@ -121,7 +123,18 @@ export function validateContent(content, k) {
   // knows which are not paint (a comment, a fallback after a theme read, a
   // compare, SVG artwork), so the generic check stays out of its way.
   let kitOwnsColours = false;
-  if (k.kit?.def && !css) {
+  // ---------- chart colours ----------
+  // A chart's series colours are judged against the chart palette, or its
+  // absence, by lib/charts.mjs: the report never counted them, the live
+  // checks counted every one, and the same file got two verdicts. On a
+  // chart file the chart rule owns colours; the kit judge and the generic
+  // colour check stay out of its way.
+  const chartFile = !css && !!k.charts && isChartFile(file, text);
+  if (chartFile) {
+    const paint = got.colors.filter((c) => !k.colorInfo.get(c.value)?.isToken);
+    for (const f of chartFindings({ file, colours: paint, charts: k.charts, tokenFile: k.tokens.tokenFile })) add(f.rule, f.severity, f.index, f.message, f.fix);
+  }
+  if (k.kit?.def && !css && !chartFile) {
     const judged = kitPaintFindings(text, k.kit, { file });
     if (judged && !judged.exempt) {
       kitOwnsColours = true;
@@ -187,7 +200,7 @@ export function validateContent(content, k) {
   for (const c of got.colors) {
     if (seenHere.has(`${c.value}:${c.index}`)) continue;
     seenHere.add(`${c.value}:${c.index}`);
-    if (kitOwnsColours) continue; // the kit judge said it, or judged it not paint
+    if (kitOwnsColours || chartFile) continue; // the kit judge or the chart rule said it, or judged it not paint
     const info = k.colorInfo.get(c.value);
     if (info?.isToken) continue; // it IS the token's value — the system can see it
     const near = nearestToken(c.value, k);

package/skills/roast-my-design-system/scripts/mcp/hook.mjs

@@ -0,0 +1,119 @@
+/**
+ * The edit hook — roast_validate without the agent having to ask.
+ *
+ * The MCP tools only help when the agent decides to call them. In the
+ * September 2026 runs Sonnet asked in about a third of sessions and Haiku
+ * never did, so the drift it would have caught went straight into the
+ * diff. A Claude Code plugin can also register a hook that runs after every
+ * Edit or Write; this is that hook. It reads the event, judges the one file
+ * that changed with the same engine and the same words as roast_validate,
+ * and hands the findings back as context. Silent when there is nothing to
+ * say: a hook that talks on every edit is a hook people switch off.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { validateContent } from './engine.mjs';
+import { loadKnowledge } from './knowledge.mjs';
+import { RELEVANT, beforeOf, findingLines } from './tools.mjs';
+
+const gitTop = (dir) => {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { return null; }
+};
+
+// The files a shell command may have written: everything changed or untracked
+// in the repo that the review would judge. Cheap (two git calls), and the
+// mtime ledger below keeps it from re-judging what the hook already saw.
+function changedFiles(root) {
+  try {
+    const git = (...a) => execFileSync('git', a, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const top = realpathSync.native(git('rev-parse', '--show-toplevel').trim());
+    const names = [...git('diff', 'HEAD', '--name-only').split('\n'), ...git('ls-files', '--others', '--exclude-standard', '--full-name').split('\n')];
+    return [...new Set(names.map((s) => s.trim()).filter((f) => f && RELEVANT.test(f)))].map((f) => join(top, f));
+  } catch { return []; }
+}
+
+// What the hook has judged this session, file → mtime, so a file is judged
+// once per change however it was written, and never twice for one save.
+const ledgerPath = (session) => join(tmpdir(), `roast-hook-${String(session).replace(/[^A-Za-z0-9_-]/g, '')}.json`);
+function readLedger(session) {
+  if (!session) return {};
+  try { return JSON.parse(readFileSync(ledgerPath(session), 'utf8')); } catch { return {}; }
+}
+function writeLedger(session, ledger) {
+  if (!session) return;
+  try { writeFileSync(ledgerPath(session), JSON.stringify(ledger)); } catch { /* a lost ledger costs one repeat, nothing more */ }
+}
+
+const keyOf = (f) => `${f.rule}|${f.message}`;
+/** The findings in `now` that `prior` does not account for, kind by kind. */
+export function newSince(now, prior) {
+  const budget = new Map();
+  for (const f of prior) budget.set(keyOf(f), (budget.get(keyOf(f)) ?? 0) + 1);
+  return now.filter((f) => {
+    const n = budget.get(keyOf(f)) ?? 0;
+    if (!n) return true;
+    budget.set(keyOf(f), n - 1);
+    return false;
+  });
+}
+
+/**
+ * @param payload the PostToolUse event Claude Code writes to stdin
+ * @returns { text, total } when a changed file has new findings, else null
+ */
+export function hookResult(payload) {
+  const cwd = typeof payload?.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  const named = payload?.tool_input?.file_path;
+  const fromEditor = typeof named === 'string' && RELEVANT.test(named);
+  // An Edit or Write names its file. A shell command (cat > file, sed -i, a
+  // generator) names nothing, so every changed UI file is a candidate and
+  // the ledger decides which ones are new since the hook last looked.
+  const candidates = fromEditor
+    ? [isAbsolute(named) ? named : resolve(cwd, named)]
+    : payload?.tool_name === 'Bash' ? changedFiles(cwd) : [];
+  const session = payload?.session_id;
+  const ledger = readLedger(session);
+  const blocks = [];
+  let total = 0, knowledge = null;
+  for (const abs of candidates) {
+    if (!existsSync(abs)) continue;
+    const real = realpathSync.native(abs);
+    const mtime = statSync(real).mtimeMs;
+    if (!fromEditor && ledger[real] === mtime) continue;
+    ledger[real] = mtime;
+    // The repo is the session's working directory when the file lives under
+    // it (the same root the MCP server would be pointed at); a file edited
+    // elsewhere is judged against its own repository.
+    const under = (root) => root && real.startsWith(realpathSync.native(root) + '/');
+    const root = under(cwd) ? cwd : gitTop(dirname(real));
+    if (!root) continue;
+    const k = knowledge?.root === root ? knowledge : (knowledge = loadKnowledge(root));
+    const r = judge(real, root, k);
+    if (r) { blocks.push(r.text); total += r.total; }
+  }
+  writeLedger(session, ledger);
+  if (!blocks.length) return null;
+  blocks.push('Fix these now, in the repo\'s own vocabulary as each fix says (a token, a spacing step, a theme path), not by deleting the code. A value that is deliberate stays, with a one-line comment saying why.');
+  return { text: blocks.join('\n'), total };
+}
+
+/** One file against the system: only what the working copy added since HEAD. */
+function judge(real, root, k) {
+  const rel = relative(realpathSync.native(root), real).split('\\').join('/');
+  const text = readFileSync(real, 'utf8');
+  const before = beforeOf(k, rel);
+  const { findings: all, exempt } = validateContent({ text, file: rel, before }, k);
+  if (exempt || !all.length) return null;
+  // Only what this edit added. A legacy file carries its old findings on
+  // every touch; repeating them after each edit is noise, and the review
+  // (--check, roast_review) already reports them once at the end. Same rule
+  // as the September runs measured by: a finding is new when the file has
+  // more of it than the committed version did.
+  const findings = typeof before === 'string' ? newSince(all, validateContent({ text: before, file: rel }, k).findings) : all;
+  if (!findings.length) return null;
+  return { text: `Design-system check of ${rel} (roast-my-design-system, the same engine as roast_validate): ${findingLines(findings, k).join('\n')}`, total: findings.length };
+}

package/skills/roast-my-design-system/scripts/mcp/knowledge.mjs

@@ -26,6 +26,7 @@ import { decideProfile, profileOf } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { repoTokenDefs } from '../lib/tokentwins.mjs';
 import { dupeCopiesOf } from '../lib/avoidedimports.mjs';
+import { chartSystemOf } from '../lib/charts.mjs';
 
 const MAX_DEPTH = 14; // same ruler as the harvest CLI
 
@@ -128,6 +129,9 @@ export function loadKnowledge(root) {
   // Every colour token each stylesheet defines, light and dark, so a new one
   // can be compared with the ones already there (lib/tokentwins).
   const tokenDefs = repoTokenDefs(files.styles, read);
+  // the chart palette the repo keeps, or the charts that paint by hand
+  // without one (lib/charts.mjs)
+  const charts = chartSystemOf(files, read);
 
   return {
     root,
@@ -156,6 +160,7 @@ export function loadKnowledge(root) {
     dupeByName,
     dupeCopies,
     tokenDefs,
+    charts,
     neverImported,
     // stock, not debt: see profiles/index.mjs
     vendoredUi: P.vendoredUi,

package/skills/roast-my-design-system/scripts/mcp/tools.mjs

@@ -15,6 +15,8 @@ import { hexRgb } from '../lib/nearpairs.mjs';
 import { distinctTypefaces } from '../lib/typefaces.mjs';
 
 const CONTEXT_BUDGET = 1600; // chars ≈ 400 tokens
+// the files a review or an edit hook judges; everything else is not UI
+export const RELEVANT = /\.(tsx|jsx|ts|js|vue|svelte|css|scss|sass|less)$/i;
 const MAX_VALIDATE_CHARS = 200_000; // a whole file, not a whole bundle
 const approxTokens = (s) => Math.ceil(s.length / 4);
 
@@ -288,7 +290,7 @@ function headVersion(gitRoot, gitPath) {
     } catch { return undefined; }
   }
 }
-function beforeOf(k, file) {
+export function beforeOf(k, file) {
   if (!file) return undefined;
   try {
     const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: k.root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
@@ -304,13 +306,18 @@ export function validate(k, { code, file = null } = {}) {
   const { findings, exempt } = validateContent({ text: code, file, before: beforeOf(k, file) }, k);
   if (exempt) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
   if (!findings.length) return cleanResultText(k);
+  return findingLines(findings, k).join('\n');
+}
+
+/** The finding list as roast_validate prints it; the edit hook prints the same. */
+export function findingLines(findings, k) {
   const L = [`${findings.length} finding${findings.length === 1 ? '' : 's'}:`];
   for (const f of findings.slice(0, 12)) {
     L.push(`${f.severity === 'violation' ? '✕' : '⚠'} L${f.line} ${f.message}${f.fix ? `\n   Fix: ${f.fix}` : ''}`);
   }
   if (findings.length > 12) L.push(`(+${findings.length - 12} more of the same kinds)`);
   L.push(`Checked: ${checksFor(k).join(', ')}.`);
-  return L.join('\n');
+  return L;
 }
 
 // ---------- roast_review ----------
@@ -336,7 +343,6 @@ export function reviewData(k) {
   } catch {
     return { text: 'Not a git repository (or git is unavailable), so there is no diff to review. Use roast_validate with the code instead.', total: 0 };
   }
-  const RELEVANT = /\.(tsx|jsx|ts|js|vue|svelte|css|scss|sass|less)$/i;
   const changed = names.filter((f) => RELEVANT.test(f));
   if (!changed.length) return { text: 'No changed UI or style files in the working tree. Nothing to review.', total: 0 };