nexus-core-v3 3.0.0

package/tasks/db-dry-run.md

@@ -0,0 +1,50 @@
+---
+id: db-dry-run
+agent: data-engineer
+title: Testar uma migration sem commitar (dry-run)
+inputs: [migration (path)]
+outputs: [relatório de dry-run (sucesso/erro, objetos afetados, avisos)]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Testar uma migration sem commitar (dry-run)
+
+**Objetivo:** rodar a migration dentro de uma transação que é sempre revertida no fim, para descobrir
+erros, conflitos e efeitos colaterais **antes** de aplicar de verdade — sem alterar o banco.
+
+**Pré-condições:**
+- A migration existe no path informado.
+- Há um ambiente de teste/dev acessível (`db-env-check` ok). Nunca rodo dry-run contra produção sem
+  justificativa explícita — prefiro um clone/staging.
+
+## Passos
+
+1. **Abra uma transação** (`BEGIN`) no ambiente de teste. Tudo aqui dentro vai ser descartado no fim —
+   por isso é seguro.
+2. **Execute o DDL/DML da migration** dentro dessa transação, capturando cada erro com a linha/objeto
+   que o causou.
+3. **Colete os efeitos:** quais objetos seriam criados/alterados/removidos, quais constraints e FKs
+   entram, se o baseline (`id`/`created_at`/`updated_at`) está presente nas tabelas novas.
+4. **Sinalize riscos:** FK sem índice, coluna `NOT NULL` sem default em tabela com dados, operação que
+   reescreve tabela grande (lock), tabela pública sem RLS. Aviso, não silencio.
+5. **Reverta sempre** (`ROLLBACK`) ao final — com sucesso ou com erro. O dry-run **nunca** deixa
+   resíduo no banco.
+6. **Emita o relatório:** veredito (passa / falha), objetos afetados, avisos e a recomendação (seguir
+   para `db-verify-order` + `db-apply-migration`, ou corrigir antes).
+
+## Critério de pronto (DoD)
+
+- [ ] Migration executada dentro de transação revertida (`ROLLBACK` garantido)
+- [ ] Objetos afetados e avisos de risco listados
+- [ ] Veredito claro: passa para aplicação ou volta para correção
+- [ ] Nenhum resíduo deixado no banco
+
+## Falha / recuperação
+
+- **A migration falha no dry-run** → ótimo, foi exatamente pra isso. Reporto o erro com objeto/linha e
+  devolvo para correção; **não** sigo para `db-apply-migration`.
+- **O `ROLLBACK` não pôde ser garantido** (ex.: comando que faz commit implícito) → HALT, aviso que a
+  migration não é dry-run-safe e exijo refatorá-la antes de qualquer aplicação real.
+- **Sem ambiente de teste disponível** → escalo para o @devops provisionar; não rodo dry-run em
+  produção como atalho.

package/tasks/db-env-check.md

@@ -0,0 +1,57 @@
+---
+id: db-env-check
+agent: data-engineer
+title: Validar variáveis de ambiente do banco
+inputs: [ambiente alvo (local/staging/prod)]
+outputs: [relatório de validação, veredito GO/NO-GO para operar o banco]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Validar variáveis de ambiente do banco
+
+**Objetivo:** confirmar que as variáveis de ambiente do banco estão presentes, coerentes e seguras
+antes de qualquer operação — para nenhuma task de banco rodar às cegas ou contra o alvo errado.
+
+**Pré-condições:**
+- Existe uma fonte de configuração de ambiente (`.env`, variáveis exportadas, ou config do projeto).
+  Se nenhuma fonte existe, **pare** e reporte: não há o que validar.
+- O ambiente alvo está claro (local, staging ou prod). Se ambíguo, elicito qual — operar no alvo
+  errado é o pior erro de banco que existe.
+
+## Passos
+
+1. **Liste as variáveis exigidas** pelo ambiente alvo: host, porta, nome do banco, usuário, senha/
+   credencial, e — em Supabase — URL do projeto, anon key e service role key.
+2. **Verifique presença e formato** de cada variável. Vazia, ausente ou malformada (URL inválida,
+   porta não numérica) é falha imediata para aquele item.
+3. **Cheque coerência de alvo:** o host/URL aponta para o ambiente declarado? Uma string de produção
+   num check de "local" é **NO-GO** — sinalizo antes que alguém escreva no lugar errado.
+4. **Valide a postura de segurança:** em produção, exijo Pooler com `sslmode=require`. Service role
+   bypassa RLS — confirmo que está presente só onde é justificado e nunca exposto em cliente.
+5. **Teste a conexão** com uma query trivial e read-only (`SELECT 1`), sem escrever nada. Confirma que
+   a credencial conecta de fato, não só que a string existe.
+6. **Redija os segredos** no relatório: presença e formato são reportados como OK/FALHA, nunca o valor
+   inteiro de senha ou token.
+7. **Emita o veredito:** **GO** (todas as variáveis presentes, coerentes, conexão OK) ou **NO-GO**
+   (lista objetiva do que falta ou está errado, com o que corrigir).
+
+## Critério de pronto (DoD)
+
+- [ ] Todas as variáveis exigidas pelo alvo verificadas (presença + formato)
+- [ ] Coerência de alvo confirmada (host/URL bate com o ambiente declarado)
+- [ ] Postura de segurança validada (SSL em prod; service role só onde justificado)
+- [ ] Conexão testada com query read-only
+- [ ] Segredos redigidos no relatório (nunca valor inteiro)
+- [ ] Veredito GO/NO-GO emitido com itens acionáveis no caso de NO-GO
+
+## Falha / recuperação
+
+- **Variável ausente ou malformada** → **NO-GO**; reporto exatamente qual e o formato esperado, sem
+  adivinhar o valor.
+- **Alvo incoerente** (string de prod num check de local) → **NO-GO** imediato e **HALT** em qualquer
+  operação subsequente até a correção.
+- **Conexão falha** → reporto o erro bruto (redigido) e o veredito NO-GO; nenhuma task de banco deve
+  prosseguir.
+- **Segredo exposto em cliente ou local inseguro** → sinalizo como achado de segurança e bloqueio até
+  remediar; gestão de MCP/infra de credencial, se necessária, é delegada ao @devops.

package/tasks/db-load-csv.md

@@ -0,0 +1,54 @@
+---
+id: db-load-csv
+agent: data-engineer
+title: Carregar CSV com segurança (staging → merge)
+inputs: [table, file, story]
+outputs: [linhas carregadas idempotentemente, relatório de rejeitadas]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Carregar CSV com segurança (staging → merge)
+
+**Objetivo:** carregar um CSV numa tabela alvo de forma idempotente e segura — via tabela de staging e
+merge por chave — sem corromper dados existentes nem quebrar no replay.
+
+**Pré-condições:**
+- O arquivo CSV existe em `file` e a tabela alvo `table` existe. Se faltar qualquer um, **pare** e
+  reporte.
+- A tabela alvo tem chave natural ou única para o merge (ex.: `email`, `external_id`). Sem chave de
+  conflito, o merge não tem como ser idempotente — **pare** e peça a chave.
+
+## Passos
+
+1. **Snapshot antes de carregar** (`*snapshot load-{table}`): carga em massa é mudança de dados;
+   preciso do ponto de rollback.
+2. **Inspecione o CSV:** cabeçalho, encoding, delimitador, tipos por coluna e amostra de linhas. Mapeie
+   colunas do CSV → colunas da tabela. Mapeamento ambíguo eu elicito — não adivinho coluna.
+3. **Crie a staging idempotente:** `CREATE TABLE IF NOT EXISTS stg_{table} (...)` com os tipos do CSV
+   (texto onde houver dúvida, para validar antes de converter). `TRUNCATE stg_{table};` antes de cada
+   carga.
+4. **Carregue na staging** (`COPY stg_{table} FROM ...` ou loader equivalente). Sem auto-commit na
+   alvo: a alvo só é tocada após validação.
+5. **Valide na staging:** tipos convertem? NOT NULL respeitado? duplicatas na chave de conflito?
+   linhas inválidas vão para um relatório de rejeitadas — não barram as válidas, mas são reportadas.
+6. **Merge idempotente em transação:** `BEGIN; INSERT INTO {table} (...) SELECT ... FROM stg_{table}
+   ON CONFLICT ({chave}) DO UPDATE/NOTHING; COMMIT;`. Rodar de novo não duplica nem corrompe.
+7. **Reconcilie:** linhas no CSV vs. válidas vs. carregadas vs. rejeitadas. Os números têm que fechar.
+8. **Limpe a staging** se for descartável, ou deixe-a para auditoria conforme a story pedir.
+
+## Critério de pronto (DoD)
+
+- [ ] Snapshot criado antes da carga
+- [ ] Carga via staging + merge por chave de conflito (idempotente no replay)
+- [ ] Merge rodou em transação (sem estado parcial na alvo)
+- [ ] Linhas rejeitadas reportadas; contagens reconciliam (CSV = válidas + rejeitadas)
+- [ ] Mapeamento de colunas rastreia à story/spec — nada inventado
+
+## Falha / recuperação
+
+- **Sem chave de conflito** → **pare**; merge idempotente é impossível sem ela.
+- **Erro no merge** → `ROLLBACK` deixou a alvo intacta; investigo na staging e repito. Se preciso,
+  `*rollback load-{table}`.
+- **Muitas linhas rejeitadas** → suspendo e reporto a qualidade do CSV em vez de empurrar dado sujo.
+- **Subir o resultado (push/PR)** → delego ao @devops. Eu carrego no banco, não faço push.

package/tasks/db-policy-apply.md

@@ -0,0 +1,58 @@
+---
+id: db-policy-apply
+agent: data-engineer
+title: Instalar política RLS numa tabela
+inputs: [table, mode, story]
+outputs: [política RLS aplicada, casos de teste positivo/negativo, snapshot]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Instalar política RLS numa tabela
+
+**Objetivo:** habilitar Row Level Security e instalar a política de acesso de uma tabela — no modo
+KISS (dono-só) ou granular — de forma idempotente e reversível, rastreando à story/spec.
+
+**Pré-condições:**
+- A tabela existe e tem a coluna de posse esperada (ex.: `user_id`/`owner_id`). Se não tiver, **pare**
+  e devolva ao design de schema — RLS sem coluna de posse não tem como filtrar.
+- Existe camada de auth (Supabase Auth ou equivalente). Sem ela, `auth.uid()` retorna NULL — aviso
+  explicitamente que a política vai negar tudo.
+- O `mode` é `kiss` (dono lê/escreve só o que é dele) ou `granular` (regras por operação/role). Se
+  ambíguo, elicito — não invento a regra de acesso.
+
+## Passos
+
+1. **Snapshot antes de tocar** (`*snapshot policy-{table}`): RLS é mudança de schema; preciso de ponto
+   de rollback antes de qualquer `ALTER`.
+2. **Confirme a regra de acesso na story/spec.** Quem pode ler? Quem pode escrever? Há leitura pública?
+   A regra rastreia a um requisito — não deduzo permissão por conta própria.
+3. **Habilite RLS idempotente:** `ALTER TABLE {table} ENABLE ROW LEVEL SECURITY;` (seguro repetir).
+   Sem isso a tabela fica aberta mesmo com política definida.
+4. **Escreva a(s) política(s)** com `DROP POLICY IF EXISTS ... ; CREATE POLICY ...` para idempotência:
+   - **kiss:** uma política `USING (auth.uid() = user_id)` + `WITH CHECK` igual, cobrindo SELECT/
+     INSERT/UPDATE/DELETE do dono.
+   - **granular:** políticas separadas por comando/role, cada uma justificada pela regra de acesso.
+5. **Aplique em transação** (via `*run-sql` ou `*apply-migration`): `BEGIN; ... COMMIT;`. Erro =
+   `ROLLBACK` automático, tabela intacta.
+6. **Valide com `*test-as-user`** (positivo E negativo): o dono enxerga o dele; um terceiro NÃO enxerga
+   nem altera. Política sem teste negativo é política não-comprovada.
+7. **Registre** a política e os casos de teste no rastro da story (File List / nota de banco).
+
+## Critério de pronto (DoD)
+
+- [ ] RLS habilitada na tabela e política(s) criada(s) de forma idempotente
+- [ ] Teste positivo passa (dono acessa o dele) e teste negativo passa (terceiro é bloqueado)
+- [ ] Snapshot criado antes da aplicação; rollback possível
+- [ ] Regra de acesso rastreia à story/spec — nada inventado
+- [ ] Aplicação rodou em transação (sem estado parcial)
+
+## Falha / recuperação
+
+- **`auth.uid()` é NULL (sem auth)** → política nega tudo; **pare**, sinalize a dependência de auth e
+  não declare pronto.
+- **Teste negativo falha (terceiro enxerga o dado)** → política está vazando; reverto via snapshot,
+  corrijo o predicado e revalido. Não entrego com vazamento.
+- **Erro na aplicação** → `ROLLBACK` deixou a tabela intacta; investigo o DDL e repito. Se o snapshot
+  for necessário, `*rollback policy-{table}`.
+- **Subir a mudança (push/PR)** → delego ao @devops. Eu aplico no banco, mas não faço push.

package/tasks/db-rollback.md

@@ -0,0 +1,51 @@
+---
+id: db-rollback
+agent: data-engineer
+title: Reverter banco para um snapshot ou rodar rollback script
+inputs: [snapshot (label) ou rollback script (path)]
+outputs: [banco restaurado, registro do rollback]
+elicit: true
+modes: [interactive]
+---
+
+# Reverter banco para um snapshot ou rodar rollback script
+
+**Objetivo:** desfazer uma mudança de schema/dados restaurando um snapshot ou aplicando o rollback
+script — devolvendo o banco a um estado bom conhecido, com confirmação humana antes de qualquer
+operação destrutiva.
+
+**Pré-condições:**
+- Existe o snapshot rotulado OU o rollback script correspondente à mudança a desfazer.
+- O ambiente-alvo está identificado (`db-env-check` ok). Reverter no ambiente errado é dano duplo.
+
+## Passos
+
+1. **Identifique o alvo da reversão:** qual migration/operação está sendo desfeita, e qual o ponto de
+   destino (snapshot label ou rollback script).
+2. **PONTO DE ELICITAÇÃO — confirme com o humano** antes de qualquer operação destrutiva: mostre o
+   ambiente, o ponto de destino e o que será perdido (dados gravados após o snapshot, por exemplo).
+   **Só prossiga com confirmação explícita.** Em produção, isso é inegociável.
+3. **Crie um snapshot de segurança do estado atual** antes de reverter — para poder desfazer o próprio
+   rollback se for preciso. Reversibilidade vale também para a reversão.
+4. **Execute a reversão** em transação: restaure o snapshot OU rode o rollback script idempotente
+   (`IF EXISTS`), com `ROLLBACK` automático em caso de erro.
+5. **Verifique o estado pós-rollback:** as estruturas voltaram ao esperado, constraints/FKs/RLS estão
+   coerentes, e o smoke-test (`db-smoke-test`) passa no estado restaurado.
+6. **Registre o rollback** (alvo, ponto de destino, ambiente, timestamp, snapshot de segurança criado)
+   na trilha da story.
+
+## Critério de pronto (DoD)
+
+- [ ] Confirmação humana obtida antes da operação destrutiva
+- [ ] Snapshot de segurança do estado atual criado antes de reverter
+- [ ] Reversão executada em transação; estado pós-rollback verificado
+- [ ] Smoke-test verde no estado restaurado
+- [ ] Rollback registrado na trilha da story
+
+## Falha / recuperação
+
+- **A reversão falha no meio** → a transação faz `ROLLBACK`; confirmo que o banco continua no estado
+  pré-rollback e reporto. Não improviso correção destrutiva ao vivo.
+- **O snapshot/script não restaura limpo** → recorro ao snapshot de segurança criado no passo 3 e
+  escalo, em vez de empurrar um estado inconsistente.
+- **Humano não confirma** → não executo. Rollback sem confirmação não acontece.

package/tasks/db-run-sql.md

@@ -0,0 +1,61 @@
+---
+id: db-run-sql
+agent: data-engineer
+title: Executar SQL bruto em transação
+inputs: [arquivo .sql, objetivo/story que justifica a execução]
+outputs: [resultado da execução, snapshot prévio, log da transação]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Executar SQL bruto em transação
+
+**Objetivo:** rodar um arquivo SQL contra o banco dentro de uma transação reversível, com snapshot
+antes e rollback garantido se algo falhar — sem inventar SQL fora do que o arquivo e a story pedem.
+
+**Pré-condições:**
+- O arquivo `.sql` existe, é legível e rastreia a uma story/spec/objetivo. Se não rastreia, **pare**
+  e elicito o porquê — não executo SQL órfão (Constituição Art. IV).
+- As variáveis de ambiente do banco estão válidas (rode `db-env-check` antes se houver dúvida). Sem
+  conexão verificada, **pare**.
+- Eu li o conteúdo do SQL inteiro. Se ele contém DDL destrutivo (`DROP`, `TRUNCATE`, `DELETE` sem
+  `WHERE`), confirmo o alvo e o escopo antes de prosseguir.
+
+## Passos
+
+1. **Leia o arquivo `.sql` por completo** e classifique a operação: leitura pura, DML, ou DDL que
+   altera schema. DDL/DML destrutivo exige snapshot obrigatório no passo 2; leitura pura pode pular.
+2. **Tire um snapshot** do estado relevante (`db-snapshot {label}`) como ponto de rollback, sempre que
+   o SQL escreve ou altera schema. Sem snapshot, eu não aplico mudança que escreve.
+3. **Abra uma transação explícita** (`BEGIN`) e execute o conteúdo do arquivo dentro dela. Nada de
+   autocommit por statement em mudança de schema/dados — ou tudo entra, ou nada entra.
+4. **Verifique o resultado antes do commit:** contagem de linhas afetadas, ausência de erro, e
+   coerência com o que a story esperava. Se algo destoa do esperado, faço `ROLLBACK` e reporto.
+5. **Commit** (`COMMIT`) só quando o resultado bate com o esperado. Em qualquer erro durante a
+   execução, `ROLLBACK` automático — a transação garante que rodar de novo é seguro.
+6. **Redija segredos** em qualquer eco de resultado ou log (senhas, tokens nunca aparecem inteiros).
+7. **Registre** o que rodou: arquivo, label do snapshot, linhas afetadas e status final, na story ou
+   no log da operação — é o rastro de auditoria.
+8. **Smoke-test rápido** quando o SQL alterou schema/dados críticos: uma query de verificação que
+   prova que o estado pós-execução está consistente.
+
+## Critério de pronto (DoD)
+
+- [ ] SQL rastreia a uma story/spec; nada órfão foi executado
+- [ ] Snapshot prévio criado para qualquer operação que escreve ou altera schema
+- [ ] Execução ocorreu dentro de transação explícita (`BEGIN`…`COMMIT`/`ROLLBACK`)
+- [ ] Resultado verificado contra o esperado antes do commit
+- [ ] Segredos redigidos em logs e ecos
+- [ ] Operação registrada (arquivo, snapshot, linhas afetadas, status)
+
+## Falha / recuperação
+
+- **Erro durante a execução** → `ROLLBACK` automático da transação; reporto o erro e o estado
+  preservado pelo snapshot. Nada parcial fica no banco.
+- **Resultado destoa do esperado** → `ROLLBACK`, registro a divergência e devolvo à origem (story/
+  @architect) em vez de forçar o commit.
+- **Snapshot falhou** → **HALT**. Sem ponto de rollback eu não escrevo no banco.
+- **Conexão indisponível ou env inválido** → paro e rodo/encaminho `db-env-check`; não tento conexão
+  às cegas.
+- **O SQL exige subir algo (push, release)** → eu não faço; delego ao @devops. Eu só executo contra o
+  banco, localmente.

package/tasks/db-seed.md

@@ -0,0 +1,52 @@
+---
+id: db-seed
+agent: data-engineer
+title: Aplicar seed idempotente
+inputs: [seed (path), story/spec de origem]
+outputs: [dados de seed aplicados, registro da carga]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Aplicar seed idempotente
+
+**Objetivo:** popular o banco com dados de referência/iniciais de forma idempotente — rodar de novo
+não duplica nem quebra nada — sempre rastreando os dados a uma story/spec.
+
+**Pré-condições:**
+- O arquivo de seed existe e os dados rastreiam a um requisito/story (dados de referência, lookup,
+  fixtures). Seed que inventa dados fora do escopo é **bloqueado** (Constituição Art. IV).
+- O schema-alvo já está aplicado (as tabelas que o seed popula existem). Se não, **pare** e aplique a
+  migration antes.
+
+## Passos
+
+1. **Confirme o ambiente-alvo** (dev / staging / produção). Seed de fixtures de teste **não** vai para
+   produção; seed de dados de referência pode — confirmo qual é qual.
+2. **Garanta a idempotência:** o seed usa `INSERT … ON CONFLICT DO NOTHING/UPDATE`, `MERGE` ou check
+   por chave natural. Se o script não for idempotente, refatoro antes — rodar duas vezes tem que ser
+   seguro.
+3. **Aplique em transação** (`BEGIN … COMMIT`), respeitando a ordem de dependências (pais antes de
+   filhos, FKs satisfeitas).
+4. **Verifique a carga:** as linhas esperadas existem, sem duplicatas, com FKs válidas e constraints
+   satisfeitas. Conto os registros e comparo com o esperado.
+5. **Rode o seed uma segunda vez** num ambiente de teste para provar a idempotência: a contagem não
+   muda. Essa é a prova, não a promessa.
+6. **Registre a carga** (seed id, ambiente, linhas afetadas, timestamp) na trilha da story.
+
+## Critério de pronto (DoD)
+
+- [ ] Seed aplicado em transação, na ordem de dependências
+- [ ] Idempotência provada (segunda execução não duplica)
+- [ ] Contagem e integridade (FKs/constraints) verificadas
+- [ ] Carga registrada na trilha da story; ambiente correto confirmado
+
+## Falha / recuperação
+
+- **O seed falha no meio** → `ROLLBACK` da transação; banco intacto. Reporto a linha/registro que
+  causou e corrijo o seed.
+- **A segunda execução duplica ou quebra** → o seed não é idempotente; HALT e refatoro antes de
+  considerar pronto.
+- **Seed mira produção com fixtures de teste** → bloqueio e reconfirmo o ambiente; dados de teste não
+  contaminam produção.
+- **Dados não rastreiam a story** → recuso a carga e escalo para alinhar escopo.

package/tasks/db-smoke-test.md

@@ -0,0 +1,51 @@
+---
+id: db-smoke-test
+agent: data-engineer
+title: Bateria de smoke-test do banco pós-migração
+inputs: [versão/migration alvo, story/spec de origem]
+outputs: [relatório de smoke-test (verde/vermelho por checagem)]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Bateria de smoke-test do banco pós-migração
+
+**Objetivo:** provar rapidamente que o banco está saudável depois de uma migration/seed — estruturas,
+integridade, RLS e queries de caminho crítico — antes de declarar a operação pronta.
+
+**Pré-condições:**
+- A migration/seed da versão-alvo já foi aplicada.
+- As checagens rastreiam aos ACs/padrões de acesso da story/spec — não invento teste fora do escopo.
+
+## Passos
+
+1. **Estrutura:** confirme que as tabelas, colunas, FKs, constraints e índices esperados pela versão
+   existem, e que toda tabela tem o baseline (`id`, `created_at`, `updated_at`).
+2. **Integridade:** rode checagens de FK órfã, constraints `CHECK`/`NOT NULL` e unicidade nas chaves
+   que importam. Nada de linha violando o contrato do schema.
+3. **RLS:** para tabelas públicas, confirme que o RLS está ativo e teste um caso **positivo** (usuário
+   autorizado lê o que deve) e um **negativo** (usuário não-autorizado é barrado). RLS sem teste
+   negativo é RLS não-verificado.
+4. **Queries de caminho crítico:** execute as principais leituras/escritas dos padrões de acesso da
+   story e confirme que retornam o esperado, com explain plan sem regressão grosseira (ex.: seq scan
+   onde havia índice).
+5. **Idempotência operacional:** confirme que reaplicar a migration/seed não quebra (replay seguro).
+6. **Emita o relatório:** verde/vermelho por checagem, com o detalhe de qualquer falha. Verde em tudo
+   → operação pronta. Qualquer vermelho → bloqueia o "pronto".
+
+## Critério de pronto (DoD)
+
+- [ ] Estrutura e baseline verificados
+- [ ] Integridade (FKs, constraints, unicidade) sem violação
+- [ ] RLS ativo com caso positivo E negativo passando
+- [ ] Queries de caminho crítico verdes, sem regressão de plano
+- [ ] Relatório emitido com veredito claro
+
+## Falha / recuperação
+
+- **Qualquer checagem vermelha** → a operação **não** está pronta. Reporto a falha e, se for regressão
+  da migration aplicada, aciono `db-rollback {snapshot}` para o ponto anterior.
+- **RLS falha no caso negativo** (vaza dado para quem não devia) → trato como CRÍTICO, bloqueio e
+  corrijo a política antes de qualquer outra coisa.
+- **Regressão de performance num caminho crítico** → registro com explain plan e devolvo para ajuste de
+  índice/query; não declaro pronto com regressão conhecida.

package/tasks/db-snapshot.md

@@ -0,0 +1,48 @@
+---
+id: db-snapshot
+agent: data-engineer
+title: Criar snapshot do banco (ponto de rollback)
+inputs: [label, escopo (schema | schema+dados)]
+outputs: [snapshot rotulado, manifesto do snapshot (label, escopo, timestamp, ambiente)]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Criar snapshot do banco (ponto de rollback)
+
+**Objetivo:** capturar um ponto de restauração rotulado do banco — para que toda mudança subsequente
+seja reversível. Nenhuma migration acontece sem um snapshot antes.
+
+**Pré-condições:**
+- O ambiente-alvo está acessível e identificado (`db-env-check` ok).
+- Há um label significativo (ex.: `pre-{migration-id}`, `baseline`). Snapshot sem label é snapshot que
+  ninguém acha depois.
+
+## Passos
+
+1. **Defina o escopo:** só schema (estrutura/DDL) ou schema + dados. Para ponto de rollback de
+   migration de estrutura, schema basta; quando dados podem ser afetados, incluo dados.
+2. **Identifique o ambiente** (dev / staging / produção) e registre-o no manifesto — restaurar no
+   ambiente errado é desastre, então o ambiente fica gravado.
+3. **Gere o snapshot** (dump de schema e, se no escopo, de dados) com o label informado, em local
+   versionado/seguro de snapshots.
+4. **Verifique a integridade** do snapshot: o arquivo existe, não está vazio e é restaurável (checagem
+   de consistência do dump).
+5. **Escreva o manifesto:** label, escopo, ambiente, timestamp e a operação que ele protege. Segredos
+   eventuais no dump são tratados com cuidado — nunca ecoo conteúdo sensível em log.
+6. **Reporte o label do snapshot** para que `db-apply-migration` e `db-rollback` possam referenciá-lo.
+
+## Critério de pronto (DoD)
+
+- [ ] Snapshot gerado com o label e escopo corretos
+- [ ] Integridade verificada (existe, não-vazio, restaurável)
+- [ ] Manifesto registrado (label, escopo, ambiente, timestamp)
+- [ ] Label reportado para uso por apply/rollback
+
+## Falha / recuperação
+
+- **A geração do snapshot falha** → HALT. Sem snapshot válido, **bloqueio** qualquer migration que
+  dependia dele — reversibilidade é pré-condição.
+- **O snapshot sai vazio ou corrompido** → descarto, recrio e só prossigo com um snapshot verificado.
+- **Ambiente ambíguo** → paro e confirmo o ambiente antes de gerar; nunca assumo produção/dev por
+  conta própria.

package/tasks/db-verify-order.md

@@ -0,0 +1,49 @@
+---
+id: db-verify-order
+agent: data-engineer
+title: Lint da ordem do DDL de uma migration
+inputs: [migration_path]
+outputs: [veredito de ordem (OK/erros), lista de dependências fora de ordem]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Lint da ordem do DDL de uma migration
+
+**Objetivo:** garantir que o DDL de uma migration está em ordem topológica — dependências criadas
+antes de quem as usa — para que a aplicação não falhe no meio por referência a objeto inexistente.
+
+**Pré-condições:**
+- O arquivo de migration existe em `migration_path`. Se não existir, **pare** e reporte.
+- A migration é DDL (cria/altera estruturas). Se for só DML/seed, esta task não se aplica — use
+  `*dry-run` ou `*seed`.
+
+## Passos
+
+1. **Leia a migration inteira** e liste os objetos definidos: tabelas, tipos/enums, funções,
+   sequences, índices, FKs, políticas RLS, triggers, views.
+2. **Monte o grafo de dependências:** tipo/enum antes da coluna que o usa; tabela referenciada antes
+   da FK; tabela antes do índice/política/trigger dela; função antes do trigger que a chama.
+3. **Verifique a ordem de declaração contra o grafo.** Todo objeto deve aparecer DEPOIS de tudo que
+   ele depende. Marque cada violação (linha X usa objeto definido só na linha Y > X).
+4. **Cheque idempotência junto:** `IF NOT EXISTS`/`IF EXISTS` nas criações e drops, para o replay ser
+   seguro. Ausência é débito a sinalizar.
+5. **Detecte ciclos** (A depende de B que depende de A): exigem `ALTER TABLE ADD CONSTRAINT` separado
+   após ambas as tabelas existirem.
+6. **Emita o veredito:** OK (ordem topológica válida) ou ERROS (lista de objetos fora de ordem, com
+   linha e dependência faltante), sem aplicar nada — esta é uma task de lint, não de execução.
+
+## Critério de pronto (DoD)
+
+- [ ] Todos os objetos do DDL inventariados e mapeados em dependências
+- [ ] Cada dependência aparece antes de quem a usa — ou a violação foi reportada com linha
+- [ ] Ciclos detectados e a correção (constraint separada) apontada
+- [ ] Idempotência verificada (IF [NOT] EXISTS)
+- [ ] Veredito emitido; nada aplicado no banco
+
+## Falha / recuperação
+
+- **Objeto fora de ordem** → veredito ERROS com a linha exata; devolvo ao autor da migration para
+  reordenar antes do `*dry-run`/`*apply-migration`.
+- **Ciclo de FK** → recomendo quebrar em `CREATE TABLE` (ambas) → `ALTER TABLE ADD CONSTRAINT`.
+- **Migration ilegível/parcial** → **pare** e reporte; não dou veredito OK por arquivo incompleto.

package/tasks/deliberate.md

@@ -0,0 +1,46 @@
+---
+id: deliberate
+agent: nexus-master
+title: Deliberar — abrir a sala para DECIDIR
+inputs: [tópico]
+outputs: [Decisão, Racional, Dissensos registrados, Próximo passo]
+elicit: false
+modes: [yolo]
+---
+
+# Deliberar — abrir a sala para DECIDIR
+
+**Objetivo:** decidir uma questão de alto valor com trade-off real, abrindo a sala (party-mode) onde
+N personas deliberam com transcript compartilhado — e o desacordo vira ativo.
+
+**Pré-condições:**
+- A questão é **decisão**, não execução. Se é construir, use `orchestrate`.
+- Para abrir **debate** (várias rodadas, ~15× mais caro), a questão tem que ser alto-valor,
+  paralelizável e de baixo acoplamento (gate de admissão). Senão, roda `quick` (1 rodada + síntese).
+
+## Passos
+
+1. **Formulo o tópico** de forma decidível (uma pergunta com trade-off), não vaga.
+2. **Escolho as 3-5 personas que mais tensionam** o tópico — não convoco a sala inteira. O valor é o
+   desacordo; chamo as lentes que vão divergir (ex.: @architect vs @pm num "monólito vs micro?").
+3. **Abro a sala** (`nexus party "{tópico}" {personas} [--debate]`): cada persona lê o que a sala já
+   disse (transcript compartilhado) e responde pela sua lente — concorda, DISCORDA, constrói.
+4. **Sintetizo no fim** (eu, a Sofia): leio a sala e entrego **Decisão → Racional → Dissensos →
+   Próximo passo**. A decisão rastreia ao que a sala disse — não invento posição que ninguém defendeu.
+5. **Registro os dissensos.** Onde a sala discordou e quem defendeu o quê vira registro — um dissenso
+   marca um risco que a decisão assume conscientemente. Dissenso registrado é um ativo (vira uma
+   proposta rastreável na governança).
+
+## Critério de pronto (DoD)
+
+- [ ] Tópico decidível e personas que genuinamente tensionam escolhidas
+- [ ] A sala deliberou com transcript compartilhado (não monólogos paralelos)
+- [ ] Síntese entregue: Decisão + Racional + Dissensos + Próximo passo
+- [ ] Cada dissenso real registrado (não varrido para debaixo do tapete)
+
+## Falha / recuperação
+
+- **A sala convergiu cedo (todos concordam)** → ou a questão era fácil (decida e siga), ou faltou uma
+  lente que tensiona — adiciono a persona que falta.
+- **Debate sem a declaração de admissão** → o motor rebaixa para `quick` automaticamente; aceito.
+- **Síntese ficaria inventando** → emito INCONCLUSIVO honesto em vez de fabricar consenso.

package/tasks/design-indexes.md

@@ -0,0 +1,59 @@
+---
+id: design-indexes
+agent: data-engineer
+title: Desenhar a estratégia de índices
+inputs: [schema, padrões de acesso (do modelo de domínio)]
+outputs: [DDL de índices, docs/data/indexes.md]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Desenhar a estratégia de índices
+
+**Objetivo:** criar índices guiados por padrão de acesso real — cada índice serve a uma query que
+existe. Índice sem query que o justifique é peso morto; FK sem índice é débito.
+
+**Pré-condições:**
+- O schema existe (saída de `create-schema`).
+- Os padrões de acesso estão documentados no modelo de domínio (quais queries, por qual chave, com
+  qual frequência). Se faltam, **pare** — índice sem padrão de acesso é palpite, e eu não otimizo por
+  palpite.
+
+## Passos
+
+1. **Releia os padrões de acesso** do modelo de domínio. Liste as queries quentes: filtros, ordenações,
+   joins frequentes. Cada índice que eu criar vai apontar para uma dessas queries.
+2. **Indexe toda foreign key** que participa de join ou filtro. FK sem índice é a causa silenciosa de
+   query lenta — eu sinalizo e cubro.
+3. **Crie índices compostos na ordem certa de colunas** (igualdade antes de range), casando com os
+   filtros `WHERE`/`ORDER BY` reais. Coluna na ordem errada é índice que o planner ignora.
+4. **Considere índices especializados quando o acesso justifica:** parcial (`WHERE deleted_at IS
+   NULL`), `GIN`/`GIN trgm` para busca textual/JSONB, `UNIQUE` para identidade de negócio. Cada um
+   com a query que o motiva anotada.
+5. **Evite over-indexing.** Todo índice custa em escrita e espaço. Não crio índice "por garantia" — se
+   não há query, não há índice.
+6. **Escreva DDL idempotente** com `CREATE INDEX IF NOT EXISTS` e, em produção, `CREATE INDEX
+   CONCURRENTLY` para não travar a tabela. Isso vai virar migration via `create-migration-plan`.
+7. **Valide com evidência, não intuição:** rode `EXPLAIN (ANALYZE)` (ou a task `analyze-performance`)
+   na query alvo antes/depois para confirmar que o índice é usado e melhora o plano. Decisão de
+   performance vem de medição.
+8. **Documente em `docs/data/indexes.md`:** cada índice, a query que o justifica e a evidência do
+   explain plan.
+
+## Critério de pronto (DoD)
+
+- [ ] Cada índice rastreia a uma query/padrão de acesso documentado
+- [ ] Toda FK que participa de join/filtro está indexada
+- [ ] Índices compostos com ordem de coluna correta
+- [ ] Sem over-indexing (nenhum índice sem query que o justifique)
+- [ ] DDL idempotente (`IF NOT EXISTS`, `CONCURRENTLY` em produção)
+- [ ] Uso e ganho confirmados por `EXPLAIN ANALYZE`
+- [ ] `docs/data/indexes.md` escrito com a evidência
+
+## Falha / recuperação
+
+- **Padrões de acesso ausentes** → volto a `db-domain-modeling`; não crio índice no escuro.
+- **`EXPLAIN` mostra que o índice não é usado** → reviso ordem de colunas/tipo do índice em vez de
+  empilhar índices; índice que o planner ignora é só custo.
+- **A indexação vira parte de uma migration** → encaminho para `create-migration-plan`; aplicação em
+  ambiente remoto é delegada ao @devops, eu não dou push.