.agent/rules/atualizacao-submodulo-sessao.md

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 e verificação diária do runtime Bun (bun upgrade --stable)	global	always_on	2026-10-30

Regra: Atualização Obrigatória do Submódulo .agent ao Iniciar Sessão e Verificação Diária do Bun

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

Além disso, todo o ecossistema utiliza o Bun como runtime e gerenciador de pacotes padrão. Trabalhar com uma versão defasada do submódulo .agent ou do runtime bun faz com que o agente tome decisões baseadas em regras antigas, falhe em auditorias de setup ou enfrente incompatibilidades de runtime. Por isso, a sincronização do submódulo na branch master (a cada sessão) e a verificação de atualização do Bun na versão estável (uma vez por dia) são mandatórias.

---

Regra Mandatória de Inicialização e Manutenção Diária

1. Sincronização por Sessão do .agent: 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
   

2. Verificação Diária do Runtime Bun (1x por dia): Uma vez por dia, o ambiente DEVE verificar se o Bun está atualizado na versão estável mais recente executando:

   bun upgrade --stable
   

Ambas as operações são classificadas como ações autônomas (conforme rules/autonomia-agente.md) e não requerem 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:

1. No início da conversa, o hook aciona o script .agent/scripts/atualizar-submodulo.sh.
2. Idempotência Diária do Bun (1x por dia): O script verifica o arquivo de controle /tmp/.antigravity_bun_upgrade_date (formato YYYY-MM-DD). Caso ainda não tenha sido verificado na data atual, executa bun upgrade --stable e grava a data do dia no arquivo de controle. Execuções subsequentes no mesmo dia ignoram o comando com zero latência.
3. Idempotência de Sessão do .agent (1x por conversa): O script detecta a raiz do projeto pai (superprojeto) e verifica a existência da trava temporária da sessão (/tmp/.antigravity_agent_updated_${conversationId}). A sincronização remota do submódulo é executada apenas no primeiro turno da sessão, retornando imediatamente ({}) nos turnos seguintes.
4. Ao concluir com sucesso, o script emite uma notificação efêmera informando a IA sobre a sincronização na branch master e, quando executada no dia, o resultado da atualização do Bun.

---

3. Resiliência e Fallback Offline

A atualização do submódulo e a verificação diária do Bun nunca devem 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 ou verificação do Bun não pôde ser completada e prossegue normalmente a execução com as versões locais já presentes.

---

Proibições

• NUNCA travar o submódulo .agent em branches experimentais ou desatualizadas sem autorização explícita do operador.
• NUNCA atualizar o Bun para versões canary/instáveis automaticamente (utilizar sempre --stable).
• NUNCA abortar a sessão ou falhar com crash caso a rede esteja indisponível para atualização remota.
• NUNCA executar git submodule update --remote descartando 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