Drift capture
When implementation diverges from specification, the difference is captured as a drift document rather than silently ignoring the gap. This prevents silent spec rot — where specs and code gradually diverge until the specs become unreliable.
Drift lifecycle
| Phase | Who | What happens |
|---|---|---|
| Detection | Agent or engineer | Notices spec says X but implementation does Y |
| Documentation | Detector | Creates .context/drift/drift-{topic}.md |
| Resolution | Human (always) | Decides: update spec, fix code, or accept with rationale |
| Archival | PR author | Moves resolved doc to .context/drift/archive/ |
Drift document format
# Drift: {topic}
**Detected**: 2026-04-07
**Detected by**: Vega (agent) / Vivek (human)
**Severity**: low | medium | high
## Spec says
What the specification describes.
## Implementation does
What actually exists.
## Impact
What breaks or is incorrect because of this drift.
## Recommended resolution
Update spec / fix code / accept drift with rationale.
Common drift patterns
| Pattern | Example | Typical resolution |
|---|---|---|
| Spec optimism | Spec describes Phase 2 feature as if built | Update spec to mark as "planned" |
| Silent evolution | Code was refactored but spec wasn't updated | Update spec to match new code structure |
| Name drift | Spec says TestResult, code says TestRunResult | Align on one name across both |
| Removed feature | Spec describes feature that was cut | Remove from spec, add to "deferred" section |
CI enforcement
When a drift doc is archived, the archival PR must also include:
- Updated spec (if spec was wrong)
- Updated context files (if architecture changed)
- Updated docs (if docs/ content needs updating)
warning
Drift docs should not accumulate. If .context/drift/ has more than 5 unresolved documents, prioritize resolution before starting new feature work.
What's next
- Spec-driven development — The planning pipeline
- Context maintenance rules — Keeping docs in sync