diff --git a/agents/agente/agent.md b/agents/agente/agent.md index b9120fa..eaaa23b 100644 --- a/agents/agente/agent.md +++ b/agents/agente/agent.md @@ -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 diff --git a/global/rules/autonomia-agente.md b/global/rules/autonomia-agente.md index c26a65b..5c13391 100644 --- a/global/rules/autonomia-agente.md +++ b/global/rules/autonomia-agente.md @@ -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 (`/../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 (`/../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 (``) +- 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 diff --git a/global/rules/proibido-commit-ia.md b/global/rules/proibido-commit-ia.md index e1bfa04..76d7f6f 100644 --- a/global/rules/proibido-commit-ia.md +++ b/global/rules/proibido-commit-ia.md @@ -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 (`/../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 (``)**: 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 (`/../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 (``) — RIGOROSAMENTE PROIBIDO MEXER NO GIT +### 1. Na Aplicação Principal (``) — 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 / + ``` + Padrão de nomenclatura: + - `feat/`: novas funcionalidades + - `fix/`: correções de bugs + - `refactor/`: refatorações de código + - `docs/`: documentações técnicas no código + - `ia/`: 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 (`/../wiki`) — COMMIT E PUSH OBRIGATÓRIOS +### 2. No Repositório da Wiki (`/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER -Sempre que a documentação em `/../wiki` for criada ou modificada (manuais de usuário em `/`, regras de negócio em `dev//`, ADRs em `dev//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 /../wiki add -A -git -C /../wiki commit -m "docs(): " -git -C /../wiki push -``` +1. **Commit e Push Diretos na Master**: + ```bash + git -C /../wiki add -A + git -C /../wiki commit -m "docs(): " + git -C /../wiki push origin master + ``` -**Fronteira Inegociável:** Esta permissão é restrita e isolada ao repositório `/../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 /../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 /../wiki add -A`), finaliza o rebase (`git -C /../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 (): 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 (/../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` diff --git a/global/skills/doc/SKILL.md b/global/skills/doc/SKILL.md index 7714d16..c203403 100644 --- a/global/skills/doc/SKILL.md +++ b/global/skills/doc/SKILL.md @@ -35,15 +35,16 @@ Ao documentar a sessão (seja via `/doc` ou `/documentacao`): ## 🔄 Versionamento Git Obrigatório da Wiki (`/../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 /../wiki add -A git -C /../wiki commit -m "docs(): sincronizar documentação" - git -C /../wiki push + git -C /../wiki pull --rebase origin master # se houver divergência, resolve na master + git -C /../wiki push origin master ``` -> 🔒 **Fronteira Inegociável de Git:** -> Na aplicação principal (``), 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 (``), 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`). --- diff --git a/global/skills/documentacao/SKILL.md b/global/skills/documentacao/SKILL.md index 74fbd6f..7b3f640 100644 --- a/global/skills/documentacao/SKILL.md +++ b/global/skills/documentacao/SKILL.md @@ -67,7 +67,7 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza /documentacao adr "" ``` -*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../wiki`) deve finalizar executando `git add`, `git commit` e `git push` dentro de `../wiki`. +*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../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 `/../wiki/`. -5. **Fronteira Git e Push Obrigatório na Wiki:** Toda atualização em `/../wiki` DEVE ser commitada e enviada via `git push` exclusivamente dentro do diretório `../wiki`. Na aplicação principal (``), 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 `/../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 (``), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`). diff --git a/global/skills/plano.executar/SKILL.md b/global/skills/plano.executar/SKILL.md index 02a94cc..1b29ef6 100644 --- a/global/skills/plano.executar/SKILL.md +++ b/global/skills/plano.executar/SKILL.md @@ -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-.md`. - Indexar no `memorias-ia/historico-acoes.md`. -4. **Staging de Segurança:** +4. **Staging e Commit Semântico:** - Executar `git add ` 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 /`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`). + - Executar o `git commit` semântico na branch de trabalho (`git commit -m "(): "`). 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" "" sucesso` diff --git a/global/workflows/doc.md b/global/workflows/doc.md index 25488a8..87eb2ee 100644 --- a/global/workflows/doc.md +++ b/global/workflows/doc.md @@ -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 (`/../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 /../wiki add -A git -C /../wiki commit -m "docs(): sincronizar documentação" - git -C /../wiki push + git -C /../wiki pull --rebase origin master # se houver divergência, resolve na master + git -C /../wiki push origin master ``` -> 🔒 **Fronteira Inegociável de Git:** -> Na aplicação principal (``), 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 (``), 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`). --- diff --git a/global/workflows/documentacao.md b/global/workflows/documentacao.md index 71930c4..f475fa1 100644 --- a/global/workflows/documentacao.md +++ b/global/workflows/documentacao.md @@ -73,7 +73,7 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud /documentacao adr "" ``` -*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../wiki`) deve finalizar executando `git add`, `git commit` e `git push` dentro de `../wiki`. +*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../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 `/../wiki/`. -5. **Fronteira Git e Push Obrigatório na Wiki:** Toda atualização em `/../wiki` DEVE ser commitada e enviada via `git push` exclusivamente dentro do diretório `../wiki`. Na aplicação principal (``), 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 `/../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 (``), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`). diff --git a/global/workflows/plano.md b/global/workflows/plano.md index 95f7b56..ae279f9 100644 --- a/global/workflows/plano.md +++ b/global/workflows/plano.md @@ -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-.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`: diff --git a/manifesto.json b/manifesto.json index 09c81a8..a7c70e8 100644 --- a/manifesto.json +++ b/manifesto.json @@ -1,6 +1,6 @@ { "versao": "3.2.0", - "atualizadoEm": "2026-09-28", + "atualizadoEm": "2026-10-01", "projeto": "e-licencie", "artefatos": { "global": { diff --git a/rules/autonomia-agente.md b/rules/autonomia-agente.md index c26a65b..5c13391 100644 --- a/rules/autonomia-agente.md +++ b/rules/autonomia-agente.md @@ -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 (`/../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 (`/../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 (``) +- 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 diff --git a/rules/proibido-commit-ia.md b/rules/proibido-commit-ia.md index e1bfa04..76d7f6f 100644 --- a/rules/proibido-commit-ia.md +++ b/rules/proibido-commit-ia.md @@ -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 (`/../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 (``)**: 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 (`/../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 (``) — RIGOROSAMENTE PROIBIDO MEXER NO GIT +### 1. Na Aplicação Principal (``) — 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 / + ``` + Padrão de nomenclatura: + - `feat/`: novas funcionalidades + - `fix/`: correções de bugs + - `refactor/`: refatorações de código + - `docs/`: documentações técnicas no código + - `ia/`: 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 (`/../wiki`) — COMMIT E PUSH OBRIGATÓRIOS +### 2. No Repositório da Wiki (`/../wiki`) — COMMIT, PUSH E RESOLUÇÃO DE CONFLITOS DIRETO NA MASTER -Sempre que a documentação em `/../wiki` for criada ou modificada (manuais de usuário em `/`, regras de negócio em `dev//`, ADRs em `dev//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 /../wiki add -A -git -C /../wiki commit -m "docs(): " -git -C /../wiki push -``` +1. **Commit e Push Diretos na Master**: + ```bash + git -C /../wiki add -A + git -C /../wiki commit -m "docs(): " + git -C /../wiki push origin master + ``` -**Fronteira Inegociável:** Esta permissão é restrita e isolada ao repositório `/../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 /../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 /../wiki add -A`), finaliza o rebase (`git -C /../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 (): 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 (/../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` diff --git a/skills/doc/SKILL.md b/skills/doc/SKILL.md index 7714d16..c203403 100644 --- a/skills/doc/SKILL.md +++ b/skills/doc/SKILL.md @@ -35,15 +35,16 @@ Ao documentar a sessão (seja via `/doc` ou `/documentacao`): ## 🔄 Versionamento Git Obrigatório da Wiki (`/../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 /../wiki add -A git -C /../wiki commit -m "docs(): sincronizar documentação" - git -C /../wiki push + git -C /../wiki pull --rebase origin master # se houver divergência, resolve na master + git -C /../wiki push origin master ``` -> 🔒 **Fronteira Inegociável de Git:** -> Na aplicação principal (``), 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 (``), 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`). --- diff --git a/skills/documentacao/SKILL.md b/skills/documentacao/SKILL.md index 74fbd6f..7b3f640 100644 --- a/skills/documentacao/SKILL.md +++ b/skills/documentacao/SKILL.md @@ -67,7 +67,7 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza /documentacao adr "" ``` -*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../wiki`) deve finalizar executando `git add`, `git commit` e `git push` dentro de `../wiki`. +*Nota:* Qualquer comando que crie ou modifique arquivos na Wiki (`/../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 `/../wiki/`. -5. **Fronteira Git e Push Obrigatório na Wiki:** Toda atualização em `/../wiki` DEVE ser commitada e enviada via `git push` exclusivamente dentro do diretório `../wiki`. Na aplicação principal (``), 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 `/../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 (``), a IA pode comitar apenas em branches de trabalho, sendo proibido comitar na `master` (ver `rules/proibido-commit-ia.md`). diff --git a/skills/plano.executar/SKILL.md b/skills/plano.executar/SKILL.md index 02a94cc..1b29ef6 100644 --- a/skills/plano.executar/SKILL.md +++ b/skills/plano.executar/SKILL.md @@ -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-.md`. - Indexar no `memorias-ia/historico-acoes.md`. -4. **Staging de Segurança:** +4. **Staging e Commit Semântico:** - Executar `git add ` 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 /`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`). + - Executar o `git commit` semântico na branch de trabalho (`git commit -m "(): "`). 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" "" sucesso`