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:
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.*
|
||||
Reference in new issue
Block a user