docs: Steering Kernel Extension Model fuer Read Models, Proposals und Agent-Slots

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-27 11:14:19 +02:00 · 2026-07-27 11:14:19 +02:00 · c5e2c69b1e
commit c5e2c69b1e
parent ef5ee0d19b
3 changed files with 269 additions and 7 deletions
--- a/docs/architecture/ADP_Agile_Steering_Program_v0.1.md
+++ b/docs/architecture/ADP_Agile_Steering_Program_v0.1.md
@ -2,7 +2,7 @@

 **Status:** PO-Freigabe (Planung — nicht implementiert)  
 **Stand:** 2026-07-27  
-**Bezug:** ADP Backlog/Epic P1–P4, SPEC-D `agile_iteration`, Steering Kernel Spine, Vision v0.2 (Program Director)
+**Bezug:** ADP Backlog/Epic P1–P4, SPEC-D `agile_iteration`, Steering Kernel Spine, **ADP Steering Kernel Extension Model v0.1**, Vision v0.2 (Program Director)

 ---

@ -34,12 +34,14 @@ Das reicht für **Dokumentation und Nachverfolgung**, aber noch nicht für **vor

 ## 3. Entscheidung — Phasen P5–P8 (Agile Steering Program)

-| Phase | Inhalt | Schicht | Abhängigkeit |
+> **Architekturrahmen:** Alle Phasen nutzen die **Extension Registry** des Kernels (Read Models, Proposals, Agent-Slots) — siehe `ADP_Steering_Kernel_Extension_Model_v0.1.md`. Agile liefert **Provider-Implementierungen**, nicht Kernel-Forks.
+
+| Phase | Inhalt | Kernel-Extension | Plugin / OM |
 |-------|--------|---------|--------------|
-| **P5** | Agent-Task-Baum unter Action | Ist / Recursive Tasks | ADP Recursive (AP1.5d) |
-| **P6** | **Sprint-Vorschlag** — Read Model: committbare Items + Prioritätsranking | Kernel + Snapshot | P4, work_cycles |
-| **P7** | **Tech-/Architekturschuld** — Backlog-Typ oder Tag + Attention-Regeln + Abbau-Ziele | Plan + Kernel | Evidence, Review |
-| **P8** | **Automatisierte Reviews** — Guardrails, Architektur, Zielerreichung (Actor + optional KI) | Recurring + Review + Agent-Slot | Principle Gate, MCP-Freigabe |
+| **P5** | Agent-Task-Baum unter Action | — | Ist / Recursive Tasks (AP1.5d) |
+| **P6** | Sprint-Vorschlag (ranked Backlog → Sprint) | `ProposalProvider` `sprint_commit` + Read Models | `agile_iteration` Strategy |
+| **P7** | Tech-/Architekturschuld führen & abbauen | `ReadModelProvider` + `AttentionContributor` | Vokabular + Review/Evidence |
+| **P8** | Automatisierte Reviews (Guardrails, Ziele) | `AgentSlotProvider` + Recurring-Attention | Review + Actor (KI nach Gate) |

 Kein Phase-Sprung. **KI/Prompt/MCP** für P8 erst nach Principle Gate und stabilem Read-Model-Kern (vgl. Architecture Rules — eingefroren bis OM trägt).

@ -92,6 +94,7 @@ P4 liefert **Ist-Fortschritt auf Epic-Ebene**. P6–P8 liefern **Vorausschau und

 | Dokument | Pfad |
 |----------|------|
+| **Kernel Extension Model** | `docs/architecture/ADP_Steering_Kernel_Extension_Model_v0.1.md` |
 | ADP Backlog/Epic | `docs/architecture/ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md` |
 | SPEC agile_iteration | `docs/architecture/methods/SPEC_D_agile_iteration_v0.1.md` |
 | Recursive Tasks | AP1.5d / ADP Recursive Containers |
--- a/docs/architecture/ADP_Steering_Kernel_Extension_Model_v0.1.md
+++ b/docs/architecture/ADP_Steering_Kernel_Extension_Model_v0.1.md
@ -0,0 +1,259 @@
+# ADP — Steering Kernel Extension Model v0.1
+
+**Status:** PO-Freigabe (Planung — Architekturrahmen)  
+**Stand:** 2026-07-27  
+**Bezug:** ADP Steering Kernel Spine v0.1, ADP Agile Steering Program v0.1, ADP AP2.4 Steering Elements, Kairo Target Architecture (Read Models, Actor-first)
+
+---
+
+## 1. Problem
+
+P4 (`epic_rollup`) zeigt das Muster: **Steuerungswert entsteht durch Read Models + Attention**, nicht durch CRUD-Felder.  
+Künftige Fähigkeiten (Sprint-Vorschläge, Tech Debt, Reviews, Agent-Slots) dürfen **nicht** pro Methode oder Page dupliziert werden — sie müssen im **Steuerungskern** anschlussfähig sein, damit `agile_iteration`, `continuous_product`, `sequential_dependency`, `program_delivery`, `care_navigation` etc. dieselben Erweiterungspunkte nutzen.
+
+**Leitfrage:** Was gehört in den **Kernel** (generisch), was in **Method-Plugins** (spezifisch)?
+
+---
+
+## 2. Entscheidung — Drei Schichten
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  Schicht A — Kernel Spine (methodenagnostisch)              │
+│  evaluate_steering() → binding, horizon, lifecycle           │
+│  → next_work, attention, read_models{}, agent_slots[]       │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ ruft nur registrierte Provider
+┌───────────────────────────▼─────────────────────────────────┐
+│  Schicht B — Extension Registry (methoden-/element-gebunden)  │
+│  ReadModelProvider · AttentionContributor · ProposalProvider  │
+│  · AgentSlotProvider — keyed by steering_element / method   │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ liefert reine Funktionen/DTOs
+┌───────────────────────────▼─────────────────────────────────┐
+│  Schicht C — Domain-Module (OM + Services)                    │
+│  backlog, actions, roadmap, work_cycle, review, recurring …   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Stop-the-line (bestehend):** Keine Steuerungsheuristik in Routern, Pages oder Archetyp-Ifs.  
+**Neu:** Kein Read Model direkt in `initiative_snapshot.py` ohne Registry — Snapshot **aggregiert** Kernel-Output.
+
+---
+
+## 3. Was in den Kernel gehört (generisch)
+
+| Baustein | Kernel-Verantwortung | Nicht im Kernel |
+|----------|----------------------|-----------------|
+| **Orchestrierung** | Reihenfolge: binding → horizon → lifecycle → next_work → read_models → attention → agent_slots | Fachliche Scoring-Formeln |
+| **SteeringBinding** | Primary + Composition-Modifier | Archetyp-UI |
+| **HorizonMarker** | Gate / Sprint / none | Gate-Designer |
+| **Attention-Merge** | Severity-Sort, Limit, Dedup, `data_source` | Domain-Queries |
+| **Read-Model-Slot** | `{ key: dto[] }` im Evaluation + Snapshot | Epic vs. Queue vs. Gate-Berechnung |
+| **Proposal-Slot** | `{ key: ranked_items[] }` — Vorschläge ohne Auto-Mutation | Sprint- vs. Gate-Priorisierung |
+| **Agent-Slot** | `{ slot_key, actor_hint, context_ref, task_template }` | Prompt-Inhalt, MCP-Wiring |
+| **Capability-Gate** | Provider nur wenn `steering_element` / `data_slice` aktiv | Hardcoded Product-Ifs |
+
+**Ziel-API (evaluate_steering v0.3):**
+
+```python
+SteeringEvaluation(
+    binding, horizon, lifecycle,
+    next_work=[...],
+    attention=[...],
+    read_models={
+        "epic_rollup": [...],           # wenn backlog_epic_hierarchy
+        "planning_debt": [...],           # wenn gate_fulfillment
+        "execution_graph": {...},         # wenn critical_path
+    },
+    proposals={
+        "sprint_commit": [...],           # wenn work_cycle_scope
+        "next_gate_work": [...],          # wenn gate_fulfillment
+    },
+    agent_slots=[
+        { "slot_key": "review.guardrail", "scope_type": "review", ... },
+    ],
+)
+```
+
+---
+
+## 4. Extension Registry (Schicht B — zu implementieren)
+
+### 4.1 ReadModelProvider
+
+```python
+@dataclass(frozen=True)
+class ReadModelProvider:
+    key: str                          # z.B. "epic_rollup"
+    requires_elements: frozenset[str] # z.B. {"backlog_epic_hierarchy"}
+    requires_data_slices: frozenset[str]  # optional
+    compute: Callable[[SteeringContext], list | dict]
+```
+
+- **Registrierung** in `backend/steering/read_models/registry.py`
+- **Aufruf** aus Kernel nach `next_work`, vor finalem Attention-Merge
+- **Beispiele:**
+
+| key | Element / Methode | Modul |
+|-----|-------------------|-------|
+| `epic_rollup` | `backlog_epic_hierarchy` | `epic_rollup.py` ✓ (P4, noch direkt in Snapshot) |
+| `planning_debt` | `gate_fulfillment` | `execution_engine.py` (existiert) |
+| `execution_graph` | `critical_path` | `execution_engine.py` |
+| `queue_depth` | `queue_inbox` | neu |
+| `maturity_progress` | `maturity_stage` | neu |
+| `dispute_deadlines` | `dispute_timeline` | neu |
+
+### 4.2 AttentionContributor
+
+```python
+@dataclass(frozen=True)
+class AttentionContributor:
+    key: str
+    requires_elements: frozenset[str]
+    contribute: Callable[[SteeringContext, read_models], list[AttentionItem]]
+```
+
+- Heute: Blocker, blocked actions, planning_debt, execution_waiting, epic_rollup inline in `attention.py`
+- **Ziel:** Jeder Contributor registriert; Kernel merged + sortiert
+- **Regel:** Contributor dürfen **keine** OM schreiben — nur Attention-DTOs
+
+### 4.3 ProposalProvider (neu — „Dirigieren“)
+
+Vorschläge = **Read Models mit Handlungscharakter**, aber ohne Auto-Commit:
+
+```python
+@dataclass(frozen=True)
+class ProposalProvider:
+    key: str                    # "sprint_commit", "gate_next_actions"
+    requires_elements: frozenset[str]
+    propose: Callable[[SteeringContext, read_models], list[ProposalItem]]
+```
+
+**ProposalItem (Minimal-DTO):**
+
+```python
+{
+    "proposal_key": "sprint_commit",
+    "scope_type": "backlog_item" | "action" | "roadmap_item" | "review",
+    "scope_id": "...",
+    "rank": 1,
+    "reason_code": "bug_in_active_sprint",
+    "summary": "Bug X — hohe Priorität, Sprint aktiv",
+    "confidence": "heuristic" | "rule" | "agent",  # später
+    "data_source": "steering_kernel",
+}
+```
+
+- UI: Accept / Adjust / Ignore — Mensch oder Agent bestätigt
+- **Agile P6:** `sprint_commit` ProposalProvider
+- **Gate-Methoden:** `gate_next_actions` (planning_debt → konkrete AP-Vorschläge)
+- **Continuous Product:** `intake_triage` (Eingang priorisieren)
+
+### 4.4 AgentSlotProvider (neu — Actor-first)
+
+Agent-Slots = **deklarierte Aufgabenfenster** für Actors — kein Prompt in Code:
+
+```python
+@dataclass(frozen=True)
+class AgentSlotProvider:
+    slot_key: str               # "review.architecture_guardrail"
+    requires_elements: frozenset[str]
+    requires_recurring: bool    # optional
+    resolve: Callable[[SteeringContext, read_models, proposals], list[AgentSlot]]
+```
+
+**AgentSlot (Minimal-DTO):**
+
+```python
+{
+    "slot_key": "review.architecture_guardrail",
+    "initiative_id": "...",
+    "scope_type": "review" | "action" | "initiative",
+    "scope_id": "...",
+    "actor_role_hint": "architecture_reviewer",  # Capability-Mapping, nicht User
+    "context_refs": ["steering_snapshot", "operating_context"],
+    "payload_keys": ["checklist_id", "guardrail_pack"],  # aus Config/Governance
+    "priority": "normal",
+    "data_source": "steering_kernel",
+}
+```
+
+- **KI-Ausführung:** Actor mit Capability `kairo.agent.review` liest Slot + Snapshot — MCP erst nach Principle Gate
+- **Ohne KI:** Mensch sieht Slot als „Review fällig“ in Control-UI
+- **Wiederverwendung:** C1 `dispute_timeline`, A1 `maturity_stage`, B2a Program Reviews — gleicher Slot-Mechanismus, andere Provider
+
+---
+
+## 5. Zuordnung: Agile P5–P8 → Kernel vs. Plugin
+
+| Phase | Fähigkeit | Kernel | Plugin / Modul |
+|-------|-----------|--------|----------------|
+| **P5** | Task-Baum unter AP | — (Ist-OM) | `services/tasks.py`, Recursive ADP |
+| **P6** | Sprint-Vorschlag | `ProposalProvider` `sprint_commit` | `strategies/proposals/agile_iteration.py` |
+| **P6** | Sprint-Attention | `AttentionContributor` | gleiches Plugin |
+| **P7** | Tech Debt Attention | `AttentionContributor` | `read_models/tech_debt.py` + Vokabular-Erweiterung |
+| **P7** | Debt Roll-up | `ReadModelProvider` `tech_debt_summary` | profilgebunden |
+| **P8** | Review fällig | `AttentionContributor` + `AgentSlotProvider` | `recurring` + `review` Services |
+| **P8** | Guardrail-Check | `AgentSlot` `review.guardrail` | Config-Pack (Governance), nicht hardcoded |
+
+---
+
+## 6. Wiederverwendung über Methoden hinweg
+
+| Extension | agile_iteration | continuous_product | sequential_dependency | program_delivery | care_navigation |
+|-----------|-----------------|--------------------|-----------------------|------------------|-----------------|
+| `epic_rollup` | ✓ | — | — | ◐ (Epic=Liefercontainer) | — |
+| `sprint_commit` proposal | ✓ | — | — | — | — |
+| `planning_debt` | ◐ | ◐ | ✓ | ✓ | — |
+| `execution_graph` | ◐ | ◐ | ✓ | ✓ | ◐ |
+| `intake_triage` proposal | ✓ | ✓ | ◐ | ◐ | ✓ |
+| `review.*` agent slot | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `tech_debt_summary` | ✓ | ✓ | ✓ | ✓ | — |
+
+◐ = optional / profilabhängig über `steering_elements`, nicht über Archetyp-If.
+
+---
+
+## 7. Implementierungsphasen (Kernel-Infrastruktur)
+
+| Phase | Inhalt | Entkoppelt |
+|-------|--------|------------|
+| **K-Ext-1** | `read_models/registry.py` + Kernel ruft Provider; P4 `epic_rollup` migrieren | Snapshot nur noch Kernel-Output spiegeln |
+| **K-Ext-2** | `attention/contributors/registry.py`; inline-Attention refactoren | Methoden adden Contributor |
+| **K-Ext-3** | `proposals/registry.py` + `SteeringEvaluation.proposals` | P6 Agile Sprint-Vorschlag |
+| **K-Ext-4** | `agent_slots/registry.py` + Operating Context Feld `agent_slots` | P8 Reviews; Principle Gate für KI |
+| **K-Ext-5** | Portfolio-Ebene: Workspace aggregiert Attention/Proposals über Initiativen | Program Director multi-initiative |
+
+**Reihenfolge-Empfehlung:** K-Ext-1 → K-Ext-2 (technische Schuld aus P4 abbauen) → K-Ext-3 (P6) → P5 Tasks parallel möglich → K-Ext-4 (P8).
+
+---
+
+## 8. Abgrenzungen
+
+| Nicht tun | Stattdessen |
+|-----------|-------------|
+| Prompts im Kernel | AgentSlot + Operating Context + auditierte Actor-Ausführung |
+| Auto-Commit aus Proposal | Accept-API / expliziter Actor |
+| Read Model in Frontend berechnen | Snapshot / Operating Context |
+| Methode-spezifische Ifs in Kernel | `requires_elements` an Provider |
+| Neue OM-Tabelle „SprintProposal“ | Proposal = Read Model; Persistenz nur bei Accept |
+
+---
+
+## 9. P4-Ist → Ziel-Migration
+
+P4 implementiert `epic_rollup` **funktional korrekt**, aber noch **doppelt** (Attention + Snapshot rufen Modul direkt).  
+**K-Ext-1** konsolidiert auf Registry — kein Verhaltenswechsel, nur Architekturhygiene.
+
+---
+
+## 10. Referenzen
+
+| Dokument | Pfad |
+|----------|------|
+| Kernel Spine | `docs/architecture/ADP_Steering_Kernel_Spine_v0.1.md` |
+| Agile Steering Program | `docs/architecture/ADP_Agile_Steering_Program_v0.1.md` |
+| Steering Elements | `docs/architecture/ADP_AP2_4_Steering_Elements_and_Method_Contract_v0.1.md` |
+| Target Architecture | `docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md` |
+| Epic Roll-up (P4) | `backend/steering/read_models/epic_rollup.py` |
--- a/docs/product/Kairo_Implementation_Truth_Table_v0.1.md
+++ b/docs/product/Kairo_Implementation_Truth_Table_v0.1.md
@ -228,7 +228,7 @@ Details: `Kairo_Status_Review_and_Next_Steps_v0.1.md` §2.1
 |----|-----------|
 | AP2.3/4 | ✓ Plugin-Architektur + Element-Registry (2026-07-25) |
 | AP2.2a | Starter-Kits ◐→✓ |
-| ADP Backlog/Epic | P1–P4 ✓ (Roll-up AP2.2h) · P5 Agent-Tasks offen |
+| ADP Backlog/Epic | P1–P4 ✓ · P5 Agent-Tasks offen · Kernel-Ext K-Ext-1…5 |
 | AP2.2b–e | Referenz-Archetypen End-to-End ◐→✓ |
 | AP2.1 | MVP-Abnahfe ✗→✓ |
 | AP1.7b | Op-API Parität |