Kairo-Jinkendo/docs/architecture/KAIRO-ARCH-01_Completion_Report_v0.1.md

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:

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:

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.