# 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"] }
  ]
}
```