vlv-code/scan-meta-project

Scanner de Integridade do Meta-Conhecimento do Repositório (Scan Meta-Project)

Skill operacional para realizar varreduras rápidas ou auditorias de integridade profundas de uma configuração de meta-projeto existente sem reinicialização destrutiva.

A skill opera em dois modos:

• --shallow (Verificação Rápida de Sanidade): Verifica a existência e não-vazio do AGENTS.md raiz, 5 fatias de conhecimento, executa o Gate de Limites (check_boundaries.py --audit-tree) para cobertura de 100% de arquivos e verifica a atualidade das tarefas.
• --deep (Imersão Profunda e Verificação de Desvio): Executa todas as verificações superficiais, invoca a Lista de Verificação de Inspeção Principal nos módulos de execução chave, delega a sincronização de componentes/fluxos de dados para sync-architecture, audita dívida técnica em weak_spots.md e executa testes de integridade locais.

---

Quando invocar a skill

• O usuário solicita: "scan-meta-project", "scan meta project", "инспекция мета-знаний", "чекни покрытие", "audit meta-knowledge", "check boundaries coverage", "найди слепые зоны", "verify slices".
• Verificação pré-lançamento, revisões de PR ou retomada do desenvolvimento após alterações extensas feitas fora da sessão agêntica.
• Invocada automaticamente por init-meta-project ao final da inicialização.
• Função designada primária: agent-quality-guardian (na topologia Compact Trio) ou agent-meta-guardian (na topologia de função expandida), ou invocação direta pelo usuário.

---

Etapas de execução

Fase 1: Determinação do Modo e Resolução do Alvo

1. Identificar o modo de invocação a partir do prompt do usuário ou usar --shallow como padrão:
   • --shallow: Verificação de integridade de rotina, validação de cobertura de limites, atualidade das tarefas.
   • --deep: Detecção completa de desvios arquiteturais, Lista de Verificação de Inspeção Principal, execução de testes.
2. Localizar o script do Gate de Limites:
   • Preferir .agents/scripts/check_boundaries.py (layout do repositório alvo).
   • Fallback para scripts/check_boundaries.py (layout do meta-projeto).
   • Se nenhum script existir, verificar limites manualmente contra os padrões glob em boundaries.md.

---

Fase 2: Inspeção Superficial (--shallow)

1. Integridade do Passaporte:
   • Verificar a presença do AGENTS.md na raiz.
   • Garantir que a Seção 1 contenha Estrelas do Norte e invariantes (Circuit Breaker, Default Deny).
   • Garantir que as Seções 2, 3, 4, 5 estejam preenchidas sem tags de espaço reservado ({{...}}).
2. Auditoria de Fatias de Conhecimento:
   • Verificar as 5 fatias canônicas em .agents/project_knowledge/:
     • architecture.md (componentes e fluxos de dados).
     • boundaries.md (zonas de responsabilidade).
     • weak_spots.md (módulos frágeis e riscos).
     • observations.md (tabela de observações de 5 colunas).
     • tasks.md (objetivo ativo e checklists).
3. Cobertura de Limites (Regra de Zero Diretórios Não Mapeados):
   • Executar a auditoria automatizada do Gate de Limites:

     python .agents/scripts/check_boundaries.py --audit-tree
     # Fallback: python scripts/check_boundaries.py --audit-tree
     

   • Se quaisquer arquivos ou diretórios não mapeados forem relatados, tratá-los como violações da Zona Preta. Sinalizá-los imediatamente para inclusão em boundaries.md.
4. Verificação do Registro de Tarefas (tasks.md):
   • Verificar se o objetivo ativo está claro e os itens concluídos estão marcados com - [x].

---

Fase 3: Inspeção Profunda (--deep)

Quando executado com --deep, o agente executa todas as verificações da Fase 2, seguidas por:

1. Lista de Verificação de Inspeção Principal (Módulos Chave):
   • Banco de Dados e Armazenamento: Ler os principais arquivos de modelo/repositório. Inspecionar acoplamento de esquema, migrações e crescimento monolítico.
   • Clientes Externos e APIs: Ler integrações (SDKs de IA, clientes HTTP). Verificar configurações de timeout, circuit breakers e propagação de erros.
   • Conteinerização e CI: Ler Dockerfile, docker-compose*.yml, .github/workflows/. Verificar matriz de build e flags de segurança.
   • Entrypoints e UI: Ler roteadores principais, entrypoints de CLI e manipuladores de comando. Verificar restrições de payload da plataforma e validação de entrada.
2. Detecção de Desvio Arquitetural (Delegação para sync-architecture):
   • NÃO duplicar a lógica personalizada de análise de código. Invocar a skill procedural sync-architecture:
     • sync-architecture realiza a Preservação Pré-Voo de todos os blocos local_repo_data.
     • Atualiza .agents/project_knowledge/architecture.md com componentes atuais e Fluxos de Dados Ponta a Ponta.
3. Recalibração de Risco e Dívida (weak_spots.md):
   • Verificar itens existentes em weak_spots.md: se uma dívida técnica registrada anteriormente foi resolvida, marcá-la como resolvida ou removê-la.
   • Se novos acoplamentos frágeis ou gargalos arquiteturais forem descobertos durante a Inspeção Principal, registrá-los.
4. Execução de Testes Automatizados:
   • Executar o conjunto de testes do projeto usando descoberta de teste padrão:

     python -m unittest discover -s tests -p "test_*.py" -v
     # Ou executor específico da stack (ex.: pytest, npm test, cargo test)
     

---

Fase 4: Atualização Oportunística e Relatório

1. Preenchimento de Lacunas Identificadas (Leitura + Atualização Oportunística):
   • Escrever atomicamente os caminhos não mapeados descobertos em boundaries.md (dentro do bloco <!-- local_repo_data:boundaries -->).
   • Atualizar tasks.md com novas subtarefas ou marcos concluídos.
   • Registrar peculiaridades de ambiente recém-resolvidas em observations.md.
2. Entregar Relatório de Varredura: Apresentar um resumo conciso ao usuário:

   ### 🔍 Relatório de Varredura (Scanner de Meta-Projeto)
   - **Modo:** `--shallow` | `--deep`
   - **Passaporte e Fatias:** 5/5 fatias presentes, AGENTS.md válido
   - **Cobertura de Limites:** 100% mapeado (ou N caminhos não mapeados detectados)
   - **Desvio Arquitetural:** Sincronizado (ou atualizado via sync-architecture)
   - **Itens de Ação Identificados:** [Lista de 1–3 recomendações concretas, se houver]