melhorias na ia

rules/regras-negocio-md.global.md

@@ -0,0 +1,120 @@
+---
+type: rule
+name: regras-negocio-md
+description: Arquivo {modulo}.regras-negocio.md obrigatório para módulos com lógica complexa
+scope: global
+trigger: always_on
+updatedAt: "2026-06-01"
+---
+
+# Regra: Arquivo `{modulo}.regras-negocio.md` Obrigatório para Módulos com Lógica Complexa
+
+> **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca.
+
+## Contexto
+
+Qualquer arquivo TypeScript que contenha lógica de negócio não-trivial — múltiplas regras de decisão, critérios de bloqueio, estratégias de processamento — deve ter suas regras documentadas em linguagem natural em um arquivo Markdown co-localizado.
+
+Isso garante que produto, suporte e desenvolvimento possam entender as regras sem precisar ler TypeScript, e que o agente de IA encontre rapidamente os critérios corretos antes de alterar qualquer código.
+
+## Regra
+
+**Todo módulo com lógica de negócio não-trivial DEVE ter um arquivo `{modulo}.regras-negocio.md` co-localizado.**
+
+Considera-se lógica não-trivial qualquer módulo que:
+- possui 3 ou mais critérios de decisão distintos
+- realiza eleição/priorização entre registros
+- aplica diferentes estratégias por tipo de dado
+- pode resultar em revisão manual (caminho alternativo ao fluxo automático)
+- é consumido por CRON, worker ou importador automático
+
+O módulo TypeScript deve conter, na primeira linha do arquivo, a referência:
+
+```typescript
+// Regras de negócio: ver {modulo}.regras-negocio.md
+```
+
+O arquivo `.md` é a **fonte de verdade**. Os JSDoc do código devem referenciar o `.md`, não duplicá-lo.
+
+## Estrutura Obrigatória do Arquivo
+
+```markdown
+# Regras de Negócio — [Nome do Módulo]
+
+Módulo: `_arquivo.ts`
+Localização: `caminho/relativo/ao/arquivo`
+
+---
+
+## Contexto
+Por que este módulo existe, qual problema resolve.
+
+## Critérios de Entrada / Identificação
+O que aciona o módulo, quais dados recebe, filtros aplicados.
+
+## Regras de Processamento
+As regras numeradas em ordem de avaliação.
+
+## Casos de Revisão Manual (quando aplicável)
+Quando o processamento automático não pode prosseguir.
+
+## Estratégia de Fusão / Resultado (quando aplicável)
+O que o módulo produz, como campos são combinados.
+
+## Dependências Externas
+Tabelas, filas, serviços externos tocados pelo módulo.
+```
+
+## Exemplos
+
+✅ **Correto** — referência no topo do módulo, regras no `.md`:
+```typescript
+// Regras de negócio: ver juntar_execucoes.regras-negocio.md
+
+import { ... } from "..."
+
+export const compilarJuntarExecucoes = async (...) => {
+  // implementação conforme regras-negocio.md
+}
+```
+
+❌ **Errado** — regras embutidas no código como comentário de bloco:
+```typescript
+/**
+ * Regras de negócio:
+ * [x] Pode ter apenas uma execução por data de vencimento.
+ * [x] Se tiver apenas uma execução consolidada → ela é a principal.
+ * ...
+ */
+```
+
+❌ **Errado** — JSDoc duplicando as regras em vez de referenciar o `.md`:
+```typescript
+/**
+ * Retorna false quando:
+ * - vencimentos divergentes
+ * - executada com datas distintas
+ * - vencimento_prorrogado distintos
+ * ...
+ */
+```
+
+## Impacto
+
+Sem este padrão:
+- Regras de negócio ficam implícitas no código ou em JSDoc que envelhece sem controle
+- O agente de IA precisa inferir regras do código ao invés de lê-las diretamente
+- Produto e suporte não conseguem validar o comportamento sem ajuda técnica
+- Mudanças de regra geram JSDoc desatualizado espalhado pelo código
+
+## Aplicação
+
+- Módulos de CRON com lógica de auditoria/fusão
+- Importadores automáticos (ex: importação de licenças via IA)
+- Workers de processamento em lote
+- Qualquer utilitário com lógica de decisão multi-critério
+
+## Referências
+
+- Skill: `.agent/skills/documentar-regras-negocio.global/SKILL.md`
+- Workflow: `.agent/workflows/documentar-regras-negocio.global.md`