# LeoCRM → LeoPlatform: Entwicklungs-Roadmap

> **Erstellt:** 2026-08-11
> **Überarbeitet:** 2026-08-13 — Endstand-Audit + Privacy/DSGVO/EU-AI-Act-by-Design integriert
> **Status:** Finale Endstand-Roadmap
> **Leitlinie:** «LeoCRM soll einfacher, konsistenter und erweiterbarer werden – nicht abstrakter, generischer oder frameworklastiger.»

---

## Entscheidungsregel für alle Änderungen

Bevor eine neue zentrale Abstraktion gebaut wird, müssen drei Fragen beantwortet werden:

1. Gibt es mindestens zwei oder drei wirklich semantisch gleiche Implementierungen?
2. Verursacht die Duplizierung aktuell konkrete Fehler oder Wartungsprobleme?
3. Wird das Gesamtsystem durch die gemeinsame Lösung tatsächlich einfacher?

Wenn eine Antwort nein ist: **Nicht generalisieren.**

Bestehender funktionierender Code wird nicht nur deshalb umgebaut, weil eine theoretisch schönere Architektur möglich wäre.

---

## Querschnitt-Regeln (für alle Phasen verbindlich)

### Ein Problem = ein Standardweg

| Querschnittsfunktion | Standardweg |
|---|---|
| DB-Schema (Core) | Alembic |
| DB-Schema (Plugin) | Plugin-Migrationsweg |
| DB-Schema (Runtime Auto-Sync) | Nicht authoritative, kein Ersatz für Migrationen |
| Redis | Zentraler Pool `get_redis()` |
| LLM | Zentraler Client `llm_complete()` |
| Files | Gemeinsamer Storage-Layer |
| Auth | Bestehender Auth-Kontext |
| Permissions | Bestehendes RBAC/ABAC-System |
| Search | Unified Search |
| Langlebige Events | Outbox |
| Externe Events | WebhookDispatcher |
| Background Jobs | ARQ |
| Plugin Integration | Vorhandenes Manifest/Registry-System |
| Workstream / interne Zusammenarbeit | Zentrales Communication-System (`CommConversation` / `CommMessage`) |
| Rich Content / MiniApps | `CommMessageBlock` + gemeinsamer `MiniAppRegistry` + Plugin-Manifest |
| Agent Skills | Kleiner Skill-Registry-/Definition-Weg; Skills orchestrieren nur vorhandene Tools/Services und verleihen keine Rechte |
| Plugin-Frontend | Volle React-Seiten gebündelt/deployment-time über vorhandenes Plugin-Frontend; runtime-fähige MiniApps schema-/registry-basiert |

Keine zweite parallele Lösung hinzufügen, wenn bereits ein funktionierender Standardweg existiert.

### Workstream-/MiniApp-Invarianten

Der Workstream ist **Darstellung, Zusammenarbeit und Koordination**, nicht die fachliche Datenquelle. Kontakte, Projekte, Termine, Dateien usw. bleiben in ihren Domain-Services/Tabellen authoritative. Eine MiniApp zeigt oder bearbeitet diese Objekte über die regulären APIs/Services mit normalen Permission-Prüfungen; sie hält keine zweite fachliche Kopie.

Der zentrale Workstream basiert auf dem bestehenden Communication-System und kann Menschen, System, Agenten und Workflows als Akteure zusammenführen. Text/Chat ist nur ein Blocktyp neben Action Cards, Entity Cards, Knowledge-Quellen, Approvals und MiniApps.

**Plugin-Frontend-Vertrag:**
- Vollständige kundenspezifische React-Seiten/Komponenten dürfen über das bestehende `PluginRegistry`/`PluginLoader`-System geliefert werden, benötigen im ersten Schritt aber einen Frontend-Build/Deploy, wenn ihr Code nicht bereits im Bundle vorhanden ist.
- Runtime-installierbare/interaktive Workstream-MiniApps verwenden primär einen sicheren schema-/registry-basierten Renderer (`render_schema`) und Standardaktionen/-komponenten.
- Kein beliebiges Remote-JavaScript/Module-Federation-System im Core. Signierte Remote-Bundles erst später, falls ein echter Marketplace-Hot-Install-Use-Case das verlangt.

### Sensitive Data Boundary (verbindlich)

Secrets und sensible technische Daten dürfen niemals automatisch in folgende Systeme gelangen:
- EntityHistory Snapshots
- Search Index / Embeddings
- RAG Chunks
- LLM Context
- Agent Memory
- Export
- Logs

Betroffen: Password Hashes, SMTP/IMAP Credentials, API Keys, OAuth Tokens, Session Tokens, Encryption Keys.

Lösung: Zentrale Exclude-/Sensitive-Field-Konvention. Verbindlich, getestet, keine riesige Security-Engine.

### Error-Handling-Konvention (verbindlich)

Error Handling ist **keine nachträgliche Schicht**, sondern wird direkt an den jeweiligen Systemgrenzen konsistent umgesetzt: LLM-Client, Agent-Loop, Workflow-Engine, WebSocket, Search/Indexing, Plugin-Routes, Batch-Operationen und Frontend.

**Grundregeln:**
- **Einheitliches Error-Response-Format** für die gesamte API: `{code, detail, field, trace_id, retryable}`. Keine Ad-hoc-`HTTPException` ohne strukturierten Code.
- **Error-Kategorisierung**: `TRANSIENT` (retryable: Timeout, Rate-Limit, Connection), `PERMANENT` (non-retryable: Validation, Permission, NotFound), `PARTIAL` (teilweise erfolgreich: Batch, Bulk, Multi-Step). Jeder Fehler trägt seine Kategorie, damit Workflow-Retry, Agent-Recovery und Frontend-UX entscheiden können.
- **Error-Propagation-Kette**: Plugin/Service → Core → API → Frontend → User. Technische Details (Tracebacks, interne Pfade) werden nur geloggt/monitoriert; dem User wird eine verständliche Nachricht mit `trace_id` zur Nachverfolgung gezeigt.
- **Frontend Error Boundaries**: Jede Plugin-Seite, MiniApp und kritische Komponente wird von einer ErrorBoundary umschlossen. Ein fehlerhaftes Plugin darf nicht die ganze App crashen.
- **Partial-Failure-Semantik**: Batch-Operationen (Import, Bulk-Restore, Re-Index, Agent Multi-Step) melden `partial_success` mit klarem Fehler-Report, was committed ist und was fehlgeschlagen ist. Kein stummes Versagen, kein inkonsistenter Zustand.
- **Bestehende Resilience-Patterns nutzen**: CircuitBreaker, `retry_db`, Outbox DLQ/Replay und Plugin-Error-Isolation sind vorhanden und werden konsequent angewendet — keine zweite Error-Engine.

### Privacy / DSGVO / EU AI Act by Design (verbindlich)

Compliance wird **nicht** als nachträgliche Parallelarchitektur gebaut. Datenschutz-, Transparenz-, Human-Oversight- und Nachweisfunktionen werden direkt an den bereits vorhandenen technischen Grenzen umgesetzt: Entity/Field-Metadaten, `AIProvider`, LLM-Client, Outbox, SearchProvider, AgentRun, WorkflowRun, ApprovalRequest, Audit und Communication.

**Grundregeln:**
- Leo stellt technische Compliance-Funktionen bereit; die rechtliche Zulässigkeit eines konkreten Einsatzes hängt weiterhin von Zweck, Daten, Betreiberrolle, Rechtsgrundlage und Branchenkontext ab.
- Jeder relevante AI-Use-Case erhält mindestens: `intended_purpose`, Owner, verwendete Agenten/Modelle/Provider, Datenkategorien, zulässige Aktionen, Human-Oversight-Policy und eine konfigurierbare Risikoklasse.
- **Keine Universal-Compliance-Engine:** kleine deklarative Policies an bestehenden Grenzen statt eines zweiten Policy-/Rechtesystems.
- `SENSITIVE_FIELDS` bleibt die harte Secret-Grenze. Zusätzlich gibt es eine kleine **AI/Data Exposure Policy** für personenbezogene bzw. besonders schützenswerte Fachfelder: ob sie in LLM Context, Search, Embeddings, RAG, Agent Memory und Export gelangen dürfen.
- Löschung/Korrektur einer authoritative Quelle muss abgeleitete Daten konsistent nachziehen können: Search/FTS, Vector/Embeddings, RAG-Chunks, Graph-Referenzen und Agent Memory. Kein blindes pauschales Hard-Delete, wenn gesetzliche Aufbewahrung oder fachliche Sperrgründe gelten; dafür muss der Betreiber die passende Retention-/Erasure-Policy konfigurieren.
- AI-Akteure werden im Workstream eindeutig als AI gekennzeichnet. Extern ausgegebene AI-generierte Inhalte können je Use-Case zusätzliche Transparenz-/Kennzeichnungsmetadaten erhalten.
- Personenbezogene oder sonst hochwirksame Entscheidungen können per Use-Case-Policy zwingend Human Review/Approval verlangen; Empfehlung, Evidenz, menschliche Entscheidung und Zeitpunkt bleiben nachvollziehbar.
- AI-Provider erhalten Compliance-Metadaten (Region, DPA/Vertragsstatus, Retention, Training-on-Customer-Data, Transfer-/Hosting-Hinweise, erlaubte Datenklassen). Der zentrale LLM-Client erzwingt die konfigurierte Provider-/Datenpolicy.
- High-Risk-/regulierte Branchenplugins nutzen dieselben Plattformmechanismen, bringen aber ihre **fachspezifische** Dokumentation, Risikobewertung und zusätzliche Kontrollen selbst mit. Der Core wird nicht auf Verdacht zu einer High-Risk-Suite aufgeblasen.

### Migration-Staffelung

Nicht: neu → migrieren → alt sofort löschen.
Sondern: 1. neue Struktur → 2. Daten migrieren → 3. Reads/Writes umstellen → 4. Tests → 5. stabiler Release → 6. alte Struktur entfernen.

### Teststrategie (gestaffelt verbindlich)

Die Tests bleiben streng, werden aber sinnvoll gestaffelt. Nach größeren Entwicklungsblöcken laufen die technischen Checks; das vollständige Deployment-Gate wird am Phasenende ausgeführt.

1. **Backend Tests:** `python -m pytest -v --tb=short`
2. **Frontend Tests:** `cd frontend && npx vitest run --reporter=verbose`
3. **TypeScript Check:** `cd frontend && npx tsc --noEmit`
4. **E2E Tests:** `cd frontend && npx playwright test` (kritische Flows)
5. **Frontend Build:** `cd frontend && npm run build`
6. **Health Check:** auf deploytem Phase-Candidate → `curl /api/v1/health` → 200
7. **Login Check:** auf deploytem Phase-Candidate → Login → 200
8. **Cross-Tenant Test:** `python -m pytest tests/test_cross_tenant_security.py`

**Staffelung:**
- Einzel-Task: relevante Unit-/Integration-/Frontend-Tests + Typecheck/Build soweit betroffen
- Größerer Block: Checks 1–5 + 8
- Phase-Gate: alle 8 Checks inklusive Deploy/Health/Login

Damit bleibt das Gate streng, ohne nach jedem kleinen Backend-Task Production-Deployments zu erzwingen.

### Test-Strategie-Erweiterung (in Phase A aufzusetzen, fortlaufend pro Phase)

Die aktuelle Test-Strategie hat Lücken. Diese werden in Phase A aufgesetzt und pro Phase erweitert:

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| T-FE | **Frontend-Tests systematisch** — Vitest-Tests für neue/geänderte Fachlogik, Interaktionen, Hooks, Stores, API-Clients und kritische UI-Komponenten. Reine Präsentationskomponenten benötigen keinen Pflicht-Test ohne eigenes Verhalten | fortlaufend |
| T-SEC | **Security-Tests** — bandit (Python SAST), pip-audit (Dependencies), npm-audit (Frontend Dependencies). In CI-Pipeline integrieren | 1 Tag |
| T-LLM-MOCK | **LLM-Mocking-Strategy** — zentraler Mock für `llm_complete()` und `llm_embed()` in Tests. Keine Tests die externe APIs blockieren | 1 Tag |
| T-RLS | **RLS-Tests** — Test-DB mit echten Alembic-Migrationen (statt `create_all`) damit RLS-Policies getestet werden können | 1.5 Tage |
| T-PARALLEL | **Test-Parallelisierung** — pytest-xdist mit pro-Worker Datenbank. Reduziert Test-Laufzeit | 1 Tag |
| T-LOAD | **Load/Performance-Tests** — Basis-Load-Test mit locust/k6: Login, Contact-List, Search unter Last. In Phase A Baseline, in Phase I Vergleich | 1 Tag |
| T-CONTRACT | **Contract-Tests** — Plugin-Contracts (Mail, DMS, GraphRAG, AI UI Control) haben Tests die die Contract-Schnittstelle verifizieren | 1 Tag |
| T-A11Y | **Accessibility-Tests** — axe-core in E2E-Tests integrieren. WCAG-Checks auf kritischen Seiten | 1 Tag |
| T-E2E-EXT | **E2E-Tests erweitern** — bestehend: auth, contact-crud, calendar, dms, mail, search, plugin-toggle. Ergänzen: settings, notifications, tags, custom-fields, agent-chat, workflow-editor, knowledge, undo/restore | fortlaufend |
| T-COV | **Coverage-Tracking** — pytest-cov für Backend, vitest coverage für Frontend. CI prüft dass Coverage nicht sinkt | 0.5 Tage |
| T-DOC | **`docs/test-strategy.md` aktualisieren** — mit allen neuen Test-Typen, Mocking-Strategy, Parallelisierung, Coverage-Ziele | 1 Tag |

### Dokumentations-Pflicht (pro Phase)

Nach jeder Phase werden die betroffenen Docs aktualisiert:
- `docs/api-documentation.md` bei API-Änderungen
- `docs/plugin-development-guide.md` bei Plugin-Vorgaben
- `docs/ui-design-guidelines.md` bei UI-Änderungen
- `docs/test-strategy.md` bei Test-Änderungen
- `docs/security_kernel.md` bei Security-Änderungen
- `AGENTS.md` bei Engineering-Regeln

### Frontend-Tests (verbindlich pro Phase)

Pro Phase werden fehlende Frontend-Tests ergänzt:
- Vitest-Tests für neue/geänderte Fachlogik, Interaktionen und kritische Komponenten
- API-Client-Tests für neue/geänderte Endpoints
- Hook-Tests für neue Custom Hooks
- Store-Tests bei eigener Zustands-/Businesslogik
- E2E-Tests für neue kritische User-Flows
- Reine Präsentationskomponenten ohne eigenes Verhalten benötigen keinen Pflicht-Test

### Definition of Done (DoD) — verbindlich für jeden Task

Ein Task gilt erst als **DONE** wenn **alle** folgenden Kriterien erfüllt sind:

1. **Code implementiert** — Funktionalität ist vollständig gebaut, keine TODOs, keine Stubs
2. **Tests geschrieben** — relevante Fachlogik und Verhalten sind mit passenden Unit-/Integration-/Frontend-Tests abgedeckt; keine Pflicht zu wertlosen Tests für reine Präsentationskomponenten
3. **Tests grün** — alle Tests für diesen Task bestehen
4. **TypeScript clean** — `npx tsc --noEmit` zeigt keine neuen Fehler (nur bei Frontend-Tasks)
5. **Dokumentation aktualisiert** — betroffene Docs sind aktualisiert (API-Doku, Plugin-Guide, etc.)
6. **Keine neuen `any` Types** — neue/geänderte Dateien haben keine `any` Types (nur bei Frontend-Tasks)
7. **Sensitive Data ausgeschlossen** — falls Task mit Daten zu tun hat: SENSITIVE_FIELDS respektiert
8. **Integration verifiziert** — Task lokal/CI-grün; Production-Deploy ist kein Pflichtschritt pro Einzel-Task, sondern erfolgt am Phase-Gate

Ein Task mit testbarer Fachlogik oder relevantem Verhalten ist ohne passenden Test **NICHT done** — auch wenn der Code funktioniert. Reine Präsentationsänderungen ohne eigenes Verhalten benötigen keinen künstlichen Pflicht-Test.

### Phase-Gate-Review — verbindlich nach jeder Phase

Eine Phase gilt erst als **ABGESCHLOSSEN** wenn:

1. **Alle Tasks DONE** — jeder Task in der Phase hat DoD erfüllt
2. **8-Check-Pipeline grün** — alle 8 Checks (Backend, Frontend, TypeScript, E2E, Build, Health, Login, Cross-Tenant) bestehen
3. **Deploy verifiziert** — in Produktion deployed, Health 200, Login 200, Smoke-Test bestanden
4. **Dokumentation aktualisiert** — alle betroffenen Docs sind aktualisiert
5. **Performance verglichen** — gegen Phase A Baseline, keine signifikanten Regressionen
6. **Frontend-Tests ergänzt** — neue Features haben Vitest-Tests + E2E-Tests
7. **Keine offenen TODOs** — keine TODOs/Stubs aus dieser Phase im Code

Erst wenn alle 7 Kriterien erfüllt sind, wird die nächste Phase begonnen.

### Task-Tracking — Status pro Task

Jeder Task hat einen Status der verfolgt wird:
- `not_started` — Task noch nicht begonnen
- `in_progress` — Task wird bearbeitet
- `blocked` — Task blockiert (Abhängigkeit fehlt, Entscheidung ausstehend)
- `review` — Task implementiert, wartet auf Review/Tests
- `done` — Task hat DoD erfüllt

Tasks die `done` sind ohne DoD zu erfüllen werden auf `in_progress` zurückgesetzt.

---

## Code-Baseline 2026-08-13 — Ausgangspunkt dieser Roadmap

Die Roadmap ist **kein Greenfield-Plan**. Der aktuelle Code wurde gegen das Zielbild geprüft. Stand des geprüften Archivs:

- ca. **68.771 Backend-Python-Zeilen** in `app/`
- ca. **65.467 Frontend-TS/TSX-Zeilen** in `frontend/src/`
- ca. **32.328 Python-Testzeilen** in `tests/`
- **118 Alembic-Migrationen**, letzter Stand im Archiv `0117`
- `python -m compileall -q app` im Audit erfolgreich
- vollständiger frischer pytest-Lauf im Audit-Container nicht möglich, weil dort das Python-Paket `redis` fehlt; daraus wird **kein** Codefehler abgeleitet. Phase A verifiziert die echte Projekt-/Deploy-Umgebung.

### Bereits vorhandene Fundamente — erweitern, nicht neu bauen

| Bereich | Aktueller Code-Stand | Konsequenz für die Roadmap |
|---|---|---|
| Communication / Workstream | `CommConversation`, Teilnehmer, Messages, Rich Blocks, WebSocket, rechte `MessageSidebar`, mobile Overlay-Darstellung vorhanden | zum zentralen Workstream fertigstellen, kein neues Message-Modell |
| MiniApps | `MiniAppRegistry`, `MiniAppContribution`, `miniapp`-Message-Block, sechs registrierte Typen vorhanden; `MiniAppBlock.tsx` noch Placeholder | Runtime/Renderer und Plugin-Wiring fertigstellen |
| Proactive AI / UI Context | `useAIContext`, `ContextLog`, `ProactiveSuggestion`, Context-Events und Actions vorhanden | in gemeinsamen Trigger-/Agent-Kern konsolidieren |
| AI UI Control | REST/WebSocket, Navigation/Filter/Contact/Modal/Tab/Settings + Frontend-Feedback vorhanden | als Agent-Tool integrieren/erweitern |
| Agents | `AgentDefinition`, `AgentVersion`, `AgentRun`, `AgentSubtask`, früher `AgentCoordinator`, Agent-UI vorhanden | echten ReAct-/Permission-/Skill-Kern fertigstellen; nicht neu anfangen |
| Skills | **kein** explizites Skill-Modell/Registry im geprüften Code gefunden | kleinen Skill-Baustein in Phase F explizit ergänzen |
| Automation / Workflow | Workflow-Engine, persistente Instanz/Step-History, Conditions/Approval sowie AutomationDefinition/Run/Version/Cron vorhanden | durable Runtime erweitern; Automation und Workflow nicht zu zwei Engines auswachsen lassen |
| Search | SearchProvider, FTS, Vector/pgvector, RRF und GraphRAG-Grundlage vorhanden | auf Unified FTS+Vector+RAG+Graph konsolidieren/komplettieren |
| Knowledge | Graph-Grundlage vorhanden, aber Wiki/Document-RAG/Extraktion fehlen | Firmenwissensschicht auf bestehendem Search-Kern ergänzen |
| Import/Export | Service, Routes und Frontend für Import/Export bereits vorhanden | modularisieren/erweitern statt neu bauen |
| History/Restore | generisches Recording/History-UI teilweise vorhanden, Restore noch fachlich begrenzt | gezielt fertigstellen |
| Plugin UI | Manifest + Registry + dynamische Pfade vorhanden; externe Python-Plugins können entdeckt werden | klare Trennung: gebündelte React-Plugins vs. runtime schema-basierte MiniApps |

**Wichtiger Code-Fit:** Das Manifest kennt `miniapps`, aber die zentrale Plugin-Contribution-Registrierung und `/plugins/active-manifests` reichen MiniApps derzeit nicht vollständig bis zum Frontend durch. Genau diese konkrete Lücke wird in Phase B/I geschlossen; dafür wird keine neue Plugin-Architektur eingeführt.

## Roadmap-Übersicht

```
Phase A — Stabilität verifizieren                    [Woche 1]
Phase B — Kleine System-Konsolidierung               [Woche 2-7]
Phase C — Core UI abschließen                        [Woche 8-11]
Phase C.5 — Modularer Import/Export                  [Woche 12-13]
Phase D — Minimal Undo/Restore                       [Woche 14-17]
Phase E — Unified Search vollständig                 [Woche 18-23]
Phase F — Agent MVP                                  [Woche 24-29]
Phase G — Workflow MVP                               [Woche 30-35]
Phase H — Knowledge                                  [Woche 36-41]
Phase I — Integration, Workstream & Polish           [Woche 42-47]
Phase J — Controlled Self-Improvement                [Woche 48-52]
Phase K — EU Compliance Finalization                 [Woche 52]
Später — Advanced Autonomy/Automation nur bei echtem Bedarf
```

---

## Phase A — Stabilität verifizieren

**Dauer:** 1 Woche
**Ziel:** Verifizieren dass die 9 Minimal-Fix-Pakete stabil sind. Keine neue Architekturarbeit.

| Task | Beschreibung |
|------|-------------|
| A-VERIFY | Installation, CI, E2E, Auth, Cross-Tenant, Worker verifizieren |
| A-TEST | Test-Pipeline (8 Checks) ausführen — alle müssen grün sein |
| A-PERF | Performance-Baseline messen (Response-Times, DB-Query-Counts) für spätere Vergleiche |
| A-RESTORE | **Automatisierter Backup-Restore-Test** — bestehendes `backup_service.py` + `restore_test.sh` verifizieren und als ARQ-Cron-Job einrichten: Backup erstellen → in Test-DB restore → Schema/Row-Count validieren → Ergebnis loggen. Ein Backup das nie getestet wurde ist kein Backup |
| A-DOC | `docs/test-strategy.md` aktualisieren mit verbindlicher Test-Pipeline |

---

## Phase B — Kleine System-Konsolidierung

**Dauer:** 6 Wochen (bei 2 Entwicklern; bei 1 Entwickler ~10-12 Wochen)
**Ziel:** Nur wirklich gemeinsame technische Infrastruktur konsolidieren. Keine Universalmodelle.

### B.1 Zentraler LLM Client

Im Code-Audit verbleiben **9 direkte `litellm.acompletion()` Aufrufe außerhalb des zentralen Clients** (automation/agent_runner, ai_assistant 2x, ai_proactive 3x, unified_search 2x). Diese auf den vorhandenen zentralen Client umstellen.

**Embedding-API:** Der zentrale Client stellt nicht nur `llm_complete()` sondern auch `llm_embed(texts, model)` bereit. LiteLLM unterstützt Embeddings über `litellm.aembedding()` — derselbe Provider-/API-Key-Mechanismus wie Completion. Aktuell nutzt `unified_search/embedding.py` direkte OpenRouter-API-Calls. Diese werden auf `llm_embed()` über den zentralen Client umgestellt. Provider-Auswahl, API-Key-Auflösung, Error-Handling und Cost-Tracking laufen über denselben zentralen Weg wie Completion-Calls.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-LLM | `llm_client.py` erweitern: `llm_complete(model, messages, tools, ...)`, `llm_embed(texts, model)`. Provider-Auswahl aus DB, API-Key-Auflösung, Error-Handling, Cost-Tracking, Streaming-Helfer, Timeouts, optionale Retries | 2 Tage |
| B-LLM-MIG | Alle 9 verbleibenden direkten `litellm.acompletion()` Aufrufe außerhalb `llm_client.py` umstellen + `unified_search/embedding.py` auf `llm_embed()` umstellen | 2 Tage |
| B-LLM-TEST | Tests für zentralen Client (mock mode, real mode, error scenarios) | 1 Tag |
| B-LLM-DOC | Plugin-Dev-Guide: `from app.ai.llm_client import llm_complete`. Keine direkten LiteLLM-Aufrufe | 0.5 Tage |

### B.2 Zentraler Redis Pool

Ein zentraler `get_redis()`-Weg existiert bereits. Direkte Redis-Client-Erzeugung verbleibt im Audit u. a. in `cache.py`, `monitoring.py` und `worker.py`; Auth/Dependencies nutzen bereits den zentralen Weg. Diese technischen Sonderpfade konsolidieren, ohne neue Redis-Abstraktion.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-RED | `get_redis()` als Standard-Anlaufstelle. `cache.py`, `monitoring.py`, `worker.py` und weitere echte Direktkonstruktoren prüfen/umstellen; bestehende Dependency-/Middleware-Nutzung nicht unnötig umbauen | 1 Tag |
| B-RED-TEST | Connection-Leak-Test unter Last | 0.5 Tage |

### B.2b pgvector HNSW Optimierung

pgvector mit HNSW-Index direkt optimieren — nicht auf Phase I verschieben. Bei 100k+ Embeddings ohne Tuning wird Search langsam.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-VEC | **HNSW-Parameter optimieren** — `ef_construction=128`, `m=16` als Defaults. Konfigurierbar pro Entity. `ef_search` pro Query anpassbar (Tradeoff Speed/Recall) | 1 Tag |
| B-VEC-IVF | **IVFFlat als Alternative** — für sehr große Datasets (>1M) kann IVFFlat besser sein. Konfigurierbare Index-Strategie | 0.5 Tage |
| B-VEC-BATCH | **Batch-Embedding** — mehrere Entities in einem LLM-Call embedden (reduziert API-Calls und Kosten) | 0.5 Tage |
| B-VEC-TEST | Performance-Tests: 10k, 100k, 1M Embeddings — Query-Latenz messen | 1 Tag |

### B.3 Gemeinsamer File Storage

Gemeinsame technische Storage-Schicht für alle File-Typen. Domainmodelle (DMS File, MailAttachment, CommMessageAttachment, AIChatAttachment) bleiben separat.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-STOR | Bestehendes `core/storage.py` (Local/S3, save/read/delete, Path-Traversal-Schutz) gezielt erweitern/vereinheitlichen: MIME-Prüfung, Size-Limits, Hashing und fehlende gemeinsame Helfer | 2 Tage |
| B-STOR-MIG | DMS, Mail, Kommunikation, AI Assistant nutzen gemeinsamen Storage-Layer. Eigene Upload-Endpoints bleiben bestehen (`/dms/files/upload`, `/mail/.../attachment`) | 2 Tage |
| B-STOR-TEST | Storage-Tests (Path-Traversal, MIME, Size, Hash) | 1 Tag |

### B.4 WebSocket Helpers

Gemeinsame Helpers statt großer BaseWebSocketManager. Spezialisierte Manager bleiben.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-WS | Gemeinsame Helpers: Session-Auth, Origin-Check, Tenant-Check, Connection-Cleanup, Heartbeat. `WebSocketManager` (Kommunikation) und `AIUIControlWSManager` (AI UI) nutzen Helpers. **Redis Pub/Sub für WS-Fanout** — bei mehreren Uvicorn-Workern funktioniert In-Memory-Fanout nicht. Redis Pub/Sub als Backbone: Worker publish auf Redis-Channel, alle WS-Clients subscriben. Kein Funktionsverlust, horizontale Skalierung möglich | 3 Tage |
| B-WS-TEST | WebSocket-Auth-Tests | 1 Tag |

### B.5 Event-System Rollen dokumentieren

4 Systeme bleiben, Rollen klar definieren. Keine neue Abstraktion.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-EVT | Rollen dokumentieren: HookRegistry = Lifecycle/Daten-Anpassungen, EventBus = flüchtige interne Events, Outbox = dauerhafte Domain Events, WebhookDispatcher = externe HTTP-Zustellung. Regel: nicht dieselbe Funktion über Hook UND EventBus triggern. Inkonsistenzen bereinigen | 1 Tag |
| B-EVT-DOC | Decision Guide für Plugin-Entwickler: wann welches System | 0.5 Tage |

### B.6 Schema Authority definieren

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-SCHEMA | Dokumentieren: Core → Alembic, Plugin → Plugin-Migrationsweg, Runtime Auto-Sync → nicht authoritative. Kein neuer Schema-Mechanismus | 0.5 Tage |

### B.7 Plugin-Guide (klein)

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-PLUGIN | Plugin-Pflicht auf das Wesentliche: Manifest, Dependencies, Routes, Permissions, Tenant-Isolation, Migrationen, Activation/Deactivation. Alles andere optional (Search, History, LLM, MCP, Attachments, etc. — nur wenn benötigt). Nicht jedes ORM-Modell braucht `deleted_at` | 1 Tag |
| B-PLUGIN-MANIFEST | Bestehende Manifest-Felder und Contributions wiederverwenden. Nicht aufblasen | 0.5 Tage |
| B-PLUGIN-FE | Bestehendes Plugin-Frontend-System (`PluginLoader.tsx`, `PluginRegistry.tsx`, `PluginRouteRenderer.tsx`, `pluginStore.ts`) analysieren, testen, bei Bedarf korrigieren. NICHT neu bauen | 1 Tag |
| B-PLUGIN-MINIAPP-WIRE | **MiniApp-Contributions end-to-end verdrahten** — `manifest.miniapps` beim Aktivieren in den **gemeinsamen** `comm_miniapps`-Registry eintragen und beim Deaktivieren entfernen. Keine privaten Registry-Instanzen pro Plugin | 1 Tag |
| B-PLUGIN-UI-CONTRACT | **Frontend-Delivery-Vertrag festlegen** — gebündelte React-Pluginseiten benötigen Build/Deploy; runtime-fähige MiniApps laufen schema-/registry-basiert. Kein beliebiges Remote-JS als Core-Anforderung | 0.5 Tage |
| B-PLUGIN-GUIDE | **Vollständiger Plugin-Dev-Guide** — `docs/plugin-development-guide.md` komplett überarbeiten mit ALLEN Integration-Punkten die eine KI die Plugins baut kennen muss: | 2 Tage |

**Plugin-Dev-Guide muss folgende Kapitel enthalten:**

1. **Grundlagen** — Manifest, Dependencies, Routes, Permissions, Tenant-Isolation, Migrationen, Activation/Deactivation
2. **Hooks** — wie Plugin Hooks registriert (`register_action`, `register_filter`), welche Hooks existieren (B.10 Übersicht), wie eigene Hooks definiert werden
3. **Outbox Events** — wie Plugin Events published (`enqueue_outbox_event`), welche Events existieren (B.10 Übersicht), wie Plugin Events subscribiert
4. **Trigger** — wie Plugins Domain-Event-, UI-, Cron- und Manual-Trigger nutzen; Webhook-Trigger folgt in Phase G. Durable Domain Events und ephemere UI-Events klar trennen
5. **Message-System** — wie Plugin System-Nachrichten postet (`post_system_message()`), wie Plugin Chat-Räume erstellt, wie Plugin Mini-Apps registriert, Rich Content Blocks (action_card, contact_card, miniapp)
6. **Search** — wie Plugin SearchProvider registriert, welche Modi unterstützt werden (FTS, Vector, RAG, Graph), wie Auto-Indexierung funktioniert
7. **LLM** — wie Plugin LLM-Calls macht (`from app.ai.llm_client import llm_complete`), keine direkten LiteLLM-Aufrufe, Provider-Auswahl, Cost-Tracking
8. **File Storage** — wie Plugin Files speichert (`core/storage.py`), keine eigenen Storage-Backends, MIME-Prüfung, Path-Traversal-Schutz
9. **WebSocket** — gemeinsame Helpers für Auth, Origin, Tenant, Cleanup und Heartbeat sind Pflicht. Eigene spezialisierte WebSocket-Manager sind erlaubt, wenn ein Plugin eigene Connection-/Message-Semantik benötigt; keine parallele eigene Sicherheits-/Lifecycle-Basislogik
10. **Redis** — wie Plugin Redis nutzt (`get_redis()`), keine eigenen Connections
11. **Permissions** — wie Plugin Permissions deklariert und bestehendes RBAC/ABAC nutzt. Tools, Skills und MCP dürfen keine Rechte verleihen oder bestehende Permission-Prüfungen umgehen
12. **AI Tools** — wie Plugin Tools in ToolRegistry registriert, wie Agenten diese nutzen, `required_permission` pro Tool
13. **MCP** — MCP nur als dünne Exposure-Schicht auf bestehende Tools/Services; vorhandener Auth-/Run-as-Kontext und normale Permission-Prüfungen bleiben maßgeblich
14. **UI-Events** — wie Plugin auf UI-Events reagiert (`ui.contact_selected`, etc.), wie Plugin UI-Events published
15. **AI UI Control** — wie Plugin AI UI Control nutzt (navigate, filter, open_contact, modal, tab, settings)
16. **Sensitive Data** — welche Felder SENSITIVE sind, wie Plugin SENSITIVE_FIELDS deklariert, was NICHT in Snapshots/Index/Embeddings/Export darf
17. **Schema Authority** — Core → Alembic, Plugin → Plugin-Migrationsweg, Runtime Auto-Sync → nicht authoritative
18. **Migration-Staffelung** — wie Plugin Migrationen sicher durchführt (neu → migrieren → umstellen → testen → release → alt entfernen)
19. **Frontend** — wie Plugin Frontend-Komponenten erstellt (Standard-Komponenten nutzen, Manifest deklarieren, Theme respektieren, i18n nutzen, ErrorBoundary), inklusive Delivery-Vertrag: volle React-Komponenten deployment-time/bundled; runtime MiniApps schema-/registry-basiert
20. **Privacy/AI Compliance** — wie Plugin Datenklassen/AI-Exposure deklariert, AI-Use-Cases beschreibt, Human-Oversight/Transparency nutzt und abgeleitete Daten bei Correction/Erasure nachzieht; High-Risk-Spezialpflichten bleiben beim konkreten Vertical/Use-Case
21. **Test-Strategie** — wie Plugin Tests schreibt (Backend: pytest, Frontend: Vitest, E2E: Playwright), was getestet werden muss
22. **Error-Handling** — wie Plugin Errors werfen (`ApiError` mit `code`, `category`, `retryable`), Error-Propagation-Kette (Plugin → Core → API → Frontend → User), `trace_id`-Korrelation, Frontend-ErrorBoundary-Pflicht für Plugin-Seiten/MiniApps, Partial-Failure-Semantik bei Batch-Operationen, keine Tracebacks an User

### B.8 Rate-Limiting Konsistenz

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-RL | Zentrale Redis-basierte Rate-Limit-Implementierung verwenden und bestehende In-Memory-Limiter darauf umstellen. Policies gezielt für missbrauchs-/kostenrelevante Endpoints definieren (Auth/Login, öffentliche APIs, Webhooks, AI/LLM, Uploads, Passwort-Reset etc.). Keine pauschale Rate-Limit-Pflicht für jeden internen CRUD-Endpoint | 1 Tag |

### B.9 Sensitive Data Boundary

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-SENS | Zentrale Exclude-/Sensitive-Field-Konvention: `SENSITIVE_FIELDS` Set pro Entity. EntityHistory, Search, Embeddings, Export filtern automatisch. Tests die verifizieren dass keine Secrets in Snapshots/Index landen | 2 Tage |
| B-DATA-POL | **AI/Data Exposure Policy** — kleine deklarative Entity-/Field-Policy ergänzen: zulässig für LLM Context, Search, Embeddings/RAG, Agent Memory und Export. `SENSITIVE_FIELDS` bleibt harte Secret-Sperre; keine zweite Permission-Engine | 2 Tage |
| B-AIPROV-COMP | **AIProvider Compliance Metadata** — Region/Hosting, DPA-/Vertragsstatus, Retention, Training-on-Customer-Data, Transfer-Hinweise und erlaubte Datenklassen am bestehenden `AIProvider`; zentraler LLM-Client prüft die konfigurierte Policy vor Übermittlung | 1.5 Tage |
| B-PRIV-TEST | Tests: Secrets immer blockiert, Exposure-Policy greift, nicht freigegebener Provider erhält keine entsprechenden Daten | 1 Tag |

### B.10 Lifecycle Hooks & relevante Outbox Events

Für KI-, Plugin- und Automatisierungs-Erweiterbarkeit werden Lifecycle-Hooks dort breit und konsistent angeboten, wo Erweiterbarkeit fachlich sinnvoll ist. **Durable Outbox Events werden dagegen nur für fachlich relevante Zustandsänderungen definiert, die asynchron verarbeitet, automatisiert oder extern konsumiert werden können. Keine Events auf Vorrat.**

**Prinzip:** Hooks sind lokale Erweiterungspunkte. Outbox Events sind dauerhafte Domain Events mit Delivery-/Retry-Semantik. Technische Tabellen, reine Read-Aktionen und UI-Kontext brauchen nicht automatisch Hooks oder Outbox Events.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-HOOK-CORE | **Core Hooks vervollständigen** — Contact, Company und weitere relevante Core-Businessobjekte konsistent abdecken; nur Lifecycle-Punkte mit echtem Erweiterungsnutzen | 1 Tag |
| B-HOOK-MAIL | **Mail Hooks** — relevante receive/send/delete/move Lifecycle-Punkte ergänzen | 1 Tag |
| B-HOOK-DMS | **DMS Hooks** — relevante upload/create/update/delete/restore Lifecycle-Punkte + Folder-CRUD | 1 Tag |
| B-HOOK-CAL | **Calendar Hooks** — relevante create/update/delete Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-TASK | **Task Hooks** — relevante create/update/delete Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-COMM | **Communication Hooks** — relevante message/edit/delete + conversation Lifecycle-Punkte | 1 Tag |
| B-HOOK-AI | **AI/Agent Hooks** — nur sinnvolle Run-/Tool-/Message-Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-WF | **Workflow Hooks** — relevante start/step/complete/cancel Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-TAG | **Tag/Link Hooks** — assign/unassign bzw. create/delete soweit Plugins darauf reagieren müssen | 0.5 Tage |
| B-HOOK-SEARCH | **Search Hooks** — optional `before_search`/`after_search` für echte Query-/Result-Erweiterungspunkte. **Keine** parallelen `before/after index/reindex`-Hooks; Indexierung läuft ausschließlich über SearchProvider + Outbox→Worker | 0.25 Tage |
| B-EVT-OUTBOX | **Relevante Domain Events ergänzen** — z. B. task.completed, file.created/deleted/restored, mail.received/sent, workflow.started/completed, agent.run_started/completed. Event nur wenn ein konkreter Consumer/Automatisierungs-/Integrationsbedarf existiert | 1.5 Tage |
| B-HOOK-TEST | Tests: relevante Hooks feuern korrekt; definierte Domain Events werden zuverlässig gepublished; keine UI-/Read-Events versehentlich durable; Sensitive Fields ausgeschlossen | 1.5 Tage |
| B-HOOK-DOC | Plugin-Dev-Guide: Hook- und Domain-Event-Konventionen sowie Entscheidungsregel dokumentieren | 0.5 Tage |

### B.11 Trigger-Kern konsolidieren

Der vorhandene Trigger-Kern wird vereinheitlicht; **keine zweite Trigger-Engine**. Domain Events, UI Events, Cron und Manual nutzen denselben registrierungs-/dispatch-orientierten Kern, aber mit unterschiedlicher Delivery-Semantik.

- **Durable Domain Events** → Outbox → Worker/Trigger Dispatcher
- **UI Events** (`ui.contact_selected`, `ui.page_navigated`, `ui.mail_opened`, ...) → ephemer über EventBus/Redis/Trigger Dispatcher, **nicht** über die Transactional Outbox
- **Cron/Heartbeat** → vorhandener Automation-Scheduler/ARQ
- **Manual** → vorhandener Execution-Pfad
- **Incoming Webhook** → wird erst in Phase G als Workflow-Feature gebaut
- **Agent → Workflow** → wird später in F/G über reguläre Tools/Services integriert, nicht in B künstlich vorbereitet

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-TRIG-GEN | **Generische Domain-Event-Trigger** — hardcodierte Event-Liste entfernen; registrierte relevante Outbox Events können über den gemeinsamen Dispatcher Automations/Workflows finden | 1.5 Tage |
| B-TRIG-UI | **UI-Event Trigger-Typ definieren** — ephemerer Pfad über EventBus/Redis/Dispatcher; noch keine Agent-spezifische Parallelengine | 0.5 Tage |
| B-TRIG-CRON | **Cron/Heartbeat verifizieren** — bestehenden Scheduler/ARQ-Pfad für relevante Job-Typen konsistent nutzen; keine neue Scheduler-Architektur | 0.5 Tage |
| B-TRIG-MAN | **Manual-Trigger verifizieren** — bestehender Manual-Pfad nutzt denselben Execution-Kern | 0.5 Tage |
| B-TRIG-TEST | Tests: Domain Event, UI Event, Cron und Manual werden korrekt dispatcht; UI Events werden nicht in die Outbox geschrieben | 1 Tag |
| B-TRIG-DOC | Plugin-Dev-Guide: Trigger-Typen und durable-vs-ephemeral Semantik dokumentieren | 0.5 Tage |

### B.12 Notification → zentrales Message-System konsolidieren

Das bisher separate Notification-System und das Communication-/Message-System werden **zu einem zentralen internen Message-System zusammengeführt**. Communication wird damit der Standardweg für User-, System-, Agent- und Notification-Nachrichten. Das alte Notification-System wird nach Migration und Verifikation vollständig entfernt; `NotificationPreference` bleibt ausschließlich als Delivery-/Preference-Konfiguration. System-/Notification-Messages bleiben semantisch typisiert und sind nicht einfach normale Chattexte.

**Aktueller Stand:**
- Notification: eigenes Model (`Notification`, `NotificationType`, `NotificationPreference`), eigene Routes (`/api/v1/notifications`), eigene Frontend-Komponenten (`NotificationDropdown.tsx`, `NotificationItem.tsx`)
- Communication: eigenes Plugin (`CommConversation`, `CommMessage`, `CommMessageBlock`, etc.), eigene Routes (`/api/v1/comm`), eigene Frontend-Komponenten (`comm/blocks`)
- Keine Verbindung zwischen beiden Systemen

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-NOTIF-SYS | **System-Channel** — automatischer System-Channel (CommConversation) pro Tenant. Wird bei Tenant-Erstellung angelegt. `is_system=True` Flag. `CommParticipant` mit `participant_type='system'`. User sind automatisch Teilnehmer | 1 Tag |
| B-NOTIF-EVT | **Event → typisierte System-Message** — relevante Domain Events erzeugen bei konfigurierter Delivery typisierte `CommMessage`/Rich-Content-Blöcke mit Severity, Entity-Referenz/Action und System-Participant. Keine normale Chattext-Semantik erzwingen | 1.5 Tage |
| B-NOTIF-UI | **Notification-Dropdown → System-Channel** — Notification-Dropdown in TopBar zeigt den System-Channel an (letzte Nachrichten). Klick öffnet den System-Channel im Chat. Ungelesene System-Nachrichten = Badge in TopBar. `NotificationDropdown.tsx` und `NotificationItem.tsx` werden durch Chat-Komponenten ersetzt | 1.5 Tage |
| B-NOTIF-PREF | **Delivery-/Notification-Preferences** — `NotificationPreference` bleibt als Routing-Konfiguration, z. B. In-App/System-Channel, E-Mail oder stumm; kein zweites Nachrichtensystem | 0.5 Tage |
| B-NOTIF-MIG | **Migration** — bestehende Notifications in System-Channel als CommMessages migrieren. Alte Notification-Tabelle als View behalten für Übergang. **Field-Mapping:** `Notification.read_at` → `CommMessageRead`, `Notification.type` → Block-Metadata `notification_type`, `Notification.entity_type/entity_id` → Block-Metadata `entity_ref`, `Notification.title/body` → Text-Block + `action_card` Block mit Deep-Link | 1.5 Tage |
| B-NOTIF-DEPREC | **Notification-System vollständig zurückbauen** — nach Migration und Verifikation: `Notification` Model, `NotificationType` Model, `/api/v1/notifications` Routes, `NotificationDropdown.tsx`, `NotificationItem.tsx` vollständig entfernen. Kein doppeltes System. `NotificationPreference` bleibt (für E-Mail/Stumm-Einstellungen). `create_notification()` wird zu `post_system_message()` im Comm-System | 1 Tag |
| B-NOTIF-TEST | Tests: System-Events → Chat-Nachrichten, Preferences respektiert, Unread-Badge korrekt, Migration korrekt | 1 Tag |

### B.13 Error-Handling-Infrastruktur

Bestehende Resilience-Patterns (CircuitBreaker, `retry_db`, Outbox DLQ/Replay, Plugin-Error-Isolation) werden konsolidiert und um die fehlenden systematischen Bausteine ergänzt. Keine zweite Error-Engine, sondern ein einheitlicher Rahmen auf bestehenden Mustern.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-ERR-FMT | **Einheitliches Error-Response-Format** — `{code, detail, field, trace_id, retryable}` für die gesamte API. Bestehende `error_codes.py` (6 Codes) erweitern, `ApiError` als Standard-Exception, FastAPI Exception-Handler der alle Errors im einheitlichen Format zurückgibt. `trace_id` korreliert mit Request-Logging | 1 Tag |
| B-ERR-CAT | **Error-Kategorisierung** — `ErrorCategory.TRANSIENT` (retryable: Timeout, Rate-Limit, Connection), `PERMANENT` (non-retryable: Validation, Permission, NotFound), `PARTIAL` (teilweise erfolgreich: Batch, Bulk, Multi-Step). Jeder `ApiError` trägt seine Kategorie; Workflow-Retry, Agent-Recovery und Frontend-UX nutzen diese | 0.5 Tage |
| B-ERR-WS | **WebSocket Error-Handling** — strukturierte Error-Messages an WS-Clients, Reconnect-Hints, Dead-Message-Queue für nicht-verarbeitbare Messages. In B-WS Helpers integriert | 0.5 Tage |
| B-ERR-PROP | **Error-Propagation-Konvention** — Plugin/Service → Core → API → Frontend → User. Technische Details (Tracebacks, interne Pfade) nur geloggt/monitoriert; dem User verständliche Nachricht mit `trace_id`. Im Plugin-Dev-Guide (B-PLUGIN-GUIDE) als Kapitel 22 dokumentieren | 0.5 Tage |
| B-ERR-TEST | Tests: Error-Response-Format, Kategorisierung, WS-Error-Handling, Error-Propagation | 1 Tag |

### B.14 Observability & trace_id-Korrelation

Bestehendes `structlog` (JSON-Logging) und `monitoring.py` (Prometheus-Metriken) werden um systematische Request-/Trace-Korrelation ergänzt. Kein zweites Monitoring-System, sondern `trace_id`-Propagation durch alle Ebenen.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-OBS-TRACE | **trace_id-Propagation** — Request-ID wird pro API-Request erzeugt, im `structlog` contextvars gesetzt, in jeden Log-Eintrag eingebettet, an ARQ-Worker weitergereicht (ARQ `job_metadata`), in LLM-Client-Calls injiziert, in Error-Responses zurückgegeben. Frontend kann `trace_id` aus Response anzeigen/melden | 1 Tag |
| B-OBS-LOG | **Strukturiertes Logging konsolidieren** — alle Module nutzen `structlog.get_logger()`, keine `logging.getLogger()` mehr. Log-Level konfigurierbar pro Modul. Sensitive Fields aus Logs filtern (wie Sensitive Data Boundary) | 0.5 Tage |
| B-OBS-TEST | Tests: trace_id durch alle Ebenen korreliert, Sensitive Fields nicht in Logs | 0.5 Tage |

### B.15 Graceful Shutdown & Connection Draining

Bei Coolify-Deploy oder Worker-Restart dürfen laufende Requests, WebSocket-Connections und ARQ-Jobs nicht abrupt abgebrochen werden. Bestehende `lifespan` und `on_shutdown` werden um sauberes Draining ergänzt.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-SHUT-API | **API Graceful Shutdown** — SIGTERM-Handler: keine neuen Requests akzeptieren, in-flight Requests abschließen (Timeout 30s), dann sauber beenden. `lifespan` shutdown-Phase erweitern | 0.5 Tage |
| B-SHUT-WS | **WebSocket Connection Draining** — bei Shutdown: WS-Clients über Reconnect-Hint informieren, Connections nach Grace-Period schließen. In B-WS Helpers integriert | 0.5 Tage |
| B-SHUT-WORKER | **ARQ Worker Graceful Stop** — laufende Jobs abschließen oder Checkpoint setzen (WorkflowRun `status='paused'`), keine Jobs abrupt abbrechen. `on_shutdown` erweitern | 0.5 Tage |
| B-SHUT-TEST | Tests: SIGTERM → in-flight Requests abschließen, WS drain, Worker checkpoint | 0.5 Tage |

### B.16 API Versioning Strategie

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-API-VER | **API Versioning Strategie** — `/api/v1` bleibt. Konvention dokumentieren: Breaking Changes → neue `/api/v2`-Router parallel, alte Routes deprecated für 1 Release, dann entfernt. Non-breaking Changes (neue Felder, neue Endpoints) innerhalb v1. Im Plugin-Dev-Guide ergänzen | 0.5 Tage |

### B.17 Cost Overrun Protection (Tenant-weit)

Bestehendes `budget_limit_usd` pro Agent-Definition schützt pro Agent-Run. Es fehlt ein Tenant-weites Cost-Cap das alle LLM-Calls (Agenten, Workflows, Search-Embeddings, Proactive) aggregiert.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-COST-CAP | **Tenant Cost-Cap** — `TenantSettings` um `llm_monthly_budget_usd` und `llm_hard_cutoff` ergänzen. Zentraler LLM-Client prüft vor jedem Call: Tenant-Monatskosten + Cost-Cap. Bei Überschreitung → Hard-Stop (nur noch kostenlose Calls) oder Alert. Cost-Tracking in Redis (inkrementell) | 1 Tag |
| B-COST-ALERT | **Cost Alerts** — bei 50%/80%/100% des Tenant-Budgets → System-Message im Workstream + E-Mail an Admin. Konfigurierbar | 0.5 Tage |
| B-COST-TEST | Tests: Cost-Cap greift, Alerts feuern, Hard-Stop blockiert LLM-Calls | 0.5 Tage |

**Deliverables Phase B:** Zentraler LLM Client, zentraler Redis Pool, gemeinsamer File Storage, WebSocket Helpers, Event-System dokumentiert, Schema Authority definiert, schlanker Plugin-Guide, MiniApp-Contribution-Wiring, klarer Plugin-Frontend-Vertrag, gezieltes Rate-Limiting, Sensitive Data Boundary + AI/Data Exposure Policy, AIProvider-Compliance-Metadaten, konsistente Lifecycle-Hooks + relevante Domain-Outbox-Events, gemeinsamer Trigger-Kern, vollständige Notification→Message-Konsolidierung, systematische Error-Handling-Infrastruktur (einheitliches Response-Format, Error-Kategorisierung, WS-Error-Handling, Error-Propagation-Konvention), Observability/trace_id-Korrelation, Graceful Shutdown/Connection Draining, API-Versioning-Strategie und Tenant-weites Cost-Cap/Alerts.

---

## Phase C — Core UI abschließen

**Dauer:** 4 Wochen
**Ziel:** Bereits weitgehend vorhandene Frontend-Funktionen verifizieren, fertigstellen und konsistent machen; kein paralleler UI-Neubau.

**Code-Stand:** Workspace-/Settings-/Agent-/Tag-/Custom-Field-/Saved-Filter-/Dedup-/Print-/Onboarding-/Theme-Bausteine sind im geprüften Frontend bereits vorhanden. Die Tasks dieser Phase bedeuten deshalb überwiegend **prüfen, vervollständigen, integrieren und testen**, nicht Greenfield-Bau.

**Noch nicht bauen:** History UI (Phase D), Workflow/Webhook UI (Phase G), Backup UI nur bei konkretem Bedarf. Import/Export folgt separat in Phase C.5 auf einer kleinen modularen Backend-Basis.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| C-NAV-WS-UI | Workspace-Editor UI — Module auswählen, Unterpunkte/Reihenfolge, Drag-and-Drop | 2-3 Tage |
| C-NAV-WS-DEFAULT | Standard-Workspace konfigurierbar — zeigt alles was für User freigeschaltet ist | 1-2 Tage |
| C-NAV-WS-BACK | Workspace Zurück-Button zum Startbildschirm | 0.5 Tage |
| C-NAV-AGENT | Agentenverwaltung als eigene Seite (Standalone-Layout, nur Topbar + Zurück) | 1-2 Tage |
| C-NAV-SETTINGS | Einstellungen als eigene Seite (vertikale Reiter, nur Topbar + Zurück) | 1-2 Tage |
| C-NAV-LAYOUT | Seiten-Layout-Typen: Workspace-Layout vs Standalone-Layout | 1 Tag |
| C-NOTIF | **TopBar Message/Notification UI fertigstellen** — Unread Badge und Dropdown für typisierte System-/Notification-Messages aus dem zentralen Communication-System; Klick öffnet System-Channel oder verlinkte Entity | 1-2 Tage |
| C-TAGS | Tags UI — Tag-Manager, Tag-Filter | 2 Tage |
| C-CF | Custom Fields UI — Editor, Anzeige in Detail | 2-3 Tage |
| C-FILTER | Saved Filters — speichern, laden, teilen | 2 Tage |
| C-DEDUP | Dedup/Merge UI für Kontakte | 2-3 Tage |
| C-PRINT | Print/PDF für Contact/Company | 1 Tag |
| C-DOCS | API Docs UI (Swagger-UI Embed) | 0.5 Tage |
| C-ONBOARD | Onboarding-Wizard für neue Nutzer | 1-2 Tage |
| C-THEME | CSS Custom Properties + Dark Mode + Design Tokens. Theme-Editor/Presets später | 2 Tage |
| C-A11Y | Accessibility ergänzen — sr-only Texte, ARIA-Live-Regions | 1 Tag |
| C-PWA | **PWA behalten und Service Worker sauber reaktivieren** — kontrollierte Cache-Strategie für App-Shell und statische Assets, sauberes Update-/Cache-Invalidierungsverhalten. API-, Auth-, Tenant- und Permission-sensitive Daten nicht pauschal cachen. Keine Offline-Sync-/Offline-ERP-Architektur | 0.5 Tage |
| C-FE-CLEAN | Frontend bereinigen: neue/geänderte Dateien sauber (keine any, keine inline styles wo vermeidbar). Bestehende nur bei Fehler/Security/Inkonsistenz | fortlaufend |
| C-ERR-BOUNDARY | **Frontend Error Boundaries** — ErrorBoundary-Komponente + Plugin-ErrorBoundary-Wrapper. Jede Plugin-Seite, MiniApp und kritische Komponente wird von einer ErrorBoundary umschlossen. Ein fehlerhaftes Plugin darf nicht die ganze App crashen. Fallback-UI mit `trace_id` und „Neu laden"-Button | 1 Tag |
| C-FE-TEST | Fehlende Frontend-Tests ergänzen: Vitest für neue Komponenten, API-Client-Tests, Hook-Tests | 3 Tage |
| C-DOC | `docs/ui-design-guidelines.md` aktualisieren | 1 Tag |

**Deliverables Phase C:** Stabile Navigation, Workspace-UI, Settings-Seite, Agentenverwaltung-Seite, TopBar Message/Notification UI auf dem zentralen Message-System, Tags, Custom Fields, Saved Filters, Dedup, Print, Onboarding, Theme-Basis, Accessibility, PWA mit reaktiviertem Service Worker und Frontend Error Boundaries.

---

## Phase C.5 — Modularer Import/Export

**Dauer:** 2 Wochen
**Ziel:** Die bereits vorhandene Import/Export-Implementierung in wiederverwendbare technische Bausteine konsolidieren, ohne eine universelle Ein-Endpunkt-/Ein-Modell-Engine zu bauen. Fachmodule behalten eigene Handler/Endpoints und nutzen dieselben Parser-, Mapping-, Validation- und Job-Bausteine.

**Code-Stand:** `import_export_service.py`, Routes sowie Import/Export-Frontend existieren bereits; Contact/Company sind kein Greenfield. Phase C.5 macht daraus die kleine modulare Referenzbasis und ergänzt Mapping/Preview/Background-Verarbeitung, wo noch nötig.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| C5-BASE | **Shared Import/Export Helpers** — CSV, JSON, XLSX Parser/Writer, Encoding, Schema-/Field-Mapping, Validation und strukturierte Fehlerberichte | 2 Tage |
| C5-PREVIEW | **Import Preview & Mapping** — Preview vor Commit, Spalten-Mapping, Validierungsfehler sichtbar machen | 2 Tage |
| C5-JOB | **Background Processing** — große Imports/Exports über vorhandenes ARQ, Fortschritt/Status; keine neue Job-Infrastruktur. **Partial-Failure-Semantik**: bei Teilausfällen `partial_success` Status mit klarem Fehler-Report (welche Zeilen/Records committed, welche fehlgeschlagen), kein stummes Versagen, kein inkonsistenter Zustand | 1.5 Tage |
| C5-CONTACT | **Contact Import/Export** — erster vollständiger fachlicher Handler auf gemeinsamer Basis | 1 Tag |
| C5-COMPANY | **Company Import/Export** — zweiter fachlicher Handler, beweist Wiederverwendbarkeit ohne Universalmodell | 1 Tag |
| C5-UI | **Modulare Import/Export UI** — fachmodulspezifisch nutzbare Mapping-/Preview-Komponenten | 2 Tage |
| C5-TEST | Tests: Mapping, Validation, große Jobs, Tenant-/Permission-Kontext, Sensitive Fields | 1.5 Tage |
| C5-DOC | Plugin-Dev-Guide: wie Module eigene Import/Export-Handler auf Shared Helpers aufsetzen | 0.5 Tage |

**Spezialformate:** ICS, EML, DMS-ZIP, PST etc. nur dort implementieren, wo der fachliche Use Case besteht. Keine Universalengine, die jedes Format erzwingt.

**Deliverables Phase C.5:** Gemeinsame CSV/JSON/XLSX-Basis, Preview/Mapping/Validation, ARQ-Verarbeitung für große Jobs, Contact/Company als Referenzimplementierungen und modulare UI-Bausteine.

---

## Phase D — Minimal Undo/Restore

**Dauer:** 4 Wochen
**Ziel:** Bestehende EntityHistory/History-UI gezielt zu echtem Undo/Restore für ausgewählte Businessobjekte vervollständigen. Keine universelle Migration aller History-/Versionssysteme.

**Code-Stand:** generisches History-Recording/Lesen und UI-Bausteine existieren bereits; Restore ist derzeit noch fachlich begrenzt. Deshalb vorhandenen Service erweitern, nicht ersetzen.

### Was in EntityHistory aufgenommen wird

Contact, Company, Task, Calendar Event, DMS-Metadaten. Weitere nur bei echtem Bedarf.

### Was separat bleibt

- AgentVersion (Konfigurations-Versionierung)
- AutomationVersion (Automations-Definition-Versionierung)
- CommMessageEdit (Chat-Edit-History)
- ContactMergeHistory (Merge-Protokoll)
- AuditLog (Compliance)
- WorkflowStepHistory (Runtime-Protokoll)
- Backup (Disaster Recovery)

### History-Aufzeichnung: ein Mechanismus

Hook-basiert: `do_action('entity.after_create/after_update/after_delete')` → `record_history()`. Explizit, nachvollziehbar, testbar. Keine SQLAlchemy Event Listener (ORM-Magie).

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| D-GEN | `restore_from_history()` generisch machen, aber **nur für explizit registrierte Entity-Typen**. Registry definiert Model, Restore-Erlaubnis, erlaubte Restore-Felder, Permission-Check und optionalen Sonderhandler. Kein dynamisches beliebiges ORM-Laden, kein blindes Snapshot-Zurückschreiben | 1 Tag |
| D-HOOK | Hook-basierte History: Standard-Hooks die `record_history()` aufrufen für registrierte Entities | 1 Tag |
| D-CORE | Contact, Company: `record_history()` in allen CRUD-Operationen (bereits teilweise vorhanden) | 1 Tag |
| D-PLUG | Task, Calendar, DMS-Metadaten: `record_history()` in Services | 2 Tage |
| D-SOFT | Soft-Delete + Restore für alle EntityHistory-Entitäten | 1 Tag |
| D-MAIL | **Mail Sonderbehandlung** — eigener Restore-Handler mit echter IMAP-/DB-Semantik: Delete nach Möglichkeit als Move in serverseitigen Trash, Restore zurück in ursprünglichen Ordner (falls vorhanden), notwendige Folder-/IMAP-Referenzen speichern. Serverfehler dürfen keinen falschen lokalen Status erzeugen. Kein „Undo Send“-Versprechen für bereits zugestellte externe Mails | 2 Tage |
| D-TRASH | Trash-View UI — alle gelöschten Entitäten nach Typ filterbar, Multi-Select-Restore | 1 Tag |
| D-TOAST | Undo-Toast — nach Aktion Toast "Gelöscht — Undo?" für 5 Sekunden | 1 Tag |
| D-HIST-UI | History-Panel pro Entität — Timeline, Diff-View, Restore-Button | 2 Tage |
| D-BULK | **Bulk-Restore** — Multi-Select im Trash ruft für jedes ausgewählte Objekt denselben vorhandenen Restore-Service mit Tenant-/Permission-Checks auf. Keine Batch-History-, Transaktionsgruppen- oder eigene Bulk-Undo-Architektur. **Partial-Failure-Semantik**: bei Teilausfällen `partial_success` mit Fehler-Report (welche Objekte restored, welche fehlgeschlagen), kein stummes Versagen | 1.5 Tage |
| D-RET | Retention-Policy — EntityHistory älter als 90 Tage archivieren. GDPR-Hard-Delete | 0.5 Tage |
| D-TEST | Tests: Restore funktioniert, Snapshots korrekt, Sensitive Fields ausgeschlossen, Mail-IMAP-Trash | 2 Tage |
| D-DOC | `docs/test-strategy.md`, `docs/security_kernel.md` aktualisieren | 1 Tag |

**Deliverables Phase D:** EntityHistory für Businessobjekte (Contact, Company, Task, Calendar, DMS), generisches Restore, Hook-basierte History, Mail-Sonderbehandlung, Trash-View, Undo-Toast, History-Panel, Bulk-Undo, Retention.

---

## Phase E — Unified Search vollständig

**Dauer:** 6 Wochen
**Ziel:** Die bestehende SearchProvider-/Hybrid-Search-/pgvector-/GraphRAG-Basis zu einer gemeinsamen Search-Architektur mit FTS + Vector + RAG + Graph konsolidieren und vervollständigen. Nicht jede Entity muss jeden Modus unterstützen.

**Code-Stand:** FTS, Vector Search, pgvector/HNSW, RRF-Fusion, mehrere SearchProvider und GraphRAG-Grundlagen existieren bereits. Der Schwerpunkt liegt auf Vereinheitlichung, Document-RAG, Permission-Konsistenz und einem einzigen Indexierungsweg — nicht auf Neubau.

### Such-Modi

| Modus | Was |
|---|---|
| FTS | PostgreSQL tsvector/tsquery |
| Vector | pgvector cosine similarity |
| RAG | Document-Chunking + Chunk-Embeddings + Retrieval |
| Graph | GraphRAG BFS-Traversal |

### Provider deklarieren Modi

Provider deklariert `supports_fts`, `supports_vector`, `supports_rag`, `supports_graph`. Nicht alles in alles zwingen.

### Sinnvolle globale Suche

Contacts, Companies, Mail, DMS, Tasks, Calendar, Communication, AI Chats, Wiki/Knowledge.

Nicht: AuditLog, EntityHistory, SystemSettings, technische Logs.

### Globale + modulspezifische Suche auf demselben Kern

Es gibt ausdrücklich **beides**:
- eine globale Unified Search über die Plattform
- modulspezifische Suchoberflächen/-Endpoints in Mail, DMS, Tasks usw.

Die spezifischen Suchen bleiben für gute Fach-UX erhalten, laufen technisch aber über dieselben SearchProvider, Permission-/Tenant-Regeln und dieselbe FTS/Vector/RAG/Graph-Infrastruktur. **Keine parallele eigene Suchlogik pro Modul.** Agent Memory und weitere Module werden ebenfalls über SearchProvider angebunden.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| E-PROV | SearchProvider-Schnittstelle mit `supports_fts/vector/rag/graph` Flags. **Provider-Registration erfolgt zur Plugin-Aktivierungszeit** (`auto_register_providers`), nicht dynamisch zur Laufzeit. Neue Provider benötigen Plugin-Reaktivierung | 1 Tag |
| E-FTS | FTS für alle Provider die es unterstützen | 1 Tag |
| E-VEC | Vector Search für alle Provider die es unterstützen | 1 Tag |
| E-CHUNK | Document-Chunking für DMS (semantische Chunks) | 2 Tage |
| E-EMB | Chunk-Embeddings (pgvector, ARQ Background Job) | 2 Tage |
| E-RAG | RAG Retrieval (Query → Semantic Search über Chunks → Top-K) | 2 Tage |
| E-GRAPH | Graph Traversal (GraphRAG BFS) | 1 Tag |
| E-FUSE | RRF Result-Fusion über alle Modi | 1 Tag |
| E-LLM | LLM Query Understanding (Intent, Entities, Semantic Terms) — über zentralen LLM Client | 1 Tag |
| E-PERM | Permission-aware Search (Tenant, RBAC, Visibility-Filter) | 1 Tag |
| E-IX-EVT | Auto-Indexierung: Mutation → Outbox → Worker → Index aktualisieren. Ein Weg, nicht Hook + EventBus parallel. **Index-Fehler-Handling**: bei Embedding-LLM-Fehlern, pgvector-Errors oder Timeouts → Retry über Outbox-DLQ, Dead-Letter bei permanentem Fehler, Index-Konsistenz-Check. Kein stummes Fehlschlagen von Suchergebnissen. **Concurrency**: zwei Events die dasselbe Dokument indexieren → dedup über `entity_type+entity_id+version` Lock, kein verlorenes Update | 2.5 Tage |
| E-IX-RE | Re-Indexierung: Batch-Reindex Kommando, Delete-Handling, Retry | 1 Tag |
| E-DATA-LIFE | **Derived-Data Lifecycle für Search/Vector** — Correction/Delete/Erasure-Signal aktualisiert oder entfernt FTS-/Search-Dokumente und Embeddings reproduzierbar; Rebuild aus authoritative Quelle möglich. Retention-/Legal-Hold-Entscheidung bleibt fachlich konfiguriert | 1.5 Tage |
| E-K-MAIL | Mail-spezifische Suche behalten, interne ILIKE-Logik aber auf `MailSearchProvider`/Unified Search Core umstellen | 1 Tag |
| E-K-DMS | DMS-spezifische Suche behalten, interne Suchlogik aber auf `FileSearchProvider`/Unified Search Core umstellen | 1 Tag |
| E-K-TASKS | Task-spezifische Suche behalten, interne Suchlogik aber auf `TaskSearchProvider`/Unified Search Core umstellen | 0.5 Tage |
| E-K-MEM | Agent Memory eigene Suche → SearchProvider | 1 Tag |
| E-P-AI | AI Chat Search Provider (AIChatSession, AIChatMessage) | 1 Tag |
| E-P-COMM | Communication Search Provider (CommMessage, CommConversation) | 1 Tag |
| E-P-WF | Workflow Search Provider | 0.5 Tage |
| E-API | REST API `/api/v1/search` mit Filter-Parametern | 0.5 Tage |
| E-TOOL | Tool Registry: `unified_search` als AI Tool | 1 Tag |
| E-MCP | MCP-Exposure für Search als **dünne Schicht auf dem bestehenden Search-Tool/Service**. Auth-/Run-as-Kontext und normale RBAC/ABAC-/Tenant-Prüfungen bleiben maßgeblich; MCP erhält keine eigenen Rechte | 1 Tag |
| E-UI-CMD | Command Palette (Cmd+K) — globale Suche | 2 Tage |
| E-UI-FAC | Facetten-Filter, Preview-Cards, Click-through, Saved Searches | 2 Tage |
| E-TEST | Tests: FTS, Vector, RAG, Graph, Permission-Filter, Auto-Index, Sensitive Fields ausgeschlossen | 3 Tage |
| E-DOC | `docs/api-documentation.md`, `docs/plugin-development-guide.md` (Search-Kapitel) | 1 Tag |

**Deliverables Phase E:** Unified Search mit FTS+Vector+RAG+Graph, Provider deklarieren Modi, Auto-Indexierung (Outbox→Worker), konsistenter Correction/Delete-Lifecycle für Search/Vector, KI-nutzbar (Tool, MCP, API), Command Palette sowie globale und modulspezifische Suchen auf demselben Search-Kern.

---

## Phase F — Agent MVP

**Dauer:** 6 Wochen
**Ziel:** Die vorhandene Agentenbasis zu autonomen KI-Agenten mit echtem ReAct-Loop, Skills, sicherem Permission-/Run-as-Kontext und Workstream-Integration vervollständigen. Keine Agent-Rollenarchitektur.

**Code-Stand:** `AgentDefinition`, `AgentVersion`, `AgentRun`, `AgentSubtask`, früher Coordinator/Runner und Agent-UI existieren bereits. Der aktuelle Runner ist jedoch noch kein vollständiger mehrstufiger ReAct-Loop. Ein explizites Skill-Modell/Registry wurde im Audit nicht gefunden und wird deshalb klein ergänzt.

### Permission-Modell

Effektive Fähigkeiten = User-/Run-as-Permissions ∩ Agent-Freigaben ∩ Skill-Freigaben ∩ Tool-Freigaben.
- Interaktive Runs: `run_as = aktueller Benutzer`
- Geplante/autonome Runs: expliziter Service-/Run-as-User
- Sichtbarkeit, Ausführbarkeit und effektive Tool-/Skill-Berechtigung sind getrennte Prüfungen
- Jeder Tool-/Service-Aufruf prüft den **aktuellen** User-/Run-as-Kontext erneut; Rechte werden nicht für einen Run eingefroren
- Skills orchestrieren Fähigkeiten, verleihen aber niemals zusätzliche Rechte
- Keine parallele Agent-/Skill-Rollenarchitektur

### Agent UI & Trace

Zwei Darstellungsmodi:
- **Standard:** Status, Tool Calls, Tool Results, Fortschritt, Kosten, Fehler, finale Antwort
- **Extended Trace:** zusätzlich kurze, strukturierte Entscheidungsbegründungen/Zwischenzusammenfassungen für den Nutzer

Kein vollständiger interner Chain-of-Thought; der Extended Trace ist ein explizit erzeugter, sicherer Entscheidungs-/Aktions-Trace.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| F-LOOP | `agent_loop.py` — ReAct-Loop mit LiteLLM `acompletion()` + `tools=` über zentralen LLM Client. Multi-Step-Reasoning, Tool-Call-Parsing, Error-Recovery, Graceful-Stop, Streaming — komplexer als ein einzelner LLM-Call. **LLM-Fehlerstrategie**: Provider-Rate-Limit → Backoff+Retry; Provider-Timeout → Graceful-Stop mit Fehlermeldung; Provider-Ausfall → Failover auf konfigurierten Backup-Provider; Max-Retries → Run beenden mit Fehler-Trace | 5.5 Tage |
| F-CALL | Tool-Call-Parser — extrahiert function_calls, ruft ToolRegistry auf | 1 Tag |
| F-CTX | Context-Builder — System-Prompt, Agent-Definition, relevanter User-/Tenant-Kontext, relevantes Memory, freigegebene Skills und Tool-Schemas. Zusätzliche API-/Domain-Dokumentation nur gezielt/on-demand; keine pauschale Vollinjektion der CRM-API-Spec | 2 Tage |
| F-MAX | Max-Steps-Limit + Graceful-Stop | 0.5 Tage |
| F-ERR | Error-Handling: Tool-Fehler → LLM bekommt strukturierte Error-Message mit `ErrorCategory` (TRANSIENT/PERMANENT/PARTIAL). Transient → LLM kann entscheiden zu retry-en; Permanent → LLM muss Strategie ändern; Partial → LLM bekommt Teilerfolg-Report. Keine rohen Tracebacks an LLM | 1.5 Tage |
| F-STR | SSE-Streaming mit **Standard- und Extended-Trace-Modus**: Status, Tool-Calls/-Results, Fortschritt, Kosten, Fehler, finale Antwort; optional zusätzlich strukturierte kurze Entscheidungsbegründungen/Zwischenzusammenfassungen | 1 Tag |
| F-DEF | Bestehende AgentDefinition CRUD/API/Versionierung verifizieren und nur fehlende Felder/Contracts für Runtime, Skills, Trigger und Limits ergänzen | 1 Tag |
| F-AIUSE | **AI Use-Case Metadata** — für relevante Agent-/AI-Funktionen `intended_purpose`, Owner, Datenklassen, zugelassene Provider/Modelle, zulässige Aktionen, Oversight-Policy und konfigurierbare Risikoklasse erfassen. Kein juristischer Auto-Klassifizierer | 1 Tag |
| F-TRANS | **AI Transparency** — Agent-/AI-Teilnehmer im Workstream und relevanten UIs eindeutig als AI kennzeichnen; generierte Inhalte können typisierte Herkunfts-/Kennzeichnungsmetadaten tragen | 0.5 Tage |
| F-SKILL | **Kleiner Skill-Baustein** — `SkillDefinition`/Registry + `skill_definitions`-Plugin-Contribution (oder gleichwertig) mit Name/Beschreibung/Instructions, erlaubten Tool-IDs und optionaler Context-Policy. Skills sind Orchestrierungsmetadaten, **keine Rechtequelle**, kein `SkillRole`, kein zweites RBAC | 1.5 Tage |
| F-TOOL | Tool-/Skill-Binding — Agent definiert, welche Tools und Skills er nutzen darf. Skills dürfen nur freigegebene Tools/Services orchestrieren und keine Permissions umgehen | 1 Tag |
| F-PERM | Permission-Context: Agent agiert im Kontext eines Users/Run-as. RBAC/ABAC pro Tool-/Service-Aufruf, Visibility-Filter und EntityPermission. Effektiv: User/Run-as ∩ Agent ∩ Skill ∩ Tool. Aktuelle Rechte bei jedem Call neu prüfen. **Concurrency**: zwei Agenten die dieselbe Entity mutieren → optimistisches Locking über `version`-Feld oder Row-Level Lock, kein verlorenes Update | 2.5 Tage |
| F-PERM-VIS | User-Agent Visibility: User sehen nur Agenten die für sie freigeschaltet sind (`agents:read` + EntityPermission). Über bestehendes RBAC/ABAC | 1 Tag |
| F-PERM-USE | User-Agent Usage: `agents:execute` Permission pro Agent | 0.5 Tage |
| F-MEM | Memory-Integration — agent_memory Plugin | 1 Tag |
| F-PROACTIVE | **Bestehende Proactive AI konsolidieren** — vorhandene `ContextLog`/`ProactiveSuggestion`-/Context-Event-Basis in den gemeinsamen Trigger-/Agent-Kern integrieren. Primär Domain-/UI-/andere Trigger; zeitabhängige Prüfungen nur über vorhandenen Cron/Heartbeat/ARQ. Kein neuer Polling-Mechanismus | 1 Tag |
| F-APPR | **Agent Action Approval + zentraler ApprovalRequest-Kern** — Tool-/Skill-Aktionen können per Policy/Metadaten approval-pflichtig sein (nicht nur destruktiv; auch extern, irreversibel oder sensibel). Da Agents vor Phase G kommen, wird hier der minimale **zentrale** `ApprovalRequest`-Kern angelegt/vereinheitlicht; Phase G baut nur den Workflow-Step/Queue darauf. Keine separate Agent-Approval-Engine | 2 Tage |
| F-DRY | Dry-Run-Mode | 0.5 Tage |
| F-AUDIT | Audit-Log für jeden Tool-Call | 1 Tag |
| F-OVERSIGHT | **Human-Oversight / Decision Record** — Use-Cases können bestimmte personen-/risikorelevante Aktionen zwingend vor Außenwirkung an `ApprovalRequest` binden; Recommendation/Evidence, Reviewer, Entscheidung, Zeitpunkt und Abweichung nachvollziehbar speichern | 1 Tag |
| F-DATA-POL | **Runtime Provider/Data Policy Enforcement** — Agent/Context Builder/LLM Client respektieren B-DATA-POL und B-AIPROV-COMP; nicht erlaubte Felder/Provider werden vor dem LLM-Call geblockt bzw. minimiert | 1 Tag |
| F-UI-CTRL | **Bestehendes AI UI Control als Agent-Tool integrieren/erweitern** — Navigation, Filter, Tabs, Modals, Ansichten, Form-Prefill und UI-Kontext steuern. **Persistente fachliche Mutationen ausschließlich über reguläre Tools/Services mit bestehenden Permission-Prüfungen**; `ai_ui_control:write` darf keine Fachrechte umgehen. Feedback-Loop: Agent → REST/WebSocket → Frontend → Feedback → Agent | 1.5 Tage |
| F-UI-TRIG | **Bestehende UI-Context-Events zum allgemeinen UI-Trigger ausbauen** — Frontend-Events (`ui.contact_selected`, `ui.page_navigated`, `ui.mail_opened`, `ui.task_status_changed` etc.) triggern Agenten/Proactive Suggestions **ephemer über EventBus/Redis + gemeinsamen Trigger-Dispatcher, nicht über Outbox**. Trigger im Agent-Editor konfigurierbar; Bedingungen nutzen vorhandene Condition-Logik. Sobald ein Agent startet, wird `AgentRun` persistent gespeichert | 2 Tage |
| F-WORK | **Agent → zentraler Workstream** — Agenten posten Text, Status, `action_card`, Entity-/Contact-Cards, Knowledge-Quellen, Approval- und `miniapp`-Blocks über das bestehende Communication-System. Kein zweites Agent-Message-/Chat-Modell | 1.5 Tage |
| F-UI-LIST | Agent-Liste — Kartenansicht und Listenansicht (Toggle) | 1.5 Tage |
| F-UI-EDIT | Agent-Editor — System-Prompt, Modell, Tools, Limits, Trigger | 2 Tage |
| F-UI-CHAT | Agent-Chat-UI — interaktive Konversation | 2 Tage |
| F-UI-LOG | Agent-Run-Log — Aktionen, Tool Calls, Resultate, Status, Kosten, Fehler | 1 Tag |
| F-UI-MON | Agent-Monitoring — Live-Status, aktive Runs, Budget | 1 Tag |
| F-EMAIL | Pre-Built: E-Mail-Triage-Agent | 2 Tage |
| F-CONTACT | Pre-Built: Contact-Enrichment-Agent | 1 Tag |
| F-FOLLOW | Pre-Built: Follow-up-Agent | 1 Tag |
| F-REPORT | Pre-Built: Report-Agent | 1 Tag |
| F-TEST | Tests: ReAct-Loop, Tool-Calling, Permissions, Approval, Budget-Limits | 3 Tage |
| F-DOC | `docs/api-documentation.md`, `docs/plugin-development-guide.md` (Agent-Kapitel) | 1 Tag |

### F.14 Unified Task System

Das bestehende Tasks-Plugin (713 Zeilen, nur `contact_id`, nur User-Assignment) wird zu einem **systemweiten Assignment-System** upgegradet. Kein zweites System, sondern das bestehende Tasks-Plugin das erwachsen wird. AI, Menschen, Gruppen und Workflows können Aufgaben erstellen, zugewiesen bekommen und mit jedem Objekt verknüpfen.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| F-TASK-MODEL | **Task-Modell erweitern** — `assignee_type` (user/agent/group) + `assignee_id` (polymorph), `entity_type` + `entity_id` (polymorph, wie EntityLink), `creator_type` (user/agent/workflow/system) + `creator_id`, `parent_task_id` (Self-Reference für Subtasks), `depends_on` (Task-Dependencies), `task_type` (todo/approval/follow_up/review), Lifecycle: open/in_progress/review/blocked/done/cancelled | 2 Tage |
| F-TASK-API | **Task API erweitern** — bestehende Tasks-Routes um polymorphe Entity-Links, polymorphe Assignees, Subtasks, Dependencies und neue Lifecycle-Status ergänzen. Bestehende Contact-Tasks bleiben kompatibel | 1.5 Tage |
| F-TASK-AGENT | **Agent ↔ Task Integration** — Agenten können Tasks erstellen (`create_task` Tool), Tasks zugewiesen bekommen (`assignee_type='agent'`), Task-Status aktualisieren und Tasks als Subtasks zerlegen. `AgentSubtask` wird zu `Task` mit `task_type='agent_subtask'` migriert | 1.5 Tage |
| F-TASK-WORK | **Task → Workstream** — Tasks erscheinen als `task_card` Block-Typ im Communication-System: Titel, Assignee, Due-Date, Status, Entity-Deep-Link, Action-Buttons (Done/Reassign/Comment). Status-Änderungen posten Updates in den Workstream | 1 Tag |
| F-TASK-UI | **Task UI erweitern** — Task-Liste mit Filter (nach Assignee, Entity, Status, Due-Date), Task-Detail mit Subtasks/Dependencies, Task-Board (Kanban-View optional), Task-Assignment-Dropdown (User/Agent/Group) | 2 Tage |
| F-TASK-MIG | **Migration** — bestehende `Task.contact_id` → `entity_type='contact' + entity_id`, `Task.assigned_to` → `assignee_type='user' + assignee_id`. `AgentSubtask` → `Task` mit `task_type='agent_subtask'`. Daten-Migration + View für Übergang | 1 Tag |
| F-TASK-TEST | Tests: Polymorphe Assignment, Entity-Links, Subtasks, Agent-Task-Creation, Workstream-Integration, Migration | 1.5 Tage |

**Deliverables Phase F:** ReAct-Agenten auf vorhandener Agentenbasis, kleiner Skill-Baustein, Tool-/Skill-Calling, Permission-Modell (User/Run-as ∩ Agent ∩ Skill ∩ Tool) mit Concurrency-Schutz, AI-Use-Case-/Transparency-Metadaten, Provider/Data-Policy-Enforcement, Standard+Extended Trace, LLM-Fehlerstrategie (Rate-Limit-Backoff, Provider-Failover, Timeout-Graceful-Stop), strukturiertes Tool-Error-Handling mit ErrorCategory, trigger-basierte Proaktivität, UI Control ohne Permission-Bypass, zentraler ApprovalRequest-Kern + Human-Oversight-Record, Workstream-Ausgabe, Agent UI, 4 Pre-Built Agenten und Unified Task System (polymorphe Assignment, Entity-Links, Subtasks, Agent↔Task, Workstream-Integration).

---

## Phase G — Workflow MVP

**Dauer:** 6 Wochen
**Ziel:** Die vorhandene Workflow-/Automation-Basis zu einer robusten CRM-/Business-Automation ausbauen. Form+JSON Editor. Kein visueller Canvas. Kein Raw SQL. Kein Code-Node.

**Runtime-Invariante:** `Workflow`/`WorkflowRun` ist die authoritative langlebige Multi-Step-Engine. `AutomationDefinition` bleibt die leichte Trigger/Condition/Action-/Scheduler-Schicht und darf Workflows starten, wird aber **keine zweite durable Workflow-Engine**.

**Abgrenzung:**
- **AutomationDefinition** = einfache Event-Reaktion: 'Wenn Event X → führe Action Y aus'. Single-Step, nicht-durable, keine Resume-Semantik. Beispiele: 'Mail empfangen → Notification senden', 'Contact erstellt → Proactive Suggestion'.
- **Workflow** = komplexe Multi-Step-Prozesse: 'Warte auf Approval → führe 5 Steps aus → Warte 3 Tage → finalisiere'. Durable, resumable, mit ExecutionContext und Idempotency.
- **Automation kann Workflows starten** (Trigger → `start_workflow`), aber nicht umgekehrt.
- **Beide nutzen denselben Trigger-Kern** (B.11) und denselben ApprovalRequest-Mechanismus (F-APPR/G-APPROVAL).

**Code-Stand:** persistente Workflow-Instanz/Step-History, Conditions und Approval-Pause sowie AutomationDefinition/Run/Version/Cron existieren bereits. Phase G erweitert diese Basis um allgemeines Resume/Wait, Idempotency, neue Business-Steps und Agent-/Workstream-Integration.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| G-COND | Condition-Step (bestehend, erweitern) | 0.5 Tage |
| G-WAIT | **Wait/Delay-Step — persistent/resumable**: WorkflowRun speichert `status`, `current_step`, `execution_context` sowie `resume_at` bzw. Wait-Kriterium. Worker beendet sich während Wartezeiten und setzt den Run später über vorhandenen ARQ/Cron/Event-Pfad fort; kein langes `sleep()`/blockierender Worker | 1 Tag |
| G-HTTP | **HTTP-Request-Node** — Method/URL/Headers/Body/Response-Mapping plus Timeout, maximale Response-Größe, SSRF-Schutz für private/interne Ziele, kontrollierte Protokolle/Redirects und Credentials ausschließlich über sicheren Credential-/Secret-Mechanismus statt Workflow-JSON | 1-1.5 Tage |
| G-MAIL | Mail-Send-Node | 0.5 Tage |
| G-CAL | Calendar-Node | 0.5 Tage |
| G-DMS | DMS-Node | 0.5 Tage |
| G-SEARCH | Search-Node (Unified Search) | 0.5 Tage |
| G-AGENT | Agent-Step (ruft autonomen Agenten auf) | 1 Tag |
| G-CRM | CRM-Action-Node (create/update Contact, etc.) | 1 Tag |
| G-EVT | Event-Trigger (CRM-Event startet Workflow) | 1 Tag |
| G-CRON | Cron-Trigger (bestehender Scheduler erweitern) | 0.5 Tage |
| G-WEB | **Incoming Webhook-Trigger** — externer HTTP-Call startet Workflow über sicheren token-/permission-basierten Endpoint, Rate-Limit und Payload-Validation; nutzt gemeinsamen Trigger-/Execution-Kern aus B.11 | 1 Tag |
| G-MAN | Manual-Trigger (Button in UI) | 0.5 Tage |
| G-RETRY | **Retry-Logic für fehlgeschlagene Steps** — Retry/Backoff über vorhandenen Execution-/ARQ-Pfad. Side-Effect-Steps müssen soweit erforderlich idempotent bzw. über Execution-/Idempotency-Key vor Doppel-Ausführung geschützt sein | 1.5 Tage |
| G-LOG | Execution-Log pro Step (Input, Output, Duration, Status) | 1 Tag |
| G-WORK | **Workflow/System → zentraler Workstream** — typisierte Status-, Handoff-, Approval-, Action- und MiniApp-Blocks über Communication posten. Bestehende Workflow-`notification`-Produzenten auf zentrales Message-System umstellen; kein separates Workflow-Notification-System | 1 Tag |
| G-APPROVAL | **Generischer Approval-Step auf zentralem `ApprovalRequest`** — den in Phase F angelegten gemeinsamen Kern für Workflows verwenden/erweitern; für beliebige Workflows, Entities und Aktionen nutzbar; Approver/Gruppe, `pending/approved/rejected/expired`, Referenz auf Workflow/Run/Aktion, Kommentar, Zeitstempel, System-Message, Approval-Queue, Audit und optional Timeout. **Keine pauschalen `pending_approval/active/rejected`-Statusfelder auf allen Entities**; fachliche Status nur im jeweiligen Modul, wenn benötigt. Derselbe Mechanismus wird von Agent-Approvals verwendet | 2.5 Tage |
| G-HUMAN-DEC | **Automated-Decision Guard** — für entsprechend konfigurierte AI-Use-Cases dürfen Workflow-/Agent-Ergebnisse keine definierte personen-/risikorelevante Außenwirkung automatisch auslösen, bevor die geforderte Human-Review-/Approval-Policy erfüllt ist. Kein pauschaler Zwang für normale CRM-Automation | 1 Tag |
| G-CTX | **Persistenter Execution-Context** — Daten-Flow zwischen Steps (Variablen, Expressions) wird zusammen mit WorkflowRun dauerhaft gespeichert und kann nach Wait, Restart, Worker-Crash oder Event-Resume fortgesetzt werden | 2 Tage |
| G-RUN | **Durable WorkflowRun / Resume-Semantik** — bestehendes `WorkflowInstance`-Model wird zu `WorkflowRun` erweitert/umbenannt. Run-State, Step-State und Resume-Grund (`resume_at`, Event/Approval/Webhook) persistent halten. Resume lädt denselben Run und setzt exakt am vorgesehenen Step fort; keine zweite Workflow-Runtime. **Concurrency**: zwei Worker die denselben Run resume → Redis-Lock pro `WorkflowRun.id`, nur ein Worker resume, anderer wartet oder überspringt | 2 Tage |
| G-IDEMP | **Idempotency-/Deduplizierungsschutz für Side Effects** — Side-Effect-Steps (z. B. Mail, HTTP, CRM-Mutation) erhalten pro Execution einen stabilen Idempotency-/Execution-Key bzw. deduplizierbare Ausführungslogik, damit Retry/Worker-Restart keine unbeabsichtigten Doppelaktionen erzeugt | 1 Tag |
| G-UI-FORM | Form-basierter Step-Editor — Step-Liste mit Up/Down, Formular pro Step-Typ | 2 Tage |
| G-UI-JSON | JSON-Expert-Mode — Toggle zwischen Form und JSON | 0.5 Tage |
| G-UI-VALID | Validation — Required-Field-Check, Step-Reihenfolge | 0.5 Tage |
| G-UI-TEMPL | Template-Gallery — vorgefertigte Workflows | 1 Tag |
| G-TEST | Tests: Step-Execution, Trigger, Retry, Expressions | 2 Tage |
| G-DOC | `docs/api-documentation.md` aktualisieren | 1 Tag |

**Deliverables Phase G:** Bestehende Workflow/Automation-Basis konsolidiert, Workflow Engine mit Form+JSON Editor, 10+ Step-Types, 4 Trigger-Typen, persistenter/resumable WorkflowRun, idempotency-sicheren Side-Effect-Steps, Retry, Execution-Log, zentralem ApprovalRequest + konfigurierbarem Automated-Decision Guard, Workstream-Ausgabe und Template-Gallery.

---

## Phase H — Knowledge

**Dauer:** 6 Wochen
**Ziel:** Die **gesamte relevante Firmenwissensbasis** über denselben Search/RAG/Graph-Kern nutzbar machen: Wiki, DMS, Mail, Communication/Workstreams und ausgewählte fachliche Entitätsinhalte. Kein erneuter Search-/RAG-Aufbau und kein zweiter universeller Knowledge-Datenspeicher.

**Code-Stand:** GraphRAG/Entity-Beziehungen und Search-Grundlagen existieren; echtes Wiki, Document-RAG und automatische Knowledge-Extraktion fehlen noch.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| H-WIKI | Wiki-Plugin — Knowledge-Artikel mit Markdown-Editor, Kategorien, Tags | 2 Tage |
| H-VER | Versionierung — Artikel-Historie, Diff-View, Restore | 1 Tag |
| H-LINK | Auto-Linking — Artikel verlinken auf Entitäten | 1 Tag |
| H-SEARCH | Wiki Search Provider (in Unified Search) | 0.5 Tage |
| H-EMB | Wiki-Embeddings (in RAG-Pipeline) | 0.5 Tage |
| H-SRC | **Knowledge Source Adapter** — DMS, Wiki, Mail, Communication/Workstreams sowie explizit freigegebene fachliche Text-/Notizfelder über bestehende SearchProvider/RAG-Pipeline anbinden. Originalquelle bleibt authoritative; Permissions/Sensitive Fields gelten durchgängig | 2 Tage |
| H-CITE | **Evidence/Source References** — RAG-/Knowledge-Ergebnisse liefern strukturierte Quellenreferenzen/Deep-Links bzw. Cards auf originales Dokument, Mail, Message oder Businessobjekt; Agenten können diese im Workstream anzeigen | 1 Tag |
| H-EXT | LLM-Relationship-Extraktion — analysiert Texte, extrahiert Beziehungen | 2 Tage |
| H-ENT | Entity-Extraction — erkennt Personen, Firmen, Projekte | 1 Tag |
| H-AUTO | Auto-Relationship-Creation in GraphRAG | 1 Tag |
| H-CONF | Confidence-Score, Low-Confidence → Review-Queue | 1 Tag |
| H-EVT | Event-Driven-Extraction (neue Mail/Dokument/Message bzw. relevante fachliche Wissensänderung → ARQ-Job → Extraktion); nur konfigurierte Knowledge-Quellen | 1 Tag |
| H-DATA-LIFE | **Derived-Data Lifecycle für Knowledge** — Correction/Delete/Erasure der authoritative Quelle propagiert über denselben Event-/Worker-Weg zu RAG-Chunks, Embeddings, Graph-Referenzen und angebundenem Agent Memory; source references ermöglichen gezieltes Rebuild/Remove | 2 Tage |
| H-RET | **Knowledge/Memory Retention** — kleine Retention-/Source-Policy je Wissensquelle/Datenklasse; keine zweite Archivierungsengine, ARQ räumt nur nach konfigurierter Policy auf | 1 Tag |
| H-GRAPH | Wissensgraph-Visualisierung (Cytoscape) | 2 Tage |
| H-EDITOR | Wiki-Artikel-Editor (TipTap) | 1 Tag |
| H-BROWSE | Knowledge-Browser — Baumansicht, Artikel-Liste | 1 Tag |
| H-ASK | **Ask Knowledge im zentralen Workstream** — RAG-Queries und Antworten mit Quellen-Cards über Communication/BlockRenderer; keine neue isolierte Chat-Silo-UI | 1 Tag |
| H-REV | Review-Queue für extrahierte Beziehungen | 0.5 Tage |
| H-TEST | Tests: Wiki CRUD, RAG-Query, Extraction, Graph | 2 Tage |
| H-DOC | `docs/api-documentation.md`, `docs/plugin-development-guide.md` | 1 Tag |

**Deliverables Phase H:** Firmenwissensschicht aus Wiki + DMS + Mail + Communication + freigegebenen Businessinhalten, Document-RAG, Quellen/Evidence-Cards, automatische Wissensgraph-Extraktion, konsistenter Correction/Delete/Retention-Lifecycle für RAG/Embeddings/Graph/Memory, Knowledge-UI mit Graph-Visualisierung und Ask-Knowledge im zentralen Workstream.

---

## Phase I — Integration, Human-AI Workstream & Polish

**Dauer:** 6 Wochen
**Ziel:** Alle Systeme verbinden und den bereits vorhandenen Communication-/Sidebar-/MiniApp-Unterbau zum produktiven **Human-AI Workstream** machen: Menschen, Agenten, Workflows, Firmenwissen und interaktive Business-MiniApps arbeiten in einem gemeinsamen Strom — Desktop und mobil.

### I.1 Cross-System-Integration

Alle in Phase E-H gebauten Systeme müssen miteinander verbunden werden.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-AW | **Agent → Workflow** — Agenten können Workflows als Tools aufrufen (`start_workflow`, `check_workflow_status`) | 1 Tag |
| I-WA | **Workflow → Agent** — Workflows können Agenten als Steps aufrufen (bereits G-AGENT, verifizieren) | 0.5 Tage |
| I-AS | **Agent → Search** — Agenten nutzen Unified Search als Tool (bereits E-TOOL, verifizieren) | 0.5 Tage |
| I-AK | **Agent → Knowledge** — Agenten nutzen RAG/Graph/Knowledge mit Evidence-Referenzen | 0.5 Tage |
| I-KS | **Knowledge → Search** — Wiki/Knowledge-Quellen in Unified Search (bereits H-SRC/H-SEARCH, verifizieren) | 0.5 Tage |
| I-MCP | **MCP-Exposure für Plattformfeatures** — Search, Agents, Workflows, Knowledge als dünne Exposure-Schicht auf bestehenden Tools/Services. MCP besitzt keine eigenen Rechte; vorhandener Auth-/Run-as-Kontext und normale Permission-Prüfungen gelten immer | 1.5 Tage |

### I.2 Human-AI Workstream & MiniApp Runtime

**Prinzip:** Kein neues Workstream-Datenmodell. `CommConversation`/`CommMessage` sind der zentrale Arbeitsstrom. Die rechte `MessageSidebar` und mobile Communication-UI werden erweitert. MiniApps visualisieren/steuern vorhandene Domain-Services; Businessdaten bleiben authoritative in ihren Fachmodulen.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-WORK-BASE | **Workstream Contract festschreiben** — Menschen, System, Agents und Workflows als Teilnehmer/Akteure im vorhandenen Communication-Modell; typed blocks statt separater Agent-/Notification-/Workflow-Chats | 0.5 Tage |
| I-MINI-MANIFEST | **MiniApps bis Frontend durchreichen** — `/plugins/active-manifests` und `PluginUiManifest` um `miniapps`/Render-Metadaten ergänzen; bestehende `manifest.miniapps`-Definition wirklich nutzbar machen | 1 Tag |
| I-MINI-RENDER | **`MiniAppBlock` Placeholder ersetzen** — `app_id` über gemeinsamen Registry/Resolver zu echter interaktiver Darstellung auflösen; Fehler-/Fallback-State sauber behandeln | 2 Tage |
| I-MINI-SDK | **Kleines MiniApp UI/Schema-SDK** — Standardbausteine für Entity Card/Detail, Form, Auswahl, Liste, Action Buttons, Approval, Progress und Deep-Link. `render_schema` validieren; Aktionen gehen über reguläre APIs/Services + Permissions | 2 Tage |
| I-WORK-ACTOR | **Einheitlicher Posting-Pfad** — Human/System/Agent/Workflow können Text, Entity Cards, Action Cards, Knowledge Evidence, Approval und MiniApps über denselben Communication-Service posten | 1 Tag |
| I-WORK-HANDOFF | **Human↔Agent Handoff** — `review_needed`/`action_required`/`waiting_for_user` als typisierte Workstream-Semantik; Aktion oder User-Änderung kann denselben AgentRun/WorkflowRun fortsetzen. **Task-basierter Handoff**: Handoff erstellt automatisch einen `Task` mit `assignee_type` (user/agent/group), `entity_type+entity_id` Referenz und `task_type='handoff'`; Task-Status-Änderung fortsetzt den Run | 2 Tage |
| I-WORK-PROACTIVE | **Proactive Workstream Feed** — UI-/Domain-Trigger erzeugen kontextuelle Vorschläge/Actions im Workstream mit Priority, Dedupe, Cooldown und User-Einstellungen; kein störendes Popup-/Clippy-Verhalten | 1.5 Tage |
| I-WORK-GROUP | **Shared Group Workstreams** — vorhandene Conversation-/Participant-Rechte für mehrere Menschen + Agenten verifizieren; Mentions/Unread/Assignment/Handoffs auf Gruppenfluss testen | 1 Tag |
| I-WORK-MOBILE | **Mobile/PWA Workstream** — bestehendes mobile Sidebar/Overlay + PWA so fertigstellen, dass alle Standard-Blocks/MiniApps touch-tauglich sind; Datei-/Foto-Upload, Actions, Approval, Deep-Links und Agent-Interaktion mobil E2E testen. Keine Offline-ERP-Sync-Architektur | 2 Tage |
| I-WORK-PLUGINUI | **Branchenplugin-UI-Vertrag verifizieren** — volle React-Pluginseiten werden gebündelt/deployed; runtime-fähige Workstream-MiniApps schema-basiert. Keine Annahme, dass Vite nachträglich beliebigen React-Code hot-loaden kann | 1 Tag |
| I-PLUGIN-REF | **Reference Vertical Plugin / Contract Proof** — kleines Test-/Beispielplugin beweist ohne Core-Sondercode: eigene Migration/Domain-Route, Full-Page-UI, MiniApp, Tool, Skill, Agent/Trigger, Workflow/Automation und Search/Knowledge-Contribution. Kein neues Branchenprodukt, sondern Integrationsbeweis | 2 Tage |
| I-WORK-E2E | **Human-AI-Co-Working E2E** — Referenzfluss: Mail öffnen → UI-Trigger → Agent analysiert Mail+Knowledge → Termin/Projekt-MiniApp im Workstream → User prüft/ändert → Domain/UI-Event → Agent/Workflow setzt fort. Zusätzlich Shared-Group- und Mobile-Flow | 2 Tage |

### I.3 Dashboard & Analytics

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-DASH | **Platform Dashboard** — Agent-Status, Workflow-Stats, Search-Metrics, Knowledge-Coverage, Workstream-/Suggestion-Metriken, System-Health | 2 Tage |
| I-COST | **Cost-Tracking Dashboard** — LLM-Kosten pro Agent/Workflow/User, Budget-Alerts, Cost-Trends. LLM Client hat Cost-Tracking (B.1) und Tenant-Cost-Cap (B-COST-CAP), hier wird die UI gebaut: Live-Kosten, Budget-Auslastung, Alert-History, Cost-Per-Tenant/Agent/Workflow, Hard-Stop-Events | 2 Tage |
| I-USE | **Usage-/Collaboration-Analytics** — Feature-Nutzung, Search-Queries, Agent-Runs, Workflow-Executions sowie angenommene/verwerfene Proactive Suggestions/Handoffs als Basis für Phase J | 1 Tag |

### I.4 Performance Review & gezielte Optimierung

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-PERF | **Performance-Vergleich zuerst** — gegen Phase-A-Baseline messen, Bottlenecks und Regressionen identifizieren | 1 Tag |
| I-BATCH | **Batch-Embedding** — grundsätzlich vorsehen und anhand Durchsatz/Kosten sinnvoll konfigurieren | 0.5 Tage |
| I-CACHE | **Search-Caching (conditional)** — nur aktivieren/ausbauen, wenn Messwerte Nutzen zeigen; Tenant-/User-/Permission-Kontext und Cache-Invalidierung korrekt berücksichtigen | 1 Tag |
| I-QUEUE | **ARQ-Queue-Tuning (conditional)** — Prioritäten, Concurrency-Limits, DLQ nur anhand realer Last/Bottlenecks konfigurieren | 1 Tag |
| I-IDX | **DB-/FTS-/pgvector-/HNSW-Tuning (conditional)** — Indizes/Parameter anhand Messwerten optimieren; Write-Performance und Ressourcenverbrauch gegenprüfen | 1 Tag |

### I.5 DSGVO-Betroffenenrechte & Compliance Export

Wenn Core, Communication, Agents, Workflows und Knowledge vollständig integriert sind, wird der plattformweite Betroffenenrechts-/Nachweisweg fertiggestellt. Keine universelle Privacy-Engine und kein blindes automatisches Löschen über fachliche/gesetzliche Aufbewahrungspflichten hinweg.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-DSGVO | **Vollständiger Plattform-Datenauskunfts-Export** — personenbezogene Daten eines Users/Betroffenen über Core und aktive Plugins hinweg (u. a. CRM, Mail, Calendar, DMS, Communication/Workstreams, Agents, Workflows, Knowledge, Audit) als strukturierter JSON/ZIP-Export. Sensitive-/Exposure-Regeln zwingend beachten | 2 Tage |
| I-DSAR | **Betroffenenrechts-Workflow** — Access/Correction/Erasure/Restriction als nachvollziehbarer administrativer Vorgang: betroffene Quellen finden, fachliche Handler aufrufen, abgeleitete Daten über E/H-Lifecycle nachziehen, Ausnahmen/Retention dokumentieren. Kein generischer Blind-Hard-Delete | 2 Tage |
| I-COMP-EXPORT | **AI/Compliance Evidence Export** — AI-Use-Case-Metadaten, Provider-/Modellbezug, Agent-/Workflow-Versionen, relevante Audit-/Oversight-/Approval-Evidenz und technische Policies als exportierbares Nachweispaket | 1 Tag |

### I.6 Onboarding & Dokumentation

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-ONB | **Feature-Onboarding** — Setup-Wizard für Agenten, Workflows, Knowledge, Workstreams/MiniApps und Proactive Collaboration | 1 Tag |
| I-DOC | **Platform-Dokumentation** — Architektur-Doku, Plugin-Dev-Guide final, Agent-Dev-Guide, Workstream/MiniApp-Guide, User-Guide | 2 Tage |
| I-VID | **Feature-Videos** — kurze Screencasts für Agent-Builder, Workflow-Editor, Knowledge und Human-AI Workstream | 1 Tag |

### I.7 Final Polish

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-UI | **UI-Polish** — alle neuen Features visuell vereinheitlichen, Loading-/Error-/Empty-/Agent-working-/Review-needed-States konsistent | 2 Tage |
| I-TEST | **Vollständige Test-Pipeline** — alle 8 Checks über das gesamte System, E2E für alle kritischen Flows inklusive Workstream/MiniApps/Mobile | 2 Tage |
| I-DEPLOY | **Production-Deploy** — Deploy, Health-Check, Smoke-Test, Monitoring verifizieren | 1 Tag |

**Deliverables Phase I:** Alle Systeme verbunden (Agent↔Workflow↔Search↔Knowledge↔Communication), produktiver Human-AI Workstream auf dem zentralen Message-System, echte plugin-erweiterbare MiniApps, Proactive Collaboration, Shared Group Workstreams, mobile/PWA-Workstreams, MCP, Dashboard/Analytics, DSGVO-Betroffenenrechtsweg + Compliance Evidence Export, Onboarding und Production-Deploy.

---

## Phase J — Controlled Self-Improvement

**Dauer:** 5 Wochen
**Ziel:** Leo kann aus realer Arbeit Verbesserungspotenziale erkennen und **kontrolliert** bessere Agenten-/Skill-/Trigger-/Workflow-/MiniApp-Konfigurationen vorschlagen. Keine heimliche Selbstmodifikation und keine ungeprüften Production-Code-Änderungen.

### Grundregel

Self-Improvement ist ein **Versionierungs-, Evaluations- und Approval-Loop**, kein autonomer Production-Code-Editor:

```text
Beobachten → Muster/Effekt erkennen → ImprovementProposal
→ versionierten Draft erzeugen → Dry-Run/Simulation/Tests
→ Human Approval → kontrolliert aktivieren
→ Wirkung messen → behalten oder rollback
```

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| J-SIGNAL | **Improvement Signals** — vorhandene `ContextLog`, accepted/dismissed Proactive Suggestions, AgentRuns, WorkflowRuns, AuditLog, EntityHistory, User-Korrekturen/Handoffs und Outcome-Metriken als referenzierte Signale nutzbar machen. Datenminimierung/Exposure-Policy/Retention gelten auch hier; möglichst Referenzen/Aggregate statt unnötiger personenbezogener Vollkopien | 2 Tage |
| J-PATTERN | **Pattern/Bottleneck Detection** — wiederkehrende manuelle Sequenzen, häufige Korrekturen, abgelehnte Vorschläge, Retries/Fehler und repetitive Handoffs erkennen; Confidence/Evidence speichern | 2 Tage |
| J-PROP | **`ImprovementProposal`** — Vorschlag mit Zieltyp (`agent`, `skill`, `trigger`, `workflow`, `miniapp_template`, optional `plugin_patch`), Evidence-Refs, Begründung, erwarteter Nutzen, Risiko und Status | 1.5 Tage |
| J-DRAFT | **Versionierter Draft** — vorhandene Agent-/Automation-/Workflow-Versionierung wiederverwenden und bei Bedarf kleine Skill/MiniApp-Template-Versionierung ergänzen. Keine universelle Versionierungsengine | 2 Tage |
| J-EVAL | **Evaluation/Sandbox** — Vorschläge gegen sichere historische/synthetische Fälle per Replay, Dry-Run und Tests bewerten; keine externen Side Effects | 3 Tage |
| J-APPROVAL | **Human Approval** — Aktivierung immer über zentralen ApprovalRequest/Workstream; Verantwortlicher sieht Evidence, Diff, Tests und erwartete Auswirkung | 1 Tag |
| J-ACTIVATE | **Controlled Activate + Rollback** — atomar die freigegebene Version aktivieren; vorherige Version bleibt rollback-fähig | 1 Tag |
| J-MEASURE | **Pre/Post Impact Measurement** — Zeit, Fehler, Annahmequote, Kosten, Durchsatz und fachliche Outcome-Metriken soweit verfügbar vergleichen; Ergebnis fließt in spätere Proposal-Qualität ein | 2 Tage |
| J-UI | **Improvement Center im Workstream/Settings** — Proposal Cards/MiniApps für Review, Evidence, Simulationsergebnis, Approve/Reject/Rollback | 2 Tage |
| J-CODE | **Code-/Plugin-Verbesserungen nur über normalen Engineering-Weg** — falls Leo einen Plugin-/MiniApp-Codepatch vorschlägt: Patch/Branch → Tests/CI → menschliches Review → normaler Release. Niemals autonomer direkter Production-Code-Write | 1 Tag |
| J-TEST | Tests: Signal-Isolation/Tenant, Proposal-Evidence, Sandbox ohne Side Effects, Approval, Rollback, Measurement | 2 Tage |
| J-DOC | Self-Improvement-Sicherheits-/Betriebsregeln und Plugin-Guide ergänzen | 1 Tag |

**Deliverables Phase J:** kontrollierter Lern-/Verbesserungskreislauf auf realen Nutzungs- und Outcome-Signalen, versionierte Improvement Proposals, Evaluation/Dry-Run, Human Approval, Rollback und Wirkungsmessung — ohne autonome ungeprüfte Production-Selbstmodifikation.

---

## Phase K — EU Compliance Finalization

**Dauer:** 1 Woche
**Ziel:** Die während B–J bereits technisch eingebauten Privacy-/AI-Compliance-Funktionen zu einem prüfbaren Betreiber-/Produktnachweis zusammenführen. Kein neuer Runtime-Kern, keine juristische Auto-Entscheidungsengine.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| K-REG | **AI System / Use-Case Register UI** — vorhandene F-AIUSE-Metadaten übersichtlich verwalten: Intended Purpose, Owner, Agent/Workflow/Plugin, Provider/Model, Datenklassen, Oversight, Risk-Class, Status/Version | 1 Tag |
| K-DPIA | **DPIA / AI Impact / FRIA Support** — aus vorhandenen Metadaten und Evidence vorbefüllbare Templates/Exports für Datenschutz-Folgenabschätzung bzw. AI-/Grundrechts-Risikoprüfung, **wo der konkrete Einsatz dies verlangt**. Keine automatische Rechtsbewertung | 1 Tag |
| K-INC | **AI/Privacy Incident Register** — Incident erfassen, betroffene Use-Cases/Versionen/Provider/Runs referenzieren, Maßnahmen und Evidence dokumentieren; Reporting-Fristen/-pflichten bleiben organisatorisch/use-case-spezifisch | 0.5 Tage |
| K-RET | **Retention-/Erasure Admin UI** — vorhandene Daten-/Knowledge-/Memory-Retention-Policies administrierbar und nachvollziehbar machen; Legal Hold/Ausnahme nur als explizite Policy, keine neue Storage-Engine | 0.5 Tage |
| K-COMP-TEST | **Compliance E2E/Contract Tests** — AI-Kennzeichnung, Data-Exposure/Provider-Blocking, Search/RAG/Graph/Memory-Cleanup, Betroffenenrechtsweg, Oversight/Approval-Record, Tenant-Isolation und Evidence Export durchtesten | 1.5 Tage |
| K-DOC | **EU Compliance Betriebsdoku** — Rollen/Verantwortlichkeiten, Provider-Onboarding, Use-Case-Klassifikation, DPIA/AI-Impact-Checkliste, Incident-/DSAR-Ablauf, Plugin-Anforderungen und klare Grenze „Plattformfunktion ≠ automatische Rechtskonformität“ | 0.5 Tage |

**Deliverables Phase K:** prüfbares AI-/Privacy-Use-Case-Register, vorbefüllbare Compliance-Templates, Incident-/Retention-Administration, E2E-Nachweis der technischen Datenschutz-/Oversight-Kontrollen und vollständige EU-Compliance-Betriebsdokumentation.

---

## Zielarchitektur im Endstand

```text
Vertical / Branchen-Plugin
├── Domain Models + Services + Routes
├── Fach-UI / gebündelte React-Seiten
├── MiniApps für Workstreams/Mobile
├── Tools + Skills
├── Agent Definitions / Trigger
├── Workflows / Automation Templates
└── Search-/Knowledge-Contributions
                 │
                 ▼
┌──────────────────────────────────────────────────────────┐
│ LeoPlatform                                              │
├──────────────────────────────────────────────────────────┤
│ Human-AI Workstream                                      │
│ Communication · Groups · Rich Blocks · MiniApps · Mobile │
├──────────────────────────────────────────────────────────┤
│ Agents · Skills · Tools · Memory · Proactive/UI Context  │
├──────────────────────────────────────────────────────────┤
│ Workflows · Automation · Trigger · Approval · ARQ        │
├──────────────────────────────────────────────────────────┤
│ Unified Search · RAG · Graph · Firmenwissen              │
├──────────────────────────────────────────────────────────┤
│ Business Services · Permissions · Tenant · Audit · Files │
├──────────────────────────────────────────────────────────┤
│ Plugin Runtime / Manifest / Registries                   │
├──────────────────────────────────────────────────────────┤
│ Controlled Self-Improvement                              │
├──────────────────────────────────────────────────────────┤
│ Privacy / DSGVO / AI Compliance by Design                │
└──────────────────────────────────────────────────────────┘
```

**Architekturgrenze:** Plugins erweitern die Plattform fachlich. Workstream/MiniApps sind die gemeinsame Interaktionsschicht; sie ersetzen keine Domain-Services. Agenten/Skills/Workflows/MCP greifen immer über normale Services/Tools und deren aktuellen Auth-/Run-as-/Permission-Kontext zu. Privacy-/AI-Compliance nutzt dieselben vorhandenen Daten-, Provider-, Audit-, Approval- und Lifecycle-Grenzen; sie bildet **keine zweite Policy-/Runtime-Architektur**.

---

## Später — Advanced Autonomy/Automation nur bei echtem Bedarf

### Advanced Agent Runtime / Advanced Autonomy

Die Agent-Runtime soll später ohne Grundumbau auf höhere Autonomie ausgebaut werden können. Die heutige Basis aus Tools, Skills, Search/RAG/Graph, Memory, Triggern, Workflows, Permissions/Run-as, Approval, Audit und AgentRun bleibt dabei authoritative und wird erweitert, nicht ersetzt.

Geplante Erweiterungsfähigkeiten:

- **Goal-based Agents** — Agent erhält ein Ziel statt nur eines einzelnen Befehls; Zielzustand und Success Criteria werden explizit gespeichert
- **Task-based Execution** — Ziele können in Tasks/Subtasks zerlegt, priorisiert und nacheinander oder parallel abgearbeitet werden
- **Persistent Agent Jobs** — länger laufende Jobs mit Status wie `pending`, `running`, `waiting`, `blocked`, `approval_required`, `completed`, statt eines einzigen langen LLM-Calls
- **Loop bis Ziel erreicht** — planen → ausführen → Ergebnis prüfen → ggf. neu planen; Ende bei `done`, `blocked`, Approval, Budget-/Step-Limit oder Abbruch
- **Subagents / Delegation** — Parent-/Supervisor-Agent kann spezialisierte Child-Agenten für Teilaufgaben starten und deren Ergebnisse übernehmen
- **Agent-Hierarchien** — Supervisor → spezialisierte Agenten → optionale weitere Subagents; keine starre Organigramm-Architektur nötig
- **Agent-to-Agent Trigger/Delegation** — Agenten können andere Agenten direkt delegieren oder über relevante Events wie `agent.run_completed` / `agent.task_completed` anstoßen
- **Advisor Agents** — Berater-Agenten analysieren Search/RAG/Graph/Analytics und Systemdaten, erkennen Handlungsbedarf und veröffentlichen Evidence-basierte Empfehlungen/Handoffs im passenden gemeinsamen Workstream bzw. starten nach Policy einen Job
- **Job Agents** — Agenten können komplette fachliche Jobs übernehmen, auf externe Ereignisse/Approvals warten, später fortsetzen und mehrere Skills/Tools/Workflows koordinieren; `AgentJob` kann einem Workstream zugeordnet sein und dort sichtbare Handoffs/Status liefern
- **Evaluation & Replanning** — Ergebnisse gegen Success Criteria prüfen, Fehlschläge bewerten und gezielt neu planen

Vorgesehene Erweiterung der Runtime:

```text
AgentJob
├── goal
├── workstream_id (optional)
├── status
├── owner / run_as
├── parent_job_id / parent_agent_run_id
├── budget / limits
├── success_criteria
└── Tasks
    ├── pending
    ├── running
    ├── waiting
    ├── blocked
    └── completed
```

Berechtigungsregel bei Delegation:

```text
Effektive Child-Agent-Fähigkeiten
= Run-as/User-Permissions
∩ vom Parent delegierte Fähigkeiten
∩ Child-Agent-Freigaben
∩ Skill-Freigaben
∩ Tool-Freigaben
```

Ein Parent-/Supervisor-Agent darf einem Child-Agent keine Rechte verleihen, die im aktuellen Run-as-Kontext nicht vorhanden sind. Delegations-Tiefe, Budgets, Max-Runs und Loop-Limits verhindern unkontrollierte Agent-zu-Agent-Schleifen.

**Wichtig:** Diese Fähigkeiten werden jetzt noch nicht vorgebaut. Die aktuelle Agent-MVP-Architektur muss sie nur offenlassen. Später wird die bestehende Runtime um `AgentJob`, Task-Decomposition, Delegation/Subagents, Supervisor-Logik und Evaluation/Replanning erweitert — keine zweite Agent-Plattform. Auch Advanced AgentJobs/Subagents erben dieselbe AI-Use-Case-, Provider/Data-Policy-, Transparency-, Oversight- und Audit-Semantik; keine Sonder-Compliance-Engine für Advanced Agents.

### Advanced Automation Runtime

Die Workflow-/Automation-Runtime soll später ohne Grundumbau zu einer vollständigen langlebigen Business-Automation-Plattform ausgebaut werden können. Die heutige Basis aus gemeinsamem Trigger-Kern, persistentem `WorkflowRun`/ExecutionContext, resumable Wait, idempotency-sicheren Steps, Approval, ARQ, Outbox, Tools/Services und Agent-Integration bleibt authoritative und wird erweitert, nicht ersetzt.

Geplante Erweiterungsfähigkeiten:

- **Long-running Workflows** — Prozesse können Stunden, Tage oder Wochen laufen, ohne Worker dauerhaft zu blockieren
- **Wait for Event / Event Correlation** — Workflow wartet nicht nur auf Zeit, sondern auf ein fachlich passendes Ereignis (z. B. Antwort auf eine bestimmte Mail, Statusänderung eines bestimmten Auftrags) und setzt danach denselben Run fort
- **Branching / Switch** — mehrere fachliche Entscheidungspfade auf Basis von Daten, Expressions oder Agent-Ergebnissen
- **Loops / For-Each** — Listen/Entities kontrolliert iterieren, mit Limits und sauberem Fehlerverhalten
- **Parallel Branches / Join** — unabhängige Zweige parallel ausführen und anschließend auf definierte Ergebnisse warten
- **Subworkflows** — Workflow kann einen anderen Workflow als wiederverwendbaren Baustein starten und auf dessen Ergebnis warten
- **Reusable Workflows** — versionierte, parametrisierte Business-Abläufe als wiederverwendbare Module
- **Plugin-defined Steps & Trigger** — Plugins können über den bestehenden Registry-/Plugin-Mechanismus neue fachliche Steps und Trigger beitragen; keine zweite Workflow-Engine
- **Error Routes / Compensation** — definierte Fehlerpfade und gezielte fachliche Gegenaktionen dort, wo echte Rückabwicklung möglich/sinnvoll ist; kein universelles DB-Rollback über beliebige Systeme
- **Erweiterte Workflow-Versionierung** — laufende Runs bleiben an ihrer gestarteten Definition/Version gebunden; neue Runs verwenden die aktuelle Version
- **Agent ↔ Workflow Orchestration** — Workflows können Agenten einsetzen; Agenten können Workflows als deterministische Business-Prozesse starten und deren Status/Ergebnis verwenden
- **Workstream Correlation/Handoff** — Workstream-Aktionen/User-Reaktionen können wartende WorkflowRuns korreliert fortsetzen; Workflow-Ergebnisse/Handoffs erscheinen als typisierte Communication-Blocks, nicht in einem separaten Workflow-Chat

Zielbild:

```text
Trigger / Event / Cron / Webhook / Agent
                │
                ▼
          WorkflowRun
                │
      ┌─────────┼─────────┐
      │         │         │
  Condition   Agent     Action
      │         │         │
      └─────┬───┴─────────┘
            │
      Wait / Approval / Event
            │
      Run persistent pausiert
            │
      Resume über Trigger
            │
      weitere Steps / Subworkflow
            │
         completed
```

**Wichtig:** Diese erweiterten Fähigkeiten werden jetzt noch nicht vollständig vorgebaut. Phase G legt nur die dafür nötigen Runtime-Invarianten fest: persistenter/resumable `WorkflowRun`, persistenter ExecutionContext und idempotency-/retry-sichere Side-Effect-Ausführung. Später wird dieselbe Workflow-Engine erweitert — keine zweite Automatisierungsplattform.

### Weitere spätere Funktionen

- **Multi-Platform Messaging Gateway** — Plugin-basierte Anbindung an Telegram, Discord, Slack, WhatsApp etc. Eingehend: eigene Webhook-Route → CommMessage mit `participant_type='{platform}_gateway'`. Ausgehend: `comm.after_message` Hook → externe API. Keine Core-Änderung nötig. Rich Content Blocks werden als Text-Fallback + Action-Buttons gemappt
- **Matrix Chat Server Integration** — Synapse (Matrix Server) als eigener Docker-Container im Stack. LeoCRM Matrix-Bridge-Plugin verbindet sich als Matrix Application Service. Sync: CommConversation ↔ Matrix Room. Vorteile: native Mobile/Desktop-Clients (Element), Federation (externe Partner), E2EE, Multi-Platform Bridges (Telegram/Discord/Slack via Matrix Bridges), Push Notifications, Offline-Support. CommMessage bleibt authoritative, Matrix ist Gateway/Mirror. Keine Core-Änderung nötig
- Public Plugin Web Surface (Subdomains, Form Builder, Booking)
- React Flow Workflow Canvas (visueller Editor)
- Theme Editor mit Presets, Font Selector, Compact/Large
- Generic PST Import
- Allgemeines Plugin-Web-Hosting
- Universelle Export-Frameworks
- Code-Node / Raw-SQL-Node in Workflows
- Weitere Spezial-Abstraktionen

---

## Zusammenfassung

| Phase | Dauer | Hauptdeliverable |
|-------|-------|----------------|
| A — Stabilität | 1 Woche | Verifikation, Performance-Baseline |
| B — System-Konsolidierung | 6 Wochen | LLM, Redis, **pgvector HNSW**, Storage, **WebSocket+Redis Pub/Sub**, Event-/Trigger-Kern, Message-Konsolidierung, MiniApp-Wiring, Plugin-Contract |
| C — Core UI | 4 Wochen | vorhandene Navigation/Workspace/Settings/Agent-/Business-UI fertigstellen, PWA-Service-Worker |
| C.5 — Import/Export | 2 Wochen | vorhandenen Import/Export modularisieren, Mapping/Preview, Contact/Company Referenzhandler |
| D — Undo/Restore | 4 Wochen | vorhandene EntityHistory erweitern, Whitelist-Restore, Trash, Bulk-Restore, IMAP-sauberes Mail-Restore |
| E — Search | 6 Wochen | vorhandene Search-Basis → FTS+Vector+RAG+Graph, globale + spezifische Suche, Auto-Indexierung, AI/MCP/API |
| F — Agents | 6 Wochen | vorhandene Agent-Basis → ReAct, kleiner Skill-Kern, Tools+Skills, Permissions, Proactive/UI-Trigger, Workstream, Approval |
| G — Workflows | 6 Wochen | vorhandene Workflow/Automation-Basis → durable/resumable Runtime, Steps, Trigger, Idempotency, Workstream, Approval |
| H — Firmenwissen | 6 Wochen | Wiki + DMS + Mail + Communication + Businesswissen, RAG, Evidence, Graph-Extraktion, Ask Knowledge im Workstream |
| I — Integration & Human-AI Workstream | 6 Wochen | Agent↔Workflow↔Knowledge↔Communication, echte MiniApps, Shared/Proactive/Mobile Workstreams, Dashboard, MCP, Polish |
| J — Controlled Self-Improvement | 5 Wochen | Improvement Signals/Proposals, Evaluation/Dry-Run, Approval, Versionierung/Rollback, Wirkungsmessung |
| K — EU Compliance Finalization | 1 Woche | AI-Use-Case-Register, DPIA/AI-Impact-Support, Incident/Retention, Compliance-E2E, Betriebsdoku |
| **Total** | **52 Wochen** | **LeoPlatform Endstand-Kern inkl. Privacy/DSGVO/EU-AI-Act-by-Design** |

---

*Diese Roadmap basiert auf dem Endstand-Audit des aktuellen Code-Archivs und der gemeinsamen Detail-Review. Ziel bleibt: keine unnötigen Universalmodelle, keine Massenrefactorings und keine parallelen Mechanismen. Gemeinsame technische Kerne werden dort genutzt, wo Semantik wirklich gleich ist; fachliche Speziallogik bleibt erlaubt. Bestehender funktionierender Code wird respektiert. Die eingebauten Privacy-/AI-Compliance-Funktionen schaffen technische Voraussetzungen und Nachweise; die rechtliche Konformität eines konkreten Deployments/Branchenplugins hängt zusätzlich von dessen tatsächlichem Zweck, Datenverarbeitung, Betreiberrolle und organisatorischen Maßnahmen ab.*