spec-first-copilot 0.6.0-beta.9 → 0.7.0

package/templates/.github/templates/specs/contracts.template.md

@@ -1,141 +1,147 @@
-# Contracts — {{NOME}}
-
-> Contratos executáveis da feature: modelo de dados, API, integrações e regras de negócio.
-> Gerado pelo /sf-design a partir do SDD. NUNCA editado manualmente.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-ORIGEM: /sf-design — projeção do SDD §Área-DB (dados) + §Área-Backend (endpoints/regras)
-        + §Área-* (integrações externas). Complementa (não repete) docs/apiContracts.md.
-ATUALIZAÇÃO: Sempre regenerado junto com o SDD. NUNCA editado manualmente.
-
-REGRA DE OURO: Se algo aqui diverge do SDD, o SDD vence. Re-rode /sf-design.
-
-DISTINÇÃO CRÍTICA (3 camadas):
-- Camada 1 — Schema de DADOS: estrutura do banco (tabela, coluna, tipo, constraint DB)
-  → vira migration SQL
-  → seção "Dados"
-- Camada 2 — VALIDAÇÃO DE ENTRADA: restrição de formato/tipo do request
-  → verificada ANTES da lógica de negócio, no DTO/model via anotações
-  → ex: "email é string, obrigatório, formato válido, max 255 chars"
-  → seção "Validações de Entrada"
-- Camada 3 — REGRA DE NEGÓCIO: invariante do domínio, envolve estado
-  → verificada NO SERVIÇO, pós-schema pós-validação
-  → ex: "email não pode estar cadastrado em outra conta ativa"
-  → seção "Regras de Negócio"
-
-Essas três camadas não se sobrepõem. Regras em uma camada não aparecem na outra.
-
-CONVENÇÕES GLOBAIS: NÃO duplicar aqui o que já está em docs/apiContracts.md
-(paginação, HTTP codes genéricos, formato de erro, convenções de rota). Apenas referenciar.
-Colocar aqui apenas o que é ESPECÍFICO desta feature.
-
-PARA CODERS:
-- Campos de dados: tipos EXATOS do banco (varchar(255), não "string")
-- Requests/responses JSON: completos, com todos os campos nomeados
-- Regras de negócio: RN-NNN com enforcement point explícito
-- Integrações: timeout + retry + fallback obrigatórios
-
-=============================================================================
--->
-
-## Dados
-
-<!-- Entidades tocadas por esta feature. Dois casos:
-A) Tabela nova → usar subseção "Tabelas novas"
-B) Alteração em tabela existente → usar subseção "Alterações"
-Se nenhum dos dois: omitir seção Dados inteira. -->
-
-### Tabelas novas
-
-#### {{tabela}}
-
-> {{descrição em 1 linha}}
-
-| Coluna | Tipo | Nullable | Default | Constraint | Descrição |
-|--------|------|----------|---------|------------|-----------|
-|        |      |          |         |            |           |
-
-**Relações:**
-- `campo_id` → `tabela_ref(id)` ON DELETE RESTRICT / CASCADE / SET NULL
-
-**Índices:**
-- `idx_{{tabela}}_{{campo}}` em `(campo)` — justificativa (qual query usa)
-
-### Alterações em tabelas existentes
-
-<!-- Uma subseção por tabela alterada. Listar apenas o que MUDA. -->
-
-#### {{tabela_existente}}
-
-| Operação | Coluna / Índice | Detalhe |
-|----------|-----------------|---------|
-| ADD COLUMN | `nome_coluna` | tipo + constraint + default |
-| ALTER COLUMN | `nome_coluna` | o que muda (tipo, nullable, default) |
-| DROP COLUMN | `nome_coluna` | justificativa + impacto em dados |
-| ADD INDEX | `idx_nome` | colunas + justificativa |
-| ADD FK | `campo_id` | referência + ON DELETE |
-
-## Validações de Entrada (schema)
-
-<!-- Restrições de formato/tipo verificadas ANTES da lógica de negócio.
-Viram anotações/atributos de validação no DTO/model de request.
-NÃO são regras de negócio (que consultam estado). Se não há endpoint, omitir. -->
-
-| Endpoint | Campo | Tipo | Obrigatório | Restrição de formato | Mensagem de erro |
-|----------|-------|------|-------------|----------------------|------------------|
-|          |       |      |             |                      |                  |
-
-## API
-
-<!-- Convenções globais (rota, paginação, HTTP codes, formato de erro): ver docs/apiContracts.md.
-Documentar aqui apenas contratos ESPECÍFICOS desta feature.
-Se feature backend sem HTTP exposto (worker/job) ou frontend-only: omitir seção. -->
-
-### {{MÉTODO}} {{rota}}
-
-**Auth**: <!-- Bearer / público / papel mínimo exigido -->
-**Rate limit**: <!-- categoria (ver docs/conventions.md) -->
-
-**Request:**
-```json
-{
-}
-```
-
-**Response 200:**
-```json
-{
-}
-```
-
-**Erros específicos desta feature:**
-| Status | Código de domínio | Quando |
-|--------|------------------|--------|
-| 422 | | RN-NNN violada |
-| 409 | | |
-
-## Integrações Externas
-
-<!-- Sistemas terceiros que esta feature consome ou notifica.
-Se não houver: omitir seção. -->
-
-| Sistema | Direção | Protocolo | Timeout | Retry | Fallback |
-|---------|---------|-----------|---------|-------|----------|
-|         |         |           |         |       |          |
-
-## Regras de Negócio
-
-<!-- Invariantes do domínio que envolvem estado (banco, cache, contexto).
-Distintas de validação de entrada — estas são executadas no serviço, pós-schema.
-Enforcement point = onde a regra é verificada no código (service, middleware, DB constraint). -->
-
-| ID | Regra | Enforcement point | Código de erro |
-|----|-------|------------------|----------------|
-| RN-001 | | service / db constraint / middleware | |
-| RN-002 | | | |
+# Contracts — {{NOME}}
+
+> Contratos executáveis da feature: modelo de dados, API, integrações e regras de negócio.
+> Gerado pelo /sf-design a partir de PRD + TRD. NUNCA editado manualmente.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: /sf-design — projeção combinada:
+- TRD §4 §Área-DB (schema, índices) → seção "Dados"
+- TRD §2.3 Validações de entrada (schema) → seção "Validações de Entrada"
+- TRD §2.1 Endpoints + §6 Integrações Externas → seção "API" e "Integrações"
+- PRD §5 Regras de Negócio → seção "Regras de Negócio" (enforcement point vem do TRD)
+Complementa (não repete) docs/apiContracts.md.
+
+ATUALIZAÇÃO: Sempre regenerado junto com os specs. NUNCA editado manualmente.
+
+REGRA DE OURO: Se algo aqui diverge de PRD ou TRD, os docs source vencem.
+Re-rode /sf-design.
+
+DISTINÇÃO CRÍTICA (3 camadas):
+- Camada 1 — Schema de DADOS: estrutura do banco (tabela, coluna, tipo, constraint DB)
+  → vira migration SQL
+  → seção "Dados"
+- Camada 2 — VALIDAÇÃO DE ENTRADA: restrição de formato/tipo do request
+  → verificada ANTES da lógica de negócio, no DTO/model via anotações
+  → ex: "email é string, obrigatório, formato válido, max 255 chars"
+  → seção "Validações de Entrada"
+- Camada 3 — REGRA DE NEGÓCIO: invariante do domínio, envolve estado
+  → verificada NO SERVIÇO, pós-schema pós-validação
+  → ex: "email não pode estar cadastrado em outra conta ativa"
+  → seção "Regras de Negócio"
+
+Essas três camadas não se sobrepõem. Regras em uma camada não aparecem na outra.
+
+CONVENÇÕES GLOBAIS: NÃO duplicar aqui o que já está em docs/apiContracts.md
+(paginação, HTTP codes genéricos, formato de erro, convenções de rota). Apenas referenciar.
+Colocar aqui apenas o que é ESPECÍFICO desta feature.
+
+PARA CODERS:
+- Campos de dados: tipos EXATOS do banco (varchar(255), não "string")
+- Requests/responses JSON: completos, com todos os campos nomeados
+- Regras de negócio: RN-NNN com enforcement point explícito
+- Integrações: timeout + retry + fallback obrigatórios
+
+=============================================================================
+-->
+
+## Dados
+
+<!-- Entidades tocadas por esta feature. Dois casos:
+A) Tabela nova → usar subseção "Tabelas novas"
+B) Alteração em tabela existente → usar subseção "Alterações"
+Se nenhum dos dois: omitir seção Dados inteira. -->
+
+### Tabelas novas
+
+#### {{tabela}}
+
+> {{descrição em 1 linha}}
+
+| Coluna | Tipo | Nullable | Default | Constraint | Descrição |
+|--------|------|----------|---------|------------|-----------|
+|        |      |          |         |            |           |
+
+**Relações:**
+- `campo_id` → `tabela_ref(id)` ON DELETE RESTRICT / CASCADE / SET NULL
+
+**Índices:**
+- `idx_{{tabela}}_{{campo}}` em `(campo)` — justificativa (qual query usa)
+
+### Alterações em tabelas existentes
+
+<!-- Uma subseção por tabela alterada. Listar apenas o que MUDA. -->
+
+#### {{tabela_existente}}
+
+| Operação | Coluna / Índice | Detalhe |
+|----------|-----------------|---------|
+| ADD COLUMN | `nome_coluna` | tipo + constraint + default |
+| ALTER COLUMN | `nome_coluna` | o que muda (tipo, nullable, default) |
+| DROP COLUMN | `nome_coluna` | justificativa + impacto em dados |
+| ADD INDEX | `idx_nome` | colunas + justificativa |
+| ADD FK | `campo_id` | referência + ON DELETE |
+
+## Validações de Entrada (schema)
+
+<!-- Restrições de formato/tipo verificadas ANTES da lógica de negócio.
+Viram anotações/atributos de validação no DTO/model de request.
+NÃO são regras de negócio (que consultam estado). Se não há endpoint, omitir. -->
+
+| Endpoint | Campo | Tipo | Obrigatório | Restrição de formato | Mensagem de erro |
+|----------|-------|------|-------------|----------------------|------------------|
+|          |       |      |             |                      |                  |
+
+## API
+
+<!-- Convenções globais (rota, paginação, HTTP codes, formato de erro): ver docs/apiContracts.md.
+Documentar aqui apenas contratos ESPECÍFICOS desta feature.
+Se feature backend sem HTTP exposto (worker/job) ou frontend-only: omitir seção. -->
+
+### {{MÉTODO}} {{rota}}
+
+**Auth**: <!-- Bearer / público / papel mínimo exigido -->
+**Rate limit**: <!-- categoria (ver docs/conventions.md) -->
+
+**Request:**
+```json
+{
+}
+```
+
+**Response 200:**
+```json
+{
+}
+```
+
+**Erros específicos desta feature:**
+| Status | Código de domínio | Quando |
+|--------|------------------|--------|
+| 422 | | RN-NNN violada |
+| 409 | | |
+
+## Integrações Externas
+
+<!-- Sistemas terceiros que esta feature consome ou notifica.
+Se não houver: omitir seção. -->
+
+| Sistema | Direção | Protocolo | Timeout | Retry | Fallback |
+|---------|---------|-----------|---------|-------|----------|
+|         |         |           |         |       |          |
+
+## Regras de Negócio
+
+<!-- Invariantes do domínio que envolvem estado (banco, cache, contexto).
+Distintas de validação de entrada — estas são executadas no serviço, pós-schema.
+Enforcement point = onde a regra é verificada no código (service, middleware, DB constraint). -->
+
+| ID | Regra | Enforcement point | Código de erro |
+|----|-------|------------------|----------------|
+| RN-001 | | service / db constraint / middleware | |
+| RN-002 | | | |

package/templates/.github/templates/specs/scenarios.template.md

@@ -1,117 +1,125 @@
-# Scenarios — {{NOME}}
-
-> Critérios de aceite + fluxos + estados de UI. Fonte de verdade para o Reviewer.
-> Gerado pelo /sf-design a partir do SDD. NUNCA editado manualmente.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-ORIGEM: /sf-design — projeção do SDD §Área-Backend (fluxos/validações) + §Área-Frontend
-        (telas/componentes) + §9 Estratégia de Testes + Critérios de Aceite.
-ATUALIZAÇÃO: Sempre regenerado junto com o SDD. NUNCA editado manualmente.
-
-REGRA DE OURO: Se algo aqui diverge do SDD, o SDD vence. Re-rode /sf-design.
-
-TERMINOLOGIA (dois níveis de pré-condição):
-- PRÉ-CONDIÇÕES GLOBAIS (seção no topo): estado que aplica a TODOS os cenários abaixo.
-  Ex: "sistema populado com seed", "usuário X existe em papel Y".
-- PRÉ-CONDIÇÃO DO CA (dentro do CA): estado ADICIONAL específico daquele CA.
-  Ex: "produto com estoque = 0" em CA que testa venda sem estoque.
-
-REGRAS DE PREENCHIMENTO:
-- 1 CA = 1 regra de negócio testável (não agrupar múltiplas regras num CA)
-- Cada CA DEVE ter um teste mapeado — sem teste = CA inválido
-- Fluxos de erro têm seção própria — não esconder em "Caminhos de erro" do happy path
-- Cada linha de "Fluxos de Erro" referencia o CA correspondente (coluna Ref CA)
-- Feature sem frontend: seção UI/Componentes = "N/A — backend-only"
-- Pré-condição = estado do banco/sistema, não input do usuário (input fica no When)
-- Estratégia de testes NÃO redefine frameworks — referencia docs/architecture.md
-
-PARA O REVIEWER:
-- Validar que cada CA-NNN tem teste executável correspondente
-- Usar esta tabela de estados como checklist de UI
-- Fluxos de erro são obrigatórios no happy path test suite (não opcionais)
-
-=============================================================================
--->
-
-## Pré-condições Globais
-
-<!-- Estado do sistema ANTES de executar os cenários abaixo. Aplicam a TODOS.
-Exemplos: quais registros precisam existir no banco, qual papel está autenticado,
-quais flags de feature estão ativas. Se não houver: "Estado limpo — sem pré-condições." -->
-
-| Condição | Valor esperado |
-|----------|---------------|
-|          |               |
-
-## Fluxos — Happy Path
-
-<!-- 1 fluxo por entregável principal. Formato linear: quem faz o quê e qual resultado.
-Nível suficiente para coder implementar e reviewer validar — sem narrativa extra. -->
-
-### Fluxo: {{nome}}
-
-| Passo | Ator | Ação / Request | Resultado / Response |
-|-------|------|---------------|----------------------|
-| 1 | | | |
-| 2 | | | |
-
-## Fluxos — Erro e Edge Cases
-
-<!-- Desvios do happy path. Cada linha = 1 scenario testável.
-Não omitir: são obrigatórios nos testes de integração.
-Ref CA aponta pro CA detalhado abaixo que cobre este erro. -->
-
-| Cenário | Pré-condição | Ação | Resposta esperada | HTTP / Código | Ref CA |
-|---------|-------------|------|-------------------|---------------|--------|
-|         |             |      |                   |               |        |
-
-## UI / Componentes
-
-<!-- Se backend-only: escrever "N/A — feature sem frontend." e pular esta seção. -->
-
-### {{componente}}
-
-| Estado | Gatilho | O que exibe | Dado / Mensagem |
-|--------|---------|-------------|-----------------|
-| loading | | skeleton / spinner | — |
-| empty | | | |
-| error | | mensagem de erro | código ou texto |
-| success | | | |
-
-## Critérios de Aceite
-
-<!-- 1 CA = 1 regra de negócio testável. Given/When/Then em 1 linha cada.
-Pré-condição = estado do sistema ADICIONAL às pré-condições globais (não repetir). -->
-
-### CA-001: {{título da regra — imperativo curto}}
-
-- **Pré-condição**: <!-- estado adicional às globais. Ex: "produto com estoque = 0" -->
-- **Given**: <!-- contexto do ator -->
-- **When**: <!-- ação executada -->
-- **Then**: <!-- resultado observável e verificável -->
-- **Teste**: `unit|integration|e2e` — `caminho/do/arquivo_test.ext`
-
-### CA-002: {{título}}
-
-- **Pré-condição**:
-- **Given**:
-- **When**:
-- **Then**:
-- **Teste**:
-
-## Estratégia de Testes
-
-<!-- NÃO redefinir frameworks — usar os definidos em docs/architecture.md.
-Descrever escopo e cobertura esperada para esta feature. -->
-
-| Nível | Escopo nesta feature | Quando roda | Responsável |
-|-------|----------------------|-------------|-------------|
-| Unit | lógica de negócio isolada (serviços, validadores) | por task | coder |
-| Integration | fluxo request → DB → response | por fase | coder |
-| E2E | CAs críticos end-to-end | por feature | coder (escreve) + reviewer (valida) |
+# Scenarios — {{NOME}}
+
+> Critérios de aceite + fluxos + estados de UI. Fonte de verdade para o Reviewer.
+> Gerado pelo /sf-design a partir de PRD + TRD. NUNCA editado manualmente.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: /sf-design — projeção combinada:
+- PRD §3 Jornadas → Fluxos Happy Path
+- PRD §8 Cenários de Sucesso/Erro → Fluxos de Erro e Edge Cases
+- PRD §7 Telas/Fluxos UI → UI / Componentes (high-level)
+- PRD §5 RNs + §6 Validações de Domínio → Critérios de Aceite (Given/When/Then)
+- TRD §3 §Área-Frontend → detalhes de estados de UI (loading/empty/error/success)
+- TRD §8 Estratégia de Testes → Estratégia de Testes
+Critérios de Aceite ficam aqui (especiarias derivadas de RNs + jornadas).
+
+ATUALIZAÇÃO: Sempre regenerado junto com os specs. NUNCA editado manualmente.
+
+REGRA DE OURO: Se algo aqui diverge de PRD ou TRD, os docs source vencem.
+Re-rode /sf-design.
+
+TERMINOLOGIA (dois níveis de pré-condição):
+- PRÉ-CONDIÇÕES GLOBAIS (seção no topo): estado que aplica a TODOS os cenários abaixo.
+  Ex: "sistema populado com seed", "usuário X existe em papel Y".
+- PRÉ-CONDIÇÃO DO CA (dentro do CA): estado ADICIONAL específico daquele CA.
+  Ex: "produto com estoque = 0" em CA que testa venda sem estoque.
+
+REGRAS DE PREENCHIMENTO:
+- 1 CA = 1 regra de negócio testável (não agrupar múltiplas regras num CA)
+- Cada CA DEVE ter um teste mapeado — sem teste = CA inválido
+- Fluxos de erro têm seção própria — não esconder em "Caminhos de erro" do happy path
+- Cada linha de "Fluxos de Erro" referencia o CA correspondente (coluna Ref CA)
+- Feature sem frontend: seção UI/Componentes = "N/A — backend-only"
+- Pré-condição = estado do banco/sistema, não input do usuário (input fica no When)
+- Estratégia de testes NÃO redefine frameworks — referencia docs/architecture.md
+
+PARA O REVIEWER:
+- Validar que cada CA-NNN tem teste executável correspondente
+- Usar esta tabela de estados como checklist de UI
+- Fluxos de erro são obrigatórios no happy path test suite (não opcionais)
+
+=============================================================================
+-->
+
+## Pré-condições Globais
+
+<!-- Estado do sistema ANTES de executar os cenários abaixo. Aplicam a TODOS.
+Exemplos: quais registros precisam existir no banco, qual papel está autenticado,
+quais flags de feature estão ativas. Se não houver: "Estado limpo — sem pré-condições." -->
+
+| Condição | Valor esperado |
+|----------|---------------|
+|          |               |
+
+## Fluxos — Happy Path
+
+<!-- 1 fluxo por entregável principal. Formato linear: quem faz o quê e qual resultado.
+Nível suficiente para coder implementar e reviewer validar — sem narrativa extra. -->
+
+### Fluxo: {{nome}}
+
+| Passo | Ator | Ação / Request | Resultado / Response |
+|-------|------|---------------|----------------------|
+| 1 | | | |
+| 2 | | | |
+
+## Fluxos — Erro e Edge Cases
+
+<!-- Desvios do happy path. Cada linha = 1 scenario testável.
+Não omitir: são obrigatórios nos testes de integração.
+Ref CA aponta pro CA detalhado abaixo que cobre este erro. -->
+
+| Cenário | Pré-condição | Ação | Resposta esperada | HTTP / Código | Ref CA |
+|---------|-------------|------|-------------------|---------------|--------|
+|         |             |      |                   |               |        |
+
+## UI / Componentes
+
+<!-- Se backend-only: escrever "N/A — feature sem frontend." e pular esta seção. -->
+
+### {{componente}}
+
+| Estado | Gatilho | O que exibe | Dado / Mensagem |
+|--------|---------|-------------|-----------------|
+| loading | | skeleton / spinner | — |
+| empty | | | |
+| error | | mensagem de erro | código ou texto |
+| success | | | |
+
+## Critérios de Aceite
+
+<!-- 1 CA = 1 regra de negócio testável. Given/When/Then em 1 linha cada.
+Pré-condição = estado do sistema ADICIONAL às pré-condições globais (não repetir). -->
+
+### CA-001: {{título da regra — imperativo curto}}
+
+- **Pré-condição**: <!-- estado adicional às globais. Ex: "produto com estoque = 0" -->
+- **Given**: <!-- contexto do ator -->
+- **When**: <!-- ação executada -->
+- **Then**: <!-- resultado observável e verificável -->
+- **Teste**: `unit|integration|e2e` — `caminho/do/arquivo_test.ext`
+
+### CA-002: {{título}}
+
+- **Pré-condição**:
+- **Given**:
+- **When**:
+- **Then**:
+- **Teste**:
+
+## Estratégia de Testes
+
+<!-- NÃO redefinir frameworks — usar os definidos em docs/architecture.md.
+Descrever escopo e cobertura esperada para esta feature. -->
+
+| Nível | Escopo nesta feature | Quando roda | Responsável |
+|-------|----------------------|-------------|-------------|
+| Unit | lógica de negócio isolada (serviços, validadores) | por task | coder |
+| Integration | fluxo request → DB → response | por fase | coder |
+| E2E | CAs críticos end-to-end | por feature | coder (escreve) + reviewer (valida) |