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

ADP — Rekursive Container & Ausführungs-Granularität v0.1

Status: PO-Freigabe (2026-07-06)
Stand: 2026-07-06
Auslöser: PO-Review — Mega-Programme vs. normale Vorhaben; Granularität für Mensch vs. Agent
Bezug: ADP_PO_Product_Layering_and_IA_Reset_v0.1.md, Canonical OM v0.2, Target State §10–11

---

Problem

Zwei verwandte Fragen ohne feste Extra-Typen (Stream, Subtask, …):

1. Organisation: Sehr große Programme brauchen optional Project in Project; normale Vorhaben nicht.
2. Ausführung: Arbeitspakete und Aufgaben brauchen methoden- und akteursabhängige Tiefe — Menschen ~2–3 Untergliederungen, Agenten feiner.

Fest codierte Ebenen (Stream, WorkPackage, Subtask als eigene Typen) wären für kleine Vorhaben überdimensioniert und duplizieren semantisch Project bzw. Task.

---

Betroffene Regeln

Dokument	Regel
Canonical OM v0.2 §4	Project optional; Action = Arbeitspaket; Task methodenabhängig
Vision v0.2 §4	Action ≠ atomare Aufgabe; Task-Hierarchie / WBS
ADP Product Layering	Ist = Project → Action → Task; Gates orthogonal
Target State §10–11	Steuerbare Objekte inkl. project; SteeringContext mit scope_type
Tenant Invariants	Kein paralleles Steering; Actor-first Assignments

---

Optionen (Struktur)

Option	Kurz	Pro	Contra
A	Feste Typen Stream, Subtask	Klare UI-Labels	Schema-Ballast; Doppelung zu Project/Task
B	Rekursion gleicher Typen (parent_*_id)	Ein Modell für klein + groß	Baum-UI; Roll-up-Regeln nötig
C	Unbegrenzte Rekursion + Steuerung pro Ebene	Maximale Flexibilität	Steuerungs-Explosion; MVP-Verzögerung

---

Entscheidung (PO-Freigabe 2026-07-06)

1. Organisations-Ebene: rekursives Project

• parent_project_id nullable auf projects (Adjacency List).
• Gleiche Initiative; Zyklen verboten; max. Tiefe 5 (hard block).
• Optional container_kind (Registry/Label): project, stream, phase, release — nur Anzeige/Methoden-Hint, keine Sonderlogik pro Kind.
• Kein eigener Typ Stream.

Semantik nach Tiefe (UI, nicht Schema):

Tiefe	Typisches Label	Beispiel
0	Projekt	„Kairo MVP“
1	Stream / Phase	„Backend“, „Kumite“
2+	Teilprojekt	„API-Schicht“

Guardrails:

• Actions bevorzugt an Blatt-Projects oder direkt an Initiative (Warnung bei Container mit Kindern).
• Gates (roadmap_item_id) an jeder Project-Tiefe oder Initiative — Plan/Ist in AP1.6.

Implementierung: AP1.5c — Migration 014 o.ä.

---

2. Ausführungs-Ebene: rekursives Task (Haupthebel Granularität)

• parent_task_id nullable auf tasks — gleiche Tabelle, Zeiger auf weitere Instanz.
• Max. Tiefe Schema: 10 (Agent/API).
• Max. Tiefe UI (Menschen): 3 Ebenen (Task → Subtask → Sub-Subtask) — Policy, kein Schema-Limit.
• Roll-up: Action done wenn Task-Baum erfüllt (Regeln in AP1.5d); Task done wenn alle Kinder done oder explizit ohne Kinder.

Guardrails:

• Steuerung bleibt auf Action (Assignment, Blocker, Evidence, Next Action für Menschen).
• Kein steering_context pro Task-Ebene.
• Agenten: Blatt-Tasks als Ausführungsschritte; tiefe Bäume in UI aggregiert anzeigen.

Implementierung: AP1.5d — nach AP1.6 (Plan/Ist-Verknüpfung + Gate-Beitrag zuerst).

---

3. Action-Verschachtelung: eingeschränkt, nicht Default

• parent_action_id nur für wbs_driven (später), max. Tiefe 2.
• Nur Root-Action aus Backlog-Commit; Kind-Actions = strukturelle Teilpakete desselben Commits.
• Default-Vorhaben: eine Action + Task-Baum — kein Action-Baum.

Implementierung: dokumentiert; Code nicht in AP1.5c/d — erst mit Methodenprofil / Structure Builder.

---

4. Steuerung: Vererbung, nicht Explosion

Stufe 1 (MVP bis AP1.6+):

Initiative     = einziger Steering-Root (steering_context, heute implementiert)
Project*       = Struktur; erbt Initiative-Steuerung
Action         = operative Steuerungs-Anker für Menschen (Assignment, Blocker, Evidence)
Task*          = Ausführungsschritte; Roll-up, kein eigener Context

Stufe 2 (später, Mega-Programme):

• Polymorpher SteeringContext (scope_type, scope_id) wie Target State.
• Nur Projects mit steering_root = true oder explizitem Override — nicht jede Ebene.

---

Schichtenmodell (Ziel)

Initiative ── steering_context (Pflicht)
│
├── [optional] Project*                    parent_project_id
│     └── Project* …
│           └── Action                     Commit-Grenze (Root aus Backlog)
│                 └── Task*                parent_task_id
│                       └── Task* …
│
├── [optional] Gates (RoadmapItem)         orthogonal
└── Backlog → Commit → Action (Root)

Zwei orthogonale Dimensionen:

Dimension	Rekursion	Mensch-Tiefe	Agent-Tiefe
Project (Organisation)	ja	0–2 typisch	—
Action (Arbeitspaket)	selten (WBS)	1	1–2
Task (Ausführung)	ja	2–3	bis 10

---

Repriorisierung (verbindlich)

✓ AP1.5     Project, Task flach, Ausführung (0.14.0-ap1.5)
→ AP1.5c    parent_project_id, Baum-UI, container_kind optional
→ AP1.6     Plan/Ist-Verknüpfung, Journey
→ AP1.5d    parent_task_id, Roll-up, UI-Tiefen-Policy
⏸ AP1.4c   Gate-UI — weiter eingefroren
→ AP1.4d    Gate-Graph
→ AP1.7     Operational Actor Interface (unverändert)

AP1.5b (IA-Begriffe) kann parallel zu AP1.5c.

---

Konsequenzen

Bereich	Konsequenz
Schema	Zwei Migrationen: Project-Baum, Task-Baum — getrennte APs
UI	Baum/Outline statt nur flache Listen; Default collapsed ab Tiefe 2
API	Cycle-Detection; depth validation
Tests	Klein (flach), Mega (Project-Tiefe 3), Agent (Task-Tiefe >3)
Steering	Keine Änderung in AP1.5c/d außer Roll-up-Fortschritt
Agent AP1.7	Nutzt Task-Blätter; tiefe Zerlegung über AP1.5d

---

Risiko

Risiko	Mitigation
UI-Overload durch Tiefe	UI soft cap 3 Tasks; Mega-Projects collapsed
Redundante Pfade (Project + Action + Task alle tief)	Guardrails + PO-Dokumentation
Commit-Modell bei nested Actions	Nested Actions erst WBS-Profil; Default flach
Steuerungs-Explosion	Stufe 1: nur Initiative-Context

---

Rückbaubarkeit

• parent_*_id nullable — flache Nutzung bleibt Default.
• container_kind optional — entfernbar ohne Schema-Bruch.
• Polymorpher SteeringContext ist Add-on, kein Breaking Change für AP1.5c/d.

---

Abnahme PO

• Rekursives Project statt Stream-Typ
• Rekursives Task für Granularität (Mensch 2–3, Agent tiefer)
• Steering-Root = Initiative (Stufe 1)
• AP1.5c → AP1.6 → AP1.5d Reihenfolge
• Implementierung AP1.5c
• Implementierung AP1.5d

---

Referenz: Kairo_Corrected_MVP_Roadmap_v0.2.md (Update 2026-07-06), ADP_PO_Product_Layering_and_IA_Reset_v0.1.md