AP2.4: Steuerungselement-Registry und Methoden-Vertrag.
Deploy Development / deploy (push) Successful in 46s
Test Suite / pytest-backend (push) Failing after 3m17s
Test Suite / k6 /api/health Baseline (push) Has been skipped
Test Suite / playwright-smoke (push) Has been skipped
Test Suite / lint-backend (push) Successful in 2s
Test Suite / compose-smoke (push) Has been skipped

MethodDefinition traegt steering_elements/ui_features/graph_profile; operating-context und FE-Registry ohne Archetyp-Ifs.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-07-25 11:27:59 +02:00
1 parent ac475ab92c
commit d3bf3c36e0
25 files changed
+837 -118

No files matched your search

@@ -0,0 +1,228 @@
# ADP — Steuerungselemente & Methoden-Vertrag v0.1 (AP2.4)
**Status:** vorgeschlagen — Implementierung AP2.3g/AP2.4
**Stand:** 2026-07-25
**Bezug:** `ADP_Archetype_Method_Plugin_Architecture_v0.1.md` (AP2.3), `ADP_Archetype_and_Method_Catalog_v0.2.md`, `Kairo_Method_Design_Principles_v0.1.md`
**Ersetzt nicht:** AP2.3 A–F; **vertieft** Schicht 1 (Methode) und schließt Restschuld AP2.3g
---
## 1. Problem
AP2.3 hat Archetyp (Schicht 2) und Methode (Schicht 1) technisch entkoppelt:
- `GET /operating-context` liefert `ui_profile` + `data_slices`
- `MethodDefinition` trägt `data_slices` + `compatible_archetype_keys`
**Offene Lücke:** Steuerungsverhalten und Control-UI hängen noch an verstreuten Stellen:
| Verhalten | Heute | Soll |
|-----------|-------|------|
| Kritischer Pfad | FE-Hack `METHOD_UI_FEATURES` + Archetyp-If | Methode `sequential_dependency` |
| Product ohne Sprint | Archetyp `uiFeatures` | Methode `continuous_product` |
| Graph-Strenge | `graph/profiles.py` separat | Methoden-Vertrag |
| Control-Panels | Page-Ifs | Steuerungselement-Registry |
| Methodenwahl UI | alle Methoden | nur kompatible pro Archetyp |
**PO-Anforderung:** Jeder Archetyp kann mit **unterschiedlichen Steuerungsmethoden** geführt werden. Methoden bringen **eigene Steuerungselemente** mit und müssen **explizit** mit Archetypen kompatibel sein — ohne React-Ifs und ohne Duplikat-Registry.
---
## 2. Leitentscheidung
### 2.1 Drei Registries, eine Auflösung
```text
Archetyp-Registry (Schicht 2) → IA-Hülle, OM-Fähigkeiten, Default-Methode
Methoden-Registry (Schicht 1) → Motor: Strategie, Slices, Elemente, Graph
Steuerungselement-Registry → Katalog benannter Control-/Work-Bausteine
GET /initiatives/:id/operating-context
→ resolve(archetype, method, profile?)
```
### 2.2 Auflösungsregeln (verbindlich)
| Feld | Quelle | Regel |
|------|--------|-------|
| `ui_profile` (Nav, Routen, Outline) | **Archetyp** | unverändert |
| `data_slices` | **Schnittmenge** | `archetype.om_capabilities ∩ method.data_slices` |
| `steering_elements` | **Methode** | nur aktive Methode |
| `ui_features` | **Methode** | Verhaltensflags Work/Control |
| `graph_profile` | **Methode** | Gate-Blocking, Fulfillment |
| `method_capabilities` | **Methode** | Strategie, Lifecycle |
| `compatible_methods` | **Registry** | gefiltert nach Archetyp |
**Archetyp ≠ Methode:** Default-Methode ist **Empfehlung**, nicht Lock. Nutzer mit `kairo.initiative.manage` darf jede **kompatible** Methode wählen.
### 2.3 Kompatibilität
```text
compatible(archetype, method) :=
archetype_key ∈ method.compatible_archetype_keys (oder "*")
AND method.data_slices ⊆ archetype.om_capabilities
```
`om_capabilities` im Archetyp-Profil entspricht fachlich den erlaubten OM-Slices (Fallback: `dataSlices` aus `ui_profile_json`).
### 2.4 Methoden-Rollen (Komposition)
| Rolle | Bedeutung | Beispiel |
|-------|-----------|----------|
| `primary` | Einziger Motor am `steering_context.method_key` | `continuous_product` |
| `modifier` | Ergänzt Primärmethode über Profil/Policy | `agile_iteration` (Sprint auf Product) |
**MVP:** ein `method_key` pro Vorhaben; `agile_iteration` als Modifier über `method_profile_key` / `work_cycle`-Policy — kein zweiter SteeringContext.
---
## 3. Steuerungselemente (Schicht 1b)
Ein **Steuerungselement** ist ein stabiler Key, den eine Methode aktiviert. Backend und Frontend registrieren sich darauf.
| Key | Bedeutung | Typische Methode(n) |
|-----|-----------|---------------------|
| `next_action_primary` | Next-Action-Widget als Steuerungsdefault | alle |
| `critical_path` | Kritischer Pfad / Execution-Graph | `sequential_dependency` |
| `gate_fulfillment` | Gate-Fortschritt, Verify-Semantik | `program_delivery`, `product_milestone_driven`, … |
| `work_cycle_scope` | Sprint-Zeitbox, Sprint-Backlog | `continuous_product`, `agile_iteration` |
| `recurring_rhythm` | Rhythmen / Journey-Fokus | `maturity_progression`, `recurring_control` |
| `queue_inbox` | Queue-Pull, Eingang prominent | `queue_pull` |
| `maturity_stage` | Reifegrad-Stufen | `maturity_progression` |
| `chapter_progression` | Kapitel-Fortschritt | `chapter_based_progression` |
| `dispute_timeline` | Fristen / Verfahren | `dispute_procedure` |
**Registry:** `backend/steering/elements/registry.py`
**Frontend:** `frontend/src/registry/steeringElementRegistry.js` — Element → Panel/Widget
**Regel:** Control-/Work-Seiten composen UI aus `operating_context.steering_elements` — **keine** Archetyp-Ifs.
### 3.1 UI-Features (Verhaltensflags)
Zusätzlich zu Elementen (was gerendert wird) können Methoden **Verhaltensflags** setzen:
| Key | Bedeutung |
|-----|-----------|
| `criticalPathControl` | Next-Action-Copy / Pfad-Fokus |
| `continuousProductWorkMode` | Product-Ist ohne aktiven Sprint |
| `steeringSnapshotOnWorkSprint` | Snapshot lazy auf Work/Sprint |
Quelle: **nur Methode** (`MethodDefinition.ui_features`), nicht Archetyp.
---
## 4. Methoden-Vertrag (`MethodDefinition`)
Erweiterung gegenüber AP2.3e:
```python
@dataclass(frozen=True)
class MethodDefinition:
key: str
version: str
label: str
description: str
default_lifecycle_steps: tuple[str, ...]
next_action_strategy_key: str
data_slices: frozenset[str]
compatible_archetype_keys: frozenset[str] | Literal["*"]
steering_elements: frozenset[str] = frozenset()
ui_features: frozenset[str] = frozenset()
graph_profile: GraphMethodProfile = LIGHT
method_role: Literal["primary", "modifier"] = "primary"
composes_with: frozenset[str] = frozenset()
```
`GraphMethodProfile` wandert aus `graph/profiles.py` in den Methoden-Vertrag; `get_graph_profile(method_key)` liest aus Registry.
---
## 5. Operating Context (API-Erweiterung)
`GET /api/initiatives/{id}/operating-context` liefert zusätzlich:
```json
{
"steering_elements": ["critical_path", "next_action_primary"],
"ui_features": { "criticalPathControl": true },
"graph_profile": {
"enforce_gate_blocking": true,
"emphasize_fulfillment": false
},
"compatible_methods": [
{ "key": "sequential_dependency", "label": "…", "is_default": true }
]
}
```
`ui_profile.uiFeatures` am Archetyp wird **deprecated** (leer); Migration in Methoden-Registrations.
---
## 6. Steering API
`GET /api/steering/methods?archetype_key=initiative.linear_project`
- Filtert nach `method_compatible_with_archetype`
- Response enthält `steering_elements`, `ui_features`, `compatible_archetype_keys`
Methoden-Dropdown in Control zeigt nur kompatible Einträge.
---
## 7. Implementierungspakete
| Paket | Lieferung | Abhängigkeit |
|-------|-----------|--------------|
| **AP2.4a** | `steering/elements/registry.py`, erweiterte `MethodDefinition`, Registrations | AP2.3e |
| **AP2.4b** | `operating-context` + `/steering/methods` Filter | AP2.4a |
| **AP2.4c** | FE Resolver, `steeringElementRegistry`, Pages ohne Ifs | AP2.4b |
| **AP2.4d** | pytest + Vitest + Truth Table | AP2.4c |
Optional **AP2.4e:** explizites `omCapabilities` am Archetyp-Seed (statt `dataSlices`-Missbrauch).
---
## 8. Erweiterungs-Workflow
**Neue Methode `foo_bar`:**
1. `steering/methods/registrations/foo_bar.py` — Contract vollständig
2. Nur Keys aus `steering/elements/registry.py` referenzieren
3. Import in `steering/__init__.py`
4. pytest `test_method_foo_bar_contract.py`
5. Kein Core-Edit außer Registry-Dispatcher
**Neues Steuerungselement `my_panel`:**
1. Eintrag in `steering/elements/registry.py`
2. FE `steeringElementRegistry.js`
3. Methoden, die es brauchen, tragen Key in `steering_elements`
---
## 9. Nicht tun
- Keine Archetyp-Ifs für Control (`initiative.linear_project === …`)
- Keine parallele Graph-Profile-Map ohne Methoden-Bezug
- Keine Tenant-DSL für Methoden
- Keine zweite SteeringContext-Tabelle für Komposition
---
## 10. Abnahme
| Kriterium | Test |
|-----------|------|
| Operating Context liefert `steering_elements` + `ui_features` aus Methode | pytest AP2.4 |
| Linear + `queue_pull` → keine `critical_path`, kleinere Slices | pytest AP2.3e |
| `/steering/methods?archetype_key=…` filtert | pytest AP2.4 |
| Control rendert Critical Path nur bei Element | Vitest + manuell |
| Kein `METHOD_UI_FEATURES` im FE | Code-Review |
---
## 11. Bezug AP2.3
AP2.3 A–F liefert Operating Context, Slice-Loader, Route Gating.
AP2.4 **schließt die methodenunabhängige Steuerungsschicht** — Voraussetzung für Archetyp-Welle 2 (B1, A3, D1) ohne Page-Patches.