docs: Welle 2 — Roadmap v0.2, ADPs, AP1.2c Assignment
Deploy Development / deploy (push) Successful in 44s
Test Suite / pytest-backend (push) Successful in 1m23s
Test Suite / lint-backend (push) Successful in 1s
Test Suite / compose-smoke (push) Has been skipped
Test Suite / k6 /api/health Baseline (push) Successful in 18s
Test Suite / playwright-smoke (push) Successful in 12s

Corrected MVP Roadmap v0.2, Recovery Plan v0.2, Gap Analysis v0.2, Target State Implementation Map. ADPs für RoadmapItem/Quality Gates und Operational Actor Interface (Vibe-Coder). Handover v0.2 und Sprint-Auftrag AP1.2c IA-Skeleton.
This commit is contained in:
Lars committed 2026-07-05 18:17:25 +02:00
1 parent 8c31802662
commit 2796965aed
13 files changed
+1189 -15

No files matched your search

@@ -0,0 +1,201 @@
# ADP — Operational Actor Interface (Vibe-Coder) 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` §7.5
**Paket:** AP1.7
---
## Problem
Vibe-Coder und andere Agenten-Actors sollen Status melden, Next Action anfragen und Entscheidungsunterlagen ablegen — **ohne** UI und **ohne** Ad-hoc-Prompts.
Heute: Actors existieren (`actor_type=agent`), aber keine **definierte, auditierte API** für operative Arbeit. Gefahr: parallele Agent-Sonderlogik außerhalb `backend/steering/`.
---
## Betroffene Regel
- Canonical OM v0.2 §13 (Agenten-Regel)
- Scope Lock AP1.0 — Agent-Runtime eingefroren; **API-Oberfläche** ist erlaubt nach IA
- Tenant Invariants — Actor-first, Capability-gated
---
## Optionen
| Option | Kurzbeschreibung | Pro | Contra |
|--------|------------------|-----|--------|
| **A** | Bestehende REST-Endpoints + API-Keys pro Agent | Schnell | Uneinheitlich; fehlende Agent-Semantik |
| **B** | **`/api/operational/`** Namespace — dünne Fassade über Services + Steering | Klar, dokumentiert, auditierbar | Neues Router-Paket |
| **C** | MCP-only | Modern | Scope Lock; vorzeitig |
## Empfehlung
**Option B** — Operational API als **stabile Fassade** (AP1.7), intern ruft bestehende Services + `backend/steering/` auf.
Auth: Session oder **Actor Service Token** (Tenant-scoped, Capability-gebunden) — Detail in AP1.7 Implementierung.
---
## Endpoints (v0.1 Spec)
Basis: `/api/operational` — alle Requests mit Actor-Identität (nicht User impersonation ohne Audit).
### Kontext
```http
GET /api/operational/initiatives/{id}/context
```
→ Steering Snapshot + Lifecycle + Method (subset für Agenten).
### Next Action
```http
GET /api/operational/next-action?initiative_id=&limit=
```
→ `NextActionCandidate[]` für **aufrufenden Actor** via `backend/steering/strategies/next_action/`.
### Arbeitspaket (Action)
```http
GET /api/operational/actions/{id}
PATCH /api/operational/actions/{id}/status
{ "status": "in_progress", "note": "..." }
POST /api/operational/actions/{id}/assignments
{ "actor_ids": ["..."] }
```
Capabilities: `kairo.action.read`, `kairo.action.manage`.
### Blocker
```http
POST /api/operational/blockers
{ "initiative_id", "action_id?", "title", "description?" }
PATCH /api/operational/blockers/{id}
{ "status": "resolved" }
```
Capability: `kairo.blocker.manage`.
### Evidence
```http
POST /api/operational/evidence
{ "initiative_id", "action_id?", "roadmap_item_id?", "title", "body?" }
```
Capability: `kairo.evidence.manage`.
### Decision-Unterlage
```http
POST /api/operational/decisions/proposals
{
"initiative_id",
"title",
"rationale",
"evidence_ids": [],
"proposed_status": "proposed"
}
```
Erzeugt Decision `proposed` + verknüpfte Evidence — **kein** auto-`decided`.
Capability: `kairo.decision.manage`.
### Backlog-Vorschlag
```http
POST /api/operational/backlog/proposals
{ "initiative_id", "title", "description?", "roadmap_item_id?" }
```
Status `new` — kein Auto-Convert zu Action.
Capability: `kairo.backlog.manage`.
### Explizit nicht in v0.1
- Gate `reached` setzen
- Initiative Lifecycle ändern
- Method wechseln
- Portfolio-Priorität
---
## Response-Konvention
```json
{
"ok": true,
"data": { },
"actor_id": "uuid",
"audit_ref": "uuid optional"
}
```
Fehler: HTTP 403 Capability, 404 Tenant-Isolation, 422 Validation.
---
## Audit
Jeder mutierende Call:
- `audit_log`: actor_id, action, resource_type, resource_id, payload_hash
- Agent-Runs später korrelierbar (`agent_run_id` optional header)
---
## UI-Äquivalenz
| API | UI-Ort |
|-----|--------|
| context | Initiative-Übersicht |
| next-action | Next-Action-Widget |
| action status | Ausführung / Action-Detail |
| blockers/evidence | Action-Detail / Unterseiten |
| decision proposals | Entscheidungen-Unterseite |
---
## Implementierungsreihenfolge
1. AP1.2c — IA steht
2. AP1.7a — Read-only: context, next-action, get action
3. AP1.7b — Mutations: status, blockers, evidence, proposals
4. AP1.7c — Actor Service Token Auth (wenn Session nicht reicht)
---
## Risiko
| Risiko | Mitigation |
|--------|------------|
| Agent umgeht Gate-Verify | Endpoint-Whitelist; kein gate reached |
| Token-Leak | Tenant-scoped, rotierbar, minimal capabilities |
| Duplikat-Logik | Fassade nur — Services/steering unverändert |
---
## Rückbaubarkeit
Router `/api/operational` entfernbar ohne Domänenänderung.
---
## Freigabe-Checkliste PO
- [ ] Endpoint-Liste ausreichend für Vibe-Coder-Handover
- [ ] Proposals statt Auto-Commit akzeptiert
- [ ] AP1.7 nach AP1.2c
---
*Handover: `Sprint0_Vibe_Coder_Handover_v0.2.md`*
@@ -0,0 +1,165 @@
# 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:
```text
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)
```text
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
---
*Implementierung: `Kairo_Corrected_MVP_Roadmap_v0.2.md` AP1.4*
@@ -0,0 +1,96 @@
# Jinkendo Kairo
## Current State & Gap Analysis v0.2
**Status:** Gap-Analyse (living document)
**Stand:** 2026-07-05 (nach AP1.1b + DOC Welle 1)
**Ersetzt für Ist-Stand:** `Kairo_Current_State_Gap_Analysis_AP0.1_AP0.6b_v0.1.md`
**Detail-Tabelle:** `Kairo_Implementation_Truth_Table_v0.1.md`
---
## 1. Zweck
Ordnet **Implementierungsstand** gegen **Vision v0.2** ein — nicht gegen veraltetes „Milestone minimal = fertig“.
---
## 2. Was seit v0.1 dazugekommen ist
| Paket | Geliefert | Produktwert |
|-------|-----------|-------------|
| AP0.7 | Tenant-Invarianten, Actor Directory, Data Layer | ✓ tragfähig |
| AP0.8–0.9 | OM-Tabellen + CRUD-APIs + Workspace Attention | ◐ Inventar |
| AP0.10b | NextAction/Heute-Widgets, Snapshot v2 | ◐ Workspace |
| AP1.0 | steering_contexts, Lifecycle, Signals | ◐ Backend |
| AP1.1 | Method Registry, product_milestone_driven | ◐ |
| AP1.1b | InitiativeDetail Action-Hub | ◐ falsches IA-Pattern |
| DOC W1 | Vision v0.2, Canonical OM v0.2, Truth Table | ✓ Richtung |
---
## 3. Gap-Matrix (Vision v0.2)
| Konzept | Technisch | Produkt (Alltag) | Nächstes Paket |
|---------|-----------|------------------|----------------|
| Tenant / Actor / Capabilities | ✓ | ✓ | — |
| Initiative | ✓ | ◐ | AP1.2c Übersicht |
| Action (Arbeitspaket) | ✓ | ◐ | AP1.2c Detail-Route |
| Backlog / Blocker / Evidence / Decision / Review | ✓ API | ◐ CRUD-Wand | AP1.2c Unterseiten |
| Milestone | ◐ Tabelle | ✗ kein Gate | AP1.4 |
| RoadmapItem | ✗ | ✗ | AP1.4 |
| Plan vs. Ist | ✗ | ✗ | AP1.4–AP1.6 |
| Steering / Lifecycle | ◐ | ◐ Snapshot | AP1.2 |
| NextAction | ◐ API | ◐ Widget | AP1.2c konfigurierbar |
| Portfolio-Priorität | ✗ | ✗ | AP1.8 |
| Situativer Kontext | ✗ | ✗ | AP1.8 |
| IA Workspace Portfolio | ✗ | ✗ | AP1.2c |
| IA Initiative-Übersicht | ✗ | ✗ | AP1.2c |
| IA Unterseiten | ✗ | ✗ | AP1.2c |
| Modal/Detail-Bearbeitung | ✗ | ✗ | AP1.2c |
| Operational Actor API | ✗ | ✗ | AP1.7 |
| Project / Task | ○ / ✗ | ✗ | AP1.5 |
| Journey | ✗ | ✗ | AP1.6 |
---
## 4. Dokumenten-Gap (behoben / offen)
| Gap | Status |
|-----|--------|
| Zielbild vs. Ist vermischt | ◐ Welle 1 ✓, Welle 2 ◐ |
| Roadmap suggerierte falsche Nähe zum Ziel | ◐ Roadmap v0.2 ✓ |
| Kein Gate-ADP | ◐ Welle 2 |
| Kein Agent-Interface-ADP | ◐ Welle 2 |
| Target State ohne Implementierungs-Marker | ◐ Implementation Map v0.2 |
---
## 5. Zwingende nächste Schritte
1. **DOC Welle 2 abschließen** (ADPs, Handover)
2. **AP1.2** — `operating_phase` entfernen
3. **AP1.2c** — IA-Skeleton (größter Produkt-Hebel)
4. **AP0.10d** — Validation mit neuen Fragen
5. **AP1.4** — nur nach PO-Go
---
## 6. Risiko bei Verzögerung von IA
Ohne AP1.2c:
- weitere Features landen auf Omnibus-Seite
- Vibe-Coder bekommen keine klare API-Oberfläche
- Gate-Migration (AP1.4) baut auf falscher Navigation auf
---
## 7. Empfehlung
**Kein** AP1.1c, kein weiteres InitiativeDetail-Layout.
**Ja:** Welle 2 Docs → AP1.2 → AP1.2c in einem Sprint-Fokus.
---
*v0.1 Gap-Matrix (AP0.6b) historisch — viele „fehlt“-Zeilen sind inzwischen API-erledigt, aber produktlich unzureichend.*
@@ -0,0 +1,73 @@
# Kairo System Target State — Implementation Map v0.2
**Status:** Ergänzung zu Target State v0.1
**Stand:** 2026-07-05
**Zielbild-Inhalt:** unverändert in `Kairo_System_Target_State_v0.1.md`
**Ist-Detail:** `Kairo_Implementation_Truth_Table_v0.1.md`
---
## Legende
| Status | Bedeutung |
|--------|-----------|
| **target** | Nur dokumentiert — Zielbild |
| **partial** | Anfang implementiert, Vision nicht erfüllt |
| **done** | Für MVP-Ausschnitt ausreichend |
| **n/a** | Bewusst später (Phase C+) |
---
## Kapitel-Mapping (Target State v0.1)
| § | Thema | Status | Anmerkung |
|---|-------|--------|-----------|
| 1 | Executive Summary | target | Leitfrage ✓ in Steering |
| 2 | Grundverständnis | target | — |
| 3 | Produktidentität | partial | Program Director dokumentiert, UI To-do-artig |
| 4 | Kernmodell | partial | Initiative/Action ✓; Roadmap ✗ |
| 5 | Steering Core | partial | AP1.0 Skeleton |
| 6 | Standard Lifecycle | partial | steering_contexts ✓; Hooks stub |
| 7 | Steering Methods | partial | 2 Methoden registriert |
| 8 | Method Registry | partial | Registry ✓; kein Designer |
| 9 | Steering Domains | target | — |
| 10 | Steerable Objects | partial | OM-Tabellen, nicht RoadmapItem |
| 11 | Steering Context | done | Migration 009 |
| 12 | Roadmap / Development Model | target | Milestone-Brücke only |
| 13 | Roadmap vs Backlog vs Action | target | Konzept ✗ in UI |
| 14 | Structure Builder | n/a | Phase C+ |
| 15 | Hooks | partial | Stub AP1.0 |
| 16 | Strategies | partial | next_action strategies minimal |
| 17 | Signals | partial | AP1.0; AP1.2 konsolidieren |
| 18 | Assignment / Waiting / Reminder | partial | Assignment ✓; Rest n/a |
| 19 | Evidence / Review / Decision | partial | CRUD ✓; Gate-Verify ✗ |
| 20 | Workflow-Fragmente | n/a | eingefroren |
| 21 | Agenten / LLMs / Tools | partial | Actors ✓; AP1.7 API ✗ |
| 22 | Security / Governance / Audit | partial | Auth/Cap ✓ |
| 23 | UI-Zielbild | target | Vision §7; AP1.2c |
| 24 | Architektur-Evolutionslinie | target | Roadmap v0.2 |
| 25 | Zielzustand Satz | target | — |
---
## UI-Zielbild (§23) — Detail-Mapping Vision §7
| Vision-Element | Target State | Implementierung |
|----------------|--------------|-----------------|
| Workspace Portfolio | §23 | ✗ → AP1.2c |
| Initiative-Übersicht | §23 | ✗ → AP1.2c |
| Unterseiten Plan/Ausführung/… | §23 | ✗ → AP1.2c |
| Next-Action-Widget konfigurierbar | §16–17 | ◐ → AP1.2c |
| Roadmap/Gates UI | §12–13 | ✗ → AP1.4 |
| Journey | §19 | ✗ → AP1.6 |
| Agent Interface | §21 | ✗ → AP1.7 |
---
## Nächste Status-Updates
Nach jedem AP diese Map + Truth Table aktualisieren.
---
*Vollständiges Zielbild weiterhin: `Kairo_System_Target_State_v0.1.md`*