Kairo-Jinkendo/docs/sprints/Sprint0_AP0_8_Assignment_v0.2.md

# 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.*