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
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:
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*
|
||||
Reference in new issue
Block a user