feat(enforce): complete enforcement loop with script/CI generators and docs update

CHANGELOG.md

@@ -14,6 +14,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `SECURITY.md` with supported versions and vulnerability reporting
 - Release CI workflow (`.github/workflows/release.yml`) with PyPI Trusted Publishing and automated GitHub Release creation
 - "Releasing" section in `CLAUDE.md` documenting the tag-based release process
+- Staged enforcement pipeline: `adr-kit enforce <level>` validates ADR policies at commit, push, and CI stages
+- `adr-kit setup-enforcement` command for configuring git hooks
+- `adr-kit enforce-status` command for viewing enforcement configuration
+- `--with-enforcement` flag on `adr-kit init` for one-step git hook setup
+- Enforcement classifier maps ADR policy types to enforcement levels (commit/push/CI)
+- `StagedValidator` runs classified checks against staged, changed, or all files per enforcement level
+- `HookGenerator` creates pre-commit and pre-push git hooks with managed sections (idempotent, non-interfering)
+- JSON enforcement reporter (`--format json`) with AI-readable `EnforcementReport` schema
+- Architecture layer boundary enforcement at push level
+- Standalone validation script generator (`adr-kit generate-scripts`) — creates stdlib-only Python scripts from ADR policies with `--quick` and `--full` modes
+- CI workflow generator (`adr-kit generate-ci`) — creates GitHub Actions YAML for ADR enforcement on pull requests
+- Approval workflow auto-generates validation scripts for newly approved ADRs
+- Importance-weighted ranking in `adr_planning_context` — centrality, policy richness, tag breadth, and status penalties applied as multiplicative boost on relevance scores
+- Individual ADR MCP resources (`adr://{adr_id}`) for progressive disclosure — agents fetch full ADR content on demand via `resource_uri` field
 
 ### Changed
 - README rewritten for user focus: problem statement, quick start, tool reference, FAQ
@@ -23,6 +37,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - `pyproject.toml` project URLs updated from placeholder `your-org` to correct `kschlt`
 - Added Python 3.13 classifier to package metadata
+- `mcp-health` now shows detected version at startup and joins update thread for in-order notification
+
+### Removed
+- `PolicyPatternExtractor` and regex-based policy extraction — replaced by agent reasoning approach
 
 ---
 

README.md

@@ -25,7 +25,7 @@ ADR Kit operates in three layers:
 
 **2. Context at the Right Time** — Before implementing a feature, ADR Kit surfaces only the relevant decisions. Out of 50 ADRs, 3–5 relevant ones reach the agent's context. Right information, right time, without flooding the context window.
 
-**3. Enforcement** — Approved ADRs automatically generate ESLint and Ruff lint rules. Violations are blocked with a clear reference to the decision they violate, triggering a choice: fix the code, or supersede the ADR if the decision needs to evolve.
+**3. Enforcement** — Approved ADRs generate ESLint and Ruff lint rules, standalone validation scripts, and CI workflow configurations. Enforcement runs at three stages: pre-commit (import checks on staged files), pre-push (architecture layer boundaries), and CI (comprehensive validation). Violations include a reference to the ADR they violate, triggering a choice: fix the code, or supersede the ADR if the decision needs to evolve.
 
 ## Quick Start
 
@@ -145,19 +145,32 @@ A: Yes. No external API calls. Semantic search uses local models. Your ADRs and
 **Q: What if a decision can't be expressed as a lint rule?**
 A: Not all decisions map to lint rules — "use microservices" can't become an ESLint rule. These decisions still benefit from lifecycle management and context loading (layers 1 and 2). Enforcement only applies to decisions with concrete, checkable constraints: library choices, coding patterns, file structure.
 
+**Q: How does staged enforcement work?**
+A: ADR Kit installs git hooks that run policy checks at the right stage. Pre-commit checks import restrictions on staged files (<5s). Pre-push checks architecture boundaries on changed files (<15s). CI re-runs everything comprehensively. Set up with `adr-kit init --with-enforcement` or `adr-kit setup-enforcement`.
+
+**Q: Can I generate CI pipelines for ADR enforcement?**
+A: Yes. `adr-kit generate-ci` creates a GitHub Actions workflow that validates ADR policies on pull requests. `adr-kit generate-scripts` creates standalone validation scripts that work without ADR Kit installed — useful for CI environments or teams that don't want a runtime dependency.
+
 **Q: Does this replace code reviews?**
 A: No. ADR Kit catches architectural violations automatically, but code reviews catch logic errors, security issues, and design problems that lint rules can't detect.
 
 ## Current Status
 
 **Working today:**
-- Selective context loading by task relevance (`adr_planning_context`)
+- Selective context loading by task relevance with importance-weighted ranking (`adr_planning_context`)
+- Individual ADR MCP resources (`adr://{adr_id}`) for on-demand content fetch
 - Implicit decision discovery in existing codebases (`adr_analyze_project`)
 - ADR creation with quality gate — rejects vague decisions before file creation
 - ESLint and Ruff rule generation from import policies
+- Staged enforcement at commit, push, and CI levels (`adr-kit enforce`)
+- Architecture layer boundary enforcement at push level
+- Git hook setup via `adr-kit init --with-enforcement` or `adr-kit setup-enforcement`
+- Standalone validation script generation (`adr-kit generate-scripts`)
+- GitHub Actions CI workflow generation (`adr-kit generate-ci`)
 
 **Current limitations:**
-- Enforcement is linter-based only. Pattern policies, architecture boundaries, and config enforcement are modelled but not yet active.
+- Pattern enforcement generates standalone validation scripts but not native ESLint/Ruff rules yet.
+- Config enforcement (tsconfig, ruff, mypy settings) is modelled but not yet validated.
 - Language support: JavaScript/TypeScript (ESLint) and Python (Ruff). Other languages require manual policy application.
 
 See [ROADMAP.md](ROADMAP.md) for what's planned and why.

ROADMAP.md

@@ -2,40 +2,50 @@
 
 This document tracks what's planned, in what order, and why. Priorities reflect what most directly unblocks the core value of ADR Kit.
 
-→ For current capabilities and limitations, see [README.md](README.md#current-status)
-→ For technical implementation details, see [TECHNICAL.md](TECHNICAL.md)
+> For current capabilities and limitations, see [README.md](README.md#current-status)
+> For technical implementation details, see [TECHNICAL.md](TECHNICAL.md)
 
 ---
 
 ## Up Next
 
-### Staged Enforcement
-
-**Why:** Import restrictions currently either block immediately or warn. Real projects need a transition period — warn on existing violations, block new ones. Without staged enforcement, teams can't adopt ADR Kit on a codebase that already has violations.
+### Pattern Enforcement via Linter Adapters
 
-**What:** A warn → block enforcement pipeline with thresholds, so teams can clean up existing violations incrementally without being blocked from day one.
+**Why:** Pattern policies currently generate standalone validation scripts but don't produce native ESLint or Ruff rules. Native linter integration gives IDE-level feedback — developers see violations inline without running a separate script.
 
-### Complete Enforcement Loop
+**What:** Extend the ESLint and Ruff adapters to emit rules for the `patterns` policy type (regex-based code pattern matching with per-language support).
 
-**Why:** Pattern policies, architecture boundaries, and config enforcement are fully modelled in the schema but don't yet generate lint rules. The enforcement story is incomplete until all policy types produce real output.
+### Config Enforcement
 
-**What:** Extend the guardrail generator to cover pattern rules (regex), architecture layer boundaries, and tool configuration enforcement (tsconfig, ruff/mypy settings).
-
-### DX Polish
+**Why:** Config enforcement models exist (`TypeScriptConfig`, `PythonConfig`) but no validation logic runs at any level. Teams can define required tsconfig/ruff/mypy settings in ADR policies, but violations aren't caught.
 
-**Why:** Several rough edges in the day-to-day workflow slow down adoption: error messages that don't suggest next steps, missing `--adr-dir` defaults, gaps in CLI output.
-
-**What:** Targeted improvements to error messages, CLI UX, and feedback quality across the MCP tools.
+**What:** Implement validators that check `tsconfig.json`, `ruff.toml`, and `mypy.ini`/`pyproject.toml` settings against `config_enforcement` policies. Wire into the staged enforcement pipeline at CI level.
 
 ---
 
 ## Later
 
-- **Semantic search as primary conflict detection** — Currently keyword-based. Semantic search (sentence-transformers) is implemented but used as optional fallback. Making it primary improves conflict detection for conceptually related ADRs that don't share keywords.
+- **Semantic search as primary conflict detection** — Currently keyword-based. Semantic search (sentence-transformers) is implemented but used as optional enhancement. Making it primary improves conflict detection for conceptually related ADRs that don't share keywords.
 - **ADR templates** — Common decision types (library choice, architecture pattern, API design) as starting templates to reduce ADR creation friction.
 - **Log4brains integration** — Static site generation for browsing ADRs with history and status tracking.
 - **Import-linter support** — Python enforcement via import-linter in addition to Ruff, for more expressive architecture boundary rules.
 
 ---
 
+## Recently Completed
+
+### Staged Enforcement
+
+Enforcement pipeline with three stages: pre-commit (import checks on staged files, <5s), pre-push (architecture boundaries on changed files, <15s), and CI (comprehensive validation, <2min). Git hooks via `adr-kit init --with-enforcement` or `adr-kit setup-enforcement`. JSON reporter for agent/CI consumption.
+
+### Complete Enforcement Loop
+
+Architecture layer boundary enforcement at push level. Standalone validation script generator (`generate-scripts`) creates stdlib-only Python scripts for all policy types. CI workflow generator (`generate-ci`) creates GitHub Actions YAML. Approval workflow auto-generates scripts.
+
+### DX Polish
+
+Importance-weighted ranking in `adr_planning_context` for better ADR relevance scoring. Individual ADR MCP resources (`adr://{adr_id}`) for progressive disclosure. Health check version detection fix.
+
+---
+
 For release history, see [CHANGELOG.md](CHANGELOG.md).

TECHNICAL.md

@@ -138,6 +138,29 @@ And for Python, updates `pyproject.toml` under `[tool.ruff]`.
 
 **The feedback loop:** Violations aren't dead ends. The error message tells the developer (or agent) which ADR is being violated — feeding back into lifecycle management. Either fix the code to comply, or supersede the ADR if the decision needs to evolve.
 
+### Staged Enforcement
+
+Beyond lint rules, ADR Kit enforces policies at three stages during the development workflow:
+
+| Stage | When | Budget | What Runs |
+|---|---|---|---|
+| **Pre-Commit** | `git commit` | <5s | Import restrictions, syntax patterns (staged files only) |
+| **Pre-Push** | `git push` | <15s | Architecture layer boundaries (changed files) |
+| **CI** | Pull request | <2min | All checks comprehensively (safety net) |
+
+Set up enforcement with `adr-kit init --with-enforcement` or `adr-kit setup-enforcement`. The hooks are idempotent and non-interfering — they append managed sections to existing hooks without overwriting.
+
+Use `adr-kit enforce <level> --format json` to get an AI-readable `EnforcementReport` with structured violation data for agents and CI pipelines.
+
+### Standalone Scripts and CI Generation
+
+For teams that want enforcement without a runtime dependency on ADR Kit:
+
+- **`adr-kit generate-scripts`** creates stdlib-only Python validation scripts from ADR policies. Scripts support `--quick` (pre-push) and `--full` (CI) modes and output `EnforcementReport` JSON.
+- **`adr-kit generate-ci`** creates a GitHub Actions workflow YAML that runs enforcement checks on pull requests.
+
+Both are generated automatically when an ADR is approved.
+
 ### What's Automatic on Approval
 
 When you call `adr_approve`, this happens without any manual steps:
@@ -148,6 +171,8 @@ When you call `adr_approve`, this happens without any manual steps:
 4. Ruff rules generated (if Python policy present)
 5. ADR index updated
 6. Codebase validated against new constraints
+7. Standalone validation scripts generated (if ADR has enforceable policies)
+8. Git hooks updated (if enforcement is configured)
 
 ---
 
@@ -159,8 +184,8 @@ The `policy` block in ADR front-matter supports five enforcement types:
 |------|-----------------|--------|
 | `imports` | Library restrictions (JS/TS) | Active |
 | `python` | Module restrictions (Python) | Active |
-| `patterns` | Code pattern rules with regex | Defined, not yet enforced |
-| `architecture` | Layer boundaries + required structure | Defined, not yet enforced |
+| `patterns` | Code pattern rules with regex | Enforced via generated scripts; no native linter rules yet |
+| `architecture` | Layer boundaries + required structure | Enforced at push level + generated scripts |
 | `config_enforcement` | Tool configuration (tsconfig, ruff, mypy) | Defined, not yet enforced |
 
 <details>
@@ -245,11 +270,25 @@ adr-kit validate --id ADR-0001  # Validate a specific ADR
 adr-kit contract-build          # Rebuild constraints contract
 adr-kit contract-status         # View current contract
 
-# Enforcement
+# Lint rule management
 adr-kit guardrail-apply         # Apply lint rules manually
 adr-kit guardrail-status        # Check guardrail status
 adr-kit preflight postgresql    # Manual preflight check
 
+# Staged enforcement
+adr-kit enforce commit          # Run commit-level checks (staged files)
+adr-kit enforce push            # Run push-level checks (changed files)
+adr-kit enforce ci              # Run CI-level checks (all files)
+adr-kit enforce ci --format json  # JSON output for agents/CI
+
+# Enforcement setup
+adr-kit setup-enforcement       # Configure git hooks
+adr-kit enforce-status          # Show enforcement configuration
+
+# Script & CI generation
+adr-kit generate-scripts        # Generate standalone validation scripts
+adr-kit generate-ci             # Generate GitHub Actions workflow
+
 # Maintenance
 adr-kit mcp-health              # Test MCP server connectivity
 adr-kit update                  # Check for updates
@@ -259,6 +298,17 @@ adr-kit update                  # Check for updates
 
 ## CI/CD Integration
 
+The fastest way to set up CI enforcement is to generate a workflow automatically:
+
+```bash
+adr-kit generate-ci    # Creates .github/workflows/adr-enforcement.yml
+```
+
+The generated workflow runs `adr-kit enforce ci --format json` on pull requests and fails on violations.
+
+<details>
+<summary><b>Manual CI setup (alternative)</b></summary>
+
 ```yaml
 # .github/workflows/adr.yml
 name: ADR Validation
@@ -282,10 +332,15 @@ jobs:
       - name: Validate ADRs
         run: adr-kit validate
 
+      - name: Enforce policies
+        run: adr-kit enforce ci --format json
+
       - name: Check lint rules are current
         run: git diff --exit-code .eslintrc.adrs.json
 ```
 
+</details>
+
 ---
 
 ## Health Check
@@ -306,6 +361,6 @@ Expected output:
 
 ## Project Status
 
-ADR Kit is under active development. Test coverage: 187 tests (144 unit + 43 integration) across the core workflows, MCP server integration, and quality assessment system.
+ADR Kit is under active development. Test coverage: 309 tests (220 unit + 66 integration + 23 other) across the core workflows, MCP server integration, quality assessment, and enforcement systems.
 
 See [ROADMAP.md](ROADMAP.md) for what's planned and [CONTRIBUTING.md](CONTRIBUTING.md) to contribute.