roast-my-design-system 9.1.0 → 9.1.2

package/README.md

@@ -63,9 +63,9 @@ This tool draws the map.
 
 ## What you get
 
-### Where agents will invent
+### Where will your agent have to guess?
 
-The places where the repo has no answer yet.
+The first thing the report says: the places where the repo has no answer yet, or "No gaps found".
 
 - the gap, in one line
 - the files that prove it
@@ -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 the verdict on what the agent will learn here, the Where agents will invent section, the What the repo teaches the agent analysis written by Claude, priced Fix what makes agents guess moves each with 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.1.0)
+![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 What the repo teaches the agent analysis written by Claude, priced Fix what makes agents guess moves each with 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.1.2)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](assets/report-light-hero.png?v=9.1.0)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.1.2)
 
 ## Why the numbers hold
 
@@ -348,7 +348,7 @@ You get the roast in chat plus `design-system-roast.html` at your repo root, a s
 - 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
 - a **Fix what makes agents guess** list: up to 3 moves derived from your repo's own numbers, each with a file-path receipt
-- a **Where agents will invent** section, first under the verdict: the gaps where the repo has no answer yet, with the files that prove each one and the move that closes it, or the honest empty state when none is found
+- **Where will your agent have to guess?** opens the report: the gaps where the repo has no answer yet, with the files that prove each one and the move that closes it, or "No gaps found"
 - **Give the agent the answers**: `design-system-rules.md` wrapped inside the report as a present. Unwrap, then copy or download the agent rules generated from your scan
 
 After the roast, the skill offers to write `design-system-rules.md` to disk and merge it into your CLAUDE.md, `.cursor/rules` or AGENTS.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.1.0",
+  "version": "9.1.2",
   "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

@@ -351,15 +351,23 @@ let verdict = noSystemLikely
     ? 'This repo is in good shape, and your agent has rules to read. Keep them in step with the code.'
     : 'This repo is in good shape. The gap is documentation: your agent still can\'t see the system.')
   : findings.slice(0, 3).join('. ') + '.';
-// The lead line answers the report's question before the measured verdict
-// does: does this repo give an agent something to copy, and where does it
-// not. A gap named here is one lib/gaps admitted after a fleet probe.
+// The lead line answers the report's first question, where will the agent
+// have to guess, before the measured verdict does. A repo with an answer gets
+// copied; a repo with no answer gets guessed at. A gap named here is one
+// lib/gaps admitted after a fleet probe; nothing else is called a gap. The
+// card never talks about the scan's reach: a reader came for a diagnosis,
+// not for the limits of the instrument (Greg, 28 Sep 2026).
 const gapLead = (noSystemLikely || fresh) ? '' : (() => {
   const gaps = h.gaps ?? [];
-  if (!gaps.length) return 'This repo gives an agent something to copy everywhere this scan can measure.';
-  const named = gaps.map((g) => g.title.charAt(0).toLowerCase() + g.title.slice(1));
-  return `Most of this repo gives an agent something to copy. ${gaps.length === 1 ? 'One gap remains' : `${gaps.length} gaps remain`}: ${esc(named.join('; '))}.`;
+  return gaps.length ? `${gaps.length} gap${gaps.length === 1 ? '' : 's'} found.` : 'No gaps found.';
 })();
+// Under the headline: the condition, and nothing about the scan's reach.
+// What the fixes do to the score is said once, in the fixes section.
+function gapSub() {
+  return (h.gaps ?? []).length
+    ? 'The agent has no clear answer for these parts of the system.'
+    : 'Your repo gives the agent a clear answer for every check in this scan.';
+}
 if (bench && findings.length && !fresh) {
   const core = [['colors', tokenLed ? colorStrays : colors.length], ['greys', tokenLed ? greyStrays : greys.length],
     ['spacing', spacingTotal], ['typefaces', typefaces.length], ['exactDuplicates', hardDupes.length], ['inlineStyles', inline.count]];
@@ -1213,9 +1221,9 @@ function whereToStartSection() {
   for (const item of top3) if (item.metric && item.after !== undefined && item.delta > 0) applied.set(item.metric, item.after);
   const after = projectedScore(applied);
   startProjection = { count: top3.length, after };
-  const words = ['One tweak', 'Two tweaks', 'Three tweaks'][top3.length - 1];
+  const words = ['One fix', 'Two fixes', 'Three fixes'][top3.length - 1];
   const head = healthScore !== null && after > healthScore
-    ? `${words} · <b class="proj">${healthScore} &rarr; ${after}</b>`
+    ? `${words} could raise the design system health score from <b class="proj">${healthScore} to ${after}</b>.`
     : `${words} to increase your score.`;
   const chip = (item) => item.delta > 0
     ? `<span class="delta" title="once all of them are done">+${item.delta}</span>`
@@ -1257,24 +1265,17 @@ function whereToStartSection() {
 // A gap is a place where the next piece of UI has nothing to reuse (lib/gaps).
 // The September 2026 runs showed agents inventing exactly there; the section
 // names the gap, the files that prove it and the one move that closes it.
-function gapsSection() {
+function gapsList() {
   if (noSystemLikely || fresh) return '';
   const gaps = h.gaps ?? [];
-  if (!gaps.length) {
-    return `<section class="glass pad" style="margin-top:16px">
-    ${sectionHead('Where agents will invent', 'No gap found. This scan checks for one kind of gap so far, a chart palette, and this repo either has one or has no charts. The list grows as more gap kinds are measured on real agent runs; a clean result here says the known gaps are closed, and no more than that.')}
-</section>`;
-  }
-  const head = `${gaps.length === 1 ? 'One place' : `${gaps.length} places`} where this repo gives an agent nothing to copy. Asked to build there, an agent invents, because that is what the repo taught it. Nothing here is a violation: there is no rule yet to break. Define the answer once and every agent after that inherits it.`;
-  return `<section class="glass pad" style="margin-top:16px">
-    ${sectionHead('Where agents will invent', head)}
-    <div class="ledger">${gaps.map((g, i) => `
+  if (!gaps.length) return '';
+  return `<div class="ledger gaps-list">${gaps.map((g, i) => `
       <div class="ledger-row gap-row">
         <span class="ledger-idx">${String(i + 1).padStart(2, '0')}</span>
         <div class="start-body"><div class="start-head"><div class="start-title">${esc(g.title)}</div></div><div class="sub">${esc(g.detail)}</div>
         <div class="sub" style="margin-top:6px"><b>Close it:</b> ${esc(g.fix)}</div>
         ${g.files?.length ? `<div class="chips-row" style="margin-top:8px">${g.files.map((f) => `<span class="chip mono">${esc(f)}</span>`).join('')}</div>` : ''}</div>
-      </div>`).join('')}</div></section>`;
+      </div>`).join('')}</div>`;
 }
 
 // ---------- package by package ----------
@@ -1560,16 +1561,16 @@ function ogTags() {
 // index of what rendered, and what is not the team's and not counted.
 function sidePanel() {
   const date = esc((h.harvestedAt ?? '').slice(0, 10));
-  const def = 'How safely an AI agent can build on this repo without going off-system.';
+  const def = 'How well this repo follows the design system rules Roast checks.';
   const lift = startProjection && healthScore !== null && startProjection.after > healthScore
-    ? ` <b>${['One fix lifts', 'Two fixes lift', 'Three fixes lift'][startProjection.count - 1] ?? 'The fixes lift'} it to ${startProjection.after}.</b>` : '';
+    ? ` <b>${['One fix', 'Two fixes', 'Three fixes'][startProjection.count - 1] ?? 'The fixes'} could raise it to ${startProjection.after}.</b>` : '';
   const rp = P.shadcn?.registryPaint ?? null;
   const bd = breakdown.ownScore !== null && breakdown.installedPoints > 0 && rp
     ? `<div class="bd">Of which <b>${breakdown.installedPoints} point${breakdown.installedPoints === 1 ? '' : 's'}</b> come from installed code you did not write: ${esc(rp.dirs.map((d) => basename(d)).join(', '))} (${n(rp.files)} file${rp.files === 1 ? '' : 's'}, ${n(rp.tinUses)} palette colour${rp.tinUses === 1 ? '' : 's'}). Your own code alone would score <b>${breakdown.ownScore}</b>. Kept in the score because your agent reads those files like everything else; left out of the fixes because they are not yours to edit.</div>` : '';
   const scoreBlock = healthScore !== null
-    ? `<div class="score">${eyebrow('Health score')}<div class="val">${healthScore}<span class="slash">/</span><span class="of">100</span></div><div class="def">${def}${lift}</div>${bd}</div>`
+    ? `<div class="score">${eyebrow('Design system health')}<div class="val">${healthScore}<span class="slash">/</span><span class="of">100</span></div><div class="def">${def}${lift}</div>${bd}</div>`
     : noSystemLikely
-    ? `<div class="score muted">${eyebrow('Health score')}<div class="val">&mdash;</div><div class="note">nothing here was measured · see the note</div><div class="def">${def}</div></div>` : '';
+    ? `<div class="score muted">${eyebrow('Design system health')}<div class="val">&mdash;</div><div class="note">nothing here was measured · see the note</div><div class="def">${def}</div></div>` : '';
   const chips = `<div class="chips">${stack.map((c) => `<span class="chip">${esc(c)}</span>`).join('')}${(P.shadcn?.sheet?.tweakcnPresent ?? 0) >= 10 ? '<span class="chip">tweakcn theme</span>' : ''}${P.shadcn?.lint ? '<span class="chip">shadcn/lint</span>' : ''}${dsUnrecognised ? '<span class="chip chip-dim">design system: unrecognised</span>' : ''}${legacyChip ? `<span class="chip chip-dim">${esc(legacyChip)}</span>` : ''}${agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)}</span>`).join('')}</div>`;
   const facts = [
     shadcnReceipt(),
@@ -1787,6 +1788,7 @@ ${ogTags()}
   .verdict-card .b2 { left:-40px; bottom:-80px; width:224px; height:224px; background:var(--blob2); filter:blur(48px); }
   .verdict { position:relative; font:600 clamp(18px,2.6vw,24px)/1.45 var(--disp); letter-spacing:-.01em; margin-top:10px; }
   .verdict-sub { position:relative; margin-top:12px; font-size:14.5px; line-height:1.6; color:var(--dim); }
+  .verdict-card .gaps-list { position:relative; margin-top:18px; }
   .gap-empty { padding:0 26px 22px; color:var(--dim); font-size:14px; line-height:1.6; }
   .gap-why { margin-top:6px; color:var(--dim); font-size:13.5px; }
 
@@ -2110,12 +2112,10 @@ ${sidePanel()}
     : `There is most likely <b>no design system in this repo</b>: almost no colour or spacing values were found. Styling may live outside this codebase (CDN stylesheets, a parent repo, or generated output). No score is given.`}</span></div>` : ''}
   <div class="glass verdict-card">
     <div class="blob b1"></div><div class="blob b2"></div>
-    ${eyebrow(noSystemLikely || fresh ? 'Summary' : 'What will your agent learn here?')}
-    ${gapLead ? `<div class="verdict">${gapLead}</div><div class="verdict-sub">${esc(verdict)}</div>` : `<div class="verdict">${esc(verdict)}</div>`}
+    ${eyebrow(noSystemLikely || fresh ? 'Summary' : 'Where will your agent have to guess?')}
+    ${gapLead ? `<div class="verdict">${gapLead}</div><div class="verdict-sub">${gapSub()}</div>${gapsList()}` : `<div class="verdict">${esc(verdict)}</div>`}
   </div>
 
-${gapsSection()}
-
 ${notesSection()}
 
 ${extraSectionsHtml()}

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.1.0';
+export const VERSION = '9.1.2';
 // 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.