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

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

┌─────────────────────────────────────────────────────────────┐
│  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):

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

@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

@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:

@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):

{
    "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:

@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):

{
    "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