From 0addcfb3829efd89520a5c7e86776ed21c013f34 Mon Sep 17 00:00:00 2001 From: Lars Date: Sun, 5 Jul 2026 19:37:34 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Gate-Checkliste,=20Roadmap-Graph=20und?= =?UTF-8?q?=20Vision=20=C2=A76=20pr=C3=A4zisiert?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...RoadmapItem_and_Quality_Gate_Model_v0.1.md | 4 +- ...P_Roadmap_Graph_and_Gate_Checklist_v0.1.md | 198 ++++++++++++++++++ .../Kairo_Canonical_Operating_Model_v0.2.md | 9 +- .../Kairo_Corrected_MVP_Roadmap_v0.2.md | 42 +++- ...Kairo_Vision_and_Product_Direction_v0.2.md | 25 ++- 5 files changed, 261 insertions(+), 17 deletions(-) create mode 100644 docs/architecture/ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md diff --git a/docs/architecture/ADP_RoadmapItem_and_Quality_Gate_Model_v0.1.md b/docs/architecture/ADP_RoadmapItem_and_Quality_Gate_Model_v0.1.md index e26a46e..8557bbf 100644 --- a/docs/architecture/ADP_RoadmapItem_and_Quality_Gate_Model_v0.1.md +++ b/docs/architecture/ADP_RoadmapItem_and_Quality_Gate_Model_v0.1.md @@ -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* diff --git a/docs/architecture/ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md b/docs/architecture/ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md new file mode 100644 index 0000000..e490c18 --- /dev/null +++ b/docs/architecture/ADP_Roadmap_Graph_and_Gate_Checklist_v0.1.md @@ -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.* diff --git a/docs/product/Kairo_Canonical_Operating_Model_v0.2.md b/docs/product/Kairo_Canonical_Operating_Model_v0.2.md index a3962f1..0755fa4 100644 --- a/docs/product/Kairo_Canonical_Operating_Model_v0.2.md +++ b/docs/product/Kairo_Canonical_Operating_Model_v0.2.md @@ -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) diff --git a/docs/product/Kairo_Corrected_MVP_Roadmap_v0.2.md b/docs/product/Kairo_Corrected_MVP_Roadmap_v0.2.md index 111b449..a88e3dc 100644 --- a/docs/product/Kairo_Corrected_MVP_Roadmap_v0.2.md +++ b/docs/product/Kairo_Corrected_MVP_Roadmap_v0.2.md @@ -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` --- diff --git a/docs/product/Kairo_Vision_and_Product_Direction_v0.2.md b/docs/product/Kairo_Vision_and_Product_Direction_v0.2.md index 763c689..def9453 100644 --- a/docs/product/Kairo_Vision_and_Product_Direction_v0.2.md +++ b/docs/product/Kairo_Vision_and_Product_Direction_v0.2.md @@ -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 |