# 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**