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+):**

```text
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)

```text
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)

```text
✓ 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

- [x] Rekursives Project statt Stream-Typ  
- [x] Rekursives Task für Granularität (Mensch 2–3, Agent tiefer)  
- [x] Steering-Root = Initiative (Stufe 1)  
- [x] AP1.5c → AP1.6 → AP1.5d Reihenfolge  
- [x] 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`*