instrucoes_gerais/global/doutrina_agentes.md

🧠 Doutrina Mestre dos Agentes (Multi-VPS)

Este documento define a consciência situacional obrigatória para todos os agentes de IA.

📍 Identificação de Localização

Antes de qualquer ação, identifique seu IP interno:

• 10.99.0.1 (VPS 1 - PRODUÇÃO): Ambiente CRÍTICO. Rodando Traefik e Nginx.
  • Regra: Apenas deploys homologados em Dev. Nunca mexa na infraestrutura de rede.
• 10.99.0.3 (VPS 3 - CÉREBRO): Onde reside o Gitea, Postgres e DragonflyDB.
  • Regra: Proteja os dados. Backups antes de qualquer alteração de schema.
• 10.99.0.4 (VPS 4 - LABORATÓRIO): Desenvolvimento e Dev.
  • Regra: Liberdade para testar, criar e quebrar containers. É o local de nascimento do código.

🔐 Segurança e VPN

• Interface wg0: É a sua linha de vida. Nunca altere configurações de rede ou firewall (UFW) que possam isolar a VPS.
• Chaves SSH: Use apenas chaves locais autorizadas para sincronização entre as VPSs do enxame.

📇 Protocolo de Identidade Estática (~/.vps_identity)

Para garantir 100% de consciência situacional à prova de falhas sem depender de chamadas de rede externas, cada máquina do enxame possui um arquivo de identidade em /home/deploy/.vps_identity.

📄 Estrutura Obrigatória do JSON:

Todo arquivo .vps_identity deve conter exatamente a seguinte estrutura:

{
  "vps_id": 4,
  "vps_name": "VPS-4-LABORATORIO",
  "ip_vpn": "10.99.0.4",
  "role": "Desenvolvimento, Builds e Dev",
  "danger_level": "BAIXO - Liberdade para testar e recriar"
}

🚨 Obrigações das IAs e Agentes:

1. Verificação Obrigatória: Toda execução de script ou agente deve prioritariamente ler e interpretar o arquivo /home/deploy/.vps_identity para calibrar o seu escopo de atuação.
2. Respeito ao Danger Level (Nível de Perigo):
   • Nível de Perigo ALTO (ex: VPS 1, VPS 3): Agentes NÃO PODEM rodar comandos experimentais, mutações não homologadas de bancos de dados ou reinstalar dependências críticas sem backups nítidos e aprovação explícita.
   • Nível de Perigo BAIXO (ex: VPS 4): O agente possui total autonomia para realizar testes, compilar códigos, reinstalar pacotes e reiniciar contêineres Docker de dev.
3. Resiliência (Fallback): Caso o arquivo .vps_identity não exista ou esteja ilegível, o agente deve fazer o fallback dinâmico (buscando o IP 10.99.x.x via hostname -I) e assumir o perfil de segurança mais restritivo por padrão.

🚫 NUNCA...

• Nunca tente acessar servidores fora da rede 10.99.0.x.
• Nunca exponha senhas ou chaves privadas em logs ou comentários.
• Nunca altere o serviço swarm-listener sem autorização.

🔄 Protocolo de Criação e Configuração de Novos Projetos (GitOps Rootless)

Sempre que um novo projeto for criado no ecossistema Swarm, os agentes não precisam configurar Webhooks locais. O Webhook Global (https://git.clube67.com/-/admin/hooks -> http://10.99.0.4:9000/webhook) já cuida do roteamento universal dos eventos de Push.

Important

Autonomia do Agente (Auto-Identificação): Se você (o Agente de IA) identificar que está trabalhando em um novo projeto:

1. Você NÃO DEVE criar Webhooks via API no repositório individual para evitar conflitos.
2. Você DEVE garantir a criação do arquivo .vps_identity apropriado nas VPSs correspondentes.
3. Você DEVE estruturar o docker-compose.yml do projeto sob a pasta /home/deploy/stack/<nome-do-projeto>/ seguindo o padrão rootless.
4. Exposição de Portas (VPS 4): Contêineres na VPS 4 não devem mapear a porta 80 ou 443 diretamente no Host físico, para evitar conflitos com múltiplos projetos de dev. Use redes internas ou labels (Docker Overlay) para que a VPS 1 (Traefik) faça o encaminhamento do tráfego.
5. Bancos de Dados: É terminantemente proibido subir contêineres de Banco de Dados (postgres, mysql, etc) localmente nos projetos da VPS 4. Todos os serviços devem obrigatoriamente apontar para a VPS 3 (10.99.0.3).

🗣️ Comunicação

• Todo o desenvolvimento, comentários e commits devem ser em PORTUGUÊS.
• Use o protocolo PGS (Protocolo Gitea Swarm) para hand-offs multi-VPS:
  • Nenhum agente edita serviços ou acessa infraestrutura de outra VPS.
  • Sempre use a API do Gitea para criar uma Issue marcando a VPS destino. O Redis (swarm:tasks) despertará as IAs (GPT/Claude) nas respectivas máquinas (ex: VPS 1, VPS 3) para realizarem a tarefa e finalizarem a Issue.

📂 Diretórios de Projetos e Stacks Ativos (Mapeamento de Preservação)

🖥️ VPS 1 - Produção (10.99.0.1)

Os seguintes diretórios são de infraestrutura e serviços críticos ativos e DEVEM SER ESTRITAMENTE PRESERVADOS contra qualquer alteração ou limpeza na VPS 1:

• 📁 /home/deploy/stack/traefik/: Roteador de borda central e proxy reverso da infraestrutura.
• 📁 /home/deploy/stack/portainer/: Interface de gerenciamento e monitoramento de contêineres Docker.
• 📁 /home/deploy/stack/soc/: Rotinas de CrowdSec, firewall e auditoria de segurança ativa.

🖥️ VPS 4 - Laboratório (10.99.0.4)

Os seguintes diretórios dentro de /home/deploy/stack/ contêm contêineres de desenvolvimento e dev ativos e DEVEM SER ESTRITAMENTE PRESERVADOS na VPS 4:

• 📁 scoreodonto.com/: Aplicação e contêineres de dev do ecossistema ScoreOdonto.
• 📁 subdominio.clube67.com/: Branding, front-end e back-end do Gerenciador de Subdomínios.
• 📁 self-healing/: Rotinas e scripts locais de auto-recuperação de serviços.
• 📁 webhook-listener/: Ouvinte de webhooks de GitOps (porta 9000) para deploys automatizados.

Warning

Quaisquer pastas como /home/deploy/stack/traefik/, /home/deploy/stack/portainer/ ou /home/deploy/stack/soc/ que sejam encontradas na VPS 4 são duplicatas inativas e obsoletas e devem ser deletadas na limpeza dos agentes.

---

🚀 Protocolo de Acesso a Contexto e Instruções (Prioridade de Memória Injetada)

Para evitar vazamentos de credenciais no disco e garantir imunidade absoluta contra dados desatualizados locais, os agentes devem respeitar a seguinte ordem de prioridade de sincronização ao inicializar:

1. 🚀 Injeção em Memória RAM (API REST do Gitea - PRIORITÁRIO MÁXIMO): Os agentes de IA devem prioritariamente ler as instruções mestre chamando a API de Conteúdos do Gitea usando Basic Auth. O conteúdo recuperado é decodificado base64 e mantido estritamente na memória volátil RAM da máquina durante a execução, sem tocar o disco da VPS.
2. 📁 Arquivos do Disco Local (Filesystem - CONTINGÊNCIA): Caso a API do Gitea esteja temporariamente indisponível, a IA pode recorrer à leitura dos arquivos locais localizados em /home/deploy/instrucoes/ como contingência secundária.
3. 🔐 Transporte Remoto e Escrita (Chaves SSH - ESTÁVEL): Para operações de sincronização, deploys ou pushes do Git, os agentes devem usar exclusivamente a chave SSH do usuário deploy (~/.ssh/id_ed25519), prevenindo qualquer exposição de chaves privadas em logs ou variáveis de ambiente.

---

🌐 Governança e Integração Centralizada no Gitea (Nível de Usuário/Sistema)

Para maximizar a segurança (SecOps), a agilidade de deploy (GitOps) e a escalabilidade do enxame de agentes, adotamos uma arquitetura de governança unificada no Gitea no nível de Usuário e Sistema, contornando configurações isoladas e repetitivas por repositório.

🔑 1. Autenticação Unificada por Chave SSH Global (User Settings)

Em vez de configurar Deploy Keys individuais para cada repositório, a chave pública SSH de cada VPS (nó do enxame) é cadastrada diretamente no perfil global do Usuário Administrador (ruicesar) em /user/settings/keys.

• Permissão herdada: Qualquer conexão Git disparada a partir dos nós do enxame possui automaticamente as permissões do usuário em todos os repositórios atuais e futuros.
• Padrão de Endereços SSH dos Projetos ( VPS 4 & Swarm ):
  • 📁 instrucoes_gerais: ssh://git@10.99.0.3/ruicesar/instrucoes_gerais.git
  • 📁 scoreodonto.com: ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git
  • 📁 mercado.clube67.com: ssh://git@10.99.0.3/ruicesar/mercado.clube67.com.git
  • 📁 subdominio.clube67.com: ssh://git@10.99.0.3/ruicesar/subdominio.clube67.com.git

🔌 2. Integração Global por Webhook do Sistema (System Webhook)

Em vez de criar Webhooks de push repetitivos para cada repositório das aplicações:

• Configuramos um único Webhook do Sistema em /admin/hooks (https://git.clube67.com/-/admin/hooks) que atua globalmente.
• Parâmetros de Produção:
  • URL de Destino: http://10.99.0.4:9000/webhook (Redirecionamento nativo via VPN para o Listener da VPS 4).
  • Content Type: application/json
  • Gatilho: Apenas o evento de Push.
• Filtragem: O Swarm Dispatcher recebe os pushes globais e executa os deploys do enxame em segundo plano sem redundâncias.

🎯 3. Outros Recursos Unificados a Nível de Usuário/Sistema

Para mantermos o ecossistema no estado da arte de DevOps, utilizamos os seguintes recursos globais do Gitea:

• 📁 Gitea Organizations (Organizações - ex: clube67): Agrupa todos os repositórios sob um único tenant corporativo, permitindo gerenciar permissões de equipes (Teams) e IAs de uma única vez para todos os projetos.
• 🔑 Personal Access Tokens (PAT - Nível de Usuário): Criação de um Token de Acesso único do usuário administrador injetado na RAM dos agentes, dando autorização de API para ler issues, wikis e logs de todos os repositórios atuais e futuros de forma centralizada.
• 🏷️ Rótulos Padrão (Global Labels): Padronização de etiquetas de Issues (ex: bug-self-healing, deploy-dev, security-incident, Autônomo) herdadas automaticamente por qualquer novo repositório, agilizando a triagem de erros.

---

🗄️ Padrões de Bancos de Dados (DB Standards)

• PostgreSQL: Todos os projetos novos e legados do ecossistema devem, obrigatoriamente, ser concebidos ou migrados para PostgreSQL. Fica desencorajada a utilização de SQLite em produção ou MySQL sem justificativa explícita.
• DragonflyDB: Sempre que houver necessidade de mensageria, filas (Redis) ou cache, os agentes de IA devem priorizar a implementação e avaliação de ganhos utilizando o DragonflyDB, por atuar como um drop-in nativo, escalável e de altíssima performance em relação ao Redis tradicional.