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

package/templates/.github/rules.md

@@ -1,229 +1,229 @@
-# Regras de Desenvolvimento
-
-> Regras que todos os agentes de desenvolvimento devem seguir.
-> Lido pelo Coder/Senior Coder e Reviewer antes de cada task.
-> Aplicado globalmente a todas as features.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-QUANDO LER: Toda vez que /sf-dev executar uma task. Obrigatório.
-QUEM LÊ: Coder, Senior Coder e Reviewer.
-COMO USAR: Regras aqui são LEI — não são sugestões. Violações reprovam a task no quality gate.
-
-PERSONALIZAÇÃO: Este arquivo é editado manualmente pelo time.
-As regras abaixo são o padrão do framework. O time pode:
-- Adicionar regras específicas da stack
-- Remover regras que não se aplicam
-- Ajustar convenções ao projeto
-
-=============================================================================
--->
-
-## Regras Invioláveis
-
-1. **Spec-first**: Nenhuma task pode ser executada sem SDD aprovado
-2. **SDD é a fonte**: O coder lê APENAS o SDD + task — nunca consulta PRD ou PM diretamente
-3. **Um commit por task**: Cada task gera exatamente 1 commit
-4. **Sem invenção**: Se o SDD não especifica, o coder NÃO assume — para e reporta
-5. **Entregáveis contínuos**: Toda feature é faseada em entregáveis incrementais. Cada fase entrega valor ao usuário e pode ir para produção independentemente. Nunca "tudo ou nada" — sempre "pequeno e constante"
-6. **Nunca na main**: Todo código é desenvolvido em branch própria. Merge apenas via PR aprovado pelo usuário
-
-## Convenções de Código
-
-### Padrão geral
-- Todo código segue a stack e convenções de `docs/architecture.md` + `docs/conventions.md`
-- Nomes em inglês (código) — documentação em português
-- Sem código morto (comentado) — se não usa, apaga
-- Sem secrets hardcoded — sempre variáveis de ambiente
-
-### Backend
-- Testes obrigatórios: mínimo happy path + 1 cenário de erro
-- Validação de input na borda (controller/handler) — não no service
-- Erros de negócio: usar códigos definidos em `docs/conventions.md` (seção Códigos de Erro do Domínio)
-- Tipos explícitos (sem `any`, `object`, `dynamic` genéricos)
-
-### Frontend
-- Componentes tipados com props documentadas
-- Estados explícitos: loading, empty, error, success
-- Sem lógica de negócio no componente — delegar para hooks/services
-
-### Banco de dados
-- Toda migration tem rollback testado
-- Execução sequencial — nunca pular migrations
-- Seeds apenas para ambiente de desenvolvimento
-
-## Convenções de Git
-
-> **Escopo**: Estas regras se aplicam aos **repositórios em `projetos/`** (api, web, worker, etc.).
-> O projeto-base em si é o orquestrador — specs e docs ficam aqui, código fica nos repos.
-
-### Commits
-```
-tipo(TASK-ID): descrição curta
-
-Corpo opcional com detalhes.
-
-Refs: feat_cadastro_cliente
-```
-
-| Tipo | Quando usar |
-|------|-------------|
-| `feat` | Nova funcionalidade |
-| `fix` | Correção de bug |
-| `refactor` | Mudança sem alterar comportamento |
-| `test` | Adição/alteração de testes |
-| `docs` | Documentação |
-| `chore` | Configuração, build, CI |
-
-### Branches
-```
-feature/feat_cadastro_cliente
-feature/feat_mvp_fase1
-bugfix/bug_cpf_duplicado
-task/task_otimizar_listagem
-```
-
-| Regra | Descrição |
-|-------|-----------|
-| Base | Sempre a partir de `main` atualizada (origin) |
-| Merge | Via Pull Request aprovado pelo usuário — NUNCA merge automático |
-| Conflitos | Resolver antes de mergear — nunca force push em branch compartilhada |
-
-### Git Workflow (5 passos obrigatórios)
-
-O /sf-dev DEVE seguir este fluxo para CADA fase de entrega:
-
-#### Passo 1 — Antes de codar
-```bash
-# Verificar working tree limpo
-git status
-# Se há mudanças pendentes → sugerir commit ou stash antes de prosseguir
-# NUNCA começar a codar com working tree sujo
-```
-
-#### Passo 2 — Criar branch
-```bash
-# Atualizar main a partir do remote
-git checkout main
-git pull origin main
-
-# Criar branch para a fase
-git checkout -b feature/{nome}_fase{N}
-# Ex: feature/feat_mvp_fase1
-```
-- Branch criada no **repo do serviço** (projetos/api, projetos/web, etc.)
-- Se a fase afeta múltiplos repos → branch com mesmo nome em cada um
-- NUNCA desenvolver direto na main
-
-#### Passo 3 — Ao terminar a fase
-```bash
-# Atualizar Progresso.md com status da fase
-# Push da branch
-git push origin feature/{nome}_fase{N}
-
-# Abrir PR com template detalhado (ver seção abaixo)
-gh pr create --title "..." --body "..."
-```
-- Deixar ambiente local **rodando** (docker compose up + dotnet run + npm run dev)
-- Informar ao usuário que o ambiente está ON para testes manuais
-
-#### Passo 4 — Aguardar aprovação
-```
-⏸️ PARAR e aguardar.
-- O usuário revisa o PR, testa manualmente o ambiente local
-- Merge é MANUAL — o agente NUNCA faz merge
-- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
-```
-
-#### Passo 5 — Após merge (quando usuário confirmar)
-```bash
-# Atualizar main local
-git checkout main
-git pull origin main
-
-# Limpar branches mergeadas
-git branch -d feature/{nome}_fase{N}
-git remote prune origin
-```
-
-### Template de Pull Request
-
-Todo PR aberto pelo /sf-dev DEVE seguir este formato:
-
-```markdown
-## Fase {N} — {Nome da fase}
-
-### O que foi entregue
-- [ ] {Entregável 1 da fase}
-- [ ] {Entregável 2 da fase}
-
-### Tasks concluídas
-| Task | Descrição | Testes |
-|------|-----------|--------|
-| BACK-001 | Criar endpoint X | ✅ unit + integration |
-| DB-001 | Migration tabela Y | ✅ rollback testado |
-| FRONT-001 | Tela de cadastro | ✅ unit |
-
-### Testes
-- ✅ Unit tests passando ({N}/{N})
-- ✅ Integration tests passando ({N}/{N})
-- ✅ Security Review aprovado
-- ⬜ E2E (aguardando teste manual do usuário)
-
-### Como testar manualmente
-1. Ambiente já está rodando em:
-   - API: http://localhost:8080
-   - Web: http://localhost:3000
-   - Banco: localhost:5432
-2. Fluxo para testar:
-   - {Passo 1 do teste manual}
-   - {Passo 2 do teste manual}
-   - {Resultado esperado}
-
-### Observações
-- {Decisões tomadas, trade-offs, pontos de atenção}
-```
-
-## Quality Gate (por task)
-
-> Checklist obrigatório. O Reviewer valida TODOS os itens antes de aprovar.
-
-- [ ] Código compila sem erros
-- [ ] Testes passam (se aplicável à task)
-- [ ] Lint limpo (sem warnings não justificados)
-- [ ] Critérios de aceite da task atendidos (ref SDD §9)
-- [ ] Sem TODOs no código sem justificativa
-- [ ] Sem secrets hardcoded
-- [ ] Commit segue convenção: `tipo(TASK-ID): descrição`
-- [ ] Arquivos listados na task foram os únicos modificados (sem side effects)
-
-## Regras por Stack
-
-> Seção opcional. Adicionar regras específicas da tecnologia escolhida.
-> Exemplos abaixo — remover/ajustar conforme o projeto.
-
-<!--
-### Node.js / TypeScript
-- ESLint + Prettier como formatador
-- Strict mode no tsconfig
-- Path aliases configurados (@/modules, @/shared)
-
-### Python
-- Ruff como linter/formatter
-- Type hints obrigatórios (mypy strict)
-- Virtual environment (venv ou poetry)
-
-### React / Next.js
-- Server Components por padrão, Client Components só quando necessário
-- Zustand ou Context para estado global (não Redux)
-- Tailwind CSS para estilos
--->
-
----
-
-> **Atualização**: Editado manualmente pelo time. Aplicado globalmente a todas as features.
+# Regras de Desenvolvimento
+
+> Regras que todos os agentes de desenvolvimento devem seguir.
+> Lido pelo Coder/Senior Coder e Reviewer antes de cada task.
+> Aplicado globalmente a todas as features.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO LER: Toda vez que /sf-dev executar uma task. Obrigatório.
+QUEM LÊ: Coder, Senior Coder e Reviewer.
+COMO USAR: Regras aqui são LEI — não são sugestões. Violações reprovam a task no quality gate.
+
+PERSONALIZAÇÃO: Este arquivo é editado manualmente pelo time.
+As regras abaixo são o padrão do framework. O time pode:
+- Adicionar regras específicas da stack
+- Remover regras que não se aplicam
+- Ajustar convenções ao projeto
+
+=============================================================================
+-->
+
+## Regras Invioláveis
+
+1. **Spec-first**: Nenhuma task pode ser executada sem PRD e/ou TRD aprovados (+ `specs/{nome}/` gerado)
+2. **specs/ é a fonte do coder**: O coder lê APENAS `specs/{nome}/` + task — nunca consulta PRD/TRD ou PM diretamente
+3. **Um commit por task**: Cada task gera exatamente 1 commit
+4. **Sem invenção**: Se `specs/` não especifica, o coder NÃO assume — para e reporta
+5. **Entregáveis contínuos**: Toda feature é faseada em entregáveis incrementais. Cada fase entrega valor ao usuário e pode ir para produção independentemente. Nunca "tudo ou nada" — sempre "pequeno e constante"
+6. **Nunca na main**: Todo código é desenvolvido em branch própria. Merge apenas via PR aprovado pelo usuário
+
+## Convenções de Código
+
+### Padrão geral
+- Todo código segue a stack e convenções de `docs/architecture.md` + `docs/conventions.md`
+- Nomes em inglês (código) — documentação em português
+- Sem código morto (comentado) — se não usa, apaga
+- Sem secrets hardcoded — sempre variáveis de ambiente
+
+### Backend
+- Testes obrigatórios: mínimo happy path + 1 cenário de erro
+- Validação de input na borda (controller/handler) — não no service
+- Erros de negócio: usar códigos definidos em `docs/conventions.md` (seção Códigos de Erro do Domínio)
+- Tipos explícitos (sem `any`, `object`, `dynamic` genéricos)
+
+### Frontend
+- Componentes tipados com props documentadas
+- Estados explícitos: loading, empty, error, success
+- Sem lógica de negócio no componente — delegar para hooks/services
+
+### Banco de dados
+- Toda migration tem rollback testado
+- Execução sequencial — nunca pular migrations
+- Seeds apenas para ambiente de desenvolvimento
+
+## Convenções de Git
+
+> **Escopo**: Estas regras se aplicam aos **repositórios em `projetos/`** (api, web, worker, etc.).
+> O projeto-base em si é o orquestrador — specs e docs ficam aqui, código fica nos repos.
+
+### Commits
+```
+tipo(TASK-ID): descrição curta
+
+Corpo opcional com detalhes.
+
+Refs: feat_cadastro_cliente
+```
+
+| Tipo | Quando usar |
+|------|-------------|
+| `feat` | Nova funcionalidade |
+| `fix` | Correção de bug |
+| `refactor` | Mudança sem alterar comportamento |
+| `test` | Adição/alteração de testes |
+| `docs` | Documentação |
+| `chore` | Configuração, build, CI |
+
+### Branches
+```
+feature/feat_cadastro_cliente
+feature/feat_mvp_fase1
+bugfix/bug_cpf_duplicado
+task/task_otimizar_listagem
+```
+
+| Regra | Descrição |
+|-------|-----------|
+| Base | Sempre a partir de `main` atualizada (origin) |
+| Merge | Via Pull Request aprovado pelo usuário — NUNCA merge automático |
+| Conflitos | Resolver antes de mergear — nunca force push em branch compartilhada |
+
+### Git Workflow (5 passos obrigatórios)
+
+O /sf-dev DEVE seguir este fluxo para CADA fase de entrega:
+
+#### Passo 1 — Antes de codar
+```bash
+# Verificar working tree limpo
+git status
+# Se há mudanças pendentes → sugerir commit ou stash antes de prosseguir
+# NUNCA começar a codar com working tree sujo
+```
+
+#### Passo 2 — Criar branch
+```bash
+# Atualizar main a partir do remote
+git checkout main
+git pull origin main
+
+# Criar branch para a fase
+git checkout -b feature/{nome}_fase{N}
+# Ex: feature/feat_mvp_fase1
+```
+- Branch criada no **repo do serviço** (projetos/api, projetos/web, etc.)
+- Se a fase afeta múltiplos repos → branch com mesmo nome em cada um
+- NUNCA desenvolver direto na main
+
+#### Passo 3 — Ao terminar a fase
+```bash
+# Atualizar Progresso.md com status da fase
+# Push da branch
+git push origin feature/{nome}_fase{N}
+
+# Abrir PR com template detalhado (ver seção abaixo)
+gh pr create --title "..." --body "..."
+```
+- Deixar ambiente local **rodando** (docker compose up + dotnet run + npm run dev)
+- Informar ao usuário que o ambiente está ON para testes manuais
+
+#### Passo 4 — Aguardar aprovação
+```
+⏸️ PARAR e aguardar.
+- O usuário revisa o PR, testa manualmente o ambiente local
+- Merge é MANUAL — o agente NUNCA faz merge
+- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+```
+
+#### Passo 5 — Após merge (quando usuário confirmar)
+```bash
+# Atualizar main local
+git checkout main
+git pull origin main
+
+# Limpar branches mergeadas
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+### Template de Pull Request
+
+Todo PR aberto pelo /sf-dev DEVE seguir este formato:
+
+```markdown
+## Fase {N} — {Nome da fase}
+
+### O que foi entregue
+- [ ] {Entregável 1 da fase}
+- [ ] {Entregável 2 da fase}
+
+### Tasks concluídas
+| Task | Descrição | Testes |
+|------|-----------|--------|
+| BACK-001 | Criar endpoint X | ✅ unit + integration |
+| DB-001 | Migration tabela Y | ✅ rollback testado |
+| FRONT-001 | Tela de cadastro | ✅ unit |
+
+### Testes
+- ✅ Unit tests passando ({N}/{N})
+- ✅ Integration tests passando ({N}/{N})
+- ✅ Security Review aprovado
+- ⬜ E2E (aguardando teste manual do usuário)
+
+### Como testar manualmente
+1. Ambiente já está rodando em:
+   - API: http://localhost:8080
+   - Web: http://localhost:3000
+   - Banco: localhost:5432
+2. Fluxo para testar:
+   - {Passo 1 do teste manual}
+   - {Passo 2 do teste manual}
+   - {Resultado esperado}
+
+### Observações
+- {Decisões tomadas, trade-offs, pontos de atenção}
+```
+
+## Quality Gate (por task)
+
+> Checklist obrigatório. O Reviewer valida TODOS os itens antes de aprovar.
+
+- [ ] Código compila sem erros
+- [ ] Testes passam (se aplicável à task)
+- [ ] Lint limpo (sem warnings não justificados)
+- [ ] Critérios de aceite da task atendidos (ref `specs/{nome}/scenarios.md`)
+- [ ] Sem TODOs no código sem justificativa
+- [ ] Sem secrets hardcoded
+- [ ] Commit segue convenção: `tipo(TASK-ID): descrição`
+- [ ] Arquivos listados na task foram os únicos modificados (sem side effects)
+
+## Regras por Stack
+
+> Seção opcional. Adicionar regras específicas da tecnologia escolhida.
+> Exemplos abaixo — remover/ajustar conforme o projeto.
+
+<!--
+### Node.js / TypeScript
+- ESLint + Prettier como formatador
+- Strict mode no tsconfig
+- Path aliases configurados (@/modules, @/shared)
+
+### Python
+- Ruff como linter/formatter
+- Type hints obrigatórios (mypy strict)
+- Virtual environment (venv ou poetry)
+
+### React / Next.js
+- Server Components por padrão, Client Components só quando necessário
+- Zustand ou Context para estado global (não Redux)
+- Tailwind CSS para estilos
+-->
+
+---
+
+> **Atualização**: Editado manualmente pelo time. Aplicado globalmente a todas as features.