nexus-core-v3 3.0.0

package/templates/migration-plan-tmpl.md

@@ -0,0 +1,92 @@
+---
+id: migration-plan-tmpl
+kind: template
+agent: data-engineer
+produces: docs/data-models/{versao}-migration-plan.md
+---
+
+# Migration Plan: {versão / descrição curta}
+
+**Status:** Draft
+**Banco-alvo:** {PostgreSQL / Supabase — ambiente}
+**Schema-fonte:** {docs/data-models/{dominio}-schema.md — o design que esta migration materializa}
+**Snapshot baseline:** {label do snapshot pré-migração — ponto de rollback}
+
+## Objetivo
+
+> O que esta migração muda e por quê. Cada mudança rastreia a uma story/spec/design (No Invention).
+
+- {mudança 1 — rastro: story/spec/schema}
+- {mudança 2 — rastro}
+
+## Pré-condições
+
+> O que precisa estar verdadeiro antes de aplicar. Reversibilidade é pré-condição.
+
+- [ ] Snapshot `{label}` criado (`*snapshot {label}`)
+- [ ] Rollback script pronto e testado (ver `## Rollback`)
+- [ ] Ordem do DDL validada — dependências primeiro (`*verify-order {path}`)
+- [ ] Dry-run executado sem erro (`*dry-run {path}`)
+- [ ] Variáveis de ambiente do banco validadas (`*env-check`)
+- [ ] {pré-condição específica desta migração}
+
+## Mudanças (DDL, em ordem de dependência)
+
+> Tabelas-pai antes de filhas; tipos/enums antes de colunas que os usam. Tudo idempotente (`IF NOT EXISTS` / `IF EXISTS`) — rodar de novo é seguro.
+
+### Passo {n}: {descrição}
+
+```sql
+-- forward
+{DDL idempotente}
+```
+
+**Impacto:** {tabelas afetadas, lock esperado, downtime?}
+**Dados:** {migração/backfill de dados envolvido? volume?}
+
+## Estratégia de Aplicação
+
+| Item | Decisão |
+|---|---|
+| Transação | {tudo em uma transação? ou por passo?} |
+| Janela | {online / janela de manutenção — por quê} |
+| Lock esperado | {ACCESS EXCLUSIVE em {tabela}? duração estimada} |
+| Backfill | {síncrono no DDL / batch separado / N/A} |
+| Idempotência | {como rodar duas vezes não quebra} |
+
+## Rollback
+
+> Se eu não sei como desfazer, eu não aplico. Cada passo forward tem o seu reverso.
+
+```sql
+-- rollback (ordem inversa)
+{DDL de reversão idempotente}
+```
+
+**Restauração de snapshot:** `*rollback {label}` — quando o rollback script não basta.
+**Ponto de não-retorno:** {se houver — ex.: DROP de coluna com dados; o que se perde}
+
+## Validação Pós-Migração
+
+> Smoke-test antes de declarar pronto.
+
+- [ ] Schema aplicado bate com o design (`*smoke-test {versao}`)
+- [ ] Contagens de linha preservadas onde esperado
+- [ ] Constraints/FKs ativas e válidas
+- [ ] RLS aplicada nas tabelas que exigem (`*test-as-user`)
+- [ ] Queries quentes sem regressão de performance (`*analyze-performance`)
+- [ ] {validação específica desta migração}
+
+## Riscos
+
+| Risco | Severidade | Mitigação |
+|---|---|---|
+| {risco} | {CRÍTICO/ALTO/MÉDIO/BAIXO} | {como mitigo / rollback} |
+
+> CRÍTICO bloqueia a aplicação; ALTO exige mitigação ou rollback script comprovado.
+
+## Change Log
+
+| Data | Mudança | Autor |
+|---|---|---|
+| {data} | {o quê} | @data-engineer |

package/templates/prd-tmpl.md

@@ -0,0 +1,95 @@
+---
+id: prd-tmpl
+kind: template
+agent: pm
+produces: docs/prd/{slug}-prd.md
+---
+
+# PRD: {nome do produto/iniciativa}
+
+**Status:** Draft
+**Tipo:** {greenfield | brownfield}
+**Autor:** @pm (Morgan)
+**Data:** {data}
+
+## Visão e Problema
+
+> O "por quê" na raiz. Que dor real do usuário isto resolve? Sem dor rastreada, não vira PRD.
+
+- **Problema:** {a dor concreta do usuário, não a solução}
+- **Usuário-alvo:** {quem sente a dor — persona/segmento}
+- **Por que agora:** {gatilho/oportunidade que justifica o timing}
+- **Hipótese de valor:** {se entregarmos X, esperamos resultado Y}
+
+## Objetivos e Métricas de Sucesso
+
+> Cada objetivo tem uma métrica mensurável. Número informa a decisão — sem métrica, é desejo, não objetivo.
+
+| ID | Objetivo | Métrica | Baseline | Alvo |
+|---|---|---|---|---|
+| OBJ-1 | {resultado de negócio/usuário} | {como se mede} | {valor atual} | {valor desejado} |
+
+## Escopo do MVP
+
+> Tudo começa fora do MVP e precisa *provar* que entra. Recorte com MoSCoW/RICE.
+
+### Dentro (Must)
+- {capacidade mínima que prova a hipótese}
+
+### Fora deste recorte (vira roadmap)
+- {feature adiada e por quê — Should/Could/Won't}
+
+## Requisitos Funcionais (FR)
+
+> Cada FR rastreia a um objetivo e a uma dor. Sem rastro = não entra (No Invention, Art. IV).
+
+| ID | Requisito | Rastreia a | Critério de aceite (verificável) |
+|---|---|---|---|
+| FR-1 | {o que o sistema deve fazer} | OBJ-{n} | {dado/quando/então — testável sim/não} |
+
+## Requisitos Não-Funcionais (NFR)
+
+> Performance, segurança, escala, acessibilidade, compliance. Cada um com critério mensurável.
+
+| ID | Categoria | Requisito | Critério mensurável |
+|---|---|---|---|
+| NFR-1 | {performance/segurança/...} | {restrição de qualidade} | {limite numérico/verificável} |
+
+## Restrições e Premissas
+
+> Limites externos (CON) e suposições que, se falsas, mudam o plano.
+
+- **CON-{n}:** {restrição técnica/legal/de negócio imposta de fora}
+- **Premissa:** {suposição assumida — risco se for falsa}
+
+## Personas e Jornadas
+
+> Quem usa e como atravessa o produto. Só personas que tocam o MVP.
+
+- **{Persona}:** {objetivo, contexto, dor principal}
+  - Jornada: {passos do gatilho ao resultado}
+
+## Dependências e Riscos
+
+| Tipo | Item | Impacto | Mitigação |
+|---|---|---|---|
+| Dependência | {serviço/dado/equipe externa} | {o que trava se faltar} | {plano} |
+| Risco | {o que pode dar errado} | {severidade} | {como reduzir} |
+
+## Fora de Escopo (explícito)
+
+> O que este PRD deliberadamente NÃO cobre — para alinhar expectativa e proteger o recorte.
+
+- {item fora de escopo}
+
+## Marco de Quality Gates
+
+> Qualidade entra no plano, não depois. Quais gates esta entrega atravessa.
+
+- {gate previsto — ex.: validação @po, QA gate @qa, NFRs verificados}
+
+## Próximos Passos
+
+- Estruturar epics a partir deste PRD → `*create-epic` (@pm)
+- Arquitetura e seleção de tecnologia → delegar a @architect
+- Pesquisa pendente (se houver) → delegar a @analyst

package/templates/project-brief-tmpl.md

@@ -0,0 +1,100 @@
+---
+id: project-brief-tmpl
+kind: template
+agent: analyst
+produces: docs/research/{slug}-project-brief.md
+---
+
+# Project Brief: {nome do projeto}
+
+**Status:** Draft
+**Autor:** @analyst (Alex)
+**Data:** {data}
+**Decisão que este brief destrava:** {qual decisão de produto/escopo este documento serve}
+
+## Resumo Executivo
+
+> Uma síntese de 3-5 frases que qualquer leitor entende sem o resto do doc. O "portanto" no topo.
+
+{problema central + público + solução proposta em alto nível + valor esperado}
+
+## Problema
+
+> O que dói, para quem, e por que importa agora. Cada afirmação rastreia a evidência ou vira hipótese marcada.
+
+- **Dor:** {qual é o problema concreto}
+- **Quem sofre:** {persona/segmento afetado}
+- **Magnitude:** {frequência/custo/impacto — com fonte ou marcado [hipótese]}
+- **Por que agora:** {gatilho temporal — mudança de mercado, regulação, tecnologia}
+
+## Por que as soluções atuais falham
+
+> O gap que justifica este projeto existir. Liga ao competitor-analysis quando houver.
+
+- {alternativa atual} → {por que não resolve}
+- {fonte: docs/research/{slug}-competitor-analysis.md ou marcado [hipótese]}
+
+## Público-Alvo
+
+> Quem usa e quem compra. Sem persona inventada — cada uma vem de pesquisa de usuário ou marcada como suposição.
+
+### Segmento primário
+- **Perfil:** {quem são}
+- **Necessidade:** {o que precisam resolver}
+- **Comportamento atual:** {como lidam hoje}
+
+### Segmento secundário (se houver)
+- {perfil e necessidade}
+
+## Proposta de Valor
+
+> Por que este público escolheria isto. Uma frase de posicionamento + diferenciais.
+
+- **Posicionamento:** Para {público} que {necessidade}, {produto} é {categoria} que {benefício-chave}.
+- **Diferenciais:** {1-3 pontos que tornam a solução distinta}
+
+## Objetivos e Métricas de Sucesso
+
+> O que "deu certo" significa, em números. Cada métrica é mensurável.
+
+| Objetivo | Métrica | Alvo | Como medir |
+|---|---|---|---|
+| {objetivo de negócio} | {KPI} | {valor-alvo} | {fonte do dado} |
+
+## Escopo
+
+> A fronteira do projeto. Tão importante o que fica de fora quanto o que entra.
+
+### Dentro do escopo (MVP)
+- {capacidade incluída}
+
+### Fora do escopo (por ora)
+- {o que NÃO entra — e por quê}
+
+## Restrições e Premissas
+
+> Constraints reais (CON-*) e premissas que, se falsas, mudam tudo.
+
+- **Restrições:** {orçamento, prazo, tecnologia, regulação — rotular CON-{n} se vira spec}
+- **Premissas:** {o que assumimos verdadeiro — marcar para validar}
+
+## Riscos
+
+> O que pode dar errado. Cada risco com impacto e mitigação possível.
+
+| Risco | Impacto | Probabilidade | Mitigação possível |
+|---|---|---|---|
+| {risco} | {alto/médio/baixo} | {alta/média/baixa} | {ação} |
+
+## Perguntas em Aberto
+
+> O que ainda não sabemos e precisa de pesquisa antes de avançar.
+
+- {pergunta} → {como respondê-la: @analyst *research-prompt / @analyst *perform-market-research}
+
+## Portanto — Próximos Passos
+
+> O handoff acionável. Quem pega isto daqui e faz o quê.
+
+1. {ação} → {@pm para PRD / @architect para viabilidade técnica / @analyst para pesquisa complementar}
+2. {...}

package/templates/qa-verdict-tmpl.md

@@ -0,0 +1,73 @@
+---
+id: qa-verdict-tmpl
+kind: template
+agent: qa
+produces: bloco <verdict> no output do @qa (persistido em .nexus/verdicts/<runId>-<taskId>.json)
+---
+
+# Veredito de QA — bloco `<verdict>`
+
+O gate da Quinn tem duas faces. A **prosa** vai na seção "QA Results" da story (para humanos). O
+**veredito estruturado** vai num bloco `<verdict>` no fim do output — o motor o parseia, valida contra
+o contrato `QaVerdict` e persiste. Emita **exatamente um** bloco; dois é ambíguo e o motor descarta.
+
+```
+<verdict>
+{
+  "verdict": "PASS | FAIL | BLOCKED",
+  "attempt": 1,
+  "issues": [
+    {
+      "categoria": "{ex.: layout, segurança, rastreabilidade, regressão}",
+      "severidade": "P0 | P1 | P2 | P3",
+      "expected": "{o que a AC/spec exige}",
+      "actual": "{o que de fato acontece — observado, não suposto}",
+      "evidence": "{prova: arquivo:linha, teste que falha, a.png == b.png, log}"
+    }
+  ],
+  "fixInstructions": ["{passo objetivo para o @dev consertar}"],
+  "filesToModify": [{ "path": "{arquivo}", "oQueMudar": "{o defeito preciso}" }],
+  "evidenceRefs": ["{captura/artefato: .nexus/evidence/<story>/home-1440.png}"]
+}
+</verdict>
+```
+
+## Regras do contrato (o motor força)
+
+- **`verdict: FAIL` exige ao menos 1 `issue`.** Reprovar sem apontar o defeito com evidência não existe
+  no Nexus — o boundary Zod recusa. Se você não consegue nomear a issue, você não tem um FAIL: tem uma
+  dúvida (investigue) ou um PASS.
+- **`evidence` é obrigatória e não-vazia em toda issue.** "Parece errado" não é evidência. `arquivo:linha`,
+  o teste que falha, o diff de duas capturas, o log — isso é.
+- **`attempt` vai de 1 a 3.** Reprovar 2–3 vezes é o processo funcionando, não falhando. Na 3ª sem
+  convergir, o veredito tende a `BLOCKED` (escala), não a um PASS por cansaço.
+- **`PASS` sem `evidenceRefs`** é permitido pelo contrato, mas o gate `--reality` avisa: nota perfeita
+  sem prova é suspeita. Anexe o que você viu rodar.
+
+## Exemplos
+
+**PASS com evidência:**
+```
+<verdict>
+{ "verdict": "PASS", "attempt": 1, "evidenceRefs": [".nexus/evidence/1.4/checkout-1440.png"] }
+</verdict>
+```
+
+**FAIL rastreável (o @dev consegue consertar sem adivinhar):**
+```
+<verdict>
+{
+  "verdict": "FAIL",
+  "attempt": 2,
+  "issues": [{
+    "categoria": "regressão",
+    "severidade": "P1",
+    "expected": "acordeão expande ao clicar (AC-3)",
+    "actual": "não expande — o handler não é registrado",
+    "evidence": "accordion-0-before.png == accordion-0-after.png (idênticos); Accordion.tsx:42"
+  }],
+  "fixInstructions": ["registrar onClick no item; adicionar teste que reproduz o não-expandir"],
+  "filesToModify": [{ "path": "src/Accordion.tsx", "oQueMudar": "bind do onClick ausente na linha 42" }]
+}
+</verdict>
+```

package/templates/rls-policies-tmpl.md

@@ -0,0 +1,93 @@
+---
+id: rls-policies-tmpl
+kind: template
+agent: data-engineer
+produces: docs/data-models/{dominio}-rls-policies.md
+---
+
+# RLS Policies: {nome do domínio/módulo}
+
+**Status:** Draft
+**Banco-alvo:** {Supabase / PostgreSQL}
+**Schema-fonte:** {docs/data-models/{dominio}-schema.md — as tabelas que estas políticas protegem}
+
+## Contexto de Segurança
+
+> RLS é projetada junto com o schema, não depois. Defesa em profundidade: RLS + FKs + CHECK + NOT NULL.
+
+- **Modelo de tenancy:** {single-tenant / multi-tenant por org_id / por user_id}
+- **Função de identidade:** {ex.: `auth.uid()` no Supabase — o que retorna}
+- **Camada de auth presente?** {SIM/NÃO — se NÃO, `auth.uid()` retorna NULL e RLS não protege ainda}
+- **service_role:** {bypassa RLS — onde e por que é usado, com justificativa}
+
+## Tabelas e Cobertura
+
+> Toda tabela pública exige RLS habilitada. Sem isso, a tabela não está pronta.
+
+| Tabela | RLS habilitada | Chave de tenancy | Modo (KISS/granular) |
+|---|---|---|---|
+| {tabela} | {SIM/NÃO} | {user_id / org_id} | {KISS / granular} |
+
+## Políticas por Tabela
+
+### Tabela `{nome_tabela}`
+
+**Habilitar RLS:**
+
+```sql
+ALTER TABLE {schema}.{nome_tabela} ENABLE ROW LEVEL SECURITY;
+ALTER TABLE {schema}.{nome_tabela} FORCE ROW LEVEL SECURITY;  -- se aplicável
+```
+
+**Políticas (por operação):**
+
+| Operação | Nome da política | Roles | Regra (USING / WITH CHECK) |
+|---|---|---|---|
+| SELECT | {nome} | {authenticated/...} | {condição} |
+| INSERT | {nome} | {...} | {WITH CHECK} |
+| UPDATE | {nome} | {...} | {USING + WITH CHECK} |
+| DELETE | {nome} | {...} | {USING} |
+
+```sql
+-- SELECT
+CREATE POLICY {nome_select} ON {schema}.{nome_tabela}
+  FOR SELECT TO {role}
+  USING ({condição — ex.: user_id = auth.uid()});
+
+-- INSERT
+CREATE POLICY {nome_insert} ON {schema}.{nome_tabela}
+  FOR INSERT TO {role}
+  WITH CHECK ({condição});
+
+-- UPDATE
+CREATE POLICY {nome_update} ON {schema}.{nome_tabela}
+  FOR UPDATE TO {role}
+  USING ({condição}) WITH CHECK ({condição});
+
+-- DELETE
+CREATE POLICY {nome_delete} ON {schema}.{nome_tabela}
+  FOR DELETE TO {role}
+  USING ({condição});
+```
+
+**Justificativa:** {por que esta política — qual acesso ela libera e qual ela barra}
+
+## Casos de Teste (positivos E negativos)
+
+> Toda política tem teste positivo (quem PODE acessa) e negativo (quem NÃO PODE é barrado). Emular via `*test-as-user {user_id}`.
+
+| # | Tabela | Operação | Usuário emulado | Esperado (ACEITA/NEGA) | Justificativa |
+|---|---|---|---|---|---|
+| 1 | {tabela} | {SELECT/...} | {dono do dado} | ACEITA | {acesso legítimo} |
+| 2 | {tabela} | {SELECT/...} | {outro tenant} | NEGA | {isolamento de tenant} |
+| 3 | {tabela} | {INSERT/...} | {anônimo} | NEGA | {sem auth} |
+
+## Riscos e Decisões Abertas
+
+- {ex.: tabela sem chave de tenancy clara; uso de service_role que precisa de revisão; FK que cruza tenants}
+
+## Change Log
+
+| Data | Mudança | Autor |
+|---|---|---|
+| {data} | {o quê} | @data-engineer |

package/templates/schema-design-tmpl.md

@@ -0,0 +1,107 @@
+---
+id: schema-design-tmpl
+kind: template
+agent: data-engineer
+produces: docs/data-models/{dominio}-schema.md
+---
+
+# Schema Design: {nome do domínio/módulo}
+
+**Status:** Draft
+**Banco-alvo:** {PostgreSQL / Supabase / MySQL — versão}
+**Fonte da arquitetura:** {docs/architecture/... — de onde vêm as entidades e o contexto}
+
+## Contexto de Domínio
+
+> O quadro completo antes do DDL. Sem isto, o schema vira palpite.
+
+- **Entidades reais:** {as coisas do mundo do negócio que viram tabelas}
+- **Relações principais:** {quem pertence a quem, cardinalidades}
+- **Padrões de acesso:** {como os dados vão ser lidos e escritos — as queries quentes}
+- **Escala esperada:** {volume por tabela, taxa de crescimento, hotpaths}
+- **Restrições de segurança:** {multi-tenant? auth.uid()? dados sensíveis?}
+
+## Modelo de Dados (visão lógica)
+
+> Diagrama/lista de entidades e relações. Cada entidade rastreia a um requisito ou padrão de acesso documentado (No Invention).
+
+| Entidade | Descrição | Relações | Fonte (FR/NFR/entidade) |
+|---|---|---|---|
+| {entidade} | {o que representa} | {FK → tabela} | {rastro} |
+
+## Tabelas (DDL)
+
+> Cada tabela com baseline obrigatório (`id`, `created_at`, `updated_at`), FKs explícitas e constraints que o banco faz cumprir. Soft delete (`deleted_at`) quando há trilha de auditoria.
+
+### Tabela `{nome_tabela}`
+
+**Propósito:** {por que esta tabela existe — o requisito que ela atende}
+
+```sql
+CREATE TABLE IF NOT EXISTS {schema}.{nome_tabela} (
+  id          {uuid/bigint} PRIMARY KEY DEFAULT {gen_random_uuid()/...},
+  {coluna}    {tipo} {NOT NULL/...} {DEFAULT ...},
+  -- FKs explícitas
+  {fk_coluna} {tipo} REFERENCES {schema}.{tabela_pai}(id) ON DELETE {RESTRICT/CASCADE/SET NULL},
+  -- baseline
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  deleted_at  timestamptz,  -- soft delete, se aplicável
+  -- constraints de integridade
+  CONSTRAINT {nome_check} CHECK ({condição})
+);
+```
+
+**Colunas:**
+
+| Coluna | Tipo | Nullable | Default | Regra / Constraint |
+|---|---|---|---|---|
+| id | {tipo} | NO | {default} | PK |
+| {coluna} | {tipo} | {SIM/NÃO} | {default} | {CHECK/UNIQUE/...} |
+
+**Justificativa de normalização/desnormalização:** {por que normalizado ou onde desnormalizei e qual padrão de acesso justifica}
+
+## Integridade Referencial
+
+> Defesa em profundidade, no banco — não delegada à aplicação.
+
+| FK | Tabela origem → destino | ON DELETE | Índice na FK? | Justificativa |
+|---|---|---|---|---|
+| {fk} | {origem} → {destino} | {ação} | {SIM/NÃO} | {por quê} |
+
+## Constraints de Negócio
+
+> Regras que o banco faz cumprir mesmo com bug na aplicação.
+
+- **CHECK:** {constraint} — {regra de negócio que garante}
+- **UNIQUE:** {coluna(s)} — {invariante que protege}
+- **NOT NULL:** {colunas obrigatórias} — {por quê}
+- **Triggers:** {nome} — {comportamento, ex.: `updated_at` automático}
+
+## Estratégia de Índices
+
+> Cada índice serve a uma query real de `## Contexto de Domínio`. Índice sem query que o justifique é peso morto.
+
+| Índice | Tabela(s)/coluna(s) | Tipo | Query/padrão de acesso que justifica |
+|---|---|---|---|
+| {nome_idx} | {tabela(coluna)} | {btree/gin/...} | {query quente} |
+
+## Segurança (RLS — visão de schema)
+
+> Quais tabelas exigem Row Level Security. O detalhamento das políticas vai em `rls-policies-tmpl`.
+
+| Tabela | RLS obrigatório? | Chave de tenancy | Observação |
+|---|---|---|---|
+| {tabela} | {SIM/NÃO} | {ex.: user_id / org_id} | {ex.: service_role bypassa} |
+
+> Se não há camada de auth, registrar: `auth.uid()` retorna NULL — RLS não protege ainda.
+
+## Riscos e Decisões Abertas
+
+- {risco de modelagem, dívida registrada, decisão que depende do @architect}
+
+## Change Log
+
+| Data | Mudança | Autor |
+|---|---|---|
+| {data} | {o quê} | @data-engineer |

package/templates/spec-tmpl.md

@@ -0,0 +1,88 @@
+---
+id: spec-tmpl
+kind: template
+agent: pm
+produces: docs/specs/{slug}-spec.md
+---
+
+# Spec: {nome da feature}
+
+**Status:** Draft
+**Classe de complexidade:** {SIMPLE | STANDARD | COMPLEX}
+**Requisitos de origem:** {docs/specs/{slug}-requirements.json}
+**Autor:** @pm (Morgan)
+**Data:** {data}
+
+## Contexto e Problema
+
+> O "por quê" elicitado no gather. Toda afirmação aqui rastreia a um requisito ou achado — No Invention.
+
+- **Problema:** {a dor que motiva a spec}
+- **Usuário/stakeholder:** {quem pediu e quem usa}
+- **Resultado esperado:** {o que muda quando isto existir}
+
+## Requisitos Formalizados
+
+> Cada item carrega seu ID de origem (FR/NFR/CON ou achado de pesquisa). Sem origem = não entra.
+
+### Funcionais
+| ID | Requisito | Origem | Critério de aceite (verificável) |
+|---|---|---|---|
+| FR-1 | {comportamento esperado} | {req-id / achado} | {testável sim/não} |
+
+### Não-Funcionais
+| ID | Categoria | Requisito | Critério mensurável |
+|---|---|---|---|
+| NFR-1 | {performance/segurança/...} | {restrição} | {limite verificável} |
+
+### Restrições
+| ID | Restrição | Origem |
+|---|---|---|
+| CON-1 | {limite externo} | {req-id / decisão} |
+
+## Comportamento Esperado
+
+> Cenários no formato dado/quando/então. Cada cenário mapeia a um FR.
+
+- **Cenário {n}** (FR-{x}): dado {contexto}, quando {ação}, então {resultado observável}.
+
+## Interfaces e Contratos
+
+> Entradas, saídas e contratos que a feature expõe ou consome. Estrutura, não implementação.
+
+- **Entradas:** {dados/parâmetros}
+- **Saídas:** {retorno/efeito}
+- **Contrato/Interface:** {assinatura/forma do payload}
+
+## Fora de Escopo
+
+> O que esta spec deliberadamente NÃO cobre — protege o recorte e a crítica.
+
+- {item excluído}
+
+## Critérios de Aceite Globais
+
+> Como a feature inteira é considerada concluída. Verificável.
+
+1. {critério global testável}
+
+## Riscos e Dependências
+
+| Tipo | Item | Impacto | Mitigação |
+|---|---|---|---|
+| Dependência | {serviço/dado/spec} | {o que trava} | {plano} |
+| Risco | {o que pode falhar} | {severidade} | {redução} |
+
+## Gate de Rastreabilidade (No Invention, Art. IV)
+
+> Cada FR/NFR/CON acima aponta para uma origem. Esta tabela prova o rastro — entrada para a crítica @qa.
+
+| Item da spec | Origem rastreada |
+|---|---|
+| FR-{n} | {req-id / NFR / CON / achado de pesquisa} |
+
+## Próximos Passos (Spec Pipeline)
+
+- Crítica da spec → @qa (`critique.json`)
+- Plano de implementação → @architect (`implementation.yaml`)
+- Arquitetura/tecnologia → @architect