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

# ADP — Steering Kernel Coding Rules v0.1

**Status:** PO-freigegeben — **verbindlich für alle Coding-Agenten**  
**Stand:** 2026-07-27  
**Bezug:** ADP Steering Kernel Spine v0.1, ADP Steering Kernel Extension Model v0.1, ADP AP2.4, `.cursor/rules/kairo-steering-kernel.mdc`

---

## 1. Geltungsbereich

Diese Regeln gelten für **jede** Änderung an:

- `backend/steering/**` (Kernel, Registries, Provider, Ranker, Contributors)
- `backend/data_layer/initiative_snapshot.py` (Steuerungs-Read-Models)
- Frontend-Steuerungs-UI (`SteeringProposalsPanel`, Operating Context, Snapshot-Konsum)

**Ziel:** Ein gemeinsamer Steuerungskern für alle Methoden — keine Agile-Sonderlogik in Pages, kein Methoden-Fork im Kernel.

---

## 2. Herzmaschine (Stop-the-line)

| Regel | Detail |
|-------|--------|
| **SK-01** | Initiative-Steuerung (Next Work, Attention, Read Models, Proposals) **nur** über `steering.kernel.evaluate_steering()`. |
| **SK-02** | Snapshot/API spiegeln Kernel-Output — **keine** parallele Berechnung in `initiative_snapshot.py` (Ausnahme: Legacy-Signals bis Migration). |
| **SK-03** | Keine Steuerungsheuristik in Routers, Services außerhalb `backend/steering/`, oder React-Pages. |

---

## 3. Extension Registry (Pflicht-Muster)

Neue Steuerungsfähigkeit = **Provider registrieren**, nicht inline codieren.

| Typ | Registry | Aktivierung |
|-----|----------|-------------|
| Read Model | `steering/read_models/registry.py` | `requires_elements`, optional `requires_any_element`, `requires_data_slices` |
| Proposal | `steering/proposals/registry.py` | wie oben + optional `excludes_elements` |
| Attention | `steering/attention/contributors/registry.py` | `requires_elements` / `requires_any_element` |
| Ranker (Proposal) | `register_sprint_commit_ranker()` o. Ä. | Operating Context `proposal_rankers.{key}` |

**SK-04:** Provider-Schlüssel sind stabil (`sprint_commit`, `gate_next_actions`, `intake_triage`) — UI bindet an Keys, nicht an Archetyp.

**SK-05:** Keine feste Produktpolitik in Rankern (z. B. „Bugs immer zuerst“). Heuristik = Fallback mit `ranker_key: heuristic_v0`; Agent = `agent_v1` nach Principle Gate.

---

## 4. Proposal-DTO (Minimalvertrag)

Jeder Proposal-Eintrag liefert mindestens:

```python
{
    "proposal_key": str,
    "scope_type": "backlog_item" | "roadmap_item" | "action" | ...,
    "scope_id": str,
    "rank": int,
    "reason_code": str,
    "summary": str,
    "ranker_key": str,
    "confidence": "heuristic" | "agent",
    "factors": [{"code", "weight", "label"}],
    "dependency_refs": [...],
    "dependency_blocked": bool,
    "data_source": "steering_kernel",
}
```

**SK-06:** Proposals **mutieren nie** OM — Accept erfolgt explizit in UI/API.

**SK-07:** Abhängigkeiten (`parent_action_id`, Execution Graph, Epic) in `dependency_refs` / `dependency_blocked` — nicht stillschweigend ignorieren.

---

## 5. Methoden-Parität

| Methode / Element | Read Models | Proposals |
|-------------------|-------------|-----------|
| `work_cycle_scope` | epic_rollup (mit backlog_epic_hierarchy) | `sprint_commit` |
| `gate_fulfillment` | `planning_debt`, `execution_graph` | `gate_next_actions` |
| `backlog` ohne Sprint | — | `intake_triage` (`excludes work_cycle_scope`) |
| `queue_inbox` | — | `intake_triage` (Queue-Profil) |
| `critical_path` | `execution_graph` | (später path-basiert) |

**SK-08:** Neue Methode = Elemente im `MethodDefinition` + Provider — **kein** `if method_key == …` in Kernel.

**SK-09:** `agile_iteration` ist **Modifier**, keine Parallel-Welt — komponiert mit Primary (Product, Linear, …).

---

## 6. Frontend

**SK-10:** Steuerungs-UI liest `steeringSnapshot.steering_kernel.proposals` / `read_models` — nicht selbst sortieren.

**SK-11:** `SteeringProposalsPanel` + `PROPOSAL_UI_CONFIG` erweitern — **keine** neue Page pro Proposal-Typ.

**SK-12:** Capabilities aus `operatingContext.steering_elements` / `hasSteeringElement` — keine Archetyp-Ifs.

---

## 7. Agent-Slots (K-Ext-4)

**SK-17:** Agent-Slots = deklarierte Aufgabenfenster — **keine** Prompts, **keine** Auto-Ausführung.

**SK-18:** Neue Slot-Art = `AgentSlotProvider` in `steering/agent_slots/registry.py`; Aktivierung via `agent_slot_config.enabled_slots` im Operating Context.

**SK-19:** Slot-DTO mindestens: `slot_key`, `scope_type`, `scope_id`, `actor_role_hint`, `context_refs`, `payload_keys`, `priority`.

---

## 8. KI / Agent (eingefroren bis Principle Gate)

**SK-13:** Keine Prompts hardcodieren. Agent-Ranker implementieren als `ranker_key: agent_v1` + Actor-Slot — Kontext aus Snapshot/Operating Context.

**SK-14:** Bis Freigabe: Fallback auf `heuristic_v0` mit transparentem `factors[]`.

---

## 9. Tests & Abnahme

**SK-15:** Jeder neue Provider: Unit-Test (reine Logik) + Integration über Snapshot wenn DB verfügbar.

**SK-16:** Truth Table + ADP Extension Model §6 aktualisieren.

---

## 10. Verboten (Anti-Patterns)

- Bug-zuerst / Story-zuerst als globale Sortierregel ohne `ranker_key`-Kennzeichnung
- Proposal-Logik in `BacklogSection` / `PlanSprintPage`
- Duplicate Read Model (Snapshot + Kernel)
- Neue OM-Tabelle für Vorschläge
- Methoden-spezifische Kernel-Forks

---

## 11. Referenzen

| Dokument | Pfad |
|----------|------|
| Kernel Extension Model | `docs/architecture/ADP_Steering_Kernel_Extension_Model_v0.1.md` |
| Kernel Spine | `docs/architecture/ADP_Steering_Kernel_Spine_v0.1.md` |
| Cursor Rule | `.cursor/rules/kairo-steering-kernel.mdc` |
| Plugin-Architektur | `.cursor/rules/kairo-plugin-architecture.mdc` |