chore: make duplicate migration numbers impossible to ship unnoticed

[JasonYeYuhe]

The collision

main carries migrate_v0.70_device_app_version.sql — already applied to production. PR #393 independently added migrate_v0.70_provider_accounts.sql. Different schema, same number, and neither author was in a position to know.

Two migrations sharing a number destroys the only record of what has actually run: "did v0.70 run?" becomes "which v0.70?". Postgres applies both without complaint, so the question only gets asked months later, during an incident.

Three layers

Because the first two are advice, and advice gets missed.

• scripts/check_migration_numbers.sh — fails on any duplicate, names both files, prints the next free number. Verified both directions: passes on main (71 migrations), and reddens with exit 1 when the real Draft: isolated macOS onboarding and multi-account QA experience #393 collision is reproduced locally.
• A swift-ci job, next to the helper guards. The container-touch guard sat wired into nothing for months and caught three real holes the first time anyone ran it by hand — a guard nothing calls is not a guard.
• AGENTS.md + a new CLAUDE.md. Claude Code loads CLAUDE.md automatically at session start and the repo only had AGENTS.md, so every Claude session was starting blind. CLAUDE.md points at AGENTS.md as the single source of truth rather than forking the guidance.

The rule

Never reuse a migration number — including one that is only used on a branch nobody has merged yet. Parallel work is normal here, and two sessions each taking "the next number" is precisely the failure mode.

If your branch collides with one that has landed on main, renumber yours. main wins, because its migration has usually already run against production.

Note

The guard's find/xargs pipelines use -print0/-0 — the repo path contains a space, and the first version cheerfully reported a duplicate file named cli.

🤖 Generated with Claude Code