@noyrax/documentation-system-plugin 1.0.4-beta.3 → 1.0.4-beta.4

package/docs/adr/025-mcp-tools-scan-validate-cli-bridge.md

@@ -1,202 +0,0 @@
-# ADR-025: MCP-Server Tools Scan/Validate – CLI-Bridge-Pattern
-
-**Status:** Implementiert  
-**Datum:** 2025-12-12
-
-## Kontext
-
-Die MCP-Server Tools `validation/runScan` und `validation/runValidate` versuchten, nicht-existierende npm-Scripts (`npm run scan` und `npm run validate`) aufzurufen. Dies führte zu Fehlern:
-
-```
-Command failed: npm run scan
-npm error Missing script: "scan"
-```
-
-**Architektur-Konflikt:**
-- `mcp/` ist separates ESM-Package (`"type": "module"`, `"module": "NodeNext`)
-- `src/` ist Teil der Extension (CommonJS, VS Code APIs)
-- Direkte Imports von `mcp/` nach `src/` funktionieren nicht:
-  - TypeScript kann `../../src/` nicht auflösen (außerhalb von `mcp/tsconfig.json` include)
-  - Module-System-Mismatch (CommonJS vs ESM)
-  - VS Code API-Abhängigkeiten in Extension-Funktionen
-
-**Bestehende Lösung:**
-- `runDriftCheck` verwendet `git` CLI-Tool (externes Tool)
-- Keine direkten Imports von `src/`
-- Konsistentes Pattern: MCP-Tools rufen externe CLI-Tools auf
-
-## Entscheidung
-
-### CLI-Bridge-Pattern implementieren
-
-**Strategie:** CLI-Tools im Root-Projekt erstellen, die von MCP-Tools via npm-Scripts aufgerufen werden.
-
-### 1. CLI-Tools erstellt
-
-**Dateien:**
-- `src/cli/scan-cli.ts` - Scan-Tool ohne VS Code APIs
-- `src/cli/validate-cli.ts` - Validate-Tool ohne VS Code APIs
-
-**Implementierung:**
-- Importieren Kern-Funktionen aus `src/core/scanner.ts` und `src/validator/index.ts`
-- Keine VS Code API-Abhängigkeiten
-- JSON-Output für einfaches Parsing
-- CLI-Argument-Parsing für Optionen
-
-**Funktionalität:**
-- `scan-cli.ts`: 
-  - Ruft `scanWorkspace()` auf
-  - Parst Dateien mit Parsern (TsJsParser, JsonYamlParser, PythonParser)
-  - Extrahiert Symbole
-  - Gibt strukturiertes JSON zurück
-  
-- `validate-cli.ts`:
-  - Ruft `scanWorkspace()` und Parser auf
-  - Ruft `computeCoverage()` und `validateMarkdownDir()` auf
-  - Berechnet Coverage-Metriken
-  - Gibt strukturierte Fehler/Warnungen zurück
-
-### 2. npm-Scripts hinzugefügt
-
-**Datei:** `package.json`
-
-**Scripts:**
-```json
-"scan:cli": "node out/cli/scan-cli.js",
-"validate:cli": "node out/cli/validate-cli.js"
-```
-
-**Hinweis:** Verwenden kompilierte Versionen (`out/cli/`) statt TypeScript direkt, da `ts-node` nicht als Dependency vorhanden ist.
-
-### 3. MCP-Tools aktualisiert
-
-**Dateien:**
-- `mcp/src/tools/scan.ts` - Ruft `npm run scan:cli` auf, parst JSON-Output
-- `mcp/src/tools/validate.ts` - Ruft `npm run validate:cli` auf, parst JSON-Output
-
-**Änderungen:**
-- Ersetzen `npm run scan` → `npm run scan:cli`
-- Ersetzen `npm run validate` → `npm run validate:cli`
-- JSON-Parsing statt Text-Parsing (strukturierte Daten)
-- Fallback auf Text-Parsing für Rückwärtskompatibilität
-
-## Konsequenzen
-
-### Positive
-
-- **Konsistentes Pattern:** Gleiche Strategie wie `runDriftCheck` (externe Tools)
-- **Keine Import-Probleme:** CLI-Tools können von `src/` importieren (gleiches Projekt)
-- **Strukturierte Daten:** JSON-Output statt Freitext-Parsing
-- **Wiederverwendbar:** CLI-Tools können auch direkt verwendet werden
-- **Keine VS Code Abhängigkeiten:** CLI-Tools funktionieren außerhalb von VS Code
-- **Einfache Wartung:** Logik zentralisiert in CLI-Tools
-
-### Negative
-
-- **Zusätzliche Dateien:** 2 neue CLI-Tools zu pflegen
-- **Build-Schritt erforderlich:** CLI-Tools müssen kompiliert werden (`npm run compile`)
-- **npm-Script-Abhängigkeit:** MCP-Tools benötigen npm im PATH
-- **Performance:** Child-Process-Overhead (aber akzeptabel)
-
-### Technische Details
-
-**Import-Pfade:**
-- CLI-Tools verwenden relative Imports: `../core/scanner`, `../validator/index`
-- Funktioniert, da CLI-Tools Teil von `src/` sind
-- Kompiliert zu `out/cli/` mit korrekten relativen Pfaden
-
-**Module-System:**
-- CLI-Tools kompilieren zu CommonJS (`tsconfig.json`: `"module": "commonjs"`)
-- Werden von Node.js direkt ausgeführt
-- Keine ESM/CommonJS-Konflikte
-
-**Output-Format:**
-- JSON für strukturierte Daten
-- Einfaches Parsing in MCP-Tools
-- Fallback auf Text-Parsing für Fehlerfälle
-
-## Alternativen
-
-### Alternative 1: Direkte Imports von mcp/ nach src/
-
-**Verworfen:** 
-- TypeScript kann `../../src/` nicht auflösen
-- Module-System-Mismatch (ESM vs CommonJS)
-- VS Code API-Abhängigkeiten würden Probleme verursachen
-
-### Alternative 2: Gemeinsames Package erstellen
-
-**Verworfen:**
-- Zu komplex für diese Aufgabe
-- Würde große Refactoring-Erfordernis bedeuten
-- Nicht notwendig für diese Lösung
-
-### Alternative 3: CLI-Tool in packages/doc-system-agent/
-
-**Verworfen:**
-- `packages/doc-system-agent/` kann auch nicht direkt von `src/` importieren
-- Gleiche Import-Probleme wie bei mcp/
-- Root-Projekt ist besserer Ort für CLI-Tools
-
-### Alternative 4: TypeScript-Paths in mcp/tsconfig.json
-
-**Verworfen:**
-- Würde Module-System-Mismatch nicht lösen
-- Komplexe Konfiguration erforderlich
-- CLI-Bridge-Pattern ist einfacher und konsistenter
-
-## Implementierung
-
-### Geänderte Dateien
-
-**NEU:**
-- `src/cli/scan-cli.ts` - Scan-CLI-Tool
-- `src/cli/validate-cli.ts` - Validate-CLI-Tool
-
-**AKTUALISIERT:**
-- `package.json` - Scripts `scan:cli` und `validate:cli` hinzugefügt
-- `mcp/src/tools/scan.ts` - Ruft `npm run scan:cli` auf (bereits aktualisiert)
-- `mcp/src/tools/validate.ts` - Ruft `npm run validate:cli` auf (bereits aktualisiert)
-
-### Test-Ergebnisse
-
-**CLI-Tools:**
-- ✅ `scan-cli.ts` kompiliert erfolgreich
-- ✅ `validate-cli.ts` kompiliert erfolgreich
-- ✅ `npm run scan:cli` funktioniert: 99 Dateien verarbeitet, 406 Symbole extrahiert
-- ✅ `npm run validate:cli` funktioniert: Gibt strukturierte Fehler/Warnungen zurück
-
-**MCP-Tools:**
-- ✅ `mcp/src/tools/scan.ts` ruft korrekt `npm run scan:cli` auf
-- ✅ `mcp/src/tools/validate.ts` ruft korrekt `npm run validate:cli` auf
-- ✅ JSON-Parsing implementiert
-- ✅ MCP-Server kompiliert erfolgreich
-
-### Validierung
-
-- ✅ Build-Tests: CLI-Tools kompilieren erfolgreich
-- ✅ Funktions-Tests: CLI-Tools geben korrektes JSON zurück
-- ✅ MCP-Integration: Tools können CLI-Tools aufrufen
-- ✅ Konsistenz: Gleiches Pattern wie `runDriftCheck`
-
-## Verweise
-
-- **ADR-014:** Rules-Migration und MCP-Integration (MCP-Server Einführung)
-- **ADR-024:** Cursor Rules Überarbeitung (MCP-Server Resource-Definitionen)
-- `.cursor/ARCHITECTURE_ANALYSIS.md` - Architektur-Analyse
-- `.cursor/MCP_TOOLS_TEST_RESULTS.md` - Test-Ergebnisse
-
-## Nächste Schritte
-
-1. **Performance-Optimierung:** Bei Bedarf Caching für wiederholte Scans
-2. **Erweiterte Optionen:** Weitere CLI-Argumente für spezifische Use-Cases
-3. **Dokumentation:** CLI-Tools in README dokumentieren
-4. **Integrationstest:** MCP-Tools mit Cursor testen
-
-## Lessons Learned
-
-- **CLI-Bridge-Pattern:** Effektive Lösung für Module-System-Konflikte
-- **Konsistenz:** Gleiche Patterns wie bestehende Tools verwenden (`runDriftCheck`)
-- **Architektur-Analyse:** Systematische Analyse vor Implementierung verhindert Fehler
-- **Import-Probleme:** Relative Pfade zwischen separaten Packages funktionieren nicht ohne Konfiguration
-

package/docs/adr/026-reality-driven-development-system.md

@@ -1,173 +0,0 @@
-# ADR-026: Reality-Driven Development System
-
-**Status:** Implementiert  
-**Datum:** 2025-12-12
-
-## Kontext
-
-Cursor (und andere AI-Agenten) halluzinieren manchmal, indem sie:
-- Dokumentation lesen
-- Annehmen, dass sie stimmt
-- Code basierend auf Annahmen generieren
-- "Fertig!" sagen ohne Verification
-
-**Problem:** Es gab keine systematische Verification-Loop, die Agenten daran hindert, Code zu implementieren ohne Reality-Checks.
-
-**Beispiel:** 
-- ADR sagt "X ist implementiert"
-- Agent nimmt es an
-- Code generiert basierend auf Annahme
-- Fehler entstehen, weil X tatsächlich nicht existiert
-
-## Entscheidung
-
-### Reality-Driven Development System implementieren
-
-**Grundprinzip:** Code ist die einzige Wahrheitsquelle. Dokumentation und ADRs können veraltet sein oder Pläne beschreiben, nicht die Realität.
-
-**Strategie:** System-enforced Verification-Loops, die Agenten zwingen, Reality-Checks durchzuführen bevor, während und nach der Implementierung.
-
-### 1. Neue Cursor Rule: `026-reality-driven-verification.mdc`
-
-**Zweck:** Explizite Verification-Loop vor/nach Implementierung
-
-**Inhalt:**
-- **BEFORE Implementation:** Reality-Checks (grep, ls, cat, compile)
-- **DURING Implementation:** Incremental Verification (compile sofort, test sofort)
-- **AFTER Implementation:** End-to-End Verification (vollständiger Workflow-Test)
-- **Evidence-basierte Claims:** Nie "Ich habe X implementiert" ohne Beweis
-
-**Integration:**
-- Ergänzt `001-pre-check.mdc` mit expliziten Verification-Schritten
-- Ergänzt `023-pre-planning.mdc` mit Verification-Commands zu jeder Checkliste
-
-### 2. Verification-Scripts
-
-**Dateien:**
-- `scripts/verify-architecture.js` - Architektur-Regeln prüfen (Imports, Zyklen)
-- `scripts/verify-adrs.js` - ADR-Claims gegen Code prüfen (Dateien, Funktionen)
-- `scripts/verify-imports.js` - Import-Verfügbarkeit prüfen (Exports, Pfade)
-
-**Funktionalität:**
-- Automatische Prüfung von Architektur-Regeln
-- ADR-Claim-Verification gegen tatsächlichen Code
-- Import-Verfügbarkeit-Checks
-
-### 3. Automation
-
-**Pre-Commit Hook (`.husky/pre-commit`):**
-- Architektur-Verification
-- ADR-Verification (non-blocking)
-- Compile-Check
-
-**GitHub Actions (`.github/workflows/verification.yml`):**
-- CI/CD Reality-Checks
-- Architektur-Verification
-- ADR-Verification
-- Build-Verification
-- CLI-Tools-Test
-- MCP-Server-Test
-
-**VS Code Tasks (`.vscode/tasks.json`):**
-- "Verify Before Commit" (Default Build Task)
-- "Quick Verification"
-- "Verify ADR Claims"
-- "Verify Architecture"
-- "Verify Imports"
-
-### 4. Documentation
-
-**`.cursorrules` Datei:**
-- Cursor-spezifische Reality-Driven Instructions
-- Verification-Commands für PowerShell und Bash
-- Evidence-basierte Claims-Patterns
-
-**ADR-Template erweitert (`docs/adr/TEMPLATE.md`):**
-- "Implementation Claims" Sektion (verifizierbare Claims)
-- "Verification Report" Sektion (nach Implementierung ausfüllen)
-- Verification-Commands-Beispiele
-
-**package.json Scripts erweitert:**
-- `verify:all` - Alle Verification-Checks
-- `verify:architecture` - Architektur-Checks
-- `verify:adrs` - ADR-Checks
-- `verify:imports` - Import-Checks
-
-## Auswirkungen
-
-### Positive Auswirkungen
-
-- **Verhindert Halluzinationen:** Agenten können nicht mehr Code implementieren ohne Reality-Checks
-- **System-enforced Verification:** Pre-Commit Hooks und CI/CD erzwingen Verification
-- **Evidence-basierte Claims:** Agenten müssen Beweise für ihre Claims bereitstellen
-- **ADR-Verification:** ADR-Claims werden automatisch gegen Code geprüft
-- **Konsistenz:** Verification-Patterns sind überall gleich (Rules, Scripts, Automation)
-
-### Technische Auswirkungen
-
-- **3 Verification-Scripts:** `verify-architecture.js`, `verify-adrs.js`, `verify-imports.js`
-- **Pre-Commit Hook:** Automatische Verification vor jedem Commit
-- **GitHub Actions:** CI/CD Reality-Checks
-- **VS Code Tasks:** Development-Workflow Verification
-- **`.cursorrules`:** Cursor-spezifische Instructions
-
-### Wartbarkeit
-
-- **Zentrale Rules:** Verification-Patterns in `026-reality-driven-verification.mdc`
-- **Automatisierte Checks:** Scripts können erweitert werden
-- **CI/CD Integration:** Verification läuft automatisch bei jedem Push/PR
-
-## Implementierung
-
-### Geänderte Dateien
-
-1. **Cursor Rules:**
-   - `.cursor/rules/026-reality-driven-verification.mdc` - **NEU**
-   - `.cursor/rules/001-pre-check.mdc` - **ERWEITERT**
-   - `.cursor/rules/023-pre-planning.mdc` - **ERWEITERT**
-
-2. **Verification-Scripts:**
-   - `scripts/verify-architecture.js` - **NEU**
-   - `scripts/verify-adrs.js` - **NEU**
-   - `scripts/verify-imports.js` - **NEU**
-
-3. **Automation:**
-   - `.husky/pre-commit` - **NEU**
-   - `.github/workflows/verification.yml` - **NEU**
-   - `.vscode/tasks.json` - **NEU**
-
-4. **Documentation:**
-   - `.cursorrules` - **NEU**
-   - `docs/adr/TEMPLATE.md` - **ERWEITERT**
-   - `package.json` - Scripts erweitert
-
-### Test-Ergebnisse
-
-- ✅ Verification-Scripts funktionieren
-- ✅ Pre-Commit Hook erkannt (muss noch initialisiert werden: `npx husky install`)
-- ✅ GitHub Actions Workflow erstellt
-- ✅ VS Code Tasks erstellt
-- ✅ `.cursorrules` erstellt
-- ✅ ADR-Template erweitert
-
-## Verweise
-
-- **ADR-024:** Cursor Rules Überarbeitung (Vorläufer)
-- **ADR-025:** MCP-Server Tools CLI-Bridge-Pattern (Verification-Pattern)
-- `.cursor/REALITY_DRIVEN_PLAN.md` - Implementierungsplan
-
-## Nächste Schritte
-
-1. **Husky initialisieren:** `npx husky install` (für Pre-Commit Hook)
-2. **System testen:** Intentionale Fehler einbauen, Verification-Checks prüfen
-3. **Monitoring:** Prüfen, ob Agenten die neuen Rules korrekt nutzen
-4. **Performance:** Bei Bedarf Verification-Scripts optimieren
-5. **Dokumentation:** Verification-Workflow in README dokumentieren
-
-## Lessons Learned
-
-- **Verification-Loops sind kritisch:** Agenten müssen systematisch Reality-Checks durchführen
-- **System-enforced ist besser:** Automation erzwingt Verification besser als nur Rules
-- **Evidence-basierte Claims:** Agenten müssen Beweise für ihre Claims bereitstellen
-- **ADR-Verification:** ADR-Claims sollten automatisch gegen Code geprüft werden
-

package/docs/adr/027-scanner-excludes-and-union-logic-fix.md

@@ -1,189 +0,0 @@
-# ADR-027: Scanner-Excludes und Union-Logik Fix
-
-**Status:** Implementiert  
-**Datum:** 2025-12-12
-
-## Kontext
-
-**Problem:** Der Symbol-Index enthielt 444 Symbole, aber es wurden nur 434 beim Scan gefunden. Die Differenz kam von alten Symbolen aus Verzeichnissen, die nicht mehr gescannt werden sollten:
-
-- `demo/` - Demo-Projekt (laut `.gitignore` ausgeschlossen)
-- `website/` - Website-Projekt (laut `.gitignore` ausgeschlossen)
-- `mcp/` - MCP-Server (laut `tsconfig.json` exclude)
-- `packages/` - Packages (laut `tsconfig.json` exclude)
-- `action/` - GitHub Action (laut `tsconfig.json` exclude)
-
-**Ursache:** 
-1. Der Scanner (`src/core/scanner.ts`) scannte diese Verzeichnisse trotz `.gitignore`, weil die `ignore`-Bibliothek nur Dateien filtert, nicht Verzeichnisse beim Walken
-2. Die Union-Logik (`buildSymbolsUnion`) behielt alte Symbole von Dateien, die nicht mehr gescannt wurden, weil sie nicht als "gelöscht" markiert waren
-
-**Symptom:** 
-- Index enthielt Symbole aus `demo/package.json`, `website/package.json`, etc.
-- Diese Symbole wurden nicht mehr beim Scan gefunden
-- Union-Logik behielt sie trotzdem, weil die Dateien noch existierten (nur nicht mehr gescannt)
-
-## Entscheidung
-
-### 1. Scanner-Excludes erweitert
-
-**Datei:** `src/core/scanner.ts`
-
-**Änderung:** `DEFAULT_EXCLUDES` erweitert um:
-- `demo` - Demo-Projekt (laut .gitignore)
-- `website` - Website-Projekt (laut .gitignore)
-- `mcp` - MCP-Server (laut tsconfig.json exclude)
-- `packages` - Packages (laut tsconfig.json exclude)
-- `action` - GitHub Action (laut tsconfig.json exclude)
-
-**Grund:** Diese Verzeichnisse werden explizit beim Walken ausgeschlossen, bevor die `ignore`-Bibliothek sie filtert. Dadurch werden sie gar nicht erst gescannt.
-
-### 2. Union-Logik angepasst
-
-**Datei:** `src/core/consolidation.ts`
-
-**Änderung:** `buildSymbolsUnion()` erhält optionalen Parameter `scannedFiles?: Set<string>`
-
-**Logik:**
-- Behält nur Symbole von Dateien, die beim aktuellen Scan gefunden wurden
-- Entfernt automatisch Symbole aus Dateien, die nicht mehr gescannt werden (z.B. ausgeschlossene Verzeichnisse)
-- Prüft: `if (scannedFiles && !scannedFiles.has(sym.filePath)) continue;`
-
-**Grund:** Die Union-Logik sollte nur Symbole von Dateien behalten, die beim aktuellen Scan gefunden wurden. Dateien, die nicht mehr gescannt werden (z.B. wegen Excludes), sollten als "gelöscht" behandelt werden.
-
-### 3. Extension angepasst
-
-**Datei:** `src/extension.ts`
-
-**Änderung:** Übergibt `scannedFilesSet` an `buildSymbolsUnion()`:
-```typescript
-const scannedFilesSet = new Set<string>(scanned.map(f => f.repositoryRelativePath));
-const symbolsUnion = buildSymbolsUnion(
-    allSymbols,
-    symbolsPrev,
-    parsedFiles,
-    deletedFilesFromGit,
-    scannedFilesSet
-);
-```
-
-**Grund:** Stellt sicher, dass die Union-Logik weiß, welche Dateien beim aktuellen Scan gefunden wurden.
-
-## Implementation Claims
-
-### Files Modified
-- [x] `src/core/scanner.ts` - DEFAULT_EXCLUDES erweitert
-- [x] `src/core/consolidation.ts` - buildSymbolsUnion() angepasst
-- [x] `src/extension.ts` - scannedFilesSet übergeben
-
-### Functions Modified
-- [x] `buildSymbolsUnion()` in `src/core/consolidation.ts` - Optionaler Parameter `scannedFiles` hinzugefügt
-- [x] `generateDocumentationTs()` in `src/extension.ts` - scannedFilesSet erstellt und übergeben
-
-### Verification Commands
-```bash
-# Verify DEFAULT_EXCLUDES erweitert
-Select-String -Path src/core/scanner.ts -Pattern "demo|website|mcp|packages|action"  # PowerShell
-grep "demo\|website\|mcp\|packages\|action" src/core/scanner.ts                      # Bash
-
-# Verify buildSymbolsUnion angepasst
-Select-String -Path src/core/consolidation.ts -Pattern "scannedFiles"  # PowerShell
-grep "scannedFiles" src/core/consolidation.ts                          # Bash
-
-# Verify extension angepasst
-Select-String -Path src/extension.ts -Pattern "scannedFilesSet"  # PowerShell
-grep "scannedFilesSet" src/extension.ts                          # Bash
-
-# Verify it compiles
-npm run compile
-
-# Verify scan funktioniert
-npm run scan:cli
-```
-
-## Verification Report
-
-**Verification Date:** 2025-12-12
-
-**Results:**
-- [x] All files modified: YES
-- [x] All functions modified: YES
-- [x] Compiles without errors: YES
-- [x] Scan funktioniert: YES
-- [x] VSIX neu erstellt: YES
-
-**Evidence:**
-```
-✅ DEFAULT_EXCLUDES erweitert:
-   Select-String -Path src/core/scanner.ts -Pattern "demo|website|mcp|packages|action"
-   → Gefunden: 'demo', 'website', 'mcp', 'packages', 'action' in DEFAULT_EXCLUDES
-
-✅ buildSymbolsUnion angepasst:
-   Select-String -Path src/core/consolidation.ts -Pattern "scannedFiles"
-   → Gefunden: Parameter und Logik für scannedFiles
-
-✅ Extension angepasst:
-   Select-String -Path src/extension.ts -Pattern "scannedFilesSet"
-   → Gefunden: scannedFilesSet wird erstellt und übergeben
-
-✅ Compiles: npm run compile → Success
-
-✅ Scan funktioniert: npm run scan:cli → {"status":"success","filesProcessed":80,"symbolsExtracted":281}
-
-✅ VSIX neu erstellt: npm run package → noyrax-1.0.4.vsix (4.68 MB)
-```
-
-**Vorher/Nachher Vergleich:**
-- **Vorher:** 123 Dateien gescannt, 448 Symbole gefunden, 444 im Index (inkl. alte Symbole aus demo/, website/, etc.)
-- **Nachher:** 80 Dateien gescannt, 281 Symbole gefunden, Index wird beim nächsten Lauf korrekt neu generiert
-
-## Auswirkungen
-
-### Positive Auswirkungen
-
-- **Korrekte Symbol-Anzahl:** Index enthält nur noch Symbole aus tatsächlich gescannten Dateien
-- **Konsistenz:** Scanner-Excludes sind konsistent mit `.gitignore` und `tsconfig.json`
-- **Automatische Bereinigung:** Union-Logik entfernt automatisch Symbole aus nicht mehr gescannten Verzeichnissen
-- **Wartbarkeit:** Neue ausgeschlossene Verzeichnisse werden automatisch aus dem Index entfernt
-
-### Technische Auswirkungen
-
-- **Scanner:** Verarbeitet weniger Dateien (80 statt 123), schneller
-- **Union-Logik:** Prüft jetzt explizit, ob Dateien beim Scan gefunden wurden
-- **Index:** Wird beim nächsten Lauf automatisch bereinigt (alte Symbole entfernt)
-
-### Wartbarkeit
-
-- **Neue Excludes:** Einfach zu `DEFAULT_EXCLUDES` hinzufügen
-- **Union-Logik:** Funktioniert automatisch für alle ausgeschlossenen Verzeichnisse
-- **Konsistenz:** Scanner-Excludes sollten mit `.gitignore` und `tsconfig.json` synchronisiert bleiben
-
-## Konsequenzen
-
-### Was einfacher wird
-
-- **Index-Bereinigung:** Automatisch, keine manuelle Bereinigung nötig
-- **Konsistenz:** Scanner-Excludes sind explizit dokumentiert
-- **Performance:** Weniger Dateien zu scannen
-
-### Was zu beachten ist
-
-- **Neue Verzeichnisse:** Wenn neue Verzeichnisse ausgeschlossen werden sollen, müssen sie zu `DEFAULT_EXCLUDES` hinzugefügt werden
-- **Index-Regenerierung:** Beim ersten Lauf nach dieser Änderung wird der Index neu generiert (alte Symbole entfernt)
-- **VSIX:** Muss neu erstellt werden, um die Änderungen zu enthalten
-
-## Verweise
-
-- **Verwandte ADRs:**
-  - ADR-009: Consolidation Union-Logic (Phase 1.2) - Union-Logik eingeführt
-  - ADR-010: Extension Union-Integration (Phase 1.3 + Phase 2) - Union-Logik in Extension integriert
-  - ADR-026: Reality-Driven Development System - Verification-Loops
-
-- **Code-Referenzen:**
-  - `src/core/scanner.ts` - Scanner-Implementierung
-  - `src/core/consolidation.ts` - Union-Logik
-  - `src/extension.ts` - Extension-Hauptlogik
-
-- **Dokumentation:**
-  - `.gitignore` - Ausgeschlossene Verzeichnisse
-  - `tsconfig.json` - TypeScript-Excludes
-

package/docs/adr/028-src-coverage-union-resync.md

@@ -1,124 +0,0 @@
-# ADR-028: Vollständige `src`-Abdeckung, Union-Logik & Resync-Strategie
-
-## Status
-
-- Status: Accepted  
-- Datum: 2025-12-15
-
-## Kontext
-
-Das Documentation-System-Plugin generiert mehrere Artefakte aus dem Code:
-
-- `docs/modules/*.md` – Modul-Dokumentation pro Datei  
-- `docs/index/symbols.jsonl` – Symbol-Index (eine Zeile pro Symbol)  
-- `docs/system/DEPENDENCIES.md` & `docs/system/DEPENDENCY_GRAPH.md` – Abhängigkeitsübersicht und -Graph  
-- `docs/system/CHANGE_REPORT.md` – Änderungsreport  
-- `docs/.cache/*` – Caches für AST-Hashes, Signaturen, Output-Hashes, Dependencies
-
-Der Scan-Scope wird durch `scanWorkspace` in `src/core/scanner.ts` definiert. Der Validator bewertet die Qualität der generierten Doku mit:
-
-- Coverage-Schwellen aus `package.json` (`noyrax.coverageThresholds.*`)  
-- Signatur-Matching (`src/validator/signature-matching.ts`)  
-- Status-Berechnung (`computeValidationStatus` in `src/validator/status.ts`)
-
-Die Generate-Pipeline (`generateDocumentationTs` in `src/extension.ts`) arbeitet **inkrementell**:
-
-1. `scanWorkspace` → Liste aller scannbaren Dateien (`scannedAll`)  
-2. Optionaler Git-Diff → gefilterte Teilmenge (`scanned`)  
-3. AST-Cache (`loadAstHashCache`) → „unchanged“ Dateien werden nicht neu geparst  
-4. Parser (`TsJsParser`, `JsonYamlParser`, `PythonParser`) → neue Symbole & Dependencies (`allSymbols`, `allDependencies`)  
-5. Union-Bildung (`buildDependenciesUnionWithDebug`, `buildSymbolsUnion`)  
-6. Generierung von:
-   - `docs/modules/*` via `generatePerFileDocs`  
-   - `docs/index/symbols.jsonl` via `buildIndexFromSymbols` / `writeJsonlIndex`  
-   - `DEPENDENCIES.md` & `DEPENDENCY_GRAPH.md` via `generateDependencyOverview` / `generateMermaidGraph`
-
-Im ursprünglichen Zustand wurde für `buildSymbolsUnion` die Menge `scannedFiles` aus der Git-/Cache-gefilterten Teilmenge `scanned` abgeleitet – nicht aus dem vollen Scan-Scope `scannedAll`.
-
-## Problem
-
-1. **Symbole verschwinden inkrementell aus dem Index**, obwohl Dateien noch existieren:
-   - In Läufen mit sehr kleinem `scanned` (z. B. 14 Dateien, alle „unchanged“) wurden keine neuen Symbole erzeugt (`allSymbols.length === 0`).
-   - `scannedFilesSet` wurde aus `scanned` gebaut.  
-   - `buildSymbolsUnion` entfernt alle alten Symbole aus Dateien, die nicht in `scannedFilesSet` liegen – sie gelten wie „nicht mehr gescannt“ bzw. „deleted“.
-   - Ergebnis: Von zuvor 267 Symbolen im Index blieben nur noch ~92 übrig, obwohl der Workspace in Wirklichkeit 400+ Symbole enthielt.
-
-2. **Scope-Erweiterung auf weitere produktive Verzeichnisse**:
-   - Der Scanner schließt standardmäßig mehrere Top-Level-Verzeichnisse aus (`demo`, `website`, `mcp`, `packages`, `action`, `docs`, `out`, `dist` etc.).
-   - Für das tatsächliche Produktivsystem (`src/` + `packages/` + `mcp` + `action`) bedeutet das:
-     - Wenn diese Verzeichnisse ausgeschlossen sind, fehlen Symbole im Index, in den Modul-Dokus und im Dependency-Graph.
-
-3. **Veraltete Artefakte und Caches**:
-   - In `docs/modules`, `docs/index/symbols.jsonl`, `docs/system/*` und `.cache` lagen ältere Stände.
-   - Neue Läufe auf Basis eines geänderten Scopes (z. B. geöffnete Verzeichnisse) kombinierten alte und neue Informationen → Coverage- und Status-Anzeigen wurden „schief“.
-
-4. **Validator-Status ROT bei reinen Coverage-Problemen**:
-   - `computeCoverage` generiert Fehlerstrings, wenn Coverage-Schwellen (`classes`, `interfaces`, `methods`, `functions`) unterschritten werden.
-   - `computeValidationStatus` behandelt diese Coverage-Errors wie echte Fehler und setzt den Gesamtstatus auf „red“, auch wenn:
-     - keine Signatur-Abweichungen existieren und  
-     - keine Markdown-Fehler vorliegen.
-
-## Entscheidung
-
-1. **Scanner-Scope für produktiven Code**
-
-   - `scanWorkspace` bleibt der zentrale Mechanismus, um produktiven Code zu bestimmen:
-     - `src/` inklusive `core`, `cli`, `cache`, `drift`, `index`, `logging`, `parsers`, `ui`, `validator` wird vollständig gescannt.
-     - Zusätzlich werden `packages/`, `mcp/` und `action/` als produktive Quellverzeichnisse verstanden und in den Scan einbezogen.
-   - Sensible oder irrelevante Bereiche (z. B. `node_modules`, `.git`, `docs`, `out`, `dist`, Backups, `.ai-agent-context`, `.env`-Dateien) bleiben explizit ausgeschlossen.
-
-2. **Union-Logik an den vollen Scan-Scope binden**
-
-   - Für `buildSymbolsUnion` wird `scannedFiles` aus **`scannedAll`** abgeleitet – nicht aus der ggf. per Git/Cache gefilterten Teilmenge `scanned`.
-   - Symbole werden nur noch entfernt, wenn:
-     - die Datei im aktuellen `scanWorkspace`-Ergebnis nicht mehr existiert (z. B. durch neue Excludes), oder  
-     - Git sie als gelöscht meldet (`deletedFilesFromGit`).
-   - Inkrementelle Läufe (mit Git-Diff + AST-Cache) dürfen Symbole aus produktiven Dateien nicht als „deleted“ behandeln, solange diese Dateien weiterhin im `scannedAll`-Scope liegen.
-
-3. **Resync-/Recovery-Strategie etablieren**
-
-   - Bei größeren Änderungen am Scan-Scope oder bei offensichtlich inkonsistenten Zahlen (z. B. niedrige Index-Symbolzahl vs. hoher `scan:cli`-Wert) wird ein expliziter **Resync** als Best Practice definiert:
-     - Löschen von:
-       - `docs/modules`  
-       - `docs/index`  
-       - `docs/system`  
-       - `docs/.cache`
-     - Danach einen vollständigen Lauf (Full Cycle: Scan → Generate → Validate) ausführen.
-   - Dieser Prozess stellt sicher, dass alle Artefakte (Module-Doku, Symbol-Index, Dependencies, Change-Report, Caches) konsistent mit dem aktuellen Codezustand sind.
-
-4. **Interpretation des Validierungsstatus**
-
-   - Die Implementierung von `computeValidationStatus` bleibt bewusst unverändert:
-     - Coverage-Unterschreitungen gelten weiterhin als **Fehler**, die den Gesamtstatus auf „red“ setzen.
-   - Für die Praxis wird festgehalten:
-     - Wenn Signatur-Abweichungen (`signatureMismatches`) und Markdown-Probleme (`markdownErrors`) 0 sind, deutet ein roter Status ausschließlich auf unzureichende Coverage hin – nicht auf inkonsistente oder fehlerhafte Dokumentation.
-     - Coverage ist damit ein Qualitätsgrad, kein reiner Funktions-Health-Indikator.
-
-## Konsequenzen
-
-### Positiv
-
-- Symbole, Modul-Dokus und Dependency-Artefakte bleiben **stabil**, solange Dateien existieren und im Scan-Scope von `scanWorkspace` liegen.
-- Die Symbolanzahl in `docs/index/symbols.jsonl` reflektiert den **gesamten produktiven Code** (inkl. `src/`, `packages/`, `mcp`, `action`) und nicht nur einen Git-Diff-Ausschnitt.
-- Inkrementelle Läufe profitieren weiter von AST-/Output-/Dependencies-Caches, ohne versehentlich produktive Symbole zu „verlieren“.
-- Der Resync-Mechanismus (gezieltes Löschen der Generierungsartefakte + Full Cycle) ist als offizielles Recovery-Pattern dokumentiert.
-
-### Negativ / Trade-offs
-
-- Die Union-Logik berücksichtigt für die Entscheidung „Symbol behalten oder verwerfen“ nun den vollen Scan-Scope:
-  - Git-Diff kann weiterhin die Parsing-Arbeit reduzieren, aber nicht mehr die Semantik, welche Dateien als „noch gültig“ gelten.
-- Durch den größeren Symbol-Scope (mehr produktive Dateien) wird Coverage **strenger** wahrgenommen:
-  - Dokumentationslücken werden sichtbarer, was häufiger zu ROT führen kann, auch wenn technisch alles funktioniert.
-
-## Auswirkungen auf zukünftige Arbeit
-
-- Bei neuen Repos oder nach größeren Refactorings sollte früh ein Full Cycle laufen, um `docs/` und `.cache` in einen konsistenten Grundzustand zu bringen.
-- Bei Änderungen an `DEFAULT_EXCLUDES` oder am produktiven Scope (z. B. Hinzunahme weiterer Packages) ist ein einmaliger Resync-Lauf empfehlenswert.
-- Bei rotem Status ohne Signatur-/Markdown-Probleme:
-  - Entscheidungspunkt:
-    - Entweder Coverage durch zusätzliche Dokumentation anheben, oder  
-    - Coverage-Schwellen in `noyrax.coverageThresholds.*` bewusst an das Projekt anpassen.
-
-Diese ADR dient als Referenz für alle zukünftigen Änderungen an Scanner-Scope, Union-Logik und Resync-Mechanismen im Dokumentationssystem.
-
-