@girardelli/architect 5.0.0 → 6.0.0

package/.agent/rules/00-general.md

@@ -0,0 +1,229 @@
+---
+antigravity:
+  trigger: 'always_on'
+  globs: ['**/*']
+  description: 'Regras gerais invioláveis para @girardelli/architect'
+  priority: CRITICAL
+---
+
+# 📜 Regras Gerais — @girardelli/architect
+
+> **Estas regras são INVIOLÁVEIS. Não há exceção.**
+
+---
+
+## 🏆 Regras de Ouro
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                    9 REGRAS DE OURO                         ║
+║                                                              ║
+║  1. Git Flow completo (branch → PR → review → merge)       ║
+║  2. Arquitetura C4 (4 níveis de documentação)              ║
+║  3. BDD antes de código                                    ║
+║  4. TDD — Red → Green → Refactor                           ║
+║  5. Diagnóstico obrigatório antes de codar                 ║
+║  6. Mockup antes de qualquer UI                            ║
+║  7. Nunca decidir sozinho — perguntar ao humano            ║
+║  8. Qualidade > Velocidade                                 ║
+║  9. Não abrir browser, não tirar screenshot — apenas código║
+║                                                              ║
+║  ⚠️  Violar qualquer regra = PARAR e RECOMEÇAR              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 🏢 Identidade do Projeto
+
+| Item | Valor |
+|------|-------|
+| **Nome** | @girardelli/architect |
+| **Stack** | TypeScript + JavaScript |
+| **Score** | 94/100 |
+| **Linguagens** | TypeScript, JavaScript |
+| **Frameworks** | Nenhum detectado |
+| **Cobertura Mínima** | 80% |
+| **Score Mínimo** | 70/100 |
+
+---
+
+## 🔄 Fluxo Completo (Qualquer Ação)
+
+```
+REQUISIÇÃO
+    │
+    ▼
+LEITURA OBRIGATÓRIA (INDEX.md → 00-general → PREFLIGHT)
+    │
+    ▼
+DIAGNÓSTICO (entender ANTES de agir)
+    │
+    ▼
+ARTEFATOS (mockup → user story → arch → tasks → BDD → TDD)
+    │
+    ▼
+APROVAÇÃO HUMANA (/approved)
+    │
+    ▼
+IMPLEMENTAÇÃO (Backend → Integration Doc → Frontend/App)
+    │
+    ▼
+QUALITY GATES (build + test + coverage + score)
+    │
+    ▼
+CODE REVIEW
+    │
+    ▼
+MERGE (via PR, nunca direto)
+```
+
+---
+
+## 🌿 Git Flow
+
+### Branch Naming
+
+| Tipo | Padrão | Exemplo |
+|------|--------|---------|
+| Feature | `feature/[ticket]-[descricao]` | `feature/PROJ-123-cancelled-tab` |
+| Bug fix | `fix/[ticket]-[descricao]` | `fix/PROJ-456-null-balance` |
+| Hotfix | `hotfix/[descricao]` | `hotfix/payment-crash` |
+| Refactor | `refactor/[descricao]` | `refactor/extract-auth-service` |
+
+### Commit Messages (Conventional Commits)
+
+```
+feat: add cancelled refuelings tab
+fix: prevent null balance on payment
+refactor: extract auth service from user module
+docs: update API documentation for v2
+test: add integration tests for payment flow
+chore: upgrade dependencies
+```
+
+### Cenários de Git Flow
+
+**Cenário A: Feature nova**
+```
+git checkout develop
+git pull origin develop
+git checkout -b feature/PROJ-XXX-nome
+# ... implementar ...
+git add [arquivos específicos]
+git commit -m "feat: [descrição]"
+git push -u origin feature/PROJ-XXX-nome
+# Criar PR para develop
+```
+
+**Cenário B: Bug fix**
+```
+git checkout develop
+git pull origin develop
+git checkout -b fix/PROJ-XXX-descricao
+# ... corrigir ...
+git add [arquivos específicos]
+git commit -m "fix: [descrição]"
+git push -u origin fix/PROJ-XXX-descricao
+# Criar PR para develop
+```
+
+**Cenário C: Hotfix em produção**
+```
+git checkout main
+git pull origin main
+git checkout -b hotfix/descricao
+# ... corrigir ...
+git add [arquivos específicos]
+git commit -m "fix: [descrição] (hotfix)"
+git push -u origin hotfix/descricao
+# Criar PR para main E develop
+```
+
+---
+
+## 📝 Naming Conventions
+
+| Item | Padrão | Exemplo |
+|------|--------|---------|
+| Classes | PascalCase | `UserService` |
+| Interfaces | PascalCase (sem I prefix) | `UserPayload` |
+| Funções | camelCase | `getActiveUsers` |
+| Variáveis | camelCase | `userCount` |
+| Constantes | UPPER_SNAKE | `MAX_RETRIES` |
+| Enums | PascalCase | `UserStatus` |
+| Arquivos | kebab-case | `user-service.ts` |
+| Módulos (diretório) | kebab-case | `user-management/` |
+| Testes | kebab-case + .spec/.test | `user-service.spec.ts` |
+| Entities | PascalCase + .entity | `User.entity.ts` |
+| DTOs | PascalCase + .dto | `CreateUserDto` |
+| Controllers | PascalCase + .controller | `user.controller.ts` |
+| Services | PascalCase + .service | `user.service.ts` |
+
+---
+
+## 🔍 Diagnóstico Obrigatório
+
+> **Antes de QUALQUER implementação, execute este diagnóstico.**
+
+```bash
+# 1. Entender a estrutura
+ls -la src/
+find src/ -name "*.ts" | head -30
+
+# 2. Entender as dependências do módulo
+grep -rn "import" --include="*.ts" src/[modulo]/ | head -20
+
+# 3. Testes existentes
+find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" | wc -l
+
+# 4. Score atual
+npx @girardelli/architect score .
+
+# 5. Anti-patterns
+npx @girardelli/architect anti-patterns .
+```
+
+---
+
+## ❌ Ações PROIBIDAS
+
+```
+❌ Commitar direto em main ou develop
+❌ Push --force sem aprovação explícita
+❌ Merge sem code review
+❌ Código sem testes
+❌ Ignorar falhas de build/test
+❌ Hardcodar secrets, tokens, senhas
+❌ console.log / print() em produção
+❌ any (TypeScript) sem justificativa em comentário
+❌ @ts-ignore / type: ignore sem justificativa
+❌ Testes com .skip() permanente
+❌ Copiar/colar código (extrair abstração)
+❌ Alterar mais de 10 arquivos sem reavaliar escopo
+❌ Implementar sem artefatos aprovados (mockup, US, BDD, TDD)
+❌ Decidir arquitetura sem consultar o humano
+❌ Refatorar código alheio ao escopo da task
+```
+
+---
+
+## ✅ Checklist de Compliance (Regras de Ouro)
+
+Antes de marcar QUALQUER tarefa como "done":
+
+```
+□ Regra 1: Git Flow completo (branch + PR + review)?
+□ Regra 2: Arquitetura documentada (C4 se nova feature)?
+□ Regra 3: BDD escrito antes do código?
+□ Regra 4: TDD aplicado (RED → GREEN → REFACTOR)?
+□ Regra 5: Diagnóstico feito antes de codar?
+□ Regra 6: Mockup aprovado (se tem UI)?
+□ Regra 7: Decisões validadas com humano?
+□ Regra 8: Qualidade > Velocidade (sem atalhos)?
+□ Regra 9: Apenas código (sem abrir browser, sem screenshots)?
+```
+
+---
+
+**Gerado por Architect v3.1 · Score: 94/100 · 2026-03-30**

package/.agent/rules/01-architecture.md

@@ -0,0 +1,182 @@
+---
+antigravity:
+  trigger: 'always_on'
+  globs: ['**/*']
+  description: 'Regras de arquitetura para @girardelli/architect'
+  priority: HIGH
+---
+
+# 🏗️ Regras de Arquitetura — @girardelli/architect
+
+> **Separação de camadas, direção de dependências, e padrões de módulo.**
+
+---
+
+## 📐 Camadas Arquiteturais
+
+| Camada | Responsabilidade | Padrão |
+|--------|-----------------|--------|
+| **API / Controllers** | Routing, validação HTTP | controllers/ |
+| **Service** | Lógica de negócio | services/ |
+| **Data / Repository** | Acesso a dados | repositories/ |
+| **Entity / Model** | Modelo de domínio | entities/ ou models/ |
+| **DTO / Schema** | Contratos I/O | dto/ ou schemas/ |
+
+### Direção de Dependência (OBRIGATÓRIA)
+
+```
+UI / Controllers  →  Services  →  Repositories / Data  →  Entities
+       ↓                ↓                 ↓
+   (pode usar)     (pode usar)      (pode usar)
+   Services        Repositories     Entities
+   DTOs            Entities         Value Objects
+                   DTOs
+
+⚠️  NUNCA:
+   Entity → Controller
+   Repository → Controller
+   Service → Controller
+   Data Layer → UI Layer
+```
+
+### Regra de Ouro das Camadas
+
+```
+╔══════════════════════════════════════════════════════╗
+║  Uma camada SÓ pode depender de camadas ABAIXO.     ║
+║  NUNCA de camadas acima ou da mesma camada lateral. ║
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## 📦 Padrão de Módulo
+
+```
+src/modules/[nome-do-modulo]/
+├── [nome].module.ts
+├── [nome].controller.ts  → Endpoints / API
+├── [nome].service.ts     → Lógica de negócio
+├── dto/                       → Request/Response shapes
+├── entities/                  → Modelos de domínio
+└── __tests__/                 → Testes do módulo
+```
+
+---
+
+## 🚫 Anti-Patterns a Prevenir
+
+### God Class (> 500 linhas ou > 10 métodos)
+```
+❌ PROIBIDO: Classe com múltiplas responsabilidades
+✅ CORRETO: Extrair em classes menores com responsabilidade única
+
+Se um arquivo ultrapassar 500 linhas:
+1. PARAR
+2. Identificar responsabilidades distintas
+3. Extrair em módulos separados
+4. Atualizar imports
+```
+
+### Circular Dependencies
+```
+❌ PROIBIDO: A importa B, B importa A
+✅ CORRETO: Extrair interface comum ou usar event/mediator
+
+Detecção:
+$ npx madge --circular src/
+$ architect anti-patterns .
+```
+
+### Leaky Abstractions
+```
+❌ PROIBIDO: Service expondo detalhes de implementação
+✅ CORRETO: Interface define contrato, implementação é encapsulada
+
+Exemplos:
+- Service retornando QueryBuilder → ERRADO (vaza ORM)
+- Service retornando DTO → CORRETO (abstrai)
+- Controller acessando Entity → ERRADO (vaza modelo)
+- Controller acessando DTO → CORRETO (contrato)
+```
+
+### Feature Envy
+```
+❌ PROIBIDO: Método que usa mais atributos de outra classe que da própria
+✅ CORRETO: Mover método para a classe que possui os dados
+```
+
+### Shotgun Surgery
+```
+❌ PROIBIDO: Mudança em 1 feature exige alterar 10+ arquivos
+✅ CORRETO: Agrupar código relacionado no mesmo módulo
+
+Se uma mudança toca > 5 arquivos:
+1. PARAR
+2. Reavaliar se o código está no lugar certo
+3. Considerar refatoração preventiva
+```
+
+---
+
+## 🏛️ Princípios Arquiteturais
+
+### DDD (Domain-Driven Design) — Quando Aplicável
+```
+Entities:       Objetos com identidade (ID único)
+Value Objects:  Objetos sem identidade (imutáveis)
+Aggregates:     Cluster de entidades com root
+Repositories:   Acesso a dados de Aggregates
+Services:       Lógica que não pertence a nenhuma entidade
+```
+
+### Clean Architecture
+```
+Camada mais interna: Entities (regras de negócio)
+Camada média:        Use Cases / Services (lógica de aplicação)
+Camada externa:      Controllers, Gateways, Presenters (I/O)
+
+Dependência: SEMPRE de fora para dentro, NUNCA o contrário.
+```
+
+### Event-Driven — Quando Aplicável
+```
+Usar eventos quando:
+- Desacoplamento entre módulos é necessário
+- Processamento assíncrono é aceitável
+- Múltiplos handlers para um mesmo trigger
+
+NÃO usar eventos quando:
+- Resposta síncrona é necessária
+- Transação atômica é obrigatória
+- Ordem de execução importa
+```
+
+---
+
+## 📊 Anti-Patterns Atuais do Projeto
+
+✅ Nenhum anti-pattern detectado. Manter assim.
+
+Score atual: **94/100** | Meta: **100/100**
+
+---
+
+## ✅ Checklist de Arquitetura
+
+Antes de criar qualquer módulo novo:
+
+```
+□ Camada correta? (Controller vs Service vs Repository vs Entity)
+□ Direção de dependência respeitada? (nunca de baixo para cima)
+□ Módulo coeso? (tudo relacionado junto)
+□ Sem circular dependency?
+□ Sem God Class? (< 500 linhas, < 10 métodos)
+□ Interface/abstração antes de implementação?
+□ DTOs para comunicação entre camadas?
+□ Testes por camada? (unit para service, integration para controller)
+```
+
+---
+
+**Gerado por Architect v3.1 · Score: 94/100**