# LASTENHEFT: WP-26 Integration im Obsidian Plugin **Version:** 1.1 **Datum:** 28. Januar 2026 **Status:** Entwurf zur Review (aktualisiert: Commands, Edge-Überarbeitung, Interview Edge-Typen pro Sektion) **Projekt:** mindnet_obsidian (Obsidian Community Plugin) **Basis:** Backend WP-26 v1.3 (Section Types & Intra-Note-Edges) --- ## 1. Einleitung ### 1.1 Zweck des Dokuments Dieses Lastenheft definiert die vollständigen Anforderungen für die Integration der WP-26 Features (Section Types & Intra-Note-Edges) in das bestehende mindnet_obsidian Plugin. Es beschreibt alle notwendigen Anpassungen, Erweiterungen und neuen Funktionen, die erforderlich sind, um die Backend-Funktionalität nahtlos in die Plugin-Benutzeroberfläche zu integrieren. ### 1.2 Geltungsbereich - **Plugin:** mindnet_obsidian (`c:\Dev\cursor\mindnet_obsidian`) - **Backend-Contract:** WP-26 Lastenheft v1.3 (Section Types & Intra-Note-Edges) - **Kompatibilität:** Alle bestehenden Funktionen müssen weiterhin funktionieren - **Integration:** Nahtlose Einbindung ohne Breaking Changes ### 1.3 Grundprinzipien 1. **Vollständige Abwärtskompatibilität:** Bestehende Notes und Funktionen funktionieren unverändert 2. **Nahtlose Integration:** Neue Features fügen sich natürlich in bestehende Workflows ein 3. **Keine Deaktivierungen:** Keine Funktionen werden eigenmächtig deaktiviert oder signifikant geändert 4. **Konsistente UX:** Neue UI-Elemente folgen bestehenden Design-Patterns 5. **Backend-Konformität:** Alle generierten Markdown-Formate entsprechen der Backend-Spezifikation ### 1.4 Definitionen | Begriff | Definition | |---------|------------| | **Section-Type** | Explizit per `[!section]` Callout definierter Typ für einen Abschnitt | | **Block-ID** | Obsidian Block-Reference Format `^block-id` in Überschriften | | **Intra-Note-Edge** | Semantische Kante zwischen Chunks derselben Note (`is_internal: true`) | | **Effective Type** | Für Scoring verwendeter Typ: `section_type` falls vorhanden, sonst `note_type` | | **Retroaktive Propagation** | Section-Type gilt ab der vorhergehenden Überschrift, auch wenn Callout später steht | --- ## 2. Analyse der bestehenden Plugin-Struktur ### 2.1 Betroffene Module #### 2.1.1 Parser (`src/parser/`) **Aktuelle Funktionen:** - `parseEdgesFromCallouts.ts`: Extrahiert `[!edge]` Callouts und Targets - `parseRelLinks.ts`: Extrahiert `[[rel:type|target]]` Links - `parseFrontmatter.ts`: Extrahiert Frontmatter-Metadaten **WP-26 Relevanz:** - Muss `[!section]` Callouts erkennen - Muss Block-IDs aus Überschriften extrahieren - Muss Intra-Note-Links (`[[#^block-id]]`) identifizieren #### 2.1.2 Mapping (`src/mapping/`) **Aktuelle Funktionen:** - `sectionParser.ts`: Splittet Markdown in Sections (nach Headings) - `semanticMappingBuilder.ts`: Erstellt Semantic Mapping Blöcke - `edgeTypeSelector.ts`: Vorschläge für Edge-Types basierend auf Kontext - `graphSchema.ts`: Lädt und parst `graph_schema.md` - `schemaHelper.ts`: Hilfsfunktionen für Schema-Lookups **WP-26 Relevanz:** - Section-Parser muss `[!section]` Callouts und Block-IDs erkennen - Edge-Type-Selector muss Section-Types berücksichtigen - Schema-Helper muss Section-Type-basierte Vorschläge liefern #### 2.1.3 Interview (`src/interview/`) **Aktuelle Funktionen:** - `renderer.ts`: Rendert Interview-Antworten zu Markdown - `wizardState.ts`: Verwaltet Wizard-State - `types.ts`: TypeScript-Interfaces für Interview-Konfiguration - `sectionKeyResolver.ts`: Löst Section-Keys auf **WP-26 Relevanz:** - Renderer muss `[!section]` Callouts generieren können - Wizard-State muss Section-Types unterstützen - Section-Key-Resolver muss Block-IDs berücksichtigen #### 2.1.4 Kausal-Funktionen (Chain Inspector, Chain Workbench) **Überblick:** Die „Kausal-Funktionen“ bestehen aus (1) **Interview-Wizard** (geführte Erstellung von Notes mit kausal/argumentativen Strukturen), (2) **Chain Inspector** (Kausal-Analyse: Template-Matching, Findings wie `no_causal_roles`, `missing_link`), (3) **Chain Workbench** (UI für Findings, TODOs, Fix-Actions). Bis ca. Version 0.6.x waren diese ohne **Sektionsunterstützung mit unterschiedlichen Typen** (Section-Types); ab WP-26 wird Section-Type-basiertes Chain-Matching ergänzt (FA-PL-08). **Aktuelle Funktionen / Module:** - `src/analysis/chainInspector.ts`: Analysiert kausale Ketten, Template-Matching, Findings (u. a. `no_causal_roles`, `weak_chain_roles`) - `src/workbench/`: `todoGenerator.ts`, `workbenchBuilder.ts`, `statusCalculator.ts`, `ChainWorkbenchModal.ts` - `src/commands/inspectChainsCommand.ts`: Command „Inspect Chains (Current Section)“ - `src/commands/chainWorkbenchCommand.ts`: Command „Chain Workbench (Current Section)“ - `src/commands/vaultTriageScanCommand.ts`: Command „Scan Vault for Chain Gaps“ - Dictionary: `chain_roles.yaml` (Edge-Typen → kausale Rollen), `chain_templates.yaml` (Kettenmuster) **Warum die Module „nicht aktiv“ erscheinen können:** 1. **Commands nur bei geöffneter Markdown-Datei:** „Inspect Chains“ und „Chain Workbench“ sind mit **editorCallback** registriert. In Obsidian erscheinen sie in der Befehlspalette nur, wenn eine **Markdown-Datei im Editor aktiv** ist. Ohne geöffnete Note sind sie ausgegraut bzw. nicht auffindbar – analog zu „Edge-Type ändern“ (siehe FA-PL-12a). 2. **Fehlende oder falsche Dictionary-Pfade:** Wenn `chain_roles.yaml` oder `chain_templates.yaml` am konfigurierten Pfad (Standard: `_system/dictionary/`) fehlen oder nicht lesbar sind, liefern die Loader `data === null`. Die Commands brechen **nicht** ab; Chain Inspector und Workbench laufen dann ohne Template-Matching und ohne kausale Rollen-Erkennung. Es erscheint **kein** expliziter Hinweis (z. B. „Chain Roles nicht geladen“). Das Ergebnis wirkt leer oder „inaktiv“. 3. **Sichtbarkeit in der Befehlspalette:** Ohne Hinweis in der Doku suchen Nutzer ggf. nach „Kausal“ oder „Wizard“; die registrierten Namen sind „Inspect Chains“ und „Chain Workbench“. Ein Eintrag im Lastenheft / Benutzerhandbuch verbessert die Auffindbarkeit. **Lastenheft-Referenz:** Chain Workbench mit Section-Types ist in **FA-PL-08** beschrieben. Die allgemeine Sichtbarkeit von Commands (inkl. Kausal/Chain) ist in **FA-PL-12 / FA-PL-12a** adressiert. #### 2.1.5 Chain Workbench – Module (`src/workbench/`) **Aktuelle Funktionen:** - `todoGenerator.ts`: Generiert TODOs basierend auf Chain-Templates - `chainInspector.ts` (in `src/analysis/`): Analysiert Chains und findet Gaps - `types.ts`: TypeScript-Interfaces für Workbench **WP-26 Relevanz:** - Chain-Matching muss Section-Types berücksichtigen - Gap-Detection muss Intra-Note-Edges erkennen - Template-Matching muss effective types verwenden #### 2.1.6 UI (`src/ui/`) **Aktuelle Funktionen:** - `EdgeTypeChooserModal.ts`: Modal zur Edge-Type-Auswahl - `InlineEdgeTypeModal.ts`: Inline-Edge-Type-Suggester - `LinkPromptModal.ts`: Modal für Link-Erstellung - `InterviewWizardModal.ts`: Interview-Wizard-UI **WP-26 Relevanz:** - Edge-Type-Chooser muss Section-Type-basierte Vorschläge zeigen - Link-Prompt muss Block-ID-Generierung unterstützen - Interview-Wizard muss Section-Type-Auswahl ermöglichen #### 2.1.7 Lint (`src/lint/`) **Aktuelle Funktionen:** - `LintEngine.ts`: Haupt-Lint-Engine - `rules/`: Verschiedene Lint-Regeln **WP-26 Relevanz:** - Neue Lint-Regeln für Section-Types - Validierung von Block-IDs - Validierung von Intra-Note-Edges #### 2.1.8 Schema (`src/schema/`) **Aktuelle Funktionen:** - `GraphSchemaLoader.ts`: Lädt `graph_schema.md` **WP-26 Relevanz:** - Muss erweitert werden für Section-Type-Lookups - Muss "prohibited" Edges unterstützen (Phase 3) --- ## 3. Funktionale Anforderungen ### 3.1 Phase 1: Grundlagen (Kern-Parsing) #### FA-PL-01: Section-Type-Callout-Parsing **Anforderung:** Das Plugin muss `[!section]` Callouts erkennen und parsen. **Betroffene Dateien:** - `src/parser/parseEdgesFromCallouts.ts` (erweitern) - `src/mapping/sectionParser.ts` (erweitern) **Implementierung:** 1. Neues Regex-Pattern für `[!section]` Callouts: `/^\s*>\s*\[!section\]\s*(\w+)/i` 2. Section-Parser erkennt Callouts innerhalb von Sections 3. Extrahiert Section-Type (muss in `types.yaml` validiert werden) 4. Speichert Section-Type in `NoteSection` Interface **Interface-Erweiterung:** ```typescript export interface NoteSection { // ... bestehende Felder ... sectionType: string | null; // NEU: Section-Type aus [!section] Callout blockId: string | null; // NEU: Block-ID aus Heading (^block-id) } ``` **Validierung:** - Section-Type muss in `types.yaml` existieren (Warnung bei unbekanntem Typ) - Case-insensitive Matching für Callout-Header **Kompatibilität:** - Bestehende Notes ohne `[!section]` Callouts funktionieren unverändert - `sectionType` ist optional (`null` = Fallback auf `note_type`) --- #### FA-PL-02: Block-ID-Extraktion **Anforderung:** Das Plugin muss Block-IDs aus Überschriften extrahieren. **Betroffene Dateien:** - `src/mapping/sectionParser.ts` (erweitern) **Implementierung:** 1. Regex-Pattern für Block-IDs in Headings: `/^#{1,6}\s+.+\s+\^([a-zA-Z0-9_-]+)$/` 2. Extrahiert Block-ID aus Heading-Text (z.B. `## Überschrift ^block-id`) 3. Speichert Block-ID in `NoteSection.blockId` **Beispiele:** ```markdown ## Situation ^sit → blockId: "sit" ## Reflexion ^ref → blockId: "ref" ## Überschrift ohne ID → blockId: null ``` **Kompatibilität:** - Bestehende Headings ohne Block-IDs funktionieren unverändert - Block-ID ist optional --- #### FA-PL-03: Intra-Note-Link-Erkennung **Anforderung:** Das Plugin muss Intra-Note-Links (`[[#^block-id]]`) erkennen. **Betroffene Dateien:** - `src/parser/parseEdgesFromCallouts.ts` (erweitern) - `src/mapping/sectionParser.ts` (erweitern) **Implementierung:** 1. Erweitert Wikilink-Parsing um Block-Reference-Format 2. Erkennt `[[#^block-id]]` als Intra-Note-Link 3. Markiert solche Links als `isInternal: true` in ParsedEdge **Interface-Erweiterung:** ```typescript export interface ParsedEdge { // ... bestehende Felder ... isInternal: boolean; // NEU: true für [[#^block-id]] Links blockId: string | null; // NEU: Block-ID aus [[#^block-id]] } ``` **Kompatibilität:** - Bestehende Inter-Note-Links funktionieren unverändert - Intra-Note-Links werden zusätzlich erkannt --- ### 3.2 Phase 2: UI-Komponenten #### FA-PL-04: Section-Type-Modal **Anforderung:** Neues Modal zur Auswahl und Einfügung von Section-Types. **Neue Datei:** - `src/ui/SectionTypeModal.ts` **Funktionalität:** 1. Zeigt verfügbare Section-Types aus `types.yaml` 2. Erlaubt Auswahl eines Section-Types 3. Fügt `[!section]` Callout an aktueller Cursor-Position ein 4. Unterstützt Block-ID-Generierung für Heading **UI-Flow:** 1. Command: "Mindnet: Add Section Type" 2. Modal öffnet mit Liste verfügbarer Types 3. Benutzer wählt Type 4. Callout wird eingefügt: `> [!section] ` **direkt nach der Heading-Zeile** 5. Optional: Block-ID wird automatisch generiert für vorhergehende Heading **Formatierungsregel:** `[!section]` Callout wird immer direkt nach der Heading-Zeile eingefügt (vor dem Section-Content) **Kompatibilität:** - Bestehende Commands bleiben unverändert - Neues Command ist optional --- #### FA-PL-05: Edge-Type-Chooser mit Section-Type-Support **Anforderung:** Edge-Type-Chooser muss Section-Types berücksichtigen. **Betroffene Dateien:** - `src/ui/EdgeTypeChooserModal.ts` (erweitern) - `src/mapping/schemaHelper.ts` (erweitern) **Implementierung:** 1. Edge-Type-Chooser erhält `sourceSectionType` und `targetSectionType` Parameter 2. Schema-Helper nutzt Section-Types für Vorschläge (falls vorhanden) 3. Fallback auf `note_type` wenn Section-Type nicht vorhanden 4. Zeigt "Recommended (section types)" Sektion wenn Section-Types vorhanden **Priorisierung:** 1. Suggested (from chain_roles) - unverändert 2. Recommended (section types) - NEU 3. Recommended (schema) - erweitert um Section-Types 4. All edge types - unverändert **Kompatibilität:** - Bestehende Funktionalität bleibt unverändert - Section-Types werden zusätzlich berücksichtigt --- #### FA-PL-06: Link-Prompt mit Block-ID-Generierung **Anforderung:** Link-Prompt muss Block-ID-Generierung unterstützen. **Betroffene Dateien:** - `src/ui/LinkPromptModal.ts` (erweitern) **Implementierung:** 1. Erkennt, wenn Link zu Section in aktueller Note erstellt wird 2. Fragt Benutzer, ob Block-ID generiert werden soll 3. Generiert eindeutige Block-ID basierend auf Heading-Text 4. Fügt Block-ID zu Heading hinzu: `## Heading ^generated-id` **Beispiel:** - Benutzer erstellt Link: `[[#Situation]]` - Plugin erkennt: Intra-Note-Link - Plugin fragt: "Block-ID 'situation' zu Heading hinzufügen?" - Bei Bestätigung: Heading wird zu `## Situation ^situation` **Kompatibilität:** - Bestehende Link-Erstellung funktioniert unverändert - Block-ID-Generierung ist optional --- ### 3.3 Phase 3: Feature-Integration #### FA-PL-07: Interview-Wizard mit Section-Types, Block-IDs und automatischen Edge-Vorschlägen **Anforderung:** Interview-Wizard muss Section-Types, Block-IDs und automatische Edge-Vorschläge zwischen Sections unterstützen. **Betroffene Dateien:** - `src/interview/renderer.ts` (erweitern) - `src/interview/types.ts` (erweitern) - `src/ui/InterviewWizardModal.ts` (erweitern) **Implementierung:** 1. **Section-Types:** - Interview-Config erlaubt `section_type` in Steps - Renderer generiert `[!section]` Callouts für Steps mit Section-Type - Wizard-State speichert Section-Type pro Step 2. **Block-IDs:** - Interview-Config erlaubt `block_id` (explizit) oder `generate_block_id: true` (automatisch) - Automatische Generierung: Slugify des Step-Keys oder Heading-Texts - Wizard-State trackt alle generierten Block-IDs (`generatedBlockIds` Map) - Renderer fügt Block-ID zu Heading hinzu: `## Heading ^block-id` 3. **Referenzen zu vorherigen Sections:** - Interview-Config erlaubt `references` Array in Steps - Jede Reference enthält `block_id` und optional `edge_type` - Renderer generiert `[!edge]` Callouts mit Block-References: `[[#^block-id]]` - Referenzen werden beim Rendern des aktuellen Steps eingefügt 4. **Automatische Edge-Vorschläge zwischen Sections:** - Wizard-State trackt Section-Sequenz (`sectionSequence` Array) - Für jede neue Section: Automatische Edge-Vorschläge zu vorherigen Sections - Edge-Types werden aus `graph_schema.md` ermittelt (falls verfügbar) - Fallback: `related_to` wenn kein Schema-Match gefunden wird - Rückwärts-Edges werden automatisch vorgeschlagen (inverser Edge-Type via `edge_vocabulary.md`) **Config-Erweiterung:** ```yaml profiles: - key: experience_profile note_type: experience steps: - type: capture_text key: context section: "## Kontext" section_type: experience generate_block_id: true # Generiert automatisch "context" - type: capture_text key: situation section: "## Situation" section_type: experience block_id: "sit" # Explizite Block-ID references: - block_id: "context" edge_type: "derived_from" # Optional: Vorgeschlagener Edge-Type - type: capture_text key: reflection section: "## Reflexion" section_type: insight generate_block_id: true # Generiert automatisch "reflection" # Automatischer Edge-Vorschlag wird generiert: insight -> experience (invers zu resulted_in) ``` **Renderer-Logik:** 1. **Block-ID-Generierung:** - Wenn `block_id` explizit: Verwende diesen Wert - Wenn `generate_block_id: true`: Generiere aus Step-Key (slugify) - Wenn beides fehlt: Keine Block-ID 2. **Section-Type-Generierung:** - Wenn `section_type` vorhanden: Generiere `> [!section] ` **direkt nach der Heading-Zeile** - Wenn Block-ID vorhanden: Heading wird zu `## Heading ^block-id` - **Formatierungsregel:** `[!section]` Callout steht immer unmittelbar nach der Überschrift, vor dem Section-Content 3. **Referenz-Generierung:** - Für jede Reference in `references` Array: - Generiere `> [!edge] ` (oder `related_to` wenn nicht angegeben) - Generiere `[[#^block-id]]` Link - **Formatierungsregel:** Edges werden **am Ende der Sektion** eingefügt (nach dem Section-Content, wie bisher) 4. **Automatische Edge-Vorschläge:** - Für jede neue Section (ab der zweiten): - Ermittle `effective_type` der aktuellen Section (Section-Type oder Note-Type) - Für jede vorherige Section in Sequenz: - Ermittle `effective_type` der vorherigen Section - Lookup in `graph_schema.md`: `getTopologyInfo(prevType, currentType)` - Wenn Match gefunden: Generiere Forward-Edge mit typischem Edge-Type - Generiere automatisch Rückwärts-Edge mit inversem Edge-Type (via `edge_vocabulary.md`) - Automatische Edges werden nur generiert, wenn beide Sections Block-IDs haben - **Formatierungsregel:** Automatische Edges werden **am Ende der Sektion** eingefügt (nach dem Section-Content) **Generierte Ausgabe (Beispiel):** ```markdown ## Kontext ^context > [!section] experience [Antwort aus Step "context"] > [!edge] derived_from > [[#^context]] ## Situation ^sit > [!section] experience [Antwort aus Step "situation"] > [!edge] resulted_in > [[#^sit]] > [!edge] caused_by > [[#^context]] ## Reflexion ^reflection > [!section] insight [Antwort aus Step "reflection"] > [!edge] resulted_in > [[#^sit]] > [!edge] caused_by > [[#^context]] ``` **Formatierungsregeln:** 1. `> [!section] ` steht **immer direkt nach der Heading-Zeile** (vor dem Section-Content) 2. `> [!edge]` Callouts stehen **immer am Ende der Sektion** (nach dem Section-Content, wie bisher) 3. Leerzeile zwischen Heading und `[!section]` Callout ist optional (kann weggelassen werden) 4. Leerzeile zwischen Section-Content und Edges ist optional (kann weggelassen werden) **Wizard-State-Erweiterung:** ```typescript export interface WizardState { // ... bestehende Felder ... generatedBlockIds: Map; sectionSequence: Array<{ // NEU: Sequenz aller Sections für Edge-Vorschläge stepKey: string; blockId: string | null; sectionType: string | null; noteType: string; // Fallback für effective_type }>; } ``` **Kompatibilität:** - Bestehende Interview-Configs ohne neue Felder funktionieren unverändert - Alle neuen Felder sind optional - Block-ID-Generierung ist standardmäßig deaktiviert (muss explizit aktiviert werden) - Automatische Edge-Vorschläge werden nur generiert, wenn beide Sections Block-IDs haben --- #### FA-PL-08: Chain Workbench mit Section-Types **Anforderung:** Chain Workbench muss Section-Types für Chain-Matching verwenden. **Betroffene Dateien:** - `src/workbench/chainInspector.ts` (erweitern) - `src/workbench/todoGenerator.ts` (erweitern) - `src/workbench/types.ts` (erweitern) **Implementierung:** 1. Chain Inspector verwendet `effective_type` (Section-Type oder Note-Type) 2. Template-Matching berücksichtigt Section-Types 3. Gap-Detection erkennt fehlende Section-Types 4. TODO-Generator schlägt Section-Types vor **Logik:** - Für jeden Chunk: `effectiveType = sectionType || noteType` - Template-Matching: `template.slot.type === effectiveType` - Gap-Detection: Wenn Template `experience` Slot erwartet, aber Section hat `insight` → Gap **Kompatibilität:** - Bestehende Chain-Analysen funktionieren unverändert - Section-Types werden zusätzlich berücksichtigt --- #### FA-PL-09: Semantic Mapping mit Section-Types **Anforderung:** Semantic Mapping Builder muss Section-Types berücksichtigen. **Betroffene Dateien:** - `src/mapping/semanticMappingBuilder.ts` (erweitern) - `src/mapping/edgeTypeSelector.ts` (erweitern) **Implementierung:** 1. Mapping Builder erkennt Section-Types in Sections 2. Edge-Type-Selector verwendet Section-Types für Vorschläge 3. Automatische Edge-Generierung berücksichtigt Section-Types **Logik:** - Für jede Section: Ermittle `effectiveType` - Für Links zwischen Sections: Verwende `effectiveType` für Edge-Type-Vorschläge - Schema-Lookup: `getTopologyInfo(sourceSectionType, targetSectionType)` **Kompatibilität:** - Bestehende Semantic Mappings funktionieren unverändert - Section-Types werden zusätzlich berücksichtigt --- ### 3.4 Phase 4: Validierung & Linting #### FA-PL-10: Lint-Regeln für Section-Types **Anforderung:** Neue Lint-Regeln für Section-Types. **Neue Datei:** - `src/lint/rules/rule_section_type.ts` **Regeln:** 1. **Section-Type-Validität:** Section-Type muss in `types.yaml` existieren 2. **Block-ID-Eindeutigkeit:** Block-IDs müssen innerhalb einer Note eindeutig sein 3. **Intra-Note-Edge-Validität:** Intra-Note-Edges müssen gegen `graph_schema.md` validiert werden **Implementierung:** ```typescript export interface SectionTypeLintRule { checkSectionType(section: NoteSection, types: string[]): LintFinding[]; checkBlockIdUniqueness(sections: NoteSection[]): LintFinding[]; checkIntraNoteEdge(edge: ParsedEdge, schema: GraphSchema): LintFinding[]; } ``` **Kompatibilität:** - Bestehende Lint-Regeln bleiben unverändert - Neue Regeln sind optional (können deaktiviert werden) --- #### FA-PL-11: Schema-Validierung für Intra-Note-Edges **Anforderung:** Validierung von Intra-Note-Edges gegen `graph_schema.md`. **Betroffene Dateien:** - `src/schema/GraphSchemaLoader.ts` (erweitern) - `src/mapping/schemaHelper.ts` (erweitern) **Implementierung:** 1. Schema-Loader lädt "prohibited" Edges aus `graph_schema.md` 2. Schema-Helper prüft Edge gegen Schema 3. Lint-Engine zeigt Warnungen für prohibited Edges **Logik:** - Für Intra-Note-Edge: `sourceSectionType -> targetSectionType` - Prüfe gegen Schema: `getTopologyInfo(sourceType, targetType)` - Wenn Edge in "prohibited": Warnung - Wenn Edge nicht in "typical": Info-Hinweis **Kompatibilität:** - Bestehende Schema-Validierung bleibt unverändert - Neue Validierung ist zusätzlich --- ### 3.5 Phase 5: Commands #### FA-PL-12: Commands für WP-26 und Edge-Überarbeitung **Anforderung:** Commands für WP-26 Features und für die Edge-Überarbeitung in bestehenden Noten müssen in der Befehlspalette auffindbar und nutzbar sein. **Betroffene Dateien:** - `src/main.ts` (erweitern) **Bereits implementierte Commands (Stand: Jan 2026):** | Command-ID | Name (Befehlspalette) | Kontext | Modul / Funktion | |------------|------------------------|---------|-------------------| | `mindnet-change-edge-type` | Mindnet: Edge-Type ändern | **editorCallback** – nur bei geöffneter MD-Datei | `edgeTypeSelector.ts`: Einzellink, Auswahl, ganze Note, neuer Link | | `mindnet-build-semantic-mappings` | Mindnet: Build semantic mapping blocks (by section) | **editorCallback** – nur bei geöffneter MD-Datei | `semanticMappingBuilder.ts`: Mapping-Blöcke pro Sektion bauen/überarbeiten | | `mindnet-fix-findings` | Mindnet: Fix Findings (Current Section) | **editorCallback** | `fixFindingsCommand.ts`: fehlende Links einfügen, Kandidaten-Edges bestätigen | **Hinweis:** Commands mit `editorCallback` erscheinen in Obsidian nur, wenn eine Markdown-Datei im Editor aktiv ist. Ohne geöffnete Note sind sie in der Befehlspalette ausgegraut bzw. nicht ausführbar. Das kann dazu führen, dass Nutzer sie „nicht als Befehle abrufbar“ erleben, wenn sie z. B. in Einstellungen oder im Graph sind. **Offene / geplante Commands (Lastenheft):** 1. **"Mindnet: Add Section Type"** (noch nicht umgesetzt) - Öffnet Section-Type-Modal, fügt `[!section]` Callout ein 2. **"Mindnet: Add Block ID to Heading"** (noch nicht umgesetzt) - Generiert Block-ID für aktuelles Heading, fügt `^block-id` hinzu 3. **"Mindnet: Insert Intra-Note Edge"** (noch nicht umgesetzt) - Edge-Type-Chooser mit Section-Type-Support, Intra-Note-Link mit Block-Reference 4. **"Mindnet: Validate Section Types"** (noch nicht umgesetzt) - Section-Type-Lint-Regeln ausführen, Findings in Console **Neue Anforderung (FA-PL-12a): Sichtbarkeit der Edge-Commands** - Die Befehle **Edge-Type ändern** und **Build semantic mapping blocks** sollen für Nutzer klar auffindbar sein. - Option A: Beibehalten von `editorCallback` und in der Dokumentation (z. B. Benutzerhandbuch) festhalten: „Eine Markdown-Note muss geöffnet sein.“ - Option B: Zusätzlich einen Command ohne Editor (z. B. `callback`) anbieten, der prüft, ob eine MD-Datei aktiv ist, und ggf. eine Notice ausgibt („Bitte zuerst eine Markdown-Datei öffnen“), damit der Befehl immer in der Palette erscheint. **Kompatibilität:** - Bestehende Commands bleiben unverändert - Neue/angepasste Commands sind zusätzlich oder klären die Nutzung --- #### Edge-Überarbeitung in bestehenden Noten (bereits implementiert) Die folgenden **Module** unterstützen das Überarbeiten und Verbinden von Edges in bestehenden Noten. Sie sind über die oben genannten Commands erreichbar (jeweils bei geöffneter Markdown-Datei): | Modul | Funktion | Aufruf | |-------|----------|--------| | `src/mapping/edgeTypeSelector.ts` | Kantentyp für einen Link, mehrere Links oder ganze Note setzen; neuer Link mit Kantentyp | Command „Mindnet: Edge-Type ändern“ | | `src/mapping/semanticMappingBuilder.ts` | Pro Sektion Semantic-Mapping-Blöcke bauen/überarbeiten, Links mit Kantentypen versehen | Command „Mindnet: Build semantic mapping blocks (by section)“ | | `src/mapping/updateMappingBlocks.ts` | `[[rel:type\|link]]` in Content finden, in Mapping-Blöcke übernehmen | Wird vom Edge-Type-Selector nach Änderung aufgerufen | | `src/commands/fixFindingsCommand.ts` | Fehlende Links einfügen, Kandidaten-Edges in explizite Edges übernehmen | Command „Mindnet: Fix Findings (Current Section)“ | Ohne geöffnete Markdown-Datei erscheinen „Edge-Type ändern“ und „Build semantic mapping blocks“ in der Befehlspalette ausgegraut (siehe FA-PL-12a). --- ### 3.6 Erweiterung: Edge-Typen pro Sektion im Interview (implementiert, Jan 2026) Die folgende Erweiterung wurde umgesetzt und hat Auswirkungen auf Parsing, Renderer und Mapping. #### FA-PL-14: Section-Edges und Note-Edges im Interview **Anforderung:** Im Interview-Wizard sollen Section-zu-Section- und Note-Edges (inkl. Abschnitts-Links `Note#Abschnitt`) konfigurierbar sein und im gerenderten Markdown korrekt erscheinen. **Umsetzung (Kernkomponenten):** 1. **SectionEdgesOverviewModal** (`src/ui/SectionEdgesOverviewModal.ts`) - Zeigt am Ende des Interviews alle Section-Edges und Note-Edges. - Erlaubt Anpassung der Edge-Typen; Note-Ziele werden als vollständiger Link (z. B. `Note#Abschnitt`) gespeichert. - Liefert `sectionEdges` und `noteEdges` an den Wizard. 2. **LinkTargetPickerModal** (`src/ui/LinkTargetPickerModal.ts`) - Nach Auswahl einer Note (Entity Picker) kann gewählt werden: ganze Note oder konkreter Abschnitt (`Note#Abschnitt`). - Der gewählte Link wird in Inline-Micro-Edging und in den Übersichts-Dialog übernommen. 3. **Renderer** (`src/interview/renderer.ts`) - `RenderOptions.noteEdges`: Map von Block-ID → (toNote bzw. `Note#Abschnitt` → edgeType). - Note-Edges werden pro Sektion als `>> [!edge] type` und `>> [[Note#Abschnitt]]` im Semantic-Mapping-Block ausgegeben. - `buildAbstractWrapper` akzeptiert beliebige Wikilinks `[[…]]`, nicht nur `[[#^block-id]]`. 4. **Links mit Abschnitt erhalten** - **parseRelLinks.ts:** `linkBasename` behält `#Abschnitt`; Ersetzung erfolgt als `[[Note#Abschnitt]]`; Edge-Map verwendet vollen Link als Key. - **sectionParser.ts (extractWikilinks):** Links behalten `#Abschnitt` (kein Strip mehr); `section.links` enthält z. B. `Note#Abschnitt`. - **semanticMappingBuilder.ts / updateMappingBlocks.ts:** Beim Mergen wird der passende Section-Link (mit `#`) als Key verwendet; Mapping-Blöcke schreiben `>> [[Note#Abschnitt]]`. **Auswirkungen:** - Bestehende Notes ohne `#Abschnitt` bleiben unverändert. - Chain Workbench, Graph-Index und Backend können `Note#Abschnitt`-Links nutzen, sofern sie diese Form unterstützen. - Lint/Validierung: optional prüfen, dass Abschnitts-Links konsistent sind. **Dokumentation:** Siehe auch `docs/WP26_Plugin_Interface_Specification.md` (Abschnitt Interview, Edge-per-Section, Note#Abschnitt). --- ### 3.7 Phase 6: Dictionary-Integration #### FA-PL-13: Types-Loader (wie bisher) **Anforderung:** Laden und Validierung von `types.yaml`. **Neue Datei:** - `src/dictionary/TypesLoader.ts` **Funktionalität:** 1. Lädt `types.yaml` aus konfiguriertem Pfad 2. Parst verfügbare Note-Types und Section-Types 3. Validiert Section-Types in Notes gegen geladene Types 4. Live-Reload bei Änderungen (wie andere Dictionary-Dateien) **Interface:** ```typescript export interface TypesConfig { types: { [key: string]: { name: string; description?: string; // ... weitere Felder }; }; } export class TypesLoader { static async load(app: App, path: string): Promise; static validateSectionType(type: string, config: TypesConfig): boolean; } ``` **Kompatibilität:** - Bestehende Dictionary-Loader bleiben unverändert - Types-Loader ist zusätzlich --- ## 4. Technische Spezifikationen ### 4.1 TypeScript-Interfaces #### 4.1.1 Erweiterte Interfaces **NoteSection (erweitert):** ```typescript export interface NoteSection { heading: string | null; headingLevel: number; content: string; startLine: number; endLine: number; links: string[]; sectionType: string | null; // NEU blockId: string | null; // NEU } ``` **ParsedEdge (erweitert):** ```typescript export interface ParsedEdge { rawType: string; targets: string[]; lineStart: number; lineEnd: number; isInternal: boolean; // NEU blockId: string | null; // NEU } ``` **InterviewStep (erweitert):** ```typescript export interface CaptureTextStep { // ... bestehende Felder ... sectionType?: string; // NEU: Optionaler Section-Type blockId?: string; // NEU: Explizite Block-ID generateBlockId?: boolean; // NEU: Automatische Block-ID-Generierung references?: Array<{ // NEU: Referenzen zu vorherigen Sections blockId: string; edgeType?: string; // Optional: Vorgeschlagener Edge-Type }>; } // Gilt auch für andere Step-Types mit Section-Output: export interface CaptureTextLineStep { // ... bestehende Felder ... sectionType?: string; blockId?: string; generateBlockId?: boolean; references?: Array<{ blockId: string; edgeType?: string }>; } ``` **WizardState (erweitert):** ```typescript export interface WizardState { // ... bestehende Felder ... generatedBlockIds: Map; sectionSequence: Array<{ // NEU: Sequenz aller Sections für Edge-Vorschläge stepKey: string; blockId: string | null; sectionType: string | null; noteType: string; // Fallback für effective_type }>; } ``` --- ### 4.2 Regex-Patterns **Section-Type-Callout:** ```typescript const SECTION_CALLOUT_RE = /^\s*>\s*\[!section\]\s*(\w+)/i; ``` **Block-ID in Heading:** ```typescript const BLOCK_ID_RE = /^#{1,6}\s+(.+?)\s+\^([a-zA-Z0-9_-]+)$/; ``` **Block-Reference in Link:** ```typescript const BLOCK_REFERENCE_RE = /\[\[#\^([a-zA-Z0-9_-]+)\]\]/; ``` ### 4.3 Formatierungsregeln **Wichtig:** Die folgenden Formatierungsregeln müssen bei der Generierung von Markdown eingehalten werden: 1. **Section-Type-Callout Position:** - `> [!section] ` steht **immer direkt nach der Heading-Zeile** - Vor dem Section-Content (Text der Sektion) - Format: `## Heading ^block-id\n> [!section] type\n\nContent...` 2. **Edge-Callout Position:** - `> [!edge] ` steht **immer am Ende der Sektion** - Nach dem Section-Content (wie bisher) - Format: `Content...\n\n> [!edge] type\n> [[#^block-id]]` 3. **Konsistenz:** - Diese Regeln gelten für alle generierten Markdown-Formate (Interview-Wizard, Semantic Mapping, etc.) - Bestehende Edge-Positionierung bleibt unverändert (am Ende der Sektion) - Neue Section-Type-Positionierung (direkt nach Heading) ist konsistent mit Backend-Erwartungen --- ### 4.3 Settings-Erweiterungen **Neue Settings (optional):** ```typescript export interface MindnetSettings { // ... bestehende Settings ... // WP-26 Settings typesPath: string; // Pfad zu types.yaml autoGenerateBlockIds: boolean; // Automatische Block-ID-Generierung sectionTypeValidation: boolean; // Section-Type-Validierung aktivieren } ``` **Kompatibilität:** - Bestehende Settings bleiben unverändert - Neue Settings haben Default-Werte --- ## 5. Kompatibilitäts-Anforderungen ### 5.1 Abwärtskompatibilität **Grundsatz:** Alle bestehenden Funktionen müssen weiterhin funktionieren. **Konkret:** 1. **Notes ohne Section-Types:** Funktionieren unverändert, `sectionType = null` 2. **Notes ohne Block-IDs:** Funktionieren unverändert, `blockId = null` 3. **Bestehende Commands:** Funktionieren unverändert 4. **Bestehende UI-Modals:** Funktionieren unverändert 5. **Bestehende Lint-Regeln:** Funktionieren unverändert --- ### 5.2 Feature-Flags (Optional) **Für schrittweise Einführung:** ```typescript export interface WP26FeatureFlags { enableSectionTypes: boolean; // Default: true enableBlockIds: boolean; // Default: true enableIntraNoteEdges: boolean; // Default: true enableSectionTypeValidation: boolean; // Default: false (Phase 4) } ``` **Kompatibilität:** - Features können einzeln aktiviert/deaktiviert werden - Default: Alle Features aktiviert --- ## 6. Test-Anforderungen ### 6.1 Unit-Tests **Neue Test-Dateien:** - `tests/sectionParser.test.ts` - `tests/sectionTypeModal.test.ts` - `tests/typesLoader.test.ts` **Bestehende Tests erweitern:** - `tests/parseEdgesFromCallouts.test.ts` (Intra-Note-Links) - `tests/edgeTypeChooser.test.ts` (Section-Type-Support) - `tests/interviewRenderer.test.ts` (Section-Type-Generierung) --- ### 6.2 Integration-Tests **Test-Szenarien:** 1. Note mit Section-Types parsen 2. Block-IDs extrahieren 3. Intra-Note-Edges erkennen 4. Section-Type-Validierung 5. Chain-Matching mit Section-Types --- ## 7. Implementierungsreihenfolge ### Phase 1: Grundlagen (Kern-Parsing) - FA-PL-01: Section-Type-Callout-Parsing - FA-PL-02: Block-ID-Extraktion - FA-PL-03: Intra-Note-Link-Erkennung ### Phase 2: UI-Komponenten - FA-PL-04: Section-Type-Modal - FA-PL-05: Edge-Type-Chooser mit Section-Type-Support - FA-PL-06: Link-Prompt mit Block-ID-Generierung ### Phase 3: Feature-Integration - FA-PL-07: Interview-Wizard mit Section-Types, Block-IDs und automatischen Edge-Vorschlägen - FA-PL-08: Chain Workbench mit Section-Types - FA-PL-09: Semantic Mapping mit Section-Types ### Phase 4: Validierung & Linting - FA-PL-10: Lint-Regeln für Section-Types - FA-PL-11: Schema-Validierung für Intra-Note-Edges ### Phase 5: Commands - FA-PL-12: Commands für WP-26 und Edge-Überarbeitung (Stand: implementierte vs. geplante Commands) - FA-PL-12a: Sichtbarkeit Edge-Commands (optional: ohne Editor-Kontext auffindbar machen) ### Phase 6: Dictionary-Integration - FA-PL-13: Types-Loader ### Erweiterung (implementiert) - FA-PL-14: Section-Edges und Note-Edges im Interview (inkl. Note#Abschnitt) --- ## 8. Nächste Schritte (Empfehlung) 1. **Commands auffindbar machen:** FA-PL-12a umsetzen (Dokumentation und/oder zusätzlichen Command ohne editorCallback), damit „Edge-Type ändern“ und „Build semantic mapping blocks“ in der Befehlspalette zuverlässig gefunden werden. 2. **Kausal-Funktionen sichtbar machen:** „Inspect Chains“ und „Chain Workbench“ nutzen editorCallback und erscheinen nur bei geöffneter MD-Datei (siehe Abschnitt 2.1.4). Optionen: (a) Im Benutzerhandbuch festhalten: „Eine Markdown-Note muss geöffnet sein.“ (b) Zusätzlich Commands ohne editorCallback anbieten, die bei fehlender Datei einen Hinweis anzeigen, damit die Befehle in der Palette sichtbar bleiben. 3. **Hinweis bei fehlenden Chain-Dictionaries:** Wenn `chain_roles.yaml` oder `chain_templates.yaml` nicht geladen werden können, soll vor Ausführung von Inspect Chains / Chain Workbench ein **Notice** erscheinen (z. B. „Chain Roles nicht geladen. Bitte Pfad in den Einstellungen prüfen.“), damit Nutzer nicht mit leerer oder reduzierter Analyse dastehen. 4. **Geplante Commands (FA-PL-12):** Priorisierung von „Add Section Type“, „Add Block ID to Heading“, „Insert Intra-Note Edge“, „Validate Section Types“ gemäß Nutzerbedarf. 5. **Interview-Edge-Erweiterung (FA-PL-14):** Abnahme mit Backend (Note#Abschnitt in Links/Mapping-Blöcken); ggf. Lint-Regel für konsistente Abschnitts-Links. 6. **WP26-Spezifikation:** Implementierungsstand in `WP26_Plugin_Interface_Specification.md` fortlaufend anpassen (siehe dort Abschnitt 9 / 10). --- ## 9. Risiken und Mitigation ### 9.1 Risiken | Risiko | Wahrscheinlichkeit | Impact | Mitigation | |--------|-------------------|--------|------------| | Breaking Changes in bestehenden Funktionen | Niedrig | Hoch | Umfassende Tests, Feature-Flags | | Performance-Impact durch zusätzliches Parsing | Mittel | Mittel | Lazy Loading, Caching | | Inkonsistenz zwischen Plugin und Backend | Mittel | Hoch | Strikte Einhaltung der Backend-Spezifikation | | Komplexität der UI-Integration | Mittel | Mittel | Schrittweise Implementierung, klare Interfaces | --- ## 10. Erfolgskriterien ### 10.1 Funktionale Kriterien - ✅ Alle bestehenden Funktionen funktionieren unverändert - ✅ Section-Types werden korrekt erkannt und geparst - ✅ Block-IDs werden korrekt extrahiert - ✅ Intra-Note-Edges werden korrekt erkannt - ✅ UI-Komponenten unterstützen Section-Types - ✅ Lint-Regeln validieren Section-Types ### 10.2 Qualitätskriterien - ✅ Keine Breaking Changes - ✅ Vollständige Abwärtskompatibilität - ✅ Konsistente UX - ✅ Umfassende Test-Abdeckung --- ## 11. Anhänge ### 11.1 Referenzen - Backend Lastenheft: `docs/06_Roadmap/06_LH_Section_Types_Intra_Note_Edges.md` (v1.3) - Backend Plugin Interface: `docs/WP26_Plugin_Interface_Specification.md` - Backend Implementation Checklist: `docs/WP26_Implementation_Checklist.md` ### 11.2 Glossar Siehe Backend Lastenheft Kapitel 1.3. ### 11.3 Chain Inspector & Chain Workbench (detailliert) - **Lastenheft Chain Inspector & Chain Workbench:** `docs/09_Chain_Inspector_Workbench_Lastenheft.md` – vollständige fachliche und technische Anforderungen (effective_type, Findings, Todos, Commands). - **Umsetzungsplan Chain Inspector & Chain Workbench:** `docs/09_Chain_Inspector_Workbench_Umsetzungsplan.md` – detaillierte Phasen, Tasks und offene Punkte aus früheren Implementierungsplänen (Section-Type-Integration, Findings-Integration, FA-PL-08). --- **Ende des Lastenhefts**