codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-supabase-migrate/SKILL.md

@@ -0,0 +1,314 @@
+---
+scope: org-shared
+name: cbp-supabase-migrate
+description: Scaffold or adopt a Supabase migration for the current PR branch, apply to the branch's preview DB, run advisor checks, regenerate TypeScript types. Includes a fresh-branch dry-run pre-flight that uses one persistent dry-run ephemeral branch per feature branch.
+argument-hint: "[--new <name> | <path-to-sql>]"
+allowed-tools: Read, Edit, Write, Bash(git *), Bash(supabase *), Bash(jq *), Bash(date *), Bash(which *), Bash(cp *), Bash(mv *), Bash(test *), Bash(ls *), mcp__supabase__apply_migration, mcp__supabase__list_migrations, mcp__supabase__get_advisors, mcp__supabase__generate_typescript_types, mcp__supabase__reset_branch, mcp__supabase__list_branches
+model: sonnet
+effort: xhigh
+---
+
+# Supabase Migrate
+
+Scaffold or adopt a migration for the current PR branch, apply it to that branch's preview
+database, run security and performance advisor checks, and regenerate TypeScript types.
+
+Run from a feature branch with an open PR. The skill targets the branch's isolated preview
+database — never the main project database (unless an explicit override token is supplied).
+
+## When to Use
+
+- You have a schema change (new table, altered column, new index, RLS policy) and need to
+  ship it with your PR.
+- A migration file already exists on disk (e.g., from `supabase migration new`) and you
+  want to apply it to the preview DB and regenerate types.
+- Run after `supabase db diff` produces output you want to formalise.
+
+## Arguments
+
+Inspect `$ARGUMENTS`:
+
+- `--new <name>` — scaffold a new timestamped migration file at
+  `supabase/migrations/<timestamp>_<name>.sql` and open it for editing.
+- `<path-to-sql>` — adopt an existing file: apply it directly to the preview DB.
+- _(bare / no arguments)_ — AskUserQuestion picker (see Step 5).
+
+## Step 1 — Pre-flight: Verify Git Branch
+
+```bash
+git branch --show-current
+```
+
+If the output is empty or the branch is in detached HEAD state, **stop immediately**:
+
+```
+Cannot proceed: not on a named branch (detached HEAD or empty output).
+Check out a feature branch first: git checkout -b feat/<name>
+```
+
+Capture the branch name for use in Step 2.
+
+## Step 2 — Resolve Branch project_ref
+
+Retrieve the branch's Supabase preview environment using the CLI:
+
+```bash
+BRANCH=$(git branch --show-current)
+supabase --experimental branches get "$BRANCH" -o env
+```
+
+Parse the output for:
+- `POSTGRES_URL_NON_POOLING` — direct connection string for the preview DB
+- `project_ref` — the Supabase project ref for this branch's environment
+
+Capture both values. The `project_ref` is used in Steps 3, 4, 6, 7, and 8. (Step 5.5 resolves its own separate dry-run branch `project_ref` — see [reference/preflight-dry-run.md](reference/preflight-dry-run.md).)
+
+## Step 2.5 — Empty project_ref Handling
+
+If `project_ref` is empty after Step 2, AskUserQuestion:
+
+```
+Could not resolve a Supabase project_ref for branch: <BRANCH>
+
+Three known causes:
+  1. No database-schema changes are in this PR (branching only provisions when DB paths change)
+  2. The branch has not been pushed to remote yet (git push origin <BRANCH>)
+  3. No open PR exists for this branch (Supabase branching requires an open PR on GitHub)
+
+Options:
+A) Scaffold-only mode — write the SQL file now, skip apply/advisors/types.
+   After push + open PR, re-run /cbp-supabase-migrate to apply and regenerate types.
+B) Hard-refuse — stop here and fix the root cause first (see causes above).
+C) Cancel — abort this invocation.
+```
+
+On (A): continue to Step 5 (scaffold / adopt only), then exit after writing the file.
+On (B): emit a summary of the three causes and stop.
+On (C): stop silently.
+
+## Step 3 — Main-Project Guard
+
+If `project_ref` is empty (scaffold-only mode chosen in Step 2.5), skip Steps 3 and 4 entirely and jump directly to Step 5.
+
+Read `.codebyplan.json`:
+
+```bash
+MAIN_PROJECT_REF=$(jq -r '.shipment.surfaces.supabase.project_ref' .codebyplan.json)
+```
+
+`MAIN_PROJECT_REF` is consumed by Step 5.5's dry-run CLI calls (`branches create` and `branches get`) to pin those calls to the parent project rather than any linked preview branch.
+
+If the resolved `project_ref` from Step 2 matches `$MAIN_PROJECT_REF`, the skill is targeting the
+**main production database**. This is almost always unintentional during development.
+
+Check `$ARGUMENTS` for the exact override token `I-UNDERSTAND-RUNNING-AGAINST-MAIN`.
+
+If the token is **absent**, AskUserQuestion:
+
+```
+WARNING: the resolved project_ref (<project_ref>) matches the main production project.
+
+Applying migrations directly to production is destructive and bypasses PR review.
+If you intended to target the branch preview DB, ensure:
+  - The branch is pushed to remote
+  - An open PR exists
+
+To proceed anyway, re-invoke with:
+  /cbp-supabase-migrate I-UNDERSTAND-RUNNING-AGAINST-MAIN
+
+Or cancel to abort.
+```
+
+Stop and wait for the user. Do NOT proceed against the main project without the override token.
+
+## Step 4 — Idempotency Check
+
+If `project_ref` is empty (scaffold-only mode), skip this step and jump to Step 5.
+
+Before applying anything, check whether the migration is already present on the preview DB:
+
+If `mcp__supabase__list_migrations` is available in your current toolset, call it with the
+resolved `project_ref`. Scan the returned list for a filename or version prefix that matches
+the file you are about to apply.
+
+If a match is found:
+
+```
+Migration already applied: <filename>
+No-op — skipping apply. Types will still be regenerated if needed.
+```
+
+Skip Steps 5.5 and 6 (dry-run pre-flight and apply) and proceed directly to Step 7 (advisors).
+
+## Step 5 — Scaffold or Adopt
+
+Parse `$ARGUMENTS`:
+
+### Case A: `--new <name>`
+
+Generate a timestamp strictly greater than the latest filename in `supabase/migrations/`:
+
+```bash
+ls supabase/migrations/ | sort | tail -1
+```
+
+Extract the numeric prefix from the `tail -1` output (e.g. `20260520000003` from `20260520000003_chk116_security_and_logging_fixes.sql`). Your `date -u +%Y%m%d%H%M%S` output must be strictly greater than that prefix. If two scaffolds happen in the same UTC second, append `_01`, `_02` to maintain monotonicity. Use the current wall-clock UTC time
+via:
+
+```bash
+date -u +%Y%m%d%H%M%S
+```
+
+Create the file:
+
+```bash
+TIMESTAMP=$(date -u +%Y%m%d%H%M%S)
+touch "supabase/migrations/${TIMESTAMP}_<name>.sql"
+```
+
+Open the file for editing — write the migration SQL now. Include both the intended change
+and a comment block at the top:
+
+```sql
+-- Migration: <name>
+-- Created: <ISO timestamp>
+-- Branch: <BRANCH>
+-- Purpose: <one-line description>
+```
+
+Record the created path as `MIGRATION_PATH`.
+
+### Case B: `<path-to-sql>`
+
+Verify the file exists:
+
+```bash
+test -f "$ARGUMENTS" && echo "ok" || echo "missing"
+```
+
+If missing, stop with:
+```
+File not found: <path>
+Provide a valid path to an existing .sql file, or use --new <name> to scaffold.
+```
+
+Set `MIGRATION_PATH="$ARGUMENTS"`.
+
+### Case C: bare (no arguments)
+
+AskUserQuestion:
+
+```
+No argument provided. What would you like to do?
+
+A) --new <name> — scaffold a new migration file (I will name it)
+B) <path-to-sql> — apply an existing file (I will provide the path)
+C) Cancel
+```
+
+On (A): prompt for the migration name, then follow Case A.
+On (B): prompt for the file path, then follow Case B.
+On (C): stop.
+
+## Step 5.5 — Fresh-Branch Dry-Run Pre-Flight
+
+If `project_ref` is empty (scaffold-only mode from Step 2.5), skip this step — there is no preview environment to validate against.
+
+Before applying `MIGRATION_PATH` to the real preview DB, validate the candidate migration on a persistent dry-run branch. The dry-run branch starts from main's migration baseline; `supabase db push` then advances it through the feature branch's local chain plus `MIGRATION_PATH`. This catches migration failures early — the GitHub Preview check (full replay from the feature branch) remains the authoritative gate. Full mechanics: [reference/preflight-dry-run.md](reference/preflight-dry-run.md).
+
+Outcome gate:
+
+| Dry-run result                                                               | Action                                                                                                                                  |
+|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
+| `FUNCTIONS_DEPLOYED`                                                         | Pre-flight passed — continue to Step 6.                                                                                                 |
+| `MIGRATIONS_FAILED` (db push exited non-zero)                                | Surface the verbatim CLI stderr from `supabase db push` and **stop**; do NOT apply to the PR preview DB.                                |
+| `MIGRATIONS_FAILED` (db push exited 0, status poll reached MIGRATIONS_FAILED) | Platform-side failure after apply was accepted — see Supabase dashboard: **Branches → `DRY_RUN_BRANCH` → Migrations**; **stop**.       |
+| Timeout (up to ~5 min)                                                       | Surface a timeout message and **stop**. (Two 120 s poll loops + a 60 s stuck-branch guard.)                                             |
+
+## Step 6 — Apply Migration
+
+Apply `MIGRATION_PATH` to the branch preview database.
+
+**MCP path (preferred)**: If `mcp__supabase__apply_migration` is available in your current
+toolset, use it with the resolved `project_ref` and the SQL content from `MIGRATION_PATH`.
+
+**CLI fallback**: If the MCP tool is not present, fall back to the CLI approach —
+see [reference/cli-fallback.md](reference/cli-fallback.md) for the full procedure including
+passing the branch connection string via `--db-url` and verification steps.
+
+After applying, verify with `mcp__supabase__list_migrations` (or `supabase migration list`
+on the CLI path) to confirm the migration appears in the list.
+
+If verification fails after one retry, return `blocked`:
+
+```
+Migration apply failed or could not be verified after retry.
+Check: Supabase dashboard → Branches → <BRANCH> → Migrations
+```
+
+## Step 7 — Advisor Checks
+
+Run advisor checks against the preview DB using the resolved `project_ref`.
+
+Call `mcp__supabase__get_advisors` twice:
+1. `type: "security"` — security policy findings
+2. `type: "performance"` — query performance findings
+
+Rank all findings by `level` in this order: **ERROR → WARN → INFO**.
+
+Display a summary table:
+
+```
+Advisor findings for <BRANCH> (<project_ref last 4 chars>):
+
+| Level | Count | Examples |
+|-------|-------|---------|
+| ERROR | N     | <first finding title> |
+| WARN  | N     | <first finding title> |
+| INFO  | N     | ... |
+```
+
+No advisor finding blocks migration apply — output is advisory only.
+See [reference/advisor-triage.md](reference/advisor-triage.md) for recommended actions per
+severity level. Hard-block enforcement at ship time is owned by `cbp-supabase-branch-check`.
+
+## Step 8 — Regenerate TypeScript Types
+
+Read the types output path from `.codebyplan.json`:
+
+```bash
+jq -r '.shipment.surfaces.supabase.types_path' .codebyplan.json
+```
+
+If the field is missing or empty, AskUserQuestion:
+
+```
+types_path not found in .codebyplan.json under shipment.surfaces.supabase.types_path.
+Enter the path where TypeScript types should be written (e.g., apps/web/src/lib/database.types.ts):
+```
+
+Call `mcp__supabase__generate_typescript_types` with the resolved `project_ref`. Write the
+returned content to the resolved `types_path` using the Write tool.
+
+## Step 9 — Final Summary
+
+Emit a status block:
+
+```
+## Supabase Migrate — Complete
+
+| Item                  | Value                                      |
+|-----------------------|--------------------------------------------|
+| Migration file        | <MIGRATION_PATH>                           |
+| Preview project_ref   | ....<last 4 chars of project_ref>          |
+| Advisors — ERROR      | N                                          |
+| Advisors — WARN       | N                                          |
+| Advisors — INFO       | N                                          |
+| Types written to      | <types_path>                               |
+
+Next: open a PR (if not already open) and the Supabase Preview check will run automatically.
+```
+
+## Integration
+
+Invoked by the developer or by `cbp-database-agent`'s routing rule. Companion: `/cbp-supabase-setup` (one-time enablement); ship-time hard-block lives in `cbp-supabase-branch-check`. References: [reference/advisor-triage.md](reference/advisor-triage.md) (severity), [reference/cli-fallback.md](reference/cli-fallback.md) (CLI apply).

package/templates/skills/cbp-supabase-migrate/reference/advisor-triage.md

@@ -0,0 +1,70 @@
+# Advisor Triage — Supabase Migrate
+
+Used by `/cbp-supabase-migrate` Step 7 after calling `mcp__supabase__get_advisors`.
+Covers severity definitions, recommended actions per level, escalation criteria, and the
+boundary between advisory output and hard-block enforcement.
+
+## Severity Table
+
+| Level | Definition | Urgency | Example |
+|-------|-----------|---------|---------|
+| ERROR | Critical finding — policy gap, exposed data, or query that will fail at scale under load | Fix before merging this PR | RLS disabled on a table with user data; missing index on a FK used in a high-traffic JOIN |
+| WARN  | Suboptimal pattern — likely to cause performance degradation or security ambiguity as data grows | Review and decide before merge | Sequential scan on a table expected to exceed 100k rows; overly broad RLS `USING (true)` |
+| INFO  | Low-priority observation — best-practice deviation or minor inefficiency | Log for backlog; no merge gate | Unused index; column naming convention deviation |
+
+## Recommended Actions Per Level
+
+### ERROR
+
+1. Read the advisor finding detail (`title`, `description`, `metadata`).
+2. Determine whether the finding is caused by THIS migration or pre-existed.
+   - Pre-existing ERROR: note it in the PR description; it is NOT a merge blocker for this PR.
+   - New ERROR from this migration: fix it in the migration SQL before the PR is reviewed.
+3. Common fixes:
+   - **RLS not enabled**: add `ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;` to the migration.
+   - **Missing FK index**: add `CREATE INDEX ON <table>(<fk_col>);` to the migration.
+   - **Policy always-true**: scope the `USING` predicate to `auth.uid()` or a specific role.
+4. Re-run `/cbp-supabase-migrate` after fixing to confirm the ERROR count drops.
+
+### WARN
+
+1. Read the finding and assess whether it is introduced by this migration or pre-existing.
+2. For new WARNs, evaluate impact:
+   - **Low-traffic table** (< 10k rows, internal use): note in PR description, defer fix.
+   - **High-traffic table or critical query path**: fix in this migration round.
+3. Document your decision as a comment in the PR description:
+   ```
+   Advisor WARN: <finding title> — deferred / fixed in <migration filename>
+   ```
+
+### INFO
+
+- Log for the backlog. No action required before merge.
+- If a batch of INFOs describes the same pattern (e.g., multiple missing naming conventions),
+  consider a dedicated cleanup task.
+
+## Escalation Criteria
+
+Escalate to a synchronous review (team discussion, not just async PR comment) when:
+
+- 3 or more **ERROR**-level findings are present on tables with user PII or financial data.
+- A **WARN** involves an RLS policy on a table that stores session tokens, payment info, or
+  child account data.
+- Any finding is flagged as `severity: critical` in the `metadata` field (not standard, but
+  some advisor versions use this field).
+
+## Advisory-Only Boundary
+
+**No advisor finding blocks `cbp-supabase-migrate` from completing.**
+
+The skill outputs findings for developer awareness and exits with a summary. Hard-block
+enforcement — refusing to allow a PR to merge when ERRORs are present — is owned by
+`cbp-supabase-branch-check` (TASK-3), which runs at ship time as part of the Supabase
+Preview check gate.
+
+This separation means:
+- Developers can merge WIP migrations during active development without advisor-gate friction.
+- Ship-time enforcement is consistent and automated — no manual override needed.
+
+If you want to simulate ship-time behaviour locally, run `/cbp-supabase-branch-check`
+(once implemented) against the current branch before opening the PR for review.

package/templates/skills/cbp-supabase-migrate/reference/cli-fallback.md

@@ -0,0 +1,87 @@
+# CLI Fallback — Supabase Migrate
+
+Used by `/cbp-supabase-migrate` Step 6 when `mcp__supabase__apply_migration` is not present
+in the current toolset. Covers applying via `supabase db push --db-url` with the branch
+connection string, verification, and troubleshooting common errors.
+
+## When This Path Applies
+
+Use this path when `mcp__supabase__apply_migration` is NOT available in your current tool
+list (e.g., running in a context where the Supabase MCP server is not connected, or during
+local CLI-only development). The CLI path applies the migration directly via `psql`-compatible
+connection to the branch preview database.
+
+If MCP IS available, use it — it is the preferred path.
+
+## 1. Apply via supabase db push
+
+Push the pending migration to the branch preview DB using the connection string captured
+in Step 2 of the parent skill (`POSTGRES_URL_NON_POOLING`):
+
+```bash
+supabase db push --db-url "$POSTGRES_URL_NON_POOLING"
+```
+
+Expected output (success):
+
+```
+Applying migration 20260520123456_your_migration_name.sql...
+Migration applied successfully.
+```
+
+The `--db-url` flag accepts a full connection string and routes the push to that database directly — bypassing the project configured in `supabase/config.toml`. The `--linked` and `--db-url` flags are mutually exclusive; do not combine them.
+
+To push a single specific file rather than all pending migrations:
+
+```bash
+supabase db push --db-url "$POSTGRES_URL_NON_POOLING" --file supabase/migrations/<filename>.sql
+```
+
+## 2. Verify the Migration Applied
+
+After the push, confirm the migration is recorded:
+
+```bash
+supabase migration list --db-url "$POSTGRES_URL_NON_POOLING"
+```
+
+The migration filename should appear in the list. If it does not:
+
+1. Wait 10 seconds (remote provisioning can lag) and re-run `supabase migration list --db-url "$POSTGRES_URL_NON_POOLING"`.
+2. Check the Supabase dashboard: **Branches → <branch name> → Migrations**.
+3. If still absent, retry `supabase db push --db-url "$POSTGRES_URL_NON_POOLING"` once.
+
+Once confirmed, continue with `/cbp-supabase-migrate` Step 7 (Advisor Checks).
+
+## 3. Troubleshooting
+
+### Auth failure: `FATAL: password authentication failed`
+
+- Verify the connection string was captured correctly — it may contain special characters that need
+  URL-decoding (`%40` = `@`, `%21` = `!`).
+- Re-fetch the connection string from the branch: `supabase --experimental branches get "$BRANCH" -o env`
+- Confirm the branch is still active: `supabase --experimental branches list`
+
+### Connection refused: `could not connect to server`
+
+- The branch preview DB may still be provisioning. Wait 30 seconds and retry.
+- Verify the connection string has no extra characters.
+- Check firewall / VPN — some networks block direct PostgreSQL connections to Supabase.
+
+### Migration already applied: `ERROR: relation already exists`
+
+The migration file was already applied to this preview DB (possibly via MCP in a prior run).
+This is safe to ignore. The idempotency check in `/cbp-supabase-migrate` Step 4 should have
+caught this — if not, note the discrepancy and skip to Step 7.
+
+### CLI not found
+
+```
+Supabase CLI not found. Install options:
+  brew install supabase/tap/supabase   (macOS / Homebrew)
+  npm install -g supabase              (npm global)
+  scoop install supabase               (Windows Scoop)
+  https://supabase.com/docs/guides/local-development/cli/getting-started
+```
+
+After installing, restart your shell and re-run `/cbp-supabase-migrate`.

package/templates/skills/cbp-supabase-migrate/reference/preflight-dry-run.md

@@ -0,0 +1,58 @@
+# Pre-Flight Dry-Run Mechanics
+
+Detailed procedure for `cbp-supabase-migrate` Step 5.5 — validating a new migration on a dry-run Supabase branch before applying it to the real PR preview DB.
+
+## Why
+
+`supabase --experimental branches create` clones the connected repository at `git_ref=main` — it replays **main's** migration chain as a starting baseline, not the current feature branch's chain from zero. After the branch settles to `FUNCTIONS_DEPLOYED`, `supabase db push --db-url` advances it incrementally through the feature branch's local migrations (those not yet on main) plus the candidate `MIGRATION_PATH`. The dry-run catches migration failures early — at `/cbp-supabase-migrate` time rather than at PR-open time. It is a best-effort early check, not a from-zero feature-branch replay.
+
+## Dry-run branch lifecycle
+
+The dry-run uses ONE persistent branch per feature branch — created on first use, reset on every subsequent use. Deterministic name:
+
+    DRY_RUN_BRANCH="${BRANCH}-cbp-migrate-dryrun"
+
+The CLI `branches` sub-commands act on the project the CLI is *linked* to — mid-development that is often a preview branch, not the parent project. Pin every `branches` call to the parent with `--project-ref "$MAIN_PROJECT_REF"`, where `MAIN_PROJECT_REF` is the parent `project_ref` SKILL.md Step 3 already resolves from `.codebyplan.json` (`.shipment.surfaces.supabase.project_ref`). `mcp__supabase__list_branches` and `reset_branch` need no such flag — the MCP server is already bound to the parent project.
+
+1. Call `mcp__supabase__list_branches`. Look for an entry whose name equals `DRY_RUN_BRANCH`. If found, capture its `id` field as `DRY_RUN_BRANCH_ID` — `reset_branch` and every status poll below act on the branch id, not the name.
+2. **If absent** — run `supabase --experimental branches create "$DRY_RUN_BRANCH" --project-ref "$MAIN_PROJECT_REF" --yes`. The `--yes` flag is required: branch creation prompts for cost confirmation and the skill runs non-interactively, so the prompt would otherwise hang. The CLI create command is asynchronous and returns a human-readable message (not JSON with an `id`). After the CLI call, poll `mcp__supabase__list_branches` until an entry whose name equals `DRY_RUN_BRANCH` appears, then capture its `id` as `DRY_RUN_BRANCH_ID`. This poll both confirms the create succeeded and yields the id. Creation clones at `git_ref=main` and replays main's migration chain as a baseline — skip the reset in step 4 and go straight to step 5 (the initial provisioning already gave a main baseline).
+3. **If present and its `status` is any non-terminal value** (i.e., anything other than `FUNCTIONS_DEPLOYED` or `MIGRATIONS_FAILED`) — a prior run was interrupted mid-provision. Poll `mcp__supabase__list_branches` every 10 seconds, filtering to the entry with `id = DRY_RUN_BRANCH_ID`, for up to 60 seconds (6 polls). If it has not settled to a terminal status (`FUNCTIONS_DEPLOYED` or `MIGRATIONS_FAILED`) after 60 seconds, surface `Dry-run branch ${DRY_RUN_BRANCH} is stuck in ${status}. Resolve manually before retrying.` and stop. If the branch settles to `FUNCTIONS_DEPLOYED` during the poll, fall through to step 4 (reset). If it settles to `MIGRATIONS_FAILED`, main's chain is already broken before the new migration was applied — see the Supabase dashboard: **Branches → \<DRY_RUN_BRANCH\> → Migrations** for error details; stop. Note: a branch found already in `MIGRATIONS_FAILED` (from a prior failed run) does NOT enter this non-terminal poll — it is already terminal and falls through directly to step 4 (reset), which returns it to main's baseline so the retry can proceed.
+4. **If present** — call `mcp__supabase__reset_branch` with `DRY_RUN_BRANCH_ID`. Reset re-replays **main's** migration chain from zero, returning the dry-run branch to main's baseline.
+5. Poll `mcp__supabase__list_branches` every 10 seconds, filtering to the entry with `id = DRY_RUN_BRANCH_ID`, until status reaches `FUNCTIONS_DEPLOYED`, `MIGRATIONS_FAILED`, or 12 polls (120 seconds) have elapsed.
+
+If main's chain itself reaches `MIGRATIONS_FAILED` at this stage, main's existing migrations are already broken — see the Supabase dashboard: **Branches → \<DRY_RUN_BRANCH\> → Migrations** for error details; stop. The new migration is not the cause.
+
+## Apply the new migration
+
+Once the dry-run branch is `FUNCTIONS_DEPLOYED`:
+
+1. Resolve the dry-run branch connection string:
+   ```bash
+   supabase --experimental branches get "$DRY_RUN_BRANCH" --project-ref "$MAIN_PROJECT_REF" -o env
+   ```
+   Parse `POSTGRES_URL_NON_POOLING` from the output and set it as `DRY_RUN_CONN`.
+
+2. Apply the candidate migration:
+   ```bash
+   supabase db push --db-url "$DRY_RUN_CONN"
+   ```
+   `supabase db push` is an **incremental** apply — it inspects the branch's `schema_migrations` table, skips any migration already recorded there (i.e. those from main's chain), and applies only the feature branch's not-yet-on-main migrations plus `MIGRATION_PATH`. Exit 0 = apply accepted. Non-zero exit or stderr = apply rejected; the verbatim stderr IS the error surface (no `mcp__supabase__get_logs` call needed). This works for both `--new` (uncommitted file) and `<path-to-sql>` (adopt) modes, because the SQL is read from disk.
+
+3. Poll `mcp__supabase__list_branches` every 10 seconds, filtering to the entry with `id = DRY_RUN_BRANCH_ID`, until status reaches `FUNCTIONS_DEPLOYED`, `MIGRATIONS_FAILED`, or 12 polls (120 seconds) have elapsed.
+
+## Outcome
+
+| Result                                                        | Meaning                                                                | Action                                                                                                                                  |
+|---------------------------------------------------------------|------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
+| `FUNCTIONS_DEPLOYED`                                          | New migration applies on top of main's chain                           | Return to Step 5.5 — continue to Step 6                                                                                                 |
+| `MIGRATIONS_FAILED` (db push exited non-zero)                 | Migration rejected at apply time                                       | The verbatim error is the CLI stderr from `supabase db push`; stop before Step 6                                                        |
+| `MIGRATIONS_FAILED` (db push exited 0, status poll reached MIGRATIONS_FAILED) | Platform-side failure after apply was accepted | See the Supabase dashboard: **Branches → `DRY_RUN_BRANCH` → Migrations** for error details; stop before Step 6                         |
+| Timeout (up to ~5 min)                                        | Branch did not converge                                                | Surface a timeout message; stop before Step 6. (Two 120 s poll loops + a 60 s stuck-branch guard.)                                       |
+
+## Fidelity and limitations
+
+The GitHub PR integration clones at `git_ref=<PR branch>` and replays from zero — that is the authoritative full-fidelity gate. The dry-run described here is a best-effort early check: it catches migrations that are syntactically invalid, reference missing objects, or violate ordering when applied on top of main's chain. Fidelity gap: in-place edits to migrations already recorded in main's `schema_migrations` are NOT re-applied by `db push`, so the dry-run cannot detect breakage from such edits (this is the bug class CHK-133 TASK-1 fixed in the `schema_migrations` PK collision and `remote_stub DELETE` guards). The live integration test of this dry-run design is deferred to post-CHK-133-TASK-3, once main's chain is fully healthy and `branches create` provisions successfully.
+
+## Platform cost
+
+The dry-run branch is persistent — reused via `reset_branch` across invocations rather than created and deleted each time. Supabase counts it as one active branch against the project's branch limit for as long as the feature branch exists. This is intentional: branch creation is slow, reset is fast, and one long-lived dry-run branch per feature branch is cheaper than create/delete churn.