docs: add missing ADRs and update existing ones (#321)

* chore: rename build

* docs: add missing ADRs and update existing ones

Documents architectural decisions previously undocumented in the codebase.

**New ADRs:**
- ADR-0020: Testing Framework (Vitest + property-based testing)
- ADR-0021: Code Quality Toolchain (ESLint, Prettier, TypeScript)
- ADR-0022: Package Manager Choice (pnpm)
- ADR-0023: Release Management with Changesets
- ADR-0024: CI/CD Platform (GitHub Actions)
- ADR-0025: Container and Security Scanning (Trivy, SLSA, SBOM)
- ADR-0026: Circuit Breaker Pattern (opossum)
- ADR-0027: Docker Publishing Strategy (GHCR to Docker Hub)
- ADR-0028: Session-Based HTTP Transport with SSE

**Updated ADRs:**
- ADR-0011: Docker implementation (multi-platform, GHCR, security)
- ADR-0016: Marked as superseded by ADR-0019
- ADR-0018: Circuit breaker cross-references
- ADR-0019: Marked as partially superseded by ADR-0028

ADR-0028 documents the session-based HTTP transport added after
ADR-0019 removed OAuth HTTP. Uses session management instead of OAuth
and delegates authentication to external gateways.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add key architectural decisions to CLAUDE.md

Summarizes key decisions from ADRs for quick reference:
- Testing: Vitest + fast-check (80% coverage)
- Code quality: TypeScript strict, ESLint, Prettier
- Package manager: pnpm with version consistency
- Release: Changesets workflow
- CI/CD: GitHub Actions (7 workflows)
- Security: Multi-layered (Trivy, CodeQL, SLSA, SBOM)
- Resilience: Circuit breaker (opossum)
- Docker: Multi-platform, GHCR→Docker Hub
- Transport: stdio (default) + HTTP (optional)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: add empty changeset for documentation updates

Documentation-only changes do not require a version bump.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sapientpants

.changeset/legal-mice-hope.md

@@ -0,0 +1,4 @@
+---
+---
+
+Documentation-only changes: Added 9 new ADRs (0020-0028) documenting previously undocumented architectural decisions (testing, code quality, package management, release management, CI/CD, security scanning, circuit breakers, Docker publishing, HTTP transport). Updated 4 existing ADRs (0011, 0016, 0018, 0019) with current implementation details and supersession relationships. Enhanced CLAUDE.md with key architectural decisions summary.

.github/workflows/main.yml

@@ -60,8 +60,6 @@ jobs:
   # =============================================================================
 
   build:
-    name: Build TypeScript
-
     runs-on: ubuntu-latest
     outputs:
       artifact-name: dist-${{ github.sha }}

CLAUDE.md

@@ -21,6 +21,63 @@ All architectural decisions are documented in Architecture Decision Records (ADR
 
 Refer to the ADRs for detailed information about design rationale, implementation details, and consequences of each architectural decision.
 
+## Key Architectural Decisions
+
+**Testing** (ADR-0020):
+
+- Vitest as test framework with native ES modules support
+- fast-check for property-based testing
+- 80% minimum coverage required (lines, functions, branches, statements)
+
+**Code Quality** (ADR-0021):
+
+- TypeScript strict mode enabled (all strict flags)
+- ESLint flat config with cognitive complexity limit (15)
+- Prettier for consistent formatting
+- Husky + lint-staged for pre-commit automation
+
+**Package Manager** (ADR-0022):
+
+- pnpm for disk efficiency and strict dependency management
+- Version MUST match across: package.json, Dockerfile, all workflows
+- Uses Corepack for automatic version management
+
+**Release Management** (ADR-0023):
+
+- Changesets for versioning and changelog generation
+- Changeset validation enforced in CI/CD
+- Automated GitHub releases via workflows
+
+**CI/CD** (ADR-0024):
+
+- GitHub Actions with 7 workflows (main, PR, publish, 4 reusable)
+- Parallel execution for validation, security, build
+- Quality gates block merge on failures
+
+**Security** (ADR-0025):
+
+- Multi-layered: Trivy (containers), CodeQL (SAST), OSV-Scanner (deps), SonarCloud
+- SLSA provenance attestations on all artifacts
+- SBOM (CycloneDX) generated for Docker images
+
+**Resilience** (ADR-0026):
+
+- Circuit breaker pattern via opossum library
+- Default: 50% error threshold, 10s timeout, 30s reset
+- Integrated with metrics/monitoring system
+
+**Docker Publishing** (ADR-0027):
+
+- Multi-platform: linux/amd64, linux/arm64
+- Two-stage: build→GHCR (with security scan), copy→Docker Hub
+- Build-once-deploy-many strategy
+
+**Transport** (ADR-0010, ADR-0028):
+
+- stdio: Default transport (recommended)
+- HTTP: Optional session-based transport with SSE
+- HTTP uses session management (not OAuth), delegates auth to gateways
+
 ## Code Quality Conventions
 
 Follow these conventions to maintain code quality:

docs/architecture/decisions/0011-docker-containerization-for-deployment.md

@@ -1,6 +1,7 @@
 # 11. Docker containerization for deployment
 
 Date: 2025-06-13
+Updated: 2025-10-11 (Added multi-platform, GHCR, security scanning)
 
 ## Status
 
@@ -15,22 +16,76 @@ The SonarQube MCP server needs to be easily deployable across different environm
 - Simplifies the deployment process for non-technical users
 - Supports various MCP transport mechanisms (stdio, SSE)
 - Enables easy updates and version management
+- Works on multiple CPU architectures (Intel/AMD x64, Apple Silicon ARM64)
+- Provides security guarantees through vulnerability scanning
 
 ## Decision
 
-We will provide Docker containerization as a recommended deployment option for the SonarQube MCP server. This includes:
+We will provide Docker containerization as the recommended deployment option for the SonarQube MCP server. This includes:
 
 - Maintaining a Dockerfile in the repository that packages the server with all dependencies
-- Publishing Docker images to Docker Hub (e.g., sapientpants/sonarqube-mcp-server)
+- Publishing Docker images to both GitHub Container Registry (GHCR) and Docker Hub
 - Documenting Docker usage in the README as a primary deployment method
-- Supporting both stdio and SSE transports within the containerized environment
+- Supporting stdio transport within the containerized environment (SSE removed as of ADR-0019)
 
-The Dockerfile will:
+### Modern Implementation (as of 2025-10-11)
 
-- Use an appropriate Node.js base image
-- Install all npm dependencies
-- Copy the built server code
-- Set appropriate entry points for MCP server operation
+The Docker implementation has evolved significantly beyond the initial decision:
+
+#### Multi-Platform Support
+
+- **Platforms**: Builds for both `linux/amd64` and `linux/arm64`
+- **Tooling**: Uses Docker Buildx with QEMU emulation for ARM64 builds
+- **Distribution**: Multi-platform manifest lists allow Docker to automatically select the correct architecture
+- **References**: See ADR-0027 for publishing strategy details
+
+#### Two-Registry Strategy
+
+1. **GitHub Container Registry (GHCR)** - Primary build target:
+   - Built and pushed in main workflow
+   - Security scanned before any public distribution
+   - Used as intermediate registry for Docker Hub
+   - Registry: `ghcr.io/sapientpants/sonarqube-mcp-server`
+
+2. **Docker Hub** - Public distribution:
+   - Images copied from GHCR in publish workflow
+   - Better discoverability for end users
+   - Registry: `sapientpants/sonarqube-mcp-server`
+   - References\*\*: See ADR-0027 (Docker Image Publishing Strategy)
+
+#### Security Scanning
+
+- **Tool**: Trivy vulnerability scanner
+- **Severity**: Blocks on HIGH and CRITICAL vulnerabilities
+- **Integration**: Automatic in CI/CD pipeline before publishing
+- **SARIF Upload**: Results uploaded to GitHub Security tab
+- **References**: See ADR-0025 (Container and Security Scanning Strategy)
+
+#### Supply Chain Security
+
+- **SLSA Provenance**: Build attestations attached to all images
+- **SBOM**: Software Bill of Materials (CycloneDX format) generated and attached
+- **Verification**: Users can verify image provenance using GitHub attestation API
+
+#### Base Image and Configuration
+
+The Dockerfile:
+
+- Uses `node:22-alpine` as base image for minimal size
+- Installs pnpm@10.17.0 for dependency management
+- Multi-stage build for optimal layer caching
+- Non-root user (`node`) for security
+- Proper signal handling for graceful shutdown
+- Health check endpoint for container orchestration
+
+#### Tagging Strategy
+
+Each release creates four tags:
+
+- Full semantic version: `1.10.18`
+- Major.minor version: `1.10`
+- Major version: `1`
+- Latest: `latest`
 
 ## Consequences
 
@@ -41,16 +96,36 @@ The Dockerfile will:
 - **Version consistency**: Specific server versions can be deployed using Docker tags
 - **Cross-platform compatibility**: Works identically on Linux, macOS, and Windows with Docker
 - **Easy updates**: Users can update by pulling new image versions
-- **Transport flexibility**: Both stdio and SSE transports work within containers
+- **Multi-Architecture**: Native support for both Intel/AMD and ARM64 (Apple Silicon, AWS Graviton)
+- **Security First**: Images are scanned for vulnerabilities before distribution
+- **Supply Chain Security**: SLSA provenance and SBOM provide transparency
+- **Dual Registry**: GHCR for GitHub users, Docker Hub for broader community
+- **Efficient Publishing**: Build once, copy to Docker Hub (no rebuild required)
 
 ### Negative
 
-- **Additional maintenance**: Requires maintaining Dockerfile and Docker Hub releases
+- **Additional maintenance**: Requires maintaining Dockerfile and multi-registry releases
 - **Image size**: Docker images are larger than source distributions (includes Node.js runtime)
+  - Current size: ~150MB compressed (Alpine-based)
 - **Docker requirement**: Users must have Docker installed and running
 - **Resource overhead**: Containers have slight performance overhead compared to native execution
+- **Multi-Platform Build Time**: ARM64 emulation adds 2-3 minutes to build time
+- **Registry Costs**: Potential GHCR storage costs (minimal for public repos)
+- **Two Registry Sync**: Need to maintain consistency between GHCR and Docker Hub
 
 ### Neutral
 
-- Docker deployment becomes the recommended approach but not mandatory - users can still install from source
-- Need to ensure Docker image tags align with npm package versions for consistency
+- Docker deployment is the recommended approach but not mandatory - users can still install from source
+- Docker image tags align with npm package versions for consistency
+- Multi-platform manifest lists handled transparently by Docker (users don't need to specify platform)
+- GHCR acts as intermediate storage (invisible to most users)
+
+## References
+
+- Dockerfile: `Dockerfile` (in repository root)
+- ADR-0019: Simplify to stdio-only transport (removed SSE support)
+- ADR-0024: CI/CD Platform - GitHub Actions (workflow automation)
+- ADR-0025: Container and Security Scanning Strategy (Trivy, SLSA, SBOM)
+- ADR-0027: Docker Image Publishing Strategy - GHCR to Docker Hub (two-registry approach)
+- GitHub Container Registry: https://ghcr.io/sapientpants/sonarqube-mcp-server
+- Docker Hub: https://hub.docker.com/r/sapientpants/sonarqube-mcp-server

docs/architecture/decisions/0016-http-transport-with-oauth-2-0-metadata-endpoints.md

@@ -1,10 +1,23 @@
 # 16. HTTP Transport with OAuth 2.0 Metadata Endpoints
 
 Date: 2025-06-22
+Superseded: 2025-01-30 by ADR-0019
 
 ## Status
 
-Accepted
+Superseded by ADR-0019
+
+This decision was reversed on 2025-01-30. The HTTP transport and OAuth 2.0 implementation was removed in favor of stdio-only transport with enterprise features delegated to MCP gateways (Docker MCP Gateway, IBM Context Forge, SGNL, Operant, etc.).
+
+**Rationale for reversal:**
+
+- HTTP transport added significant complexity (~60+ authentication/authorization files)
+- MCP gateway solutions now provide these enterprise features at the infrastructure layer
+- Better separation of concerns: business logic vs infrastructure concerns
+- Reduced attack surface and maintenance burden
+- Aligns with Unix philosophy of "do one thing well"
+
+See ADR-0019 for the current stdio-only transport approach.
 
 ## Context
 
@@ -97,3 +110,10 @@ class HttpTransport implements ITransport {
 - ADR-0015: Transport Architecture Refactoring
 - ADR-0014: Current Security Model and Future OAuth2 Considerations
 - ADR-0008: Use Environment Variables for Configuration
+- **ADR-0019: Simplify to stdio-only transport (SUPERSEDES THIS ADR)**
+
+## Historical Note
+
+This ADR documents the HTTP transport implementation that was later removed. The decision to implement HTTP transport with OAuth 2.0 was sound at the time (June 2025), but the rapid evolution of the MCP ecosystem with purpose-built gateway solutions made this approach redundant. The code and infrastructure described in this ADR were removed in January 2025 as part of a significant simplification effort that reduced the codebase by ~40%.
+
+This ADR is retained for historical context and to document the architectural exploration that led to the current stdio-only approach.

docs/architecture/decisions/0018-add-comprehensive-monitoring-and-observability.md

@@ -1,6 +1,7 @@
 # 18. Add comprehensive monitoring and observability
 
 Date: 2025-01-25
+Updated: 2025-10-11 (Added circuit breaker details and cross-references)
 
 ## Status
 
@@ -70,7 +71,23 @@ We will implement a comprehensive monitoring and observability stack with the fo
 
 ### 5. Operational Features
 
-- Circuit breakers using `opossum` library
+- **Circuit breakers** using `opossum` library
+  - Implemented via `CircuitBreakerFactory` pattern (see ADR-0026)
+  - Default thresholds: 50% error rate, 10-second timeout, 30-second reset
+  - Event-driven monitoring integration:
+    - `open` event: Circuit opened due to failures → metrics updated
+    - `close` event: Circuit recovered → metrics updated
+    - `halfOpen` event: Testing recovery → logged for observability
+    - `failure` event: Request failed → failure counter incremented
+    - `timeout` event: Request timed out → timeout metrics tracked
+    - `reject` event: Request rejected (circuit open) → rejection counter incremented
+  - Metrics tracked:
+    - Circuit breaker state (open/closed/half-open)
+    - Failure count per breaker
+    - Rejection count per breaker
+    - Success/failure ratio
+    - Request latency percentiles
+  - See ADR-0026 for complete circuit breaker documentation
 - Connection pooling with `undici` or `got`
 - Graceful degradation when dependencies fail
 - Request rate limiting enhancements
@@ -103,6 +120,8 @@ We will implement a comprehensive monitoring and observability stack with the fo
 - **Troubleshooting**: Quickly diagnose issues with distributed tracing
 - **Compliance**: Meet enterprise SLA requirements
 - **Integration**: Works with existing monitoring infrastructure
+- **Resilience**: Circuit breakers prevent cascading failures and provide fail-fast behavior
+- **Observability**: Circuit breaker events integrated with metrics for real-time failure detection
 
 ### Negative
 
@@ -143,3 +162,6 @@ We will implement a comprehensive monitoring and observability stack with the fo
 - [OpenTelemetry Node.js](https://opentelemetry.io/docs/instrumentation/js/)
 - [The RED Method](https://www.weave.works/blog/the-red-method-key-metrics-for-microservices-architecture/)
 - [Circuit Breaker Pattern](https://martinfowler.com/bliki/CircuitBreaker.html)
+- ADR-0026: Circuit Breaker Pattern with opossum (complete implementation details)
+- Implementation: `src/monitoring/circuit-breaker.ts`
+- Metrics Implementation: `src/monitoring/metrics.ts`

docs/architecture/decisions/0019-simplify-to-stdio-only-transport-for-mcp-gateway-deployment.md

@@ -1,10 +1,28 @@
 # 19. Simplify to stdio-only transport for MCP gateway deployment
 
 Date: 2025-01-30
+Partially Superseded: 2025-10-12 by ADR-0028
 
 ## Status
 
-Accepted
+Partially Superseded by ADR-0028
+
+This decision was partially reversed on 2025-10-12. While the removal of OAuth-based HTTP transport and authentication complexity remains valid, the "stdio-only" decision was superseded by ADR-0028, which re-introduced HTTP transport in a simpler, session-based form without OAuth complexity.
+
+**What remains valid from this ADR:**
+
+- Removal of OAuth 2.0 authentication infrastructure (60+ files)
+- Removal of service account management and permission filtering
+- Delegation of enterprise features to MCP gateways
+- Simplified authentication model
+
+**What was superseded:**
+
+- "stdio-only" transport decision (HTTP transport re-added in ADR-0028)
+- Removal of all HTTP endpoints (HTTP re-added with session management)
+- Removal of SSE (SSE re-added for real-time notifications)
+
+See ADR-0028 for the current HTTP transport implementation (session-based without OAuth).
 
 ## Context
 
@@ -91,4 +109,5 @@ Users currently using HTTP transport should:
 - GitHub Issue #243: Simplify to stdio-only transport
 - ADR-0010: Use stdio transport for MCP communication
 - ADR-0016: HTTP transport with OAuth 2.0 (being reverted)
+- **ADR-0028: Session-Based HTTP Transport with SSE (PARTIALLY SUPERSEDES THIS ADR)**
 - MCP Specification: Transport layer abstraction