vlv-code/scan-meta-project

Inspecteur d'Intégrité des Méta-Connaissances du Dépôt (Scan Meta-Project)

Compétence opérationnelle pour effectuer des analyses rapides ou des audits d'intégrité approfondis d'une configuration meta-projet existante, sans réinitialisation destructive.

La compétence fonctionne en deux modes :

• --shallow (Vérification rapide) : Vérifie l'existence et le non-vide de la racine AGENTS.md, des 5 tranches de connaissance, exécute la Boundary Gate (check_boundaries.py --audit-tree) pour une couverture à 100 % des fichiers, et vérifie la fraîcheur des tâches.
• --deep (Inspection approfondie et détection de dérive) : Exécute toutes les vérifications du mode --shallow, invoque la Checklist d'Inspection Core sur les modules d'exécution clés, délègue la synchronisation composants/flux de données à sync-architecture, audite la dette technique dans weak_spots.md, et exécute les tests d'intégrité locaux.

---

Quand invoquer la compétence

• L'utilisateur demande : "scan-meta-project", "scan meta project", "inspection des méta-connaissances", "vérifie la couverture", "audit meta-knowledge", "check boundaries coverage", "trouve les zones aveugles", "verify slices".
• Vérification pré-livraison, relectures de PR, ou reprise du développement après des modifications importantes effectuées en dehors de la session agentique.
• Invoquée automatiquement par init-meta-project à la fin de l'initialisation.
• Rôle principal désigné : agent-quality-guardian (dans la topologie Compact Trio) ou agent-meta-guardian (dans la topologie étendue), ou invocation directe par l'utilisateur.

---

Étapes d'exécution

Phase 1 : Détermination du mode et résolution de la cible

1. Identifier le mode d'invocation à partir de la demande utilisateur ou par défaut --shallow :
   • --shallow : Vérification d'intégrité de routine, validation de la couverture des limites, fraîcheur des tâches.
   • --deep : Détection complète de la dérive architecturale, Checklist d'Inspection Core, exécution des tests.
2. Localiser le script Boundary Gate :
   • Privilégier .agents/scripts/check_boundaries.py (structure du dépôt cible).
   • Repli sur scripts/check_boundaries.py (structure meta-projet).
   • Si aucun script n'existe, vérifier manuellement les limites par rapport aux motifs glob dans boundaries.md.

---

Phase 2 : Inspection superficielle (--shallow)

1. Intégrité du Passeport :
   • Vérifier la présence de la racine AGENTS.md.
   • S'assurer que la Section 1 contient les North Stars et les invariants (Circuit Breaker, Default Deny).
   • S'assurer que les Sections 2, 3, 4, 5 sont remplies sans balises d'espace réservé ({{...}}).
2. Audit des Tranches de Connaissance :
   • Vérifier les 5 tranches canoniques dans .agents/project_knowledge/ :
     • architecture.md (composants et flux de données).
     • boundaries.md (zones de responsabilité).
     • weak_spots.md (modules fragiles et risques).
     • observations.md (tableau d'observations à 5 colonnes).
     • tasks.md (objectif actif et listes de contrôle).
3. Couverture des Limites (Règle Zero Répertoire Non Mappé) :
   • Exécuter l'audit automatisé de la Boundary Gate :

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

   • Si des fichiers ou répertoires non mappés sont signalés, les traiter comme des violations de Zone Noire. Les signaler immédiatement pour inclusion dans boundaries.md.
4. Vérification du Registre des Tâches (tasks.md) :
   • Vérifier que l'objectif actif est clair et que les éléments terminés sont marqués par - [x].

---

Phase 3 : Inspection approfondie (--deep)

Lorsqu'il est exécuté avec --deep, l'agent exécute toutes les vérifications de la Phase 2, suivies de :

1. Checklist d'Inspection Core (Modules Clés) :
   • Base de données et Stockage : Lire les fichiers principaux de modèle/dépôt. Inspecter le couplage des schémas, les migrations et la croissance monolithique.
   • Clients Externes et API : Lire les intégrations (AI SDKs, clients HTTP). Vérifier les paramètres de timeout, les circuit breakers et la propagation des erreurs.
   • Conteneurisation et CI : Lire Dockerfile, docker-compose*.yml, .github/workflows/. Vérifier la matrice de build et les indicateurs de sécurité.
   • Points d'entrée et UI : Lire les routeurs principaux, les points d'entrée CLI et les gestionnaires de commandes. Vérifier les contraintes de payload de la plateforme et la validation des entrées.
2. Détection de Dérive Architecturale (Délégation à sync-architecture) :
   • Ne PAS dupliquer la logique personnalisée d'analyse de code. Invoquer la compétence procédurale sync-architecture :
     • sync-architecture effectue une Sauvegarde Pré-Vol de tous les blocs local_repo_data.
     • Met à jour .agents/project_knowledge/architecture.md avec les composants actuels et les Flux de Données de Bout en Bout.
3. Recalibrage des Risques et de la Dette (weak_spots.md) :
   • Vérifier les éléments existants dans weak_spots.md : si une dette technique précédemment enregistrée est résolue, la marquer comme résolue ou la supprimer.
   • Si de nouveaux couplages fragiles ou goulots d'étranglement architecturaux ont été découverts lors de l'Inspection Core, les enregistrer.
4. Exécution Automatisée des Tests :
   • Exécuter la suite de tests du projet en utilisant la découverte de test standard :

     python -m unittest discover -s tests -p "test_*.py" -v
     # Ou exécuteur spécifique à la pile (ex. pytest, npm test, cargo test)
     

---

Phase 4 : Rafraîchissement Opportuniste et Rapport

1. Combler les Lacunes Identifiées (Lecture + Rafraîchissement Opportuniste) :
   • Écrire atomiquement les chemins non mappés découverts dans boundaries.md (dans <!-- local_repo_data:boundaries -->).
   • Mettre à jour tasks.md avec de nouvelles sous-tâches ou des jalons atteints.
   • Enregistrer les particularités d'environnement nouvellement résolues dans observations.md.
2. Rapport d'Analyse : Présenter un résumé concis à l'utilisateur :

   ### 🔍 Rapport d'Analyse (Scanner Meta-Project)
   - **Mode :** `--shallow` | `--deep`
   - **Passeport et Tranches :** 5/5 tranches présentes, AGENTS.md valide
   - **Couverture des Limites :** 100 % mappé (ou N chemins non mappés détectés)
   - **Dérive Architecturale :** Synchronisé (ou mis à jour via sync-architecture)
   - **Actions Identifiées :** [Liste de 1 à 3 recommandations concrètes, le cas échéant]