chore(agent): remover permissoes de commit da IA no projeto e wiki (apenas sugerir texto) e manter push automatico exclusivo no .agent
This commit is contained in:
parent
212d2578f4
commit
26a4f98dab
116 changed files with 1162 additions and 1315 deletions
|
|
@ -1,8 +1,17 @@
|
|||
---
|
||||
type: rule
|
||||
name: atualizacao-submodulo-sessao
|
||||
description: Atualização obrigatória do submódulo .agent na branch master ao iniciar qualquer sessão de trabalho
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Atualização Obrigatória do Submódulo `.agent` na Branch Master ao Iniciar Sessão
|
||||
|
||||
## Contexto
|
||||
|
||||
O ecossistema Azteca adota o framework `.agent` como um **git submodule** compartilhado entre múltiplos repositórios e produtos (`quipo`, `e-licencie`, `sigma`, etc.). Novas regras, personas, correções de ferramentas (como isolamento de sessão do `agent-browser` e upload MinIO Paiol), workflows e skills são continuamente aprimorados e versionados diretamente na branch `master` do repositório remoto:
|
||||
O ecossistema Azteca adota o framework `.agent` como um **git submodule** polimórfico e agnóstico compartilhado entre múltiplos repositórios e produtos (identificados individualmente via `memorias-ia/modulo.yml`). Novas regras, personas, correções de ferramentas (como isolamento de sessão do `agent-browser`, Grafo de Conhecimento Graphify e upload MinIO Paiol), workflows e skills são continuamente aprimorados e versionados diretamente na branch `master` do repositório remoto:
|
||||
|
||||
```
|
||||
https://git2.idz.one/publico/.agent.git
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ description: Define limites de autonomia do agente — o que pode fazer sozinho,
|
|||
scope: global
|
||||
trigger: always_on
|
||||
priority: alta
|
||||
updatedAt: "2026-10-01"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Limites de Autonomia do Agente
|
||||
|
|
@ -18,18 +18,18 @@ O agente existe para **ampliar a capacidade humana**, não para substituir decis
|
|||
|
||||
O agente pode executar sem perguntar:
|
||||
|
||||
- Consultar `memorias-ia/modulo.yml` para obter identificador (`modulo-id`), rotas (`modulo-caminho`), descrição (`modulo-descricao`) e tipo (`modulo-tipo`)
|
||||
- Consultar `memorias-ia/modulo.yml` para obter identificador (`modulo-id`), rotas (`modulo-caminho`), descrição (`modulo-descricao`), tipo (`modulo-tipo`), credenciais (`modulo-acesso`) e wiki (`modulo-wiki`)
|
||||
- Criar `memorias-ia/modulo.yml` a partir do template quando inexistente em novo projeto
|
||||
- Corrigir erros de tipagem em arquivos que já está modificando
|
||||
- Aplicar formatação (`biome check --write`)
|
||||
- Atualizar referências quebradas entre artefatos
|
||||
- Criar ou atualizar documentação de regras de negócio em `<base_projeto>/../wiki/dev/<modulo-id>/`
|
||||
- Criar ou atualizar documentação de regras de negócio em `<modulo-wiki>/dev/<modulo-id>/`
|
||||
- Gerar JSDoc em funções compartilhadas
|
||||
- Extrair CSS para arquivo co-localizado
|
||||
- Aplicar padrões de nomenclatura já definidos em rules
|
||||
- Executar `git add`, `git commit`, `git push` e resolver conflitos diretamente na branch `master` no repositório da Wiki (`<base_projeto>/../wiki` ou `wiki/`) ao criar ou atualizar documentações
|
||||
- Executar `git commit` na aplicação principal em branches de trabalho (criando compulsoriamente uma nova branch caso o repositório esteja na `master`)
|
||||
- Sugerir o texto de mensagem de commit (padrão Conventional Commits) ao operador humano após concluir implementações ou documentações
|
||||
- Atualizar o submódulo `.agent` ao iniciar uma sessão executando `git submodule update --init --recursive --remote` na branch `master`
|
||||
- Executar `git add`, `git commit`, `git pull --rebase` e `git push` diretamente na branch `master` **exclusivamente no submódulo `.agent`** ao evoluir artefatos de IA
|
||||
|
||||
## Ações que Requerem Confirmação
|
||||
|
||||
|
|
@ -37,18 +37,17 @@ O agente deve **propor e aguardar aprovação**:
|
|||
|
||||
- Criar novas rules, workflows ou skills
|
||||
- Alterar mais de 5 arquivos em uma única operação
|
||||
- Remover ou renomear artefatos do `.agent/base/` (submodule herdado)
|
||||
- Remover ou renomear artefatos do `.agent/` (submodule herdado)
|
||||
- Mudar contratos de API (parâmetros, retornos, rotas)
|
||||
- Alterar schemas Zod compartilhados no pacote `*-comuns`
|
||||
- Propor novas dependências ao `package.json`
|
||||
- Mudar configurações de build, deploy ou CI/CD
|
||||
- Executar `git push` de novas branches criadas na aplicação principal
|
||||
|
||||
## Ações Proibidas
|
||||
|
||||
O agente **nunca** deve:
|
||||
|
||||
- Executar `git commit` ou `git push` diretamente na branch `master` (ou `main`) no repositório da aplicação principal
|
||||
- Executar `git commit` ou `git push` em qualquer branch do repositório da aplicação principal (`<base_projeto>`) ou da Wiki (`<modulo-wiki>`) — o commit é exclusivo do operador humano (a IA apenas sugere o texto do commit; apenas o submódulo `.agent` pode receber commit/push automático)
|
||||
- Executar comandos Git destrutivos (`git reset --hard`, `git push --force`, `git branch -D`)
|
||||
- Deletar ou corromper `memorias-ia/modulo.yml` ou memórias/ADRs sem instrução explícita do operador
|
||||
- Assumir ou inventar IDs de módulos ou rotas sem consultar `memorias-ia/modulo.yml`
|
||||
|
|
|
|||
114
global/rules/caminho-arquivos-minio.md
Normal file
114
global/rules/caminho-arquivos-minio.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
---
|
||||
type: rule
|
||||
name: caminho-arquivos-minio
|
||||
description: Padronização obrigatória de caminhos de arquivos persistidos no MinIO em quatro segmentos ({inquilino}/{tabela_origem}/{codigo_origem}/{id})
|
||||
scope: global
|
||||
trigger: model_decision
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Padronização Obrigatória de Caminhos de Arquivos no MinIO
|
||||
|
||||
## Contexto
|
||||
|
||||
Todos os arquivos persistidos e referenciados no MinIO dentro dos módulos do ecossistema (identificados via `modulo-id` em `memorias-ia/modulo.yml`) devem seguir uma estrutura canônica hierárquica e determinística composta por **exatamente quatro segmentos**:
|
||||
|
||||
```
|
||||
{inquilino}/{tabela_origem}/{codigo_origem}/{id}
|
||||
```
|
||||
|
||||
Essa padronização evita colisão de arquivos entre inquilinos ou entidades, permite identificação imediata da origem do arquivo e padroniza a gestão de permissões e storage.
|
||||
|
||||
---
|
||||
|
||||
## 1. Regra de Formato e Validação Canônica
|
||||
|
||||
Todo caminho de arquivo enviado para o MinIO deve ser construído via função canônica `caminhoMinio` exportada pelo pacote `<modulo>-comuns` (onde `<modulo>` é extraído de `memorias-ia/modulo.yml`) e validado por `regexCamninhoMinio`:
|
||||
|
||||
```typescript
|
||||
/** Valida quatro segmentos e exige extensão no id. */
|
||||
export const regexCamninhoMinio = /^[\w$.-]+\/\w+\/[\w.-]+\/[\w.%$-]+\.\w+$(?![\s\S])/
|
||||
|
||||
export type CaminhoMinioParams = {
|
||||
inquilino: string
|
||||
tabela_origem: string
|
||||
codigo_origem: string
|
||||
id: string
|
||||
}
|
||||
|
||||
export const caminhoMinio = ({
|
||||
inquilino,
|
||||
tabela_origem,
|
||||
codigo_origem,
|
||||
id,
|
||||
}: CaminhoMinioParams): string => {
|
||||
const partes = [inquilino, tabela_origem, codigo_origem, id]
|
||||
const caminho = partes.join("/")
|
||||
|
||||
if (partes.some((parte) => parte.includes("/")) || !regexCamninhoMinio.test(caminho)) {
|
||||
throw new Error("Caminho MinIO inválido")
|
||||
}
|
||||
|
||||
return caminho
|
||||
}
|
||||
```
|
||||
|
||||
### Regras dos Quatro Segmentos
|
||||
1. **`inquilino`**: Identificador do município / cliente / tenant (ex.: `padrao-rs`). Não pode conter barras.
|
||||
2. **`tabela_origem`**: Nome canônico da tabela no banco de dados (ex.: `tabelas.licenciamentos`, `tabelas.denuncias`, `tabelas.oficios`).
|
||||
3. **`codigo_origem`**: UUID ou identificador único do registro na tabela de origem (ou identificador de escopo como `sistema` para brasões/ativos globais do tenant).
|
||||
4. **`id`**: Identificador único do arquivo acompanhado obrigatoriamente de sua extensão (ex.: `01J...pdf`, `brasao.png`, `oficio_123.pdf`).
|
||||
|
||||
---
|
||||
|
||||
## 2. Persistência Obrigatória no Banco de Dados
|
||||
|
||||
É **mandatório** que toda coluna do banco de dados que armazena referências a arquivos salve a **string completa retornada por `caminhoMinio`** (os 4 segmentos unidos por barras).
|
||||
|
||||
Exemplos de colunas que armazenam o caminho completo:
|
||||
- `licencas.codigo_arquivo`
|
||||
- `anexos.codigo_arquivo`
|
||||
- `denuncias.codigo_pdf_documento`
|
||||
- `oficios.codigo_pdf_documento`
|
||||
- `documentos_registros.codigo_pdf_documento`
|
||||
- `auto_de_infracao.codigo_pdf_documento`
|
||||
- `fluxos_recebimentos.codigo_pdf_documento`
|
||||
- `entidades.prefeitura_brasao`
|
||||
|
||||
> ⚠️ **Atenção:** Nunca salve apenas o último segmento (`id`) de arquivos gerados ou anexados. A string armazenada no banco deve ser a chave completa de 4 segmentos.
|
||||
|
||||
---
|
||||
|
||||
## 3. Upload e Integração com Plugins MinIO
|
||||
|
||||
No backend (`<modulo>-back`):
|
||||
- O plugin `enviarArquivoMiniO` valida o `codigoArquivo` recebido contra `regexCamninhoMinio`.
|
||||
- Caso `codigoArquivo` já contenha barras, o plugin reconhece que o inquilino já está incorporado no primeiro segmento e faz o upload direto para essa chave, sem duplicar o prefixo do inquilino.
|
||||
- No download ou cache temporário (`baixarArquivoMiniO`), caso a chave possua barras, o nome do arquivo temporário local em disco deve substituir as barras por underscores (`replace(/\//g, "_")`) para evitar erros de diretórios inexistentes em `/tmp`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Miniaturas e Resoluções Gráficas
|
||||
|
||||
No caso de imagens que possuem geração de miniaturas (thumbnails via Sharp):
|
||||
- A miniatura adiciona o sufixo `_y{tamanho}` **antes da extensão no 4º segmento**:
|
||||
`{inquilino}/{tabela_origem}/{codigo_origem}/{id_base}_y200.{ext}`
|
||||
- No frontend (`<modulo>-front`), helpers como `urlArquivoBaixar` devem utilizar `lastIndexOf(".")` para formatar a URL da miniatura mantendo a hierarquia intacta.
|
||||
|
||||
---
|
||||
|
||||
## 5. Compatibilidade Legada
|
||||
|
||||
O helper `bucket().caminho` em `<modulo>-comuns` é retrocompatível:
|
||||
- Se `id` contém barras (`/`), ele já representa o caminho estruturado completo e é retornado sem alteração.
|
||||
- Se `id` não contém barras, ele trata como registro legado de 1 segmento e compõe `{inquilino}/{id}`.
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Identidade do Módulo: `memorias-ia/modulo.yml`
|
||||
- `<modulo>-comuns/src/minio.ts`
|
||||
- `<modulo>-back/src/plugins/MiniO/enviarArquivoMiniO.ts`
|
||||
- `<modulo>-back/src/plugins/MiniO/baixarArquivoMiniO.ts`
|
||||
- `<modulo>-front/src/api/recursos/arquivos.ts`
|
||||
|
|
@ -1,25 +1,24 @@
|
|||
---
|
||||
type: rule
|
||||
name: css-global-betha
|
||||
description: Define o padrão de CSS global com variáveis --bth-* para todos os frontends do ecossistema GOV (QUIPO-FRONT, QUIPO-PORTAL3, AUTENTICACAO-FRONT, QUIPO-CONSOLE)
|
||||
description: Define o padrão de CSS global com variáveis --bth-* para os frontends de gestão pública/governo do ecossistema
|
||||
scope: global
|
||||
trigger: model_decision
|
||||
priority: alta
|
||||
updatedAt: "2026-09-28"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: CSS Global Betha — Variáveis `--bth-*`
|
||||
|
||||
Todo frontend do ecossistema GOV deve possuir um arquivo CSS global com as variáveis `--bth-*` e reset visual Betha.
|
||||
Todo frontend de módulo voltado a governo/gestão pública (identificado via `modulo-id` e `modulo-tipo` em `memorias-ia/modulo.yml`) deve possuir um arquivo CSS global com as variáveis `--bth-*` e reset visual Betha.
|
||||
|
||||
## Localização por Frontend
|
||||
## Localização por Tipo de Frontend (`*-front`)
|
||||
|
||||
| Frontend | Arquivo | Importado em |
|
||||
|----------|---------|-------------|
|
||||
| QUIPO-FRONT | `src/styles/index.css` | `index.tsx` |
|
||||
| QUIPO-PORTAL3 | `src/styles/globals.css` | `layout.tsx` |
|
||||
| AUTENTICACAO-FRONT | `src/styles/global.css` | `App.tsx` |
|
||||
| QUIPO-CONSOLE | `src/styles/global.css` | `main.ts` |
|
||||
| Arquitetura do Pacote `<modulo>-front` | Arquivo CSS Global | Importado em |
|
||||
|----------------------------------------|--------------------|--------------|
|
||||
| SPA React / Vite | `src/styles/index.css` ou `src/styles/global.css` | `index.tsx` / `App.tsx` |
|
||||
| Next.js / Nuxt / SSR | `src/styles/globals.css` | `layout.tsx` / `app.vue` |
|
||||
| Vue 3 / Vite | `src/styles/global.css` | `main.ts` |
|
||||
|
||||
## Variáveis Obrigatórias
|
||||
|
||||
|
|
@ -76,8 +75,8 @@ body {
|
|||
|
||||
## Fonte Open Sans
|
||||
|
||||
- **QUIPO-PORTAL3:** usa `@fontsource/open-sans` (npm package) — sem request externo
|
||||
- **Outros frontends:** importar via `<link>` no `index.html`:
|
||||
- **Via pacote NPM (recomendado sem request externo):** `@fontsource/open-sans`
|
||||
- **Ou via `<link>` no `index.html`:**
|
||||
|
||||
```html
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||||
|
|
@ -94,8 +93,9 @@ body {
|
|||
|
||||
## Impacto
|
||||
|
||||
Garante consistência visual entre todos os frontends e facilita troca de tema — alterar uma variável reflete em todo o sistema.
|
||||
Garante consistência visual entre todos os frontends do módulo e facilita troca de tema — alterar uma variável reflete em todo o sistema.
|
||||
|
||||
## Referências
|
||||
|
||||
- Identidade do Módulo: `memorias-ia/modulo.yml`
|
||||
- Rule: `estilos-design-system`
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ description: Regra global de Documentation-Driven Development (DDD) definindo os
|
|||
scope: global
|
||||
trigger: always_on
|
||||
priority: alta
|
||||
updatedAt: "2026-09-01"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Documentação Obrigatória Antes da Implementação (DDD)
|
||||
|
|
@ -31,13 +31,13 @@ Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeit
|
|||
| **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** | `<base_projeto>/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 (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`)**:
|
||||
> ℹ️ **Estrutura da Wiki VitePress (`<modulo-wiki>`, padrão: `../wiki/`)**:
|
||||
> - `<modulo-wiki>/<modulo-id>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `<modulo-id>` e `<modulo-wiki>` são extraídos de `memorias-ia/modulo.yml`, com fallback padrão para `../wiki/`).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/` $\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`, `modulo-acesso`, `modulo-wiki`). Sempre consultado quando precisar de IDs, rotas base, credenciais de teste 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, wiki ou stack.
|
||||
> - `./memorias-ia/`: Registros individuais `sessao-AAAA-MM-DD-slug.md` e índice cumulativo `historico-acoes.md`.
|
||||
> - `<modulo-wiki>/<modulo-id>/`: Documentação do módulo com acesso dos usuários (VitePress).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
|
||||
|
|
@ -76,8 +76,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 `<modulo-wiki>/<modulo>/` (Pilar 3).
|
||||
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `<modulo-wiki>/dev/<modulo>/` (Pilar 4).
|
||||
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `<modulo-wiki>/<modulo-id>/` (Pilar 3).
|
||||
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `<modulo-wiki>/dev/<modulo-id>/` (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/sessao-AAAA-MM-DD-slug.md` e indexar em `historico-acoes.md` (Pilar 6).
|
||||
|
||||
|
|
@ -108,14 +108,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 `<base_projeto>/../wiki/dev/e-licencie.sigma/` e o guia de uso em `<base_projeto>/../wiki/e-licencie.sigma/`.
|
||||
- Criou um serviço de cálculo no módulo $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `<modulo-wiki>/dev/<modulo-id>/` e o guia de uso em `<modulo-wiki>/<modulo-id>/`.
|
||||
- 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 `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
- Criou regras técnicas complexas sem atualizar `<modulo-wiki>/dev/<modulo-id>/`.
|
||||
- Gravou registros de ações da IA em pastas despadronizadas fora de `<base_projeto>/memorias-ia/`.
|
||||
|
||||
---
|
||||
|
|
@ -123,5 +123,5 @@ A etapa de documentação prévia pode ser simplificada apenas para:
|
|||
## Referências
|
||||
|
||||
- `DOCUMENTACAO/README` (Manifesto DDD e matriz de documentação)
|
||||
- Rules: `jsdoc-padrao.md`, `regras-negocio-md.md`, `autonomia-agente.md`
|
||||
- Rules: `jsdoc-padrao.md`, `regras-negocio-md.md`, `autonomia-agente.md`, `identidade-modulo.md`
|
||||
- Skills: `adicionar-ajuda`, `documentar-dominio-modulo`, `documentar-decisao-tecnica`, `diagnosticar-lacunas-documentacao`
|
||||
|
|
|
|||
|
|
@ -1,21 +1,17 @@
|
|||
---
|
||||
type: rule
|
||||
name: drive-entidades-internas
|
||||
description: Consultar entidades do e-licencie (empreendedor, empreendimento, usuário) via eLicencieDrive com token interno
|
||||
description: Consultar entidades compartilhadas (empreendedor, empreendimento, usuário) via Drive SSO com token interno
|
||||
scope: local
|
||||
trigger: model_decision
|
||||
updatedAt: "2026-09-28"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Consultar Entidades do e-licencie via Drive Interno
|
||||
# Regra: Consultar Entidades Compartilhadas via Drive Interno
|
||||
|
||||
## Contexto
|
||||
|
||||
Dentro de `sigma-back/src/INFO/` e `sigma-back/src/_FILAS/`, quando um gerador de info
|
||||
ou um worker de fila precisa dos dados de **empreendedor**, **empreendimento** ou
|
||||
**usuário**, esses dados **não existem localmente no banco do SIGMA** — eles vivem no
|
||||
e-licencie. A consulta deve ser feita via `eLicencieDrive` com token interno,
|
||||
nunca retornando campos em branco (`nome: ""`, `documento: ""`).
|
||||
Nos módulos do ecossistema (identificados em `memorias-ia/modulo.yml`), dentro de `<modulo>-back/src/INFO/` e `<modulo>-back/src/_FILAS/`, quando um gerador de info ou um worker de fila precisa dos dados de **empreendedor**, **empreendimento** ou **usuário** providos via SSO/Drive, esses dados **não existem localmente no banco do módulo** — eles vivem no serviço centralizado de diretório/SSO (`eLicencieDrive`). A consulta deve ser feita via `eLicencieDrive` com token interno, nunca retornando campos em branco (`nome: ""`, `documento: ""`).
|
||||
|
||||
## Regra
|
||||
|
||||
|
|
@ -34,7 +30,7 @@ const drive = eLicencieDrive({ token: montarTokenInterno({ inquilino }) })
|
|||
### 2. Preferir os helpers de `cacheEntidadesDrive`
|
||||
|
||||
Para buscas pontuais por código, usar os helpers prontos de
|
||||
`sigma-back/src/e-licencie-drive/cacheEntidadesDrive.ts`:
|
||||
`<modulo>-back/src/e-licencie-drive/cacheEntidadesDrive.ts`:
|
||||
|
||||
```ts
|
||||
import {
|
||||
|
|
@ -143,10 +139,10 @@ const resultado = await drive.listarEmpreendedores()
|
|||
|
||||
| Arquivo | Papel |
|
||||
|---|---|
|
||||
| `sigma-back/src/plugins/e-licencie-drive.ts` | Ponto único de importação do drive + `montarTokenInterno` |
|
||||
| `sigma-back/src/e-licencie-drive/cacheEntidadesDrive.ts` | Helpers: `obterEmpreendedorPorCodigo`, `obterEmpreendimentoPorCodigo`, `obterUsuarioPorCodigo` |
|
||||
| `sigma-back/src/INFO/tipagem.ts` | Define `tipoGeradorInfo<T>` com `{ objeto, schema, inquilino }` |
|
||||
| `sigma-back/src/INFO/index.ts` | `gravarInfo` — repassa `inquilino` para cada gerador |
|
||||
| `<modulo>-back/src/plugins/e-licencie-drive.ts` | Ponto único de importação do drive + `montarTokenInterno` |
|
||||
| `<modulo>-back/src/e-licencie-drive/cacheEntidadesDrive.ts` | Helpers: `obterEmpreendedorPorCodigo`, `obterEmpreendimentoPorCodigo`, `obterUsuarioPorCodigo` |
|
||||
| `<modulo>-back/src/INFO/tipagem.ts` | Define `tipoGeradorInfo<T>` com `{ objeto, schema, inquilino }` |
|
||||
| `<modulo>-back/src/INFO/index.ts` | `gravarInfo` — repassa `inquilino` para cada gerador |
|
||||
|
||||
## Impacto
|
||||
|
||||
|
|
|
|||
|
|
@ -1,23 +1,23 @@
|
|||
---
|
||||
type: rule
|
||||
name: estilos-design-system
|
||||
description: Define os dois design systems do ecossistema e-licencie — Floreta (iniciativa privada) e Betha (governo) — e quando usar cada um
|
||||
description: Define os dois design systems do ecossistema — Floreta (iniciativa privada) e Betha (governo/setor público) — parametrizados via memorias-ia/modulo.yml
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-09-28"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Estilos e Design Systems do Ecossistema
|
||||
|
||||
O ecossistema e-licencie opera com **dois design systems distintos**, selecionados conforme o público-alvo da aplicação.
|
||||
O ecossistema Azteca opera com **dois design systems distintos**, selecionados conforme o público-alvo e a definição em `memorias-ia/modulo.yml` (`modulo-id`, `modulo-descricao` e `modulo-tipo`).
|
||||
|
||||
## 1. Estilo Floreta — Iniciativa Privada
|
||||
|
||||
Usado em: `e-licencie`, `e-licencie.qualifica`, `e-licencie.gee` e todos os módulos voltados a empresas privadas.
|
||||
Usado nos módulos voltados a empresas privadas e gestão corporativa.
|
||||
|
||||
### Características
|
||||
|
||||
- **Framework UI:** Vuetify (Vue 3)
|
||||
- **Framework UI:** Vuetify (Vue 3) / `eli-vue`
|
||||
- **Cores:** paleta própria definida no tema Vuetify do projeto
|
||||
- **Tipografia:** controlada pelo tema Vuetify
|
||||
- **Componentes:** componentes Vuetify (`v-btn`, `v-card`, `v-data-table`, etc.)
|
||||
|
|
@ -25,14 +25,14 @@ Usado em: `e-licencie`, `e-licencie.qualifica`, `e-licencie.gee` e todos os mód
|
|||
|
||||
### Quando aplicar
|
||||
|
||||
- Todo código em pacotes `*-front` dos produtos e-licencie voltados ao mercado privado
|
||||
- Landing pages e painéis públicos de empresas
|
||||
- Todo código em pacotes `<modulo>-front` de módulos voltados ao setor privado (conforme descrito em `memorias-ia/modulo.yml`)
|
||||
- Landing pages e painéis públicos corporativos
|
||||
|
||||
---
|
||||
|
||||
## 2. Estilo Betha — Governo / Setor Público
|
||||
|
||||
Usado em: aplicações integradas à plataforma Betha (gestão municipal, e-Gov).
|
||||
Usado em módulos voltados a órgãos governamentais, gestão municipal e e-Gov (conforme identificado em `memorias-ia/modulo.yml`).
|
||||
|
||||
**Documentação oficial:** https://design.plataforma.betha.cloud/doc/index.html
|
||||
|
||||
|
|
@ -56,8 +56,8 @@ Usado em: aplicações integradas à plataforma Betha (gestão municipal, e-Gov)
|
|||
- Light (mais clara): sufixos `--l10`, `--l20`, `--l30`, `--l40`
|
||||
- Exemplo: `.bg__blue--d20`, `.tx__red--l30`
|
||||
|
||||
**Cores de produtos Betha:**
|
||||
| Produto | Hex |
|
||||
**Cores de linhas de produto:**
|
||||
| Linha de Produto | Hex |
|
||||
|--------------------------------------|-----------|
|
||||
| Gestão Municipal | `#9A8B7D` |
|
||||
| Planejamento e Contabilidade | `#A6B8FF` |
|
||||
|
|
@ -104,15 +104,9 @@ Usado em: aplicações integradas à plataforma Betha (gestão municipal, e-Gov)
|
|||
<script src="https://cdn.betha.cloud/base/g4/design/4.0.0/bth-design.js"></script>
|
||||
```
|
||||
|
||||
### Quando aplicar
|
||||
### Tokens para Frontends `<modulo>-front` (React/MUI e Vue 3/Vuetify)
|
||||
|
||||
- Módulos integrados à plataforma Betha de gestão municipal
|
||||
- Interfaces que operam dentro do ecossistema e-Gov Betha
|
||||
- Aplicações web com `body class="suite-pla iv"`
|
||||
|
||||
### Tokens Reais — Ecossistema GOV (React/MUI)
|
||||
|
||||
Os frontends React (QUIPO-FRONT, QUIPO-PORTAL3, AUTENTICACAO-FRONT) usam estes tokens via MUI ThemeProvider:
|
||||
Nos módulos governamentais (`memorias-ia/modulo.yml`), os pacotes `<modulo>-front` utilizam estes tokens:
|
||||
|
||||
| Token | Hex | Uso |
|
||||
|-------|-----|-----|
|
||||
|
|
@ -129,15 +123,13 @@ Os frontends React (QUIPO-FRONT, QUIPO-PORTAL3, AUTENTICACAO-FRONT) usam estes t
|
|||
| danger | `#dc3545` | erro/exclusão |
|
||||
| warning | `#ffc107` | alerta |
|
||||
| info | `#17a2b8` | informação |
|
||||
| e-licencie primary | `#688c00` | substituição de primary quando marca e-licencie ativa |
|
||||
| white-label primary alternativo | `#688c00` | substituição de primary quando marca alternativa ativa |
|
||||
|
||||
**Seleção de itens (cartões interativos):**
|
||||
- Selecionado: `#cce5ff` / hover: `#b8daff`
|
||||
- Não selecionado: `#f8f9fa` / hover: `#e9ecef`
|
||||
|
||||
### Vue 3 + Vuetify — QUIPO-CONSOLE
|
||||
|
||||
O QUIPO-CONSOLE usa Vue 3 + Vuetify 3. Configuração do tema em `src/plugins/vuetify.ts`:
|
||||
### Configuração Vue 3 + Vuetify (`src/plugins/vuetify.ts` em `<modulo>-front`)
|
||||
|
||||
```typescript
|
||||
theme: {
|
||||
|
|
@ -165,9 +157,9 @@ theme: {
|
|||
|
||||
---
|
||||
|
||||
## 3. Branding Dinâmico — eBetha() nos Footers
|
||||
## 3. Branding Dinâmico — `eBetha()` nos Footers
|
||||
|
||||
Todos os footers do ecossistema usam a função `eBetha()` para determinar a identidade da empresa exibida:
|
||||
Quando o módulo suporta white-label dinâmico, os footers de `<modulo>-front` utilizam a função `eBetha()` para determinar a identidade exibida:
|
||||
|
||||
```typescript
|
||||
import { eBetha } from "p-ambiente";
|
||||
|
|
@ -176,27 +168,20 @@ import { eBetha } from "p-ambiente";
|
|||
// eBetha() == false → Azteca Software LTDA, CNPJ 29.979.144/0001-13, Içara-SC
|
||||
```
|
||||
|
||||
**Arquivos de footer por frontend:**
|
||||
|
||||
| Frontend | Arquivo |
|
||||
|----------|---------|
|
||||
| QUIPO-FRONT | `src/components/Footer.tsx` e `src/pages/Portal/PortalFooter.tsx` |
|
||||
| QUIPO-PORTAL3 | `src/components/Footer/Footer.tsx` |
|
||||
| AUTENTICACAO-FRONT | sem footer próprio |
|
||||
|
||||
- O footer exibe sempre a versão da API e do frontend
|
||||
- O logotipo é condicional: logotipo diferente por marca
|
||||
- O logotipo é condicional conforme a marca ativa
|
||||
|
||||
---
|
||||
|
||||
## Decisão: Como identificar qual estilo usar
|
||||
|
||||
1. **Pergunte o contexto:** se o operador não especificar, pergunte se o módulo é para iniciativa privada (Floreta/Vuetify) ou governo (Betha)
|
||||
2. **Nunca misture:** um módulo usa UM estilo — nunca combine Vuetify com Betha Design
|
||||
3. **Header identifica:** header `#343a40` com logo = Betha; barra lateral com menu Vuetify customizado = Floreta
|
||||
1. **Consultar `memorias-ia/modulo.yml`:** verificar `modulo-id`, `modulo-descricao` e `modulo-tipo` para identificar se o projeto é privado (Floreta/Vuetify) ou governamental (Betha)
|
||||
2. **Nunca misturar:** um módulo usa UM estilo — nunca combinar ambos na mesma tela
|
||||
3. **Header identifica:** header `#343a40` = padrão governamental/Betha; barra lateral com menu Vuetify customizado = padrão privado/Floreta
|
||||
|
||||
## Referências
|
||||
|
||||
- Identidade do Módulo: `memorias-ia/modulo.yml`
|
||||
- Betha Design System: https://design.plataforma.betha.cloud/doc/index.html
|
||||
- Framework Design CDN: https://cdn.betha.cloud/base/g4/design/4.0.0/
|
||||
- Rule: `css-global-betha` (variáveis --bth-*)
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ description: Identificação obrigatória do projeto/módulo via memorias-ia/mod
|
|||
scope: global
|
||||
trigger: always_on
|
||||
priority: critica
|
||||
updatedAt: "2026-10-08"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Identidade do Projeto via `memorias-ia/modulo.yml`
|
||||
|
|
@ -65,12 +65,12 @@ modulo-wiki: <caminho-da-wiki>
|
|||
|
||||
| Campo | Tipo | Descrição | Exemplo |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e prefixo da sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `e-licencie.sigma` |
|
||||
| **`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-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e prefixo da sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `nome-do-modulo` |
|
||||
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/modulo/` ou `/` |
|
||||
| **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão operacional e ambiental` |
|
||||
| **`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`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@gov.br", senha: "123" }` ou subchaves de contexto |
|
||||
| **`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` |
|
||||
| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@exemplo.com", senha: "123" }` ou subchaves de contexto |
|
||||
| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `../wiki` ou `./WIKI` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -81,7 +81,7 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
|
|||
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>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 as credenciais do contexto específico (`interno`, `externo`, `cliente`, etc.) ou credenciais diretas de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística sem contaminação de cookies/tokens entre perfis;
|
||||
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;
|
||||
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou escrita na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
|
||||
6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`.
|
||||
|
||||
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
---
|
||||
type: rule
|
||||
name: modal-dialog-padrao-betha
|
||||
description: Define a estrutura obrigatória de modais e dialogs MUI no padrão Betha — header escuro, body branco, footer cinza — para os frontends React do ecossistema GOV
|
||||
description: Define a estrutura obrigatória de modais e dialogs MUI no padrão Betha — header escuro, body branco, footer cinza — para frontends React de gestão pública
|
||||
scope: global
|
||||
trigger: model_decision
|
||||
priority: alta
|
||||
updatedAt: "2026-09-28"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Padrão Modal/Dialog MUI — Estrutura Betha
|
||||
|
||||
Todo modal/dialog nos frontends React do ecossistema GOV deve seguir a estrutura visual Betha: **header escuro + body branco + footer cinza**.
|
||||
Nos projetos cujo `memorias-ia/modulo.yml` indica frontend React/MUI com estilo governamental/Betha, todo modal/dialog em `<modulo>-front` deve seguir a estrutura visual Betha: **header escuro + body branco + footer cinza**.
|
||||
|
||||
## Estrutura Obrigatória
|
||||
|
||||
|
|
@ -97,9 +97,10 @@ Todo modal/dialog nos frontends React do ecossistema GOV deve seguir a estrutura
|
|||
|
||||
## Impacto
|
||||
|
||||
Evita modais com aparências inconsistentes entre telas e garante conformidade com a identidade visual Betha exigida pelo parceiro.
|
||||
Evita modais com aparências inconsistentes entre telas e garante conformidade com a identidade visual exigida.
|
||||
|
||||
## Referências
|
||||
|
||||
- Identidade do Módulo: `memorias-ia/modulo.yml`
|
||||
- Rule: `theme-provider-mui-betha`
|
||||
- Rule: `estilos-design-system`
|
||||
|
|
|
|||
|
|
@ -1,76 +1,40 @@
|
|||
---
|
||||
type: rule
|
||||
name: proibido-commit-ia
|
||||
description: Condições de commit pela IA (proibido comitar na master na aplicação; deve criar nova branch se em master); na Wiki (../wiki), commit, push e resolução de conflitos são permitidos direto na master
|
||||
description: Proíbe a IA de executar git commit ou git push na aplicação principal e na Wiki (commit exclusivo por humano; IA apenas sugere o texto do commit). Apenas o submódulo .agent pode receber commit/push automático.
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-10-01"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Diretrizes de Versionamento Git — Commit Condicional na Aplicação e Gestão Direta em Master na Wiki
|
||||
# Regra: Diretrizes de Versionamento Git — Commit Exclusivo por Humano (IA Apenas Sugere Texto) e Push Automático Apenas no `.agent`
|
||||
|
||||
## Contexto
|
||||
|
||||
O ecossistema adota uma política de versionamento clara e segura que equilibra agilidade na documentação com proteção do código produtivo:
|
||||
O ecossistema adota uma política de versionamento estrita onde o controle de histórico dos projetos pertence exclusivamente ao operador humano:
|
||||
|
||||
1. **Aplicação Principal (`<base_projeto>`)**: A IA pode comitar alterações, com a salvaguarda estrita e inegociável de **NUNCA comitar diretamente na branch `master` (ou `main`)**. Estando em `master`, a IA deve compulsoriamente criar e alternar para uma nova branch de trabalho antes de realizar qualquer commit.
|
||||
2. **Repositório da Wiki (`<base_projeto>/../wiki` ou `wiki/`)**: Hospeda a base viva de documentação (Pilares 3 e 4). Na Wiki, a IA possui autonomia total para executar `git commit`, `git push` e resolver eventuais conflitos de sincronização diretamente na branch `master`.
|
||||
1. **Aplicação Principal (`<base_projeto>`) e Repositório da Wiki (`<modulo-wiki>`, padrão `../wiki/`)**: É **terminantemente proibido** à IA executar `git commit`, `git push` ou criar branches para comitar. O commit deve ser realizado **apenas por um humano**, cabendo à IA **apenas sugerir o texto da mensagem de commit** (no padrão Conventional Commits) ao concluir suas alterações.
|
||||
2. **Submódulo `.agent` (`<base_projeto>/.agent`)**: É o **único** repositório onde a IA possui permissão para executar `git add`, `git commit`, `git pull --rebase origin master` e `git push origin master` de forma automática quando artefatos de IA são atualizados.
|
||||
|
||||
---
|
||||
|
||||
## Regra
|
||||
|
||||
### 1. Na Aplicação Principal (`<base_projeto>`) — COMMIT CONDICIONAL E SALVAGUARDA DE MASTER
|
||||
### 1. Na Aplicação Principal (`<base_projeto>`) e na Wiki (`<modulo-wiki>`) — COMMIT EXCLUSIVO POR HUMANO (IA APENAS SUGERE TEXTO)
|
||||
|
||||
A IA **PODE** realizar commits na aplicação principal, **ESTRITAMENTE CONDICIONADA** às regras:
|
||||
|
||||
1. **NUNCA comitar diretamente na branch `master`**: É expressamente proibido rodar `git commit` quando a branch atual for `master` (ou `main`).
|
||||
2. **Criação obrigatória de nova branch se estiver em `master`**:
|
||||
Antes de qualquer commit, a IA deve inspecionar a branch atual:
|
||||
```bash
|
||||
BRANCH_ATUAL=$(git branch --show-current)
|
||||
```
|
||||
Se `BRANCH_ATUAL` for `master` ou `main`, a IA **DEVE** criar e alternar para uma nova branch semântica:
|
||||
```bash
|
||||
git checkout -b <tipo>/<descricao-curta>
|
||||
```
|
||||
Padrão de nomenclatura:
|
||||
- `feat/<slug>`: novas funcionalidades
|
||||
- `fix/<slug>`: correções de bugs
|
||||
- `refactor/<slug>`: refatorações de código
|
||||
- `docs/<slug>`: documentações técnicas no código
|
||||
- `ia/<slug>`: planos e tarefas automatizadas de IA
|
||||
|
||||
3. **Commit em branch de trabalho**: Se o repositório já estiver em uma branch que NÃO seja `master`/`main`, a IA pode comitar diretamente nessa branch.
|
||||
4. **Mensagens semânticas**: Usar o padrão Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`).
|
||||
5. **Comandos PROIBIDOS na aplicação principal**:
|
||||
- `git commit` diretamente na branch `master` ou `main` ❌
|
||||
- `git push` direto na branch `master` ou `main` ❌
|
||||
- `git push --force` ou `git push -f` ❌
|
||||
- `git reset --hard` sem autorização explícita ❌
|
||||
- `git branch -D` ❌
|
||||
- `git stash drop` ❌
|
||||
|
||||
---
|
||||
|
||||
### 2. No Repositório da Wiki (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER
|
||||
|
||||
Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modulo.yml`, com fallback mandatório para `<base_projeto>/../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
|
||||
# <modulo-wiki> extraído de memorias-ia/modulo.yml (fallback padrão: ../wiki)
|
||||
git -C <modulo-wiki> add -A
|
||||
git -C <modulo-wiki> commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
|
||||
git -C <modulo-wiki> 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 <modulo-wiki> 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 <modulo-wiki> add -A`), finaliza o rebase (`git -C <modulo-wiki> rebase --continue` ou commit) e envia com `git push origin master`.
|
||||
A IA **NUNCA** deve executar commits ou pushes na aplicação principal ou na Wiki:
|
||||
|
||||
1. **Proibição Absoluta de Commit e Push pela IA**:
|
||||
- É expressamente proibido rodar `git commit` ou `git push` em qualquer branch da aplicação principal (`<base_projeto>`) ou do repositório da Wiki (`<modulo-wiki>`).
|
||||
- A IA não deve criar branches (`git checkout -b`) com a finalidade de comitar alterações automaticamente.
|
||||
2. **Obrigação de Sugerir o Texto do Commit**:
|
||||
- Ao finalizar qualquer implementação, correção, refatoração ou documentação, a IA **DEVE** apresentar ao operador humano uma **Sugestão de Mensagem de Commit** seguindo o padrão Conventional Commits:
|
||||
- `feat(<escopo>): <descrição sucinta>` — novas funcionalidades
|
||||
- `fix(<escopo>): <descrição sucinta>` — correções de bugs
|
||||
- `refactor(<escopo>): <descrição sucinta>` — refatorações de código
|
||||
- `docs(<modulo-id>): <descrição sucinta>` — criações ou atualizações de documentação (código ou Wiki)
|
||||
- `test(<escopo>): <descrição sucinta>` — adição ou ajuste de testes
|
||||
- `chore(<escopo>): <descrição sucinta>` — manutenção e configurações
|
||||
3. **Proibição de Binários Pesados no Git da Wiki (Usar MinIO Paiol)**:
|
||||
- É expressamente proibido versionar no Git da Wiki arquivos binários ou mídias pesadas (manuais em `.pdf`, vídeos `.mp4`/`.webm`, imagens pesadas, pacotes `.zip`).
|
||||
- Todo arquivo estático da Wiki DEVE ser enviado ao MinIO Paiol:
|
||||
|
|
@ -78,50 +42,61 @@ Na Wiki (caminho resolvido dinamicamente via `modulo-wiki` em `memorias-ia/modul
|
|||
./.agent/scripts/upload-paiol-wiki.sh <arquivo> <funcionalidade/pagina>
|
||||
```
|
||||
ou via `curl -X PUT --upload-file ... https://paiol.idz.one/wiki/{modulo}/{slug}-{aleatorio}.{ext}`.
|
||||
- Apenas o arquivo Markdown contendo a URL pública gerada deve ser commitado no repositório.
|
||||
- Apenas o arquivo Markdown contendo a URL pública gerada deve permanecer no repositório para que o humano realize o commit.
|
||||
4. **Comandos PROIBIDOS na aplicação principal e na Wiki**:
|
||||
- `git commit` (em qualquer branch) ❌
|
||||
- `git push` (em qualquer branch) ❌
|
||||
- `git push --force` ou `git push -f` ❌
|
||||
- `git reset --hard` sem autorização explícita ❌
|
||||
- `git branch -D` ❌
|
||||
- `git stash drop` ❌
|
||||
|
||||
---
|
||||
|
||||
### 2. No Submódulo `.agent` (`<base_projeto>/.agent`) — ÚNICO COM COMMIT E PUSH AUTOMÁTICO PERMITIDO
|
||||
|
||||
Exclusivamente quando houver evolução de regras, skills, workflows, scripts ou personas dentro do submódulo `.agent`, a IA está autorizada a versionar e publicar automaticamente na branch `master` do `.agent`:
|
||||
|
||||
```bash
|
||||
git -C .agent add -A
|
||||
git -C .agent commit -m "chore(agent): <descrição sucinta da evolução>"
|
||||
git -C .agent pull --rebase origin master
|
||||
git -C .agent push origin master
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemplos
|
||||
|
||||
### ❌ Errado — comitar diretamente na branch master da aplicação
|
||||
### ❌ Errado — IA executando commit na aplicação ou na Wiki
|
||||
```bash
|
||||
# Branch atual: master
|
||||
git add src/servicos/auth.ts
|
||||
git commit -m "fix: ajustar token de auth" # PROIBIDO EM MASTER!
|
||||
git commit -m "fix(auth): ajustar renovação de token" # PROIBIDO! Apenas humano faz commit.
|
||||
```
|
||||
|
||||
### ✅ Correto — ramificar antes de comitar se estiver em master
|
||||
```bash
|
||||
# Branch atual: master
|
||||
git checkout -b fix/ajuste-token-auth
|
||||
git add src/servicos/auth.ts
|
||||
git commit -m "fix(auth): ajustar renovação de token"
|
||||
# Notificar o operador: "Commit realizado na branch fix/ajuste-token-auth"
|
||||
### ✅ Correto — IA finaliza a alteração e apenas sugere o texto do commit ao humano
|
||||
```markdown
|
||||
Alterações concluídas e validadas.
|
||||
|
||||
💬 **Sugestão de Commit (Aplicação):**
|
||||
`fix(auth): ajustar renovação de token expirado`
|
||||
```
|
||||
|
||||
### ✅ Correto — comitar em branch secundária já existente
|
||||
```bash
|
||||
# Branch atual: feat/novo-painel (diferente de master)
|
||||
git add src/paginas/Painel.vue
|
||||
git commit -m "feat(painel): adicionar gráfico de métricas"
|
||||
```
|
||||
### ✅ Correto — IA atualiza a Wiki e sugere o texto do commit ao humano
|
||||
```markdown
|
||||
Documentação atualizada em `<modulo-wiki>/dev/<modulo-id>/`.
|
||||
|
||||
### ✅ Correto — ciclo completo na Wiki direto na master
|
||||
```bash
|
||||
git -C ../wiki add -A
|
||||
git -C ../wiki commit -m "docs(quipo): atualizar manual de licenciamento"
|
||||
git -C ../wiki pull --rebase origin master # Se houver conflitos, resolve e prossegue
|
||||
git -C ../wiki push origin master
|
||||
💬 **Sugestão de Commit (Wiki):**
|
||||
`docs(<modulo-id>): atualizar manual operacional e regras de negócio`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impacto
|
||||
|
||||
- **Segurança da Master**: A branch principal de produção fica totalmente protegida contra commits acidentais.
|
||||
- **Rastreabilidade e Revisão**: Todas as alterações da IA na aplicação ficam isoladas em branches específicas, facilitando Pull Requests e revisões do operador.
|
||||
- **Agilidade na Wiki**: A documentação viva nunca fica travada por divergências ou bloqueios manuais.
|
||||
- **Controle Humano Total**: Nenhum commit ou push entra no histórico da aplicação ou da Wiki sem revisão e ação direta do operador humano.
|
||||
- **Padronização Semântica**: O operador recebe sempre uma sugestão de mensagem clara e pronta para uso no formato Conventional Commits.
|
||||
- **Evolução Contínua do `.agent`**: O submódulo `.agent` permanece sincronizado na `master` quando aprimorado.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -129,5 +104,6 @@ git -C ../wiki push origin master
|
|||
|
||||
- Rule: `rules/autonomia-agente.md`
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/identidade-modulo.md`
|
||||
- Skill: `skills/documentacao/SKILL.md`
|
||||
- Skill: `skills/plano.executar/SKILL.md`
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ Se não há testes cobrindo o trecho:
|
|||
2. Executar testes → todos passam
|
||||
3. Extrair cálculo de multa para `calcularMulta()`
|
||||
4. Executar testes → todos passam
|
||||
5. Commit: "refactor: extrair calcularMulta de calcularLicenca"
|
||||
5. Sugerir commit ao humano: "refactor: extrair calcularMulta de calcularLicenca"
|
||||
```
|
||||
|
||||
### ❌ Incorreto
|
||||
|
|
@ -43,7 +43,7 @@ Se não há testes cobrindo o trecho:
|
|||
1. Refatorar `calcularLicenca()` inteiro
|
||||
2. Adicionar nova regra de desconto (feature!)
|
||||
3. Descobrir que não tinha testes
|
||||
4. Commit: "refactor: melhorar cálculos" ← mentira, é feature + refatoração
|
||||
4. Sugerir commit: "refactor: melhorar cálculos" ← mentira, é feature + refatoração
|
||||
```
|
||||
|
||||
## Impacto
|
||||
|
|
|
|||
|
|
@ -1,24 +1,24 @@
|
|||
---
|
||||
type: rule
|
||||
name: regras-negocio-md
|
||||
description: O conteúdo de regras de negócio deve ficar em <base_projeto>/../wiki/dev/<modulo>/.
|
||||
description: O conteúdo de regras de negócio deve ficar em <modulo-wiki>/dev/<modulo-id>/ (resolvido via memorias-ia/modulo.yml).
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-09-01"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Conteúdo de Regras de Negócio em `<modulo-wiki>/dev/<modulo>/`
|
||||
# Regra: Conteúdo de Regras de Negócio em `<modulo-wiki>/dev/<modulo-id>/`
|
||||
|
||||
> **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 `<modulo-wiki>/dev/<modulo>/`.
|
||||
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 `<modulo-wiki>/dev/<modulo-id>/`.
|
||||
|
||||
> 💡 **Aplicação VitePress (`<modulo-wiki>`, padrão: `<base_projeto>/../wiki`) e Resolução do Módulo**:
|
||||
> 💡 **Aplicação VitePress (`<modulo-wiki>`, padrão: `../wiki/`) e Resolução do Módulo**:
|
||||
> - O caminho da Wiki `<modulo-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, `<modulo-wiki>/<modulo-id>/` é voltado ao acesso dos **usuários**, e `<modulo-wiki>/dev/<modulo-id>/` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**.
|
||||
> - O identificador `<modulo-id>` (ou `<modulo>`) **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`).
|
||||
> - O identificador `<modulo-id>` (ou `<modulo>`) **DEVE** ser obtido obrigatoriamente do campo `modulo-id` em `memorias-ia/modulo.yml` na raiz do projeto.
|
||||
|
||||
Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.
|
||||
|
||||
|
|
@ -26,8 +26,7 @@ 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 `<modulo-wiki>/dev/<modulo>/`.**
|
||||
|
||||
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `<modulo-wiki>/dev/<modulo-id>/`.**
|
||||
|
||||
Considera-se lógica não-trivial qualquer módulo que:
|
||||
- Possui 3 ou mais critérios de decisão distintos
|
||||
|
|
@ -39,7 +38,7 @@ Considera-se lógica não-trivial qualquer módulo que:
|
|||
O módulo TypeScript deve conter, na primeira linha útil do arquivo, a referência:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver <modulo-wiki>/dev/<modulo-id>/{servico}.regras-negocio.md
|
||||
```
|
||||
|
||||
A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógica operacional**. Os comentários JSDoc no código explicam a aplicação prática da função e apontam para a wiki para o detalhamento dos critérios.
|
||||
|
|
@ -48,7 +47,7 @@ A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógi
|
|||
|
||||
## Estrutura do Documento de Regras na Wiki de Desenvolvimento
|
||||
|
||||
**Localização:** `<base_projeto>/../wiki/dev/<modulo>/` (ex.: `<base_projeto>/../wiki/dev/e-licencie.sigma/regras-negocio/` ou `<base_projeto>/../wiki/dev/e-licencie.sigma/{modulo}.regras-negocio.md`)
|
||||
**Localização:** `<modulo-wiki>/dev/<modulo-id>/` (ex.: `<modulo-wiki>/dev/<modulo-id>/regras-negocio/` ou `<modulo-wiki>/dev/<modulo-id>/{servico}.regras-negocio.md`)
|
||||
|
||||
```markdown
|
||||
# Regras de Negócio — [Nome do Módulo / Serviço]
|
||||
|
|
@ -83,7 +82,7 @@ Tabelas, filas BullMQ, rotas e serviços externos tocados pelo módulo.
|
|||
|
||||
✅ **Correto** — referência no topo do módulo apontando para a Wiki de Desenvolvimento:
|
||||
```typescript
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/e-licencie.sigma/juntar_execucoes.regras-negocio.md
|
||||
// Regras de negócio: ver <modulo-wiki>/dev/<modulo-id>/juntar_execucoes.regras-negocio.md
|
||||
|
||||
import { ... } from "..."
|
||||
|
||||
|
|
@ -118,7 +117,8 @@ export const compilarJuntarExecucoes = async (...) => {
|
|||
## Referências
|
||||
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/identidade-modulo.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Skill: `skills/documentar-regras-negocio/SKILL.md`
|
||||
- Workflow: `global/workflows/documentar-regras-negocio.md`
|
||||
- Wiki de Desenvolvimento: `<base_projeto>/../wiki/dev/<modulo>/`
|
||||
- Wiki de Desenvolvimento: `<modulo-wiki>/dev/<modulo-id>/`
|
||||
|
|
|
|||
|
|
@ -1,25 +1,25 @@
|
|||
---
|
||||
type: rule
|
||||
name: theme-provider-mui-betha
|
||||
description: Define a arquitetura centralizada do ThemeProvider MUI Betha nos frontends React do ecossistema GOV (AUTENTICACAO-FRONT, QUIPO-FRONT, QUIPO-PORTAL3)
|
||||
description: Define a arquitetura centralizada do ThemeProvider MUI Betha nos frontends React de gestão pública (<modulo>-front)
|
||||
scope: global
|
||||
trigger: model_decision
|
||||
priority: alta
|
||||
updatedAt: "2026-09-28"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: ThemeProvider MUI Centralizado — Arquitetura Betha
|
||||
|
||||
Os frontends React do ecossistema GOV usam MUI com tema centralizado. **Nunca criar temas locais em componentes.**
|
||||
Nos módulos cujo `memorias-ia/modulo.yml` (`modulo-tipo`) utiliza frontend React com Material UI (MUI) voltado à gestão pública, o pacote `<modulo>-front` deve usar tema centralizado. **Nunca criar temas locais em componentes.**
|
||||
|
||||
## Arquitetura de Camadas
|
||||
|
||||
```
|
||||
themeOptions.ts
|
||||
├── tema-betha.ts → createTheme(themeOptions) — marca Betha
|
||||
├── tema-e-licencie.ts → createTheme({...themeOptions, — marca e-licencie
|
||||
├── tema-betha.ts → createTheme(themeOptions) — marca Betha
|
||||
├── tema-padrao.ts → createTheme({...themeOptions, — marca white-label alternativa
|
||||
│ palette: { primary: { main: "#688c00" } }})
|
||||
└── tema.ts → exporta { tema } baseado em eBetha()
|
||||
└── tema.ts → exporta { tema } baseado em eBetha()
|
||||
↓
|
||||
index.tsx / App.tsx
|
||||
<ThemeProvider theme={tema.tema}>
|
||||
|
|
@ -56,7 +56,7 @@ const themeOptions = {
|
|||
|
||||
## Regras
|
||||
|
||||
✅ **Correto:** importar `tema` de `styles/tema-betha.ts` quando um componente isolado precisa de ThemeProvider próprio
|
||||
✅ **Correto:** importar `tema` de `styles/tema-betha.ts` (ou `Plugins/tema.ts`) quando um componente isolado precisa de ThemeProvider próprio
|
||||
✅ **Correto:** `themeOptions.ts` é a única fonte de tokens — modificar só lá
|
||||
❌ **Incorreto:** `createTheme()` vazio ou com tokens hardcoded dentro de componentes
|
||||
❌ **Incorreto:** múltiplos `ThemeProvider` aninhados com temas distintos
|
||||
|
|
@ -72,19 +72,12 @@ import { tema } from "@/styles/tema-betha";
|
|||
</ThemeProvider>
|
||||
```
|
||||
|
||||
## AUTENTICACAO-FRONT — Estrutura específica
|
||||
|
||||
```
|
||||
src/_FRONT/Components/Plugins/tema.ts
|
||||
→ exporta themeBetha e themeELicencie
|
||||
→ App.tsx decide qual usar via eBetha()
|
||||
```
|
||||
|
||||
## Impacto
|
||||
|
||||
Evita divergências visuais entre telas e garante que a troca de marca (Betha ↔ e-licencie) seja controlada por um único ponto.
|
||||
Evita divergências visuais entre telas e garante que a troca dinâmica de marca white-label seja controlada por um único ponto.
|
||||
|
||||
## Referências
|
||||
|
||||
- Identidade do Módulo: `memorias-ia/modulo.yml`
|
||||
- Rule: `estilos-design-system`
|
||||
- Rule: `css-global-betha`
|
||||
|
|
|
|||
82
global/rules/uso-estrito-enums-tabelas.md
Normal file
82
global/rules/uso-estrito-enums-tabelas.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
---
|
||||
type: rule
|
||||
name: uso-estrito-enums-tabelas
|
||||
description: Uso estrito de constantes canônicas de Tabelas e Enums exportados por *-comuns (proibição de magic strings)
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Regra: Uso Estrito de Enums e Constantes de Tabelas (Eliminação de Strings Literais)
|
||||
|
||||
## Contexto
|
||||
|
||||
A utilização de strings mágicas (magic strings) e literais soltos para representar tabelas de banco de dados ou valores de enums é uma fonte crônica de bugs silenciosos em runtime. Quando um valor de enum ou nome de tabela é refatorado, o TypeScript não detecta comparações literais soltas (`u.papel === "administrador"`, `db("tickets")`), quebrando regras de negócio e consultas.
|
||||
|
||||
---
|
||||
|
||||
## Regra Fundamental
|
||||
|
||||
**É terminantemente proibido utilizar strings literais para referenciar tabelas do banco de dados ou valores que pertençam a enums canônicos.**
|
||||
|
||||
Todo desenvolvedor e agente de IA deve obrigatoriamente:
|
||||
1. Consultar `memorias-ia/modulo.yml` para identificar o módulo e importar as definições a partir do pacote compartilhado `<modulo>-comuns`;
|
||||
2. Utilizar a constante canônica `Tabelas` (ou `tabelas`) para toda e qualquer referência a tabelas no banco de dados (Knex, migrations, queries);
|
||||
3. Utilizar os objetos de Enum canônicos correspondentes para toda comparação, atribuição e checagem condicional de estado, papel, tipo ou severidade.
|
||||
|
||||
---
|
||||
|
||||
## 1. Referência a Tabelas de Banco de Dados
|
||||
|
||||
### ❌ Proibido
|
||||
```typescript
|
||||
db("tickets")
|
||||
db("usuarios as u")
|
||||
db("tarefas_manutencao")
|
||||
```
|
||||
|
||||
### ✅ Correto
|
||||
```typescript
|
||||
// Importar do pacote <modulo>-comuns do projeto atual
|
||||
import { Tabelas } from "<modulo>-comuns";
|
||||
|
||||
db(Tabelas.tickets)
|
||||
db(`${Tabelas.usuarios} as u`)
|
||||
db(Tabelas.tarefas_manutencao)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Comparações e Atribuições de Enums
|
||||
|
||||
### ❌ Proibido
|
||||
```typescript
|
||||
if (ticket.status === "resolvido") { ... }
|
||||
if (usuario.papel === "administrador") { ... }
|
||||
if (tarefa.tipo_manutencao === "corretiva_bug") { ... }
|
||||
if (msg.tipo_mensagem === "nota_interna_equipe") { ... }
|
||||
```
|
||||
|
||||
### ✅ Correto
|
||||
```typescript
|
||||
// Importar os enums canônicos do pacote <modulo>-comuns
|
||||
import {
|
||||
StatusTicket,
|
||||
TipoUsuarioInterno,
|
||||
TipoManutencaoSoftware,
|
||||
TipoMensagem,
|
||||
} from "<modulo>-comuns";
|
||||
|
||||
if (ticket.status === StatusTicket.resolvido) { ... }
|
||||
if (usuario.papel === TipoUsuarioInterno.administrador) { ... }
|
||||
if (tarefa.tipo_manutencao === TipoManutencaoSoftware.corretiva_bug) { ... }
|
||||
if (msg.tipo_mensagem === TipoMensagem.nota_interna_equipe) { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impacto
|
||||
|
||||
- Refatorações seguras assistidas pelo compilador TypeScript (`tsc --noEmit`);
|
||||
- Zero regressões causadas por erros tipográficos em nomes de tabelas ou enums;
|
||||
- Código fortemente tipado em todas as camadas (`*-comuns`, `*-back`, `*-front` e `*-migracao`).
|
||||
|
|
@ -29,10 +29,10 @@ O conhecimento do agente está organizado em **três tipos de artefatos**, cada
|
|||
|
||||
> 🧩 **Polimorfismo do `.agent` e Identidade por Projeto**:
|
||||
> O `.agent` é polimórfico e genérico. A personalização e identidade de cada projeto específico é mantida fora do `.agent`:
|
||||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
|
||||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso` e `modulo-wiki`.
|
||||
> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
|
||||
> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
|
||||
> - `<base_projeto>/../wiki/dev/<modulo-id>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
> - `<modulo-wiki>/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress (fallback de wiki: `../wiki/`).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
|
||||
### Diferenças entre os artefatos
|
||||
|
||||
|
|
|
|||
|
|
@ -45,18 +45,18 @@ find <modulo>-front/src -name "modal*.vue" -o -name "Modal*.vue" | while read vu
|
|||
done
|
||||
```
|
||||
|
||||
### 3. Pilar 3 — Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
|
||||
### 3. Pilar 3 — Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`)
|
||||
|
||||
```sh
|
||||
# Verificar se existe documentação de usuário do módulo
|
||||
ls -la <base_projeto>/../wiki/<modulo-id>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM <base_projeto>/../wiki/<modulo-id>/"
|
||||
# Verificar se existe documentação de usuário do módulo (modulo-wiki com fallback para ../wiki)
|
||||
ls -la <modulo-wiki>/<modulo-id>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM <modulo-wiki>/<modulo-id>/"
|
||||
```
|
||||
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`)
|
||||
### 4. Pilar 4 — Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`)
|
||||
|
||||
```sh
|
||||
# Verificar se existe documentação de desenvolvimento, regras de negócio ({modulo}.regras-negocio.md) e ADRs
|
||||
ls -la <base_projeto>/../wiki/dev/<modulo-id>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM <base_projeto>/../wiki/dev/<modulo-id>/"
|
||||
ls -la <modulo-wiki>/dev/<modulo-id>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM <modulo-wiki>/dev/<modulo-id>/"
|
||||
```
|
||||
|
||||
### 5. Pilar 5 — Rota de Integração de IA (`/llm.md`)
|
||||
|
|
@ -71,8 +71,8 @@ rg "llm\.md" --include='*.ts' <modulo>-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 (<base_projeto>/../wiki/<modulo-id>/):** Presente / Ausente
|
||||
- **Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/):** Presente / Ausente
|
||||
- **Wiki de Usuário (<modulo-wiki>/<modulo-id>/):** Presente / Ausente
|
||||
- **Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/):** 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. ...
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
name: doc
|
||||
description: Alias rápido para /documentacao - acionar o Agente de Documentação & Memória com versionamento automático na Wiki
|
||||
description: Alias rápido para /documentacao - acionar o Agente de Documentação & Memória nos 6 pilares com sugestão de mensagem de commit para o operador humano
|
||||
scope: global
|
||||
updatedAt: "2026-09-05"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Skill: /doc (Alias para /documentacao)
|
||||
|
|
@ -32,19 +32,18 @@ Ao documentar a sessão (seja via `/doc` ou `/documentacao`):
|
|||
```
|
||||
|
||||
|
||||
## 🔄 Versionamento Git Obrigatório da Wiki (`<base_projeto>/../wiki`)
|
||||
## 💬 Sugestão de Mensagem de Commit (Commit Exclusivo por Humano)
|
||||
|
||||
Sempre que a documentação na Wiki (Pilares 3 e 4) for alterada ou criada:
|
||||
- O agente **DEVE obrigatoriamente executar commit, push e resolução de conflitos** das alterações diretamente na branch `master` do repositório da Wiki:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): sincronizar documentação"
|
||||
git -C <base_projeto>/../wiki pull --rebase origin master # se houver divergência, resolve na master
|
||||
git -C <base_projeto>/../wiki push origin master
|
||||
Sempre que documentações na aplicação (`<base_projeto>`) ou na Wiki (`<modulo-wiki>`, padrão `../wiki`) forem criadas ou alteradas:
|
||||
- O agente **NUNCA executa `git commit` ou `git push`** — o commit deve ser feito **exclusivamente pelo operador humano** (ver `rules/proibido-commit-ia.md`).
|
||||
- Ao concluir, o agente apresenta a sugestão de mensagem de commit pronta para o humano copiar:
|
||||
```markdown
|
||||
💬 **Sugestão de Commit (Wiki / Aplicação):**
|
||||
`docs(<modulo-id>): <descrição sucinta das alterações>`
|
||||
```
|
||||
|
||||
> 🔒 **Fronteira Git e Salvaguarda de Master:**
|
||||
> Na Wiki, commit, push e resolução de conflitos ocorrem diretamente na branch `master`. Na aplicação principal (`<base_projeto>`), a IA pode realizar commits apenas em branches de trabalho, sendo **terminantemente proibido comitar na branch `master`** (se estiver em `master`, deve criar uma nova branch; ver `rules/proibido-commit-ia.md`).
|
||||
> 🔒 **Fronteira Git:**
|
||||
> Apenas o submódulo `.agent` pode receber commit/push de forma automática pela IA. Tanto na aplicação principal (`<base_projeto>`) quanto na Wiki (`<modulo-wiki>`), a IA apenas sugere o texto do commit ao operador humano.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
name: documentacao
|
||||
description: Acionar o Agente de Documentação & Memória para documentar o contexto da conversa ou gerar artefatos nos 6 pilares canônicos com versionamento automático na Wiki
|
||||
description: Acionar o Agente de Documentação & Memória para documentar o contexto da conversa ou gerar artefatos nos 6 pilares canônicos com sugestão de mensagem de commit para o operador humano
|
||||
scope: global
|
||||
updatedAt: "2026-09-05"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Skill / Workflow: /documentacao
|
||||
|
|
@ -21,14 +21,10 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
4. **Pilar 4 (Wiki de Desenvolvimento):** Documenta regras de negócio (`{modulo}.regras-negocio.md`), modelos e ADRs em `<base_projeto>/../wiki/dev/<modulo>/` (aplicação VitePress com acesso interno dev).
|
||||
5. **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
|
||||
6. **Pilar 6 (Memória IA):** Registra o relatório completo da sessão no arquivo individual `<base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md` e atualiza o índice central `<base_projeto>/memorias-ia/historico-acoes.md` adicionando a linha correspondente na tabela com as colunas: `Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte`.
|
||||
7. **Sincronização Git da Wiki (Obrigatório e Exclusivo):**
|
||||
- Se houver arquivos novos ou alterados em `<base_projeto>/../wiki/`:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): sincronizar documentação [contexto]"
|
||||
git -C <base_projeto>/../wiki push
|
||||
```
|
||||
- **Trava de Segurança da Aplicação:** Na aplicação (`<base_projeto>`), o agente **NÃO pode mexer no git** (o versionamento do código-fonte da aplicação permanece sob controle humano exclusivo).
|
||||
7. **Sugestão de Mensagem de Commit (Commit Exclusivo por Humano):**
|
||||
- O agente **NUNCA executa `git commit` ou `git push`** na aplicação (`<base_projeto>`) nem na Wiki (`<modulo-wiki>`).
|
||||
- Ao finalizar, apresenta ao operador humano a sugestão de mensagem de commit pronta para copiar:
|
||||
`💬 Sugestão de Commit: docs(<modulo-id>): <descrição sucinta das alterações>`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -57,20 +53,20 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
# Criar ajuda contextual modalX.ajuda.md para modal/tela
|
||||
/documentacao ajuda <caminho/modalX.vue>
|
||||
|
||||
# Documentar domínio na Wiki do Usuário (VitePress) + commit/push na wiki
|
||||
# Documentar domínio na Wiki do Usuário (VitePress) + sugestão de commit
|
||||
/documentacao wiki-usuario <modulo>
|
||||
|
||||
# Documentar regras de negócio na Wiki Dev (VitePress) + commit/push na wiki
|
||||
# Documentar regras de negócio na Wiki Dev (VitePress) + sugestão de commit
|
||||
/documentacao regras <caminho/servico.ts>
|
||||
|
||||
# Criar um ADR na Wiki Dev + commit/push na wiki
|
||||
# Criar um ADR na Wiki Dev + sugestão de commit
|
||||
/documentacao adr "<Título da Decisão>"
|
||||
|
||||
# Upload de arquivo/mídia (PDF, imagem, vídeo) para o MinIO Paiol com link pronto para a Wiki
|
||||
/documentacao upload <caminho/arquivo.ext> <slug-funcionalidade>
|
||||
```
|
||||
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`<base_projeto>/../wiki`) deve finalizar executando `git add`, `git commit`, `git pull --rebase` (resolvendo conflitos na master se houver) e `git push` diretamente na branch `master` dentro de `../wiki`.
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na aplicação ou na Wiki (`<base_projeto>/../wiki`) **não deve executar `git commit` nem `git push`**, apresentando ao final apenas a sugestão de mensagem de commit para o operador humano.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -80,5 +76,5 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
|
|||
2. **Linguagem acessível no usuário:** Sem termos técnicos de TI na Wiki do Usuário ou em `.ajuda.md`.
|
||||
3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos.
|
||||
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `<base_projeto>/../wiki/`.
|
||||
5. **Fronteira Git e Gestão em Master na Wiki:** Toda atualização em `<base_projeto>/../wiki` DEVE ser commitada, sincronizada com resolução de conflitos e enviada via `git push` diretamente na branch `master` de `../wiki`. Na aplicação principal (`<base_projeto>`), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`).
|
||||
5. **Fronteira Git (Commit Exclusivo por Humano):** É proibido à IA executar `git commit` ou `git push` na aplicação principal (`<base_projeto>`) e na Wiki (`<modulo-wiki>`). A IA deve apenas sugerir o texto do commit (`docs(<modulo-id>): ...`) para o operador humano. Apenas o submódulo `.agent` pode receber commit/push automático (ver `rules/proibido-commit-ia.md`).
|
||||
6. **Mídias e Binários no MinIO Paiol:** Arquivos pesados (PDFs, vídeos, imagens e anexos) NUNCA devem ser commitados no Git da Wiki; envie sempre para o MinIO Paiol via `./.agent/scripts/upload-paiol-wiki.sh` e versione apenas a URL pública nos arquivos Markdown.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ name: documentar-decisao-tecnica
|
|||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
description: >
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/adrs/).
|
||||
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/adrs/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Decisão Técnica (ADR)
|
||||
|
|
@ -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 `<base_projeto>/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`).
|
||||
2. Convenção de diretório: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/` (na Wiki de Desenvolvimento).
|
||||
1. Ler `modulo-id` e `modulo-wiki` em `<base_projeto>/memorias-ia/modulo.yml` (fallback de wiki: `../wiki/`).
|
||||
2. Convenção de diretório: `<modulo-wiki>/dev/<modulo-id>/adrs/` (na Wiki de Desenvolvimento).
|
||||
|
||||
```bash
|
||||
mkdir -p <base_projeto>/../wiki/dev/<modulo-id>/adrs
|
||||
mkdir -p <modulo-wiki>/dev/<modulo-id>/adrs
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar o Arquivo ADR
|
||||
|
|
@ -43,7 +44,7 @@ Nomenclatura: `NNN-titulo-em-kebab-case.md`
|
|||
|
||||
```bash
|
||||
# Encontrar o próximo número
|
||||
NEXT=$(ls .docs/adrs/*.md 2>/dev/null | wc -l | xargs -I{} expr {} + 1)
|
||||
NEXT=$(ls <modulo-wiki>/dev/<modulo-id>/adrs/*.md 2>/dev/null | wc -l | xargs -I{} expr {} + 1)
|
||||
NEXT=$(printf "%03d" $NEXT)
|
||||
echo "Próximo ADR: $NEXT"
|
||||
```
|
||||
|
|
@ -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 `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`?
|
||||
- [ ] O ADR foi salvo em `<modulo-wiki>/dev/<modulo-id>/adrs/`?
|
||||
- [ ] A decisão foi registrada na memória em `<base_projeto>/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: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`
|
||||
- Wiki de Desenvolvimento: `<modulo-wiki>/dev/<modulo-id>/adrs/`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,37 +1,38 @@
|
|||
---
|
||||
name: documentar-dominio-modulo
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
updatedAt: "2026-10-14"
|
||||
description: >
|
||||
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
|
||||
de usuário (<base_projeto>/../wiki/<modulo-id>/) e de desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/).
|
||||
de usuário (<modulo-wiki>/<modulo-id>/) e de desenvolvimento (<modulo-wiki>/dev/<modulo-id>/).
|
||||
---
|
||||
|
||||
# Skill: Documentar Domínio de um Módulo
|
||||
|
||||
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 `<base_projeto>/../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
||||
1. **Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
||||
2. **Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`):** 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 operacional ou ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, atendimento, etc.). O repositório `<modulo-wiki>` (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 (`<modulo-wiki>/<modulo-id>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
||||
2. **Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`):** 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).
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Identificar a Identidade e Domínio do Módulo via `memorias-ia/modulo.yml`
|
||||
|
||||
Consultar obrigatoriamente `<base_projeto>/memorias-ia/modulo.yml` na raiz do projeto pai:
|
||||
- `modulo-id`: identificador do módulo (ex: `e-licencie.sigma`)
|
||||
- `modulo-caminho`: rota base na URL (ex: `/sigma/`)
|
||||
- `modulo-id`: identificador canônico do módulo
|
||||
- `modulo-caminho`: rota base na URL
|
||||
- `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 (`<base_projeto>/../wiki`) são:
|
||||
- **Wiki do Usuário:** `<base_projeto>/../wiki/<modulo-id>/`
|
||||
- **Wiki de Desenvolvimento:** `<base_projeto>/../wiki/dev/<modulo-id>/`
|
||||
Os destinos canônicos da documentação na aplicação VitePress (`<modulo-wiki>`) são:
|
||||
- **Wiki do Usuário:** `<modulo-wiki>/<modulo-id>/`
|
||||
- **Wiki de Desenvolvimento:** `<modulo-wiki>/dev/<modulo-id>/`
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
|
||||
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`)
|
||||
|
||||
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
|
||||
|
||||
|
|
@ -48,8 +49,8 @@ Breve descrição do propósito do módulo para o gestor e operador.
|
|||
| Parâmetro Ambiental | Variável físico-química monitorada (ex: DBO, DQO) | — |
|
||||
|
||||
## Fluxos Operacionais do Usuário
|
||||
1. Cadastro de pontos de monitoramento.
|
||||
2. Lançamento e importação de medições.
|
||||
1. Cadastro de entidades base.
|
||||
2. Lançamento e acompanhamento de registros.
|
||||
3. Emissão de relatórios e acompanhamento de conformidade.
|
||||
```
|
||||
|
||||
|
|
@ -62,7 +63,7 @@ Utilize exclusivamente a URL pública gerada (`https://paiol.idz.one/wiki/...`)
|
|||
|
||||
---
|
||||
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo>/`)
|
||||
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`)
|
||||
|
||||
Estruturar a especificação técnica, modelos de banco e arquitetura:
|
||||
|
||||
|
|
@ -70,11 +71,11 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|||
# [Nome do Módulo] — Arquitetura e Engenharia
|
||||
|
||||
## Modelo de Dados e Entidades
|
||||
- **Tabelas principais:** `sigma_pontos`, `sigma_medicoes`, `sigma_parametros`
|
||||
- **Schemas Zod canônicos:** `zPontoCriar`, `zMedicaoRegistrar` em `*-comuns`
|
||||
- **Tabelas principais:** `<modulo>_entidade_a`, `<modulo>_entidade_b`, `<modulo>_parametros`
|
||||
- **Schemas Zod canônicos:** `zEntidadeCriar`, `zRegistroAtualizar` em `<modulo>-comuns`
|
||||
|
||||
## Processamento Assíncrono e Filas (BullMQ)
|
||||
- **Fila `calcular_agenda`:** Recalcula status e prazos de monitoramento.
|
||||
- **Fila `processar_agenda`:** Recalcula status e prazos operacionais.
|
||||
|
||||
## Rotas e Integração de IA
|
||||
- **Rota `/llm.md`:** Disponibiliza catálogo dinâmico de endpoints e contratos.
|
||||
|
|
@ -85,18 +86,18 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|||
## PASSO 4 — Conectar com Código e UI
|
||||
|
||||
1. Verificar se mensagens e labels na UI seguem o vocabulário definido (rule `mensagens-usuario`).
|
||||
2. Verificar se componentes e modais Vue possuem `modalX.ajuda.md` co-localizado (skill `adicionar-ajuda`).
|
||||
2. Verificar se componentes e modais possuem `{componente}.ajuda.md` co-localizado (skill `adicionar-ajuda`).
|
||||
3. Garantir que funções centrais e serviços possuem comentários claros de aplicação (rule `jsdoc-padrao`).
|
||||
4. Assegurar que regras com 3+ critérios possuam `.regras-negocio.md` co-localizado (rule `regras-negocio-md`).
|
||||
4. Assegurar que regras com 3+ critérios possuam `.regras-negocio.md` na Wiki de Desenvolvimento (rule `regras-negocio-md`).
|
||||
|
||||
---
|
||||
|
||||
## Checklist Final
|
||||
|
||||
- [ ] Documentação de usuário criada/atualizada em `<modulo-wiki>/<modulo>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<modulo-wiki>/dev/<modulo>/`?
|
||||
- [ ] Documentação de usuário criada/atualizada em `<modulo-wiki>/<modulo-id>/`?
|
||||
- [ ] Documentação técnica criada/atualizada em `<modulo-wiki>/dev/<modulo-id>/`?
|
||||
- [ ] Glossário com os termos centrais do domínio documentado?
|
||||
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
|
||||
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `<modulo>-comuns`?
|
||||
- [ ] Rota `/llm.md` no backend reflete o módulo?
|
||||
- [ ] Imagens, manuais e anexos hospedados no MinIO Paiol (sem binários no Git da Wiki)?
|
||||
|
||||
|
|
@ -105,7 +106,7 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|||
## Referências
|
||||
|
||||
- Rule: `rules/ddd-documentacao-primeiro.md`
|
||||
- Rule: `rules/identidade-modulo.md`
|
||||
- Rule: `rules/jsdoc-padrao.md`
|
||||
- Rule: `rules/regras-negocio-md.md`
|
||||
- Skill: `skills/adicionar-ajuda/SKILL.md`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,19 +1,19 @@
|
|||
---
|
||||
name: documentar-regras-negocio
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
|
||||
scope: global
|
||||
updatedAt: "2026-09-02"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# 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 `<base_projeto>/../wiki/dev/<modulo-id>/`.
|
||||
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 `<modulo-wiki>/dev/<modulo-id>/`.
|
||||
|
||||
---
|
||||
|
||||
[1] Obter a identidade do módulo e ler o código TypeScript
|
||||
|
||||
1. Ler `modulo-id` em `<base_projeto>/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`).
|
||||
1. Ler `modulo-id` e `modulo-wiki` em `<base_projeto>/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 <base_projeto>/../wiki/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
||||
ls <modulo-wiki>/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
||||
```
|
||||
|
||||
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
||||
|
|
@ -38,7 +38,7 @@ ls <base_projeto>/../wiki/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
|||
|
||||
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
||||
|
||||
**Localização:** `<base_projeto>/../wiki/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<base_projeto>/../wiki/dev/<modulo-id>/regras-negocio/`).
|
||||
**Localização:** `<modulo-wiki>/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<modulo-wiki>/dev/<modulo-id>/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 <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver <modulo-wiki>/dev/<modulo>/{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 `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
- Criar ou atualizar ADR em `<base_projeto>/../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<modulo-wiki>/dev/<modulo>/`.
|
||||
- Criar ou atualizar ADR em `<modulo-wiki>/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.
|
||||
- **Sincronização Git:** Executar commit e push exclusivamente na Wiki (`git -C <base_projeto>/../wiki add -A && git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): regras de negócio" && git -C <base_projeto>/../wiki push`). Na aplicação (`<base_projeto>`), nunca mexer no git.
|
||||
- **Sugestão de Commit (Sem Executar Commit):** Nunca executar `git commit` ou `git push` na aplicação (`<base_projeto>`) nem na Wiki (`<modulo-wiki>`), pois o commit é exclusivo de humano (ver `rules/proibido-commit-ia.md`). Apresentar ao operador a sugestão de mensagem: `docs(<modulo-id>): regras de negócio`.
|
||||
|
||||
|
|
|
|||
|
|
@ -42,18 +42,23 @@ git submodule update --init --recursive --remote
|
|||
|
||||
## PASSO 2 — Configurar a Identidade do Módulo (`memorias-ia/modulo.yml`)
|
||||
|
||||
1. Criar a pasta de memórias e copiar o template oficial:
|
||||
1. Criar a pasta de memórias e copiar os templates oficiais:
|
||||
```bash
|
||||
mkdir -p memorias-ia
|
||||
cp .agent/DOCUMENTACAO/templates/modulo.yml.template memorias-ia/modulo.yml
|
||||
cp .agent/DOCUMENTACAO/templates/historico-acoes.md.template memorias-ia/historico-acoes.md
|
||||
```
|
||||
|
||||
2. Editar `memorias-ia/modulo.yml` preenchendo os 4 campos obrigatórios:
|
||||
2. Editar `memorias-ia/modulo.yml` preenchendo os campos canônicos:
|
||||
```yaml
|
||||
modulo-id: nome-do-modulo.submodulo # ex: e-licencie.qualifica
|
||||
modulo-caminho: /qualifica/ # rota base na URL
|
||||
modulo-descricao: Módulo para gestão de conformidade de fornecedores
|
||||
modulo-id: nome-do-modulo
|
||||
modulo-caminho: /modulo/
|
||||
modulo-descricao: Descrição funcional e escopo de negócio do módulo
|
||||
modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
|
||||
modulo-acesso:
|
||||
usuario: usuario@exemplo.com.br
|
||||
senha: "123"
|
||||
modulo-wiki: ../wiki
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -76,11 +81,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** | `<base_projeto>/../wiki/<modulo-id>/index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` |
|
||||
| **Pilar 4: Wiki Dev** | `<base_projeto>/../wiki/dev/<modulo-id>/` | `DOCUMENTACAO/templates/regra-negocio.md.template` e `adr.md.template` |
|
||||
| **Pilar 3: Wiki Usuário** | `<modulo-wiki>/<modulo-id>/index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` |
|
||||
| **Pilar 4: Wiki Dev** | `<modulo-wiki>/dev/<modulo-id>/` | `DOCUMENTACAO/templates/regra-negocio.md.template` e `adr.md.template` |
|
||||
| **Pilar 5: IA (/llm.md)** | `GET <modulo-caminho>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
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui
|
|||
| **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. |
|
||||
| **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. |
|
||||
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session <modulo>_<contexto?> --headed`. |
|
||||
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `wiki/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`wiki/dev/<modulo>/`). |
|
||||
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `<modulo-wiki>/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`<modulo-wiki>/dev/<modulo-id>/`). |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -157,10 +157,11 @@ Ao atingir 100% de conformidade com todos os critérios do plano:
|
|||
4. **Memória do Projeto (Pilar 6 - @documentacao):**
|
||||
- Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
|
||||
- Indexar no `memorias-ia/historico-acoes.md`.
|
||||
5. **Staging e Commit Semântico:**
|
||||
- Executar `git add <arquivos>` e `git status`.
|
||||
- Inspecionar a branch atual com `git branch --show-current`: se estiver em `master` (ou `main`), criar e alternar para uma nova branch semântica (`git checkout -b <tipo>/<slug-plano>`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`).
|
||||
- Executar o `git commit` semântico na branch de trabalho (`git commit -m "<tipo>(<escopo>): <descrição>"`).
|
||||
5. **Sugestão de Mensagem de Commit (Sem Executar Commit):**
|
||||
- Inspecionar os arquivos modificados com `git status --short`.
|
||||
- **NUNCA executar `git commit` ou `git push`** no projeto ou na Wiki — o commit é exclusivo do operador humano (ver `rules/proibido-commit-ia.md`).
|
||||
- Apresentar ao operador humano a sugestão de mensagem de commit no padrão Conventional Commits pronta para copiar:
|
||||
`💬 Sugestão de Commit: <tipo>(<escopo>): <descrição>`
|
||||
6. **Notificação no Sistema Operacional (Linux & macOS):**
|
||||
- Disparar notificação sonora e visual no SO via script `.agent/notificar.sh`:
|
||||
`sh .agent/notificar.sh "Plano Concluído" "<Nome ou Título do Plano>" sucesso`
|
||||
|
|
|
|||
|
|
@ -104,10 +104,10 @@ Para cada item do plano, em ordem:
|
|||
**Agente:** `@refatorar` → `@documentacao`
|
||||
|
||||
- Atualizar JSDoc se interfaces mudaram
|
||||
- Registrar decisão em `.regras-negocio.md` se refatoração foi significativa
|
||||
- Registrar decisão e regras na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`) se a refatoração foi significativa
|
||||
- Informar `@documentacao` sobre mudanças estruturais
|
||||
|
||||
**Formato do commit:**
|
||||
**Sugestão de texto do commit (para o operador humano):**
|
||||
```
|
||||
refactor(<módulo>): <técnica aplicada>
|
||||
|
||||
|
|
|
|||
|
|
@ -29,10 +29,10 @@ O conhecimento do agente está organizado em **três tipos de artefatos**, cada
|
|||
|
||||
> 🧩 **Polimorfismo do `.agent` e Identidade por Projeto**:
|
||||
> O `.agent` é polimórfico e genérico. A personalização e identidade de cada projeto específico é mantida fora do `.agent`:
|
||||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
|
||||
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`, `modulo-acesso` e `modulo-wiki`.
|
||||
> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
|
||||
> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
|
||||
> - `<base_projeto>/../wiki/dev/<modulo-id>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
> - `<modulo-wiki>/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress (fallback padrão: `../wiki/`).
|
||||
> - `<modulo-wiki>/dev/<modulo-id>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
|
||||
|
||||
### Diferenças entre os artefatos
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
type: workflow
|
||||
name: doc
|
||||
description: Alias para /documentacao - acionar o Agente de Documentação & Memória com versionamento automático na Wiki
|
||||
description: Alias para /documentacao - acionar o Agente de Documentação & Memória nos 6 pilares com sugestão de mensagem de commit para o operador humano
|
||||
scope: global
|
||||
updatedAt: "2026-09-05"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Workflow: /doc (Alias para /documentacao)
|
||||
|
|
@ -21,19 +21,18 @@ Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pila
|
|||
|
||||
---
|
||||
|
||||
## 🔄 Versionamento Git Obrigatório da Wiki (`<base_projeto>/../wiki`)
|
||||
## 💬 Sugestão de Mensagem de Commit (Commit Exclusivo por Humano)
|
||||
|
||||
Sempre que a documentação na Wiki (Pilares 3 e 4) for criada ou atualizada:
|
||||
- O agente **DEVE obrigatoriamente executar commit, push e resolução de conflitos** das alterações diretamente na branch `master` no repositório da Wiki:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): sincronizar documentação"
|
||||
git -C <base_projeto>/../wiki pull --rebase origin master # se houver divergência, resolve na master
|
||||
git -C <base_projeto>/../wiki push origin master
|
||||
Sempre que a documentação na aplicação (`<base_projeto>`) ou na Wiki (`<modulo-wiki>`, padrão `../wiki`) for criada ou atualizada:
|
||||
- O agente **NUNCA executa `git commit` ou `git push`** — o commit deve ser feito **exclusivamente pelo operador humano** (ver `rules/proibido-commit-ia.md`).
|
||||
- O agente apresenta ao operador humano a sugestão de mensagem de commit pronta para uso:
|
||||
```markdown
|
||||
💬 **Sugestão de Commit (Wiki / Aplicação):**
|
||||
`docs(<modulo-id>): <descrição sucinta das alterações>`
|
||||
```
|
||||
|
||||
> 🔒 **Fronteira Git e Salvaguarda de Master:**
|
||||
> Na Wiki, commit, push e resolução de conflitos ocorrem diretamente na branch `master`. Na aplicação principal (`<base_projeto>`), a IA pode realizar commits apenas em branches de trabalho, sendo **terminantemente proibido comitar na branch `master`** (se estiver em `master`, deve criar uma nova branch; ver `rules/proibido-commit-ia.md`).
|
||||
> 🔒 **Fronteira Git:**
|
||||
> Apenas o submódulo `.agent` pode receber commit/push de forma automática pela IA. Tanto na aplicação principal (`<base_projeto>`) quanto na Wiki (`<modulo-wiki>`), a IA apenas sugere o texto do commit ao operador humano.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
type: workflow
|
||||
name: documentacao
|
||||
description: Acionar o Agente de Documentação para documentar o contexto do chat ou executar comandos específicos nos 6 pilares com versionamento automático na Wiki
|
||||
description: Acionar o Agente de Documentação para documentar o contexto do chat ou executar comandos específicos nos 6 pilares com sugestão de mensagem de commit para o operador humano
|
||||
scope: global
|
||||
updatedAt: "2026-09-05"
|
||||
updatedAt: "2026-10-14"
|
||||
---
|
||||
|
||||
# Workflow: /documentacao (Agente de Documentação & Memória)
|
||||
|
|
@ -25,16 +25,12 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud
|
|||
- **Pilar 4 (Wiki Dev):** Documenta regras técnicas (`{modulo}.regras-negocio.md`) e ADRs em `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
- **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
|
||||
- **Pilar 6 (Memória IA):** Registra o relatório completo da sessão no arquivo dedicado `<base_projeto>/memorias-ia/sessao-AAAA-MM-DD-slug.md` e indexa a alteração no arquivo central `<base_projeto>/memorias-ia/historico-acoes.md` inserindo linha na tabela com as colunas: `Data | Memória / Ação | Arquivo Memoria | Citações no Código-Fonte`.
|
||||
3. **Sincronização Git da Wiki (Obrigatório e Exclusivo):**
|
||||
- Se houver arquivos novos ou alterados em `<base_projeto>/../wiki/`:
|
||||
```bash
|
||||
git -C <base_projeto>/../wiki add -A
|
||||
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): sincronizar documentação [contexto]"
|
||||
git -C <base_projeto>/../wiki push
|
||||
```
|
||||
- **Fronteira Inegociável da Aplicação:** Na aplicação principal (`<base_projeto>`), o agente **NÃO pode mexer no git** (o versionamento do código-fonte da aplicação permanece sob controle humano exclusivo).
|
||||
3. **Sugestão de Mensagem de Commit (Commit Exclusivo por Humano):**
|
||||
- O agente **NUNCA executa `git commit` ou `git push`** na aplicação principal (`<base_projeto>`) nem na Wiki (`<modulo-wiki>`).
|
||||
- Apresenta ao operador humano a sugestão de mensagem de commit pronta para copiar:
|
||||
`💬 Sugestão de Commit: docs(<modulo-id>): <descrição sucinta das alterações>`
|
||||
4. **Entrega de Relatório:**
|
||||
- Apresenta um resumo claro ao operador de tudo o que foi documentado com links diretos para os arquivos gerados e confirmação do push na Wiki.
|
||||
- Apresenta um resumo claro ao operador de tudo o que foi documentado com links diretos para os arquivos gerados e a sugestão do texto de commit.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -63,17 +59,17 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud
|
|||
# Criar ajuda contextual modalX.ajuda.md para modal/tela
|
||||
/documentacao ajuda <caminho/modalX.vue>
|
||||
|
||||
# Documentar domínio na Wiki do Usuário (VitePress) + commit/push na wiki
|
||||
# Documentar domínio na Wiki do Usuário (VitePress) + sugestão de commit
|
||||
/documentacao wiki-usuario <modulo>
|
||||
|
||||
# Documentar regras de negócio na Wiki Dev (VitePress) + commit/push na wiki
|
||||
# Documentar regras de negócio na Wiki Dev (VitePress) + sugestão de commit
|
||||
/documentacao regras <caminho/servico.ts>
|
||||
|
||||
# Criar um ADR na Wiki Dev + commit/push na wiki
|
||||
# Criar um ADR na Wiki Dev + sugestão de commit
|
||||
/documentacao adr "<Título da Decisão>"
|
||||
```
|
||||
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`<base_projeto>/../wiki`) deve finalizar executando `git add`, `git commit`, `git pull --rebase` (resolvendo conflitos na master se houver) e `git push` diretamente na branch `master` dentro de `../wiki`.
|
||||
*Nota:* Qualquer comando que crie ou modifique arquivos na aplicação ou na Wiki (`<base_projeto>/../wiki`) **não deve executar `git commit` nem `git push`**, apresentando ao final apenas a sugestão de mensagem de commit para o operador humano.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -83,4 +79,4 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud
|
|||
2. **Linguagem acessível no usuário:** Sem termos técnicos de TI na Wiki do Usuário ou em `.ajuda.md`.
|
||||
3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos.
|
||||
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `<base_projeto>/../wiki/`.
|
||||
5. **Fronteira Git e Gestão em Master na Wiki:** Toda atualização em `<base_projeto>/../wiki` DEVE ser commitada, sincronizada com resolução de conflitos e enviada via `git push` diretamente na branch `master` de `../wiki`. Na aplicação principal (`<base_projeto>`), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`).
|
||||
5. **Fronteira Git (Commit Exclusivo por Humano):** É proibido à IA executar `git commit` ou `git push` na aplicação principal (`<base_projeto>`) e na Wiki (`<modulo-wiki>`). A IA deve apenas sugerir o texto do commit (`docs(<modulo-id>): ...`) para o operador humano. Apenas o submódulo `.agent` pode receber commit/push automático (ver `rules/proibido-commit-ia.md`).
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
name: documentar-regras-negocio
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
|
||||
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# 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 `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
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 `<modulo-wiki>/dev/<modulo-id>/` (onde `<modulo-wiki>` e `<modulo-id>` são extraídos de `memorias-ia/modulo.yml`, com fallback padrão `../wiki/`).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ Identificar e anotar:
|
|||
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
|
||||
|
||||
```bash
|
||||
ls <base_projeto>/../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
|
||||
ls <modulo-wiki>/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
||||
```
|
||||
|
||||
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
||||
|
|
@ -38,7 +38,7 @@ ls <base_projeto>/../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
|
|||
|
||||
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
||||
|
||||
**Localização:** `<base_projeto>/../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `<base_projeto>/../wiki/dev/<modulo>/regras-negocio/`).
|
||||
**Localização:** `<modulo-wiki>/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<modulo-wiki>/dev/<modulo-id>/regras-negocio/`).
|
||||
|
||||
Preencher com a estrutura padrão:
|
||||
- Contexto operacional
|
||||
|
|
@ -55,7 +55,7 @@ Preencher com a estrutura padrão:
|
|||
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
||||
|
||||
```typescript
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
|
||||
// Regras de negócio: ver <modulo-wiki>/dev/<modulo-id>/{modulo}.regras-negocio.md
|
||||
```
|
||||
|
||||
Se já existia e está correto → sem mudança necessária.
|
||||
|
|
@ -100,6 +100,6 @@ 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 `<base_projeto>/../wiki/dev/<modulo>/`.
|
||||
- Criar ou atualizar ADR em `<base_projeto>/../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<modulo-wiki>/dev/<modulo-id>/`.
|
||||
- Criar ou atualizar ADR em `<modulo-wiki>/dev/<modulo-id>/adrs/` via skill `documentar-decisao-tecnica`.
|
||||
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.
|
||||
|
|
|
|||
|
|
@ -131,10 +131,10 @@ Ao confirmar que a implementação está verde e validada:
|
|||
3. **Atualização do Grafo de Conhecimento (Graphify):**
|
||||
- Executa `bash .agent/scripts/graphify.sh update` para sincronizar o grafo do projeto com as alterações recém-implementadas.
|
||||
|
||||
4. **Registro na Memória do Projeto (Pilar 6 - @documentacao):**
|
||||
4. **Registro na Memória do Projeto (Pilar 6 - @documentacao) e Sugestão de Commit:**
|
||||
- Cria o registro de sessão em `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
|
||||
- Indexa no `memorias-ia/historico-acoes.md`.
|
||||
- Executa `git add` nos arquivos alterados e realiza o `git commit` semântico (se a branch atual for `master`, cria e seleciona previamente uma nova branch de trabalho — nunca comita em `master`, conforme `rules/proibido-commit-ia.md`).
|
||||
- **Não executa `git commit` ou `git push`** (exclusivo do operador humano, conforme `rules/proibido-commit-ia.md`); apresenta ao operador a sugestão de mensagem de commit no padrão Conventional Commits (`<tipo>(<escopo>): <descrição>`).
|
||||
|
||||
5. **Notificação no Sistema Operacional (Linux & macOS):**
|
||||
- Dispara alerta sonoro e notificação visual de desktop via `.agent/notificar.sh`:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue