@luanpdd/kit-mcp 1.20.0 → 1.21.0

package/kit/skills/audit-log-multi-tenant/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: audit-log-multi-tenant
+description: Use ao implementar audit log em B2B SaaS multi-tenant Supabase — tabela append-only (REVOKE DELETE/UPDATE), 7 event types canônicos, retention pg_cron 3 tiers (30d/90d/365d), legal_hold flag para LGPD erasure, PII sanitization (hash actor_email), tenant_id obrigatório indexed.
+---
+
+# Audit Log Multi-Tenant — Compliance + Forensics
+
+## Quando usar
+
+LLM carrega esta skill ao implementar audit log em B2B SaaS multi-tenant. Trigger phrases:
+
+- "audit log multi-tenant", "audit trail compliance"
+- "append-only table Postgres", "REVOKE DELETE UPDATE"
+- "retention pg_cron tiers"
+- "legal hold LGPD erasure"
+- "PII sanitization audit"
+- "event taxonomy canônica"
+
+Esta skill é consumida pelo agent `audit-log-implementer` (Phase 109) que materializa migration + retention scheduler.
+
+## Regras absolutas
+
+**REGRA #1 (append-only):** Tabela `audit_logs` é **append-only** via `REVOKE DELETE, UPDATE ON public.audit_logs FROM authenticated`. Apenas service_role pode mutar (via partition swap, raramente). Comprometimento de admin não consegue apagar evidências.
+
+**REGRA #2 (tenant_id obrigatório indexed first):** Toda row em `audit_logs` tem `tenant_id` (= `org_id`) **NOT NULL** + index composite `(tenant_id, created_at desc)` como **primeira** coluna. Sem isso, queries "todos eventos da org X" viram table scan.
+
+**REGRA #3 (legal_hold flag):** Coluna `legal_hold boolean default false`. Quando user da org X faz DSR LGPD de erasure, marcar `legal_hold = true` em todas suas rows pendentes — bloqueia delete pelo retention scheduler até DSR processada.
+
+**REGRA #4 (PII sanitization):** `actor_email` e `target_email` armazenados como **SHA-256 hash** (não raw). Para investigação, forensic mode rehasha email candidato e busca match. PII em log = LGPD violation.
+
+**REGRA #5 (retention 3 tiers):** Default retention via pg_cron:
+- **Free tier**: 30 dias
+- **Pro tier**: 90 dias
+- **Enterprise tier**: 365 dias
+- **Sempre respeitando legal_hold = true** (skip rows com legal hold)
+
+**REGRA #6 (event taxonomy mínima — 7 events):** `login`, `member_invited`, `role_changed`, `data_exported`, `member_removed`, `settings_changed`, `super_admin_action`. Custom events permitidos via campo `event_type text` mas estes 7 são obrigatórios em qualquer app B2B.
+
+## Patterns canônicos
+
+### Tabela `audit_logs` — DDL completo
+
+```sql
+-- Tabela append-only, particionada por tenant_id (LIST partitioning) se >50k rows/tenant
+create table public.audit_logs (
+  id uuid not null default gen_random_uuid(),
+  tenant_id uuid not null references public.organizations(id) on delete cascade,
+  event_type text not null check (event_type ~ '^[a-z_]+$'),
+  actor_id uuid references auth.users(id) on delete set null,  -- NULL após erasure
+  actor_email_hash text,                                        -- SHA-256, REGRA #4
+  target_id uuid,                                               -- ID do recurso afetado (lead, member, etc.)
+  target_type text,                                             -- 'lead', 'member', 'org', etc.
+  target_email_hash text,                                       -- SHA-256 do email se aplicável
+  payload jsonb,                                                -- detalhes do evento (campos changed, etc.)
+  ip_address inet,                                              -- IP de origem (opcional)
+  user_agent text,                                              -- UA (opcional)
+  legal_hold boolean not null default false,                    -- REGRA #3
+  created_at timestamptz not null default now(),
+  primary key (id, tenant_id),                                  -- composite para particionamento
+  -- REGRA #2: index composite tenant_id first
+  constraint event_type_canonical check (
+    event_type in (
+      'login', 'member_invited', 'role_changed', 'data_exported',
+      'member_removed', 'settings_changed', 'super_admin_action'
+    ) or event_type ~ '^custom_[a-z_]+$'  -- custom events com prefix
+  )
+);
+
+-- Index composite tenant_id first (REGRA #2)
+create index audit_logs_tenant_created_idx
+  on public.audit_logs (tenant_id, created_at desc);
+
+-- Index para busca por actor (compliance investigation)
+create index audit_logs_actor_id_idx
+  on public.audit_logs (actor_id, created_at desc) where actor_id is not null;
+
+-- Index para legal hold (rotina retention precisa filtrar)
+create index audit_logs_legal_hold_idx
+  on public.audit_logs (legal_hold, created_at) where legal_hold = false;
+
+-- REGRA #1: append-only — REVOKE DELETE e UPDATE
+alter table public.audit_logs enable row level security;
+
+revoke delete on public.audit_logs from authenticated, anon;
+revoke update on public.audit_logs from authenticated, anon;
+-- service_role bypassa RLS — partition swap futuro é o único delete legítimo
+
+-- POLICY SELECT: members da org com permission view:audit_logs
+create policy "audit_logs_select_with_permission"
+  on public.audit_logs
+  for select
+  to authenticated
+  using (
+    private.has_permission('view', 'audit_logs', tenant_id)
+  );
+
+-- POLICY INSERT: qualquer authenticated pode inserir (helper function escreve via SECURITY DEFINER)
+create policy "audit_logs_insert_authenticated"
+  on public.audit_logs
+  for insert
+  to authenticated
+  with check (
+    tenant_id is not null
+    and event_type is not null
+  );
+
+-- POLICY super_admin bypass (PERMISSIVE)
+create policy "audit_logs_super_admin_bypass"
+  on public.audit_logs
+  as permissive
+  for select
+  to authenticated
+  using (private.is_super_admin());
+```
+
+### Helper function — emit audit event
+
+```sql
+-- SECURITY DEFINER porque precisa hash email mesmo se user não tiver INSERT direto
+create or replace function private.audit_log(
+  p_event_type text,
+  p_tenant_id uuid,
+  p_target_id uuid default null,
+  p_target_type text default null,
+  p_target_email text default null,
+  p_payload jsonb default null
+)
+returns void
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_actor_id uuid;
+  v_actor_email text;
+begin
+  v_actor_id := (select auth.uid());
+  select email into v_actor_email from auth.users where id = v_actor_id;
+
+  insert into public.audit_logs (
+    tenant_id,
+    event_type,
+    actor_id,
+    actor_email_hash,
+    target_id,
+    target_type,
+    target_email_hash,
+    payload
+  )
+  values (
+    p_tenant_id,
+    p_event_type,
+    v_actor_id,
+    case when v_actor_email is not null then encode(digest(v_actor_email, 'sha256'), 'hex') end,
+    p_target_id,
+    p_target_type,
+    case when p_target_email is not null then encode(digest(p_target_email, 'sha256'), 'hex') end,
+    p_payload
+  );
+end;
+$$;
+
+-- Permitir authenticated chamar
+grant execute on function private.audit_log(text, uuid, uuid, text, text, jsonb) to authenticated;
+```
+
+### Retention via pg_cron — 3 tiers
+
+```sql
+-- Schedule diário 03:00 UTC — apaga rows velhas respeitando legal_hold
+select cron.schedule(
+  'audit-log-retention',
+  '0 3 * * *',
+  $$
+    -- Free tier orgs: 30 dias
+    delete from public.audit_logs al
+    using public.organizations o
+    where al.tenant_id = o.id
+      and o.plan = 'free'
+      and al.created_at < now() - interval '30 days'
+      and al.legal_hold = false;
+
+    -- Pro tier orgs: 90 dias
+    delete from public.audit_logs al
+    using public.organizations o
+    where al.tenant_id = o.id
+      and o.plan = 'pro'
+      and al.created_at < now() - interval '90 days'
+      and al.legal_hold = false;
+
+    -- Enterprise tier orgs: 365 dias
+    delete from public.audit_logs al
+    using public.organizations o
+    where al.tenant_id = o.id
+      and o.plan = 'enterprise'
+      and al.created_at < now() - interval '365 days'
+      and al.legal_hold = false;
+  $$
+);
+```
+
+**Nota:** o DELETE acima é executado pelo pg_cron com role `postgres` (bypassa RLS). NÃO é `authenticated` — REGRA #1 não é violada.
+
+### Emit eventos canônicos — exemplos
+
+```sql
+-- Login (após auth callback)
+select private.audit_log(
+  p_event_type := 'login',
+  p_tenant_id := <org_id>,
+  p_payload := jsonb_build_object('ip', '<ip>', 'user_agent', '<ua>')
+);
+
+-- Member invited
+select private.audit_log(
+  p_event_type := 'member_invited',
+  p_tenant_id := <org_id>,
+  p_target_id := <invited_user_id>,
+  p_target_email := <invited_email>,
+  p_payload := jsonb_build_object('role', 'admin', 'invited_by', '<actor_email_hash>')
+);
+
+-- Role changed
+select private.audit_log(
+  p_event_type := 'role_changed',
+  p_tenant_id := <org_id>,
+  p_target_id := <member_user_id>,
+  p_payload := jsonb_build_object('from_role', 'member', 'to_role', 'admin')
+);
+
+-- super_admin action (chamado pelo trigger gerado por multi-tenant-rls-writer)
+select private.audit_log(
+  p_event_type := 'super_admin_action',
+  p_tenant_id := <target_org_id>,
+  p_payload := jsonb_build_object('table', 'leads', 'op', 'DELETE', 'reason', 'cleanup')
+);
+```
+
+### Query forensics — investigar incident
+
+```sql
+-- "Quem deletou todos os leads da org X em 2026-04-15?"
+select
+  al.created_at,
+  al.event_type,
+  al.actor_email_hash,  -- hash, mas pode rehasher candidates
+  al.payload
+from public.audit_logs al
+where al.tenant_id = '<org_id>'
+  and al.created_at::date = '2026-04-15'
+  and al.event_type in ('super_admin_action', 'data_exported')
+  and al.payload->>'table' = 'leads'
+order by al.created_at;
+
+-- Match actor por email (forensics) — calcular hash do email candidato
+select * from public.audit_logs
+where actor_email_hash = encode(digest('admin@acme.com', 'sha256'), 'hex')
+  and tenant_id = '<org_id>'
+order by created_at desc
+limit 100;
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Tabela audit_logs sem REVOKE
+
+**Errado:**
+```sql
+create table public.audit_logs (...);
+alter table public.audit_logs enable row level security;
+-- Sem REVOKE — admin pode delete via UPDATE policy
+```
+
+**Por quê:** atacante ou admin compromised pode `DELETE FROM audit_logs WHERE event_type = 'super_admin_action'` e apagar evidências de acesso indevido.
+
+**Certo:** `REVOKE DELETE, UPDATE ON public.audit_logs FROM authenticated, anon;`
+
+### Anti-pattern 2: actor_email/target_email em raw
+
+**Errado:**
+```sql
+create table public.audit_logs (
+  ...
+  actor_email text,    -- raw email
+  target_email text    -- raw email
+);
+```
+
+**Por quê:** PII em audit log = LGPD violation. DSR de erasure de user X torna-se complexo (precisa anonimizar todas as rows com email do user).
+
+**Certo:** SHA-256 hash. Para forensics, rehasher email candidato e buscar match.
+
+### Anti-pattern 3: Retention sem respeitar legal_hold
+
+**Errado:**
+```sql
+delete from public.audit_logs where created_at < now() - interval '30 days';
+-- Sem filter legal_hold
+```
+
+**Por quê:** apaga evidências necessárias para responder DSR LGPD em curso. Legal violation.
+
+**Certo:** `... and legal_hold = false`. Quando DSR processada, marcar `legal_hold = false` permite next retention run.
+
+### Anti-pattern 4: tenant_id ausente ou nullable
+
+**Errado:**
+```sql
+tenant_id uuid -- nullable
+```
+
+**Por quê:** queries "todos eventos da org X" precisam filtrar por tenant_id. NULL quebra filter (`tenant_id = $1` exclui NULLs). Index composite (tenant_id, created_at) menos eficaz com NULLs.
+
+**Certo:** `tenant_id uuid not null references public.organizations(id) on delete cascade`. NOT NULL + FK garante consistência.
+
+### Anti-pattern 5: Single audit_logs sem partitioning para org grande
+
+**Errado:**
+```sql
+-- Org enterprise com 10M events/ano em tabela única
+```
+
+**Por quê:** vacuum lento, queries lentas, retention DELETE bloqueia outras escritas.
+
+**Certo:** LIST partitioning por `tenant_id` (ver [`multi-tenant-performance-scaling`](../multi-tenant-performance-scaling/SKILL.md)). Cada org = partição própria. Retention vira `DROP TABLE <partition>` (instantâneo).
+
+## Ver também
+
+- [supabase-cron-queues](../supabase-cron-queues/SKILL.md) — pg_cron pattern usado para retention scheduler (cross-suite)
+- [multi-tenant-performance-scaling](../multi-tenant-performance-scaling/SKILL.md) — partitioning por org_id (REGRA #5)
+- [multi-tenant-rls-hierarchy](../multi-tenant-rls-hierarchy/SKILL.md) — `private.is_super_admin` + super_admin trigger pattern
+- [lgpd-multi-tenant-compliance](../lgpd-multi-tenant-compliance/SKILL.md) — Phase 114, integração com legal_hold
+- [super-admin-platform-pattern](../super-admin-platform-pattern/SKILL.md) — Phase 111, `super_admin_action` event obrigatório
+- [_shared-multi-tenant/glossary.md](../_shared-multi-tenant/glossary.md) — termos `audit log`, `event taxonomy`, `legal hold`, `PII sanitization`

package/kit/skills/b2b-saas-architecture/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: b2b-saas-architecture
+description: Use ao desenhar app B2B multi-tenant (org→department→leader→collaborator) com Supabase + React — Single Schema + org_id + RLS é default; JWT minimal (super_admin: bool); 7 tabelas canônicas; slug imutável.
+---
+
+# B2B SaaS Multi-Tenant — Arquitetura Canônica
+
+## Quando usar
+
+LLM carrega esta skill ao desenhar arquitetura de app B2B SaaS multi-tenant em Supabase. Trigger phrases:
+
+- "B2B SaaS multi-tenant", "arquitetura multi-tenant", "isolation strategy"
+- "single schema vs schema-per-tenant"
+- "schema canônico organizations", "departments table", "members"
+- "JWT claims multi-tenant", "app_metadata orgs"
+- "slug org imutável", "tenant routing"
+
+Esta skill define o **schema canônico** que `multi-tenant-rls-writer` (Phase 108), `org-onboarding-implementer` (Phase 107), `super-admin-implementer` (Phase 111), `audit-log-implementer` (Phase 109), e demais agents da suíte v1.21 consomem como entrada.
+
+## Regras absolutas
+
+**REGRA #1 (estratégia default):** **Single Schema + `org_id` + RLS** é o caminho canônico para 90% dos B2B SaaS. Schema-per-tenant é justificado apenas em compliance extremo (saúde/jurídico com auditoria isolacional). Database-per-tenant é inviável economicamente fora de contratos enterprise.
+
+**REGRA #2 (JWT minimal):** **APENAS** `super_admin: bool` em `app_metadata`. Lista de orgs no JWT é anti-pattern — bloat linear no token + stale de 1h após mudança de role. O banco (helper functions PG) é fonte de verdade.
+
+**REGRA #3 (slug imutável):** `organizations.slug` é **append-only** após criação. Mutação requer tabela `slug_history` + redirect 301 em rotas afetadas. Quebra silenciosa de bookmarks/webhooks/OAuth callbacks é o pior bug que cliente B2B encontra.
+
+**REGRA #4 (super_admin via service_role):** `app_metadata.super_admin = true` é setado **APENAS** via `auth.admin.updateUserById()` (service role). Cliente NUNCA consegue mutá-lo (≠ `user_metadata` que é editável).
+
+**REGRA #5 (FKs com CASCADE explícito):** Todas as FKs têm `ON DELETE` explícito (CASCADE para entidades dependentes da org, RESTRICT para evitar deleção acidental). Sem default — força decisão consciente.
+
+## Patterns canônicos
+
+### Estratégia de isolation — tabela comparativa
+
+| Estratégia | Isolation | Custo ops | Compliance | Quando usar |
+|---|---|---|---|---|
+| **Single Schema + `org_id` + RLS** ⭐ | Lógico (RLS) | Baixo | Padrão B2B SaaS | **DEFAULT 90% dos casos** — Stripe, Linear, Vercel, Notion |
+| Schema-per-tenant | Físico (PG schemas) | Médio (N migrations) | Compliance auditável | Saúde/jurídico/governo com requisito explícito de isolamento |
+| Database-per-tenant | Físico (DB separadas) | Alto (N projects Supabase) | Compliance extremo | Apenas contratos enterprise com SLA de isolamento físico |
+
+**Recomendação:** comece sempre com Single Schema. Migração para schema-per-tenant é viável (script de fan-out por org_id). Migração reversa não é.
+
+### Schema canônico — 7 tabelas (DDL completo)
+
+```sql
+-- Ordem de criação respeita dependências FK
+
+-- 1. organizations (root tenant)
+create table public.organizations (
+  id uuid primary key default gen_random_uuid(),
+  name text not null,
+  slug text unique not null check (slug ~ '^[a-z0-9-]+$' and length(slug) between 2 and 60),
+  owner_id uuid not null references auth.users(id) on delete restrict,
+  plan text not null default 'free' check (plan in ('free', 'pro', 'enterprise')),
+  status text not null default 'active' check (status in ('active', 'suspended', 'archived')),
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+-- 2. departments (sub-tenant opcional)
+create table public.departments (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references public.organizations(id) on delete cascade,
+  parent_id uuid references public.departments(id) on delete set null,
+  name text not null,
+  slug text not null check (slug ~ '^[a-z0-9-]+$'),
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  unique (org_id, slug)
+);
+
+-- 3. roles (org-scoped, custom roles permitidos)
+create table public.roles (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references public.organizations(id) on delete cascade,
+  name text not null check (name ~ '^[a-z_]+$'),
+  description text,
+  is_built_in boolean not null default false,
+  created_at timestamptz not null default now(),
+  unique (org_id, name)
+);
+
+-- 4. permissions (catálogo global)
+create table public.permissions (
+  id uuid primary key default gen_random_uuid(),
+  action text not null check (action ~ '^[a-z_]+$'),
+  resource text not null check (resource ~ '^[a-z_]+$'),
+  description text,
+  created_at timestamptz not null default now(),
+  unique (action, resource)
+);
+
+-- 5. role_permissions (M:N — roles ganham permissions)
+create table public.role_permissions (
+  role_id uuid not null references public.roles(id) on delete cascade,
+  permission_id uuid not null references public.permissions(id) on delete restrict,
+  created_at timestamptz not null default now(),
+  primary key (role_id, permission_id)
+);
+
+-- 6. organization_members (user ↔ org com role)
+create table public.organization_members (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references public.organizations(id) on delete cascade,
+  user_id uuid not null references auth.users(id) on delete cascade,
+  role_id uuid not null references public.roles(id) on delete restrict,
+  status text not null default 'active' check (status in ('active', 'suspended', 'left')),
+  joined_at timestamptz not null default now(),
+  unique (org_id, user_id)
+);
+
+-- 7. department_members (user ↔ dept com role override opcional)
+create table public.department_members (
+  id uuid primary key default gen_random_uuid(),
+  dept_id uuid not null references public.departments(id) on delete cascade,
+  user_id uuid not null references auth.users(id) on delete cascade,
+  role_id uuid references public.roles(id) on delete set null, -- NULL herda do organization_members
+  is_leader boolean not null default false,
+  joined_at timestamptz not null default now(),
+  unique (dept_id, user_id)
+);
+
+-- Slug history (suporte a redirect 301 quando slug é mutado)
+create table public.organization_slug_history (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references public.organizations(id) on delete cascade,
+  old_slug text not null,
+  new_slug text not null,
+  changed_at timestamptz not null default now(),
+  unique (old_slug)
+);
+```
+
+### JWT claims minimal — Custom Access Token Hook
+
+```sql
+-- Hook chamado pelo Supabase Auth a cada token emit
+-- Injeta apenas super_admin no app_metadata
+create or replace function public.custom_access_token_hook(event jsonb)
+returns jsonb
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  claims jsonb;
+  is_super boolean;
+begin
+  -- Buscar super_admin do app_metadata atual
+  select coalesce((raw_app_meta_data->>'super_admin')::boolean, false)
+  into is_super
+  from auth.users
+  where id = (event->>'user_id')::uuid;
+
+  claims := event->'claims';
+  claims := jsonb_set(claims, '{app_metadata}', coalesce(claims->'app_metadata', '{}'::jsonb));
+  claims := jsonb_set(claims, '{app_metadata,super_admin}', to_jsonb(is_super));
+
+  event := jsonb_set(event, '{claims}', claims);
+  return event;
+end;
+$$;
+
+-- Registrar como hook em supabase/config.toml:
+-- [auth.hook.custom_access_token]
+-- enabled = true
+-- uri = "pg-functions://postgres/public/custom_access_token_hook"
+```
+
+### Set super_admin via service_role apenas
+
+```typescript
+// Edge Function ou backend admin com service_role key
+import { createClient } from 'jsr:@supabase/supabase-js@2'
+
+const admin = createClient(
+  Deno.env.get('SUPABASE_URL')!,
+  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!  // service role — nunca expor ao client
+)
+
+// Promover usuário a super_admin
+await admin.auth.admin.updateUserById(userId, {
+  app_metadata: { super_admin: true }
+})
+
+// IMPORTANTE: usar updateUserById com app_metadata (não user_metadata)
+```
+
+### Slug com redirect trail
+
+```sql
+-- Trigger que registra mudança de slug em organization_slug_history
+create or replace function public.track_org_slug_change()
+returns trigger
+language plpgsql
+security invoker
+set search_path = ''
+as $$
+begin
+  if old.slug is distinct from new.slug then
+    insert into public.organization_slug_history (org_id, old_slug, new_slug)
+    values (new.id, old.slug, new.slug);
+  end if;
+  return new;
+end;
+$$;
+
+create trigger track_org_slug_change_trigger
+  after update of slug on public.organizations
+  for each row execute function public.track_org_slug_change();
+```
+
+App side (Next.js middleware): se `slug` em URL não existe em `organizations`, consulta `organization_slug_history.old_slug` → 301 para `/orgs/{new_slug}/`.
+
+## Anti-patterns
+
+### Anti-pattern 1: Lista de orgs no JWT (claims bloat + stale)
+
+**Errado:**
+```sql
+-- Hook injeta lista de orgs do user no JWT
+-- claims.app_metadata.orgs = [{id, role}, {id, role}, ...]
+```
+
+**Por quê:**
+- JWT tem limite ~4KB — usuário em 50 orgs estoura
+- JWT cacheado por 1h — mudança de role demora até 1h pra propagar
+- Cada Edge Function paga overhead de parsing de claims grandes
+
+**Certo:** JWT só com `super_admin: bool`. Helper functions PG (`private.is_member_of`, `private.has_role`) consultam o banco — fonte de verdade sem stale.
+
+### Anti-pattern 2: Slug mutável sem redirect trail
+
+**Errado:**
+```sql
+update public.organizations set slug = 'new-name' where id = '...';
+-- Sem entry em organization_slug_history
+```
+
+**Por quê:** bookmarks externos, webhooks Stripe/Slack, OAuth callbacks, Twitter cards, sitemaps — todos quebram silenciosamente. Cliente B2B descobre semanas depois quando recebe email "seu link parou de funcionar".
+
+**Certo:** trigger `track_org_slug_change` automático + middleware redirect 301 em rotas com slug.
+
+### Anti-pattern 3: Schema-per-tenant sem justificativa de compliance
+
+**Errado:**
+```sql
+-- Pra cada nova org, criar schema próprio
+create schema "org_acme";
+create table org_acme.members (...);
+-- ...repetir migration por org
+```
+
+**Por quê:** N migrations por nova org, provisioning lento, queries cross-tenant impossíveis sem UNION manual, monitoring complexo. Sem ganho real para SaaS comum (RLS bem feita já isola).
+
+**Certo:** Single Schema + `org_id` + RLS. Schema-per-tenant só quando regulatório exige.
+
+### Anti-pattern 4: `user_metadata` para super_admin
+
+**Errado:**
+```sql
+-- Policy lê super_admin de user_metadata
+using ((auth.jwt()->'user_metadata'->>'super_admin')::boolean = true)
+```
+
+**Por quê:** `user_metadata` é editável pelo cliente via `auth.updateUser({ data: { super_admin: true } })`. Privilege escalation imediato — qualquer usuário se torna super_admin. Documentado em [Supabase Splinter 0015](https://supabase.github.io/splinter/0015_rls_references_user_metadata/).
+
+**Certo:** `app_metadata.super_admin` (set apenas via service_role).
+
+### Anti-pattern 5: FKs sem CASCADE/RESTRICT explícito
+
+**Errado:**
+```sql
+references public.organizations(id)  -- default ON DELETE NO ACTION
+```
+
+**Por quê:** decisão importante (deletar org com 100k rows? bloquear?) fica implícita. NO ACTION pode falhar deleção sem mensagem clara. Comportamento varia por engine.
+
+**Certo:**
+```sql
+references public.organizations(id) on delete cascade   -- entidade dependente
+references auth.users(id) on delete restrict            -- prevenir orfão
+references public.roles(id) on delete set null          -- preservar histórico
+```
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — anti-patterns RLS herdados (`(select auth.uid())` wrapper, no `user_metadata` em authz)
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — padrões PG functions (security invoker, search_path = '')
+- [supabase-postgres-style](../supabase-postgres-style/SKILL.md) — naming snake_case, lowercase reserved
+- [multi-tenant-rls-hierarchy](../multi-tenant-rls-hierarchy/SKILL.md) — 4 helper functions PG canônicas + policies hierárquicas (Phase 108)
+- [multi-tenant-performance-scaling](../multi-tenant-performance-scaling/SKILL.md) — Supavisor pooling + partitioning por `org_id` + MVs per-tenant (skill irmã)
+- [rbac-permissions-matrix-supabase](../rbac-permissions-matrix-supabase/SKILL.md) — modelagem permissions action × resource × scope (Phase 108)
+- [_shared-supabase/glossary.md](../_shared-supabase/glossary.md) — termos canônicos `app_metadata`, `service_role`
+- [_shared-multi-tenant/glossary.md](../_shared-multi-tenant/glossary.md) — termos novos `tenant`, `org_id`, `super_admin`, `RBAC`
+- [Supabase RLS Best Practices](https://makerkit.dev/blog/tutorials/supabase-rls-best-practices) — fonte external canônica
+- [Custom Access Token Hook — Supabase Docs](https://supabase.com/docs/guides/auth/auth-hooks/custom-access-token-hook)