mindnet/docs/99_Archive/WP24c_release_notes.md

MindNet v4.5.8 - Release Notes: WP-24c

Release Date: 2026-01-XX
Type: Feature Release - Phase 3 Agentic Edge Validation & Chunk-Aware Multigraph-System
Version: 4.5.8 (WP-24c)

---

🎯 Überblick

Mit WP-24c wurde MindNet um ein finales Validierungs-Gate (Phase 3 Agentic Edge Validation) erweitert, das "Geister-Verknüpfungen" verhindert und die Graph-Qualität sichert. Zusätzlich wurde das System um automatische Spiegelkanten (Invers-Logik) und Note-Scope Zonen erweitert, die es ermöglichen, globale Verbindungen für ganze Notizen zu definieren.

Diese Version markiert einen wichtigen Schritt zur Graph-Integrität: Von manueller Kanten-Pflege hin zu automatischer Validierung und bidirektionaler Durchsuchbarkeit.

---

✨ Neue Features

1. Phase 3 Agentic Edge Validation

Implementierung (app/core/ingestion/ingestion_validation.py v2.14.0):

Finales Validierungs-Gate für alle Kanten mit candidate: Präfix:

• Trigger-Kriterium: Kanten in ### Unzugeordnete Kanten Sektionen erhalten candidate: Präfix
• Validierungsprozess: LLM prüft semantisch, ob die Verbindung zum Kontext passt
• Ergebnis: VERIFIED (Präfix entfernt, persistiert) oder REJECTED (nicht in DB geschrieben)
• Kontext-Optimierung: Note-Scope nutzt Note-Summary/Text, Chunk-Scope nutzt spezifischen Chunk-Text

Vorteile:

• Graph-Qualität: Verhindert persistente "Geister-Verknüpfungen"
• Präzision: Höhere Validierungs-Genauigkeit durch Kontext-Optimierung
• Fehlertoleranz: Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern

2. Automatische Spiegelkanten (Invers-Logik)

Implementierung (app/core/ingestion/ingestion_processor.py v2.13.12):

Automatische Erzeugung von Spiegelkanten für explizite Verbindungen:

• Funktionsweise: Explizite Kante A depends_on: B erzeugt automatisch B enforced_by: A
• Priorität: Explizite Kanten haben Vorrang (keine Duplikate)
• Schutz: System-Kanten (belongs_to, next, prev) können nicht manuell überschrieben werden
• Phase 2 Injektion: Spiegelkanten werden am Ende des Imports in einem Batch-Prozess injiziert

Vorteile:

• Bidirektionale Durchsuchbarkeit: Beide Richtungen sind durchsuchbar ohne manuelle Pflege
• Konsistenz: Volle Graph-Konsistenz ohne "Link-Nightmare"
• Höhere Wirksamkeit: Explizite Kanten haben höhere Confidence-Werte als automatisch generierte

3. Note-Scope Zonen (v4.2.0)

Implementierung (app/core/graph/graph_derive_edges.py v1.1.2):

Globale Verbindungen für ganze Notizen:

• Format: Links in ## Smart Edges Zonen werden als scope: note behandelt
• Priorität: Höchste Priorität bei Duplikaten
• Phase 3 Validierung: Nutzt Note-Summary (Top 5 Chunks) oder Note-Text für bessere Validierung
• Konfigurierbar: Header-Namen und -Ebene via ENV-Variablen

Vorteile:

• Globale Verbindungen: Links gelten für die gesamte Note, nicht nur einen Abschnitt
• Bessere Validierung: Note-Kontext ermöglicht präzisere LLM-Validierung
• Flexibilität: Konfigurierbare Header-Namen für verschiedene Workflows

4. Chunk-Aware Multigraph-System

Erweiterung des bestehenden Multigraph-Systems:

• Section-basierte Links: [[Note#Section]] wird präzise in target_id und target_section aufgeteilt
• Multigraph-Support: Mehrere Kanten zwischen denselben Knoten möglich, wenn sie auf verschiedene Sections zeigen
• Semantische Deduplizierung: Basierend auf src->tgt:kind@sec Key

Vorteile:

• Präzision: Präzise Verlinkung innerhalb langer Dokumente
• Flexibilität: Mehrere Verbindungen zur gleichen Note möglich
• Konsistenz: Verhindert "Phantom-Knoten"

---

🔧 Technische Änderungen

Konfigurationsdateien

config/llm_profiles.yaml (v1.3.0):

• Keine Änderungen: Bestehende Profile bleiben unverändert
• ingest_validator Profil: Wird für Phase 3 Validierung genutzt (Temperature 0.0 für Determinismus)

config/prompts.yaml (v3.2.2):

• Keine Änderungen: Bestehende Prompts bleiben unverändert
• edge_validation Prompt: Wird für Phase 3 Validierung genutzt

Environment Variablen (.env)

Neue Variablen für WP-24c:

# --- WP-24c v4.2.0: Konfigurierbare Markdown-Header für Edge-Zonen ---
# Komma-separierte Liste von Headern für LLM-Validierung
# Format: Header1,Header2,Header3
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates

# Header-Ebene für LLM-Validierung (1-6, Default: 3 für ###)
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3

# Komma-separierte Liste von Headern für Note-Scope Zonen
# Format: Header1,Header2,Header3
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen

# Header-Ebene für Note-Scope Zonen (1-6, Default: 2 für ##)
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2

Default-Werte:

• MINDNET_LLM_VALIDATION_HEADERS: Unzugeordnete Kanten,Edge Pool,Candidates
• MINDNET_LLM_VALIDATION_HEADER_LEVEL: 3 (für ###)
• MINDNET_NOTE_SCOPE_ZONE_HEADERS: Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen
• MINDNET_NOTE_SCOPE_HEADER_LEVEL: 2 (für ##)

Hinweis: Falls diese Variablen nicht gesetzt sind, werden die Default-Werte verwendet. Das System funktioniert ohne explizite Konfiguration.

Code-Komponenten

Neue/Erweiterte Module:

• app/core/ingestion/ingestion_validation.py: v2.14.0

  • Phase 3 Validierung mit Kontext-Optimierung
  • Differenzierte Fehlerbehandlung (transient vs. permanent)
  • Lazy-Prompt-Orchestration Integration

• app/core/ingestion/ingestion_processor.py: v2.13.12

  • Automatische Spiegelkanten-Generierung (Phase 2)
  • Authority-Check für explizite Kanten
  • ID-Konsistenz mit Phase 1

• app/core/graph/graph_derive_edges.py: v1.1.2

  • Note-Scope Zonen Extraktion
  • LLM-Validierung Zonen Extraktion
  • Konfigurierbare Header-Erkennung

• app/core/chunking/chunking_processor.py: v2.13.0

  • LLM-Validierung Zonen Erkennung
  • candidate: Präfix-Setzung

• app/core/chunking/chunking_parser.py: v2.12.0

  • Header-Level Erkennung
  • Zonen-Extraktion

---

📋 Migration Guide

Für Endbenutzer

Keine Migration erforderlich! Das System funktioniert ohne Änderungen.

Optionale Nutzung neuer Features:

1. Explizite Links (empfohlen):

   Diese Entscheidung [[rel:depends_on Performance-Analyse]] wurde getroffen.
   

   • Sofortige Übernahme, höchste Priorität, keine Validierung

2. Validierte Links (für explorative Verbindungen):

   ### Unzugeordnete Kanten
   
   related_to:Mögliche Verbindung
   depends_on:Unsicherer Link
   

   • Phase 3 Validierung, kann abgelehnt werden

3. Note-Scope Links (für globale Verbindungen):

   ## Smart Edges
   
   [[rel:depends_on|Projekt-Übersicht]]
   [[rel:part_of|Größeres System]]
   

   • Globale Verbindung für ganze Note, höchste Priorität

Für Administratoren

1. Environment Variablen hinzufügen (optional):

Fügen Sie die folgenden Zeilen zu Ihrer .env oder config/prod.env hinzu:

# --- WP-24c v4.2.0: Konfigurierbare Markdown-Header für Edge-Zonen ---
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2

Hinweis: Falls diese Variablen nicht gesetzt sind, werden die Default-Werte verwendet. Das System funktioniert ohne explizite Konfiguration.

2. LLM-Profil prüfen:

Stellen Sie sicher, dass das ingest_validator Profil in config/llm_profiles.yaml existiert:

ingest_validator:
  provider: ollama
  model: phi3:mini
  temperature: 0.0
  fallback_profile: null

3. Prompt prüfen:

Stellen Sie sicher, dass der edge_validation Prompt in config/prompts.yaml existiert.

4. System neu starten:

Nach dem Hinzufügen der ENV-Variablen:

systemctl restart mindnet-prod
systemctl restart mindnet-ui-prod

Für Entwickler

Keine Code-Änderungen erforderlich! Die neuen Features sind vollständig rückwärtskompatibel.

Optionale Integration:

• Phase 3 Validierung: Nutzen Sie validate_edge_candidate() aus ingestion_validation.py
• Note-Scope Zonen: Nutzen Sie extract_note_scope_zones() aus graph_derive_edges.py
• Spiegelkanten: Werden automatisch erzeugt, keine manuelle Integration erforderlich

---

🚀 Deployment-Anweisungen

Pre-Deployment Checkliste

• Backup: Vollständiges Backup von Qdrant und Vault durchführen
• ENV-Variablen: Neue ENV-Variablen zu .env hinzufügen (optional)
• LLM-Profil: ingest_validator Profil in llm_profiles.yaml prüfen
• Prompt: edge_validation Prompt in prompts.yaml prüfen
• Dependencies: requirements.txt aktualisieren (falls neue Abhängigkeiten)
• Tests: Unit Tests und Integration Tests ausführen

Deployment-Schritte

1. Code aktualisieren:

git pull origin main
# oder
git checkout WP24c
git merge main

2. Dependencies aktualisieren:

source .venv/bin/activate
pip install -r requirements.txt

3. ENV-Variablen konfigurieren (optional):

# Fügen Sie die neuen Variablen zu .env hinzu
nano .env
# oder
nano config/prod.env

4. Services neu starten:

systemctl restart mindnet-prod
systemctl restart mindnet-ui-prod

5. Health Check:

curl http://localhost:8001/healthz
curl http://localhost:8501/healthz

6. Logs prüfen:

journalctl -u mindnet-prod -n 50 --no-pager
journalctl -u mindnet-ui-prod -n 50 --no-pager

Post-Deployment Validierung

1. Phase 3 Validierung testen:

Erstellen Sie eine Test-Notiz mit ### Unzugeordnete Kanten:

---
type: concept
title: Test-Notiz
---

# Test-Notiz

Hier ist der Inhalt...

### Unzugeordnete Kanten

related_to:Test-Ziel

Erwartetes Verhalten:

• Log zeigt 🚀 [PHASE 3] Validierung: ...
• Log zeigt ✅ [PHASE 3] VERIFIED: oder 🚫 [PHASE 3] REJECTED:
• Kante wird nur bei VERIFIED persistiert

2. Note-Scope Zonen testen:

Erstellen Sie eine Test-Notiz mit ## Smart Edges:

---
type: decision
title: Test-Entscheidung
---

# Test-Entscheidung

Hier ist der Inhalt...

## Smart Edges

[[rel:depends_on|Test-Projekt]]

Erwartetes Verhalten:

• Link wird als scope: note behandelt
• provenance: explicit:note_zone
• Höchste Priorität bei Duplikaten

3. Automatische Spiegelkanten testen:

Erstellen Sie eine explizite Kante:

[[rel:depends_on Projekt Alpha]]

Erwartetes Verhalten:

• Log zeigt 🔄 [SYMMETRY] Add inverse: ...
• Beide Richtungen sind durchsuchbar
• Explizite Kante hat höhere Priorität

---

🐛 Bekannte Probleme & Einschränkungen

Keine bekannten Probleme.

Hinweise:

• Phase 3 Validierung: Erfordert LLM-Verfügbarkeit. Bei transienten Fehlern wird die Kante erlaubt (Datenintegrität vor Präzision).
• Spiegelkanten: Werden nur für explizite Kanten erzeugt. Validierte Kanten erhalten keine Spiegelkanten, bis sie VERIFIED sind.
• Note-Scope: Header-Namen müssen exakt (case-insensitive) übereinstimmen.

---

📚 Dokumentation

Aktualisierte Dokumente:

• docs/01_User_Manual/01_knowledge_design.md - Automatische Spiegelkanten, Phase 3 Validierung, Note-Scope Zonen
• docs/01_User_Manual/NOTE_SCOPE_ZONEN.md - Phase 3 Validierung integriert
• docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md - Phase 3 statt global_pool
• docs/02_concepts/02_concept_graph_logic.md - Phase 3 Validierung, automatische Spiegelkanten, Note-Scope vs. Chunk-Scope
• docs/03_Technical_References/03_tech_data_model.md - candidate: Präfix, verified Status, virtual Flag
• docs/03_Technical_References/03_tech_configuration.md - Neue ENV-Variablen dokumentiert
• docs/04_Operations/04_admin_operations.md - Troubleshooting für Phase 3 Validierung
• docs/05_Development/05_testing_guide.md - WP-24c Test-Szenarien

Neue Dokumente:

• Keine neuen Dokumente (alle Features in bestehenden Dokumenten integriert)

---

✅ Breaking Changes

Keine Breaking Changes!

Das System ist vollständig rückwärtskompatibel. Bestehende Notizen funktionieren ohne Änderungen.

---

🎉 Danksagungen

Diese Version wurde entwickelt, um die Graph-Integrität zu sichern und die Benutzerfreundlichkeit durch automatische Spiegelkanten zu verbessern.

---

Status: ✅ WP-24c ist zu 100% implementiert und audit-geprüft.
Nächster Schritt: WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung).