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