@luanpdd/kit-mcp 1.26.0 → 1.27.0

package/kit/agents/supabase-migration-writer.md

@@ -197,6 +197,18 @@ Se a mudança envolve `drop table`, `drop column`, `truncate`, `delete from` em
 - `Validation:` (query upstream que validou seguro)
 - `Rollback:` (como reverter)
 
+## Caveats v1.27 — Branching & Concurrent Push
+
+**Anti-pattern:** Concurrent `supabase db push` from different machines/CI runners.
+- **Por quê:** migrations são aplicadas em timestamp order. Push concorrente de duas máquinas pode resultar em conflitos quando ambas tentam aplicar migrations com timestamps próximos.
+- **Solução:** coordenar — apenas 1 deployer por vez. Ou usar GitHub Actions com `concurrency` control.
+
+**Anti-pattern:** Migration com timestamp wrong order após git rebase.
+- **Sintoma:** migration que depende de earlier change tem timestamp ANTERIOR à da dependência (após rebase teammate's migration foi para frente).
+- **Solução:** renomear arquivo migration com timestamp ATUAL (mais recente que dependências), reset local com `supabase db reset` para validar ordem.
+
+Ver skill canônica: `kit/skills/supabase-migration-repair/SKILL.md` (Pattern 4 — schema drift após rebase).
+
 ### Step 5 — Validação prévia (live mode apenas)
 
 **Se MCP disponível:**

package/kit/file-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.26.0",
-  "timestamp": "2026-05-11T04:13:53.239Z",
+  "version": "1.27.0",
+  "timestamp": "2026-05-11T07:25:37.591Z",
   "files": {
     "COMANDOS.md": "d24ec61a6ec35db314cc5f2ae287bfb927b794789c8f1d558c55862f5e6534b2",
     "COMPATIBILITY.md": "794e336a87045cdf0161785b9a7a0975a49abbd80bdd816b8852251fcc8126ca",
@@ -42,7 +42,7 @@
     "agents/project-researcher.md": "3cf77520ff888cf0a4c879e147180f6f9c3ba04bd9b0def10ef8f35e7ccedbf6",
     "agents/prr-conductor.md": "22710f35f702f132a9cdd5c6e3fe2dcf44cda24af36a2cd91060799dd19e9a02",
     "agents/refactor-safety-auditor.md": "4051f2f57dbf932bf0c7bfb57194e9800f3ca362a9a6c16649e11792919fa05b",
-    "agents/release-pipeline-auditor.md": "e7accd6a629453dd865f4938f1bb3ad5d5da25d9f3d3211d0badb521c903b00a",
+    "agents/release-pipeline-auditor.md": "2d1946b52107a90467f88e1328f8c2a3ca2f6025e3826e2b25fbe9cbc7fc2b28",
     "agents/research-synthesizer.md": "be103c503d73ab5e9ed8c6db36e611d437a117665dcc4dc2af4f016427e63281",
     "agents/roadmapper.md": "63d26611dcb40c965f4edc3f6d7c8e765c7b34f1900920823026bb0dc8f9f700",
     "agents/schema-checker.md": "065398b08fc023516b1798b3c00ed8e135a74b5bbef7fc2a2cc4086ef9085d03",
@@ -50,11 +50,13 @@
     "agents/shotgun-surgery-detector.md": "334966916715c4c5eff3324b81a09e17b312defd9a8549f17bfe19c06dbd9e92",
     "agents/slo-engineer.md": "1e6ec6e3031a40be6a6d631400f0dd12bb2b94ce37a9816d89d1badae1e7d7ca",
     "agents/storytelling-analyst.md": "dd68f9e8cb01bbd102acb9a2021be81a0b8d6f2528f30971f9aa5ef331f7e563",
-    "agents/supabase-architect.md": "523247c1ae7f69158d42971b19d51d299bc94a386ed871bdfe7eefbf3471a076",
+    "agents/supabase-architect.md": "ac7e08f287a37667d0ce9500890a6047d234121be3b2deaafac235c675e18a93",
     "agents/supabase-auth-bootstrapper.md": "a197c3cd2c817f67a53400d5ba4fbf491f365a45e601fc60cd708ed07340272b",
+    "agents/supabase-branching-architect.md": "0a335c144c03ed4b3d69844dbcfc8a41aa48ddd187cb47500a491117be5bbfaa",
+    "agents/supabase-cicd-pipeline-implementer.md": "9a37ad75ac1419516b637f0099bafa884807cd2c21983307db3bfc6cf2283688",
     "agents/supabase-column-privileges-writer.md": "dc6ed23511008cda6b9698afc3b577512547aaaf555d2a4de9273417f247ee6b",
     "agents/supabase-edge-fn-writer.md": "7b470664173f8c5c9ab12af74f58ddaeee3eb46bb3d2ca8de21b1c284961d9dd",
-    "agents/supabase-migration-writer.md": "a964dd676362184fe657446415202e0c620b0d4ce26ebe25125b6a55937c2fba",
+    "agents/supabase-migration-writer.md": "2c940ab2123f206dad3e1b6cee1393ff405ea23cc39644fce022af1d2260e10a",
     "agents/supabase-rbac-implementer.md": "605de2d2a43a3d1eda2e181b98f53aae45b0c80123acc059305b65adf51f9f74",
     "agents/supabase-realtime-implementer.md": "e10d7f723734da0dd930d6e0481e2afb2abde5b470d9c45e4364889dac19f3d6",
     "agents/supabase-rls-hardener.md": "2d20a112d9fac3e2d6f7012acfd1aa141608952bfe0412878dad0201411c1a56",
@@ -305,7 +307,7 @@
     "skills/_shared-multi-tenant/glossary.md": "1e040a36025489859312430771dde13bde9c62098fcd100440a82a2bb4d22b6a",
     "skills/_shared-observability/glossary.md": "ec3892c226af03299c0875e36fd0170cc9f801b02df52a2e0ec5c7468229912a",
     "skills/_shared-sre/glossary.md": "55a052c7d2292622150ed1cbb5aa0d675c332287b00ee4e3dd84900f9cf0ec84",
-    "skills/_shared-supabase/glossary.md": "24a794d195bdcf7ee6a5cc5c81b0ca93e3c8470afee6965fb104d9490072c450",
+    "skills/_shared-supabase/glossary.md": "5896a4d44c1027aff3ef5d6484dc4789ddd2332921ea8bea3dd7ed4b6443c7a0",
     "skills/ai-prompt-characterization/SKILL.md": "1a8114296c754e2018b1c1fd428c364f8de4485fedd5df78d3afcb33c3fef1a4",
     "skills/armadilhas-sistemas-distribuidos/SKILL.md": "fd33913c41a03f37eaa5fbc2aa3c33321397daa98a505ccb5f2d692dd8a00d5a",
     "skills/audit-log-multi-tenant/SKILL.md": "877871e609008ec04c805c3f1c6de494c80adc838285eae119a23355a13bbe48",
@@ -358,13 +360,18 @@
     "skills/streams-eventos-cdc/SKILL.md": "64af5564e999ec0d8c3a0e1edbbea9f80a212d8ce8d03b0dfcf9c2db29b76d8f",
     "skills/structured-events/SKILL.md": "a693c8a19709066ea60860a01ba54731406d7daf41ed51adea9c29a2de131fac",
     "skills/supabase-auth-ssr/SKILL.md": "941d80ad88b4cbeccadf852d82f64f0167bce204005f72b32bc2aaf81a460af6",
+    "skills/supabase-branching-workflow/SKILL.md": "305dde598f7bbc11f57f07354c47df27e4870a3b51a5156de12ec38fac5e9e38",
+    "skills/supabase-ci-cd-github-actions/SKILL.md": "da51f19f98ae8183fda0070a656a6f86bc789cdba1f35beab2a43e9d98e2e3ea",
     "skills/supabase-column-level-security/SKILL.md": "0fcdac70be44ffbdccb56d5b0ca4f80c1267ddba037a757fcf969013754e521f",
+    "skills/supabase-config-toml-remotes/SKILL.md": "810595fd935014223b82b6b3b934bfc47a6c551f09b9e6bc07bb4cc7e31cdaef",
     "skills/supabase-cron-queues/SKILL.md": "4f48ed9cea9b5b2bc187983ffbbb63f9e46ad65ff6a6306b5c8b4b01b4e6911a",
     "skills/supabase-custom-claims-rbac/SKILL.md": "2120bd49e0b6f1ee9723128654550836634f93dee5a80e6c6409fe96af223a0c",
     "skills/supabase-database-functions/SKILL.md": "77b49f2930d61667e4ae1839944dbee012267253444aef63cc1dc24d227deff7",
     "skills/supabase-declarative-schema/SKILL.md": "8a78cae2d74287002c02bafdfb8218a9ac20b7d75047c269c702d9b8e3d22476",
     "skills/supabase-edge-functions/SKILL.md": "bf195e3fbce2bd94cb782ce15ecc60260217ac40d9ac5cbc787362de6629f960",
+    "skills/supabase-migration-repair/SKILL.md": "e000734b9e9d77bd428075a76099452f259b056b8b9ece185e13f752408afdc7",
     "skills/supabase-migrations/SKILL.md": "bd7a4e43e2c135d0f15f3ac4045c22e378b863b2c878c1895486cdfb39f4e968",
+    "skills/supabase-pgtap-testing/SKILL.md": "95f301ff3490c0d9bead12224806d0744a158ca5014123bf7f11d5ce52b5f648",
     "skills/supabase-pgvector-rag/SKILL.md": "cd50663c5b19d08d9bc17bc9b4444f7fc2f6910f5c52502e7c50b1578ebe7e70",
     "skills/supabase-postgres-roles/SKILL.md": "eec741701e1f71b380c0275c318968d0674e20017437a00e39808b33115e62fa",
     "skills/supabase-postgres-style/SKILL.md": "4e48bd0a9ed46bea7c3be97ef749e5c148369ceca08ef3dc8d813d8a03a48703",

package/kit/skills/_shared-supabase/glossary.md

@@ -115,8 +115,18 @@
 | EN | PT-BR / Significado |
 |---|---|
 | **branch database** | Cópia preview do DB de produção para feature branches. |
+| **Branching Compute Hours** (v1.27) | Métrica de billing Supabase para tempo de compute consumido por branches. FORA do Spend Cap. Compute Credits NÃO aplicam. Micro $0.01344/h. |
+| **Branching workflow (Supabase)** (v1.27) | Fluxo de criar preview/persistent branches separados da production. Cada branch tem própria instância Supabase + API credentials. |
+| **Deploy DAG (7 steps)** (v1.27) | Directed Acyclic Graph que descreve deployment de branch: clone → pull → health → configure → migrate → seed → deploy. Falha em parent step skipa children. |
+| **dotenvx encrypted fields** (v1.27) | Pattern de encryptar secrets em arquivos `.env.*` commitados no git. Decryption key em `.env.keys` (gitignored). Sintaxe `encrypted:<value>` em config.toml — só funciona em designated secret fields. |
+| **Migration repair** (v1.27) | Comando `supabase migration repair --status applied\|reverted <timestamp>` que atualiza tracking table only, NÃO aplica/reverte SQL. Para corrigir history record quando schema state real está OK. |
 | **persistent branch** | Branch que sobrevive entre PRs (staging long-lived). |
+| **Persistent branch** (v1.27) | Branch Supabase long-lived (staging/QA/dev), NÃO auto-pause em inatividade, não auto-delete em PR merge. Custo Branching Compute Hours contínuo. |
+| **pgTAP testing** (v1.27) | Pattern de testing PostgreSQL usando pgTAP extension (TAP — Test Anything Protocol). Comando `supabase test db` busca em `supabase/tests/*.sql`. Funções canônicas: plan/ok/is/throws_ok/finish. |
 | **preview branch** | Branch criado para PR específico — destruído ao merge. |
+| **Preview branch** (v1.27) | Branch Supabase ephemeral, auto-pause em inatividade, auto-delete em PR merge/close. Padrão para feature development. |
+| **[remotes] block** (v1.27) | Seção em `config.toml` que define configuração branch-specific. Referencia `project_id` obtido via `supabase --experimental branches list`. Permite override de db/api/auth/edge_runtime per branch. |
+| **Schema drift** (v1.27) | Divergência entre estado real do schema e migration tracking. Causa típica: changes diretos no dashboard, ou timestamps wrong order após git rebase. Resolução via `migration repair` (tracking) ou rebase rename (timestamps). |
 
 ---
 

package/kit/skills/supabase-branching-workflow/SKILL.md

@@ -0,0 +1,544 @@
+---
+name: supabase-branching-workflow
+description: Use ao adotar Supabase Branching — preview vs persistent branches, deploy DAG 7 steps (clone→pull→health→configure→migrate→seed→deploy), GitHub integration setup, Dashboard alpha caveats, custo Branching Compute Hours (FORA do Spend Cap). v1.27 incorpora 100% da doc oficial.
+---
+
+# Supabase — Branching Workflow
+
+## Quando usar
+
+Supabase Branching cria cópias **isoladas** do projeto Postgres + Edge Functions + Storage config para cada branch git — workflow tipo Vercel preview deployments, mas com schema/migrations versionados.
+
+Trigger phrases:
+
+- "preview branch Supabase", "persistent branch staging"
+- "deploy DAG Supabase", "branching workflow"
+- "GitHub integration Supabase", "automatic branching"
+- "Dashboard branching alpha"
+- "Branching Compute Hours custo", "custo branching Supabase"
+- "preview ephemeral vs long-lived"
+- "PR-driven Supabase workflow"
+
+**Use Supabase Branching APENAS para:**
+
+- Validar migrations + schema declarativo em PR antes do merge
+- Isolar mudanças destrutivas (DROP COLUMN, ALTER TYPE) em preview
+- QA team rodar smoke tests em staging persistente
+- Validar deploy de Edge Functions com `[remotes]` block em `config.toml`
+
+**NÃO use Supabase Branching para:**
+
+- QA com dados reais de produção — branches são **dataless by design** (seed.sql é dados sintéticos)
+- Replicar production traffic — preview branches têm compute Micro por default (não dimensionado para load)
+- Substituir staging Supabase project separado quando precisar SLA/uptime
+- Test environments sem expirar — preview branches são **ephemeral** (auto-delete em PR merge/close)
+
+## Princípio canônico
+
+**Preview branches:** ephemeral, criados em PR open, auto-pause em inatividade, **auto-delete em PR merge/close**.
+
+**Persistent branches:** long-lived (staging/QA), NÃO auto-pause, requerem delete **manual** via Dashboard ou CLI.
+
+Critério de escolha canônico:
+
+- PR-driven dev workflow + features curtas (< 1 semana) → **preview**
+- Staging compartilhada + features longas + manual control → **persistent**
+- Mix possível: 1 persistent staging compartilhado + N ephemeral previews por PR
+
+## ALERTA DE CUSTO — Branching Compute Hours
+
+> **ATENÇÃO CANÔNICA — leia antes de habilitar branching em produção.**
+>
+> Cada branch Supabase (preview ou persistent) consome **Branching Compute Hours** independentes do projeto principal.
+>
+> - **Micro Compute size starts at $0.01344/h** (cobrança por hora de branch ativo)
+> - **Branching Compute Hours FORA do Spend Cap** — Spend Cap do projeto NÃO protege contra este custo
+> - **Compute Credits NÃO aplicam** a Branching Compute (FAQ pricing oficial)
+> - **Billing aparece como "Branching Compute Hours"** no invoice (linha separada)
+>
+> ### Estimativa concreta
+>
+> - **10 PRs/mês × 24h média de vida útil** = 240h × $0.01344 = **~$3.23/mês adicional**
+> - **30 PRs/mês × 72h média (PRs grandes)** = 2160h × $0.01344 = **~$29.03/mês adicional**
+> - **Persistent staging branch 24/7** = 720h × $0.01344 = **~$9.67/mês adicional** (acumula continuamente)
+>
+> ### Atenção
+>
+> - Persistent branches **acumulam horas continuamente** (não pausam) — custo previsível por mês
+> - Preview branches **auto-pausam** em inatividade — custo varia com atividade do PR
+> - Branch creation pode levar até **30 minutos** (health check) — primeira hora já é cobrada
+>
+> ### Mitigações canônicas
+>
+> - Habilitar **"Supabase changes only" filter** (Pattern 3) — preview branch SÓ para PRs que tocam `supabase/`
+> - Considerar **1 persistent staging** compartilhado em vez de N preview branches
+> - Monitorar billing manualmente — **Spend Cap NÃO protege**, reforço
+
+## Pattern 1: Preview vs Persistent Branches
+
+Distinção operacional canônica (BRANCH-01):
+
+| | Preview Branch | Persistent Branch |
+|---|---|---|
+| Ciclo de vida | Ephemeral (criado em PR open) | Long-lived (criado manualmente) |
+| Auto-pause | Sim (inatividade) | NÃO |
+| Auto-delete | Sim (PR merge/close) | NÃO (delete manual via Dashboard/CLI) |
+| Caso de uso | PR-driven dev workflow | Staging/QA compartilhada |
+| Custo (Branching Compute Hours) | Acumula durante PR vida útil | Acumula continuamente 24/7 |
+| Trigger | GitHub PR webhook (automatic) | CLI ou Dashboard (manual) |
+| Naming | Auto: `pr-<N>-<branch-name>` | User-defined (ex: `staging`, `qa`) |
+| Health check inicial | Até 30 minutos | Até 30 minutos |
+
+### Critério de escolha
+
+**Use preview SE:**
+
+- Equipe usa PR workflow disciplinado (features curtas, < 1 semana de PR aberto)
+- Cada PR deve ter ambiente isolado para review
+- Aceita custo proporcional a número de PRs ativos
+
+**Use persistent SE:**
+
+- Precisa staging compartilhado para QA team validar release
+- Features longas (sprints multi-semana com PR aberto continuamente)
+- Manual control sobre lifecycle (não querer auto-delete)
+
+**Pode haver MIX (recomendação canônica para times maduros):**
+
+- 1 persistent branch `staging` para QA team rodar smoke tests pós-merge para `main`
+- N preview branches ephemeral, 1 por PR ativo, para review de mudanças
+
+### CLI canônico
+
+```bash
+# criar persistent branch via CLI
+supabase --experimental branches create staging --persistent
+
+# listar branches do projeto
+supabase --experimental branches list
+
+# inspecionar branch específico
+supabase --experimental branches get staging
+
+# deletar branch
+supabase --experimental branches delete staging
+
+# atualizar persistent branch para latest main
+supabase --experimental branches update staging
+```
+
+### Caveat — Health check pode levar 30 minutos
+
+Branch creation aplica DAG (Pattern 2) — health check do Postgres pode demorar **até 30 minutos** dependendo de:
+
+- Tamanho do schema migrado
+- Número de migrations
+- Tamanho do seed.sql
+
+Durante este tempo, a primeira **hora de Branching Compute** já é cobrada (Pattern 5 — custo arrendondado a hora cheia inicial).
+
+## Pattern 2: Deploy DAG — 7 steps canônicos
+
+Cada branch (preview ou persistent) aplica um **DAG (Directed Acyclic Graph)** de 7 steps em ordem (BRANCH-02):
+
+1. **clone** — clone do repositório git no contexto do branch Supabase
+2. **pull** — pull das migrations (`supabase/migrations/`) e schema declarativo (`supabase/schemas/`)
+3. **health** — health check do branch DB (espera até 30 min — Postgres ready + connection pooler ativo)
+4. **configure** — aplica `config.toml` (incluindo `[remotes.<branch>]` block — cross-ref skill `supabase-config-toml-remotes` v1.27)
+5. **migrate** — executa migrations em ordem cronológica (`supabase/migrations/*.sql`)
+6. **seed** — aplica `supabase/seed.sql` (dataless by design — sem dados de produção)
+7. **deploy** — deploy de Edge Functions e secrets (via `supabase functions deploy`)
+
+### Diagrama ASCII
+
+```
+clone → pull → health → configure → migrate → seed → deploy
+  ✓      ✓       ✓         ✓          ✓         ✓        ✓
+                                       ↓ falha
+                                    [seed: SKIPPED]
+                                    [deploy: SKIPPED]
+```
+
+### Skip behavior canônico (anti-cascading failure)
+
+**Falha em step N → todos steps N+1...7 são SKIPPED.**
+
+Exemplo concreto:
+
+- **migrate falha no step 5** (ex: migration com `DROP COLUMN` em coluna que tem FK)
+- **seed (step 6) é SKIPPED** — sem aplicar seed.sql
+- **deploy (step 7) é SKIPPED** — sem deploy de Edge Functions
+- DAG status no Dashboard mostra: ✗ migrate (step 5), ⊘ seed (skipped), ⊘ deploy (skipped)
+
+Este comportamento previne **cascading failures** — se schema falha, não aplicar Edge Functions que dependem do schema.
+
+### Logs por step
+
+Cada step tem stdout/stderr **próprio** acessível no Dashboard:
+
+- **Settings → Integrations → GitHub → "View deployment logs"** (link no PR comment)
+- Logs persistidos durante vida útil do branch
+- Útil para debug: step 5 (migrate) tem stderr com SQL error específico
+
+### Recovery pattern
+
+**Sem rollback automático** — branch fica em estado "failed".
+
+Para recovery:
+
+1. Push **novo commit** no PR com migration corrigida
+2. GitHub webhook → re-run DAG (steps 1-7 do zero)
+3. Se step 5 (migrate) passa → step 6 (seed) e step 7 (deploy) executam
+
+Se migration drift entre branches → ver skill `supabase-migration-repair` (v1.27, Phase 153) para `migration list/repair`.
+
+### Caveat — Dataless by design
+
+`seed.sql` aplicado no step 6 NÃO deve conter:
+
+- Dados sensíveis de produção (PII, tokens, secrets)
+- Snapshot real de tabelas grandes
+- Dados com FKs para tabelas Auth (`auth.users`) — preview branches têm Auth schema separado
+
+**Recomendação canônica:** seed.sql contém apenas:
+
+- Dados de referência (ex: lista de países, categorias estáticas)
+- Fixtures sintéticos pequenos para smoke tests
+- Setup de roles + permissions iniciais (cross-ref skill `supabase-postgres-roles` v1.26)
+
+Preview branches são para **dev workflow**, não para QA com dados reais — se precisar dados reais, use staging Supabase project separado.
+
+## Pattern 3: GitHub Integration Setup
+
+Setup canônico para preview branching automatizado via GitHub (BRANCH-03):
+
+### Step 1: Authorize Supabase no GitHub
+
+1. Dashboard → **Project Settings → Integrations → GitHub**
+2. Clicar **"Authorize Supabase"** — OAuth flow do GitHub
+3. Selecionar **organization** + **repos específicos** (princípio do least privilege — não autorizar todos os repos)
+
+### Step 2: Working directory
+
+Definir diretório raiz do projeto Supabase no repositório:
+
+- **Monorepo single Supabase project:** `./`
+- **Monorepo com Supabase em subdiretório:** `./supabase` ou `./apps/api/supabase`
+- **Default:** `./` (raiz do repo)
+
+Working directory deve conter `supabase/migrations/`, `supabase/schemas/`, `supabase/config.toml`.
+
+### Step 3: Automatic branching toggle
+
+- **ON (recomendado):** preview branch criado **automaticamente** quando PR é aberto
+- **OFF:** branches criados apenas manualmente via CLI ou Dashboard
+
+Recomendação: **ON** para workflow PR-driven canônico.
+
+### Step 4: "Supabase changes only" filter
+
+**Recomendação canônica para reduzir custo Branching Compute Hours:**
+
+- **ON:** preview branch criado **APENAS** se o PR toca arquivos em `supabase/` (migrations, schemas, functions, config.toml)
+- **OFF:** preview branch criado em **TODOS** os PRs (alto custo se time abre muitos PRs frontend-only)
+
+Recomendação: **ON** em todos projetos com Spend Cap awareness (cross-ref Pattern 5).
+
+### Step 5: Deploy to production toggle
+
+- **ON:** quando PR é merged para `main`, mudanças são automaticamente push para production project Supabase
+- **OFF:** merge não trigger deploy production (deploy manual via CLI ou outro workflow CI)
+
+**Use com CAUTELA** — exige:
+
+- Migrations bem testadas em preview branch
+- Required check "Supabase Preview" gating merge (sem ✓ verde, sem merge)
+- Política de rollback documentada (cross-ref skill `supabase-migration-repair` v1.27)
+
+Recomendação inicial: **OFF** até equipe estabelecer disciplina de PR review.
+
+### Workflow esperado após setup
+
+```
+Dev abre PR
+  ↓
+GitHub webhook → Supabase cria preview branch
+  ↓
+Deploy DAG roda (7 steps canônicos)
+  ↓
+Required check "Supabase Preview" reportado no PR
+  ↓
+Dev valida em preview (smoke tests, manual QA)
+  ↓
+Merge para main (se check ✓ verde)
+  ↓
+(se "deploy to production" ON) → push para production project Supabase
+  ↓
+Preview branch auto-delete (em PR merge ou close)
+```
+
+### Required check enforcement
+
+GitHub branch protection rules:
+
+1. Settings → Branches → Add rule para `main`
+2. **Require status checks to pass before merging** — selecionar **"Supabase Preview"** como required
+3. **Sem check ✓ verde → bloqueia merge** (gate canônico — DAG falha = merge bloqueado)
+
+### Recomendação canônica
+
+**Use GitHub integration em qualquer projeto sério.** Dashboard branching alpha (Pattern 4) tem limitações documentadas que tornam unsuitable para production workflow.
+
+## Pattern 4: Dashboard Branching Alpha — Caveats canônicos
+
+**Dashboard branching está em ALPHA — desencorajado para projetos sério. Use GitHub integration (Pattern 3).**
+
+Caveats canônicos documentados (BRANCH-04):
+
+### Caveat 1: Custom roles NÃO capturados
+
+Branches criados via Dashboard alpha **NÃO capturam Postgres custom roles** definidos no DB principal.
+
+- **Roles definidos em migrations** (`CREATE ROLE` em arquivo `.sql`) → aplicados pelo DAG step 5 (migrate) → presentes no branch
+- **Roles criados via Dashboard SQL editor** ou diretamente no DB → **perdidos** no branch creation
+
+Cross-ref skill `supabase-postgres-roles` v1.26: roles **DEVEM** ser definidos em migrations versionadas, nunca via Dashboard ad-hoc.
+
+### Caveat 2: Merge só para `main`
+
+Dashboard alpha aceita **merge só para `main`** — não suporta merge entre preview branches.
+
+- Direção suportada: `preview → main` (1 sentido apenas)
+- **NÃO suportado:** `preview-A → preview-B`, ou seja, não combinar 2 features em desenvolvimento via Dashboard
+
+**Workaround:** combinar features via git workflow:
+
+```
+git checkout feature-B
+git rebase feature-A    # ou git merge feature-A
+git push --force-with-lease
+# PR-B atualizado contém commits de A + B
+```
+
+### Caveat 3: Edge Functions sobrescritas no "update branch"
+
+Clicar **"Update branch"** no Dashboard sobrescreve **TODAS** as Edge Functions no preview branch com versão atual de `main`.
+
+- **Perda silenciosa** — sem confirmation prompt
+- Mudanças in-flight em Edge Functions no preview são **perdidas**
+- Deploy de edge functions via Dashboard alpha é **high-risk**
+
+**Mitigação:** sempre commit Edge Functions em git antes de clicar "Update branch".
+
+### Caveat 4: Delete de functions MANUAL em main
+
+Se você **deleta** uma Edge Function em preview branch, no merge para `main` a deletion **NÃO é propagada automaticamente**.
+
+- Edge Function continua existindo em produção mesmo após merge
+- Você deve **manualmente** executar `supabase functions delete <name>` em main após merge
+
+Cross-ref: GitHub integration (Pattern 3) propaga deletion via git diff — comportamento esperado em production workflow.
+
+### Recomendação canônica explícita
+
+- Para qualquer projeto em produção: **GitHub integration** (Pattern 3)
+- Dashboard alpha aceitável APENAS para:
+  - Experimentação solo (1 dev, sem time)
+  - Prototipagem rápida (sem intenção de production)
+  - Projetos sem migration history estável
+
+### Tabela comparativa Dashboard alpha vs GitHub integration
+
+| | Dashboard alpha | GitHub integration |
+|---|---|---|
+| Custom roles capturados | NÃO | SIM (via migrations) |
+| Merge entre previews | NÃO | SIM (git workflow) |
+| Edge functions safety | Sobrescreve silenciosamente | Versioned via git |
+| Delete propagation | Manual em main | Automatic via merge |
+| Required check enforcement | NÃO | SIM (branch protection rules) |
+| Audit trail | Limited Dashboard logs | Full git history |
+| Maturity | Alpha | Estável (recomendação canônica) |
+| Recomendação | Experimentação solo | Produção |
+
+## Pattern 5: Custo Branching Compute Hours
+
+Branching tem custo **independente** do projeto principal — atenção canônica para evitar surpresas no invoice (BRANCH-05).
+
+### Pricing oficial
+
+- **Micro Compute size** (default para preview branches): **$0.01344/h**
+- **Maior compute sizes** disponíveis para persistent branches via `supabase branches update --size <size>`
+- Cobrança **por hora** (arredonda para hora cheia mesmo em branches curtos)
+
+### Spend Cap canônico — caveat crítico
+
+> **Branching Compute Hours são FORA do Spend Cap do projeto.**
+>
+> Mesmo com Spend Cap configurado em $0 (Pro plan), Branching Compute Hours **continuam sendo cobradas**.
+
+Implicação: equipe que adota branching sem revisar billing pode receber invoice surpresa de $50-200/mês adicional em projetos com muitos PRs.
+
+### Compute Credits NÃO aplicam
+
+- Pro plan vem com **$10/mês de Compute Credits** que cobrem instance do projeto principal
+- **Compute Credits NÃO aplicam a Branching Compute Hours** (FAQ pricing oficial)
+- Cada hora de branch é cobrada **adicionalmente** ao plan base
+
+### Linha de billing canônica
+
+No invoice mensal Supabase, Branching Compute aparece como linha separada:
+
+```
+Pro Plan                              $25.00/mês
+Compute (Project Main)                  $0.00 (covered by Compute Credits)
+Branching Compute Hours        240h × $0.01344 = $3.23/mês
+Database egress                        $0.00 (under threshold)
+                                      -------
+Total                                  $28.23/mês
+```
+
+### Mitigações canônicas
+
+1. **"Supabase changes only" filter ON** (Pattern 3) — preview branch só para PRs com mudanças em `supabase/`
+2. **1 persistent staging** compartilhado em vez de N preview branches (custo previsível)
+3. **PR lifetime curto** — disciplina de team merge em < 1 semana reduz horas acumuladas
+4. **Monitorar billing manualmente** — Spend Cap NÃO protege contra Branching Compute
+5. **Documentar custo esperado** no onboarding do projeto — equipe sabe o trade-off
+
+### Cálculo de capacity planning
+
+Fórmula canônica:
+
+```
+Custo Branching Compute/mês = (N_PRs_ativos × duracao_media_horas × compute_size_hourly_rate)
+
+Exemplo:
+  20 PRs/mês × 48h média × $0.01344/h = $12.90/mês adicional
+```
+
+Para persistent branches:
+
+```
+Custo persistent branch/mês = (24h × 30 dias × compute_size_hourly_rate)
+
+Exemplo (Micro 24/7):
+  720h × $0.01344/h = $9.67/mês por branch persistent
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Usar Dashboard branching alpha para projeto sério
+
+**Errado:** Time de 5+ devs gerencia branches via Dashboard alpha em projeto production.
+
+**Por quê:** custom roles não capturados + edge functions sobrescritas silenciosamente + merge só p/ main = surprise bugs em produção; sem audit trail confiável; sem required check enforcement.
+
+**Certo:** GitHub integration (Pattern 3) — versionado, audit trail completo via git, branch protection rules enforced, deploy DAG transparente com logs por step.
+
+### Anti-pattern 2: Ignorar Spend Cap caveat
+
+**Errado:** Habilitar branching assumindo Spend Cap protege contra cost overrun.
+
+**Por quê:** Branching Compute Hours são **FORA do Spend Cap** — projeto Pro plan com 30 PRs/mês de 72h média pode gerar **$29-100/mês adicional sem alert algum**. Compute Credits NÃO aplicam — cada hora é cobrança nova.
+
+**Certo:**
+
+- monitorar billing manualmente (Settings → Usage → Branching Compute Hours)
+- "Supabase changes only" filter ON (Pattern 3 step 4)
+- considerar persistent branch único compartilhado em vez de 1 preview/PR
+- documentar custo no onboarding do time
+
+### Anti-pattern 3: Tentar merge entre preview branches
+
+**Errado:** Time tenta `preview-feature-A → preview-feature-B` via Dashboard branching.
+
+**Por quê:** Dashboard NÃO suporta merge entre preview branches — só direção `preview → main`. Tentativa resulta em state inconsistente, schemas dessincronizados, ou silent no-op.
+
+**Certo:** combinar features via git workflow:
+
+```
+# PR-A merges to main primeiro
+git checkout main
+git pull
+
+# PR-B rebase on top
+git checkout feature-B
+git rebase main
+git push --force-with-lease
+
+# preview-B é recriado com mudanças de A + B
+# merge to main
+```
+
+### Anti-pattern 4: Push direto na main sem preview branch
+
+**Errado:** Dev pusha migration direto em `main` sem PR/preview branch — "vai dar certo, é só um ALTER TABLE".
+
+**Por quê:** sem validação de DAG → migration falha em production → downtime + rollback complexo + possíveis dados perdidos. Especialmente perigoso para `DROP COLUMN`, `ALTER TYPE`, mudanças destrutivas.
+
+**Certo:** SEMPRE PR + preview branch validado:
+
+1. Migration em PR aberto
+2. Preview branch DAG executa (step 5 migrate validado)
+3. Required check "Supabase Preview" ✓ verde
+4. Merge gated por required check + branch protection rule
+5. (Se "deploy to production" ON) → automatic push para production
+
+Cross-ref skill `evolucao-schema-compativel` (v1.22) — 3-step migration safe para mudanças destrutivas.
+
+### Anti-pattern 5: Esperar persistent branch funcionar como production
+
+**Errado:** Assumir persistent staging branch é "cópia de produção" para QA team.
+
+**Por quê:** branches são **dataless by design** — `seed.sql` é dados sintéticos, não snapshot real. Auth.users separado, sem dados de prod, sem volume real, sem latência real.
+
+**Certo:**
+
+- persistent branches são para **schema/code validation**, NÃO para QA com dados reais
+- Se precisar QA com dados reais → use staging Supabase project **separado** (não branching)
+- Staging project separado tem SLA, dados reais via replicação, custo previsível Pro plan
+
+### Anti-pattern 6: Criar persistent branch sem cleanup policy
+
+**Errado:** Criar persistent branches ad-hoc sem documentar lifecycle ou owner.
+
+**Por quê:** persistent branches não auto-pausam — acumulam Branching Compute Hours **24/7 indefinidamente**. 6 meses depois, ninguém sabe pra que serve o branch `qa-test-old`, mas continua sendo cobrado $9.67/mês × 6 = **$58 desperdiçados**.
+
+**Certo:**
+
+- documentar persistent branches em README ou onboarding doc
+- definir owner por branch (Slack handle + função)
+- review trimestral: `supabase --experimental branches list` + cleanup
+- comment no Dashboard descrevendo propósito + data de criação
+
+## Cross-suite integration (v1.27)
+
+Esta skill é base para skills v1.27 (Phases 150-153):
+
+- **supabase-config-toml-remotes** (Phase 150) — `[remotes]` block + branch-specific config + secrets per-branch
+- **supabase-ci-cd-github-actions** (Phase 151) — 8 workflows canônicos GitHub Actions (preview deploy, prod deploy, migration gates)
+- **supabase-pgtap-testing** (Phase 152) — testes pgTAP que rodam no DAG step 5/6
+- **supabase-migration-repair** (Phase 153) — `migration list/repair` + rollback preview branch quando step migrate falha
+
+Base para agents v1.27 (Phase 154):
+
+- **supabase-branching-architect** — projeta strategy (preview-only vs preview + persistent staging mix)
+- **supabase-cicd-pipeline-implementer** — materializa GitHub Actions workflows + Supabase integration config
+
+Pattern de handoff cooperativo herdado v1.23-v1.26: **architect** projeta → **cicd-pipeline-implementer** materializa → **release-pipeline-auditor** (v1.10) audita hermeticidade do pipeline final. Nenhum agente descarta upstream — handoff cooperativo SQL (princípio canônico v1.23).
+
+## Ver também
+
+- [supabase-config-toml-remotes](../supabase-config-toml-remotes/SKILL.md) (v1.27, Phase 150) — `[remotes]` block + branch-specific config + secrets per-branch
+- [supabase-ci-cd-github-actions](../supabase-ci-cd-github-actions/SKILL.md) (v1.27, Phase 151) — 8 workflows canônicos GitHub Actions
+- [supabase-pgtap-testing](../supabase-pgtap-testing/SKILL.md) (v1.27, Phase 152) — testes pgTAP integrados no DAG
+- [supabase-migration-repair](../supabase-migration-repair/SKILL.md) (v1.27, Phase 153) — `migration list/repair` + rollback preview branch
+- [supabase-migrations](../supabase-migrations/SKILL.md) (v1.23) — 5 blocos obrigatórios CREATE TABLE, naming canônico
+- [supabase-declarative-schema](../supabase-declarative-schema/SKILL.md) — schema declarative workflow (`supabase/schemas/`)
+- [evolucao-schema-compativel](../evolucao-schema-compativel/SKILL.md) (v1.22) — 3-step migration safe rolling upgrade (expand → migrate data → contract)
+- [release-engineering](../release-engineering/SKILL.md) — deployment philosophy + self-service deploys
+- [hermetic-builds](../hermetic-builds/SKILL.md) — pipeline reproducibility + isolation + provenance
+- [supabase-postgres-roles](../supabase-postgres-roles/SKILL.md) (v1.26) — caveat custom roles NÃO capturados em Dashboard alpha (Pattern 4 Caveat 1)
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — Edge Functions deploy no DAG step 7
+- [glossário compartilhado](../_shared-supabase/glossary.md) — termos branching workflow, preview branch, persistent branch, deploy DAG, Branching Compute Hours (será +10 termos em REL-04 v1.27)
+- Doc oficial: [Supabase Branching](https://supabase.com/docs/guides/deployment/branching), [GitHub Integration](https://supabase.com/docs/guides/deployment/branching#github-integration), [Pricing](https://supabase.com/pricing)