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:

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)

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