architecture-evolution-tracking

# Architecture Evolution Tracking - Quantified Design Alignment

## Purpose

Maintain alignment between code and architectural decisions. Calculate alignment score (0.00-1.00) showing conformance to ADRs. Auto-detect violations like circular dependencies, layer violations, and unauthorized coupling. Track architecture health via Serena MCP.

## When to Use

- Reviewing large architectural changes
- Detecting unauthorized couplings between modules
- Monitoring compliance with ADRs
- Preventing architectural drift
- Planning refactoring work
- Measuring architecture quality evolution

## Core Metrics

**Alignment Score Calculation:**
```
Score = 1.0 - (Violations / Total Dependencies) × 1.0
Range: 0.00 (complete chaos) to 1.00 (perfect alignment)

Violations: Unauthorized dependencies, circular refs, layer violations
Total Dependencies: All module-to-module connections

Example: 5 violations in 200 dependencies = 0.975 score
```

**Violation Types & Impact:**
- Circular dependencies: -0.15 per cycle
- Layer violations: -0.10 per violation
- Unauthorized coupling: -0.05 per edge
- Missing abstraction: -0.05 per case

**Architecture Scoring:**

```
Component: User Authentication Service
├─ Allowed dependencies: Core, Utils
├─ Actual dependencies: Core, Utils, Payment (VIOLATION)
├─ Violations: 1 (unauthorized Payment coupling)
├─ Alignment: 0.90 (1 violation in 10 deps)
└─ Status: ⚠️ Review needed

Component: Payment Processing
├─ Allowed: Core, Database, Logging
├─ Actual: Core → Auth (CIRCULAR), Database, Logging
├─ Violations: 2 (circular + missing abstraction)
├─ Alignment: 0.80
└─ Status: ❌ Critical refactoring needed
```

## Workflow

### Phase 1: ADR Definition
1. **Document decisions**: Create ADRs for major design choices
2. **Define boundaries**: Specify allowed module dependencies
3. **Set rules**: Layer separation, coupling limits
4. **Establish baseline**: Calculate initial alignment

**ADR Format Example:**
```
ADR-001: Layered Architecture

Decision:
Impl