slopbrick 0.40.0 → 0.41.0

package/dist/index.js

@@ -19,7 +19,7 @@ var VERSION;
 var init_header = __esm({
   "src/types/_header.ts"() {
     "use strict";
-    VERSION = "0.40.0";
+    VERSION = "0.41.0";
   }
 });
 
@@ -45804,6 +45804,15 @@ function formatCompositeScore(report) {
       )
     );
   }
+  const composite = report.compositeScore;
+  if (composite !== void 0) {
+    lines.push("");
+    lines.push(
+      chalk.dim(
+        `composite=${composite.tier}@${composite.mean.toFixed(2)} \u2014 project-level Bayesian aggregate across ${composite.fileCount} file${composite.fileCount === 1 ? "" : "s"} (max ${composite.max.toFixed(2)}); informational, does not gate CI.`
+      )
+    );
+  }
   return lines.join("\n");
 }
 function formatCoherenceScores(report) {
@@ -54226,6 +54235,21 @@ function safeRelative(cwd, filePath) {
     return filePath;
   }
 }
+function buildInventorySummary(inventory) {
+  const patternCounts = {};
+  const patternNames = {};
+  for (const [category, matches] of Object.entries(inventory.patterns)) {
+    if (matches.length === 0) continue;
+    const names = Array.from(new Set(matches.map((m) => m.name))).sort();
+    patternCounts[category] = names.length;
+    patternNames[category] = names.slice(0, TELEMETRY_INVENTORY_NAME_CAP);
+  }
+  return {
+    scannedFiles: inventory.scannedFiles,
+    patternCounts,
+    patternNames
+  };
+}
 function aggregateViolations(report) {
   const counts = /* @__PURE__ */ new Map();
   for (const issue of report.issues) {
@@ -54305,7 +54329,7 @@ function readTelemetry(cwd) {
   }
   return payloads;
 }
-function recordTelemetry(cwd, report, results, config) {
+function recordTelemetry(cwd, report, results, config, inventory) {
   if (config.telemetry === false) {
     return void 0;
   }
@@ -54326,7 +54350,14 @@ function recordTelemetry(cwd, report, results, config) {
       framework: config.framework
     },
     violations: aggregateViolations(report),
-    files: buildFileRecords(cwd, report, results)
+    files: buildFileRecords(cwd, report, results),
+    // v0.41.0 (Sprint 2, task 2a.1): the inventory summary is
+    // additive — omitting it (legacy callers) keeps the JSONL line
+    // shape identical to v0.40.x payloads, so old readers stay
+    // green. New readers (`slopbrick drift --since <date>` in
+    // Sprint 2a.2) treat the field as optional and fall back to
+    // a re-scan when it's missing.
+    ...inventory ? { inventory: buildInventorySummary(inventory) } : {}
   };
   const path = telemetryPath2(cwd);
   const dir = dirname11(path);
@@ -54337,7 +54368,7 @@ function recordTelemetry(cwd, report, results, config) {
   appendFileSync(path, JSON.stringify(payload) + "\n", "utf-8");
   return payload;
 }
-var TELEMETRY_DIR, TELEMETRY_FILE2, MAX_TELEMETRY_BYTES, MAX_ROTATED_FILES;
+var TELEMETRY_DIR, TELEMETRY_FILE2, MAX_TELEMETRY_BYTES, MAX_ROTATED_FILES, TELEMETRY_INVENTORY_NAME_CAP;
 var init_telemetry = __esm({
   "src/engine/telemetry.ts"() {
     "use strict";
@@ -54345,6 +54376,7 @@ var init_telemetry = __esm({
     TELEMETRY_FILE2 = "scans.jsonl";
     MAX_TELEMETRY_BYTES = 10 * 1024 * 1024;
     MAX_ROTATED_FILES = 5;
+    TELEMETRY_INVENTORY_NAME_CAP = 50;
   }
 });
 
@@ -54660,11 +54692,11 @@ async function persistRun(input) {
     }
     report.issues.push(...flywheelOutput.hotspotIssues);
   }
-  recordTelemetry(cwd, report, results, config);
+  let patternInventory;
   if (config.projectMemory !== false) {
     try {
       const durationMs = Date.now() - startTime;
-      const patternInventory = await buildPatternInventory(cwd, config);
+      patternInventory = await buildPatternInventory(cwd, config);
       const inventory = buildInventoryFromScan(
         { cwd, results },
         patternInventory,
@@ -54698,6 +54730,7 @@ async function persistRun(input) {
       }
     }
   }
+  recordTelemetry(cwd, report, results, config, patternInventory);
 }
 var init_persistRun = __esm({
   "src/cli/report/persistRun.ts"() {
@@ -55078,6 +55111,7 @@ function formatSarif(report, options) {
   const results = report.issues.map(
     (issue) => buildResultFromIssue(issue, options?.cwd, fileContentCache)
   );
+  const driverProperties = report.compositeScore ? { compositeScore: report.compositeScore } : void 0;
   const log = {
     $schema: "https://json.schemastore.org/sarif-2.1.0.json",
     version: "2.1.0",
@@ -55088,7 +55122,8 @@ function formatSarif(report, options) {
             name: "slopbrick",
             version: report.version,
             informationUri: REPO_INFORMATION_URI,
-            rules
+            rules,
+            ...driverProperties ? { properties: driverProperties } : {}
           }
         },
         results
@@ -57075,402 +57110,6 @@ var init_scan2 = __esm({
   }
 });
 
-// src/mcp/slop-suggest-structure.ts
-async function runSuggestWithStructure(args, ctx) {
-  const cached = await readStructureMarkdown(ctx.cwd);
-  if (cached !== null) {
-    return {
-      content: [{ type: "text", text: cached }]
-    };
-  }
-  const { handleToolCall: handleToolCall2 } = await Promise.resolve().then(() => (init_tools(), tools_exports));
-  const result = await handleToolCall2("slop_suggest", args, ctx);
-  if (result.isError) return result;
-  try {
-    const parsed = JSON.parse(result.content[0].text);
-    if (parsed !== null && typeof parsed === "object") {
-      parsed.structureHint = STRUCTURE_NOT_FOUND_HINT;
-      return {
-        content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }]
-      };
-    }
-  } catch {
-  }
-  return result;
-}
-var STRUCTURE_NOT_FOUND_HINT;
-var init_slop_suggest_structure = __esm({
-  "src/mcp/slop-suggest-structure.ts"() {
-    "use strict";
-    init_structure_md();
-    STRUCTURE_NOT_FOUND_HINT = "No .slopbrick/structure.md found. Run `slopbrick scan` to persist the pattern inventory, then call this tool again for the O(read file) fast path.";
-  }
-});
-
-// src/mcp/tools.ts
-var tools_exports = {};
-__export(tools_exports, {
-  TOOL_DEFINITIONS: () => TOOL_DEFINITIONS,
-  canonicalToolNames: () => canonicalToolNames,
-  getDeprecation: () => getDeprecation,
-  handleToolCall: () => handleToolCall
-});
-import { readFileSync as readFileSync27 } from "fs";
-import { resolve as resolve17 } from "path";
-function toolError(message) {
-  return {
-    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
-    isError: true
-  };
-}
-async function runScanFile(args, ctx) {
-  const path = args.path;
-  if (!path) return toolError("Missing required argument: path");
-  const result = await scanFile(path, ctx.config);
-  const simplified = {
-    filePath: result.filePath,
-    componentCount: result.componentCount,
-    parseError: result.parseError,
-    issues: result.issues.map((i) => ({
-      ruleId: i.ruleId,
-      category: i.category,
-      severity: i.severity,
-      line: i.line,
-      column: i.column,
-      message: i.message,
-      advice: i.advice
-    }))
-  };
-  return {
-    content: [{ type: "text", text: JSON.stringify(simplified, null, 2) }]
-  };
-}
-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);
-  if (!rule) return toolError("Unknown rule: " + ruleId);
-  const explanation = {
-    ruleId: rule.id,
-    category: rule.category,
-    severity: rule.severity,
-    aiSpecific: rule.aiSpecific,
-    rationale: "This rule flags " + rule.category + " patterns associated with AI-generated code. It is marked as " + (rule.aiSpecific ? "AI-specific" : "cross-cutting") + ". Severity: " + rule.severity + ".",
-    whereToLook: "src/rules/" + rule.category + "/" + rule.id.replace(/^[^/]+\//, "") + ".ts"
-  };
-  return {
-    content: [{ type: "text", text: JSON.stringify(explanation, null, 2) }]
-  };
-}
-function listRules(args, ctx) {
-  const category = args.category;
-  const filtered = category ? ctx.rules.filter((r) => r.category === category) : ctx.rules;
-  const rules = filtered.map((r) => ({
-    id: r.id,
-    category: r.category,
-    severity: r.severity,
-    aiSpecific: r.aiSpecific
-  }));
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({ count: rules.length, rules }, null, 2)
-      }
-    ]
-  };
-}
-async function runSuggest(args, ctx) {
-  const maxFilesRaw = args.maxFiles;
-  const maxFiles = typeof maxFilesRaw === "number" && Number.isFinite(maxFilesRaw) && maxFilesRaw > 0 ? Math.min(2e3, Math.floor(maxFilesRaw)) : 200;
-  try {
-    const inventory = await buildPatternInventory(ctx.cwd, ctx.config, maxFiles);
-    const doNotCreate = [
-      ...ctx.config.constitution?.forbidden ?? []
-    ];
-    const declared = /* @__PURE__ */ new Set();
-    for (const list of [
-      ctx.config.constitution?.stateManagement ?? [],
-      ctx.config.constitution?.dataFetching ?? [],
-      ctx.config.constitution?.uiLibrary ?? [],
-      ctx.config.constitution?.forms ?? [],
-      ctx.config.constitution?.styling ?? [],
-      ctx.config.constitution?.routing ?? []
-    ]) {
-      for (const lib of list) declared.add(lib);
-    }
-    const doNotCreateCapped = doNotCreate.slice(0, 10);
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            {
-              hint: "Use these patterns instead of creating new ones. Pick the closest existing entry and import it. The `doNotCreate` list is the deny-list \u2014 never import any of these.",
-              doNotCreate: doNotCreateCapped,
-              declaredStack: Array.from(declared),
-              existingPatterns: inventory
-            },
-            null,
-            2
-          )
-        }
-      ]
-    };
-  } catch (err) {
-    return toolError(err instanceof Error ? err.message : String(err));
-  }
-}
-function runCheckConstitution(args, ctx) {
-  const path = args.path;
-  if (!path) return toolError("Missing required argument: path");
-  const absPath = resolve17(ctx.cwd, path);
-  let source;
-  try {
-    source = readFileSync27(absPath, "utf-8");
-  } catch (err) {
-    return toolError(
-      `Cannot read file ${absPath}: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-  const result = checkFileConstitution(source, ctx.config.constitution);
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify(
-          {
-            file: absPath,
-            importCount: result.imports.length,
-            violationCount: result.violations.length,
-            imports: result.imports,
-            violations: result.violations,
-            // Field name kept stable for backward compatibility with
-            // older consumers; the value reflects whether the merged
-            // `config.constitution` was declared, detected, or absent.
-            conventionSource: ctx.config.constitution ? "declared-or-detected" : "none"
-          },
-          null,
-          2
-        )
-      }
-    ]
-  };
-}
-async function runFindSimilar(args, ctx) {
-  const { findSimilarFunctions: findSimilarFunctions2 } = await Promise.resolve().then(() => (init_dist2(), dist_exports2));
-  const hooks = Array.isArray(args.hooks) ? args.hooks : [];
-  const props = Array.isArray(args.props) ? args.props : [];
-  const limitRaw = args.limit;
-  const limit = typeof limitRaw === "number" && Number.isFinite(limitRaw) && limitRaw > 0 ? Math.floor(limitRaw) : 10;
-  try {
-    const matches = await findSimilarFunctions2(
-      {
-        name: typeof args.name === "string" ? args.name : void 0,
-        hooks,
-        props,
-        limit,
-        workspaceDir: ctx.cwd
-      },
-      { cwd: ctx.cwd }
-    );
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            {
-              hint: "Each match is ranked by Jaccard similarity over (hooks \u222A props \u222A params). similarity=1 means the matched signature has an identical feature set. Agents should prefer the top match instead of writing a new implementation.",
-              count: matches.length,
-              matches: matches.map((m) => ({
-                name: m.signature.name,
-                file: m.signature.fileRel,
-                line: m.signature.line,
-                similarity: Number(m.similarity.toFixed(3)),
-                fingerprint: m.fingerprint,
-                hooks: m.signature.hooks,
-                props: m.signature.props,
-                params: m.signature.params
-              }))
-            },
-            null,
-            2
-          )
-        }
-      ]
-    };
-  } catch (err) {
-    return toolError(err instanceof Error ? err.message : String(err));
-  }
-}
-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);
-    case "slop_explain_rule":
-      return explainRule2(args, ctx);
-    case "slop_list_rules":
-      return listRules(args, ctx);
-    case "slop_suggest":
-      return runSuggest(args, ctx);
-    case "slop_suggest_with_structure":
-      return runSuggestWithStructure(args, ctx);
-    // v0.39.0: removed 3 deprecated tools (slop_governance,
-    // slop_architecture_score, slop_business_logic_score) that
-    // were marked for removal in v0.13.0 but never removed.
-    // Their runner functions (runGovernance, runArchitectureScore,
-    // runBusinessLogicScore) are kept in the file for now
-    // (marked @deprecated) to keep the diff small; they can be
-    // deleted in a follow-up. New clients will never see these
-    // tools listed in the MCP tools/list response.
-    case "slop_check_constitution":
-      return runCheckConstitution(args, ctx);
-    case "slop_find_similar":
-      return runFindSimilar(args, ctx);
-    default:
-      return toolError("Unknown tool: " + toolName);
-  }
-}
-function canonicalToolNames() {
-  return TOOL_DEFINITIONS.filter((t) => !t.deprecated).map((t) => t.name);
-}
-function getDeprecation(toolName) {
-  return TOOL_DEFINITIONS.find((t) => t.name === toolName)?.deprecated;
-}
-var TOOL_DEFINITIONS;
-var init_tools = __esm({
-  "src/mcp/tools.ts"() {
-    "use strict";
-    init_worker();
-    init_patterns();
-    init_architecture_score();
-    init_business_logic();
-    init_slop_suggest_structure();
-    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.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            path: { type: "string", description: "Absolute or cwd-relative path to the source file." },
-            framework: {
-              type: "string",
-              enum: ["react", "vue", "svelte", "astro", "html"],
-              description: "Framework multiplier to apply. Defaults to the configured framework."
-            }
-          },
-          required: ["path"]
-        }
-      },
-      {
-        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.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            ruleId: { type: "string", description: 'e.g. "visual/ai-default-palette".' }
-          },
-          required: ["ruleId"]
-        }
-      },
-      {
-        name: "slop_list_rules",
-        description: "List all registered rules with their category, severity, and aiSpecific flag. Optional category filter (visual | logic | wcag | security | perf | typo | layout | component | arch).",
-        inputSchema: {
-          type: "object",
-          properties: {
-            category: { type: "string", description: "Optional category filter." }
-          }
-        }
-      },
-      {
-        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.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            maxFiles: {
-              type: "number",
-              description: "Cap on files scanned to keep the inventory cheap. Defaults to 200."
-            }
-          }
-        }
-      },
-      {
-        name: "slop_suggest_with_structure",
-        description: "Fast-path variant of `slop_suggest` that reads `.slopbrick/structure.md` from disk instead of re-scanning the codebase. Requires a prior `slopbrick scan` to have persisted the inventory (100\u20131000\xD7 latency win on the agent integration). If `structure.md` is missing, falls back to `slop_suggest` and annotates the response with `structureHint` so the caller knows to run `slopbrick scan` first.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            maxFiles: {
-              type: "number",
-              description: "Cap on files scanned for the slow-path fallback. Defaults to 200."
-            }
-          }
-        }
-      },
-      {
-        // v0.39.0: removed 3 deprecated tools (slop_governance,
-        // slop_architecture_score, slop_business_logic_score) that
-        // were marked for removal in v0.13.0 but never removed.
-        // They were strict subsets of slop_suggest; users should
-        // 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.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            path: { type: "string", description: "Absolute or cwd-relative path to the source file." }
-          },
-          required: ["path"]
-        }
-      },
-      {
-        // v0.10.1: find_similar_function. The GIR (Give-Implementation-
-        // Reference) primitive for slop_suggest. Given a function signature
-        // (name + hooks + props), find the most similar existing
-        // implementations across the codebase. Uses AST fingerprints
-        // (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].",
-        inputSchema: {
-          type: "object",
-          properties: {
-            name: {
-              type: "string",
-              description: "Function/component name to match. Omit to match by hooks+props only."
-            },
-            hooks: {
-              type: "array",
-              items: { type: "string" },
-              description: 'React hooks used by the target signature, e.g. ["useState", "useEffect"].'
-            },
-            props: {
-              type: "array",
-              items: { type: "string" },
-              description: 'Component props for the target signature, e.g. ["variant", "size", "children"].'
-            },
-            limit: {
-              type: "number",
-              description: "Top-k results to return. Default 10. Capped at 50."
-            }
-          }
-        }
-      }
-    ];
-  }
-});
-
 // src/index.ts
 init_types();
 init_config2();
@@ -62141,7 +61780,374 @@ init_logger();
 init_builtins();
 init_config2();
 init_header();
-init_tools();
+
+// src/mcp/tools.ts
+init_worker();
+init_patterns();
+init_architecture_score();
+init_business_logic();
+init_structure_md();
+import { readFileSync as readFileSync27 } from "fs";
+import { resolve as resolve17 } from "path";
+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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or cwd-relative path to the source file." },
+        framework: {
+          type: "string",
+          enum: ["react", "vue", "svelte", "astro", "html"],
+          description: "Framework multiplier to apply. Defaults to the configured framework."
+        }
+      },
+      required: ["path"]
+    }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ruleId: { type: "string", description: 'e.g. "visual/ai-default-palette".' }
+      },
+      required: ["ruleId"]
+    }
+  },
+  {
+    name: "slop_list_rules",
+    description: "List all registered rules with their category, severity, and aiSpecific flag. Optional category filter (visual | logic | wcag | security | perf | typo | layout | component | arch).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: { type: "string", description: "Optional category filter." }
+      }
+    }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        maxFiles: {
+          type: "number",
+          description: "Cap on files scanned to keep the inventory cheap. Defaults to 200."
+        }
+      }
+    }
+  },
+  {
+    name: "slop_suggest_with_structure",
+    description: "Fast-path variant of `slop_suggest` that reads `.slopbrick/structure.md` from disk instead of re-scanning the codebase. Requires a prior `slopbrick scan` to have persisted the inventory (100\u20131000\xD7 latency win on the agent integration). If `structure.md` is missing, falls back to `slop_suggest` and annotates the response with `structureHint` so the caller knows to run `slopbrick scan` first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        maxFiles: {
+          type: "number",
+          description: "Cap on files scanned for the slow-path fallback. Defaults to 200."
+        }
+      }
+    }
+  },
+  {
+    // v0.39.0: removed 3 deprecated tools (slop_governance,
+    // slop_architecture_score, slop_business_logic_score) that
+    // were marked for removal in v0.13.0 but never removed.
+    // They were strict subsets of slop_suggest; users should
+    // 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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or cwd-relative path to the source file." }
+      },
+      required: ["path"]
+    }
+  },
+  {
+    // v0.10.1: find_similar_function. The GIR (Give-Implementation-
+    // Reference) primitive for slop_suggest. Given a function signature
+    // (name + hooks + props), find the most similar existing
+    // implementations across the codebase. Uses AST fingerprints
+    // (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].",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Function/component name to match. Omit to match by hooks+props only."
+        },
+        hooks: {
+          type: "array",
+          items: { type: "string" },
+          description: 'React hooks used by the target signature, e.g. ["useState", "useEffect"].'
+        },
+        props: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Component props for the target signature, e.g. ["variant", "size", "children"].'
+        },
+        limit: {
+          type: "number",
+          description: "Top-k results to return. Default 10. Capped at 50."
+        }
+      }
+    }
+  }
+];
+function toolError(message) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    isError: true
+  };
+}
+async function runScanFile(args, ctx) {
+  const path = args.path;
+  if (!path) return toolError("Missing required argument: path");
+  const result = await scanFile(path, ctx.config);
+  const simplified = {
+    filePath: result.filePath,
+    componentCount: result.componentCount,
+    parseError: result.parseError,
+    issues: result.issues.map((i) => ({
+      ruleId: i.ruleId,
+      category: i.category,
+      severity: i.severity,
+      line: i.line,
+      column: i.column,
+      message: i.message,
+      advice: i.advice
+    }))
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(simplified, null, 2) }]
+  };
+}
+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);
+  if (!rule) return toolError("Unknown rule: " + ruleId);
+  const explanation = {
+    ruleId: rule.id,
+    category: rule.category,
+    severity: rule.severity,
+    aiSpecific: rule.aiSpecific,
+    rationale: "This rule flags " + rule.category + " patterns associated with AI-generated code. It is marked as " + (rule.aiSpecific ? "AI-specific" : "cross-cutting") + ". Severity: " + rule.severity + ".",
+    whereToLook: "src/rules/" + rule.category + "/" + rule.id.replace(/^[^/]+\//, "") + ".ts"
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(explanation, null, 2) }]
+  };
+}
+function listRules(args, ctx) {
+  const category = args.category;
+  const filtered = category ? ctx.rules.filter((r) => r.category === category) : ctx.rules;
+  const rules = filtered.map((r) => ({
+    id: r.id,
+    category: r.category,
+    severity: r.severity,
+    aiSpecific: r.aiSpecific
+  }));
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ count: rules.length, rules }, null, 2)
+      }
+    ]
+  };
+}
+var STRUCTURE_NOT_FOUND_HINT = "No .slopbrick/structure.md found. Run `slopbrick scan` to persist the pattern inventory, then call this tool again for the O(read file) fast path.";
+async function runSuggest(args, ctx, options = {}) {
+  const { includeStructure = false } = options;
+  if (includeStructure) {
+    const cached = await readStructureMarkdown(ctx.cwd);
+    if (cached !== null) {
+      return {
+        content: [{ type: "text", text: cached }]
+      };
+    }
+  }
+  const maxFilesRaw = args.maxFiles;
+  const maxFiles = typeof maxFilesRaw === "number" && Number.isFinite(maxFilesRaw) && maxFilesRaw > 0 ? Math.min(2e3, Math.floor(maxFilesRaw)) : 200;
+  try {
+    const inventory = await buildPatternInventory(ctx.cwd, ctx.config, maxFiles);
+    const doNotCreate = [
+      ...ctx.config.constitution?.forbidden ?? []
+    ];
+    const declared = /* @__PURE__ */ new Set();
+    for (const list of [
+      ctx.config.constitution?.stateManagement ?? [],
+      ctx.config.constitution?.dataFetching ?? [],
+      ctx.config.constitution?.uiLibrary ?? [],
+      ctx.config.constitution?.forms ?? [],
+      ctx.config.constitution?.styling ?? [],
+      ctx.config.constitution?.routing ?? []
+    ]) {
+      for (const lib of list) declared.add(lib);
+    }
+    const doNotCreateCapped = doNotCreate.slice(0, 10);
+    const payload = {
+      hint: "Use these patterns instead of creating new ones. Pick the closest existing entry and import it. The `doNotCreate` list is the deny-list \u2014 never import any of these.",
+      doNotCreate: doNotCreateCapped,
+      declaredStack: Array.from(declared),
+      existingPatterns: inventory
+    };
+    if (includeStructure) {
+      payload.structureHint = STRUCTURE_NOT_FOUND_HINT;
+    }
+    try {
+      const { loadHealth: loadHealth2 } = await Promise.resolve().then(() => (init_dist(), dist_exports));
+      const health = loadHealth2(ctx.cwd);
+      if (health?.compositeScore) {
+        payload.compositeScore = health.compositeScore;
+      }
+    } catch {
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(payload, null, 2)
+        }
+      ]
+    };
+  } catch (err) {
+    return toolError(err instanceof Error ? err.message : String(err));
+  }
+}
+function runCheckConstitution(args, ctx) {
+  const path = args.path;
+  if (!path) return toolError("Missing required argument: path");
+  const absPath = resolve17(ctx.cwd, path);
+  let source;
+  try {
+    source = readFileSync27(absPath, "utf-8");
+  } catch (err) {
+    return toolError(
+      `Cannot read file ${absPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const result = checkFileConstitution(source, ctx.config.constitution);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            file: absPath,
+            importCount: result.imports.length,
+            violationCount: result.violations.length,
+            imports: result.imports,
+            violations: result.violations,
+            // Field name kept stable for backward compatibility with
+            // older consumers; the value reflects whether the merged
+            // `config.constitution` was declared, detected, or absent.
+            conventionSource: ctx.config.constitution ? "declared-or-detected" : "none"
+          },
+          null,
+          2
+        )
+      }
+    ]
+  };
+}
+async function runFindSimilar(args, ctx) {
+  const { findSimilarFunctions: findSimilarFunctions2 } = await Promise.resolve().then(() => (init_dist2(), dist_exports2));
+  const hooks = Array.isArray(args.hooks) ? args.hooks : [];
+  const props = Array.isArray(args.props) ? args.props : [];
+  const limitRaw = args.limit;
+  const limit = typeof limitRaw === "number" && Number.isFinite(limitRaw) && limitRaw > 0 ? Math.floor(limitRaw) : 10;
+  try {
+    const matches = await findSimilarFunctions2(
+      {
+        name: typeof args.name === "string" ? args.name : void 0,
+        hooks,
+        props,
+        limit,
+        workspaceDir: ctx.cwd
+      },
+      { cwd: ctx.cwd }
+    );
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              hint: "Each match is ranked by Jaccard similarity over (hooks \u222A props \u222A params). similarity=1 means the matched signature has an identical feature set. Agents should prefer the top match instead of writing a new implementation.",
+              count: matches.length,
+              matches: matches.map((m) => ({
+                name: m.signature.name,
+                file: m.signature.fileRel,
+                line: m.signature.line,
+                similarity: Number(m.similarity.toFixed(3)),
+                fingerprint: m.fingerprint,
+                hooks: m.signature.hooks,
+                props: m.signature.props,
+                params: m.signature.params
+              }))
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  } catch (err) {
+    return toolError(err instanceof Error ? err.message : String(err));
+  }
+}
+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);
+    case "slop_explain_rule":
+      return explainRule2(args, ctx);
+    case "slop_list_rules":
+      return listRules(args, ctx);
+    case "slop_suggest":
+      return runSuggest(args, ctx);
+    case "slop_suggest_with_structure":
+      return runSuggest(args, ctx, { includeStructure: true });
+    // v0.39.0: removed 3 deprecated tools (slop_governance,
+    // slop_architecture_score, slop_business_logic_score) that
+    // were marked for removal in v0.13.0 but never removed.
+    // Their runner functions (runGovernance, runArchitectureScore,
+    // runBusinessLogicScore) are kept in the file for now
+    // (marked @deprecated) to keep the diff small; they can be
+    // deleted in a follow-up. New clients will never see these
+    // tools listed in the MCP tools/list response.
+    case "slop_check_constitution":
+      return runCheckConstitution(args, ctx);
+    case "slop_find_similar":
+      return runFindSimilar(args, ctx);
+    default:
+      return toolError("Unknown tool: " + toolName);
+  }
+}
+function getDeprecation(toolName) {
+  return TOOL_DEFINITIONS.find((t) => t.name === toolName)?.deprecated;
+}
+
+// src/mcp/server.ts
 var SERVER_INFO = {
   name: "slopbrick",
   // v0.39.0: use the VERSION constant (same source as the CLI)
@@ -63579,6 +63585,7 @@ import { resolve as resolve26 } from "path";
 // src/cli/drift.ts
 init_discover();
 init_patterns();
+init_telemetry();
 import { readFileSync as readFileSync30 } from "fs";
 import { basename as basename4, relative as relative16 } from "path";
 async function runDrift(cwd, config, options = {}) {
@@ -63688,26 +63695,217 @@ function formatDrift(result, opts = {}) {
 function driftExitCode(result) {
   return result.totalViolations > 0 ? 1 : 0;
 }
+async function runDriftOverTime(cwd, config, options) {
+  const payloads = readTelemetry(cwd);
+  const sortedAsc = [...payloads].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  const withInventory = sortedAsc.filter((p) => p.inventory !== void 0);
+  const baselineSource = options.since === "baseline" ? "baseline" : "since";
+  let baseline;
+  if (baselineSource === "baseline") {
+    baseline = withInventory[0];
+  } else {
+    baseline = withInventory.find((p) => p.timestamp >= options.since);
+  }
+  const current = withInventory.at(-1);
+  if (!baseline || !current) {
+    return {
+      scannedFiles: 0,
+      filesWithViolations: 0,
+      totalViolations: 0,
+      byCategory: {},
+      byFile: [],
+      conventionSource: deriveSource(config.constitution),
+      constitution: config.constitution,
+      introduced: [],
+      removed: [],
+      introducedUndeclared: [],
+      snapshotsConsidered: withInventory.length,
+      driftScore: 0,
+      baselineAt: baseline?.timestamp ?? "",
+      currentAt: current?.timestamp ?? "",
+      baselineSource
+    };
+  }
+  const baselineNames = flattenPatternNames(baseline.inventory.patternNames);
+  const currentNames = flattenPatternNames(current.inventory.patternNames);
+  const baselineSet = new Set(baselineNames.map((p) => `${p.category}\0${p.name}`));
+  const currentSet = new Set(currentNames.map((p) => `${p.category}\0${p.name}`));
+  const introduced = [];
+  const removed = [];
+  for (const p of currentNames) {
+    const key = `${p.category}\0${p.name}`;
+    if (!baselineSet.has(key)) introduced.push(p);
+  }
+  for (const p of baselineNames) {
+    const key = `${p.category}\0${p.name}`;
+    if (!currentSet.has(key)) removed.push(p);
+  }
+  introduced.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+  removed.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+  const declared = collectDeclaredNames(config.constitution);
+  const introducedUndeclared = introduced.filter((p) => !declared.has(p.name.toLowerCase()));
+  const baselineTotal = Math.max(baselineSet.size, 1);
+  const driftScore = Math.min(
+    100,
+    Math.round((introduced.length + removed.length) / baselineTotal * 100)
+  );
+  return {
+    scannedFiles: current.inventory.scannedFiles,
+    filesWithViolations: 0,
+    totalViolations: 0,
+    byCategory: {},
+    byFile: [],
+    conventionSource: deriveSource(config.constitution),
+    constitution: config.constitution,
+    introduced,
+    removed,
+    introducedUndeclared,
+    snapshotsConsidered: withInventory.length,
+    driftScore,
+    baselineAt: baseline.timestamp,
+    currentAt: current.timestamp,
+    baselineSource
+  };
+}
+function flattenPatternNames(patternNames) {
+  const out = [];
+  for (const [category, names] of Object.entries(patternNames)) {
+    for (const name of names) {
+      out.push({ category, name });
+    }
+  }
+  out.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+  return out;
+}
+function collectDeclaredNames(constitution) {
+  const out = /* @__PURE__ */ new Set();
+  if (!constitution) return out;
+  const fields = ["stateManagement", "dataFetching", "uiLibrary", "forms", "styling", "routing"];
+  for (const f of fields) {
+    for (const v of constitution[f] ?? []) {
+      out.add(v.toLowerCase());
+    }
+  }
+  for (const list of Object.values(constitution.custom ?? {})) {
+    for (const v of list) {
+      out.add(v.toLowerCase());
+    }
+  }
+  for (const v of constitution.forbidden ?? []) {
+    out.add(v.toLowerCase());
+  }
+  return out;
+}
+function formatDriftOverTime(result) {
+  const lines = [];
+  lines.push("Temporal drift report");
+  lines.push("");
+  if (result.snapshotsConsidered === 0 || !result.baselineAt || !result.currentAt) {
+    lines.push("  No historical telemetry found at .slopbrick/flywheel/scans.jsonl.");
+    lines.push("  Run a few scans with `slopbrick scan` first; the temporal drift");
+    lines.push("  detector needs \u2265 2 scan payloads to compute a baseline window.");
+    return lines.join("\n");
+  }
+  const sinceLabel = result.baselineSource === "baseline" ? `baseline (oldest scan)` : `since ${result.baselineAt}`;
+  lines.push(`  Window: ${sinceLabel} \u2192 ${result.currentAt}`);
+  lines.push(`  Snapshots considered: ${result.snapshotsConsidered}`);
+  lines.push(`  Drift score: ${result.driftScore} / 100  (informational)`);
+  lines.push("");
+  lines.push(`  Patterns introduced: ${result.introduced.length}`);
+  for (const p of result.introduced) {
+    lines.push(`    + ${p.category}/${p.name}`);
+  }
+  if (result.introducedUndeclared.length > 0) {
+    lines.push("");
+    lines.push(
+      `  Patterns introduced but not in declared constitution: ${result.introducedUndeclared.length}`
+    );
+    for (const p of result.introducedUndeclared) {
+      lines.push(`    ! ${p.category}/${p.name}`);
+    }
+  }
+  lines.push("");
+  lines.push(`  Patterns removed: ${result.removed.length}`);
+  for (const p of result.removed) {
+    lines.push(`    - ${p.category}/${p.name}`);
+  }
+  lines.push("");
+  if (result.introducedUndeclared.length > 0) {
+    lines.push(
+      "  Tip: add undeclared patterns to slopbrick.config.mjs#constitution to"
+    );
+    lines.push("  promote them into the declared set on the next scan.");
+  } else if (result.introduced.length === 0 && result.removed.length === 0) {
+    lines.push("  \u2713 No pattern churn since the baseline window.");
+  }
+  return lines.join("\n");
+}
+function driftOverTimeExitCode(result) {
+  return result.introducedUndeclared.length > 0 ? 1 : 0;
+}
+
+// src/cli/commands/drift.ts
+init_load();
+
+// src/cli/commands/_shared.ts
+init_logger();
+import { CommanderError } from "commander";
+function setExitOverride(program) {
+  program.exitOverride();
+}
+async function dispatch(program, runFn) {
+  try {
+    await runFn();
+  } catch (err) {
+    if (err instanceof CommanderError) {
+      if (err.code !== "commander.helpDisplayed" && err.code !== "commander.help") {
+        logger.error(err.message);
+      }
+      process.exit(err.exitCode);
+      return;
+    }
+    throw err;
+  }
+}
+function withExitCode(result, compute, message) {
+  const code = compute(result);
+  if (code === 0) return;
+  throw new CommanderError(code, "slopbrick.exit", message);
+}
 
 // src/cli/commands/drift.ts
 function registerDrift(program) {
   program.command("drift").description(
     "detect imports that violate declared constitution (state, data-fetching, UI, forms, styling, routing) or import forbidden packages"
-  ).option("--format <pretty|json>", "output format", "pretty").option("--max-files <n>", "cap on files scanned", parseCount, 1e3).action(
+  ).option("--format <pretty|json>", "output format", "pretty").option("--max-files <n>", "cap on files scanned", parseCount, 1e3).option(
+    "--temporal-since <date>",
+    `temporal drift since the given date (ISO-8601, or the literal string \`baseline\` to use the oldest scan in scans.jsonl)`
+  ).action(
     async (cmdOptions, command) => {
-      try {
-        const options = command.optsWithGlobals();
-        const rawFormat = options.format ?? cmdOptions.format ?? "pretty";
-        const format = rawFormat === "json" || rawFormat === "pretty" ? rawFormat : "pretty";
-        const cwd = resolve26(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" }));
-        process.exit(driftExitCode(result));
-      } catch (err) {
-        logger.error(err instanceof Error ? err.message : String(err));
-        process.exit(2);
+      const options = command.optsWithGlobals();
+      const rawFormat = options.format ?? cmdOptions.format ?? "pretty";
+      const format = rawFormat === "json" || rawFormat === "pretty" ? rawFormat : "pretty";
+      const cwd = resolve26(options.workspace ?? process.cwd());
+      if (cmdOptions.temporalSince !== void 0) {
+        const temporalSince = cmdOptions.temporalSince.trim();
+        if (temporalSince.length === 0) {
+          throw new Error("--temporal-since expects a non-empty ISO date or `baseline`");
+        }
+        const sinceArg = temporalSince === "baseline" ? "baseline" : temporalSince;
+        const config2 = await loadConfig(cwd);
+        const result2 = await runDriftOverTime(cwd, config2, { since: sinceArg });
+        logger.info(formatDriftOverTime(result2));
+        withExitCode(
+          result2,
+          driftOverTimeExitCode,
+          `drift --temporal-since: ${result2.introducedUndeclared.length} undeclared patterns introduced`
+        );
+        return;
       }
+      const { config } = await runScan({ ...options, workspace: cwd });
+      const result = await runDrift(cwd, config, { maxFiles: cmdOptions.maxFiles });
+      logger.info(formatDrift(result, { json: format === "json" }));
+      withExitCode(result, driftExitCode, `drift: ${result.totalViolations} violations`);
     }
   );
 }
@@ -66368,6 +66566,7 @@ async function runCli({ start }) {
   try {
     const program = new 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("--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);
     registerInstall(program);
     registerUninstall(program);
@@ -66552,7 +66751,9 @@ async function runCli({ start }) {
       program.outputHelp();
       process.exit(0);
     }
-    await program.parseAsync(process.argv);
+    await dispatch(program, async () => {
+      await program.parseAsync(process.argv);
+    });
   } catch (err) {
     if (err instanceof ConfigValidationError) {
       logger.error(err.message);