chore: CI audit, docs overhaul, and release infrastructure

.github/workflows/ci.yml

@@ -7,20 +7,15 @@ on:
     branches: [ main ]
 
 jobs:
-  test:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
-
+  lint:
+    runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    
-    - name: Set up Python ${{ matrix.python-version }}
+
+    - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
-        python-version: ${{ matrix.python-version }}
+        python-version: "3.11"
 
     - name: Install uv
       uses: astral-sh/setup-uv@v6
@@ -30,61 +25,55 @@ jobs:
     - name: Install dependencies
       run: |
         uv pip install --system -e ".[dev]"
-    
+
     - name: Run linting with ruff
       run: |
         ruff check adr_kit/ tests/
-    
+
     - name: Check code formatting with black
       run: |
         black --check adr_kit/ tests/
-    
+
     - name: Run type checking with mypy
       run: |
         mypy adr_kit/
-
-    - name: Run tests with pytest
-      run: |
-        pytest tests/ --cov=adr_kit --cov-report=xml --cov-report=term-missing
 
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v4
-      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
-      with:
-        file: ./coverage.xml
-        flags: unittests
-        name: codecov-umbrella
+  test:
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        exclude:
+          - os: macos-latest
+            python-version: "3.10"
 
-  validate-adrs:
-    runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
 
-    - name: Set up Python
+    - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
-        python-version: "3.11"
+        python-version: ${{ matrix.python-version }}
 
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
         enable-cache: true
 
-    - name: Install ADR Kit
-      run: |
-        uv pip install --system -e .
-
-    - name: Validate project ADRs
-      run: |
-        adr-kit validate --adr-dir docs/adr || echo "ADR validation completed with issues"
-
-    - name: Generate ADR index
+    - name: Install dependencies
       run: |
-        adr-kit index --out docs/adr/adr-index.json --adr-dir docs/adr --no-validate
-    
-    - name: Check ADR index was updated
+        uv pip install --system -e ".[dev]"
+
+    - name: Run tests with pytest
       run: |
-        if [ ! -f "docs/adr/adr-index.json" ]; then
-          echo "ADR index was not generated"
-          exit 1
-        fi
+        pytest tests/ --cov=adr_kit --cov-report=xml --cov-report=term-missing
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella

.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write    # Create GitHub Release
+      id-token: write    # PyPI Trusted Publishing (OIDC)
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv pip install --system -e ".[dev]"
+
+    - name: Run tests
+      run: pytest tests/
+
+    - name: Build
+      run: uv build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        generate_release_notes: true

CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `CHANGELOG.md` with full version history
+- `TECHNICAL.md` with implementation details for each layer
+- `CONTRIBUTING.md` with development environment setup
+- `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
+
+### Changed
+- README rewritten for user focus: problem statement, quick start, tool reference, FAQ
+- `ROADMAP.md` "Recent Additions" section replaced with link to this changelog
+- CI workflow consolidated from 13 to 8 checks: dedicated lint job (blocks tests), trimmed test matrix to `(ubuntu + macOS) × (3.11–3.13) + ubuntu-only 3.10`
+
+### Fixed
+- `pyproject.toml` project URLs updated from placeholder `your-org` to correct `kschlt`
+- Added Python 3.13 classifier to package metadata
+
+---
+
+## [0.2.7] - 2026-02-10
+
+### Added
+- Decision quality guidance system: two-phase ADR creation with structured reasoning steps, quality criteria, and anti-pattern examples
+- Pre-validation quality gate: quality check runs before file creation, enabling correction loop without partial files — ADRs below B-grade threshold (75 pts) return `REQUIRES_ACTION` with improvement guidance
+- `skip_quality_gate` parameter on `adr_create` for test overrides
+- Pattern policy models (`PatternRule`, `PatternPolicy`) with JSON schema
+- Architecture policy models (`LayerBoundaryRule`, `RequiredStructure`, `ArchitecturePolicy`) with JSON schema
+- Config enforcement models (`TypeScriptConfig`, `PythonConfig`, `ConfigEnforcementPolicy`) with JSON schema
+- `adr_create` policy suggestion engine: auto-detects policy candidates from decision text and returns a structured promptlet guiding policy construction
+- AI warning extraction in `adr_planning_context`: consequences containing warnings are surfaced for relevant decisions
+- Domain filtering in `adr_planning_context` for 60–80% context reduction
+
+### Changed
+- Integration test architecture: replaced ~308 lines of regex extraction with a reasoning-agent promptlet. Agents reason about policies from their own decision text rather than ADR Kit extracting via pattern matching
+- MCP tool documentation moved from static docstrings to just-in-time response payloads (context-efficient ping-pong pattern)
+
+### Fixed
+- `adr_create` content generation simplified to prevent empty sections
+
+---
+
+## [0.2.6] - 2025-12-15
+
+### Added
+- Policy validation warnings for ADR creation — front-matter policy blocks are validated on `adr_create`
+- Constraint extraction guide and example ADR fixtures
+- MCP server configuration for development (`.mcp.json`)
+- Middleware to fix stringified JSON parameters from buggy MCP clients
+
+### Changed
+- Project structure refactored and developer documentation improved
+- Version read dynamically from package metadata
+
+### Fixed
+- CLI version detection with semantic comparison
+- `uv run` prefix added to all Makefile tool commands
+
+---
+
+## [0.2.5] - 2025-11-01
+
+### Added
+- Complete MCP server redesign with clean entry points and comprehensive tests
+- Strict mypy type safety configuration
+- Full test suite reorganization (unit / integration / MCP server)
+- Python 3.10 compatibility fixes (`datetime.timezone.utc`)
+
+### Changed
+- Migrated from pipx to uv for package installation
+- CI Python version matrix updated to match package requirements (`3.10+`)
+- `setup-uv` action upgraded from v4 to v6
+
+### Fixed
+- MCP server startup `TypeError` (Rich console parameter)
+- MCP server `next_steps` type compatibility
+- Windows-specific test failures
+- All deprecation warnings eliminated
+
+---
+
+## [0.1.0] - 2025-09-03
+
+Initial release.
+
+- 6 MCP tools: `adr_analyze_project`, `adr_preflight`, `adr_create`, `adr_approve`, `adr_supersede`, `adr_planning_context`
+- MADR format with optional `policy` block for enforcement
+- ESLint and Ruff rule generation from import policies
+- Selective context loading by task relevance
+- Local semantic search via sentence-transformers and FAISS
+- `adr-kit init`, `setup-cursor`, `setup-claude` CLI commands
+
+[Unreleased]: https://github.com/kschlt/adr-kit/compare/v0.2.7...HEAD
+[0.2.7]: https://github.com/kschlt/adr-kit/compare/v0.2.6...v0.2.7
+[0.2.6]: https://github.com/kschlt/adr-kit/compare/v0.2.5...v0.2.6
+[0.2.5]: https://github.com/kschlt/adr-kit/compare/v0.1.0...v0.2.5
+[0.1.0]: https://github.com/kschlt/adr-kit/releases/tag/v0.1.0

CLAUDE.md

@@ -1,3 +1,19 @@
+## Releasing
+
+1. Bump version in `pyproject.toml`
+2. Update `CHANGELOG.md` — move items from `[Unreleased]` to new `[X.Y.Z]` section with today's date
+3. Commit: `git commit -m "chore: bump version to X.Y.Z"`
+4. Tag: `git tag vX.Y.Z`
+5. Push tag: `git push origin vX.Y.Z`
+6. CI runs automatically: tests → build → PyPI publish → GitHub Release
+
+**PyPI Trusted Publishing** is configured (kschlt/adr-kit, workflow: `release.yml`).
+No tokens needed. If CI publish fails, fallback: `scripts/publish.sh` (requires `~/.pypirc`).
+
+> **One-time setup** (already done): pypi.org → adr-kit project → Manage → Publishing → add trusted publisher: owner `kschlt`, repo `adr-kit`, workflow `release.yml`.
+
+---
+
 # Project Context: What You're Building
 
 **You are developing ADR Kit** - a Python library and CLI tool that other projects install to manage their Architectural Decision Records.

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to ADR Kit
+
+Thank you for your interest in contributing to ADR Kit.
+
+## Getting Started
+
+**Prerequisites**: Python 3.10+, [uv](https://github.com/astral-sh/uv)
+
+```bash
+git clone https://github.com/kschlt/adr-kit.git
+cd adr-kit
+uv pip install -e ".[dev]"
+```
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+# Unit tests (fast)
+pytest tests/unit/
+
+# All tests
+pytest tests/
+
+# With coverage
+pytest tests/ --cov=adr_kit
+```
+
+### Quality Checks
+
+```bash
+ruff check adr_kit/ tests/   # Linting
+black adr_kit/ tests/        # Formatting
+mypy adr_kit/                # Type checking
+```
+
+Or use the Makefile:
+
+```bash
+make lint     # ruff + mypy
+make format   # black + ruff
+make test-all # all tests
+```
+
+### MCP Server
+
+ADR Kit's primary interface is an MCP server. To test it manually:
+
+```bash
+uv run adr-kit mcp-server
+```
+
+Always use `uv run adr-kit` (not a bare `adr-kit`) to ensure you're running the local editable install, not a system-wide version.
+
+**Detailed developer documentation:** See [CLAUDE.md](CLAUDE.md) for comprehensive instructions, including:
+- The three versions of ADR Kit (source, local install, system install) and which to use when
+- Development workflow (Edit → Test → Verify)
+- Testing the MCP server with local changes
+- Project structure and what gets packaged vs what's dev-only
+
+## Submitting Changes
+
+1. Fork the repository and create a branch from `main`
+2. Make your changes with tests
+3. Ensure all quality checks pass (`make lint && make test-all`)
+4. Open a pull request against `main`
+
+Please keep PRs focused — one concern per PR. Large refactors should be discussed in an issue first.
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/kschlt/adr-kit/issues). Include:
+- ADR Kit version (`adr-kit --version`)
+- Python version
+- Steps to reproduce
+- Expected vs actual behaviour