publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(regras): atualizar regras de versionamento, workflows, skills e manifesto

Browse source
This commit is contained in:
Luiz Silva 2026-10-01 11:32:37 -03:00
parent 6795ca3bd2
commit d43631be13
15 changed files with 210 additions and 141 deletions
Download patch file Download diff file Expand all files Collapse all files

2
agents/agente/agent.md
View file

@ -212,7 +212,7 @@ sh verificar-linhas.sh
## Restrições
- **NUNCA executar `git commit`, `git push` ou qualquer comando que altere o histórico do repositório** — o controle de versão é responsabilidade exclusiva do usuário humano (ver `global/rules/proibido-commit-ia`)
- **NUNCA executar `git commit` ou `git push` diretamente na branch `master` da aplicação** — se estiver em `master`, criar uma nova branch antes de comitar; na Wiki, commit, push e resolução de conflitos são feitos direto na `master` (ver `global/rules/proibido-commit-ia.md`)
- NÃO altera regras de negócio dos projetos — atua exclusivamente no ecossistema de agentes
- NÃO cria agentes sem escopo claramente diferenciado dos existentes
- NÃO duplica conteúdo entre artefatos — prefere referência cruzada a cópia

9
global/rules/autonomia-agente.md
View file

@ -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-06-01"
updatedAt: "2026-10-01"
---
# Regra: Limites de Autonomia do Agente
@ -27,7 +27,8 @@ O agente pode executar sem perguntar:
- 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` e `git push` exclusivamente no repositório da Wiki (`<base_projeto>/../wiki`) ao criar ou atualizar documentações
- 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`)
## Ações que Requerem Confirmação
@ -40,12 +41,14 @@ O agente deve **propor e aguardar aprovação**:
- 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` no repositório da aplicação (`<base_projeto>`)
- Executar `git commit` ou `git push` diretamente na branch `master` (ou `main`) no repositório da aplicação principal
- 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`
- Alterar artefatos globais (sufixo `.global`) sem justificativa

139
global/rules/proibido-commit-ia.md
View file

@ -1,94 +1,123 @@
---
type: rule
name: proibido-commit-ia
description: A IA nunca mexe no git da aplicação principal; commit e push são permitidos e obrigatórios exclusivamente no repositório da Wiki (../wiki)
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
scope: global
trigger: always_on
updatedAt: "2026-09-05"
updatedAt: "2026-10-01"
---
# Regra: Proibido Commit pela IA na Aplicação e Exceção Obrigatória da Wiki
# Regra: Diretrizes de Versionamento Git — Commit Condicional na Aplicação e Gestão Direta em Master na Wiki
## Contexto
O controle de versão do código-fonte da aplicação principal é de responsabilidade exclusiva do usuário humano. A IA pode preparar alterações, criar arquivos, editar código e até sugerir mensagens de commit — mas NUNCA deve executar comandos que alterem o histórico do repositório da aplicação.
O ecossistema adota uma política de versionamento clara e segura que equilibra agilidade na documentação com proteção do código produtivo:
Por outro lado, o repositório central de documentação (`<base_projeto>/../wiki`), que hospeda a Wiki do Usuário (Pilar 3) e a Wiki de Desenvolvimento (Pilar 4), é uma base viva de documentação. Quando atualizado pelo agente (ex.: via `/doc`, `/documentacao` ou workflows DDD), o commit e o push DEVEM ser executados automaticamente pelo agente, restritos exclusivamente a esse repositório.
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`.
---
## Regra
### 1. Na Aplicação Principal (`<base_projeto>`) — RIGOROSAMENTE PROIBIDO MEXER NO GIT
### 1. Na Aplicação Principal (`<base_projeto>`) — COMMIT CONDICIONAL E SALVAGUARDA DE MASTER
A IA **NUNCA** deve executar comandos que alterem o histórico do repositório da aplicação (nem variações deles):
A IA **PODE** realizar commits na aplicação principal, **ESTRITAMENTE CONDICIONADA** às regras:
- `git commit` ❌
- `git push` ❌
- `git merge` ❌
- `git rebase` ❌
- `git tag` ❌
- `git reset` ❌
- `git revert` ❌
- `git cherry-pick` ❌
- `git stash drop` ❌
- `git branch -d` / `git branch -D` ❌
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
**Comandos permitidos na aplicação (somente leitura e staging):**
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` ❌
- `git status` ✅
- `git diff` ✅
- `git log` ✅
- `git add` ✅ (preparar alterações para o usuário revisar)
- `git stash` / `git stash pop` ✅ (preservar trabalho temporário)
- `git branch` (listar) ✅
- `git ls-files` ✅
- `git show` ✅
---
### 2. No Repositório da Wiki (`<base_projeto>/../wiki`) — COMMIT E PUSH OBRIGATÓRIOS
### 2. No Repositório da Wiki (`<base_projeto>/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER
Sempre que a documentação em `<base_projeto>/../wiki` for criada ou modificada (manuais de usuário em `<modulo-id>/`, regras de negócio em `dev/<modulo-id>/`, ADRs em `dev/<modulo-id>/adrs/`, etc.), o agente **DEVE obrigatoriamente** realizar o commit e push das alterações:
Na Wiki, a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`:
```bash
# Executar estritamente apontando para a pasta ../wiki
git -C <base_projeto>/../wiki add -A
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
git -C <base_projeto>/../wiki push
```
1. **Commit e Push Diretos na Master**:
```bash
git -C <base_projeto>/../wiki add -A
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
git -C <base_projeto>/../wiki push origin master
```
**Fronteira Inegociável:** Esta permissão é restrita e isolada ao repositório `<base_projeto>/../wiki`. A IA **nunca** deve executar commit ou push na aplicação principal.
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 <base_projeto>/../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 <base_projeto>/../wiki add -A`), finaliza o rebase (`git -C <base_projeto>/../wiki rebase --continue` ou commit) e envia com `git push origin master`.
---
## Exemplos
### ❌ Errado — commitar automaticamente na aplicação
```sh
# Na raiz da aplicação (<base_projeto>): PROIBIDO
git add -A && git commit -m "fix: corrigir bug"
git push origin main
### ❌ Errado — comitar diretamente na branch master da aplicação
```bash
# Branch atual: master
git add src/servicos/auth.ts
git commit -m "fix: ajustar token de auth" # PROIBIDO EM MASTER!
```
### ✅ Correto — na aplicação principal, apenas preparar e sugerir
```sh
git add -A
git status
# Informar ao usuário: "Alterações staged na aplicação. Revise e faça o commit quando estiver pronto."
# Sugestão de commit: git commit -m "feat: adicionar validação de schema"
### ✅ 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 — na Wiki, commitar e enviar automaticamente
```sh
# No repositório de documentação (<base_projeto>/../wiki): OBRIGATÓRIO
### ✅ 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 — ciclo completo na Wiki direto na master
```bash
git -C ../wiki add -A
git -C ../wiki commit -m "docs(e-licencie): atualizar regras de negócio e manuais"
git -C ../wiki push
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
```
---
## Impacto
- **Segurança na aplicação:** O desenvolvedor mantém controle total sobre o histórico de código da aplicação.
- **Agilidade e perenidade na wiki:** A documentação fica sempre sincronizada e publicada imediatamente sem fricção manual.
- **Isolamento de escopo:** Fronteira clara e explícita entre repositório de aplicação e repositório de documentação.
- **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.
---
## Referências
- Rule: `rules/autonomia-agente.md`
- Rule: `rules/ddd-documentacao-primeiro.md`
- Skill: `skills/documentacao/SKILL.md`
- Workflow: `global/workflows/documentacao.md`
- Skill: `skills/plano.executar/SKILL.md`

9
global/skills/doc/SKILL.md
View file

@ -35,15 +35,16 @@ Ao documentar a sessão (seja via `/doc` ou `/documentacao`):
## 🔄 Versionamento Git Obrigatório da Wiki (`<base_projeto>/../wiki`)
Sempre que a documentação na Wiki (Pilares 3 e 4) for alterada ou criada:
- O agente **DEVE obrigatoriamente executar commit e push** das alterações exclusivamente no repositório da Wiki:
- 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 push
git -C <base_projeto>/../wiki pull --rebase origin master # se houver divergência, resolve na master
git -C <base_projeto>/../wiki push origin master
```
> 🔒 **Fronteira Inegociável de Git:**
> Na aplicação principal (`<base_projeto>`), o agente **NUNCA pode mexer no git** (proibido `git commit`, `git push`, `git merge`, etc.). O controle de versão do código da aplicação é de responsabilidade humana exclusiva (ver `rules/proibido-commit-ia.md`).
> 🔒 **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`).
---

4
global/skills/documentacao/SKILL.md
View file

@ -67,7 +67,7 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
/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` e `git push` dentro de `../wiki`.
*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`.
---
@ -77,4 +77,4 @@ 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 Push Obrigatório na Wiki:** Toda atualização em `<base_projeto>/../wiki` DEVE ser commitada e enviada via `git push` exclusivamente dentro do diretório `../wiki`. Na aplicação principal (`<base_projeto>`), a IA nunca mexe no Git (ver `rules/proibido-commit-ia.md`).
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
global/skills/plano.executar/SKILL.md
View file

@ -154,9 +154,10 @@ Ao atingir 100% de conformidade com todos os critérios do plano:
3. **Memória do Projeto (Pilar 6 - @documentacao):**
- Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexar no `memorias-ia/historico-acoes.md`.
4. **Staging de Segurança:**
4. **Staging e Commit Semântico:**
- Executar `git add <arquivos>` e `git status`.
- Relembrar a regra `rules/proibido-commit-ia.md`: nunca executar `git commit` na aplicação. Sugerir o comando semântico para o operador.
- 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. **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`

9
global/workflows/doc.md
View file

@ -24,15 +24,16 @@ Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pila
## 🔄 Versionamento Git Obrigatório da Wiki (`<base_projeto>/../wiki`)
Sempre que a documentação na Wiki (Pilares 3 e 4) for criada ou atualizada:
- O agente **DEVE obrigatoriamente executar commit e push** das alterações exclusivamente no diretório da Wiki:
- 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 push
git -C <base_projeto>/../wiki pull --rebase origin master # se houver divergência, resolve na master
git -C <base_projeto>/../wiki push origin master
```
> 🔒 **Fronteira Inegociável de Git:**
> Na aplicação principal (`<base_projeto>`), o agente **NUNCA pode mexer no git** (proibido `git commit`, `git push`, `git merge`, etc.). O versionamento do código da aplicação é mantido exclusivamente pelo usuário (ver `rules/proibido-commit-ia.md`).
> 🔒 **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`).
---

4
global/workflows/documentacao.md
View file

@ -73,7 +73,7 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud
/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` e `git push` dentro de `../wiki`.
*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`.
---
@ -83,4 +83,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 Push Obrigatório na Wiki:** Toda atualização em `<base_projeto>/../wiki` DEVE ser commitada e enviada via `git push` exclusivamente dentro do diretório `../wiki`. Na aplicação principal (`<base_projeto>`), a IA nunca mexe no Git (ver `rules/proibido-commit-ia.md`).
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`).

2
global/workflows/plano.md
View file

@ -129,7 +129,7 @@ Ao confirmar que a implementação está verde e validada:
3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):**
- 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 sugere o comando de commit semântico ao operador (seguindo `rules/proibido-commit-ia.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`).
4. **Notificação no Sistema Operacional (Linux & macOS):**
- Dispara alerta sonoro e notificação visual de desktop via `.agent/notificar.sh`:

2
manifesto.json
View file

@ -1,6 +1,6 @@
{
"versao": "3.2.0",
"atualizadoEm": "2026-09-28",
"atualizadoEm": "2026-10-01",
"projeto": "e-licencie",
"artefatos": {
"global": {

9
rules/autonomia-agente.md
View file

@ -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-06-01"
updatedAt: "2026-10-01"
---
# Regra: Limites de Autonomia do Agente
@ -27,7 +27,8 @@ O agente pode executar sem perguntar:
- 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` e `git push` exclusivamente no repositório da Wiki (`<base_projeto>/../wiki`) ao criar ou atualizar documentações
- 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`)
## Ações que Requerem Confirmação
@ -40,12 +41,14 @@ O agente deve **propor e aguardar aprovação**:
- 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` no repositório da aplicação (`<base_projeto>`)
- Executar `git commit` ou `git push` diretamente na branch `master` (ou `main`) no repositório da aplicação principal
- 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`
- Alterar artefatos globais (sufixo `.global`) sem justificativa

139
rules/proibido-commit-ia.md
View file

@ -1,94 +1,123 @@
---
type: rule
name: proibido-commit-ia
description: A IA nunca mexe no git da aplicação principal; commit e push são permitidos e obrigatórios exclusivamente no repositório da Wiki (../wiki)
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
scope: global
trigger: always_on
updatedAt: "2026-09-05"
updatedAt: "2026-10-01"
---
# Regra: Proibido Commit pela IA na Aplicação e Exceção Obrigatória da Wiki
# Regra: Diretrizes de Versionamento Git — Commit Condicional na Aplicação e Gestão Direta em Master na Wiki
## Contexto
O controle de versão do código-fonte da aplicação principal é de responsabilidade exclusiva do usuário humano. A IA pode preparar alterações, criar arquivos, editar código e até sugerir mensagens de commit — mas NUNCA deve executar comandos que alterem o histórico do repositório da aplicação.
O ecossistema adota uma política de versionamento clara e segura que equilibra agilidade na documentação com proteção do código produtivo:
Por outro lado, o repositório central de documentação (`<base_projeto>/../wiki`), que hospeda a Wiki do Usuário (Pilar 3) e a Wiki de Desenvolvimento (Pilar 4), é uma base viva de documentação. Quando atualizado pelo agente (ex.: via `/doc`, `/documentacao` ou workflows DDD), o commit e o push DEVEM ser executados automaticamente pelo agente, restritos exclusivamente a esse repositório.
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`.
---
## Regra
### 1. Na Aplicação Principal (`<base_projeto>`) — RIGOROSAMENTE PROIBIDO MEXER NO GIT
### 1. Na Aplicação Principal (`<base_projeto>`) — COMMIT CONDICIONAL E SALVAGUARDA DE MASTER
A IA **NUNCA** deve executar comandos que alterem o histórico do repositório da aplicação (nem variações deles):
A IA **PODE** realizar commits na aplicação principal, **ESTRITAMENTE CONDICIONADA** às regras:
- `git commit` ❌
- `git push` ❌
- `git merge` ❌
- `git rebase` ❌
- `git tag` ❌
- `git reset` ❌
- `git revert` ❌
- `git cherry-pick` ❌
- `git stash drop` ❌
- `git branch -d` / `git branch -D` ❌
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
**Comandos permitidos na aplicação (somente leitura e staging):**
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` ❌
- `git status` ✅
- `git diff` ✅
- `git log` ✅
- `git add` ✅ (preparar alterações para o usuário revisar)
- `git stash` / `git stash pop` ✅ (preservar trabalho temporário)
- `git branch` (listar) ✅
- `git ls-files` ✅
- `git show` ✅
---
### 2. No Repositório da Wiki (`<base_projeto>/../wiki`) — COMMIT E PUSH OBRIGATÓRIOS
### 2. No Repositório da Wiki (`<base_projeto>/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER
Sempre que a documentação em `<base_projeto>/../wiki` for criada ou modificada (manuais de usuário em `<modulo-id>/`, regras de negócio em `dev/<modulo-id>/`, ADRs em `dev/<modulo-id>/adrs/`, etc.), o agente **DEVE obrigatoriamente** realizar o commit e push das alterações:
Na Wiki, a IA possui permissão total e obrigação de manter a documentação atualizada diretamente na branch `master`:
```bash
# Executar estritamente apontando para a pasta ../wiki
git -C <base_projeto>/../wiki add -A
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
git -C <base_projeto>/../wiki push
```
1. **Commit e Push Diretos na Master**:
```bash
git -C <base_projeto>/../wiki add -A
git -C <base_projeto>/../wiki commit -m "docs(<modulo-id>): <descrição sucinta das alterações>"
git -C <base_projeto>/../wiki push origin master
```
**Fronteira Inegociável:** Esta permissão é restrita e isolada ao repositório `<base_projeto>/../wiki`. A IA **nunca** deve executar commit ou push na aplicação principal.
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 <base_projeto>/../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 <base_projeto>/../wiki add -A`), finaliza o rebase (`git -C <base_projeto>/../wiki rebase --continue` ou commit) e envia com `git push origin master`.
---
## Exemplos
### ❌ Errado — commitar automaticamente na aplicação
```sh
# Na raiz da aplicação (<base_projeto>): PROIBIDO
git add -A && git commit -m "fix: corrigir bug"
git push origin main
### ❌ Errado — comitar diretamente na branch master da aplicação
```bash
# Branch atual: master
git add src/servicos/auth.ts
git commit -m "fix: ajustar token de auth" # PROIBIDO EM MASTER!
```
### ✅ Correto — na aplicação principal, apenas preparar e sugerir
```sh
git add -A
git status
# Informar ao usuário: "Alterações staged na aplicação. Revise e faça o commit quando estiver pronto."
# Sugestão de commit: git commit -m "feat: adicionar validação de schema"
### ✅ 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 — na Wiki, commitar e enviar automaticamente
```sh
# No repositório de documentação (<base_projeto>/../wiki): OBRIGATÓRIO
### ✅ 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 — ciclo completo na Wiki direto na master
```bash
git -C ../wiki add -A
git -C ../wiki commit -m "docs(e-licencie): atualizar regras de negócio e manuais"
git -C ../wiki push
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
```
---
## Impacto
- **Segurança na aplicação:** O desenvolvedor mantém controle total sobre o histórico de código da aplicação.
- **Agilidade e perenidade na wiki:** A documentação fica sempre sincronizada e publicada imediatamente sem fricção manual.
- **Isolamento de escopo:** Fronteira clara e explícita entre repositório de aplicação e repositório de documentação.
- **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.
---
## Referências
- Rule: `rules/autonomia-agente.md`
- Rule: `rules/ddd-documentacao-primeiro.md`
- Skill: `skills/documentacao/SKILL.md`
- Workflow: `global/workflows/documentacao.md`
- Skill: `skills/plano.executar/SKILL.md`

9
skills/doc/SKILL.md
View file

@ -35,15 +35,16 @@ Ao documentar a sessão (seja via `/doc` ou `/documentacao`):
## 🔄 Versionamento Git Obrigatório da Wiki (`<base_projeto>/../wiki`)
Sempre que a documentação na Wiki (Pilares 3 e 4) for alterada ou criada:
- O agente **DEVE obrigatoriamente executar commit e push** das alterações exclusivamente no repositório da Wiki:
- 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 push
git -C <base_projeto>/../wiki pull --rebase origin master # se houver divergência, resolve na master
git -C <base_projeto>/../wiki push origin master
```
> 🔒 **Fronteira Inegociável de Git:**
> Na aplicação principal (`<base_projeto>`), o agente **NUNCA pode mexer no git** (proibido `git commit`, `git push`, `git merge`, etc.). O controle de versão do código da aplicação é de responsabilidade humana exclusiva (ver `rules/proibido-commit-ia.md`).
> 🔒 **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`).
---

4
skills/documentacao/SKILL.md
View file

@ -67,7 +67,7 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
/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` e `git push` dentro de `../wiki`.
*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`.
---
@ -77,4 +77,4 @@ 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 Push Obrigatório na Wiki:** Toda atualização em `<base_projeto>/../wiki` DEVE ser commitada e enviada via `git push` exclusivamente dentro do diretório `../wiki`. Na aplicação principal (`<base_projeto>`), a IA nunca mexe no Git (ver `rules/proibido-commit-ia.md`).
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
skills/plano.executar/SKILL.md
View file

@ -154,9 +154,10 @@ Ao atingir 100% de conformidade com todos os critérios do plano:
3. **Memória do Projeto (Pilar 6 - @documentacao):**
- Criar `memorias-ia/sessao-AAAA-MM-DD-<slug>.md`.
- Indexar no `memorias-ia/historico-acoes.md`.
4. **Staging de Segurança:**
4. **Staging e Commit Semântico:**
- Executar `git add <arquivos>` e `git status`.
- Relembrar a regra `rules/proibido-commit-ia.md`: nunca executar `git commit` na aplicação. Sugerir o comando semântico para o operador.
- 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. **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`