docs: Backlog-Hierarchie, Dual Commit Path und Epic-Zielbild

ADP v0.1 plus Updates in B2b-Spec, agile_iteration, Katalog und Truth Table.
This commit is contained in:
Lars committed 2026-07-26 18:25:12 +02:00
1 parent 1c10e5b798
commit f7d65dde01
11 files changed
+327 -15

No files matched your search

@@ -213,11 +213,13 @@ Kanoniche Typen aus OM v0.2 — **keine eigenen Tabellen** pro Typ.
**Sprint-Backlog-Semantik (B3):**
- **Product Backlog** = `BacklogItem` (+ optional Gate-Link) — Plan-Eingang
- **Product Backlog** = `BacklogItem` (+ optional Gate-Link, optional Epic-Baum) — Plan-Eingang
- **Sprint Backlog** = `Action` (Status open/ready/in_progress) mit **`work_cycle_id`** (FK auf `roadmap_items.id` wo `item_type=work_cycle`)
- Commit aus Eingang → Action **mit** aktivem Zyklus = Sprint-Commit
- Abgeschlossener Sprint: Actions done/cancelled; Zyklus `reached` oder `closed`; Review optional via `Review`-Objekt
**Dual Commit & Epic:** [`ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md`](ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md)
Migration: `actions.work_cycle_id UUID NULL REFERENCES roadmap_items(id)` (AP2.0f).
### 3.5 Agile-Begriffe — Abbildung in Kairo
@@ -225,6 +227,8 @@ Migration: `actions.work_cycle_id UUID NULL REFERENCES roadmap_items(id)` (AP2.0
| Scrum/Agile-Begriff | In Kairo | Status |
|---------------------|----------|--------|
| Product Backlog | `BacklogItem`, Plan → Eingang | ✓ implementiert |
| **Epic** | `BacklogItem` `item_kind=epic` + `parent_backlog_id`-Baum | ○ ADP P2 — **nicht** RoadmapItem |
| **Story** | `BacklogItem` `item_kind=story` → Commit → `Action` | ✓ (ohne Epic-Parent) |
| Sprint | `RoadmapItem(type=work_cycle)` | ○ Katalog + AP2.0f |
| Sprint Goal | `work_cycle.title` + optional EFS `sprint_goal` | ○ |
| Sprint Backlog | `Action.work_cycle_id` | ○ AP2.0f |
@@ -235,6 +239,8 @@ Migration: `actions.work_cycle_id UUID NULL REFERENCES roadmap_items(id)` (AP2.0
| Velocity / Burndown | — | **explizit post-MVP** |
| Kanban-Board | — | **explizit nicht Kern** |
| Story Points | EFS optional | post-MVP |
| **Direct AP (ohne Backlog)** | `Action` direkt — Plan → Arbeit | ○ ADP P1 (Continuous) |
| **Agent Task-Baum** | `Task` unter `Action` | ◐ ADP Recursive Containers |
### 3.6 Explizit nicht im MVP-Kern (Anti-Scope)
@@ -0,0 +1,202 @@
# ADP — Backlog-Hierarchie, Dual Commit Path & Agile-Vollmodell v0.1
**Status:** PO-Freigabe (Dokumentation vor Implementierung)
**Stand:** 2026-07-26
**Autor:** Product / Architecture (Session PO 2026-07-26)
**Bezug:** Canonical OM v0.2, ADP Archetype Catalog v0.2 §3.4–3.5, SPEC B2b, SPEC-D `agile_iteration` / `continuous_product`, ADP Recursive Containers v0.1, Steering Kernel Spine
---
## 1. Problem
Kairo muss **zwei gleichwertige Commit-Pfade** unterstützen, ohne das Operating Model zu verwässern:
1. **Agile/Scrum (Jira-Vokabular):** Eingang mit Hierarchie (Epic → Story → Bug/Issue) → Sprint-Planung → committete Actions.
2. **Continuous / Programmentwicklung:** Ad-hoc-**Arbeitspakete** aus laufender Entwicklung (Erkenntnis, Spike, Nacharbeit) **ohne** Backlog-Umweg — nicht zwingend Bug.
**Ist-Zustand (MVP):** Global hardcodiert `story` / `bug` / `issue`; kein Epic; kein `parent_backlog_id`; Product-UI ohne direktes AP-Anlegen; Epic als Gate/Meilenstein wäre semantisch falsch.
**PO-Anforderung:** Agile-Volllogik dokumentieren und implementierbar machen; Continuous-Pfad explizit; Epic **nicht** als RoadmapItem; Kairo als **Program Director** für Agent-Steuerung (Actor-first, Kernel — nicht Prompt-Drift).
---
## 2. Betroffene Regeln
| Dokument | Regel |
|----------|--------|
| Canonical OM v0.2 | Plan (Backlog) vs. Ist (Action); Gates orthogonal |
| ADP Catalog §3.4 | BacklogItem ≠ Sprint-Backlog; Action.work_cycle_id = Sprint-Ist |
| ADP Catalog §3.5 | Agile-Begriffe — Epic fehlte |
| SPEC B2b | Eingang Pflicht-Kanal **für Triage**, nicht für jeden Commit |
| SPEC-D agile_iteration | Modifier — volle Sprint-Logik, keine Vorhaben-Natur |
| ADP Recursive Containers | Task-Hierarchie unter Action für Agent-Granularität |
| Steering Kernel | Leading = committete Action; Next/Attention in `backend/steering/` |
| Plugin-Architektur AP2.3/4 | Backlog-Typen methoden-/profilgebunden, keine Page-Ifs |
---
## 3. Entscheidung — Schichtmodell
### 3.1 Zwei Commit-Pfade (Dual Commit Path)
| Pfad | Wann | Flow | Leading nach Commit |
|------|------|------|---------------------|
| **A — Intake → Commit** | Geplante/große Arbeit, Refinement, Scrum | `BacklogItem` → triage → convert → `Action` | Primary + optional Sprint |
| **B — Direct Commit** | Ad-hoc aus Ist, Erkenntnis, Spike, Agent-Auftrag | `Action` direkt anlegen (optional Gate/Project) | Primary + optional Sprint |
Beide Pfade erzeugen dasselbe Ist-Objekt: **`Action` (Arbeitspaket)**.
Backlog ist **Plan-Eingang**, kein Ersatz für committete Arbeit.
**Guardrail:** Pfad B darf Pfad A nicht ersetzen müssen — UI muss **Plan → Arbeit** (direct AP) für Continuous-Profile anbieten (Product, Programm).
### 3.2 Backlog-Hierarchie (Agile / Jira)
Epic ist **Liefercontainer im Eingang**, kein Gate:
```text
BacklogItem (Plan-Eingang)
├── item_kind = epic parent_backlog_id = NULL
│ └── Story/Bug/Issue parent_backlog_id → Epic
└── optional roadmap_item_id (Gate-Orientierung — orthogonal)
Commit (convert):
Story → Action (action_kind=delivery)
Bug/Issue → Action (action_kind=bug|issue) + optional parent_action_id → Feature-AP
Sprint (Modifier agile_iteration):
Commit mit work_cycle_id → Action im Sprint-Backlog (Ist!)
```
**Epic-Fortschritt** = Roll-up aus committeten/erledigten Stories/Actions im Epic-Subbaum — **nicht** Gate-Status.
**Anti-Pattern (verboten):** Epic als `RoadmapItem` / Meilenstein modellieren — verschleiert Ausgangslage und Ist-Fortschritt.
### 3.3 Gates vs. Epics
| Konzept | Ebene | Zweck |
|---------|-------|-------|
| **Gate / RoadmapItem** | Plan-Horizont | Orientierung, Reife, Release-Rahmen |
| **Epic / BacklogItem** | Plan-Eingang | Lieferumfang, Zerlegung, Refinement |
| **Action** | Ist | Committete Ausführungseinheit |
| **Task** | Ist (sub) | Granularität, v. a. Agent-Schritte |
Epic kann **optional** ein Orientierungs-Gate referenzieren (`roadmap_item_id`) — ohne Epic = Gate zu ersetzen.
### 3.4 Vokabular — methoden-/profilgebunden
| Kontext | Backlog-Typen (UI/API) | Labels |
|---------|------------------------|--------|
| **Continuous Product** (Default B2b) | `idea`, `bug`, `incident` (Ziel) | Kairo Product Language |
| **Agile-Profil** (`agile_iteration` aktiv / Profil) | `epic`, `story`, `bug`, `issue` | Jira-nah |
| **MVP-Ist** | `story`, `bug`, `issue` | AP2.2e — Migration geplant |
Steuerung über **Methoden-Vertrag** / `method_profile_key` — nicht hardcodiert in Pages.
### 3.5 Agent-Steuerung (Program Director)
Kairo bleibt **Steuerungskern**; Agents sind **Actors**:
| Schicht | Verantwortung |
|---------|----------------|
| Kairo (Initiative, Kernel) | Scope, Plan/Ist, Next Action, Attention, Gates, Epic-Roll-up |
| Actor (Agent/Mensch) | Ausführung am committeten AP + Task-Baum |
| Nicht im Prompt | Roadmap, Sprint-Stand, Prioritäten — kommen aus Operating Context / Snapshot |
**Leading Work** für Mensch und Agent = **`Action`** (ggf. Sprint-gefiltert).
**Tasks** = Ausführungsgranularität (ADP Recursive Tasks); Steuerung bleibt auf Action-Ebene.
Ziel: Programmentwicklung **fast autark durch Kairo** steuerbar — Agents näher am Kern, weniger Drift durch Kontextfenster.
---
## 4. Optionen (Epic-Modellierung)
| Option | Beschreibung | Pro | Contra |
|--------|--------------|-----|--------|
| A | Epic = `RoadmapItem` | Bestehende Gate-UI | Falsche Semantik; kein Story-Roll-up |
| B | Epic = `BacklogItem` + `parent_backlog_id` | Plan/Ist-trennungskonform; Jira-parallel | Migration + Baum-UI nötig |
| C | Eigene Tabelle `epics` | Klare UI | Parallel-Welt; OM-Inflation |
**Empfehlung: Option B** — gleiche Entität `backlog_items`, erweiterte `item_kind` + `parent_backlog_id`.
---
## 5. Schema-Ziel (Implementierung — noch nicht geliefert)
```sql
-- Ziel-Migration (nummeriert, kein ad-hoc DDL in Routern)
ALTER TABLE backlog_items
ADD COLUMN parent_backlog_id UUID NULL REFERENCES backlog_items(id) ON DELETE SET NULL;
ALTER TABLE backlog_items DROP CONSTRAINT ...;
ALTER TABLE backlog_items ADD CONSTRAINT backlog_items_item_kind_check
CHECK (item_kind IN ('epic', 'story', 'bug', 'issue', 'idea', 'incident'));
-- Exact set profile-filtered in service layer
```
**Convert-Regeln:**
- `epic` → nicht direkt convertierbar (Container)
- `story` / `idea` → `Action` delivery
- `bug` / `issue` / `incident` → `Action` bug/issue + optional Feature-Referenz
- Beim Convert: `source_backlog_id` / Link Epic-Kette in Action-Metadaten oder `backlog_item_id` FK beibehalten für Roll-up
---
## 6. UI / IA (Ziel)
| Fläche | Continuous Product | Agile-Profil |
|--------|-------------------|--------------|
| Plan → Eingang | Triage, optional | Epic-Baum, Story-Refinement |
| Plan → Arbeit | **Direct AP** (Pfad B) | Sichtbar; oft nach Commit |
| Plan → Sprint | optional | Sprint-Planung aus Eingang |
| Labels | Idee, Bug, Störung | Epic, Story, Bug, Issue |
Product `planOutlineKeys` (Ziel): `profile`, `inbox`, `work`, `sprint`, `gates` — **work** ergänzen.
---
## 7. Implementierungsphasen (nach Doku)
| Phase | Inhalt | Abhängigkeit |
|-------|--------|--------------|
| **P0 — Doku** | ADP, Spec-Updates, Katalog §3.5 | ✓ diese ADP |
| **P1 — Direct AP** | Plan → Arbeit im Product-Profil; Product-Labels | UI only |
| **P2 — Backlog-Baum** | `parent_backlog_id`, `item_kind=epic` | Migration |
| **P3 — Profil-Vokabular** | Operating Context liefert erlaubte `backlog_item_kinds` | AP2.4 Erweiterung |
| **P4 — Epic Roll-up** | Read Model Fortschritt / Attention | Steering Kernel |
| **P5 — Agent-Tasks** | Task-Baum unter AP (ADP Recursive) | AP1.5d |
Kein Phase-Sprung ohne ADP/Spec-Referenz.
---
## 8. Risiko
| Risiko | Mitigation |
|--------|------------|
| Todo-Wand im Epic-Baum | Epic convertierbar nur als Container; Leading bleibt Action |
| Doppelte Wahrheit Backlog + Action | Convert markiert Backlog `converted`; Sprint nur auf Action |
| Jira-Kopie | Kein Story Points/Burndown im Kern; nur Steuerungs-Subset |
| Agent-Overload | Tasks unter AP; Kernel liefert ein Next pro Actor-Kontext |
---
## 9. Rückbaubarkeit
- `parent_backlog_id` nullable — flache Backlogs bleiben gültig
- `item_kind`-Erweiterung abwärtskompatibel (`story` Default)
- Direct-AP-Pfad optional pro Archetyp-UI-Profil abschaltbar
- Epic-Roll-up als Read Model — kein Pflichtfeld an Action
---
## 10. Referenzen
| Dokument | Pfad |
|----------|------|
| SPEC B2b Product | `docs/product/archetypes/SPEC_B2b_product_v0.1.md` |
| SPEC-D agile_iteration | `docs/architecture/methods/SPEC_D_agile_iteration_v0.1.md` |
| SPEC-D continuous_product | `docs/architecture/methods/SPEC_D_continuous_product_v0.1.md` |
| UI-Navigation | `docs/product/archetypes/ARCHETYPE_UI_NAVIGATION_v0.1.md` |
| Ist-Stand Backlog | Migration `026_sprint_planning_kinds.sql` |
+2
View File
@@ -16,3 +16,5 @@
| `generic_operating` | Primary (Ausführung, Fallback) | SPEC_D_generic_operating_v0.1.md | vorläufig freigegeben|
| `program_delivery` | Primary (**Meta**) | SPEC_D_program_delivery_v0.1.md | vorläufig freigegeben|
| `agile_iteration` | **Komposition** | SPEC_D_agile_iteration_v0.1.md | vorläufig freigegeben|
**Querschnitt:** [`../ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md`](../ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md) — Epic, Dual Commit, Agent-Steuerung
@@ -90,6 +90,44 @@ Elements: `work_cycle_scope`.
---
## D10b Backlog-Hierarchie & Jira-Abbildung (Agile-Vollmodell)
**Verbindlich:** [`ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md`](../ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md)
Diese Methode **aktiviert** das Scrum/Jira-Vokabular im Eingang — ersetzt nicht die Primary-Methode.
| Jira / Scrum | Kairo (Plan) | Kairo (Ist nach Commit) |
|--------------|--------------|---------------------------|
| Product Backlog | `BacklogItem` (Eingang) | — |
| Epic | `BacklogItem` `item_kind=epic`, Container | Roll-up über Stories/Actions |
| Story | `BacklogItem` `item_kind=story`, `parent_backlog_id` → Epic | `Action` `delivery` |
| Bug | `BacklogItem` `item_kind=bug` | `Action` `bug` (+ Feature-Ref) |
| Issue | `BacklogItem` `item_kind=issue` | `Action` `issue` (+ Feature-Ref) |
| Sprint | `RoadmapItem` `work_cycle` | Filter: `Action.work_cycle_id` |
| Sprint Backlog | — | committete Actions im Sprint (**keine** BacklogItems) |
**Regeln:**
- Epic ist **nicht** `RoadmapItem` / Meilenstein.
- Epic wird **nicht** direkt convertiert — nur Stories/Bugs/Issues darunter.
- Stories können **mehreren Epics** nicht zugeordnet sein (MVP: genau ein `parent_backlog_id`; n:m post-MVP).
- Ohne aktiven Sprint: Backlog-Hierarchie bleibt Plan; Leading = Primary Continuous/Sequential.
**MVP-Ist:** `story`/`bug`/`issue` ohne Epic/`parent_backlog_id` (AP2.2e). Volllogik = ADP Phase P2–P3.
---
## D10c Dual Commit Path (Primary + Agile)
| Pfad | Agile-Profil | Primary Continuous |
|------|--------------|-------------------|
| A Intake → Commit | Epic/Story → Sprint optional | Idee → Action |
| B Direct AP | erlaubt (Spike, Agent) | **Pflicht-Option** Plan → Arbeit |
`agile_iteration` verschärft Sprint-Scope; sie **erzwingt** nicht Pfad A für jedes AP.
---
## D12
| Punkt | PO ✓ |
@@ -98,6 +98,17 @@ Sprint: Action ∩ `work_cycle_id` des aktiven Sprints (Primary-Ready ∩ Agile-
**Leerer Fall ohne Sprint:** keine ready Action → Attention `planning_debt` / „Eingang triagieren oder committen“ — kein Closure-Druck.
### Dual Commit Path
Verbindlich: [`ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md`](../ADP_Backlog_Hierarchy_and_Dual_Commit_Path_v0.1.md)
| Pfad | Beschreibung |
|------|--------------|
| **A** | BacklogItem → convert → Action |
| **B** | Action direkt (Plan → Arbeit) — Continuous-Pflicht für B2b |
Direct AP ist gleichwertig, kein Anti-Pattern.
**Anti:** Sprint-Backlog als BacklogItem-Liste; Product-Backlog als B1-Checklisten-Vorhaben; leere Sprint-Sackgasse ohne aktiven Sprint; Closure erzwingen.
---