# 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,
    "score": 127.5,
    "reason_code": "priority_critical",
    "summary": "...",
    "ranker_key": "heuristic_v0" | "agent_v1",
    "confidence": "heuristic" | "agent",
    "factors": [{"code": "priority", "weight": 100, "label": "..."}],
    "dependency_refs": [{"ref_type": "parent_action", "ref_id": "...", "status": "..."}],
    "dependency_blocked": false,
    "data_source": "steering_kernel",
}
```

- UI: Accept / Adjust / Ignore — Mensch oder Agent bestätigt
- **Kein** festes „Bugs zuerst“ — Ranker austauschbar via `proposal_rankers.sprint_commit` im Operating Context / Governance
- **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 | ✓ (work_cycle_scope) | ✓ | — | ◐ | ◐ |
| `gate_next_actions` proposal | — | ◐ | ✓ | ✓ | — |
| `intake_triage` proposal | — | ✓ (excl. sprint) | ✓ | ◐ | ✓ |
| `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` migriert | ✓ Kernel v0.3 |
| **K-Ext-2** | `attention/contributors/registry.py`; inline-Attention refactoren | ✓ AP2.2j |
| **K-Ext-3** | `proposals/registry.py` + `SteeringEvaluation.proposals` | ✓ AP2.2i (P6) |
| **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 — ✓ geliefert (Kernel v0.3, Snapshot spiegelt `evaluation.read_models`).

---

## 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` |