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:**

```env
# --- 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):**
   ```markdown
   Diese Entscheidung [[rel:depends_on Performance-Analyse]] wurde getroffen.
   ```
   * Sofortige Übernahme, höchste Priorität, keine Validierung

2. **Validierte Links (für explorative Verbindungen):**
   ```markdown
   ### 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):**
   ```markdown
   ## 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:

```env
# --- 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:

```yaml
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:

```bash
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:**

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

**2. Dependencies aktualisieren:**

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

**3. ENV-Variablen konfigurieren (optional):**

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

**4. Services neu starten:**

```bash
systemctl restart mindnet-prod
systemctl restart mindnet-ui-prod
```

**5. Health Check:**

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

**6. Logs prüfen:**

```bash
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`:

```markdown
---
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`:

```markdown
---
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:

```markdown
[[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).