Programmmanagement/Überarbeitungshinweise_WP03.md hinzugefügt

Programmmanagement/Überarbeitungshinweise_WP03.md

@@ -0,0 +1,307 @@
+# mindnet v2 — Dokumentationsreview (vollständig & konsolidiert)
+
+Dieses Dokument fasst alle notwendigen Anpassungen der mindnet-v2 Dokumentation zusammen.  
+Der Fokus liegt ausschließlich auf Aspekten, die durch die aktuellen Arbeiten verändert wurden:
+
+- neue Edge-Mechanik  
+- neuer Importer  
+- neues Verhalten von note_payload & chunk_payload  
+- Default-Typregeln aus `types.yaml`  
+- Inline- und Callout-Relations  
+- WP04a – Einführung der Retriever-Schicht  
+- neue Diagnose- und Testskripte  
+
+Es handelt sich um eine strukturelle Analyse.  
+Nichts davon überschreibt bestehende Inhalte — es markiert nur, **was angepasst werden muss**.
+
+---
+
+# 1) knowledge_design.md  
+## Erforderliche Anpassungen
+
+### 1.1 Neue Edge-Arten dokumentieren
+Es müssen vier neue Kategorien beschrieben werden:
+
+1. **Inline-Edges**
+    
+    Beispiel:  
+        `[ [rel:depends_on Embeddings 101] ]`  
+    (Leerzeichen hier zur Demonstration; im echten Dokument ohne Leerzeichen)
+
+2. **Callout-Edges**
+    
+        > [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
+
+3. **Typbasierte Default-Kanten**  
+   Aus `types.yaml` → `edge_defaults`
+
+4. **Strukturkanten**
+    - belongs_to
+    - next
+    - prev
+
+### 1.2 Neue Edge-Felder ergänzen  
+Jeder Edge enthält jetzt:
+
+- `rule_id`
+- `confidence`
+- `scope = "chunk"`
+- deterministischer `edge_id`
+
+Diese Felder müssen vollständig erklärt werden.
+
+### 1.3 Chunk-basierte Kanten  
+Neu: **Alle Kanten entstehen ausschließlich zwischen Chunks**, nie zwischen Notes.  
+Notes dienen nur noch als Metadatencontainer.
+
+---
+
+# 2) TYPE_REGISTRY_MANUAL.md  
+## Erforderliche Anpassungen
+
+### 2.1 Typauflösung dokumentieren
+Die Regeln sind jetzt:
+
+- Typ aus Frontmatter → höchste Priorität
+- Falls nicht gesetzt: Typ aus Dateipfad ableiten
+- Falls unbekannt: Fallback auf `types.default`
+- Typ definiert:
+    - retriever_weight
+    - chunk_profile
+    - edge_defaults
+
+Diese müssen klar dokumentiert werden.
+
+### 2.2 Neue Fallback-Regeln
+Wenn Werte fehlen, werden sie ersetzt durch:
+
+        types.default.retriever_weight
+        types.default.chunk_profile
+        types.default.edge_defaults
+
+### 2.3 Beispiele aktualisieren  
+Alle Beispiele müssen auf die neue Inline-Syntax angepasst werden.
+
+---
+
+# 3) wp04_retriever_scoring.md  
+## Erforderliche Anpassungen
+
+### 3.1 Neue Scoring-Formel  
+        total_score =
+            semantic_weight   * semantic_score
+          + edge_weight       * edge_bonus
+          + centrality_weight * centrality_bonus
+          + type_weight       * retriever_weight
+
+### 3.2 Bedeutung von `confidence`  
+confidence wirkt multiplikativ bei edge_bonus.  
+Inline > Callout > Default (Standardwerte im Code hinterlegt).
+
+### 3.3 Pfadbegründungen  
+Der Retriever gibt optional `paths[]` zurück:
+
+        paths: [
+            {
+                "via": "depends_on",
+                "confidence": 0.7,
+                "hops": ["Note A", "Chunk A#01", "Note B"]
+            }
+        ]
+
+Diese Funktion müssen dokumentiert werden.
+
+---
+
+# 4) mindnet_v2_implementation_playbook.md  
+## Erforderliche Anpassungen
+
+### 4.1 Neuer Import-Prozess vollständig dokumentieren
+Der Importer läuft jetzt so:
+
+1. Markdown lesen  
+2. Frontmatter extrahieren  
+3. Typauflösung via `types.yaml`  
+4. Note-Payload generieren  
+5. Chunking anwenden  
+6. Inline-Kanten finden  
+7. Callout-Kanten finden  
+8. Default-Edges erzeugen  
+9. Strukturkanten erzeugen  
+10. Chunks in Qdrant upserten  
+11. Edges upserten  
+12. Diagnose laufen lassen:
+
+        python3 -m scripts.payload_dryrun
+        python3 -m scripts.edges_full_check
+
+### 4.2 Erweiterte Testpipeline  
+Neu zu dokumentieren:
+
+        tests.test_edges_all
+        scripts.edges_full_check
+        scripts.payload_dryrun
+
+Diese Testschritte sind jetzt Standardanforderung nach jeder Änderung.
+
+---
+
+# 5) mindnet_technical_architecture.md  
+## Erforderliche Anpassungen
+
+### 5.1 Aktualisiertes Schema für Qdrant Collections
+
+#### Notes:
+        note_id
+        title
+        type
+        fulltext
+        retriever_weight
+        chunk_profile
+        edge_defaults
+        tags
+        updated
+
+#### Chunks:
+        chunk_id
+        note_id
+        text
+        window
+        ord
+        retriever_weight
+        chunk_profile
+        neighbors_prev
+        neighbors_next
+
+#### Edges:
+        edge_id
+        source_id
+        target_id
+        kind
+        scope = "chunk"
+        rule_id
+        confidence
+
+### 5.2 Dokumentation der Edge-Pipeline  
+Neu beschreiben:
+
+- Inline-Parser  
+- Callout-Parser  
+- Default-Edge-Resolver  
+- Strukturkanten  
+- Normalisierung für Qdrant  
+- deterministische ID-Bildung  
+
+---
+
+# 6) mindnet_functional_architecture.md  
+## Erforderliche Anpassungen
+
+### 6.1 Inline-Relations – einzig gültige Syntax
+Nur diese Syntax erzeugt Kanten:
+
+        [[rel:depends_on Embeddings 101]]
+
+Nicht unterstützt:
+
+        rel:depends_on [[Embeddings 101]]
+
+Dies muss klar dokumentiert werden.
+
+### 6.2 Prioritäten der Kantenerzeugung  
+Gültige Reihenfolge:
+
+1. Inline  
+2. Callout  
+3. Typdefaults  
+4. Strukturkanten  
+
+### 6.3 Relaunch der Chunk-zentrierten Funktionslogik  
+Alle Beispiele müssen angepasst werden.
+
+---
+
+# 7) chunking_strategy.md  
+## Erforderliche Änderungen
+
+### 7.1 Neues Verhalten der Chunks
+- `ord` ist jetzt Sortierkriterium  
+- `window` wird über chunk_config erzeugt  
+- Chunkprofile kommen ausschließlich aus `types.yaml`
+
+### 7.2 Best Practices erneuern
+Empfehlung:
+
+- keine manuelle Chunkprofile mehr im Frontmatter setzen  
+
+---
+
+# 8) docs_mindnet_retriever.md  
+## Erforderliche Änderungen
+
+### 8.1 Neue Ausgabeparameter dokumentieren  
+Retriever liefert jetzt:
+
+        semantic_score
+        edge_bonus
+        centrality_bonus
+        type_score
+        total_score
+        paths[]
+
+### 8.2 Graph-Expansion  
+Dokumentieren:
+
+- Seed-Auswahl  
+- Depth-Limit  
+- Edge-Filterung  
+- Wirkung von `confidence` auf edge_bonus  
+
+---
+
+# 9) Handbuch.md  
+## Erforderliche Änderungen
+
+### 9.1 Neuer Import-Workflow  
+Erläuterung der Parser:
+
+- Inline-Parser  
+- Callout-Parser  
+- Default-Kanten  
+- Struktur-Kanten  
+
+### 9.2 Best Practices  
+Ergänzen:
+
+- Typenpflege erfolgt nur in `types.yaml`  
+- Tests immer nach Änderungen ausführen  
+
+---
+
+# Gesamtübersicht der notwendigen Anpassungen
+
+| Dokument | Anpassungsbedarf |
+|---------|------------------|
+| knowledge_design.md | neue Edge-Arten, Felder, Chunk-Edges |
+| TYPE_REGISTRY_MANUAL.md | Typauflösung, neue Felder, neue Fallbacks |
+| wp04_retriever_scoring.md | neue Score-Formel, Pfade, confidence |
+| implementation_playbook.md | neuer Importprozess, Tests |
+| technical_architecture.md | aktualisierte Schemas |
+| functional_architecture.md | Syntax + Prioritäten |
+| chunking_strategy.md | ord, window, neue Profile |
+| docs_mindnet_retriever.md | neue API-Parameter |
+| Handbuch.md | Parser + Best Practices |
+
+---
+
+# Empfehlung zur Umsetzung
+1. Dieses Review-Dokument als Master-Referenz verwenden.  
+2. Jedes Dokument strikt nur an den beschriebenen Stellen anpassen.  
+3. Überprüfen, ob Wann/Wo Typen, Kanten und Parser erklärt werden.  
+4. Nach jeder Anpassung Testlauf:
+
+        python3 -m scripts.payload_dryrun
+        python3 -m scripts.edges_full_check
+
+5. Danach Playbook + Programmplan updaten.
+