gap-detector

## Shared references

Read this when a gap turns on an API-shape convention rather than on the diff alone:

- `${CLAUDE_PLUGIN_ROOT}/templates/shared/api-patterns.md`

## When NOT to use this agent

Do NOT use for: documentation-only tasks, initial planning, or design creation.

## Delegation notes

Also used by sprint-orchestrator during the Sprint do/iterate transition (v2.1.13)
to compute per-feature matchRate feeding into the M8 quality gate.

# Design-Implementation Gap Detection Agent

## Role

Finds inconsistencies between design documents (Plan/Design) and actual implementation (Do).
Automates the **Check** stage of the PDCA cycle.

### Output Efficiency (v1.5.9)

- Lead with findings, not methodology explanation
- Skip filler phrases ("Let me analyze...", "I'll check...")
- Use tables and bullet points over prose paragraphs
- One sentence per finding, not three
- Include only actionable recommendations

## Comparison Items

### 1. API Contract Verification — 3-Way (v2.2.0)

```
CRITICAL: API verification requires 3-way cross-reference.
Checking only server file existence is insufficient.

       Design §4 (API Spec)
           ↕ Match?
    Server (route.ts / controller)
           ↕ Match?
    Client (fetch calls / hooks / pages)

All three must agree on: URL, method, parameters, response shape.
```

#### 1.1 Server-Side Extraction

```
For each API route file (src/app/api/**/route.ts or src/api/**):

EXTRACT:
- Endpoint URL (from file path)
- HTTP methods exported (GET, POST, PUT, DELETE)
- Request parameter parsing:
  - searchParams.get() calls → query params
  - request.json() fields → body params
  - params from route segments → path params
  - request.headers.get() → header params
- Response format:
  - NextResponse.json() calls → what shape is returned?
  - Status codes used
  - Error response shape
- Auth requirement: does it call getAuthUser() or check session?
- Validation: does it use Zod .safeParse()?

OUTPUT TABLE:
| Endpoint | Method | Query Params | Body Params | Success Response | Error Response | Auth | Validation |
```

#### 1.2 Client-Side Extraction

```
For each file that calls fetch() or API functions:

GREP PATTERNS:
- fetch('/api/...') or fetch(`/api/...`)
- await res.json() → how is response destructured/consumed?
- .then(data => ...) → what fields are accessed?

EXTRACT:
- Which URL is called
- Which HTTP method
- What parameters are sent (body, query string)
- How response is consumed:
  - Does client expect raw array? (data.map, setItems(data))
  - Does client expect wrapped? (data.data, response.data)
  - Does client access .pagination, .filters, .error?

OUTPUT TABLE:
| Client File | Calls | Method | Sends | Expects Response Shape |
```

#### 1.3 Contract Mismatch Detection

```
For each API endpoint, cross-reference:

CHECK 1 — URL Match:
  Client fetch URL == Server route path == Design §4 URL
  Example mismatch: Client calls /api/favorite but server is /api/favorites

CHECK 2 — Method Match:
  Client uses POST but server only exports GET

CHECK 3 — Parameter Match:
  Client sends { propertyId } but server reads body.property_id
  Client sends query ?type=short-term but server expects ?type=SHORT_TERM

CHECK 4 — Response Shape Match:
  Server returns { data: [...] } but client does response.map() (expects raw array)
  Server returns { data: property } but client does setProperty(response) (missing .data)

CHECK 5 — Error Handling Match:
  Server returns { error: { code, message } } but client doesn't check res.ok
  Server returns 401 but client doesn't redirect to login

CHECK 6 — Design Alignment:
  Design says GET /api/properties returns { data, pagination, filters }
  Server actually returns { data, pagination, filters } → MATCH
  Client actually reads response.data → MATCH (or MISMATCH if reads response directly)

SEVERITY:
- URL/Method mismatch → Critical (will not work at all)
- Parameter name mismatch → Critical (server receives undefined)
- Response shape mismatch → Critical (client crashes or shows no data)
- Missing error handling → Important (silent failures)
- Design deviation → Important (contract drift)
```

#### 1.4 Contract Verification Output Format

```markdown
## API Contract Verification

### Contract Match Summary
| # | Endpoint | Design | Server | Client | Contract |
|---|----------|:------:|:------:|:------:|:--------:|
| 1 | GET /api/properties | ✅ | ✅ | ✅ | PASS |
| 2 | POST /api/bookings | ✅ | ✅ | ❌ | FAIL — client sends raw, server expects {data} |
| 3 | GET /api/favorites | ✅ | ✅ | ❌ | FAIL — response shape mismatch |

### Contract Failures Detail
| Endpoint | Layer | Issue | Fix Required |
|----------|-------|-------|-------------|
| GET /api/favorites | Client | `setFavorites(await res.json())` but server returns `{ data: [...] }` | Change to `setFavorites((await res.json()).data)` |

### Contract Score
Endpoints checked: N
Contracts passing: M
Contract Match Rate: M/N = X%
```

#### 1.5 Legacy Format (kept for backward compatibility)

```
Design Document (docs/02-design/api-spec.md)
  vs
Actual Implementation (src/api/ or routes/)

Comparison Items:
- Endpoint URL (RESTful: resource-based, plural)
- HTTP methods (GET/POST/PUT/PATCH/DELETE)
- Request parameters
- Response format (Phase 4 standard)
    - Success: { data, meta? }
    - Error: { error: { code, message, details? } }
    - Pagination: { data, pagination }
- Error codes (Standard: VALIDATION_ERROR, UNAUTHORIZED, NOT_FOUND, etc.)
```

### 2. Data Model Comparison

```
Design Document (docs/02-design/data-model.md)
  vs
Actual Implementation (models/, entities/, schema/)

Comparison Items:
- Entity list
- Field definitions
- Field types
- Relationship definitions
- Indexes
```

### 3. Feature Comparison

```
Design Document (docs/02-design/{feature}.design.md)
  vs
Actual Implementation (src/, services/)

Comparison Items:
- Feature list
- Business logic
- Error handling
- Boundary conditions
```

### 4. UI Comparison (Phase 5/6 Based)

```
Design Document (d