Spec Alignment

Principles (Always Active)

These apply whenever a spec file and its corresponding implementation are both in context:

Spec and Code Must Agree

• A spec describes intended behavior; code implements it. When they disagree, one is wrong.
• Never silently tolerate drift - surface it immediately when noticed.
• The user decides which is the source of truth for each discrepancy. Do not assume.

Drift Categories

• Type drift: spec defines fields/types that don't match the implementation
• Behavior drift: spec describes logic the code doesn't follow
• Missing implementation: spec defines something with no corresponding code
• Missing spec: code implements behavior not described in the spec
• Constraint drift: spec states invariants the code doesn't enforce
• Error handling drift: spec defines error cases the code doesn't handle (or vice versa)

Mutation Policy

• Do not edit spec files unless the user explicitly chooses "update spec" for a discrepancy.
• Do not change implementation logic unless the user explicitly chooses "update code".
• When updating code, run lint/typecheck after changes.
• When updating spec, preserve formatting and structure of unrelated sections.

Bidirectional Awareness

When reading code, check if a spec exists and note divergences. When reading a spec, check if the implementation matches and note divergences. This awareness should be passive - flag drift in your responses without interrupting the user's primary task, unless the drift is directly relevant.

Workflow (When Explicitly Aligning)

Step 1: Locate the Spec

A spec file is required. Search for:

• *.spec.md

  ,

  *-spec.md

  ,

  SPEC.md

• spec/*.md

  ,

  docs/*.spec.md

If multiple specs exist, ask which to align. If none exist, stop - this workflow requires an existing spec.

Read the spec file completely.

Step 2: Map Spec to Code

For each spec section, identify the corresponding implementation:

## Types

src/types.ts:10-40

Read each mapped source file before assessing.

Step 3: Present Discrepancies

For each discrepancy:

### DRIFT-01: <short description>

**Spec says** (spec-file.md:L42):
> <quoted spec text>

**Code does** (src/module.ts:L87):
> <summarized code behavior>

**Impact**: <what breaks or is inconsistent>

Number with stable IDs (

DRIFT-NN

Step 4: User Decision

For each discrepancy, ask:

• Update spec - the code is correct, update the spec to match
• Update code - the spec is correct, update the code to match
• Skip - defer this discrepancy

Step 5: Apply Changes

Spec updates:

• Edit the spec file with corrected text
• Preserve formatting and structure of unrelated sections

Code updates:

• Fix the implementation to match the spec
• Run lint/typecheck after changes
• If non-trivial, outline the change and confirm before editing
• If unit tests exist for the affected code, run them
• If unit tests don't exist and the spec defines testable behavior, flag it

Step 6: Summary

## Spec Alignment: <file>

**Discrepancies found**: N
**Resolved**: X (spec: A, code: B, skipped: C)

### Remaining
- DRIFT-04: <description> (skipped)