roast-my-design-system 9.2.0 → 9.2.2

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.1.** Version history in [CHANGELOG.md](CHANGELOG.md).
+**Current release: 9.2.** Version history in [CHANGELOG.md](CHANGELOG.md).
 
 ## The idea
 
@@ -73,7 +73,7 @@ The first thing the report says: the places where the repo has no answer yet, or
 
 One gap is known for certain today, because the runs found it: charts hardcoding colours in a repo with no chart palette. 43 of 126 public repos look like that. A gap joins the list when it has been measured.
 
-### Fix what makes agents guess
+### Fixes you can make right now to increase the health score
 
 The mess the agent will copy, ranked by what fixing it is worth.
 
@@ -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 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 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.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.2)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.2.2)
 
 ## Why the numbers hold
 
@@ -347,7 +347,7 @@ You get the roast in chat plus `design-system-roast.html` at your repo root, a s
 - stat tiles comparing you to all 3 yardsticks
 - 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 **Fixes you can make right now to increase the health score** list: up to 3 moves derived from your repo's own numbers, each with a file-path receipt
 - **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
 

package/package.json

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

@@ -1201,17 +1201,22 @@ function whereToStartSection() {
   }
 
   // What each move is actually worth, then rank by payoff for real.
+  // A move with no points says why, so the list never promises what the
+  // score cannot give: the thing it fixes is not scored, or its tile is
+  // already green, or the move lands inside the band it started in.
   for (const item of c) {
-    item.delta = 0; item.target = null;
+    item.delta = 0; item.target = null; item.why = 'not part of the score';
     if (!item.metric) continue;
-    const now = bigStats.find((st) => st.metric === item.metric)?.healthValue;
-    if (now === undefined) continue;
+    const tile = bigStats.find((st) => st.metric === item.metric);
+    const now = tile?.healthValue;
+    if (now === undefined || !(tile.health in SCORE_OF)) continue;
     if (item.after !== undefined) {
       const gain = bandPoints(item.metric, now, item.after);
       if (gain > 0) { item.delta = gain; continue; }
     }
     const nb = nextBand(item.metric, now);
     if (nb && nb.gain > 0) item.target = nb;
+    else item.why = healthOf(item.metric, now) === 'good' ? 'already green' : 'no points on its own';
   }
   const top3 = c.sort((a, b) => (b.delta - a.delta) || (b.score - a.score)).slice(0, 3);
   if (!top3.length) return '';
@@ -1220,16 +1225,32 @@ function whereToStartSection() {
   const applied = new Map();
   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 fix', 'Two fixes', 'Three fixes'][top3.length - 1];
-  const head = healthScore !== null && after > healthScore
-    ? `${words} could raise the design system health score from <b class="proj">${healthScore} to ${after}</b>.`
-    : `${words} to increase your score.`;
+  // The line under the heading counts only the moves that pay, and says what
+  // the others are. "Three fixes to increase your score" stood over a list
+  // where 1 of the 3 could, by 4 points (shadcn-admin, 2026-09-29).
+  const paying = healthScore !== null && after > healthScore ? top3.filter((item) => item.delta > 0) : [];
+  const later = top3.filter((item) => !paying.includes(item) && item.target);
+  startProjection = { count: paying.length, after };
+  const COUNT = ['one', 'two', 'three'];
+  const cap = (s) => s[0].toUpperCase() + s.slice(1);
+  const total = top3.length;
+  const none = total - paying.length - later.length;
+  const ofThese = (k) => (k === total
+    ? `${cap(COUNT[k - 1])} ${k === 1 ? 'fix' : 'fixes'}`
+    : `${cap(COUNT[k - 1])} of these ${COUNT[total - 1]} fixes`);
+  const inFull = (k) => `once ${k === 1 ? 'it is' : 'they are'} done in full`;
+  const rest = none ? ` The remaining ${none === 1 ? 'one does' : `${COUNT[none - 1]} do`} not move the score.` : '';
+  const head = paying.length
+    ? `${ofThese(paying.length)} could raise the design system health score from <b class="proj">${healthScore} to ${after}</b>.${later.length ? ` ${cap(COUNT[later.length - 1])} more ${later.length === 1 ? 'pays' : 'pay'} ${inFull(later.length)}.` : ''}${rest}`
+    : later.length
+      ? `${ofThese(later.length)} ${later.length === 1 ? `raises the score, by ${later[0].target.gain},` : 'raise the score'} ${inFull(later.length)}.${rest}`
+      : `${total === 1 ? 'It does' : 'They do'} not move the score. ${total === 1 ? 'It is' : 'They are'} here because ${total === 1 ? 'it stops' : 'each one stops'} the agent guessing.`;
+  const title = paying.length || later.length ? 'Fixes you can make right now to increase the health score' : 'Fixes you can make right now';
   const chip = (item) => item.delta > 0
     ? `<span class="delta" title="once all of them are done">+${item.delta}</span>`
     : item.target
       ? `<span class="delta delta-target">${item.target.target === 0 ? 'clear them all' : `under ${n(item.target.target)}`} · +${item.target.gain}</span>`
-      : '';
+      : `<span class="delta delta-none">${item.why}</span>`;
   // The copy button beside each move hands the finding to whatever agent the
   // reader pastes it into: one move per prompt, so progress stays visible and
   // finishable. Prompt text is composed from the same title/sub the row shows
@@ -1251,7 +1272,7 @@ function whereToStartSection() {
     delta: item.delta || 0, prompt: promptFor(item),
   }));
   return `<section class="glass pad">
-    ${sectionHead('Fix what makes agents guess', head)}
+    ${sectionHead(title, head)}
     <div class="ledger">${top3.map((item, i) => `
       <div class="ledger-row start-row">
         <span class="ledger-idx">${String(i + 1).padStart(2, '0')}</span>
@@ -1651,7 +1672,7 @@ function exceptionsBlock() {
 function addIndex(page) {
   // heading text is already HTML-escaped; strip tags and leading counts only
   const short = (t) => t.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim().replace(/^[\d,]+ /, '')
-    .replace(/^What your AI agent sees today$/, 'What your agent sees').replace(/^Give the agent the answers$/, 'Agent rules').replace(/^What the repo teaches the agent$/, 'What it teaches').replace(/^Fix what makes agents guess$/, 'What to fix')
+    .replace(/^What your AI agent sees today$/, 'What your agent sees').replace(/^Give the agent the answers$/, 'Agent rules').replace(/^What the repo teaches the agent$/, 'What it teaches').replace(/^Fixes you can make right now( to increase the health score)?$/, 'What to fix')
     .replace(/^The shadcn theme and the 2 shadcn checks$/, 'shadcn theme and checks')
     .replace(/^Your Tailwind theme, and what goes around it$/, 'Your Tailwind theme').replace(/^Your (\w+) theme, and what is written around it$/, 'Your $1 theme').replace(/, declared .*$/, '')
     .replace(/^off-scale spacing values$/, 'Off-scale spacing').replace(/^inline style blocks?$/, 'Inline styles').replace(/^typefaces?$/, 'Typefaces');
@@ -2047,6 +2068,7 @@ ${ogTags()}
   .delta { font:700 11px/1 var(--sans); letter-spacing:.04em; padding:5px 9px; border-radius:99px;
     background:var(--ok-soft); color:var(--ok); white-space:nowrap; }
   .delta-target { background:var(--amber-soft); color:var(--amber); font-weight:600; }
+  .delta-none { background:transparent; box-shadow:inset 0 0 0 1px var(--line-soft); color:var(--dim); font-weight:500; letter-spacing:0; }
   .proj { color:var(--accent); font-weight:700; }
   .ndot { display:inline-block; width:9px; height:9px; border-radius:3px; margin-right:4px; vertical-align:-1px; box-shadow:inset 0 0 0 1px var(--cell-ring); }
   .nsim { color:var(--dim2); font-weight:400; padding:0 2px; }

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

@@ -158,7 +158,10 @@ export function definedComponents(src) {
   return [...names];
 }
 
-const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
+// A file with no markup defines no component the report can count: a stub
+// returning null, a wrapper built with a factory call. Asked by the harvest
+// and by the live checks, so both read the same files as component files.
+export const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
 
 // ---------- web components: the tag-registered world ----------
 // Stencil, Lit and raw customElements.define register components by TAG, and
@@ -241,6 +244,28 @@ function importedDef(src, file, name, defs, workspaces = [], aliases = []) {
   return null;
 }
 
+const JSX_FILE_RE = /\.(tsx|jsx|js)$/;
+
+/**
+ * Every component a file defines, by either door the harvest reads: a React
+ * component in a file with markup in it, and a web component registered by
+ * tag (Stencil, Lit, customElements.define), generated bindings left out.
+ * The live checks ask here, so a file defines for them what it defines for
+ * the report.
+ */
+export function componentNamesIn(src, file = null) {
+  // .js too, never .ts: a TypeScript generic reads like a tag, and the
+  // harvest takes React components from the same three extensions
+  const react = (!file || JSX_FILE_RE.test(file)) && looksLikeJSXFile(src) ? definedComponents(src) : [];
+  const web = GENERATED_RE.test(src.slice(0, 2000)) ? [] : webComponentDefs(src).map((d) => d.name);
+  return [...new Set([...react, ...web])];
+}
+
+// A page is a route, not a reusable part. Asked by the harvest for every file
+// it reads and by the live checks for the one file under review.
+export const isPageFile = (file) => /(^|\/)(app\/.*page|pages\/(?!_app|_document|api))/.test(file)
+  || /(^|\/)app\/.*\/(layout|template|error|loading)\.(tsx|jsx)$/.test(file);
+
 /**
  * Harvest all components: definitions (with variants/props) + usages across the
  * repo. `codeFiles` are relative paths; returns { components, totalDefined }.
@@ -248,7 +273,7 @@ function importedDef(src, file, name, defs, workspaces = [], aliases = []) {
 export function harvestComponents(root, codeFiles) {
   // .js too — CRA-era repos (a big slice of the messy-repo audience) put JSX in
   // plain .js files; requiring .tsx/.jsx made whole repos read as empty.
-  const jsxFiles = codeFiles.filter((f) => /\.(tsx|jsx|js)$/.test(f));
+  const jsxFiles = codeFiles.filter((f) => JSX_FILE_RE.test(f));
   const sources = new Map();
   for (const f of jsxFiles) {
     const src = readSource(join(root, f));
@@ -259,8 +284,7 @@ export function harvestComponents(root, codeFiles) {
   const components = [];
   for (const [file, src] of sources) {
     if (!looksLikeJSXFile(src)) continue;
-    const isPage = /(^|\/)(app\/.*page|pages\/(?!_app|_document|api))/.test(file)
-      || /(^|\/)app\/.*\/(layout|template|error|loading)\.(tsx|jsx)$/.test(file);
+    const isPage = isPageFile(file);
     for (const name of definedComponents(src)) {
       components.push({
         name,

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

@@ -54,8 +54,59 @@ const ROUTE_FRAGMENT_RE = /(^|\/)app\/.*\/(form|header|footer|nav|page|layout|lo
 // and _dashboard.analytics.tsx both export Page, 2026-09-17). A story is a
 // demo of a component, not a second implementation of it (medplum keeps a
 // MockDateWrapper in two stories folders).
-const ROUTE_FILE_RE = /(^|\/)routes\/[^/]+\.[jt]sx?$|(^|\/)(page|layout|route|loading|error|not-found|template|default)\.[jt]sx?$/;
+// Next.js's crash page is one more of these: every app in a monorepo has its
+// own global-error, and a starter keeps a second one in its templates folder
+// (9.2.1).
+const ROUTE_FILE_RE = /(^|\/)routes\/[^/]+\.[jt]sx?$|(^|\/)(page|layout|route|loading|error|global-error|not-found|template|default)\.[jt]sx?$/;
 const STORY_FILE_RE = /(^|\/)(stories|__stories__|\.storybook)\/|\.stories\.[jt]sx?$/;
+// Email templates legitimately mirror web component names (email Footer !=
+// web Footer); cross-matching them manufactures duplicates. An email folder
+// or file is one whose name carries "email" as a word of its own: emails/,
+// email-templates/, twenty-emails/, welcome-email.tsx. A screen about email
+// (ConfirmUserEmail, EmailInput) is interface and stays in (9.2.1: the rule
+// asked for the word at the start of the name and missed twenty-emails/).
+const EMAIL_PATH_RE = /(^|\/)(?:[a-z0-9]+[-_.])*emails?(?:[-_][a-z0-9]+)*(?:\/|\.[jt]sx?$)/i;
+// Same-name components living in different icons/ directories are ONE
+// problem — two icon libraries colliding — not N separate duplicates.
+const ICON_DIR_RE = /(^|\/)icons?\//i;
+
+/**
+ * Whether a definition can be a duplicate at all. The report's finder and the
+ * live checks both ask here, so a name the report lets repeat by design is
+ * never a finding on the file an agent just wrote (9.2.1: every TanStack
+ * route file was told its Route already existed in 40 places).
+ */
+export function canBeDuplicate({ name, file = '', isPage = false }) {
+  return !isPage && !NOT_DUPLICATES.has(name)
+    && !ROUTE_FRAGMENT_RE.test(file) && !ROUTE_FILE_RE.test(file)
+    && !STORY_FILE_RE.test(file) && !EMAIL_PATH_RE.test(file);
+}
+
+/**
+ * The other copies that make one definition a duplicate, or none. The live
+ * checks and the guard ask here, so their answer is the report's answer.
+ *
+ * A file the scan has read is settled by the report: the definition is a
+ * duplicate when the report counts the name and this file is one of the
+ * copies it counts. A wrapper, shadcn's own overlap inside the catalogue and
+ * two icon libraries colliding are listed by the report and never counted,
+ * so they are not findings on the file either. A file the scan has not read
+ * (content validated before it is saved) is judged on the copies that exist.
+ *
+ * @param def     { name, file, isPage } the definition under review
+ * @param copies  the ledger's entries for the name: [{ file, isPage, usageCount }]
+ * @param counted the files of the duplicate the report counts under the name,
+ *                or null when it counts none
+ * @param same    how two paths are compared (a guard matches on path tails)
+ */
+export function duplicateCopies({ name, file = '', isPage = false }, copies, counted = null, same = (a, b) => a === b) {
+  if (!canBeDuplicate({ name, file, isPage })) return [];
+  const others = (copies ?? []).filter((c) => !same(c.file, file) && canBeDuplicate({ ...c, name }));
+  if (!others.length) return [];
+  if ((copies ?? []).some((c) => same(c.file, file))) return (counted ?? []).some((f) => same(f, file)) ? others : [];
+  if (ICON_DIR_RE.test(file) && others.every((c) => ICON_DIR_RE.test(c.file))) return [];
+  return others;
+}
 
 /**
  * @param components output of harvestComponents (non-page components matter most)
@@ -66,12 +117,7 @@ const STORY_FILE_RE = /(^|\/)(stories|__stories__|\.storybook)\/|\.stories\.[jt]
  */
 export function findDuplicates(components, uiDir = null, root = null, uiDirs = null) {
   const catalogueDirs = uiDirs ?? (uiDir ? [uiDir] : []);
-  // Email templates legitimately mirror web component names (email Footer !=
-  // web Footer); cross-matching them manufactures duplicates.
-  const EMAIL_PATH_RE = /(^|\/)emails?(\/|-)/i;
-  const comps = components.filter((c) => !c.isPage && !NOT_DUPLICATES.has(c.name)
-    && !ROUTE_FRAGMENT_RE.test(c.file) && !ROUTE_FILE_RE.test(c.file)
-    && !STORY_FILE_RE.test(c.file) && !EMAIL_PATH_RE.test(c.file));
+  const comps = components.filter(canBeDuplicate);
 
   // 1. exact same component name defined in >1 file
   const byName = new Map();
@@ -88,9 +134,6 @@ export function findDuplicates(components, uiDir = null, root = null, uiDirs = n
     }))
     .sort((a, b) => b.files.length - a.files.length);
 
-  // Same-name components living in different icons/ directories are ONE
-  // problem — two icon libraries colliding — not N separate duplicates.
-  const ICON_DIR_RE = /(^|\/)icons?\//i;
   const iconCollisions = exactDuplicates.filter((d) => d.files.every((f) => ICON_DIR_RE.test(f)));
   exactDuplicates = exactDuplicates.filter((d) => !iconCollisions.includes(d));
 

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

@@ -35,6 +35,21 @@ export { extractStyling, normalizeHex, isGrey, hexRgb, typefaceOf, GENERIC_FONTS
 // The components a piece of text defines. With the ledger below, a guard can
 // tell a second <Button> from an edit to the first one.
 export { definedComponents };
+// Duplicates, by the report's own answer (9.2.1). duplicateCopies(def,
+// copies, counted, same) returns the other copies that make one definition a
+// duplicate, or none: `copies` is the ledger's entries for the name
+// (learnSystem's components), `counted` the files of the duplicate the report
+// counts under it (the copies in learnSystem's duplicates), `same` how two
+// paths compare. canBeDuplicate({ name, file, isPage }) is the first question
+// it asks: a framework's Route, a page, a route file, the crash page, a story
+// and an email template repeat by design. isPageFile(file) answers isPage for
+// a file not in the ledger. componentNamesIn(text, file) lists what a whole
+// file defines for the report: React components in a .tsx, .jsx or .js file
+// with markup in it, and web components registered by tag. The exemptions
+// (exemptReason) are about styling, so a duplicate is still a duplicate in
+// an exempt file.
+export { canBeDuplicate, duplicateCopies } from '../harvest/duplicates.mjs';
+export { isPageFile, looksLikeJSXFile, componentNamesIn } from '../harvest/components.mjs';
 
 // The files no checker should judge. Exported so a guard reads the same list
 // as the engine rather than keeping a copy that drifts.
@@ -115,7 +130,7 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
   // the same two lists the MCP knowledge builds (mcp/knowledge.mjs), from the
   // same helpers, for tokenTwinFindings and avoidedImportFindings (8.6.1)
   const read = (f) => readSource(join(repoRoot, f));
-  const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot).exactDuplicates ?? []).filter((d) => !d.wrapped);
+  const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot, profile.uiDirs ?? null).exactDuplicates ?? []).filter((d) => !d.wrapped);
   const P = profileOf(profile);
   const installedNow = installedDirs(P);
   const charts = chartSystemOf(files, read, { own: (f) => !installedNow.some((d) => f === d || f.startsWith(`${d}/`)) });

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.0';
+export const VERSION = '9.2.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.

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

@@ -11,7 +11,8 @@
  *    in the repo means saying so, not inventing one.
  */
 import { extractStyling } from '../harvest/tokens.mjs';
-import { definedComponents } from '../harvest/components.mjs';
+import { componentNamesIn, isPageFile } from '../harvest/components.mjs';
+import { duplicateCopies } from '../harvest/duplicates.mjs';
 import { hexRgb } from '../lib/nearpairs.mjs';
 import { exemptReason } from '../lib/exempt.mjs';
 import { extraDeclarations, fontDeclarations } from '../lib/declarations.mjs';
@@ -83,6 +84,29 @@ function nearestToken(value, k) {
   return best;
 }
 
+/**
+ * The report's answer on duplicates, asked of one file: a name that repeats
+ * by design, a pair the report lists without counting and a file that
+ * defines nothing the report reads are not duplicates here either
+ * (harvest/duplicates.mjs).
+ */
+function duplicateFindings({ text, file, k, add }) {
+  for (const name of componentNamesIn(text, file)) {
+    const dupe = k.dupeByName.get(name);
+    const counted = dupe ? dupe.files.map((f) => (typeof f === 'string' ? f : f.file)) : null;
+    const existing = duplicateCopies({ name, file: file ?? '', isPage: !!file && isPageFile(file) }, k.byName.get(name), counted);
+    if (!existing.length) continue;
+    // the scan may already include this very file — count the OTHER copies
+    const otherCopies = counted ? counted.filter((f) => f !== file) : null;
+    const best = [...existing].sort((a, b) => b.usageCount - a.usageCount)[0];
+    add('duplicate-component', 'violation', text.indexOf(name),
+      otherCopies && otherCopies.length > 1
+        ? `Defines <${name}>, which already exists in ${otherCopies.length} other places. This makes ${otherCopies.length + 1} competing copies, and every wrong pick becomes the example the next agent copies.`
+        : `Defines <${name}>, but ${best.file} already defines it${best.usageCount ? ` (used ${best.usageCount}x)` : ''}.`,
+      `Import ${best.file} instead of creating a copy.`);
+  }
+}
+
 /**
  * Validate one piece of content against the repo's knowledge.
  * @param content { text, file?, before? } — file name decides css-vs-code
@@ -91,7 +115,8 @@ function nearestToken(value, k) {
  *   unknown), so a token or an import the change ADDS can be told from one
  *   that was already there
  * @returns { findings: [{ rule, severity, line, message, fix? }], checked,
- *   exempt? } — exempt is a sentence saying why the file was not judged
+ *   exempt? } — exempt is a sentence saying why the file's styling was not
+ *   judged; its findings are then duplicates only, and checked says so
  */
 export function validateContent(content, k) {
   const { text, file = null, before } = content;
@@ -99,13 +124,20 @@ export function validateContent(content, k) {
   // checker earns its reputation for crying wolf, and a checker people
   // distrust gets switched off. Say nothing, and say why nothing was said.
   const exempt = exemptReason(file, text);
-  if (exempt) return { findings: [], checked: checksFor(k), exempt };
   const css = file ? CSS_FILE_RE.test(file) : looksLikeCss(text);
-  const got = extractStyling(text, { css });
   const findings = [];
   const add = (rule, severity, index, message, fix) => findings.push({
     rule, severity, line: lineOf(text, index), message, ...(fix ? { fix } : {}),
   });
+  // The exemption is about styling: what an email, a drawing or a crash page
+  // cannot take from the system. A second copy of a component is a second
+  // copy in any medium, and the report counts it, so that one check still
+  // runs and the result says it was the only one.
+  if (exempt) {
+    if (!css) duplicateFindings({ text, file, k, add });
+    return { findings, checked: css ? [] : ['duplicate component definitions'], exempt };
+  }
+  const got = extractStyling(text, { css });
 
   // The knowledge scan includes the working tree, so a file under review has
   // already leaked its own values into the repo counts — without a discount,
@@ -258,9 +290,13 @@ export function validateContent(content, k) {
     // a raw value the repo already uses, in a non-Tailwind repo, is consistency,
     // not a new offence — silence
   }
+  // Bracket values inside installed code (the shadcn catalogue, kit blocks,
+  // registries) are the kit's own choices. The report names them and keeps
+  // them out of the count; a file under review is judged by the same line.
+  const installed = !!file && (k.installedDirs ?? []).some((d) => file === d || file.startsWith(`${d}/`));
   const localArb = new Map();
   for (const a of got.arbitrary) localArb.set(a.value, (localArb.get(a.value) ?? 0) + 1);
-  for (const a of got.arbitrary) {
+  for (const a of installed ? [] : got.arbitrary) {
     const repoArb = (k.tokens.tailwind?.arbitrary ?? []).find((x) => x.value === a.value);
     const priorArb = discount(repoArb?.count, localArb, a.value);
     add('arbitrary-value', 'violation', a.index,
@@ -345,23 +381,7 @@ export function validateContent(content, k) {
   }
 
   // ---------- duplicate components ----------
-  if (!css) {
-    for (const name of definedComponents(text)) {
-      const existing = (k.byName.get(name) ?? []).filter((c) => !file || c.file !== file);
-      if (!existing.length) continue;
-      const dupe = k.dupeByName.get(name);
-      // the scan may already include this very file — count the OTHER copies
-      const otherCopies = dupe
-        ? dupe.files.map((f) => (typeof f === 'string' ? f : f.file)).filter((f) => f !== file)
-        : null;
-      const best = [...existing].sort((a, b) => b.usageCount - a.usageCount)[0];
-      add('duplicate-component', 'violation', text.indexOf(name),
-        otherCopies && otherCopies.length > 1
-          ? `Defines <${name}>, which already exists in ${otherCopies.length} other places. This makes ${otherCopies.length + 1} competing copies, and every wrong pick becomes the example the next agent copies.`
-          : `Defines <${name}>, but ${best.file} already defines it${best.usageCount ? ` (used ${best.usageCount}x)` : ''}.`,
-        `Import ${best.file} instead of creating a copy.`);
-    }
-  }
+  if (!css) duplicateFindings({ text, file, k, add });
 
   // ---------- an import of the copy the canon replaces ----------
   if (!css) {

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

@@ -114,7 +114,8 @@ function judge(real, root, k, warned = new Set()) {
   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;
+  // an exempt file is judged on duplicates only; with none, there is nothing to say
+  if (!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
@@ -129,5 +130,5 @@ function judge(real, root, k, warned = new Set()) {
     return true;
   });
   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 };
+  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 };
 }

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

@@ -74,7 +74,10 @@ export function loadKnowledge(root) {
     // same shape as a harvested colour, so every reader of `files` keeps working
     for (const v of themeSet) if (!tokens.colors.some((c) => c.value === v)) tokens.colors.push({ value: v, count: 1, files: [{ file: kit.themeFiles[0] ?? '', count: 1 }], isToken: true });
   }
-  const duplicates = findDuplicates(components, profile.uiDir, root);
+  // every catalogue folder, as the report passes them (harvest/index.mjs): a
+  // monorepo with two installs has two, and shadcn's own overlap in the
+  // second is no more the team's than in the first
+  const duplicates = findDuplicates(components, profile.uiDir, root, profile.uiDirs ?? null);
   const context = harvestContext(root);
   const workspaces = resolveWorkspaces(root);
 
@@ -196,6 +199,10 @@ export function loadKnowledge(root) {
     neverImported,
     // stock, not debt: see profiles/index.mjs
     vendoredUi: P.vendoredUi,
+    // folders the team did not write, by the same line the guard doorway
+    // draws (lib/guard-api.mjs): only a shadcn kit has installed code, and a
+    // registry's published folders are its own work
+    installedDirs: P.isShadcn && !P.isRegistry ? installed : [],
     // the kit the product is built on, and the Tailwind theme it names its
     // colours in: null when the repo is neither (see profiles/)
     kit,

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

@@ -306,19 +306,22 @@ export function validate(k, { code, file = null } = {}) {
   if (file != null && typeof file !== 'string') return invalidInput('file is optional, but when sent it must be a repo-relative path as a string.');
   if (code.length > MAX_VALIDATE_CHARS) return invalidInput(`That is ${Math.round(code.length / 1000)}k characters; send the part you changed (up to ${MAX_VALIDATE_CHARS / 1000}k).`);
   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 (exempt && !findings.length) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
   if (!findings.length) return cleanResultText(k);
-  return findingLines(findings, k).join('\n');
+  return findingLines(findings, k, exempt).join('\n');
 }
 
 /** The finding list as roast_validate prints it; the edit hook prints the same. */
-export function findingLines(findings, k) {
+export function findingLines(findings, k, exempt = null) {
   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(', ')}.`);
+  // an exempt file is judged on one thing, and the reader is told which
+  L.push(exempt
+    ? `Checked: duplicate component definitions. The styling was not judged, because ${exempt}.`
+    : `Checked: ${checksFor(k).join(', ')}.`);
   return L;
 }
 
@@ -355,12 +358,12 @@ export function reviewData(k) {
     try { text = readFileSync(join(gitRoot, f), 'utf8'); } catch { continue; }
     // knowledge paths are scanned-root-relative; git paths are toplevel-relative
     const { findings, exempt } = validateContent({ text, file: relative(realRoot, join(gitRoot, f)), before: headVersion(gitRoot, f) }, k);
-    if (exempt) { exemptCount++; continue; }
+    if (exempt) exemptCount++;
     if (findings.length) { perFile.push({ f, findings }); total += findings.length; }
   }
   // Skipped is not the same as clean, and the reader is owed the difference.
   const exemptNote = exemptCount
-    ? ` ${exemptCount} file${exemptCount === 1 ? ' was' : 's were'} left unjudged: email, print, artwork or pictures drawn with code.`
+    ? ` The styling of ${exemptCount} file${exemptCount === 1 ? ' was' : 's were'} left unjudged: email, print, artwork or pictures drawn with code.`
     : '';
   if (!total) {
     return { text: `Reviewed ${changed.length} changed file${changed.length === 1 ? '' : 's'}. ${cleanResultText(k)}${exemptNote}`, total: 0 };