docs(ST-1111.9): document Claude job queue architecture and agent flow

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/plans/ST-1111-claude-job-trigger.md

@@ -0,0 +1,69 @@
+# ST-1111 — 'Voer uit'-knop met Claude Code job queue
+
+**Story:** Als developer wil ik op het solo-scherm per task een 'Voer uit'-knop, zodat ik mijn lokale Claude Code-sessie kan inschakelen om de taak uit te voeren.
+
+**Branch:** `feat/M13-claude-job-queue`
+
+---
+
+## Sub-tasks en commits
+
+| Task | Commit |
+|---|---|
+| ST-1111.1 DB: ClaudeJob model + enum + migration | `5274e1e` |
+| ST-1111.2 API: ClaudeJob status mappers | `a1b1f69` |
+| ST-1111.3 Server actions: enqueue + cancel | `9d9fb4b` |
+| ST-1111.4 SSE: ClaudeJob events op solo-stream + initial state | `ece0aa9` |
+| ST-1111.5 MCP-tools (scrum4me-mcp repo — aparte PR) | — |
+| ST-1111.6 UI: 'Voer uit' + cancel in TaskDetailDialog | `b9c65eb` |
+| ST-1111.7 UI: status-pill op SoloTaskCard | `dace427` |
+| ST-1111.8 Tests: mappers + actions | `2c2a246` |
+| ST-1111.9 Docs | dit bestand |
+
+---
+
+## Architectuur
+
+### State machine
+
+```
+QUEUED → CLAIMED → RUNNING → DONE
+                           → FAILED
+       → CANCELLED (cancel-knop of server action)
+CLAIMED → QUEUED  (stale cleanup, >30min, via wait_for_job)
+```
+
+### NOTIFY-pijplijn
+
+Omdat `claude_jobs` geen row-trigger heeft (zoals `tasks` en `stories`), stuurt de **server action** zelf `pg_notify` via `prisma.$executeRaw`:
+
+```ts
+await prisma.$executeRaw`SELECT pg_notify('scrum4me_changes', ${JSON.stringify(payload)}::text)`
+```
+
+Voordeel: expliciete controle over het payload-shape (met `type` i.p.v. `entity`). Nadeel: MCP-tools in de `scrum4me-mcp`-repo moeten hun eigen NOTIFY-aanroep hebben bij `update_job_status`.
+
+### SSE-routing
+
+De bestaande `/api/realtime/solo`-route herkent nu twee payload-shapes:
+- `entity: 'task'|'story'` — bestaande trigger-events
+- `type: 'claude_job_enqueued'|'claude_job_status'` — nieuwe job-events
+
+Job-events worden gefilterd op `user_id + product_id`. Bij connect stuurt de route een `claude_jobs_initial`-event met alle actieve + recente (vandaag) jobs.
+
+### Idempotency
+
+`enqueueClaudeJobAction` weigert als `claude_jobs WHERE task_id=X AND status IN (QUEUED, CLAIMED, RUNNING)` bestaat. De client ontvangt `{ error, jobId }` zodat de UI naar de actieve job kan linken in plaats van een nieuw venstertje te openen.
+
+---
+
+## Beslissingen
+
+**Waarom geen DB-trigger voor NOTIFY?**
+De MCP-server claimt jobs via raw SQL (FOR UPDATE SKIP LOCKED); die schrijft ook direct naar de DB. Een trigger zou clean zijn, maar de MCP-tools moeten hoe dan ook hun eigen NOTIFY-payload bouwen voor `update_job_status`. Applicatie-NOTIFY houdt de payloads consistent en expliciet.
+
+**Waarom `cancelled` verwijderd uit de store?**
+Geannuleerde jobs zijn terminaal; het pill-element zou "Geannuleerd" tonen tot de gebruiker een refresh doet. In plaats daarvan wist `handleJobEvent` de entry bij `status === 'cancelled'` zodat de kaart teruggaat naar de "Voer uit"-staat.
+
+**Auto-clear DONE/FAILED?**
+Niet geïmplementeerd in v1. De pill blijft staan totdat de SSE-connectie herstart (refresh, tab-hidden+visible). Acceptabel voor de eerste iteratie.