create-genia-os 1.0.0

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}}*

package/template/.genia/development/checklists/story-dod.md

@@ -0,0 +1,155 @@
+# Checklist: Definition of Done (DoD) — Story
+
+> Critérios obrigatórios para uma story ser considerada Done.
+> Verificado por @po (negócio) + @qa (técnica) + @reviewer (código).
+
+---
+
+## O que é o Definition of Done?
+
+O Definition of Done (DoD) é o conjunto de critérios acordados pelo time que define quando uma story está genuinamente pronta — não "tecnicamente funcionando", mas entregável com qualidade para o usuário final. Uma story que não atende ao DoD não é Done, independente de o código estar escrito.
+
+---
+
+## Checklist Completo (10 Critérios)
+
+### Critério 1 — Acceptance Criteria Atendidos
+- [ ] Todos os ACs da story foram implementados
+- [ ] Todos os ACs foram verificados manualmente por @qa
+- [ ] @po confirmou que o comportamento atende à intenção de negócio
+- [ ] Não há ACs parcialmente implementados ou com workaround
+
+**Responsável de verificar:** @qa + @po
+
+---
+
+### Critério 2 — Testes Passando
+- [ ] Todos os testes unitários passam: `npm run test`
+- [ ] Nenhum teste ignorado (`skip`, `xtest`, `.only`) sem justificativa documentada
+- [ ] Testes de regressão de funcionalidades existentes passando (se brownfield)
+
+**Responsável de verificar:** @qa
+
+---
+
+### Critério 3 — Cobertura de Testes
+- [ ] Cobertura de testes >= 80% nas linhas novas/modificadas
+- [ ] Verificado com: `npm run coverage`
+- [ ] Linhas não cobertas têm justificativa (ex: código de fallback impossível de testar)
+
+**Responsável de verificar:** @qa
+
+---
+
+### Critério 4 — Qualidade de Código (Lint + Types)
+- [ ] `npm run lint` — zero erros e zero warnings
+- [ ] `npm run typecheck` — zero erros TypeScript
+- [ ] Sem `any` injustificado
+- [ ] Imports absolutos com `@/` em todos os arquivos novos
+
+**Responsável de verificar:** @reviewer
+
+---
+
+### Critério 5 — Sem Bugs Críticos
+- [ ] Zero bugs de severidade CRÍTICO pendentes
+- [ ] Máximo 2 bugs de severidade ALTO (documentados no backlog para sprint futuro)
+- [ ] Bugs de severidade MÉDIO e BAIXO documentados no backlog
+
+**Responsável de verificar:** @qa
+
+---
+
+### Critério 6 — Code Review Aprovado
+- [ ] @reviewer realizou code review formal
+- [ ] Todos os itens BLOQUEANTES foram corrigidos
+- [ ] Aprovação (LGTM) emitida por @reviewer
+- [ ] Relatório de code review disponível em `docs/reviews/`
+
+**Responsável de verificar:** @reviewer
+
+---
+
+### Critério 7 — Arquitetura Respeitada
+- [ ] Código segue os padrões do SPEC-TECNICO.md
+- [ ] Estrutura de pastas correta
+- [ ] Separação de responsabilidades respeitada
+- [ ] Nenhuma decisão arquitetural tomada sem aprovação de @architect
+
+**Responsável de verificar:** @reviewer (+ @architect se houver dúvida)
+
+---
+
+### Critério 8 — PR Criado por @devops
+- [ ] Branch feito push para o remoto por @devops (nunca diretamente por @dev)
+- [ ] Pull Request criado com template completo
+- [ ] PR associado à story (referência no título ou body)
+- [ ] CI/CD pipeline verde no PR
+- [ ] PR mergeado para `main`
+
+**Responsável de verificar:** @devops
+
+---
+
+### Critério 9 — Segurança Básica
+- [ ] Sem hardcoded secrets, tokens ou URLs de ambiente
+- [ ] Inputs validados e sanitizados onde necessário
+- [ ] Dados sensíveis não expostos em logs
+- [ ] Autenticação/autorização corretas nos endpoints protegidos
+
+**Responsável de verificar:** @reviewer + @qa
+
+---
+
+### Critério 10 — Validação Final por @po
+- [ ] @po revisou o entregue e confirmou que atende à User Story
+- [ ] @po atualizou o status da story para `Done` no arquivo
+- [ ] @po atualizou o backlog para refletir a story entregue
+- [ ] Velocity do sprint atualizado
+
+**Responsável de verificar:** @po
+
+---
+
+## Resumo Visual
+
+| # | Critério | Responsável | Bloqueante |
+|---|---------|------------|-----------|
+| 1 | Acceptance Criteria atendidos | @qa + @po | Sim |
+| 2 | Testes passando | @qa | Sim |
+| 3 | Coverage >= 80% | @qa | Sim |
+| 4 | Lint + Typecheck limpos | @reviewer | Sim |
+| 5 | Sem bugs críticos | @qa | Sim |
+| 6 | Code review aprovado | @reviewer | Sim |
+| 7 | Arquitetura respeitada | @reviewer | Sim |
+| 8 | PR criado e mergeado | @devops | Sim |
+| 9 | Segurança básica | @reviewer + @qa | Sim |
+| 10 | Validação final de @po | @po | Sim |
+
+**Todos os 10 critérios são obrigatórios.** Uma story com 9/10 critérios não é Done.
+
+---
+
+## Processo de Verificação do DoD
+
+1. @qa verifica critérios 1, 2, 3, 5, 9 (parcial)
+2. @reviewer verifica critérios 4, 6, 7, 9 (parcial)
+3. @devops executa critério 8
+4. @po verifica critério 10 e confirma o Done
+
+Qualquer critério não atendido bloqueia a story de ir para Done.
+
+---
+
+## DoD vs. Acceptance Criteria
+
+| | DoD | Acceptance Criteria |
+|-|-----|-------------------|
+| **Escopo** | Toda story | Específico por story |
+| **Quem define** | Time (imutável no sprint) | @sm + @po (por story) |
+| **O que avalia** | Qualidade do processo de entrega | Comportamento funcional |
+| **Pode variar** | Não (é padrão do time) | Sim (por story) |
+
+---
+
+*GEN.IA OS v1.0 — {{TEAM_NAME}} — {{CREATOR_NAME}}*