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.
- 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.
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.
### Execution Principles (verbindlich für alle Phasen)
Diese 10 Prinzipien sind keine Tasks sondern **Arbeitsweise-Regeln** die für alle 12 Phasen gelten. Sie kosten keine zusätzliche Zeit sondern verändern wie gearbeitet wird.
1.**Spike First** — Riskante Phasen werden vorher mit einem 2-Tage-Spike validiert (siehe Spike-Tasks unten). Keine 6-Wochen-Phase ohne Proof-of-Concept.
2.**Test-First** — Jeder Task beginnt mit failing Tests, dann Code bis grün, dann Refactor. „Es compiliert" ist nicht „fertig".
3.**Phase-Gate-Disziplin** — Nach jeder Phase: AI-Review gegen 7 Kriterien. Bei ❌ → Bugfix-Sprint, keine neue Phase. Zeitbewusst: 2-3 Stunden Review, nicht 2 Tage.
4.**AI-Code-Review vor Merge** — Jeder Commit wird von AI reviewed bevor er gemerged wird: Forbidden Patterns, Permission-Bypass, Tenant-Isolation, Error-Handling, Test-Abdeckung.
5.**Task-Block-Deploy** — Pro Task-Block deployen (z.B. alle B-LLM Tasks zusammen = 1 Deploy), nicht pro Einzel-Task und nicht pro ganzer Phase. Mittelweg zwischen Micro-Deploy und 6-Wochen-Sammler.
6.**Architektur-Reviews** — Nach Phase B, F und I: AI-Architektur-Review. Dependency-Graph, Pattern-Check, Cross-Plugin-Imports, zirkuläre Abhängigkeiten. 2-3 Stunden pro Review.
7.**AI nach Stärken** — AI für repetitive Tasks (CRUD, Tests, Migrationen, Doku, Refactoring, Code-Review). Mensch für kritische Logik (ReAct-Loop, Workflow-Engine, Permission-Checks, Race-Conditions, Performance-Tuning, Security-Review).
8.**Fortlaufende Integration-Tests** — Nach jeder Phase: neue Features mit vorherigen Phasen zusammen testen. Nicht erst in Phase I alles kombinieren.
9.**Rollback-Lite** — Jeder Task hat Rollback-Plan (`git revert` + redeploy). Riskante Änderungen hinter Feature-Flag. Migrationen immer downgrade-fähig.
10.**Ehrliche Status-Reports** — „done" = bewiesen mit Test-Output, Build-Result, Health-Check. „Glaube ich" = `in_progress`, nicht `done`. PROGRESS.md bei jedem Status-Wechsel aktualisieren.
### Spike-Tasks (vor riskanten Phasen)
Vor den 4 Hochrisiko-Phasen (E, F, G, I) wird je ein 2-Tage-Spike durchgeführt. Spikes sind keine Tasks die in die Phase fallen — sie laufen **vor** der Phase und validieren das Kernrisiko.
| Spike | Vor Phase | Was wird validiert | Aufwand |
|-------|----------|-------------------|--------|
| SPIKE-E | Phase E | Minimaler FTS+Vector+Permission-Proof auf 10k Datensätzen. Funktioniert Permission-Filterung? Ist pgvector schnell genug? | 2 Tage |
| SPIKE-F | Phase F | Minimaler ReAct-Loop mit 3 Tools, 5 Steps, Permission-Check. Funktioniert Tool-Calling? Sind Responses brauchbar? | 2 Tage |
| SPIKE-G | Phase G | Minimaler durable WorkflowRun mit Wait+Resume+Idempotency. Überlebt er einen Worker-Restart? | 2 Tage |
| SPIKE-I | Phase I | Agent → Search → Knowledge → Workstream → Task → Approval in einem minimalen Flow. Funktionieren die Übergänge? | 2 Tage |
**Regel:** Spike scheitert → Risiko wird in der Phase adressiert oder Phase wird angepasst. Spike erfolgreich → Phase kann fokussiert umgesetzt werden.
### Phase-Gate-Reviews (zeitbewusst)
Nach jeder Phase führt AI ein Phase-Gate-Review durch. Dauer: 2-3 Stunden. Format: 7-Kriterien-Checkliste.
| 7. PROGRESS.md aktuell | Alle Task-Status eingetragen und verifiziert |
**Regel:** Bei ❌ bei einem Kriterium → Bugfix-Sprint bis ✅, keine neue Phase starten.
### Architektur-Reviews (nach B, F, I)
Nach den 3 wichtigsten Fundament-Phasen führt AI ein Architektur-Review durch. Dauer: 2-3 Stunden.
| Review | Nach Phase | Was wird geprüft |
|--------|-----------|----------------|
| ARCH-B | Phase B | LLM/Redis/Storage/WS/Error/Observability/Shutdown — funktioniert das Zusammenspiel? Gibt es zirkuläre Abhängigkeiten? |
| ARCH-F | Phase F | Agent+Tasks+Permissions+Approval+Workstream — gibt es Permission-Lücken? Ist das Task-Modell konsistent? |
| ARCH-I | Phase I | Alle Systeme verbunden — Search↔Agent↔Workflow↔Knowledge↔Workstream↔Tasks↔Approval — gibt es zirkuläre Abhängigkeiten oder inkonsistente Patterns? |
### Integration-Tests (fortlaufend)
Nach jeder Phase werden die neuen Features mit den vorherigen Phasen zusammen getestet. Nicht erst in Phase I alles kombinieren.
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.
| 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 |
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.
- 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.
| 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.
| 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 |
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.
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.
| 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-STOR-EXT | **External Storage Plugin System** — `StorageProvider` Interface für externe Storage-Quellen (WebDAV, Nextcloud, Google Drive, Dropbox). Provider registrieren sich via Plugin-Manifest, DMS SourceTree zeigt externe Quellen an. Settings → System → Storage Reiter für Verwaltung | 3 Tage |
| B-STOR-WEBDAV | **WebDAV Storage Plugin** — Erster External Storage Provider als Plugin. Verbindet WebDAV-Server (Nextcloud, ownCloud, radicale). Browse, Upload, Download, Delete. Credentials in Settings → System → Storage konfigurierbar | 2 Tage |
| 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 |
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
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-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 |
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.
| 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-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 |
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.
| 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 |
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`)
| 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 |
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 |
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-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 |
**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.
| 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-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 |
**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.
| 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 |
**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.
**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.
| 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 |
**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.
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.
| 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-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-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 |
**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.
| 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-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 |
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.
| 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. **Goal Decomposition**: Agent kann ein Goal erhalten und es in Milestones/Tasks/Subtasks zerlegen (`decompose_goal` Tool) | 2 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. Goals/Milestones erscheinen als `goal_card` Block mit Progress-Bar, Success-Criteria, Target-Date und Child-Task-Übersicht | 1.5 Tage |
| F-TASK-UI | **Task UI erweitern** — Task-Liste mit Filter (nach Assignee, Entity, Status, Due-Date, Task-Type), Task-Detail mit Subtasks/Dependencies, Task-Board (Kanban-View optional), Task-Assignment-Dropdown (User/Agent/Group). **Goal-Views**: Goal-Übersicht mit Progress-Bar, Goal-Detail mit Milestone/Task-Hierarchie-Baum, Success-Criteria-Checkliste | 2.5 Tage |
| F-TASK-GOAL | **Goal/Milestone Logik** — `progress`-Aggregation: Parent-Task/Goal/Milestone Progress wird aus Child-Task-Status berechnet (0-100%). `success_criteria`-Evaluation: strukturierte Kriterien die manuell oder per Agent/Workflow gecheckt werden können. Goal ist `done` wenn alle Success-Criteria erfüllt ODER alle Child-Tasks `done` sind (konfigurierbar). Milestone ist `done` wenn alle Child-Tasks `done`. Parent-Status-Propagation: wenn alle Child-Tasks `done` → Parent wird automatisch `review` (konfigurierbar) | 1.5 Tage |
**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**.
- **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-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 |
**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-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-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-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.
**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-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 |
**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.
| 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-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 |
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.
| 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 |
**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.
| 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.
**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.
| 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-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 |
**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
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.
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
**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.
- **AI Assistant API:** `/api/v1/ai/sessions`, `/api/v1/ai/sessions/:id/messages`, `/api/v1/ai/sessions/:id/stream` — eigene API
- **Kommunikation hat schon AI-Chat:** `comm_conversations` mit `conversation_type='ai'`, `streamChat()` aus `@/api/ai`, `categorizeConversation()` mit 'KI Chats' Kategorie, `new-ai-chat` Toolbar-Button
*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.*
**Ziel:** Zentrale Dokument-Generierung mit Briefpapier + dynamischen Blöcken, Drag/Drop-Editor, KI-Steuerung, E-Rechnung-Fähigkeit. Module registrieren ihre Blöcke als Contribution (Contract-Muster wie Import/Export).
