aplimoramento de agent

rules/ddd-documentacao-primeiro.md

@@ -26,20 +26,21 @@ Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeit
 | :--- | :--- | :--- | :--- |
 | **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | Comentários claros e coerentes quanto à sua aplicação prática, contexto e raciocínio de negócio (JSDoc no topo de funções, serviços e rotas). |
 | **2. Ajuda na Tela (UI)** | `*-front/src/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue`, o arquivo de ajuda **DEVE** ser `modalX.ajuda.md`. Detalha objetivo, botões, campos e instruções de uso. |
-| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
-| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
+| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo-id>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
+| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo-id>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
 | **5. Integração de IA** | Rota de Backend `/llm.md` | Agentes de IA / LLMs | Documentação gerada/servida dinamicamente contendo schemas Zod, enums canônicos, endpoints e contratos para consumo por LLMs. |
-| **6. Memória das Ações da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões da IA, otimizações executadas, histórico de decisões arquiteturais e relatórios de aprimoramento contínuo. |
+| **6. Memória das Ações da IA e Identidade** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Arquivo mandatório `modulo.yml` (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`), registros de sessões, histórico de decisões e relatórios de aprimoramento. |
 
-> ℹ️ **Estrutura da Wiki VitePress (`../../wiki`)**:
-> - `../../wiki/<modulo>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes**.
-> - `../../wiki/dev/<modulo>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
+> ℹ️ **Estrutura da Wiki VitePress (`<base_projeto>/../wiki`)**:
+> - `<base_projeto>/../wiki/<modulo-id>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `<modulo-id>` é o ID do módulo em `memorias-ia/modulo.yml`).
+> - `<base_projeto>/../wiki/dev/<modulo-id>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
 
-> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
-> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização de cada projeto reside em:
-> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
-> - `../../wiki/<modulo>/`: Documentação do módulo com acesso dos usuários (VitePress).
-> - `../../wiki/dev/<modulo>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
+> 🧩 **Polimorfismo do `.agent` e Identidade do Projeto**:
+> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização e identidade de cada projeto reside em:
+> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`). Sempre consultado quando precisar de IDs, rotas base ou stack.
+> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
+> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação do módulo com acesso dos usuários (VitePress).
+> - `<base_projeto>/../wiki/dev/<modulo-id>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
 
 ---
 
@@ -50,8 +51,8 @@ Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo:
 1. **Identificar os Pilares Impactados**:
    - É alteração de código? $\rightarrow$ Planejar comentários contextuais claros (Pilar 1).
    - É tela/modal com ajuda ao usuário? $\rightarrow$ Criar/atualizar `modalX.ajuda.md` co-localizado (Pilar 2).
-   - É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `../../wiki/<modulo>/` (Pilar 3).
-   - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `../../wiki/dev/<modulo>/` (Pilar 4).
+   - É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `<base_projeto>/../wiki/<modulo>/` (Pilar 3).
+   - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `<base_projeto>/../wiki/dev/<modulo>/` (Pilar 4).
    - É endpoint, schema ou contrato de API? $\rightarrow$ Assegurar reflexão na rota `/llm.md` (Pilar 5).
    - É ação estruturante ou otimização de IA? $\rightarrow$ Registrar memória em `<base_projeto>/memorias-ia/` (Pilar 6).
 
@@ -82,14 +83,14 @@ A etapa de documentação prévia pode ser simplificada apenas para:
 
 ✅ **Correto**:
 - Criou um novo modal `ModalParametros.vue` $\rightarrow$ criou `ModalParametros.ajuda.md` na mesma pasta explicando campos e botões para o usuário.
-- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `../../wiki/dev/e-licencie.sigma/` e o guia de uso em `../../wiki/e-licencie.sigma/`.
+- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `<base_projeto>/../wiki/dev/e-licencie.sigma/` e o guia de uso em `<base_projeto>/../wiki/e-licencie.sigma/`.
 - Criou endpoints novos no backend $\rightarrow$ rota `/llm.md` atualizada automaticamente via gerador de contratos.
 - Realizou otimização no ecossistema de agentes $\rightarrow$ registrou relatório em `<base_projeto>/memorias-ia/`.
 
 ❌ **Incorreto**:
 - Criou `modalX.vue` e colocou ajuda em formato desconhecido ou fora da pasta do componente.
 - Implementou código sem comentários ou com JSDoc que apenas repete os tipos sem explicar a aplicação real no sistema.
-- Criou regras técnicas complexas sem atualizar `../../wiki/dev/<modulo>/`.
+- Criou regras técnicas complexas sem atualizar `<base_projeto>/../wiki/dev/<modulo>/`.
 - Gravou registros de ações da IA em pastas despadronizadas fora de `<base_projeto>/memorias-ia/`.
 
 ---