publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/rules/proibido-commit-ia.md

6.1 KiB
Raw Blame History

type name description scope trigger updatedAt
rule proibido-commit-ia 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 global always_on 2026-10-01

Regra: Diretrizes de Versionamento Git — Commit Condicional na Aplicação e Gestão Direta em Master na Wiki

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:

  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>) — COMMIT CONDICIONAL E SALVAGUARDA DE MASTER

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:

    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:

    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:

    # <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.

  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: 
      ./.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.

Exemplos

❌ Errado — comitar diretamente na branch master da aplicação

# Branch atual: master
git add src/servicos/auth.ts
git commit -m "fix: ajustar token de auth" # PROIBIDO EM MASTER!

✅ Correto — ramificar antes de comitar se estiver em master

# 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 — comitar em branch secundária já existente

# 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

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

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.

Referências

  • Rule: rules/autonomia-agente.md
  • Rule: rules/ddd-documentacao-primeiro.md
  • Skill: skills/documentacao/SKILL.md
  • Skill: skills/plano.executar/SKILL.md