diff --git a/DOCUMENTACAO/templates/modulo.yml.template b/DOCUMENTACAO/templates/modulo.yml.template index 0918659..1635c4d 100644 --- a/DOCUMENTACAO/templates/modulo.yml.template +++ b/DOCUMENTACAO/templates/modulo.yml.template @@ -2,7 +2,7 @@ # Este arquivo é obrigatório na raiz de todos os projetos que utilizam .agent. # Ele define a identidade oficial e as configurações de rota do módulo. -# Identificador único do módulo (utilizado para pacotes, wikis /../wiki// e regras de negócio) +# Identificador único do módulo (utilizado para pacotes, wikis // e regras de negócio) modulo-id: nome-do-modulo.submodulo # Rota/prefixo utilizado na URL e navegação do módulo (com barras inicial e final) @@ -13,3 +13,11 @@ modulo-descricao: Descrição detalhada do módulo para contextualização opera # Descrição da arquitetura, stack tecnológica e banco de dados modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres + +# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +modulo-acesso: + usuario: usuario@exemplo.com.br + senha: "123" + +# Caminho para a Wiki do projeto (quando omitido ou vazio, o padrão adotado é ../wiki/) +modulo-wiki: ../wiki diff --git a/global/rules/ddd-documentacao-primeiro.md b/global/rules/ddd-documentacao-primeiro.md index b3fca12..f6fefa6 100644 --- a/global/rules/ddd-documentacao-primeiro.md +++ b/global/rules/ddd-documentacao-primeiro.md @@ -26,21 +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//` | 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//` | 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** | `//` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários (caminho definido em `modulo-wiki` em `modulo.yml`, fallback padrão: `../wiki/`). Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. | +| **4. Wiki de Desenvolvimento** | `/dev//` | Desenvolvedores / Arquitetos | Seçã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 e Identidade** | `/memorias-ia/` | Agentes de IA / Auditoria | `modulo.yml` (identidade), índice central `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e sessões individuais `sessao-AAAA-MM-DD-slug.md`. | -> ℹ️ **Estrutura da Wiki VitePress (`/../wiki`)**: -> - `/../wiki//` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `` é o ID do módulo em `memorias-ia/modulo.yml`). -> - `/../wiki/dev//` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**. +> ℹ️ **Estrutura da Wiki VitePress (``, padrão: `/../wiki`)**: +> - `//` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `` e `` são extraídos de `memorias-ia/modulo.yml`, com fallback padrão para `../wiki/`). +> - `/dev//` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**. > 🧩 **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/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso`, `modulo-wiki`). Sempre consultado quando precisar de IDs, rotas base, credenciais de teste ou stack. > - `./memorias-ia/`: Registros individuais `sessao-AAAA-MM-DD-slug.md` e índice cumulativo `historico-acoes.md`. -> - `/../wiki//`: Documentação do módulo com acesso dos usuários (VitePress). -> - `/../wiki/dev//`: Documentação técnica do módulo com acesso interno dev (VitePress). +> - `//`: Documentação do módulo com acesso dos usuários (VitePress). +> - `/dev//`: Documentação técnica do módulo com acesso interno dev (VitePress). --- @@ -51,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//` (Pilar 3). - - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `/../wiki/dev//` (Pilar 4). + - É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `//` (Pilar 3). + - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `/dev//` (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 `/memorias-ia/sessao-AAAA-MM-DD-slug.md` e indexar em `historico-acoes.md` (Pilar 6). diff --git a/global/rules/identidade-modulo.md b/global/rules/identidade-modulo.md index 03afd99..bbb0797 100644 --- a/global/rules/identidade-modulo.md +++ b/global/rules/identidade-modulo.md @@ -1,18 +1,18 @@ --- type: rule name: identidade-modulo -description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo). +description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki). scope: global trigger: always_on priority: critica -updatedAt: "2026-09-02" +updatedAt: "2026-10-06" --- # Regra: Identidade do Projeto via `memorias-ia/modulo.yml` ## Contexto -O framework `.agent` é polimórfico e genérico, sendo compartilhado como submódulo Git entre múltiplos projetos do ecossistema. Para que qualquer agente saiba com precisão e sem ambiguidades qual é o projeto hospedeiro, seu identificador canônico, suas rotas de URL, sua descrição e sua stack técnica, a identidade do módulo é centralizada em um arquivo padronizado. +O framework `.agent` é polimórfico e genérico, sendo compartilhado como submódulo Git entre múltiplos projetos do ecossistema. Para que qualquer agente saiba com precisão e sem ambiguidades qual é o projeto hospedeiro, seu identificador canônico, suas rotas de URL, sua descrição, sua stack técnica, suas credenciais de teste e o caminho da sua Wiki, a identidade do módulo é centralizada em um arquivo padronizado. --- @@ -30,13 +30,21 @@ Caso o arquivo não exista ou esteja incompleto ao iniciar uma interação em um ## Estrutura Canônica de `memorias-ia/modulo.yml` -O arquivo deve conter estritamente as 4 chaves abaixo: +O arquivo contém os seguintes campos estruturados: ```yaml modulo-id: modulo-caminho: modulo-descricao: modulo-tipo: + +# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +modulo-acesso: + usuario: + senha: + +# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) +modulo-wiki: ``` ### Definição dos Campos @@ -47,15 +55,19 @@ modulo-tipo: | **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` | | **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` | | **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` | +| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` | +| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | --- ## Regra Universal de Consulta Sempre que qualquer agente, persona, workflow ou skill necessitar de: -1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`/../wiki//`), Wiki de Desenvolvimento (`/../wiki/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/../wiki/dev//adrs/`) ou relatórios; +1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`//`), Wiki de Desenvolvimento (`/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/dev//adrs/`) ou relatórios; 2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `llm.md`), links de navegação ou proxies; 3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes; +4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface; +5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia. 👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.** @@ -63,8 +75,8 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de: ## Proibições -- **NUNCA** assumir, deduzir ou "chutar" o ID ou a rota do módulo via heurísticas incertas quando o arquivo existir. -- **NUNCA** codificar IDs ou rotas de módulos hardcoded em regras e artefatos globais do `.agent`. +- **NUNCA** assumir, deduzir ou "chutar" o ID, a rota, credenciais de teste ou caminho de wiki via heurísticas incertas quando o arquivo existir. +- **NUNCA** codificar IDs, rotas ou credenciais hardcoded em regras e artefatos globais do `.agent`. - **NUNCA** deletar ou corromper o arquivo `memorias-ia/modulo.yml`. --- @@ -73,5 +85,6 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de: - Rule: `global/rules/ddd-documentacao-primeiro.md` - Rule: `global/rules/regras-negocio-md.md` +- Rule: `global/rules/testes-interface-agent-browser.md` - Template: `.agent/DOCUMENTACAO/templates/modulo.yml.template` - Hub: `.agent/DOCUMENTACAO/README` diff --git a/global/rules/proibido-commit-ia.md b/global/rules/proibido-commit-ia.md index 76d7f6f..3007af7 100644 --- a/global/rules/proibido-commit-ia.md +++ b/global/rules/proibido-commit-ia.md @@ -53,22 +53,23 @@ A IA **PODE** realizar commits na aplicação principal, **ESTRITAMENTE CONDICIO --- -### 2. No Repositório da Wiki (`/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER +### 2. No Repositório da Wiki (``, padrão: `/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER -Na Wiki, a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`: +Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modulo.yml`, com fallback mandatório para `/../wiki`), a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`: 1. **Commit e Push Diretos na Master**: ```bash - git -C /../wiki add -A - git -C /../wiki commit -m "docs(): " - git -C /../wiki push origin master + # extraído de memorias-ia/modulo.yml (fallback padrão: ../wiki) + git -C add -A + git -C commit -m "docs(): " + git -C push origin master ``` 2. **Resolução de Conflitos Direto na Master**: Se ao dar push houver rejeição ou divergência com o upstream remoto: - - A IA executa `git -C /../wiki pull --rebase origin master`. + - A IA executa `git -C pull --rebase origin master`. - Havendo conflitos de merge, a IA resolve as marcações diretamente na `master`, preservando a coerência da documentação dos 6 pilares. - - Adiciona os arquivos resolvidos (`git -C /../wiki add -A`), finaliza o rebase (`git -C /../wiki rebase --continue` ou commit) e envia com `git push origin master`. + - Adiciona os arquivos resolvidos (`git -C add -A`), finaliza o rebase (`git -C rebase --continue` ou commit) e envia com `git push origin master`. --- diff --git a/global/rules/regras-negocio-md.md b/global/rules/regras-negocio-md.md index 1e59411..c433213 100644 --- a/global/rules/regras-negocio-md.md +++ b/global/rules/regras-negocio-md.md @@ -7,17 +7,18 @@ trigger: always_on updatedAt: "2026-09-01" --- -# Regra: Conteúdo de Regras de Negócio em `/../wiki/dev//` +# Regra: Conteúdo de Regras de Negócio em `/dev//` > **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca. ## Contexto -Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `/../wiki/dev//`. +Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `/dev//`. -> 💡 **Aplicação VitePress (`/../wiki`) e Resolução do Módulo**: -> - O diretório `/../wiki` é uma aplicação VitePress na qual `/../wiki//` é voltado ao acesso dos **usuários**, e `/../wiki/dev//` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**. -> - O identificador `` (ou ``) **DEVE** ser obtido obrigatoriamente do campo `modulo-id` em `memorias-ia/modulo.yml` na raiz do projeto (ex: `e-licencie.sigma`). +> 💡 **Aplicação VitePress (``, padrão: `/../wiki`) e Resolução do Módulo**: +> - O caminho da Wiki `` **DEVE** ser obtido dinamicamente a partir do campo `modulo-wiki` em `memorias-ia/modulo.yml` (adotando compulsoriamente o fallback padrão `../wiki/` quando omitido ou não configurado). +> - Na Wiki resolvida, `//` é voltado ao acesso dos **usuários**, e `/dev//` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**. +> - O identificador `` (ou ``) **DEVE** ser obtido obrigatoriamente do campo `modulo-id` em `memorias-ia/modulo.yml` na raiz do projeto (ex: `e-licencie.sigma` ou `e-licencie-gov`). Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA. @@ -25,7 +26,8 @@ Isso garante centralização, governança técnica e facilidade de consulta por ## Regra -**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `/../wiki/dev//`.** +**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `/dev//`.** + Considera-se lógica não-trivial qualquer módulo que: - Possui 3 ou mais critérios de decisão distintos diff --git a/global/rules/testes-interface-agent-browser.md b/global/rules/testes-interface-agent-browser.md index 96d477c..efe0dc3 100644 --- a/global/rules/testes-interface-agent-browser.md +++ b/global/rules/testes-interface-agent-browser.md @@ -32,6 +32,9 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar 4. **Registrar evidências e fechar sessão**: - Registrar comprovações visuais com `agent-browser screenshot `. - Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo. +5. **Credenciais Canônicas de Teste (`modulo-acesso`)**: + - Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**. + - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. --- diff --git a/rules/ddd-documentacao-primeiro.md b/rules/ddd-documentacao-primeiro.md index b3fca12..f6fefa6 100644 --- a/rules/ddd-documentacao-primeiro.md +++ b/rules/ddd-documentacao-primeiro.md @@ -26,21 +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//` | 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//` | 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** | `//` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários (caminho definido em `modulo-wiki` em `modulo.yml`, fallback padrão: `../wiki/`). Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. | +| **4. Wiki de Desenvolvimento** | `/dev//` | Desenvolvedores / Arquitetos | Seçã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 e Identidade** | `/memorias-ia/` | Agentes de IA / Auditoria | `modulo.yml` (identidade), índice central `historico-acoes.md` (`Data \| Memória / Ação \| Arquivo Memoria \| Citações no Código-Fonte`) e sessões individuais `sessao-AAAA-MM-DD-slug.md`. | -> ℹ️ **Estrutura da Wiki VitePress (`/../wiki`)**: -> - `/../wiki//` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `` é o ID do módulo em `memorias-ia/modulo.yml`). -> - `/../wiki/dev//` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**. +> ℹ️ **Estrutura da Wiki VitePress (``, padrão: `/../wiki`)**: +> - `//` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `` e `` são extraídos de `memorias-ia/modulo.yml`, com fallback padrão para `../wiki/`). +> - `/dev//` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**. > 🧩 **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/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso`, `modulo-wiki`). Sempre consultado quando precisar de IDs, rotas base, credenciais de teste ou stack. > - `./memorias-ia/`: Registros individuais `sessao-AAAA-MM-DD-slug.md` e índice cumulativo `historico-acoes.md`. -> - `/../wiki//`: Documentação do módulo com acesso dos usuários (VitePress). -> - `/../wiki/dev//`: Documentação técnica do módulo com acesso interno dev (VitePress). +> - `//`: Documentação do módulo com acesso dos usuários (VitePress). +> - `/dev//`: Documentação técnica do módulo com acesso interno dev (VitePress). --- @@ -51,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//` (Pilar 3). - - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `/../wiki/dev//` (Pilar 4). + - É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `//` (Pilar 3). + - É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `/dev//` (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 `/memorias-ia/sessao-AAAA-MM-DD-slug.md` e indexar em `historico-acoes.md` (Pilar 6). diff --git a/rules/identidade-modulo.md b/rules/identidade-modulo.md index 03afd99..bbb0797 100644 --- a/rules/identidade-modulo.md +++ b/rules/identidade-modulo.md @@ -1,18 +1,18 @@ --- type: rule name: identidade-modulo -description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo). +description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki). scope: global trigger: always_on priority: critica -updatedAt: "2026-09-02" +updatedAt: "2026-10-06" --- # Regra: Identidade do Projeto via `memorias-ia/modulo.yml` ## Contexto -O framework `.agent` é polimórfico e genérico, sendo compartilhado como submódulo Git entre múltiplos projetos do ecossistema. Para que qualquer agente saiba com precisão e sem ambiguidades qual é o projeto hospedeiro, seu identificador canônico, suas rotas de URL, sua descrição e sua stack técnica, a identidade do módulo é centralizada em um arquivo padronizado. +O framework `.agent` é polimórfico e genérico, sendo compartilhado como submódulo Git entre múltiplos projetos do ecossistema. Para que qualquer agente saiba com precisão e sem ambiguidades qual é o projeto hospedeiro, seu identificador canônico, suas rotas de URL, sua descrição, sua stack técnica, suas credenciais de teste e o caminho da sua Wiki, a identidade do módulo é centralizada em um arquivo padronizado. --- @@ -30,13 +30,21 @@ Caso o arquivo não exista ou esteja incompleto ao iniciar uma interação em um ## Estrutura Canônica de `memorias-ia/modulo.yml` -O arquivo deve conter estritamente as 4 chaves abaixo: +O arquivo contém os seguintes campos estruturados: ```yaml modulo-id: modulo-caminho: modulo-descricao: modulo-tipo: + +# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +modulo-acesso: + usuario: + senha: + +# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) +modulo-wiki: ``` ### Definição dos Campos @@ -47,15 +55,19 @@ modulo-tipo: | **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` | | **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` | | **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` | +| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` | +| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | --- ## Regra Universal de Consulta Sempre que qualquer agente, persona, workflow ou skill necessitar de: -1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`/../wiki//`), Wiki de Desenvolvimento (`/../wiki/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/../wiki/dev//adrs/`) ou relatórios; +1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`//`), Wiki de Desenvolvimento (`/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/dev//adrs/`) ou relatórios; 2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `llm.md`), links de navegação ou proxies; 3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes; +4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface; +5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia. 👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.** @@ -63,8 +75,8 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de: ## Proibições -- **NUNCA** assumir, deduzir ou "chutar" o ID ou a rota do módulo via heurísticas incertas quando o arquivo existir. -- **NUNCA** codificar IDs ou rotas de módulos hardcoded em regras e artefatos globais do `.agent`. +- **NUNCA** assumir, deduzir ou "chutar" o ID, a rota, credenciais de teste ou caminho de wiki via heurísticas incertas quando o arquivo existir. +- **NUNCA** codificar IDs, rotas ou credenciais hardcoded em regras e artefatos globais do `.agent`. - **NUNCA** deletar ou corromper o arquivo `memorias-ia/modulo.yml`. --- @@ -73,5 +85,6 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de: - Rule: `global/rules/ddd-documentacao-primeiro.md` - Rule: `global/rules/regras-negocio-md.md` +- Rule: `global/rules/testes-interface-agent-browser.md` - Template: `.agent/DOCUMENTACAO/templates/modulo.yml.template` - Hub: `.agent/DOCUMENTACAO/README` diff --git a/rules/proibido-commit-ia.md b/rules/proibido-commit-ia.md index 76d7f6f..3007af7 100644 --- a/rules/proibido-commit-ia.md +++ b/rules/proibido-commit-ia.md @@ -53,22 +53,23 @@ A IA **PODE** realizar commits na aplicação principal, **ESTRITAMENTE CONDICIO --- -### 2. No Repositório da Wiki (`/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER +### 2. No Repositório da Wiki (``, padrão: `/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER -Na Wiki, a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`: +Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modulo.yml`, com fallback mandatório para `/../wiki`), a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`: 1. **Commit e Push Diretos na Master**: ```bash - git -C /../wiki add -A - git -C /../wiki commit -m "docs(): " - git -C /../wiki push origin master + # extraído de memorias-ia/modulo.yml (fallback padrão: ../wiki) + git -C add -A + git -C commit -m "docs(): " + git -C push origin master ``` 2. **Resolução de Conflitos Direto na Master**: Se ao dar push houver rejeição ou divergência com o upstream remoto: - - A IA executa `git -C /../wiki pull --rebase origin master`. + - A IA executa `git -C pull --rebase origin master`. - Havendo conflitos de merge, a IA resolve as marcações diretamente na `master`, preservando a coerência da documentação dos 6 pilares. - - Adiciona os arquivos resolvidos (`git -C /../wiki add -A`), finaliza o rebase (`git -C /../wiki rebase --continue` ou commit) e envia com `git push origin master`. + - Adiciona os arquivos resolvidos (`git -C add -A`), finaliza o rebase (`git -C rebase --continue` ou commit) e envia com `git push origin master`. --- diff --git a/rules/regras-negocio-md.md b/rules/regras-negocio-md.md index 1e59411..c433213 100644 --- a/rules/regras-negocio-md.md +++ b/rules/regras-negocio-md.md @@ -7,17 +7,18 @@ trigger: always_on updatedAt: "2026-09-01" --- -# Regra: Conteúdo de Regras de Negócio em `/../wiki/dev//` +# Regra: Conteúdo de Regras de Negócio em `/dev//` > **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca. ## Contexto -Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `/../wiki/dev//`. +Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `/dev//`. -> 💡 **Aplicação VitePress (`/../wiki`) e Resolução do Módulo**: -> - O diretório `/../wiki` é uma aplicação VitePress na qual `/../wiki//` é voltado ao acesso dos **usuários**, e `/../wiki/dev//` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**. -> - O identificador `` (ou ``) **DEVE** ser obtido obrigatoriamente do campo `modulo-id` em `memorias-ia/modulo.yml` na raiz do projeto (ex: `e-licencie.sigma`). +> 💡 **Aplicação VitePress (``, padrão: `/../wiki`) e Resolução do Módulo**: +> - O caminho da Wiki `` **DEVE** ser obtido dinamicamente a partir do campo `modulo-wiki` em `memorias-ia/modulo.yml` (adotando compulsoriamente o fallback padrão `../wiki/` quando omitido ou não configurado). +> - Na Wiki resolvida, `//` é voltado ao acesso dos **usuários**, e `/dev//` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**. +> - O identificador `` (ou ``) **DEVE** ser obtido obrigatoriamente do campo `modulo-id` em `memorias-ia/modulo.yml` na raiz do projeto (ex: `e-licencie.sigma` ou `e-licencie-gov`). Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA. @@ -25,7 +26,8 @@ Isso garante centralização, governança técnica e facilidade de consulta por ## Regra -**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `/../wiki/dev//`.** +**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `/dev//`.** + Considera-se lógica não-trivial qualquer módulo que: - Possui 3 ou mais critérios de decisão distintos diff --git a/rules/testes-interface-agent-browser.md b/rules/testes-interface-agent-browser.md index 96d477c..efe0dc3 100644 --- a/rules/testes-interface-agent-browser.md +++ b/rules/testes-interface-agent-browser.md @@ -32,6 +32,9 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar 4. **Registrar evidências e fechar sessão**: - Registrar comprovações visuais com `agent-browser screenshot `. - Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo. +5. **Credenciais Canônicas de Teste (`modulo-acesso`)**: + - Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**. + - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. --- diff --git a/skills/diagnosticar-lacunas-documentacao/SKILL.md b/skills/diagnosticar-lacunas-documentacao/SKILL.md index 5da2eae..3c821cf 100644 --- a/skills/diagnosticar-lacunas-documentacao/SKILL.md +++ b/skills/diagnosticar-lacunas-documentacao/SKILL.md @@ -45,18 +45,18 @@ find -front/src -name "modal*.vue" -o -name "Modal*.vue" | while read vu done ``` -### 3. Pilar 3 — Wiki do Usuário (`/../wiki//`) +### 3. Pilar 3 — Wiki do Usuário (`//`) ```sh -# Verificar se existe documentação de usuário do módulo -ls -la /../wiki//*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM /../wiki//" +# Verificar se existe documentação de usuário do módulo (modulo-wiki com fallback para ../wiki) +ls -la //*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM //" ``` -### 4. Pilar 4 — Wiki de Desenvolvimento (`/../wiki/dev//`) +### 4. Pilar 4 — Wiki de Desenvolvimento (`/dev//`) ```sh # Verificar se existe documentação de desenvolvimento, regras de negócio ({modulo}.regras-negocio.md) e ADRs -ls -la /../wiki/dev//*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM /../wiki/dev//" +ls -la /dev//*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM /dev//" ``` ### 5. Pilar 5 — Rota de Integração de IA (`/llm.md`) @@ -71,8 +71,8 @@ rg "llm\.md" --include='*.ts' -back/src/ -n || echo "ROTA /llm.md NÃO E ```sh # 1. Verificar arquivo obrigatório modulo.yml e chaves if [ -f "memorias-ia/modulo.yml" ]; then - for chave in modulo-id modulo-caminho modulo-descricao modulo-tipo; do - grep -q "^$chave:" memorias-ia/modulo.yml || echo "CHAVE AUSENTE EM modulo.yml: $chave" + for chave in modulo-id modulo-caminho modulo-descricao modulo-tipo modulo-acesso modulo-wiki; do + grep -q "^$chave:" memorias-ia/modulo.yml || echo "CHAVE AUSENTE OU RECOMENDADA EM modulo.yml: $chave" done else echo "CRÍTICO: memorias-ia/modulo.yml AUSENTE" @@ -92,12 +92,13 @@ ls -la memorias-ia/ 2>/dev/null || echo "DIRETÓRIO memorias-ia/ NÃO ENCONTRADO ## Resumo dos 6 Pilares - **Código-fonte sem JSDoc de aplicação:** N - **Modais/Telas sem .ajuda.md co-localizado:** N -- **Wiki de Usuário (/../wiki//):** Presente / Ausente -- **Wiki de Desenvolvimento (/../wiki/dev//):** Presente / Ausente +- **Wiki de Usuário (//):** Presente / Ausente +- **Wiki de Desenvolvimento (/dev//):** Presente / Ausente - **Rota /llm.md no backend:** Configurada / Ausente - **Identidade em memorias-ia/modulo.yml:** Conforme / Ausente - **Registros em memorias-ia/:** N registros + ## Ações Recomendadas 1. ... ``` diff --git a/skills/documentar-decisao-tecnica/SKILL.md b/skills/documentar-decisao-tecnica/SKILL.md index fa08b7b..212c238 100644 --- a/skills/documentar-decisao-tecnica/SKILL.md +++ b/skills/documentar-decisao-tecnica/SKILL.md @@ -28,13 +28,14 @@ O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdi ## PASSO 1 — Obter Identidade do Módulo e Localizar o Diretório de ADRs -1. Ler `modulo-id` em `/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`). -2. Convenção de diretório: `/../wiki/dev//adrs/` (na Wiki de Desenvolvimento). +1. Ler `modulo-id` e `modulo-wiki` em `/memorias-ia/modulo.yml` (fallback de wiki: `../wiki/`). +2. Convenção de diretório: `/dev//adrs/` (na Wiki de Desenvolvimento). ```bash -mkdir -p /../wiki/dev//adrs +mkdir -p /dev//adrs ``` + --- ## PASSO 2 — Criar o Arquivo ADR @@ -153,7 +154,7 @@ Antes de considerar completo: - [ ] As consequências (positivas e negativas) estão claras? - [ ] Os pacotes impactados estão listados? - [ ] O status está definido (proposto/aceito)? -- [ ] O ADR foi salvo em `/../wiki/dev//adrs/`? +- [ ] O ADR foi salvo em `/dev//adrs/`? - [ ] A decisão foi registrada na memória em `/memorias-ia/`? - [ ] Alguém de fora do contexto entenderia este ADR? @@ -163,4 +164,5 @@ Antes de considerar completo: - Rule: `rules/ddd-documentacao-primeiro.md` - Workflow: `global/workflows/aprimora-ia.md` -- Wiki de Desenvolvimento: `/../wiki/dev//adrs/` +- Wiki de Desenvolvimento: `/dev//adrs/` + diff --git a/skills/documentar-dominio-modulo/SKILL.md b/skills/documentar-dominio-modulo/SKILL.md index db46f2a..9f013f8 100644 --- a/skills/documentar-dominio-modulo/SKILL.md +++ b/skills/documentar-dominio-modulo/SKILL.md @@ -11,9 +11,9 @@ description: > Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda. -Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `/../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso: -1. **Wiki do Usuário (`/../wiki//`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais). -2. **Wiki de Desenvolvimento (`/../wiki/dev//`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs). +Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `` (configurado em `memorias-ia/modulo.yml`, com fallback padrão para `/../wiki`) é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso: +1. **Wiki do Usuário (`//`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais). +2. **Wiki de Desenvolvimento (`/dev//`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs). --- @@ -24,14 +24,16 @@ Consultar obrigatoriamente `/memorias-ia/modulo.yml` na raiz do pr - `modulo-caminho`: rota base na URL (ex: `/sigma/`) - `modulo-descricao`: escopo funcional e propósito do módulo - `modulo-tipo`: stack tecnológica e arquitetura +- `modulo-wiki`: caminho relativo ou absoluto para a Wiki (fallback: `../wiki/`) -Os destinos canônicos da documentação na aplicação VitePress (`/../wiki`) são: -- **Wiki do Usuário:** `/../wiki//` -- **Wiki de Desenvolvimento:** `/../wiki/dev//` +Os destinos canônicos da documentação na aplicação VitePress (``) são: +- **Wiki do Usuário:** `//` +- **Wiki de Desenvolvimento:** `/dev//` --- -## PASSO 2 — Criar Documentação na Wiki do Usuário (`/../wiki//`) +## PASSO 2 — Criar Documentação na Wiki do Usuário (`//`) + Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível: @@ -55,7 +57,7 @@ Breve descrição do propósito do módulo para o gestor e operador. --- -## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`/../wiki/dev//`) +## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`/dev//`) Estruturar a especificação técnica, modelos de banco e arquitetura: @@ -86,8 +88,9 @@ Estruturar a especificação técnica, modelos de banco e arquitetura: ## Checklist Final -- [ ] Documentação de usuário criada/atualizada em `/../wiki//`? -- [ ] Documentação técnica criada/atualizada em `/../wiki/dev//`? +- [ ] Documentação de usuário criada/atualizada em `//`? +- [ ] Documentação técnica criada/atualizada em `/dev//`? + - [ ] Glossário com os termos centrais do domínio documentado? - [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`? - [ ] Rota `/llm.md` no backend reflete o módulo? diff --git a/skills/documentar-regras-negocio/SKILL.md b/skills/documentar-regras-negocio/SKILL.md index c0491a8..cc9f58a 100644 --- a/skills/documentar-regras-negocio/SKILL.md +++ b/skills/documentar-regras-negocio/SKILL.md @@ -7,13 +7,13 @@ updatedAt: "2026-09-02" # Workflow / Skill: Documentar Regras de Negócio de um Módulo -Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `/../wiki/dev//`. +Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `/dev//`. --- [1] Obter a identidade do módulo e ler o código TypeScript -1. Ler `modulo-id` em `/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`). +1. Ler `modulo-id` e `modulo-wiki` em `/memorias-ia/modulo.yml` (fallback de wiki: `../wiki/`). 2. Identificar e anotar no código: - Nome do arquivo e localização exata no código - Funções exportadas e suas responsabilidades @@ -28,7 +28,7 @@ Use este workflow para criar ou atualizar o arquivo de regras de negócio de qua [2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento ```bash -ls /../wiki/dev//*regras-negocio*.md 2>/dev/null +ls /dev//*regras-negocio*.md 2>/dev/null ``` - **Existe** → ler e identificar o que está desatualizado → ir para o passo [4] @@ -38,7 +38,7 @@ ls /../wiki/dev//*regras-negocio*.md 2>/dev/null [3] Criar o arquivo de regras na Wiki de Desenvolvimento -**Localização:** `/../wiki/dev//{nome-do-modulo}.regras-negocio.md` (ou `/../wiki/dev//regras-negocio/`). +**Localização:** `/dev//{nome-do-modulo}.regras-negocio.md` (ou `/dev//regras-negocio/`). Preencher com a estrutura padrão: - Contexto operacional @@ -55,9 +55,10 @@ Preencher com a estrutura padrão: Garantir que a primeira linha útil do arquivo TypeScript seja: ```typescript -// Regras de negócio: ver /../wiki/dev//{modulo}.regras-negocio.md +// Regras de negócio: ver /dev//{modulo}.regras-negocio.md ``` + Se já existia e está correto → sem mudança necessária. --- @@ -100,7 +101,8 @@ Zero erros = concluído. Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo: -- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `/../wiki/dev//`. -- Criar ou atualizar ADR em `/../wiki/dev//adrs/` via skill `documentar-decisao-tecnica`. +- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `/dev//`. +- Criar ou atualizar ADR em `/dev//adrs/` via skill `documentar-decisao-tecnica`. - Registrar decisões e ações na memória em `/memorias-ia/`. -- **Sincronização Git:** Executar commit e push exclusivamente na Wiki (`git -C /../wiki add -A && git -C /../wiki commit -m "docs(): regras de negócio" && git -C /../wiki push`). Na aplicação (``), nunca mexer no git. +- **Sincronização Git:** Executar commit e push exclusivamente na Wiki (`git -C add -A && git -C commit -m "docs(): regras de negócio" && git -C push`). Na aplicação (``), nunca comitar em master. + diff --git a/skills/onboarding-projeto/SKILL.md b/skills/onboarding-projeto/SKILL.md index b139a73..852965d 100644 --- a/skills/onboarding-projeto/SKILL.md +++ b/skills/onboarding-projeto/SKILL.md @@ -68,11 +68,12 @@ Utilize os modelos canônicos disponíveis em `.agent/DOCUMENTACAO/templates/`: | :--- | :--- | :--- | | **Pilar 1: Código** | `.ts`, `.vue`, `.js` | JSDoc no topo das funções | | **Pilar 2: Ajuda UI** | `*-front/src/.../{componente}.ajuda.md` | `DOCUMENTACAO/templates/ajuda-tela.md.template` | -| **Pilar 3: Wiki Usuário** | `/../wiki//index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` | -| **Pilar 4: Wiki Dev** | `/../wiki/dev//` | `DOCUMENTACAO/templates/regra-negocio.md.template` e `adr.md.template` | +| **Pilar 3: Wiki Usuário** | `//index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` | +| **Pilar 4: Wiki Dev** | `/dev//` | `DOCUMENTACAO/templates/regra-negocio.md.template` e `adr.md.template` | | **Pilar 5: IA (/llm.md)** | `GET llm.md` | `DOCUMENTACAO/templates/contrato-api.md.template` | | **Pilar 6: Memórias IA** | `memorias-ia/sessao-*.md` | Frontmatter `type: session_memory` | + --- ## 🧩 Extensibilidade Local (`.agent-local/`) — Opcional diff --git a/skills/testar-interface-agent-browser/SKILL.md b/skills/testar-interface-agent-browser/SKILL.md index 24851f4..43a209e 100644 --- a/skills/testar-interface-agent-browser/SKILL.md +++ b/skills/testar-interface-agent-browser/SKILL.md @@ -133,6 +133,25 @@ agent-browser close --- +## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`) + +Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`: + +```bash +# Extrair credenciais canônicas de teste de memorias-ia/modulo.yml +USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') +SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') + +# Preenchimento determinístico no formulário de login +agent-browser fill @e1 "$USUARIO" +agent-browser fill @e2 "$SENHA" +agent-browser click @e3 +``` + +> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. + +--- + ## Sessões Persistentes e Autenticação Para fluxos que necessitam manter login ativo entre comandos: @@ -144,6 +163,7 @@ agent-browser --session auth-test --restore open --headed http://localhost:8080/ agent-browser session info --json ``` + --- ## Skills Nativas do agent-browser diff --git a/validar-setup.sh b/validar-setup.sh index 8ac388d..ecb0549 100644 --- a/validar-setup.sh +++ b/validar-setup.sh @@ -15,10 +15,10 @@ NEGRITO="\033[1m" RESET="\033[0m" # Identificar a raiz do projeto pai -if [ -d "../memorias-ia" ] || [ -f "../package.json" ]; then - ROOT_DIR=".." -elif [ -d "memorias-ia" ] || [ -f "package.json" ]; then +if [ -d "memorias-ia" ] || [ -f "memorias-ia/modulo.yml" ] || [ -f "package.json" ]; then ROOT_DIR="." +elif [ -d "../memorias-ia" ] || [ -f "../memorias-ia/modulo.yml" ] || [ -f "../package.json" ]; then + ROOT_DIR=".." else ROOT_DIR="." fi @@ -71,6 +71,20 @@ if [ -f "$MODULO_YML" ]; then TOTAL_ERROS=$((TOTAL_ERROS + 1)) fi + # Validar modulo-acesso (credenciais de teste para automação e QA) + if grep -q "modulo-acesso:" "$MODULO_YML"; then + echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais de teste configuradas." + else + echo -e " ${AMARELO}⚠${RESET} modulo-acesso: credenciais de teste não configuradas em modulo.yml." + fi + + # Resolver modulo-wiki (caminho da wiki com fallback mandatório para ../wiki) + MODULO_WIKI=$(grep -E "^modulo-wiki:" "$MODULO_YML" | awk '{print $2}' || true) + if [ -z "$MODULO_WIKI" ]; then + MODULO_WIKI="../wiki" + fi + echo -e " ${VERDE}✓${RESET} modulo-wiki resolvido: ${NEGRITO}$MODULO_WIKI${RESET}" + # Validar memorias-ia/historico-acoes.md (Pilar 6 - Índice de Ações) HISTORICO_MD="$ROOT_DIR/memorias-ia/historico-acoes.md" if [ -f "$HISTORICO_MD" ]; then @@ -89,11 +103,11 @@ fi # 2. Validar Wiki do Usuário (Pilar 3) echo -e "\n${NEGRITO}[2/6] Wiki do Usuário (Pilar 3)${RESET}" if [ -n "$MODULO_ID" ]; then - WIKI_USER_DIR="$ROOT_DIR/../wiki/$MODULO_ID" + WIKI_USER_DIR="$ROOT_DIR/$MODULO_WIKI/$MODULO_ID" if [ -d "$WIKI_USER_DIR" ]; then - echo -e " ${VERDE}✓${RESET} Diretório encontrado em: /../wiki/$MODULO_ID/" + echo -e " ${VERDE}✓${RESET} Diretório encontrado em: $MODULO_WIKI/$MODULO_ID/" else - echo -e " ${AMARELO}⚠${RESET} Diretório /../wiki/$MODULO_ID/ não encontrado." + echo -e " ${AMARELO}⚠${RESET} Diretório $MODULO_WIKI/$MODULO_ID/ não encontrado." TOTAL_AVISOS=$((TOTAL_AVISOS + 1)) fi else @@ -103,11 +117,11 @@ fi # 3. Validar Wiki de Desenvolvimento (Pilar 4) echo -e "\n${NEGRITO}[3/6] Wiki de Desenvolvimento (Pilar 4)${RESET}" if [ -n "$MODULO_ID" ]; then - WIKI_DEV_DIR="$ROOT_DIR/../wiki/dev/$MODULO_ID" + WIKI_DEV_DIR="$ROOT_DIR/$MODULO_WIKI/dev/$MODULO_ID" if [ -d "$WIKI_DEV_DIR" ]; then - echo -e " ${VERDE}✓${RESET} Diretório encontrado em: /../wiki/dev/$MODULO_ID/" + echo -e " ${VERDE}✓${RESET} Diretório encontrado em: $MODULO_WIKI/dev/$MODULO_ID/" else - echo -e " ${AMARELO}⚠${RESET} Diretório /../wiki/dev/$MODULO_ID/ não encontrado." + echo -e " ${AMARELO}⚠${RESET} Diretório $MODULO_WIKI/dev/$MODULO_ID/ não encontrado." TOTAL_AVISOS=$((TOTAL_AVISOS + 1)) fi else