feat: implement knowledge management system (spec complete, all 53 tasks done)

.kiro/specs/knowledge-management/tasks.md

@@ -0,0 +1,325 @@
+# Implementation Plan: Knowledge Management System
+
+## Overview
+
+Implementierung des vereinheitlichten Knowledge Management Systems als Erweiterung des bestehenden Monorepo-CLI. Die Umsetzung erfolgt inkrementell: zuerst die Kerninfrastruktur (Datenmodelle, Routing, Konfiguration), dann die Ingestion-Pipeline, Source-Strategien, Enrichment, Integrationen und abschließend die CLI-Schnittstelle.
+
+**Sprache:** Python (konsistent mit dem bestehenden Monorepo-CLI)
+**Pfade:**
+- Ingestion-Pipeline: `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/`
+- Source-Strategien: `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/`
+- Integrationen: `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/`
+- CLI: `shared/tools/monorepo-cli/src/monorepo/knowledge/cli.py`
+- Knowledge-Ordner: `bahn/knowledge/`, `dhive/knowledge/`, `privat/knowledge/`
+
+## Tasks
+
+- [x] 1. Projekt-Struktur und Knowledge-Ordner anlegen
+  - [x] 1.1 Erstelle die Knowledge-Ordner-Struktur für alle drei Kontexte
+    - Erstelle `bahn/knowledge/`, `dhive/knowledge/`, `privat/knowledge/` mit Unterordnern: `inbox/`, `meetings/`, `decisions/`, `projects/`, `people/`, `references/`, `links/`
+    - Erstelle eine `index.md` pro Unterordner als Platzhalter-Inhaltsverzeichnis
+    - Erstelle eine leere `_index.yaml` und `sources.yaml` pro Kontext-Knowledge-Folder
+    - _Requirements: 1.1, 1.2, 1.6, 12.1_
+
+  - [x] 1.2 Erstelle die Modul-Struktur für die Ingestion-Pipeline
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/__init__.py`
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/__init__.py`
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/__init__.py`
+    - Erstelle leere Module: `pipeline.py`, `router.py`, `enrichment.py`, `capture.py`, `config.py`, `git_integration.py` im ingestion-Ordner
+    - _Requirements: 2.1_
+
+- [x] 2. Datenmodelle und Konfiguration
+  - [x] 2.1 Erweitere ArtifactMetadata um Knowledge-Management-Felder
+    - Erweitere die bestehende `ArtifactMetadata`-Klasse in `artifact.py` um: `source` (dict), `category` (str), `people` (list), `projects` (list), `enrichment_pending` (bool), `ocr_failed` (bool), `fetch_failed` (bool)
+    - Stelle Rückwärtskompatibilität sicher (alle neuen Felder sind optional mit Defaults)
+    - Passe `parse`/`write`-Funktionen an, damit Round-Trip für erweiterte Felder funktioniert
+    - _Requirements: 1.5, 16.6_
+
+  - [x] 2.2 Property-Test: Artifact Serialization Round-Trip
+    - **Property 1: Artifact Serialization Round-Trip**
+    - **Validates: Requirements 16.6, 1.5**
+
+  - [x] 2.3 Implementiere SourceConfig und sources.yaml-Parsing
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/config.py`
+    - Implementiere `SourceConfig`-Dataclass mit Feldern: type, name, params, target_folder, sync_frequency, enabled
+    - Implementiere `load_sources_config(path: Path) -> list[SourceConfig]` zum Parsen der YAML-Datei
+    - Implementiere Umgebungsvariablen-Auflösung für `${VAR_NAME}`-Patterns in Werten
+    - Implementiere Validierung: fehlende Pflichtfelder, nicht auflösbare Env-Vars → Fehler
+    - _Requirements: 12.1, 12.2, 12.4, 12.6_
+
+  - [x] 2.4 Property-Test: Environment Variable Resolution
+    - **Property 21: Environment Variable Resolution in Config**
+    - **Validates: Requirements 12.4, 12.6**
+
+- [x] 3. Context Router
+  - [x] 3.1 Implementiere ContextRouter
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/router.py`
+    - Implementiere `determine_context(source_config, cwd)` – leitet Kontext aus SourceConfig oder Arbeitsverzeichnis ab
+    - Implementiere `resolve_target_path(context, category, filename)` – berechnet `{root}/{context}/knowledge/{category}/{filename}`
+    - Implementiere Kategorie-zu-Ordner-Mapping: meeting→meetings/, decision→decisions/, project→projects/, reference→references/, link→links/, inbox→inbox/, unbekannt→inbox/
+    - _Requirements: 1.4, 2.3, 3.2, 3.5, 9.6_
+
+  - [x] 3.2 Property-Tests: Context Routing und Category Mapping
+    - **Property 2: Context Derivation from Path**
+    - **Property 6: Context Routing Determinism**
+    - **Property 8: Category to Folder Mapping**
+    - **Validates: Requirements 1.4, 2.3, 3.2, 3.5, 9.6**
+
+- [x] 4. Checkpoint – Basis-Infrastruktur
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 5. Quick Capture und Inbox
+  - [x] 5.1 Implementiere QuickCapture
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/capture.py`
+    - Implementiere `capture(input_text, context, tags)` – erzeugt Markdown-Datei in `{context}/knowledge/inbox/`
+    - Implementiere `_detect_input_type(input_text)` – erkennt ob Input eine URL, ein Dateipfad oder Freitext ist
+    - Implementiere `_generate_filename(title)` – erzeugt `YYYY-MM-DD-HH-MM-title-slug.md`
+    - Erzeuge minimales Frontmatter: title, created, source, type: inbox
+    - Gib den Dateipfad des erstellten Artefakts zurück
+    - _Requirements: 3.1, 3.2, 3.3, 3.7, 8.3_
+
+  - [x] 5.2 Property-Tests: Quick Capture
+    - **Property 7: Filename Pattern from Title**
+    - **Property 11: URL Detection in Quick Capture**
+    - **Validates: Requirements 3.3, 8.3**
+
+- [x] 6. Source Strategies – Base und Markdown
+  - [x] 6.1 Implementiere SourceStrategy ABC und MarkdownSource
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/base.py` mit `SourceStrategy` ABC (extract, supports_incremental)
+    - Erstelle `ExtractionResult`-Dataclass und `SourceError`-Dataclass
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/markdown.py`
+    - Implementiere MarkdownSource: liest .md/.txt-Dateien, extrahiert bestehendes Frontmatter
+    - Unterstütze inkrementelle Verarbeitung via Content-Hash
+    - _Requirements: 2.2, 2.4, 2.7, 4.1_
+
+  - [x] 6.2 Property-Test: File Extension Format Detection
+    - **Property 9: File Extension Format Detection**
+    - **Validates: Requirements 4.7**
+
+  - [x] 6.3 Implementiere PDF- und OCR-Source
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/pdf.py`
+    - Implementiere PDF-Text-Extraktion (eingebetteter Text via PyPDF2 oder pdfplumber)
+    - Implementiere OCR-Fallback für gescannte Seiten (Kiro Vision als primärer Provider)
+    - Setze `ocr_failed: true` falls OCR fehlschlägt
+    - Behalte Referenz auf Originaldatei in `source.file`
+    - _Requirements: 4.2, 4.3, 4.4, 4.5, 4.6_
+
+  - [x] 6.4 Property-Test: Image Source File Reference
+    - **Property 10: Image Source File Reference Preservation**
+    - **Validates: Requirements 4.5**
+
+- [x] 7. Source Strategies – Externe Quellen
+  - [x] 7.1 Implementiere Confluence-Source
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/confluence.py`
+    - Implementiere Confluence REST-API-Anbindung (Seiten, Bäume, FAQ-Spaces)
+    - Extrahiere Seiteninhalte als Markdown, reichere Frontmatter an (URL, Space, Titel, Last-Modified)
+    - Unterstütze inkrementelle Updates via Versions-Nummer
+    - Behandle API-Fehler graceful (skip source, log error)
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7_
+
+  - [x] 7.2 Implementiere Jira-Source
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/jira.py`
+    - Implementiere JQL-basierte Issue-Extraktion
+    - Stelle Issue als Markdown zusammen (Summary, Description, Kommentare, Status)
+    - Reichere Frontmatter an (Issue-Key, Projekt, Status, Assignee, Reporter, URL)
+    - Unterstütze inkrementelle Updates via `updated`-Feld
+    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.7_
+
+  - [x] 7.3 Implementiere Email- und Chat-Source
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/email.py`
+    - Implementiere .eml/.msg-Parsing (Absender, Empfänger, Betreff, Datum, Body)
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/chat.py`
+    - Implementiere Chat-Export-Parsing (Text/JSON)
+    - Verarbeite Anhänge als separate Artefakte mit Link im Eltern-Artefakt
+    - _Requirements: 7.1, 7.2, 7.3, 7.5, 7.6_
+
+  - [x] 7.4 Implementiere Link-Source und LinkRegistry
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/link.py`
+    - Implementiere `LinkRegistry`: save_link, search_links, _fetch_metadata, _find_existing
+    - Speichere Links als Artefakte vom Typ `link` in `links/`
+    - Implementiere URL-Deduplication mit Tag-Merging
+    - Implementiere Suche über URL, Titel, Tags
+    - Setze `fetch_failed: true` falls URL nicht erreichbar
+    - _Requirements: 8.1, 8.2, 8.4, 8.5, 8.6, 8.7_
+
+  - [x] 7.5 Property-Tests: Link Registry
+    - **Property 12: Link Artifact Structure**
+    - **Property 13: Link Deduplication with Tag Merging**
+    - **Property 14: Link Search Completeness**
+    - **Validates: Requirements 8.1, 8.2, 8.6, 8.7**
+
+  - [x] 7.6 Implementiere Wissensdatenbank-Source
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/sources/wissensdatenbank.py`
+    - Implementiere Adapter für `bahn/wissensdatenbank/output/`
+    - Führe Artefakte als Read-Only-Referenzen im Index (`source: wissensdatenbank`)
+    - Lasse Originaldateien unverändert (kein Google-OKF-Reformat)
+    - _Requirements: 13.1, 13.2, 13.3, 13.4, 13.5_
+
+- [x] 8. Checkpoint – Source Strategies
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 9. Enrichment Agent
+  - [x] 9.1 Implementiere EnrichmentAgent
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/enrichment.py`
+    - Implementiere `enrich(content, source_type)` → EnrichmentResult (title, category, tags, people, projects, action_items, confidence)
+    - Implementiere `classify_relevance(content)` → float
+    - Implementiere Kiro-first Provider-Strategie (kein API-Key nötig im Normalfall)
+    - Implementiere Konfidenz-Schwelle: nur Entitäten ≥ 0.7 in Ausgabe
+    - Generiere Wiki-Links: `[[people/vorname-nachname]]`, `[[projects/projekt-slug]]`
+    - Generiere `## Action Items`-Abschnitt aus erkannten ActionItems
+    - Setze `enrichment_pending: true` falls Provider nicht erreichbar
+    - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.7_
+
+  - [x] 9.2 Property-Tests: Enrichment
+    - **Property 15: Wiki-Link Format for Entities**
+    - **Property 16: Confidence Threshold Filtering**
+    - **Property 17: Action Items Section Generation**
+    - **Validates: Requirements 9.2, 9.4, 9.5**
+
+- [x] 10. Ingestion Pipeline Orchestrator
+  - [x] 10.1 Implementiere IngestionPipeline
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/pipeline.py`
+    - Implementiere `run()`: load config → extract (via Strategies) → enrich → store → index → commit
+    - Implementiere `process_inbox()`: verarbeite alle Dateien in `{context}/knowledge/inbox/`
+    - Implementiere inkrementelle Verarbeitung via Content-Hash (skip unchanged)
+    - Implementiere Fail-Forward: einzelne Source-Fehler loggen, Rest weiterverarbeiten
+    - Aktualisiere `_index.yaml` nach jedem Durchlauf
+    - Aktualisiere `index.md` pro Unterordner (OKF-Konformität)
+    - Gib `IngestionResult` zurück (processed, updated, skipped, errors, tasks_created, commit_sha)
+    - _Requirements: 2.2, 2.3, 2.4, 2.5, 2.6, 3.4, 3.5, 3.6, 12.3_
+
+  - [x] 10.2 Property-Tests: Ingestion Pipeline
+    - **Property 3: Idempotent Ingestion via Content Hash**
+    - **Property 4: Error Resilience – Partial Source Failure**
+    - **Property 5: Index Completeness After Ingestion**
+    - **Property 24: Ingestion Produces Valid Artifacts**
+    - **Validates: Requirements 2.2, 2.4, 2.5, 2.6**
+
+- [x] 11. Integrationen
+  - [x] 11.1 Implementiere OrgMyLife-Integration
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/orgmylife.py`
+    - Implementiere `create_tasks(artifact_id, action_items, source_path)` → list[TaskMapping]
+    - Implementiere Deduplication via `.task-mapping.yaml` (Hash-basiert)
+    - Erstelle Tasks nur für neue Action-Items (nicht bereits gemappte)
+    - Setze Deadline falls im ActionItem erkannt
+    - Behandle API-Fehler graceful (Warnung loggen, weiter)
+    - _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5, 10.6_
+
+  - [x] 11.2 Property-Test: Task Deduplication
+    - **Property 18: Task Deduplication via Mapping**
+    - **Validates: Requirements 10.5, 10.6**
+
+  - [x] 11.3 Implementiere Git-Auto-Commit-Integration
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/git_integration.py`
+    - Implementiere Commit-Message-Generierung im Format `knowledge({context}): {action} {count} artifacts from {source}`
+    - Implementiere `auto_commit(context, action, count, source, paths)` – staged + committed
+    - Respektiere `--no-commit`-Flag und `git.auto_commit`-Config
+    - Behandle Git-Fehler graceful (Warnung, Dateien bleiben)
+    - _Requirements: 16.1, 16.2, 16.3, 16.4, 16.5_
+
+  - [x] 11.4 Property-Test: Git Commit Message Format
+    - **Property 23: Git Commit Message Format**
+    - **Validates: Requirements 16.2**
+
+  - [x] 11.5 Implementiere Kiro-Client-Integration
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/integrations/kiro_client.py`
+    - Implementiere Wrapper für Kiro AI-Agent als LLM-Provider (Enrichment + OCR)
+    - Implementiere Fallback-Logik: Kiro nicht verfügbar → `enrichment_pending: true`
+    - _Requirements: 9.3, 9.7_
+
+- [x] 12. Checkpoint – Pipeline und Integrationen
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 13. Suche und Federation
+  - [x] 13.1 Erweitere die Suche um Knowledge-Folder-Support
+    - Erweitere `store.py` um kontextübergreifende Suche über alle `_index.yaml`-Dateien
+    - Implementiere Scope-Filterung (nur autorisierte Kontexte in Ergebnissen)
+    - Implementiere Agent-Context-Injection: max. 10 relevante Artefakt-Pfade, sortiert nach Relevanz
+    - Implementiere Progressive-Disclosure: Schicht 1 (Index) für Relevanz, Schicht 2 (Datei) bei Bedarf
+    - _Requirements: 11.1, 11.2, 11.3, 11.5, 11.6_
+
+  - [x] 13.2 Property-Tests: Suche
+    - **Property 19: Scope-Filtered Search Isolation**
+    - **Property 20: Context Injection Result Limit**
+    - **Validates: Requirements 11.5, 11.6**
+
+  - [x] 13.3 Implementiere Federation-Sync-Filter
+    - Erweitere die bestehende Federation-Logik um Knowledge-Ordner-Behandlung
+    - Exkludiere Artefakte mit `shareable: false` aus der Sync-Liste
+    - Exkludiere ctx-guard-markierte sensible Artefakte
+    - Stelle sicher, dass keine kontextübergreifenden Links in Team-Repos gelangen
+    - _Requirements: 14.1, 14.2, 14.3, 14.4, 14.5_
+
+  - [x] 13.4 Property-Test: Federation Sync Exclusion
+    - **Property 22: Federation Sync Exclusion**
+    - **Validates: Requirements 14.4**
+
+- [x] 14. CLI-Schnittstelle
+  - [x] 14.1 Implementiere das knowledge-Subcommand
+    - Erstelle `shared/tools/monorepo-cli/src/monorepo/knowledge/cli.py`
+    - Registriere als Subcommand-Gruppe unter dem Monorepo-CLI
+    - Implementiere `knowledge capture <text|url|path> [--context CTX] [--tags TAG,TAG]`
+    - Implementiere `knowledge ingest [--context CTX] [--dry-run] [--verbose] [--no-commit]`
+    - Implementiere `knowledge search <query> [--context CTX] [--limit N]`
+    - Implementiere `knowledge status [--context CTX]`
+    - Implementiere `knowledge link <url> [--title TITLE] [--tags TAG,TAG] [--context CTX]`
+    - Implementiere Hilfe-Ausgabe bei Aufruf ohne Argumente
+    - Leite Kontext aus `--context`-Flag oder CWD ab
+    - _Requirements: 15.1, 15.2, 15.3, 15.4, 15.5, 15.6, 15.7_
+
+  - [x] 14.2 Unit-Tests: CLI-Argument-Parsing
+    - Teste alle Subcommands mit verschiedenen Flag-Kombinationen
+    - Teste Kontext-Ableitung aus CWD
+    - Teste Hilfe-Ausgabe
+    - _Requirements: 15.2, 15.3, 15.7_
+
+- [x] 15. End-to-End-Wiring und Integration
+  - [x] 15.1 Verdrahte alle Komponenten im Pipeline-Orchestrator
+    - Verbinde CLI → Router → Pipeline → Sources → Enrichment → Store → Index → Git
+    - Stelle sicher, dass `knowledge ingest` den vollständigen Workflow durchläuft
+    - Stelle sicher, dass `knowledge capture` → Inbox → nächster `ingest`-Durchlauf → Kategorisierung funktioniert
+    - Verbinde OrgMyLife-Integration (Task-Erstellung bei Action-Items)
+    - Aktualisiere `__init__.py` aller Module mit korrekten Exports
+    - _Requirements: 2.1, 2.2, 2.3, 3.4, 10.1_
+
+  - [x] 15.2 Integration-Tests: Full Pipeline E2E
+    - Teste vollständigen Pipeline-Durchlauf mit Fixture-Daten
+    - Teste Quick Capture → Inbox → Ingest → Kategorisierung
+    - Teste Confluence- und Jira-Source mit gemockten API-Responses
+    - _Requirements: 2.2, 2.3, 5.1, 6.1_
+
+- [x] 16. Final Checkpoint – Alle Tests bestehen
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Tasks mit `*` markiert sind optional und können für ein schnelleres MVP übersprungen werden
+- Jede Task referenziert spezifische Requirements für Nachvollziehbarkeit
+- Checkpoints sichern inkrementelle Validierung
+- Property-Tests validieren universelle Korrektheitseigenschaften aus dem Design-Dokument
+- Unit-Tests validieren spezifische Beispiele und Edge Cases
+- Die bestehenden Module in `shared/tools/monorepo-cli/src/monorepo/knowledge/` (artifact.py, etl.py, index.py, store.py) werden wiederverwendet und erweitert – nicht neu geschrieben
+- Kiro ist der primäre LLM/OCR-Provider; LiteLLM und Tesseract sind optionale Alternativen für CI/Batch
+
+## Task Dependency Graph
+
+```json
+{
+  "waves": [
+    { "id": 0, "tasks": ["1.1", "1.2"] },
+    { "id": 1, "tasks": ["2.1", "2.3"] },
+    { "id": 2, "tasks": ["2.2", "2.4", "3.1"] },
+    { "id": 3, "tasks": ["3.2", "5.1"] },
+    { "id": 4, "tasks": ["5.2", "6.1"] },
+    { "id": 5, "tasks": ["6.2", "6.3", "7.4", "7.6"] },
+    { "id": 6, "tasks": ["6.4", "7.1", "7.2", "7.3", "7.5"] },
+    { "id": 7, "tasks": ["9.1"] },
+    { "id": 8, "tasks": ["9.2", "10.1"] },
+    { "id": 9, "tasks": ["10.2", "11.1", "11.3", "11.5"] },
+    { "id": 10, "tasks": ["11.2", "11.4", "13.1", "13.3"] },
+    { "id": 11, "tasks": ["13.2", "13.4", "14.1"] },
+    { "id": 12, "tasks": ["14.2", "15.1"] },
+    { "id": 13, "tasks": ["15.2"] }
+  ]
+}
+```