slopbrick 0.41.0 → 0.43.0

package/README.md

@@ -24,7 +24,7 @@ For the prevention layer:
 
 ```bash
 slopbrick watch           # re-run scan on every file change
-slopbrick lock            # install the Git pre-commit hook
+slopbrick install         # install the Git pre-commit hook
 slopbrick ci              # CI gate: exit 1 on constitution violation
 ```
 
@@ -40,14 +40,15 @@ on every scan — your repository, encoded for the next agent.
   inventory, constitution, health) make your codebase queryable by
   any AI agent in O(read file) instead of O(parse AST).
 - **LockBrick prevention** — `slopbrick watch` flags violations as you
-  write, `slopbrick lock` blocks AI-introduced slop at pre-commit,
+  write, `slopbrick install` blocks AI-introduced slop at pre-commit,
   `slopbrick ci` enforces the same in CI.
 - **Constitution** — declare your canonical stack (state lib, form
   lib, modal system, API client) once. The agent and the linter
   enforce it together.
 
-**Status:** v0.38.0 (current). See the [CHANGELOG](./CHANGELOG.md) for
-the full release notes.
+**Status:** v0.43.0 (current) (current). Engine: 103 rules in 22 categories,
+4 headline scores, 9+ language frontends, v10-calibrated against 576,750
+real files. See [CHANGELOG](./CHANGELOG.md) for the full release notes.
 
 ---
 
@@ -78,27 +79,31 @@ For every other config question, see [`EXAMPLES.md`](./EXAMPLES.md).
 
 ## The headlines (4-score model, v0.21.0+)
 
-> **v0.15.0 introduced the 4-score model; v0.21.0 FLIPPED `aiSlopScore`
-> to the natural-reading "raw amount" direction (0=clean, 100=saturated).**
-> The other three scores stay "higher = better". The legacy `slopIndex`
-> field is kept as optional on `ProjectReport` for backward compat with
-> existing test fixtures and historical telemetry; the v0.14-compat
+> **v0.15.0 introduced the 4-score model. v0.21.0 FLIPPED `aiSlopScore`
+> to the natural-reading "raw amount of slop" direction
+> (0 = clean, 100 = saturated, **lower = cleaner**).** v0.18.0 added
+> the 4th score (security). The other three scores stay "higher = better".
+> The legacy `slopIndex` field is kept as optional on `ProjectReport`
+> for backward compat with existing test fixtures; the v0.14-compat
 > removal is tracked separately.
 
 | Score | What it measures | Direction | CI gate? |
 |-------|------------------|-----------|----------|
-| **`aiSlopScore`** | AI-slop signatures (16 `ai/*` rules). | **lower = cleaner** (raw amount) | **Yes** (`≤ meanSlop: 30` passes) |
+| **`aiSlopScore`** | AI-slop signatures (16 `ai/*` rules). | **lower = cleaner** (raw amount of slop) | **Yes** (`≤ meanSlop` passes; default 30) |
 | **`engineeringHygiene`** | Average of 6 category scores: arch, logic, layout, visual, component, test | higher = better | No (informational) |
-| **`security`** | AI Security Risk band: low=100, medium=67, high=33, critical=0 | higher = better | No (informational) |
-| **`repositoryHealth`** (composite) | Weighted: `0.4 × (100 − aiSlopScore) + 0.3 × eng + 0.2 × sec + 0.1 × test` | higher = better (inverts `aiSlopScore` internally) | No (informational) |
+| **`security`** | AI Security Risk band: low=100, medium=75, high=40, critical=10 | higher = better | No (informational) |
+| **`repositoryHealth`** | Weighted average of 8 axes (slopIndex, architectureConsistency, aiSecurityRisk, designTokenViolations, testQuality, businessLogicCoherence, docFreshness, dbHealth). Default weights in `REPOSITORY_HEALTH_WEIGHTS`. | higher = better | No (informational) |
 
 **Score-band messages** (v0.21.0+): every score ships with a one-line
 verdict in the pretty output — e.g. `AI Slop Score: 25 → "low amount
-of slop"`, `Security Risk: 33 → "high risk"`. See `src/report/pretty.ts`.
+of AI slop"`, `Security Risk: low`. The band mapping for aiSlopScore
+is **0–9 no slop**, **10–29 low**, **30–49 medium**, **50–69 high**,
+**70–100 saturated** (v0.21.0 lower-is-better direction). See
+`src/report/pretty.ts`.
 
-The same numbers are in `.slopbrick/health.json`.
+The same numbers live in `.slopbrick/health.json`.
 
-For the full math, the 2×2 quadrant, and which one to focus on, see
+For the full math, the 4-score quadrant, and which one to focus on, see
 [`docs/scoring-explained.md`](./docs/scoring-explained.md).
 
 For per-rule precision/recall/FPR (auditable), see
@@ -110,8 +115,7 @@ For per-rule precision/recall/FPR (auditable), see
 
 Starting in **v0.24.0**, slopbrick can send a single one-shot usage
 ping after `slopbrick scan` completes. This is **opt-in** — the
-default is OFF — and is intended for the v9 corpus build script
-and self-hosted CI.
+default is OFF — and is intended for self-hosted CI telemetry.
 
 ### How to opt in
 
@@ -134,13 +138,13 @@ A single POST with `Content-Type: application/json` and exactly
 | Field | Type | Example | Source |
 |-------|------|---------|--------|
 | `schema_version` | string | `"1"` | constant |
-| `slopbrick_version` | string | `"0.24.0"` | `package.json` |
+| `slopbrick_version` | string | `"0.42.0"` | `package.json` |
 | `scan_id` | string (UUID v4) | `"f47ac10b-…"` | generated per run |
 | `file_count` | int | `42` | `results.length` |
-| `rule_count` | int | `95` | `builtinRules.length` |
+| `rule_count` | int | `103` | `builtinRules.length` |
 | `duration_ms` | int | `1834` | wall-clock scan time |
 | `platform` | string | `"darwin"` | `process.platform` |
-| `node_version` | string | `"v20.11.0"` | `process.version` |
+| `node_version` | string | `"v24.15.0"` | `process.version` |
 
 ### Privacy promise
 
@@ -181,42 +185,27 @@ for the receiver.
 ## Example output
 
 ```text
-$ npx slopbrick scan
-Repo is concerning (25/100). The biggest problem is AI patterns — worst file is src/cli/scan.ts. Run `slopbrick scan --why-failing` for the top 5 rules, or `slopbrick scan --suggest` for fixes.
-
-AI Slop Score:  25 / 100 [HIGH]  ↑5 (worse)
-higher = better · measures AI-slop signatures. The same number in .slopbrick/health.json.
-  ├─ boundary:  10  (40%)  — structural integrity
-  ├─ context:   50  (35%)  — props / state / imports
-  └─ visual:     5  (25%)  — CSS / a11y / layout
-
-Engineering Hygiene:  60 / 100 [NEEDS WORK] — higher = better · measures internal consistency. This is a secondary view; the AI Slop Score above is the gate.
-
-Other signals (not the gate):
-  Code Hygiene          75/100
-  Accessibility        100/100
-  Performance          100/100
-  Business Logic         0/100
-  Security Risk        LOW
-
-✓ 99 INVERTED/NOISY issues correctly suppressed from 24 default-off rules.
-
-Category breakdown (what kind of issue, and how much):
-  AI patterns      ████████████████████    167 — signatures of LLM-generated code
-  visual style     ████████░░░░░░░░░░░░     70 — colors, spacing, font sizes, layout
-  logic patterns   ████████░░░░░░░░░░░░     68 — state, hooks, prop usage
-  13 other categories are clean
-
-Next step:
-  → `slopbrick scan --rule src/cli/scan.ts` to drill into the worst file (4 issues)
-  → `slopbrick scan --suggest` for auto-fix advice
-  → `slopbrick scan --baseline` to accept today's scores as the new floor
-  → `slopbrick scan --why-failing` for the top 5 issues dragging the score down
+$ npx slopbrick scan --brief
+[v0.43.0] auto-suppressed 184 INVERTED/NOISY issue(s) from 18 default-off rule(s).
+Memory persisted to .slopbrick/ (0 patterns, 0 components, 537 bytes of structure.md).
+
+Repo is low (25/100). The biggest problem is AI patterns — worst file is packages/slopbrick/src/engine/parser-rust.ts.
+
+  AI Slop Score         25   low  (aiSlopScore)
+  Engineering Hygiene  100   excellent  (engineeringHygiene)
+  Security             100   excellent  (security)
+  Repository Health     57   needs work  (repositoryHealth)
+
+  CI gate: AI Slop Score <= 15 -> fail
+
+  Scanned 593 files, 346 issues. Run with --all for the full report.
+1 threshold failed: meanSlop (score 25 > 15)
 ```
 
 `--brief` (CI/scripts): same headline + threshold + delta in 4 lines.
 `--why-failing`: top 5 rules ranked by weighted impact.
 `--suggest`: per-rule auto-fix advice.
+`--human-only` / `--ai-only`: filter issues by category.
 
 ---
 
@@ -226,14 +215,14 @@ Next step:
 |-------------------|-----------|
 | Add a new rule (most common contribution) | [`CONTRIBUTING.md`](./CONTRIBUTING.md) |
 | Configure for strict CI, monorepo, Python, etc. | [`EXAMPLES.md`](./EXAMPLES.md) |
-| Understand the Slop Index vs Coherence | [`docs/scoring-explained.md`](./docs/scoring-explained.md) |
+| Understand the 4-score model (AI Slop Score, Engineering Hygiene, Security, Repository Health) | [`docs/scoring-explained.md`](./docs/scoring-explained.md) |
 | Connect Claude Code / Cursor / Copilot | [`docs/MCP.md`](./docs/MCP.md) |
 | See the 4 `.slopbrick/` artifacts (structure, inventory, ...) | [`docs/repository-structure.md`](./docs/repository-structure.md) |
 | See the 103 rules (per-rule descriptions + citations) | [`docs/rule-catalog.md`](./docs/rule-catalog.md) |
 | See how the engine works (parser → facts → rules) | [`docs/architecture.md`](./docs/architecture.md) |
 | See which frameworks are supported | [`docs/framework-parity-matrix.md`](./docs/framework-parity-matrix.md) |
 | See what's changed in each release | [`CHANGELOG.md`](./CHANGELOG.md) |
-| See the strategic plan (0.14 → 0.15 → 1.0) | [`ROADMAP.md`](./ROADMAP.md) |
+| See the strategic plan (v0.x → v1.0) | [`ROADMAP.md`](./ROADMAP.md) |
 | See research behind the calibration | [`docs/research/`](./docs/research/) |
 | Report a security vulnerability | [`SECURITY.md`](./SECURITY.md) |
 | Run a CI gate | `slopbrick ci` (see [`EXAMPLES.md`](./EXAMPLES.md#strict-ci-gate)) |
@@ -249,8 +238,9 @@ The 19 subcommands are auto-generated from commander and run
 npm install -D slopbrick
 ```
 
-Requires Node 18+. The package ships ESM + CJS dual builds, TypeScript
-types, and is published to npm as `slopbrick`.
+Requires Node 20+ (verified by `slopbrick doctor`). The package ships
+ESM + CJS dual builds, TypeScript types, and is published to npm as
+`slopbrick`.
 
 For the MCP server, add to your AI agent's config:
 

package/bin/slopbrick.js

@@ -1,6 +1,27 @@
 #!/usr/bin/env node
+// Top-level error guards: converts unhandled exceptions into a
+// human-readable message + a non-zero exit code, instead of the
+// default Node "UnhandledPromiseRejectionWarning" + stack trace.
+// Without this, a transitive module-throwing-on-load (e.g. a
+// config importer with a syntax error) showed a stack trace and
+// exited with code 1 + a useless warning, confusing new users.
 (async () => {
   const start = performance.now();
-  const { runCli } = await import('../dist/index.js');
-  await runCli({ start });
+  try {
+    const { runCli } = await import('../dist/index.js');
+    await runCli({ start });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`slopbrick: unhandled error — ${msg}\n`);
+    process.exit(1);
+  }
 })();
+process.on('unhandledRejection', (reason) => {
+  const msg = reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(`slopbrick: unhandled rejection — ${msg}\n`);
+  process.exit(1);
+});
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`slopbrick: uncaught exception — ${err.message}\n`);
+  process.exit(1);
+});

package/dist/engine/worker.cjs

@@ -6897,6 +6897,26 @@ function dispatchNode(node, parent, path, vctx) {
 // src/engine/parser-rust.ts
 var import_tree_sitter = __toESM(require("tree-sitter"), 1);
 var import_tree_sitter_rust = __toESM(require("tree-sitter-rust"), 1);
+
+// 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;
+  }
+}
+
+// src/engine/parser-rust.ts
 var cachedParser = null;
 var rustLanguage = null;
 var loadError = null;
@@ -6923,21 +6943,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();
@@ -7551,8 +7557,6 @@ function mergeTemplateClassNames(filePath, source, facts, templateClassNames) {
 }
 function extractFacts(filePath, ast, source, supportsRsc = true, framework = "react", config) {
   const lineOffsets = buildLineOffsets(source);
-  const isTypeScript = /\.tsx?$/i.test(filePath);
-  const NON_JSX_FRAMEWORKS = /* @__PURE__ */ new Set(["vue", "svelte", "astro"]);
   const facts = {
     filePath,
     components: [],
@@ -32976,7 +32980,7 @@ var aiCommentRatioRule = createRule({
         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;
@@ -33750,7 +33754,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;
@@ -35543,7 +35546,7 @@ var RESERVED = /* @__PURE__ */ new Set([
 ]);
 var SOURCE_EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var SOURCE_ROOTS = ["src", "lib", "app", "components"];
-var CAP = 200;
+var CAP = 4e3;
 function walk(dir, out, cap) {
   if (!(0, import_node_fs.existsSync)(dir) || out.length >= cap) return;
   let entries;
@@ -35623,6 +35626,7 @@ var staleFunctionReferenceRule = createRule({
     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;
@@ -35785,6 +35789,7 @@ var stalePackageReferenceRule = createRule({
     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);
@@ -35830,6 +35835,8 @@ var stalePackageReferenceRule = createRule({
 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] ?? "";
@@ -35837,13 +35844,22 @@ 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;
 }
 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] ?? "";
@@ -35851,10 +35867,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_path3.join)(cwd, "package.json");
@@ -35874,8 +35935,63 @@ function declaredPackages(cwd) {
   }
   return out;
 }
+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;
+}
 
 // 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 brokenLinkRule = createRule({
   id: "docs/broken-link",
   category: "docs",
@@ -35898,6 +36014,8 @@ var brokenLinkRule = createRule({
       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_path4.join)(docDir, filePart);
@@ -37222,8 +37340,16 @@ var DEFAULT_CONFIG3 = {
       // 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/**"
     ]
   }
 };
@@ -41124,23 +41250,16 @@ var builtinRules = [
 // src/rules/registry.ts
 var RuleRegistry = class {
   rules = /* @__PURE__ */ new Map();
-  register(ruleOrId, factory) {
-    if (typeof ruleOrId === "string") {
-      if (!factory) {
-        throw new Error("Factory is required when registering by id");
-      }
-      const rule = {
-        id: ruleOrId,
-        category: factory.category,
-        severity: factory.severity,
-        aiSpecific: factory.aiSpecific,
-        create: factory.create,
-        analyze: factory.analyze
-      };
-      this.rules.set(ruleOrId, rule);
-    } else {
-      this.rules.set(ruleOrId.id, ruleOrId);
-    }
+  /**
+   * Register a rule. The 2-arg overload `register(id, factory)` was
+   * deleted in v0.42.0 (architecture review F6): no callers used it,
+   * every `Rule` carries its own `id`, and the per-id registration
+   * was ergonomically redundant with the 1-arg form (`register(rule)`).
+   * External consumers that needed `register-by-id` semantics can
+   * construct a `Rule` directly and pass it in.
+   */
+  register(rule) {
+    this.rules.set(rule.id, rule);
   }
   loadBuiltins(onlyRuleId) {
     for (const rule of builtinRules) {
@@ -41169,6 +41288,15 @@ var RuleRegistry = class {
   all() {
     return Array.from(this.rules.values());
   }
+  /** v0.42.0 (§3b.5): look up a registered rule by id.
+   *  Returns undefined if not registered. */
+  get(id) {
+    return this.rules.get(id);
+  }
+  /** v0.42.0 (§3b.5): check whether a rule id is registered. */
+  has(id) {
+    return this.rules.has(id);
+  }
   createContexts(config, filePath, cwd, hotspotIssues = []) {
     const context = {
       config,
@@ -44863,6 +44991,36 @@ async function scanFile(filePath, config, registry, cwd = process.cwd()) {
     const issues = applyRuleOverrides(rawIssues, config.rules);
     const triggeredRuleIds = Array.from(new Set(issues.map((i) => i.ruleId)));
     const compScore = compositeScore(triggeredRuleIds, loadSignalStrength());
+    const fireSet = new Set(triggeredRuleIds);
+    const factsWithFireSet = Object.assign(facts, {
+      compositeFireSet: fireSet
+    });
+    for (const { rule } of rules) {
+      if (!rule.id.startsWith("composite/")) continue;
+      try {
+        const compositeIssues = rule.analyze(
+          rule.create({
+            config,
+            filePath,
+            cwd,
+            framework: config.framework,
+            uiLibraries: config.uiLibraries,
+            hasTailwind: config.hasTailwind,
+            supportsRsc: config.supportsRsc,
+            hotspotIssues: []
+          }),
+          factsWithFireSet
+        );
+        if (compositeIssues.length > 0) {
+          issues.push(...compositeIssues);
+          for (const ci of compositeIssues) fireSet.add(ci.ruleId);
+        }
+      } catch (err) {
+        if (process.env.SLOP_AUDIT_DEBUG === "1") {
+          console.error(`[worker] composite ${rule.id} threw: ${err.message}`);
+        }
+      }
+    }
     const gapValues = collectGapValues(facts);
     const styleSources = collectStyleSources(facts);
     const elementTags = facts.v2.jsx.elements.map((e) => e.tag);