AP0.8: Operating Model Extension I (Attention, Blocker, Backlog, Milestone)
Deploy Development / deploy (push) Successful in 45s
Test Suite / pytest-backend (push) Successful in 58s
Test Suite / lint-backend (push) Successful in 2s
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

Schema 007, regelbasierte Attention/NextAction im Data Layer, CRUD fuer Blocker/Backlog/Meilensteine, Workspace-Widget und Initiative-Detail-Sektionen. 25 Capabilities. Tests fuer Remote-Pytest auf Pi angepasst (conftest Session-Guard).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-07-05 15:11:15 +02:00
1 parent 6dd9dd4f62
commit fe3bc4f057
39 files changed
+4333 -22

No files matched your search

@@ -0,0 +1,808 @@
# Kairo – System Target State
## v0.1 – Zielzustand des angedachten Gesamtsystems
**Status:** konsolidiertes Zielbild / Nordstern-Dokument
**Stand:** 2026-07-05
**Zweck:** Beschreibung des angedachten späteren Zielzustands von Kairo als System, unabhängig von konkreten Implementierungsschnitten.
---
## 1. Executive Summary
Kairo ist langfristig keine einfache Aufgabenliste, keine reine Projektmanagement-App, kein Roadmap-Tool und keine freie Workflow-Automatisierungsplattform.
Kairo ist eine:
```text
adaptive, methodengeführte Entwicklungs- und Steuerungsplattform
```
Der Kern ist ein:
```text
Method-driven Adaptive Steering Core
```
Kairo soll unterschiedliche Entwicklungs- und Steuerungskontexte führen können:
```text
- Software- und Produktentwicklung
- Buch- und Content-Entwicklung
- Programmsteuerung
- Projekt- und Initiativensteuerung
- persönliche Entwicklung
- Reifegradentwicklung
- Lernpfade
- Routinen / Betrieb
- Review- und Auditkontexte
- Agentenläufe
- KI-/Tool-gestützte Steuerung
```
Die zentrale Leitfrage lautet:
```text
Welcher nächste Schritt bringt diesen steuerbaren Kontext jetzt am wirksamsten voran?
```
---
## 2. Grundverständnis
Kairo steuert nicht nur Aufgaben.
Kairo steuert Entwicklungen.
Eine Entwicklung kann sein:
```text
- ein Produkt
- ein Programm
- ein Projekt
- eine Initiative
- ein Buch
- eine Fähigkeit
- ein Reifegradziel
- eine Routine
- ein Review
- ein Audit
- ein Agentenauftrag
```
Kairo hält dabei fest:
```text
- Was soll entwickelt werden?
- Warum ist es relevant?
- Welche Methode gilt?
- Welche Struktur braucht diese Methode?
- Wo steht der Kontext aktuell?
- Was fehlt?
- Was blockiert?
- Was braucht Aufmerksamkeit?
- Was ist der nächste wirksame Schritt?
- Wer oder welcher Agent soll handeln?
- Worauf wartet Kairo?
- Welche Nachweise, Reviews oder Entscheidungen sind nötig?
- Wann wird angepasst, eskaliert oder abgeschlossen?
```
---
## 3. Produktidentität
Kairo ist:
```text
System of Record
Steering Authority
Actor-/Tenant-sicherer Kontextgeber
methodengeführter Steuerungskern
Roadmap- und Entwicklungsstrukturmodell
Signal- und NextAction-System
später Workflow-/Agenten-/Tool-orchestrierend
```
Kairo ist nicht:
```text
freie Workflow-Plattform
beliebiger Automatisierungsbaukasten
reines Projektmanagementsystem
reine To-do-Liste
reines Roadmap-Tool
reine KI-Agentenplattform
reines Prompt-System
```
---
## 4. Kernmodell
Das Zielmodell:
```text
Steerable Object
→ Steering Context
→ Steering Method
→ Standard Lifecycle / Method Lifecycle
→ Hook Slugs
→ Structure Builder
→ Signal Rules
→ NextAction Strategy
→ Assignment Strategy
→ Waiting / Reminder / Escalation Strategy
→ Result Intake
→ Evidence / Review / Decision
→ Adaptation / Closure
→ optionale Workflow-Fragmente
→ optionale Human / Agent / LLM / Tool Steps
```
---
## 5. Method-driven Adaptive Steering Core
Der Adaptive Steering Core ist der fachliche und technische Kern von Kairo.
Er führt steuerbare Kontexte durch methodengeführte Steuerungsabläufe.
Typischer Ablauf:
```text
1. Ziel / Entwicklungsabsicht erfassen
2. Name, Scope und Kontext definieren
3. passende Basismethode wählen oder vorschlagen
4. gemäß Methode eine Steuerungsstruktur erzeugen
- Roadmap
- Backlog
- WBS
- Reifegradpfad
- Kapitelstruktur
- Feature Landscape
- WorkCycles
- Review Gates
5. Next Best Action ableiten
6. Actor zuweisen
7. auf Ergebnis, Rückmeldung, Termin oder Ereignis warten
8. erinnern, eskalieren oder nachsteuern
9. Ergebnis zurückführen
10. prüfen, reviewen, adaptieren oder abschließen
```
Dieser Ablauf ist der methodengeführte Steuerungsworkflow.
Er ist nicht gleichbedeutend mit einer freien technischen Workflow Engine.
---
## 6. Standard Lifecycle
Kairo besitzt einen minimalen Standard Lifecycle als gemeinsame Basis.
```text
intake
method_selection
structure_setup
planning
action_selection
assignment
waiting
result_intake
validation
review
adaptation
closure
```
Methoden können diesen Lifecycle:
```text
- verwenden
- teilweise überspringen
- spezialisieren
- erweitern
- eigene Hooks ergänzen
```
Der Standard Lifecycle ist kein starrer Projektprozess, sondern ein gemeinsames Steuerungsraster.
---
## 7. Steering Methods
Eine Methode ist kein Label, sondern ein registriertes Steuerungspaket.
Eine Methode definiert:
```text
- supported_domains
- supported_scope_types
- default_lifecycle
- required_structures
- allowed_structures
- hook_slugs
- structure_builders
- attention_rule_providers
- next_action_strategy
- assignment_strategy
- waiting_strategy
- reminder_strategy
- escalation_strategy
- result_intake_strategy
- review_strategy
- evidence_policy
- closure_policy
- allowed_workflow_fragments
- allowed_node_types
- default_configuration
```
Methoden werden zunächst built-in und code-first angelegt, später versioniert und begrenzt konfigurierbar.
Langfristig können Method Profiles entstehen.
---
## 8. Method Registry
Kairo benötigt eine Method Registry.
Sie funktioniert ähnlich einem Widget-System:
```text
Eine Methode meldet sich mit Slug, Version, unterstützten Domains,
Lifecycle, Hooks, Structure Builders, Strategies und Policies an.
```
Ziel:
```text
Neue Methoden sollen ergänzt werden können,
ohne den Core jedes Mal umzubauen.
```
Beispiele für Methoden:
```text
simple_action_driven
product_milestone_driven
backlog_driven
wbs_driven
cycle_based
content_chapter_based
maturity_progression
routine_control
review_driven
audit_driven
agent_controlled
```
---
## 9. Steering Domains
Kairo unterstützt unterschiedliche Steuerungsdomänen.
Beispiele:
```text
program
project
product_development
content_development
personal_development
maturity_development
routine_operations
audit_review
agent_execution
custom
```
Jede Domain kann eigene typische Lifecycles, Roadmap-Strukturen, Methoden, Hooks und Signals haben.
---
## 10. Steerable Objects
Steuerbar sind nicht nur Initiativen.
Mögliche steuerbare Objekte:
```text
program
initiative
project
roadmap
roadmap_item
backlog_item
action
blocker
review
evidence
decision
recurring_element
work_cycle
agent_run
custom
```
Diese Objekte werden über Steering Contexts an Methoden und Domains gebunden.
---
## 11. Steering Context
Ein Steering Context beschreibt:
```text
Für welches steuerbare Objekt gilt welche Methode, Domain und Lifecycle-Logik?
```
Konzeptuell:
```text
SteeringContext
- tenant_id
- scope_type
- scope_id
- steering_domain
- lifecycle_model
- steering_method
- method_profile_id optional
- method_version
- configuration_json
- inherits_from_parent
- is_active
```
Untergeordnete Objekte können den Steering Context ihres Parents erben oder überschreiben.
---
## 12. Roadmap / Development Model
Roadmap ist ein Kernmodell, nicht nur eine UI-Ansicht.
Kairo braucht Roadmaps, um Entwicklungsrichtung und Entwicklungsstruktur abzubilden.
Roadmap-Struktur:
```text
Roadmap
→ Roadmap Lane
→ Roadmap Item
```
RoadmapItems können sein:
```text
milestone
maturity_stage
feature
capability
phase
release
chapter
research_topic
work_cycle
learning_step
review_gate
decision_gate
architecture_step
dependency
risk_reduction
custom
```
Entscheidung:
```text
Milestone = RoadmapItem(type = milestone)
```
---
## 13. Roadmap vs. Backlog vs. Action
Zentrale Unterscheidung:
```text
RoadmapItem = Entwicklungsziel / Orientierung / geplanter Entwicklungsschritt
BacklogItem = konkreter möglicher Handlungsbedarf
Action = freigegebene operative Maßnahme
```
Beispiel Softwareentwicklung:
```text
RoadmapItem:
Attention Engine regelbasiert
BacklogItems:
- Attention DTO definieren
- Blockierte Maßnahmen auswerten
- Widget bauen
Actions:
- Endpoint implementieren
- Tests schreiben
```
Beispiel Buchentwicklung:
```text
RoadmapItem:
Kapitel 3 – Argumentation ausarbeiten
BacklogItems:
- Recherche zur These prüfen
- Beispiel suchen
- Rohfassung schreiben
Actions:
- Heute Abschnitt 3.1 entwerfen
```
Beispiel Reifegradentwicklung:
```text
RoadmapItem:
Reifegrad: stabile Seitkick-Beweglichkeit
BacklogItems:
- Hüftmobilität prüfen
- Dehnroutine auswählen
- Technikvideo aufnehmen
Actions:
- 10 Minuten Mobility durchführen
```
---
## 14. Structure Builder
Structure Builder erzeugen methodenspezifische Steuerungsstrukturen.
Beispiele:
```text
roadmap_builder
milestone_plan_builder
feature_landscape_builder
wbs_builder
backlog_builder
maturity_path_builder
chapter_structure_builder
cycle_structure_builder
review_gate_builder
routine_structure_builder
```
Sie sind zentrale Erweiterungspunkte für Methoden.
Ein Structure Builder legt z. B. an:
```text
- Roadmap
- Roadmap Lanes
- Roadmap Items
- initiale BacklogItems
- Review Gates
- WorkCycles
```
---
## 15. Hooks
Hooks sind stabile Einhängepunkte in Steuerungsabläufen.
Beispiele:
```text
on_goal_captured
on_scope_named
on_method_selection_required
on_method_selected
on_structure_required
on_roadmap_required
on_backlog_required
on_wbs_required
on_maturity_path_required
on_content_structure_required
on_plan_required
on_dependency_analysis_required
on_dod_definition_required
on_next_action_requested
on_assignment_required
on_wait_started
on_due_date_reached
on_result_overdue
on_reminder_required
on_escalation_required
on_result_received
on_evidence_required
on_review_due
on_reassessment_required
on_replan_required
on_closure_requested
```
An Hooks können später kleine Workflow-Fragmente, Rules, Prompts, Agent Steps oder Tool Steps gebunden werden.
Hooks sind nicht beliebige technische Events, sondern fachlich stabile Steuerungspunkte.
---
## 16. Strategies
Methoden bringen oder referenzieren Strategies.
Zentrale Strategy-Typen:
```text
NextActionStrategy
AttentionRuleProvider
AssignmentStrategy
WaitingStrategy
ReminderStrategy
EscalationStrategy
ResultIntakeStrategy
EvidencePolicy
ReviewStrategy
ClosurePolicy
```
Diese verhindern, dass methodenspezifische Logik monolithisch im Core wächst.
---
## 17. Signals
Signals sind sichtbare Ausgaben des Steuerungskerns.
Signal Types:
```text
attention
next_action
review_due
evidence_required
escalation
blocker_signal
progress_signal
risk_signal
decision_required
dependency_signal
dod_signal
workflow_trigger
```
### Attention
Beantwortet:
```text
Was braucht Aufmerksamkeit?
```
### NextActionCandidate
Beantwortet:
```text
Was ist der nächste wirksame Schritt?
```
Signals müssen erklärbar sein:
```text
- warum erzeugt?
- durch welche Methode?
- durch welchen Hook?
- auf welchen Scope bezogen?
- welche Datenquelle?
- welche empfohlene Handlung?
```
---
## 18. Assignment / Waiting / Reminder / Escalation
Der Steuerungskern endet nicht mit dem Erzeugen einer Action.
Kairo muss steuern:
```text
- Actor auswählen
- Actor zuweisen
- auf Ergebnis warten
- Fälligkeit überwachen
- erinnern
- eskalieren
- externe Ereignisse aufnehmen
- Agentenergebnisse zurückführen
```
Actors können sein:
```text
human
agent
working_group
external_system
```
---
## 19. Result Intake / Evidence / Review / Decision
Kairo führt Ergebnisse zurück und entscheidet, was daraus folgt.
Mögliche Rückführungen:
```text
- Action erledigt
- Ergebnis unvollständig
- Evidence erforderlich
- Review erforderlich
- Decision erforderlich
- Blocker entstanden
- RoadmapItem erreicht
- Reifegrad plausibel erhöht
- neue NextAction nötig
```
Evidence, Reviews und Decisions sind zentrale Qualitätssicherungs- und Steuerungsobjekte.
---
## 20. Workflow-Fragmente und Runtime
Kairo soll langfristig Workflow-Fähigkeit haben.
Aber:
```text
Workflows sind methodengeführte Steuerungsabläufe,
keine beliebige freie Automatisierungsplattform als Produktkern.
```
Zielmodell:
```text
Hook
→ Workflow Fragment
→ Node / Step
→ Result
→ Rückführung in Kairo
```
Workflow-Fragmente können später enthalten:
```text
human_task
approval
decision_gate
review
reflection
llm_prompt
agent_task
tool_call
state_transition
evidence_check
dod_check
dependency_analysis
notification
reminder
escalation
```
---
## 21. Agenten / LLMs / Tools
Kairo bleibt Steering Authority.
Agenten, LLMs und Tools sind Provider.
Sie können später an Hooks und Workflow-Fragmente angebunden werden.
Grundsatz:
```text
Kairo entscheidet Kontext, Methode, Auftrag und Rückführung.
Agenten / LLMs / Tools führen einzelne Steps aus.
```
Agenten sind Actors.
Das ist wichtig für:
```text
- Verantwortlichkeit
- Audit
- Assignments
- Sichtbarkeit
- Tenant-Kontext
```
---
## 22. Security / Governance / Audit
Kairo muss tenant- und actor-sicher bleiben.
Grundsätze:
```text
- tenant_id immer aus TenantContext
- keine tenant_id aus Client Input vertrauen
- Actor-Bezüge tenant-intern validieren
- Capabilities prüfen
- Router dünn
- Services schreiben
- Data Layer liest
- Audit-by-design
- Signals und NextActions erklärbar
- Agentenaktionen nachvollziehbar
```
---
## 23. UI-Zielbild
Die UI dient als Steuerungs- und Interaktionsschicht.
Langfristige Views:
```text
Workspace
Steering View
Roadmap View
Method View
Attention / NextAction View
Backlog View
Action View
Waiting / Reminder View
Evidence / Review / Decision View
Workflow Run View später
Method/Profile Admin später
Agent Run View später
```
Die UI darf nicht die Methode hart kodieren.
Sie muss methodenbewusst und strukturgetrieben sein.
---
## 24. Architektur-Evolutionslinie
Grobe Evolutionslinie:
```text
1. Existing Foundation
2. Adaptive Steering Core Foundation
3. Method Registry / Hook Registry / Standard Lifecycle
4. Roadmap / Structure Builder Foundation
5. Signal / NextAction Engine
6. Assignment / Waiting / Reminder / Escalation
7. Evidence / Review / Decision
8. Workflow Fragments and Bindings
9. Workflow Runtime
10. Agent / LLM / Tool Providers
11. Method Profiles
12. Method Designer / Advanced Configuration
13. Advanced AI Steering / Next Best Action Ranking
```
Dies ist keine Sprintplanung, sondern ein Zielbild der technischen Entwicklung.
---
## 25. Zielzustand in einem Satz
Kairo soll ein methodengeführter adaptiver Steuerungskern werden, der Entwicklungen unterschiedlichster Art über registrierbare Methoden, gemeinsame Kernstrukturen, Roadmaps, Hooks, Signals, NextActions, Assignments, Waiting-/Reminder-/Escalation-Mechanismen und später Agent-/Workflow-Fragmente wirksam und nachvollziehbar steuert.
@@ -1,7 +1,7 @@
# AP0.8 – Operating Model Extension I
## Implementierungsauftrag zur Prüfung v0.1
**Status:** Entwurf zur Freigabe
**Status:** ersetzt durch `Sprint0_AP0_8_Assignment_v0.2.md`
**Stand:** 2026-07-05
**Vorgänger:** AP0.7 ✓ · AP0.R1 ✓
**Zielversion:** `0.8.0-ap0.8` · Schema `007`
@@ -0,0 +1,402 @@
# AP0.8 – Operating Model Extension I
## Implementierungsauftrag v0.2 (freigegeben)
**Status:** freigegeben zur Umsetzung
**Stand:** 2026-07-05
**Vorgänger:** AP0.7 ✓ · AP0.R1 ✓ · KAIRO-ARCH-01 ✓
**Zielversion:** `0.8.0-ap0.8` · Schema `007`
**Ersetzt:** `Sprint0_AP0_8_Assignment_v0.1.md` (Entwurf)
---
## Einordnung
AP0.8 ist der **erste fachliche Ausbau nach dem Product Reset** und der **erste Schritt der Operating-Model-Evolutionslinie** gemäß System Target State §24:
```text
1. Existing Foundation ✓ AP0.1–AP0.7
2. Adaptive Steering Core — nicht AP0.8 (→ AP1.x)
3. Method Registry / Hooks — nicht AP0.8
4. Roadmap / Structure Builder — nicht AP0.8 (Milestone als MVP-Brücke)
5. Signal / NextAction Engine ← AP0.8a startet hier (regelbasiert, Data Layer)
6. Assignment / Waiting / … — teilweise vorhanden; Waiting → AP0.9+
7. Evidence / Review / Decision — AP0.9
```
Ziel: Kairo sichtbar über `Initiative → Action` hinausheben und die Leitfrage operationalisieren:
> Welcher nächste Schritt bringt ein Vorhaben aktuell am wirkungsvollsten voran?
AP0.8 baut auf AP0.7 auf (Tenant-Invarianten, Actor Directory, Data Layer) und bleibt **regelbasiert ohne KI, ohne Method Registry, ohne SteeringContext**.
---
## Verbindliche Referenzen
Vor Umsetzung lesen:
1. `docs/product/Kairo_Product_Definition_and_MVP_Reset_v0.1.md`
2. `docs/product/Kairo_Canonical_Operating_Model_v0.1.md` — §5 Objektmodell, §7 Attention Logic, §8 Data Layer
3. `docs/product/Kairo_Corrected_MVP_Roadmap_v0.1.md` — AP0.8
4. `docs/architecture/Kairo_System_Target_State_v0.1.md` — §13 Roadmap/Backlog/Action, §17 Signals
5. `docs/architecture/Kairo_Target_Architecture_Method_Driven_Adaptive_Steering_Core_v0.1.md` — Phasen A/B, AD-TA-08
6. `docs/architecture/Kairo_Tenant_Invariants_v0.1.md`
7. `docs/sprints/Sprint0_AP0_7_Completion_Report_v0.2.md`
---
## Abgleich System Target State
| Zielbild (System Target State) | AP0.8-Umsetzung |
|-------------------------------|-----------------|
| RoadmapItem = Entwicklungsziel; BacklogItem = möglicher Handlungsbedarf; Action = committete Maßnahme | Backlog und Action **getrennt**; Convert-Flow |
| Milestone = RoadmapItem(type=milestone) langfristig | **MVP-Brücke:** eigene `milestones`-Tabelle; Konsolidierung → RoadmapItem in Phase C (AD-TA-08) |
| Attention + NextActionCandidate als Signal-Typen | Read Models in `data_layer/attention.py` |
| Signals erklärbar (reason, scope, data_source) | DTO-Felder `reason_code`, `scope_type`, `scope_id`, `data_source` |
| Blocker als Steuerungsobjekt | eigene Tabelle, nicht nur Action-Status |
| Kein SteeringContext / Method Registry yet | explizit Nicht-Scope |
| Kein Workflow / KI | explizit Nicht-Scope |
---
## Leitentscheidungen (freigegeben)
| Entscheidung | Entscheidung | Begründung |
|--------------|--------------|------------|
| Umsetzungsreihenfolge | 4 Slices (8a→8d) in **einem** AP0.8 | Attention zuerst für Produktwirkung |
| Blocker | **Eigenes Objekt** | Canonical Model + System Target State §10 |
| Backlog vs. Action | **Getrennte Tabellen** | §13 Unterscheidung Program Director vs. To-do |
| Milestone | **Eigene Tabelle (MVP-Brücke)** | Schnell prüfbar; Roadmap-Konsolidierung später |
| Project | **Nicht in AP0.8** | Milestone direkt an Initiative |
| Action-Status `ready`/`review_required` | **Nicht in AP0.8** | AP0.9 |
| Due Dates auf Actions | **Nicht in AP0.8** | Regel 7 stub; Milestone `target_date` optional |
| Attention: open Blockers | **Ja, Regel 1b** | Ergänzung zu blocked Actions |
| Capabilities | 7 neue (1 read + 3×2) | Registry-first |
| `kairo.attention.read` | **Eigene Capability** | Explizit, Grants wie workspace.read |
| Member manage Blocker/Backlog/Milestone | **Ja** | wie Actions |
| Convert Backlog→Action | **Pflicht, minimal** | Commit-Flow |
| Blocker ↔ action.status=blocked | **Optional bei Create** | nicht zwingend synchron |
| UI | AP0.6b-Optik | kein Redesign |
---
## Empfohlene Umsetzungsreihenfolge
```text
AP0.8a Attention / NextActionCandidate (Read Model + Widget)
AP0.8b Blocker (Domäne + API + UI)
AP0.8c BacklogItem (Domäne + API + UI + convert)
AP0.8d Milestone minimal (Domäne + API + UI + Attention Regel 6)
```
Reihenfolge ist verbindlich für die Implementierung.
---
# Teil A — AP0.8a: Attention / NextActionCandidate
## Ziel
Regelbasierte **Signal-Schicht** im Data Layer — erste Instanz der Signal/NextAction-Engine (System Target State §17). Später Refactor in `backend/steering/signals/` mit Method Rule Providers.
## Data Layer
Neue Datei: `backend/data_layer/attention.py`
```text
get_attention_items(ctx) -> list[AttentionItemDTO]
get_next_action_candidates(ctx, *, limit=10) -> list[NextActionCandidateDTO]
```
**AttentionItemDTO** (mit Erklärbarkeit):
```json
{
"kind": "blocked_action | open_blocker | high_priority_action | unassigned_action | initiative_without_next_action | stale_initiative | milestone_at_risk",
"severity": "info | warning | critical",
"title": "...",
"summary": "...",
"scope_type": "action | blocker | initiative | milestone",
"scope_id": "...",
"initiative_id": "...",
"action_id": "...",
"blocker_id": "...",
"milestone_id": "...",
"reason_code": "...",
"data_source": "actions | blockers | initiatives | milestones | backlog_items"
}
```
**NextActionCandidateDTO:**
```json
{
"kind": "assign_action | resolve_blocker | create_action | convert_backlog | review_milestone",
"title": "...",
"summary": "...",
"initiative_id": "...",
"action_id": "...",
"backlog_item_id": "...",
"reason_code": "...",
"recommended_action": "..."
}
```
### Regeln
| # | Regel | Datenquelle | Severity |
|---|-------|-------------|----------|
| 1 | Blockierte Maßnahmen | `actions.status = blocked` | critical |
| 1b | Offene Blocker | `blockers.status IN (open, in_progress)` | warning |
| 2 | High-Priority offen | `priority = high`, open/in_progress; **personal** wenn Actor zugewiesen | warning |
| 3 | Maßnahmen ohne Assignment | keine `action_assignments` | warning |
| 4 | Vorhaben ohne offene Maßnahme | active/paused, keine open/in_progress/blocked Action | info |
| 5 | Lange unveränderte Vorhaben | `updated_at` > 14 Tage, status active | info |
| 6 | Meilenstein at_risk | ab AP0.8d: `milestones.status = at_risk` | warning |
| 7–9 | Due Dates, Reviews, Recurring | AP0.9+ — stub/leer | — |
**NextAction-Kandidaten (regelbasiert, limitiert):**
- unassigned Action → `assign_action`
- blocked Action / open Blocker → `resolve_blocker`
- Initiative ohne offene Maßnahme → `create_action`
- accepted BacklogItem ohne Action → `convert_backlog`
Sortierung Attention: critical → warning → info. Keine Client-Priorisierung.
## API
```text
GET /api/workspace/attention
GET /api/workspace/next-actions?limit=10
```
Capability: **`kairo.attention.read`**
## Frontend
- **`AttentionWidget`** (Registry-Key `kairo.attention`, order 8, unter Überblick)
- Links zu Vorhaben/Maßnahmen/Blockern
- Loading / Error / Empty States
## Tests
- Regeln 1, 1b, 2–5; Regel 6 nach 8d
- NextAction: convert_backlog, create_action
- Cross-Tenant isolation
- Router delegiert an Data Layer
---
# Teil B — AP0.8b: Blocker
## Migration `007_operating_model_extension_i.sql`
```sql
blockers (
id UUID PK,
tenant_id UUID NOT NULL REFERENCES tenants(id),
initiative_id UUID NOT NULL REFERENCES initiatives(id),
action_id UUID NULL REFERENCES actions(id),
title VARCHAR(255) NOT NULL,
description TEXT DEFAULT '',
status VARCHAR(32) NOT NULL, -- open, in_progress, resolved, accepted_risk, dismissed
reported_by_actor_id UUID NULL REFERENCES actors(id),
created_at, updated_at
)
```
Index: `(tenant_id, initiative_id)`, `(tenant_id, status)`
## Service + API
`backend/services/blockers.py` — CRUD, Audit: `blocker.created/updated/status_changed/deleted`
```text
GET/POST /api/initiatives/{id}/blockers
GET/PATCH/DELETE /api/blockers/{id}
```
Capabilities: **`kairo.blocker.read`**, **`kairo.blocker.manage`**
## Frontend
Vorhaben-Detail: Sektion **Blocker**
---
# Teil C — AP0.8c: BacklogItem
## Migration (gleiche `007`)
```sql
backlog_items (
id UUID PK,
tenant_id UUID NOT NULL,
initiative_id UUID NOT NULL REFERENCES initiatives(id),
title VARCHAR(255) NOT NULL,
description TEXT DEFAULT '',
status VARCHAR(32) NOT NULL, -- new, triaged, accepted, rejected, converted
priority VARCHAR(16) DEFAULT 'normal',
converted_action_id UUID NULL REFERENCES actions(id),
created_at, updated_at
)
```
## Service + API
```text
GET/POST /api/initiatives/{id}/backlog
GET/PATCH/DELETE /api/backlog/{id}
POST /api/backlog/{id}/convert-to-action
```
Capabilities: **`kairo.backlog.read`**, **`kairo.backlog.manage`**
Convert: erzeugt Action, setzt `converted_action_id`, status=converted, Audit.
## Frontend
Vorhaben-Detail: Sektion **Backlog** + Button „In Maßnahme umwandeln“
---
# Teil D — AP0.8d: Milestone minimal
## Migration (gleiche `007`)
```sql
milestones (
id UUID PK,
tenant_id UUID NOT NULL,
initiative_id UUID NOT NULL REFERENCES initiatives(id),
title VARCHAR(255) NOT NULL,
goal_description TEXT DEFAULT '',
status VARCHAR(32) NOT NULL, -- planned, active, at_risk, reached, moved, discarded
target_date DATE NULL,
created_at, updated_at
)
```
**Hinweis Zielarchitektur:** Langfristig `RoadmapItem(item_type=milestone)`. Diese Tabelle ist bewusste MVP-Brücke (AD-TA-08).
## Service + API
```text
GET/POST /api/initiatives/{id}/milestones
GET/PATCH/DELETE /api/milestones/{id}
```
Capabilities: **`kairo.milestone.read`**, **`kairo.milestone.manage`**
Attention-Regel 6 nach Implementierung aktivieren.
## Frontend
Vorhaben-Detail: Sektion **Meilensteine** (kompakt, kein Gantt)
---
# Capabilities AP0.8
| Capability | Modul | Grants |
|------------|-------|--------|
| `kairo.attention.read` | attention | Member+ (wie workspace.read) |
| `kairo.blocker.read` | blocker | Member+ |
| `kairo.blocker.manage` | blocker | Member+ |
| `kairo.backlog.read` | backlog | Member+ |
| `kairo.backlog.manage` | backlog | Member+ |
| `kairo.milestone.read` | milestone | Member+ |
| `kairo.milestone.manage` | milestone | Member+ |
Registrierung: `backend/rights_registrations/operating_model_ops.py`
Gesamt nach AP0.8: **25 Capabilities** (18 + 7)
---
# Architekturregeln (verbindlich)
1. **Tenant-first** — `tenant_id` aus TenantContext
2. **Actor-first** — `reported_by_actor_id` optional; Assignments unverändert
3. **Data Layer read / Services write** — Attention nur Data Layer
4. **Router dünn** — keine Aggregations-SQL in Routern
5. **Signals erklärbar** — reason_code, scope_type, data_source in DTOs
6. **Cross-Tenant → 404**
7. **Migration `007`** — kein ad-hoc DDL
8. **Kein Prompt/KI/MCP/Workflow/SteeringContext/Method Registry**
9. **Product Reset** — drei Ebenen RoadmapItem/BacklogItem/Action respektieren
---
# Nicht-Scope AP0.8
- Project / Program / SteeringContext / Method Registry / Hook Runtime
- Evidence, Decision, Review, RecurringElement (→ AP0.9)
- Action-Status `ready`, `review_required`
- Due Dates auf Actions / Überfälligkeits-Engine
- KI, MCP, Workflow Engine
- Roadmap/RoadmapLane/RoadmapItem-Modell (→ Phase C)
- Workspace-weite Backlog-Navigation
- AP0.10 Validation Testvorhaben
---
# Tests (Mindestumfang)
## Backend — `backend/tests/test_ap08_operating_model.py`
| Bereich | Tests |
|---------|-------|
| Attention | Regeln 1, 1b, 2–6, Sortierung, Cross-Tenant |
| NextAction | assign, convert_backlog, create_action, limit |
| Blocker | CRUD, Tenant-Isolation, optional action_id |
| Backlog | CRUD, convert-to-action |
| Milestone | CRUD, at_risk in Attention |
| Capabilities | Member grants, Gate 403, 25 sync |
| Migration | `007` in test_migrations |
## Frontend
- Vitest: Registry enthält `kairo.attention`
- Build grün
---
# Abnahmekriterien AP0.8
1. Migration `007`; Schema `007`
2. Attention/NextAction regelbasiert (Regeln 1–6)
3. Blocker, Backlog, Milestone CRUD tenant-sicher
4. `data_layer/attention.py`; Router delegieren
5. AttentionWidget im Workspace
6. Vorhaben-Detail: Blocker, Backlog, Meilensteine
7. Convert Backlog → Action
8. Cross-Tenant-Tests grün
9. 25 Capabilities registriert
10. AP0.6b UX erhalten
11. Kein Prompt/KI/MCP/Steering-Scope
12. Abschlussbericht + README
---
# Abschlussbericht (nach Umsetzung)
Siehe Vorlage in v0.1 — Abschnitte 1–15.
---
# Freigegebene Punkte (ehemals offen)
| # | Entscheidung |
|---|--------------|
| 1 | Ein AP0.8, 4 interne Slices |
| 2 | Eigene Capability `kairo.attention.read` |
| 3 | Blocker/Action-Status optional synchron |
| 4 | Convert Backlog→Action Pflicht |
| 5 | Member manage wie Actions |
| 6 | Initiative draft → AP0.8.1 |
| 7 | Backlog nur Initiative-Detail |
---
*Freigegeben — Umsetzung gemäß Slice-Reihenfolge 8a→8d.*
@@ -0,0 +1,149 @@
# AP0.8 – Abschlussbericht Operating Model Extension I
**Status:** abgeschlossen (Implementierung) · QA mit DB ausstehend
**Stand:** 2026-07-05
**Version:** Backend/Frontend `0.8.0-ap0.8` · Schema `007`
**Auftrag:** `Sprint0_AP0_8_Assignment_v0.2.md` (abgeglichen mit System Target State v0.1)
---
## 1. Scope und Einordnung
AP0.8 ist der erste fachliche Ausbau nach dem Product Reset. Er operationalisiert die Leitfrage über regelbasierte Attention/NextAction und erweitert das Domänenmodell um Blocker, BacklogItem und Milestone.
Einordnung in der Evolutionslinie (System Target State §24):
- Foundation ✓ (AP0.7)
- **Signal / NextAction Engine — erste Instanz** ✓ (AP0.8a, Data Layer)
- Operating Model Phase A ✓ (Blocker, Backlog, Milestone)
- SteeringContext / Method Registry — bewusst **nicht** in AP0.8
---
## 2. Definition of Done — Prüfmatrix
| Kriterium | Ergebnis | Nachweis |
|-----------|----------|----------|
| Migration 007 | ✓ | `007_operating_model_extension_i.sql` |
| Attention Regeln 1–6 | ✓ | `data_layer/attention.py` |
| NextActionCandidates | ✓ | `get_next_action_candidates` |
| Blocker CRUD | ✓ | `services/blockers.py`, Router |
| Backlog CRUD + Convert | ✓ | `services/backlog.py` |
| Milestone CRUD | ✓ | `services/milestones.py` |
| AttentionWidget | ✓ | `widgets/AttentionWidget.jsx` |
| Initiative-Detail Sektionen | ✓ | Blockers/Backlog/Milestones |
| 25 Capabilities | ✓ | `operating_model_ops.py` |
| Frontend Vitest + Build | ✓ | 9/9, build grün |
| Backend pytest | ⏳ Remote | Gitea `test.yml` nach Push auf `develop` (Pi, Container) |
| Kein KI/MCP/Steering | ✓ | Scope eingehalten |
---
## 3. Migration 007
Tabellen: `blockers`, `backlog_items`, `milestones` — alle mit `tenant_id`, FK RESTRICT/CASCADE wie AP0.5.
---
## 4. Attention / NextActionCandidate
- Datei: `backend/data_layer/attention.py`
- API: `GET /api/workspace/attention`, `GET /api/workspace/next-actions`
- Regeln: blocked_action, open_blocker, high_priority (personal), unassigned, initiative_without_next_action, stale_initiative, milestone_at_risk
- DTOs mit `reason_code`, `scope_type`, `data_source` (Erklärbarkeit gemäß System Target State §17)
---
## 5. Blocker
- Service + nested/flat API
- Audit: `blocker.created/updated/status_changed/deleted`
- Optional: `set_action_blocked` bei Create
---
## 6. BacklogItem
- Getrennt von Actions (RoadmapItem/Backlog/Action-Unterscheidung)
- Convert-to-action mit Audit `backlog.converted_to_action`
---
## 7. Milestone minimal
- MVP-Brücke (langfristig RoadmapItem — AD-TA-08)
- Attention-Regel 6 für `at_risk`
---
## 8. Data Layer Erweiterung
Neu: `attention.py` — Read-only, tenant-scoped, keine Router-SQL.
---
## 9. API-Endpunkte
Siehe README AP0.8-Tabelle.
---
## 10. Capabilities
7 neue: `kairo.attention.read`, `kairo.blocker.*`, `kairo.backlog.*`, `kairo.milestone.*`
Gesamt: 25
---
## 11. Frontend-Integration
- `AttentionWidget` (order 8, capability `kairo.attention.read`)
- `BlockersSection`, `BacklogSection`, `MilestonesSection` im Vorhaben-Detail
- Status-Badges erweitert für blocker/backlog/milestone
---
## 12. Tests und Verifikation
| Test | Status |
|------|--------|
| `test_ap08_operating_model.py` | 14 Tests — Lauf auf Pi via `test.yml` |
| `test_rights_registry.py` | aktualisiert (25 Capabilities) |
| `test_migrations.py` | Migration 007 ergänzt |
| `conftest.py` | Session-Guard: skip lokal ohne DB, kein Migrations-Timeout |
| Vitest | 9/9 grün (lokal) |
| `vite build` | grün (lokal) |
**Verifikation:** Push auf `develop` → `deploy-dev.yml` + `test.yml` (pytest im Backend-Container gegen PostgreSQL im Compose-Stack).
---
## 13. Abweichungen von diesem Auftrag
| Punkt | Abweichung |
|-------|------------|
| Auftrag v0.1 | Ersetzt durch v0.2 nach Abgleich System Target State |
| Attention DTO | Zusätzlich `scope_type`, `data_source`, Regel 1b open_blocker |
| NextAction DTO | Explizit dokumentiert und implementiert |
| Milestone API target_date | Router akzeptiert ISO-Date-String |
Keine fachlichen Scope-Abweichungen.
---
## 14. Offene Punkte für AP0.9
- Evidence, Decision, Review, RecurringElement
- Action-Status `ready`, `review_required`
- Due Dates auf Actions + Attention Regeln 7–9
- Attention-Refactor in `backend/steering/signals/` (wenn Steering Core startet)
---
## 15. Empfehlung für AP0.10 / Validation
Nach AP0.9 ein reales Testvorhaben durchspielen (Backlog → Action → Blocker → Meilenstein → Attention). Milestone→RoadmapItem-Konsolidierung als ADP vor Phase C klären.
---
*Implementierung abgeschlossen — Backend-pytest und Smoke auf dem Pi nach Push auf `develop`.*