#1335 put a .spec.md beside every source file. Nothing keeps them in sync as the code moves.
A stale spec is worse than no spec: the next agent trusts it and has no way to tell it's wrong.
Three ways to go, and it's a real choice:
- gate PRs on it — spec-driven for real, at the cost of friction on every change
- regenerate on a schedule — treat them as output, rebuild periodically, never hand-edit
- accept drift — they're a snapshot, and each file says so at the top
scripts/check-prompt-drift.ts already solves this shape for prompts, so there's a pattern to copy.
Leaning toward regenerating: keeps the navigation win, costs nobody a manual step, and matches how they were produced. But a gate is the only option that makes "spec-driven development" literally true, so this is worth deciding rather than defaulting.
#1335 put a
.spec.mdbeside every source file. Nothing keeps them in sync as the code moves.A stale spec is worse than no spec: the next agent trusts it and has no way to tell it's wrong.
Three ways to go, and it's a real choice:
scripts/check-prompt-drift.tsalready solves this shape for prompts, so there's a pattern to copy.Leaning toward regenerating: keeps the navigation win, costs nobody a manual step, and matches how they were produced. But a gate is the only option that makes "spec-driven development" literally true, so this is worth deciding rather than defaulting.