spec-first-copilot 0.7.0-beta.1 → 0.7.0

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

@@ -1,66 +1,66 @@
-# Brief — {{NOME}}
-
-> Contexto da feature para o coder: por quê, o quê e onde.
-> 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 de:
-- PRD §1 Contexto e Motivação → Problema / Solução
-- PRD §10 Fora de Escopo → Escopo (seção Fora)
-- PRD §11 Fases de Entrega (visão geral) → Escopo (seção Dentro)
-- TRD §1.1 Stack + §1.2 Arquitetura → Serviços tocados + Decisões principais
-- TRD §9 ADRs (resumo) → Decisões principais
-
-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.
-
-O brief é o "por quê + o quê + onde" destilado. O coder lê ANTES de abrir contracts.md.
-Sem narrativa longa — bullets objetivos. Código NÃO é derivado daqui.
-
-SOBRE "Serviços tocados":
-- Listar os repos de projetos.yaml que esta feature modifica
-- Incluir a área (BACK/FRONT/DB/INFRA) por serviço
-- Se first-run (setup), listar todos os repos que serão CRIADOS
-
-=============================================================================
--->
-
-## Problema
-
-<!-- 2-3 frases. O que está faltando ou quebrado que esta feature resolve. -->
-
-## Solução
-
-<!-- High level: como estamos resolvendo. Sem design técnico — isso está em contracts.md. -->
-
-## Serviços tocados
-
-<!-- Quais repos (de projetos.yaml) esta feature toca e em quais áreas. -->
-
-| Repo | Áreas | Tipo de mudança |
-|------|-------|-----------------|
-|      |       | nova funcionalidade / alteração / infra |
-
-## Escopo
-
-### Dentro
--
-
-### Fora
--
-
-## Decisões principais
-
-<!-- Mini-ADRs inline — só decisões específicas desta feature, não as globais de docs/decisions.md. -->
-
-| # | Decisão | Justificativa |
-|---|---------|---------------|
-| 1 |         |               |
+# Brief — {{NOME}}
+
+> Contexto da feature para o coder: por quê, o quê e onde.
+> 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 de:
+- PRD §1 Contexto e Motivação → Problema / Solução
+- PRD §10 Fora de Escopo → Escopo (seção Fora)
+- PRD §11 Fases de Entrega (visão geral) → Escopo (seção Dentro)
+- TRD §1.1 Stack + §1.2 Arquitetura → Serviços tocados + Decisões principais
+- TRD §9 ADRs (resumo) → Decisões principais
+
+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.
+
+O brief é o "por quê + o quê + onde" destilado. O coder lê ANTES de abrir contracts.md.
+Sem narrativa longa — bullets objetivos. Código NÃO é derivado daqui.
+
+SOBRE "Serviços tocados":
+- Listar os repos de projetos.yaml que esta feature modifica
+- Incluir a área (BACK/FRONT/DB/INFRA) por serviço
+- Se first-run (setup), listar todos os repos que serão CRIADOS
+
+=============================================================================
+-->
+
+## Problema
+
+<!-- 2-3 frases. O que está faltando ou quebrado que esta feature resolve. -->
+
+## Solução
+
+<!-- High level: como estamos resolvendo. Sem design técnico — isso está em contracts.md. -->
+
+## Serviços tocados
+
+<!-- Quais repos (de projetos.yaml) esta feature toca e em quais áreas. -->
+
+| Repo | Áreas | Tipo de mudança |
+|------|-------|-----------------|
+|      |       | nova funcionalidade / alteração / infra |
+
+## Escopo
+
+### Dentro
+-
+
+### Fora
+-
+
+## Decisões principais
+
+<!-- Mini-ADRs inline — só decisões específicas desta feature, não as globais de docs/decisions.md. -->
+
+| # | Decisão | Justificativa |
+|---|---------|---------------|
+| 1 |         |               |

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

@@ -1,147 +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 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 | | | |
+# 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 | | | |