Code Review

# ADR Gate — Pre-Review Spec Enforcement

Every code review must have architectural context. This gate runs before review engines and ensures changes are linked to ADRs (Architecture Decision Records) and specs.

---

## Gate Protocol

Before any review engine runs, execute this sequence:

```
Changed files detected
      |
      v
[1. Classify change scope]
      |
      v
  Trivial? ──YES──> Skip gate, proceed to review
      |
      NO
      v
[2. Discover linked ADRs + specs]
      |
      v
  Found? ──YES──> Inject into review context
      |
      NO
      v
[3. Reverse-engineer ADR draft]
      |
      v
[4. Present draft to user OR auto-tag as "proposed"]
      |
      v
[5. Proceed to review with ADR context]
```

---

## Step 1: Classify Change Scope

Exempt trivial changes from ADR requirements:

### Trivial (Skip Gate)
- Typo fixes, comment edits, whitespace
- Dependency version bumps (patch/minor)
- Test-only changes that don't alter behavior
- Config value changes (not structural)
- Changelog/README updates

### Detection
```bash
# If ALL changed files match trivial patterns, skip gate
TRIVIAL_PATTERNS="CHANGELOG|README|\.lock$|\.md$|__snapshots__|\.test\.|\.spec\."
```

### Non-Trivial (Gate Applies)
- New files or deleted files
- Changes to API routes, models, schemas
- Security-related files (auth, crypto, permissions)
- Architecture changes (new services, new patterns)
- Database migrations

---

## Step 2: Discover ADRs + Specs

Search in order — stop when context is sufficient:

### 2a. Check `docs/adr/` directory
```bash
# List existing ADRs
ls docs/adr/*.md 2>/dev/null

# Search ADR content for references to changed files/modules
grep -rl "module_name\|feature_name" docs/adr/ 2>/dev/null
```

### 2b. Query iCPG (if indexed)
```
search_graph(name_pattern="*", label="ReasonNode")
```
Match ReasonNodes to changed file paths. If iCPG is not available, skip — this step is optional.

### 2c. Check `_project_specs/`
```bash
# Search specs for references to the changed area
grep -rl "feature_name\|module_name" _project_specs/ 2>/dev/null
```

### 2d. Check git history for decision context
```bash
# Get commit messages that explain WHY for changed files
git log --oneline -10 -- <changed_files>
git log --grep="decision\|chose\|instead of\|trade-off" -5
```

### 2e. Check issue tracker references
```bash
# Look for ticket references in recent commits
git log --oneline -20 | grep -oE "(#[0-9]+|[A-Z]+-[0-9]+)"

# Check PR description if in PR context
gh pr view --json body -q .body 2>/dev/null
```

### Discovery Output
Produce an ADR context block:

```markdown
## ADR Context for Review

### Linked ADRs
- ADR-0003: Use Zustand for state management (accepted)
- ADR-0007: Atomic file writes for editor (accepted)

### Linked Specs
- _project_specs/phase-08-editor.md
- GitHub Issue #25: In-browser file editor

### Relevant Decisions (from git history)
- "Chose atomic write via temp+rename over direct write" (commit abc123)

### Coverage
- 3/5 changed files have ADR linkage
- 2 files have no documented decision context
```

---

## Step 3: Reverse-Engineer ADR Draft

When ADRs are missing for non-trivial changes, draft one:

### Input Sources
1. `git log --follow -5 <file>` — commit messages for intent
2. `git diff` — what actually changed
3. File content — module structure, imports, patterns
4. PR description (if available)

### Draft Template
```markdown
# NNNN - [Auto-generated title from change description]

**Status:** proposed
**Date:** [today]
**Spec:** [discovered spec or "none — needs linking"]
**Deciders:** [git author]

## Context
[Extracted from commit messages and PR description]

## Decision
[Inferred from the code changes — what pattern/library/approach was chosen]

## Consequences
[Inferred trade-