Update claude db migration skill reference with additional constraints

[iplay88keys]

What

Expands the migrations guide in the kagent-dev skill reference (.claude/skills/kagent-dev/references/database-migrations.md) to document the migration safety constraints.

Changes

New sections:

• One Linear History — migrations are immutable from merge (not release); sequence numbers are claimed at merge and a draft on a feature branch renumbers if main moved; a backward-compatible migration may ship in the same PR as its code.
• Rollback and ahead-schema tolerance — failure-rollback vs. version-rollback; the runner tolerates a database ahead of it; an in-window version rollback runs no down files; the server does no startup version arithmetic.
• Upgrade and rollback testing — previous-minor round-trip and query-level backward-compatibility tests.
• Schema-agnostic SQL — migrations must not name a schema; the connection selects it.

Reworked:

• Backward compatibility and contraction (was "Backward-compatible schema changes") — rule stated by effect rather than DDL shape; expanded compatibility table (new ❌ rows: new constraint on a shipped table, type narrowing, data rewrite); windowed-contraction model with the rollback window defined as one minor back (Major.Minor.Patch − 1 minor); destructive DDL must be declared and reviewed.
• Static Analysis Enforcement — table gains two rows (contraction guard, schema-agnostic lint).
• sqlc Workflow, Down migrations, Downstream Extension Model, Structure — cross-links and short notes tying the above together.

Enforcement status

Gates that do not exist yet are marked Target — not yet enforced: the contraction guard, schema-agnostic lint, previous-minor round-trip and query-level tests, and the release-time patch/prefix checks. They document the intended gates; building them is follow-up work. The checks that exist today (TestNoCrossTrackDDL, TestMigrationGuards, sqlc sync) are unchanged.

[Copilot]

Pull request overview

Updates the kagent-dev database migrations reference to document stricter migration safety constraints (immutability, backward-compatibility window, and rollback/ahead-schema behavior) and to outline current vs. planned enforcement.

Changes:

• Expands the backward-compatibility guidance into a windowed “expand → deploy → contract” model with additional unsafe-change examples.
• Adds new guidance on linear migration history, ahead-schema tolerance, schema-agnostic SQL, and upgrade/rollback testing expectations.
• Extends the static-analysis enforcement section with additional (target) gates.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mesutoezdil]

step 3 says "re-runs the failed up migration" but rollbackToVersion only rolls back and then the process exits with an error. the re-run happens on the next startup, not in the same 1. might be worth correcting since the doc is being expanded anyway.

[mesutoezdil]

1 more thing: it says "the core and vector migrations already comply" but the lint that would enforce this is marked as target/not yet enforced. how was compliance verified?