quiver-cli 0.7.0 → 1.0.0

package/template/.agents/skills/design/impeccable/scripts/critique-storage.mjs

@@ -2,11 +2,11 @@
 /**
  * Critique persistence helper.
  *
- * Each run of /impeccable critique writes a per-target snapshot to
+ * Each critique run writes a per-target snapshot to
  *   .impeccable/critique/<timestamp>__<slug>.md
  * with a small YAML frontmatter carrying the score + P0/P1 counts.
  *
- * /impeccable polish reads the latest matching snapshot at start as its
+ * The polish workflow reads the latest matching snapshot at start as its
  * fix backlog. No other skill auto-reads critique output.
  *
  * The slug is derived mechanically from the *resolved* primary artifact
@@ -29,8 +29,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { getCritiqueDir } from './lib/impeccable-paths.mjs';
+import { slugFromTarget } from './lib/target-slug.mjs';
 
-const SLUG_MAX = 50;
+export { slugFromTarget } from './lib/target-slug.mjs';
 
 /**
  * Mechanically derive a slug from a resolved target. Returns null if the
@@ -40,46 +41,6 @@ const SLUG_MAX = 50;
  * concrete artifact before calling this — we never slug a natural-language
  * phrase.
  */
-export function slugFromTarget(resolved, { cwd = process.cwd() } = {}) {
-  if (!resolved || typeof resolved !== 'string') return null;
-  const trimmed = resolved.trim();
-  if (!trimmed) return null;
-
-  // URL
-  if (/^https?:\/\//i.test(trimmed)) {
-    let url;
-    try { url = new URL(trimmed); } catch { return null; }
-    const hostPath = `${url.hostname}${url.pathname}`;
-    return kebab(hostPath);
-  }
-
-  // File path. Make it project-relative so two devs critiquing the same
-  // checkout get the same slug regardless of where their repo is cloned.
-  const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
-  let rel = path.relative(cwd, abs);
-  // If the target is outside cwd, fall back to the basename so we still
-  // produce a stable slug (vs the absolute path, which would include
-  // home dirs / usernames).
-  if (rel.startsWith('..') || path.isAbsolute(rel)) {
-    rel = path.basename(abs);
-  }
-  if (!rel || rel === '.' || rel === '') return null;
-  return kebab(rel);
-}
-
-function kebab(s) {
-  const slug = s
-    .toLowerCase()
-    .replace(/[/\\.]+/g, '-')
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '');
-  if (!slug) return null;
-  // Cap from the tail — the tail (filename) is more identifying than the
-  // top-level directory.
-  return slug.length <= SLUG_MAX ? slug : slug.slice(slug.length - SLUG_MAX).replace(/^-/, '');
-}
-
 /**
  * Filename-safe UTC ISO timestamp: hyphens for separators, trailing Z.
  * Plain colons aren't allowed on Windows filesystems.
@@ -180,6 +141,15 @@ export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
 
 // ---- CLI ---------------------------------------------------------------
 
+// Accept either a ready slug or a concrete target (path/URL) everywhere, so
+// callers never have to run the slug step separately. Anything containing a
+// path or URL marker is resolved through slugFromTarget.
+function coerceSlug(value) {
+  if (!value) return null;
+  if (/^[a-z0-9-]+$/.test(value) && !value.includes('/')) return value;
+  return slugFromTarget(value);
+}
+
 function main(argv) {
   const [cmd, ...args] = argv;
   switch (cmd) {
@@ -190,8 +160,9 @@ function main(argv) {
       return;
     }
     case 'write': {
-      const [slug, bodyFile] = args;
-      if (!slug || !bodyFile) { process.stderr.write('usage: write <slug> <body-file>\n'); process.exit(1); }
+      const [slugArg, bodyFile] = args;
+      const slug = coerceSlug(slugArg);
+      if (!slug || !bodyFile) { process.stderr.write('usage: write <slug-or-target> <body-file>\n'); process.exit(1); }
       const raw = fs.readFileSync(bodyFile, 'utf-8');
       // The body file may be a full report. The caller passes the meta as
       // a JSON object on stdin if it wants structured frontmatter; otherwise
@@ -206,13 +177,13 @@ function main(argv) {
       return;
     }
     case 'latest': {
-      const latest = readLatestSnapshot(args[0]);
+      const latest = readLatestSnapshot(coerceSlug(args[0]));
       if (!latest) { process.exit(2); }
       process.stdout.write(latest.body);
       return;
     }
     case 'trend': {
-      const rows = readTrend(args[0], { limit: args[1] ? Number(args[1]) : 5 });
+      const rows = readTrend(coerceSlug(args[0]), { limit: args[1] ? Number(args[1]) : 5 });
       process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
       return;
     }

package/template/.agents/skills/design/impeccable/scripts/detector/browser/injected/index.mjs

@@ -530,7 +530,11 @@ if (IS_BROWSER) {
   function generateSelector(el) {
     if (el === document.body) return 'body';
     if (el === document.documentElement) return 'html';
-    if (el.id) return '#' + CSS.escape(el.id);
+    // Read via getAttribute when `el.id` is not a string — a <form> with a
+    // named control (e.g. <input name="id">) shadows the builtin getter and
+    // returns the element, producing a garbage `#[object …]` selector (#407).
+    const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
+    if (elId) return '#' + CSS.escape(elId);
 
     const parts = [];
     let current = el;
@@ -1222,7 +1226,11 @@ if (IS_BROWSER) {
         return {
           type: f.type || f.id,
           category: ap ? ap.category : 'quality',
-          severity: ap?.severity || 'warning',
+          severity: f.severity || ap?.severity || 'warning',
+          // Advisory findings (em-dash overuse, etc.) are surfaced but never
+          // treated as failures; carry the flag so the overlay/extension can
+          // render them with the mildest affordance and consumers can filter.
+          advisory: (ap && ap.advisory === true) || f.advisory === true,
           detail: f.detail || f.snippet,
           ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
@@ -1458,16 +1466,16 @@ if (IS_BROWSER) {
     const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
     const designSystem = browserDesignSystemConfig();
     const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
-    // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
-    // real browser env (detector page, live overlay, extension) running every
-    // check is free, so we always surface them; the gating is purely a CLI
-    // output concern, applied in the Node engines' detect* return paths.
+    // All deterministic rules run in the browser and extension path.
 
     for (const el of document.querySelectorAll('*')) {
       // Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
       if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
-      // Skip browser extension elements (Claude, etc.)
-      const elId = el.id || '';
+      // Skip browser extension elements (Claude, etc.). Use getAttribute when
+      // `el.id` is not a string: a <form> with a named control like
+      // <input name="id"> shadows the builtin `id` getter and returns the
+      // element, whose `.startsWith` throws (issue #407).
+      const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
       if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
       // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
       // These are inspector chrome, not part of the user's design.
@@ -1477,10 +1485,12 @@ if (IS_BROWSER) {
 
       const findings = [
         ...checkElementBordersDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
+        ...checkElementPseudoStripeDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementColorsDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
+        ...checkElementRadialSpotlightDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
@@ -1488,6 +1498,7 @@ if (IS_BROWSER) {
         ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
+        ...checkElementBlinkingCursorDOM(el).map(f => ({ type: f.id, detail: f.snippet, ...(f.severity ? { severity: f.severity } : {}) })),
         ...checkElementDesignSystemDOM(el, designSystem, designSeen),
       ].filter(f => _ruleOk(f.type));
 
@@ -1518,7 +1529,7 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, typoFindings);
     }
 
-    const sectionKickerFindings = checkRepeatedSectionKickersDOM()
+    const sectionKickerFindings = checkKickerAboveHeadingDOM()
       .map(f => ({ type: f.id, detail: f.snippet }))
       .filter(f => _ruleOk(f.type));
     if (sectionKickerFindings.length > 0) {
@@ -1526,12 +1537,66 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, sectionKickerFindings);
     }
 
+    const numberedLabelFindings = checkNumberedSectionLabelsDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (numberedLabelFindings.length > 0) {
+      pageLevelFindings.push(...numberedLabelFindings);
+      addBrowserFindings(groupMap, document.body, numberedLabelFindings);
+    }
+
+    const repeatedTextFindings = checkRepeatedContainerTextDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (repeatedTextFindings.length > 0) {
+      pageLevelFindings.push(...repeatedTextFindings);
+      addBrowserFindings(groupMap, document.body, repeatedTextFindings);
+    }
+
+    // Em-dash overuse (advisory): browser parity with the static/regex path.
+    // Reads rendered body text so it catches dashes written as HTML entities.
+    // serializeFindings stamps the advisory flag from the registry.
+    const emDashFindings = checkEmDashOveruseDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (emDashFindings.length > 0) {
+      pageLevelFindings.push(...emDashFindings);
+      addBrowserFindings(groupMap, document.body, emDashFindings);
+    }
+
     const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
     for (const f of layoutFindings) {
       const el = f.el || document.body;
       addBrowserFindings(groupMap, el, [{ type: f.type, detail: f.detail || f.snippet }]);
     }
 
+    // Heading rhythm (browser-only: needs real layout for the gap math)
+    const headingRhythmFindings = checkHeadingRhythmDOM().filter(f => _ruleOk(f.type));
+    for (const f of headingRhythmFindings) {
+      addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
+    }
+
+    // Edge-flush cards in horizontal scrollers (browser-only: needs real
+    // layout for the scroller clip box vs card rect math)
+    const edgeFlushFindings = checkEdgeFlushCardsDOM().filter(f => _ruleOk(f.type));
+    for (const f of edgeFlushFindings) {
+      addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
+    }
+
+    // Text occlusion / element overlap (browser-only: needs real layout +
+    // elementFromPoint to confirm what actually paints on top)
+    const occlusionFindings = checkTextOcclusionDOM().filter(f => _ruleOk(f.type));
+    for (const f of occlusionFindings) {
+      addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
+    }
+
+    // First-viewport column overflow — the stretched-hero signature
+    // (browser-only: needs real layout for the content-extent math)
+    const colOverflowFindings = checkFirstViewportColumnOverflowDOM().filter(f => _ruleOk(f.type));
+    for (const f of colOverflowFindings) {
+      addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
+    }
+
     // Page-level quality checks (headings, etc.)
     const qualityFindings = checkPageQualityDOM().filter(f => _ruleOk(f.type));
     if (qualityFindings.length > 0) {
@@ -1557,7 +1622,25 @@ if (IS_BROWSER) {
     }
     const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
     if (htmlPatternFindings.length > 0) {
-      const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
+      const mapped = htmlPatternFindings.map(f => {
+        const item = { type: f.id, detail: f.snippet };
+        if (f.severity) {
+          item.severity = f.severity;
+        } else if (f.id === 'pulsing-dot' && f.selector) {
+          // The string scan promotes header/nav dots on its own; with a live
+          // layout also promote dots resting in the first ~900px of the page
+          // (the hero region), which the source scan cannot measure.
+          try {
+            const dotEl = document.querySelector(f.selector);
+            if (dotEl) {
+              const rect = dotEl.getBoundingClientRect();
+              const pageTop = rect.top + (window.scrollY || 0);
+              if (pageTop <= 900) item.severity = 'error';
+            }
+          } catch { /* unresolvable selector: keep registry severity */ }
+        }
+        return item;
+      }).filter(f => _ruleOk(f.type));
       pageLevelFindings.push(...mapped);
       addBrowserFindings(groupMap, document.body, mapped);
     }
@@ -1931,6 +2014,9 @@ if (IS_BROWSER) {
   window.impeccableDetectAsync = detectAsync;
   window.impeccableScan = scan;
   window.impeccableScanAsync = scanAsync;
+  // Raw measurement for the URL engine's content-hidden-at-rest pass: it
+  // drives a reveal sweep from Node and thresholds the result itself.
+  window.impeccableMeasureHiddenText = measureHiddenTextDOM;
   window.impeccableCollectVisualContrastCandidates = collectVisualContrastCandidates;
   window.impeccableAnalyzeVisualContrast = analyzeVisualContrast;
   window.impeccableGetLastVisualContrastAnalyses = () => lastVisualContrastAnalyses.slice();

package/template/.agents/skills/design/impeccable/scripts/detector/cli/main.mjs

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-import { loadDesignSystemForCwd } from '../design-system.mjs';
+import { loadDesignSystemForTarget } from '../design-system.mjs';
+import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
 import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
 import { detectHtml } from '../engines/static-html/detect-html.mjs';
 import { detectText } from '../engines/regex/detect-text.mjs';
@@ -26,9 +28,37 @@ function formatFindingSummary(count) {
   return `${count} anti-pattern${count === 1 ? '' : 's'} found.`;
 }
 
-function formatFindings(findings, jsonMode) {
-  if (jsonMode) return JSON.stringify(findings, null, 2);
+// Local filesystem path behind a file:// URL, or null when it can't be mapped.
+function fileUrlToLocalPath(url) {
+  try {
+    return fileURLToPath(url);
+  } catch {
+    return null;
+  }
+}
+
+// Advisory findings are detected but never treated as failures: they list in a
+// separate, visually dimmed section, are excluded from the failure count that
+// drives the exit code, and carry `"advisory": true` in JSON so consumers can
+// filter. Every advisory finding carries the flag (stamped by the registry via
+// findings.mjs).
+function isAdvisory(finding) {
+  return finding && finding.advisory === true;
+}
+
+function partitionAdvisory(findings) {
+  const primary = [];
+  const advisory = [];
+  for (const f of findings) (isAdvisory(f) ? advisory : primary).push(f);
+  return { primary, advisory };
+}
+
+// ANSI dim, when stderr is a TTY. Advisory output is chrome, so keep it quiet.
+function dim(text) {
+  return process.stderr.isTTY ? `\x1b[2m${text}\x1b[0m` : text;
+}
 
+function formatFindingsBody(findings) {
   const grouped = {};
   for (const f of findings) {
     if (!grouped[f.file]) grouped[f.file] = [];
@@ -43,7 +73,28 @@ function formatFindings(findings, jsonMode) {
       out.push(`    → ${item.description}`);
     }
   }
-  out.push(`\n${formatFindingSummary(findings.length)}`);
+  return out;
+}
+
+function formatAdvisorySection(advisory) {
+  if (!advisory || advisory.length === 0) return '';
+  const lines = [`\n${dim('── Advisory (not counted as failures) ──')}`];
+  for (const line of formatFindingsBody(advisory)) lines.push(dim(line));
+  lines.push(dim(`\n${advisory.length} advisory note${advisory.length === 1 ? '' : 's'}. Suppress with --no-advisory.`));
+  return lines.join('\n');
+}
+
+// Text/JSON formatter. `findings` is the full set; advisory items are separated
+// out into their own section and excluded from the failure summary count. JSON
+// output keeps every finding (each advisory one flagged) in a single array.
+function formatFindings(findings, jsonMode) {
+  if (jsonMode) return JSON.stringify(findings, null, 2);
+
+  const { primary, advisory } = partitionAdvisory(findings);
+  const out = [...formatFindingsBody(primary)];
+  out.push(`\n${formatFindingSummary(primary.length)}`);
+  const advisorySection = formatAdvisorySection(advisory);
+  if (advisorySection) out.push(advisorySection);
   return out.join('\n');
 }
 
@@ -51,7 +102,11 @@ function formatFindings(findings, jsonMode) {
 // Stdin handling
 // ---------------------------------------------------------------------------
 
-async function handleStdin(options = {}) {
+// `optionsFor` maps a local path to scan options carrying that path's own
+// project design system (or base options when null). Falls back to a plain
+// object so direct/legacy callers still work.
+async function handleStdin(optionsFor = () => ({})) {
+  const resolve = typeof optionsFor === 'function' ? optionsFor : () => optionsFor;
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
   const input = Buffer.concat(chunks).toString('utf-8');
@@ -59,11 +114,12 @@ async function handleStdin(options = {}) {
     const parsed = JSON.parse(input);
     const fp = parsed?.tool_input?.file_path;
     if (fp && fs.existsSync(fp)) {
+      const options = resolve(fp);
       return HTML_EXTENSIONS.has(path.extname(fp).toLowerCase())
         ? detectHtml(fp, options) : detectText(fs.readFileSync(fp, 'utf-8'), fp, options);
     }
   } catch { /* not JSON */ }
-  return detectText(input, '<stdin>', options);
+  return detectText(input, '<stdin>', resolve(null));
 }
 
 
@@ -91,14 +147,22 @@ Scan files or URLs for UI anti-patterns and design quality issues.
 Options:
   --json              Output results as JSON
   --quiet             In text mode, only print the final findings count
-  --gpt               Also report GPT-specific provider tells (off by default)
-  --gemini            Also report Gemini-specific provider tells (off by default)
+  --scope <name>      Only report rules in the given design domain
+                      (type, layout). Comma-separated.
+  --viewport <WxH>    Browser viewport for URL scans (default 1280x800),
+                      e.g. --viewport 390x844 for a mobile-width pass
   --no-config         Do not apply project config, detector ignores, inline
                       ignore comments, or DESIGN.md
   --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
   --no-design-system  Do not load local DESIGN.md / .impeccable/design.json context
+  --no-advisory       Suppress advisory findings entirely (e.g. em-dash overuse)
   --help              Show this help message
 
+Advisory findings:
+  Some rules are advisory: detected and listed in a separate section, but never
+  counted as failures and never changing the exit code. They stay out of the
+  failure count so they never block automation. --no-advisory hides them.
+
 Project config:
   Respects .impeccable/config.json and .impeccable/config.local.json detector
   settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
@@ -115,7 +179,8 @@ Inline ignores:
 Detection modes:
   HTML files     Static HTML/CSS analysis (default, catches linked CSS)
   Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
-  URLs           Puppeteer full browser rendering (auto-detected)
+  URLs           Puppeteer full browser rendering (auto-detected;
+                 http(s):// and file:// URLs)
 
 Examples:
   impeccable detect src/
@@ -135,6 +200,7 @@ async function detectCli() {
   const jsonMode = args.includes('--json');
   const quietMode = args.includes('--quiet');
   const helpMode = args.includes('--help');
+  const noAdvisory = args.includes('--no-advisory');
   // --fast (regex-only) is deprecated: since the jsdom removal, the static
   // HTML/CSS analysis is fast and covers every rule, so the regex-only path
   // only loses coverage for no real speed win. Accept the flag for back-compat
@@ -144,21 +210,74 @@ async function detectCli() {
       'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
     );
   }
+  if (args.includes('--gpt') || args.includes('--gemini')) {
+    process.stderr.write(
+      'Note: --gpt and --gemini are deprecated and ignored. Generated-UI tells now run by default.\n',
+    );
+  }
   const configEnabled = !args.includes('--no-config');
   const detectionConfig = configEnabled
     ? readDetectionConfig(process.cwd())
     : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
-  const providers = [];
-  if (args.includes('--gpt')) providers.push('gpt');
-  if (args.includes('--gemini')) providers.push('gemini');
+  const scopes = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
+    const inline = args[i].startsWith('--scope=');
+    const value = inline ? args[i].slice('--scope='.length) : args[i + 1];
+    const parsed = (value && !value.startsWith('--'))
+      ? value.split(',').map(s => s.trim()).filter(Boolean)
+      : [];
+    // A bare `--scope` would otherwise fall out of `targets` and scan unscoped;
+    // fail loudly so a mistyped pre-scan never runs the wrong rule set.
+    if (parsed.length === 0) {
+      process.stderr.write(
+        `Error: --scope requires a value. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
+      );
+      process.exit(1);
+    }
+    scopes.push(...parsed);
+    args.splice(i, inline ? 1 : 2);
+    i -= 1;
+  }
+  let viewport = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== '--viewport' && !args[i].startsWith('--viewport=')) continue;
+    const inline = args[i].startsWith('--viewport=');
+    const value = inline ? args[i].slice('--viewport='.length) : args[i + 1];
+    const match = /^(\d{2,5})x(\d{2,5})$/i.exec(value || '');
+    if (!match) {
+      process.stderr.write('Error: --viewport requires a WxH value, e.g. --viewport 390x844\n');
+      process.exit(1);
+    }
+    viewport = { width: Number(match[1]), height: Number(match[2]) };
+    args.splice(i, inline ? 1 : 2);
+    i -= 1;
+  }
+  const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
+  if (unknownScopes.length > 0) {
+    process.stderr.write(
+      `Error: unknown --scope value(s): ${unknownScopes.join(', ')}. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
+    );
+    process.exit(1);
+  }
   const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
-  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
   // Inline `impeccable-disable*` waivers are part of the scanned file, so they
   // apply by default. `--no-config` (raw scan) and the dedicated
   // `--no-inline-ignores` both turn them off.
   const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
-  const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
-  if (designSystem) scanOptions.designSystem = designSystem;
+  const baseScanOptions = { inlineIgnores: inlineIgnoresEnabled };
+  if (viewport) baseScanOptions.viewport = viewport;
+  // DESIGN.md must resolve from EACH scan target's own project root, not from
+  // process.cwd(): scanning project B's files from inside project A applied A's
+  // design rules (cross-project contamination). Resolve per target, memoized by
+  // resolved project root so a multi-file scan pays the read once per project.
+  // A target with no project marker above it gets no design system (never cwd's).
+  const designSystemCache = new Map();
+  const scanOptionsFor = (localPath) => {
+    if (!designSystemEnabled || !localPath) return baseScanOptions;
+    const designSystem = loadDesignSystemForTarget(localPath, { cache: designSystemCache });
+    return designSystem ? { ...baseScanOptions, designSystem } : baseScanOptions;
+  };
   const targets = args.filter(a => !a.startsWith('--'));
 
   if (helpMode) { printUsage(); process.exit(0); }
@@ -166,19 +285,31 @@ async function detectCli() {
   let allFindings = [];
 
   if (!process.stdin.isTTY && targets.length === 0) {
-    allFindings = await handleStdin(scanOptions);
+    allFindings = await handleStdin(scanOptionsFor);
   } else {
     const paths = targets.length > 0 ? targets : [process.cwd()];
-    const urlTargetCount = paths.filter(target => /^https?:\/\//i.test(target)).length;
+    // file:// URLs get the same Puppeteer-rendered pass as http(s) — the
+    // real cascade, real computed styles, real layout. Callers that want a
+    // browser-grade scan of a local artifact can pass file:///abs/path.html
+    // instead of the bare path (which stays on the static engine).
+    const urlRe = /^(?:https?|file):\/\//i;
+    const urlTargetCount = paths.filter(target => urlRe.test(target)).length;
     const browserDetector = urlTargetCount > 1 ? await createBrowserDetector() : null;
 
     try {
       for (const target of paths) {
-        if (/^https?:\/\//i.test(target)) {
+        if (urlRe.test(target)) {
+          // A file:// URL points at a local artifact, so its design system
+          // resolves from that file's project. A remote http(s) URL has no
+          // local project — it gets base options (no design system), never
+          // process.cwd()'s.
+          const urlOptions = /^file:/i.test(target)
+            ? scanOptionsFor(fileUrlToLocalPath(target))
+            : baseScanOptions;
           try {
             const scanner = browserDetector
-              ? (url) => browserDetector.detectUrl(url, scanOptions)
-              : (url) => detectUrl(url, scanOptions);
+              ? (url) => browserDetector.detectUrl(url, urlOptions)
+              : (url) => detectUrl(url, urlOptions);
             allFindings.push(...await scanner(target));
           } catch (e) { process.stderr.write(`Error: ${e.message}\n`); }
           continue;
@@ -244,11 +375,14 @@ async function detectCli() {
 
           for (const file of files) {
             const ext = path.extname(file).toLowerCase();
+            // Each file resolves its own project design system (cached by root),
+            // so a scan spanning sibling projects applies the right rules per file.
+            const fileOptions = scanOptionsFor(file);
             let fileFindings;
             if (HTML_EXTENSIONS.has(ext)) {
-              fileFindings = await detectHtml(file, scanOptions);
+              fileFindings = await detectHtml(file, fileOptions);
             } else {
-              fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file, scanOptions);
+              fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file, fileOptions);
             }
             // Annotate findings with import context
             const importers = importedByMap.get(file);
@@ -263,10 +397,11 @@ async function detectCli() {
         } else if (stat.isFile()) {
           if (shouldIgnoreDetectionFile(resolved, process.cwd(), detectionConfig)) continue;
           const ext = path.extname(resolved).toLowerCase();
+          const fileOptions = scanOptionsFor(resolved);
           if (HTML_EXTENSIONS.has(ext)) {
-            allFindings.push(...await detectHtml(resolved, scanOptions));
+            allFindings.push(...await detectHtml(resolved, fileOptions));
           } else {
-            allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved, scanOptions));
+            allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved, fileOptions));
           }
         }
       }
@@ -276,12 +411,25 @@ async function detectCli() {
   }
 
   allFindings = filterDetectionFindings(allFindings, detectionConfig);
+  allFindings = filterByScopes(allFindings, scopes);
+  // --no-advisory drops advisory findings before any output or exit-code math.
+  if (noAdvisory) allFindings = allFindings.filter((f) => !isAdvisory(f));
+
+  // The exit code and failure count reflect non-advisory findings only. An
+  // advisory-only scan still prints its notes but exits 0 (a clean pass), so
+  // advisory rules never break CI or block automation.
+  const { primary, advisory } = partitionAdvisory(allFindings);
 
   if (allFindings.length > 0) {
     if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
-    else if (quietMode) process.stderr.write(formatFindingSummary(allFindings.length) + '\n');
+    else if (quietMode) {
+      process.stderr.write(formatFindingSummary(primary.length) + '\n');
+      if (advisory.length > 0) {
+        process.stderr.write(dim(`${advisory.length} advisory note${advisory.length === 1 ? '' : 's'} (not counted).`) + '\n');
+      }
+    }
     else process.stderr.write(formatFindings(allFindings, false) + '\n');
-    process.exit(2);
+    process.exit(primary.length > 0 ? 2 : 0);
   }
   if (jsonMode) process.stdout.write('[]\n');
   process.exit(0);