---
name: check
description: >
  Read-only drift detector comparing SPEC.md against current codebase.
  Audits invariants (§V), interface shapes (§I), and task completion (§T), reporting violations with file:line citations.
  Use when asked to "check drift", "audit spec", "spec vs code", or before releasing.
concerns: [system-one-balance]
---

# Check — Drift Detector

Pure diagnostic audit. Reports violations and interface drift. Strictly read-only; writes nothing.

Spec drifting silently from code is the primary failure mode of long-lived projects. `check` catches drift before it becomes production defects.

---

## Phase 0: Setup and Protocols

1. **Non-Negotiable Invariants**:
   - **Zero Writes**: Never edit code or `SPEC.md`. Report findings only.
   - Every violation must cite `file:line` evidence.
   - If `SPEC.md` is absent at repo root, report "no spec found" and exit.

---

## Phase 1: Ingest and Check

1. Ingest `SPEC.md` from the project root.
2. Parse audit scope from arguments:
   - `§V`: Audit invariants only (default).
   - `§I`: Audit external interfaces only.
   - `§T`: Audit task status against reality.
   - `--all` (or empty): Audit all three sections.

---

## Phase 2: Processing (Core Logic)

### Step 1: Audit Invariants (§V)
For each `V<n>` invariant:
1. Translate invariant into a verifiable assertion about code.
2. Search and inspect corresponding files.
3. Classify state:
   - **HOLD**: Invariant actively satisfied with test or code assertion.
   - **VIOLATE**: Invariant actively violated in implementation.
   - **UNVERIFIABLE**: Invariant has no corresponding automated test or code guard.

### Step 2: Audit Interfaces (§I)
For each interface defined in §I:
1. Locate implementation in routes, CLI, or exported functions.
2. Classify state:
   - **MATCH**: Code shape matches §I specification exactly.
   - **DRIFT**: Implementation exists but signatures, parameters, or return types diverge.
   - **MISSING**: Interface declared in spec but absent from code.
   - **EXTRA**: Code exposes public endpoints/flags not documented in §I.

### Step 3: Audit Tasks (§T)
For each `T<n>` row:
1. If status is `x`: verify claimed files/tests exist in git. If absent, flag **STALE**.
2. If status is `~`: note as in-progress.
3. If status is `.`: note as pending.

---

## Phase 3: The System One Balance Pass

- **Augment, Don't Handcuff**:
  - Report findings concisely without lecturing or auto-triggering refactors.
  - Provide actionable remedy hints for each class of drift, leaving decisions to the user.

---

## Phase 4: Output Execution & Verification

Emit the structured Caveman drift report:

```markdown
## Drift Report

### §V Invariants
- V2 VIOLATE: src/auth/mw.ts:47 uses `<` instead of `≤`.
- V5 UNVERIFIABLE: no test covers concurrent refund boundary.

### §I Interfaces
- I.api DRIFT: POST /v1/charge returns `{result}` instead of `{id}`. routes/charge.py:82.
- I.cmd MISSING: `limiter bench` absent from CLI definitions.

### §T Tasks
- T3 STALE: marked `x` but auth middleware file not found in tree.

### Summary
- X violations, Y drifts, Z missing, W stale.
- **Remedy Hints**:
  - VIOLATE / DRIFT: Invoke `spec` with `bug: <V.n>` or fix code at cited lines.
  - MISSING: Invoke `build §T.n` or `spec amend §T`.
  - STALE: Invoke `spec amend §T` to reset status.
```