roast-my-design-system 9.2.6 → 9.3.1

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
 
@@ -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.6",
+  "version": "9.3.1",
   "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/harvest/paint.mjs

@@ -50,7 +50,12 @@ const DOOR_TYPO_RE = /(?<![\w-])(?:[\w-]+:)*(?:font-(?:thin|extralight|light|nor
 export const blankComments = (s) => s
   .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
   .replace(/(^|[^:'"`\\])(\/\/[^\n]*)/g, (m, pre, c) => pre + ' '.repeat(c.length));
-export const DEMO_PATH_RE = /(^|\/)(stories|storybook|__stories__|examples?|demos?|templates?|playground|fixtures?|__tests__|__mocks__|e2e|cypress)\//i;
+// Not templates: in a product a templates folder is usually a screen
+// (teable's admin templates, documenso's and formbricks' template pickers),
+// and hiding it hid their colours from the report and the live checks. A
+// project generator's templates are left out by the walk instead, and email
+// templates by the email rule (2026-09-30).
+export const DEMO_PATH_RE = /(^|\/)(stories|storybook|__stories__|examples?|demos?|playground|fixtures?|__tests__|__mocks__|e2e|cypress)\//i;
 
 /**
  * @param root repo root

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

@@ -80,12 +80,13 @@ const LEGACY_DIR_RE = /^(?:old|legacy|deprecated|archive|archived)$|[-_](?:old|l
 
 // 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;
+// generator (create-app, a cli, a command-line tool's commands), a script or
+// a dev tool: backstage's create-app/templates, the dashboard starter's
+// scripts/cleanup-templates, BuilderIO's starters (133 duplicate copies),
+// novu's commands/init/templates. 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|commands|scripts|dev|generators?)\/(?:[^/]+\/)*[\w-]*templates?$/i;
 
 export function walkRepo(root, maxDepth = 14, exclusions = null, readAnyway = new Set()) {
   const files = { code: [], styles: [], other: [] };

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.6';
+export const VERSION = '9.3.1';
 // 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 };
+}