vlv-code/scan-meta-project

Escáner de Integridad de Meta-Conocimiento del Repositorio (Scan Meta-Project)

Habilidad operativa para realizar escaneos rápidos o auditorías de integridad profundas de una configuración de meta-proyecto existente sin reinicialización destructiva.

La habilidad opera en dos modos:

• --shallow (Verificación Rápida de Cordura): Verifica la existencia y no vacío de AGENTS.md raíz, 5 slices de conocimiento, ejecuta Boundary Gate (check_boundaries.py --audit-tree) para cobertura del 100% de archivos, y comprueba la frescura de tareas.
• --deep (Inmersión Profunda y Detección de Desviación): Ejecuta todas las comprobaciones superficiales, invoca la Lista de Verificación de Inspección Central en módulos runtime clave, delega la sincronización de componentes/flujo de datos a sync-architecture, audita deuda técnica en weak_spots.md y ejecuta pruebas de integridad locales.

---

Cuándo invocar la habilidad

• El usuario solicita: "scan-meta-project", "escanear meta proyecto", "инспекция мета-знаний", "chéckame cobertura", "auditar meta-conocimiento", "verificar cobertura de límites", "найди слепые зоны", "verificar slices".
• Verificación previa a lanzamiento, revisiones de PR, o reanudación del desarrollo después de cambios extensos realizados fuera de la sesión agéntica.
• Invocada automáticamente por init-meta-project al concluir la inicialización.
• Rol designado principal: agent-quality-guardian (en topología Compact Trio) o agent-meta-guardian (en topología de roles expandida), o invocación directa por el usuario.

---

Pasos de ejecución

Fase 1: Determinación del Modo y Resolución del Objetivo

1. Identificar el modo de invocación a partir del prompt del usuario o por defecto --shallow:
   • --shallow: Verificación de integridad rutinaria, validación de cobertura de límites, frescura de tareas.
   • --deep: Detección completa de desviación arquitectónica, Lista de Verificación de Inspección Central, ejecución de pruebas.
2. Localizar el script Boundary Gate:
   • Preferir .agents/scripts/check_boundaries.py (estructura del repositorio objetivo).
   • Alternativa: scripts/check_boundaries.py (estructura del meta-proyecto).
   • Si ninguno existe, verificar límites manualmente contra los patrones glob de boundaries.md.

---

Fase 2: Inspección Superficial (--shallow)

1. Integridad del Pasaporte:
   • Verificar presencia de AGENTS.md raíz.
   • Asegurar que la Sección 1 contiene North Stars e invariantes (Circuit Breaker, Default Deny).
   • Asegurar que las Secciones 2, 3, 4, 5 están pobladas sin marcadores de posición ({{...}}).
2. Auditoría de Slices de Conocimiento:
   • Verificar los 5 slices canónicos en .agents/project_knowledge/:
     • architecture.md (componentes y flujos de datos).
     • boundaries.md (zonas de responsabilidad).
     • weak_spots.md (módulos frágiles y riesgos).
     • observations.md (tabla de observaciones de 5 columnas).
     • tasks.md (objetivo activo y listas de verificación).
3. Cobertura de Límites (Regla de Cero Directorios no Mapeados):
   • Ejecutar la auditoría automatizada de Boundary Gate:

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

   • Si se reportan archivos o directorios no mapeados, tratarlos como violaciones de Zona Negra. Señalarlos inmediatamente para su inclusión en boundaries.md.
4. Verificación del Registro de Tareas (tasks.md):
   • Verificar que el objetivo activo esté claro y que los elementos completados estén marcados con - [x].

---

Fase 3: Inspección Profunda (--deep)

Cuando se ejecuta con --deep, el agente ejecuta todas las comprobaciones de la Fase 2, seguidas de:

1. Lista de Verificación de Inspección Central (Módulos Clave):
   • Base de Datos y Almacenamiento: Leer archivos del modelo/repositorio principal. Inspeccionar acoplamiento de esquemas, migraciones y crecimiento monolítico.
   • Clientes Externos y APIs: Leer integraciones (SDKs de IA, clientes HTTP). Verificar configuraciones de timeout, circuit breakers y propagación de errores.
   • Contenedorización y CI: Leer Dockerfile, docker-compose*.yml, .github/workflows/. Verificar matriz de compilación y banderas de seguridad.
   • Puntos de Entrada e IU: Leer routers principales, puntos de entrada CLI y manejadores de comandos. Verificar restricciones de payload de plataforma y validación de entrada.
2. Detección de Desviación Arquitectónica (Delegación a sync-architecture):
   • NO duplicar lógica personalizada de análisis de código. Invocar la habilidad procedimental sync-architecture:
     • sync-architecture realiza Preservación Pre-Vuelo de todos los bloques local_repo_data.
     • Actualiza .agents/project_knowledge/architecture.md con componentes actuales y Flujos de Datos Extremo a Extremo.
3. Re-calibración de Riesgo y Deuda (weak_spots.md):
   • Verificar elementos existentes en weak_spots.md: si una deuda técnica previamente registrada está resuelta, marcarla como resuelta o eliminarla.
   • Si se descubrieron nuevos acoplamientos frágiles o cuellos de botella arquitectónicos durante la Inspección Central, registrarlos.
4. Ejecución Automatizada de Pruebas:
   • Ejecutar el conjunto de pruebas del proyecto usando detección estándar de pruebas:

     python -m unittest discover -s tests -p "test_*.py" -v
     # O ejecutor específico del stack (ej. pytest, npm test, cargo test)
     

---

Fase 4: Actualización Oportunista e Informe

1. Relleno de Brechas Identificadas (Lectura + Actualización Oportunista):
   • Escribir atómicamente las rutas no mapeadas descubiertas en boundaries.md (dentro de <!-- local_repo_data:boundaries -->).
   • Actualizar tasks.md con nuevas subtareas o hitos completados.
   • Registrar peculiaridades de entorno recién resueltas en observations.md.
2. Entregar el Informe de Escaneo: Presentar un resumen conciso al usuario:

   ### 🔍 Informe de Escaneo (Escáner de Meta-Proyecto)
   - **Modo:** `--shallow` | `--deep`
   - **Pasaporte y Slices:** 5/5 slices presentes, AGENTS.md válido
   - **Cobertura de Límites:** 100% mapeado (o N rutas no mapeadas detectadas)
   - **Desviación Arquitectónica:** En sincronía (o actualizado vía sync-architecture)
   - **Elementos de Acción Identificados:** [Lista de 1 a 3 recomendaciones concretas, si las hay]