roast-my-design-system 9.2.5 → 9.3.0

package/README.md

@@ -17,7 +17,7 @@ npx roast-my-design-system@latest
 Run it at the root of a UI repo. One second later, a report opens.
 No account. No network. No telemetry. Nothing in your repo changes.
 
-**Current release: 9.2.** Version history in [CHANGELOG.md](CHANGELOG.md).
+**Current release: 9.3.** Version history in [CHANGELOG.md](CHANGELOG.md).
 
 ## The idea
 
@@ -142,11 +142,11 @@ Eleven reports, hosted exactly as the tool writes them. Every number determinist
 
 The full report for vercel/ai-chatbot. The verdict answers what the agent will learn here, the gap section comes first, then "What the repo teaches the agent", Claude's read of the scan:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then where the agent will have to guess, the fixes you can make right now, each with what it is worth and its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](assets/report-full-dark.png?v=9.2.4)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then where the agent will have to guess, the fixes you can make right now, each with what it is worth and its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](assets/report-full-dark.png?v=9.2.6)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](assets/report-light-hero.png?v=9.2.4)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.2.6)
 
 ## Why the numbers hold
 
@@ -206,6 +206,7 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 | <code>...&nbsp;--notes&nbsp;&lt;file.md&gt;</code> | The agent's read of this scan, embedded in the report as **"What the repo teaches the agent"**: 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 |
 | `... --hook` | The check the Claude Code plugin runs after every edit, for hand-installed setups: reads the hook event on stdin, checks the file that changed, prints only the findings the edit added as JSON. Always exits 0 |
+| `... --stop-hook` | The review the Claude Code plugin runs when the agent finishes its turn, for hand-installed setups: reads the Stop event on stdin and, when the files the session changed carry new problems, answers with a block that sends the agent back once. `--session-start` notes the work that was already uncommitted. `ROAST_STOP_REVIEW=off` turns it off. Always exits 0 |
 | `... --mcp` | The scan as a local MCP server: 5 tools your agent calls while writing UI, 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 repo teaches the agent", the rules offer, and the fix loop with Claude on your own numbers |
 
@@ -300,7 +301,7 @@ npx roast-my-design-system@latest
 /plugin install roast-my-design-system@roast-my-design-system
 ```
 
-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, 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 hook runs after every file the agent edits and hands back the findings that edit added; a file with nothing new gets no message.
+What it installs: two skills, one local MCP server and two checks that run on their own, nothing else. **roast** (`/roast-my-design-system`, or "roast my design system") scans the whole repo, 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 edit check runs after every file the agent edits and hands back the findings that edit added; a file with nothing new gets no message. The end-of-turn review runs when the agent says it is done: if the files this session changed still carry problems it added, the agent is sent back once to fix them before it finishes. Advice-only warnings never send it back, a problem is sent back once a session, and work that was uncommitted before the session started is left alone. To turn the review off, set `ROAST_STOP_REVIEW=off` in your Claude Code settings (`"env": { "ROAST_STOP_REVIEW": "off" }`).
 
 If those commands error, your Claude Code is older than the plugin marketplace. Update it, or use the manual route:
 

package/cli/roast.mjs

@@ -92,6 +92,10 @@ 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)
+  --stop-hook     Claude Code end-of-turn review: reads the Stop event on stdin
+                  and sends the agent back once when the files this session
+                  changed carry new violations. ROAST_STOP_REVIEW=off turns it
+                  off. --session-start notes the work that was already there
   --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
@@ -141,6 +145,24 @@ if (argv.includes('--mcp')) {
     console.error(`roast-my-design-system --hook: ${e.message}`);
   }
   process.exit(0);
+} else if (argv.includes('--stop-hook') || argv.includes('--session-start')) {
+  // Claude Code's Stop and SessionStart hooks, same rules as --hook: read the
+  // event on stdin, exit 0 whatever happens. Stop answers with a block and the
+  // findings when the agent should go back and fix what it added.
+  let raw = '';
+  try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  try {
+    const { stopResult, sessionStart } = await import(pathToFileURL(join(SCRIPTS, 'mcp/hook.mjs')).href);
+    const event = raw.trim() ? JSON.parse(raw) : {};
+    if (argv.includes('--session-start')) sessionStart(event);
+    else {
+      const r = stopResult(event);
+      if (r) console.log(JSON.stringify({ decision: 'block', reason: r.text }));
+    }
+  } catch (e) {
+    console.error(`roast-my-design-system ${argv.includes('--session-start') ? '--session-start' : '--stop-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": "9.2.5",
+  "version": "9.3.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/diagnose/index.mjs

@@ -1534,7 +1534,7 @@ function skippedLine() {
   const parts = [];
   if (skippedDirs.length) {
     const list = skippedDirs.slice(0, 6).map((e) => `<span class="mono">${esc(e.dir)}/</span> (${n(e.files)} UI file${e.files === 1 ? '' : 's'})`).join(', ');
-    parts.push(`<div class="excl">Left out by design: ${list}${skippedDirs.length > 6 ? ` and ${n(skippedDirs.length - 6)} more` : ''}. A docs site, a demo, an examples folder or a replaced app carries its own styling, which is not the product's design language.</div>`);
+    parts.push(`<div class="excl">Left out by design: ${list}${skippedDirs.length > 6 ? ` and ${n(skippedDirs.length - 6)} more` : ''}. A docs site, a demo, an examples folder, a replaced app or the templates a project generator copies out carries its own styling, which is not the product's design language.</div>`);
   }
   const ra = h.files?.readAnyway;
   if (ra) parts.push(`<div class="excl"><span class="mono">${esc(ra.dir)}/</span> is normally left out, but it holds ${n(ra.files)} UI files, more than the rest of the repo, so it was read as the product.</div>`);

package/skills/roast-my-design-system/scripts/harvest/walk.mjs

@@ -36,7 +36,7 @@ const SKIP_DIRS = new Set([
   'examples', 'example', 'demos', 'demo', 'playground', 'fixtures',
   // Test/fixture surfaces are not the product's design language — counting a
   // story's `export const Default` 36× would poison the diagnosis numbers.
-  '__tests__', '__mocks__', '__fixtures__', '__snapshots__',
+  '__tests__', '__mocks__', '__fixtures__', '__testfixtures__', '__snapshots__',
   'cypress', 'e2e', 'playwright', 'test', 'tests', '.storybook',
 ]);
 
@@ -78,6 +78,15 @@ const STYLE_EXTS = new Set(['.css', '.scss', '.sass', '.less']);
 // (2026-09-17). Named in the report like any other skipped folder.
 const LEGACY_DIR_RE = /^(?:old|legacy|deprecated|archive|archived)$|[-_](?:old|legacy|deprecated)$|^(?:old|legacy)[-_]/i;
 
+// Scaffolding: the code a project generator copies into someone else's new
+// repo, not the product. A starters/ folder, or a templates folder kept by a
+// generator (create-app, a cli), a script or a dev tool: backstage's
+// create-app/templates, the dashboard starter's scripts/cleanup-templates,
+// BuilderIO's starters (133 duplicate copies). The name alone is not enough:
+// backstage's scaffolder form templates, OpenCTI's case templates and
+// nocobase's block templates are screens of the product (2026-09-30).
+const SCAFFOLD_DIR_RE = /(^|\/)starters$|(^|\/)(?:create-[\w-]+|cli|scripts|dev|generators?)\/(?:[^/]+\/)*[\w-]*templates?$/i;
+
 export function walkRepo(root, maxDepth = 14, exclusions = null, readAnyway = new Set()) {
   const files = { code: [], styles: [], other: [] };
   const excluded = exclusions?.match ?? (() => null);
@@ -135,6 +144,7 @@ export function walkRepo(root, maxDepth = 14, exclusions = null, readAnyway = ne
       const p = join(dir, e.name);
       if (e.name === 'public' && e.isDirectory() && !hasComponentSource(p)) continue;
       const rel = relative(root, p).replaceAll('\\', '/');
+      if (e.isDirectory() && SCAFFOLD_DIR_RE.test(rel)) { countSkipped(p, rel); continue; }
       const hit = excluded(rel);
       if (hit) {
         if (e.isDirectory()) countExcluded(p, depth + 1, hit);

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 = '9.2.5';
+export const VERSION = '9.3.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/hook.mjs

@@ -83,6 +83,12 @@ export function hookResult(payload) {
   // (five repeats in one Dub rehearsal, 2026-09-25). Violations repeat
   // until they are fixed.
   const warned = new Set(ledger['\u0000warned'] ?? []);
+  // the files this session wrote, for the review at the end of the turn: a
+  // file named by an edit, or a file a shell command changed after the
+  // session began (uncommitted work already there is the person's, not the
+  // agent's)
+  const touched = new Set(ledger['\u0000touched'] ?? []);
+  const base = ledger['\u0000base'] ?? {};
   const blocks = [];
   let total = 0, knowledge = null;
   for (const abs of candidates) {
@@ -91,6 +97,7 @@ export function hookResult(payload) {
     const mtime = statSync(real).mtimeMs;
     if (!fromEditor && ledger[real] === mtime) continue;
     ledger[real] = mtime;
+    if (fromEditor || base[real] !== mtime) touched.add(real);
     // 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.
@@ -102,6 +109,7 @@ export function hookResult(payload) {
     if (r) { blocks.push(r.text); total += r.total; }
   }
   ledger['\u0000warned'] = [...warned];
+  ledger['\u0000touched'] = [...touched];
   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.');
@@ -109,7 +117,7 @@ export function hookResult(payload) {
 }
 
 /** One file against the system: only what the working copy added since HEAD. */
-function judge(real, root, k, warned = new Set()) {
+function judge(real, root, k, warned = new Set(), { violationsOnly = false } = {}) {
   const rel = relative(realpathSync.native(root), real).split('\\').join('/');
   const text = readFileSync(real, 'utf8');
   const before = beforeOf(k, rel);
@@ -124,11 +132,89 @@ function judge(real, root, k, warned = new Set()) {
   const fresh = typeof before === 'string' ? newSince(all, validateContent({ text: before, file: rel }, k).findings) : all;
   const findings = fresh.filter((f) => {
     if (f.severity !== 'warning') return true;
+    if (violationsOnly) return false;
     const key = `${rel}|${f.rule}|${f.message}`;
     if (warned.has(key)) return false;
     warned.add(key);
     return true;
   });
   if (!findings.length) return null;
+  if (violationsOnly) return { rel, findings, exempt, total: findings.length };
   return { text: `Design-system check of ${rel} (roast-my-design-system, the same engine as roast_validate): ${findingLines(findings, k, exempt).join('\n')}`, total: findings.length };
 }
+
+/**
+ * SessionStart: note the uncommitted UI files that were already there, so the
+ * review at the end of a turn never hands the agent someone else's work.
+ * Kept for the whole session: a resumed or compacted session keeps its start.
+ */
+export function sessionStart(payload) {
+  const session = payload?.session_id;
+  if (!session) return;
+  const ledger = readLedger(session);
+  if (ledger['\u0000base']) return;
+  const cwd = typeof payload?.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  const base = {};
+  for (const abs of changedFiles(cwd)) {
+    try { const real = realpathSync.native(abs); base[real] = statSync(real).mtimeMs; } catch { /* gone */ }
+  }
+  ledger['\u0000base'] = base;
+  writeLedger(session, ledger);
+}
+
+// Anything but these leaves the review on: it exists so that nobody has to
+// remember to ask for it.
+const OFF = /^(off|0|false|no)$/i;
+
+/**
+ * Stop: the review at the end of the agent's turn. The edit hook tells the
+ * agent about drift after each edit, and the agent may carry on regardless
+ * (Haiku still shipped it in 1 of 5 runs with the edit hook on, September
+ * 2026). This judges every UI file the session changed, keeps the violations
+ * that are new since HEAD, and when there are any sends the agent back once to
+ * fix them. Warnings never send it back. A second stop in a row always goes
+ * through: one extra round, never a loop.
+ * @param payload the Stop event Claude Code writes to stdin
+ * @returns { text, total } when the agent should go back, else null
+ */
+export function stopResult(payload, env = process.env) {
+  if (OFF.test(String(env.ROAST_STOP_REVIEW ?? ''))) return null;
+  if (payload?.stop_hook_active) return null;
+  const session = payload?.session_id;
+  if (!session) return null;
+  const ledger = readLedger(session);
+  const touched = ledger['\u0000touched'] ?? [];
+  if (!touched.length) return null;
+  const cwd = typeof payload?.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  // A problem is sent back once a session. What the agent kept after that
+  // (a deliberate value, commented) is its call, not a loop across turns.
+  const sent = new Set(ledger['\u0000sentback'] ?? []);
+  const results = [];
+  let total = 0, knowledge = null;
+  for (const real of touched) {
+    if (!existsSync(real)) continue;
+    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, new Set(), { violationsOnly: true });
+    if (!r) continue;
+    const findings = r.findings.filter((f) => !sent.has(`${r.rel}|${f.rule}|${f.message}`));
+    if (!findings.length) continue;
+    for (const f of findings) sent.add(`${r.rel}|${f.rule}|${f.message}`);
+    results.push({ ...r, findings, total: findings.length });
+    total += findings.length;
+  }
+  if (!total) return null;
+  ledger['\u0000sentback'] = [...sent];
+  writeLedger(session, ledger);
+  const L = [`Before you finish: the design-system review (roast-my-design-system) found ${total} problem${total === 1 ? '' : 's'} in what this session added to ${results.length} file${results.length === 1 ? '' : 's'}.`];
+  for (const r of results.slice(0, 10)) {
+    L.push(`${r.rel}:`);
+    for (const f of r.findings.slice(0, 8)) L.push(`  ✕ L${f.line} ${f.message}${f.fix ? `\n     Fix: ${f.fix}` : ''}`);
+    if (r.findings.length > 8) L.push(`  (+${r.findings.length - 8} more in this file)`);
+  }
+  if (results.length > 10) L.push(`(+${results.length - 10} more files)`);
+  L.push('Fix these in the repo\'s own vocabulary, as each fix says (a token, a spacing step, a theme path, the existing component), then finish. A value that is deliberate stays, with a one-line comment saying why; say so in your reply.');
+  return { text: L.join('\n'), total };
+}