spec-first-copilot 0.4.0 → 0.5.0-beta.0

package/templates/.github/templates/estrutura/architecture.template.md

@@ -0,0 +1,158 @@
+# Arquitetura
+
+> Arquitetura do sistema: containers, componentes, stack tecnológica, ambientes e deploy.
+> C4 Níveis 2-3 + camadas da stack + infraestrutura de runtime.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §2 (Stack), §3 (Arquitetura)
+e §6 (Infraestrutura — ambientes, deploy, CI/CD, rollback).
+ATUALIZAÇÃO: /merge-delta quando features adicionam containers, componentes,
+dependências de stack ou mudam ambientes/deploy.
+
+COMO GERAR:
+1. Ler TRD §3 (Arquitetura) — containers, padrões de comunicação, padrões de design
+2. Ler TRD §2 (Stack) — tecnologias por camada, versões
+3. Ler TRD §6 (Infraestrutura) — ambientes, deploy, CI/CD, rollback
+4. Montar diagrama C4 Nível 2 mostrando TODOS os containers e conexões
+5. Para cada container relevante, listar componentes internos (C4 Nível 3)
+6. Documentar stack principal com versões EXATAS (não "latest")
+7. Documentar ambientes (URLs, bancos, branches) e pipeline CI/CD concreto
+
+O QUE NÃO VAI AQUI:
+- Variáveis de ambiente → conventions.md
+- Monitoramento e observabilidade → conventions.md
+- Segurança (auth, CORS, rate limiting) → conventions.md
+- Alternativas descartadas de stack → conventions.md
+- Entidades e modelo de dados → domain.md
+
+REGRAS:
+- Versões fixadas (18.3.1, não ^18.0.0)
+- Cada container tem: tecnologia, responsabilidade, porta, tipo de comunicação
+- Padrões de design precisam de justificativa (não apenas nome)
+- Pipeline CI/CD deve ser concreto — passos reais e ferramentas
+- Rollback strategy obrigatória — "como voltar se der errado?"
+
+=============================================================================
+-->
+
+## Diagrama de Containers (C4 Nível 2)
+
+```
+<!-- Representação textual dos containers e suas conexões -->
+<!-- Usar formato: [Container] --protocolo--> [Container] -->
+```
+
+## Containers
+
+| Container | Tecnologia | Responsabilidade | Porta | Comunicação |
+|-----------|-----------|-----------------|-------|-------------|
+|           |           |                 |       |             |
+
+## Componentes Principais (C4 Nível 3)
+
+<!-- Repetir esta seção para cada container que tenha componentes internos relevantes -->
+
+### {{Container}}
+
+| Componente | Responsabilidade | Dependências internas | Dependências externas |
+|------------|-----------------|----------------------|----------------------|
+|            |                 |                      |                      |
+
+## Padrões de Comunicação
+
+### Síncrona (request/response)
+
+| De | Para | Protocolo | Formato | Observações |
+|----|------|-----------|---------|-------------|
+|    |      |           |         |             |
+
+### Assíncrona (eventos/filas)
+
+| Produtor | Tópico/Fila | Consumer | Formato | Garantia |
+|----------|-------------|----------|---------|----------|
+|          |             |          |         | at-least-once / exactly-once |
+
+## Padrões de Design Adotados
+
+| Padrão | Onde é usado | Justificativa | Ref decisão |
+|--------|-------------|---------------|-------------|
+|        |             |               |             |
+
+## Stack Principal
+
+| Camada | Tecnologia | Versão | Justificativa |
+|--------|-----------|--------|---------------|
+| Frontend | | | |
+| Backend | | | |
+| Banco de Dados | | | |
+| ORM/Query Builder | | | |
+| Autenticação | | | |
+| Testes | | | |
+| CI/CD | | | |
+
+<!-- Adicionar camadas conforme necessidade: Mobile, Cache, Fila, Monitoramento, etc. -->
+
+## Bibliotecas e Dependências por Camada
+
+<!-- Repetir bloco para cada camada com dependências relevantes -->
+
+### {{Camada}}
+
+| Pacote | Versão | Para quê |
+|--------|--------|----------|
+|        |        |          |
+
+## Ambientes
+
+| Ambiente | URL | Banco | Propósito | Branch |
+|----------|-----|-------|-----------|--------|
+| Local | `localhost:{{PORT}}` | local | Desenvolvimento | qualquer |
+| Staging | | | Testes e homologação | develop |
+| Produção | | | Usuários finais | main |
+
+## Deploy
+
+### Estratégia
+
+| Aspecto | Decisão |
+|---------|---------|
+| Plataforma | <!-- Docker? Serverless? VPS? Cloud provider? --> |
+| Orquestração | <!-- Kubernetes? ECS? PM2? --> |
+| Build | <!-- Docker multi-stage? Build nativo? --> |
+| Estratégia de deploy | <!-- Rolling? Blue-green? Canary? --> |
+
+### Pipeline CI/CD
+
+```
+push → lint → test → build → deploy(staging) → aprovação → deploy(prod)
+```
+
+| Etapa | Ferramenta | Trigger | Timeout |
+|-------|-----------|---------|---------|
+| Lint | <!-- eslint, ruff --> | push | |
+| Testes | <!-- jest, pytest --> | push | |
+| Build | <!-- docker build --> | push em main/develop | |
+| Deploy staging | <!-- CD tool --> | push em develop | |
+| Deploy produção | <!-- CD tool --> | aprovação manual | |
+
+### Rollback
+
+| Cenário | Procedimento | Responsável |
+|---------|-------------|-------------|
+| Bug em produção | <!-- Reverter deploy? Hotfix? --> | |
+| Migration com erro | <!-- Rollback da migration? --> | |
+| Serviço externo fora | <!-- Fallback? Circuit breaker? --> | |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

package/templates/{docs/_templates/estrutura/Seguranca.template.md → .github/templates/estrutura/conventions.template.md}

@@ -1,138 +1,202 @@
-# Segurança
-
-> Autenticação, autorização, CORS, rate limiting, LGPD, auditoria e proteção de dados.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-ORIGEM: Gerado pelo /setup-projeto a partir do TRD §7.
-ATUALIZAÇÃO: /merge-delta quando features adicionam permissões, dados pessoais ou políticas.
-
-COMO GERAR:
-1. Ler TRD §7 (Segurança) — autenticação, autorização, CORS, LGPD
-2. Autenticação: método, expiração, hash, refresh strategy
-3. Autorização: papéis e matriz de permissões (RBAC/ABAC)
-4. LGPD: mapear TODOS dados pessoais com base legal
-5. Auditoria: definir O QUE é logado, ONDE e POR QUANTO TEMPO
-
-REGRAS:
-- Matriz de permissões é DINÂMICA — cresce a cada feature (via merge-delta)
-- Dados pessoais da LGPD precisam de base legal ESPECÍFICA
-- Nunca armazenar senhas em texto plano (hash obrigatório)
-- Secrets nunca no código — sempre variáveis de ambiente
-- Rate limiting obrigatório em endpoints públicos (login, registro)
-- Auditoria obrigatória para operações destrutivas (delete, update de dados sensíveis)
-
-=============================================================================
--->
-
-## Autenticação
-
-| Aspecto | Implementação |
-|---------|--------------|
-| Método | <!-- JWT? Session? OAuth2? --> |
-| Expiração access token | <!-- Ex: 15min --> |
-| Refresh token | <!-- Existe? Expiração? Rotação? --> |
-| Hash de senha | <!-- bcrypt rounds? argon2? --> |
-| Header | <!-- Authorization: Bearer {token} --> |
-| Armazenamento (client) | <!-- httpOnly cookie? localStorage? --> |
-
-### Fluxo de autenticação
-
-```
-<!-- Descrever o fluxo: login → token → refresh → logout -->
-```
-
-## Autorização
-
-### Modelo
-
-| Aspecto | Decisão |
-|---------|---------|
-| Tipo | <!-- RBAC / ABAC / RBAC + ABAC --> |
-| Onde é verificado | <!-- Middleware? Decorator? Service? --> |
-| Granularidade | <!-- Por rota? Por recurso? Por campo? --> |
-
-### Papéis
-
-| Papel | Descrição | Herda de |
-|-------|-----------|----------|
-|       |           | <!-- Hierarquia: admin herda de user? --> |
-
-### Matriz de Permissões
-
-> Atualizada a cada feature via /merge-delta.
-
-| Recurso | Ação | {{role_1}} | {{role_2}} | {{role_N}} |
-|---------|------|------------|------------|------------|
-|         | criar | | | |
-|         | ler | | | |
-|         | editar | | | |
-|         | deletar | | | |
-
-## CORS
-
-| Aspecto | Configuração |
-|---------|-------------|
-| Allowed Origins | <!-- Configurável por ambiente --> |
-| Allowed Methods | `GET, POST, PUT, PATCH, DELETE` |
-| Allowed Headers | `Authorization, Content-Type` |
-| Credentials | <!-- true/false --> |
-| Max Age | <!-- Preflight cache em segundos --> |
-
-## Rate Limiting
-
-| Categoria | Limite | Janela | Resposta |
-|-----------|--------|--------|----------|
-| Login/Registro | <!-- Ex: 5 req --> | <!-- Ex: 15min --> | 429 + Retry-After |
-| API autenticada | <!-- Ex: 100 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
-| API pública | <!-- Ex: 30 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
-| Upload | <!-- Ex: 10 req --> | <!-- Ex: 1h --> | 429 + Retry-After |
-
-## LGPD / Privacidade
-
-### Dados pessoais coletados
-
-| Dado | Base legal | Finalidade | Retenção | Criptografado? |
-|------|-----------|------------|----------|----------------|
-|      | <!-- Consentimento / Contrato / Legítimo interesse / Obrigação legal --> | | | |
-
-### Direitos do titular
-
-| Direito | Implementação | Endpoint/Fluxo |
-|---------|--------------|----------------|
-| Acesso aos dados | | <!-- Como o usuário acessa? --> |
-| Correção | | |
-| Exclusão (right to be forgotten) | | <!-- Soft delete? Hard delete? Anonimização? --> |
-| Portabilidade | | <!-- Formato de exportação? --> |
-| Revogação de consentimento | | |
-
-## Auditoria
-
-| O que é logado | Quando | Onde armazena | Retenção |
-|----------------|--------|---------------|----------|
-| Login/Logout | sempre | | |
-| Alteração de dados sensíveis | sempre | | |
-| Operações destrutivas (DELETE) | sempre | | |
-| Falhas de autenticação | sempre | | |
-| Mudanças de permissão | sempre | | |
-
-## Proteção de Dados em Trânsito e Repouso
-
-| Aspecto | Implementação |
-|---------|--------------|
-| TLS | <!-- Versão mínima? --> |
-| Dados sensíveis em repouso | <!-- Criptografia? Quais campos? --> |
-| Backup | <!-- Criptografado? Frequência? --> |
-
----
-
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-|      |         |      |           |
+# Convenções
+
+> Regras transversais do sistema: autenticação, autorização, CORS, rate limiting,
+> LGPD, auditoria, variáveis de ambiente, monitoramento, códigos de erro de domínio
+> e versionamento de dependências. Padrões que todo código segue.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §7 (Segurança),
+§6 (Infra — env vars, domínios, monitoramento), §5 (API — códigos de erro
+de domínio) e §2 (Stack — alternativas descartadas, versionamento).
+ATUALIZAÇÃO: /merge-delta quando features adicionam permissões, papéis,
+dados pessoais, variáveis de ambiente, códigos de erro ou alteram políticas.
+
+COMO GERAR:
+1. Ler TRD §7 (Segurança) — autenticação, autorização, CORS, LGPD
+2. Ler TRD §6 (Infra) — variáveis de ambiente, domínios, monitoramento
+3. Ler TRD §5 (API) — códigos de erro do domínio (reutilizáveis)
+4. Ler TRD §2 (Stack) — alternativas descartadas e versionamento de dependências
+5. Autenticação: método, expiração, hash, refresh strategy
+6. Autorização: papéis e matriz de permissões (RBAC/ABAC)
+7. LGPD: mapear TODOS dados pessoais com base legal específica
+8. Auditoria: O QUE é logado, ONDE, POR QUANTO TEMPO
+9. Variáveis de ambiente: NUNCA valores reais, só exemplos
+
+O QUE NÃO VAI AQUI:
+- Rotas, paginação, filtros, catálogo de endpoints → apiContracts.md
+- Containers, ambientes, deploy → architecture.md
+- Entidades, tabelas → domain.md
+
+REGRAS:
+- Matriz de permissões é DINÂMICA — cresce a cada feature (via merge-delta)
+- Dados pessoais da LGPD precisam de base legal ESPECÍFICA
+- Nunca armazenar senhas em texto plano (hash obrigatório)
+- Secrets nunca no código — sempre variáveis de ambiente
+- Rate limiting obrigatório em endpoints públicos (login, registro)
+- Auditoria obrigatória para operações destrutivas
+- Códigos de erro do domínio são globais — reutilizáveis por múltiplos endpoints
+
+=============================================================================
+-->
+
+## Autenticação
+
+| Aspecto | Implementação |
+|---------|--------------|
+| Método | <!-- JWT? Session? OAuth2? --> |
+| Expiração access token | <!-- Ex: 15min --> |
+| Refresh token | <!-- Existe? Expiração? Rotação? --> |
+| Hash de senha | <!-- bcrypt rounds? argon2? --> |
+| Header | <!-- Authorization: Bearer {token} --> |
+| Armazenamento (client) | <!-- httpOnly cookie? localStorage? --> |
+
+### Fluxo de autenticação
+
+```
+<!-- Descrever o fluxo: login → token → refresh → logout -->
+```
+
+## Autorização
+
+### Modelo
+
+| Aspecto | Decisão |
+|---------|---------|
+| Tipo | <!-- RBAC / ABAC / RBAC + ABAC --> |
+| Onde é verificado | <!-- Middleware? Decorator? Service? --> |
+| Granularidade | <!-- Por rota? Por recurso? Por campo? --> |
+
+### Papéis
+
+| Papel | Descrição | Herda de |
+|-------|-----------|----------|
+|       |           | <!-- Hierarquia: admin herda de user? --> |
+
+### Matriz de Permissões
+
+> Atualizada a cada feature via /merge-delta.
+
+| Recurso | Ação | {{role_1}} | {{role_2}} | {{role_N}} |
+|---------|------|------------|------------|------------|
+|         | criar | | | |
+|         | ler | | | |
+|         | editar | | | |
+|         | deletar | | | |
+
+## CORS
+
+| Aspecto | Configuração |
+|---------|-------------|
+| Allowed Origins | <!-- Configurável por ambiente --> |
+| Allowed Methods | `GET, POST, PUT, PATCH, DELETE` |
+| Allowed Headers | `Authorization, Content-Type` |
+| Credentials | <!-- true/false --> |
+| Max Age | <!-- Preflight cache em segundos --> |
+
+## Rate Limiting
+
+| Categoria | Limite | Janela | Resposta |
+|-----------|--------|--------|----------|
+| Login/Registro | <!-- Ex: 5 req --> | <!-- Ex: 15min --> | 429 + Retry-After |
+| API autenticada | <!-- Ex: 100 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
+| API pública | <!-- Ex: 30 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
+| Upload | <!-- Ex: 10 req --> | <!-- Ex: 1h --> | 429 + Retry-After |
+
+## LGPD / Privacidade
+
+### Dados pessoais coletados
+
+| Dado | Base legal | Finalidade | Retenção | Criptografado? |
+|------|-----------|------------|----------|----------------|
+|      | <!-- Consentimento / Contrato / Legítimo interesse / Obrigação legal --> | | | |
+
+### Direitos do titular
+
+| Direito | Implementação | Endpoint/Fluxo |
+|---------|--------------|----------------|
+| Acesso aos dados | | |
+| Correção | | |
+| Exclusão (right to be forgotten) | | <!-- Soft delete? Hard delete? Anonimização? --> |
+| Portabilidade | | <!-- Formato de exportação? --> |
+| Revogação de consentimento | | |
+
+## Auditoria
+
+| O que é logado | Quando | Onde armazena | Retenção |
+|----------------|--------|---------------|----------|
+| Login/Logout | sempre | | |
+| Alteração de dados sensíveis | sempre | | |
+| Operações destrutivas (DELETE) | sempre | | |
+| Falhas de autenticação | sempre | | |
+| Mudanças de permissão | sempre | | |
+
+## Proteção de Dados em Trânsito e Repouso
+
+| Aspecto | Implementação |
+|---------|--------------|
+| TLS | <!-- Versão mínima? --> |
+| Dados sensíveis em repouso | <!-- Criptografia? Quais campos? --> |
+| Backup | <!-- Criptografado? Frequência? --> |
+
+## Variáveis de Ambiente
+
+> NUNCA colocar valores reais aqui. Apenas nomes, descrição e exemplos.
+
+| Variável | Ambientes | Obrigatória | Descrição | Exemplo |
+|----------|-----------|-------------|-----------|---------|
+| `DATABASE_URL` | todos | sim | Conexão com banco | `postgres://user:pass@host:5432/db` |
+| `JWT_SECRET` | todos | sim | Chave de assinatura JWT | `sua-chave-secreta-aqui` |
+| `NODE_ENV` | todos | sim | Ambiente atual | `development` / `production` |
+
+## Domínios e DNS
+
+| Domínio | Aponta para | Certificado | Gerenciado por |
+|---------|-------------|-------------|----------------|
+|         |             | <!-- Let's Encrypt? AWS ACM? --> | |
+
+## Monitoramento e Observabilidade
+
+| Aspecto | Ferramenta | O que monitora |
+|---------|-----------|----------------|
+| Logs | <!-- Ex: CloudWatch, Datadog --> | |
+| APM | <!-- Ex: New Relic, Sentry --> | |
+| Uptime | <!-- Ex: Pingdom, UptimeRobot --> | |
+| Alertas | <!-- Ex: PagerDuty, Slack --> | |
+
+## Códigos de Erro do Domínio
+
+> Códigos reutilizáveis por múltiplos endpoints. Novos códigos são adicionados via /merge-delta.
+
+| Código | Descrição | HTTP padrão |
+|--------|-----------|-------------|
+| <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
+
+## Alternativas Tecnológicas Descartadas
+
+> Decisões já tomadas. Se alguém perguntar "por que não usamos X?", a resposta está aqui.
+
+| Tecnologia escolhida | Alternativa considerada | Por que descartamos | Ref decisão |
+|----------------------|------------------------|---------------------|-------------|
+|                      |                        |                     |             |
+
+## Convenções de Versionamento de Dependências
+
+| Aspecto | Convenção |
+|---------|-----------|
+| Versionamento | <!-- Semver? Pinned? --> |
+| Lock files | <!-- package-lock.json? yarn.lock? --> |
+| Atualização | <!-- Dependabot? Manual? Periodicidade? --> |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |