Spec-to-reality sync: reconcile plan artifacts after implementation

[diegoserranobst]

Problem

When using shape-spec to plan work, the resulting artifacts (plan.md, shape.md, references.md) capture the intended implementation. But during actual coding, things change:

• You discover edge cases the plan didn't anticipate
• A planned approach doesn't work and you pivot
• You add logic that wasn't in scope (e.g., server-side IVA calculation that the plan assumed frontend would handle)
• An API doesn't support a feature you planned to use (e.g., a decorator not accepting deprecated: true)

After implementation, the spec artifacts are stale — they describe what you planned, not what you built. Anyone reading the spec later (including future-you or an AI agent) gets a misleading picture.

Idea

A /sync-spec command that reconciles spec artifacts with the actual implementation:

1. Reads the spec artifacts (plan.md, shape.md)
2. Inspects the real code changes (via git diff + file reads)
3. Compares plan vs reality per task
4. Classifies divergences: additions (new undocumented logic), changes (different from plan), omissions (planned but skipped), extra files (not in plan)
5. Presents divergences to the user for confirmation
6. Updates artifacts — adds "Implementation notes" to tasks in plan.md, "Implementation decisions" to shape.md

The key insight: this is an agent-driven diff, not a mechanical merge. The agent reads code, understands why something diverged, and writes human-readable notes about it.

Example output in plan.md

### Task 3: Backend — Route invoices in emitWithMode()

[original description preserved]

#### Implementation notes

- **Addition:** Server-side totals calculation — the plan assumed net prices, 
  but this document type uses tax-inclusive pricing. Implemented reverse 
  calculation: total → net → tax.
- **Addition:** Emission mode resolved from tenant config when not explicit 
  in request.

Why it matters

Specs become living documentation that stays accurate post-implementation. Future agents (or humans) reading the spec get the real story, not the original guess.