Lars
6dd9dd4f62
All checks were successful
Deploy Development / deploy (push) Successful in 44s
Test Suite / pytest-backend (push) Successful in 43s
Test Suite / lint-backend (push) Successful in 2s
Test Suite / compose-smoke (push) Has been skipped
Test Suite / k6 /api/health Baseline (push) Successful in 18s
Test Suite / playwright-smoke (push) Successful in 25s
167 lines
7.3 KiB
Markdown
167 lines
7.3 KiB
Markdown
# KAIRO-ARCH-01 – Abschlussbericht
|
||
|
||
**Status:** abgeschlossen
|
||
**Stand:** 2026-07-05
|
||
**Auftrag:** `docs/architecture/Kairo_Target_Architecture_Assignment_Method_Driven_Adaptive_Steering_Core_v0.2.md`
|
||
**Ergebnis:** Zielarchitektur v0.1 (Nordstern, keine Implementierung)
|
||
|
||
---
|
||
|
||
## 1. Erstellte Dateien
|
||
|
||
| Datei | Zweck |
|
||
|-------|-------|
|
||
| `docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md` | Technische Zielarchitektur (20 Kapitel) |
|
||
| `docs/architecture/KAIRO-ARCH-01_Completion_Report_v0.1.md` | Dieser Abschlussbericht |
|
||
|
||
**Gelesene Grundlagen (alle vorhanden):**
|
||
|
||
- `docs/architecture/Kairo_Core_Model_Decision_v0.2.md`
|
||
- `docs/architecture/Kairo_Method_Design_Principles_v0.1.md`
|
||
- `docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md`
|
||
- `docs/product/Kairo_Canonical_Operating_Model_v0.1.md`
|
||
- `docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md`
|
||
- `docs/architecture/Kairo_Tenant_Invariants_v0.1.md`
|
||
- `docs/sprints/Sprint0_AP0_7_Completion_Report_v0.2.md`
|
||
|
||
**Fehlende Dokumente:** keine — alle im Auftrag genannten Grundlagen waren im Repo vorhanden.
|
||
|
||
---
|
||
|
||
## 2. Wichtigste Architekturentscheidungen
|
||
|
||
| # | Entscheidung |
|
||
|---|--------------|
|
||
| 1 | **Kairo ist methodengeführter Steuerungskern**, keine freie Workflow Engine |
|
||
| 2 | **Drei Ebenen:** Steering Method → Steering Workflow (Lifecycle/Hooks) → Workflow Runtime (später) |
|
||
| 3 | **Method Registry** als zentraler Erweiterungspunkt — analog zu bestehendem Capability/Feature-Registry-Muster |
|
||
| 4 | **Hook Slugs** als stabile Einhängepunkte zwischen Core, Methoden und späteren Workflow-Fragmenten |
|
||
| 5 | **Standard Lifecycle** (12 Schritte) als gemeinsame Basis; Methoden aktivieren/spezialisieren |
|
||
| 6 | **Gemeinsame Kernstrukturen** — RoadmapItem als generisches Strukturelement (Milestone, Feature, Kapitel, Reifegradstufe) |
|
||
| 7 | **Attention/NextAction** als erklärbare Read Models im Data Layer; Signal Rule Providers methodenregistrierbar |
|
||
| 8 | **Kairo bleibt Steering Authority** — Agenten sind Actors/Provider, nicht eigenständige Steuerungsinstanzen |
|
||
| 9 | **Prompt/Workflow-Runtime bleibt eingefroren** bis Operating-Model-MVP (AP0.8–0.10) trägt |
|
||
| 10 | **Neue Schicht `backend/steering/`** — schrittweise nach AP0.8, ohne Foundation-Umbau |
|
||
|
||
---
|
||
|
||
## 3. Kritische Bewertung der fachlichen Annahmen
|
||
|
||
### 3.1 Bestätigt
|
||
|
||
Die fachliche Präferenz **„methodengeführter Steuerungskern statt freier Workflow-Baukasten“** ist aus Sicht der Codebase **tragfähig**:
|
||
|
||
- Registry-Muster (Capabilities, Features, Prompts) ist etabliert und erprobt
|
||
- Tenant/Actor/Capability-Foundation ist produktionsreif (AP0.7)
|
||
- Data Layer als Read-Schicht passt zur Attention-/Signal-Architektur
|
||
- Product Reset und Principle Gate verbieten vorzeitige Workflow/KI-Ausbauten — konsistent mit Zielarchitektur
|
||
|
||
### 3.2 Präzisiert
|
||
|
||
| Annahme | Bewertung |
|
||
|---------|-----------|
|
||
| Standard Lifecycle (12 Schritte) | Tragfähig als **generische Steuerungslogik**; UI muss fachliche Labels zeigen, nicht technische States |
|
||
| Hook Registry | Sinnvoll; Versionierung über `since_version` + Deprecation, nicht über Slug-Änderung |
|
||
| Structure Builder | Korrekt als methodenspezifische Erweiterung; **muss Domain Services nutzen**, nicht Router/SQL |
|
||
| Milestone als eigenes Objekt (AP0.8) | MVP-pragmatisch; Zielarchitektur empfiehlt **Konsolidierung zu RoadmapItem** in Phase C |
|
||
| Methoden sofort im MVP | **Nein** — erst Operating-Model-Entitäten, dann SteeringContext + erste Built-in Method |
|
||
|
||
### 3.3 Abweichung von Method Design Principles
|
||
|
||
Keine inhaltliche Abweichung. Technische Präzisierung: AP0.8 Attention startet als **globaler Rule Provider** in `data_layer/attention.py` und wird später in die Signal Engine refactored — bewusste Brücke, kein Widerspruch.
|
||
|
||
---
|
||
|
||
## 4. Empfohlene Zielarchitektur
|
||
|
||
**Kurzfassung:**
|
||
|
||
```text
|
||
Foundation (bestehend)
|
||
+ Domain Operating Model (AP0.8 → AP0.9)
|
||
+ Steering Core (Method/Hooks/Lifecycle/Signals)
|
||
+ Method Packages (Built-in)
|
||
+ später: Workflow Fragments + Runtime + Agent/LLM Nodes
|
||
```
|
||
|
||
**Kernmodell:**
|
||
|
||
```text
|
||
Initiative
|
||
→ SteeringContext (method_key, version, lifecycle_state)
|
||
→ Method Registry → Structure Builders + Strategies + Signal Rules
|
||
→ gemeinsame Strukturen (Roadmap, Backlog, Action, Blocker, Evidence, Review, …)
|
||
→ Attention / NextAction (Read Models)
|
||
→ Assignment → Waiting → Result Intake → Review → Adaptation
|
||
```
|
||
|
||
Das vollständige Dokument: `Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md`.
|
||
|
||
---
|
||
|
||
## 5. Was gegenüber der bisherigen Architektur geändert werden sollte
|
||
|
||
| Bereich | Bisher | Soll (Ziel) |
|
||
|---------|--------|-------------|
|
||
| Produktkern | Initiative → Action (flach) | Methodengeführter SteeringContext + Operating Model |
|
||
| Steuerungslogik | verstreut in Services/Data Layer | `backend/steering/` mit Registry, Lifecycle, Hooks, Signals |
|
||
| Blocker | nur Action-Status | eigenes Objekt (AP0.8) |
|
||
| Struktur | keine Roadmap/Backlog/Milestone | Operating Model + RoadmapItem-Generik |
|
||
| Attention | fehlt | Data Layer + später Signal Engine |
|
||
| Methoden | nicht modelliert | Method Registry + Built-in Methods |
|
||
| Workflow/Prompt | technisch vorhanden, eingefroren | später hook-gebundene Fragmente, nicht Produktkern |
|
||
| Milestone (AP0.8) | — | eigene Tabelle als Brücke → RoadmapItem konsolidieren |
|
||
|
||
**Was bleibt unverändert:**
|
||
|
||
- TenantContext, Actor-Modell, Capabilities, Audit-Grundlage
|
||
- Router dünn / Services Write / Data Layer Read
|
||
- Frontend Widget/View Registry
|
||
- Nummerierte Migrationen, Registry-first Capabilities
|
||
|
||
---
|
||
|
||
## 6. Risiken
|
||
|
||
| Risiko | Schwere | Hinweis |
|
||
|--------|---------|---------|
|
||
| Vorzeitige Workflow-Runtime | hoch | Operating Model MVP zuerst |
|
||
| Over-Engineering Steering-Schicht | mittel | Skeleton erst nach AP0.8 |
|
||
| Doppelmodell Milestone/RoadmapItem | mittel | ADP vor Konsolidierung |
|
||
| Lifecycle zu abstrakt für Nutzer | mittel | Fachliche UI-Labels |
|
||
| Methoden-Explosion | mittel | Built-in only, Review-Gate |
|
||
| Agenten ohne klare Authority-Grenze | hoch | Canonical Model §11 durchsetzen |
|
||
|
||
---
|
||
|
||
## 7. Offene Entscheidungen
|
||
|
||
1. **SteeringContext-Einführung** — mit AP0.9 oder als AP1.0?
|
||
2. **Milestone → RoadmapItem Migration** — Zeitpunkt und Strategie
|
||
3. **Generisches Assignment** — über Actions hinaus, wann?
|
||
4. **Scheduler für Waiting/Reminder** — Infrastruktur-Wahl
|
||
5. **Audit `actor_id`-Spalte** — Nachzug vor Agent-Integration
|
||
6. **Erste Built-in Method** — `generic_operating` vs. direkt `product_milestone_driven`?
|
||
|
||
Diese Punkte sollten als Architecture Decision Proposals vor der Steering-Core-Implementierung geklärt werden.
|
||
|
||
---
|
||
|
||
## 8. Empfehlung für den nächsten Schritt
|
||
|
||
**Nicht** sofort `backend/steering/` implementieren.
|
||
|
||
**Empfohlene Reihenfolge:**
|
||
|
||
1. **AP0.8 freigeben und umsetzen** (`Sprint0_AP0_8_Assignment_v0.1.md`) — Attention, Blocker, BacklogItem, Milestone
|
||
2. **AP0.9** — Evidence, Decision, Review, RecurringElement
|
||
3. **AP0.10** — Validierung mit realem Testvorhaben
|
||
4. **ADP:** SteeringContext-Einführung + Milestone/RoadmapItem-Strategie
|
||
5. **Danach:** `backend/steering/` Skeleton + erste Built-in Method
|
||
|
||
Die Zielarchitektur dient als **Nordstern** für AP0.8–AP0.10 und verhindert Rückfall auf reines Initiative→Action sowie vorzeitige Workflow-Engine-Arbeit.
|
||
|
||
---
|
||
|
||
*KAIRO-ARCH-01 abgeschlossen — reine Architekturarbeit, keine Code-Änderungen.*
|