create-genia-os 2.0.0 → 2.1.1

package/template/.genia/development/checklists/pre-commit.md

@@ -0,0 +1,205 @@
+# Checklist: Pré-Commit
+
+> Verificações obrigatórias antes de qualquer commit.
+> Executado por @dev. Automatizável via git hooks.
+
+---
+
+## Objetivo
+
+Garantir que nenhum commit "sujo" entre no histórico do repositório. Um commit deve ser uma unidade de mudança coesa, funcional e segura. Esta checklist previne problemas que são muito mais custosos de corrigir depois do commit.
+
+---
+
+## Checklist Completo
+
+### Bloco 1 — Qualidade de Código (Obrigatório)
+
+```bash
+npm run lint
+```
+
+- [ ] Zero erros de lint
+- [ ] Zero warnings de lint (warnings são erros em potencial)
+- [ ] Nenhuma regra do ESLint desabilitada com `// eslint-disable` sem comentário explicativo
+
+```bash
+npm run typecheck
+```
+
+- [ ] Zero erros TypeScript
+- [ ] Nenhum `@ts-ignore` ou `@ts-expect-error` sem explicação no comentário
+- [ ] Sem `any` usado como atalho — tipagem explícita ou `unknown`
+
+---
+
+### Bloco 2 — Testes (Obrigatório)
+
+```bash
+npm run test
+```
+
+- [ ] Todos os testes passando
+- [ ] Nenhum teste em `skip` ou `xtest` que foi esquecido
+- [ ] Nenhum `test.only` esquecido (faria outros testes serem ignorados no CI)
+
+```bash
+npm run coverage
+```
+
+- [ ] Coverage >= 80% nas linhas modificadas
+- [ ] Se coverage caiu abaixo de 80%: adicionar testes antes de commitar
+
+---
+
+### Bloco 3 — Segurança (Obrigatório)
+
+Antes de executar `git add`, verifique todos os arquivos no diff:
+
+```bash
+git diff --staged
+```
+
+- [ ] Sem passwords, tokens, API keys ou secrets hardcodados
+- [ ] Sem credenciais de banco de dados no código
+- [ ] Sem URLs de ambiente hardcodadas (usar variáveis de ambiente)
+- [ ] Arquivo `.env` ou `.env.local` NÃO está sendo commitado
+- [ ] Sem chaves privadas (`.pem`, `.key`) no staged
+- [ ] Sem tokens de autenticação em nenhum arquivo
+
+**Se encontrar qualquer desses:** remova ANTES de commitar. Secrets no histórico git são permanentes e comprometem a segurança do projeto.
+
+---
+
+### Bloco 4 — Limpeza de Código (Obrigatório)
+
+Leia o diff uma vez como se fosse o reviewer:
+
+- [ ] Sem `console.log`, `console.debug`, `console.warn` de debug esquecidos
+- [ ] Sem código comentado desnecessariamente (use `git stash` se quiser salvar)
+- [ ] Sem imports não utilizados
+- [ ] Sem variáveis declaradas e não utilizadas
+- [ ] Sem arquivos de teste manual esquecidos (`test.html`, `debug.js`, etc.)
+
+---
+
+### Bloco 5 — Conformidade com Padrões (Obrigatório)
+
+- [ ] Todos os imports novos usam paths absolutos com `@/`
+- [ ] Nenhum import relativo com `../../` em arquivos novos
+- [ ] Nomenclatura seguindo os padrões do SPEC-TECNICO (camelCase, PascalCase)
+- [ ] Arquivos criados nas pastas corretas conforme estrutura definida
+
+---
+
+### Bloco 6 — Formato do Commit (Obrigatório)
+
+A mensagem de commit deve seguir o formato:
+
+```
+tipo(escopo): descrição em imperativo presente
+
+[corpo opcional com contexto adicional]
+
+Story: STORY-XXX
+Co-Authored-By: GEN.IA OS <genia@bedata.com.br>
+```
+
+- [ ] Tipo válido: `feat`, `fix`, `refactor`, `test`, `docs`, `style`, `chore`
+- [ ] Escopo relevante ao módulo modificado
+- [ ] Descrição em imperativo: "adicionar", "corrigir", "implementar" (não "adicionado", "foi corrigido")
+- [ ] Descrição em até 72 caracteres na primeira linha
+- [ ] Story ID incluído quando aplicável
+- [ ] Co-authored-by incluído
+
+**Exemplos corretos:**
+```
+feat(auth): implementar formulário de login com validação de email
+fix(api): corrigir erro 500 ao criar usuário sem telefone
+test(payment): adicionar casos de teste para falha de pagamento
+```
+
+**Exemplos incorretos:**
+```
+update stuff
+fixing bug
+WIP
+feat: fiz várias coisas no componente de login e também corrigi um bug
+```
+
+---
+
+### Bloco 7 — Atomicidade (Boas Práticas)
+
+- [ ] Este commit representa UMA mudança coesa e descritível em uma frase?
+- [ ] Se o commit precisaria de "e também" na descrição, considere dividir em 2 commits
+- [ ] Arquivos não relacionados a esta mudança NÃO estão em stage
+- [ ] Arquivos de configuração pessoal (`.vscode/settings.json` pessoal, etc.) não incluídos
+
+---
+
+## Verificação Rápida Final
+
+Execute a sequência completa antes de `git commit`:
+
+```bash
+npm run lint && npm run typecheck && npm run test && echo "PRÉ-COMMIT OK ✓"
+```
+
+Se este comando terminar com `PRÉ-COMMIT OK ✓`, o commit pode ser feito.
+
+Se falhar: corrija o problema identificado antes de commitar.
+
+---
+
+## Automatização com Git Hooks
+
+Para automatizar parte desta checklist, adicione o hook em `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/sh
+echo "Executando verificações pré-commit..."
+
+npm run lint
+if [ $? -ne 0 ]; then
+  echo "BLOQUEADO: Lint falhou. Corrija os erros antes de commitar."
+  exit 1
+fi
+
+npm run typecheck
+if [ $? -ne 0 ]; then
+  echo "BLOQUEADO: TypeScript com erros. Corrija antes de commitar."
+  exit 1
+fi
+
+npm run test
+if [ $? -ne 0 ]; then
+  echo "BLOQUEADO: Testes falhando. Corrija antes de commitar."
+  exit 1
+fi
+
+echo "Verificações pré-commit concluídas. ✓"
+exit 0
+```
+
+Tornar executável:
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+**Nota:** @devops é responsável por configurar hooks em nível de projeto (usando Husky ou similar) para que se apliquem a todo o time.
+
+---
+
+## Exceções
+
+Em situações excepcionais, @architect pode autorizar um commit que não passa em todas as verificações, com:
+- Registro documentado da exceção
+- Justificativa técnica
+- Issue criada para resolução imediata (no mesmo sprint)
+
+**Exceções nunca são a norma.** Se você se pega precisando de exceções frequentemente, o problema é no código ou no processo.
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

package/template/.genia/development/checklists/pre-deploy.md

@@ -0,0 +1,230 @@
+# Checklist: Pré-Deploy
+
+> Verificações obrigatórias antes de qualquer deploy em produção.
+> Executado por @devops. Nenhum deploy acontece sem este checklist completo.
+
+---
+
+## Objetivo
+
+Garantir que um deploy em produção seja seguro, reversível e comunicado adequadamente. Deploys sem checklist são causa comum de incidentes. Este checklist é o contrato de @devops com a estabilidade do sistema.
+
+---
+
+## Regra de Ouro
+
+**Production nunca recebe código que não passou por staging.**
+
+Se staging não está estável, o deploy não acontece. Sem exceção.
+
+---
+
+## Checklist Completo
+
+### Bloco 1 — Pré-Requisitos (Verificar ANTES de qualquer ação)
+
+- [ ] @pm aprovou formalmente a release (decisão de delivery documentada)
+- [ ] Todas as stories da release têm status `Done` (aprovadas por @po)
+- [ ] PRs de todas as stories estão mergeados em `main`
+- [ ] Branch `main` está sem conflitos pendentes
+- [ ] Não há incidentes abertos em produção no momento
+
+---
+
+### Bloco 2 — Validação de Staging
+
+```bash
+# Verificar status do pipeline de staging
+gh run list --branch main --limit 5
+```
+
+- [ ] Pipeline CI/CD de staging: **verde** nos últimos 48h
+- [ ] Ambiente de staging está respondendo (health check passa)
+- [ ] Testes de integração em staging: passando
+- [ ] Funcionalidades da release verificadas em staging por @qa
+- [ ] Sem erros críticos nos logs de staging nas últimas 24h
+
+---
+
+### Bloco 3 — Segurança
+
+- [ ] Security scan executado no código da release (sem vulnerabilidades CRÍTICAS)
+- [ ] Secrets e variáveis de ambiente de produção estão configurados
+- [ ] Nenhum secret de staging sendo usado em produção
+- [ ] Dependências verificadas por vulnerabilidades conhecidas (`npm audit`)
+- [ ] Certificados SSL/TLS válidos e não próximos do vencimento
+
+```bash
+npm audit --audit-level=critical
+```
+
+- [ ] Zero vulnerabilidades críticas em dependências
+
+---
+
+### Bloco 4 — Banco de Dados (se aplicável)
+
+- [ ] Backup completo do banco de dados de produção realizado ANTES do deploy
+- [ ] Migrações de banco testadas em staging sem erros
+- [ ] Migrações são backward-compatible (se sistema precisa ser zero-downtime)
+- [ ] Script de rollback de migração existe e foi testado
+- [ ] Não há migrações destrutivas sem confirmação de @architect e @pm
+- [ ] Tempo estimado de migração documentado (se > 5 min: avisar usuários)
+
+---
+
+### Bloco 5 — Variáveis de Ambiente e Configuração
+
+- [ ] Todas as variáveis de ambiente necessárias estão configuradas em produção
+- [ ] Nenhuma variável com valor de staging sendo usada em produção
+- [ ] Arquivo `.env.example` atualizado com novas variáveis necessárias
+- [ ] Configurações de feature flags (se usadas) verificadas
+
+```bash
+# Verificar variáveis críticas (sem expor valores)
+env | grep -E "(API_URL|DATABASE|AUTH)" | cut -d= -f1
+```
+
+---
+
+### Bloco 6 — Performance e Capacidade
+
+- [ ] Build de produção gerado com sucesso (`npm run build`)
+- [ ] Tamanho do bundle verificado (sem regressão de performance inesperada)
+- [ ] Capacidade da infraestrutura verificada para o volume esperado
+- [ ] Cache invalidado/renovado conforme necessário
+
+```bash
+npm run build
+npm run build:analyze  # se disponível
+```
+
+---
+
+### Bloco 7 — Plano de Rollback
+
+**Pré-requisito:** Plano de rollback DEVE existir ANTES de iniciar o deploy.
+
+- [ ] Versão anterior identificada: `v[X.X.X]`
+- [ ] Comando de rollback documentado e testado:
+  ```bash
+  # Exemplo para Vercel
+  vercel rollback [deployment-id]
+
+  # Exemplo para Railway
+  railway rollback
+  ```
+- [ ] Rollback de migração de banco documentado (se houver migração)
+- [ ] Tempo estimado para rollback: < 10 minutos
+- [ ] @architect e @pm notificados sobre plano de rollback
+
+---
+
+### Bloco 8 — Comunicação e Janela de Deploy
+
+- [ ] Time notificado sobre a janela de deploy (com pelo menos 2h de antecedência)
+- [ ] Deploy agendado em horário de baixo tráfego (evitar horário de pico)
+- [ ] Evitar deploys em sexta-feira após 14h ou véspera de feriado
+- [ ] Suporte de plantão identificado para primeiras 2h após deploy
+- [ ] Canal de comunicação de incidentes configurado e verificado
+- [ ] Stakeholders que precisam ser notificados identificados
+
+**Janelas ideais de deploy:**
+- Segunda a quinta: 10h-12h ou 14h-16h
+- Evitar: sextas à tarde, vésperas de datas importantes, horário de pico de usuários
+
+---
+
+### Bloco 9 — Monitoramento Pós-Deploy
+
+Configure alertas ANTES de iniciar o deploy:
+
+- [ ] Alertas de erro (5xx) configurados com threshold e notificação imediata
+- [ ] Dashboard de métricas aberto para monitoramento em tempo real
+- [ ] Health check endpoint identificado para verificação contínua
+- [ ] Plano de monitoramento por pelo menos 30 minutos após o deploy
+
+---
+
+### Bloco 10 — Release Notes e Documentação
+
+- [ ] Release notes geradas e revisadas
+- [ ] CHANGELOG.md atualizado com as mudanças desta release
+- [ ] Documentação de APIs atualizada (se houve mudança de contrato)
+- [ ] Tag de versão criada: `git tag -a v[X.X.X] -m "Release v[X.X.X]"`
+
+---
+
+## Execução do Deploy
+
+Após checklist completo, a sequência de deploy:
+
+```bash
+# 1. Tag a versão
+git tag -a v1.2.0 -m "Release v1.2.0: [descrição resumida]"
+git push origin v1.2.0
+
+# 2. Deploy (específico para cada plataforma)
+# Vercel: vercel --prod
+# Railway: railway up
+# AWS: [comando específico]
+
+# 3. Verificação imediata pós-deploy
+curl https://[url-producao]/health
+```
+
+---
+
+## Protocolo de Incidente Durante Deploy
+
+Se algo der errado durante ou após o deploy:
+
+```
+NÍVEL 1 (degradação leve):
+→ Monitorar por 15 minutos
+→ Se não melhorar: NÍVEL 2
+
+NÍVEL 2 (funcionalidade impactada):
+→ Notificar @architect imediatamente
+→ Decidir: aguardar fix hotfix ou rollback
+→ Timeout de decisão: 30 minutos
+
+NÍVEL 3 (sistema fora do ar / dados em risco):
+→ ROLLBACK IMEDIATO
+→ Notificar @pm e @architect simultaneamente
+→ Comunicar usuários via [canal definido]
+→ Post-mortem obrigatório nas próximas 24h
+```
+
+---
+
+## Verificação Pós-Deploy (Executar imediatamente após)
+
+- [ ] Health check em produção: passando
+- [ ] Testes de fumaça (smoke tests) em produção: passando
+- [ ] Logs de produção: sem erros críticos nos primeiros 5 minutos
+- [ ] Métricas de performance: normais (sem degradação)
+- [ ] @qa executou smoke tests em produção e confirmou estabilidade
+- [ ] @pm comunicado sobre sucesso do deploy
+
+---
+
+## Confirmação de Conclusão
+
+```markdown
+## Deploy Concluído — v[X.X.X]
+Data/Hora: YYYY-MM-DD HH:MM
+Ambiente: Production
+Deploy executado por: Gate (@devops)
+
+Checklist: ✅ Completo
+Smoke tests: ✅ Passando
+Monitoramento: ✅ Ativo (30 min)
+Status: ✅ DEPLOY BEM-SUCEDIDO
+
+Próximo passo: @pm comunica stakeholders
+```
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*

package/template/.genia/development/checklists/qa-gate.md

@@ -0,0 +1,216 @@
+# Checklist: QA Gate
+
+> Verificações que @qa executa para emitir veredicto de qualidade.
+> 7 verificações principais. Todas obrigatórias para aprovação.
+
+---
+
+## O que é o QA Gate?
+
+O QA Gate é o checkpoint de qualidade que determina se o código pode avançar para code review e, posteriormente, para produção. @qa é a autoridade exclusiva para abrir ou fechar este gate. Um veredicto APROVADO pelo QA Gate é pré-requisito obrigatório para o code review por @reviewer.
+
+---
+
+## Verificação 1 — Acceptance Criteria (Funcional)
+
+**Propósito:** Garantir que o código implementa exatamente o que foi prometido na story.
+
+Para cada AC da story:
+
+| AC | Cenário testado | Resultado |
+|----|----------------|---------|
+| AC-01 | [descrever como foi testado] | ✅ / ❌ |
+| AC-02 | [descrever como foi testado] | ✅ / ❌ |
+| AC-03 | [descrever como foi testado] | ✅ / ❌ |
+
+**Critério de passagem:** Todos os ACs com resultado ✅
+
+- [ ] Todos os ACs verificados manualmente
+- [ ] Happy path de cada AC funciona conforme descrito
+- [ ] Nenhum AC implementado parcialmente ou com workaround oculto
+- [ ] Comportamentos descritos nos ACs correspondem ao comportamento real
+
+**BLOQUEANTE se falhar.**
+
+---
+
+## Verificação 2 — Testes Automáticos
+
+**Propósito:** Garantir que a suite de testes está saudável e cobrindo o código.
+
+```bash
+npm run test
+```
+
+- [ ] Todos os testes passando (zero falhas)
+- [ ] Nenhum teste em `skip` ou `xtest` sem justificativa documentada
+- [ ] Sem `test.only` que silencia outros testes
+
+```bash
+npm run coverage
+```
+
+- [ ] Coverage >= 80% nas linhas novas/modificadas
+- [ ] Relatório de coverage gerado e verificado
+
+**Resultados esperados:**
+```
+Test Suites: X passed, X total
+Tests:       X passed, X total
+Coverage:    XX% (>= 80%)
+```
+
+**BLOQUEANTE se falhar.**
+
+---
+
+## Verificação 3 — Qualidade Estática
+
+**Propósito:** Garantir que o código segue os padrões de qualidade definidos.
+
+```bash
+npm run lint
+```
+
+- [ ] Zero erros de lint
+- [ ] Zero warnings de lint
+- [ ] Nenhuma regra desabilitada sem comentário explicativo
+
+```bash
+npm run typecheck
+```
+
+- [ ] Zero erros TypeScript
+- [ ] Sem `@ts-ignore` injustificado
+- [ ] Sem `any` como atalho para evitar tipagem
+
+**BLOQUEANTE se falhar.**
+
+---
+
+## Verificação 4 — Cenários de Borda (Edge Cases)
+
+**Propósito:** Garantir que o código é robusto além dos cenários principais.
+
+Testar:
+
+- [ ] Campos obrigatórios vazios: o sistema se comporta corretamente?
+- [ ] Caracteres especiais em inputs de texto: sem injeção ou quebra?
+- [ ] Valores extremos (muito longos, muito curtos, zero, negativos): tratados?
+- [ ] Ações repetidas rapidamente (double-click em botões): sem efeito duplo?
+- [ ] Sem conexão ou timeout de API: mensagem de erro adequada?
+- [ ] Dados nulos/undefined vindos da API: sem crash?
+
+Documente cada cenário testado e o resultado.
+
+**ALTO se falhar em cenário relevante. BLOQUEANTE se causar crash ou corrupção de dados.**
+
+---
+
+## Verificação 5 — Regressão
+
+**Propósito:** Garantir que as mudanças desta story não quebraram funcionalidades existentes.
+
+Testar as funcionalidades RELACIONADAS ao módulo modificado:
+
+- [ ] Funcionalidades adjacentes ainda funcionam corretamente
+- [ ] Navegação entre páginas relacionadas funciona
+- [ ] Integrações com outros módulos não foram quebradas
+- [ ] Dados persistidos anteriormente ainda são lidos corretamente
+
+Em projetos brownfield, a verificação de regressão é expandida e inclui teste dos fluxos críticos de produção.
+
+**CRÍTICO se houver regressão em funcionalidade existente.**
+
+---
+
+## Verificação 6 — Segurança Básica
+
+**Propósito:** Identificar vulnerabilidades de segurança óbvias antes que cheguem ao code review.
+
+- [ ] Sem dados sensíveis expostos em respostas de API desnecessariamente
+- [ ] Endpoints protegidos retornam 401/403 sem autenticação válida
+- [ ] Inputs com caracteres especiais não quebram o sistema
+- [ ] Sem informações de stack trace expostas em respostas de erro para o usuário
+- [ ] Sem secrets visíveis em logs ou respostas de API
+- [ ] Rate limiting funcionando se implementado
+
+**CRÍTICO se encontrar vulnerabilidade de segurança.**
+
+---
+
+## Verificação 7 — Experiência do Usuário Básica
+
+**Propósito:** Garantir que a entrega é usável e não causa frustração desnecessária.
+
+Para funcionalidades com interface:
+
+- [ ] Estados de loading presentes durante operações assíncronas?
+- [ ] Estado vazio (lista sem itens) tem tratamento visual adequado?
+- [ ] Mensagens de erro são compreensíveis para o usuário (não stack traces)?
+- [ ] Formulários fornecem feedback claro sobre campos inválidos?
+- [ ] Interface não quebra visualmente em resoluções comuns (desktop 1280px+, mobile 375px)?
+- [ ] Botões não ficam habilitados após ação que deveria desabilitá-los?
+
+Para funcionalidades de API:
+
+- [ ] Respostas de sucesso têm estrutura consistente?
+- [ ] Respostas de erro têm mensagem clara e código HTTP correto?
+- [ ] Documentação da API atualizada se necessário?
+
+**MÉDIO se falhar (não bloqueia, mas deve ser documentado).**
+
+---
+
+## Sumário de Verificações
+
+| # | Verificação | Criticidade | Resultado |
+|---|-------------|------------|---------|
+| 1 | Acceptance Criteria atendidos | BLOQUEANTE | ✅ / ❌ |
+| 2 | Testes automáticos passando | BLOQUEANTE | ✅ / ❌ |
+| 3 | Lint + TypeScript limpos | BLOQUEANTE | ✅ / ❌ |
+| 4 | Edge cases tratados | ALTO | ✅ / ❌ |
+| 5 | Sem regressão | CRÍTICO | ✅ / ❌ |
+| 6 | Segurança básica | CRÍTICO | ✅ / ❌ |
+| 7 | UX básica adequada | MÉDIO | ✅ / ❌ |
+
+---
+
+## Veredicto
+
+**APROVADO** quando:
+- Verificações 1, 2, 3 passam (obrigatórias)
+- Verificações 5, 6 passam (zero críticos)
+- Verificação 4 sem bugs ALTO ou com máx 2 documentados
+- Verificação 7 com issues documentados para backlog
+
+**REPROVADO** quando:
+- Qualquer verificação BLOQUEANTE falha
+- Verificação 5 ou 6 identificam bug CRÍTICO
+- Verificação 4 tem mais de 2 bugs ALTO
+
+---
+
+## Registro do Veredicto
+
+```markdown
+## QA Gate — STORY-XXX — [APROVADO | REPROVADO]
+Data: YYYY-MM-DD | QA: Quinn (@qa) | Iteração: X/5
+
+| Verificação | Status |
+|-------------|--------|
+| 1. ACs | ✅ PASS |
+| 2. Testes | ✅ PASS |
+| 3. Estática | ✅ PASS |
+| 4. Edge cases | ⚠️ 1 bug MÉDIO documentado |
+| 5. Regressão | ✅ PASS |
+| 6. Segurança | ✅ PASS |
+| 7. UX | ✅ PASS |
+
+Veredicto: ✅ APROVADO
+Próximo passo: @reviewer para code review
+```
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*