---
description: Archetyp-/Methoden-Plugin-Architektur (AP2.3/AP2.4) — verbindlich für neue Implementierungen
globs: backend/steering/**,backend/entity_archetypes/**,backend/services/operating_context.py,frontend/src/registry/**,frontend/src/pages/**,frontend/src/context/InitiativeOperationsContext.jsx
alwaysApply: true
---

# Kairo Plugin-Architektur (AP2.3 / AP2.4)

Verbindliche ADPs: `docs/architecture/ADP_Archetype_Method_Plugin_Architecture_v0.1.md`, `docs/architecture/ADP_AP2_4_Steering_Elements_and_Method_Contract_v0.1.md`

## Vier Schichten — Auflösung zur Laufzeit

| Schicht | Registry | Liefert |
|---------|----------|---------|
| **Archetyp** | `entity_archetypes` + `ui_profile_json` | Nav, Routen, Plan-Outline, `om_capabilities` |
| **Methode** | `steering/methods/registrations/` | `data_slices`, `steering_elements`, `ui_features`, `graph_profile`, Strategie |
| **Element** | `steering/elements/registry.py` + FE `steeringElementRegistry.js` | Control-/Work-Bausteine |
| **Runtime** | `GET /api/initiatives/:id/operating-context` | Schnittmenge + Methoden-Vertrag |

```text
data_slices       = archetype.om_capabilities ∩ method.data_slices
steering_elements = method.steering_elements   (nur Methode)
ui_features       = method.ui_features           (nur Methode)
nav / routes      = archetype.ui_profile         (nur Archetyp)
```

Archetyp-Default-Methode ist **Empfehlung**, nicht Lock — kompatible Methoden über `compatible_archetype_keys` + `om_capabilities`.

## Erweitern (Open/Closed)

**Neue Methode:** neues Modul unter `steering/methods/registrations/` → `MethodDefinition` vollständig → Import in `steering/__init__.py` → pytest. **Kein** Core-Edit.

**Neuer Archetyp:** Seed in `entity_archetypes/registry.py` + `ui_profiles.py` + optional EFS — **kein** React-If in Pages.

**Neues Steuerungselement:** Eintrag in `steering/elements/registry.py` + FE `steeringElementRegistry.js`; Methoden referenzieren nur registrierte Keys.

## Frontend — verbindlich

- UI aus `operating-context` via `resolveOperatingProfile.js`
- Control/Work: `hasSteeringElement(steeringElements, '…')` — **keine** `archetype_key === 'initiative.…'`-Ifs
- Daten: `loadOperatingSlices` / `refreshOm([…])` — **kein** Full-Reload nach Mutationen
- Route Gating: `OperatingRouteGate` + `MODE_ROUTE_GROUPS`
- Provider: `ScopedOperationsBridge` (ein Provider pro Vorhaben)

## Verboten

- `uiFeatures` am Archetyp-Profil (deprecated — nur Methode)
- Hardcodierte Methoden-UI in `methodUiDefaults.js` für **neue** Archetypen
- Parallele Steuerungslogik außerhalb `backend/steering/`
- Methoden-Dropdown ohne Archetyp-Filter (`GET /steering/methods?archetype_key=…`)

## Fallback (legacy)

`methodUiDefaults.js` nur wenn Operating Context fehlt — nicht für neue Features erweitern.

## Abnahme neuer Archetyp-/Methoden-Slices

- Operating Context liefert `steering_elements` + `ui_features`
- pytest für Methoden-Vertrag (`test_ap24_*`) grün
- Spec unter `docs/product/archetypes/` referenziert Elemente und kompatible Methoden