new-migration

# New Schema Migration The general flow (worktree, TDD, lint) is in CLAUDE.md and `/tdd`. The schema-migration mechanics are visible in `storage.py` — the `_CURRENT_VERSION` constant and `_MIGRATIONS` dict show every prior migration as a worked example. This skill captures only the migration-specific gotchas: - **Bump `_CURRENT_VERSION` in `storage.py` by exactly 1** — never skip numbers, never reuse one. Version collisions across concurrent agent worktrees are the main reason CLAUDE.md mandates worktree isolation; check the diff at PR time to confirm no other agent shipped the same number while you were branched. - **Migrations must be idempotent.** Use `CREATE TABLE IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS`. SQLite's `ALTER TABLE` is add-column-only — no drops, no renames. Plan accordingly. - **One migration per logical schema change.** Don't bundle unrelated table creations into one version — it makes rollback reasoning and the `RELEASES.md` entry harder. - **Update CLAUDE.md's Stack table** with the new schema version when the migration ships (per `/pr-checklist`). - **Use the `storage` fixture** for tests — it runs all migrations on an in-memory database, so a TDD red-step will fail with "no such table" until the migration lands. That's the intended signal.