slopbrick 0.42.0 → 0.43.0

package/dist/index.cjs

@@ -36,7 +36,7 @@ var VERSION;
 var init_header = __esm({
   "src/types/_header.ts"() {
     "use strict";
-    VERSION = "0.42.0";
+    VERSION = "0.43.0";
   }
 });
 
@@ -338,8 +338,16 @@ var init_defaults = __esm({
           // rule definitions are meta-code
           "**/snippet/**",
           // RULE_HINTS examples are intentional bad code
-          "**/tests/**"
+          "**/tests/**",
           // all test files (fixtures + unit + integration)
+          // v0.42.0 (post-self-scan cleanup): language visitors are
+          // intentional clones — see the §3 v0.42.0 release notes for
+          // the design rationale. `dup/identical-block` fires 100+
+          // times during self-scan because each visitor shares the
+          // same service-suffix arrays and import-walking preamble.
+          // Suppress these from the self-scan noise floor; they
+          // remain on for user codebases.
+          "**/src/engine/visitors/**"
         ]
       }
     };
@@ -26001,7 +26009,7 @@ var init_comment_ratio = __esm({
             message: `Comment-line ratio is ${direction} (${ratio.toFixed(2)} vs corpus mean ${mean3}). Reductive LLMs (GPT-3.5, Claude 3 Haiku) skip comments; expansive LLMs (Claude Haiku 4.5, GPT-OSS) over-comment when prompted for "well-commented code".`,
             line: 1,
             column: 1,
-            advice: direction === "low" ? "Add doc comments explaining intent (not just restating the next line) for non-obvious logic." : "Trim comments that just restate the next line. Keep comments that explain WHY, not WHAT."
+            advice: direction === "low" ? "Add doc comments explaining intent (not just restating the next line) for non-obvious logic." : "High comment ratio \u2014 consider whether the comments are intentional (api docs, type defs, tutorials). For functional code, trim comments that just restate the next line. Keep comments that explain WHY, not WHAT."
           }
         ];
         return issues;
@@ -26852,7 +26860,6 @@ function buildTrigramLM(samples, alpha = 1) {
     logProb(context, t) {
       const ctxKey = context.slice(-2).join("|");
       const triKey = `${ctxKey}|${t}`;
-      const biKey = context.slice(-1).join("|") + "|" + t;
       const triCount = tri.get(triKey) ?? 0;
       const biCount = bi.get(ctxKey) ?? 0;
       const V = uni.size;
@@ -28860,7 +28867,7 @@ var init_stale_function_reference = __esm({
     ]);
     SOURCE_EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
     SOURCE_ROOTS = ["src", "lib", "app", "components"];
-    CAP = 200;
+    CAP = 4e3;
     staleFunctionReferenceRule = createRule({
       id: "docs/stale-function-reference",
       category: "docs",
@@ -28876,6 +28883,7 @@ var init_stale_function_reference = __esm({
         if (!source) return issues;
         for (const span of extractInlineCodeSpans(source)) {
           const text = span.text;
+          if (span.inBlockComment || span.inComment) continue;
           if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(text)) continue;
           if (text.length < 3) continue;
           if (RESERVED.has(text.toLowerCase())) continue;
@@ -29046,6 +29054,7 @@ var init_stale_package_reference = __esm({
         if (!source) return issues;
         const spans = extractInlineCodeSpans(source);
         for (const span of spans) {
+          if (span.inComment) continue;
           const lineStart = source.lastIndexOf("\n", span.index) + 1;
           const lineEnd = source.indexOf("\n", span.index);
           const line = source.slice(lineStart, lineEnd === -1 ? source.length : lineEnd);
@@ -29100,11 +29109,14 @@ __export(doc_freshness_exports, {
   extractExports: () => extractExports,
   extractFencedCodeBlocks: () => extractFencedCodeBlocks,
   extractInlineCodeSpans: () => extractInlineCodeSpans,
-  extractMarkdownLinks: () => extractMarkdownLinks
+  extractMarkdownLinks: () => extractMarkdownLinks,
+  findCommentLineRanges: () => findCommentLineRanges
 });
 function extractInlineCodeSpans(source) {
   const hits = [];
   const re = /`([^`\n]+?)`/g;
+  const blockRanges = findBlockCommentRanges(source);
+  const commentLines = findCommentLineRanges(source);
   let m;
   while ((m = re.exec(source)) !== null) {
     const text = m[1] ?? "";
@@ -29112,7 +29124,14 @@ function extractInlineCodeSpans(source) {
     const line = upTo.split("\n").length;
     const lastNl = upTo.lastIndexOf("\n");
     const column = lastNl === -1 ? m.index + 1 : m.index - lastNl;
-    hits.push({ text, line, column, index: m.index });
+    hits.push({
+      text,
+      line,
+      column,
+      index: m.index,
+      inBlockComment: isInBlockComment(blockRanges, m.index),
+      inComment: commentLines.has(line)
+    });
   }
   return hits;
 }
@@ -29151,6 +29170,8 @@ function extractFencedCodeBlocks(source) {
 function extractMarkdownLinks(source) {
   const hits = [];
   const re = /(?<!\!)\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  const blockRanges = findBlockCommentRanges(source);
+  const commentLines = findCommentLineRanges(source);
   let m;
   while ((m = re.exec(source)) !== null) {
     const target = m[2] ?? "";
@@ -29158,10 +29179,55 @@ function extractMarkdownLinks(source) {
     const line = upTo.split("\n").length;
     const lastNl = upTo.lastIndexOf("\n");
     const column = lastNl === -1 ? m.index + 1 : m.index - lastNl;
-    hits.push({ target, line, column });
+    hits.push({
+      target,
+      line,
+      column,
+      index: m.index,
+      inBlockComment: isInBlockComment(blockRanges, m.index),
+      inComment: commentLines.has(line)
+    });
   }
   return hits;
 }
+function findBlockCommentRanges(source) {
+  const ranges = [];
+  const stack = [];
+  let i = 0;
+  while (i < source.length) {
+    if (source[i] === "/" && source[i + 1] === "/") {
+      const eol = source.indexOf("\n", i);
+      i = eol === -1 ? source.length : eol + 1;
+      continue;
+    }
+    if (source[i] === "/" && source[i + 1] === "*") {
+      stack.push(i);
+      i += 2;
+      continue;
+    }
+    if (source[i] === "*" && source[i + 1] === "/" && stack.length > 0) {
+      const start = stack.pop();
+      ranges.push([start, i + 2]);
+      i += 2;
+      continue;
+    }
+    i += 1;
+  }
+  ranges.sort((a, b) => a[0] - b[0]);
+  return ranges;
+}
+function isInBlockComment(ranges, pos) {
+  let lo = 0;
+  let hi = ranges.length - 1;
+  while (lo <= hi) {
+    const mid = lo + hi >>> 1;
+    const [start, end] = ranges[mid];
+    if (pos < start) hi = mid - 1;
+    else if (pos >= end) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}
 function declaredPackages(cwd) {
   const out = /* @__PURE__ */ new Set();
   const pkgPath = (0, import_node_path6.join)(cwd, "package.json");
@@ -29316,6 +29382,58 @@ function docDriftFromFreshness(score) {
   if (score >= DOC_FRESHNESS_THRESHOLDS.high) return "high";
   return "critical";
 }
+function findCommentLineRanges(source) {
+  const out = /* @__PURE__ */ new Set();
+  const stack = [];
+  let inLineComment = false;
+  const lines = source.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    let j = 0;
+    while (j < line.length) {
+      const c = line[j];
+      const next = line[j + 1];
+      if (!stack.length && c === "/" && next === "/") {
+        inLineComment = true;
+        out.add(lineNo);
+        break;
+      }
+      if (c === "/" && next === "*") {
+        stack.push(lineNo);
+        out.add(lineNo);
+        j += 2;
+        continue;
+      }
+      if (c === "*" && next === "/" && stack.length > 0) {
+        stack.pop();
+        j += 2;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === "`") {
+        const quote = c;
+        j += 1;
+        while (j < line.length) {
+          if (line[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (line[j] === quote) {
+            j += 1;
+            break;
+          }
+          j += 1;
+        }
+        continue;
+      }
+      j += 1;
+    }
+    if (stack.length > 0) {
+      out.add(lineNo);
+    }
+  }
+  return out;
+}
 var import_node_fs6, import_node_path6, import_globby, DOC_RULE_WEIGHTS, DOC_FRESHNESS_THRESHOLDS;
 var init_doc_freshness = __esm({
   "src/engine/doc-freshness.ts"() {
@@ -29340,6 +29458,9 @@ var init_doc_freshness = __esm({
 });
 
 // src/rules/docs/broken-link.ts
+function looksLikeRegexSyntax(target) {
+  return /\[[^\]]*\]/.test(target) || /^\s*[?:=!]/.test(target) || /\\(?:s|d|w|S|D|W|t|n|r|[^\\])/.test(target) || /[{}|]/.test(target);
+}
 var import_node_fs7, import_node_path7, brokenLinkRule;
 var init_broken_link = __esm({
   "src/rules/docs/broken-link.ts"() {
@@ -29370,6 +29491,8 @@ var init_broken_link = __esm({
           if (target.startsWith("#")) continue;
           if (target.startsWith("//")) continue;
           if (target.startsWith("/")) continue;
+          if (link.inBlockComment) continue;
+          if (looksLikeRegexSyntax(target)) continue;
           const filePart = target.split("#")[0] ?? target;
           if (filePart === "") continue;
           const resolved = (0, import_node_path7.join)(docDir, filePart);
@@ -38545,6 +38668,29 @@ var init_stringly_typed = __esm({
   }
 });
 
+// src/engine/parser-shared.ts
+function parseTreeSitterSource(parserResult, source) {
+  if (!parserResult.ok) return null;
+  if (!source || source.trim() === "") return null;
+  try {
+    const rawTree = parserResult.parser.parse(source);
+    if (!rawTree) return null;
+    const tree = rawTree;
+    if (!tree || !tree.rootNode) return null;
+    if (tree.rootNode.type === "ERROR" && tree.rootNode.childCount === 0) {
+      return null;
+    }
+    return tree;
+  } catch {
+    return null;
+  }
+}
+var init_parser_shared = __esm({
+  "src/engine/parser-shared.ts"() {
+    "use strict";
+  }
+});
+
 // src/engine/parser-rust.ts
 function getRustParser() {
   if (cachedParser) return { ok: true, parser: cachedParser };
@@ -38568,21 +38714,7 @@ function effectiveParser() {
   return getRustParser();
 }
 function parseRust(source) {
-  const result = effectiveParser();
-  if (!result.ok) return null;
-  if (!source || source.trim() === "") return null;
-  try {
-    const rawTree = result.parser.parse(source);
-    if (!rawTree) return null;
-    const tree = rawTree;
-    if (!tree || !tree.rootNode) return null;
-    if (tree.rootNode.type === "ERROR" && tree.rootNode.childCount === 0) {
-      return null;
-    }
-    return tree;
-  } catch {
-    return null;
-  }
+  return parseTreeSitterSource(effectiveParser(), source);
 }
 function isRustParserAvailable() {
   const result = getRustParser();
@@ -38594,6 +38726,7 @@ var init_parser_rust = __esm({
     "use strict";
     import_tree_sitter = __toESM(require("tree-sitter"), 1);
     import_tree_sitter_rust = __toESM(require("tree-sitter-rust"), 1);
+    init_parser_shared();
     cachedParser = null;
     rustLanguage = null;
     loadError = null;
@@ -43701,8 +43834,6 @@ function mergeTemplateClassNames(filePath, source, facts, templateClassNames) {
 }
 function extractFacts(filePath, ast, source, supportsRsc = true, framework = "react", config) {
   const lineOffsets = buildLineOffsets2(source);
-  const isTypeScript = /\.tsx?$/i.test(filePath);
-  const NON_JSX_FRAMEWORKS = /* @__PURE__ */ new Set(["vue", "svelte", "astro"]);
   const facts = {
     filePath,
     components: [],
@@ -45641,7 +45772,7 @@ function formatDeltaSuffix(report) {
 }
 function formatVerdict(report) {
   const score = report.aiSlopScore;
-  const band = scoreBand(score);
+  const band = slopScoreBand(score);
   const ranked = rankByImpact(report.issues);
   const topRule = ranked[0];
   const topFile = report.topOffenders?.[0];
@@ -45724,7 +45855,8 @@ function formatNextStep(report) {
       `  \u2192 \`slopbrick scan --baseline\` to accept today's scores as the new floor`
     )
   );
-  if (report.aiSlopScore > 30) {
+  const meanSlop = report.thresholds?.meanSlop ?? 30;
+  if (report.aiSlopScore > meanSlop) {
     lines.push(
       import_chalk.default.dim(
         `  \u2192 \`slopbrick scan --why-failing\` for the top 5 issues dragging the score down`
@@ -45749,17 +45881,18 @@ function formatWhyFailing(report) {
     return import_chalk.default.green("Nothing is failing the threshold. Score is clean.");
   }
   const headline = report.aiSlopScore;
-  const status = headline <= 30 ? "PASS" : "FAIL";
-  const colorize = headline <= 30 ? import_chalk.default.green : import_chalk.default.red;
+  const meanSlop = report.thresholds?.meanSlop ?? 30;
+  const status = headline <= meanSlop ? "PASS" : "FAIL";
+  const colorize = headline <= meanSlop ? import_chalk.default.green : import_chalk.default.red;
+  const qualifier = headline <= meanSlop ? `below ${meanSlop}` : `above ${meanSlop}`;
   const lines = [];
-  lines.push(colorize.bold(`Headline score: ${headline.toFixed(0)}/100 (${status} \u2014 above 30)`));
+  lines.push(colorize.bold(`Headline score: ${headline.toFixed(0)}/100 (${status} \u2014 ${qualifier})`));
   lines.push("");
   lines.push(import_chalk.default.bold("Top 5 rules dragging the score down:"));
   for (let i = 0; i < ranked.length; i++) {
     const [ruleId, info] = ranked[i];
     const fileCount = info.files.size;
     const fileHint = fileCount > 0 ? ` across ${fileCount} file${fileCount === 1 ? "" : "s"}` : "";
-    const catShort = CATEGORY_GLOSSARY[info.count > 0 ? "" : ""]?.short;
     const sampleIssue = report.issues.find((i2) => i2.ruleId === ruleId);
     const cat = sampleIssue ? CATEGORY_GLOSSARY[sampleIssue.category]?.short : null;
     const catHint = cat ? import_chalk.default.dim(` [${cat}]`) : "";
@@ -45819,7 +45952,7 @@ function formatCompositeScore(report) {
     lines.push("");
     lines.push(
       import_chalk.default.dim(
-        `Repository Coherence: ${coherenceValue} / 100 [${cohBand.label.toUpperCase()}] \u2014 higher = better \xB7 measures internal consistency. This is a secondary view; the Slop Index above is the gate.`
+        `Repository Coherence: ${coherenceValue} / 100 [${cohBand.label.toUpperCase()}] \u2014 higher = better \xB7 measures internal consistency. This is a secondary view; the AI Slop Score above is the gate.`
       )
     );
   }
@@ -45949,13 +46082,12 @@ function formatDriftSection(report) {
   return lines.join("\n");
 }
 function formatThresholds(report) {
-  const limit = report.thresholds.meanSlop;
+  const meanSlop = report.thresholds?.meanSlop ?? 30;
   const headline = report.aiSlopScore;
-  const passed = headline >= 70;
-  const valueText = `${headline.toFixed(1)} \u2265 70`.padStart(12, " ");
+  const passed = headline <= meanSlop;
+  const valueText = `${headline.toFixed(1)} \u2264 ${meanSlop}`.padStart(12, " ");
   const status = passed ? import_chalk.default.green("pass") : import_chalk.default.red("fail");
   const result = ["Threshold (CI gate)", `  AI Slop Score  ${valueText}  ${status}`];
-  void limit;
   return result;
 }
 function formatTopComponents(components, topOffenders) {
@@ -46033,9 +46165,10 @@ function formatPretty(report) {
   }
   return sections.join("\n\n");
 }
-function formatScoringExplainer(_report) {
+function formatScoringExplainer(report) {
+  const meanSlop = report.thresholds?.meanSlop ?? 30;
   return import_chalk.default.dim(
-    "Four orthogonal scores (all 0-100, higher = better): AI Slop Score (AI-slop signatures; the CI gate, AI Slop Score >= 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 Slop Score + 0.3*Engineering Hygiene + 0.2*Security + 0.1*Test Quality). Only AI Slop Score gates CI; the others are informational. Default-off rules (INVERTED/NOISY/DORMANT) are suppressed from the scores automatically."
+    `Four orthogonal scores (all 0-100, **lower AI Slop Score = cleaner**): AI Slop Score (AI-slop signatures; the CI gate, AI Slop Score \u2264 ${meanSlop} passes), Engineering Hygiene (issues per category across arch/logic/layout/component/test; higher = cleaner), Security (AI-flagged security risks, inverted from risk level; higher = cleaner), Repository Health (composite: 0.4*AI Slop Score + 0.3*Engineering Hygiene + 0.2*Security + 0.1*Test Quality). Only AI Slop Score gates CI; the others are informational. Default-off rules (INVERTED/NOISY/DORMANT) are suppressed from the scores automatically.`
   );
 }
 function formatWhyFailingReport(report) {
@@ -46053,7 +46186,7 @@ function formatBriefReport(report) {
   ];
   const deltaSuffix = formatDeltaSuffix(report);
   scoreLines.forEach(({ label, field, value }, idx) => {
-    const band = scoreBand(value);
+    const band = field === "aiSlopScore" ? slopScoreBand(value) : scoreBand(value);
     const paddedLabel = label.padEnd(20, " ");
     const valueStr = value.toFixed(0).padStart(3, " ");
     const delta = idx === 0 ? deltaSuffix : "";
@@ -46061,11 +46194,12 @@ function formatBriefReport(report) {
       `  ${paddedLabel} ${band.color(valueStr)}   ${import_chalk.default.dim(band.label)}  ${import_chalk.default.dim.italic(`(${field})`)}${delta}`
     );
   });
-  const passed = report.aiSlopScore <= 30;
+  const meanSlop = report.thresholds?.meanSlop ?? 30;
+  const passed = report.aiSlopScore <= meanSlop;
   lines.push("");
   lines.push(
     import_chalk.default.dim(
-      `  CI gate: AI Slop Score <= 30 -> ${passed ? import_chalk.default.green("pass") : import_chalk.default.red("fail")}`
+      `  CI gate: AI Slop Score <= ${meanSlop} -> ${passed ? import_chalk.default.green("pass") : import_chalk.default.red("fail")}`
     )
   );
   const suppressed = report.defaultOffSuppressedCount ?? 0;
@@ -46210,19 +46344,22 @@ function thresholdExceeded(report, config) {
   return categoryThresholdBreached(report, config.thresholds.categoryThresholds);
 }
 function failedThresholdCount(report, config) {
-  let count = 0;
-  if (report.aiSlopScore > config.thresholds.meanSlop) count += 1;
-  if (report.p90Score > config.thresholds.p90Slop) count += 1;
-  if (report.peakScore > config.thresholds.individualSlopThreshold) count += 1;
+  return failedThresholds(report, config).length;
+}
+function failedThresholds(report, config) {
+  const failed = [];
+  if (report.aiSlopScore > config.thresholds.meanSlop) failed.push("meanSlop");
+  if (report.p90Score > config.thresholds.p90Slop) failed.push("p90Slop");
+  if (report.peakScore > config.thresholds.individualSlopThreshold) failed.push("individualSlopThreshold");
   const cat = config.thresholds.categoryThresholds;
   if (cat) {
     for (const [category, limit] of Object.entries(cat)) {
       if (limit === void 0) continue;
       const score = report.categoryScores[category];
-      if (score !== void 0 && score > limit) count += 1;
+      if (score !== void 0 && score > limit) failed.push(`category:${category}`);
     }
   }
-  return count;
+  return failed;
 }
 function categoryThresholdBreached(report, categoryThresholds) {
   if (!categoryThresholds) return false;
@@ -50890,9 +51027,22 @@ function computeFlywheelOutput(runs, currentTopFiles, recentTopHashes, unmatched
     }
   }
   if (currentTopFiles.length > 0 && runs.length >= CONSECUTIVE_THRESHOLD) {
+    const latestRun = runs[runs.length - 1];
+    const isNoiseTier = (id) => {
+      const rule = ruleById.get(id);
+      if (!rule) return false;
+      if (rule.defaultOff === true) return true;
+      if (rule.aiSpecific && (rule.severity === "medium" || rule.severity === "low")) return true;
+      return false;
+    };
+    const onRulesInLatestTop = latestRun.topOffenseIds.filter(
+      (id) => !isNoiseTier(id)
+    );
+    const skipChronicOnDefaultOffNoise = onRulesInLatestTop.length === 0;
     for (const file of currentTopFiles) {
       const consecutive = countConsecutiveTopFileAppearances(file.hash, recentTopHashes);
       if (consecutive >= CONSECUTIVE_THRESHOLD) {
+        if (skipChronicOnDefaultOffNoise) continue;
         hotspotIssues.push({
           ruleId: "component/chronic-offender",
           category: "component",
@@ -50902,7 +51052,7 @@ function computeFlywheelOutput(runs, currentTopFiles, recentTopHashes, unmatched
           filePath: file.filePath,
           line: 1,
           column: 1,
-          advice: "Prioritize refactoring this file or add it to the baseline."
+          advice: "Run `slopbrick scan --baseline` to accept current scores as the new floor, or refactor the file to reduce its issue count."
         });
       }
     }
@@ -53236,16 +53386,16 @@ function axisSlopIndex(slopIndex) {
   if (slopIndex === void 0 || Number.isNaN(slopIndex)) {
     return {
       axis: "slopIndex",
-      label: "Slop Index",
+      label: "AI Slop Score (raw)",
       health: 70,
       source: "default (not measured) \u2014 neutral 70"
     };
   }
   return {
     axis: "slopIndex",
-    label: "Slop Index",
+    label: "AI Slop Score (raw)",
     health: clamp100(100 - slopIndex),
-    source: `100 - slopIndex (${slopIndex.toFixed(1)}) \u2192 inverted`
+    source: `100 - aiSlopScore (${slopIndex.toFixed(1)}) \u2192 inverted to cleanliness`
   };
 }
 function axisArchitecture(architectureConsistency) {
@@ -54193,6 +54343,16 @@ function assembleScanReport(input) {
     enrichment
   } = input;
   const prSlopScore = computePrSlopScore(diffRef, allIssues);
+  const thresholdReport = {
+    aiSlopScore: aggregated.aiSlopScore,
+    p90Score: aggregated.p90Score,
+    peakScore: aggregated.peakScore,
+    categoryScores: aggregated.categoryScores
+  };
+  const failedThresholds_ = failedThresholds(
+    thresholdReport,
+    config
+  );
   return {
     version: VERSION,
     generatedAt,
@@ -54248,6 +54408,11 @@ function assembleScanReport(input) {
     parseErrors: parseErrors.length > 0 ? parseErrors : void 0,
     baseline: baselineMeta,
     thresholds: config.thresholds,
+    // v0.42.0 (user-review fix): expose which gates tripped so CI
+    // consumers can read the JSON output instead of grepping stderr.
+    // Optional field: absent when no thresholds tripped. Computed from
+    // the report's own scores so the JSON is self-describing.
+    failedThresholds: failedThresholds_,
     topOffenders: topOffenders.length > 0 ? topOffenders : void 0,
     coherence: enrichment.coherence,
     coherenceBreakdown: enrichment.coherenceBreakdown,
@@ -54264,6 +54429,7 @@ var PR_SLOP_WEIGHTS;
 var init_assembleScanReport = __esm({
   "src/cli/report/assembleScanReport.ts"() {
     "use strict";
+    init_threshold();
     init_types();
     PR_SLOP_WEIGHTS = { high: 10, medium: 5, low: 1 };
   }
@@ -55756,11 +55922,13 @@ function extractNamedScores(report) {
   };
 }
 function renderThresholds(report) {
-  const r = report;
-  const score = typeof r.repositoryHealth === "number" ? r.repositoryHealth : report.repositoryHealth;
-  const limit = 70;
-  const available = typeof score === "number";
-  const failed = available && score < limit;
+  const meanSlop = report.thresholds?.meanSlop ?? 30;
+  const aiAvailable = typeof report.aiSlopScore === "number";
+  const aiPassed = aiAvailable && report.aiSlopScore <= meanSlop;
+  const rh = report.repositoryHealth;
+  const rhAvailable = typeof rh === "number";
+  const rhLimit = 70;
+  const rhPassed = rhAvailable && rh >= rhLimit;
   return `
   <section class="thresholds-section">
     <h2>Thresholds</h2>
@@ -55774,9 +55942,14 @@ function renderThresholds(report) {
       </thead>
       <tbody>
         <tr>
-          <td>Repository Health (composite)</td>
-          <td>${available ? `${score.toFixed(1)} / ${limit}` : "\u2013"}</td>
-          <td><span class="status-badge ${thresholdStatusClass(failed)}">${available ? failed ? "fail" : "pass" : "n/a"}</span></td>
+          <td>AI Slop Score (CI gate)</td>
+          <td>${aiAvailable ? `${report.aiSlopScore.toFixed(1)} / ${meanSlop}` : "\u2013"}</td>
+          <td><span class="status-badge ${thresholdStatusClass(!aiPassed)}">${aiAvailable ? aiPassed ? "pass" : "fail" : "n/a"}</span></td>
+        </tr>
+        <tr>
+          <td>Repository Health (informational)</td>
+          <td>${rhAvailable ? `${rh.toFixed(1)} / ${rhLimit}` : "\u2013"}</td>
+          <td><span class="status-badge ${thresholdStatusClass(!rhPassed)}">${rhAvailable ? rhPassed ? "pass" : "fail" : "n/a"}</span></td>
         </tr>
       </tbody>
     </table>
@@ -57337,12 +57510,16 @@ async function runScan(options, explicitPaths) {
     files = intersectFiles(files, since, cwd);
   }
   let incrementalSummary;
+  let cachePath3;
+  let existingCache;
+  let unchanged = [];
   if (options.incremental) {
-    const cachePath3 = options.cachePath ?? ".slopbrick-cache.json";
-    const existing = loadCache(cachePath3);
-    const { toScan, unchanged } = partitionByCache(files, existing);
-    files = toScan;
-    incrementalSummary = { skipped: unchanged.length, rescanned: toScan.length };
+    cachePath3 = options.cachePath ?? ".slopbrick-cache.json";
+    existingCache = loadCache(cachePath3);
+    const partition = partitionByCache(files, existingCache);
+    files = partition.toScan;
+    unchanged = partition.unchanged;
+    incrementalSummary = { skipped: unchanged.length, rescanned: partition.toScan.length };
   }
   const machineReadableStdout = !!options.json || !!options.html || options.format === "json" || options.format === "sarif" || options.format === "html";
   if (files.length === 0 && !options.quiet && !machineReadableStdout) {
@@ -57362,6 +57539,9 @@ async function runScan(options, explicitPaths) {
       logger.warn(
         `No source files matched in ${cwd}. Adjust --include or check your config at ${projectRoot}.`
       );
+      logger.warn(
+        "Tip: run from a directory with source files, or pass --workspace <path> (monorepos usually want `--workspace packages/<name>`)."
+      );
     }
   }
   const configHash = hashConfig(config);
@@ -57511,6 +57691,38 @@ async function runScan(options, explicitPaths) {
     telemetryEnabled,
     machineReadableStdout
   });
+  if (options.incremental && cachePath3 !== void 0) {
+    const cachedFiles = {};
+    for (const r of results) {
+      try {
+        cachedFiles[r.filePath] = {
+          hash: computeFileHash(r.filePath),
+          issueCount: r.issues.length,
+          lastScannedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      } catch {
+      }
+    }
+    for (const f of unchanged) {
+      const cached = existingCache?.files[f];
+      if (cached) {
+        cachedFiles[f] = {
+          hash: cached.hash,
+          issueCount: cached.issueCount,
+          lastScannedAt: cached.lastScannedAt
+        };
+      } else {
+      }
+    }
+    try {
+      saveCache(cachePath3, {
+        version: VERSION,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        files: cachedFiles
+      });
+    } catch {
+    }
+  }
   return {
     report,
     scores,
@@ -57657,6 +57869,7 @@ __export(src_exports, {
   directoryScore: () => directoryScore,
   extractSignatures: () => extractSignatures,
   failedThresholdCount: () => failedThresholdCount,
+  failedThresholds: () => failedThresholds,
   filterByDisabledDirectives: () => filterByDisabledDirectives,
   filterIssues: () => filterIssues,
   findSimilarFunctions: () => findSimilarFunctions,
@@ -57742,6 +57955,7 @@ init_scan2();
 init_scan2();
 
 // src/cli/init.ts
+var import_chalk2 = __toESM(require("chalk"), 1);
 var import_node_fs31 = require("fs");
 var import_node_path34 = require("path");
 var import_node_readline = require("readline");
@@ -57750,6 +57964,7 @@ init_discover();
 init_git();
 init_cache();
 init_logger();
+init_types();
 
 // src/rules/registry-loader.ts
 var import_node_fs30 = require("fs");
@@ -57924,7 +58139,12 @@ async function refreshRegistrySnapshot(cwd, _url = REGISTRY_URL, _timeoutMs = 5e
     snapshot: shadcn_registry_default,
     ok: true,
     fresh: false,
-    message: "Using bundled snapshot (upstream URL returns 404)."
+    // v0.42.0 (user-review fix): the previous message said
+    // "upstream URL returns 404" which is alarming without context —
+    // upstream has been dead since v0.39.0, and the bundled snapshot
+    // IS the snapshot in use. Replaced with a neutral message that
+    // doesn't suggest "something is wrong".
+    message: "Using bundled shadcn/ui snapshot (built-in; no network fetch)."
   };
 }
 function copyBundledSnapshotToCache(cwd) {
@@ -58095,16 +58315,23 @@ async function runDoctor(cwd) {
   lines.push("slopbrick doctor\n");
   lines.push("Checking your setup:\n");
   const nodeMajor = parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-  if (nodeMajor >= 20) ok(`Node ${process.versions.node}`);
+  if (nodeMajor >= 20) ok(`Node ${process.versions.node}, slopbrick ${VERSION}`);
   else fail(`Node ${process.versions.node} \u2014 slopbrick needs Node 20 or newer. Run: nvm install 20`);
   lines.push(`
   Working in: ${cwd}`);
   try {
+    const configPath = resolveConfigPath(cwd);
     const config = await loadConfig(cwd);
-    lines.push(`
-  \u2713 Config loaded from: ${resolveConfigPath(cwd) ?? "(default)"}`);
-    const ruleCount = Object.keys(config.rules ?? {}).length;
-    lines.push(`    ${ruleCount} rules configured in your config file.`);
+    if (configPath) {
+      const ruleCount = Object.keys(config.rules ?? {}).length;
+      lines.push(`
+  \u2713 Config loaded from: ${configPath}`);
+      lines.push(`    ${ruleCount} rule${ruleCount === 1 ? "" : "s"} configured in your config file.`);
+    } else {
+      lines.push(`
+  \u2713 Config: using built-in defaults (no config file found).`);
+      lines.push(import_chalk2.default.dim(`    Run \`slopbrick init\` to create ${cwd.endsWith("/") ? cwd : cwd + "/"}slopbrick.config.mjs and tune rule severity/rules to your project.`));
+    }
   } catch (error) {
     fail(`Could not read your config: ${error.message}`);
     exitCode = 3;
@@ -58161,6 +58388,7 @@ async function runDoctor(cwd) {
       ok(`Found ${scannable.length} source files to scan.`);
     } else {
       warn("No source files (.ts/.tsx/.js/.jsx/.vue/.svelte/.astro/.mdx) found in this directory.");
+      lines.push(import_chalk2.default.dim("    Run from a directory with source files, or pass --workspace <path>. Monorepos usually want `--workspace packages/<name>`."));
     }
   } catch {
   }
@@ -58225,7 +58453,7 @@ function registerBadge(program) {
     const health = loadHealth2(cwd);
     if (health) {
       const synthetic = {
-        slopIndex: 100 - health.repositoryHealth
+        aiSlopScore: health.aiSlopScore ?? 0
       };
       logger.info(formatBadge(synthetic));
       process.exit(0);
@@ -58769,7 +58997,11 @@ init_logger();
 init_builtins();
 init_data();
 function registerExplain(program) {
-  program.command("explain <ruleId>").description("Print rationale, pattern, and remediation for a single rule").action((ruleId) => {
+  program.command("explain [ruleId]").description("Print rationale, pattern, and remediation for a single rule. With no ruleId, lists the rules.").action((ruleId) => {
+    if (!ruleId) {
+      logger.warn("Missing ruleId. Run `slopbrick rules` to see available rules, then `slopbrick explain <ruleId>`.");
+      process.exit(2);
+    }
     const result = explainRule(ruleId, builtinRules, RULE_HINTS);
     logger.info(formatExplain(result));
     if ("error" in result) process.exit(2);
@@ -62688,7 +62920,7 @@ init_structure_md();
 var TOOL_DEFINITIONS = [
   {
     name: "slop_scan_file",
-    description: "Scan a single TypeScript/JavaScript file for AI-generated frontend slop. Returns issues (ruleId, severity, line, column, message, advice) and the file-level Slop Index.",
+    description: 'Scan a single TypeScript/JavaScript file for AI-generated frontend slop. Returns issues (ruleId, category, severity, line, column, message, advice), a composite AI-likelihood score (probability + confidenceTier), and a componentCount. The composite score is the Bayesian log-likelihood ratio of all rules that fired, NOT a per-file "Slop Index" \u2014 for project-level scores use slop_suggest.',
     inputSchema: {
       type: "object",
       properties: {
@@ -62704,7 +62936,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "slop_explain_rule",
-    description: "Return metadata for a single rule (id, category, severity, aiSpecific) plus a rationale and the recommended fix. Use this before auto-applying --fix to understand what the rule catches.",
+    description: "Return metadata for a single rule: ruleId, category, severity, aiSpecific, a brief rationale string, and a whereToLook path into src/rules/. The actual fix-steps live in the rule source (whereToLook) rather than in this response \u2014 read that file to understand the rule before auto-applying --fix.",
     inputSchema: {
       type: "object",
       properties: {
@@ -62725,7 +62957,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "slop_suggest",
-    description: "**Primary entry point for AI agents.** Returns the project's existing patterns (modals, buttons, api clients, state libs, data-fetching libs), the do-not-create list (forbidden imports + canonical patterns not to duplicate), top issues by rule, hot files by issue count, and the composite Repository Health score. Call this BEFORE writing new code so the agent reuses existing patterns instead of duplicating them.",
+    description: "**Primary entry point for AI agents.** Returns the project's existing patterns (modals, buttons, api clients, state libs, data-fetching libs), the do-not-create list (forbidden imports + canonical patterns not to duplicate), the declared stack, and (when .slopbrick/health.json exists) a Bayesian composite AI-likelihood score. Call this BEFORE writing new code so the agent reuses existing patterns instead of duplicating them. For per-issue details or per-file hot-spots, use slop_scan_file on each candidate path.",
     inputSchema: {
       type: "object",
       properties: {
@@ -62757,7 +62989,7 @@ var TOOL_DEFINITIONS = [
     // call slop_suggest and read repositoryHealth /
     // architectureConsistency / businessLogicCoherence.
     name: "slop_check_constitution",
-    description: "Check a single file against the project's declared constitution (stateManagement, dataFetching, uiLibrary, forms, styling, routing, plus a forbidden deny-list in slopbrick.config.mjs). Returns a list of imports that violate declared values or hit the deny-list. Use this on a newly-written or modified file before suggesting a PR.",
+    description: "Check a single file against the project's declared constitution (stateManagement, dataFetching, uiLibrary, forms, styling, routing, plus a forbidden deny-list in slopbrick.config.mjs). Returns the file path, total import + violation counts, the parsed imports, the list of violations (each with import, category, and reason), and a conventionSource indicating whether the constitution was declared, detected, or absent. Use this on a newly-written or modified file before suggesting a PR.",
     inputSchema: {
       type: "object",
       properties: {
@@ -62774,7 +63006,7 @@ var TOOL_DEFINITIONS = [
     // (sha256 over sorted hooks ∪ props ∪ params) + Jaccard similarity
     // — no LLM, no embeddings, deterministic. Foundation for StackPick.
     name: "slop_find_similar",
-    description: "Find the most similar existing function/component implementations across the codebase, ranked by Jaccard similarity over the union of (hooks \u222A props \u222A params). Use this BEFORE writing new code so the agent reuses an existing pattern instead of inventing a new one. Returns top-k matches with name, file, line, fingerprint, and similarity score in [0, 1].",
+    description: "Find the most similar existing function/component implementations across the codebase, ranked by Jaccard similarity over the union of (hooks \u222A props \u222A params). Use this BEFORE writing new code so the agent reuses an existing pattern instead of inventing a new one. Returns up to `limit` matches (default 10) with name, file, line, fingerprint (sha256 over signature), hooks, props, params, and similarity in [0, 1].",
     inputSchema: {
       type: "object",
       properties: {
@@ -63005,13 +63237,6 @@ async function runFindSimilar(args, ctx) {
   }
 }
 async function handleToolCall(toolName, args, ctx) {
-  const deprecation = getDeprecation(toolName);
-  const deprecationNotice = deprecation ? {
-    tool: toolName,
-    replacedBy: deprecation.replacedBy,
-    removedIn: deprecation.removedIn ?? "next major",
-    reason: deprecation.reason
-  } : void 0;
   switch (toolName) {
     case "slop_scan_file":
       return runScanFile(args, ctx);
@@ -63219,7 +63444,7 @@ var import_node_path46 = require("path");
 init_logger();
 init_dist();
 function registerCi(program, scanAction) {
-  program.command("ci").description("CI gate: run a scan and exit 1 on constitution violations, threshold breach, or new issues since the last run. Use this in GitHub Actions / GitLab CI.").option("--max-slop <n>", "exit 1 if slopIndex exceeds this number", parseCount).option("--max-new-issues <n>", "exit 1 if new issues (vs .slop-audit-cache.json) exceed this number", parseCount).option("--strict-constitution", "exit 1 on any constitution violation").option("--format <pretty|json>", "output format", "json").action(
+  program.command("ci").description("CI gate: run a scan and exit 1 on constitution violations, threshold breach, or new issues since the last run. Use this in GitHub Actions / GitLab CI.").option("--max-slop <n>", "exit 1 if aiSlopScore exceeds this number (lower = cleaner since v0.21)", parseCount).option("--max-new-issues <n>", "exit 1 if new issues (vs .slop-audit-cache.json) exceed this number", parseCount).option("--strict-constitution", "exit 1 on any constitution violation").option("--format <pretty|json>", "output format", "json").action(
     async (cmdOptions, command) => {
       const globals = command.optsWithGlobals();
       const options = {
@@ -63559,7 +63784,25 @@ function registerRules(program) {
         const sev = r.severity.padEnd(8);
         const tag = r.aiSpecific ? "[AI]" : "     ";
         lines.push(`  ${sev} ${tag} ${r.id}`);
-        if (r.description) lines.push(`           ${r.description}`);
+        if (r.description) {
+          const cols = process.stdout.isTTY ? process.stdout.columns ?? 100 : 100;
+          const indent = "           ";
+          const firstCol = indent.length + 1;
+          const maxWidth = Math.max(40, cols - firstCol);
+          const words = r.description.split(" ");
+          let line = "";
+          for (const word of words) {
+            if (line === "") {
+              line = word;
+            } else if ((line + " " + word).length > maxWidth) {
+              lines.push(indent + line);
+              line = word;
+            } else {
+              line = line + " " + word;
+            }
+          }
+          if (line) lines.push(indent + line);
+        }
       }
     }
     logger.info(lines.join("\n"));
@@ -64404,19 +64647,20 @@ function trendToText(report) {
   }
   const slopValues = report.points.map((p) => p.slopIndex);
   const spark = sparkline(slopValues);
-  lines.push("Slop Index trend (last " + report.points.length + " scans, " + report.totalScans + " total):");
+  lines.push("AI Slop Score trend (last " + report.points.length + " scans, " + report.totalScans + " total; lower = cleaner since v0.21):");
   lines.push("");
   lines.push("  " + spark + "  " + slopValues[0].toFixed(1) + " -> " + slopValues[slopValues.length - 1].toFixed(1));
   lines.push("");
   if (report.first && report.latest) {
     const direction = report.delta < 0 ? "improved" : report.delta > 0 ? "regressed" : "unchanged";
     const arrow = report.delta < 0 ? "v" : report.delta > 0 ? "^" : "=";
-    lines.push("  " + arrow + " Slop Index " + direction + " by " + Math.abs(report.delta).toFixed(1) + " points");
+    lines.push("  " + arrow + " AI Slop Score " + direction + " by " + Math.abs(report.delta).toFixed(1) + " points (lower = cleaner since v0.21)");
     lines.push("    " + report.first.timestamp + "  ->  " + report.latest.timestamp);
   }
   lines.push("");
   lines.push("Recent scans:");
-  lines.push("  Timestamp                  Slop    Health  Framework  Issues");
+  lines.push("  Timestamp                  AI Slop   Health  Framework  Issues");
+  lines.push("                             (lower=cleaner)");
   lines.push("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500   \u2500\u2500\u2500\u2500   \u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500");
   for (const p of report.points.slice(-10)) {
     const ts = p.timestamp.slice(0, 19).replace("T", " ");
@@ -64428,14 +64672,14 @@ function trendToText(report) {
 }
 function trendToMarkdown(report) {
   const lines = [];
-  lines.push("# Slop Index Trend");
+  lines.push("# AI Slop Score Trend (lower = cleaner since v0.21)");
   lines.push("");
   if (report.points.length === 0) {
     lines.push("No telemetry data yet. Run `slopbrick scan` to start tracking.");
     return lines.join("\n");
   }
   const slopValues = report.points.map((p) => p.slopIndex);
-  lines.push("Slop Index sparkline (last " + report.points.length + " scans):");
+  lines.push("AI Slop Score sparkline (last " + report.points.length + " scans; lower = cleaner since v0.21):");
   lines.push("");
   lines.push("```");
   lines.push(sparkline(slopValues));
@@ -64443,10 +64687,10 @@ function trendToMarkdown(report) {
   lines.push("");
   if (report.first && report.latest) {
     const direction = report.delta < 0 ? "improved" : report.delta > 0 ? "regressed" : "unchanged";
-    lines.push("Slop Index " + direction + " by **" + Math.abs(report.delta).toFixed(1) + " points** between first and latest scan.");
+    lines.push("AI Slop Score " + direction + " by **" + Math.abs(report.delta).toFixed(1) + " points** between first and latest scan (lower = cleaner since v0.21).");
   }
   lines.push("");
-  lines.push("| Timestamp | Slop Index | Health | Framework | Issues |");
+  lines.push("| Timestamp | AI Slop Score (lower = cleaner) | Health | Framework | Issues |");
   lines.push("|-----------|-----------:|-------:|-----------|-------:|");
   for (const p of report.points) {
     lines.push("| " + p.timestamp + " | " + p.slopIndex.toFixed(1) + " | " + p.assemblyHealth.toFixed(1) + " | " + p.framework + " | " + p.totalIssues + " |");
@@ -64456,7 +64700,7 @@ function trendToMarkdown(report) {
 
 // src/cli/commands/trend.ts
 function registerTrend(program) {
-  program.command("trend").description("Slop Index over time, from .slopbrick/flywheel/scans.jsonl").option("--max-points <n>", "how many recent scans to plot", parseCount, 30).option("--render <kind>", "output rendering: text | markdown", "text").action((cmdOptions) => {
+  program.command("trend").description("AI Slop Score over time, from .slopbrick/flywheel/scans.jsonl (lower = cleaner since v0.21)").option("--max-points <n>", "how many recent scans to plot", parseCount, 30).option("--render <kind>", "output rendering: text | markdown", "text").action((cmdOptions) => {
     try {
       const cwd = process.cwd();
       const report = buildTrend(cwd, cmdOptions.maxPoints);
@@ -64464,7 +64708,14 @@ function registerTrend(program) {
       logger.info(out);
       if (report.delta > 1) {
         logger.info("");
-        logger.info("Warning: Slop Index increased by " + report.delta.toFixed(1) + " points over this period.");
+        logger.info(
+          // v0.42.0: the legacy 'Slop Index increased' message implied higher
+          // = worse, which is the v0.15-v0.20.1 inverted reading. Since v0.21,
+          // AI Slop Score is lower-is-better; an INCREASE is worse, but
+          // the warning should say "AI Slop Score got worse" or just
+          // "delta went up" so users don't have to remember the direction.
+          `Warning: AI Slop Score got worse by ${report.delta.toFixed(1)} points over this period (lower = cleaner since v0.21).`
+        );
       }
     } catch (error) {
       logger.error(error instanceof Error ? error.message : String(error));
@@ -65082,13 +65333,13 @@ function parseUnifiedDiffPaths(diff) {
 async function runPrScanFromDiffFile(cwd, config, diffPath, options = {}) {
   const threshold = options.threshold ?? config.prScoreThreshold ?? 20;
   const maxFiles = options.maxFiles ?? 500;
-  const { existsSync: existsSync32, readFileSync: readFileSync42 } = await import("fs");
+  const { existsSync: existsSync31, readFileSync: readFileSync41 } = await import("fs");
   const { isAbsolute: isAbsolute4, resolve: resolvePath } = await import("path");
-  if (!existsSync32(diffPath)) {
+  if (!existsSync31(diffPath)) {
     throw new Error(`Diff file not found: ${diffPath}`);
   }
   const diffAbs = isAbsolute4(diffPath) ? diffPath : resolvePath(cwd, diffPath);
-  const diff = readFileSync42(diffAbs, "utf-8");
+  const diff = readFileSync41(diffAbs, "utf-8");
   const changedPaths = parseUnifiedDiffPaths(diff);
   if (changedPaths.length === 0) {
     return emptyPrResult(threshold);
@@ -65096,7 +65347,7 @@ async function runPrScanFromDiffFile(cwd, config, diffPath, options = {}) {
   return scoreChangedPaths(cwd, config, changedPaths, maxFiles, threshold);
 }
 async function scoreChangedPaths(cwd, config, paths, maxFiles, threshold) {
-  const { existsSync: existsSync32, statSync: statSync8 } = await import("fs");
+  const { existsSync: existsSync31, statSync: statSync8 } = await import("fs");
   const { resolve: resolvePath } = await import("path");
   const { readFile: readFile4 } = await import("fs/promises");
   const { scanFile: scanFile2 } = await Promise.resolve().then(() => (init_worker(), worker_exports));
@@ -65108,7 +65359,7 @@ async function scoreChangedPaths(cwd, config, paths, maxFiles, threshold) {
   let constitutionViolations = 0;
   for (const rel of limited) {
     const abs = resolvePath(cwd, rel);
-    if (!existsSync32(abs) || !statSync8(abs).isFile()) continue;
+    if (!existsSync31(abs) || !statSync8(abs).isFile()) continue;
     let source;
     try {
       source = await readFile4(abs, "utf-8");
@@ -65286,7 +65537,7 @@ var TEST_INCLUDE_GLOBS = [
   "**/__tests__/**/*.{ts,tsx,js,jsx}",
   "**/__fixtures__/**/*.{ts,tsx,js,jsx,json}"
 ];
-async function runTestScan(cwd, config, options = {}) {
+async function runTestScan(cwd, _config, options = {}) {
   const include = TEST_INCLUDE_GLOBS;
   const cliOptions = {
     include,
@@ -66235,7 +66486,7 @@ function formatText2(report) {
     const label = CATEGORY_LABELS2[cat].padEnd(20);
     const count = String(stats.count).padStart(2);
     const baseline = String(stats.baseline).padStart(1);
-    const excess = stats.excess > 0 ? `\u26A0 +${stats.excess} over` : "\u2713 clean";
+    const excess = stats.excess > 0 ? `\u26A0 +${stats.excess} over` : stats.count === 0 ? "\u2713 none" : "\u2713 within baseline";
     lines.push(`  ${label} ${count} implementations  (baseline ${baseline})  ${excess}`);
   }
   if (report.doNotCreate.length > 0) {
@@ -66293,7 +66544,7 @@ function formatMarkdown3(report) {
   for (const cat of PATTERN_CATEGORIES) {
     const stats = report.byCategory[cat];
     const label = CATEGORY_LABELS2[cat];
-    const excess = stats.excess > 0 ? `+${stats.excess}` : "\u2014";
+    const excess = stats.excess > 0 ? `+${stats.excess}` : stats.count === 0 ? "\u2014" : "\xB7";
     lines.push(`| ${label} | ${stats.count} | ${stats.baseline} | ${excess} |`);
   }
   if (report.doNotCreate.length > 0) {
@@ -66718,8 +66969,9 @@ function formatFlywheel(summary, options = {}) {
   if (summary.firstRunAt && summary.latestRunAt) {
     lines.push(`  Window: ${summary.firstRunAt} \u2192 ${summary.latestRunAt}`);
   }
-  lines.push(`  Average slop index: ${summary.averageSlopIndex.toFixed(2)}`);
-  lines.push(`  Latest slop index: ${summary.latestSlopIndex.toFixed(2)}`);
+  const directionNote = "  (lower = cleaner since v0.21.0)";
+  lines.push(`  Average AI Slop Score: ${summary.averageSlopIndex.toFixed(2)}`);
+  lines.push(`  Latest AI Slop Score: ${summary.latestSlopIndex.toFixed(2)}${directionNote}`);
   lines.push(`  Average assembly health: ${summary.averageAssemblyHealth.toFixed(2)}`);
   lines.push(`  Latest assembly health: ${summary.latestAssemblyHealth.toFixed(2)}`);
   if (summary.topViolations.length > 0) {
@@ -67066,7 +67318,7 @@ function applyVisualCodemods(filePath) {
 function collectAllFixes2(issue) {
   return [...issue.fix ? [issue.fix] : [], ...issue.fixes ?? []];
 }
-async function applyFixes(report, config, scannedFiles) {
+async function applyFixes(report, _config, scannedFiles) {
   const byFile = /* @__PURE__ */ new Map();
   for (const issue of report.issues) {
     const fixes = collectAllFixes2(issue);
@@ -67127,7 +67379,6 @@ async function applyFixes(report, config, scannedFiles) {
         const result = applyLayoutTokenFix(filePath, group.replaces);
         const total = group.replaceApps.length;
         const appliedCount = Math.min(result.applied, total);
-        const skippedCount = total - appliedCount;
         applied.push(...group.replaceApps.slice(0, appliedCount));
         skipped.push(...group.replaceApps.slice(appliedCount));
       } catch (err) {
@@ -67322,6 +67573,40 @@ function formatGroupedHelp(cmd) {
     }
   }
   lines.push("");
+  lines.push(
+    "Commands (run `<command> --help` for per-command details):\n" + [
+      "  scan     score a workspace, with severity gating and report views",
+      "  pr       score a PR (or a unified-diff file via `--diff <file>`)",
+      "  drift    detect constitution / forbidden-package violations",
+      "  test     test quality sub-score (CI gate)",
+      "  docs     documentation freshness sub-score",
+      "  security AI security-risk sub-score",
+      "  rules    list all built-in rules with categories and severities",
+      "  explain  show rationale, pattern, and remediation for a single rule",
+      "  suggest  print per-issue remediation advice",
+      "  badge    print a shields.io slop-index badge",
+      "  doctor   check setup, config, and environment for common problems",
+      "  init     create a slopbrick config file and AGENTS.md/CLAUDE.md snippets",
+      "  flywheel  summarize aggregated scan telemetry",
+      "  composite empirical-composite rule discover / enable (Sprint 3 \xA73b)",
+      "  calibrate empirical precision/recall/F1 calibration from held-out corpora",
+      "  patterns  pattern-fragmentation sub-score",
+      "  business-logic  business-logic coherence sub-score",
+      "  maintenance-cost  AI maintenance-cost sub-score",
+      "  architecture architecture-consistency sub-score",
+      "  memory   show patterns detected for `slop_suggest`",
+      "  lock     install a git pre-commit hook (idempotent)",
+      "  migrate  v0.10.x slop-audit/ \u2192 v0.11.0+ .slopbrick/ migration",
+      "  validate-config  validate slopbrick.config.mjs",
+      "  tokens   merge a design-tokens.json layout values into the allowlist",
+      "  report   re-render a saved JSON report (from --json <path>)",
+      "  install / uninstall  manage the git pre-commit hook",
+      "  mcp       run the MCP server (JSON-RPC 2.0 over stdio)",
+      "  watch / --watch  re-run scan on file change",
+      "  trend     sparkline of the last n runs"
+    ].join("\n")
+  );
+  lines.push("");
   lines.push(
     "Use `--help-flat` for the standard un-grouped list. See `https://usebrick.dev/docs/scan-options` for full docs."
   );
@@ -67439,7 +67724,7 @@ process.on("uncaughtException", (err) => {
 });
 async function runCli({ start }) {
   try {
-    const program = new import_commander3.Command().name("slopbrick").description("Repository Coherence Scanner \u2014 surface AI-induced pattern drift, secret leaks, and design-token violations").version(VERSION).option("--framework <name>", "framework multiplier to apply").option("--include <glob>", "include pattern (repeatable)", collectGlob, []).option("--exclude <glob>", "exclude pattern (repeatable)", collectGlob, []).option("--ai-only", "only report AI-specific issues").option("--human-only", "only report human-facing issues").option("--ignore-wcag22", "ignore WCAG 2.2 related issues").option("--format <pretty|json|sarif|html>", "output format", "pretty").option("--threads <n>", "number of worker threads", parseThreads).option("--since <ref>", "only scan files changed since git ref").option("--diff <ref>", "alias for --since <ref>; also adds PR Slop Score to the report").option("--workspace <path>", "workspace/project path", process.cwd()).option("--tighten", "tighten baseline allowances").option("--fix", "apply auto-fixes").option("--dry-run", "with --fix: print what would change without writing").option("--show-fixes-diff", "print unified diff of proposed auto-fixes").option("--doctor", "run diagnostics").option("--watch", "watch files and re-run").option("--suggest", "print remediation advice").option("--why-failing", "print the top 5 rules dragging the score down").option("--brief", "terse output (verdict + headline + threshold + delta only)").option("--heatmap", "print migration ROI heatmap").option("--quiet", "suppress non-error output").option("--verbose", "enable debug logging (file paths, timings, rule-fire counts)").option("--strict", "exit 2 if any high-severity issue remains").option("--no-increase", "exit 2 if slop index increased since last run").option("--refresh-snippets", "rewrite the managed slopbrick block in AGENTS.md and CLAUDE.md after a scan").option("--baseline", "save a baseline after this scan").option("--trend [n]", "print a sparkline of the last n runs", parseTrend).option("--json [path]", "write JSON report to path or stdout").option("--html [path]", "write HTML report to path or stdout").option("--staged", "scan only changed files (staged and unstaged)").option("--changed", "scan working-tree changes (staged + unstaged + untracked)").option("--incremental", "skip unchanged files using the persisted hash cache").option("--cache-path <path>", "path to the incremental-scan cache (default: .slopbrick-cache.json)").option("--tokens <path>", "merge tokens.json layout values into the arbitrary-value allowlist").option("--cache", "cache parsed AST results locally").option("--no-color", "suppress ANSI color codes in output").option("--security-only", "run only the security/* rules").option("--full", "show the complete report (all issues, all categories)").option("--report-usage", "opt in to a one-shot usage ping to SLOPBRICK_TELEMETRY_ENDPOINT (no PII)");
+    const program = new import_commander3.Command().name("slopbrick").description("Repository Coherence Scanner \u2014 surface AI-induced pattern drift, secret leaks, and design-token violations").version(VERSION).option("--framework <name>", "framework multiplier to apply").option("--include <glob>", "include pattern (repeatable)", collectGlob, []).option("--exclude <glob>", "exclude pattern (repeatable)", collectGlob, []).option("--ai-only", "only report AI-specific issues").option("--human-only", "only report human-facing issues").option("--ignore-wcag22", "ignore WCAG 2.2 related issues").option("--format <pretty|json|sarif|html>", "output format", "pretty").option("--threads <n>", "number of worker threads", parseThreads).option("--since <ref>", "only scan files changed since git ref").option("--diff <ref>", "alias for --since <ref>; also adds PR Slop Score to the report").option("--workspace <path>", "workspace/project path", process.cwd()).option("--tighten", "tighten baseline allowances").option("--fix", "apply auto-fixes").option("--dry-run", "with --fix: print what would change without writing").option("--show-fixes-diff", "print unified diff of proposed auto-fixes").option("--doctor", "run diagnostics").option("--watch", "watch files and re-run").option("--suggest", "print remediation advice").option("--why-failing", "print the top 5 rules dragging the score down").option("--brief", "terse output (verdict + headline + threshold + delta only)").option("--heatmap", "print migration ROI heatmap").option("--quiet", "suppress non-error output").option("--verbose", "enable debug logging (file paths, timings, rule-fire counts)").option("--strict", "exit 2 if any high-severity issue remains").option("--no-increase", "exit 2 if AI Slop Score increased since last run (lower = cleaner since v0.21)").option("--refresh-snippets", "rewrite the managed slopbrick block in AGENTS.md and CLAUDE.md after a scan").option("--baseline", "save a baseline after this scan").option("--trend [n]", "print a sparkline of the last n runs", parseTrend).option("--json [path]", "write JSON report to path or stdout").option("--html [path]", "write HTML report to path or stdout").option("--staged", "scan only changed files (staged and unstaged)").option("--changed", "scan working-tree changes (staged + unstaged + untracked)").option("--incremental", "skip unchanged files using the persisted hash cache").option("--cache-path <path>", "path to the incremental-scan cache (default: .slopbrick-cache.json)").option("--tokens <path>", "merge tokens.json layout values into the arbitrary-value allowlist").option("--cache", "cache parsed AST results locally").option("--no-color", "suppress ANSI color codes in output").option("--security-only", "run only the security/* rules").option("--full", "show the complete report (all issues, all categories)").option("--report-usage", "opt in to a one-shot usage ping to SLOPBRICK_TELEMETRY_ENDPOINT (no PII)");
     program.helpInformation = () => formatGroupedHelp(program);
     setExitOverride(program);
     registerInit(program);
@@ -67520,20 +67805,20 @@ async function runCli({ start }) {
         const gitHead = await getGitHead(cwd2) ?? "unknown";
         const cache = buildBaselineCache(report, configHash, gitHead, cwd2);
         saveBaseline(cwd2, cache);
-        if (!options.quiet) {
+        if (!options.quiet && !machineReadableStdout) {
           logger.info(`Saved baseline to ${baselinePath(cwd2)}`);
         }
       }
       if (options.tighten && baseline) {
         saveBaseline(cwd, baseline);
-        if (!options.quiet) {
+        if (!options.quiet && !machineReadableStdout) {
           logger.info(`Tightened baseline saved (revision ${baseline.baseline_revision}).`);
         }
       }
-      if (options.doctor && !options.quiet) {
+      if (options.doctor && !options.quiet && !machineReadableStdout) {
         logger.info(`Doctor: bootstrap ${totalElapsed - scanElapsed}ms, scan ${scanElapsed}ms`);
       }
-      if (report.baseline && !options.quiet) {
+      if (report.baseline && !options.quiet && !machineReadableStdout) {
         logger.info(baselineStatusMessage(report.baseline));
       }
       if (options.fix) {
@@ -67547,7 +67832,7 @@ async function runCli({ start }) {
         }
         const scannedFiles = results.map((r) => r.filePath);
         const fixResults = await applyFixes(report, config, scannedFiles);
-        const { totalApplied, totalSkipped, hasErrors } = printFixSummary(fixResults, options.quiet ?? false);
+        const { hasErrors } = printFixSummary(fixResults, options.quiet ?? false);
         if (!options.showFixesDiff && !options.quiet) {
           logger.info("Tip: pass --show-fixes-diff to see the unified diff of proposed changes.");
         }
@@ -67587,8 +67872,18 @@ async function runCli({ start }) {
         if (options.staged && stagedGatingResult.reason) {
           logger.error(`Gating failure: ${stagedGatingResult.reason}`);
         } else {
-          const failed = failedThresholdCount(report, config);
-          logger.error(`${failed} threshold${failed === 1 ? "" : "s"} failed. See details above.`);
+          const failedNames = failedThresholds(report, config);
+          const detail = failedNames.map((name) => {
+            if (name === "meanSlop") return `meanSlop (score ${report.aiSlopScore} > ${config.thresholds.meanSlop})`;
+            if (name === "p90Slop") return `p90Slop (score ${report.p90Score} > ${config.thresholds.p90Slop})`;
+            if (name === "individualSlopThreshold") return `individualSlopThreshold (peak ${report.peakScore} > ${config.thresholds.individualSlopThreshold})`;
+            const cat = name.replace(/^category:/, "");
+            const limit = config.thresholds.categoryThresholds?.[cat];
+            const score = report.categoryScores[cat];
+            return `${name} (score ${score} > ${limit})`;
+          }).join(", ");
+          const failed = failedNames.length;
+          logger.error(`${failed} threshold${failed === 1 ? "" : "s"} failed: ${detail}`);
         }
       }
       if (!options.quiet && !machineReadableStdout) {
@@ -67686,6 +67981,7 @@ init_render();
   directoryScore,
   extractSignatures,
   failedThresholdCount,
+  failedThresholds,
   filterByDisabledDirectives,
   filterIssues,
   findSimilarFunctions,