feat: add epic retrospectives (3, 4, 5), update sprint status and project context

Co-authored-by: Kenearos <86194771+Kenearos@users.noreply.github.com>

_bmad-output/implementation-artifacts/epic-5-retro-2026-03-12.md

@@ -0,0 +1,100 @@
+# Retrospektive — Epic 5: Tools & God Mode (Phase 4)
+
+<!-- 🏃 Facilitiert von BMAD SM Skill — Agent: Bob (Scrum Master) -->
+<!-- Skill Command: /bmad-agent-bmm-sm → [ER] Epic Retrospective -->
+<!-- Workflow: _bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml -->
+
+**Datum:** 2026-03-12
+**Epic:** Epic 5 — Tools & God Mode (Phase 4)
+**Status:** Abgeschlossen — 4/4 Stories erledigt
+**Facilitiert von:** Bob (🏃 Scrum Master)
+
+---
+
+## 1. Epic-Zusammenfassung
+
+**Ziel:** Tavily-Web-Suche, PDF-Reader mit ChromaDB, und Human-in-the-Loop via `interrupt_before`.
+
+**Stories abgeschlossen:**
+- ✅ 5.1: Tavily Web-Suche als Agent-Tool
+- ✅ 5.2: PDF-Upload & ChromaDB-Ingestion
+- ✅ 5.3: God Mode — Human-in-the-Loop
+- ✅ 5.4: Run-Verlauf (History)
+
+---
+
+## 2. Was lief gut? (Keep)
+
+**Technische Entscheidungen:**
+- **LangChain `@tool`-Decorator** macht Tool-Implementierungen direkt LLM-kompatibel — kein Adapter-Boilerplate nötig
+- **Lazy Imports** in `web_search.py` und `pdf_reader.py` verhindern `ImportError` wenn Pakete fehlen oder API-Keys nicht gesetzt sind
+- **`create_web_search_tool()` / `create_pdf_search_tool()` Factory-Pattern** ermöglicht bedingtes Tool-Binding — Tools werden nur gebunden wenn die Voraussetzungen erfüllt sind
+- **LangGraph `interrupt_before`** — God Mode funktioniert ohne eigenes Pause-Protokoll; der LangGraph-Mechanismus übernimmt das gesamte State-Handling
+- **ChromaDB `_collection_cache`** verhindert mehrfache Client-Initialisierungen pro Request
+- **`council_runs`-PostgreSQL-Tabelle** mit `status`, `final_draft`, `critic_score` ermöglicht vollständigen Run-Verlauf ohne In-Memory-Abhängigkeit
+
+**Prozess:**
+- Story 5.4 (History) konnte parallel zu 5.3 (God Mode) entwickelt werden — keine Abhängigkeit
+- Alle Tool-Tests sind vollständig gemockt — kein Tavily-/ChromaDB-Aufruf in CI nötig
+- God-Mode-Tests mit LangGraph-Checkpointer komplett gemockt — stabile Tests
+
+---
+
+## 3. Was lief nicht gut? (Drop / Improve)
+
+**Technisch:**
+- `_collection_cache` in `pdf_reader.py` ist ein Modul-Level-Dict — bei hoher Last und vielen Collections könnte Speicher wachsen; TTL fehlt
+- `god_mode_states`-Dict in `dynamic_graph_builder.py` ist In-Memory — bei Server-Neustart gehen alle pausierten God-Mode-Runs verloren
+- PDF-Chunks mit `words`-basiertem Split beachtet keine semantischen Grenzen (Sätze, Absätze) — könnte zu abgeschnittenen Kontexten führen
+- `POST /api/councils/upload-pdf` speichert keine Referenz auf die Collection-Zuordnung zu einem Blueprint
+
+**Prozess:**
+- Story 5.3 (God Mode) war die komplexeste Story des gesamten Projekts — hätte in zwei Sub-Stories aufgeteilt werden können (Backend God Mode / Frontend Overlay)
+
+---
+
+## 4. Lernerkenntnisse
+
+| Erkenntnis | Anwendung / Empfehlung |
+|------------|----------------------|
+| LangGraph's `interrupt_before` ist sehr einfach zu aktivieren — aber die State-Persistenz (Checkpointer) ist der eigentliche Komplexitätspunkt | Für Produktions-God-Mode: `PostgresSaver`-Checkpointer statt In-Memory verwenden |
+| Tool-Factory-Pattern trennt Konfiguration (API-Key prüfen) von Ausführung (Tool aufrufen) | Für zukünftige Tools immer Factory-Funktion + @tool-Funktion getrennt implementieren |
+| ChromaDB-Collections sollten an einen Blueprint-Run gebunden sein | `collection_name = f"run_{run_id}"` wäre eine sauberere Isolation |
+| `UploadFile.content_type` ist browser-abhängig | Immer auch Dateiendung prüfen als Fallback (`filename.endswith(".pdf")`) |
+
+---
+
+## 5. Post-MVP Backlog
+
+| Priorität | Verbesserung | Kategorie |
+|-----------|-------------|-----------|
+| Hoch | `PostgresSaver`-Checkpointer für God Mode (Persistenz über Neustarts) | Tech Debt |
+| Hoch | PDF-Collection pro Blueprint-Run isolieren | Feature |
+| Mittel | Sentence-basierter Text-Splitter statt Word-basiertem | Quality |
+| Mittel | `god_mode_states`-Dict durch Redis oder DB ersetzen | Scalability |
+| Niedrig | CORS `allow_origins` via `ALLOWED_ORIGINS`-Env konfigurierbar machen | Security |
+| Niedrig | `_collection_cache` TTL / maximale Collection-Anzahl | Stability |
+
+---
+
+## 6. Projekt-Abschluss-Retrospektive
+
+**Alle 5 Epics abgeschlossen. Das MVP von CouncilOS ist implementiert.**
+
+### Was das Projekt gelehrt hat:
+
+1. **LangGraph's Zyklus-Unterstützung** ist der Kern des Mehrwerts — kein anderes Framework ermöglicht so einfach echte Feedback-Schleifen
+2. **BMAD-Method** hat die Planung strukturiert und sichergestellt, dass Backend-First-Reihenfolge eingehalten wurde
+3. **TypedDict + `operator.add`-Reducer** ist ein elegantes Muster für akkumulativen State — keine Race Conditions möglich
+4. **Factory-Pattern für Tools** und **`@tool`-Decorator** von LangChain ermöglichen saubere, testbare Tool-Integration
+5. **WebSockets + `interrupt_before`** sind das Fundament für eine responsive, interaktive AI-Erfahrung
+
+### Quantitative Zusammenfassung:
+- **5 Epics, 18 Stories** — alle `done`
+- **125 Backend-Tests** (pytest, alle grün, LLMs vollständig gemockt)
+- **26 Frontend-Tests** (vitest, alle grün)
+- **0 echte API-Calls in Tests**
+
+---
+
+*Bob (Scrum Master): "Epic 5 schließt das MVP ab. Besonders beeindruckend: God Mode mit LangGraph's `interrupt_before` war konzeptuell elegant und in der Praxis überraschend einfach zu implementieren. Das BMAD-Method-Vorgehen — Zyklen über Story→Dev→Review — hat die Codequalität nachhaltig verbessert. Herzlichen Glückwunsch zum CouncilOS-MVP!"*