@crossplatformai/skills/skills/post-build-ship/references/database-migration-lifecycle.md

Reusable Agent Skills for CrossPlatform.ai projects.

# Database Migration Lifecycle

This reference is the canonical detailed owner of the Post.Build.Ship database migration handoff.
It applies whenever an active unit changes schema source or depends on generated migration artifacts.
Phase skills keep their mandatory refusal and verification invariants inline and route lifecycle
detail here.

This is a Post.Build.Ship reference contract, not a standalone skill.

## Hard Ownership Boundary

Preparatory schema-source work remains Tier 3 under `risk-tiers.md` even though migration generation
and application are user-owned. Build may implement and Ship may commit schema source plus directly
related application or test changes approved for that preparatory unit.

Agents never:

- run `db:generate`, `db:migrate`, or `db:push`;
- create, edit, stage, or commit generated migration artifacts, including the illustrative
  `apps/api/drizzle/migrations/**` output path or an equivalent repository-specific directory; or
- claim that preparatory source evidence proves migration-backed behavior.

This boundary applies under every approval state. Approval to implement schema source never transfers migration command or
generated-artifact ownership to an agent.

## Three-Phase Handoff

### 1. Agent Completes The Preparatory Source Unit

Post identifies the schema-source unit as Tier 3 and records the boundary in the packet. Build
implements only the approved schema source and directly related application or test changes. Ship
commits that source unit only after Authorizing User authority, required QA, ownership, drift, and
safety checks pass.

The completion report distinguishes both statuses exactly:

- `source unit complete`
- `migration lifecycle pending and user-owned`

The second status is not partial completion of the source unit. It records that the separate
user-owned phase must finish before any dependent work can resume.

### 2. User Generates, Applies, And Commits Migrations

The preparatory completion report gives the user all repository-specific handoff data:

1. the exact migration-generation command;
2. the exact migration-application command, when application is required;
3. any other declared database command the user must run;
4. every expected generated output path; and
5. whether the user must run an application command, with that command named when required or an
   explicit statement that no application command is required.

The user runs the declared commands, inspects the results, and commits the generated artifacts.
Post.Build.Ship execution pauses until the user confirms that generated-artifact commit. Agents do
not continue dependent work based on uncommitted output, working-tree presence, or an assertion that
the commands ran.

### 3. Work Resumes Through A Fresh Candidate

User confirmation of the generated-artifact commit does not reactivate the preparatory candidate.
Any resumed work requires a fresh Post.Build.Ship candidate with:

1. an independently classified risk tier;
2. fresh Authorizing User authority appropriate to that candidate;
3. a fresh admission result under the current packet;
4. new staged-file and whole-index hash evidence;
5. a new candidate identity; and
6. new preliminary and authoritative QA evidence selected for the resumed surface.

Prior authority records, candidate identity, and QA evidence are never reusable
across the user-owned migration boundary. A valid legacy multi-unit handoff pauses at the same point;
its later unit does not bypass the fresh-candidate requirement.

## Planning And Handoff Requirements

For schema work, the frozen candidate and Build-to-Ship handoff record:

- the Tier-3 preparatory source scope and directly related application or test scope;
- the exact prohibition on agent-run migration commands and agent-mutated generated artifacts;
- the expected repository-specific output paths;
- the exact commands reserved for the user;
- whether a user-run application command is required;
- the two completion statuses;
- the pause pending confirmation of the user's generated-artifact commit; and
- the fresh-candidate, new-authority, new-identity, and new-evidence requirements for resumption.

An explicit no-schema statement satisfies the migration field when the active unit does not touch
schema source and does not depend on generated migration artifacts.

## Intentionally Absent-Migration QA Exception

At the pending user boundary only, a Tier-3 database-backed QA failure may be recorded under the
intentionally absent-migration exception when the failure is caused solely by migrations remaining
ungenerated or unapplied. The receipt identifies the exact failing command and explains why the
pending user-owned migration is its sole cause.

The exception:

- is not proof of migration-backed behavior;
- never excuses a schema-source, type, build, or other non-database-backed failure;
- never permits an agent to generate or apply migrations to make QA pass;
- does not turn a failed command into a passing receipt; and
- is unavailable once generated migration artifacts exist.

Any failure with another plausible cause remains blocking. Migration-backed acceptance criteria
remain unproven until a fresh post-boundary candidate supplies new evidence after the user's commit.