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

# ADP — RoadmapItem & Quality Gate Model v0.1

**Status:** Entwurf zur Freigabe  
**Stand:** 2026-07-05  
**Autor:** Product/Architecture (DOC Welle 2)  
**Vision:** `Kairo_Vision_and_Product_Direction_v0.2.md` §6  
**Paket:** AP1.4

---

## Problem

Die Tabelle `milestones` ist eine **MVP-Brücke** mit Titel, optionalem Text, Status-Dropdown — **kein Quality Gate**:

- kein prüfbares DoD-Modell
- keine Abhängigkeiten (sequenziell / parallel)
- kein Verify vor `reached`
- keine Plan-Ist-Verknüpfung zu Actions/Backlog
- irreführend in UI und Docs als „Meilenstein fertig“

Gleichzeitig verbietet Scope Lock (ADP AP1.0) neue OM-Tabellen **bis ADP** — dieses ADP ist die Freigabe für AP1.4.

---

## Betroffene Regel

- `Kairo_Canonical_Operating_Model_v0.2.md` §6–7  
- `Kairo_System_Target_State_v0.1.md` §12–13  
- `ADP_AP1_0_Steering_Foundation_Scope_Lock_v0.1.md` — Ausnahme AP1.4  
- AD-TA-08 (Milestone-Brücke → RoadmapItem Konsolidierung)

---

## Optionen

| Option | Kurzbeschreibung | Pro | Contra |
|--------|------------------|-----|--------|
| **A** | `milestones` erweitern (DoD JSON, deps) | Weniger Migration | Doppelmodell bleibt; widerspricht Target State |
| **B** | **Roadmap + RoadmapItem** neu; `milestones` migrieren | Kanonisches Modell; Gates; Dependencies | Migration; größerer Scope |
| **C** | Nur UI/DoD auf `milestones` | Schnell | Kein Roadmap; Plan/Ist unmöglich |

## Empfehlung

**Option B** — schmale erste Migration:

```text
roadmaps (1 pro Initiative initial)
roadmap_items
roadmap_item_dependencies
roadmap_item_criteria (DoD-Zeilen, optional Phase 1 nur JSONB)
```

`item_type` initial: `milestone`, `review_gate`, `maturity_stage`.

Bestehende `milestones` → `roadmap_items` mit `legacy_milestone_id` oder One-shot-Migration.

---

## Fachmodell (Minimal AP1.4)

### RoadmapItem

| Feld | Typ | Pflicht |
|------|-----|---------|
| id | uuid | ✓ |
| tenant_id, initiative_id, roadmap_id | uuid | ✓ |
| item_type | enum | ✓ |
| title | text | ✓ |
| goal_description | text | |
| definition_of_done | jsonb / criteria table | ◐ Phase 1: jsonb Liste |
| target_date | date | |
| status | planned/active/at_risk/reached/moved/discarded | ✓ |
| sequencing_mode | sequential / parallel / optional | ✓ default sequential |
| sort_order | int | |

### Dependencies

| Feld | Typ |
|------|-----|
| from_item_id | uuid |
| to_item_id | uuid |
| dependency_type | requires / blocks / related |

### Verknüpfung Ist → Plan

| Relation | Beschreibung |
|----------|--------------|
| `backlog_items.roadmap_item_id` | optional FK |
| `actions.roadmap_item_id` | optional FK |

### Gate-Verify

- Übergang `→ reached`: mindestens eine **Evidence** `accepted` ODER **Review** `completed` ODER explizite **Decision** `decided` mit Typ `gate_override`
- Übergang `→ moved/discarded`: **Decision** Pflicht

---

## API (Minimal)

```text
GET  /api/initiatives/:id/roadmap
GET  /api/initiatives/:id/roadmap/items
POST /api/initiatives/:id/roadmap/items
PATCH /api/roadmap-items/:id
POST /api/roadmap-items/:id/verify-reached
GET  /api/roadmap-items/:id/dependencies
POST /api/roadmap-items/:id/dependencies
```

Steering Snapshot: `upcoming_milestones` liest aus `roadmap_items` statt `milestones`.

---

## UI (Minimal)

- Unterseite **Plan** (`/initiatives/:id/plan`) — Liste + Gate-Detail-Route
- Initiative-**Übersicht**: Horizont aus RoadmapItems (read)
- Gate-Detail: DoD, Dependencies, Verify-Aktionen

**Nicht AP1.4:** Gantt, Drag-Drop-Graph (Tabelle reicht).

---

## Migration

1. Migration `010_roadmap_items.sql`  
2. Datenmigration `milestones` → `roadmap_items` (type=milestone)  
3. Deprecate `milestones` Router (410 + Link) oder View-Compat one release  
4. Drop `milestones` in `011` nach Compat-Periode  

---

## Risiko

| Risiko | Mitigation |
|--------|------------|
| Scope Creep | AP1.4 nur Minimal; kein Structure Builder |
| Breaking API | Compat-Layer one release |
| UI vor Schema | AP1.2c Plan-Shell vor AP1.4 Daten |

---

## Rückbaubarkeit

- `roadmap_items` isoliert; Rollback Migration 010  
- Milestone-Compat-View aus roadmap_items möglich  

---

## Auswirkung auf Sprint 0 / Scope Lock

**Erweitert Scope Lock** explizit für AP1.4. Keine anderen Tabellen ohne neues ADP.

---

## Freigabe-Checkliste PO

- [ ] Gate-Verify-Regel akzeptiert  
- [ ] item_type initial: milestone, review_gate, maturity_stage  
- [ ] milestones-Tabelle darf deprecated werden  
- [ ] AP1.4 nach AP1.2c  
- [ ] **Methodenneutralität:** Schema/UI nicht nur für sequenzielle Software-Gates  

---

## Methodische Neutralität (AP1.4)

AP1.4 liefert das **generische Plan-Gerüst**. Konkrete Methoden (z. B. `product_milestone_driven`, Reifegrad-Parallelpfade, Content-Kapitel) **registrieren sich** über:

- `item_type` + `sequencing_mode` auf RoadmapItem  
- `method_key` auf `steering_context` (bereits vorhanden)  
- später: Method-spezifische Verify-Policies, Structure Builder, Next-Action-Strategien  

**Nicht:** fest codierte „Meilenstein = lineare Software-Roadmap“-UI oder Dependency-Modell nur für WBS.

---

*Implementierung: `Kairo_Corrected_MVP_Roadmap_v0.2.md` AP1.4*