vlv-code/scan-meta-project

Repository-Meta-Knowledge-Integritätsscanner (Scan Meta-Project)

Operatives Skill zur Durchführung schneller Express-Scans oder tiefergehender Integritätsaudits eines bestehenden Meta-Projekt-Setups ohne destruktive Neuinitialisierung.

Das Skill arbeitet in zwei Modi:

• --shallow (Express-Sanity-Check): Überprüft Existenz und Nicht-Leere der Wurzeldatei AGENTS.md, der 5 Wissens-Slices, führt Boundary Gate (check_boundaries.py --audit-tree) für 100% Dateiabdeckung durch und prüft die Aktualität der Aufgaben.
• --deep (Kern-Tiefenprüfung & Drift-Erkennung): Führt alle flachen Prüfungen aus, ruft die Core Inspection Checklist für Schlüsselmodule auf, delegiert die Komponenten-/Datenfluss-Synchronisation an sync-architecture, auditieret technische Schulden in weak_spots.md und führt lokale Integrationstests durch.

---

Wann das Skill aufgerufen werden sollte

• Der Benutzer fordert: "scan-meta-project", "scan meta project", "инспекция мета-знаний", "чекни покрытие", "audit meta-knowledge", "check boundaries coverage", "найди слепые зоны", "verify slices".
• Vor der Freigabeprüfung (Pre-Release), bei PR-Reviews oder bei Wiederaufnahme der Entwicklung nach umfangreichen Änderungen außerhalb der agentischen Sitzung.
• Automatisch von init-meta-project am Ende der Initialisierung aufgerufen.
• Primäre zugewiesene Rolle: agent-quality-guardian (in Compact Trio Topologie) oder agent-meta-guardian (in erweiterter Rollentopologie), oder direkter Aufruf durch den Benutzer.

---

Ausführungsschritte

Phase 1: Modusbestimmung & Zielauflösung

1. Identifiziere den Aufrufmodus aus der Benutzeraufforderung oder verwende standardmäßig --shallow:
   • --shallow: Routinemäßiger Integritätscheck, Boundary-Abdeckungsvalidierung, Aufgabenaktualität.
   • --deep: Vollständige Architekturdrift-Erkennung, Core Inspection Checklist, Testausführung.
2. Lokalisiere das Boundary-Gate-Skript:
   • Bevorzuge .agents/scripts/check_boundaries.py (Ziel-Repository-Layout).
   • Fallback auf scripts/check_boundaries.py (Meta-Projekt-Layout).
   • Wenn keines der Skripte existiert, überprüfe die Boundaries manuell anhand der Glob-Muster in boundaries.md.

---

Phase 2: Flache Prüfung (--shallow)

1. Passport-Integrität:
   • Überprüfe das Vorhandensein der Wurzeldatei AGENTS.md.
   • Stelle sicher, dass Abschnitt 1 North Stars und Invarianten enthält (Circuit Breaker, Default Deny).
   • Stelle sicher, dass die Abschnitte 2, 3, 4, 5 ohne Platzhalter-Tags ({{...}}) ausgefüllt sind.
2. Wissens-Slices-Audit:
   • Überprüfe die 5 kanonischen Slices in .agents/project_knowledge/:
     • architecture.md (Komponenten und Datenflüsse).
     • boundaries.md (Verantwortungsbereiche).
     • weak_spots.md (Fragile Module und Risiken).
     • observations.md (5-spaltige Beobachtungstabelle).
     • tasks.md (Aktuelles Ziel und Checklisten).
3. Boundary-Abdeckung (Zero Unmapped Dirs Rule):
   • Führe das automatisierte Boundary-Gate-Audit aus:

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

   • Wenn ungemappte Dateien oder Verzeichnisse gemeldet werden, behandle sie als Black-Zone-Verstöße. Markiere sie sofort für die Aufnahme in boundaries.md.
4. Aufgabenregister-Prüfung (tasks.md):
   • Überprüfe, ob das aktive Ziel klar ist und abgeschlossene Elemente mit - [x] markiert sind.

---

Phase 3: Tiefenprüfung (--deep)

Wenn mit --deep ausgeführt, führt der Agent alle Prüfungen der Phase 2 durch, gefolgt von:

1. Core Inspection Checklist (Schlüsselmodule):
   • Datenbank & Speicher: Lese primäre Modell-/Repository-Dateien. Überprüfe Schema-Kopplung, Migrationen und monolithisches Wachstum.
   • Externe Clients & APIs: Lese Integrationen (AI SDKs, HTTP-Clients). Überprüfe Timeout-Einstellungen, Circuit Breaker und Fehlerweitergabe.
   • Containerisierung & CI: Lese Dockerfile, docker-compose*.yml, .github/workflows/. Überprüfe Build-Matrix und Sicherheitsflags.
   • Einstiegspunkte & UI: Lese Hauptrouter, CLI-Einstiegspunkte und Befehlshandler. Überprüfe Plattform-Payload-Einschränkungen und Eingabevalidierung.
2. Architekturdrift-Erkennung (Delegation an sync-architecture):
   • Dupliziere NIEMALS benutzerdefinierte Codelogik zur Analyse. Rufe das prozedurale Skill sync-architecture auf:
     • sync-architecture führt einen Pre-Flight Preservation aller local_repo_data-Blöcke durch.
     • Aktualisiert .agents/project_knowledge/architecture.md mit aktuellen Komponenten und End-to-End-Datenflüssen.
3. Risiko- & Schulden-Neukalibrierung (weak_spots.md):
   • Überprüfe vorhandene Einträge in weak_spots.md: Wenn eine zuvor aufgezeichnete technische Schuld behoben ist, markiere sie als behoben oder entferne sie.
   • Wenn während der Core Inspection neue fragile Kopplungen oder architektonische Engpässe entdeckt wurden, zeichne sie auf.
4. Automatische Testausführung:
   • Führe die Testsuite des Projekts mit Standard-Test-Erkennung aus:

     python -m unittest discover -s tests -p "test_*.py" -v
     # Oder Stack-spezifischer Läufer (z. B. pytest, npm test, cargo test)
     

---

Phase 4: Opportunistische Aktualisierung & Bericht

1. Nachfüllen identifizierter Lücken (Lesen + Opportunistische Aktualisierung):
   • Schreibe atomar entdeckte ungemappte Pfade in boundaries.md (innerhalb von <!-- local_repo_data:boundaries -->).
   • Aktualisiere tasks.md mit neuen Unteraufgaben oder abgeschlossenen Meilensteinen.
   • Zeichne neu aufgelöste Umgebungsbesonderheiten in observations.md auf.
2. Scan-Bericht ausgeben: Präsentiere dem Benutzer eine prägnante Zusammenfassung:

   ### 🔍 Scan-Bericht (Meta-Projekt-Scanner)
   - **Modus:** `--shallow` | `--deep`
   - **Passport & Slices:** 5/5 Slices vorhanden, AGENTS.md gültig
   - **Boundary-Abdeckung:** 100% gemappt (oder N ungemappte Pfade erkannt)
   - **Architekturdrift:** Synchron (oder aktualisiert via sync-architecture)
   - **Identifizierte Aktionspunkte:** [Liste von 1–3 konkreten Empfehlungen, falls vorhanden]