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:
parent
fdda8a9fae
commit
0addcfb382
|
|
@ -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*
|
||||
|
|
|
|||
198
docs/architecture/ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md
Normal file
198
docs/architecture/ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md
Normal file
|
|
@ -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.*
|
||||
|
|
@ -95,8 +95,8 @@ Die Brücke ist **technisch nutzbar**, **fachlich unzureichend** für Gates und
|
|||
### Plan (Roadmap)
|
||||
|
||||
- Entwicklungsrichtung und **überprüfbare Zielpunkte**
|
||||
- RoadmapItems mit DoD, Abhängigkeiten, Terminen
|
||||
- Kann sequenziell, parallel oder gemischt sein
|
||||
- RoadmapItems mit DoD (Checkliste), Abhängigkeiten als **Graph**, Terminen
|
||||
- Sequenziell / parallel / optional = **Kantenlogik**, nicht Feld am Item
|
||||
|
||||
### Ist (Operativ)
|
||||
|
||||
|
|
@ -128,9 +128,10 @@ Typen (Auswahl): `milestone`, `maturity_stage`, `feature`, `review_gate`, `chapt
|
|||
|
||||
**Pflicht im Zielbild (nicht heute):**
|
||||
|
||||
- prüfbare Kriterien (DoD)
|
||||
- optional Abhängigkeiten
|
||||
- prüfbare Kriterien (DoD / **Checkliste**, Schritt für Schritt)
|
||||
- Abhängigkeiten als **Graph** zu anderen RoadmapItems (sequenziell / parallel / optional über Kanten)
|
||||
- Verifikation vor Status `reached`
|
||||
- Reopen nach versehentlichem Schließen (Decision-gated)
|
||||
|
||||
### Milestone (Product-Begriff)
|
||||
|
||||
|
|
|
|||
|
|
@ -136,7 +136,47 @@ Vorlage: `Sprint0_AP0_10_Validation_Report_v0.1.md`
|
|||
|
||||
**ADP:** `ADP_RoadmapItem_and_Quality_Gate_Model_v0.1.md`
|
||||
|
||||
**Version:** `0.13.0-ap1.4`
|
||||
**Version:** `0.13.0-ap1.4` — **Minimal geliefert**; Verify-Compat siehe 0.13.1.
|
||||
|
||||
---
|
||||
|
||||
### AP1.4b — Gate-Checkliste & Pflege (nächstes Plan-Paket)
|
||||
|
||||
**Ziel:** Prüfplan pro Gate; Item bearbeiten/löschen; Reopen nach versehentlichem Schließen.
|
||||
|
||||
| Scope | |
|
||||
|-------|--|
|
||||
| `roadmap_item_criteria` oder strukturiertes DoD |
|
||||
| Checkliste in Plan-Detail (Modal/Route) |
|
||||
| Reopen `reached → active` (Decision-gated) |
|
||||
| Verify gegen Kriterien (Compat: Default-Kriterium) |
|
||||
|
||||
**ADP:** `ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md`
|
||||
|
||||
**Version:** `0.13.1-ap1.4b`
|
||||
|
||||
---
|
||||
|
||||
### AP1.4d — Roadmap Graph Engine
|
||||
|
||||
**Ziel:** Sequenziell/Parallel/Optional nur über **Kanten**; erste Graph Engine in `backend/steering/graph/`.
|
||||
|
||||
| Scope | |
|
||||
|-------|--|
|
||||
| `edge_kind`, `parallel_group` auf Dependencies |
|
||||
| Deprecate `sequencing_mode` am Item (UI + Engine) |
|
||||
| Read Models: blocked, ready, fulfillment_ratio |
|
||||
| Attention/Blocker aus Graph ableiten |
|
||||
|
||||
**Version:** `0.14.0-ap1.4d`
|
||||
|
||||
---
|
||||
|
||||
### AP1.4e — Methodenprofile am Graph
|
||||
|
||||
Erfüllungsgrad-Methoden vs. Gate-Abschluss; Next Action aus Graph + Method Registry.
|
||||
|
||||
**Version:** `0.14.1-ap1.4e`
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -94,10 +94,11 @@ Zentrale Unterscheidung — fehlt im heutigen Produkt vollständig:
|
|||
PLAN (Roadmap) IST (Operativ)
|
||||
───────────────── ─────────────────
|
||||
RoadmapItem: Meilenstein/Gate Action: committete Arbeit
|
||||
├─ DoD / Kriterien ├─ Status, Assignments
|
||||
├─ Abhängigkeiten ├─ Blocker, Evidence
|
||||
├─ Zieltermin └─ Reviews
|
||||
└─ parallel | sequenziell
|
||||
├─ DoD / Kriterien (Checkliste) ├─ Status, Assignments
|
||||
├─ Kanten zu anderen Items ├─ Blocker, Evidence
|
||||
│ (sequenziell | parallel └─ Reviews
|
||||
│ | optional — Baumlogik)
|
||||
└─ Zieltermin
|
||||
│
|
||||
│ BacklogItem zahlt ein auf Plan
|
||||
▼
|
||||
|
|
@ -118,16 +119,18 @@ Ein Meilenstein im Sinne der Vision ist ein **Quality Gate**:
|
|||
|
||||
| Dimension | Anforderung |
|
||||
|-----------|-------------|
|
||||
| Definition | Titel, Ziel, **Definition of Done** (prüfbare Kriterien) |
|
||||
| Typ | sequenziell · parallel · optional (z. B. Reifegrade) |
|
||||
| Abhängigkeiten | `requires` / `blocks` zu anderen RoadmapItems |
|
||||
| Verifikation | Erreichen nur mit Evidence und/oder Review — nicht per Status-Dropdown |
|
||||
| Abweichung | `moved` / `discarded` → **Decision** mit Begründung |
|
||||
| Definition | Titel, Ziel, **Definition of Done** — **Checkliste / Prüfplan** (Schritt für Schritt; später KI-prüfbar) |
|
||||
| `item_type` | `milestone`, `review_gate`, `maturity_stage`, … — **kein** sequenzielles/paralleles Item-Attribut |
|
||||
| Graph / Baum | Sequenziell · parallel · optional nur über **Kanten und Gruppen** zu anderen RoadmapItems (Graph Engine in `steering/`) |
|
||||
| Abhängigkeiten | `requires` / `blocks` / `parallel_group` / `optional_branch` zwischen Items |
|
||||
| Verifikation | `reached` nur wenn **Kriterienplan erfüllt** (Evidence/Review pro Kriterium oder Policy) — nicht per Status-Dropdown |
|
||||
| Abweichung | `moved` / `discarded` → **Decision**; Reopen `reached → active` → **Decision** + Audit |
|
||||
| Bezug zur Arbeit | BacklogItems und Actions **zahlen ein** auf ein Gate |
|
||||
| Pflege | Bearbeiten, Löschen, Checkliste pflegen — auf Plan-Unterseite / Detail, nicht Omnibus-CRUD |
|
||||
|
||||
**Heute:** Tabelle `milestones` mit Titel, optionalem Text, Status — **MVP-Brücke**, kein Gate-Modell.
|
||||
|
||||
**Ziel:** `RoadmapItem` mit `item_type` (milestone, review_gate, maturity_stage, …) — siehe `Kairo_System_Target_State` §12–13.
|
||||
**Ziel:** `RoadmapItem` mit `item_type` (milestone, review_gate, maturity_stage, …) — siehe `Kairo_System_Target_State` §12–13. Folge-ADP: `ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md` (Checkliste, Graph Engine, Reopen).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -369,7 +372,7 @@ Kairo ist **kein** einzelnes PM- oder Software-Framework. Auf **allen Ebenen** k
|
|||
|-------|-------------------------|---------------------|
|
||||
| **Portfolio** | Priorisierung, Attention | Strategien in `steering/` (AP1.8) |
|
||||
| **Initiative / Programm** | Lifecycle, Signals, Next Action | `steering_context.method_key` |
|
||||
| **Plan** | Gate-Typen, Abfolge, DoD | `RoadmapItem.item_type`, `sequencing_mode`, Method-Hooks |
|
||||
| **Plan** | Gate-Typen, Abfolge, DoD | `RoadmapItem.item_type`, **Graph-Kanten**, Method-Hooks |
|
||||
| **Ist / Ausführung** | Hierarchie (WBS vs. flach), Commit-Regeln | Method-Profil + Structure Builder (später) |
|
||||
| **Verify / Review** | Was zählt als „erreicht“ | Evidence/Review-Policies pro Methode |
|
||||
| **Agenten / Vibe-Coder** | Empfohlene nächste Schritte | Operational API + gleiche Steering-Strategien |
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user