docs(migrations): note that verify:cloud's ledger checks are branch-relative (#541)

The two ledger checks compare cloud against the migrations in the CURRENT
checkout, so on a feature branch a migration another in-flight branch has
already applied reads as an orphan, and one on this branch not yet applied
reads as pending. Neither is drift.

Found while confirming #541: PRs #553 (#542) and #554 (#543) had applied
20260726013256, 20260726015858, 20260726100000 and 20260726110000 to cloud,
none of which exist on this branch — so verify:cloud run here reports four
orphans that are not drift at all.

Left as guidance rather than logic. Filtering by "is this stamp on some other
branch" would need a remote ref walk and would silently excuse the exact
condition the check exists to catch. The orphan detail line now names the
possibility and says to re-check on master; the payment-invariant checks are
branch-independent and meaningful anywhere.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HPFyHjqzSR6Ku1gyWjeQie

Author: guillermoscript

docs/MIGRATIONS.md

@@ -81,6 +81,13 @@ It reads catalog state, not migration text, so it also catches a *later*
 migration re-widening something — including a schema dump re-applying the
 original `GRANT ALL ON TABLE transactions TO authenticated`.
 
+**Run it from `master`, after merging.** The two ledger checks compare cloud
+against the migrations in your *current checkout*. On a feature branch, any
+migration another in-flight branch has already applied to cloud shows up as an
+orphan, and any migration on your branch not yet applied shows up as pending —
+neither is real drift. The payment-invariant checks are branch-independent and
+meaningful anywhere.
+
 The token is a [personal access token](https://supabase.com/dashboard/account/tokens).
 It uses the Management API over HTTPS rather than a Postgres connection because
 port 5432 is blocked on some networks this project is developed from — the same

scripts/lib/verify-cloud-schema-checks.ts

@@ -90,11 +90,20 @@ export function evaluateChecks(facts: CloudFacts): Check[] {
 
   // An orphan stamp is the failure mode that hid #538: it matches no file, so it
   // pads the ledger and makes the pending list above untrustworthy.
+  //
+  // RUN THIS FROM `master`, AFTER MERGING. Both lists compare the ledger against
+  // the migrations present on the CURRENT checkout, so on a feature branch every
+  // migration another in-flight branch has already applied to cloud reads as an
+  // orphan, and every migration on this branch not yet applied reads as pending.
+  // Neither is drift. The detail line below says so rather than leaving someone
+  // to rediscover it and conclude the check is noisy.
   add(
     'cloud carries no migration stamp that matches no repo file',
     orphans.length === 0,
     orphans.length
-      ? `orphan stamps (applied ad hoc, not via db push): ${orphans.join(', ')}`
+      ? `orphan stamps (applied ad hoc, not via db push — or applied by an ` +
+        `in-flight branch this checkout does not have; re-check on master): ` +
+        orphans.join(', ')
       : 'ledger matches repo filenames exactly'
   )