Orchestrator/docs/TODO.md

# TODO / Roadmap

## Leitprinzipien (immer beachten)

- **Qualitaet vor Menge.** Lieber weniger, dafuer sauberes/freigegebenes Wissen.
- **Einfach konfigurierbar.** Neues Wissen ueber `config/tools.yaml` /
  `config/general.yaml` ergaenzbar (Domaene/Tool + Link + Strategie + Scope),
  ohne Code zu aendern.
- **Transparenz.** Jederzeit sichtbar, welches Wissen wo liegt und mit welchen Tags
  (GitLab Pages: Uebersicht + Wissensquellen, Frontmatter).



## Offen (Code/Inhalt)

### Bugs / beobachten
- [x] **Confluence-Abruf schlug im CI fehl** (gefunden 2026-06-28 im ETL-Log): alle
  `confluence_*`-Quellen brachen mit `No scheme supplied` ab (CI-Variable `CONFLUENCE_URL`
  ohne `https://`) -> pathos/nur/mateo/infraportal/rechnungsbahnhof wurden nicht
  aktualisiert. **URL inzwischen korrigiert** - der naechste ETL-Lauf muss bestaetigen,
  dass es wieder laedt (jetzt in `output/run_log.jsonl` als `sources_failed: 0` sichtbar).
- [ ] **ETL-Sichtung insb. wegen Dateigroesse** (naechster Check: 2026-06-30): nach dem
  Merge von `chore/data-to-output` (v2.0.0) pruefen, ob der naechste ETL-Lauf sauber
  durchlaeuft (output/staging-Trennung in CI korrekt? `run_log.jsonl` Fehler-frei?).
  Ausserdem Repo-Groesse im Auge behalten – gerade die INB-Chunks erzeugen viele
  Dateien. Ggf. alte Chunk-Generationen (`output/chunks/`) per Shallow-Clone oder
  LFS-Strategie entschaerfen, falls das Repo >500 MB waechst.

### Monitoring / Logging
- [ ] **ETL-Laeufe regelmaessig pruefen** - jetzt einfach ueber `output/run_log.jsonl`
  (letzte Laeufe inkl. Fehler je Quelle) bzw. die Health-Zeile in der Pages-Fusszeile.
- [x] **Lauf-Log umgesetzt** (`output/run_log.jsonl`, append-only, gekappt auf 500):
  Zeit, verarbeitete Dokumente, Status-Counts, Fehler je Quelle; Health-Zeile auf der
  Uebersicht; Manifest-Eintrag auf der Chatbot-Seite. (v1.3.0)

### Inhalt / Datenqualitaet
- [x] **Dedup ueberlappender Quellen** (v1.4.0): gleiche Seite je scope/domaene nur ein
  Dokument (Gate-Dedup per `page_identity`, spezifischere Aufbereitung gewinnt) +
  `prune_duplicate_files`. Einmalig 42 Alt-Duplikate entfernt (v.a. `nur`).
- [x] **pathOS „FAQ PathOS Extern" wieder erfasst** (v1.3.1): Seite ist h2/Absatz-basiert,
  nicht als Q/A-Tabelle -> Strategie von `confluence_faq` auf `confluence_page` umgestellt.
  Vorher landete das komplette externe FAQ leer in pending.
- [x] **Confluence-Anhaenge (eingebundene PDFs) werden erfasst** (v1.5.0): bei
  `confluence_page`/`confluence_tree` werden `view-file`/`viewpdf`-Anhaenge ueber den
  PDF-Parser zu Markdown und als eigene Dokumente (`kind: attachment`, `parent_url` ->
  Seite) abgelegt. Inkrementell. Default an, per `options: { attachments: false }`
  abschaltbar. Bilder: alt-Text bleibt als `[Bild: ...]` erhalten (Variante A).
  Offen/optional: drawio-Diagramme (Text aus XML extrahieren) - aktuell nicht erfasst.
- [x] **INB-Sectioning / Chunking** umgesetzt (v1.1.0/1.2.0): heading-basiert,
  deterministisch, inkrementell, `output/chunks/`, Katalog `output/_index.json`. Default aus,
  aktiv fuer INB. Spaeter ggf. weitere grosse Dokumente (Regelwerk).

### Ideen (Konzept steht, Entscheidung offen)
- [ ] **#1 Nachtraegliches Taggen.** Regelbasiert: `config/tag_rules.yaml`
  (match: domain/url/titel/keyword -> add_tags) + Befehl `python -m src.retag`, der
  NUR die `tags:`-Zeile im Frontmatter neu schreibt (Body unveraendert -> content_hash
  stabil, kein Netz, idempotent), committet. Optional spaeter LLM/Keyword-Vorschlaege,
  die in die Regeln einfliessen. Auf Pages ggf. Tag-Filter/Tag-Wolke. Gut v.a. fuer
  allgemeines Wissen (Kundeninfos). Aufwand: mittel.
- [ ] **#5 Intern/extern aus EINER Confluence-Seite trennen.** Regel: extern ⊆ intern
  (nur EINE Richtung). Marker fuer interne Abschnitte (Konvention zu entscheiden:
  Panel/Info-Makro vs. Textmarker `[[intern]]..[[/intern]]` vs. Ueberschrift „Nur intern").
  Quelle `scope: "intern,extern"`: intern = ganze Seite; extern = interne Bloecke
  entfernt (zu kurz -> nur intern). Sicherheitsnetz: content_filter prueft extern weiter.
  Erkennung im `md_converter` + Tests + Redakteurs-Doku. Aufwand: mittel-hoch, Leak-Risiko
  bei vergessenem Marker -> „im Zweifel raus".

### Bedienbarkeit
- [ ] Helfer `scripts/add_tool.py` (interaktiv: Domaene + Link + Strategie + Scope,
  inkl. yaml-Validierung) als Zwischenschritt zur Web-App.
- [ ] **Web-App (Option C, mittelfristig):** Flask auf DBCS, Formular ->
  GitLab-API legt MR an, mit Live-Vorschau. Pages verlinkt darauf. (Skill
  `dbcs-python-webapp`.)
- [ ] **Issue->MR-Bot verdrahten:** Webhook-Service ODER scheduled `glab`-Job, der
  `scripts/issue_to_source.py` ausfuehrt und automatisch einen MR samt Vorschau anlegt.
  (Bausteine `scripts/issue_to_source.py` + `scripts/issue_to_mr.sh` sind da.)

### Quality Gates
- [ ] **`min_quality`-Schwelle** in `filter_rules.json`: `content_filter` setzt Docs
  unter der Schwelle auf `pending` („niedrige Qualitaet"). Erst Verteilung sichten,
  dann aktiv schalten. (Score + Aufschluesselung sind jetzt auf den Pages sichtbar.)
- [ ] **gitleaks-Baseline** (`.gitleaks.toml`) fuer False Positives in `data/`, dann
  `secret-scan` scharf schalten (aktuell `allow_failure: true`).

### Vereinfachungen
- [x] **Strategie `kundeninfo` entfernt** (war redundant zu `crawler`/`sitemap`); inkl.
  `ComponentType.KUNDENINFO` + `ComponentType.DEEPLINK` (beide ungenutzt).
- [x] **`docs/catalog.md` (src/catalog.py) abgeschafft** – Seite „Wissensquellen"
  (config.html) ersetzt es.
- [x] **`docs/review_queue.md` (src/review_queue.py) abgeschafft** – Pages-Uebersicht
  zeigt pending/rejected inkl. Grund + Aktionslinks.
- `--only` bleibt (vom MR-`preview`-Job genutzt).

### Betrieb / Skalierung
- [ ] **CI-Timeout** fuer `knowledge-etl` im Auge behalten (inkrementell unkritisch,
  ein Timeout wird vom naechsten Lauf nachgeholt).
- Hinweis: Korpus bleibt bewusst in Git (kein externer Speicher) – Repo = Single
  Source of Truth.

---

## Out of scope (vorerst, bewusst zurueckgestellt)

- Mehr externes Wissen pro Tool (eigene kund:innenfaehige Confluence-Seite).
- Owners-Backfill fuer alte kundeninfo-/INB-Dokumente (bleiben ohne Owner).

---

## Erledigt (Kern)

- [x] ETL-Grundgeruest: Extract (Confluence/Web/Sitemap/PDF/GitLab/File) -> Transform
  (md_converter, tagger, content_filter) -> Review-Gate (approved/pending).
- [x] Strategien: confluence_page/tree/faq, crawler, sitemap, pdf, **gitlab_md**, **file**.
- [x] Strategie-Erkennung pro URL (`src/strategy_detect.py`), unbekannte URLs flaggen.
- [x] Scope-Modell: tool-weit `intern|extern|allgemein|mixed`, source `intern,extern`
  (ganze Seite fuer beide). Pro-Seite-Trennlogik bewusst entfernt.
- [x] Output `output/processed/<scope>/<domaene>[/<tool>]` IST der Vektor-DB-Feed
  (kein separater ingest-Export).
- [x] Gate 2: Allowlist `config/approvals.yaml` (URL/Hash) im content_filter;
  `review_notes` erklaeren WARUM pending.
- [x] Quality-Score (0-100) pro Dokument (`src/quality.py`), auf Pages + Hilfe erklaert.
- [x] **INB-Feintuning**: `pymupdf4llm`-Parser (`parser: pymupdf`) -> echte
  Markdown-Tabellen; INB 2026/2027 + Regelwerk; PDF-Connector inkrementell (`max_pdfs`,
  `keep_raw`, `redact`-Option).
- [x] **Confluence inkrementell** (`options: { incremental: true }`): Versions-Check
  pro Seite, unveraenderte Seiten werden uebersprungen (`source_version` im Frontmatter).
- [x] GitLab Pages (DB-UX): Logo, Footer (Sebastian Reinig · V.IWF 91 · #Einfachbahn),
  Filter (extern/intern/allgemein/pending), Suche, Quality-Score sichtbar,
  Modal mit Inhalt/Quality-Aufschluesselung/Aktionslinks.
- [x] **Smoke-Test** fuer `src.site.build()` (erzeugt index/hilfe/chatbot/config/changelog + json).
- [x] **Hilfe-Seite** (`hilfe.html`): Strategien-Tabelle, Ablauf, pending/rejected-Gruende.
- [x] **Chatbot-Anschluss-Seite** (`chatbot.html`): welche Pfade pro Bot-Typ, wie
  Frontmatter zu interpretieren ist, Pruefhinweis, RAG-Ablauf.
- [x] CI: **PyPI-Mirror** (`PIP_INDEX_URL`) statt Deps-Image; test/etl/pages ohne
  Custom-Image. Test-Fix `python -m pytest`. renovate.
- [x] CI: stuendlicher Daten-Commit (Mo-Fr 8-17) loest `pages`-Refresh aus (kein `ci.skip` mehr),
  damit die Live-Seite nach dem Schedule aktuell ist.
- [x] Owners (1-2 Ansprechpartner) pro Tool/Quelle -> Frontmatter/Katalog/Pages.
- [x] Issue-/MR-Templates, CODEOWNERS, `docs/SETUP.md`, scm-info.yaml,
  Architektur-Steering mit Diagrammen.
- [x] Pages: einheitliches Sticky-Menu auf allen Seiten (Logo + Uebersicht/
  Wissensquellen/Chatbot/Hilfe + CTA), Zaehler (Dokumente, Quellen); Ziel prominent;
  Strategien gruppiert/vereinfacht; Konfig-Transparenzseite (config.html).
- [x] Pages: **Domaenen-Filter** auf der Uebersicht (Dropdown mit Anzahl je Domaene).
- [x] CI: MR-Vorschau ueber GitLab-Pages parallel deployments (`pages.path_prefix`),
  Produktion auf Root.