docs: Gate-Checkliste, Roadmap-Graph und Vision §6 präzisiert

Neues ADP für Checkliste, Graph Engine und Methodenprofile; sequenziell/parallel nur über Kanten.
Roadmap AP1.4b–4e; Vision und Canonical OM an PO-Richtung angeglichen.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-07-05 19:37:34 +02:00
1 parent fdda8a9fae
commit 0addcfb382
5 files changed
+261 -17

No files matched your search

@@ -70,7 +70,7 @@ Bestehende `milestones` → `roadmap_items` mit `legacy_milestone_id` oder One-s
| 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 |
| sequencing_mode | sequential / parallel / optional | ✓ default sequential — **⚠ deprecated AP1.4d:** nur noch Kanten/Graph |
| sort_order | int | |
### Dependencies
@@ -173,6 +173,8 @@ AP1.4 liefert das **generische Plan-Gerüst**. Konkrete Methoden (z. B. `product
**Nicht:** fest codierte „Meilenstein = lineare Software-Roadmap“-UI oder Dependency-Modell nur für WBS.
**Folge-ADP (PO 2026-07-05):** `ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md` — Checkliste, Graph Engine, Reopen, Methodenprofile; `sequencing_mode` am Item wird deprecated.
---
*Implementierung: `Kairo_Corrected_MVP_Roadmap_v0.2.md` AP1.4*
@@ -0,0 +1,198 @@
# ADP — Roadmap-Graph, Gate-Checkliste & Methodenprofile v0.1
**Status:** Entwurf — PO-Richtung 2026-07-05
**Stand:** 2026-07-05
**Bezug:** `ADP_RoadmapItem_and_Quality_Gate_Model_v0.1.md`, Vision v0.2 §9.1
**Ersetzt nicht:** AP1.4-Minimal (Schema 010/011) — **korrikt und erweitert** Zielbild
---
## Auslöser (PO)
Ein Meilenstein / Gate ist mehr als Status + Verify-Klick:
1. **Prüfplan / Checkliste** — Schritt für Schritt durchgehbar; später KI-prüfbar
2. **Volle Pflege** — bearbeiten, löschen (AP1.4: API teils, UI unvollständig)
3. **Reaktivierung** — versehentlich geschlossenes Gate wieder `active`
4. **Methodenvariabilität** — manche Methoden planen **gegen** Gates; andere messen **Erfüllungsgrad** oder leiten **Next Action** ab
5. **Baum-/Graphlogik** — sequenziell / parallel / optional **nicht am Item**, sondern in **Beziehungen** zu anderen Items
6. Daraus: **Roadblocker**, Attention, „ready vs. blocked“ — erstmals **Graph Engine** nötig
---
## Korrektur am AP1.4-Minimal (technische Schuld)
| AP1.4-Minimal | PO-Korrektur |
|---------------|--------------|
| `sequencing_mode` am `roadmap_item` | **Deprecated** — Semantik nur über Kanten |
| `definition_of_done` JSONB ohne UI | **GateChecklist** (strukturierte Kriterien) |
| `reached` terminal, kein Reopen | **Reopen** mit Audit (Decision oder explizite Aktion) |
| Verify = ein Evidence reicht | Verify = **Kriterienplan** erfüllt (Evidence pro Kriterium oder Sammel-Review) |
| Dependencies Tabelle minimal | **Graph Engine** wertet Kanten + Methodenprofil |
Migration 010/011 bleibt gültig; Erweiterung additiv (012+).
---
## Zielmodell
### 1. Gate-Checkliste (Prüfplan)
Strukturierte Kriterien pro `RoadmapItem` — nicht nur Freitext `goal_description`.
**Tabelle `roadmap_item_criteria`** (empfohlen statt nur JSONB):
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| id | uuid | |
| tenant_id, roadmap_item_id | uuid | |
| sort_order | int | Reihenfolge in der Checkliste |
| title | text | Prüfschritt |
| description | text | optional |
| criterion_kind | enum | `manual`, `evidence_required`, `review_required`, `metric` (später) |
| verification_hint | text | optional — für spätere KI („Was gilt als erfüllt?“) |
| status | enum | `open`, `satisfied`, `waived`, `failed` |
| satisfied_by_evidence_id | uuid | optional FK |
| satisfied_at | timestamptz | |
**Verify `→ reached` (neu):**
- Alle **Pflicht-Kriterien** `satisfied` oder `waived` (waive nur mit Decision)
- Oder explizite **gate_override** Decision (bestehend)
- Ein globales Evidence ohne Kriterienbezug reicht **nicht** mehr (Compat-Übergang: ein Kriterium „Gate allgemein“ migrieren)
**UI:**
- Plan-Detail / Modal: Checkliste pflegen, Schritt für Schritt abhaken
- Fortschritt: `3/7 Kriterien erfüllt` — Erfüllungsgrad für Methoden ohne harten Gate-Abschluss
### 2. Graph — Beziehungen statt Item-`sequencing_mode`
Kanten modellieren die **Baumlogik** (Forest pro Roadmap):
**Erweiterung `roadmap_item_dependencies` → `roadmap_item_edges`:**
| Feld | Typ |
|------|-----|
| from_item_id | uuid — abhängiges / untergeordnetes Item |
| to_item_id | uuid — Voraussetzung / Parent |
| edge_kind | `requires` (sequenziell), `parallel_group`, `optional_branch`, `blocks`, `related` |
| group_key | text optional — parallele Geschwister gleicher `group_key` |
| weight | optional — für Erfüllungsgrad |
**Semantik (Beispiele):**
```text
[Gate A]
/ | \
requires | optional_branch
/ | \
[Gate B] [Gate C] [Gate D optional]
\ | /
parallel_group (group_key: "phase-1")
|
[Gate E] requires all of B,C (+ D if taken)
```
- **Sequenziell:** Kante `requires`
- **Parallel:** gleiche `parallel_group` + gemeinsamer Parent / Join-Gate
- **Optional:** Kante `optional_branch` — Erfüllung zählt nicht für Join, unless committed
**`sequencing_mode` am Item:** nur noch Anzeige-Default / Migration; **nicht** für Engine-Logik.
### 3. Graph Engine (erstes Mal im Produkt)
**Ort:** `backend/steering/graph/` — keine parallele Logik in Routern oder Snapshot.
**Read Models (pro Initiative / Item):**
| Output | Nutzen |
|--------|--------|
| `blocked_items` | Voraussetzung nicht `reached` |
| `ready_items` | Alle `requires` erfüllt, Kriterien offen |
| `fulfillment_ratio` | satisfied criteria / total (Methoden: Reifegrad) |
| `derived_blockers` | AttentionItem „Gate X blockiert durch Y“ |
| `next_graph_action` | Methodenprofil: nächstes Gate oder nächstes offenes Kriterium |
**Kein Neo4j im MVP** — tenant-scoped Graph in PostgreSQL, Traversals in Python (AP1.4d), Cache optional später.
**Snapshot / Plan-UI** konsumieren Graph-Engine — nicht eigene Heuristiken.
### 4. Methodenprofile (Registry)
`steering_context.method_key` wählt **Graph-Strategie** (nicht Item-Felder):
| Profil | Plan-Verhalten | Ist-Verhalten |
|--------|----------------|---------------|
| `product_milestone_driven` | linearer/Join-Gate-Plan | Verify Checkliste → `reached` |
| `maturity_fulfillment` | parallele Stufen | **Erfüllungsgrad** sichtbar, kein Zwang `reached` |
| `generic_operating` | flacher Graph optional | Next Action aus offenen Kriterien |
| (später) | Content-Kapitel, Regelmäßigkeit | recurring + fulfillment |
Hooks in `backend/steering/methods/` — **keine** Sonder-Tabellen pro Methode.
### 5. Reaktivierung geschlossener Gates
**Regel:** `reached → active` (Reopen) nur mit:
- **Decision** `gate_reopen` mit Begründung, oder
- Capability-gated Admin-Aktion + Audit
Kriterien-Status: PO-Entscheidung — Option A: Kriterien bleiben `satisfied`; Option B: zurück auf `open` (empfohlen: **A**, Reopen dokumentiert Abweichung).
Verify-Historie bleibt in Audit / Journey (AP1.6).
### 6. Bearbeiten & Löschen
| Aktion | Regel |
|--------|--------|
| Bearbeiten Titel/DoD/Kriterien | solange nicht `discarded`; `reached` → nur mit Reopen |
| Löschen | nur `planned` oder mit Decision; Kanten mit-löschen |
| Status manuell | `reached`/`moved`/`discarded` nicht direkt (bestehend) |
Plan-UI: **Detail-Modal/Route** `/initiatives/:id/plan/items/:itemId` — Checkliste + Graph-Kontext read-only.
---
## KI (später, eingefroren bis Graph + Kriterien tragfähig)
- `verification_hint` + Evidence-Inhalt → Vorschlag `satisfied`
- Kein Auto-`reached` ohne Verify-Pfad
- Prompt/MCP bleiben hinter Gate-Checkliste + Graph Engine
---
## Paketierung (Vorschlag)
| Paket | Inhalt | Version |
|-------|--------|---------|
| **AP1.4b** | Plan-Item bearbeiten/löschen UI; Reopen-API; Checkliste CRUD (JSONB oder criteria Tabelle) | 0.13.1 |
| **AP1.4d** | Graph Engine v1; `edge_kind` + group_key; deprecate `sequencing_mode` in UI | 0.14.0 |
| **AP1.4e** | Verify gegen Kriterien; Erfüllungsgrad-Widget; derived Blockers in Attention | 0.14.1 |
| **AP1.6** | Journey: Checkliste Schritt-für-Schritt; Graph-Sicht (Baum, nicht Gantt) | 0.15.x |
**Nicht in AP1.4b:** volle Graph-Visualisierung, KI-Verify.
---
## Risiko
| Risiko | Mitigation |
|--------|------------|
| Graph over-engineered | Forest + 5 edge_kinds; kein beliebiger Graph |
| Breaking Verify | Compat: ein Default-Kriterium pro bestehendem Item |
| sequencing_mode Migration | Feld deprecated, Werte aus Edges backfill wo möglich |
---
## PO-Freigabe-Checkliste
- [ ] Kriterienplan statt „ein Evidence reicht“ (mit Compat-Übergang?)
- [ ] `sequencing_mode` am Item entfernen — nur Kanten
- [ ] Reopen-Regel (Decision vs. direkte Aktion)
- [ ] Erfüllungsgrad-Methoden ohne hartes `reached`
- [ ] Graph Engine in `backend/steering/graph/` — Scope Lock Erweiterung
---
*Implementierung nach Freigabe: Roadmap v0.2 AP1.4b–1.4e, Truth Table, Sprint Assignment.*