ankn/Orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9c8728bd5b908162b8545cf5b6669f5d0852ff03
Orchestrator/.kiro/specs/knowledge-management/tasks.md
T

18 KiB
Raw Blame History

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

  • 1. Projekt-Struktur und Knowledge-Ordner anlegen

    • 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

    • 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

  • 2. Datenmodelle und Konfiguration

    • 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

    • 2.2 Property-Test: Artifact Serialization Round-Trip

      • Property 1: Artifact Serialization Round-Trip
      • Validates: Requirements 16.6, 1.5

    • 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

    • 2.4 Property-Test: Environment Variable Resolution

      • Property 21: Environment Variable Resolution in Config
      • Validates: Requirements 12.4, 12.6

  • 3. Context Router

    • 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

    • 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

  • 4. Checkpoint – Basis-Infrastruktur

    • Ensure all tests pass, ask the user if questions arise.

  • 5. Quick Capture und Inbox

    • 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

    • 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

  • 6. Source Strategies – Base und Markdown

    • 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

    • 6.2 Property-Test: File Extension Format Detection

      • Property 9: File Extension Format Detection
      • Validates: Requirements 4.7

    • 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

    • 6.4 Property-Test: Image Source File Reference

      • Property 10: Image Source File Reference Preservation
      • Validates: Requirements 4.5

  • 7. Source Strategies – Externe Quellen

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

  • 8. Checkpoint – Source Strategies

    • Ensure all tests pass, ask the user if questions arise.

  • 9. Enrichment Agent

    • 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

    • 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

  • 10. Ingestion Pipeline Orchestrator

    • 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

    • 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

  • 11. Integrationen

    • 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

    • 11.2 Property-Test: Task Deduplication

      • Property 18: Task Deduplication via Mapping
      • Validates: Requirements 10.5, 10.6

    • 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

    • 11.4 Property-Test: Git Commit Message Format

      • Property 23: Git Commit Message Format
      • Validates: Requirements 16.2

    • 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

  • 12. Checkpoint – Pipeline und Integrationen

    • Ensure all tests pass, ask the user if questions arise.

  • 13. Suche und Federation

    • 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

    • 13.2 Property-Tests: Suche

      • Property 19: Scope-Filtered Search Isolation
      • Property 20: Context Injection Result Limit
      • Validates: Requirements 11.5, 11.6

    • 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

    • 13.4 Property-Test: Federation Sync Exclusion

      • Property 22: Federation Sync Exclusion
      • Validates: Requirements 14.4

  • 14. CLI-Schnittstelle

    • 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

    • 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

  • 15. End-to-End-Wiring und Integration

    • 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

    • 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

  • 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

{
  "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"] }
  ]
}
Reference in New Issue View Git Blame Copy Permalink