🧠 Doutrina Mestre dos Agentes (Multi-VPS) - Versão v1.0.3 (Atual)

Note

Histórico de Atualização (Versão v1.0.3 - 17/05/2026):

Protocolo de Auto-Configuração de Novos Projetos: Inserida a obrigatoriedade de criação automática do Webhook de Deploy (http://127.0.0.1:5000/webhook) na API do Gitea caso o agente identifique que se trata de um novo projeto, prevenindo falhas de GitOps.

Versão v1.0.2 (17/05/2026): Micro-segmentação de Firewall (SecOps Hardening) na VPS 3.

Versão v1.0.1 (17/05/2026): Hardening de terminal (.bash_logout) e carregamento dinâmico JIT via API REST do Gitea.

Versão v1.0.0 (16/05/2026): Primeira versão consolidada e estruturada das diretrizes.

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 Staging. 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 Staging.
- 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 Staging",
  "danger_level": "BAIXO - Liberdade para testar e recriar"
}

🚨 Obrigações das IAs e Agentes:

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.
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 staging.
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 (Auto-Config de Webhook)

Sempre que um novo projeto for criado no ecossistema Swarm, os agentes e desenvolvedores devem seguir e configurar automaticamente a seguinte rotina de integração de CI/CD para que o GitOps funcione perfeitamente:

1. Criação Obrigatória do Webhook de Deploy

Todo novo repositório criado no Gitea DEVE possuir um Webhook de deploy ativo configurado da seguinte forma:

URL de Destino: http://10.99.0.3:5000/webhook (Se configurado externamente) ou http://127.0.0.1:5000/webhook (Se configurado de dentro da VPS 3).
Tipo de Conteúdo: application/json
Segredo (Secret): Em branco ou chave secreta padrão.
Eventos que disparam: Apenas o evento de Push (Commit enviado).

Important

Autonomia do Agente (Auto-Identificação): Se você (o Agente de IA) identificar que está trabalhando em um novo projeto ou que o repositório do projeto atual não possui o webhook do Swarm Dispatcher (http://127.0.0.1:5000/webhook) configurado no Gitea:

Você DEVE usar a API REST do Gitea para criar ou corrigir esse webhook automaticamente.

Você DEVE garantir a criação do arquivo .vps_identity apropriado nas VPSs correspondentes.

Você DEVE estruturar o docker-compose.yml do projeto sob a pasta /home/deploy/stack/<nome-do-projeto>/ seguindo o padrão rootless.

🗣️ Comunicação

Todo o desenvolvimento, comentários e commits devem ser em PORTUGUÊS.
Use o protocolo PGS (Protocolo Gitea Swarm) para hand-offs.

📂 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 staging ativos e DEVEM SER ESTRITAMENTE PRESERVADOS na VPS 4:

📁 scoreodonto.com/: Aplicação e contêineres de staging 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.