slopbrick 0.17.4 → 0.18.1

package/dist/index.cjs

@@ -45379,7 +45379,7 @@ function formatPretty(report) {
 }
 function formatScoringExplainer(_report) {
   return import_chalk.default.dim(
-    "Why two scores? The Slop Index measures AI-slop signatures (lower = better, this is the CI gate). The Repository Coherence measures internal consistency (higher = better, informational). A codebase can be hand-written AND inconsistent (low Slop, low Coherence) or AI-generated AND consistent (high Slop, high Coherence). See docs/scoring-explained.md for the full math."
+    "Four orthogonal scores (all 0-100, higher = better): AI Quality (AI-slop signatures; the CI gate, AI Quality >= 70), Engineering Hygiene (issues per category across arch/logic/layout/component/test), Security (AI-flagged security risks, inverted from risk level), Repository Health (composite: 0.4*AI Quality + 0.3*Engineering Hygiene + 0.2*Security + 0.1*Test Quality). Only AI Quality gates CI; the others are informational. Default-off rules (INVERTED/NOISY/DORMANT) are suppressed from the scores automatically."
   );
 }
 function formatWhyFailingReport(report) {
@@ -46041,11 +46041,11 @@ var init_pool = __esm({
         for (let i = 0; i < this.threadCount; i++) {
           spawnWorker();
         }
-        return new Promise((resolve18) => {
+        return new Promise((resolve20) => {
           const check = setInterval(() => {
             if (resolved) {
               clearInterval(check);
-              resolve18(results);
+              resolve20(results);
             }
           }, 10);
         });
@@ -49990,29 +49990,29 @@ function renderStructureMarkdown(inventory, constitution) {
   return lines.join("\n");
 }
 async function writeStructureMarkdown(workspaceDir, md) {
-  await new Promise((resolve18, reject) => {
+  await new Promise((resolve20, reject) => {
     try {
       const path = (0, import_node_path21.join)(workspaceDir, STRUCTURE_MD_FILE);
       (0, import_node_fs21.mkdirSync)((0, import_node_path21.dirname)(path), { recursive: true });
       (0, import_node_fs21.writeFileSync)(path, md, "utf-8");
-      resolve18();
+      resolve20();
     } catch (err) {
       reject(err instanceof Error ? err : new Error(String(err)));
     }
   });
 }
 async function readStructureMarkdown(workspaceDir) {
-  return new Promise((resolve18) => {
+  return new Promise((resolve20) => {
     try {
       const path = (0, import_node_path21.join)(workspaceDir, STRUCTURE_MD_FILE);
       if (!(0, import_node_fs21.existsSync)(path)) {
-        resolve18(null);
+        resolve20(null);
         return;
       }
       const content = (0, import_node_fs21.readFileSync)(path, "utf-8");
-      resolve18(content);
+      resolve20(content);
     } catch {
-      resolve18(null);
+      resolve20(null);
     }
   });
 }
@@ -50281,11 +50281,12 @@ async function finalizeReport(input) {
   if (options.noIncrease) {
     const previous = (await readRuns(cwd, fsMemoryIO)).at(-1);
     if (previous) {
-      if ((report.aiQuality ?? 0) < previous.slopIndex) {
+      const previousBaseline = previous.slopIndex;
+      if ((report.aiQuality ?? 0) < previousBaseline) {
         noIncreaseFailure = true;
         if (!options.quiet) {
           logger.error(
-            `AI Quality went DOWN from ${previous.slopIndex.toFixed(1)} to ${(report.aiQuality ?? 0).toFixed(1)} \u2014 your code got sloppier. See which files changed and fix the new issues.`
+            `AI Quality went DOWN from ${previousBaseline.toFixed(1)} to ${(report.aiQuality ?? 0).toFixed(1)} \u2014 your code got sloppier. (Both values are 0-100, higher = better; the comparison is against the previous run's aiQuality, stored historically in the legacy slopIndex field.) See which files changed and fix the new issues.`
           );
         }
       }
@@ -52560,11 +52561,11 @@ __export(installer_exports, {
   uninstallHook: () => uninstallHook
 });
 function hookPath(gitRoot) {
-  const huskyDir = (0, import_node_path37.join)(gitRoot, ".husky");
+  const huskyDir = (0, import_node_path39.join)(gitRoot, ".husky");
   if ((0, import_node_fs35.existsSync)(huskyDir)) {
-    return (0, import_node_path37.join)(huskyDir, "pre-commit");
+    return (0, import_node_path39.join)(huskyDir, "pre-commit");
   }
-  return (0, import_node_path37.join)(gitRoot, ".git", "hooks", "pre-commit");
+  return (0, import_node_path39.join)(gitRoot, ".git", "hooks", "pre-commit");
 }
 function readHookContent(path) {
   return (0, import_node_fs35.readFileSync)(path, "utf8");
@@ -52629,7 +52630,7 @@ function installHook(gitRoot) {
       exitCode: 0
     };
   }
-  (0, import_node_fs35.mkdirSync)((0, import_node_path37.dirname)(path), { recursive: true });
+  (0, import_node_fs35.mkdirSync)((0, import_node_path39.dirname)(path), { recursive: true });
   (0, import_node_fs35.writeFileSync)(path, SENTINEL_BLOCK, { mode: 493 });
   (0, import_node_fs35.chmodSync)(path, 493);
   return {
@@ -52684,12 +52685,12 @@ function uninstallHook(gitRoot) {
     exitCode: 0
   };
 }
-var import_node_fs35, import_node_path37, BEGIN_SENTINEL, END_SENTINEL, SENTINEL_BLOCK;
+var import_node_fs35, import_node_path39, BEGIN_SENTINEL, END_SENTINEL, SENTINEL_BLOCK;
 var init_installer = __esm({
   "src/cli/installer.ts"() {
     "use strict";
     import_node_fs35 = require("fs");
-    import_node_path37 = require("path");
+    import_node_path39 = require("path");
     BEGIN_SENTINEL = "# slopbrick-hook-begin";
     END_SENTINEL = "# slopbrick-hook-end";
     SENTINEL_BLOCK = `${BEGIN_SENTINEL}
@@ -52767,7 +52768,7 @@ async function runScanFile(args, ctx) {
     content: [{ type: "text", text: JSON.stringify(simplified, null, 2) }]
   };
 }
-function explainRule(args, ctx) {
+function explainRule2(args, ctx) {
   const ruleId = args.ruleId;
   if (!ruleId) return toolError("Missing required argument: ruleId");
   const rule = ctx.rules.find((r) => r.id === ruleId);
@@ -52878,7 +52879,7 @@ async function runGovernance(args, ctx) {
 function runCheckConstitution(args, ctx) {
   const path = args.path;
   if (!path) return toolError("Missing required argument: path");
-  const absPath = (0, import_node_path40.resolve)(ctx.cwd, path);
+  const absPath = (0, import_node_path42.resolve)(ctx.cwd, path);
   let source;
   try {
     source = (0, import_node_fs38.readFileSync)(absPath, "utf-8");
@@ -53041,7 +53042,7 @@ async function handleToolCall(toolName, args, ctx) {
     case "slop_scan_file":
       return runScanFile(args, ctx);
     case "slop_explain_rule":
-      return explainRule(args, ctx);
+      return explainRule2(args, ctx);
     case "slop_list_rules":
       return listRules(args, ctx);
     case "slop_suggest":
@@ -53068,12 +53069,12 @@ function canonicalToolNames() {
 function getDeprecation(toolName) {
   return TOOL_DEFINITIONS.find((t) => t.name === toolName)?.deprecated;
 }
-var import_node_fs38, import_node_path40, TOOL_DEFINITIONS;
+var import_node_fs38, import_node_path42, TOOL_DEFINITIONS;
 var init_tools = __esm({
   "src/mcp/tools.ts"() {
     "use strict";
     import_node_fs38 = require("fs");
-    import_node_path40 = require("path");
+    import_node_path42 = require("path");
     init_worker();
     init_patterns();
     init_architecture_score();
@@ -53259,36 +53260,36 @@ function planMigration(workspaceDir) {
   const moves = [];
   const rewrites = [];
   const gitignoreEdits = [];
-  const oldDir = (0, import_node_path43.join)(workspaceDir, ".slop-audit");
-  const newDir = (0, import_node_path43.join)(workspaceDir, ".slopbrick");
+  const oldDir = (0, import_node_path45.join)(workspaceDir, ".slop-audit");
+  const newDir = (0, import_node_path45.join)(workspaceDir, ".slopbrick");
   if ((0, import_node_fs44.existsSync)(oldDir)) {
     moves.push({ from: oldDir, to: newDir, kind: "dir" });
     rewrites.push({
-      path: (0, import_node_path43.join)(newDir, "inventory.json"),
+      path: (0, import_node_path45.join)(newDir, "inventory.json"),
       field: "version",
       from: '"1"',
       to: '"2"'
     });
     rewrites.push({
-      path: (0, import_node_path43.join)(newDir, "constitution.json"),
+      path: (0, import_node_path45.join)(newDir, "constitution.json"),
       field: "version",
       from: '"1"',
       to: '"2"'
     });
   }
-  const oldCache = (0, import_node_path43.join)(workspaceDir, ".slop-audit-cache.json");
-  const newCache = (0, import_node_path43.join)(workspaceDir, ".slopbrick-cache.json");
+  const oldCache = (0, import_node_path45.join)(workspaceDir, ".slop-audit-cache.json");
+  const newCache = (0, import_node_path45.join)(workspaceDir, ".slopbrick-cache.json");
   if ((0, import_node_fs44.existsSync)(oldCache)) {
     moves.push({ from: oldCache, to: newCache, kind: "file" });
   }
   for (const ext of ["mjs", "cjs", "js"]) {
-    const oldCfg = (0, import_node_path43.join)(workspaceDir, `slop-audit.config.${ext}`);
-    const newCfg = (0, import_node_path43.join)(workspaceDir, `slopbrick.config.${ext}`);
+    const oldCfg = (0, import_node_path45.join)(workspaceDir, `slop-audit.config.${ext}`);
+    const newCfg = (0, import_node_path45.join)(workspaceDir, `slopbrick.config.${ext}`);
     if ((0, import_node_fs44.existsSync)(oldCfg)) {
       moves.push({ from: oldCfg, to: newCfg, kind: "config" });
     }
   }
-  const gi = (0, import_node_path43.join)(workspaceDir, ".gitignore");
+  const gi = (0, import_node_path45.join)(workspaceDir, ".gitignore");
   if ((0, import_node_fs44.existsSync)(gi)) {
     const content = (0, import_node_fs44.readFileSync)(gi, "utf-8");
     if (content.includes(".slop-audit/")) {
@@ -53309,7 +53310,7 @@ function planMigration(workspaceDir) {
   return { moves, rewrites, gitignoreEdits };
 }
 function isAlreadyMigrated(workspaceDir) {
-  return (0, import_node_fs44.existsSync)((0, import_node_path43.join)(workspaceDir, ".slopbrick")) && !(0, import_node_fs44.existsSync)((0, import_node_path43.join)(workspaceDir, ".slop-audit"));
+  return (0, import_node_fs44.existsSync)((0, import_node_path45.join)(workspaceDir, ".slopbrick")) && !(0, import_node_fs44.existsSync)((0, import_node_path45.join)(workspaceDir, ".slop-audit"));
 }
 function applyMigration(plan, options = {}) {
   if (options.dryRun) return;
@@ -53340,8 +53341,8 @@ function runMigrate(options) {
     };
   }
   const alreadyMigrated = isAlreadyMigrated(workspace);
-  const newDir = (0, import_node_path43.join)(workspace, ".slopbrick");
-  const oldDir = (0, import_node_path43.join)(workspace, ".slop-audit");
+  const newDir = (0, import_node_path45.join)(workspace, ".slopbrick");
+  const oldDir = (0, import_node_path45.join)(workspace, ".slop-audit");
   if ((0, import_node_fs44.existsSync)(newDir) && (0, import_node_fs44.existsSync)(oldDir) && !force) {
     return {
       ok: false,
@@ -53409,12 +53410,12 @@ function formatMigrate(result) {
   }
   return lines.join("\n");
 }
-var import_node_fs44, import_node_path43;
+var import_node_fs44, import_node_path45;
 var init_migrate = __esm({
   "src/cli/migrate.ts"() {
     "use strict";
     import_node_fs44 = require("fs");
-    import_node_path43 = require("path");
+    import_node_path45 = require("path");
     init_logger();
   }
 });
@@ -53506,7 +53507,7 @@ init_dist2();
 
 // src/cli/program.ts
 var import_node_fs45 = require("fs");
-var import_node_path44 = require("path");
+var import_node_path46 = require("path");
 var import_node_perf_hooks = require("perf_hooks");
 var import_commander2 = require("commander");
 
@@ -55012,17 +55013,17 @@ var UI_LIBRARY_OPTIONS = ["shadcn/ui", "mui", "chakra", "radix", "tamagui", "nat
 var STRICTNESS_OPTIONS = ["strict", "balanced", "permissive"];
 var STRUCTURE_OPTIONS = ["feature-based", "layer-based", "flat", "monorepo", "other"];
 function promptText(rl, question, detected) {
-  return new Promise((resolve18) => {
+  return new Promise((resolve20) => {
     const lines = [
       `? ${question} (detected: ${detected || "none"}) \u2014 npm package name, or Enter to skip:`
     ];
     rl.question(lines.join("\n") + "\n", (answer) => {
       const trimmed = answer.trim();
       if (trimmed === "") {
-        resolve18(void 0);
+        resolve20(void 0);
         return;
       }
-      resolve18(trimmed);
+      resolve20(trimmed);
     });
   });
 }
@@ -55030,7 +55031,7 @@ function promptSingleSelect(rl, question, options, defaultValue) {
   const defaultIndex = options.indexOf(defaultValue);
   const safeDefaultIndex = defaultIndex >= 0 ? defaultIndex : 0;
   const safeDefaultValue = options[safeDefaultIndex];
-  return new Promise((resolve18) => {
+  return new Promise((resolve20) => {
     function ask() {
       const lines = [
         `? ${question} (detected: ${safeDefaultValue}):`,
@@ -55040,7 +55041,7 @@ function promptSingleSelect(rl, question, options, defaultValue) {
       rl.question(lines.join("\n") + "\n", (answer) => {
         const trimmed = answer.trim();
         if (trimmed === "") {
-          resolve18(safeDefaultValue);
+          resolve20(safeDefaultValue);
           return;
         }
         const num = parseInt(trimmed, 10);
@@ -55049,7 +55050,7 @@ function promptSingleSelect(rl, question, options, defaultValue) {
           ask();
           return;
         }
-        resolve18(options[num - 1]);
+        resolve20(options[num - 1]);
       });
     }
     ask();
@@ -55059,7 +55060,7 @@ function promptMultiSelect(rl, question, options, defaultValue) {
   const defaultIndices = defaultValue.map((v) => options.indexOf(v)).filter((i) => i >= 0);
   const defaultDisplay = defaultValue.length > 0 ? defaultValue.join(", ") : "none";
   const defaultNumbers = defaultIndices.length > 0 ? defaultIndices.map((i) => i + 2).join(",") : "1";
-  return new Promise((resolve18) => {
+  return new Promise((resolve20) => {
     function ask() {
       const lines = [
         `? ${question} (detected: ${defaultDisplay}):`,
@@ -55070,7 +55071,7 @@ function promptMultiSelect(rl, question, options, defaultValue) {
       rl.question(lines.join("\n") + "\n", (answer) => {
         const trimmed = answer.trim();
         if (trimmed === "") {
-          resolve18(defaultValue.length > 0 ? defaultValue : []);
+          resolve20(defaultValue.length > 0 ? defaultValue : []);
           return;
         }
         const numbers = trimmed.split(",").map((s) => parseInt(s.trim(), 10)).filter((n) => !Number.isNaN(n));
@@ -55080,11 +55081,11 @@ function promptMultiSelect(rl, question, options, defaultValue) {
           return;
         }
         if (numbers.includes(1)) {
-          resolve18([]);
+          resolve20([]);
           return;
         }
         const selected = [...new Set(numbers.map((n) => options[n - 2]).filter((v) => v !== void 0))];
-        resolve18(selected);
+        resolve20(selected);
       });
     }
     ask();
@@ -55264,6 +55265,234 @@ async function runDoctor(cwd) {
   return exitCode;
 }
 
+// src/cli/commands/badge.ts
+var import_node_path37 = require("path");
+init_render();
+init_logger();
+init_scan();
+function registerBadge(program) {
+  program.command("badge").description(
+    "print a shields.io slop-index badge. Reads .slopbrick/health.json if present (no re-scan); falls back to a fresh scan."
+  ).action(async (_cmdOptions, command) => {
+    const options = command.optsWithGlobals();
+    const cwd = (0, import_node_path37.resolve)(options.workspace ?? process.cwd());
+    const { loadHealth: loadHealth2 } = await Promise.resolve().then(() => (init_dist(), dist_exports));
+    const health = loadHealth2(cwd);
+    if (health) {
+      const synthetic = {
+        slopIndex: 100 - health.repositoryHealth
+      };
+      logger.info(formatBadge(synthetic));
+      process.exit(0);
+    }
+    const { report } = await runScan(options);
+    logger.info(formatBadge(report));
+    process.exit(0);
+  });
+}
+
+// src/cli/commands/suggest.ts
+var import_node_path38 = require("path");
+init_advice();
+init_unified_diff();
+init_logger();
+init_scan();
+function registerSuggest(program) {
+  program.command("suggest").description("print remediation advice").action(async (_cmdOptions, command) => {
+    const options = command.optsWithGlobals();
+    const { report } = await runScan(options);
+    const cwd = (0, import_node_path38.resolve)(options.workspace ?? process.cwd());
+    logger.info(formatAdvice(report));
+    const diff = formatUnifiedDiff(report, cwd);
+    if (diff) logger.info(diff);
+    process.exit(0);
+  });
+}
+
+// src/cli/explain.ts
+var RULES_BASE_URL2 = "https://github.com/Dystx/slopbrick/blob/main/src/rules";
+function ruleIdToFilename2(ruleId) {
+  const slash = ruleId.indexOf("/");
+  return slash === -1 ? ruleId : ruleId.slice(slash + 1);
+}
+function explainRule(ruleId, rules, ruleHints) {
+  const rule = rules.find((r) => r.id === ruleId);
+  if (!rule) {
+    return { error: "Unknown rule: " + ruleId + ". Run `slopbrick rules` to see all available rules." };
+  }
+  const filename = ruleIdToFilename2(rule.id);
+  return {
+    ruleId: rule.id,
+    category: rule.category,
+    severity: rule.severity,
+    aiSpecific: rule.aiSpecific,
+    pattern: ruleHints[rule.id] ?? "Patterns flagged by " + rule.id + ".",
+    remediation: "See the rule source for the canonical before/after: src/rules/" + rule.category + "/" + filename + ".ts",
+    sourcePath: "src/rules/" + rule.category + "/" + filename + ".ts",
+    helpUri: `${RULES_BASE_URL2}/${rule.category}/${filename}.ts`,
+    suppressionSnippet: 'rules: { "' + rule.id + '": "off" }  // or set to a lower severity'
+  };
+}
+function formatExplain(result) {
+  if ("error" in result) return result.error;
+  const lines = [];
+  lines.push("Rule:        " + result.ruleId);
+  lines.push("Category:    " + result.category);
+  lines.push("Severity:    " + result.severity);
+  lines.push("AI-specific: " + (result.aiSpecific ? "yes (designed to fire on AI tells)" : "no (cross-cutting quality rule)"));
+  lines.push("Source:      " + result.sourcePath);
+  lines.push("Help:        " + result.helpUri);
+  lines.push("");
+  lines.push("Pattern:");
+  lines.push("  " + result.pattern);
+  lines.push("");
+  lines.push("Remediation:");
+  lines.push("  " + result.remediation);
+  lines.push("");
+  lines.push("Suppress / configure in slopbrick.config.mjs:");
+  lines.push("  " + result.suppressionSnippet);
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/cli/commands/explain.ts
+init_logger();
+init_builtins();
+
+// src/snippet/data.ts
+var CATEGORY_DIRECTIVES = {
+  visual: 'Avoid the saturated "vibe purple" Tailwind palette (violet-400-700, indigo-400-700). Prefer emerald, sky, amber, rose for accents. Never use arbitrary color values like bg-[#7c3aed] when a token exists.',
+  logic: "Never use explicit `any`. Use `unknown` and narrow. Always add an AbortSignal to fetches. Handle errors with try/catch, never swallow with empty catch. Use `as const` instead of `as Type` casts.",
+  wcag: 'All form inputs must have an accessible label (visible <label>, aria-label, or aria-labelledby). Decorative images must have empty alt="". Buttons must be <button>, never <div onClick>. Touch targets must be \u2265 24\xD724 CSS px.',
+  security: 'Never store tokens in localStorage or sessionStorage \u2014 use httpOnly Secure SameSite cookies. Never put secrets in NEXT_PUBLIC_* / REACT_APP_* / VITE_* env vars. Validate e.origin in postMessage handlers. Never dangerouslySetInnerHTML with user input. Never use target="_blank" without rel="noopener".',
+  perf: "Always use AbortController with fetch. Use image width/height attributes to prevent CLS. Use <Suspense> around async client components. Don't load all images eagerly.",
+  typo: `Never leave TODO / placeholder / "change me" copy in shipped code. Use real i18n strings or the project's content map.`,
+  layout: "Don't stack badge-above-h1 hero patterns. Don't build 3-stat banner rows without explicit user request. Don't use emoji inside nav items (use SVG icons). Use the project's spacing scale (4px or 8px grid), never arbitrary values like p-[13px].",
+  component: "Don't build components > 200 lines. Extract shared subcomponents. Avoid circular prop drilling \u2014 use context.",
+  arch: "For Astro: server-render everything by default; only opt-in to client islands when you need interactivity. Don't put secrets in client-side code.",
+  test: "Use domain-specific fixture data, assert on value shapes not just truthiness, and consolidate repeated setup into helpers. Avoid `expect(x).toBeDefined()` placeholders and textbook fixtures like 'John Doe' or 'test@test.com'."
+};
+var RULE_HINTS = {
+  // v0.16.0 hygiene: 35 out-of-scope orphan hints (keys with no matching
+  // rule in src/rules/builtins.ts) were moved out of this map. The
+  // verbatim source text is preserved in
+  //   docs/research/backlog-rule-hints.md
+  // so future implementers can paste a hint back when the corresponding
+  // rule ships. The 5 in-scope orphans (`security/eval`,
+  // `security/localstorage-token`, `security/target-blank-no-noopener`,
+  // `wcag/missing-alt`, `typo/placeholder-text`) are kept here for v0.16.0.
+  "security/hardcoded-secret": "Never inline API keys, JWT secrets, or database passwords in source. Load them from env vars and never commit a .env file. Assume any published secret is compromised and rotate it.",
+  "security/exposed-env-var": "NEVER prefix a secret with NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_, GATSBY_, or PUBLIC_ \u2014 those vars are inlined into every browser build.",
+  "security/dangerous-cors": "Don't set Access-Control-Allow-Origin: * on production endpoints. Restrict to an explicit allowlist; never combine wildcard origin with credentials: true.",
+  "security/missing-auth-check": "Every server route handler must perform an authentication + authorization check at the top. Reachability of an endpoint by any user (authenticated or not) is a vulnerability, not a feature.",
+  "security/unsafe-html-render": "Sanitize any non-literal value passed to dangerouslySetInnerHTML with DOMPurify. Better: avoid the prop entirely and let React escape via children.",
+  "security/fail-open-auth": "Don't gate auth bypasses on NODE_ENV. Replace dev-env checks with an explicit AUTH_BYPASS flag that's never set in production.",
+  "security/sql-construction": 'Never build SQL with string concatenation or template-literal interpolation. Use parameterized queries: pg client.query("... WHERE id = $1", [id]) or your ORM query builder.',
+  "security/public-admin-route": "Routes under /admin, /internal, /debug, /staff, /manage, /private need an explicit role check on top of standard auth \u2014 auth alone is not enough for privileged paths.",
+  "visual/arbitrary-escape": "Never use bracket-notation values like text-[13px] or bg-[#7c3aed]. Use design tokens instead.",
+  "visual/spacing-scale-violation": "Use spacing scale tokens (p-2, gap-4, etc.) instead of arbitrary values like p-[13px] or gap-[1.75rem].",
+  "visual/radius-scale-violation": "Use radius scale tokens (rounded-md, rounded-lg, etc.) instead of arbitrary values like rounded-[7px].",
+  // v0.16.0 — in-scope orphans kept here (corresponding rule ships in v0.16.0).
+  "typo/placeholder-text": 'Never leave "TODO", "placeholder", "change me", "your text here" in shipped UI.',
+  "logic/key-prop-missing": "Always provide a stable `key` prop when rendering lists.",
+  "logic/boundary-violation": "Don't import data-layer / DB code into UI components. Server-side only.",
+  "wcag/missing-alt": 'Every <img> needs alt text. Decorative: alt="". Informative: describe the image.',
+  "security/localstorage-token": "Never store JWT / access token / refresh token in localStorage or sessionStorage. Issue as httpOnly cookie.",
+  "security/eval": "Never use eval() or new Function(). These are RCE vectors if the input is ever attacker-controlled.",
+  "security/target-blank-no-noopener": 'Always add rel="noopener" (or rel="noreferrer") to target="_blank" links.',
+  "arch/astro-island-leak": "For Astro: server-render everything by default. Only opt-in to client islands when interactivity is needed.",
+  "component/giant-component": "Don't build components > 200 lines. Extract shared subcomponents.",
+  "component/multiple-components-per-file": "One component per file. Move subcomponents into their own files so the Context Window stays small and boundary tests are easy.",
+  "component/shadcn-prop-mismatch": "Select shadcn variants via the `variant` prop, not long `className` overrides. See the component registry for available variants.",
+  "context/import-path-mismatch": "Use only the canonical import paths declared in brick.config.json (e.g. @/components/ui/, @/lib/).",
+  "layout/forced-layout": "Vary structural patterns: some containers as grids, some as horizontal flex, some as blocks. Don't repeat `flex flex-col gap-4` everywhere.",
+  "layout/gap-monopoly": "Mix gap-2 / gap-4 / gap-6 / gap-12 deliberately. Don't repeat the same gap value across the whole project.",
+  "layout/math-element-uniformity": "Human files have lopsided interactive counts (1 button + 12 inputs). AI tends to balance them. Build forms with many inputs and few buttons.",
+  "layout/math-grid-uniformity": "Vary grid-cols-N (grid-cols-2, grid-cols-3, grid-cols-4, grid-cols-6) across sections instead of repeating grid-cols-3.",
+  "layout/spacing-grid": "Use the configured spacing scale (4px or 8px grid). Avoid arbitrary values like p-[13px] that aren't on the scale.",
+  "logic/ghost-defensive": "Use optional chaining (?.) or early returns instead of deep && guards. If a defensive chain runs 3+ levels deep, refactor.",
+  "logic/bayesian-conditional": "The Bayesian combiner aggregates multiple weak signals into a calibrated posterior P(AI|fires). Treat any fire above 0.7 as evidence of AI authorship; above 0.9 as strong evidence. (v0.12.0 \u2014 Bento et al. 2024 *Neurocomputing*.)",
+  "logic/heaps-deviation": "Inspect for LLM-style vocabulary patterns: this file's vocabulary grows faster (high Heaps \u03BB) or slower (low \u03BB) than typical source code. Verify authorship if unexpected. (v0.12.0 \u2014 Christ et al. EMNLP Findings 2025.)",
+  "logic/ks-distribution-shift": "Inspect the shifted features. KS detects both AI anomalies and production-rot anomalies (it is symmetric); combine with Heaps/Zipf for AI-specific signal. (v0.12.0 \u2014 arXiv:2510.15996, Oct 2025.)",
+  "logic/zipf-slope-anomaly": "Inspect for LLM-style frequency distribution: this file's identifier usage is more peaked or flatter than typical human code. (v0.12.0 \u2014 Christ et al. EMNLP Findings 2025.)",
+  "logic/math-any-density": "Replace `: any` with proper types. Start with the parameter/return types of the most-used functions.",
+  "logic/math-console-log-storm": "Replace debug logs with a proper debugger or logger.debug(). Remove all console.log before shipping.",
+  "logic/math-gini-class-usage": "Spread usage across more class tokens instead of repeating the same handful (p-4, p-8, rounded-lg, etc.).",
+  "logic/math-variable-name-entropy": "Use domain-specific identifier names (reservations, invoices, customers) instead of generic data/items/value.",
+  "logic/optimistic-no-rollback": "In optimistic updates, revert state in the catch block: `setX(prev => prev)`. Never leave stale UI on error.",
+  "logic/qwik-hook-leak": "Use Qwik primitives ($state, $effect, useSignal) instead of React hooks (useState, useEffect).",
+  "logic/reactive-hook-soup": "Coordinate state via a single derived value (useMemo) or a state machine. Avoid chained useEffects that sync local state.",
+  "logic/zombie-state": "Remove unused useState or wire it into the component. Don't leave declared-but-never-read state bindings.",
+  "perf/cls-image": "Add width/height attributes or an aspect-ratio utility to prevent layout shift.",
+  "perf/css-bloat": "Extract to a CSS variable (`--surface-card`) or a component prop when a class string repeats 5+ times.",
+  "perf/halstead-anomaly": "Introduce domain-specific identifiers and varied operations. Low vocabulary per line is a strong AI signature (Halstead 1977 \xA73).",
+  "typo/calc-fontsize": "Use a design token (`var(--font-size-lg)`) or `clamp(min, fluid, max)` for responsive typography.",
+  "typo/calc-raw-px": "Replace px values in calc() with rem or em units for scalable layout.",
+  "typo/clamp-offscale": "Anchor clamp() values to standard sizes (12, 14, 16, 18, 20, 24, 30, 36, 48) so they remain on the design grid.",
+  "typo/math-button-label-uniformity": 'Mix button lengths deliberately \u2014 pair a short "Save" with a longer "Mark as complete" \u2014 instead of repeating the same template.',
+  "typo/math-cta-vocabulary": 'Use domain-specific action verbs ("Reserve", "Confirm ride", "Activate card") instead of falling back on the AI-default CTA vocabulary.',
+  "visual/clamp-soup": "Use design-system aliases (`--text-fluid-sm`, `--text-fluid-lg`) with bounded ranges (typically 2\xD7 max).",
+  "visual/generic-centering": "Vary hero layouts: some as grids (`grid place-items-center`), some as blocks, some with different alignment.",
+  "visual/inline-style-dominance": "Replace inline `style={{...}}` with className utilities (e.g. Tailwind `p-4 m-2 gap-3`) or a CSS module class.",
+  "visual/math-default-font": "Import a distinctive font (next/font/google, @font-face, or a CSS variable) instead of relying on the framework default.",
+  "visual/math-font-entropy": "Use a wider range of text sizes (text-xs, text-sm, text-lg, text-xl, text-2xl, text-3xl) for a more deliberate type scale.",
+  "visual/math-gradient-hue-rotation": "Use wider hue spans across gradients (e.g. blue\u2192amber, emerald\u2192indigo) to break the violet-fuchsia monotony.",
+  "visual/math-rounded-entropy": "Use a wider range of border-radius values (sm, md, 2xl, 3xl) instead of repeating the same lg/xl/full pattern.",
+  "visual/math-spacing-entropy": "Mix more spacing values from the design scale (e.g. 3, 5, 7, 10, 14, 20, 28) instead of repeating the same 4/8 pattern.",
+  "visual/naturalness-anomaly": "Use domain-specific identifier names so the identifier stream reflects the actual problem domain. Hindle 2012 \xA74.3: LLM-generated code reuses a narrow band of training-data identifiers, dropping distinct-token ratio below 30%.",
+  "visual/math-color-cluster": "Use at least 3 distinct hue families (e.g. blue + amber + green) instead of clustering every color in the violet/fuchsia band.",
+  "wcag/dragging-movements": "Provide an onClick, onKeyDown, or button role as an alternative to dragging (WCAG 2.1.1).",
+  "wcag/focus-appearance": "Add a focus-visible:ring-* class, or remove outline-none. Keyboard users need a visible focus indicator.",
+  "wcag/focus-obscured": "Ensure focused elements are not hidden behind fixed or sticky wrappers.",
+  "wcag/target-size": "Add h-*, w-*, p-*, min-w-*, min-h-*, size-*, or an explicit width/height attribute to bring the target to \u2265 24\xD724 px.",
+  "test/weak-assertion": "Assert on a specific value or shape: `expect(x).toEqual(expectedValue)`. Avoid `.toBeDefined()` / `.toBeTruthy()` placeholders and tautological `expect(x).toBe(x)`.",
+  "test/duplicate-setup": "Extract shared `beforeEach` / `setupServer` blocks into a single helper (e.g. `renderWithProviders`) so each describe block calls it instead of repeating setup.",
+  "test/missing-edge-case": "When generating tests, cover the alternate path: `else` branches, `catch` blocks, ternary alternates, and `??` fallbacks. Production branches without tests are a CI smell.",
+  "test/fake-placeholder": "Use domain-specific fixture values (`alice@acme-corp.com`, `Order#48231`) or a factory like @faker-js/faker. Avoid textbook placeholders (`John Doe`, `test@test.com`, `id: 1`).",
+  "product/terminology-drift": "Keep the leading noun consistent across files: `PostList`, `PostDetail`, `PostCard` are one entity, not three. AI agents pick slightly different words each invocation; product copy drifts.",
+  "product/ux-pattern-fragmentation": "Keep the per-category count tight: modal \u22643, toast \u22642, button \u22644, input \u22643, card \u22643. Pick the canonical one and alias the rest. `slopbrick patterns` reports the per-category count.",
+  // v0.13.0 — AI-specific rules (peer-reviewed signals).
+  "ai/markdown-leakage": "Delete stray `\\`\\`\\`<lang>\\`\\`\\`` markers; they are Markdown fences, not valid syntax in standalone source files (Yotkova et al. SemEval-2026).",
+  "ai/comment-ratio": "AI tools either skip comments (reductive models) or over-comment (expansive models). Match the corpus mean \xB1 2\u03C3 (Rahman et al. 2024, Bisztray et al. 2025).",
+  "ai/whitespace-regularity": "Vary inter-token spacing (single spaces mostly, occasional alignment in tables). Uniform runs are an AI tell (Shi et al. DetectCodeGPT 2024).",
+  "ai/text-like-ratio": "Move natural-language explanations to README files or doc comments. Inline prose in source code is hard to maintain (Yotkova 2026).",
+  "ai/errors-near-eof": "Check whether the file was truncated by a token limit. Unbalanced delimiters near EOF suggest the model ran out of output budget (Yotkova 2026).",
+  "ai/any-density": "Replace `any` with `unknown`, `Record<string, unknown>`, or a domain type. The `: any` annotation propagates type-errors and defeats TS safety (Lee, Hassan, Hindle MSR 2026).",
+  "ai/renyi-profile": "The token distribution is mass-concentrated on a few high-frequency tokens. Verify authorship if unexpected (R\xE9nyi 1961, Moslonka 2025).",
+  "ai/log-rank-histogram": "The token vocabulary is concentrated in the top-1000 most common tokens. Real codebases use more diverse identifiers (Gehrmann 2019 GLTR).",
+  "ai/segment-surprisal-cv": "The cross-entropy is suspiciously uniform across the file. Real codebases have varied registers (Binoculars, Hans 2024).",
+  "ai/compression-profile": "The file compresses unusually well and lines are highly repetitive \u2014 characteristic of AI-generated boilerplate (Cilibrasi 2005, Mahoney 1999).",
+  // v0.14.5b — 6 new AI tendency detection rules (DORMANT in v0.14.5b;
+  // reclassified post-v7 calibration in v0.14.5d)
+  "ai/tailwind-color-overuse": "If most utility classes are bg-violet-500, text-violet-600, ring-violet-400 \u2014 the project is on the AI-default palette. Audit and replace with the project's design tokens.",
+  "ai/default-react-stack": "Every new file is a Vite + React + Tailwind + Zustand + React Hook Form clone. Verify the project actually needs each piece before adding it.",
+  "ai/library-reinvention": "Re-implementing zustand, react-hook-form, or date-fns inline (custom event emitters, useState reducers, manual date math) is a sign of LLM completion-mode code. Use the libraries the project already depends on.",
+  "ai/state-default-overuse": "Wrapping every component in useState + useEffect for transient UI state is the React tutorial default. Real production code uses refs, uncontrolled inputs, or the project's state lib.",
+  "ai/fetch-default-overuse": "Calling fetch() inline in components instead of going through the project's data-fetching layer (react-query, swr, or your own client) bypasses the cache, error boundary, and abort handling.",
+  "ai/console-debug-storm": "5+ console.log calls in a single file is debug-by-print-statement, the LLM training-data default. Remove before commit; use the project's logger or a real debugger.",
+  // v0.17.0 — db/* rules (Postgres static analysis via pgsql-parser)
+  "db/missing-fk-index": "Add `CREATE INDEX ON <table> (<fk_column>);` for every foreign key column. Without it, parent deletes do a sequential scan on the child. Use `CREATE INDEX CONCURRENTLY` in production (Squawk `require-concurrent-index-creation`).",
+  "db/duplicate-index": "Drop one of two indexes that cover the same column list \u2014 extra indexes slow writes without read benefit. Postgres does not warn about this; the duplicate will silently sit in production.",
+  "db/missing-not-null": "Add `NOT NULL` (or `PRIMARY KEY`) on required-identifier columns (id, email, created_at, status, uuid, \u2026). Optional identifiers are a common AI-generated SQL smell that produces silent NULL inserts in production.",
+  "db/enum-sprawl": "Enums with more than 12 values are brittle to extend and hard to localize. Move to a lookup table joined by foreign key.",
+  "db/naming-inconsistency": "Standardize on snake_case (Postgres convention) or camelCase, but never mix both in the same schema. Mixed styles break ORM generators and confuse code-reviewers.",
+  "db/sql-concat": 'Never build SQL with template-literal interpolation \u2014 `db.query(`SELECT \u2026 WHERE id = ${id}`)` is a SQL injection vector. Use parameterized queries (`db.query("\u2026 WHERE id = $1", [id])`) or your ORM query builder.',
+  // v0.17.0 — docs/* rules (markdown drift detection)
+  "docs/stale-package-reference": "Update the doc to reference an installed package, or add the package to package.json. Copy-pasted install commands from a previous project are the #1 doc-drift failure mode.",
+  "docs/stale-function-reference": "Rename the doc reference to match a current export, or add a wrapper export. Stale function callouts in tutorials cost readers 10+ minutes of debugging.",
+  "docs/expired-code-example": "Update the example to use a declared dependency, or add the package to package.json. A copy-pasteable example that does not install erodes trust in the whole docs site.",
+  "docs/broken-link": "Create the file or fix the link target. On a public docs site, broken links erode trust more than stale copy."
+};
+
+// src/cli/commands/explain.ts
+function registerExplain(program) {
+  program.command("explain <ruleId>").description("Print rationale, pattern, and remediation for a single rule").action((ruleId) => {
+    const result = explainRule(ruleId, builtinRules, RULE_HINTS);
+    logger.info(formatExplain(result));
+    if ("error" in result) process.exit(2);
+  });
+}
+
 // src/cli/program.ts
 init_config();
 init_git();
@@ -55325,7 +55554,7 @@ function createProvider(config) {
 
 // src/research/generator.ts
 var import_node_fs36 = require("fs");
-var import_node_path38 = require("path");
+var import_node_path40 = require("path");
 
 // src/research/prompts.ts
 var DEFAULT_PROMPT_TEMPLATES = [
@@ -55388,13 +55617,13 @@ async function generateSamples(options) {
   }
   const samples = [];
   const ext = extForFramework(framework);
-  const dir = (0, import_node_path38.join)(outputDir, framework, componentType);
+  const dir = (0, import_node_path40.join)(outputDir, framework, componentType);
   (0, import_node_fs36.mkdirSync)(dir, { recursive: true });
   for (let i = 1; i <= count; i += 1) {
     const raw = await provider.generateSample(renderPrompt(template), { temperature });
     const code = extractCodeFromMarkdown(raw);
     const fileName = `sample-${i}${ext}`;
-    const filePath = (0, import_node_path38.join)(dir, fileName);
+    const filePath = (0, import_node_path40.join)(dir, fileName);
     (0, import_node_fs36.writeFileSync)(filePath, code, "utf8");
     const sample = {
       filePath,
@@ -55406,7 +55635,7 @@ async function generateSamples(options) {
     };
     samples.push(sample);
   }
-  const metadataPath = (0, import_node_path38.join)(dir, "metadata.json");
+  const metadataPath = (0, import_node_path40.join)(dir, "metadata.json");
   (0, import_node_fs36.writeFileSync)(metadataPath, JSON.stringify(samples, null, 2), "utf8");
   return samples;
 }
@@ -55614,11 +55843,11 @@ function slugify(value) {
 // src/research/calibrator.ts
 var import_node_child_process3 = require("child_process");
 var import_node_fs37 = require("fs");
-var import_node_path39 = require("path");
+var import_node_path41 = require("path");
 var DEFAULT_POSITIVE = "/Users/cheng/ai-slop-baseline/extracted/positive";
 var DEFAULT_NEGATIVE = "/Users/cheng/ai-slop-baseline/extracted/negative";
 function buildFileList(dir, extensions) {
-  const tmpList = (0, import_node_path39.join)("/tmp", `cal-build-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
+  const tmpList = (0, import_node_path41.join)("/tmp", `cal-build-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
   const expr = extensions.map((e) => `-name '*.${e}'`).join(" -o ");
   (0, import_node_child_process3.execFileSync)("bash", ["-c", `find ${dir} -maxdepth 8 -type f \\( ${expr} \\) -print0 | xargs -0 realpath > ${tmpList}`]);
   const out = (0, import_node_fs37.readFileSync)(tmpList, "utf8");
@@ -55631,13 +55860,13 @@ function runScan2(fileListPath) {
   const ruleFires = /* @__PURE__ */ new Map();
   const uniqueFilesPerRule = /* @__PURE__ */ new Map();
   let fileCount = 0;
-  const tmpOut = (0, import_node_path39.join)("/tmp", `calibrate-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  const tmpOut = (0, import_node_path41.join)("/tmp", `calibrate-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
   for (let i = 0; i < files.length; i += CHUNK) {
     const chunk = files.slice(i, i + CHUNK);
     try {
       (0, import_node_child_process3.execFileSync)(
         "node",
-        [(0, import_node_path39.join)(process.cwd(), "bin", "slopbrick.js"), "scan", ...chunk, "--json", tmpOut, "--no-telemetry", "--quiet"],
+        [(0, import_node_path41.join)(process.cwd(), "bin", "slopbrick.js"), "scan", ...chunk, "--json", tmpOut, "--no-telemetry", "--quiet"],
         { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
       );
     } catch {
@@ -55677,8 +55906,8 @@ async function calibrate(cwd, options = {}) {
   const negativeFiles = buildFileList(negativeDir, ["tsx", "ts"]);
   const posSample = options.positiveLimit ? positiveFiles.slice(0, options.positiveLimit) : positiveFiles;
   const negSample = options.negativeLimit ? negativeFiles.slice(0, options.negativeLimit) : negativeFiles;
-  const posListPath = (0, import_node_path39.join)("/tmp", `cal-pos-${Date.now()}.txt`);
-  const negListPath = (0, import_node_path39.join)("/tmp", `cal-neg-${Date.now()}.txt`);
+  const posListPath = (0, import_node_path41.join)("/tmp", `cal-pos-${Date.now()}.txt`);
+  const negListPath = (0, import_node_path41.join)("/tmp", `cal-neg-${Date.now()}.txt`);
   (0, import_node_fs37.writeFileSync)(posListPath, posSample.join("\n"));
   (0, import_node_fs37.writeFileSync)(negListPath, negSample.join("\n"));
   const builtins = await Promise.resolve().then(() => (init_builtins(), builtins_exports));
@@ -55947,7 +56176,7 @@ function errorResponse(id, code, message, data2) {
   return { jsonrpc: "2.0", id, error: { code, message, ...data2 !== void 0 ? { data: data2 } : {} } };
 }
 async function runMcpServer(input, output, cwd) {
-  return new Promise((resolve18) => {
+  return new Promise((resolve20) => {
     let buffer = "";
     input.setEncoding("utf-8");
     input.on("data", (chunk) => {
@@ -55985,138 +56214,13 @@ async function runMcpServer(input, output, cwd) {
         nlIdx = buffer.indexOf("\n");
       }
     });
-    input.on("end", () => resolve18());
-    input.on("close", () => resolve18());
+    input.on("end", () => resolve20());
+    input.on("close", () => resolve20());
   });
 }
 
-// src/snippet/data.ts
-var CATEGORY_DIRECTIVES = {
-  visual: 'Avoid the saturated "vibe purple" Tailwind palette (violet-400-700, indigo-400-700). Prefer emerald, sky, amber, rose for accents. Never use arbitrary color values like bg-[#7c3aed] when a token exists.',
-  logic: "Never use explicit `any`. Use `unknown` and narrow. Always add an AbortSignal to fetches. Handle errors with try/catch, never swallow with empty catch. Use `as const` instead of `as Type` casts.",
-  wcag: 'All form inputs must have an accessible label (visible <label>, aria-label, or aria-labelledby). Decorative images must have empty alt="". Buttons must be <button>, never <div onClick>. Touch targets must be \u2265 24\xD724 CSS px.',
-  security: 'Never store tokens in localStorage or sessionStorage \u2014 use httpOnly Secure SameSite cookies. Never put secrets in NEXT_PUBLIC_* / REACT_APP_* / VITE_* env vars. Validate e.origin in postMessage handlers. Never dangerouslySetInnerHTML with user input. Never use target="_blank" without rel="noopener".',
-  perf: "Always use AbortController with fetch. Use image width/height attributes to prevent CLS. Use <Suspense> around async client components. Don't load all images eagerly.",
-  typo: `Never leave TODO / placeholder / "change me" copy in shipped code. Use real i18n strings or the project's content map.`,
-  layout: "Don't stack badge-above-h1 hero patterns. Don't build 3-stat banner rows without explicit user request. Don't use emoji inside nav items (use SVG icons). Use the project's spacing scale (4px or 8px grid), never arbitrary values like p-[13px].",
-  component: "Don't build components > 200 lines. Extract shared subcomponents. Avoid circular prop drilling \u2014 use context.",
-  arch: "For Astro: server-render everything by default; only opt-in to client islands when you need interactivity. Don't put secrets in client-side code.",
-  test: "Use domain-specific fixture data, assert on value shapes not just truthiness, and consolidate repeated setup into helpers. Avoid `expect(x).toBeDefined()` placeholders and textbook fixtures like 'John Doe' or 'test@test.com'."
-};
-var RULE_HINTS = {
-  // v0.16.0 hygiene: 35 out-of-scope orphan hints (keys with no matching
-  // rule in src/rules/builtins.ts) were moved out of this map. The
-  // verbatim source text is preserved in
-  //   docs/research/backlog-rule-hints.md
-  // so future implementers can paste a hint back when the corresponding
-  // rule ships. The 5 in-scope orphans (`security/eval`,
-  // `security/localstorage-token`, `security/target-blank-no-noopener`,
-  // `wcag/missing-alt`, `typo/placeholder-text`) are kept here for v0.16.0.
-  "security/hardcoded-secret": "Never inline API keys, JWT secrets, or database passwords in source. Load them from env vars and never commit a .env file. Assume any published secret is compromised and rotate it.",
-  "security/exposed-env-var": "NEVER prefix a secret with NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_, GATSBY_, or PUBLIC_ \u2014 those vars are inlined into every browser build.",
-  "security/dangerous-cors": "Don't set Access-Control-Allow-Origin: * on production endpoints. Restrict to an explicit allowlist; never combine wildcard origin with credentials: true.",
-  "security/missing-auth-check": "Every server route handler must perform an authentication + authorization check at the top. Reachability of an endpoint by any user (authenticated or not) is a vulnerability, not a feature.",
-  "security/unsafe-html-render": "Sanitize any non-literal value passed to dangerouslySetInnerHTML with DOMPurify. Better: avoid the prop entirely and let React escape via children.",
-  "security/fail-open-auth": "Don't gate auth bypasses on NODE_ENV. Replace dev-env checks with an explicit AUTH_BYPASS flag that's never set in production.",
-  "security/sql-construction": 'Never build SQL with string concatenation or template-literal interpolation. Use parameterized queries: pg client.query("... WHERE id = $1", [id]) or your ORM query builder.',
-  "security/public-admin-route": "Routes under /admin, /internal, /debug, /staff, /manage, /private need an explicit role check on top of standard auth \u2014 auth alone is not enough for privileged paths.",
-  "visual/arbitrary-escape": "Never use bracket-notation values like text-[13px] or bg-[#7c3aed]. Use design tokens instead.",
-  "visual/spacing-scale-violation": "Use spacing scale tokens (p-2, gap-4, etc.) instead of arbitrary values like p-[13px] or gap-[1.75rem].",
-  "visual/radius-scale-violation": "Use radius scale tokens (rounded-md, rounded-lg, etc.) instead of arbitrary values like rounded-[7px].",
-  // v0.16.0 — in-scope orphans kept here (corresponding rule ships in v0.16.0).
-  "typo/placeholder-text": 'Never leave "TODO", "placeholder", "change me", "your text here" in shipped UI.',
-  "logic/key-prop-missing": "Always provide a stable `key` prop when rendering lists.",
-  "logic/boundary-violation": "Don't import data-layer / DB code into UI components. Server-side only.",
-  "wcag/missing-alt": 'Every <img> needs alt text. Decorative: alt="". Informative: describe the image.',
-  "security/localstorage-token": "Never store JWT / access token / refresh token in localStorage or sessionStorage. Issue as httpOnly cookie.",
-  "security/eval": "Never use eval() or new Function(). These are RCE vectors if the input is ever attacker-controlled.",
-  "security/target-blank-no-noopener": 'Always add rel="noopener" (or rel="noreferrer") to target="_blank" links.',
-  "arch/astro-island-leak": "For Astro: server-render everything by default. Only opt-in to client islands when interactivity is needed.",
-  "component/giant-component": "Don't build components > 200 lines. Extract shared subcomponents.",
-  "component/multiple-components-per-file": "One component per file. Move subcomponents into their own files so the Context Window stays small and boundary tests are easy.",
-  "component/shadcn-prop-mismatch": "Select shadcn variants via the `variant` prop, not long `className` overrides. See the component registry for available variants.",
-  "context/import-path-mismatch": "Use only the canonical import paths declared in brick.config.json (e.g. @/components/ui/, @/lib/).",
-  "layout/forced-layout": "Vary structural patterns: some containers as grids, some as horizontal flex, some as blocks. Don't repeat `flex flex-col gap-4` everywhere.",
-  "layout/gap-monopoly": "Mix gap-2 / gap-4 / gap-6 / gap-12 deliberately. Don't repeat the same gap value across the whole project.",
-  "layout/math-element-uniformity": "Human files have lopsided interactive counts (1 button + 12 inputs). AI tends to balance them. Build forms with many inputs and few buttons.",
-  "layout/math-grid-uniformity": "Vary grid-cols-N (grid-cols-2, grid-cols-3, grid-cols-4, grid-cols-6) across sections instead of repeating grid-cols-3.",
-  "layout/spacing-grid": "Use the configured spacing scale (4px or 8px grid). Avoid arbitrary values like p-[13px] that aren't on the scale.",
-  "logic/ghost-defensive": "Use optional chaining (?.) or early returns instead of deep && guards. If a defensive chain runs 3+ levels deep, refactor.",
-  "logic/bayesian-conditional": "The Bayesian combiner aggregates multiple weak signals into a calibrated posterior P(AI|fires). Treat any fire above 0.7 as evidence of AI authorship; above 0.9 as strong evidence. (v0.12.0 \u2014 Bento et al. 2024 *Neurocomputing*.)",
-  "logic/heaps-deviation": "Inspect for LLM-style vocabulary patterns: this file's vocabulary grows faster (high Heaps \u03BB) or slower (low \u03BB) than typical source code. Verify authorship if unexpected. (v0.12.0 \u2014 Christ et al. EMNLP Findings 2025.)",
-  "logic/ks-distribution-shift": "Inspect the shifted features. KS detects both AI anomalies and production-rot anomalies (it is symmetric); combine with Heaps/Zipf for AI-specific signal. (v0.12.0 \u2014 arXiv:2510.15996, Oct 2025.)",
-  "logic/zipf-slope-anomaly": "Inspect for LLM-style frequency distribution: this file's identifier usage is more peaked or flatter than typical human code. (v0.12.0 \u2014 Christ et al. EMNLP Findings 2025.)",
-  "logic/math-any-density": "Replace `: any` with proper types. Start with the parameter/return types of the most-used functions.",
-  "logic/math-console-log-storm": "Replace debug logs with a proper debugger or logger.debug(). Remove all console.log before shipping.",
-  "logic/math-gini-class-usage": "Spread usage across more class tokens instead of repeating the same handful (p-4, p-8, rounded-lg, etc.).",
-  "logic/math-variable-name-entropy": "Use domain-specific identifier names (reservations, invoices, customers) instead of generic data/items/value.",
-  "logic/optimistic-no-rollback": "In optimistic updates, revert state in the catch block: `setX(prev => prev)`. Never leave stale UI on error.",
-  "logic/qwik-hook-leak": "Use Qwik primitives ($state, $effect, useSignal) instead of React hooks (useState, useEffect).",
-  "logic/reactive-hook-soup": "Coordinate state via a single derived value (useMemo) or a state machine. Avoid chained useEffects that sync local state.",
-  "logic/zombie-state": "Remove unused useState or wire it into the component. Don't leave declared-but-never-read state bindings.",
-  "perf/cls-image": "Add width/height attributes or an aspect-ratio utility to prevent layout shift.",
-  "perf/css-bloat": "Extract to a CSS variable (`--surface-card`) or a component prop when a class string repeats 5+ times.",
-  "perf/halstead-anomaly": "Introduce domain-specific identifiers and varied operations. Low vocabulary per line is a strong AI signature (Halstead 1977 \xA73).",
-  "typo/calc-fontsize": "Use a design token (`var(--font-size-lg)`) or `clamp(min, fluid, max)` for responsive typography.",
-  "typo/calc-raw-px": "Replace px values in calc() with rem or em units for scalable layout.",
-  "typo/clamp-offscale": "Anchor clamp() values to standard sizes (12, 14, 16, 18, 20, 24, 30, 36, 48) so they remain on the design grid.",
-  "typo/math-button-label-uniformity": 'Mix button lengths deliberately \u2014 pair a short "Save" with a longer "Mark as complete" \u2014 instead of repeating the same template.',
-  "typo/math-cta-vocabulary": 'Use domain-specific action verbs ("Reserve", "Confirm ride", "Activate card") instead of falling back on the AI-default CTA vocabulary.',
-  "visual/clamp-soup": "Use design-system aliases (`--text-fluid-sm`, `--text-fluid-lg`) with bounded ranges (typically 2\xD7 max).",
-  "visual/generic-centering": "Vary hero layouts: some as grids (`grid place-items-center`), some as blocks, some with different alignment.",
-  "visual/inline-style-dominance": "Replace inline `style={{...}}` with className utilities (e.g. Tailwind `p-4 m-2 gap-3`) or a CSS module class.",
-  "visual/math-default-font": "Import a distinctive font (next/font/google, @font-face, or a CSS variable) instead of relying on the framework default.",
-  "visual/math-font-entropy": "Use a wider range of text sizes (text-xs, text-sm, text-lg, text-xl, text-2xl, text-3xl) for a more deliberate type scale.",
-  "visual/math-gradient-hue-rotation": "Use wider hue spans across gradients (e.g. blue\u2192amber, emerald\u2192indigo) to break the violet-fuchsia monotony.",
-  "visual/math-rounded-entropy": "Use a wider range of border-radius values (sm, md, 2xl, 3xl) instead of repeating the same lg/xl/full pattern.",
-  "visual/math-spacing-entropy": "Mix more spacing values from the design scale (e.g. 3, 5, 7, 10, 14, 20, 28) instead of repeating the same 4/8 pattern.",
-  "visual/naturalness-anomaly": "Use domain-specific identifier names so the identifier stream reflects the actual problem domain. Hindle 2012 \xA74.3: LLM-generated code reuses a narrow band of training-data identifiers, dropping distinct-token ratio below 30%.",
-  "visual/math-color-cluster": "Use at least 3 distinct hue families (e.g. blue + amber + green) instead of clustering every color in the violet/fuchsia band.",
-  "wcag/dragging-movements": "Provide an onClick, onKeyDown, or button role as an alternative to dragging (WCAG 2.1.1).",
-  "wcag/focus-appearance": "Add a focus-visible:ring-* class, or remove outline-none. Keyboard users need a visible focus indicator.",
-  "wcag/focus-obscured": "Ensure focused elements are not hidden behind fixed or sticky wrappers.",
-  "wcag/target-size": "Add h-*, w-*, p-*, min-w-*, min-h-*, size-*, or an explicit width/height attribute to bring the target to \u2265 24\xD724 px.",
-  "test/weak-assertion": "Assert on a specific value or shape: `expect(x).toEqual(expectedValue)`. Avoid `.toBeDefined()` / `.toBeTruthy()` placeholders and tautological `expect(x).toBe(x)`.",
-  "test/duplicate-setup": "Extract shared `beforeEach` / `setupServer` blocks into a single helper (e.g. `renderWithProviders`) so each describe block calls it instead of repeating setup.",
-  "test/missing-edge-case": "When generating tests, cover the alternate path: `else` branches, `catch` blocks, ternary alternates, and `??` fallbacks. Production branches without tests are a CI smell.",
-  "test/fake-placeholder": "Use domain-specific fixture values (`alice@acme-corp.com`, `Order#48231`) or a factory like @faker-js/faker. Avoid textbook placeholders (`John Doe`, `test@test.com`, `id: 1`).",
-  "product/terminology-drift": "Keep the leading noun consistent across files: `PostList`, `PostDetail`, `PostCard` are one entity, not three. AI agents pick slightly different words each invocation; product copy drifts.",
-  "product/ux-pattern-fragmentation": "Keep the per-category count tight: modal \u22643, toast \u22642, button \u22644, input \u22643, card \u22643. Pick the canonical one and alias the rest. `slopbrick patterns` reports the per-category count.",
-  // v0.13.0 — AI-specific rules (peer-reviewed signals).
-  "ai/markdown-leakage": "Delete stray `\\`\\`\\`<lang>\\`\\`\\`` markers; they are Markdown fences, not valid syntax in standalone source files (Yotkova et al. SemEval-2026).",
-  "ai/comment-ratio": "AI tools either skip comments (reductive models) or over-comment (expansive models). Match the corpus mean \xB1 2\u03C3 (Rahman et al. 2024, Bisztray et al. 2025).",
-  "ai/whitespace-regularity": "Vary inter-token spacing (single spaces mostly, occasional alignment in tables). Uniform runs are an AI tell (Shi et al. DetectCodeGPT 2024).",
-  "ai/text-like-ratio": "Move natural-language explanations to README files or doc comments. Inline prose in source code is hard to maintain (Yotkova 2026).",
-  "ai/errors-near-eof": "Check whether the file was truncated by a token limit. Unbalanced delimiters near EOF suggest the model ran out of output budget (Yotkova 2026).",
-  "ai/any-density": "Replace `any` with `unknown`, `Record<string, unknown>`, or a domain type. The `: any` annotation propagates type-errors and defeats TS safety (Lee, Hassan, Hindle MSR 2026).",
-  "ai/renyi-profile": "The token distribution is mass-concentrated on a few high-frequency tokens. Verify authorship if unexpected (R\xE9nyi 1961, Moslonka 2025).",
-  "ai/log-rank-histogram": "The token vocabulary is concentrated in the top-1000 most common tokens. Real codebases use more diverse identifiers (Gehrmann 2019 GLTR).",
-  "ai/segment-surprisal-cv": "The cross-entropy is suspiciously uniform across the file. Real codebases have varied registers (Binoculars, Hans 2024).",
-  "ai/compression-profile": "The file compresses unusually well and lines are highly repetitive \u2014 characteristic of AI-generated boilerplate (Cilibrasi 2005, Mahoney 1999).",
-  // v0.14.5b — 6 new AI tendency detection rules (DORMANT in v0.14.5b;
-  // reclassified post-v7 calibration in v0.14.5d)
-  "ai/tailwind-color-overuse": "If most utility classes are bg-violet-500, text-violet-600, ring-violet-400 \u2014 the project is on the AI-default palette. Audit and replace with the project's design tokens.",
-  "ai/default-react-stack": "Every new file is a Vite + React + Tailwind + Zustand + React Hook Form clone. Verify the project actually needs each piece before adding it.",
-  "ai/library-reinvention": "Re-implementing zustand, react-hook-form, or date-fns inline (custom event emitters, useState reducers, manual date math) is a sign of LLM completion-mode code. Use the libraries the project already depends on.",
-  "ai/state-default-overuse": "Wrapping every component in useState + useEffect for transient UI state is the React tutorial default. Real production code uses refs, uncontrolled inputs, or the project's state lib.",
-  "ai/fetch-default-overuse": "Calling fetch() inline in components instead of going through the project's data-fetching layer (react-query, swr, or your own client) bypasses the cache, error boundary, and abort handling.",
-  "ai/console-debug-storm": "5+ console.log calls in a single file is debug-by-print-statement, the LLM training-data default. Remove before commit; use the project's logger or a real debugger.",
-  // v0.17.0 — db/* rules (Postgres static analysis via pgsql-parser)
-  "db/missing-fk-index": "Add `CREATE INDEX ON <table> (<fk_column>);` for every foreign key column. Without it, parent deletes do a sequential scan on the child. Use `CREATE INDEX CONCURRENTLY` in production (Squawk `require-concurrent-index-creation`).",
-  "db/duplicate-index": "Drop one of two indexes that cover the same column list \u2014 extra indexes slow writes without read benefit. Postgres does not warn about this; the duplicate will silently sit in production.",
-  "db/missing-not-null": "Add `NOT NULL` (or `PRIMARY KEY`) on required-identifier columns (id, email, created_at, status, uuid, \u2026). Optional identifiers are a common AI-generated SQL smell that produces silent NULL inserts in production.",
-  "db/enum-sprawl": "Enums with more than 12 values are brittle to extend and hard to localize. Move to a lookup table joined by foreign key.",
-  "db/naming-inconsistency": "Standardize on snake_case (Postgres convention) or camelCase, but never mix both in the same schema. Mixed styles break ORM generators and confuse code-reviewers.",
-  "db/sql-concat": 'Never build SQL with template-literal interpolation \u2014 `db.query(`SELECT \u2026 WHERE id = ${id}`)` is a SQL injection vector. Use parameterized queries (`db.query("\u2026 WHERE id = $1", [id])`) or your ORM query builder.',
-  // v0.17.0 — docs/* rules (markdown drift detection)
-  "docs/stale-package-reference": "Update the doc to reference an installed package, or add the package to package.json. Copy-pasted install commands from a previous project are the #1 doc-drift failure mode.",
-  "docs/stale-function-reference": "Rename the doc reference to match a current export, or add a wrapper export. Stale function callouts in tutorials cost readers 10+ minutes of debugging.",
-  "docs/expired-code-example": "Update the example to use a declared dependency, or add the package to package.json. A copy-pasteable example that does not install erodes trust in the whole docs site.",
-  "docs/broken-link": "Create the file or fix the link target. On a public docs site, broken links erode trust more than stale copy."
-};
-
 // src/snippet/targets.ts
-var import_node_path41 = require("path");
+var import_node_path43 = require("path");
 
 // src/snippet/render.ts
 function aiSpecificRules(rules) {
@@ -56347,7 +56451,7 @@ var SNIPPET_TARGETS = [
   }
 ];
 function resolveTargetPath(target) {
-  return target.isFolder ? (0, import_node_path41.join)(target.path, target.filename) : target.path;
+  return target.isFolder ? (0, import_node_path43.join)(target.path, target.filename) : target.path;
 }
 function renderMatrix() {
   const lines = [];
@@ -56361,52 +56465,6 @@ function renderMatrix() {
   return lines.join("\n");
 }
 
-// src/cli/explain.ts
-var RULES_BASE_URL2 = "https://github.com/Dystx/slopbrick/blob/main/src/rules";
-function ruleIdToFilename2(ruleId) {
-  const slash = ruleId.indexOf("/");
-  return slash === -1 ? ruleId : ruleId.slice(slash + 1);
-}
-function explainRule2(ruleId, rules, ruleHints) {
-  const rule = rules.find((r) => r.id === ruleId);
-  if (!rule) {
-    return { error: "Unknown rule: " + ruleId + ". Run `slopbrick rules` to see all available rules." };
-  }
-  const filename = ruleIdToFilename2(rule.id);
-  return {
-    ruleId: rule.id,
-    category: rule.category,
-    severity: rule.severity,
-    aiSpecific: rule.aiSpecific,
-    pattern: ruleHints[rule.id] ?? "Patterns flagged by " + rule.id + ".",
-    remediation: "See the rule source for the canonical before/after: src/rules/" + rule.category + "/" + filename + ".ts",
-    sourcePath: "src/rules/" + rule.category + "/" + filename + ".ts",
-    helpUri: `${RULES_BASE_URL2}/${rule.category}/${filename}.ts`,
-    suppressionSnippet: 'rules: { "' + rule.id + '": "off" }  // or set to a lower severity'
-  };
-}
-function formatExplain(result) {
-  if ("error" in result) return result.error;
-  const lines = [];
-  lines.push("Rule:        " + result.ruleId);
-  lines.push("Category:    " + result.category);
-  lines.push("Severity:    " + result.severity);
-  lines.push("AI-specific: " + (result.aiSpecific ? "yes (designed to fire on AI tells)" : "no (cross-cutting quality rule)"));
-  lines.push("Source:      " + result.sourcePath);
-  lines.push("Help:        " + result.helpUri);
-  lines.push("");
-  lines.push("Pattern:");
-  lines.push("  " + result.pattern);
-  lines.push("");
-  lines.push("Remediation:");
-  lines.push("  " + result.remediation);
-  lines.push("");
-  lines.push("Suppress / configure in slopbrick.config.mjs:");
-  lines.push("  " + result.suppressionSnippet);
-  lines.push("");
-  return lines.join("\n");
-}
-
 // src/cli/program.ts
 init_validation();
 init_signal_strength2();
@@ -56564,13 +56622,12 @@ function formatMarkdown3(report) {
 }
 
 // src/cli/program.ts
-init_advice();
 init_unified_diff();
 init_heatmap();
 
 // src/report/flywheel.ts
 var import_node_fs39 = require("fs");
-var import_node_path42 = require("path");
+var import_node_path44 = require("path");
 function average(values) {
   if (values.length === 0) return 0;
   return values.reduce((a, b) => a + b, 0) / values.length;
@@ -57100,8 +57157,8 @@ async function runCli({ start }) {
         logger.info(renderMatrix());
         process.exit(0);
       }
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
-      const configPath = (0, import_node_path44.join)(cwd, "slopbrick.config.mjs");
+      const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
+      const configPath = (0, import_node_path46.join)(cwd, "slopbrick.config.mjs");
       const detected = detectStack(cwd);
       const fallbackConfig = { ...DEFAULT_CONFIG, ...detected };
       const proposed = serializeConfig(fallbackConfig);
@@ -57157,8 +57214,8 @@ async function runCli({ start }) {
         return Boolean(opts[t.flag]);
       });
       for (const target of targetsToWrite) {
-        const snippetPath = (0, import_node_path44.join)(cwd, resolveTargetPath(target));
-        (0, import_node_fs45.mkdirSync)((0, import_node_path44.dirname)(snippetPath), { recursive: true });
+        const snippetPath = (0, import_node_path46.join)(cwd, resolveTargetPath(target));
+        (0, import_node_fs45.mkdirSync)((0, import_node_path46.dirname)(snippetPath), { recursive: true });
         const generated = target.generator(builtinRules);
         if (!target.isFolder && (0, import_node_fs45.existsSync)(snippetPath)) {
           const existing = (0, import_node_fs45.readFileSync)(snippetPath, "utf8");
@@ -57196,7 +57253,7 @@ async function runCli({ start }) {
     });
     program.command("install").description("install the git pre-commit hook").action(async (_cmdOptions, command) => {
       const options = command.optsWithGlobals();
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+      const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
       const root = getGitRoot(cwd);
       if (!root) {
         logger.error("Not a Git repository. Run `git init` first, or remove --staged from your command.");
@@ -57210,7 +57267,7 @@ async function runCli({ start }) {
     });
     program.command("uninstall").description("uninstall the git pre-commit hook").action(async (_cmdOptions, command) => {
       const options = command.optsWithGlobals();
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+      const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
       const root = getGitRoot(cwd);
       if (!root) {
         logger.error("Not a Git repository. Run `git init` first, or remove --staged from your command.");
@@ -57222,34 +57279,12 @@ async function runCli({ start }) {
       }
       process.exit(result.exitCode);
     });
-    program.command("badge").description("print a shields.io slop-index badge. Reads .slopbrick/health.json if present (no re-scan); falls back to a fresh scan.").action(async (_cmdOptions, command) => {
-      const options = command.optsWithGlobals();
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
-      const { loadHealth: loadHealth2 } = await Promise.resolve().then(() => (init_dist(), dist_exports));
-      const health = loadHealth2(cwd);
-      if (health) {
-        const synthetic = {
-          slopIndex: 100 - health.repositoryHealth
-        };
-        logger.info(formatBadge(synthetic));
-        process.exit(0);
-      }
-      const { report } = await runScan(options);
-      logger.info(formatBadge(report));
-      process.exit(0);
-    });
-    program.command("suggest").description("print remediation advice").action(async (_cmdOptions, command) => {
-      const options = command.optsWithGlobals();
-      const { report } = await runScan(options);
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
-      logger.info(formatAdvice(report));
-      const diff = formatUnifiedDiff(report, cwd);
-      if (diff) logger.info(diff);
-      process.exit(0);
-    });
+    registerBadge(program);
+    registerSuggest(program);
+    registerExplain(program);
     program.command("flywheel").description("summarize aggregated scan telemetry").option("--format <pretty|json>", "output format", "pretty").option("--export <path>", "write summary as JSON to <path>").action(async (cmdOptions, command) => {
       const options = command.optsWithGlobals();
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+      const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
       const payloads = readTelemetry(cwd);
       if (payloads.length === 0) {
         logger.info("No flywheel telemetry found. Run a scan first.");
@@ -57257,8 +57292,8 @@ async function runCli({ start }) {
       }
       const summary = summarizeTelemetry(payloads);
       if (cmdOptions.export) {
-        const exportPath = (0, import_node_path44.resolve)(cmdOptions.export);
-        (0, import_node_fs45.mkdirSync)((0, import_node_path44.dirname)(exportPath), { recursive: true });
+        const exportPath = (0, import_node_path46.resolve)(cmdOptions.export);
+        (0, import_node_fs45.mkdirSync)((0, import_node_path46.dirname)(exportPath), { recursive: true });
         (0, import_node_fs45.writeFileSync)(exportPath, JSON.stringify(summary, null, 2), "utf-8");
         logger.info(`Wrote flywheel summary to ${exportPath}`);
         process.exit(0);
@@ -57282,7 +57317,7 @@ async function runCli({ start }) {
         logger.error("--heatmap and --suggest can't be used together. Pick one: a heatmap of severity, or text advice.");
         process.exit(2);
       }
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+      const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
       if (options.trend !== void 0) {
         const runs = await readRuns(cwd, fsMemoryIO);
         if (runs.length === 0) {
@@ -57315,7 +57350,7 @@ async function runCli({ start }) {
       const scanElapsed = Math.round(import_node_perf_hooks.performance.now() - scanStart);
       const totalElapsed = Math.round(import_node_perf_hooks.performance.now() - start);
       if (options.baseline) {
-        const cwd2 = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+        const cwd2 = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
         const configHash = hashConfig(config);
         const gitHead = await getGitHead(cwd2) ?? "unknown";
         const cache = buildBaselineCache(report, configHash, gitHead, cwd2);
@@ -57409,14 +57444,14 @@ async function runCli({ start }) {
         framework: cmdOptions.framework,
         componentType: cmdOptions.componentType,
         provider,
-        outputDir: (0, import_node_path44.resolve)(cmdOptions.outputDir),
+        outputDir: (0, import_node_path46.resolve)(cmdOptions.outputDir),
         temperature: cmdOptions.temperature
       });
       logger.info(`Generated ${samples.length} samples in ${cmdOptions.outputDir}`);
     });
     research.command("analyze").description("analyze generated samples and report coverage").requiredOption("--input-dir <path>", "directory with generated samples containing metadata.json").option("--output <path>", "analysis output path", ".slopbrick/flywheel/analysis.json").option("--config <path>", "slopbrick config path").option("--framework <name>", "framework multiplier to apply", "react").action(async (cmdOptions) => {
       try {
-        const metadataPath = (0, import_node_path44.resolve)(cmdOptions.inputDir, "metadata.json");
+        const metadataPath = (0, import_node_path46.resolve)(cmdOptions.inputDir, "metadata.json");
         if (!(0, import_node_fs45.existsSync)(metadataPath)) {
           logger.error(`No metadata.json found in ${cmdOptions.inputDir}`);
           process.exit(2);
@@ -57424,8 +57459,8 @@ async function runCli({ start }) {
         const samples = JSON.parse((0, import_node_fs45.readFileSync)(metadataPath, "utf8"));
         const config = cmdOptions.config ? await loadConfig(cmdOptions.config) : { ...DEFAULT_CONFIG, framework: cmdOptions.framework };
         const analysis = await analyzeSamples(samples, config);
-        const outputPath = (0, import_node_path44.resolve)(cmdOptions.output);
-        (0, import_node_fs45.mkdirSync)((0, import_node_path44.dirname)(outputPath), { recursive: true });
+        const outputPath = (0, import_node_path46.resolve)(cmdOptions.output);
+        (0, import_node_fs45.mkdirSync)((0, import_node_path46.dirname)(outputPath), { recursive: true });
         (0, import_node_fs45.writeFileSync)(outputPath, JSON.stringify(analysis, null, 2), "utf8");
         logger.info(`Analyzed ${analysis.summary.total} samples; coverage: ${analysis.summary.coverage}%`);
         logger.info(`Wrote analysis to ${outputPath}`);
@@ -57436,7 +57471,7 @@ async function runCli({ start }) {
     });
     research.command("candidates").description("extract patterns from generated samples and emit candidate rules").requiredOption("--input-dir <path>", "directory with generated samples containing metadata.json").option("--output <path>", "output path", ".slopbrick/flywheel/rule-candidates.json").option("--config <path>", "slopbrick config path").option("--framework <name>", "framework multiplier to apply", "react").option("--min-frequency <n>", "minimum cluster frequency", parseCount, 2).option("--include-covered", "include samples already covered by AI-specific rules").action(async (cmdOptions) => {
       try {
-        const metadataPath = (0, import_node_path44.resolve)(cmdOptions.inputDir, "metadata.json");
+        const metadataPath = (0, import_node_path46.resolve)(cmdOptions.inputDir, "metadata.json");
         if (!(0, import_node_fs45.existsSync)(metadataPath)) {
           logger.error(`No metadata.json found in ${cmdOptions.inputDir}`);
           process.exit(2);
@@ -57451,8 +57486,8 @@ async function runCli({ start }) {
         const candidates = clustersToCandidates(extraction.clusters, {
           minFrequency: cmdOptions.minFrequency
         });
-        const outputPath = (0, import_node_path44.resolve)(cmdOptions.output);
-        (0, import_node_fs45.mkdirSync)((0, import_node_path44.dirname)(outputPath), { recursive: true });
+        const outputPath = (0, import_node_path46.resolve)(cmdOptions.output);
+        (0, import_node_fs45.mkdirSync)((0, import_node_path46.dirname)(outputPath), { recursive: true });
         const payload = {
           generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
           sampleCount: analysis.summary.total,
@@ -57477,8 +57512,8 @@ async function runCli({ start }) {
           positiveLimit: cmdOptions.positiveLimit,
           negativeLimit: cmdOptions.negativeLimit
         });
-        const outputPath = cmdOptions.output ? (0, import_node_path44.resolve)(cwd, cmdOptions.output) : (0, import_node_path44.resolve)(cwd, "corpus", "calibration-empirical.md");
-        (0, import_node_fs45.mkdirSync)((0, import_node_path44.dirname)(outputPath), { recursive: true });
+        const outputPath = cmdOptions.output ? (0, import_node_path46.resolve)(cwd, cmdOptions.output) : (0, import_node_path46.resolve)(cwd, "corpus", "calibration-empirical.md");
+        (0, import_node_fs45.mkdirSync)((0, import_node_path46.dirname)(outputPath), { recursive: true });
         (0, import_node_fs45.writeFileSync)(outputPath, reportToMarkdown(report), "utf8");
         logger.info(
           "Calibrated " + report.rules.length + " rules across " + report.positiveFileCount + " positive + " + report.negativeFileCount + " negative files."
@@ -57517,7 +57552,7 @@ async function runCli({ start }) {
           const options = command.optsWithGlobals();
           const rawFormat = options.format ?? cmdOptions.format ?? "pretty";
           const format = rawFormat === "json" || rawFormat === "pretty" ? rawFormat : "pretty";
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const result = await runDrift(cwd, config, { maxFiles: cmdOptions.maxFiles });
           logger.info(formatDrift(result, { json: format === "json" }));
@@ -57534,7 +57569,7 @@ async function runCli({ start }) {
       async (cmdOptions, command) => {
         try {
           const options = command.optsWithGlobals();
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const rawFormat = options.format ?? cmdOptions.format ?? "text";
           const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "text" ? rawFormat : "text";
           const { config } = await runScan({ ...options, workspace: cwd });
@@ -57561,7 +57596,7 @@ async function runCli({ start }) {
           const options = command.optsWithGlobals();
           const rawFormat = options.format ?? cmdOptions.format ?? "pretty";
           const format = rawFormat === "json" || rawFormat === "pretty" ? rawFormat : "pretty";
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { report } = await runScan({ ...options, workspace: cwd });
           const securityIssues = report.issues.filter((i) => i.category === "security");
           const { risk, findings } = computeAiSecurityRisk(securityIssues);
@@ -57612,7 +57647,7 @@ async function runCli({ start }) {
           const options = command.optsWithGlobals();
           const rawFormat = options.format ?? cmdOptions.format ?? "pretty";
           const format = rawFormat === "json" || rawFormat === "pretty" ? rawFormat : "pretty";
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const { result } = await runTestScan(cwd, config, { strict: options.strict });
           logger.info(formatTestReport(result, { json: format === "json" }));
@@ -57631,7 +57666,7 @@ async function runCli({ start }) {
           const options = command.optsWithGlobals();
           const rawFormat = options.format ?? cmdOptions.format ?? "pretty";
           const format = rawFormat === "json" || rawFormat === "pretty" ? rawFormat : "pretty";
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const score = await buildArchitectureScore(cwd, config, cmdOptions.maxFiles);
           const out = format === "json" ? JSON.stringify(score, null, 2) : formatArchitectureScore(score);
@@ -57651,7 +57686,7 @@ async function runCli({ start }) {
           const options = command.optsWithGlobals();
           const rawFormat = options.format ?? cmdOptions.format ?? "text";
           const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "text" ? rawFormat : "text";
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const result = await runBusinessLogicScan(cwd, config, {
             maxFiles: cmdOptions.maxFiles
@@ -57673,7 +57708,7 @@ async function runCli({ start }) {
           const rawFormat = options.format ?? cmdOptions.format ?? "text";
           const format = rawFormat === "json" || rawFormat === "text" ? rawFormat : "text";
           const strict = options.strict ?? cmdOptions.strict ?? false;
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const result = await runMaintenanceCostScan(cwd, config, {
             maxFiles: cmdOptions.maxFiles,
@@ -57696,7 +57731,7 @@ async function runCli({ start }) {
           const rawFormat = options.format ?? cmdOptions.format ?? "text";
           const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "text" ? rawFormat : "text";
           const strict = options.strict ?? cmdOptions.strict ?? false;
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const result = await runDocsScan(cwd, config, {
             maxDocFiles: cmdOptions.maxFiles,
@@ -57724,7 +57759,7 @@ async function runCli({ start }) {
           const rawFormat = options.format ?? cmdOptions.format ?? "text";
           const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "text" ? rawFormat : "text";
           const strict = options.strict ?? cmdOptions.strict ?? false;
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const result = await runDbScan(cwd, config, {
             maxFiles: cmdOptions.maxFiles,
@@ -57751,7 +57786,7 @@ async function runCli({ start }) {
           const options = command.optsWithGlobals();
           const rawFormat = options.format ?? cmdOptions.format ?? "text";
           const format = rawFormat === "json" || rawFormat === "markdown" || rawFormat === "text" ? rawFormat : "text";
-          const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+          const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
           const { config } = await runScan({ ...options, workspace: cwd });
           const result = await runPatternsScan(cwd, config, {
             maxFiles: cmdOptions.maxFiles,
@@ -57782,14 +57817,14 @@ async function runCli({ start }) {
         ...rawGlobals,
         noIncrease: rawGlobals.increase === false
       };
-      const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+      const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
       const { watchProject: watchProject2 } = await Promise.resolve().then(() => (init_scan(), scan_exports));
       await scanAction([], options, command);
       await watchProject2(options, cwd, []);
     });
     program.command("lock").description("install a Git pre-commit hook that runs `slopbrick scan --staged` on every commit. The LockBrick prevention loop: block AI-introduced slop from ever reaching the repo.").option("--uninstall", "remove the pre-commit hook instead of installing it").option("--husky", "force-install under .husky/pre-commit (Husky v9). Default auto-detects via .husky/ dir.").option("--workspace <path>", "workspace directory", process.cwd()).action(
       (cmdOptions) => {
-        const cwd = (0, import_node_path44.resolve)(cmdOptions.workspace ?? process.cwd());
+        const cwd = (0, import_node_path46.resolve)(cmdOptions.workspace ?? process.cwd());
         const { installHook: installHook2, uninstallHook: uninstallHook2 } = (init_installer(), __toCommonJS(installer_exports));
         if (cmdOptions.uninstall) {
           const result2 = uninstallHook2(cwd);
@@ -57819,7 +57854,7 @@ async function runCli({ start }) {
           // scan only changed files
           format: cmdOptions.format ?? "json"
         };
-        const cwd = (0, import_node_path44.resolve)(options.workspace ?? process.cwd());
+        const cwd = (0, import_node_path46.resolve)(options.workspace ?? process.cwd());
         await scanAction([], options, command);
         const { loadHealth: loadHealth2 } = await Promise.resolve().then(() => (init_dist(), dist_exports));
         const health = loadHealth2(cwd);
@@ -57847,7 +57882,7 @@ async function runCli({ start }) {
     );
     program.command("memory").description("show or regenerate .slopbrick/structure.md (the agent-readable repository summary) without re-scanning").option("--show", "print the current .slopbrick/structure.md to stdout (default if no flag is passed)").option("--regenerate", "re-render structure.md from the existing inventory.json + constitution.json (no scan)").option("--workspace <path>", "workspace directory", process.cwd()).action(
       async (cmdOptions) => {
-        const cwd = (0, import_node_path44.resolve)(cmdOptions.workspace ?? process.cwd());
+        const cwd = (0, import_node_path46.resolve)(cmdOptions.workspace ?? process.cwd());
         const { renderStructureMarkdown: renderStructureMarkdown2, readStructureMarkdown: readStructureMarkdown2, writeStructureMarkdown: writeStructureMarkdown2 } = await Promise.resolve().then(() => (init_structure_md(), structure_md_exports));
         const { loadInventory: loadInventory2, loadConstitution: loadConstitution2, inventoryPath: invPath, constitutionPath: conPath } = await Promise.resolve().then(() => (init_dist(), dist_exports));
         if (cmdOptions.regenerate) {
@@ -57880,7 +57915,7 @@ async function runCli({ start }) {
       (cmdOptions, command) => {
         const globals = command.optsWithGlobals();
         const format = (cmdOptions.format ?? globals.format) === "json" ? "json" : "pretty";
-        const cwd = (0, import_node_path44.resolve)(cmdOptions.workspace ?? process.cwd());
+        const cwd = (0, import_node_path46.resolve)(cmdOptions.workspace ?? process.cwd());
         const { runMigrate: runMigrate2, formatMigrate: formatMigrate2 } = (init_migrate(), __toCommonJS(migrate_exports));
         const result = runMigrate2({
           workspace: cwd,
@@ -57975,19 +58010,14 @@ async function runCli({ start }) {
       }
       logger.info(lines.join("\n"));
     });
-    program.command("explain <ruleId>").description("Print rationale, pattern, and remediation for a single rule").action((ruleId) => {
-      const result = explainRule2(ruleId, builtinRules, RULE_HINTS);
-      logger.info(formatExplain(result));
-      if ("error" in result) process.exit(2);
-    });
     program.command("validate-config [path]").description("Statically validate a slopbrick.config.mjs without scanning").action(async (configPath) => {
-      const path = configPath ? (0, import_node_path44.resolve)(configPath) : (0, import_node_path44.resolve)(process.cwd(), "slopbrick.config.mjs");
+      const path = configPath ? (0, import_node_path46.resolve)(configPath) : (0, import_node_path46.resolve)(process.cwd(), "slopbrick.config.mjs");
       if (!(0, import_node_fs45.existsSync)(path)) {
         logger.error(`Error: config file not found: ${path}`);
         process.exit(2);
       }
       try {
-        const mod = (0, import_node_path44.extname)(path) === ".cjs" ? require(path) : await import(path);
+        const mod = (0, import_node_path46.extname)(path) === ".cjs" ? require(path) : await import(path);
         const userConfig = mod.default ?? mod;
         const result = validateConfig(userConfig);
         if (result.errors.length === 0) {