Orchestrator/.kiro/specs/knowledge-management/requirements.md

Requirements Document

Introduction

Dieses Dokument beschreibt die Anforderungen für ein vereinheitlichtes persönliches Wissensmanagement-System, das in die bestehende Monorepo-Struktur integriert wird. Das System ersetzt die nicht funktionierende NoteGraph-App und baut auf dem bereits implementierten Knowledge Store (ETL-Pipeline, YAML-Index, Scope-basierte Suche) sowie der NoteGraph-Ingestion-Pipeline (OCR, LLM-Enrichment, Entity-Detection) auf.

Kernziel: Wissen aus allen drei Arbeitskontexten (bahn, dhive, privat) erfassen, organisieren und für den AI-Orchestrator nutzbar machen – mit Quellen wie Markdown-Notizen, handschriftlichen Aufzeichnungen (reMarkable), Confluence, Jira, E-Mails, Chat-Exporten und Web-Links.

Architekturentscheidungen:

• Jeder Kontext erhält einen eigenen knowledge/-Ordner (kontextlokale Ablage)
• Eine gemeinsame Ingestion-Pipeline im shared-Bereich mit kontextbasiertem Routing
• Die bahn/wissensdatenbank bleibt als Upstream-Quelle bestehen; bahn/knowledge/ enthält zusätzlich persönliches Bahn-Wissen
• Workflow: Quick Capture → Inbox → Verarbeitung → Organisation
• Google Open Knowledge Format (OKF) als verbindliches Strukturprinzip für alle eigenen Wissensartefakte (privat, dhive, persönliches bahn-Wissen): ein Konzept pro Datei, Markdown mit YAML-Frontmatter, Cross-Links als Graph-Kanten, index.md pro Verzeichnis. Die Wissensdatenbank (Upstream DB-InfraGO) ist davon ausgenommen und behält ihr bestehendes Format.

Glossary

• Knowledge_Management_System: Das Gesamtsystem zur Erfassung, Verarbeitung, Organisation und Abfrage von persönlichem Wissen über alle Arbeitskontexte hinweg
• Kontext_Knowledge_Folder: Der kontextspezifische Ordner (bahn/knowledge/, dhive/knowledge/, privat/knowledge/) zur lokalen Ablage verarbeiteter Wissensartefakte
• Ingestion_Pipeline: Die gemeinsame Verarbeitungspipeline im shared-Bereich, die Rohdaten aus verschiedenen Quellen in strukturierte Wissensartefakte transformiert
• Inbox: Der Eingangsordner pro Kontext ({context}/knowledge/inbox/), in dem unverarbeitete Rohdaten und Quick-Captures landen
• Quellstrategie: Ein austauschbarer Adapter, der eine bestimmte Quelle (Confluence, Jira, E-Mail, Markdown, etc.) anbindet und Rohdaten extrahiert
• Wissensartefakt: Eine strukturierte Markdown-Datei mit YAML-Frontmatter, die ein einzelnes Wissenselement repräsentiert (Notiz, Meeting-Protokoll, Entscheidung, Referenz, Link)
• YAML_Index: Der maschinenlesbare Index pro Kontext-Knowledge-Folder, der kompakte Metadaten aller Artefakte enthält (Progressive Disclosure Schicht 1)
• Enrichment_Agent: Die LLM-gestützte Komponente, die Rohdaten analysiert, Entitäten erkennt, Tags generiert und Artefakte kategorisiert
• Quick_Capture: Der vereinfachte Erfassungsmechanismus für schnelle Notizen, Links oder Ideen ohne manuelle Metadaten-Eingabe
• Kontext_Router: Die Komponente, die eingehende Daten anhand von Quelltyp und Konfiguration dem richtigen Arbeitskontext zuordnet
• Link_Registry: Die Verwaltung gespeicherter Web-Links als Referenzmaterial mit Tags und Kontext-Zuordnung
• Federation_Sync: Der Mechanismus, der kontextlokales Wissen mit dem jeweiligen Team-Repo synchronisiert
• OCR_Engine: Die Komponente zur Texterkennung aus Bildern und gescannten PDFs (reMarkable-Exporte, Whiteboard-Fotos)
• Wissensdatenbank: Die bestehende ETL-Pipeline in bahn/wissensdatenbank/ für DB-InfraGO-Wissen (Confluence, Web, PDFs)
• Google_OKF: Das Google Open Knowledge Format – ein Strukturprinzip für Wissensartefakte: ein Konzept pro Datei, Markdown mit YAML-Frontmatter, Cross-Links als Graph-Kanten, index.md pro Verzeichnis für Inhaltsübersichten. Verbindlich für alle eigenen Artefakte (privat, dhive, persönliches bahn-Wissen); nicht verbindlich für Upstream-Wissensdatenbank-Artefakte

Requirements

Requirement 1: Kontextlokale Wissensordner-Struktur

User Story: Als Wissensarbeiter möchte ich in jedem Arbeitskontext einen dedizierten Knowledge-Ordner haben, damit mein Wissen kontextnah organisiert ist und die Sicherheitsgrenzen des Monorepos automatisch greifen.

Acceptance Criteria

1. THE Knowledge_Management_System SHALL für jeden Arbeitskontext (bahn, dhive, privat) einen eigenen Kontext_Knowledge_Folder unter {context}/knowledge/ bereitstellen
2. THE Kontext_Knowledge_Folder SHALL folgende Unterordner enthalten: inbox/, meetings/, decisions/, projects/, people/, references/, links/
3. THE Kontext_Knowledge_Folder SHALL einen eigenen YAML_Index (_index.yaml) bereitstellen, der alle lokalen Artefakte mit kompakten Metadaten (Titel, Tags, Typ, Erstelldatum, Content-Hash, Verknüpfungen) indexiert
4. WHEN ein Wissensartefakt in einem Kontext_Knowledge_Folder erstellt wird, THE Knowledge_Management_System SHALL den Quellkontext automatisch aus dem Dateipfad ableiten und im YAML-Frontmatter als source_context eintragen
5. THE Kontext_Knowledge_Folder SHALL die bestehende Artefakt-Struktur des Knowledge Store verwenden: Markdown-Dateien mit YAML-Frontmatter (mindestens type, title, tags, source_context, created, content_hash, links)
6. THE Kontext_Knowledge_Folder SHALL dem Google_OKF folgen: ein Konzept pro Datei, Cross-Links als Graph-Kanten im Frontmatter, und eine index.md-Datei pro Unterordner, die als Inhaltsverzeichnis dient und bei jedem Ingestion-Durchlauf aktualisiert wird
7. WHILE der bestehende Knowledge Store im shared-Bereich existiert, THE Knowledge_Management_System SHALL die Kontext_Knowledge_Folder als primäre Ablageorte verwenden und den shared Knowledge Store als übergreifenden Suchindex beibehalten

Requirement 2: Gemeinsame Ingestion-Pipeline mit Kontext-Routing

User Story: Als Wissensarbeiter möchte ich eine einheitliche Verarbeitungspipeline für alle Quellen haben, die eingehende Daten automatisch dem richtigen Kontext zuordnet, damit ich nicht für jeden Kontext separate Tools betreiben muss.

Acceptance Criteria

1. THE Ingestion_Pipeline SHALL als gemeinsames Modul im shared-Bereich (shared/tools/monorepo-cli/src/monorepo/knowledge/ingestion/) implementiert werden
2. THE Ingestion_Pipeline SHALL Rohdaten aus einer konfigurierbaren Menge von Quellstrategien entgegennehmen und in strukturierte Wissensartefakte transformieren
3. WHEN Rohdaten verarbeitet werden, THE Kontext_Router SHALL den Zielkontext anhand der Quellkonfiguration bestimmen und das resultierende Artefakt im entsprechenden Kontext_Knowledge_Folder ablegen
4. THE Ingestion_Pipeline SHALL inkrementelle Verarbeitung über Content-Hashes unterstützen, wobei nur neue oder geänderte Inhalte verarbeitet werden
5. WHEN die Verarbeitung einer einzelnen Quelle fehlschlägt, THE Ingestion_Pipeline SHALL den Fehler mit Quellidentifikator und Zeitstempel protokollieren und mit den verbleibenden Quellen fortfahren
6. THE Ingestion_Pipeline SHALL nach jedem Verarbeitungsdurchlauf den YAML_Index des betroffenen Kontext_Knowledge_Folders aktualisieren, sodass neue Artefakte sofort auffindbar sind
7. THE Ingestion_Pipeline SHALL die bestehenden ETL-Quellstrategien der Wissensdatenbank wiederverwenden können (confluence_page, confluence_tree, crawler, sitemap, gitlab_md, file, pdf)

Requirement 3: Quick Capture und Inbox-Workflow

User Story: Als Wissensarbeiter möchte ich schnell Notizen, Links und Ideen erfassen können, die später automatisch verarbeitet und eingeordnet werden, damit ich im Arbeitsfluss bleibe und nichts verloren geht.

Acceptance Criteria

1. THE Quick_Capture SHALL eine CLI-Schnittstelle bereitstellen (knowledge capture), die einen Freitext, eine URL oder einen Dateipfad entgegennimmt und als Rohartefakt in der Inbox des angegebenen Kontexts ablegt
2. WHEN kein Kontext explizit angegeben wird, THE Quick_Capture SHALL den Kontext aus dem aktuellen Arbeitsverzeichnis ableiten
3. THE Quick_Capture SHALL das erfasste Element mit minimalem Frontmatter (title, created, source, type: inbox) als Markdown-Datei im Format YYYY-MM-DD-HH-MM-title-slug.md in {context}/knowledge/inbox/ ablegen
4. THE Inbox SHALL einen Drop-Folder-Mechanismus bereitstellen, der neue Dateien im Inbox-Ordner automatisch erkennt und zur Verarbeitung durch die Ingestion_Pipeline einreiht
5. WHEN ein Inbox-Element von der Ingestion_Pipeline verarbeitet wird, THE Enrichment_Agent SHALL das Element analysieren, kategorisieren und in den passenden Unterordner des Kontext_Knowledge_Folders verschieben (meetings, decisions, projects, references)
6. IF der Enrichment_Agent keine klare Kategorie bestimmen kann, THEN THE Ingestion_Pipeline SHALL das Artefakt im inbox/-Ordner belassen und mit dem Tag unclassified versehen
7. WHEN ein Quick_Capture ein erfolgreich abgelegt wird, THE Quick_Capture SHALL den Dateipfad des erstellten Artefakts auf der Konsole ausgeben

Requirement 4: Multi-Source-Ingestion – Markdown und Dateien

User Story: Als Wissensarbeiter möchte ich Markdown-Dateien, PDFs und Bilder (reMarkable-Exporte, Whiteboard-Fotos) als Wissensquellen importieren können, damit meine handschriftlichen Notizen und Dokumente durchsuchbar werden.

Acceptance Criteria

1. WHEN eine Markdown-Datei als Quelle bereitgestellt wird, THE Ingestion_Pipeline SHALL den Inhalt inklusive bestehendem Frontmatter einlesen und als Wissensartefakt verarbeiten
2. WHEN eine Bilddatei (PNG, JPG, JPEG) als Quelle bereitgestellt wird, THE OCR_Engine SHALL den Text mittels OCR extrahieren und der Ingestion_Pipeline als Rohtext übergeben
3. WHEN eine PDF-Datei als Quelle bereitgestellt wird, THE Ingestion_Pipeline SHALL eingebetteten Text direkt extrahieren und für gescannte Seiten die OCR_Engine einsetzen
4. THE OCR_Engine SHALL für die Sprachkombination Deutsch und Englisch (deu+eng) konfiguriert sein
5. WHEN der Enrichment_Agent ein Bild-basiertes Artefakt verarbeitet, THE Enrichment_Agent SHALL eine Referenz auf die Originaldatei im Frontmatter-Feld source.file beibehalten
6. IF die OCR_Engine keinen lesbaren Text aus einem Bild extrahieren kann, THEN THE Ingestion_Pipeline SHALL das Artefakt mit leerem Textinhalt erstellen und im Frontmatter das Feld ocr_failed: true setzen
7. THE Ingestion_Pipeline SHALL die Dateiformat-Erkennung anhand der Dateiendung vornehmen und folgende Formate unterstützen: .md, .txt, .pdf, .png, .jpg, .jpeg, .docx

Requirement 5: Multi-Source-Ingestion – Confluence

User Story: Als Wissensarbeiter möchte ich Confluence-Seiten und -Bäume als Wissensquellen einbinden, damit relevantes Team-Wissen aus Confluence automatisch in meinem persönlichen Wissensspeicher verfügbar ist.

Acceptance Criteria

1. THE Ingestion_Pipeline SHALL eine Quellstrategie für Confluence bereitstellen, die einzelne Seiten, Seitenbäume und FAQ-Spaces importieren kann
2. WHEN eine Confluence-Quelle konfiguriert wird, THE Quellstrategie SHALL die Confluence-REST-API verwenden und Seiteninhalte als Markdown extrahieren
3. THE Quellstrategie SHALL pro Kontext eine separate Confluence-Instanz-Konfiguration unterstützen (bahn: DB-Confluence, dhive: dhive-Confluence)
4. WHEN eine Confluence-Seite aktualisiert wurde (erkannt über Versions-Nummer oder Last-Modified), THE Ingestion_Pipeline SHALL das zugehörige Artefakt inkrementell aktualisieren
5. THE Quellstrategie SHALL das Confluence-Seiten-Frontmatter mit Quell-URL, Space-Key, Seitentitel und letztem Aktualisierungsdatum anreichern
6. WHEN eine Confluence-Seite Anhänge enthält, THE Quellstrategie SHALL Anhänge als Referenz-Links im Artefakt vermerken
7. IF die Confluence-API nicht erreichbar ist, THEN THE Ingestion_Pipeline SHALL den Fehler protokollieren und den Verarbeitungsdurchlauf für diese Quelle überspringen, ohne bestehende Artefakte zu löschen

Requirement 6: Multi-Source-Ingestion – Jira

User Story: Als Wissensarbeiter möchte ich Jira-Issues und deren Kommentare als Wissensartefakte importieren, damit Entscheidungen und Diskussionen aus Jira-Tickets in meinem Wissensspeicher auffindbar sind.

Acceptance Criteria

1. THE Ingestion_Pipeline SHALL eine Quellstrategie für Jira bereitstellen, die Issues anhand von JQL-Filtern importiert
2. WHEN ein Jira-Issue importiert wird, THE Quellstrategie SHALL Summary, Description, Kommentare und Status als strukturiertes Markdown-Artefakt zusammenstellen
3. THE Quellstrategie SHALL das Artefakt-Frontmatter mit Issue-Key, Projekt, Status, Assignee, Reporter und Jira-URL anreichern
4. WHEN ein Jira-Issue seit dem letzten Import aktualisiert wurde (erkannt über updated-Feld), THE Ingestion_Pipeline SHALL das zugehörige Artefakt inkrementell aktualisieren
5. THE Quellstrategie SHALL konfigurierbare JQL-Filter pro Kontext unterstützen (z.B. project = ACV2 AND updatedDate > -7d für bahn)
6. WHEN Jira-Kommentare Action-Items enthalten (erkannt über den Enrichment_Agent), THE Ingestion_Pipeline SHALL diese als TODO-Einträge im Artefakt markieren
7. IF die Jira-API nicht erreichbar ist oder die Authentifizierung fehlschlägt, THEN THE Ingestion_Pipeline SHALL den Fehler mit API-Endpunkt protokollieren und den Verarbeitungsdurchlauf für diese Quelle überspringen

Requirement 7: Multi-Source-Ingestion – E-Mail und Chat

User Story: Als Wissensarbeiter möchte ich relevante E-Mail-Threads und Chat-Nachrichten als Wissensartefakte importieren, damit wichtige Informationen aus der Kommunikation nicht verloren gehen.

Acceptance Criteria

1. THE Ingestion_Pipeline SHALL eine Quellstrategie für E-Mails bereitstellen, die exportierte E-Mail-Dateien (.eml, .msg) oder Ordner mit E-Mails verarbeitet
2. WHEN eine E-Mail verarbeitet wird, THE Quellstrategie SHALL Absender, Empfänger, Betreff, Datum und Body als strukturiertes Markdown-Artefakt zusammenstellen
3. THE Ingestion_Pipeline SHALL eine Quellstrategie für Chat-Exporte bereitstellen, die Textdateien oder JSON-Exporte aus Chat-Systemen verarbeitet
4. WHEN der Enrichment_Agent eine E-Mail oder Chat-Nachricht analysiert, THE Enrichment_Agent SHALL explizit nach Action-Items, Entscheidungen und Deadlines suchen
5. THE Quellstrategie SHALL das Artefakt-Frontmatter mit Absender, Empfänger-Liste, Datum und Thread-Referenz anreichern
6. WHEN eine E-Mail Anhänge enthält, THE Quellstrategie SHALL Anhänge als separate Artefakte verarbeiten und über Links im Eltern-Artefakt referenzieren
7. IF eine E-Mail oder Chat-Nachricht keine verwertbare Information enthält (vom Enrichment_Agent als irrelevant klassifiziert), THEN THE Ingestion_Pipeline SHALL das Element überspringen und im Verarbeitungsprotokoll als skipped: low-relevance vermerken

Requirement 8: Link-Management

User Story: Als Wissensarbeiter möchte ich Web-Links als Referenzmaterial speichern und taggen können, damit ich wichtige Ressourcen pro Kontext organisiert wiederfinde.

Acceptance Criteria

1. THE Link_Registry SHALL Web-Links als Wissensartefakte vom Typ link im links/-Unterordner des jeweiligen Kontext_Knowledge_Folders speichern
2. WHEN ein Link gespeichert wird, THE Link_Registry SHALL die URL, einen optionalen Titel, Tags und den Speicherzeitpunkt im YAML-Frontmatter erfassen
3. THE Quick_Capture SHALL URLs automatisch erkennen und als Link-Artefakte behandeln, wenn der eingegebene Text eine gültige HTTP(S)-URL ist
4. WHEN ein Link-Artefakt erstellt wird, THE Ingestion_Pipeline SHALL versuchen den Seitentitel und eine Kurzbeschreibung von der Ziel-URL zu extrahieren (via HTTP-Request auf die Seite)
5. IF die Ziel-URL nicht erreichbar ist, THEN THE Link_Registry SHALL den Link dennoch speichern, mit dem vom Nutzer angegebenen Titel und dem Frontmatter-Feld fetch_failed: true
6. THE Link_Registry SHALL eine Suche über gespeicherte Links nach URL, Titel und Tags unterstützen
7. THE Link_Registry SHALL duplikate URLs innerhalb eines Kontexts erkennen und bei erneutem Speichern die Tags des bestehenden Artefakts ergänzen statt ein neues Artefakt zu erstellen

Requirement 9: LLM-gestützte Anreicherung und Kategorisierung

User Story: Als Wissensarbeiter möchte ich, dass importierte Inhalte automatisch mit Tags, Kategorien und erkannten Entitäten angereichert werden, damit ich weniger manuelle Metadaten-Pflege betreiben muss.

Acceptance Criteria

1. WHEN ein Rohartefakt verarbeitet wird, THE Enrichment_Agent SHALL den Inhalt analysieren und folgende Metadaten generieren: Titel (sofern nicht vorhanden), Kategorie (meeting, decision, project, reference, inbox), Tags, erkannte Personen und Projekte
2. THE Enrichment_Agent SHALL erkannte Personen als Wiki-Links im Format [[people/vorname-nachname]] und Projekte als [[projects/projekt-slug]] in den Artefakt-Body einfügen
3. THE Enrichment_Agent SHALL die modell-agnostische LLM-Schicht (LiteLLM) verwenden und über Umgebungsvariablen (LLM_PROVIDER, LLM_MODEL) konfigurierbar sein
4. WHEN der Enrichment_Agent Action-Items im Text erkennt, THE Enrichment_Agent SHALL diese in einem ## Action Items-Abschnitt am Ende des Artefakts zusammenfassen
5. THE Enrichment_Agent SHALL Entitäten nur mit einer Konfidenz von 0.7 oder höher in die Ausgabe übernehmen
6. WHEN der Enrichment_Agent ein Artefakt kategorisiert hat, THE Ingestion_Pipeline SHALL die Zielordner-Zuordnung aus der Kategorie ableiten (meeting → meetings/, decision → decisions/, project → projects/, link → links/, default → inbox/)
7. IF der LLM-Provider nicht erreichbar ist, THEN THE Ingestion_Pipeline SHALL das Artefakt mit minimalen Metadaten (Titel aus Dateiname, Kategorie inbox) im Inbox-Ordner ablegen und im Frontmatter enrichment_pending: true setzen

Requirement 10: OrgMyLife-Integration und Action-Item-Extraktion

User Story: Als Wissensarbeiter möchte ich, dass erkannte Action-Items automatisch als Tasks in OrgMyLife erstellt werden, damit Aufgaben aus Meetings und E-Mails nicht verloren gehen.

Acceptance Criteria

1. WHEN der Enrichment_Agent Action-Items in einem Artefakt erkennt, THE Ingestion_Pipeline SHALL optional für jedes Action-Item einen Task in OrgMyLife erstellen (steuerbar über Konfigurationsflag create_tasks)
2. WHEN ein OrgMyLife-Task erstellt wird, THE Ingestion_Pipeline SHALL den Task-Titel auf die Action-Item-Beschreibung setzen und im Feld source_url einen Verweis auf das Quell-Artefakt hinterlegen
3. WHEN ein Action-Item eine erkannte Deadline enthält, THE Ingestion_Pipeline SHALL das Fälligkeitsdatum im OrgMyLife-Task setzen
4. IF die OrgMyLife-API nicht erreichbar ist, THEN THE Ingestion_Pipeline SHALL eine Warnung protokollieren und die Verarbeitung ohne Task-Erstellung fortsetzen
5. THE Ingestion_Pipeline SHALL bereits erstellte Tasks nicht duplizieren, indem sie eine Mapping-Datei ({context}/knowledge/.task-mapping.yaml) führt, die Artefakt-ID und Action-Item-Hash auf OrgMyLife-Task-IDs abbildet
6. WHEN ein Artefakt erneut verarbeitet wird und neue Action-Items enthält, THE Ingestion_Pipeline SHALL nur für bisher nicht erfasste Action-Items neue Tasks erstellen

Requirement 11: Kontextübergreifende Suche und Agent-Context-Injection

User Story: Als Wissensarbeiter und als AI-Orchestrator möchte ich relevantes Wissen aus dem aktiven Kontext in Agenten-Prompts injizieren, damit der Agent fundierte Antworten auf Basis meines persönlichen Wissens geben kann.

Acceptance Criteria

1. THE Knowledge_Management_System SHALL eine einheitliche Suchschnittstelle bereitstellen, die über alle Kontext_Knowledge_Folder und den shared Knowledge Store sucht, gefiltert nach autorisierten Scopes
2. WHEN der AI-Orchestrator einen Task-Prompt zusammenstellt, THE Knowledge_Management_System SHALL die relevantesten Artefakte aus dem YAML_Index des aktiven Kontexts identifizieren und deren Pfade als Kontextinformation bereitstellen
3. THE Knowledge_Management_System SHALL die Suche über den Progressive-Disclosure-Ansatz realisieren: Schicht 1 (YAML_Index mit kompakten Metadaten) für schnelle Relevanzprüfung, Schicht 2 (vollständiges Dokument) nur bei Bedarf
4. WHEN eine Suchanfrage gestellt wird, THE Knowledge_Management_System SHALL Ergebnisse innerhalb von 5 Sekunden zurückgeben und bei Timeout-Überschreitung Teilergebnisse mit einer partial_results-Markierung liefern
5. THE Knowledge_Management_System SHALL die Sicherheitsgrenzen des ctx-guard-Systems respektieren und ausschließlich Artefakte aus autorisierten Kontexten in Suchergebnissen und Agent-Prompts berücksichtigen
6. WHEN der AI-Orchestrator Kontext injiziert, THE Knowledge_Management_System SHALL maximal 10 relevante Artefakt-Pfade pro Anfrage zurückliefern, sortiert nach Relevanz-Score

Requirement 12: Quellkonfiguration pro Kontext

User Story: Als Wissensarbeiter möchte ich pro Kontext definieren, welche Quellen regelmäßig importiert werden sollen, damit der Wissensimport automatisiert und kontextspezifisch abläuft.

Acceptance Criteria

1. THE Knowledge_Management_System SHALL eine Konfigurationsdatei pro Kontext bereitstellen ({context}/knowledge/sources.yaml), die alle aktiven Quellstrategien mit ihren Parametern definiert
2. THE Konfigurationsdatei SHALL pro Quellstrategie folgende Felder unterstützen: Typ (confluence, jira, email, file, link), Verbindungsparameter, Filterkriterien, Sync-Frequenz und Zielordner
3. WHEN die Ingestion_Pipeline gestartet wird, THE Ingestion_Pipeline SHALL alle in der sources.yaml des angegebenen Kontexts konfigurierten Quellen sequentiell verarbeiten
4. THE Konfigurationsdatei SHALL Secrets über Umgebungsvariablen-Referenzen einbinden (z.B. api_key: ${JIRA_API_TOKEN}) statt Klartext-Credentials zu enthalten
5. WHEN eine neue Quellstrategie zur Konfiguration hinzugefügt wird, THE Ingestion_Pipeline SHALL beim nächsten Durchlauf einen vollständigen Initial-Import dieser Quelle durchführen
6. THE Knowledge_Management_System SHALL eine Validierung der sources.yaml bereitstellen, die fehlende Pflichtfelder und nicht-auflösbare Umgebungsvariablen vor dem Start der Verarbeitung erkennt

Requirement 13: Wissensdatenbank-Integration (bahn-Kontext)

User Story: Als Wissensarbeiter im bahn-Kontext möchte ich, dass die bestehende Wissensdatenbank als Upstream-Quelle in mein Knowledge-System einfließt, damit ich DB-InfraGO-Wissen zusammen mit meinen persönlichen bahn-Notizen durchsuchen kann.

Acceptance Criteria

1. THE Knowledge_Management_System SHALL die Wissensdatenbank (bahn/wissensdatenbank/output/) als Quellstrategie vom Typ wissensdatenbank für den bahn-Kontext einbinden
2. WHEN die Wissensdatenbank aktualisiert wird (via Upstream-Sync), THE Ingestion_Pipeline SHALL geänderte Artefakte im bahn/knowledge/ YAML_Index aktualisieren, ohne die Originaldateien in bahn/wissensdatenbank/ zu verändern
3. THE Quellstrategie SHALL Artefakte aus der Wissensdatenbank als Read-Only-Referenzen im bahn-Knowledge-Index führen, mit dem Frontmatter-Feld source: wissensdatenbank und einer Referenz auf den Originalpfad
4. THE Quellstrategie SHALL Wissensdatenbank-Artefakte in ihrem Originalformat belassen und NICHT dem Google_OKF-Strukturprinzip unterwerfen (kein Splitting in Ein-Konzept-pro-Datei, keine erzwungene index.md-Generierung für Wissensdatenbank-Inhalte)
5. THE Knowledge_Management_System SHALL persönliche bahn-Notizen (Meetings, Entscheidungen) separat von Wissensdatenbank-Artefakten im bahn/knowledge/ ablegen, wobei persönliche Artefakte dem Google_OKF folgen und beide über den YAML_Index durchsuchbar sind
6. WHEN ein Wissensdatenbank-Artefakt und ein persönliches bahn-Artefakt thematisch verknüpft sind, THE Knowledge_Management_System SHALL bidirektionale Links zwischen beiden im YAML_Index unterstützen

Requirement 14: Federation und Team-Repo-Synchronisation

User Story: Als Wissensarbeiter möchte ich, dass mein kontextlokales Wissen über die bestehende Föderationsstruktur mit dem jeweiligen Team-Repo synchronisiert wird, damit relevantes Wissen auch im Team-Kontext verfügbar ist.

Acceptance Criteria

1. WHEN der Kontext_Knowledge_Folder eines Kontexts aktualisiert wird, THE Federation_Sync SHALL die Änderungen im Rahmen der regulären Team-Repo-Synchronisation (gemäß monorepo-consolidation Req 10) mit dem zugehörigen Team-Repo synchronisieren
2. THE Federation_Sync SHALL die bestehende team-repos.yaml-Konfiguration respektieren und den Knowledge-Ordner als Teil des Kontextordners behandeln (keine separate Sync-Konfiguration nötig)
3. WHILE Artefakte synchronisiert werden, THE Knowledge_Management_System SHALL sicherstellen, dass keine kontextübergreifenden Links oder Referenzen auf andere Kontexte in das Team-Repo gelangen
4. THE Knowledge_Management_System SHALL Artefakte mit dem Frontmatter-Feld shareable: false von der Federation-Synchronisation ausschließen
5. IF ein Artefakt sensible Inhalte enthält (erkannt über den bestehenden ctx-guard-Mechanismus), THEN THE Federation_Sync SHALL das Artefakt von der Synchronisation ausschließen und dies im Sync-Protokoll vermerken

Requirement 15: CLI-Schnittstelle

User Story: Als Wissensarbeiter möchte ich alle Knowledge-Management-Operationen über eine konsistente CLI-Schnittstelle ausführen, damit ich Wissen effizient von der Kommandozeile aus verwalten kann.

Acceptance Criteria

1. THE Knowledge_Management_System SHALL eine CLI-Schnittstelle als Unterkommando des Monorepo-CLI bereitstellen (monorepo knowledge oder knowledge)
2. THE CLI SHALL folgende Unterkommandos unterstützen: capture (Quick-Capture), ingest (Pipeline-Durchlauf starten), search (Suche über Knowledge-Index), status (Übersicht über Inbox-Elemente und letzte Verarbeitung)
3. THE CLI SHALL den aktiven Kontext über das Flag --context oder automatisch aus dem aktuellen Arbeitsverzeichnis ableiten
4. WHEN das Unterkommando ingest ausgeführt wird, THE CLI SHALL die sources.yaml des aktiven Kontexts laden und alle konfigurierten Quellen verarbeiten
5. THE CLI SHALL die Flags --dry-run (Vorschau ohne Schreiboperationen), --verbose (detaillierte Ausgabe) und --no-commit (Git-Commit überspringen) unterstützen
6. WHEN das Unterkommando search mit einem Suchbegriff ausgeführt wird, THE CLI SHALL die Ergebnisse mit Titel, Typ, Tags und Dateipfad auf der Konsole ausgeben
7. WHEN das CLI ohne Argumente aufgerufen wird, THE CLI SHALL eine Hilfe-Nachricht mit verfügbaren Unterkommandos und Beispielen anzeigen

Requirement 16: Git-Integration und Versionierung

User Story: Als Wissensarbeiter möchte ich, dass alle Wissensänderungen automatisch versioniert werden, damit ich die Historie meines Wissensspeichers nachvollziehen und bei Bedarf zurückspringen kann.

Acceptance Criteria

1. WHEN die Ingestion_Pipeline neue oder aktualisierte Artefakte erzeugt, THE Knowledge_Management_System SHALL diese automatisch mit einer beschreibenden Commit-Message in Git committen
2. THE Knowledge_Management_System SHALL die Commit-Message im Format knowledge({context}): {action} {count} artifacts from {source} generieren (z.B. knowledge(bahn): ingest 3 artifacts from confluence)
3. WHEN der Quick_Capture ein neues Artefakt erstellt, THE Knowledge_Management_System SHALL einen separaten Commit mit der Message knowledge({context}): capture "{title}" erzeugen
4. WHEN das Flag --no-commit gesetzt ist, THE Knowledge_Management_System SHALL keine Git-Commits erzeugen
5. IF ein Git-Commit fehlschlägt, THEN THE Knowledge_Management_System SHALL eine Warnung protokollieren, die erstellten Dateien beibehalten und die Verarbeitung fortsetzen
6. FOR ALL gültige Artefakt-Inhalte, das Schreiben in eine Markdown-Datei mit YAML-Frontmatter und anschließendes Einlesen SHALL ein identisches ArtifactMetadata-Objekt reproduzieren (Round-Trip-Eigenschaft)