Kairo-Jinkendo/docs/architecture/ADP_UX_Composition_Kernel_v0.1.md

ADP — UX Composition Kernel v0.1 (AP-UX-0 / AP-UX-1)

Status: PO-Arbeitsentwurf — MVP geliefert (2026-07-27)
Stand: 2026-07-27
Bezug: ADP_Steering_Kernel_Extension_Model_v0.1.md, ADP_AP2_4_Steering_Elements_and_Method_Contract_v0.1.md, Kairo_PM_Frontend_UI_Concept_v0.1.md, ARCHETYPE_UI_NAVIGATION_v0.1.md

---

1. Problem

Das Backend hat mit dem Steering Kernel v0.4 einen zentralen Steuerungs-Einstieg (evaluate_steering()). Provider für Read Models, Proposals und Agent-Slots hängen an registrierten Keys und steering_elements — nicht an Archetyp-Ifs.

Das Frontend spiegelt das noch nicht zentral:

Baustein	Heute	Soll
Control-Panels	InitiativeOverviewPage mit manuellen Ifs	UI-Slots + Provider
Proposals	SteeringProposalsPanel direkt in Plan-Pages	Slot plan.*.proposals
Agent-Slots	Direktimport in Overview	Slot control.status.agent
Cockpit-Widgets	widgetRegistry + manuelle Grid-Schleife	Slot cockpit.main
Steuerungselement-Registry	Labels/Hints only	Aktiviert Composition-Provider

Leitfrage: Wie composen Cockpit, Control und Plan konsistent aus dem gleichen Modell — analog zum Steering Kernel?

---

2. Entscheidung — Vier Schichten (Frontend-Spiegel)

Operating Context + Steering Snapshot
        ↓
resolveSteeringComposition(mode, routeKey, scope, context)
        ↓
UI-Slots (z.B. control.status.steering, plan.inbox.proposals)
        ↓
registrierte Provider (steering_element | proposal | agent_slots | widget | core)
        ↓
React-Komponenten (generisch, keine Archetyp-Ifs)

Schicht	Registry	Liefert
UI-Slot	composition/uiSlotRegistry.js	Benannte Flächen pro Modus/Route
Provider	composition/compositionProviders.js	Match-Regeln + Slot-Zuordnung
Resolver	composition/resolveSteeringComposition.js	Aktive Provider pro Slot zur Laufzeit
Renderer	CompositionSlot.jsx, providerComponents.jsx	Generisches Rendering

Parallele zum Backend:

Backend (Steering Kernel)	Frontend (UX Composition)
steering_elements	Provider kind: steering_element
proposals[key]	Provider kind: proposal
agent_slots[]	Provider kind: agent_slots
Portfolio-Aggregation	Provider kind: widget (Cockpit)
Snapshot-Kern	Provider kind: core

---

3. UI-Slots (MVP)

Slots sind stabil benannte Flächen — unabhängig von React-Page-Struktur.

Slot-Key	Modus	Route	Inhalt (MVP)
cockpit.main	cockpit	—	Portfolio-Widgets
control.status.core	control	status	Steering-Snapshot
control.status.steering	control	status	Kritischer Pfad, Next Action
control.status.agent	control	status	Agent-Slots
control.status.alerts	control	status	Roadblocker-Strip
plan.inbox.proposals	plan	inbox	Triage-Vorschläge
plan.sprint.proposals	plan	sprint	Sprint-Commit-Vorschläge
plan.gates.proposals	plan	gates	Gate-Vorschläge
work.today.primary	work	today	Next Action (Steuerung)
work.today.actions	work	today	Arbeitspakete (Drill-down)
work.sprint.primary	work	sprint	Next Action im Sprint
work.sprint.backlog	work	sprint	Sprint-Backlog (Drill-down)

Erweiterung (post-MVP): control.plan-ist.read_models, plan.inbox.read_models.

AP1.9d (2026-07-27): Work-Modus-Slots work.today.*, work.sprint.* — Next Action als Hauptbild, Arbeitspaket-Listen als Drill-down. Layout-neutral für späteres UI-Redesign; Provider-Vertrag bleibt stabil.

---

4. Provider-Vertrag

{
  key: 'steering.critical_path',
  kind: 'steering_element',       // steering_element | proposal | agent_slots | widget | core | conditional
  steeringElement: 'critical_path',
  slotKeys: ['control.status.steering'],
  componentKey: 'CriticalPathPanel',
  requiresCapability: 'kairo.action.read',
  scopeTypes: ['initiative'],     // portfolio | initiative
  order: 10,
}

Match-Regeln

kind	Aktiv wenn
steering_element	steering_elements enthält Key
proposal	steering_kernel.proposals[key] nicht leer (+ optional filterContext)
agent_slots	agent_slots oder steering_kernel.agent_slots nicht leer
widget	Capability erfüllt; Widget aus widgetRegistry
core	Immer auf Surface (Scope + Capability)
conditional	Custom predicate (z.B. Roadblocker counts > 0)

Verboten: archetype_key === '…' in Pages — nur Provider-Match über Operating Context.

---

5. Auflösung zur Laufzeit

resolveSteeringComposition({
  mode: 'control',
  routeKey: 'status',
  scope: 'initiative',
  operatingContext,
  steeringSnapshot,
  capabilities,
  filterContext: {},
  // Initiative-Ops für Props:
  opsContext: { initiativeId, actions, ... },
})
// → { surfaceKey: 'control.status', slots: { 'control.status.core': [ProviderInstance, ...], ... } }

Surfaces sind deklarativ in COMPOSITION_SURFACES — eine Page rendert <CompositionSurface surfaceKey="control.status" /> statt ad-hoc Imports.

---

6. Frontend-Dateien (MVP)

frontend/src/composition/
  uiSlotRegistry.js              — Slot- + Surface-Definitionen
  compositionProviders.js        — Provider-Registry
  resolveSteeringComposition.js  — Resolver + buildProviderProps
  resolveSteeringComposition.test.js
  providerComponents.jsx         — Component-Map + Prop-Adapter
  CompositionSlot.jsx            — Slot-Renderer
  CompositionSurface.jsx         — Surface-Renderer (mehrere Slots)
  useSteeringComposition.js      — Hook (InitiativeOperationsContext)

---

7. Migration (AP-UX-1)

Page	Vorher	Nachher
InitiativeOverviewPage	Manuelle Panel-Ifs	CompositionSurface surfaceKey="control.status"
InitiativeInboxPage	Direkt SteeringProposalsPanel	Slot plan.inbox.proposals
PlanSprintPage	Direkt SteeringProposalsPanel	Slot plan.sprint.proposals
InitiativePlanPage	Direkt SteeringProposalsPanel	Slot plan.gates.proposals
CockpitPage	getWidgetsForArea Schleife	Slot cockpit.main via Composition

Nicht migriert (post-MVP): PlanIstPanel, BacklogSection, GatesPlanPanel — Domain-CRUD bleibt außerhalb Composition (P4: Übersicht entscheidet, Detail pflegt).

---

8. Abnahme (AP-UX-1)

• resolveSteeringComposition Unit-Tests für alle Provider-Kinds
• Control/Plan-Pages ohne direkte SteeringProposalsPanel/AgentSlotsPanel-Imports
• Keine neuen Archetyp-Ifs in migrierten Pages
• Vitest grün (npm test)
• Dev-Deploy: Cockpit, Control/status, Plan/inbox/sprint/gates funktional

---

9. Referenzen

Artefakt	Pfad
Steering Element Registry	frontend/src/registry/steeringElementRegistry.js
Proposal UI Config	frontend/src/utils/steeringProposals.js
Widget Registry	frontend/src/registry/widgetRegistry.js
Operating Profile	frontend/src/registry/resolveOperatingProfile.js
Steering Kernel Coding Rules	docs/architecture/ADP_Steering_Kernel_Coding_Rules_v0.1.md

---

AP-UX-0 = dieses ADP. AP-UX-1 = MVP-Implementierung unter frontend/src/composition/.