diff --git a/docs/architecture/ADP_Agile_Steering_Program_v0.1.md b/docs/architecture/ADP_Agile_Steering_Program_v0.1.md index de26170..666a51f 100644 --- 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 | diff --git a/docs/architecture/ADP_Steering_Kernel_Extension_Model_v0.1.md b/docs/architecture/ADP_Steering_Kernel_Extension_Model_v0.1.md new file mode 100644 index 0000000..9c946bd --- /dev/null +++ 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` | diff --git a/docs/product/Kairo_Implementation_Truth_Table_v0.1.md b/docs/product/Kairo_Implementation_Truth_Table_v0.1.md index f6fc943..bee61c3 100644 --- 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 |