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 at colocated paths:

• SPEC.md (root, apps// , packages// , src/lib/*/ )

• Supporting files linked from a SPEC.md TOC (e.g., commands.spec.md )

• Legacy patterns as fallback: *.spec.md , -spec.md , 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:

Spec Section Source File(s) Status

Types

src/types.ts:10-40

aligned / drifted / missing-impl / missing-spec

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 ). Batch related discrepancies that share a root cause.

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)