89 lines
4 KiB
Markdown
89 lines
4 KiB
Markdown
---
|
|
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
|
|
scope: global
|
|
trigger: always_on
|
|
updatedAt: "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`:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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. 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}`).
|
|
3. **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.
|
|
4. 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 `.agent` em 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 --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`
|