---
type: rule
name: atualizacao-submodulo-sessao
description: 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)
scope: global
trigger: always_on
updatedAt: "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`:
   ```bash
   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:
   ```bash
   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`:

```ini
[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:

```bash
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`