AP1.0: Steering Foundation — Lifecycle, Context, Signal Engine
Deploy Development / deploy (push) Successful in 44s
Test Suite / pytest-backend (push) Successful in 1m19s
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 11s

Persistierter Standard Lifecycle pro Initiative, backend/steering/ Skeleton, Attention-Refactor und Hook-Dispatch als Basis für Method Registry.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-07-05 17:09:20 +02:00
1 parent 451d62ed46
commit 95feba6204
36 files changed
+2006 -724

No files matched your search

@@ -0,0 +1,240 @@
# Architecture Decision Proposal — AP1.0 Steering Foundation & Scope Lock
**Status:** angenommen (Umsetzung ausstehend)
**Stand:** 2026-07-05
**Autor:** Product/Architektur-Review (Cursor-Session)
**Auslöser:** AP0.8–0.10b liefern OM-Inventar + provisorische Steuerungsfragmente ohne `backend/steering/` — Architektur-Kohärenz und MVP-Nachweis fehlen.
---
## Problem
Kairo hat drei parallele Steuerungsfragmente ohne gemeinsamen Kern:
| Fragment | Ort | Rolle |
|----------|-----|--------|
| Attention / NextAction | `data_layer/attention.py` | Regelbasierte Signale |
| Transitions | `services/operating_transitions.py` | Blocker/Review Side Effects |
| Operating Phase | `initiative_snapshot._derive_operating_phase` | UI-Heuristik (nicht persistiert) |
Das **Zielmodell** (Standard Lifecycle, Method Registry, Hook Registry, SteeringContext) ist in Target Architecture und Universal Steering Engine **entschieden**, aber **nicht implementiert** (`backend/steering/` = 0 Dateien).
Gleichzeitig wurde der dokumentierte Pfad „Inventar → Validation → Steering Core“ **gebrochen**:
- AP0.10a/b lieferten Integration/UI statt Validation
- Offene Entscheidungen (Universal Steering §33: `steering_contexts`, `roadmap_item_id`) blieben ungeklärt
- `milestones`-Tabelle als MVP-Brücke ohne Roadmap-Konsolidierungs-ADP
**Leitfrage:** Bauen wir weiter provisorische Enden, die später teuer refactored werden müssen — oder wechseln wir zu **Foundation-first** mit schmalem Steering-Skeleton?
---
## Betroffene Regel
| Dokument | Regel |
|----------|--------|
| `Kairo_Product_Definition_and_MVP_Reset_v0.1.md` §4 | Kairo ≠ `Initiative → Action` |
| `Kairo_Canonical_Operating_Model_v0.1.md` §8 | Data Layer Read; Services Write |
| `Kairo_Target_Architecture_…_v0.1.md` §7 | Standard Lifecycle als gemeinsame Basis |
| `Kairo_Universal_Steering_Engine_Decision_v0.1.md` §32 | AP0.8 max. Ebene 1; spätere Fähigkeit nicht verbauen |
| `Kairo_Operating_Model_Steering_Bridge_v0.1.md` §6 | Evolutionspfad AP1.0 → AP1.3 |
| `Kairo_Sprint0_Principle_Gate_v0.1.md` G-01 | Verhindert teures Refactoring? |
| `Kairo_MVP_Usability_Recovery_Plan_v0.1.md` §3 | Roadmap-Korrektur (wird durch dieses ADP ersetzt) |
---
## Optionen
| Option | Kurzbeschreibung | Pro | Contra |
|--------|------------------|-----|--------|
| A | **Weiter wie bisher** — AP0.10c UI, mehr Heuristiken, AP1.0 „irgendwann“ | Kurzfristig sichtbar | Mehr lose Enden; Doppel-Wahrheit Phase/Lifecycle; teurer Refactor |
| B | **Strategiewechsel:** Scope Lock + AP1.0 Skeleton + Konsolidierung | Passt zu Zielarchitektur; eine Steuerungswahrheit | Kurz weniger neue UI-Features |
| C | **Big Bang** — vollständiger Steering Core + Method Registry sofort | Architektonisch „fertig“ | Over-Engineering; ohne Validation falsche Methoden |
---
## Empfehlung
**Option B — angenommen.**
Begründung:
1. OM-Tabellen (AP0.8/0.9) sind **Andockdaten**, kein Wegwerf-Inventar.
2. Was teuer wird, ist **verteilte Steuerungslogik** — nicht die Entitäten.
3. Ein **schmaler AP1.0-Skeleton** (persistierter Lifecycle, Registry-Gerüst, Signal-Engine-Interface) ist die fehlende Foundation, auf die Methoden und Features einrasten.
4. Validation (AP0.10d) **informiert** AP1.1 (erste Built-in-Methode), blockiert AP1.0 nicht.
---
## Scope Lock — ab sofort verbindlich
### Eingefroren (kein neues Code ohne ADP-Ausnahme)
| # | Verbot | Begründung |
|---|--------|------------|
| L1 | Neue Steuerungs-Heuristiken in `initiative_snapshot`, Routern, Frontend | Ersetzt durch `lifecycle_state` ab AP1.0 |
| L2 | Duplizierte NextAction-/Attention-Regeln (neue SQL-Varianten) | Konsolidierung in `steering/signals/` |
| L3 | **AP0.10c** Initiative Flow UI (Maßnahmen-Hub, Sektionen) | Erst nach AP1.0a — UI soll `lifecycle_state` lesen, nicht dritte Phase-Logik |
| L4 | Neue OM-Tabellen | Regel aus Recovery Plan bleibt |
| L5 | Workflow Runtime, Method Designer, KI/MCP | Product Direction |
| L6 | `operating_phase` als zweite Wahrheit ausbauen | Nur Anzeige-Proxy bis AP1.2; dann aus `SteeringContext` |
### Erlaubt ohne ADP
| # | Erlaubt |
|---|---------|
| E1 | Bugfixes, Tenant-Invarianten, Tests |
| E2 | AP0.10d Validation (Dokument + Checkliste, kein neues Steuerungs-SQL) |
| E3 | AP1.0 Implementierung gemäß Assignment |
| E4 | Refactor bestehender Regeln **in** `backend/steering/` (keine neuen Regeln) |
| E5 | UI-Labels, die `lifecycle_state` / Hook-Signale **anzeigen** (nach AP1.0) |
---
## AP1.0 — Minimaler Steering-Skeleton (nächstes Code-Paket)
**Ziel:** Eine persistierte Steuerungswahrheit pro Initiative — Methoden können später einhängen.
**Nicht-Ziel:** Workflow Runtime, Agenten, Method Designer, Roadmap-Konsolidierung, volle Method Packages.
### A) Schema (Migration 009)
```text
steering_contexts (
id, tenant_id, initiative_id UNIQUE,
method_key DEFAULT 'generic_operating',
method_version DEFAULT '0.1.0',
lifecycle_state NOT NULL, -- Standard Lifecycle Slug
lifecycle_metadata JSONB DEFAULT '{}',
created_at, updated_at
)
```
**Initial `lifecycle_state`:** bestehende Initiativen → `action_selection` wenn offene Actions, sonst `structure_setup` (Seed/Backfill-Logik im Assignment).
**Entscheidung Milestone-Brücke:** `milestones`-Tabelle **bleibt** bis AP1.2/ADP-TA-08 — keine Migration 009 zu `roadmap_items`.
### B) Backend-Modul `backend/steering/`
```text
steering/
__init__.py
lifecycle/
states.py # STANDARD_LIFECYCLE_STEPS (12 Slugs)
orchestrator.py # get_state, transition (minimal, Guards stub)
hooks/
registry.py # HookDefinition + register_hook (Slugs aus Target Arch §7.3)
dispatch.py # dispatch_hook(slug, ctx, payload) — no-op + audit stub
methods/
registry.py # MethodDefinition + register_method
registrations/
generic_operating.py # einzige Built-in-Methode AP1.0
signals/
engine.py # evaluate(ctx, scope) → ruft Provider auf
default_rules.py # Move/wrap aus attention.py (keine neuen Regeln)
context.py # get_or_create_steering_context, resolve_for_initiative
```
### C) Services-Integration (minimal)
| Heute | AP1.0 |
|-------|-------|
| `operating_transitions.after_blocker_*` | ruft `dispatch_hook('on_blocker_resolved', …)` + Lifecycle-Transition wenn Guard passt |
| `operating_transitions.after_review_*` | `on_review_completed` |
| `initiative_snapshot.operating_phase` | **Deprecated-Feld**; parallel `lifecycle_state` + `lifecycle_label` aus Context |
| `data_layer/attention.py` | Delegiert an `signals/engine.py` (Wrapper, Datei bleibt für API-Kompatibilität) |
### D) API (minimal)
| Endpoint | Beschreibung |
|----------|--------------|
| `GET /api/initiatives/{id}/steering-context` | Context + lifecycle_state + method_key |
| Erweiterung `steering-snapshot` | Felder `lifecycle_state`, `lifecycle_label`; `operating_phase` als deprecated alias |
### E) Frontend (minimal)
- Steuerungszustand-Panel: **Lifecycle-Label** aus API (fachliches Label via `operating.js` Mapping auf Standard Lifecycle)
- Kein AP0.10c Maßnahmen-Hub
### F) Tests
- SteeringContext tenant-scoped, Cross-Tenant 404
- Lifecycle-Transition bei Blocker resolved (bestehendes Verhalten, neuer Pfad)
- Signal Engine liefert gleiche Attention-Count wie vor Refactor (Regression)
### G) Version
- `0.11.0-ap1.0` · Schema `009`
---
## Konsolidierungs-Roadmap nach AP1.0
```text
AP1.0 Steering Foundation (dieses ADP) ← JETZT
AP0.10d MVP Validation (5 Vorhaben) ← parallel / unmittelbar danach
AP1.1 Method Registry + 2. Built-in-Methode (product_milestone_driven)
AP1.2 attention.py vollständig → signals/; operating_phase entfernen
AP1.3 operating_transitions → Hook Orchestrator
AP1.4 Milestone → RoadmapItem (ADP-TA-08) — nur mit separater ADP
AP0.10c Initiative Flow UI ← nach AP1.2
```
---
## Was bleibt / was wird refactored / was nicht weggeworfen
| Kategorie | Inhalt |
|-----------|--------|
| **Bleibt** | OM-Tabellen, Tenant/Actor/Capabilities, Data Layer Pattern, Backlog→Action, CRUD Services |
| **Refactor** | `attention.py`, `operating_transitions.py`, Snapshot-Phase |
| **Deprecated dann entfernen** | `operating_phase` Heuristik (AP1.2) |
| **Spätere ADP** | `milestones` → `roadmap_items`, Project-Entität, generisches Assignment |
---
## Risiko
| Risiko | Schwere | Mitigation |
|--------|---------|------------|
| AP1.0 verzögert Nutzer-UI | mittel | AP0.10b bleibt; Validation dokumentiert Lücken |
| Refactor bricht Attention-Tests | mittel | Regression-Suite vor Move |
| Lifecycle zu abstrakt | mittel | Fachliche Labels in UI; `generic_operating` Method |
| Doppelmodell Phase + Lifecycle kurz | niedrig | `operating_phase` deprecated; ADP L6 |
| Over-Engineering AP1.0 | mittel | Assignment definiert harte Nicht-Ziele |
---
## Rückbaubarkeit
- Migration 009 additiv; `steering_contexts` droppbar ohne OM-Tabellen zu berühren
- Wrapper in `attention.py` kann wieder direkt SQL ausführen
- `operating_transitions` bleibt bis AP1.3 als Fallback aufrufbar
- Method Registry mit einem Eintrag — Erweiterung ohne Schema-Change
---
## Auswirkung auf Sprint 0 / Sprint 1
| Thema | Auswirkung |
|-------|------------|
| AP0.8–0.9 | **Gültig** — System of Record |
| AP0.10a/b | **Gültig** — Integration/UI; keine weiteren Ausbauten |
| AP0.10c | **Eingefroren** bis AP1.2 |
| AP0.10d | **Freigegeben** — Validation Report als Gate für AP1.1 |
| Sprint 1 Start | AP1.0 = offizieller Sprint-1-Einstieg (Steering Foundation) |
| Foundation AP0.1–0.7 | Unverändert gültig |
---
## Nächste Schritte
1. ~~ADP (dieses Dokument)~~ — angenommen
2. `docs/sprints/Sprint1_AP1_0_Steering_Foundation_Assignment_v0.1.md` — Implementierungsauftrag
3. `Kairo_MVP_Usability_Recovery_Plan_v0.1.md` §3 — Roadmap an ADP anbinden
4. Umsetzung AP1.0 auf Branch `develop`
5. AP0.10d Validation Report vor AP1.1
---
*Referenz: KAIRO-ARCH-01, Operating Model Steering Bridge, Universal Steering Engine Decision §31–32*