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:

{
    "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. 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[].

---

8. 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.

---

9. 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

---

10. 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