feat(codebase-readiness, agent-ready): score and install regression-aware quality gates

.claude-plugin/marketplace.json

@@ -51,13 +51,13 @@
       "name": "codebase-readiness",
       "source": "./plugins/codebase-readiness",
       "description": "Score your codebase's readiness for autonomous AI agent work across 8 dimensions, framed around the Stripe benchmark of 1k+ AI-generated PRs per week",
-      "version": "1.7.0"
+      "version": "1.8.0"
     },
     {
       "name": "agent-ready",
       "source": "./plugins/agent-ready",
-      "description": "Make a codebase agent-ready with progressive-disclosure documentation and opinionated, stack-specific project skill recommendations. Creates CLAUDE.md as a symlink for Claude Code compatibility.",
-      "version": "1.4.0"
+      "description": "Make a codebase agent-ready with progressive-disclosure documentation, regression-aware quality gates, and opinionated, stack-specific project skill recommendations. Creates CLAUDE.md as a symlink for Claude Code compatibility.",
+      "version": "1.5.0"
     },
     {
       "name": "doc-audit",

.github/workflows/validate-skills.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     paths:
       - 'plugins/*/skills/**'
+      - 'plugins/*/tests/**'
       - 'plugins/*/.claude-plugin/plugin.json'
       - '.claude-plugin/marketplace.json'
 
@@ -57,6 +58,18 @@ jobs:
 
           echo "All skills passed validation."
 
+  test-templates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Test quality-gate engine template
+        run: python3 -m unittest discover -s plugins/agent-ready/tests -v
+
   validate-json:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -6,3 +6,6 @@ CLAUDE.local.md
 
 # Claude Code — worktree state
 .claude/worktrees
+
+# Python bytecode from template tests
+__pycache__/

README.md

@@ -47,7 +47,7 @@ Once you have your score, the [agent-ready](plugins/agent-ready/README.md) plugi
 | Skill | Description |
 |-------|-------------|
 | [Codebase Readiness](plugins/codebase-readiness/README.md) | Score your repo's readiness for autonomous AI agent work |
-| [Agent Ready](plugins/agent-ready/README.md) | Fix documentation gaps: scaffold CLAUDE.md, ARCHITECTURE.md, and docs/ |
+| [Agent Ready](plugins/agent-ready/README.md) | Fix documentation gaps and install regression-aware quality gates: CLAUDE.md, ARCHITECTURE.md, docs/, baseline-gated CI |
 | [TDD Workflow](plugins/tdd-workflow/README.md) | Test-driven development, one test at a time |
 | [Conventional Commits](plugins/conventional-commits/README.md) | Structured commit messages |
 | [Parallel Code Review](plugins/parallel-code-review/README.md) | Multi-agent code reviews |

plugins/agent-ready/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-ready",
-  "version": "1.4.0",
-  "description": "Make a codebase agent-ready with progressive-disclosure documentation and opinionated, stack-specific project skill recommendations. Creates CLAUDE.md as a symlink for Claude Code compatibility.",
+  "version": "1.5.0",
+  "description": "Make a codebase agent-ready with progressive-disclosure documentation, regression-aware quality gates, and opinionated, stack-specific project skill recommendations. Creates CLAUDE.md as a symlink for Claude Code compatibility.",
   "author": {
     "name": "Damian Galarza",
     "url": "https://www.damiangalarza.com"
@@ -16,6 +16,10 @@
     "agents-md",
     "claude-md",
     "progressive-disclosure",
-    "scaffolding"
+    "scaffolding",
+    "quality-gates",
+    "baseline",
+    "complexity",
+    "dead-code"
   ]
 }

plugins/agent-ready/README.md

@@ -1,6 +1,6 @@
 # agent-ready
 
-Make a codebase agent-ready by scaffolding AGENTS.md, ARCHITECTURE.md, and docs/ structure following progressive disclosure patterns, then recommend project-local skills for the detected stack.
+Make a codebase agent-ready by scaffolding AGENTS.md, ARCHITECTURE.md, and docs/ structure following progressive disclosure patterns, installing a regression-aware quality gate, and recommending project-local skills for the detected stack.
 
 This is the **remediation companion** to [codebase-readiness](../codebase-readiness/). While codebase-readiness *scores* how agent-ready your codebase is, agent-ready *fixes* the gaps by generating the documentation and structural artifacts that make a codebase legible to AI agents.
 
@@ -17,10 +17,28 @@ npx skills add dgalarza/claude-code-workflows --skill "agent-ready"
 
 | Mode | What It Does | Example Prompt |
 |------|-------------|----------------|
-| **scaffold** | Full documentation setup: docs/ structure, ARCHITECTURE.md, AGENTS.md, CLAUDE.md symlink, starter ADR | "Make this codebase agent-ready" |
+| **scaffold** | Full setup: docs/ structure, ARCHITECTURE.md, AGENTS.md, CLAUDE.md symlink, starter ADR, quality gate | "Make this codebase agent-ready" |
 | **architecture** | Generate ARCHITECTURE.md from actual codebase analysis | "Create an ARCHITECTURE.md" |
 | **agents-md** | Create or refactor AGENTS.md for progressive disclosure, create CLAUDE.md symlink | "Set up AGENTS.md" |
-| **audit** | Check existing agent-readiness artifacts for staleness and coherence | "Are my agent docs up to date?" |
+| **quality-gates** | Install a regression-aware quality gate: native complexity/duplication/dead-code checks, reviewed baseline, merge-base-aware CI, docs, tests | "Set up quality gates", "baseline our tech debt" |
+| **audit** | Check existing agent-readiness artifacts and the quality gate for staleness, coherence, and governance | "Are my agent docs up to date?" |
+
+## Quality Gates
+
+Documentation tells agents what good looks like; a quality gate stops them from shipping the opposite. The `quality-gates` mode installs a **regression-aware** gate: legacy debt is inventoried in a baseline and allowed to stay, while any PR that adds new complexity, duplication, or dead code -- or makes a baselined finding worse -- fails CI.
+
+What gets installed in your repo:
+
+| Piece | Detail |
+|-------|--------|
+| Checks | The language's native tools (ESLint/knip/jscpd, RuboCop/flay/debride, ruff/pylint/vulture, golangci-lint, detekt/PMD, clippy, PHPStan/phpmd). Native baseline or diff modes are used where they exist; otherwise a small stdlib engine (`scripts/quality-gate.py`) fingerprints findings so line-number churn does not create false "new" debt |
+| Commands | `report` / `check` / `baseline --prune`, identical locally and in CI, exposed through the project's task runner |
+| Baseline | Created only with a written `--reason` and a human `--approve --reviewed-by`; `check` fails while it is unreviewed; refused in CI; CODEOWNERS-protected. Stale entries fail `check` until pruned, so the baseline only shrinks |
+| CI | Merge-base-aware job that annotates findings on the PR diff. No `continue-on-error` |
+| Docs | `docs/guides/quality-gates.md` plus Definition of Done and directives in AGENTS.md |
+| Tests | A self-test proving a clean tree passes, synthetic debt fails, and stale entries are pruned |
+
+The pattern is documented in `references/quality-gates-pattern.md` with adapter recipes per language. The engine template has its own unit tests in `tests/`.
 
 ## Project Skill Recommendations
 
@@ -68,7 +86,8 @@ If an `AGENT_READY_ASSESSMENT.md` exists from a prior codebase-readiness assessm
 
 1. Run [codebase-readiness](../codebase-readiness/) to score your repo and identify gaps
 2. Run agent-ready to fix the documentation and structure gaps automatically
-3. Re-run the assessment to measure improvement
+3. If the assessment's Gate Maturity Level is L0-L2, run agent-ready in **quality-gates** mode
+4. Re-run the assessment to measure improvement
 
 [What each dimension means and why it matters →](https://www.damiangalarza.com/codebase-readiness/?utm_source=github&utm_medium=readme&utm_campaign=agent-ready)