feat(submodule): atualizar submodulo .agent na branch master ao iniciar sessao

global/rules/atualizacao-submodulo-sessao.md

@@ -0,0 +1,80 @@
+# 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** compartilhado entre múltiplos repositórios e produtos (`quipo`, `e-licencie`, `sigma`, etc.). Novas regras, personas, correções de ferramentas (como isolamento de sessão do `agent-browser` 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`

global/rules/autonomia-agente.md

@@ -29,6 +29,7 @@ O agente pode executar sem perguntar:
 - Aplicar padrões de nomenclatura já definidos em rules
 - Executar `git add`, `git commit`, `git push` e resolver conflitos diretamente na branch `master` no repositório da Wiki (`<base_projeto>/../wiki` ou `wiki/`) ao criar ou atualizar documentações
 - Executar `git commit` na aplicação principal em branches de trabalho (criando compulsoriamente uma nova branch caso o repositório esteja na `master`)
+- Atualizar o submódulo `.agent` ao iniciar uma sessão executando `git submodule update --init --recursive --remote` na branch `master`
 
 ## Ações que Requerem Confirmação
 

global/rules/identidade-modulo.md

@@ -67,7 +67,8 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
 2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
 3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
 4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;
-5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia.
+5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
+6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`.
 
 👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
 
@@ -83,6 +84,7 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
 
 ## Referências
 
+- Rule: `global/rules/atualizacao-submodulo-sessao.md`
 - Rule: `global/rules/ddd-documentacao-primeiro.md`
 - Rule: `global/rules/regras-negocio-md.md`
 - Rule: `global/rules/testes-interface-agent-browser.md`

global/skills/onboarding-projeto/SKILL.md

@@ -22,14 +22,22 @@ flowchart LR
 
 ---
 
-## PASSO 1 — Adicionar o Submódulo `.agent`
+## PASSO 1 — Adicionar e Configurar o Submódulo `.agent` na Branch Master
 
 Na raiz do repositório do novo projeto:
 
 ```bash
-git submodule add https://git2.idz.one/publico/.agent.git.agent
+# Adicionar rastreando explicitamente a branch master
+git submodule add -b master https://git2.idz.one/publico/.agent.git .agent
+git submodule update --init --recursive --remote
 ```
 
+> 💡 **Repositórios existentes:** Caso o submódulo já esteja adicionado, garanta o rastreamento da branch `master`:
+> ```bash
+> git submodule set-branch --branch master .agent
+> git submodule update --init --recursive --remote
+> ```
+
 ---
 
 ## PASSO 2 — Configurar a Identidade do Módulo (`memorias-ia/modulo.yml`)