roast-my-design-system 5.0.2 → 5.1.0

package/README.md

@@ -6,6 +6,8 @@
 
 A free CLI tool (and Claude Code skill) that roasts your repo's design system with real data, then generates the rules that keep your AI agent on-system.
 
+> **New in 5.1: the roast's analysis now ships inside the report.** Run as the Claude Code skill, the report gains a "What the numbers mean" section — Claude's read of your scan, in the same shareable file as the score, so the analysis reaches whoever the report is forwarded to. Labelled as written by AI, never mixed into the measurement.
+
 > **New in 5.0: it runs as a local MCP server.** One command, and your agent asks the design system before writing UI, then gets the work checked after: which Button is canonical, which token holds that colour, review my changes. Local, deterministic, nothing leaves your machine. See [Live answers over MCP](#live-answers-over-mcp).
 
 Run it on your codebase and get, in about a second:
@@ -35,10 +37,11 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 | `... --mcp` | The scan as a local MCP server: five tools your agent calls while writing UI, from "is there a Button already?" to "review my changes". See [Live answers over MCP](#live-answers-over-mcp) |
 | `... --check` | The working tree's changed files checked against the design system, in the terminal. Exits 1 on findings, so it slots into scripts |
 | <code>...&nbsp;--by&nbsp;"Dwayne&nbsp;Hicks"</code> | A requester credit in the report header, next to the scan date |
+| <code>...&nbsp;--notes&nbsp;&lt;file.md&gt;</code> | An agent-written analysis embedded in the report as **"What the numbers mean"**: labelled as written by AI, kept apart from the measured numbers. The Claude Code skill writes and passes this automatically; the flag is here so any agent can |
 | <code>...&nbsp;--exclude&nbsp;lab/</code> | Leave a folder out of the scan (repeat the flag or comma-separate). Or list folders in a `.roastignore` file at the repo root. Either way the report says so in the header; see [Scoping the scan](#scoping-the-scan) |
 | `... --json` | The scan summary as JSON on stdout, for scripts and pipelines |
 | <code>...&nbsp;--theme&nbsp;light</code>&nbsp;/ <code>--out&nbsp;&lt;file&gt;</code>&nbsp;/ <code>--no-open</code> | Light report, custom report path, don't open the browser |
-| <code>/roast-my-design-system</code> (in&nbsp;Claude&nbsp;Code) | The full experience: the roast in chat, the report, the rules offer, and the fix loop with Claude on your own numbers |
+| <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 |
 
 **One scan writes rules for every agent: Claude, Cursor, GitHub Copilot, and Windsurf.** Every scan also checks the agent rules you already have and flags stale references, no flag needed.
 
@@ -171,6 +174,7 @@ Open Claude Code in the repo you want roasted and type:
 You get the roast in chat plus `design-system-roast.html` at your repo root: a self-contained page (open it, Slack it, email it, no external requests) with:
 
 - a **health score** computed from how your numbers sit against the ideal
+- **"What the numbers mean"**: Claude's read of your scan — which findings actually matter, which good numbers are accidents, what to fix first — embedded in the same file you'll forward, labelled as written by Claude and kept apart from the measured numbers. The score alone can flatter; this section is what keeps a shared 85/100 honest
 - stat tiles comparing you to all three yardsticks: Ideal, the 34-repo average, and the reputable systems
 - a **light/dark theme toggle** in one file
 - the usage-weighted palette bar, the grey ramp, the off-scale spacing receipts, the duplicate-component receipts with clickable file paths, and the worst-offenders ledger

package/bin/roast.mjs

@@ -65,6 +65,10 @@ Usage: npx roast-my-design-system [path] [options]
                   scanning: findings annotated on files in the Security tab
   --by <name>     put a requester credit in the report header, next to the
                   scan date ("commissioned by <name>")
+  --notes <file>  embed an agent-written analysis (markdown-lite) in the
+                  report as "What the numbers mean", labelled as written by
+                  AI and kept apart from the measured numbers. The Claude
+                  Code skill writes and passes this automatically
   --exclude <p>   leave a folder out of the scan (repo-relative, e.g.
                   --exclude lab/ --exclude piglet/ or --exclude lab/,piglet/;
                   same as listing it in a .roastignore file at the repo root).
@@ -113,6 +117,7 @@ const asJson = flag('json') === true;
 const noOpen = flag('no-open') === true || asJson;
 const theme = opt('theme', 'dark');
 const commissionedBy = opt('by', null);
+const notesFile = opt('notes', null);
 const excludes = optAll('exclude');
 const target = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());
 if (!existsSync(target) || !statSync(target).isDirectory()) {
@@ -143,7 +148,8 @@ run('harvest/index.mjs', [target, '--out', harvestPath,
   ...excludes.flatMap((e) => ['--exclude', e])], { ROAST_EPHEMERAL_OUT: '1' });
 say('');
 run('diagnose/index.mjs', [harvestPath, '--out', outPath, '--theme', theme, '--summary', summaryPath,
-  ...(commissionedBy ? ['--by', commissionedBy] : [])]);
+  ...(commissionedBy ? ['--by', commissionedBy] : []),
+  ...(notesFile ? ['--notes', resolve(notesFile)] : [])]);
 
 // The verdict leads, the evidence follows: harvest details print here, after
 // the diagnosis, rendered from harvest.json via the same lines the direct

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 34 public repos, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [
     "design-system",

package/skills/roast-my-design-system/scripts/diagnose/index.mjs

@@ -6,6 +6,13 @@
  *
  *   node src/diagnose/index.mjs harvest.json [--out diagnosis.html] [--theme dark|light]
  *   (--theme sets the initial mode; the page itself has a light/dark toggle)
+ *
+ *   --notes <file.md> embeds an agent-written analysis ("What the numbers
+ *   mean") between the verdict and the punch list, clearly labelled as
+ *   written-by-AI so it never reads as part of the measurement. The file is
+ *   markdown-lite: paragraphs, **bold**, `code`, and "- " lists. Reruns of
+ *   this script (e.g. --by credit) must pass --notes again or the section
+ *   is gone — which is why a missing notes file is a hard error, not a skip.
  */
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { resolve, basename, join, dirname } from 'node:path';
@@ -116,6 +123,14 @@ const themeName = arg('theme', 'dark');
 // Requester credit ("commissioned by"): their name up top next to the scan
 // date; the generated-by authorship stays in the footer, never confused.
 const commissionedBy = arg('by', null);
+// Agent-written analysis to embed (see the header comment). Read eagerly so
+// a bad path fails the run instead of silently shipping a report without it.
+const notesPath = arg('notes', null);
+let notesText = null;
+if (notesPath) {
+  try { notesText = readFileSync(resolve(notesPath), 'utf8').trim() || null; }
+  catch { console.error(`--notes: cannot read ${notesPath}`); process.exit(1); }
+}
 const T = THEMES[themeName];
 if (!T) { console.error(`Unknown theme "${themeName}" (dark | light)`); process.exit(1); }
 
@@ -694,6 +709,35 @@ function giftSection() {
   </section>`;
 }
 
+// ---------- agent-written analysis (--notes) ----------
+// Markdown-lite renderer: escape everything first, then allow exactly
+// **bold**, `code` and "- " bullet lists. No raw HTML ever passes through,
+// so a hostile notes file cannot inject into the report.
+function notesInline(s) {
+  return esc(s)
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/`([^`]+)`/g, '<span class="mono">$1</span>');
+}
+function notesBody(md) {
+  return md.split(/\n\s*\n/).map((block) => {
+    const lines = block.trim().split('\n');
+    if (lines.every((l) => /^[-*] /.test(l.trim()))) {
+      return `<ul>${lines.map((l) => `<li>${notesInline(l.trim().slice(2))}</li>`).join('')}</ul>`;
+    }
+    return `<p>${notesInline(block.trim())}</p>`;
+  }).join('');
+}
+function notesSection() {
+  if (!notesText) return '';
+  return `<section class="glass pad notes-sec">
+    <div class="sec-head">
+      ${eyebrow(`Written by ${esc(arg('notes-author', 'Claude'))} from this scan · ${esc((h.harvestedAt ?? '').slice(0, 10))} · not part of the measurement`)}
+      <h2>What the numbers mean</h2>
+    </div>
+    <div class="notes-body">${notesBody(notesText)}</div>
+</section>`;
+}
+
 function whereToStartSection() {
   const c = [];
   if (agentFiles.length === 0) c.push({ score: 60, metric: null, title: 'Write the agent rules file',
@@ -958,6 +1002,14 @@ const html = `<!doctype html>
 
   .eyebrow { font:700 10.5px/1.4 var(--sans); letter-spacing:.16em; text-transform:uppercase; color:var(--dim); }
   .sec-head h2 { font:600 19px/1.3 var(--disp); letter-spacing:-.01em; }
+  /* agent-written analysis (--notes): same glass, but an accent spine and a
+     written-by label keep prose visibly apart from measurement */
+  .notes-sec { border-left:3px solid var(--accent); }
+  .notes-sec .sec-head .eyebrow { margin-bottom:6px; }
+  .notes-body { display:flex; flex-direction:column; gap:14px; margin-top:10px;
+    font-size:15px; line-height:1.65; color:var(--text); }
+  .notes-body ul { margin:0; padding-left:20px; display:flex; flex-direction:column; gap:6px; }
+  .notes-body .mono { font-family:var(--mono); font-size:.92em; }
   .sec-head .sub { margin-top:3px; }
   .sub { color:var(--dim); font-size:13.5px; }
   .h3d { font:600 16px/1.3 var(--disp); letter-spacing:-.01em; margin-top:3px; }
@@ -1258,6 +1310,8 @@ const html = `<!doctype html>
   </div>
 </header>
 
+${notesSection()}
+
 ${whereToStartSection()}
 
 ${giftSection()}
@@ -1341,6 +1395,7 @@ if (summaryPath) {
     repo: repoName,
     version: VERSION,
     ...(commissionedBy ? { commissionedBy } : {}),
+    ...(notesText ? { notesEmbedded: true } : {}),
     ...(h.exclusions ? { exclusions: h.exclusions } : {}),
     score: healthScore,
     noSystemLikely,

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

@@ -1,4 +1,4 @@
 // 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 = '5.0.2';
+export const VERSION = '5.1.0';