chore(ratchet): require ci-ratchet; add scripts/hooks/CI, baseline; README/CLI next steps

require ci-ratchet status check; add scripts/hooks/CI; add baseline; update README and DEVELOPING; CLI init prints ratchet next steps

Author: mojoatomic

.github/workflows/ci-ratchet.yml

@@ -0,0 +1,42 @@
+name: ci-ratchet
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  ratchet-and-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: ESLint JSON
+        run: npm run lint:json
+
+      - name: Analyze current
+        run: npm run analyze:current
+
+      - name: Ratchet (fail on new debt)
+        run: npm run ratchet
+
+      - name: Run tests
+        run: npm test
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: analysis-and-lint-${{ github.sha }}
+          path: |
+            lint-results.json
+            analysis-current.json
+          if-no-files-found: error
+          retention-days: 7

.husky/pre-push

@@ -1 +1 @@
-npm test
+npm run lint:json && npm run analyze:current && npm run ratchet && npm test

README.md

@@ -10,10 +10,11 @@ ESLint plugin with AI agent configuration generator for JavaScript projects.
 
 ## What This Provides
 
-This plugin combines two functions:
+This plugin combines two functions and built-in guardrails:
 
 1. **ESLint rules** - 8 rules targeting AI-generated code patterns
 2. **Configuration generator** - CLI tool that creates AI agent guides and ESLint configs
+3. **Guardrails: No-New-Debt Ratchet** — hooks + CI that block increases in analyzer categories. See [No-New-Debt Ratchet (All projects)](#no-new-debt-ratchet-all-projects)
 
 ### Generated Files
 
@@ -87,6 +88,7 @@ After setup, you'll have:
 
 - Review `AGENTS.md` for coding guidelines
 - Run `npx eslint .` to check your code
+- Enable the No‑New‑Debt Ratchet to prevent regressions (see section below)
 - Use AI assistants (they'll automatically read AGENTS.md)
 
 ## Quick Start
@@ -464,6 +466,48 @@ This tool is designed for JavaScript/Node.js projects and is currently in active
 
 ---
 
+## No-New-Debt Ratchet (All projects)
+
+Keep quality trending in one direction only: better. The ratchet blocks any increase in analyzer categories (complexity, architecture, domain terms, magic numbers) while allowing gradual cleanup.
+
+Why this matters (works for greenfield and brownfield)
+- New templates often ship with violations; accept the baseline once, then prevent regressions
+- Rapid prototyping: iterate fast without blocking, but never get worse than the last accepted state
+- AI-generated and copied code: capture current count as baseline; fix over time
+
+How it works in this repo
+- Baseline file: analysis-baseline.json
+- Local hook: pre-push runs `npm run lint:json && npm run analyze:current && npm run ratchet && npm test`
+- CI: .github/workflows/ci-ratchet.yml runs the same and uploads artifacts
+
+Usage
+```bash
+# Create/refresh baseline from current state (intend to accept current count)
+npm run lint:json && npm run analyze:baseline
+
+# Check current branch against baseline (runs in hooks/CI)
+npm run lint:json && npm run analyze:current && npm run ratchet
+
+# After reducing violations, refresh baseline intentionally
+npm run lint:json && npm run analyze:baseline
+# Commit the updated baseline (recommended message):
+# 'ratchet: refresh baseline after reductions'
+```
+
+Modes for different project types
+- Zero-Tolerance (pure greenfield)
+  - Keep baseline at 0; optionally promote key rules to error in CI-only config
+- Flexible Greenfield (prototype mode)
+  - Set baseline from current state (e.g., template/prototype); prevent increases; ratchet down as you fix
+- Brownfield (existing code)
+  - Set baseline from current codebase; prevent increases; reduce over time; optionally use path-specific overrides for legacy areas
+
+Adopting ratchet in other repos
+- Manual setup today: copy scripts/ratchet.js, add the npm scripts shown above, wire a pre-push hook, and add a CI job similar to ci-ratchet
+- Coming soon: a one-shot "guardrails setup" command to scaffold these pieces automatically (see issue #180)
+
+---
+
 ## Developing (Self-hosting guardrails)
 
 For contributors to this repo (self-hosting the plugin): running our rule fixers on the plugin’s own rule sources can mutate rule implementations. We added guardrails and documented a safe workflow — see docs/DEVELOPING.md.