4 KiB
| type | name | description | scope | trigger | updatedAt |
|---|---|---|---|---|---|
| rule | atualizacao-submodulo-sessao | Atualização obrigatória do submódulo .agent na branch master ao iniciar qualquer sessão de trabalho | global | always_on | 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 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
Trabalhar com uma versão defasada do submódulo .agent faz com que o agente tome decisões baseadas em regras antigas, falhe em auditorias de setup ou use padrões depreciados. Por isso, a sincronização do submódulo na branch master é mandatória ao iniciar qualquer sessão.
Regra Mandatória de Inicialização
Ao iniciar uma nova sessão de trabalho ou interação no projeto hospedeiro, a sincronização do submódulo .agent DEVE OBRIGATORIAMENTE ser executada na branch master:
git submodule update --init --recursive --remote
Esta operação é classificada como uma ação autônoma (conforme rules/autonomia-agente.md) e não requer autorização prévia do operador humano.
1. Rastreamento Obrigatório de Branch no .gitmodules
Para que o parâmetro --remote do Git saiba qual branch do submódulo deve ser consultada e atualizada, o arquivo .gitmodules na raiz do projeto pai deve conter explicitamente a declaração branch = master:
[submodule ".agent"]
path = .agent
url = https://git2.idz.one/publico/.agent.git
branch = master
Caso o atributo branch esteja ausente no .gitmodules, o script de governança ou o próprio agente deve configurá-lo executando:
git submodule set-branch --branch master .agent
2. Protocolo de Automação via Lifecycle Hook
O framework .agent disponibiliza um hook nativo do Antigravity em .agent/hooks.json vinculado ao evento PreInvocation:
- No início da conversa, o hook aciona o script
.agent/scripts/atualizar-submodulo.sh. - O script detecta a raiz do projeto pai (superprojeto) e verifica a existência de uma trava temporária da sessão (
/tmp/.antigravity_agent_updated_${conversationId}). - Idempotência: A sincronização remota é executada apenas no primeiro turno da sessão. Turnos subsequentes retornam imediatamente (
{}), garantindo zero latência adicional durante o diálogo. - Ao concluir com sucesso, o script emite uma notificação efêmera informando a IA sobre a sincronização na branch
master.
3. Resiliência e Fallback Offline
A atualização do submódulo nunca deve interromper ou impedir o atendimento ao operador:
- Se o ambiente estiver sem acesso à internet, com DNS indisponível ou falha temporária de rede, o script captura o erro graciosamente.
- O agente emite um aviso no log/contexto informando que a sincronização remota não pôde ser completada e prossegue normalmente a execução com a versão local já presente no submódulo.
Proibições
- NUNCA travar o submódulo
.agentem branches experimentais ou desatualizadas sem autorização explícita do operador. - NUNCA abortar a sessão ou falhar com crash caso a rede esteja indisponível para atualização remota.
- NUNCA executar
git submodule update --remotedescartando alterações locais em desenvolvimento sem verificação prévia.
Referências
- Rule:
rules/autonomia-agente.md - Rule:
rules/identidade-modulo.md - Script:
.agent/scripts/atualizar-submodulo.sh - Hook:
.agent/hooks.json - Script:
.agent/validar-setup.sh