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

# Kairo – Method Design Principles
## v0.1 – Designprinzipien für registrierbare Steuerungsmethoden

**Status:** verbindlicher Architektur- und Methodendesign-Entwurf  
**Stand:** 2026-07-25 (§11 AP2.4-Vertrag ergänzt)  
**Zweck:** Definition der Designprinzipien, nach denen Kairo-Methoden künftig entwickelt, registriert, erweitert und versioniert werden.

---

## 1. Ziel

Kairo soll im Lauf der Zeit viele unterschiedliche Steuerungsmethoden unterstützen, ohne dass für jede Methode der komplette Codekern angepasst werden muss.

Methoden sollen sich ähnlich wie Widgets an einem klaren Abstraktionslayer anmelden können.

Die Architektur muss ermöglichen:

```text
- neue Methoden hinzufügen
- bestehende Methoden versionieren
- methodenspezifische Steuerungsstrukturen erzeugen
- methodenspezifische NextAction-Logik einhängen
- methodenspezifische Review-/Evidence-Logik einhängen
- später Method Profiles konfigurieren
- später Workflow-Fragmente an Hooks binden
- später Agent/LLM/Tool-Steps pro Methode erlauben
```

Gleichzeitig darf die Methodenarchitektur nicht beliebig und untestbar werden.

---

## 2. Grundprinzip

Eine Kairo-Methode ist kein Label.

Eine Kairo-Methode ist ein registriertes Steuerungspaket.

Sie beschreibt:

```text
- für welche Domains sie gilt
- welche Scope Types sie steuern kann
- welchen Standard Lifecycle sie nutzt oder erweitert
- welche Steuerungsstrukturen sie benötigt
- welche Hook Slugs sie unterstützt
- welche Structure Builder sie bereitstellt
- welche Signal Rules sie registriert
- welche NextAction Strategy sie nutzt
- welche Assignment / Waiting / Reminder / Escalation Strategy sie nutzt
- welche Review- und Evidence-Policies gelten
- welche Workflow-Fragmente später erlaubt sind
- welche Node Types später erlaubt sind
```

---

## 3. Method Registry als zentraler Erweiterungspunkt

Alle Methoden registrieren sich in einer zentralen Method Registry.

Zielbild:

```text
backend/steering/methods/registry.py
```

Beispielhafte Registrierung:

```python
register_method(
    MethodDefinition(
        method_key="maturity_progression",
        version="v1",
        label="Maturity Progression",
        supported_domains=["maturity_development", "personal_development"],
        supported_scope_types=["initiative", "roadmap_item", "action"],
        default_lifecycle="standard_development_lifecycle",
        required_structures=["roadmap", "roadmap_lanes", "roadmap_items", "backlog", "actions"],
        hook_slugs=[
            "on_goal_captured",
            "on_structure_required",
            "on_maturity_path_required",
            "on_next_action_requested",
            "on_evidence_required",
            "on_review_due",
            "on_reassessment_required",
        ],
        structure_builders=[
            "maturity_path_builder",
            "practice_backlog_builder",
        ],
        signal_rule_providers=[
            "maturity_gap_attention_rules",
            "evidence_required_rules",
        ],
        next_action_strategy="maturity_next_action_strategy",
        assignment_strategy="default_actor_assignment_strategy",
        waiting_strategy="default_waiting_strategy",
        review_strategy="maturity_review_strategy",
        evidence_policy="maturity_evidence_policy",
        allowed_node_types=[
            "human_task",
            "evidence_check",
            "review",
            "reflection",
            "llm_prompt",
            "agent_task",
        ],
    )
)
```

---

## 4. Built-in zuerst, konfigurierbar später

Die Methodenarchitektur folgt einem Stufenmodell.

### Stufe 1 – Built-in Methods

```text
- Methoden code-seitig definiert
- klare Slugs
- testbar
- keine freie Nutzerkonfiguration
```

### Stufe 2 – Built-in Method Profiles

```text
- vordefinierte Profile pro Methode
- z. B. "einfach", "evidence_strict", "review_driven"
```

### Stufe 3 – Tenant Method Profiles

```text
- tenant-spezifische Konfiguration
- begrenzte Parameter
- keine freie Ausführungslogik
```

### Stufe 4 – Workflow Bindings an Hooks

```text
- kleine Workflow-Fragmente an definierte Hooks
- nur erlaubte Node Types
- nur innerhalb Method Governance
```

### Stufe 5 – Method Designer

```text
- spätere UI
- nur für fortgeschrittene Nutzung
- Governance, Tests und Freigaben erforderlich
```

---

## 5. Zentrale gemeinsame Strukturen

Alle Methoden müssen auf gemeinsamen Kairo-Strukturen aufbauen.

Gemeinsame Kernstrukturen:

```text
SteeringContext
Roadmap
RoadmapLane
RoadmapItem
BacklogItem
Action
ActionAssignment
Blocker
Signal
AttentionItem
NextActionCandidate
Evidence
Review
Decision
Actor
Capability
AuditEvent
```

Eine Methode darf keine parallelen Kernmodelle erfinden.

Beispiele:

```text
Meilenstein = RoadmapItem(type = milestone)
Reifegrad = RoadmapItem(type = maturity_stage)
Feature = RoadmapItem(type = feature)
Kapitel = RoadmapItem(type = chapter)
Sprint-Grobplanung = RoadmapItem(type = work_cycle)
```

---

## 6. Minimaler Standard Lifecycle

Alle Methoden basieren auf einem gemeinsamen minimalen Lifecycle.

```text
intake
method_selection
structure_setup
planning
action_selection
assignment
waiting
result_intake
validation
review
adaptation
closure
```

Eine Methode darf:

```text
- Schritte auslassen
- Schritte spezialisieren
- zusätzliche Hook Slugs ergänzen
- eigene Structure Builder an bestimmten Schritten registrieren
```

Eine Methode darf nicht:

```text
- Tenant-Sicherheit umgehen
- eigene Actor-Logik außerhalb des Actor-Modells einführen
- eigene Rechteprüfung außerhalb der Capability-Schicht einführen
- persistente Kernobjekte ohne Service-/Audit-Schicht verändern
```

---

## 7. Hook Slugs

Hook Slugs sind stabile Einhängepunkte.

Sie sind die Hauptabstraktion, über die Methoden erweitert werden.

Beispiele:

```text
on_goal_captured
on_method_selection_required
on_method_selected
on_structure_required
on_roadmap_required
on_backlog_required
on_wbs_required
on_maturity_path_required
on_content_structure_required
on_plan_required
on_dependency_analysis_required
on_dod_definition_required
on_next_action_requested
on_assignment_required
on_wait_started
on_due_date_reached
on_result_overdue
on_reminder_required
on_escalation_required
on_result_received
on_dod_check_required
on_evidence_required
on_quality_gate_required
on_review_due
on_reassessment_required
on_reflection_required
on_replan_required
on_structure_update_required
on_closure_requested
```

Hook Slugs müssen:

```text
- eindeutig sein
- versionierbar bleiben
- fachlich benannt sein
- in Method Definitions referenziert werden
- in Signals als Ursache auftauchen können
- später Workflow Bindings tragen können
```

---

## 8. Structure Builder

Structure Builder legen die methodenspezifische Steuerungsstruktur an.

Beispiele:

```text
roadmap_builder
milestone_plan_builder
feature_landscape_builder
wbs_builder
backlog_builder
maturity_path_builder
chapter_structure_builder
cycle_structure_builder
review_gate_builder
routine_structure_builder
```

Ein Structure Builder darf:

```text
- Roadmaps anlegen
- RoadmapLanes anlegen
- RoadmapItems anlegen
- initiale BacklogItems vorschlagen oder erzeugen
- methodenspezifische Startstruktur erzeugen
```

Ein Structure Builder darf nicht:

```text
- ungeprüft produktive Actions erzeugen, wenn ein Gate vorgesehen ist
- Actors ohne Assignment Strategy zuweisen
- Tenant-Kontext aus Client Input übernehmen
- Rechteprüfung umgehen
```

---

## 9. Strategies

Methoden nutzen austauschbare Strategies.

Wichtige Strategy Interfaces:

```text
NextActionStrategy
AttentionRuleProvider
AssignmentStrategy
WaitingStrategy
ReminderStrategy
EscalationStrategy
ResultIntakeStrategy
EvidencePolicy
ReviewStrategy
ClosurePolicy
```

Diese Strategies sind zentrale Erweiterungspunkte.

Sie verhindern, dass methodenspezifische Logik monolithisch in Services oder Data Layer wächst.

---

## 10. Signal Rules

Signal Rules erzeugen AttentionItems und NextActionCandidates.

Sie müssen erklären können:

```text
- warum ein Signal erzeugt wurde
- welcher Hook relevant ist
- welche Methode/Domain beteiligt ist
- welcher Scope betroffen ist
- welche Datenquelle genutzt wurde
- welche nächste Handlung empfohlen wird
```

Signal Rules müssen tenant-sicher sein und dürfen nicht quer über Tenants lesen.

---

## 11. Method Definition Contract

**Implementiert (AP2.4, Jul 2026):** Der produktive Vertrag in `backend/steering/methods/registry.py` ist schmaler als das Zielbild unten, aber verbindlich für MVP. Vollständige Spezifikation: `ADP_AP2_4_Steering_Elements_and_Method_Contract_v0.1.md`.

**AP2.4-Pflichtfelder (heute):**

```text
method_key
label
data_slices                    # Schnittmenge mit archetype.om_capabilities
compatible_archetype_keys
steering_elements              # Keys aus steering/elements/registry.py
ui_features                    # z. B. critical_path, recurring_panel
graph_profile                  # Kanten-/Graph-Strenge
next_action_strategy           # optional, Strategie-Slug
method_role                    # primary | composable | profile
composes_with                  # optional, andere method_keys
```

**Zielbild (langfristig, noch nicht voll implementiert):**

Eine MethodDefinition sollte zusätzlich mindestens enthalten:

```text
method_key
version
label
description
supported_domains
supported_scope_types
default_lifecycle
required_structures
allowed_structures
hook_slugs
structure_builders
attention_rule_providers
next_action_strategy
assignment_strategy
waiting_strategy
reminder_strategy
escalation_strategy
result_intake_strategy
review_strategy
evidence_policy
closure_policy
allowed_workflow_fragments
allowed_node_types
default_configuration
```

**Regel:** Neue MVP-Methoden erweitern den AP2.4-Vertrag — keine parallelen UI-Registry-Hacks im Frontend.

---

## 12. Method Versioning

Methoden müssen versionierbar sein.

Regeln:

```text
- method_key bleibt stabil
- version beschreibt fachliche/technische Methode
- bestehende SteeringContexts referenzieren method_key + version
- neue Versionen dürfen bestehende Kontexte nicht stillschweigend verändern
- Migration oder Upgrade muss explizit sein
```

---

## 13. Method Profiles

Method Profiles sind spätere konkrete Konfigurationen.

Sie dürfen Parameter anpassen, aber nicht den Kairo-Kern umgehen.

Beispiele:

```text
maturity_progression.basic
maturity_progression.evidence_strict
content_chapter_based.light_review
product_milestone_driven.release_focused
routine_control.escalation_strict
```

Ein Method Profile darf z. B. konfigurieren:

```text
- welche Hooks aktiv sind
- welche Review-Frequenz gilt
- ob Evidence erforderlich ist
- welche Reminder-Strategie gilt
- welche Node Types erlaubt sind
- ob Agent Steps erlaubt sind
```

Ein Method Profile darf nicht:

```text
- beliebigen Code ausführen
- Tenant-Sicherheit umgehen
- Capabilities außer Kraft setzen
- systemgeschützte Hooks überschreiben
```

---

## 14. Methodenbeispiele

### 14.1 product_milestone_driven

```text
Domain:
- product_development
- project

Structures:
- Roadmap
- Feature Lane
- Architecture Lane
- Release Lane
- Backlog
- Actions
- Blockers

Primary Hooks:
- on_goal_captured
- on_roadmap_required
- on_backlog_required
- on_next_action_requested
- on_review_due
```

### 14.2 content_chapter_based

```text
Domain:
- content_development

Structures:
- Roadmap
- Chapter Lane
- Research Lane
- Draft Lane
- Review Lane
- Backlog
- Actions

Primary Hooks:
- on_content_structure_required
- on_next_action_requested
- on_review_due
```

### 14.3 maturity_progression

```text
Domain:
- maturity_development
- personal_development

Structures:
- Roadmap
- Maturity Stage Lane
- Capability Lane
- Practice Lane
- Evidence Lane
- Reflection Lane

Primary Hooks:
- on_maturity_path_required
- on_evidence_required
- on_review_due
- on_reassessment_required
```

### 14.4 wbs_driven

```text
Domain:
- project
- program

Structures:
- WBS Roadmap
- Work Package Items
- Dependencies
- Backlog
- Actions

Primary Hooks:
- on_wbs_required
- on_dependency_analysis_required
- on_next_action_requested
```

---

## 15. Designprinzipien kurz

```text
1. Methoden sind registrierte Steuerungspakete, keine Labels.
2. Neue Methoden melden sich an einer Registry an.
3. Alle Methoden nutzen gemeinsame Kairo-Kernstrukturen.
4. Der Standard Lifecycle ist die gemeinsame Basis.
5. Erweiterung erfolgt über Hook Slugs, Structure Builder und Strategies.
6. Built-in Methods kommen vor freier Konfiguration.
7. Profiles konfigurieren, aber ersetzen nicht den Kern.
8. Signals müssen erklärbar und tenant-sicher sein.
9. Agenten und LLMs sind spätere Step Provider, nicht Methoden selbst.
10. Keine Methode darf Capabilities, TenantContext oder Actor-Modell umgehen.
```

---

## 16. Konsequenz für die technische Zielarchitektur

Die technische Zielarchitektur muss diese Methodendesign-Prinzipien als verbindlich übernehmen.

Insbesondere muss sie definieren:

```text
- Method Registry
- Hook Registry
- MethodDefinition Contract
- Standard Lifecycle
- Structure Builder Interfaces
- Strategy Interfaces
- Signal Rule Provider Interfaces
- Method Versioning
- Method Profiles als spätere Konfigurationsebene
```