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

package/docs/system/PLUGIN_UPDATE_GUIDE.md

@@ -1,212 +0,0 @@
-# Plugin Update Guide
-
-> Leitfaden, um in **anderen Plugins** (z. B. `database-plugin`, `semantic-brain-plugin`, `context-rag-plugin`) dieselben Reality‑Driven Development‑Fähigkeiten wie im `documentation-system-plugin` zu etablieren.
-
----
-
-## 1. Ziel & Scope
-
-- **Ziel**:  
-  - Alle Plugins im Noyrax‑Ökosystem sollen:
-    - dieselben **Cursor Rules** (z. B. `000-orchestrator.mdc`, `026-reality-driven-verification.mdc`) nutzen,
-    - denselben **Verification-Loop** (compile → scan → validate → verify:all) unterstützen,
-    - die **CLI-Bridge** (`scan:cli`, `validate:cli`, Drift/Impact) verwenden,
-    - ihren **Status** in den jeweiligen `MVP_PLAN … .md`‑Dateien und in `docs/system/PLUGIN_ECOSYSTEM_STATUS.md` widerspiegeln.
-
-- **Geltungsbereich**:  
-  - Dieser Guide ist generisch und kann für jedes Plugin angewendet werden:
-    - `d:\Extensions\database-plugin\`
-    - `d:\Extensions\semantic-brain-plugin\`
-    - `d:\Extensions\context-rag-plugin\`
-    - weitere zukünftige Plugins
-
----
-
-## 2. Voraussetzungen pro Plugin
-
-- **Ordnerstruktur**:
-  - Das Plugin hat einen klaren Root‑Ordner (z. B. `d:\Extensions\semantic-brain-plugin\`).
-  - Es existiert eine `package.json` im Plugin‑Root.
-- **Tooling**:
-  - **Node**: mindestens `>= 18.0.0`
-  - **TypeScript**: kompatibel zu der Version in `documentation-system-plugin`.
-- **Abhängigkeit zum Noyrax‑CLI**:
-  - Das CLI‑Package `@noyrax/cli` ist entweder:
-    - lokal im `documentation-system-plugin` gebaut (`packages/doc-system-agent`), oder
-    - aus dem npm‑Registry installiert (sobald veröffentlicht).
-
----
-
-## 3. Einmaliges Setup: Rules & CLI integrieren
-
-### 3.1 Lokales CLI im Plugin nutzen (vor npm‑Release)
-
-- **Windows (PowerShell)**:
-
-```powershell
-# Im Plugin-Root (Beispiel: semantic-brain-plugin)
-cd D:\Extensions\semantic-brain-plugin
-
-# Noyrax-CLI (lokal aus dem documentation-system-plugin) ausführen
-node D:\Extensions\documentation-system-plugin\packages\doc-system-agent\dist\cli\index.js init --verbose
-```
-
-- **Erwartetes Ergebnis**:
-  - Im Plugin‑Root wird ein Ordner `.cursor\rules\` angelegt/aktualisiert.
-  - Die Rules `000-orchestrator.mdc`, `001-pre-check.mdc`, `002-system-context.mdc`, `026-reality-driven-verification.mdc` und weitere werden aus dem Noyrax‑Template kopiert.
-
-### 3.2 Alternative: Installation über npm / npx
-
-- Sobald `@noyrax/cli` im npm‑Registry veröffentlicht ist:
-
-```bash
-cd D:\Extensions\mein-plugin
-npm install --save-dev @noyrax/cli
-
-# Rules initialisieren oder aktualisieren
-npx @noyrax\cli init --verbose
-npx @noyrax\cli update-rules --verbose
-```
-
-- **Hinweis zum NPX-Cache**:
-  - Wenn NPX noch eine alte Version nutzt, wie in `docs/system/NPX_LOCAL_USAGE.md` beschrieben:
-    - **Cache leeren**:
-      ```bash
-      npx clear-npx-cache
-      npx @noyrax/cli@<aktuelle-Version> update-rules
-      ```
-
----
-
-## 4. Verification-Loop im Plugin einrichten
-
-### 4.1 NPM-Skripte ergänzen
-
-Erweitere die `scripts`‑Sektion der `package.json` im Plugin so, dass sie den gleichen Loop wie das `documentation-system-plugin` anbietet:
-
-```json
-"scripts": {
-  "compile": "tsc -p ./",
-  "scan:cli": "node out/cli/scan-cli.js",
-  "validate:cli": "node out/cli/validate-cli.js",
-  "verify:architecture": "node scripts/verify-architecture.js",
-  "verify:adrs": "node scripts/verify-adrs.js",
-  "verify:imports": "node scripts/verify-imports.js",
-  "verify:all": "npm run verify:architecture && npm run verify:adrs && npm run verify:imports"
-}
-```
-
-- **Hinweis**:
-  - Falls das Plugin eigene CLI‑Kommandos oder Skripte verwendet, sollten diese das **CLI-Bridge‑Pattern** aus ADR‑025 übernehmen:
-    - Kleine `src/cli/*-cli.ts` Dateien, die lediglich die internen Funktionen (`scanWorkspace`, `runValidateCli`, Drift‑Check, Impact‑Analyse) kapseln.
-
-### 4.2 Standard-Loop pro Plugin
-
-- **Lokaler Entwicklungsloop**:
-
-```bash
-# 1. Kompilieren
-npm run compile
-
-# 2. Scan ausführen
-npm run scan:cli
-
-# 3. Doku validieren
-npm run validate:cli
-
-# 4. Architektur- & ADR-Checks
-npm run verify:all
-```
-
-- **CI-Integration**:
-  - In CI‑Pipelines (z. B. GitHub Actions) können diese Skripte direkt wiederverwendet werden.
-  - Optionale Pre‑Commit‑Hooks analog zu `documentation-system-plugin/.husky/pre-commit` einrichten.
-
----
-
-## 5. Sync- vs. Drift-Modus im Validator nutzen
-
-### 5.1 Sync-Modus (nach Generate / Full Cycle)
-
-- Direkt nach einem **Generate** oder **Full Cycle**:
-  - Der Generate‑Flow hat `docs/modules/*`, `docs/index/symbols.jsonl` und Caches aktualisiert.
-  - Der Validator (`validate:cli`, `validateDocumentationTs`) lädt primär die **Symbolbasis aus dem Index** (`readSymbolsFromIndex`), anstatt neu zu parsen.
-  - Ergebnis:
-    - Keine künstlichen `stale_docs` durch unterschiedliche Parser-Flows.
-    - Validierung prüft Konsistenz von Generator‑Output (Doku) mit der gerade verwendeten Symbolbasis.
-
-### 5.2 Drift-Modus (späterer Check)
-
-- Wenn sich der Code nach einer Generierung ändert, ohne dass direkt neu generiert wurde:
-  - `validate:cli` kann im **Drift-Modus** laufen:
-    - Führt `scanWorkspace` erneut aus,
-    - parst den aktuellen Code,
-    - vergleicht die neuen Signaturen mit dem bestehenden Signatur-Cache und den Modul-Dokumenten (`docs/modules`).
-  - Echte Signatur-Drift (z. B. geänderte Parameter, Rückgabetypen) wird als `stale_docs`/Drift berichtet.
-
-- **Empfehlung**:
-  - Im Plugin‑Readme klar dokumentieren, wie der Sync‑ vs. Drift‑Modus ausgelöst wird (z. B. via CLI‑Option oder separaten Commands).
-
----
-
-## 6. Plugin-spezifische Hinweise
-
-### 6.1 Database Plugin
-
-- **Abhängigkeit vom Documentation-System-Plugin**:
-  - Benötigt aktuelle `docs/`‑Artefakte (Module, Index, Dependencies, Change-Report) aus dem `documentation-system-plugin`.
-  - Vor dem eigenen `scan:cli`/`validate:cli` sollte der Full Cycle im Documentation‑Plugin gelaufen sein.
-- **Drift/Verification**:
-  - Zusätzlich zu den Standard-Checks sollten die Skripte im `database-plugin` auch die Konsistenz der Workspace‑DB (`initializeWorkspace`, Ingestors, APIs) mit den importierten Docs prüfen.
-
-### 6.2 Semantic Brain Plugin
-
-- **Wichtig**:
-  - Keine automatischen `npm install`‑Aufrufe im Verification-Loop.  
-    - `npm install` ist ein **separater Setup-Schritt** (Dokumentation/Onboarding), kein Teil des Reality‑Driven‑Loops.
-  - Der Loop im `semantic-brain-plugin` sollte ausschließlich aus:
-    - `npm run compile`
-    - `npm run scan:cli`
-    - `npm run validate:cli`
-    - `npm run verify:all`
-    bestehen.
-- **Integration mit Database Plugin**:
-  - Sicherstellen, dass vor `scan:cli`/`validate:cli` im Semantic Brain die Workspace‑DB im `database-plugin` initialisiert ist (z. B. via `initializeWorkspace`‑Call im Setup oder automatischem Pre‑Step).
-
-### 6.3 Context/RAG Plugin (geplant)
-
-- **Voraussetzungen**:
-  - `database-plugin`: Status „KOMPLETT“ (MVP‑Plan & Ecosystem‑Status).
-  - `semantic-brain-plugin`: benötigte Graph‑ und Such‑APIs implementiert (z. B. `graph-api.ts`, `semanticSearch`).
-- **Integration**:
-  - Übernimmt denselben Rules‑Satz und denselben Verification‑Loop.
-  - Nutzt MCP‑ und Database‑/Semantic‑Brain‑APIs als Datenquellen für den Context‑Assembler.
-
----
-
-## 7. Verifikation & Pflege des Ökosystems
-
-- **Nach jeder Erweiterung eines Plugins**:
-
-  1. **Code/Tests**:
-     - `npm run compile`
-     - `npm test` (falls vorhanden)
-     - `npm run scan:cli`
-     - `npm run validate:cli`
-     - `npm run verify:all`
-  2. **MVP_PLAN aktualisieren** (z. B. `MVP_PLAN semantic brain.md`):
-     - Status‑Sektion, Roadmaps, Code‑Referenzen.
-  3. **`docs/system/PLUGIN_ECOSYSTEM_STATUS.md` anpassen**:
-     - Anzahl Artefakte, ADR‑Anzahl, neue Features.
-  4. **ADR ergänzen**, wenn es sich um eine relevante Architektur‑/Prozessentscheidung handelt (siehe ADR‑TEMPLATE).
-
-- **Drift regelmäßig prüfen**:
-  - Im `documentation-system-plugin`:
-    - `npm run scan:cli`
-    - `npm run validate:cli`
-    - `npm run verify:all`
-  - In abhängigen Plugins: analoger Loop.
-
-Damit bleibt das gesamte Plugin‑Ökosystem in einem konsistenten, **Reality‑Driven** Zustand und die MVP‑Pläne in `docs/` spiegeln jederzeit den tatsächlichen Stand der Implementierung wider.  
-
-

package/docs/system/RULES_UPDATE_GUIDE.md

@@ -1,182 +0,0 @@
-# Rules Update Guide
-
-**Stand:** 2025-01-XX  
-**Aktuelle Rules-Version:** 2
-
-## Übersicht
-
-Die Cursor Rules wurden überarbeitet, um das System als **mehrdimensionalen Navigationsraum** zu erklären. Neue Features:
-
-- **Neue Rule:** `002-system-context.mdc` - System-Verständnis und Navigation
-- **Aktualisierte Rules:** `000-orchestrator.mdc`, `001-pre-check.mdc`, `021-impact-analysis.mdc`
-- **MCP-Server:** Erweiterte Resource-Definitionen (99 Resources verfügbar)
-
-## Update für andere Systeme
-
-### Automatisches Update
-
-**WICHTIG:** Wenn das Package noch nicht auf npm veröffentlicht wurde, muss die lokale Version verwendet werden (siehe unten).
-
-**Nach Veröffentlichung auf npm:**
-
-```bash
-# Update durchführen
-npx @noyrax/cli update-rules
-
-# Oder mit verbose-Ausgabe
-npx @noyrax/cli update-rules --verbose
-
-# Alias (auch möglich)
-npx @noyrax/cli update --verbose
-```
-
-**Lokale Version verwenden (wenn noch nicht auf npm):**
-
-```powershell
-# Windows PowerShell
-node D:\Extensions\documentation-system-plugin\packages\doc-system-agent\dist\cli\index.js update-rules --verbose
-```
-
-Siehe `docs/system/NPX_LOCAL_USAGE.md` für Details.
-
-**Was passiert:**
-- Prüft aktuelle Rules-Version
-- Aktualisiert alle Rules auf Version 2
-- Erstellt Backups der alten Versionen (`.v1.backup`)
-- Aktualisiert `.rules-version.json`
-
-### Manuelles Update
-
-Falls kein CLI verfügbar:
-
-1. **Neue Rule kopieren:**
-   ```bash
-   # Von GitHub oder npm package
-   cp node_modules/@noyrax/cli/templates/cursor-rules/002-system-context.mdc .cursor/rules/
-   ```
-
-2. **Bestehende Rules aktualisieren:**
-   ```bash
-   cp node_modules/@noyrax/cli/templates/cursor-rules/000-orchestrator.mdc .cursor/rules/
-   cp node_modules/@noyrax/cli/templates/cursor-rules/001-pre-check.mdc .cursor/rules/
-   cp node_modules/@noyrax/cli/templates/cursor-rules/021-impact-analysis.mdc .cursor/rules/
-   ```
-
-3. **Version aktualisieren:**
-   ```json
-   // .cursor/rules/.rules-version.json
-   {
-     "version": 2,
-     "updatedAt": "2025-01-XX"
-   }
-   ```
-
-## Was ist neu?
-
-### Neue Rule: `002-system-context.mdc`
-
-Erklärt das System als mehrdimensionalen Navigationsraum mit 5 Dimensionen:
-
-- **Modul-Raum (X)**: `docs/modules/*.md`
-- **Symbol-Raum (Y)**: `docs/index/symbols.jsonl`
-- **Beziehungs-Raum (Z)**: `docs/system/DEPENDENCY_GRAPH.md`
-- **Wissens-Raum (W)**: `docs/adr/*.md`
-- **Zeit-Raum (T)**: `docs/system/CHANGE_REPORT.md`
-
-### Aktualisierte Rules
-
-**`000-orchestrator.mdc`:**
-- Workflow um "Systemkontext verstehen" erweitert
-- Abschnitt "Mehrdimensionaler Navigationsraum" hinzugefügt
-- `002-system-context` zur Always-Apply-Rule-Hierarchie hinzugefügt
-
-**`001-pre-check.mdc`:**
-- Verweis auf `002-system-context.mdc`
-- Neuer Abschnitt "Bei neuen Dateien: Systemkontext besorgen"
-- Change Report in Schritt "Nach der Änderung" integriert
-- MCP-Server-Zugriff dokumentiert
-
-**`021-impact-analysis.mdc`:**
-- MCP-Server `validation/analyzeImpact` als primäre Quelle
-- Zeit-Dimension (Change Report) integriert
-- Dimensionen-Spalte in Datenquellen-Tabelle
-- Abschnitt "Navigation im mehrdimensionalen Raum"
-
-## MCP-Server Updates
-
-Die MCP-Server-Implementierung wurde erweitert:
-
-- **Dynamisches Laden:** Module und ADRs werden zur Laufzeit geladen
-- **99 Resources verfügbar:**
-  - 4 System-Resources
-  - 71 Modul-Resources (dynamisch)
-  - 24 ADR-Resources (dynamisch)
-
-**Wichtig:** MCP-Server muss ebenfalls aktualisiert werden, wenn er als Package verwendet wird.
-
-## Migration von Version 1 zu Version 2
-
-### Breaking Changes
-
-**Keine Breaking Changes** - alle Änderungen sind rückwärtskompatibel.
-
-### Neue Abhängigkeiten
-
-- Keine neuen Abhängigkeiten erforderlich
-- MCP-Server sollte aktualisiert werden (falls verwendet)
-
-### Verhalten
-
-- **Vorher:** Rules erklärten nicht den mehrdimensionalen Raum
-- **Nachher:** Rules erklären vollständig, wie man im System navigiert
-
-## Validierung nach Update
-
-Nach dem Update prüfen:
-
-```bash
-# Rules-Verzeichnis prüfen
-ls -la .cursor/rules/
-
-# Sollte enthalten:
-# - 002-system-context.mdc (NEU)
-# - 000-orchestrator.mdc (aktualisiert)
-# - 001-pre-check.mdc (aktualisiert)
-# - 021-impact-analysis.mdc (aktualisiert)
-# - .rules-version.json (Version: 2)
-```
-
-## Troubleshooting
-
-### Problem: Rules werden nicht aktualisiert
-
-**Lösung:**
-```bash
-# Force-Update
-npx @noyrax/cli update-rules --force
-```
-
-### Problem: Backup-Dateien vorhanden
-
-**Lösung:**
-- Backup-Dateien (`.v1.backup`) können gelöscht werden, nachdem das Update erfolgreich war
-- Oder manuell mergen, falls lokale Anpassungen vorhanden
-
-### Problem: MCP-Server zeigt alte Resources
-
-**Lösung:**
-- MCP-Server-Package aktualisieren
-- Oder MCP-Server neu starten
-
-## Referenzen
-
-- **ADR-024:** Cursor Rules Überarbeitung – Mehrdimensionaler Navigationsraum
-- **ADR-023:** ADR-Verknüpfung mit Modul-Dokumentation
-- **ADR-014:** Rules-Migration und MCP-Integration
-
-## Support
-
-Bei Fragen oder Problemen:
-- GitHub Issues: https://github.com/noyrax/noyrax/issues
-- Dokumentation: https://noyrax.dev
-