leocrm/docs/arch-f-review.md

ARCH-F Review — Architecture Review nach Phase F

Datum: 2026-08-18 Reviewer: AI Agent Phase: F — Agents (41/41 Tasks done)

---

Review-Kriterien

1. Permission-Lücken ✅

Permission Intersection (User ∩ Agent ∩ Skill ∩ Tool):

• agent_permissions.py: resolve_agent_permissions() korrekt implementiert
• agent_tools.py: get_agent_tools() filtert Tools nach User-Permissions
• Skills orchestrieren Tools aber erweitern niemals Permissions
• System Admins bekommen alle Tools (korrekt)
• check_agent_execute_permission() prüft RBAC + Entity-Level Access
• filter_visible_agents() prüft agents:read + EntityPermission
• Jeder Tool/Service Call re-checkt Permissions (nicht eingefroren)

Fazit: Keine Permission-Lücken gefunden. Die Intersection-Logik ist solide.

2. Task-Modell-Konsistenz ✅

• TASK_TYPES pattern: ^(todo|approval|follow_up|review|goal|milestone|agent_subtask)$ — konsistent in Schema und Model
• Polymorphic Fields: assignee_type/assignee_id, entity_type/entity_id, creator_type/creator_id — korrekt
• contact_id wird aus entity_id abgeleitet (nicht in FK-Spalte gespeichert) — vermeidet FK-Constraint-Probleme
• Subtasks: parent_task_id self-reference korrekt
• Dependencies: depends_on JSONB array korrekt
• Progress Aggregation: _recompute_progress() + _propagate_parent_status() korrekt
• Success Criteria: _evaluate_success_criteria() mit all_done und criteria shapes
• tenant_id auf allen Queries und Operations

Fazit: Task-Modell ist konsistent. Keine Inkonsistenzen gefunden.

3. Approval-Integration ⚠️

Approval API: Vollständig implementiert (create, list, get, approve, reject, expire) Approval Model: ApprovalRequest mit tenant_id, entity_type, entity_id, action, status Workstream: post_approval_request() korrekt implementiert

⚠️ Finding: Agent Loop hat keine Human-in-the-Loop Approval-Integration

• run_react_loop() hat keinen require_approval oder human_in_loop Parameter
• Agent kann aktuell keine Approval-Requests während eines Loops pausieren/warten
• Approval API existiert aber ist nicht in den Agent Loop integriert
• Empfehlung: In Phase G oder I integrieren — require_approval Parameter in run_react_loop(), der den Loop pausiert und eine Approval-Request erstellt

4. Workstream-Konsistenz ✅

• post_agent_message(): Erstellt CommMessage in Agent-Channel
• post_agent_step(): Postet Thought/Action/Observation als CommBlock
• post_agent_result(): Postet finales Ergebnis
• post_approval_request(): Postet Approval-Request in Channel
• Alle Funktionen verwenden tenant_id und agent_id konsistent
• _get_or_create_agent_channel() für dedizierte Agent-Channels

Fazit: Workstream-Patterns sind konsistent.

5. Zirkuläre Abhängigkeiten ✅

Import-Test erfolgreich:

from app.ai.agent_loop import run_react_loop
from app.ai.agent_permissions import resolve_agent_permissions
from app.ai.agent_workstream import post_agent_message
from app.ai.data_policy import enforce_data_policy
from app.ai.oversight import create_decision_record
from app.core.approval import create_approval_request
→ No circular imports

Fazit: Keine zirkulären Abhängigkeiten.

6. Data Policy ✅

• enforce_data_policy() prüft SENSITIVE_FIELDS vor LLM-Calls
• Provider Compliance: _filter_by_provider_compliance() filtert Felder nach Provider-Datenklassen
• get_provider_compliance() lädt Provider-Konfiguration aus DB
• Tenant-spezifische Provider-Konfiguration

Fazit: Data Policy korrekt implementiert.

7. Transparency ✅

• mark_as_ai_generated(): Fügt ai_generated flag + ai_metadata (model, provider, timestamp) hinzu
• is_ai_participant(): Erkennt AI-Participant-Types (agent, ai, system_ai)
• Wird von Kommunikation-Plugin und Agent Loop verwendet

Fazit: Transparency-Layer korrekt implementiert.

8. Oversight ✅

• DecisionRecord + DecisionRecordDB: Audit-Trail für AI-Entscheidungen
• create_decision_record(): Erstellt Decision Record mit tenant_id, agent_id, tool_name, decision
• DecisionRecordDB erbt von Base, TenantMixin, OwnedMixin

Fazit: Oversight korrekt implementiert.

9. Agent Memory ✅

• store_agent_memory(), retrieve_agent_memory(), search_agent_memory()
• Alle Operationen verwenden tenant_id
• Embedding-basierte Suche korrekt

Fazit: Agent Memory korrekt implementiert.

10. Migrations ✅

• 0122: Agent Definition Phase F Fields (temperature, max_tokens, max_steps, trace_mode, skill_ids, trigger_config, ai_use_case_metadata)
• 0123: approval_requests + ai_decision_records Tabellen (tenant_id, UUID PKs, Indizes)
• 0124: Unified Task System (polymorphic fields, subtasks, dependencies)
• Alle Migrations korrekt verkettet (0122 → 0123 → 0124)
• tenant_id auf allen neuen Tabellen/Spalten
• UUID Primary Keys (keine Integer IDs)

Fazit: Migrations korrekt und konsistent.

---

Zusammenfassung

Kriterium	Status	Findings
Permission-Lücken	✅	Keine — Intersection-Logik solide
Task-Modell-Konsistenz	✅	Konsistent — polymorphic fields korrekt
Approval-Integration	⚠️	Agent Loop hat keine Human-in-the-Loop Integration
Workstream-Konsistenz	✅	Konsistente Patterns
Zirkuläre Abhängigkeiten	✅	Keine
Data Policy	✅	SENSITIVE_FIELDS + Provider Compliance
Transparency	✅	AI-Generated Marking korrekt
Oversight	✅	Decision Records mit Audit-Trail
Agent Memory	✅	tenant_id auf allen Operationen
Migrations	✅	Korrekt verkettet, tenant_id, UUID PKs

Findings

⚠️ ARCH-F-1: Agent Loop fehlt Human-in-the-Loop Approval-Integration

Schwere: Medium (Design-Gap, kein Bug) Beschreibung: run_react_loop() hat keinen require_approval Parameter. Approval API existiert aber ist nicht in den Agent Loop integriert. Empfehlung: In Phase G oder I integrieren — require_approval Parameter in run_react_loop(), der den Loop pausiert und eine Approval-Request erstellt.

ℹ️ ARCH-F-2: contact_id FK redundant mit entity_id

Schwere: Low (bereits im Code behoben) Beschreibung: Task Model hat sowohl contact_id (FK zu contacts) als auch entity_type/entity_id (polymorphic). Code leitet contact_id aus entity_id ab, aber die FK-Spalte existiert noch in der DB. Empfehlung: In einer zukünftigen Migration die contact_id FK-Constraint droppen und die Spalte als nullable belassen (oder entfernen).

Fazit

ARCH-F Review: ✅ BESTANDEN

Phase F Architektur ist solide. Keine Permission-Lücken, keine zirkulären Abhängigkeiten, konsistente Patterns. Ein Design-Gap (Agent Loop Approval-Integration) wurde identifiziert und für Phase G/I empfohlen.

Freigabe für Phase G: ✅ erteilt