@alexcodeplace/slopgate 0.1.0

package/README.md

@@ -0,0 +1,720 @@
+# slopgate
+
+A global code-quality / anti-slop gate for Claude Code and git. Engine is shared, rules are per-project.
+
+**What it does:** Catches code quality violations in two tiers — a fast post-edit scan (regex + AST rules, instant feedback) and a heavy commit-tier scan (static type checkers, dead-code analysis, architecture rules, copy-paste detection). A **ratchet baseline** lets legacy repos adopt without flooding — only NEW violations block commits; pre-existing ones are baselined and tracked for paydown.
+
+---
+
+## Features
+
+- **Two-tier gate**
+  - **Fast tier** (post-edit hook): regex patterns + AST rules, instant feedback as you code
+  - **Commit tier** (pre-commit hook): includes heavy checkers (tsc, knip, jscpd, dependency-cruiser, type-coverage, diff-shape) + AST + regex, blocks commits
+  
+- **Ratchet baseline** — snapshot violations at adoption time; only NEW violations fail the gate. Track debt paydown over time.
+
+- **Six commit-tier checkers**
+  - **tsc** — TypeScript type errors (full-project scope)
+  - **knip** — dead/unused code (exports, files, dependencies)
+  - **jscpd** — copy-paste duplication (token-level)
+  - **dependency-cruiser** — architecture rules (cycles, orphans, layer boundaries)
+  - **type-coverage** — propagation of `any` type (per-expression tracking)
+  - **diff-shape** — wide commits spanning too many directories (encourages focused changes)
+
+- **Shared regex + AST rule packs** — fast-tier and commit-tier both run these
+  - Convention: `no-stubs`, `ts-suppress`, `as-any`, `raw-hex` (design tokens), `sql-safety`
+  - Security: `live-secrets`, `eval-ban`, `pii-logs`, `weak-hash`
+  - Cloudflare boundary: `kv-ban` (plus the opt-in `stack = ["cloudflare"]` pack)
+  - Built-in AST rules: empty-catch, unsafe `innerHTML`/`dangerouslySetInnerHTML`, `target="_blank"` without `rel`, `window` access during render
+  
+- **Native git pre-commit hook** — no daemon, no CI coupling, just git
+  
+- **Claude Code integration** — hooks into PreToolUse (commit) and PostToolUse (edit) events
+  
+- **Suppressions** — per-file, per-line, with line-hash stability across edits
+  
+- **Self-test** — `slopgate --self-test` validates rule engines + baseline checker parsers against bundled fixtures
+
+---
+
+## Install
+
+```bash
+npm install -g slopgate
+```
+
+The matching prebuilt native engine for your platform (linux / macOS / Windows × x64 / arm64) is pulled in automatically as an optional dependency — no toolchain or build step required.
+
+Then onboard a project:
+
+```bash
+slopgate init [path-to-repo]
+```
+
+This:
+1. Detects TypeScript roots, file extensions, and package layout
+2. Scaffolds `.slopgate/config.toml` with detected checkers enabled
+3. Writes `.slopgate/suppressions.json` and `.slopgate/depcruise.cjs` (starter)
+4. Creates `.slopgate/convention-sources.json` (hints for authoring project rules from local skills/agents/docs)
+5. Creates `.slopgate/rules/ast/` and `.slopgate/fixtures/src/` directories
+6. Installs git pre-commit hook (or appends to existing)
+7. Merges Claude Code hook settings into `.claude/settings.json`
+8. Prints next steps (including: run `slopgate baseline --config .slopgate/config.toml`)
+
+---
+
+## Quickstart
+
+### Run the gate on staged changes (pre-commit):
+```bash
+slopgate --staged --config .slopgate/config.toml
+```
+
+### Run on a single file (post-edit, fast tier):
+```bash
+slopgate --file src/app.ts --config .slopgate/config.toml
+```
+
+### Create/update the baseline:
+```bash
+# Create baseline (refuses if it exists)
+slopgate baseline --config .slopgate/config.toml
+
+# Update baseline (re-snapshot all current violations)
+slopgate baseline --update --config .slopgate/config.toml
+
+# Prune baseline (remove entries no longer occurring)
+slopgate baseline --prune --config .slopgate/config.toml
+```
+
+### Run self-test (validate the engine against bundled fixtures):
+```bash
+slopgate --self-test --config "$(npm root -g)/slopgate/rules/baseline/selftest.config.toml"
+```
+
+### Install or reinstall hooks:
+```bash
+slopgate install-hooks --config .slopgate/config.toml
+```
+
+---
+
+## Command Reference
+
+### `slopgate init [dir]`
+Onboard a new repository. Detects roots, extensions, installed checkers, and scaffolds project structure.
+
+**Args:**
+- `dir` (optional) — target directory; defaults to `process.cwd()`
+- No `--config` required; generates config during init
+
+**Creates:**
+- `.slopgate/config.toml` — project config (roots, extensions, rule packs, checkers, baseline/suppressions paths)
+- `.slopgate/suppressions.json` — line-level violation suppressions (empty initially)
+- `.slopgate/depcruise.cjs` — starter dependency-cruiser rules (if depcruise detected)
+- `.slopgate/convention-sources.json` — hints for authoring project-specific rule packs
+- `.slopgate/rules/ast/` and `.slopgate/fixtures/src/` — directories for custom rules and fixtures
+- `.git/hooks/pre-commit` — native git pre-commit hook (creates new or appends to existing)
+- `.claude/settings.json` — Claude Code hook entries (idempotent merge)
+
+**Next step:** Run `slopgate baseline --config .slopgate/config.toml` to create the initial ratchet baseline
+
+---
+
+### `slopgate --staged --config <path>`
+Run commit-tier gate on staged files. Used by git pre-commit hook and Claude Code PreToolUse hook.
+
+**Flags:**
+- `--config <path>` (required) — path to `.slopgate/config.toml`
+- `--tier fast|commit` (optional) — override default tier (default: commit for `--staged`)
+
+**Exit codes:**
+- `0` — no violations (or all baselined/suppressed)
+- `1` — violations block the commit
+- `2` — config error or missing argument
+
+**Output:**
+- Violations grouped by source (regex, ast, checker:tsc, etc.)
+- Baselined count footer
+- Skipped checkers (if tool/config missing)
+
+---
+
+### `slopgate --file <path> --config <path>`
+Run fast-tier gate on a single file (post-edit). Used by Claude Code PostToolUse hook.
+
+**Flags:**
+- `--file <path>` (required) — repo-relative path to check
+- `--config <path>` (required) — path to `.slopgate/config.toml`
+- `--tier fast|commit` (optional) — override default tier (default: fast for `--file`)
+
+**Exit codes:** same as `--staged`
+
+**Output:** violations in the touched file only; no baseline filtering
+
+---
+
+### `slopgate baseline --config <path> [--update] [--prune]`
+Manage the ratchet baseline.
+
+**Flags:**
+- `--config <path>` (required)
+- `--update` — re-snapshot all current violations (overwrites baseline)
+- `--prune` — remove entries whose fingerprint no longer occurs (dry-run only)
+- Both flags can be combined; `--prune --update` prunes then updates
+
+**Behavior:**
+- No flags, file missing → create baseline with current violations
+- No flags, file exists → error (refuses overwrite; use `--update`)
+- `--update` → snapshot all violations in full commit tier scan
+- `--prune` → drop resolved fingerprints (non-destructive; just removes old entries)
+
+---
+
+### `slopgate install-hooks --config <path>`
+Install or upgrade the git pre-commit hook.
+
+**Flags:**
+- `--config <path>` (required)
+
+**Behavior:**
+- No hook exists → create new hook with slopgate check
+- Hook exists with slopgate marker → upgrade (idempotent)
+- Foreign hook exists → append slopgate block before final `exec` (preserves other hooks)
+
+**Hook location:** `<git-dir>/hooks/pre-commit` (or respects `git config core.hooksPath`)
+
+---
+
+
+### `slopgate --self-test --config <path>`
+Internal: validate regex + AST engines and checker parsers against fixtures.
+
+**Flags:**
+- `--config <path>` (required) — typically `rules/baseline/selftest.config.toml`
+
+Runs in-process tests; exit 0 = all pass, exit 1 = failure. Used by `npm run self-test`.
+
+---
+
+## How the Two Tiers Work
+
+### Fast Tier (Post-Edit)
+Runs on every Edit/Write to a `.ts`, `.tsx`, or `.astro` file.
+
+**Scope:** Single file
+**Engines:** Regex patterns + AST rules (baseline packs only)
+**Baseline:** Not consulted (all violations shown)
+**Latency:** < 1 second
+**Feedback:** Instant, in-editor
+
+**Rules applied:**
+- All regex patterns in enabled baseline packs (`no-stubs`, `ts-suppress`, `as-any`, etc.)
+- All AST rules from enabled baseline packs
+- Project-owned AST rules (from `astRules` config)
+
+---
+
+### Commit Tier (Pre-Commit)
+Runs before `git commit` or when `--staged` is called manually.
+
+**Scope:** All staged files + full repo (for checkers like tsc, knip that need graph context)
+**Engines:** Regex patterns + AST rules + six heavy checkers
+**Baseline:** Consulted; only NEW violations block commit
+**Latency:** 5–30 seconds (tsc + knip dominate)
+**Feedback:** Commit blocked or passes
+
+**Rules applied:**
+- All regex patterns (same as fast tier)
+- All AST rules (same as fast tier)
+- **tsc** — TypeScript type errors (full-project compile)
+- **knip** — unused exports/files/dependencies
+- **jscpd** — copy-paste clones (staged files only are reported)
+- **dependency-cruiser** — architecture violations
+- **type-coverage** — NEW uncovered expressions
+- **diff-shape** — staged files spanning > N top-level dirs
+
+**Filtering:**
+1. Run all sources (regex, ast, checkers)
+2. Fingerprint violations (sha256 of source, rule, file, normalized message, line text)
+3. Filter by ratchet baseline (drop fingerprints in baseline.json)
+4. Filter by suppressions (line-level, per file + lineHash)
+5. Filter by severity gate (only show `critical`/`high` by default, configurable)
+6. Print report; exit 1 if violations remain
+
+---
+
+## Ratchet Baseline
+
+The ratchet prevents violations from blocking adoption of new rules or onboarding legacy repos.
+
+### How It Works
+
+1. **At init:** `slopgate baseline --config ...` creates `.slopgate/baseline.json` with a snapshot of ALL current violations.
+
+2. **On commit:** The gate compares the current full-repo commit-tier scan against the baseline. Violations whose fingerprint is in the baseline are ignored (baselined); NEW violations block the commit.
+
+3. **Paydown:** As issues are fixed, their fingerprint disappears from the current scan. `slopgate baseline --prune` removes old entries from the baseline, lowering the bar.
+
+4. **Re-snapshot:** `slopgate baseline --update` does a full re-scan and updates the baseline (use after intentionally widening rules or adding new checkers).
+
+### Fingerprint Stability
+
+Fingerprints include:
+- Rule ID
+- File path (repo-relative)
+- Normalized message (digit runs replaced with `#`, kills line/col churn)
+- First 60 chars of the source line (trimmed)
+
+Fingerprints do NOT include the line number, so they survive unrelated edits shifting lines.
+
+### Suppressions vs. Baseline
+
+- **Baseline** — temporary allowlist; debt should be paid down over time. Track in version control. Entire project-wide snapshot.
+- **Suppressions** — permanent per-file exemptions (e.g., "this pattern is correct in this context"). Sparse, line-level. Also tracked.
+
+---
+
+## UX Module (optional)
+
+The UX module provides opinionated static analysis rules for common UX anti-patterns. It is **off by default** since UX preferences vary across teams and projects. Enable selectively via the `ux:{}` config namespace.
+
+**Why optional?** Many teams have different UX preferences, and enabling UX rules on existing projects would flag pre-existing markup. These are good-enough defaults for NEW projects where you want opinionated UX guidance but have no specific opinion yourself.
+
+### Configuration
+
+```toml
+# .slopgate/config.toml
+# ... other config
+
+# UX module (optional) — off by default, opt-in per sub-module
+[ux]
+a11y = "high"        # Accessibility violations (gate commits)
+cls = "high"         # Cumulative Layout Shift violations (gate commits)
+feedback = "high"    # Silent async / double-submit (gate commits)
+taste = "advisory"   # Design taste violations (report only, don't gate)
+advisory = "advisory" # Heuristic nudges (report only, higher false-positive)
+# taste = "medium"   # equivalent to 'advisory'
+# taste = true       # use sub-module default severity
+# omit key = that sub-module OFF
+# delete whole [ux] table = entire module OFF
+```
+
+### Sub-modules
+
+| Key | Catches | Default Severity | Framework § |
+|-----|---------|------------------|-------------|
+| `a11y` | onClick on `<div>`/`<span>` without role; `<a onClick>` without href; `<img>` without alt; `<button>` without type; positive `tabIndex` | `high` | §11 |
+| `cls` | `<img>`/`<video>`/`<iframe>` without width/height | `high` | §13 |
+| `feedback` | async `onClick` on a `<button>` with no `disabled` state (double-submit, silent wait) | `high` | §3/§12 |
+| `taste` | emoji in UI, "trusted by" clichés, Lorem ipsum, robotic microcopy, heavy drop shadows, linear/long (>300ms) motion | `medium` | §0/§6/§26 |
+| `advisory` | modal without `onClose`; array index as React `key`; view state (tab/page/filter) in `useState` instead of the URL | `medium` | §10/§14 |
+
+Magic hardcoded colors/spacing (`#hex`, `rgb()`/`hsl()`, multi-digit `px`) are caught by the baseline `raw-hex` pack (§15), independent of the UX module.
+
+### Severity Levels
+
+- **`'critical'`/`'high'`**: Gates commits (blocks by default, since default gate is `['critical','high']`)
+- **`'medium'`/`'advisory'`**: Reports but doesn't block commits (useful for gradual adoption)
+- **`true`**: Use the sub-module's default severity
+- **Omit key**: That sub-module is OFF
+- **Delete `ux:{}` block**: Entire UX module is OFF
+
+### Opt-out
+
+Symmetric and trivial:
+- Delete a key to disable one sub-module: `ux: { a11y: 'high' }` (cls and taste OFF)
+- Delete the whole `ux:{}` block to disable the entire module
+
+### Companion Skill
+
+Pair the static UX module with the `/slopgate-ux` skill for semantic UX directives that static analysis can't enforce (four-states, button hierarchy, focus-trap, optimistic UI, etc.).
+
+---
+
+## Config Reference (`.slopgate/config.toml`)
+
+```toml
+# Repository layout
+roots = ["src"]                          # source roots to scan
+exts = [".ts", ".tsx", ".astro"]         # file extensions
+skipDirs = ["node_modules", "dist"]      # dirs to skip
+
+# Rule packs
+baseline = ["no-stubs", "ts-suppress", "as-any"]  # built-in baseline packs to enable (opt-in)
+rules = []                               # project regex rule packs — must be [] (PHASE-2, not yet supported)
+astRules = "./rules/ast"                 # dir of .yml AST rules (optional)
+astDisable = []                          # rule ids to disable (escape hatch)
+
+# Custom file paths (relative to repo root)
+suppressions = "./suppressions.json"     # line-level exemptions
+fixtures = "./fixtures"                  # test fixture canaries
+# baselinePath is auto-computed: .slopgate/baseline.json
+
+# Commit-tier checkers (detected at init; absent = off)
+# Per-checker options as key = value under each [checkers.<name>] table.
+[checkers.tsc]
+# e.g. timeout = 60
+
+# UX module (optional) — off by default, opt-in per sub-module
+[ux]
+a11y = "high"        # accessibility violations
+cls = "high"         # cumulative layout shift
+taste = "advisory"   # design taste (reports, doesn't gate)
+
+# Severity filtering (which violations show in reports)
+[gate]
+file = ["critical", "high"]    # fast-tier report threshold
+staged = ["critical", "high"]  # commit-tier report threshold
+```
+
+**Auto-generated during `init`:**
+- `roots` — detected from workspace packages and src/ dirs
+- `exts` — detected from file walk
+- `skipDirs` — detected from common exclusions (node_modules, dist, tests, .worktrees)
+- `checkers` — detected from installed binaries and config files (all true initially)
+
+---
+
+## Rule Packs
+
+### Baseline Regex Packs (Shipped)
+
+All are opt-in via the `baseline` array in config. Severity drives the gate threshold (`critical`/`high` block by default).
+
+| Pack | Severity | Category | Catches |
+|------|----------|----------|---------|
+| `no-stubs` | critical | convention | Stub / placeholder / "not implemented" / deferred-work markers |
+| `ts-suppress` | high | convention | `@ts-ignore` / `@ts-expect-error` — suppressing tsc instead of fixing the cause |
+| `as-any` | high | convention | `as any` casts that disable type safety |
+| `raw-hex` | high | convention | Hardcoded hex / `rgb()` colors + raw multi-digit `px` — use design tokens |
+| `sql-safety` | critical | convention | `SELECT … FOR UPDATE` with an aggregate (Postgres rejects this at runtime) |
+| `kv-ban` | critical | boundary | Cloudflare KV in read-after-write paths (eventually-consistent) |
+| `live-secrets` | critical | security | Hardcoded Stripe / webhook / Google live credentials |
+| `eval-ban` | critical | security | `eval` / dynamic code execution (injection surface) |
+| `pii-logs` | high | security | PII fields written to logs / error trackers |
+| `weak-hash` | high | security | MD5 / SHA-1 for integrity checks or passwords (cryptographically broken) |
+
+### Baseline AST Rules (Shipped, Always Active)
+
+Loaded automatically alongside the regex packs (the resolver always adds `rules/baseline/ast`); disable any by id via `astDisable = [...]`.
+
+| Rule id | Catches |
+|---------|---------|
+| `empty-catch` (ts + tsx) | Empty `catch` block silently swallowing an error |
+| `inner-html` | Unsafe `innerHTML` / `dangerouslySetInnerHTML` assignment |
+| `target-blank-norel` | `target="_blank"` anchor missing `rel="noopener"` |
+| `window-in-render` | `window`/`document` access during render (SSR hazard) |
+
+### Stack Packs (Shipped)
+
+Opt-in via `stack = ["cloudflare"]`:
+
+| Pack | Rule ids |
+|------|----------|
+| `cloudflare` | `cf-env-spread-secrets`, `process-env-access`, `waituntil-bare-method-ref`, `cf-getCloudflareContext-banned`, `hono-env-direct-access` |
+
+**Planned (v2+):**
+- Depth rules — pass-through-fn, delegating-wrapper (Ousterhout symptoms)
+- Test-slop rules — test-no-assertion, test-skip-only
+- Custom project **regex** rule packs (the `rules = [...]` field — see [Project-Owned Rules](#project-owned-rules))
+
+### Project-Owned Rules
+
+Add custom rules as **AST rules** — `.yml` files in ast-grep syntax:
+
+```yaml
+id: my-ast-rule
+language: tsx
+severity: error          # ast-grep level (error|warning|info)
+message: Rule violation
+note: '{"severity":"high","category":"convention","resolution":"…"}'  # slopgate metadata
+rule:
+  pattern: 'someBadCall($$$ARGS)'   # code-snippet matcher; or structural kind/has/inside/all/any/not
+```
+
+Point `astRules` at the directory holding them:
+
+```toml
+astRules = "./rules/ast"  # auto-loads all .yml files in this dir
+```
+
+> **Note:** Custom **project regex rule packs** (the `rules = [...]` field) are **not yet supported** by the native engine. `rules` must currently be `[]`; a non-empty value errors with `slopgate: project rule pack "<path>" cannot be loaded by the native TOML resolver (PHASE-2: project rule packs)`. Project regex packs are planned (PHASE-2). For now, use ast-grep YAML for custom rules, or one of the built-in baseline/stack packs.
+
+---
+
+## How Rules Are Authored
+
+### Regex Rules
+
+> **Note:** Authoring *custom project* regex rule packs is **not yet supported** by the native engine (PHASE-2 — see [Project-Owned Rules](#project-owned-rules)). The shape below describes how the **built-in** regex packs are defined (compiled into the engine); it is reference, not a workflow you can wire in via `rules` today. Use ast-grep YAML for custom rules.
+
+Patterns are regex strings with flags (i, m, s, etc.). A pattern matches any line containing the regex.
+
+**Example:**
+```
+{
+  id: 'no-stubs-placeholder',
+  pattern: 'placeholder\\s+(?:for now|impl)',
+  flags: 'i',
+  canary: '// placeholder for now',
+  negativeCanary: ['placeholder={t(\'x\')}'],  // should NOT match
+}
+```
+
+**Advanced:**
+- `minFiles: N` — pattern must match in ≥ N files to fire (catch widespread slop)
+- `excludeGlobs: ['*.test.ts']` — skip matching in these paths
+- `includeGlobs: ['src/**']` — only match in these paths
+- Suppressions: per-file, per-line (lineHash = sha256 of line text)
+
+### AST Rules
+
+Written in ast-grep YAML syntax; scoped to source roots + extensions from config.
+
+**Example** (modeled on the shipped `rules/baseline/ast/empty-catch-block-tsx.yml`):
+```yaml
+id: empty-catch
+language: tsx
+severity: error          # ast-grep level (error|warning|info)
+message: Empty catch block swallows error silently
+note: '{"severity":"high","category":"convention","resolution":"Handle or rethrow; log with context."}'
+rule:
+  pattern: 'try { $A } catch ($E) {}'   # code-snippet matcher; or structural kind/has/inside/all/any/not
+```
+
+The top-level `severity` is ast-grep's own level; slopgate's gating severity/category/resolution live in the
+JSON `note` field.
+
+**Fixtures:** add a source canary that *triggers* the rule to `.slopgate/fixtures/src/` (built-in rules use
+`rules/baseline/fixtures/src/`). A `.ts`/`.tsx` file containing the violating code is enough:
+
+```tsx
+// .slopgate/fixtures/src/empty-catch.tsx
+export function f() { try { risky(); } catch (e) {} }  // should fire empty-catch
+```
+
+`slopgate --self-test --config .slopgate/config.toml` scans the fixtures and asserts every rule fires at
+least once.
+
+---
+
+## Hooks Integration
+
+### Claude Code Hooks
+
+Init wires slopgate into `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "/path/to/slopgate/hooks/commit-hook.sh"
+        }
+      ]
+    }],
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "/path/to/slopgate/hooks/edit-hook.sh"
+        }
+      ]
+    }]
+  }
+}
+```
+
+- **PreToolUse** (commit-hook.sh) — fires before Bash tool use; checks for `git commit` in the command and runs `slopgate --staged`
+- **PostToolUse** (edit-hook.sh) — fires after Edit/Write; runs `slopgate --file` on the touched file (fast tier, 5-second timeout)
+
+### Git Pre-Commit Hook
+
+`init` also installs `.git/hooks/pre-commit` (or appends to existing). This is the native git hook; it catches commits from any tool (terminal, IDE, other agents).
+
+```bash
+#!/usr/bin/env bash
+ROOT=$(git rev-parse --show-toplevel) || exit 0
+CONFIG="$ROOT/.slopgate/config.toml"
+[ -f "$CONFIG" ] || exit 0
+exec slopgate --staged --config "$CONFIG"
+```
+
+The hook can be bypassed with `git commit --no-verify`, which is intentional (user-initiated escape hatch).
+
+---
+
+## Suppressions
+
+Edit `.slopgate/suppressions.json`:
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {
+      "ruleId": "no-stubs-placeholder",
+      "file": "src/app.ts",
+      "lineHash": "abc123def..."
+    }
+  ]
+}
+```
+
+Line hash is auto-generated: `sha256(trimmedLine).slice(0, 16)`.
+
+To suppress a violation, grab the line hash from the report and add an entry. The line text must match exactly (trimmed); unrelated edits shift line numbers but keep line text stable.
+
+---
+
+## Testing
+
+### Run Self-Test
+
+```bash
+npm run self-test
+```
+
+Validates:
+- Regex engine (patterns match canaries, skip negativeCanaries)
+- AST engine (ast-grep rules parse + match fixtures)
+- Checker parsers (tsc, knip, jscpd, depcruise, type-coverage outputs parse correctly)
+- Ratchet fingerprints (stability under line shifts)
+- Suppressions (line hashing, deduplication)
+
+---
+
+## Examples
+
+### Example 1: Block Unsafe Type Casts
+
+Config:
+```toml
+baseline = ["as-any"]
+[gate]
+staged = ["critical", "high"]
+```
+
+Commit a file with `const x = y as any;`:
+```
+slopgate: 1 violation(s)
+
+regex › as-any-cast
+  src/utils.ts:42
+  Unsafe `as any` cast
+  severity: high
+  resolution: Use a precise type or a discriminated narrowing.
+
+exit code: 1 (commit blocked)
+```
+
+Fix it to `const x = y as unknown;` or a proper type, then commit.
+
+### Example 2: Allow Pre-Existing Copy-Paste, Block New Ones
+
+Config:
+```toml
+baseline = []
+[checkers.jscpd]
+minTokens = 50
+```
+
+Run `slopgate baseline --config .slopgate/config.toml` to baseline existing clones. Now:
+- Commits pass unless they introduce NEW duplications
+- Track paydown via `slopgate baseline --prune` (drops resolved entries)
+
+### Example 3: Custom Architecture Rules
+
+Create `.slopgate/depcruise.cjs`:
+```javascript
+module.exports = {
+  forbidden: [
+    {
+      name: 'no-ui-to-db',
+      severity: 'error',
+      from: { path: 'src/ui' },
+      to: { path: 'src/db' },
+    },
+  ],
+};
+```
+
+Now commits that import database code from UI layer are blocked.
+
+### Example 4: Silence a Built-in Rule in One Project
+
+Config:
+```toml
+baseline = ["no-stubs", "as-any"]
+astDisable = ["target-blank-norel"]  # this app links only to vetted internal routes
+```
+
+`astDisable` lists built-in AST rule ids to turn off for this repo; every other rule stays active.
+
+---
+
+## Architecture
+
+### Data Flow (Commit Tier)
+
+```
+git commit
+  └─ .git/hooks/pre-commit
+       └─ slopgate --staged --config <repo>/.slopgate/config.toml
+            ├─ Enumerate staged files
+            ├─ Regex engine (patterns → violations)
+            ├─ AST engine (ast-grep rules → violations)
+            ├─ Checker adapters
+            │  ├─ tsc (type errors)
+            │  ├─ knip (dead code)
+            │  ├─ jscpd (duplication)
+            │  ├─ dependency-cruiser (architecture)
+            │  ├─ type-coverage (any propagation)
+            │  └─ diff-shape (mixed concerns)
+            ├─ Ratchet baseline filter (drop pre-existing)
+            ├─ Suppressions filter (per-file, per-line)
+            ├─ Severity gate (critical/high)
+            └─ Report + exit code (0 = pass, 1 = blocked)
+```
+
+### Checker Timeout and Errors
+
+Each checker has a per-tool timeout (configurable):
+- tsc: 120s
+- knip: 90s
+- jscpd: 60s
+- depcruise: 60s
+- type-coverage: 120s
+
+Tool crash / timeout → `⚠ skipped: <id> (<reason>)` warning, gate continues (fail-open on infra). Violations still block; missing tools don't.
+
+---
+
+## Limitations & Future Work
+
+- **Git-only** — no other VCS support
+- **No auto-fix** — violations are reported, not automatically corrected
+- **No CI integration yet** — hooks are local and Claude Code only; CI layer is future work
+- **`slopgate audit` command** — planned for v2 (non-gating architecture-health report: hotspots, module shape, co-change coupling, ratchet progress tracking)
+- **Embeddings-based semantic duplicate detection** — planned, not in v1
+- **API-surface diff gate** — track breaking changes to public exports (future)
+- **LLM-judge skill** — on-demand deep review of architectural debt (separate sub-project)
+- **Rule harvesting** — auto-generate rules from repeated violations (separate sub-project)
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT — See [LICENSE](./LICENSE) for details.