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*
@@ -43,25 +43,23 @@ Das ist **nicht** Feature-Parität mit Todoist — sondern **Steuerungsmehrwert*
## 3. Strategische Korrektur der Roadmap
Die bisherige Reihenfolge:
**Stand 2026-07-05 (Strategiewechsel):** Siehe `docs/architecture/ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md`
Die Reihenfolge „Inventar → mehr UI → irgendwann Core“ hat **lose Steuerungsfragmente** erzeugt ohne `backend/steering/`. **Neue Leitlinie: Foundation-first.**
```text
AP0.8 Entitäten → AP0.9 Entitäten → AP0.10 Validation → Sprint 1 Steering Core
AP0.10b Steering UI Minimum ✓ erledigt
Scope Lock aktiv ← keine neuen Heuristiken / kein AP0.10c
AP1.0 Steering Foundation Skeleton ← NÄCHSTES Code-Paket
AP0.10d MVP Validation (5 Vorhaben) ← parallel / unmittelbar nach AP1.0
AP1.1 Method Registry + 2. Methode
AP1.2 Signals konsolidieren; operating_phase entfernen
AP1.3 operating_transitions → Hook Orchestrator
AP0.10c Initiative Flow UI ← erst nach AP1.2 (lifecycle-aware)
AP1.4 Milestone → RoadmapItem ← separate ADP
```
**Problem:** Validation auf CRUD-Listen liefert nur „fehlt alles“ — ohne vorherige **Steering Surface**.
**Korrigierte Reihenfolge:**
```text
AP0.10b Steering UI Minimum ← zuerst (Nutzen sichtbar)
AP0.10c Initiative Flow Minimum
AP0.10d MVP Validation (5 Vorhaben)
AP1.0 Steering Core Foundation (nur mit Validation-Ergebnis)
AP1.1 Method Registry minimal
```
**Regel bis AP1.0:** Keine neuen OM-Tabellen. Nur verbinden, anzeigen, orchestrieren, validieren.
**Regel bis AP1.2:** Keine neuen OM-Tabellen. Keine parallele Steuerungslogik außerhalb `backend/steering/`.
---
@@ -82,9 +80,12 @@ AP1.1 Method Registry minimal
---
### AP0.10c — Initiative Flow Minimum (Priorität 2)
### AP0.10c — Initiative Flow Minimum — **EINGEFROREN**
**Ziel:** Vorhaben-Detail beantwortet „Wo stehe ich?“ — nicht „Hier sind 8 Listen“.
**Status:** eingefroren bis AP1.2 (ADP AP1.0 Scope Lock).
**Grund:** UI ohne Lifecycle-Foundation würde dritte Steuerungswahrheit erzeugen.
**Ziel (später):** Vorhaben-Detail beantwortet „Wo stehe ich?“ — nicht „Hier sind 8 Listen“.
| # | Lieferung | Aufwand | Nutzen |
|---|-----------|---------|--------|
@@ -0,0 +1,224 @@
# AP1.0 — Steering Foundation (Skeleton)
## Implementierungsauftrag v0.1
**Status:** umgesetzt
**Stand:** 2026-07-05
**Vorgänger:** AP0.10b ✓
**ADP:** `docs/architecture/ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md`
**Zielversion:** `0.11.0-ap1.0` · Schema `009`
---
## Ziel
**Eine persistierte Steuerungswahrheit pro Initiative** — Standard Lifecycle als Foundation, in die Methoden später einhängen.
Leitfrage bleibt: *Welcher nächste Schritt bringt ein Vorhaben am wirkungsvollsten voran?* — technisch beantwortet über `SteeringContext.lifecycle_state` + Signal Engine, nicht über verstreute Heuristiken.
---
## Scope Lock (verbindlich)
Siehe ADP § Scope Lock. **Kein AP0.10c.** Keine neuen Attention-Regeln. Keine neuen OM-Tabellen außer `steering_contexts`.
---
## Teil A — Schema 009
### Tabelle `steering_contexts`
```sql
CREATE TABLE steering_contexts (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
initiative_id UUID NOT NULL REFERENCES initiatives(id) ON DELETE CASCADE,
method_key VARCHAR(64) NOT NULL DEFAULT 'generic_operating',
method_version VARCHAR(32) NOT NULL DEFAULT '0.1.0',
lifecycle_state VARCHAR(64) NOT NULL DEFAULT 'intake',
lifecycle_metadata JSONB NOT NULL DEFAULT '{}',
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
UNIQUE (tenant_id, initiative_id)
);
CREATE INDEX idx_steering_contexts_tenant ON steering_contexts(tenant_id);
```
### Backfill (Seed oder Migration-Block)
Bestehende Initiativen erhalten Context:
| Bedingung | `lifecycle_state` |
|-----------|-------------------|
| `status IN (completed, archived)` | `closure` |
| offene Actions existieren | `action_selection` |
| nur Backlog (new/triaged/accepted), keine offenen Actions | `structure_setup` |
| sonst active/paused | `planning` |
---
## Teil B — `backend/steering/`
### B1 — Lifecycle
**Datei:** `steering/lifecycle/states.py`
```python
STANDARD_LIFECYCLE_STEPS = (
"intake", "method_selection", "structure_setup", "planning",
"action_selection", "assignment", "waiting", "result_intake",
"validation", "review", "adaptation", "closure",
)
```
**Datei:** `steering/lifecycle/orchestrator.py`
- `get_lifecycle_state(ctx, initiative_id) -> str`
- `transition(ctx, initiative_id, to_state, *, reason: str) -> dict` — Guard minimal: nur erlaubte Übergänge aus `generic_operating` oder freier Übergang für AP1.0 stub
- Audit-Log bei Transition
### B2 — Hook Registry
**Datei:** `steering/hooks/registry.py`
- `HookDefinition` dataclass (slug, lifecycle_step, description, since_version)
- `register_hook()`, `get_hook()`, `list_hooks()`
- Registrierung der Slugs aus Target Architecture §7.3 (Definition only, Implementierung stub)
**Datei:** `steering/hooks/dispatch.py`
- `dispatch_hook(slug, ctx, payload) -> list[dict]` — ruft registrierte Handler; AP1.0: leere Handler + Audit-Eintrag
### B3 — Method Registry
**Datei:** `steering/methods/registry.py` + `registrations/generic_operating.py`
- Eine Built-in-Methode: `generic_operating`
- Liefert: `default_lifecycle_steps`, erlaubte Hooks (alle globalen), keine Structure Builder
### B4 — Signal Engine
**Datei:** `steering/signals/default_rules.py`
- Bestehende Regeln aus `data_layer/attention.py` **verschieben** (nicht duplizieren)
- `evaluate_attention(ctx) -> list[dict]`
- `evaluate_next_actions(ctx, *, limit, initiative_id=None) -> list[dict]`
**Datei:** `steering/signals/engine.py`
- `evaluate(ctx, kind='attention'|'next_action', **kwargs)` — delegiert an default_rules
**Datei:** `data_layer/attention.py`
- Wird dünner Wrapper um `steering.signals.engine` (API-Kompatibilität)
### B5 — Steering Context Service
**Datei:** `steering/context.py` + `services/steering_context.py` (Write)
- `get_or_create_for_initiative(ctx, initiative_id)`
- `get_steering_context(ctx, initiative_id) -> Optional[dict]`
- Tenant-scoped; Cross-Tenant → None / 404
---
## Teil C — Integration bestehender Flows
### C1 — `operating_transitions.py`
Vor/nach bestehender Logik:
```python
from steering.hooks.dispatch import dispatch_hook
dispatch_hook("on_blocker_resolved", ctx, {...})
# optional: lifecycle transition assignment → action_selection
```
Verhalten Blocker→entblocken **unverändert** (Regression-Tests).
### C2 — `initiative_snapshot.py`
Snapshot ergänzt:
```json
{
"lifecycle_state": "action_selection",
"lifecycle_label": "Maßnahmen auswählen",
"operating_phase": "execute",
"operating_phase_deprecated": true
}
```
`_derive_operating_phase` bleibt für Rückwärtskompatibilität; markiert deprecated in Docstring.
### C3 — Initiative Create
Bei `create_initiative` → `steering_contexts` Zeile anlegen (`lifecycle_state=intake` oder Backfill-Regel).
---
## Teil D — API
| Endpoint | Capability | Beschreibung |
|----------|------------|--------------|
| `GET /api/initiatives/{id}/steering-context` | `kairo.initiative.read` | Context DTO |
| `GET .../steering-snapshot` | (bestehend) | + lifecycle Felder |
---
## Teil E — Frontend (minimal)
**Datei:** `frontend/src/constants/operating.js`
- `LIFECYCLE_LABELS` für 12 Standard-Schritte (DE)
- Steuerungszustand-Panel: primär `lifecycle_label`; `operating_phase` nur Fallback
Kein Maßnahmen-Hub. Keine neuen Widgets.
---
## Teil F — Tests
| Test | Erwartung |
|------|-----------|
| `test_ap1_steering_context.py` | CRUD Context, tenant isolation |
| `test_ap1_lifecycle.py` | Transition + Audit |
| `test_ap1_signals_regression.py` | Attention/NextAction gleich wie vor Refactor |
| `test_ap10_integration.py` | weiter grün; Snapshot hat lifecycle_state |
---
## Nicht-Scope
- Workflow Runtime, Waiting/Reminder Scheduler
- Zweite Built-in-Methode (`product_milestone_driven`) → AP1.1
- `roadmap_items`, `projects`, `milestones`-Migration
- AP0.10c UI
- Prompt/KI/MCP
- Entfernen von `operating_phase` → AP1.2
---
## Abnahme
1. Migration 009 deployed; bestehende Initiativen haben Context
2. `backend/steering/` existiert mit Lifecycle, Hooks, Methods, Signals
3. Attention/NextAction APIs unverändert im Verhalten (Regression)
4. Snapshot + neuer steering-context Endpoint liefern `lifecycle_state`
5. Scope Lock aus ADP eingehalten (kein AP0.10c)
6. pytest grün remote
---
## Reihenfolge Implementierung
1. Migration 009 + Backfill
2. `steering/lifecycle`, `steering/context`
3. Initiative-Create Hook
4. `steering/signals` Refactor aus attention.py
5. Hook dispatch in operating_transitions
6. API + Snapshot + Frontend Labels
7. Tests + Version bump
---
*Nächster Schritt nach Abnahme: AP0.10d Validation Report, dann AP1.1 Method Registry erweitern*