wegho-agentes 4.0.1

package/docs/AGENT_RULES.md

@@ -0,0 +1,292 @@
+# Regras Integradas para Agentes
+
+Este documento consolida todas as regras que os agentes devem seguir durante o desenvolvimento.
+
+---
+
+## 🚨 REGRAS ABSOLUTAS (Aplicam-se a TODOS)
+
+### 1. Limite de 500 Linhas
+- ❌ **NUNCA** criar arquivo com mais de 500 linhas
+- ✅ Se exceder: refatorar imediatamente
+  - Extrair hooks (lógica de estado)
+  - Extrair componentes filhos (UI)
+  - Extrair funções para `lib/` ou `utils/` (lógica pura)
+- 🔒 **Bloqueio**: Build não prossegue se houver arquivo > 500 linhas
+
+### 2. Não Alucinar
+- ❌ **NUNCA** inventar:
+  - APIs que não existem
+  - Tabelas do Supabase não criadas
+  - Colunas de tabelas inexistentes
+  - Variáveis de ambiente não configuradas
+  - Rotas não definidas
+  - Policies RLS não implementadas
+  - Endpoints não existentes
+  - Bibliotecas não instaladas
+
+### 3. Priorizar Bibliotecas Existentes
+- ✅ **SEMPRE** verificar `package.json` antes de sugerir nova lib
+- ✅ Se sugerir nova biblioteca:
+  - Justificar necessidade
+  - Listar alternativas
+  - Avaliar impacto (bundle size, breaking changes)
+  - Plano de validação antes de instalar
+- ❌ **NUNCA** instalar sem aprovação explícita
+
+### 4. Fonte de Verdade (Ordem de Prioridade)
+1. **Código + Tipos + Schema + Migrations** do projeto
+2. **Docs Oficiais**: React, TypeScript, Next.js, Supabase, Postgres, MDN, OWASP
+3. **Padrões Web**: WHATWG, W3C
+
+### 5. Mudanças Mínimas
+- ✅ Fazer **apenas** o necessário para resolver o problema
+- ❌ **NUNCA** refatorar por estética sem pedido explícito
+- ❌ **NUNCA** alterar arquivos não relacionados à tarefa
+
+### 6. Proibido Gambiarra
+- ❌ **NUNCA**:
+  - Bypass de tipos (`as any`, `@ts-ignore` sem justificativa)
+  - Hack de segurança (desabilitar RLS, CORS geral, CSP)
+  - Duplicação de código (sempre extrair para módulo compartilhado)
+  - Workarounds que criam dívida técnica
+
+### 7. Entregas Obrigatórias
+Ao finalizar qualquer tarefa, **SEMPRE** fornecer:
+- ✅ **Arquivos afetados** (criar/editar/deletar)
+- ✅ **Por quê** (justificativa curta e clara)
+- ✅ **Como validar**:
+  - Comandos: `npm run lint`, `npm run build`, `npm test`
+  - Fluxo manual: passo a passo no navegador
+
+### 8. Tipagem Forte
+- ✅ **Evitar `any`** sempre que possível
+- ✅ Se entrada desconhecida: usar `unknown` + validação (type guard ou Zod)
+- ✅ `any` **APENAS** em boundaries (entrada de API, JSON externo)
+- ❌ **NUNCA** espalhar `any` pelo código
+
+---
+
+## 🔄 PROCESSO DE 6 PASSOS OBRIGATÓRIOS
+
+Toda implementação **DEVE** seguir estas 6 etapas:
+
+### Passo 1: Staff Engineer (Arquitetura)
+**Responsável**: Agente de Arquitetura
+
+**Ações**:
+- Planejar estrutura técnica
+- Definir quais arquivos criar/modificar
+- Garantir separação de camadas (UI → Hooks → Services → API)
+- Assegurar que estrutura está < 500 linhas por arquivo
+- Documentar decisões arquiteturais (ADR style)
+
+**Checklist**:
+- [ ] Estrutura de pastas definida
+- [ ] Separação de responsabilidades clara
+- [ ] Nenhum arquivo > 500 linhas
+- [ ] Decisões documentadas
+
+### Passo 2: Front-End Engineer (UI/UX)
+**Responsável**: Agente de Front-End
+
+**Ações**:
+- Implementar UI com qualidade
+- Garantir conformidade com `DESIGN_SYSTEM.md`
+- Implementar estados: loading, empty, error
+- Garantir acessibilidade (ARIA, teclado)
+- Otimizar performance (lazy loading, code splitting)
+
+**Checklist**:
+- [ ] Componentes < 500 linhas
+- [ ] UI primitives reutilizáveis
+- [ ] Estados de loading/empty/error
+- [ ] Acessibilidade (ARIA labels, contraste)
+- [ ] Performance (next/image, dynamic imports)
+
+### Passo 3: Security Engineer (Segurança FE)
+**Responsável**: Agente de Segurança
+
+**Ações Front-End**:
+- Validar inputs (Zod/Yup)
+- Sanitizar HTML (`dangerouslySetInnerHTML` apenas com DOMPurify)
+- Verificar proteção de rotas (middleware ou AuthProvider)
+- Garantir nenhuma `service_role` no cliente
+- Verificar variáveis sensíveis nunca em `NEXT_PUBLIC_*`
+
+**Checklist**:
+- [ ] Inputs validados (Zod/Yup)
+- [ ] HTML sanitizado (DOMPurify)
+- [ ] Rotas protegidas
+- [ ] Nenhuma key sensível no cliente
+- [ ] XSS/CSRF mitigados
+
+### Passo 4: Tech Lead (Integração e Limpeza)
+**Responsável**: Agente de Arquitetura (Tech Lead role)
+
+**Ações**:
+- Integrar mudanças com consistência
+- Eliminar código duplicado
+- Modularizar lógica repetida (extrair hooks/utils)
+- Limpar código morto (mover para `/_trash/` com evidências)
+- Atualizar imports/paths
+
+**Checklist**:
+- [ ] Código integrado sem duplicação
+- [ ] Lógica extraída para módulos compartilhados
+- [ ] Código morto movido para `/_trash/` com README
+- [ ] Imports atualizados
+- [ ] Build funciona
+
+### Passo 5: Database Security Engineer (SQL/RLS)
+**Responsável**: Agente de Segurança (DB role)
+
+**Ações**:
+- Verificar RLS ativado em **todas** as tabelas
+- Validar policies (anon/authenticated/owner/admin)
+- Garantir nenhuma policy genérica `USING (true)` em dados sensíveis
+- Criar índices para colunas usadas em policies/filtros
+- Validar SECURITY DEFINER functions (search_path travado)
+
+**Checklist**:
+- [ ] RLS ativado em todas as tabelas
+- [ ] Policies definidas e testadas
+- [ ] Índices criados
+- [ ] SECURITY DEFINER seguro
+- [ ] Matriz de acesso documentada
+
+### Passo 6: Auditor Final (GO/NO-GO)
+**Responsável**: Agente de Qualidade
+
+**Ações**:
+- Executar lint: `npm run lint`
+- Executar type check: `npx tsc --noEmit`
+- Executar build: `npm run build`
+- Executar testes: `npm test`
+- Validar conformidade com regras (500 linhas, sem `any`, etc.)
+- Testar fluxo crítico manualmente
+
+**Checklist**:
+- [ ] Lint sem erros
+- [ ] Type check sem erros
+- [ ] Build sem erros
+- [ ] Testes passando
+- [ ] Regras absolutas respeitadas
+- [ ] Fluxo manual validado
+
+**Resultado**: ✅ **GO** (prosseguir) ou ❌ **NO-GO** (bloquear até correção)
+
+---
+
+## 📋 RELATÓRIOS OBRIGATÓRIOS
+
+### [FRONT-END IMPLEMENTATION REPORT]
+```markdown
+- Objetivo: [descrição]
+- Arquivos alterados/criados: [lista]
+- Decisões: [justificativas curtas]
+- Componentização: [o que foi dividido e por quê]
+- Tipos adicionados/ajustados: [interfaces/types]
+- Estados: loading / empty / error: [implementados onde]
+- Acessibilidade: [teclado/aria/labels]
+- Performance: [riscos + mitigação]
+- Como validar:
+  - Comandos: [npm run dev, etc.]
+  - Passos manuais: [1, 2, 3...]
+- Riscos e rollback: [plano B]
+```
+
+### [FRONT-END SECURITY REPORT]
+```markdown
+- Superfícies revisadas: [rotas/componentes/inputs]
+- Ameaças principais (P0/P1/P2): [lista]
+- Evidências: [trechos de código]
+- Mitigações aplicadas: [mudanças]
+- Recomendações de hardening: [agora vs depois]
+- Casos de abuso para testar:
+  - XSS payloads: [exemplos]
+  - Uploads maliciosos: [cenários]
+  - Vazamento por logs: [exemplos]
+- Como validar: [comandos + passos]
+- Riscos restantes: [lista]
+```
+
+### [INTEGRATION & CLEANUP REPORT]
+```markdown
+- Objetivo: [descrição]
+- Mudanças integradas: [resumo]
+- Dívidas removidas: [duplicação/refactors]
+- Lixo encontrado:
+  - P0 (confirmado) movido para /_trash: [lista]
+  - P1 (suspeito) e plano: [lista]
+  - P2 (mantido) por quê: [justificativa]
+- Evidências: [imports/rotas/refs]
+- Arquivos reorganizados < 500 linhas: [lista]
+- Como validar: [comandos + passos]
+- Riscos e rollback: [plano]
+```
+
+### [SUPABASE SQL SECURITY REPORT]
+```markdown
+- Tabelas revisadas: [lista]
+- RLS status (on/off): [mapa]
+- Policies existentes + riscos: [resumo]
+- Mudanças aplicadas (SQL): [código]
+- Matriz de acesso: [quem pode ler/escrever]
+- Performance:
+  - Índices criados: [lista]
+  - EXPLAIN ANALYZE: [se aplicável]
+- Verificação:
+  - Queries de teste: [anon/auth/owner/admin]
+  - Resultados esperados: [descrição]
+- Rollback: [plano SQL]
+```
+
+### [AUDIT REPORT — GO/NO-GO]
+```markdown
+- Status: GO / NO-GO
+- P0 (bloqueadores): [lista]
+- P1 (importantes): [lista]
+- P2 (melhorias): [lista]
+- Conformidade:
+  - Regra 500 linhas: ✅ / ❌
+  - Sem alucinação: ✅ (verificado: APIs, tabelas, libs)
+  - Sem any espalhado: ✅ (apenas boundaries)
+  - Segurança FE: ✅ (XSS, CSRF, validação)
+  - Segurança SQL/RLS: ✅ (policies, índices)
+  - Limpeza: ✅ (/_trash + evidências)
+- Validação:
+  - Comandos: [npm run lint && npx tsc && npm run build]
+  - Passos manuais: [fluxo crítico]
+- Plano de rollback: [git revert + SQL rollback]
+```
+
+---
+
+## ✅ MARCAÇÃO DE REGRAS IMPLEMENTADAS
+
+Ao finalizar uma tarefa, **SEMPRE** incluir no relatório:
+
+```markdown
+[x] Regra 1 implementada (Arquitetura)
+[x] Regra 2 implementada (Front-End)
+[x] Regra 3 implementada (Segurança FE)
+[x] Regra 4 implementada (Tech Lead)
+[x] Regra 5 implementada (Database Security)
+[x] Regra 6 implementada (Auditor Final)
+```
+
+---
+
+## 🌐 CONTEXTO DE IDIOMA
+
+- **Comunicação**: Sempre em **Português** (Brasil)
+- **Código**: Inglês (variáveis, funções, comentários técnicos)
+- **Comentários de Código**: Português quando explicativos, inglês quando técnicos
+- **Relatórios**: Sempre em Português
+
+---
+
+**Última atualização**: 2026-01-20  
+**Versão**: 1.0.0  
+**Gerado por**: Documentation Agent

package/docs/BUILD_HISTORY.md

@@ -0,0 +1,65 @@
+# Histórico de Builds
+
+Este arquivo contém um resumo cronológico de todas as builds e mudanças significativas do projeto.
+
+---
+
+## [2026-01-20 10:10] Build 001 - Inicialização do Sistema de Agentes
+
+**Descrição**: Criação da estrutura base do sistema de agentes especializados e documentação automática.
+
+**Mudanças**:
+- ✅ Estrutura de diretórios `.agents/` criada
+  - `core/` - 5 agentes principais
+  - `domains/` - Agentes especializados (news, production, logistics)
+- ✅ Estrutura de documentação `docs/` criada
+  - `DESIGN_SYSTEM.md` - Sistema de design
+  - `SYMBOLS_TREE.md` - Árvore de símbolos
+  - `BUILD_HISTORY.md` - Este arquivo
+  - `AGENT_RULES.md` - Regras integradas
+  - `builds/` - Diretório de builds detalhados
+
+**Arquivos Criados**:
+- `.agents/core/` (preparado para agentes)
+- `.agents/domains/news/`
+- `.agents/domains/production/`
+- `.agents/domains/logistics/`
+- `docs/DESIGN_SYSTEM.md`
+- `docs/SYMBOLS_TREE.md`
+- `docs/BUILD_HISTORY.md`
+
+**Detalhes**: [build-001.md](./builds/build-001.md) *(será criado)*
+
+**Responsável**: Documentation Agent  
+**Status**: ✅ Concluído
+
+---
+
+## [Próximas Entradas]
+
+<!-- As próximas builds serão registradas aqui automaticamente -->
+
+---
+
+**Formato de Entrada**:
+```markdown
+## [YYYY-MM-DD HH:mm] Build XXX - Título Curto
+
+**Descrição**: Breve descrição do que foi feito
+
+**Mudanças**:
+- Lista de mudanças principais
+
+**Arquivos Criados/Modificados**:
+- Lista de arquivos
+
+**Detalhes**: [build-XXX.md](./builds/build-XXX.md)
+
+**Responsável**: [Nome do Agente ou Desenvolvedor]
+**Status**: ✅ Concluído / 🚧 Em Progresso / ❌ Bloqueado
+```
+
+---
+
+**Gerado por**: Documentation Agent  
+**Última atualização**: 2026-01-20 10:10

package/docs/DESIGN_SYSTEM.md

@@ -0,0 +1,256 @@
+# Sistema de Design - Triunfo Mineração
+
+## 🎨 Paleta de Cores
+
+### Cores Primárias
+- **Primary**: `#1E40AF` (blue-800) - Ações principais, links, botões primários
+- **Secondary**: `#10B981` (green-500) - Sucesso, confirmações, status positivo
+- **Accent**: `#F59E0B` (amber-500) - Destaques, alertas importantes
+- **Neutral**: `#6B7280` (gray-500) - Textos secundários, bordas
+- **Error**: `#EF4444` (red-500) - Erros, validações, alertas críticos
+
+### Cores de Status
+- **Success**: `#10B981` (green-500)
+- **Warning**: `#F59E0B` (amber-500)
+- **Error**: `#EF4444` (red-500)
+- **Info**: `#3B82F6` (blue-500)
+
+### Cores de Background
+- **Background**: `#F9FAFB` (gray-50)
+- **Surface**: `#FFFFFF` (white)
+- **Surface Secondary**: `#F3F4F6` (gray-100)
+
+---
+
+## 📝 Tipografia
+
+### Fonte Principal
+- **Família**: Inter (Google Fonts)
+- **Fallback**: system-ui, -apple-system, sans-serif
+
+### Hierarquia de Texto
+- **H1**: `font-bold text-3xl md:text-4xl` (30px → 36px)
+- **H2**: `font-bold text-2xl md:text-3xl` (24px → 30px)
+- **H3**: `font-semibold text-xl md:text-2xl` (20px → 24px)
+- **H4**: `font-semibold text-lg` (18px)
+- **Body**: `font-normal text-base` (16px)
+- **Body Small**: `font-normal text-sm` (14px)
+- **Caption**: `font-light text-xs` (12px)
+
+---
+
+## 🧩 Componentes Base
+
+### Buttons
+Baseado em **shadcn/ui Button**
+
+**Variantes**:
+- `default`: Background primary, texto branco
+- `outline`: Borda primary, texto primary, background transparente
+- `ghost`: Sem borda, texto primary, hover com background leve
+- `destructive`: Background red-500, texto branco
+- `link`: Sem background, underline no hover
+
+**Tamanhos**:
+- `sm`: `h-8 px-3 text-sm`
+- `default`: `h-10 px-4`
+- `lg`: `h-12 px-6 text-lg`
+- `icon`: `h-10 w-10` (quadrado)
+
+**Exemplo**:
+```tsx
+<Button variant="default" size="default">Salvar</Button>
+<Button variant="outline" size="sm">Cancelar</Button>
+```
+
+---
+
+### Inputs
+Baseado em **shadcn/ui Input**
+
+**Padrão**:
+- Borda: `border border-gray-300`
+- Focus: `ring-2 ring-primary`
+- Disabled: `opacity-50 cursor-not-allowed`
+- Error: `border-red-500 ring-red-500`
+
+**Com Label**:
+```tsx
+<div className="space-y-2">
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" type="email" placeholder="seu@email.com" />
+</div>
+```
+
+---
+
+### Cards
+Baseado em **shadcn/ui Card**
+
+**Estrutura**:
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Título do Card</CardTitle>
+    <CardDescription>Descrição opcional</CardDescription>
+  </CardHeader>
+  <CardContent>
+    {/* Conteúdo principal */}
+  </CardContent>
+  <CardFooter>
+    {/* Ações opcionais */}
+  </CardFooter>
+</Card>
+```
+
+**Estilos**:
+- Background: `bg-white`
+- Borda: `border border-gray-200`
+- Sombra: `shadow-sm`
+- Border radius: `rounded-lg` (0.5rem)
+
+---
+
+### Modals/Dialogs
+Baseado em **shadcn/ui Dialog**
+
+**Estrutura**:
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Abrir Modal</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Título</DialogTitle>
+      <DialogDescription>Descrição</DialogDescription>
+    </DialogHeader>
+    {/* Conteúdo */}
+    <DialogFooter>
+      <Button variant="outline">Cancelar</Button>
+      <Button>Confirmar</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+---
+
+### Tables
+Baseado em **TanStack Table v8**
+
+**Padrão**:
+- Header: `bg-gray-50 font-semibold text-left`
+- Rows: `border-b hover:bg-gray-50`
+- Células: `px-4 py-3`
+
+**Exemplo com shadcn/ui Table**:
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Coluna 1</TableHead>
+      <TableHead>Coluna 2</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>Dado 1</TableCell>
+      <TableCell>Dado 2</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+---
+
+## 🎯 Tokens de Design
+
+### Espaçamento
+- **Base unit**: `1rem` (16px)
+- **Scale**: 0.25rem, 0.5rem, 0.75rem, 1rem, 1.5rem, 2rem, 3rem, 4rem
+
+### Border Radius
+- **sm**: `0.25rem` (4px)
+- **default**: `0.5rem` (8px)
+- **md**: `0.75rem` (12px)
+- **lg**: `1rem` (16px)
+- **full**: `9999px` (círculo)
+
+### Sombras
+- **sm**: `shadow-sm` - Elevação leve
+- **default**: `shadow-md` - Elevação padrão
+- **lg**: `shadow-lg` - Elevação forte
+- **xl**: `shadow-xl` - Elevação máxima
+
+### Transições
+- **Padrão**: `transition-all duration-200 ease-in-out`
+- **Hover**: Aplicar em botões, links, cards clicáveis
+
+---
+
+## ♿ Acessibilidade
+
+### Contraste
+- Texto em background branco: mínimo AA (4.5:1)
+- Texto grande (18px+): mínimo AA (3:1)
+
+### Navegação por Teclado
+- Todos os botões/links acessíveis via Tab
+- Focus visível: `ring-2 ring-primary`
+- Escape fecha modals
+
+### ARIA Labels
+- Botões de ícone: `aria-label` obrigatório
+- Inputs: associar com `<Label>` via `htmlFor`
+- Estados: `aria-disabled`, `aria-expanded`, etc.
+
+---
+
+## 📱 Responsividade
+
+### Breakpoints (Tailwind)
+- **sm**: 640px
+- **md**: 768px
+- **lg**: 1024px
+- **xl**: 1280px
+- **2xl**: 1536px
+
+### Mobile-First
+Sempre começar com mobile e escalar para desktop:
+```tsx
+<div className="text-sm md:text-base lg:text-lg">
+  Texto responsivo
+</div>
+```
+
+---
+
+## 🚀 Performance
+
+### Imagens
+- Usar `next/image` sempre
+- Definir `width` e `height`
+- `priority` apenas above-the-fold
+- Lazy loading por padrão
+
+### Code Splitting
+- Componentes pesados: `dynamic(() => import())`
+- Bibliotecas grandes: carregar sob demanda
+
+---
+
+## 📦 Bibliotecas Aprovadas
+
+- **UI**: shadcn/ui (Radix UI + Tailwind)
+- **Forms**: React Hook Form + Zod
+- **Data Fetching**: TanStack Query
+- **Tabelas**: TanStack Table
+- **Datas**: date-fns
+- **Utils**: clsx / classnames
+- **Ícones**: lucide-react
+
+---
+
+**Última atualização**: 2026-01-20
+**Versão**: 1.0.0