slopbrick 0.11.0

package/README.md

@@ -0,0 +1,902 @@
+# slopbrick
+
+> **The AI-coding-agent drift detector.** Stops the `zustand + redux in the same project`, the three-modal-systems, the off-scale `p-[13px]`, the hardcoded `sk-...` keys, and the `expect(x).toBeDefined()` tests that no one wrote and no one will run. Run `npx slopbrick` and get a single Repository Coherence score (0–100) with per-rule precision/recall so you know which findings to fix and which to ignore. Add the MCP server and your AI agent reads your existing patterns before it writes new ones.
+
+**The problem.** AI coding assistants write logic well, but they drift. Every project ends up with three button variants, a hardcoded API key, inline styles next to Tailwind utilities, and a test file full of `expect(x).toBeDefined()`. The drift isn't the agent's fault — it's that the agent doesn't know your conventions. Existing linters catch syntax; nothing catches "you just invented a fourth modal system when this repo already has three."
+
+**What this does.** `slopbrick` extracts the canonical patterns from your codebase (state lib, form lib, modal system, API client, data-fetching), enforces a declared Constitution at PR time, and exposes the pattern inventory to AI agents via MCP (`slop_suggest`) so they reuse what's there instead of inventing new patterns. The headline Repository Coherence score (0–100) is a proof that the Constitution is being followed — but the actual moat is the Constitution + Pattern Inventory itself, not the number.
+
+## What an AI agent gets from `slop_suggest` (the primary entry point)
+
+The MCP tool `slop_suggest` returns, in one call:
+
+- **Existing patterns** — the canonical modal, button, API client, state library, data-fetching library the project already uses.
+- **Do-not-create list** — explicit `constitution.forbidden` packages + canonical patterns not to duplicate.
+- **Top issues by rule** — what to fix first in the changed files.
+- **Hot files by issue count** — where the slop is concentrated.
+- **Composite Repository Health** — the headline 0-100 score.
+
+> **Call this BEFORE writing new code so the agent reuses existing patterns instead of duplicating them.**
+
+`src/mcp/tools.ts:69-81`. The MCP server is one command: `slopbrick mcp`.
+
+## Headline 5-bucket score (compressed from 13 subscores)
+
+The full diagnostic surface is 13 subscores. The user-facing surface is 5 buckets:
+
+| Bucket | What it measures | One-line question | v4.1 calibration |
+|--------|------------------|-------------------|------------------|
+| **Architecture Consistency** | Cross-file pattern duplication + token usage + component reuse | "Are components and patterns consistent?" | 8 USEFUL rules, top signal: Pattern Fragmentation |
+| **AI Slop Signal** | Ghost defensive code, debug logs, unused state, missing auth, hardcoded secrets | "Does this look like AI wrote it?" | 18 USEFUL rules with measured P/R/FPR |
+| **Security** | Hardcoded secrets, dangerous CORS, unsafe HTML, SQL concat, missing auth | "Are there security holes?" | 4 USEFUL, 3 INVERTED |
+| **Delivery Quality** | Test quality, business-logic coherence, docs freshness | "Can the team ship safely?" | 4 PASS, 3 INVERTED |
+| **Codebase Health** | DB schema, design-token drift, product consistency | "Will this codebase hold up at scale?" | 5 INVERTED/DORMANT — calibration pending |
+
+`Repository Health` (the composite) = `0.25 × Architecture + 0.30 × AI Slop + 0.25 × Security + 0.10 × Delivery + 0.10 × Codebase`.
+
+The 13-subscore diagnostic surface remains available behind `slopbrick scan --format json` and `--format detailed` for the calibration / power-user audience.
+
+## Why this works (calibration evidence, v4.1)
+
+The rules are calibrated against a balanced 1:1 corpus:
+
+- **95,467 human-written frontend files** — 39 production repos (mui 16k, supabase 6.8k, antd 5.5k, storybook 3.5k, react-spectrum 3.3k, refine 6.3k, appsmith 5.5k, heroui 2.1k, …) + 54,980 from `ai-slop-baseline`.
+- **76,981 AI-generated frontend files** — 50 existing repos + **100 NEW shallow-cloned vibe-coded repos** (Claude Code, Cursor, Lovable, Bolt, gpt-pilot, v0, BloopAI, tldraw) in `corpus-expansion/positive/vibe-coded/`.
+
+The form engineers actually trust, per-rule (full table in [`docs/research/v4-per-rule-pr-fpr.md`](./docs/research/v4-per-rule-pr-fpr.md)):
+
+> `security/missing-auth-check` fires on **0.63% of AI files** and **0.04% of human files**. When it fires, **92% of the time the file is AI**.
+
+Top 5 AI signals (v4.1 P/R/FPR):
+
+| Rule | Precision | Lift | Verdict |
+|------|----------:|-----:|---------|
+| `logic/ghost-defensive` (dead `if (x) return` guards) | 94.74% | 22.5× | USEFUL |
+| `security/missing-auth-check` (auth bypass) | 92.47% | 15.3× | USEFUL |
+| `logic/math-console-log-storm` (debug logs everywhere) | 89.84% | 11.0× | USEFUL |
+| `logic/zombie-state` (unused `useState`) | 83.33% | 6.2× | USEFUL |
+| `test/duplicate-setup` (`beforeEach` copy-paste) | 70.97% | 3.1× | USEFUL |
+
+The 18 USEFUL rules have **per-file P/R/FPR thresholds** in `tests/integration/calibration-expanded.test.ts` that fail CI when the signal drifts. See [`docs/research/calibration-report-2026.md`](./docs/research/calibration-report-2026.md) for the full calibration trajectory (v1 ratio → v3 ratio → v4 ratio → **v4.1 P/R/FPR**).
+
+## For humans
+
+- `slopbrick scan` in CI gates PRs on `slopIndex` and the Constitution.
+- `slopbrick pr` scores the PR itself, weighted by severity.
+- `slopbrick architecture` is the headline consistency number.
+- `slopbrick security` is the categorical security gate.
+- `slopbrick test` / `business-logic` / `patterns` / `db` are specialised subcommands.
+- `slopbrick drift` exits 1 on any Constitution violation.
+- `slopbrick --format json` exposes the 13-subscore diagnostic surface + per-rule P/R/FPR for the calibration audience.
+
+## For AI agents
+
+Install the MCP server (`@slopbrick/mcp`), then call `slop_suggest` before writing new code. The agent never has to guess what's already in the codebase.
+
+## What it does not do
+
+It does **not** detect whether a human or AI wrote the code. It surfaces patterns that AI generates disproportionately (4 modal systems, exposed `NEXT_PUBLIC_OPENAI_API_KEY`, `if (NODE_ENV === 'development') return true`), and enforces the constitution the project has declared.
+
+---
+
+## 13-score diagnostic surface (for the calibration audience)
+
+The headline 5-bucket score is a compression of 13 subscores. The full surface is what `slopbrick scan --format json` returns, and what the [`tests/integration/calibration-expanded.test.ts`](./tests/integration/calibration-expanded.test.ts) test guards against drift.
+
+**Tier 1 — Deterministic (Constitution enforcement):**
+
+| Score | Shape | Use it for |
+|-------|-------|------------|
+| **Slop Index** | 0–100 | Frontend lint quality (composite) |
+| **Architecture Consistency** | 0–100 | Cross-file pattern duplication |
+| **AI Security Risk** | `low` / `medium` / `high` / `critical` | AI-induced security failures |
+| **Constitution drift** | pass / fail | Imports that violate the declared stack |
+| **Design-token drift** | inline violations | Spacing/radius off declared scales |
+| **Pattern Fragmentation** | 0–100 | How many competing patterns per category (modal / auth / state / api / …) — *the input to `slop_suggest`'s `doNotCreate` list* |
+| **PR Slop Score** | integer | One number per PR, weighted by severity |
+
+**Tier 2 — Heuristic (specialised subcommands):**
+
+| Score | Shape | Use it for |
+|-------|-------|------------|
+| **Test Quality** | 0–100 | AI test smells |
+| **Business Logic Coherence** | 0–100 | Pricing precision, validation completeness |
+| **Documentation Freshness** | 0–100 | Stale READMEs, drift between docs and code |
+| **Database Health** | 0–100 | Missing indexes, N+1, soft-delete inconsistencies |
+
+**Tier 3 — Derived (dashboards):**
+
+| Score | Shape | Use it for |
+|-------|-------|------------|
+| **Repository Health** | 0–100 | Weighted average of the 5 buckets |
+| **AI Maintenance Cost** | $/month | $ cost of fixing the issues, given velocity |
+| **AI Debt band** | A / B / C / D / F | Letter grade from the above two |
+
+---
+
+## What's new in 0.7.0
+
+> **Repository Constitution Engine for AI Coding Agents.** The moat is the Constitution. Everything else is a score that proves it's being followed.
+
+0.7.0 is the **Constitution-first release** — three new specialised subcommands (`test`, `business-logic`, `patterns`), a one-number-per-PR score (`pr`), the `forbidden` deny-list for explicit "never use this", and the rename from `conventions` to `constitution` everywhere.
+
+The 0.6.x series built the foundation. The 0.7.x series turns the Constitution from a config field into a working contract — AI agents that read it via MCP (`slop_suggest`) and humans that enforce it via PR gates.
+
+**What landed in 0.7.0:**
+
+- `slopbrick pr` — one weighted number per PR, gates on `--threshold`
+- `slopbrick test` — Test Quality score (0–100) + 4 `test/*` rules
+- `slopbrick business-logic` — Business Logic Coherence score (0–100) + 8 rules
+- `slopbrick patterns` — Pattern Fragmentation score (0–100), 8 categories
+- `constitution.forbidden` — explicit deny-list (e.g. `['moment', 'lodash']`)
+- `conventions` → `constitution` rename across config, types, MCP tool names, report columns
+
+### 0.6.0 – 0.6.4 recap (the foundation)
+
+0.6.0 was the engine re-architecture. The 0.6.1 – 0.6.4 patch series shifts the framing from "AI slop detector" to **repository coherence engine** — the same scanner, now with three new scores, MCP tools so AI agents check before they PR, and eight security rules for AI-induced failures.
+
+Five orthogonal scores, all in `slopbrick scan`:
+
+| Score | Shape | Use it for |
+|-------|-------|------------|
+| **Slop Index** | 0–100 | Frontend lint quality |
+| **Architecture Consistency** | 0–100 | Cross-file pattern duplication *(0.6.3)* |
+| **AI Security Risk** | `low` / `medium` / `high` / `critical` | AI-induced security failures *(0.6.4)* |
+| **Constitution drift** | pass / fail | Imports that violate declared stack *(0.6.2)* |
+| **Design-token drift** | inline violations | Spacing/radius off declared scales *(0.6.3)* |
+
+The slop detector is still here — but the bigger lever is *coherence*: one modal system, one state library, one fetch lib, a declared constitution that the AI agent checks before PR.
+
+### What landed in 0.6.1 – 0.6.4
+
+**0.6.4 — AI Security Risk (new score) + 8 Tier-1/Tier-2 security rules**
+
+NOT a security scanner — Semgrep / GHAS / CodeQL / Gitleaks own that. This is a **categorical** score (`low | medium | high | critical`) for security failures that AI generates disproportionately. Independent of `slopIndex` — security failures do not get diluted into "good slop score" territory.
+
+- `security/hardcoded-secret` — provider prefixes (`sk-`, `sk-ant-`, `AKIA`, `ghp_`, `sk_live_`, `AIza`, `xox[abprs]-`) + sensitive-name literals.
+- `security/exposed-env-var` — `NEXT_PUBLIC_*` / `VITE_*` / etc. with secret names — inlined into every browser build.
+- `security/dangerous-cors` — wildcard `Access-Control-Allow-Origin: *` + `cors({ origin: '*' })` + reflective `cors({ origin: true })`.
+- `security/missing-auth-check` — Next.js `route.ts` / `pages/api` / Express handlers with no auth primitive.
+- `security/unsafe-html-render` — `dangerouslySetInnerHTML` fed a non-literal value.
+- `security/fail-open-auth` — `if (NODE_ENV === 'development') return true/next()`.
+- `security/sql-construction` — template-literal / concat SQL queries (use parameterized queries).
+- `security/public-admin-route` — routes under `/admin`, `/internal`, `/debug`, `/staff`, `/manage`, `/private`, etc. without an additional role check.
+
+New `slopbrick security [--format pretty|json] [--strict]` subcommand. `--strict` exits 1 on high/critical (CI gate).
+
+**0.6.3 — Architecture Consistency Score (the headline metric) + design-token enforcement**
+
+One 0–100 number that reflects how consistent a repository's patterns are. Subtracts from 100 for each pattern-duplication finding: `-12` per extra modal system, `-8` per extra button variant, `-10` per extra API client module, `-15` per extra state library (highest), `-10` per extra data-fetching library, `-1` per 5 off-scale spacing values, `-1` per 5 off-scale radius values. A project with 1 modal, 1 button, 1 api client, 1 state lib, 1 fetch lib lands at 100. A project with 3 modal systems + 4 button variants + 2 state libs lands at 37.
+
+Two new rules turn design tokens from docs into enforceable contracts:
+- `visual/spacing-scale-violation` — flags `p-[13px]`, `gap-[1.75rem]` etc. off the declared `spacingScale`.
+- `visual/radius-scale-violation` — flags `rounded-[7px]`, `rounded-tl-[2rem]` etc. off the declared `radiusScale`.
+
+Both emit auto-fix candidates so `slopbrick scan --fix` rewrites `p-[13px]` → `p-1`.
+
+**0.6.2 — Repository governance for AI coding agents**
+
+The single feature most projects asked for. New top-level `constitution` field in `slopbrick.config.mjs`:
+
+```js
+export default {
+  constitution: {
+    stateManagement: ['zustand'],
+    dataFetching: ['react-query'],
+    uiLibrary: ['shadcn', 'radix'],
+    forms: ['react-hook-form', 'zod'],
+    styling: ['tailwind'],
+    routing: ['next'],
+  },
+};
+```
+
+Auto-detected from `package.json` when unset; user declarations always win.
+
+- `slopbrick drift` — CLI command, exits 1 on any violation (CI-friendly).
+- `slop_suggest` MCP tool — project-wide inventory of existing patterns; AI agents call before writing new code.
+- `slop_check_constitution` MCP tool — per-file constitution diff.
+- `slop_architecture_score` MCP tool — Architecture Consistency Score via MCP.
+
+**0.6.1 — bug fixes + small refinements**
+
+- `slopbrick trend --format markdown` now actually emits markdown (the local flag was being shadowed by the global scan `--format`; renamed to `--render`).
+- Calibration test surfaces stderr/stdout on chunk failures instead of swallowing them.
+- v1.x working-tree labels stripped.
+
+### CLI surface summary (post-0.8.0)
+
+| Command | Purpose |
+|---------|---------|
+| `slopbrick scan` | Main scan — runs all rules + computes all 8 scores |
+| `slopbrick architecture` | Architecture Consistency Score only |
+| `slopbrick security` | AI Security Risk only |
+| `slopbrick drift` | Constitution-violation scanner |
+| `slopbrick pr` | PR slop score (single weighted number per PR) |
+| `slopbrick test` | Test Quality score (4 `test/*` rules) |
+| `slopbrick business-logic` | Business Logic Coherence score (8 rules) |
+| `slopbrick patterns` | Pattern Fragmentation score (input to `slop_suggest`) |
+| `slopbrick maintenance-cost` | AI Maintenance Cost (categorical low/medium/high/critical + $/month) *(0.8.0)* |
+| `slopbrick docs` | Documentation Freshness (4 `docs/*` rules) *(0.8.0)* |
+| `slopbrick db` | Database Health (6 `db/*` rules, Postgres-only) *(0.8.0)* |
+| `slopbrick mcp` | MCP server (`slop_scan_file`, `slop_explain_rule`, `slop_list_rules`, `slop_suggest`, `slop_check_constitution`, `slop_architecture_score`) |
+| `slopbrick trend` | Slop Index trend over time |
+| `slopbrick flywheel` | Aggregated scan telemetry |
+| `slopbrick init` | Interactive setup wizard |
+
+### What 0.6.x did *not* change
+
+- **No new competitor overlap.** We did not add a general security scanner, dependency vulnerability scanner, formatter, type checker, or coverage tool.
+- **No breaking CLI changes.** Existing scan commands, JSON / SARIF / HTML output formats, and public-API exports are unchanged.
+
+The full release history is in [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## Why this matters (research-backed)
+
+The 0.7.0 release sits on top of an industry that's converging fast on AI-generated-code debt. The numbers below are from 2024–2026 studies and explain why the Constitution, not the Slop Index, is the moat.
+
+- **AI slows experienced developers.** METR's July 2025 RCT (16 experienced open-source devs, 246 tasks on repos averaging 22k stars / 1M LoC) found AI tools produced a **19% slowdown** — developers had expected a 24% speedup. ([METR, 2025](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/))
+- **AI-generated code carries 1.7× more issues per PR** (10.83 vs 6.45) and a higher share of critical/major issues. ([CodeRabbit, 2025](https://coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report))
+- **Refactoring is collapsing.** GitClear's 211M-line analysis of Google/Microsoft/Meta repos shows "refactored" lines fell from 25% → <10% and "copy-pasted" lines rose from 8.3% → 12.3% between 2021–2024. ([GitClear, 2025](https://www.gitclear.com/ai_assistant_code_quality_2025_research))
+- **PR size is up 51%, bugs/PR up 28%, incidents/PR up 3×, code churn up 10×** across 22k developers in 2026. ([Faros AI, 2026](https://www.faros.ai/research/ai-acceleration-whiplash))
+- **Trust in AI accuracy dropped from 40% → 29%** in one year; 66% of devs spend *more* time debugging AI output. ([Stack Overflow 2025 Developer Survey](https://survey.stackoverflow.co/2025/ai))
+- **Code-surface ↔ doc-surface staleness is an open hole.** No shipped tool (Docusaurus, Mintlify, GitBook, mkdocstrings, TypeDoc) cross-references `package.json` ↔ README or exported names ↔ markdown inline code. The 2026 state-of-the-art is F1 = 96.73% on a single analog task (description-code inconsistency, [arXiv 2606.04769](https://arxiv.org/html/2606.04769v1)). That's what `slopbrick docs` ships against in 0.8.0.
+- **Schema-quality static analysis is an open hole for Drizzle.** The official `eslint-plugin-drizzle` has exactly 2 rules. Prisma has 8+ Prisma-Lens rules but they target per-file linting, not schema-wide drift. Squawk owns migration safety; nobody owns schema quality. That's the wedge for `slopbrick db` in 0.8.0.
+- **The canonical AI-coding-agent failure is the AWS Kiro outage (Dec 2025).** An agentic coding tool autonomously deleted a production environment; 13-hour outage in a China region. ([Docker blog, 2026](https://www.docker.com/blog/coding-agent-horror-stories-the-13-hour-aws-outage/)) The post-mortem: "predictable given unchecked AI permissions." The preventive: a Constitution the agent checks before it acts, with a `$306,000/yr/MLoC` baseline for what the debt costs when it isn't checked. ([Sonar, 2025](https://www.sonarsource.com/blog/new-research-from-sonar-on-cost-of-technical-debt/))
+
+The full research notes for each 0.8.0 phase are in [`docs/research/`](./docs/research/).
+
+**Mathematical foundations** — the peer-reviewed methods behind every threshold:
+[`docs/research/math-foundations-for-slopbrick.md`](./docs/research/math-foundations-for-slopbrick.md) maps 8 published results (Halstead 1977, Hindle 2012, Rissanen 1978, Kullback-Leibler 1951, Blondel 2008, Fiedler 1973, McCabe 1976, Adams-MacKay 2007) to the slopbrick rules and composite scores that cite them. v0.9.3+ ships the highest-leverage ones (Halstead, Code Naturalness, MDL composite) to replace heuristic thresholds with closed-form citations.
+
+**v0.10 implementation plan** — the credibility-milestone roadmap with dependency graph, effort estimates per phase, and readiness checklist: [`docs/research/v0.10-implementation-plan.md`](./docs/research/v0.10-implementation-plan.md). Phases 1–5 (~4 working days) ship v0.10; Phases 6–11 land the far-horizon graph-theoretic, Repository Memory, `--diff`, `find_similar_function`, BRICK, and SARIF work.
+
+---
+
+## Roadmap
+
+| Version | Themes | Status |
+|---------|--------|--------|
+| 0.5.x | Engine re-architecture, Slop Index, framework support | Shipped |
+| 0.6.x | Constitution, Architecture Consistency, AI Security Risk, design-token enforcement | Shipped |
+| 0.7.0 | Constitution rename + `forbidden` deny-list, `pr` subcommand, Test / Business-Logic / Patterns subcommands | Shipped 2026-06-25 |
+| 0.8.0 | `docs` (Doc Drift), `db` (Database Health, Postgres-static), `maintenance-cost` ($/month categorical) | Shipped 2026-07-15 |
+| **0.9.0** | **Repository Coherence Scanner reframe, default-off INVERTED + NOISY rules, expanded `slop_suggest`, new `slop_governance` MCP tool** | **Shipped 2026-08-15** |
+| **0.10** | **Credibility milestone: per-rule P/R/FPR + peer-reviewed thresholds (Halstead, McCabe, Hindle, Rissanen, Kullback-Leibler); MDL composite replaces heuristic weights** | **In flight — see [`docs/research/v0.10-implementation-plan.md`](./docs/research/v0.10-implementation-plan.md)** |
+| 1.0 | Stability commitment — 6+ months post-v0.10 empirical feedback; freezes the surface, no new scores | Far horizon |
+
+Per-version research notes:
+- [Phase 6 — Doc Drift](./docs/research/phase-6-doc-drift-internet-2026.md)
+- [Phase 8 — DB Health](./docs/research/phase-8-db-health-internet-2026.md)
+- [Memo #4 — AI Maintenance Cost](./docs/research/phase-memo4-ai-cost-internet-2026.md)
+- [Math foundations — peer-reviewed methods for v0.9.3+ rules](./docs/research/math-foundations-for-slopbrick.md)
+- [v0.10 implementation plan — credibility milestone roadmap](./docs/research/v0.10-implementation-plan.md)
+
+---
+
+## Installation
+
+Run once without installing:
+
+```bash
+npx slopbrick
+```
+
+Add to a project as a dev dependency:
+
+```bash
+pnpm add -D slopbrick
+```
+
+---
+
+## Quick start
+
+Initialize a config in the project root:
+
+```bash
+npx slopbrick init
+```
+
+Scan the current workspace:
+
+```bash
+npx slopbrick scan
+```
+
+Or scan specific paths:
+
+```bash
+npx slopbrick scan src app
+```
+
+On first run, `slopbrick` auto-detects your framework, styling solution, UI libraries (Tailwind, Tamagui, shadcn/ui, MUI, etc.), and workspace packages. Framework presets automatically disable or downgrade rules that are idiomatic for React Native, Expo, or Tamagui.
+
+### Don't want to write a config from scratch?
+
+Four ready-to-use starter configs live in [`examples/`](./examples):
+
+- [`examples/basic/`](./examples/basic) — sensible defaults for most projects
+- [`examples/strict/`](./examples/strict) — CI gating with `noIncrease` baseline
+- [`examples/monorepo/`](./examples/monorepo) — pnpm/turbo workspaces
+- [`examples/ci/`](./examples/ci) — JSON + SARIF output for code-scanning upload
+
+```bash
+cp examples/strict/slopbrick.config.mjs ./slopbrick.config.mjs
+npx slopbrick validate-config   # check it before running a scan
+```
+
+See [`examples/README.md`](./examples/README.md) for the full walkthrough.
+
+---
+
+## Configuration
+
+Config lives at `slopbrick.config.mjs` in the project root. It is an ES module that exports a default object.
+
+```js
+export default {
+  include: ['src/**/*', 'app/**/*', 'pages/**/*', 'components/**/*'],
+  exclude: [
+    '**/node_modules/**',
+    '**/*.test.{ts,tsx,js,jsx}',
+    '**/*.stories.{ts,tsx}',
+    '**/.next/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/coverage/**',
+  ],
+
+  // Per-category weight multiplier
+  categoryWeights: {
+    visual: 1.2,
+    logic: 1.0,
+    perf: 0.8,
+    typo: 0.5,
+    wcag: 1.0,
+    layout: 1.0,
+    component: 1.0,
+    arch: 1.0,
+    security: 1.0,
+  },
+
+  // CI threshold (Phase 2 §10: composite Slop Index only)
+  thresholds: {
+    meanSlop: 30,
+  },
+
+  // Rule severity overrides.
+  // 'auto' keeps the rule's natural severity; 'off' disables it.
+  rules: {
+    'visual/inline-style': 'auto',
+    'visual/hardcoded-color': 'low',
+    'logic/style-sheet-avoidance': 'medium',
+  },
+
+  // Boost or reduce scores for specific frameworks
+  frameworkMultipliers: {
+    astro: 0.8,
+  },
+
+  // Phase 2 §10: brick.config.json import paths. Defaults to common
+  // shadcn-style paths. Imports from `@/components/*` not matching
+  // these prefixes are flagged by `context/import-path-mismatch`.
+  allowedImports: [
+    '@/components/ui/',
+    '@/components/',
+    '@/lib/',
+    '@/hooks/',
+  ],
+};
+```
+
+### Key options
+
+| Option | What it does |
+|--------|--------------|
+| `include` | File patterns to scan (default: all source files) |
+| `exclude` | File patterns to skip |
+| `categoryWeights` | Make certain issue types count more or less |
+| `thresholds` | CI gates — see "Thresholds" below |
+| `rules` | Turn specific rules off or change their severity |
+| `frameworkMultipliers` | Boost/reduce scores for specific frameworks |
+| `arbitraryValueAllowlist` | Tailwind values that are OK to use |
+| `allowedImports` | brick.config.json import paths (Phase 2 §10) |
+| `wcag` | Accessibility-specific settings |
+
+---
+
+## Composite Slop Index (Phase 2 §10)
+
+slopbrick produces a single composite score that prioritizes structural integrity over minor visual escapes:
+
+```
+S = (0.40 × S_boundary) + (0.35 × S_context) + (0.25 × S_visual)
+```
+
+Each subscore is `min(100, severityPoints / componentCount)`, where `severityPoints` is the sum of severity weights for issues in that bucket.
+
+**Bucket weights:**
+
+| Bucket | Weight | What it measures |
+|--------|-------:|------------------|
+| **Boundary** | 40% | Structural integrity: file-size limits, multiple components per file, direct API calls in UI |
+| **Context** | 35% | Prop correctness, imports, state management |
+| **Visual** | 25% | CSS, layout, typography, accessibility |
+
+**Rule → Subscore mapping:**
+
+- **Boundary (40%)**: `logic/boundary-violation`, `component/giant-component`, `component/multiple-components-per-file`
+- **Context (35%)**: `component/shadcn-prop-mismatch`, `arch/astro-island-leak`, `context/import-path-mismatch`, most `logic/*`
+- **Visual (25%)**: all `visual/*`, `layout/*`, `typo/*`, `wcag/*`, `perf/*`
+
+---
+
+## CLI reference
+
+```text
+Usage: slopbrick [options] [command]
+
+Options:
+  -V, --version                       output the version number
+  --framework <name>                  framework multiplier to apply
+  --include <glob>                    include pattern (repeatable)
+  --exclude <glob>                    exclude pattern (repeatable)
+  --ai-only                           only report AI-specific issues
+  --human-only                        only report human-facing issues
+  --ignore-wcag22                     ignore WCAG 2.2 related issues
+  --format <pretty|json|sarif|html>   output format (default: "pretty")
+  --threads <n>                       number of worker threads
+  --since <ref>                       only scan files changed since git ref
+  --workspace <path>                  workspace/project path
+  --tighten                           tighten baseline allowances
+  --fix                               apply auto-fixes
+  --dry-run                           preview fixes without writing any files
+  --diff                              print unified diff of proposed auto-fixes
+  --doctor                            run diagnostics
+  --watch                             watch files and re-run
+  --suggest                           print remediation advice
+  --heatmap                           print migration ROI heatmap
+  --quiet                             suppress non-error output
+  --strict                            exit 2 if any high-severity issue remains
+  --no-increase                       exit 2 if slop index increased since last run
+  --auto-disable-noisy-rules          downgrade rules whose measured precision < 0.5
+                                       or recall < 0.1 by one severity step
+  --baseline                          save a baseline after this scan
+  --trend [n]                         print a sparkline of the last n runs
+  --json [path]                       write JSON report to path or stdout
+  --html [path]                       write HTML report to path or stdout
+  --staged                            scan only staged files
+  --changed                           scan working-tree changes
+  --incremental                       skip unchanged files via content-hash cache
+  --cache-path <path>                 path to the incremental cache (default: .slop-audit-cache.json)
+  --tokens <path>                     merge tokens.json layout values into the
+                                       arbitrary-value allowlist
+  --cache                             cache parsed AST results locally
+  --rule <ruleId>                     run a single rule by id, skip all others
+  -h, --help                          display help for command
+
+Commands:
+  init [options]                      create a slopbrick config file
+  install                             install the git pre-commit hook
+  uninstall                           uninstall the git pre-commit hook
+  badge                               print a shields.io slop-index badge
+  suggest                             print remediation advice
+  flywheel [options]                  summarize aggregated scan telemetry
+  scan [paths...]                     scan files for slop
+  explain <ruleId>                    print rationale, pattern, and remediation for a single rule
+  tokens <path>                       ingest a W3C DTCG tokens.json and summarize it by category
+  report <path>                       re-render a saved JSON report (from --json path.json)
+  doctor                              check your setup, config, and environment for common problems
+  rules [--category <name>] [--ai-only] [--json]
+                                      list all built-in rules with descriptions
+  mcp                                 run an MCP server (for AI agents)
+  help [command]                      display help for command
+```
+
+### pr — score a pull request
+
+`slopbrick pr` runs the engine over the files changed between two
+git refs and returns a single weighted slop score. The score is
+`sum(SEVERITY_WEIGHTS[issue.severity]) + constitution_violations`
+per file, summed across the diff. With the default threshold of
+`20` (configurable via `prScoreThreshold` or `--threshold`), a PR
+can introduce roughly 4 medium-severity issues before it fails.
+
+```bash
+slopbrick pr [--base <ref>] [--head <ref>]
+              [--format text|json|markdown]
+              [--threshold <n>] [--max-files <n>]
+```
+
+Defaults: `--base main` (falls back to `master` then the first
+commit), `--head HEAD`, `--format text`, `--threshold 20`,
+`--max-files 500`. The diff is computed with three-dot syntax
+(`git diff --name-only base...head`), which matches GitHub's PR
+view (merge-base comparison).
+
+```text
+$ slopbrick pr
+PR score: 4 (threshold: 20) — PASS
+Base: main  Head: HEAD
+Files changed: 1
+
+src/store.ts  issues=1  constitution=1  score=4
+  [medium ] security/public-admin-route — line 1
+  [forbidden] Constitution violation: … imports 'redux' (canonical: 'redux').
+
+────────────────────────────────────────────
+PR score: 4 / 20 threshold — PASS
+```
+
+Use it as a CI gate:
+
+```yaml
+- run: npx slopbrick pr --threshold 10
+  # exits 1 when PR score > 10
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Composite Slop Index under `meanSlop` threshold |
+| `1` | Composite Slop Index exceeds threshold |
+| `2` | High-severity issues with `--strict`, score regression with `--no-increase`, or hook install failure |
+| `3` | Unexpected scan error (parser crash, worker failure after retries) |
+
+---
+
+## Example terminal output
+
+```text
+$ npx slopbrick scan
+Scanned 312 files, 501 components, 1423 issues (high: 48, medium: 321, low: 1054)
+
+Slop Index:  14.2 / 100 [PASS]
+(Phase 2 §10 composite: 0.40 × Boundary + 0.35 × Context + 0.25 × Visual)
+  ├─ Boundary Slop: 12.5 (Weighted: 5.0)
+  ├─ Context Slop:    4.0 (Weighted: 1.4)
+  └─ Visual Slop:    31.0 (Weighted: 7.8)
+
+Top offending components
+    72.3  src/app/(tabs)/keepsakes.tsx
+    65.1  src/app/(tabs)/search.tsx
+    58.0  src/app/child/[id]/edit.tsx
+    ...
+
+Thresholds
+
+  Composite Slop Index   14.2 ≤ 30  pass
+
+All thresholds passed.
+
+Issues (1423)
+[HIGH   ] logic/boundary-violation · src/app/(tabs)/keepsakes.tsx:91:22
+  Data layer mixed with UI component
+  → Move fetch/state into a server action or hook.
+```
+
+---
+
+## How scoring works
+
+### Severity weights
+
+| Severity | Weight |
+|----------|-------:|
+| high | 5 |
+| medium | 3 |
+| low | 1 |
+
+(The `critical` tier was removed during the scoring-model refactor to prevent scoring inflation.)
+
+### Per-file scoring
+
+For each file, the engine:
+1. Parses the source (SWC for TS/JS, regex for HTML, dedicated parsers for Vue/Svelte/Astro).
+2. Walks the AST to extract facts: imports, JSX elements, class names, inline styles, hooks, state bindings, etc.
+3. Runs each of the 42 registered rules against the facts.
+4. Each rule returns 0+ issues with severity, line, column, and optional fix suggestions.
+
+### Project scoring (Phase 2 §10)
+
+1. **Bucket** every issue into one of three subscores (boundary, context, visual) using the rule-to-bucket map.
+2. **Sum** severity weights per bucket: `bucketPoints[b] = Σ SEVERITY_WEIGHTS[issue.severity]`.
+3. **Normalize**: `subscore[b] = min(100, bucketPoints[b] / componentCount × 100)`.
+4. **Composite**: `slopIndex = 0.40 × boundary + 0.35 × context + 0.25 × visual`.
+5. **Health**: `assemblyHealth = max(0, 100 - slopIndex)`.
+
+### Threshold
+
+A single threshold (`meanSlop`) gates the exit code: `slopIndex > meanSlop` → exit 1.
+
+---
+
+## Architecture
+
+### High-level pipeline
+
+```
+┌────────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│   CLI bin/ │───▶│ discover │───▶│  parser  │───▶│ visitor  │───▶│  rules   │
+│ slopbrick │    │ discover │    │  engine/ │    │  engine/ │    │ rules/   │
+│    .js     │    │   .ts    │    │ parser.ts│    │ visitor.ts│   │ *.ts     │
+└────────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
+                                                                  │
+                                                                  ▼
+┌────────────┐    ┌──────────────┐    ┌────────────────┐    ┌─────────────────┐
+│  Output    │◀───│  aggregate   │◀───│   report       │◀───│  ProjectReport  │
+│  report/   │    │   metrics    │    │   ProjectReport│    │   (per-issue)   │
+│  *.ts      │    │   metrics.ts │    │                │    │                 │
+└────────────┘    └──────────────┘    └────────────────┘    └─────────────────┘
+```
+
+### End-to-end flow (`slopbrick scan`)
+
+1. **CLI entry** (`bin/slopbrick.js`)
+
+   Loads `dist/index.js` (the bundled CLI), parses command-line flags with Commander, and resolves `cwd` from `--workspace` or `process.cwd()`.
+
+2. **Config loading** (`src/config.ts`)
+
+   Walks up from cwd looking for `slopbrick.config.{js,mjs,cjs,ts}`, merges the user config with `DEFAULT_CONFIG` (which sets `thresholds`, `rules`, `allowedImports`), and validates the merged result against the schema.
+
+3. **File discovery** (`src/discover.ts`)
+
+   Uses `globby` to expand `include` patterns and `minimatch` to apply `exclude`. For files without an extension, it reads the first 512 bytes and sniffs the content type (TSX/TS/JSX/JS/Vue/Svelte/Astro/HTML). It de-duplicates by basename when both extension-less and proper-extension versions exist, then filters by `SOURCE_EXTENSIONS` (`.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.html`).
+
+4. **Per-file scanning** (`src/engine/worker.ts`, `src/engine/parser.ts`, `src/engine/visitor.ts`)
+
+   Runs in worker threads (configurable via `--threads`).
+
+   The **parser** dispatches based on file extension: SWC for TS/JS, dedicated handlers for Vue/Svelte/Astro, regex for HTML. Extension-less files try TSX → TS → JSX → JS in order.
+
+   The **visitor** walks the AST and extracts a `ScanFacts` summary, including:
+   - `imports[]` — `{source, importedNames, line, column}`
+   - `interactiveElements[]` — JSX `<button>`, `<a>`, `<input>`, etc. with attributes
+   - `staticClassNames[]` — className string literals
+   - `styleProps[]` — inline `style={{...}}` props
+   - `componentSizes[]` — per-component line count + JSX branch count
+   - `propBindings[]`, `stateBindings[]`, `hooks[]`, `logicalExpressions[]`, etc.
+
+   **Rule execution** iterates the registered rules (built-ins + user overrides) and calls each rule's `analyze(facts, context)` method, collecting `Issue[]`.
+
+5. **Aggregation** (`src/engine/metrics.ts`)
+
+   Sums severity points per subscore bucket (boundary / context / visual), normalizes each bucket by component count capped at 100, and computes `slopIndex = 0.40 × boundary + 0.35 × context + 0.25 × visual`. Returns the structured `ProjectReport` with all subscores, severity counts, and per-file scores.
+
+6. **Threshold check** (`src/cli/threshold.ts`)
+
+   Calls `thresholdExceeded(report, config)`, which compares `report.slopIndex` against `config.thresholds.meanSlop`. Returns true → exit code 1. Also checks per-category thresholds (`categoryThresholds`) if configured.
+
+7. **Output rendering** (`src/report/`)
+
+   One module per format:
+   - `pretty.ts` — human-readable terminal output with the composite breakdown tree
+   - `json.ts` — serialized `ProjectReport` (full data)
+   - `sarif.ts` — SARIF 2.1.0 for IDE/editor integration
+   - `html.ts` — self-contained HTML report with score cards
+   - `markdown.ts` — Markdown report for PR comments
+   - `heatmap.ts` — migration ROI heatmap (top files by score)
+   - `unified-diff.ts` — unified diff of the report
+   - `advice.ts` — remediation suggestions
+   - `flywheel.ts` — telemetry summary
+
+### File layout
+
+```
+src/
+├── index.ts                  # Public facade (re-exports from ./cli/)
+├── config.ts                 # Public config facade (re-exports from ./config/)
+├── config/                   # config/{defaults,presets,detect,load,init}
+├── cli/                      # CLI surface (Commander wiring + scan + init engines)
+│   ├── program.ts            # runCli — Commander setup, per-command .action() callbacks
+│   ├── scan.ts               # runScan, scanProject, watchProject, renderOutput
+│   ├── init.ts               # runInitWizard, runDoctor, init prompts
+│   ├── options.ts            # CLI option parsers (parseThreads, collectGlob, …)
+│   ├── render.ts             # colorForSlop, formatBadge, formatSparkline, …
+│   └── threshold.ts          # thresholdExceeded, stagedGating, filterIssues, …
+├── engine/
+│   ├── parser.ts             # SWC/Vue/Svelte/Astro/HTML dispatch + extension-less fallback
+│   ├── visitor.ts            # AST walker → ScanFacts extraction (1313 lines — largest file)
+│   ├── worker.ts             # Per-file scan worker thread
+│   ├── metrics.ts            # Composite Slop Index aggregation
+│   ├── logger.ts             # Test-aware logging
+│   ├── pool.ts               # WorkerPool with work-stealing + retry
+│   ├── executor.ts           # Inline scan path for small file counts
+│   ├── cache.ts              # .slop-audit-cache.json + baseline.json
+│   ├── memory.ts             # run-history.json (--trend, --no-increase)
+│   ├── telemetry.ts          # Flywheel payloads
+│   └── trend.ts              # --trend sparkline builder
+├── rules/                    # Rule modules (42 built-in rules across 9 categories)
+│   ├── arch/                 #   1 rule  — astro-island-leak
+│   ├── component/            #   3 rules — giant-component, multiple-components-per-file,
+│   │                                    shadcn-prop-mismatch
+│   ├── context/              #   1 rule  — import-path-mismatch
+│   ├── layout/               #   4 rules — gap-monopoly, math-element-uniformity,
+│   │                                    math-grid-uniformity, spacing-grid
+│   ├── logic/                #  11 rules — boundary-violation, ghost-defensive,
+│   │                                    key-prop-missing, math-any-density,
+│   │                                    math-console-log-storm, math-gini-class-usage,
+│   │                                    math-variable-name-entropy, optimistic-no-rollback,
+│   │                                    qwik-hook-leak, reactive-hook-soup, zombie-state
+│   ├── perf/                 #   2 rules — cls-image, css-bloat
+│   ├── typo/                 #   5 rules — calc-fontsize, calc-raw-px, clamp-offscale,
+│   │                                    math-button-label-uniformity, math-cta-vocabulary
+│   ├── visual/               #  11 rules — arbitrary-escape, clamp-soup, generic-centering,
+│   │                                    inline-style-dominance, math-color-cluster,
+│   │                                    math-default-font, math-font-entropy,
+│   │                                    math-gradient-hue-rotation, math-rounded-entropy,
+│   │                                    math-spacing-entropy
+│   ├── wcag/                 #   4 rules — dragging-movements, focus-appearance,
+│   │                                    focus-obscured, target-size
+│   ├── builtins.ts           # Auto-generated registry (pnpm generate:rules)
+│   ├── rule.ts               # createRule + RuleDefinition types
+│   ├── registry.ts           # RuleRegistry (loadBuiltins, loadProjects)
+│   ├── registry-loader.ts    # shadcn/ui registry snapshot cache
+│   ├── project.ts            # Project-level rules (runProjectRules)
+│   ├── signal-strength.ts    # --show-signal-strength lookup
+│   └── signal-strength.json  # Per-rule precision/recall measurements
+├── report/                   # Output formatters (pretty, json, sarif, html, …)
+│   ├── pretty.ts, json.ts, sarif.ts, html.ts, markdown.ts
+│   ├── advice.ts             # --suggest output
+│   ├── unified-diff.ts       # --diff output
+│   ├── heatmap.ts            # --heatmap output
+│   ├── flywheel.ts           # flywheel summary
+│   └── html/                 # html/{utils,sections,static}.ts
+├── fix/                      # Auto-fix codemods
+│   ├── index.ts              # applyFixes orchestrator
+│   ├── visual-codemod.ts     # Round-20 visual codemods entry point
+│   └── visual-codemods/      # tailwind.ts, jsx.ts, source.ts
+├── snippet.ts                # AI agent rule snippet generators (facade)
+├── snippet/                  # snippet/{data,render,generators,targets}
+├── flywheel.ts               # Flywheel state machine
+├── mcp/                      # MCP server (src/mcp/server.ts + tools)
+├── research/                 # research/generate, analyze, candidates, calibrate
+├── config-validation.ts      # Static config schema validator
+├── discover.ts               # File discovery + extension sniffing
+├── git.ts                    # --staged / --changed / --since git integration
+├── installer.ts              # install/uninstall git pre-commit hook
+├── explain.ts                # `slopbrick explain <ruleId>` output
+├── tokens.ts                 # W3C DTCG tokens.json parser
+├── types.ts                  # All public types (ProjectReport, ScanFacts, Issue, …)
+└── bin/                      # bin/slopbrick.js entry point
+```
+
+---
+
+## MCP server (for AI agents)
+
+slopbrick ships a [Model Context Protocol](https://modelcontextprotocol.io/) server so AI coding agents can call it directly:
+
+```bash
+slopbrick mcp   # JSON-RPC 2.0 over stdio
+```
+
+Exposes three tools:
+
+| Tool | Args | Returns |
+|------|------|---------|
+| `slop_scan_file`    | `{path, framework?}` | issues + Slop Index for one file |
+| `slop_explain_rule` | `{ruleId}`          | rule metadata + rationale + file location |
+| `slop_list_rules`   | `{category?}`       | all rules with category / severity / aiSpecific |
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "slopbrick": {
+      "command": "npx",
+      "args": ["slopbrick", "mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+### AI agent rule snippets
+
+Generate directive snippets that teach your AI agent the slop rules BEFORE it writes code:
+
+```bash
+slopbrick init --matrix                       # print the matrix table
+slopbrick init --yes --agents-md              # Codex / opencode / Pi / Cline / Gemini
+slopbrick init --yes --claude-md              # Claude Code
+slopbrick init --yes --all                    # all targets at once
+```
+
+| Flag | File | Agent |
+|------|------|-------|
+| `--cursor`      | `.cursor/rules/slopbrick.mdc` | Cursor (new format) |
+| `--cursorrules` | `.cursorrules` | Cursor (legacy format, deprecated) |
+| `--agents-md`   | `AGENTS.md` | OpenAI Codex / opencode / Pi / Cline / Continue / Gemini |
+| `--claude-md`   | `CLAUDE.md` | Claude Code (takes precedence over AGENTS.md) |
+| `--aider`       | `CONVENTIONS.md` | Aider |
+| `--windsurf`    | `.windsurfrules` | Windsurf (Cascade) |
+| `--cline`       | `.clinerules/AGENTS.md` | Cline (folder-based) |
+| `--gemini`      | `.gemini/GEMINI.md` | Gemini CLI |
+| `--copilot`     | `.github/copilot-instructions.md` | GitHub Copilot |
+
+Content is generated live from the rule registry — always matches what slopbrick actually checks.
+
+---
+
+## Adding new rules
+
+Rule modules live in `src/rules/<category>/<rule>.ts`. Each module must export a const ending in `Rule` and a matching default export:
+
+```ts
+import { createRule } from '../rule';
+import type { Issue, Rule, RuleContext, ScanFacts } from '../../types';
+
+export const myRule = createRule<RuleContext>({
+  id: 'category/my-rule',
+  category: 'visual',
+  severity: 'medium',
+  aiSpecific: true,
+  description: 'Short one-line description used in `slopbrick rules` output.',
+  create(context) {
+    return context;
+  },
+  analyze(_context, facts: ScanFacts): Issue[] {
+    const issues: Issue[] = [];
+    // ... analyze facts ...
+    return issues;
+  },
+});
+
+export default myRule satisfies Rule<RuleContext>;
+```
+
+Run `pnpm generate:rules` to regenerate `src/rules/builtins.ts`. This runs automatically before `pnpm build` and `pnpm test`.
+
+---
+
+## Calibration against held-out human code
+
+The tool ships with an automated calibration test (`tests/integration/calibration.test.ts`) that scans both corpora and asserts every AI-signal rule has a recall/FP ratio ≥ its threshold. It runs as part of `pnpm test` and exits non-zero on regression.
+
+The corpora live at `/Users/cheng/ai-slop-baseline/extracted/`:
+- `positive/` — 6,142 AI-generated samples (vibe-coded React apps).
+- `negative/` — 54,980 human-written samples (shadcn/ui, calcom, dub, mantine, excalidraw, lobehub, etc.).
+
+A rule with a recall/FP ratio above 1.0× is a useful AI tell. A ratio below 1.0× is an anti-signal — tighten it, scope-restrict it, or drop it.
+
+---
+
+## Glossary
+
+- **Slop Index** — 0–100 composite score per Phase 2 §10. Lower is better. Weighted average of boundary (40%), context (35%), and visual (25%) subscores.
+- **Assembly Health** — Inverse of Slop Index. Higher is better.
+- **Composite Slop Index** — Phase 2 §10's weighted three-bucket formula.
+- **AI-specific rule** — Rule that catches patterns AI defaults to but humans rarely do (e.g. `bg-violet-500`, "Get started today", badge-above-h1 layout).
+- **General rule** — Catches real bugs or code-quality issues regardless of author.
+- **brick.config.json** — Project config (in `slopbrick.config.mjs`) listing allowed import paths for `context/import-path-mismatch`.
+- **RSC / Server component** — React Server Component. Runs on the server, can't use `useState`/`useEffect`. The fix is `'use client'`.
+- **Memoization** — React skips re-renders if inputs haven't changed. Inline handlers break memoization because they're new functions on every render.
+- **Astro island** — Interactive component inside an otherwise static Astro page. Without `client:*` directive, clicks won't fire.
+- **DTCG tokens** — W3C Design Token Community Group JSON format. `slopbrick tokens <path>` reads these.
+- **MCP** — Model Context Protocol. JSON-RPC 2.0 over stdio for AI agent integration.
+
+---
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Adding a rule? Update `tests/integration/calibration.test.ts` to add a calibration entry — the corpus test will verify your rule discriminates AI from human code.
+
+---
+
+## License
+
+[MIT](./LICENSE)