From 55a1ee035c8e528ee4d3d262d4e5e28b4e9a18a3 Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 13:09:25 +0200
Subject: [PATCH 01/17] docs: introduce generic entity-dialog pattern +
 entity-profiles (#45)

* docs(dialog-pattern): add generic entity-dialog spec

Introduceert docs/patterns/dialog.md als bron-of-truth voor elke
create/edit/detail-dialog in Scrum4Me, ongeacht het achterliggende
dataobject. Bevat 14 secties: uitgangspunten, stack, component-
architectuur, layout, validatie, drielaagse demo-policy, submission,
dialog-gedrag, theming, footer, triggers/URL-state, per-entiteit
profile-template, out-of-scope, en een verificatie-checklist.

Registreert het patroon in CLAUDE.md "Implementatiepatronen"-tabel
zodat Claude (en mensen) de spec verplicht raadplegen voor elke
nieuwe dialog.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(dialog-pattern): convert task spec + add pbi/story entity-profiles

Reduceert docs/scrum4me-task-dialog.md van 507 naar ~140 regels: alle
gedeelde regels verhuisd naar docs/patterns/dialog.md, dit document
bevat nu alleen Task-specifieke velden, URL-pattern, status-veld,
server actions, triggers en bewuste out-of-scope-keuzes.

Voegt twee nieuwe entity-profielen toe voor bestaande dialogen:
- docs/scrum4me-pbi-dialog.md (PbiDialog: state-based, code+title-rij,
  PbiStatusSelect, geen delete in v1)
- docs/scrum4me-story-dialog.md (StoryDialog: state-based, header met
  status/priority badges, inline activity-log, demo-readonly-fallback,
  inline-delete-confirm i.p.v. AlertDialog)

Beide profielen documenteren expliciet de "Bekende gaps t.o.v.
generieke spec" zodat opvolgende PR's de afwijkingen kunnen
rechtzetten of bewust kunnen accorderen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Added pdevelopment docs

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |   3 +-
 CLAUDE.md                                     |   1 +
 docs/patterns/dialog.md                       | 387 ++++++++++++
 docs/plans/ST-1114-copilot-reviews.md         | 133 +++++
 .../Tweede Claude Agent — Planning Agent.md   | 346 +++++++++++
 docs/scrum4me-pbi-dialog.md                   | 120 ++++
 docs/scrum4me-story-dialog.md                 | 163 +++++
 docs/scrum4me-task-dialog.md                  | 557 +++---------------
 8 files changed, 1241 insertions(+), 469 deletions(-)
 create mode 100644 docs/patterns/dialog.md
 create mode 100644 docs/plans/ST-1114-copilot-reviews.md
 create mode 100644 docs/plans/Tweede Claude Agent — Planning Agent.md
 create mode 100644 docs/scrum4me-pbi-dialog.md
 create mode 100644 docs/scrum4me-story-dialog.md

diff --git a/.gitignore b/.gitignore
index e3c508b..9c8093c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -71,4 +71,5 @@ jp.sh
 .codex/
 
 # Lokale scratch-bestanden
-Brainstro
\ No newline at end of file
+Brainstro
+/graphify-out
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 65be9e6..010083b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -111,6 +111,7 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
 | Middleware (route protection) | `docs/patterns/middleware.md` |
 | QR-pairing (unauth-SSE + pre-auth cookie) | `docs/patterns/qr-login.md` |
 | Bidirectionele async-comms MCP-agent ↔ user | `docs/patterns/claude-question-channel.md` |
+| **Entity Dialog (verplicht voor élke create/edit/detail-dialog)** | `docs/patterns/dialog.md` — bron-of-truth; per entiteit één profile-doc (bv. `docs/scrum4me-task-dialog.md`) |
 | Status-enum mapping (DB ↔ API) | `lib/task-status.ts` |
 | Client/server module-boundary | `*-server.ts` bevat DB-calls of node-only deps; `*.ts` is pure (client-safe). Nooit `import { ... } from '@/lib/foo-server'` in een client-component, anders krijg je `Module not found: 'dns'`/`'pg'`-style runtime fouten |
 
diff --git a/docs/patterns/dialog.md b/docs/patterns/dialog.md
new file mode 100644
index 0000000..9bf4682
--- /dev/null
+++ b/docs/patterns/dialog.md
@@ -0,0 +1,387 @@
+# Pattern — Entity Dialog
+
+Deze pagina is **bindend** voor elke create/edit/detail-dialog in Scrum4Me, ongeacht het achterliggende dataobject (PBI, Story, Task, Todo, Sprint, Product, User, of toekomstige entiteiten). Een nieuwe dialog die hier niet aan voldoet, hoort niet gemerged te worden.
+
+> **Doel:** elke dialog voelt identiek aan voor de gebruiker, hergebruikt dezelfde primitives, en heeft de drielaagse demo-policy + auth-scoping standaard ingebakken.
+
+Voor entity-specifieke afwijkingen of velden: schrijf één begeleidende doc per entiteit (zie sectie [§ Per-entiteit profile](#per-entiteit-profile-verplicht)). Voorbeeld: `docs/scrum4me-task-dialog.md` is het Task-profiel.
+
+---
+
+## 1 — Verplichte uitgangspunten
+
+| # | Regel | Bron / waarom |
+|---|---|---|
+| 1.1 | Bouw op `components/ui/dialog.tsx` (de bestaande shadcn/`@base-ui/react`-wrapper). **Geen** directe imports van dialog-primitives uit `@base-ui/react`. | Voorkomt twee parallelle dialog-implementaties met inconsistente animatie/focus-trap/theming |
+| 1.2 | Gebruik composition via de **`render`-prop** (zie `CLAUDE.md` "UI Library Conventions"). Nooit Radix' `asChild`. | Project gebruikt `@base-ui/react`, niet Radix |
+| 1.3 | Mode (`create` vs `edit` vs `detail`) wordt afgeleid uit één input — een prop, een `state`-object of een `searchParam`. **Niet** twee aparte componenten. | Voorkomt code-duplicatie en inconsistente labels/footer-layouts |
+| 1.4 | Auth-scoping op elke server action via `productAccessFilter(userId)` (of het scope-helper-equivalent). Cross-tenant writes mogen onmogelijk zijn. | `CLAUDE.md` "Toegangsmodel" + `docs/patterns/server-action.md` |
+| 1.5 | **Drielaagse demo-policy** (verplicht — zie § 6) op elke write-actie. | `CLAUDE.md` "Demo-check" + `docs/scrum4me-architecture.md#demo-user-policy` |
+| 1.6 | Validatie via één gedeeld zod-schema (`lib/schemas/<entity>.ts`) — gebruikt door zowel form als server action. | `CLAUDE.md` "Validatie" |
+| 1.7 | Foutcodes volgen de project-conventie (§ 5). | `CLAUDE.md` "Foutcodes API" |
+| 1.8 | Geen willekeurige Tailwind-kleuren (`bg-blue-500` etc.). Alleen MD3-tokens uit `app/styles/theme.css`. | `docs/scrum4me-styling.md` |
+
+---
+
+## 2 — Stack & dependencies
+
+Toegestane runtime-deps voor dialog-werk (al aanwezig of standaard pattern):
+
+| Doel | Voorkeur | Acceptabele alternatief |
+|---|---|---|
+| Form-state | `react-hook-form` + `@hookform/resolvers/zod` | `useActionState` + `useFormStatus` (Server Actions, native React) |
+| Auto-grow textarea | `react-textarea-autosize` | — |
+| Markdown-rendering (preview) | `react-markdown` + `remark-gfm` (via bestaande `<Markdown>`-wrapper) | — |
+| Toasts | `sonner` | — |
+| Iconen | `lucide-react` | — |
+
+> **Per-dialog mag je kiezen tussen `react-hook-form` of `useActionState`.** Beide patronen draaien al in deze codebase. Kies één per dialog en blijf consistent binnen dat bestand. Mix ze niet.
+
+Verboden in dialog-context (v1):
+- `material-color-utilities` (dynamic color valt buiten v1)
+- Nieuwe form-libraries — geen `formik`, `final-form`, etc.
+
+---
+
+## 3 — Component-architectuur
+
+### 3.1 Reusables (`components/entity-dialog/` of `components/shared/`)
+
+Deze primitives kennen géén entity-specifieke types en mogen door élke dialog gebruikt worden:
+
+| Primitive | Locatie | Verantwoordelijkheid |
+|---|---|---|
+| `<Dialog>` + `<DialogContent>` etc. | `components/ui/dialog.tsx` | Shell, motion, focus-trap, backdrop |
+| `<PrioritySelect>` / `<PrioritySegmented>` | `components/shared/priority-select.tsx` | P1-P4 — identiek over alle entiteiten |
+| `<DemoTooltip>` | `components/shared/demo-tooltip.tsx` | Wrapper rond write-knoppen voor demo-modus (laag 3 van 3) |
+| Auto-grow textarea | (toe te voegen wanneer nodig in `components/shared/`) | Wrapper rond `react-textarea-autosize` met char-counter + markdown-hint |
+| Dirty-close-guard | (gedeelde AlertDialog-flow) | "Wijzigingen niet opgeslagen — weggooien?" |
+| `<Markdown>` | `components/markdown.tsx` | `react-markdown` + `remark-gfm` voor description/criteria-preview |
+
+> Wanneer je een primitive twee keer kopieert tussen entity-dialogs, **promote 'm meteen** naar `components/shared/` (of `components/entity-dialog/`). Drie keer is te laat.
+
+### 3.2 Entity-specifieke laag (`components/<domain>/<entity>-dialog.tsx`)
+
+Per entiteit één wrapper-bestand dat:
+1. De juiste form/body rendert
+2. De juiste server actions koppelt (`save<Entity>Action`, `delete<Entity>Action`)
+3. Entiteit-specifieke labels levert ("Story bewerken", "PBI aanmaken", etc.)
+
+Een entity-dialog bevat **geen** layout-mechanica, motion-config of dirty-check zelf — die komen uit § 3.1.
+
+---
+
+## 4 — Layout & responsive gedrag
+
+Identiek voor élke dialog (geen entity-specifieke variaties tenzij expliciet beargumenteerd in het entity-profile):
+
+| Breakpoint | Breedte | Hoogte |
+|---|---|---|
+| Mobiel (< 640px) | full-screen | full-screen |
+| Tablet (640–1024px) | `90vw` | `max-h-[85vh]` |
+| Desktop (≥ 1024px) | `max-w-[50vw]`, `min-w-[480px]` | `max-h-[85vh]` |
+
+Verplicht:
+- Padding `p-6` rondom (24px)
+- Veld-spacing in body `space-y-6` (24px)
+- **Sticky** header (titel + close) en **sticky** footer (knoppen)
+- Body scrollt onafhankelijk; geneste scrolls vermijden
+- Footer heeft `border-t` in `outline-variant`
+
+---
+
+## 5 — Validatie & foutcodes
+
+### 5.1 zod-schema
+
+Eén `lib/schemas/<entity>.ts` per entiteit. Geïmporteerd door zowel form als server action — geen aparte definities.
+
+### 5.2 Foutcodes (verplicht)
+
+| Code | Wanneer | UI-respons |
+|---|---|---|
+| **422** | zod-validatiefout (server-side dubbelcheck) | `fieldErrors` mappen naar `form.setError()`, géén toast |
+| **403** | demo-sessie probeert te schrijven, of cross-tenant write geblokkeerd | toast "Niet toegestaan in demo-modus" of "Geen toegang", form blijft open |
+| **400** | malformed JSON-body (`request.json()` faalt) — alleen bij REST-route-handlers | toast "Ongeldige aanvraag" |
+| **500** | onverwachte serverfout | toast met "Opnieuw proberen"-knop, form-state behouden |
+
+> Field-level errors zijn **alleen** geldig bij `code: 422`. Bij andere codes is `fieldErrors` ongedefinieerd.
+
+### 5.3 Field-level rendering
+
+- Errors **onder** het veld, in `text-error`, met `border-error` op het input-element
+- Géén toast voor field-level errors
+- Submit-knop **blijft enabled** bij errors — klik scrollt naar eerste error-veld + focus
+- react-hook-form mode: `onTouched` (eerste validatie bij blur, daarna onChange)
+
+---
+
+## 6 — Drielaagse demo-policy (verplicht voor write-dialogs)
+
+Elke dialog die schrijft (create / edit / delete) MOET door alle drie de lagen heen:
+
+1. **Middleware-guard** in `proxy.ts` — blokkeert demo-sessies op write-routes vóór de server action loopt. Returnt **403**.
+2. **`session.isDemo`-check** binnen elke `save<Entity>Action` / `delete<Entity>Action` zelf — defense-in-depth voor het geval een actie buiten een proxy-route loopt. Returnt **403**.
+3. **`<DemoTooltip show={isDemo}>`** rond de submit- en delete-knoppen — UI-laag: knoppen `disabled` met tooltip "Demo-modus: opslaan uitgeschakeld".
+
+> Eén laag missen = bug. Reviewers moeten alle drie de lagen kunnen aanwijzen in de PR.
+
+---
+
+## 7 — Submission-flow
+
+### 7.1 Server Action (template)
+
+```ts
+// actions/<entity>.ts
+'use server'
+
+export async function save<Entity>Action(
+  input: <Entity>Input,
+  context: { /* ids voor revalidatePath en scope */ },
+): Promise<Save<Entity>Result> {
+  const session = await getSession()
+  if (!session.userId) return { ok: false, code: 403, error: 'forbidden' }
+  if (session.isDemo)  return { ok: false, code: 403, error: 'demo_readonly' }
+
+  const scope = await productAccessFilter(session.userId) // verplicht
+  const parsed = <entity>Schema.safeParse(input)
+  if (!parsed.success) {
+    return { ok: false, code: 422, error: 'validation', fieldErrors: parsed.error.flatten().fieldErrors }
+  }
+  // ... Prisma write binnen `scope` ...
+  // revalidatePath(...) op de context-route
+  return { ok: true, <entity>: row }
+}
+
+type Save<Entity>Result =
+  | { ok: true; <entity>: <Entity> }
+  | { ok: false; code: 422; error: 'validation'; fieldErrors: Record<string, string[]> }
+  | { ok: false; code: 403; error: 'demo_readonly' | 'forbidden' }
+  | { ok: false; code: 500; error: 'server_error' }
+```
+
+### 7.2 Revalidation
+
+`revalidatePath` op de **context-route** waarin de dialog werd geopend, niet op een statisch path. Context wordt door de aanroepende client meegegeven (geen hard-coded paths in de action).
+
+### 7.3 Submit-flow
+
+- Synchroon (geen optimistic update in v1, behalve waar het store-patroon `usePlannerStore` al bestaat)
+- Tijdens submit: cancel- en submit-knop disabled, spinner of "…" in submit-knop, velden **blijven enabled**
+- Server saniteert en valideert opnieuw met hetzelfde zod-schema
+
+---
+
+## 8 — Dialog-gedrag (UX-regels)
+
+### 8.1 Sluiten met dirty state
+
+- Form niet aangeraakt → Esc / backdrop-klik / Cancel sluiten **direct**
+- Form `isDirty` → Esc / backdrop-klik / Cancel triggeren `AlertDialog`: *"Wijzigingen niet opgeslagen — weggooien?"*
+
+### 8.2 Keyboard shortcuts
+
+| Toets | Actie |
+|---|---|
+| **Esc** | Sluiten (met dirty-check) |
+| **Cmd/Ctrl + Enter** | Submit vanuit elk veld |
+| **Enter in `<input type=text>`** | **Geen** submit (alleen Cmd/Ctrl+Enter) |
+| **Enter in `<textarea>`** | Newline (default browser, niet overriden) |
+| **Tab** | Top-naar-bottom door velden, dan Cancel → Submit (en Delete in edit-mode) |
+
+### 8.3 Focus management
+
+- Bij openen: focus op het eerste tekstveld (meestal `title` / `name`)
+- Edit-mode: cursor aan het einde van bestaande waarde, **geen auto-select** (anders typt user per ongeluk weg)
+- Bij sluiten: focus terug naar het element dat de dialog opende (`@base-ui/react` doet dit by default — niet breken)
+- Bij submit-error: focus naar eerste error-veld
+
+### 8.4 Motion (MD3-conform)
+
+- Open: 250ms, easing `cubic-bezier(0.2, 0, 0, 1)`, scale 0.95→1 + opacity 0→1
+- Close: 200ms, easing `cubic-bezier(0.4, 0, 1, 1)`
+
+### 8.5 Backdrop
+
+`rgba(0,0,0,0.4)` (iets sterker dan MD3-default 0.32 voor contrast op zowel licht als donker).
+
+---
+
+## 9 — Theming (MD3-tokens)
+
+| Surface | Token |
+|---|---|
+| Dialog-background | `surface-container-high` + `shadow-2xl` (getemperde opacity) |
+| Form input-background | `surface-container-low`, geen shadow |
+| Footer top-border | `outline-variant` |
+| Submit-knop (filled) | `primary` background + `on-primary` tekst |
+| Cancel-knop (text) | geen background + `primary` tekst |
+| Delete-knop (tonal error) | `error-container` background + `on-error-container` tekst |
+
+Density: **comfortable** (geen compact). Single-line input `h-14` (56px MD3-default).
+
+Typography:
+- `headline-small` (24px) — dialog-titel
+- `body-large` (16px) — form-input tekst
+- `body-medium` (14px) — helptext, counter
+
+---
+
+## 10 — Footer
+
+### 10.1 Edit-mode
+
+```
+[ Verwijderen ]                    [ Annuleren ]   [ Opslaan ]
+  tonal (error-container)            text            filled (primary)
+```
+
+### 10.2 Create-mode
+
+```
+                                   [ Annuleren ]   [ Aanmaken ]
+                                     text            filled (primary)
+```
+
+### 10.3 Detail-mode (read-only)
+
+```
+                                                   [ Sluiten ]
+                                                     filled (primary)
+```
+
+### 10.4 Delete-flow (verplicht patroon)
+
+1. Klik "Verwijderen" → `AlertDialog`: *"Weet je zeker? Dit kan niet ongedaan worden."*
+2. Bevestigen → `delete<Entity>Action` (zelfde auth-scoping én demo-checks als save) → `revalidatePath` op context-route → dialog sluit → toast "<Entity> verwijderd"
+3. Geen undo in v1
+
+---
+
+## 11 — Triggers & URL-state
+
+Elke dialog wordt geopend vanuit een context-pagina (sprint, backlog, dashboard, …). Twee patronen zijn toegestaan:
+
+### 11.1 URL-based (voorkeur voor deep-link-bare dialogen)
+
+```
+?new<Entity>=1                         → create-dialog open
+?edit<Entity>=<id>                     → edit-dialog open
+```
+
+Kies dit patroon wanneer de dialog gedeeld of gebookmarkt moet kunnen worden, of wanneer Suspense + skeleton voor edit-mode gewenst is.
+
+Sluiten = dezelfde route opnieuw pushen zonder de query-params.
+
+### 11.2 State-based (voor pure UI-dialogen binnen één client-component)
+
+```tsx
+const [dialogState, setDialogState] = useState<DialogState | null>(null)
+<EntityDialog state={dialogState} onClose={() => setDialogState(null)} />
+```
+
+Kies dit patroon voor dialogen die altijd binnen één parent-component leven en geen deep-linking nodig hebben (bv. PBI-dialog binnen PbiList, Story-dialog binnen StoryPanel).
+
+> Mix de twee patronen niet binnen één entity-dialog. Documenteer in het entity-profile welk patroon gekozen is en waarom.
+
+### 11.3 Server-side fetch in edit-mode
+
+Bij URL-based pattern: server component fetcht het record vóór render — **inclusief auth-scoping**. Bestaat het record niet of valt het buiten scope → toast + redirect naar context-route zonder query-param.
+
+Voor state-based pattern: het record komt al uit de parent (in-memory store of server-prop), dus geen aparte fetch nodig.
+
+---
+
+## 12 — Per-entiteit profile (verplicht)
+
+Voor elke entiteit met een dialog hoort één profiel-doc te bestaan: `docs/<scrum4me-<entity>-dialog>.md` (of vergelijkbaar). Het profiel **vult de generieke spec aan** en bevat **alleen** de entity-specifieke onderdelen.
+
+### Verplichte secties van het entity-profile
+
+```md
+# <Entity>Dialog Profiel
+
+> Volgt `docs/patterns/dialog.md`. Dit document beschrijft alleen de afwijkingen en entity-specifieke keuzes.
+
+## Velden
+| Veld | Type | Mode | Validatie |
+|---|---|---|---|
+| ... | ... | create / edit / both | ... |
+
+## URL- of state-pattern
+- Gekozen: <URL-based | state-based>
+- Reden: <korte motivatie>
+- Routes (indien URL-based): `?new<Entity>=1` op `<route>`, `?edit<Entity>=<id>` op `<route>`
+
+## Status-veld (indien aanwezig)
+- Enum: ...
+- Dot-kleur-mapping: ...
+- Default bij create: ...
+
+## Server actions
+- `save<Entity>Action` — locatie, context-arg, revalidate-paden
+- `delete<Entity>Action` — locatie, context-arg, revalidate-paden
+
+## Speciale gedragingen (alleen indien de generieke spec niet volstaat)
+- ... (bv. story-log-tab, claude-question-historie, file-upload, etc.)
+
+## Bewust NIET in v1
+- ...
+```
+
+> Geen entity-profile = geen merge. Reviewers checken op het bestaan van het profiel-bestand bij een PR die een nieuwe dialog introduceert.
+
+---
+
+## 13 — Bewust **niet** in deze pattern (out of scope)
+
+Deze items zijn over het algemeen niet welkom in een dialog. Een entity-profile mag ze toevoegen, maar moet dan de afweging documenteren:
+
+- ❌ Bulk-edit (meerdere records tegelijk)
+- ❌ Drag-and-drop binnen de dialog (drag hoort op de lijst-view)
+- ❌ Tabs voor secties — alleen spacing-gebaseerde groepering
+- ❌ Section-headers — implicit via spacing, geen labels
+- ❌ Sub-entiteiten (parent-child binnen dezelfde dialog)
+- ❌ File uploads (uitzondering: avatar — eigen pattern)
+- ❌ Comments / activity log binnen de dialog (mag wel als read-only side-panel; zie `StoryLog`)
+- ❌ Optimistic locking — last-write-wins binnen scope
+- ❌ Cmd+K / quick-create zonder dialog
+- ❌ Templates voor terugkerende records
+- ❌ Telemetrie / per-veld analytics
+
+---
+
+## 14 — Verificatie-checklist (per nieuwe dialog)
+
+Reviewer en bouwer lopen deze door vóór merge:
+
+- [ ] Bouwt op `components/ui/dialog.tsx` (geen directe `@base-ui/react`-imports)
+- [ ] Composition via `render`-prop waar nodig
+- [ ] Layout volgt § 4 (responsive breakpoints, padding, sticky header/footer)
+- [ ] zod-schema in `lib/schemas/<entity>.ts`, gedeeld door form en action
+- [ ] Server action heeft `productAccessFilter(userId)` + `session.isDemo`-check
+- [ ] `proxy.ts` heeft een guard voor de bijbehorende write-route(s) (laag 1)
+- [ ] Submit/Delete-knoppen omwikkeld met `<DemoTooltip show={isDemo}>` (laag 3)
+- [ ] Foutcodes 422/403/500 correct teruggemapt naar UI (zie § 5)
+- [ ] Dirty-close-guard actief
+- [ ] Cmd/Ctrl+Enter submit, Esc sluit (met dirty-check)
+- [ ] Focus management: opent op eerste veld, geen auto-select in edit-mode
+- [ ] Motion + backdrop conform § 8.4–8.5
+- [ ] Alleen MD3-tokens; geen `bg-blue-500`-style classes
+- [ ] Footer-layout per mode conform § 10
+- [ ] Delete-flow: AlertDialog → action → toast
+- [ ] URL- of state-pattern gekozen + gedocumenteerd in entity-profile
+- [ ] Entity-profile bestaat in `docs/` en is up-to-date
+- [ ] Test gedekt: server action met validatie + demo + scope, en component-test op render + submit-flow
+
+---
+
+## 15 — Referenties
+
+- `CLAUDE.md` — UI Library Conventions, Demo-check, Foutcodes API, Validatie
+- `docs/scrum4me-styling.md` — MD3-tokens, kleurklassen
+- `docs/scrum4me-architecture.md` — Demo user policy, scope-helpers
+- `docs/patterns/server-action.md` — Server Action template (auth + Zod)
+- `docs/patterns/zustand-optimistic.md` — voor lijst-views die de dialog aanroepen
+- `docs/scrum4me-task-dialog.md` — voorbeeld-profile voor entiteit "Task"
diff --git a/docs/plans/ST-1114-copilot-reviews.md b/docs/plans/ST-1114-copilot-reviews.md
new file mode 100644
index 0000000..ce35a6d
--- /dev/null
+++ b/docs/plans/ST-1114-copilot-reviews.md
@@ -0,0 +1,133 @@
+# Plan — ST-1114 · Copilot reviews op dashboard
+
+## Context
+
+Als ontwerper wil je een overzicht zien van GitHub Copilot's PR-reviews om per stuk te beslissen of je 'm implementeert of overslaat. De codebase heeft nu **nul** GitHub-integratie — alleen `product.repo_url` als string voor hyperlinks. We bouwen een minimale, hobby-vriendelijke architectuur.
+
+## Architectuurkeuzes (via AskUserQuestion bevestigd)
+
+- **Auth**: lokaal script met `GITHUB_TOKEN` — webapp heeft GEEN GitHub-credentials. Het script draai je lokaal wanneer je wil verversen.
+- **Fetch**: on-demand op dashboard-load (server-side `prisma.copilotReview.findMany`, geen externe call)
+- **Decision**: alleen visuele toggle in `localStorage` (geen DB-persistentie)
+- **Scope**: MVP — tonen + lokale toggle. Geen cron, geen webhook, geen GitHub-auth in productie.
+
+## Architectuur
+
+```
+┌──────────────┐   octokit   ┌────────────┐   API token   ┌─────────────┐
+│ scripts/     │ ──────────▶ │  GitHub    │               │  Scrum4Me   │
+│ sync-copilot │             │  REST API  │               │  /api/      │
+│ -reviews.ts  │ ◀────────── │            │               │  copilot-   │
+└──────────────┘   reviews   └────────────┘   POST batch  │  reviews    │
+        │                                                  │             │
+        └──────────────────────────────────────────────────▶ DB upsert  │
+                                                            └──────┬──────┘
+                                                                   │
+                                                            ┌──────▼──────┐
+                                                            │  /dashboard │
+                                                            │ server-side │
+                                                            │ findMany    │
+                                                            └─────────────┘
+```
+
+Het script is de enige plek waar GitHub-credentials nodig zijn. Productie kent alleen Scrum4Me-data.
+
+## Datamodel
+
+```prisma
+model CopilotReview {
+  id            String   @id @default(cuid())
+  product       Product  @relation(fields: [product_id], references: [id], onDelete: Cascade)
+  product_id    String
+  pr_number     Int
+  pr_title      String
+  pr_url        String
+  pr_state      String   // 'open' | 'closed' | 'merged'
+  author_login  String   // bv. 'copilot-pull-request-reviewer[bot]'
+  review_state  String   // 'COMMENTED' | 'APPROVED' | 'CHANGES_REQUESTED'
+  body          String   @db.Text
+  submitted_at  DateTime
+  html_url      String   // directe link naar de review
+  fetched_at    DateTime @default(now())
+
+  @@unique([product_id, pr_number, submitted_at])
+  @@index([product_id, submitted_at])
+  @@map("copilot_reviews")
+}
+```
+
+`@@unique` zorgt voor idempotency — script kan herhaald draaien zonder dupes. Geen `decision`-veld: dat staat in `localStorage`.
+
+## Script
+
+`scripts/sync-copilot-reviews.ts` — TypeScript via `tsx`, leest env, gebruikt Octokit, POST naar eigen API.
+
+```bash
+GITHUB_TOKEN=ghp_... \
+SCRUM4ME_API_URL=http://localhost:3000 \
+SCRUM4ME_API_TOKEN=s4m_... \
+npx tsx scripts/sync-copilot-reviews.ts
+```
+
+Stappen:
+1. `GET /api/products` (Bearer-auth) — lijst toegankelijke producten met `repo_url`
+2. Per product: parse `owner/repo` uit `repo_url`, `octokit.pulls.list({state: 'all', per_page: 50})`
+3. Per PR: `octokit.pulls.listReviews(...)`, filter op `user.type === 'Bot' && user.login.includes('copilot')`
+4. `POST /api/copilot-reviews` met `{ product_id, reviews: [...] }` — endpoint doet `deleteMany` + `createMany` per product (atomic replace)
+5. Print samenvatting: aantal reviews per product + totale runtime
+
+## API endpoint
+
+`app/api/copilot-reviews/route.ts`:
+
+- **POST**: Bearer-auth, demo-block, payload `{ product_id, reviews: CopilotReview[] }`. Atomic transaction: delete-all-for-product → createMany. Validatie via Zod.
+- **GET**: niet nodig — dashboard leest direct via Prisma server-side. Endpoint kan komen voor toekomstige clients.
+
+## Dashboard widget
+
+Boven of onder de bestaande product-grid een nieuwe sectie "Copilot reviews".
+
+`components/dashboard/copilot-reviews.tsx` (client component):
+- Props: `reviews: CopilotReview[]` (server-fetched)
+- Lijst met cards: PR-titel + nummer (link naar PR), Copilot's body (truncated of accordion), state-badge, "Implementeer" / "Skip"-knoppen
+- Decision-state in `localStorage` keyed op `review.id`: `'implement' | 'skip' | undefined` (default: ongezien)
+- Cards met decision='skip' visueel gedimmed; cards met 'implement' krijgen een groen randje
+- Filter-toggles bovenaan: "Alle / Te beoordelen / Implementeren / Skip"
+- Empty state: "Geen Copilot-reviews gevonden — draai het sync-script."
+
+`app/(app)/dashboard/page.tsx` past `prisma.copilotReview.findMany({ where: { product_id: { in: accessibleIds } }, orderBy: { submitted_at: 'desc' } })` en geeft door.
+
+## Voorgestelde sub-tasks
+
+| Code | Onderwerp |
+|---|---|
+| ST-1114.2 | DB: `CopilotReview` model + migration |
+| ST-1114.3 | API: `POST /api/copilot-reviews` (Bearer-auth + demo-block + replace-by-product) |
+| ST-1114.4 | Script: `scripts/sync-copilot-reviews.ts` met octokit |
+| ST-1114.5 | UI: dashboard-widget met cards, localStorage-decision, filter-toggle |
+| ST-1114.6 | Tests: API endpoint (auth, demo-block, validation), dashboard-widget snapshot |
+| ST-1114.7 | Docs: README-sectie over script + env-vars; CLAUDE.md-update |
+
+## M11-keuzes voor de implementerende sessie
+
+Drie open beslissingen die niet kritiek zijn voor het plan zelf:
+
+1. **PR-state filter**: alle PR's of alleen `state=open`? (closed-PRs hebben oude reviews die misschien niet meer relevant zijn)
+2. **Markdown-rendering**: react-markdown, of plain `<pre>`? (react-markdown is +35KB bundle)
+3. **localStorage-key-vorm**: `scrum4me:copilot-decision:{review_id}` per review, of één map-object onder één key?
+
+## Branch + PR
+
+- Branch: `feat/M14-copilot-reviews` (M14 = nieuwe milestone)
+- 6 commits (.2 t/m .7), één per laag
+- PR pas openen na handmatige test door gebruiker
+
+## Verificatie (end-to-end)
+
+1. `npm run dev`
+2. `GITHUB_TOKEN=... SCRUM4ME_API_TOKEN=... npx tsx scripts/sync-copilot-reviews.ts` — toont `n reviews opgeslagen`
+3. Browser refresht dashboard → "Copilot reviews"-sectie toont cards met PR-titels
+4. Klik "Implementeer" → kaart krijgt groen randje, decision in localStorage
+5. Refresh → state blijft (localStorage)
+6. Filter toggle "Alleen te beoordelen" → cards met decision verdwijnen
+7. Demo-user: kan reviews zien, maar `POST /api/copilot-reviews` weigert (al via middleware-guard van ST-1110)
diff --git a/docs/plans/Tweede Claude Agent — Planning Agent.md b/docs/plans/Tweede Claude Agent — Planning Agent.md
new file mode 100644
index 0000000..7775d60
--- /dev/null
+++ b/docs/plans/Tweede Claude Agent — Planning Agent.md	
@@ -0,0 +1,346 @@
+# Plan: Tweede Claude Agent — Planning Agent (PBI/Story → children)
+
+> **Eerder goedgekeurd plan in deze file:** *Scrum4Me v1.0 Release* (mobile shell + sprint-snapshots + release-discipline). Beschikbaar in chat-history; te verhuizen naar `docs/plans/v1-release.md` op een later moment. Dit nieuwe plan vervangt de plan-file inhoudelijk niet — het v1.0-werk blijft van kracht parallel hieraan.
+
+---
+
+## Context
+
+**Wat de gebruiker wil:** twee gespecialiseerde Claude-agents, elk met eigen context.
+
+| Agent | Doel | Context | Status |
+|---|---|---|---|
+| **Implementation Agent** | Codeert één task af → branch + PR | Code-repo (filesystem), `implementation_plan`, story, pbi, sprint, repo_url | ✅ Live (M13 / ST-1111) |
+| **Planning Agent** *(nieuw)* | Genereert children: PBI→stories of story→tasks (incl. `implementation_plan` per task) | Specs + architectuur + patterns (filesystem in Scrum4Me-checkout), parent-record, bestaande children | ❌ Te bouwen |
+
+**Wat al staat (hergebruikbaar):**
+
+- `ClaudeJob`-model met state-machine `QUEUED→CLAIMED→RUNNING→DONE/FAILED`, `CANCELLED`-pad, stale-cleanup >30min
+- `ClaudeWorker`-model voor presence-heartbeat
+- SSE-pijplijn op `/api/realtime/solo` met payload-routing op `user_id + product_id`
+- MCP-tools `wait_for_job`, `update_job_status`, `get_claude_context`, `create_pbi`, `create_story`, `create_task`, `update_task_plan`, `log_implementation`
+- Idempotency-pattern: max 1 actieve job per resource
+
+**Vastgelegde keuzes (uit AskUserQuestion-sessies):**
+
+1. Agent kan **beide** niveaus: PBI→stories én story→tasks (één agent, twee modi via `target_type`)
+2. Output: items **direct in DB** aanmaken via bestaande `create_*`-tools — geen review-stap in v1
+3. Context: **lokaal draaien + filesystem-toegang** tot Scrum4Me-checkout (zoals impl-agent al doet)
+4. Rol-scheiding: **`ClaudeJob.kind` enum** (`IMPLEMENTATION` | `PLANNING`) — één table, polymorf
+5. Bestaande children: **aanvullen** — agent leest bestaande titels en voegt alleen ontbrekende toe
+6. Live feedback: **stille SSE + status-pill** op de PBI/Story-card; geen aparte modal
+7. MCP-shape: **bestaande `wait_for_job` uitbreiden** met `accept_kinds: string[]`-arg, default `['IMPLEMENTATION']` (backwards-compat)
+
+---
+
+## Approach (8 stappen)
+
+### Stap 1 — Schema-uitbreiding
+
+**`prisma/schema.prisma`:**
+
+```prisma
+enum ClaudeJobKind {
+  IMPLEMENTATION
+  PLANNING
+}
+
+enum PlanningTargetType {
+  PBI
+  STORY
+}
+
+enum ApiTokenKind {
+  IMPLEMENTATION
+  PLANNING
+  // beide kinds simultaan = afzonderlijke tokens; eenvoudiger dan multi-kind-flag
+}
+
+model ClaudeJob {
+  // ... bestaande velden ...
+  kind                ClaudeJobKind   @default(IMPLEMENTATION)
+  task_id             String?         // wordt nullable — planning-jobs hebben geen task
+  task                Task?           @relation(fields: [task_id], references: [id], onDelete: Cascade)
+  planning_target_type PlanningTargetType?
+  planning_target_id   String?
+
+  @@index([kind, status])
+  @@index([planning_target_type, planning_target_id, status])
+}
+
+model ApiToken {
+  // ... bestaande velden ...
+  kind  ApiTokenKind  @default(IMPLEMENTATION)
+}
+
+model ClaudeWorker {
+  // ... bestaande velden ...
+  // accepted_kinds wordt afgeleid uit token.kind (geen extra kolom nodig)
+}
+```
+
+**Constraint via DB-check (CHECK constraint of app-level):** een `ClaudeJob` heeft óf `task_id` (kind=IMPLEMENTATION) óf `planning_target_*` (kind=PLANNING). Nooit beide leeg, nooit beide gevuld.
+
+**Migratie:** alle bestaande rijen krijgen `kind=IMPLEMENTATION` + `apiToken.kind=IMPLEMENTATION` als default. Backwards-compatible.
+
+**Bestand:** `prisma/migrations/<date>_planning_job_kind/migration.sql`
+
+### Stap 2 — Status-mappers + Zod-schemas
+
+- `lib/claude-job-status.ts` — voeg `kind` toe aan API-shape (lowercase: `implementation` | `planning`)
+- `lib/schemas/claude-job.ts` (NEW of MODIFY) — discriminated union op `kind`
+- `lib/schemas/planning-target.ts` (NEW) — `{ type: 'PBI'|'STORY', id: string }` validator
+
+### Stap 3 — Server actions
+
+**`actions/claude-jobs.ts`** uitbreiden:
+
+```ts
+export async function enqueuePlanningJobAction(input: {
+  productId: string
+  target: { type: 'PBI' | 'STORY', id: string }
+}): Promise<EnqueueResult>
+```
+
+Logica:
+1. Auth-scope-check (`productAccessFilter`) — target moet binnen product zitten
+2. Demo-block (`session.isDemo` → 403)
+3. Idempotency: weiger als er al een `PLANNING`-job actief is voor dit `(target_type, target_id)`
+4. Insert `ClaudeJob` met `kind=PLANNING`, `task_id=null`, `planning_target_*` ingevuld
+5. `pg_notify('scrum4me_changes', { type: 'claude_job_enqueued', kind: 'planning', ... })`
+
+`cancelClaudeJobAction` (bestaand) blijft werken — accepteert nu ook PLANNING-jobs (zelfde state-machine).
+
+### Stap 4 — SSE-routing
+
+**`app/api/realtime/solo/route.ts`:**
+
+- Bestaande `claude_job_*`-events krijgen `kind` in payload
+- Bij connect: `claude_jobs_initial`-event bevat ook actieve PLANNING-jobs van vandaag
+- Filter blijft `user_id + product_id` — geen extra topic nodig
+
+### Stap 5 — UI: triggers + status-pills
+
+**Trigger in beide dialog-profielen** (geprofileerd in PR #45):
+
+| Locatie | Knop-label | Target |
+|---|---|---|
+| `components/backlog/story-dialog.tsx` (edit-mode) | `🤖 Genereer taken met Claude` | `{ type: 'STORY', id: story.id }` |
+| `components/backlog/pbi-dialog.tsx` (edit-mode) | `🤖 Genereer stories met Claude` | `{ type: 'PBI', id: pbi.id }` |
+
+Knop-gedrag:
+- `<DemoTooltip show={isDemo}>` rond knop (laag 3 demo-policy)
+- `disabled` als er al een PLANNING-job actief is voor deze target (live via SSE-store)
+- Tooltip bij disabled: "Plan-job al gestart — wachten op resultaat"
+- Klik → `enqueuePlanningJobAction` → toast "Plan gestart" → dialog blijft open zodat user resultaat ziet binnenkomen
+
+**Status-pill component (NEW):**
+
+`components/shared/planning-job-pill.tsx` — kleine badge die de status van een lopende PLANNING-job toont:
+- `QUEUED` — grijs, "In wachtrij"
+- `CLAIMED / RUNNING` — blauw met spinner, "Plan wordt gegenereerd…"
+- `DONE` — groen, fade-out na 5s
+- `FAILED` — rood, klikbaar voor error-detail
+- `CANCELLED` — niet getoond (verwijdert pill)
+
+Plaatsing:
+- Op `PbiList`-card naast PBI-titel (rechts)
+- Op `StoryPanel`-card naast story-titel (rechts)
+- In `PbiDialog` / `StoryDialog`-header (edit-mode) als large variant
+
+**Live updates:** bestaande `useClaudeJobsStore` (Zustand, populated uit SSE) — alleen `kind` toevoegen aan filter-helpers.
+
+### Stap 6 — MCP-tools (`scrum4me-mcp` repo, aparte PR)
+
+**Wijziging 1 — bestaande tool uitbreiden:**
+
+```ts
+// wait_for_job tool input schema
+{
+  accept_kinds?: ('IMPLEMENTATION' | 'PLANNING')[]  // default: ['IMPLEMENTATION']
+  wait_seconds?: number                             // bestaand
+}
+```
+
+Server-side: `WHERE kind = ANY($1) AND status = 'QUEUED'` in de `FOR UPDATE SKIP LOCKED`-query. Token-kind moet ook compatibel zijn (token.kind `IN` accept_kinds-overlap).
+
+Response-shape voegt `kind` toe; voor `PLANNING`-jobs vervangt `task` door `planning_target` met embedded record:
+
+```ts
+{
+  job_id: string
+  kind: 'IMPLEMENTATION' | 'PLANNING'
+  product: { id, name, repo_url, ... }
+  // IMPL-only:
+  task?: { ..., implementation_plan, story, pbi, sprint }
+  // PLANNING-only:
+  planning_target?: {
+    type: 'PBI' | 'STORY'
+    pbi?: { id, code, title, description, priority, status, existing_stories: [{ id, code, title, priority }] }
+    story?: { id, code, title, description, acceptance_criteria, priority, status, pbi: {...}, existing_tasks: [{ id, title, priority, status }] }
+  }
+}
+```
+
+**Wijziging 2 — nieuwe MCP-tool:**
+
+`get_planning_context(target_type, target_id)` — losstaande lookup voor agent die handmatig een planning wil starten zonder job-claim. Optioneel; `wait_for_job` retourneert dezelfde data al.
+
+**Geen nieuwe write-tools nodig:** bestaande `create_story` + `create_task` + `update_task_plan` werken al.
+
+**Schema-sync:** vendor/scrum4me submodule update na Scrum4Me-PR merge.
+
+### Stap 7 — Agent-prompt + lokale Claude-command
+
+In de Scrum4Me-checkout (of in een gedeelde plek voor agent-prompts) twee Claude Code commands:
+
+**`/implement-next-story`** — bestaand, gebruikt `wait_for_job({ accept_kinds: ['IMPLEMENTATION'] })`
+
+**`/generate-plan`** — nieuw:
+
+Korte prompt-flow:
+1. `wait_for_job({ accept_kinds: ['PLANNING'], wait_seconds: 600 })` — claim
+2. Lees `planning_target` uit response (PBI of STORY) + `existing_*`
+3. **Lees lokale docs uit Scrum4Me-checkout:**
+   - `docs/scrum4me-functional-spec.md` (functioneel kader)
+   - `docs/scrum4me-architecture.md` (technisch kader)
+   - `docs/patterns/*.md` (relevante patterns op basis van target-titel/-beschrijving)
+   - `docs/scrum4me-styling.md` als target UI-werk betreft
+4. Bedenk children:
+   - Voor `STORY`-target: 3-7 taken met titel, korte beschrijving, `implementation_plan` (verwijst naar relevante patterns + bestanden), priority
+   - Voor `PBI`-target: 2-5 stories met titel, beschrijving in user-story-format, acceptance_criteria, priority
+5. Filter ontbrekende items: skip wat overlapt met `existing_*` (titel-match)
+6. Voor elk: `create_task` of `create_story` via MCP
+7. `update_job_status({ status: 'DONE', summary: 'Aangemaakt: 4 taken / 0 overgeslagen (titel-overlap)' })`
+
+Bij failure: `update_job_status({ status: 'FAILED', error })` + toast voor user.
+
+**Mens-rolverdeling:** twee Claude Code-sessies tegelijk draaien (één met `/implement-next-story` running, één met `/generate-plan` running). Beide claimen alleen hun eigen kind via `accept_kinds`. Dezelfde gebruiker-token of twee aparte (afhankelijk van hoe je workers wilt scheiden).
+
+### Stap 8 — Tests
+
+| Test | Locatie |
+|---|---|
+| `enqueuePlanningJobAction` — auth, demo, idempotency, scope | `__tests__/actions/claude-jobs-planning.test.ts` |
+| Schema-mapper voor `kind` + `planning_target_*` | `__tests__/lib/claude-job-status.test.ts` |
+| SSE-event format met `kind` | `__tests__/api/realtime-solo-planning.test.ts` |
+| Status-pill rendering per status | `__tests__/components/shared/planning-job-pill.test.tsx` |
+| Knop disabled-state in StoryDialog/PbiDialog bij actieve job | `__tests__/components/backlog/dialog-planning-button.test.tsx` |
+
+MCP-tools testen in `scrum4me-mcp` repo (aparte PR).
+
+---
+
+## Critical files
+
+### Scrum4Me-repo
+
+| File | Action | Reden |
+|---|---|---|
+| `prisma/schema.prisma` | MODIFY | `ClaudeJobKind`, `PlanningTargetType`, `ApiTokenKind` enums + nullable `task_id` + `planning_target_*` velden |
+| `prisma/migrations/<date>_planning_job_kind/` | NEW | Migratie + check-constraint |
+| `lib/claude-job-status.ts` | MODIFY | `kind` in API-shape |
+| `lib/schemas/claude-job.ts` | NEW/MODIFY | Discriminated union op `kind` |
+| `lib/schemas/planning-target.ts` | NEW | Target-validator |
+| `actions/claude-jobs.ts` | MODIFY | `enqueuePlanningJobAction` toevoegen, idempotency uitbreiden |
+| `app/api/realtime/solo/route.ts` | MODIFY | `kind` in payload, initial-state ook PLANNING-jobs |
+| `stores/claude-jobs-store.ts` (of vergelijkbaar) | MODIFY | `kind`-filter helpers |
+| `components/backlog/story-dialog.tsx` | MODIFY | "Genereer taken"-knop + status-pill in header |
+| `components/backlog/pbi-dialog.tsx` | MODIFY | "Genereer stories"-knop + status-pill in header |
+| `components/backlog/story-panel.tsx` | MODIFY | Status-pill op story-card |
+| `components/backlog/pbi-list.tsx` | MODIFY | Status-pill op pbi-card |
+| `components/shared/planning-job-pill.tsx` | NEW | Generic pill-component |
+| `docs/patterns/claude-agent-roles.md` | NEW | Pattern-doc: één table, kind-enum, accept_kinds-arg, lokale agent-prompts |
+| `docs/scrum4me-architecture.md` | MODIFY | Sectie "Claude Agents" uitbreiden — twee rollen, schema, queue, prompts |
+| `docs/scrum4me-pbi-dialog.md` | MODIFY | Sectie "Speciale gedragingen → Planning-trigger" toevoegen |
+| `docs/scrum4me-story-dialog.md` | MODIFY | Idem |
+| `docs/scrum4me-task-dialog.md` | MODIFY | Vermelden dat tasks ook door planning-agent kunnen ontstaan |
+| `__tests__/actions/claude-jobs-planning.test.ts` | NEW | |
+| `__tests__/lib/claude-job-status.test.ts` | MODIFY | `kind`-mapping testen |
+| `__tests__/api/realtime-solo-planning.test.ts` | NEW | |
+| `__tests__/components/shared/planning-job-pill.test.tsx` | NEW | |
+| `__tests__/components/backlog/dialog-planning-button.test.tsx` | NEW | |
+
+### scrum4me-mcp repo (aparte PR, na Scrum4Me-merge)
+
+| File | Action |
+|---|---|
+| `src/tools/wait_for_job.ts` | MODIFY — `accept_kinds`-arg + polymorf response |
+| `src/tools/get_planning_context.ts` | NEW (optioneel, helper) |
+| `src/types/job.ts` | MODIFY — kind + planning_target |
+| `src/prompts/generate-plan.md` | NEW — Claude command-prompt |
+| `vendor/scrum4me/` (submodule) | UPDATE — na Scrum4Me-merge |
+
+---
+
+## Volgorde van uitvoering
+
+1. **Schema + migratie + status-mapper** (Stap 1+2) — eigen commit, geen UI-impact
+2. **Server action `enqueuePlanningJobAction` + tests** (Stap 3) — werkt headless via curl/test
+3. **SSE-payload uitbreiden + claude-jobs-store** (Stap 4) — backend pipe klaar
+4. **Status-pill component + tests** (Stap 5a) — losstaande primitive
+5. **Trigger-knoppen in StoryDialog + PbiDialog** (Stap 5b) — UI-trigger werkt, agent nog niet
+6. **Pause** — verifieer end-to-end met handmatig insert in `claude_jobs` (kind=PLANNING) of via mock-MCP-call
+7. **MCP-PR in scrum4me-mcp repo** (Stap 6) — `wait_for_job` uitbreiden, types updaten
+8. **Lokaal `/generate-plan`-command schrijven + testen** (Stap 7) — agent claimt, leest, schrijft
+9. **End-to-end test** (Stap 8) — story → klik knop → agent rendert taken → SSE → live in TaskPanel
+10. **Docs-PR** — pattern-doc `claude-agent-roles.md`, architecture-update, dialog-profielen aanvullen
+
+Branch-naming: `feat/M15-planning-agent` (Scrum4Me) + `feat/planning-agent` (scrum4me-mcp).
+
+Conform CLAUDE.md "branch-per-milestone": commits accumuleren lokaal, pushen pas na gebruikerstest.
+
+---
+
+## Verification
+
+1. `npm run lint && npm test && npm run build` groen
+2. **Schema-migratie:** bestaande `claude_jobs`-rijen krijgen `kind=IMPLEMENTATION`; check-constraint blokkeert ongeldige combinaties
+3. **Idempotency:** twee keer klikken op "Genereer taken" → tweede klik geeft toast "Plan-job al gestart", knop disabled
+4. **Demo-block:** demo-user ziet knop disabled met DemoTooltip; server action returnt 403 als je 'm toch aanroept
+5. **SSE live:** trigger planning-job → status-pill verschijnt op story-card binnen 1s zonder refresh
+6. **End-to-end:** lokale `/generate-plan` agent claimt job, leest target via `wait_for_job`, leest 3-4 docs uit Scrum4Me-checkout, maakt 3-5 taken via `create_task`, status DONE → taken zichtbaar in TaskPanel zonder refresh
+7. **Cancel-flow:** gebruiker kan vanuit dialog een running PLANNING-job cancellen → status-pill verdwijnt, agent ziet job-status `CANCELLED` bij volgende `update_job_status`
+8. **Cross-kind isolation:** een implementation-agent met `accept_kinds=['IMPLEMENTATION']` (default) ziet PLANNING-jobs niet; idem omgekeerd
+9. **Aanvullen-policy:** trigger op story die al 2 taken heeft — agent voegt alleen ontbrekende toe (logged in summary: "Aangemaakt: 3 / Overgeslagen: 2 (titel-overlap)")
+10. **Documentatie:** `docs/patterns/claude-agent-roles.md` beschrijft beide agent-rollen, hun job-flow, en hoe je een derde agent zou toevoegen
+
+---
+
+## Open punten (na approval expliciet maken)
+
+1. **Token-strategie:** krijgt elke agent-rol een eigen ApiToken (cleaner, twee credentials), of bestaat er één multi-kind-token per user? *Voorstel: aparte tokens — één per kind. Gebruiker beheert ze in Settings.*
+2. **Concurrency in 1 worker:** mag `accept_kinds: ['IMPLEMENTATION', 'PLANNING']` (één worker pakt allebei)? *Voorstel: ja, technisch toegestaan, maar in v1 raad je af want context-pollution. Documenteren als "kan, maar gebruik gescheiden processen".*
+3. **Doc-selectie:** hoe bepaalt de agent welke `docs/patterns/*.md` relevant zijn? *Voorstel: lees `docs/patterns/`-index op + match op keywords uit target-titel/-beschrijving. Geen embeddings in v1.*
+4. **Hoeveel children per run?** *Voorstel: hard cap 8 in de prompt (anders gaat 'ie speculeren). Gebruiker kan opnieuw klikken voor meer.*
+5. **Editable plan-text:** wanneer agent `implementation_plan` invult op een nieuwe task, kan de gebruiker die later via TaskDialog editen — dat werkt al, geen extra werk.
+6. **Failure-recovery:** wat als agent halverwege crasht? Stale-cleanup >30min werkt al; partial-children blijven aangemaakt. *Voorstel: accepteer partial — gebruiker kan opnieuw triggeren, aanvullen-policy filtert duplicaten.*
+
+---
+
+## Out of scope (v1 van deze feature)
+
+- ❌ Diff-review-flow (vervangen-modus uit eerdere AskUserQuestion)
+- ❌ Live streaming-output van agent (alleen status-events, geen tekst-stream)
+- ❌ Meerdere parallele PLANNING-jobs op dezelfde target (idempotency blokkeert)
+- ❌ Custom prompts per product (vaste prompt-template `/generate-plan`)
+- ❌ Embeddings / vector-search over docs (agent leest plain files)
+- ❌ Cross-user planning (agent werkt altijd binnen eigen product-scope)
+- ❌ Auto-trigger (bv. "elke nieuwe lege story krijgt automatisch een plan-job") — handmatige trigger blijft regel
+- ❌ Agent-tot-agent-orkestratie (planning-agent kan geen impl-agent triggeren) — gebruiker blijft in the loop
+- ❌ Planning op product-niveau (PBI's genereren) — pas zinvol als product-spec-input bestaat
+- ❌ Planning-agent UI in Solo Paneel (Solo blijft impl-only) — triggers zitten in backlog-dialogs
+
+---
+
+## Migratie-pad voor toekomstige derde agent (referentie)
+
+Als er ooit een derde agent komt (bv. **review-agent** die een PR review't):
+
+1. `ClaudeJobKind` enum uitbreiden met `REVIEW`
+2. `ApiTokenKind` enum uitbreiden met `REVIEW`
+3. `enqueueReviewJobAction` aanmaken (kopieert pattern van planning)
+4. `wait_for_job` accepteert nieuwe `kind` automatisch via `accept_kinds`
+5. Pattern-doc `claude-agent-roles.md` uitbreiden met de derde rol
+
+Geen schema-revolutie nodig — `kind`-enum is het uitbreidingspunt.
diff --git a/docs/scrum4me-pbi-dialog.md b/docs/scrum4me-pbi-dialog.md
new file mode 100644
index 0000000..79fb5ae
--- /dev/null
+++ b/docs/scrum4me-pbi-dialog.md
@@ -0,0 +1,120 @@
+# PbiDialog Profiel
+
+> Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me).
+> Dit document beschrijft alleen de PBI-specifieke afwijkingen en keuzes — alle gedeelde regels (layout, motion, demo-policy, foutcodes, validatie, theming, dialog-gedrag) staan in de generieke spec en worden hier niet herhaald.
+
+> **Belangrijk:** als een regel in dit profiel botst met de generieke spec, wint de generieke spec. Documenteer hier de afwijking + reden, of pas de generieke spec aan.
+
+---
+
+## Velden
+
+| Veld | Type | Mode | Validatie |
+|---|---|---|---|
+| `code` | `string \| null` | beide | optional, max 30 chars, mono-font, placeholder `auto` op create (server kent dan zelf een code toe) |
+| `title` | `string` (required) | beide | trim, 1-200 chars |
+| `priority` | `int` (1-4, P1 = hoogste) | beide | int 1-4, default 2 (kan via `defaultPriority`-prop bij create) |
+| `status` | `PbiStatusApi` enum | beide | enum, default `'ready'` |
+| `description` | `string \| null` | beide | optional, max 2000 chars, plain textarea (geen markdown rendering binnen de dialog) |
+
+`PbiStatusApi` enum (lowercase, mapped via `lib/task-status.ts`): zie `<PbiStatusSelect>` voor de waarden.
+
+### Veld-specifiek gedrag
+
+- **Code + Titel** in één rij (`grid-cols-[6rem_1fr]`)
+- **Prioriteit + Status** in één rij (`grid-cols-2`)
+- **Prioriteit** via `<PrioritySelect>` (gedeelde primitive, géén segmented buttons in deze dialog)
+- **Status** via `<PbiStatusSelect>` (PBI-specifieke wrapper rond gedeelde select)
+- **Description** is `<Textarea rows={3} resize-none>` — géén auto-grow, géén markdown-hint, géén char-counter (afwijking van generieke spec; rationale: PBI-descriptions zijn doorgaans kort en richtinggevend)
+
+---
+
+## URL- of state-pattern
+
+- **Gekozen:** state-based (`state: PbiDialogState | null` prop, gerendeerd binnen `PbiList`)
+- **Reden:** PBI-dialog leeft altijd binnen `PbiList` op de product-backlog-pagina; deep-linking is niet vereist en zou een tweede edit-flow toevoegen.
+- **State-shape:**
+  ```ts
+  type PbiDialogState =
+    | { mode: 'create'; productId: string; defaultPriority?: number }
+    | { mode: 'edit'; pbi: PbiDialogPbi; productId: string }
+  ```
+- **Sluiten:** `onClose()` callback uit de parent — `setState(null)` in `PbiList`.
+
+---
+
+## Status-veld
+
+- **Default bij create:** `'ready'` (PBI-default state)
+- **Geen verberging in create-mode** — anders dan TaskDialog wordt status hier wél getoond bij create, omdat een PBI zonder expliciete status onhandig is voor backlog-grooming
+
+---
+
+## Server actions
+
+| Actie | Locatie | Form-binding | Revalidatie |
+|---|---|---|---|
+| `createPbiAction` | `actions/pbis.ts` | via `useActionState` + `<form action>` (FormData) | server-side `revalidatePath` op product-backlog |
+| `updatePbiAction` | `actions/pbis.ts` | idem | idem |
+| ~~`deletePbiAction`~~ | **(ontbreekt)** | n.v.t. | n.v.t. |
+
+Beide acties moeten de drielaagse demo-policy volgen (zie § Bekende gaps).
+
+---
+
+## Speciale gedragingen
+
+### Form-state via `useActionState`
+
+PbiDialog gebruikt het `useActionState` + `useFormStatus`-patroon (Server Actions / native React), niet `react-hook-form`. Dit is een toegestaan alternatief volgens de generieke spec § 2. Field-errors worden gemapt via een lokale `fieldError(field)`-helper die `result.error` als `Record<string, string[]>` interpreteert wanneer 'm geen string is.
+
+### `key`-prop op `<form>`
+
+Het `<form>`-element heeft `key={isEdit ? pbi!.id : 'create'}` — dit reset native form-state (defaultValues) wanneer de dialog tussen create en edit wisselt of wanneer een ander record bewerkt wordt.
+
+### Hidden inputs voor server-binding
+
+`priority` en `status` worden via `<input type="hidden">` doorgegeven aan de Server Action (de UI-controls zijn JS-state, niet directe form-fields).
+
+---
+
+## Triggers
+
+- **Create-trigger:** `+ PBI`-knop in `PanelNavBar` van `PbiList` → `setPbiDialogState({ mode: 'create', ... })`
+- **Edit-trigger:** edit-icoon op een PBI-rij in `PbiList` → `setPbiDialogState({ mode: 'edit', pbi, ... })`
+
+---
+
+## Bekende gaps t.o.v. generieke spec
+
+> Deze items wijken af van `docs/patterns/dialog.md` en horen in een vervolg-PR rechtgezet (niet onderdeel van de huidige docs-introductie).
+
+- ❌ **Geen `<DemoTooltip>`** rond submit-knop — laag 3 van de drielaagse demo-policy ontbreekt voor PBI-create/update. Dat betekent dat een demo-user de knop kan klikken; de server action blokkeert nog steeds (laag 2), maar de UX is suboptimaal.
+- ❌ **Geen delete-knop / `deletePbiAction`** — alleen create + update. Of dat bewust is (PBI's worden nooit verwijderd, alleen status veranderd) of een gat, moet expliciet worden besloten en in dit profiel vastgelegd.
+- ❌ **Geen dirty-close-guard** — Esc / backdrop / Cancel sluiten direct, ook met onopgeslagen wijzigingen. Generieke spec § 8.1 vereist een AlertDialog bij `isDirty`.
+- ❌ **Geen Cmd/Ctrl+Enter shortcut** — alleen klik op submit-knop.
+- ❌ **Geen char-counter / markdown-hint** op description — bewust weggelaten omdat PBI-descriptions kort zijn, maar verdient expliciete bevestiging.
+- ⚠️ **Layout wijkt af** van de generieke responsive-tabel: `sm:max-w-md` i.p.v. de `max-w-[50vw]` / `90vw` / full-screen-progressie uit § 4.
+
+---
+
+## Bewust NIET in v1
+
+Specifiek voor PbiDialog (boven op de algemene out-of-scope-lijst in `docs/patterns/dialog.md` § 13):
+
+- ❌ Inline aanmaken van child-stories binnen de PBI-dialog (gebeurt via StoryDialog vanuit `StoryPanel`)
+- ❌ Bulk-status-update over meerdere PBI's
+- ❌ PBI-templates / kopiëren
+
+---
+
+## Referenties
+
+- `components/backlog/pbi-dialog.tsx` — implementatie
+- `actions/pbis.ts` — server actions
+- `components/shared/priority-select.tsx` — gedeelde priority-control
+- `components/shared/pbi-status-select.tsx` — PBI-status-select
+- `lib/task-status.ts` — `PbiStatusApi`-mapper
+- `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
+- `docs/scrum4me-architecture.md` — datamodel `Pbi`
+- `docs/scrum4me-styling.md` — MD3-tokens, status- en priority-kleuren
diff --git a/docs/scrum4me-story-dialog.md b/docs/scrum4me-story-dialog.md
new file mode 100644
index 0000000..250dec0
--- /dev/null
+++ b/docs/scrum4me-story-dialog.md
@@ -0,0 +1,163 @@
+# StoryDialog Profiel
+
+> Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me).
+> Dit document beschrijft alleen de Story-specifieke afwijkingen en keuzes — alle gedeelde regels (layout, motion, demo-policy, foutcodes, validatie, theming, dialog-gedrag) staan in de generieke spec en worden hier niet herhaald.
+
+> **Belangrijk:** als een regel in dit profiel botst met de generieke spec, wint de generieke spec. Documenteer hier de afwijking + reden, of pas de generieke spec aan.
+
+---
+
+## Velden
+
+| Veld | Type | Mode | Validatie |
+|---|---|---|---|
+| `code` | `string \| null` | beide | optional, max 30 chars, mono-font, placeholder `auto` op create |
+| `title` | `string` (required) | beide | trim, 1-200 chars |
+| `priority` | `int` (1-4, P1 = hoogste) | beide | int 1-4, default 2 (overschrijfbaar via `defaultPriority`-prop bij create) |
+| `description` | `string \| null` | beide | optional, plain textarea, placeholder `Als… wil ik… zodat…` (user-story-template) |
+| `acceptance_criteria` | `string \| null` | beide | optional, plain textarea, placeholder `- Gegeven… Als… Dan…` (Gherkin-template) |
+| `status` | `StoryStatus` enum | alleen edit | read-only badge in header, niet bewerkbaar in deze dialog |
+
+`StoryStatus` enum: `OPEN | IN_SPRINT | DONE` (uppercase in DB).
+
+### Veld-specifiek gedrag
+
+- **Code + Titel** in één rij (`grid-cols-[6rem_1fr]`)
+- **Prioriteit** via `<PrioritySelect>` (gedeelde primitive)
+- **Description** als `<Textarea rows={3} resize-none>` — géén auto-grow, géén markdown-hint binnen de dialog (afwijking van generieke spec; rationale: stories zijn meestal één zin)
+- **Acceptatiecriteria** idem — géén auto-grow, géén char-counter
+- **Status** wordt **niet bewerkt** vanuit deze dialog. Status verandert via lijst-acties (sleep naar sprint = IN_SPRINT, taak-completion = DONE). Read-only badge in dialog-header.
+
+---
+
+## URL- of state-pattern
+
+- **Gekozen:** state-based (`state: StoryDialogState | null` prop, gerendeerd binnen `StoryPanel`)
+- **Reden:** StoryDialog leeft binnen `StoryPanel` met live-store-data (geselecteerde PBI bepaalt zichtbare stories); deep-linking zou parallelle data-fetch-paden vereisen.
+- **State-shape:**
+  ```ts
+  type StoryDialogState =
+    | { mode: 'create'; pbiId: string; productId: string; defaultPriority?: number }
+    | { mode: 'edit'; story: Story; productId: string }
+  ```
+- **Sluiten:** `onClose()` callback uit de parent — `setState(null)` in `StoryPanel`.
+
+---
+
+## Status-veld
+
+- **Niet bewerkbaar in deze dialog** — alleen weergegeven als badge in de header (edit-mode)
+- **Default bij create:** `OPEN` (server-default, niet expliciet gezet vanuit form)
+- Status-overgangen lopen via:
+  - `OPEN → IN_SPRINT` — drag-and-drop naar een sprint of `sprint-id` zetten via story-actions
+  - `IN_SPRINT → DONE` — alle taken op `DONE` zetten triggert auto-promotion (zie story-status-logic in `actions/stories.ts`)
+
+---
+
+## Server actions
+
+| Actie | Locatie | Form-binding | Revalidatie |
+|---|---|---|---|
+| `createStoryAction` | `actions/stories.ts` | via `useActionState` + `<form action>` (FormData) | server-side `revalidatePath` op product-backlog |
+| `updateStoryAction` | `actions/stories.ts` | idem | idem |
+| `deleteStoryAction` | `actions/stories.ts` | aangeroepen vanuit `useTransition` (geen form) | server-side `revalidatePath` |
+| `getStoryLogsAction` | `actions/stories.ts` | aangeroepen on-mount in edit-mode | n.v.t. (read-only) |
+
+Alle write-acties zijn drielaags afgedekt (proxy-guard + server-action-check + DemoTooltip op submit-knop).
+
+---
+
+## Speciale gedragingen
+
+### Header-presentatie (afwijking van generieke spec)
+
+In edit-mode toont de dialog-header **drie elementen** boven op de standaard titel:
+
+1. Story-titel als dialog-title (groot)
+2. Story-code als monospace-badge rechtsboven (klein)
+3. Twee badges direct onder de titel: priority-badge (kleur via `PRIORITY_COLORS`) en status-badge (kleur via `STATUS_COLORS`)
+
+Generieke spec gaat uit van een sobere header met alleen `headline-small` titel + optioneel een `created_at`-meta-string. StoryDialog wijkt hier bewust van af omdat status + priority belangrijke context zijn voor de gebruiker bij het openen van een story (vaak wisselt iemand vlot tussen meerdere stories).
+
+### Demo-modus = read-only weergave
+
+Wanneer `isDemo === true` én `isEdit === true`, wordt het form **vervangen** door een read-only weergave:
+
+- `description` via gedeelde `<Markdown>`-wrapper (`react-markdown` + `remark-gfm`)
+- `acceptance_criteria` als plain whitespace-pre-line tekst
+
+In create-mode is er voor demo-users niets te tonen — de dialog wordt alsnog geopend maar de submit-knop is `disabled` met `<DemoTooltip>`.
+
+> Dit "read-only-fallback"-patroon is uniek voor StoryDialog tot nu toe. Het zou geadopteerd kunnen worden door andere edit-dialogs zodra demo-flow-vereisten dat rechtvaardigen.
+
+### Activity-log (StoryLog) inline
+
+In edit-mode wordt onder het form een `<StoryLog>`-paneel getoond met de chronologische logs van deze story (commit-hashes, status-transitions, etc.). Logs worden lazy-fetched via `getStoryLogsAction(story.id)` zodra de dialog opent.
+
+Dit is een **read-only side-panel** en valt binnen de uitzondering die de generieke spec § 13 maakt voor `<StoryLog>`-style activity-rendering.
+
+### Delete-flow (afwijking van generieke spec)
+
+Generieke spec § 10.4 vereist een **`AlertDialog`** voor delete-confirmatie. StoryDialog gebruikt in plaats daarvan een **inline-confirm** in dezelfde footer-rij:
+
+```
+[ Weet je het zeker? Taken worden ook verwijderd.   [Verwijderen]  [Annuleren] ]
+```
+
+Een `AlertDialog` zou een tweede modale laag toevoegen die in deze context onhandig voelt (de dialog zelf is al een interruptive overlay). De inline-confirm is een **bewuste afwijking** van de generieke spec.
+
+### Form-state via `useActionState`
+
+Net als PbiDialog gebruikt StoryDialog `useActionState` + `useFormStatus`, niet `react-hook-form`. Dit is een toegestaan alternatief volgens de generieke spec § 2.
+
+### `key`-prop op `<form>`
+
+Het `<form>` heeft `key={isEdit ? story!.id : 'create'}` — reset native form-state bij record-wissel of mode-switch.
+
+---
+
+## Triggers
+
+- **Create-trigger:** `+ Story`-knop in `PanelNavBar` van `StoryPanel` → `setStoryDialogState({ mode: 'create', pbiId, productId, defaultPriority: 2 })`
+- **Edit-trigger:** edit-icoon op een story-card in `StoryPanel` → `setStoryDialogState({ mode: 'edit', story, productId })`
+- **Empty-state-trigger:** `Maak je eerste story aan`-knop in `EmptyPanel` (zelfde state als create-trigger)
+
+---
+
+## Bekende gaps t.o.v. generieke spec
+
+> Deze items wijken af van `docs/patterns/dialog.md` en horen in een vervolg-PR rechtgezet (niet onderdeel van de huidige docs-introductie).
+
+- ❌ **Geen dirty-close-guard** — Esc / backdrop / Cancel sluiten direct, ook met onopgeslagen wijzigingen. Generieke spec § 8.1 vereist een AlertDialog bij `isDirty`.
+- ❌ **Geen Cmd/Ctrl+Enter shortcut** — alleen klik op submit-knop.
+- ❌ **Geen char-counter / markdown-hint** op description / acceptance_criteria — bewust weggelaten, maar verdient expliciete bevestiging als design-keuze.
+- ⚠️ **Inline-delete-confirm** in plaats van AlertDialog (zie § Speciale gedragingen). Bewuste afwijking; de generieke spec mag deze variant expliciet toestaan, of dit profile moet als precedent gelden voor toekomstige dialogen.
+- ⚠️ **Header-layout** met meerdere badges wijkt af van de sobere header in § 4. Bewuste afwijking — context-zwaar bij story-wisselen.
+- ⚠️ **Layout wijkt af** van de generieke responsive-tabel: `sm:max-w-lg` met eigen `max-h-[90vh]` + `flex flex-col` i.p.v. de exacte `max-w-[50vw]` / `90vw` / full-screen-progressie uit § 4.
+
+---
+
+## Bewust NIET in v1
+
+Specifiek voor StoryDialog (boven op de algemene out-of-scope-lijst in `docs/patterns/dialog.md` § 13):
+
+- ❌ Status bewerken vanuit de dialog (gebeurt via lijst-acties / drag-and-drop / auto-promotion)
+- ❌ Inline aanmaken van child-tasks (gebeurt via TaskDialog vanuit `TaskPanel`)
+- ❌ Bulk-edit over meerdere stories
+- ❌ Story-templates
+- ❌ Linking aan externe issues (GitHub / Linear) — staat op v1.1+ roadmap
+
+---
+
+## Referenties
+
+- `components/backlog/story-dialog.tsx` — implementatie
+- `actions/stories.ts` — server actions (incl. `getStoryLogsAction`)
+- `components/shared/priority-select.tsx` — gedeelde priority-control
+- `components/shared/story-log.tsx` — activity-log paneel
+- `components/shared/demo-tooltip.tsx` — demo-policy laag 3
+- `components/markdown.tsx` — gedeelde markdown-wrapper
+- `lib/task-status.ts` — status-enum-mapper
+- `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
+- `docs/scrum4me-architecture.md` — datamodel `Story`
+- `docs/scrum4me-styling.md` — MD3-tokens, status- en priority-kleuren
diff --git a/docs/scrum4me-task-dialog.md b/docs/scrum4me-task-dialog.md
index fa676bd..c2ecca1 100644
--- a/docs/scrum4me-task-dialog.md
+++ b/docs/scrum4me-task-dialog.md
@@ -1,506 +1,127 @@
-# Scrum4Me — TaskDialog Spec
+# TaskDialog Profiel
 
-> Volledige design-spec voor de add/update task dialog van de inspannings monitor app.
-> Resultaat van een grill-me sessie (15 vragen, alle beslissingen vastgelegd).
+> Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me).
+> Dit document beschrijft alleen de Task-specifieke afwijkingen en keuzes — alle gedeelde regels (layout, motion, demo-policy, foutcodes, validatie, theming, dialog-gedrag) staan in de generieke spec en worden hier niet herhaald.
 
----
-
-## Stack
-
-- **Framework:** Next.js (App Router)
-- **ORM:** Prisma
-- **UI components:** shadcn/ui — wrappers rond `@base-ui/react` (zoals expliciet vastgelegd in `CLAUDE.md`)
-- **Styling:** Tailwind CSS
-- **Form:** react-hook-form + @hookform/resolvers/zod
-- **Design language:** Material Design 3 als theming-laag (geen MUI components)
-- **Theming:** `material-color-utilities` voor dynamic color, `next-themes` voor dark mode
-- **Icons:** Lucide
-- **Markdown rendering:** `react-markdown` + `remark-gfm`
-- **Toasts:** sonner (shadcn default)
-
-> **Composition-regel:** dit project gebruikt `@base-ui/react`, niet Radix. Composition gebeurt via de **`render`-prop**, niet via `asChild`. Zie ook `CLAUDE.md` "UI Library Conventions".
->
-> ```tsx
-> // ✅ goed
-> <TooltipTrigger render={<button />}>...</TooltipTrigger>
-> // ❌ fout — geeft TS-errors
-> <TooltipTrigger asChild><button>...</button></TooltipTrigger>
-> ```
-
-> **Dialog-primitive:** bouw de TaskDialog op de bestaande wrapper in `components/ui/dialog.tsx` (shadcn rond `@base-ui/react`). **Geen** directe imports uit `@base-ui/react` voor dialog-primitives in deze feature — anders krijg je twee parallelle dialog-implementaties die uit de pas gaan lopen qua animatie, focus-trap en theming.
-
----
-
-## Dependency-impact
-
-De volgende packages staan **nog niet** in `package.json` en moeten direct als runtime-`dependencies` worden toegevoegd voordat de eerste commit van deze feature gemerged wordt (CLAUDE.md "Dependencies"-regel). Voeg ze in dezelfde change toe waarin ze geïmporteerd worden, en vermeld ze in de docs-sync.
-
-| Package | Doel | Scope |
-|---|---|---|
-| `react-hook-form` | form-state management voor TaskDialog | runtime |
-| `@hookform/resolvers` | zod-resolver voor `react-hook-form` | runtime |
-| `react-textarea-autosize` | auto-grow textareas voor `description` / `implementation_plan` | runtime |
-| `react-markdown` | markdown rendering elders in de app (taakdetail, hover-card) | runtime |
-| `remark-gfm` | GFM-extensies (tabellen, taken, strikethrough) | runtime |
-| `@tailwindcss/typography` | `prose`-classes voor markdown-styling | runtime (Tailwind v4 plugin) |
-
-**Bewust niet meegenomen:**
-
-- `material-color-utilities` — dynamic color valt buiten v1 (zie Theming hieronder).
-- `nuqs` — start met **native `searchParams`**; als de URL-state-handling te omslachtig wordt, dan pas `nuqs` als losse refactor-task introduceren. Niet in deze feature mengen.
-
-Reeds aanwezig en gebruikt: `@base-ui/react`, `next-themes`, `lucide-react`, `sonner`, `zod`, `prisma`.
-
----
-
-## Component-API
-
-Eén component `TaskDialog`, mode afgeleid uit `task?: Task` prop:
-
-```tsx
-<TaskDialog task={editTask} />   // task undefined = create mode, task aanwezig = edit mode
-```
-
-Open/close-state komt uit de URL via `nuqs` of `searchParams`. Taken leven binnen de context van een sprint of een PBI/story — er is **geen** zelfstandige `/tasks`-route:
-
-```
-/sprint/<sprintId>?newTask=1               → create-dialog open binnen sprint-context
-/sprint/<sprintId>?editTask=<taskId>       → edit-dialog open binnen sprint-context
-/products/<productId>/backlog?newTask=1    → create-dialog open binnen backlog-context
-/products/<productId>/backlog?editTask=<taskId>
-```
-
-Dialog sluit door dezelfde route opnieuw te pushen zonder de `newTask` / `editTask` query-params (bv. `router.push(\`/sprint/\${sprintId}\`)`).
-
----
-
-## Velden die de dialog gebruikt
-
-De dialog leest en schrijft uitsluitend deze velden van het `Task`-record. Het volledige datamodel valt buiten scope van deze spec.
-
-| Veld | Type | Mode |
-|---|---|---|
-| `title` | `string` (required) | beide |
-| `description` | `string \| null` | beide |
-| `implementation_plan` | `string \| null` | beide |
-| `priority` | `int` (1-4, P1 = hoogste) | beide |
-| `status` | `TaskStatus` enum | alleen edit (default `TO_DO` op create, niet getoond) |
-| `created_at` | `Date` | alleen edit, read-only metadata in header |
-
-`TaskStatus` enum-waarden: `TO_DO | IN_PROGRESS | REVIEW | DONE`.
-
----
-
-## Layout & responsive gedrag
-
-| Breakpoint | Breedte | Hoogte |
-|---|---|---|
-| Mobiel (<640px) | full-screen | full-screen |
-| Tablet (640-1024px) | `90vw` | `max-h-[85vh]` |
-| Desktop (≥1024px) | `max-w-[50vw]`, `min-w-[480px]` | `max-h-[85vh]` |
-
-- Padding: `p-6` rondom
-- Veld-spacing binnen blok: `space-y-6` (24px)
-- Sticky header (titel + close) en sticky footer (knoppen)
-- Body scrollt als content de `max-h` overschrijdt
-- Footer heeft top-border in `outline-variant` kleur
+> **Belangrijk:** als een regel in dit profiel botst met de generieke spec, wint de generieke spec. Documenteer hier de afwijking + reden, of pas de generieke spec aan.
 
 ---
 
 ## Velden
 
-In volgorde van boven naar beneden:
-
-| Veld | Control | Mode | Validatie |
+| Veld | Type | Mode | Validatie |
 |---|---|---|---|
-| `title` | `Input` (single-line) | beide | required, trim, 1-120 chars |
-| `description` | `Textarea` (auto-grow, 3-6 regels) | beide | optional, max 2.000 chars, markdown |
-| `implementation_plan` | `Textarea` (auto-grow, 5-12 regels) | beide | optional, max 10.000 chars, markdown |
-| `priority` | Segmented buttons (P1/P2/P3/P4) | beide | int 1-4, default 3 |
-| `status` | `Select` met gekleurde dot | alleen edit | enum, default TO_DO |
+| `title` | `string` (required) | beide | trim, 1-120 chars |
+| `description` | `string \| null` | beide | optional, max 2.000 chars, markdown |
+| `implementation_plan` | `string \| null` | beide | optional, max 10.000 chars, markdown |
+| `priority` | `int` (1-4, P1 = hoogste) | beide | int 1-4, default 3 |
+| `status` | `TaskStatus` enum | alleen edit (default `TO_DO` op create, niet getoond) | enum |
+| `created_at` | `Date` | alleen edit | read-only metadata in header |
 
-Verberg `status` in create-mode (default = TO_DO is genoeg).
+`TaskStatus` enum: `TO_DO | IN_PROGRESS | REVIEW | DONE`.
 
-### Auto-grow textareas
-Gebruik `react-textarea-autosize`. Bereikt het veld zijn max-regels, dan `overflow-y-auto` (interne scroll). De **dialog-body** scrollt onafhankelijk; je krijgt zelden geneste scrolls.
+### Veld-specifiek gedrag
 
-### Karakter-counter
-Alleen tonen vanaf 75% van de limiet. Klein, rechtsonder in het veld, `muted-foreground` kleur. Bv. `1547 / 2000`.
-
-### Markdown hint
-Onder elk textarea: `Markdown ondersteund (lijstjes, **vet**, \`code\`)` — klein, muted.
-
-### Priority segmented buttons
-```
-[ P1 Critical ]  [ P2 High ]  [ P3 Medium ]  [ P4 Low ]
-   error           tertiary      primary        outline
-```
-- Lager getal = hoger prio (industriestandaard, Linear/Jira-conform)
-- Default geselecteerd: P3 Medium
-- Geen 0-waarde toestaan
-
-### Status select (alleen edit)
-- TO_DO — grijze dot
-- IN_PROGRESS — blauwe dot
-- REVIEW — paarse dot
-- DONE — groene dot
-
-### `created_at` als header-metadata
-In edit-mode tonen in de dialog-header naast de titel:
-
-```
-Taak bewerken                          Aangemaakt: 23 apr 2026
-```
-
-Klein, `muted-foreground`, niet als form-veld.
+- **Auto-grow textareas** (`description`, `implementation_plan`) via `react-textarea-autosize`. Max 6 regels (description) / 12 regels (implementation_plan), daarna `overflow-y-auto`.
+- **Karakter-counter** vanaf 75% van de limiet, klein, rechtsonder, `text-muted-foreground`. Bv. `1547 / 2000`.
+- **Markdown-hint** onder elk textarea: `Markdown ondersteund (lijstjes, **vet**, \`code\`)`.
+- **Priority** als segmented buttons via `<PrioritySelect>` / `<PrioritySegmented>`. Default P3 (Medium).
+- **Status** met gekleurde dot:
+  - `TO_DO` — grijs
+  - `IN_PROGRESS` — `status-in-progress` (blauw)
+  - `REVIEW` — paars
+  - `DONE` — `status-done` (groen)
+- **`created_at` als header-metadata** in edit-mode, naast de titel: `Aangemaakt: 23 apr 2026`. Klein, `muted-foreground`, géén form-veld.
 
 ---
 
-## Validatie
+## URL- of state-pattern
 
-- **Gedeeld zod-schema** in `lib/schemas/task.ts`, geïmporteerd door zowel form als server action
-- react-hook-form mode: `onTouched` (eerste validatie bij blur, daarna onChange)
-- Errors onder het veld, in error-color, met label en outline van het veld in dezelfde kleur
-- Geen toasts voor field-level errors
-- Submit-button blijft enabled bij errors — klik scrollt naar eerste error-veld + focus
-
-```ts
-// lib/schemas/task.ts (richtlijn)
-export const taskSchema = z.object({
-  title: z.string().trim().min(1, "Verplicht").max(120),
-  description: z.string().max(2000).optional(),
-  implementation_plan: z.string().max(10000).optional(),
-  priority: z.number().int().min(1).max(4),
-  status: z.nativeEnum(TaskStatus).optional(), // alleen in edit
-});
-```
+- **Gekozen:** URL-based (`searchParams`)
+- **Reden:** TaskDialog wordt geopend vanuit twee context-pagina's (sprint-detail en product-backlog) en moet deep-linkable zijn voor share/refresh-scenario's. Suspense + skeleton voor edit-mode loading is gewenst.
+- **Routes:**
+  ```
+  /sprint/<sprintId>?newTask=1                      → create
+  /sprint/<sprintId>?editTask=<taskId>              → edit
+  /products/<productId>/backlog?newTask=1           → create
+  /products/<productId>/backlog?editTask=<taskId>   → edit
+  ```
+- **Sluiten:** `router.push(<base-route>)` zonder query-params.
+- **Server-side fetch in edit-mode:** server component fetcht de taak vóór render mét `productAccessFilter(userId)`. Bestaat de taak niet of valt 'm buiten scope → toast + redirect naar de context-route.
+- Optioneel: `nuqs` als de query-state-handling te omslachtig wordt — pas introduceren als losse refactor-task, niet inline.
 
 ---
 
-## Submission
+## Status-veld
 
-### Auth-scoping (verplicht)
-
-Elke server action — zowel `saveTask` als `deleteTask` — moet de operatie scope-en op de huidige user. Cross-tenant writes voorkomen via `productAccessFilter(userId)` (of het project-equivalent), zodat een user geen task kan schrijven of verwijderen die niet onder zijn product-scope valt.
-
-> Concreet: de Prisma-mutatie staat nóóit alleen op `where: { id: taskId }`. De scope wordt verplicht gecombineerd in elke `update`/`delete`/`create`-call.
-
-### Demo read-only enforcement (drie lagen — ST-1110)
-
-Elke write-flow moet door deze drie lagen:
-
-1. **Middleware-guard in `proxy.ts`** — blokkeert demo-sessies op write-routes vóór de server action überhaupt loopt. Returnt **403**.
-2. **`session.isDemo`-check in de server action zelf** — defense-in-depth voor het geval een write-flow buiten een proxy-route loopt (bv. directe action-invocation). Returnt **403**.
-3. **`<DemoTooltip>` op de save- en delete-knoppen** — UI-laag: knoppen zijn zichtbaar disabled met tooltip "Demo-modus: opslaan uitgeschakeld". Vermijdt onnodige round-trips.
-
-### Server Action
-
-```ts
-// app/actions/tasks.ts
-"use server"
-
-export async function saveTask(
-  input: TaskInput,
-  context: { sprintId?: string; productId?: string }, // voor revalidatePath en scope
-): Promise<SaveTaskResult> {
-  const session = await getSession();
-  if (session.isDemo) return { ok: false, code: 403, error: "demo_readonly" };
-
-  const scope = await productAccessFilter(session.userId); // verplicht
-  // ... validate met taskSchema → Prisma write binnen `scope`
-}
-
-type SaveTaskResult =
-  | { ok: true; task: Task }
-  | { ok: false; code: 422; error: "validation"; fieldErrors: Record<string, string> }
-  | { ok: false; code: 403; error: "demo_readonly" | "forbidden" }
-  | { ok: false; code: 500; error: "server_error" }
-```
-
-### Foutcodes (volgens `CLAUDE.md` "Foutcodes API")
-
-| Code | Wanneer | UI-respons |
-|---|---|---|
-| **422** | zod-validatiefout (server-side dubbelcheck) | `fieldErrors` mappen naar `form.setError()`, geen toast |
-| **403** | demo-sessie probeert te schrijven, of cross-tenant write geblokkeerd | toast "Niet toegestaan in demo-modus" / "Geen toegang", form blijft open |
-| **500** | onverwachte serverfout | toast met "Opnieuw proberen"-knop, form-state behouden |
-
-> Field-level errors zijn **alleen** geldig bij `code: 422`. Bij andere codes is `fieldErrors` ongedefinieerd.
-
-### Revalidation
-
-`revalidatePath` op de **context-route** waarin de dialog werd geopend, niet op een statische `/tasks`-path:
-
-```ts
-if (context.sprintId)  revalidatePath(`/sprint/${context.sprintId}`);
-if (context.productId) revalidatePath(`/products/${context.productId}/backlog`);
-```
-
-De aanroepende client geeft de relevante `sprintId` of `productId` mee als argument bij elke save/delete. Geen hard-coded paths in de action zelf.
-
-### Flow
-
-- Synchroon (geen optimistic update in v1)
-- Tijdens submit: cancel- en save-knop disabled, spinner in save-knop met "Opslaan...", velden blijven enabled
-- Server saniteert en valideert opnieuw met hetzelfde zod-schema
-- Field-level server errors (bv. unique constraint op title binnen scope) → `code: 422` met `fieldErrors`, terugmappen naar `form.setError()`
-
-### Error handling
-
-- **422** → field errors inline tonen, geen toast
-- **403** → toast met passende boodschap, form blijft open, ingevulde waarden behouden
-- **500 / netwerk** → toast met "Opnieuw proberen"-knop, form-state behouden, knoppen weer enabled
+Verberg `status` in **create-mode** (default = `TO_DO` is genoeg). Toon alleen in edit-mode als `<Select>` met gekleurde dot per optie.
 
 ---
 
-## Dialog-gedrag
+## Server actions
 
-### Sluiten met dirty state
-- Form niet aangeraakt → Esc / backdrop-klik / Cancel sluiten direct
-- Form `isDirty` → Esc / backdrop-klik / Cancel triggeren `AlertDialog`: *"Wijzigingen niet opgeslagen — weggooien?"*
+| Actie | Locatie | Context-arg | Revalidatie |
+|---|---|---|---|
+| `saveTask` | `app/actions/tasks.ts` | `{ sprintId?: string; productId?: string }` | `revalidatePath('/sprint/<sprintId>')` óf `revalidatePath('/products/<productId>/backlog')` afhankelijk van context |
+| `deleteTask` | `app/actions/tasks.ts` | idem | idem |
 
-### Keyboard shortcuts
-- **Esc** — sluit (met dirty-check)
-- **Cmd/Ctrl+Enter** — submit vanuit elk veld
-- **Enter in title-input** — submit niet (alleen Cmd/Ctrl+Enter)
-- **Enter in textarea** — newline (default browser behavior, niet overriden)
-- **Tab** — title → description → implementation_plan → priority → (status) → cancel → save
-
-### Focus management
-- Bij openen: focus op `title`-input
-- Edit-mode: cursor aan einde van bestaande titel, **geen auto-select** (anders typt user per ongeluk de titel weg)
-- Bij sluiten: focus terug naar het element dat de dialog opende (`@base-ui/react` doet dit by default — niet breken)
-- Bij submit-error: focus naar eerste error-veld
-
-### Motion
-MD3-conform:
-- Open: 250ms, easing `cubic-bezier(0.2, 0, 0, 1)`, scale 0.95→1 + opacity 0→1
-- Close: 200ms, easing `cubic-bezier(0.4, 0, 1, 1)`
-
-### Backdrop
-Scrim `rgba(0,0,0,0.4)` (iets sterker dan MD3-default 0.32 voor betere contrast op licht/donker).
+Beide acties volgen de drielaagse demo-policy + auth-scoping uit `docs/patterns/dialog.md` § 6–7.
 
 ---
 
-## Footer
+## Speciale gedragingen
 
-### Edit-mode
-```
-[ Verwijderen ]                       [ Annuleren ]   [ Opslaan ]
-  tonal (error-container)               text            filled (primary)
-```
+### Triggers (bestaande UI vervangen)
 
-### Create-mode
-```
-                                      [ Annuleren ]   [ Aanmaken ]
-                                        text            filled (primary)
-```
+Deze TaskDialog is de **enige** create/edit-flow voor taken in beide contexten (sprint én backlog). Bestaande inline-edit-paden in `components/sprint/task-list.tsx` en het backlog-equivalent worden vervangen, niet ernaast geplaatst.
 
-### Delete-flow
-- Klik op "Verwijderen" → `AlertDialog`: *"Weet je zeker? Dit kan niet ongedaan worden."*
-- Bevestigen → `deleteTask` server action (zelfde auth-scoping en demo-checks als `saveTask`) → `revalidatePath` op de context-route (`/sprint/<sprintId>` of `/products/<productId>/backlog`) → dialog sluit → toast "Taak verwijderd"
-- Geen undo in v1
+- **Create-trigger:** filled button `+ Nieuwe taak` in tasklist-header → zet `?newTask=1` op huidige route
+- **Edit-trigger:** klik op de hele rij in de tasklist (geen apart edit-icoon) → zet `?editTask=<id>` op huidige route
+- **Loading edit-mode:** Suspense met minimale skeleton (3 grijze balken), `200ms`-delay zodat snelle fetches geen flicker tonen
 
----
+### Markdown-rendering elders
 
-## Triggers (hoe komt de user erbij?)
-
-De dialog wordt vanuit twee context-pagina's geopend: een sprint-detail (`/sprint/<sprintId>`) of een product-backlog (`/products/<productId>/backlog`).
-
-> **Vervangt bestaande create/edit-flows.** Deze TaskDialog is de **enige** flow voor het aanmaken en bewerken van taken in beide contexten. Bestaande inline-edit-paden in `components/sprint/task-list.tsx` (en eventueel in de backlog) worden door deze dialog vervangen — niet er naast geplaatst. De huidige task-row-rendering wordt aangepast om bij klik de dialog te openen via `?editTask=<id>`; geen aparte edit-icon, geen inline form. Een eventuele "+ Nieuwe taak"-knop in de bestaande tasklist-header wordt eveneens omgeleid naar `?newTask=1` op dezelfde route.
-
-- **Create:** filled button `+ Nieuwe taak` rechtsboven in de tasklist-header van de huidige context (FAB op mobiel optioneel later). Klik zet de juiste query-param (`?newTask=1`) op de huidige route.
-- **Edit:** klik op de hele rij in de tasklist (geen apart edit-icoon). Klik zet `?editTask=<id>` op de huidige route.
-- **Loading edit-mode:** Suspense met minimale skeleton (3 grijze balken voor inputs), `200ms` delay zodat snelle fetches geen flicker tonen
-
-### Server-fetch
-Bij `?editTask=<id>`: server component fetcht de taak vóór render — **inclusief auth-scoping** via `productAccessFilter(userId)` zodat een user nooit een task uit een ander product kan openen via een geraden ID. Bestaat de taak niet of valt 'm buiten scope → toast + redirect naar de context-route zonder query-param (bv. `/sprint/<sprintId>`).
-
----
-
-## Theming (Material Design 3 tokens)
-
-> **Bron-of-truth in v1:** de bestaande **statische** tokens in `app/styles/theme.css` zijn canoniek. De TaskDialog **consumeert** deze tokens en voegt er geen nieuwe aan toe. Dynamic color (`material-color-utilities`) valt **buiten v1** — niet introduceren in deze feature.
-
-### Color
-- TaskDialog gebruikt de bestaande MD3-tokens uit `app/styles/theme.css`: `--primary`, `--on-primary`, `--surface-container`, `--surface-container-high`, `--surface-container-low`, `--error-container`, `--on-error-container`, `--outline-variant`, plus de project-specifieke `--status-*` en `--priority-*` tokens
-- Eventueel ontbrekende tokens (bv. een specifieke `surface-container-high` als die er nog niet is) worden in **dezelfde commit** als de feature aan `theme.css` toegevoegd, niet ad-hoc per component gehard-codeerd
-- **Verboden:** willekeurige Tailwind-kleuren (`bg-blue-500`, etc.). Altijd semantische tokens — zie `docs/scrum4me-styling.md`
-
-### Dark mode
-- `next-themes` is al in de stack; TaskDialog erft automatisch de actieve kleurmodus via de bestaande tokens
-- Geen extra setup nodig in deze feature
-
-### Surface elevation
-Hybrid (tonal surface + zachte shadow):
-- Dialog: `surface-container-high` background + `shadow-2xl` met getemperde opacity
-- Form inputs: `surface-container-low` background, geen shadow
-- Geen pure tonal-only (voelt te plat op desktop)
-
-### Buttons
-- **Filled** (Save/Aanmaken): `primary` background, `on-primary` tekst
-- **Text** (Cancel): geen background, `primary` tekst
-- **Tonal error** (Delete): `error-container` background, `on-error-container` tekst
-
-### Density
-Comfortable (geen compact):
-- Single-line input-hoogte: 56px (MD3 outlined text field default)
-- Veld-spacing: 24px (`space-y-6`)
-- Dialog-padding: 24px alle kanten (`p-6`)
-
-### Typography
-- **Font:** Inter via `next/font/google` (geen Roboto-dwang)
-- **Schaal (beperkt):**
-  - `headline-small` (24px) — dialog-titel
-  - `body-large` (16px) — form-input tekst
-  - `body-medium` (14px) — helptext, counter
-- Geen Material-specifieke letter-spacing tweaks; Inter-defaults voldoen
-
-### Iconen
-Lucide (shadcn default). Geen Material Symbols importeren — ~150kb winst en visueel neutraal genoeg om in MD3-themed app te passen.
-
----
-
-## Markdown rendering (buiten de dialog)
-
-Voor weergave van `description` en `implementation_plan` elders in de app (taakdetail, hover-card, etc.):
-
-```tsx
-import ReactMarkdown from "react-markdown";
-import remarkGfm from "remark-gfm";
-
-<ReactMarkdown
-  remarkPlugins={[remarkGfm]}
-  disallowedElements={["script", "iframe"]}
-  className="prose prose-sm dark:prose-invert"
->
-  {content}
-</ReactMarkdown>
-```
-
-- Tailwind Typography (`prose prose-sm`) voor styling
-- `remark-gfm` voor tabellen, taken, strikethrough
-- `react-markdown` saniteert by default; `disallowedElements` als extra defense-in-depth
-
----
-
-## Hergebruik & generalisatie
-
-De TaskDialog is de eerste van naar verwachting meerdere entity-dialogs (PBI, Story, Todo volgen logisch). Bouw daarom **vanaf dag 1** een dunne scheiding tussen generic shell+primitives en entity-specifieke form-body. Dit is geen speculatieve abstractie: de breuklijn tussen "dialog-mechanica" en "welke velden horen bij deze entiteit" is natuurlijk en levert per nieuwe entiteit ~70% codebesparing op.
-
-### Wat generic wordt (`components/entity-dialog/`)
-
-| Component | Waarom generic |
-|---|---|
-| `entity-dialog.tsx` | Shell: sticky header/footer, responsive layout, motion, backdrop, dirty-close-guard, keyboard-shortcuts, focus-management. Slot-props voor body en footer-actions. |
-| `priority-segmented.tsx` | P1-P4 segmented buttons; `priority: int 1-4` is identiek over Task / PBI / Story / Todo. |
-| `auto-grow-textarea.tsx` | Wrapper rond `react-textarea-autosize` met char-counter (vanaf 75%) en markdown-hint. Generic — neemt min/max regels en max-chars als props. |
-| `dirty-close-guard.tsx` | AlertDialog "Wijzigingen niet opgeslagen — weggooien?" — entity-agnostisch. |
-
-Deze primitives importeren **alleen** uit `components/ui/*` en hebben geen kennis van Task / Story / PBI.
-
-### Wat entity-specifiek blijft (`components/tasks/`)
-
-| Component | Waarom niet generic |
-|---|---|
-| `task-dialog.tsx` | Dunne wrapper: kiest body, koppelt `saveTask`/`deleteTask`, levert label-strings ("Taak bewerken" / "Aangemaakt: …"). Geen mechanica meer in dit bestand. |
-| `task-form.tsx` | Velden zijn task-specifiek (`title`, `description`, `implementation_plan`, `priority`, `status`). Andere entiteiten (Story heeft `acceptance_criteria`, PBI heeft alleen `description`) krijgen elk hun eigen `*-form.tsx`. |
-| `task-status-select.tsx` | `TaskStatus` enum met 4 specifieke waarden + dot-kleurmapping. `StoryStatus` (`OPEN | IN_SPRINT | DONE`) en `PbiStatus` (`OPEN | IN_SPRINT | DONE` + `BLOCKED`) hebben andere enums en horen bij eigen select-componenten. |
-
-### Wat **niet** abstraheren in v1
-
-- **URL-state pattern** — `?newTask=1` / `?editTask=<id>` per route. Een toekomstige PBI-dialog krijgt `?newPbi=1` / `?editPbi=<id>` op zijn eigen routes. Copy-paste tussen 2-3 pages is goedkoper dan een generic helper die je later toch moet generaliseren.
-- **Save/delete-flows** — auth-scoping, demo-checks en revalidatePath verschillen subtiel per entiteit (verschillende productAccessFilter-paden, verschillende context-routes). Per entiteit een eigen actions-file in `app/actions/<entity>.ts`.
-
-### Per-entiteit kostenplaatje
-
-Wanneer er straks een PbiDialog of StoryDialog gebouwd wordt, kost dat alleen:
-
-1. `components/<entity>/<entity>-form.tsx` — de velden + zod-schema
-2. `components/<entity>/<entity>-status-select.tsx` — als de entiteit een status-veld heeft
-3. `components/<entity>/<entity>-dialog.tsx` — dunne wrapper rond `EntityDialog` met de juiste form en save/delete-handler
-4. `app/actions/<entity>.ts` — server actions
-5. URL-state uitbreiding op de relevante page(s)
-
-Geen herhaling van layout, motion, dirty-check, keyboard-shortcuts, of segmented/textarea-primitives.
-
----
-
-## Bewust NIET in v1
-
-Om scope te bewaken:
-
-- ❌ Bulk-edit (meerdere taken tegelijk)
-- ❌ Drag-and-drop herorderen
-- ❌ Sub-tasks / parent-child relaties
-- ❌ Tags / labels / categorieën
-- ❌ Due dates / reminders
-- ❌ Attachments / file uploads
-- ❌ Comments / activity log
-- ❌ Sharing / collaboration
-- ❌ Undo na delete (toast met undo-actie)
-- ❌ Cmd+K keyboard-driven creation zonder dialog
-- ❌ Templates voor terugkerende taken
-- ❌ Time tracking (uren-registratie) — wel relevant voor inspannings-monitor, maar apart feature
-- ❌ Telemetrie / analytics
-- ❌ Optimistic locking — niet geïmplementeerd in v1 (last-write-wins binnen scope)
-- ❌ Tabs voor secties — alleen spacing-gebaseerde groepering
-- ❌ Section-headers — implicit via spacing, geen labels
-
-> Heroverweeg deze keuzes pas als de app groeit. Niet om je te beperken, maar om elke "ja maar moeten we niet ook…"-impuls een bewuste afweging te maken.
-
----
-
-## File structuur (richtlijn)
-
-```
-app/
-├── sprint/
-│   └── [id]/
-│       └── page.tsx                # leest searchParams, rendert TaskDialog
-├── products/
-│   └── [id]/
-│       └── backlog/
-│           └── page.tsx            # leest searchParams, rendert TaskDialog
-├── actions/
-│   └── tasks.ts                    # saveTask, deleteTask server actions (auth-scoped)
-components/
-├── ui/
-│   ├── dialog.tsx                  # bestaande @base-ui/react-wrapper
-│   └── demo-tooltip.tsx            # wrapper voor save/delete-knoppen in demo-mode
-├── entity-dialog/                  # GENERIC — geen kennis van Task/Story/PBI
-│   ├── entity-dialog.tsx           # shell: header/footer/motion/dirty-check/keyboard
-│   ├── priority-segmented.tsx     # P1-P4 segmented buttons
-│   ├── auto-grow-textarea.tsx     # textarea met counter + markdown-hint
-│   └── dirty-close-guard.tsx      # AlertDialog bij dirty close
-├── tasks/                          # ENTITY-SPECIFIEK
-│   ├── task-dialog.tsx             # dunne wrapper rond EntityDialog
-│   ├── task-form.tsx               # task-velden + react-hook-form binding
-│   └── task-status-select.tsx      # TaskStatus enum + dot-kleuren
-lib/
-├── schemas/
-│   └── task.ts                     # gedeeld zod-schema (form + server action)
-├── auth/
-│   └── product-access-filter.ts    # scope-helper, gedeeld door page-fetches en actions
-proxy.ts                            # demo-readonly middleware-guard (laag 1 van 3)
-```
+`description` en `implementation_plan` worden buiten de dialog (taakdetail, hover-card) gerenderd via de gedeelde `<Markdown>`-wrapper (`react-markdown` + `remark-gfm`). Niet in de dialog zelf.
 
 ---
 
 ## Implementatie-volgorde (suggestie)
 
-1. Dependencies toevoegen aan `package.json` (zie "Dependency-impact"); commit als `chore(ST-XXX): add deps for task dialog`
-2. zod-schema in `lib/schemas/task.ts`
-3. `productAccessFilter` helper checken/uitbreiden in `lib/auth/`
-4. Server actions (`saveTask`, `deleteTask`) met **auth-scoping én demo-check** (laag 2) — testen via thunk
-5. `proxy.ts` middleware-guard voor demo-routes (laag 1) — alleen als nog niet aanwezig voor deze routes
-6. Eventueel ontbrekende MD3-tokens aanvullen in `app/styles/theme.css` (geen dynamic color in v1)
-7. `<DemoTooltip>`-wrapper component (laag 3)
-8. TaskDialog — create-mode eerst (minder edge cases), bovenop bestaande `components/ui/dialog.tsx`-wrapper
-9. Edit-mode toevoegen (status field, delete-knop, `created_at`-metadata)
-10. URL-state via native `searchParams` binnen sprint en backlog routes (geen `nuqs` in v1)
-11. **Bestaande task-row / tasklist-trigger refactoren** — `components/sprint/task-list.tsx` (en backlog-equivalent) klikbaar maken zodat ze de dialog openen via query-param; oude inline-edit-paden verwijderen
-12. Suspense + skeleton voor edit-mode loading + scope-check op fetch
-13. Dirty-check + AlertDialog
+Hergebruik dit als checklist bij het bouwen of refactoren van TaskDialog:
+
+1. Dependencies in `package.json` (zie `docs/patterns/dialog.md` § 2)
+2. zod-schema in `lib/schemas/task.ts` — gedeeld door form en action
+3. `productAccessFilter`-helper checken in `lib/auth/`
+4. `saveTask` / `deleteTask` in `app/actions/tasks.ts` met auth-scoping + demo-check (laag 2)
+5. `proxy.ts`-guard voor demo-write-routes (laag 1) — alleen als nog niet aanwezig
+6. Eventueel ontbrekende MD3-tokens in `app/styles/theme.css` aanvullen
+7. `<DemoTooltip>` rond submit/delete-knoppen (laag 3)
+8. TaskDialog — create-mode eerst (minder edge cases)
+9. Edit-mode toevoegen (status, delete, `created_at`-metadata)
+10. URL-state via native `searchParams` op beide context-pagina's
+11. Bestaande task-row trigger refactoren (klikbaar maken naar dialog)
+12. Suspense + skeleton voor edit-mode + scope-check op fetch
+13. Dirty-close-guard
 14. Keyboard shortcuts (Cmd+Enter)
-15. Markdown rendering elders (out-of-scope voor dialog zelf, maar related)
+
+---
+
+## Bewust NIET in v1
+
+Specifiek voor TaskDialog (boven op de algemene out-of-scope-lijst in `docs/patterns/dialog.md` § 13):
+
+- ❌ Sub-tasks / parent-child relaties tussen taken
+- ❌ Tags / labels / categorieën op taken
+- ❌ Due dates / reminders per taak
+- ❌ Time tracking (uren-registratie) — wel relevant voor inspannings-monitor, eigen feature
+- ❌ Sharing / collaboration per taak
+- ❌ Templates voor terugkerende taken
+
+---
+
+## Referenties
+
+- `docs/patterns/dialog.md` — generieke spec (bron-of-truth voor alles wat hier niet beschreven is)
+- `docs/scrum4me-architecture.md` — datamodel `Task`
+- `docs/scrum4me-styling.md` — MD3-tokens, status- en priority-kleuren
+- `lib/task-status.ts` — enum-mapper DB ↔ API

From ce94fb48c359f92185b6df54ceb9d83a40c1eaf5 Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 15:58:15 +0200
Subject: [PATCH 02/17] Foundation: route, recharts, sprint-dates migration,
 chart-colors helper (#46)

* feat(ST-1201): add Sprint start_date/end_date + claude_jobs index migration

- Sprint model: optionele start_date en end_date (DATE) voor burndown x-as
- CREATE INDEX claude_jobs(status, finished_at) voor agent-throughput-queries
- Bestaande sprints houden NULL; burndown skipt die

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

* feat(ST-1202): add lib/chart-colors.ts + vitest coverage

MD3-token-to-CSS-var mappings for STATUS, PRIORITY, VERIFY, JOB_STATUS
and SERIES_COLORS; all 5 tests pass.

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

* feat(ST-1203): add Insights link to NavBar

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

* feat(ST-1204): move Insights NavBar link between Solo and Todo's

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

* feat(ST-1205): add sprint start_date/end_date UI + server actions

- createSprintAction + updateSprintDatesAction: Zod date validation
  with end_date >= start_date cross-check
- start-sprint-button: date inputs in create dialog
- sprint-header: date display button + edit dialog with updateSprintDatesAction
- sprint page: select start_date/end_date for SprintHeader prop
- Demo blokkade via bestaande isDemo checks
- 6 tests groen (validation + demo guard)

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 __tests__/actions/sprint-dates.test.ts        | 97 +++++++++++++++++++
 __tests__/lib/chart-colors.test.ts            | 52 ++++++++++
 actions/sprints.ts                            | 45 ++++++++-
 app/(app)/products/[id]/sprint/page.tsx       |  7 ++
 components/shared/nav-bar.tsx                 |  1 +
 components/sprint/sprint-header.tsx           | 74 ++++++++++++--
 components/sprint/start-sprint-button.tsx     | 17 ++++
 lib/chart-colors.ts                           | 39 ++++++++
 .../migration.sql                             |  6 ++
 prisma/schema.prisma                          |  2 +
 10 files changed, 333 insertions(+), 7 deletions(-)
 create mode 100644 __tests__/actions/sprint-dates.test.ts
 create mode 100644 __tests__/lib/chart-colors.test.ts
 create mode 100644 lib/chart-colors.ts
 create mode 100644 prisma/migrations/20260502132322_add_sprint_dates_and_jobs_index/migration.sql

diff --git a/__tests__/actions/sprint-dates.test.ts b/__tests__/actions/sprint-dates.test.ts
new file mode 100644
index 0000000..6cb59c2
--- /dev/null
+++ b/__tests__/actions/sprint-dates.test.ts
@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('next/cache', () => ({ revalidatePath: vi.fn() }))
+vi.mock('next/headers', () => ({ cookies: vi.fn().mockResolvedValue({}) }))
+vi.mock('iron-session', () => ({
+  getIronSession: vi.fn().mockResolvedValue({ userId: 'user-1', isDemo: false }),
+}))
+vi.mock('@/lib/session', () => ({
+  sessionOptions: { cookieName: 'test', password: 'test' },
+}))
+vi.mock('@/lib/product-access', () => ({
+  productAccessFilter: vi.fn().mockReturnValue({}),
+  getAccessibleProduct: vi.fn().mockResolvedValue({ id: 'product-1', user_id: 'user-1' }),
+}))
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    sprint: {
+      findFirst: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+    },
+  },
+}))
+
+import { prisma } from '@/lib/prisma'
+import { createSprintAction, updateSprintDatesAction } from '@/actions/sprints'
+
+const mockSprint = prisma as unknown as { sprint: { findFirst: ReturnType<typeof vi.fn>; create: ReturnType<typeof vi.fn>; update: ReturnType<typeof vi.fn> } }
+
+function makeFormData(data: Record<string, string | null>) {
+  const fd = new FormData()
+  for (const [k, v] of Object.entries(data)) {
+    if (v !== null) fd.append(k, v)
+  }
+  return fd
+}
+
+describe('createSprintAction — date validation', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSprint.sprint.findFirst.mockResolvedValue(null)
+    mockSprint.sprint.create.mockResolvedValue({ id: 'sprint-1' })
+  })
+
+  it('accepts valid start_date + end_date', async () => {
+    const fd = makeFormData({ productId: 'product-1', sprint_goal: 'Doel', start_date: '2026-05-01', end_date: '2026-05-14' })
+    const result = await createSprintAction(undefined, fd)
+    expect(result.success).toBe(true)
+    expect(mockSprint.sprint.create).toHaveBeenCalledWith(
+      expect.objectContaining({ data: expect.objectContaining({ start_date: new Date('2026-05-01'), end_date: new Date('2026-05-14') }) })
+    )
+  })
+
+  it('rejects end_date before start_date', async () => {
+    const fd = makeFormData({ productId: 'product-1', sprint_goal: 'Doel', start_date: '2026-05-14', end_date: '2026-05-01' })
+    const result = await createSprintAction(undefined, fd)
+    expect(result.error).toBeTruthy()
+    const errors = result.error as Record<string, string[]>
+    expect(errors.end_date?.[0]).toContain('Einddatum')
+  })
+
+  it('accepts no dates (both optional)', async () => {
+    const fd = makeFormData({ productId: 'product-1', sprint_goal: 'Doel', start_date: '', end_date: '' })
+    const result = await createSprintAction(undefined, fd)
+    expect(result.success).toBe(true)
+  })
+})
+
+describe('updateSprintDatesAction — date validation', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSprint.sprint.findFirst.mockResolvedValue({ id: 'sprint-1', product_id: 'product-1' })
+    mockSprint.sprint.update.mockResolvedValue({})
+  })
+
+  it('saves valid dates', async () => {
+    const fd = makeFormData({ id: 'sprint-1', start_date: '2026-05-01', end_date: '2026-05-14' })
+    const result = await updateSprintDatesAction(undefined, fd)
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects end_date before start_date', async () => {
+    const fd = makeFormData({ id: 'sprint-1', start_date: '2026-05-10', end_date: '2026-05-05' })
+    const result = await updateSprintDatesAction(undefined, fd)
+    expect(result.error).toBeTruthy()
+    const errors = result.error as Record<string, string[]>
+    expect(errors.end_date?.[0]).toContain('Einddatum')
+  })
+
+  it('blocks demo users', async () => {
+    const { getIronSession } = await import('iron-session')
+    vi.mocked(getIronSession).mockResolvedValueOnce({ userId: 'user-1', isDemo: true } as never)
+    const fd = makeFormData({ id: 'sprint-1', start_date: '', end_date: '' })
+    const result = await updateSprintDatesAction(undefined, fd)
+    expect(result.error).toBe('Niet beschikbaar in demo-modus')
+  })
+})
diff --git a/__tests__/lib/chart-colors.test.ts b/__tests__/lib/chart-colors.test.ts
new file mode 100644
index 0000000..b8d0be2
--- /dev/null
+++ b/__tests__/lib/chart-colors.test.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import {
+  STATUS_COLORS,
+  PRIORITY_COLORS,
+  VERIFY_COLORS,
+  JOB_STATUS_COLORS,
+  SERIES_COLORS,
+} from '@/lib/chart-colors'
+
+describe('chart-colors', () => {
+  it('STATUS_COLORS has all TaskStatus keys and non-empty values', () => {
+    const keys: (keyof typeof STATUS_COLORS)[] = ['TO_DO', 'IN_PROGRESS', 'REVIEW', 'DONE']
+    for (const key of keys) {
+      expect(STATUS_COLORS[key]).toBeTruthy()
+      expect(typeof STATUS_COLORS[key]).toBe('string')
+    }
+  })
+
+  it('PRIORITY_COLORS has keys 1-4 with non-empty values', () => {
+    const keys = [1, 2, 3, 4] as const
+    for (const key of keys) {
+      expect(PRIORITY_COLORS[key]).toBeTruthy()
+      expect(typeof PRIORITY_COLORS[key]).toBe('string')
+    }
+  })
+
+  it('VERIFY_COLORS has all VerifyResult keys and non-empty values', () => {
+    const keys: (keyof typeof VERIFY_COLORS)[] = ['ALIGNED', 'PARTIAL', 'EMPTY', 'DIVERGENT']
+    for (const key of keys) {
+      expect(VERIFY_COLORS[key]).toBeTruthy()
+      expect(typeof VERIFY_COLORS[key]).toBe('string')
+    }
+  })
+
+  it('JOB_STATUS_COLORS has all ClaudeJobStatus keys and non-empty values', () => {
+    const keys: (keyof typeof JOB_STATUS_COLORS)[] = [
+      'queued', 'claimed', 'running', 'done', 'failed', 'cancelled',
+    ]
+    for (const key of keys) {
+      expect(JOB_STATUS_COLORS[key]).toBeTruthy()
+      expect(typeof JOB_STATUS_COLORS[key]).toBe('string')
+    }
+  })
+
+  it('SERIES_COLORS has 5 non-empty entries', () => {
+    expect(SERIES_COLORS).toHaveLength(5)
+    for (const color of SERIES_COLORS) {
+      expect(color).toBeTruthy()
+      expect(typeof color).toBe('string')
+    }
+  })
+})
diff --git a/actions/sprints.ts b/actions/sprints.ts
index 7eb7229..8eb2292 100644
--- a/actions/sprints.ts
+++ b/actions/sprints.ts
@@ -16,6 +16,14 @@ function hasDuplicateIds(ids: string[]) {
   return new Set(ids).size !== ids.length
 }
 
+const dateField = z.string().optional().nullable().transform(v => (v && v.trim() !== '' ? new Date(v) : null))
+
+function validateDateOrder(data: { start_date: Date | null; end_date: Date | null }, ctx: z.RefinementCtx) {
+  if (data.start_date && data.end_date && data.end_date < data.start_date) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['end_date'], message: 'Einddatum moet na startdatum liggen' })
+  }
+}
+
 export async function createSprintAction(_prevState: unknown, formData: FormData) {
   const session = await getSession()
   if (!session.userId) return { error: 'Niet ingelogd' }
@@ -24,9 +32,13 @@ export async function createSprintAction(_prevState: unknown, formData: FormData
   const parsed = z.object({
     productId: z.string(),
     sprint_goal: z.string().min(1, 'Sprint Goal is verplicht').max(500),
-  }).safeParse({
+    start_date: dateField,
+    end_date: dateField,
+  }).superRefine(validateDateOrder).safeParse({
     productId: formData.get('productId'),
     sprint_goal: formData.get('sprint_goal'),
+    start_date: formData.get('start_date'),
+    end_date: formData.get('end_date'),
   })
   if (!parsed.success) return { error: parsed.error.flatten().fieldErrors }
 
@@ -43,6 +55,8 @@ export async function createSprintAction(_prevState: unknown, formData: FormData
       product_id: parsed.data.productId,
       sprint_goal: parsed.data.sprint_goal,
       status: 'ACTIVE',
+      start_date: parsed.data.start_date,
+      end_date: parsed.data.end_date,
     },
   })
 
@@ -50,6 +64,35 @@ export async function createSprintAction(_prevState: unknown, formData: FormData
   return { success: true, sprintId: sprint.id }
 }
 
+export async function updateSprintDatesAction(_prevState: unknown, formData: FormData) {
+  const session = await getSession()
+  if (!session.userId) return { error: 'Niet ingelogd' }
+  if (session.isDemo) return { error: 'Niet beschikbaar in demo-modus' }
+
+  const parsed = z.object({
+    id: z.string(),
+    start_date: dateField,
+    end_date: dateField,
+  }).superRefine(validateDateOrder).safeParse({
+    id: formData.get('id'),
+    start_date: formData.get('start_date'),
+    end_date: formData.get('end_date'),
+  })
+  if (!parsed.success) return { error: parsed.error.flatten().fieldErrors }
+
+  const sprint = await prisma.sprint.findFirst({
+    where: { id: parsed.data.id, product: productAccessFilter(session.userId) },
+  })
+  if (!sprint) return { error: 'Sprint niet gevonden' }
+
+  await prisma.sprint.update({
+    where: { id: parsed.data.id },
+    data: { start_date: parsed.data.start_date, end_date: parsed.data.end_date },
+  })
+  revalidatePath(`/products/${sprint.product_id}/sprint`)
+  return { success: true }
+}
+
 export async function updateSprintGoalAction(_prevState: unknown, formData: FormData) {
   const session = await getSession()
   if (!session.userId) return { error: 'Niet ingelogd' }
diff --git a/app/(app)/products/[id]/sprint/page.tsx b/app/(app)/products/[id]/sprint/page.tsx
index 3b16d5f..e8a6b9e 100644
--- a/app/(app)/products/[id]/sprint/page.tsx
+++ b/app/(app)/products/[id]/sprint/page.tsx
@@ -33,6 +33,13 @@ export default async function SprintBoardPage({ params, searchParams }: Props) {
 
   const sprint = await prisma.sprint.findFirst({
     where: { product_id: id, status: 'ACTIVE' },
+    select: {
+      id: true,
+      sprint_goal: true,
+      status: true,
+      start_date: true,
+      end_date: true,
+    },
   })
   if (!sprint) redirect(`/products/${id}`)
 
diff --git a/components/shared/nav-bar.tsx b/components/shared/nav-bar.tsx
index f039e67..2a7e97e 100644
--- a/components/shared/nav-bar.tsx
+++ b/components/shared/nav-bar.tsx
@@ -137,6 +137,7 @@ export function NavBar({
                 pathname.includes('/solo')
               )
             : disabledSpan('Solo')}
+          {navLink('/insights', 'Insights', pathname.startsWith('/insights'))}
           {navLink('/todos', "Todo's", pathname.startsWith('/todos'))}
         </nav>
       </div>
diff --git a/components/sprint/sprint-header.tsx b/components/sprint/sprint-header.tsx
index e923af8..b47a567 100644
--- a/components/sprint/sprint-header.tsx
+++ b/components/sprint/sprint-header.tsx
@@ -12,13 +12,15 @@ import {
 } from '@/components/ui/dialog'
 import { toast } from 'sonner'
 import { DemoTooltip } from '@/components/shared/demo-tooltip'
-import { updateSprintGoalAction, completeSprintAction } from '@/actions/sprints'
+import { updateSprintGoalAction, updateSprintDatesAction, completeSprintAction } from '@/actions/sprints'
 import type { SprintStory } from './sprint-backlog'
 
 interface Sprint {
   id: string
   sprint_goal: string
   status: string
+  start_date: Date | null
+  end_date: Date | null
 }
 
 interface SprintHeaderProps {
@@ -34,8 +36,14 @@ function SaveGoalButton() {
   return <Button type="submit" size="sm" disabled={pending}>{pending ? 'Opslaan…' : 'Opslaan'}</Button>
 }
 
+function toDateInputValue(d: Date | null) {
+  if (!d) return ''
+  return d.toISOString().slice(0, 10)
+}
+
 export function SprintHeader({ productId: _productId, productName, sprint, isDemo, sprintStories }: SprintHeaderProps) {
   const [editingGoal, setEditingGoal] = useState(false)
+  const [editingDates, setEditingDates] = useState(false)
   const [completeOpen, setCompleteOpen] = useState(false)
   const [decisions, setDecisions] = useState<Record<string, 'DONE' | 'OPEN'>>({})
   const [isCompleting, startCompleting] = useTransition()
@@ -50,6 +58,16 @@ export function SprintHeader({ productId: _productId, productName, sprint, isDem
     undefined
   )
 
+  const [datesState, datesFormAction] = useActionState(
+    async (_prev: unknown, fd: FormData) => {
+      const result = await updateSprintDatesAction(_prev, fd)
+      if (result?.success) { setEditingDates(false); toast.success('Sprint datums opgeslagen') }
+      else if (result?.error) toast.error(typeof result.error === 'string' ? result.error : 'Opslaan mislukt')
+      return result
+    },
+    undefined
+  )
+
   function setDecision(storyId: string, value: 'DONE' | 'OPEN') {
     setDecisions(prev => ({ ...prev, [storyId]: value }))
   }
@@ -96,13 +114,57 @@ export function SprintHeader({ productId: _productId, productName, sprint, isDem
           )}
         </div>
 
-        <DemoTooltip show={isDemo}>
-          <Button size="sm" variant="outline" disabled={isDemo} className="shrink-0 border-warning/40 text-warning hover:bg-warning/10" onClick={() => setCompleteOpen(true)}>
-            Sprint afronden
-          </Button>
-        </DemoTooltip>
+        <div className="flex items-center gap-2 shrink-0">
+          <DemoTooltip show={isDemo}>
+            <Button size="sm" variant="ghost" disabled={isDemo} className="text-muted-foreground" onClick={() => !isDemo && setEditingDates(true)}>
+              {sprint.start_date && sprint.end_date
+                ? `${toDateInputValue(sprint.start_date)} → ${toDateInputValue(sprint.end_date)}`
+                : 'Datums instellen'}
+            </Button>
+          </DemoTooltip>
+          <DemoTooltip show={isDemo}>
+            <Button size="sm" variant="outline" disabled={isDemo} className="border-warning/40 text-warning hover:bg-warning/10" onClick={() => setCompleteOpen(true)}>
+              Sprint afronden
+            </Button>
+          </DemoTooltip>
+        </div>
       </div>
 
+      {/* Dates edit dialog */}
+      <Dialog open={editingDates} onOpenChange={setEditingDates}>
+        <DialogContent className="sm:max-w-sm">
+          <DialogHeader>
+            <DialogTitle>Sprint datums instellen</DialogTitle>
+          </DialogHeader>
+          <form action={datesFormAction} className="space-y-4 p-1">
+            <input type="hidden" name="id" value={sprint.id} />
+            <div className="grid grid-cols-2 gap-3">
+              <div className="space-y-1.5">
+                <label className="text-sm font-medium text-foreground">Startdatum</label>
+                <input type="date" name="start_date" defaultValue={toDateInputValue(sprint.start_date)} className="w-full rounded-md border border-border bg-surface-container px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-primary" />
+                {typeof datesState?.error === 'object' && (datesState.error as Record<string, string[]>).start_date && (
+                  <p className="text-xs text-error">{(datesState.error as Record<string, string[]>).start_date[0]}</p>
+                )}
+              </div>
+              <div className="space-y-1.5">
+                <label className="text-sm font-medium text-foreground">Einddatum</label>
+                <input type="date" name="end_date" defaultValue={toDateInputValue(sprint.end_date)} className="w-full rounded-md border border-border bg-surface-container px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-primary" />
+                {typeof datesState?.error === 'object' && (datesState.error as Record<string, string[]>).end_date && (
+                  <p className="text-xs text-error">{(datesState.error as Record<string, string[]>).end_date[0]}</p>
+                )}
+              </div>
+            </div>
+            {typeof datesState?.error === 'string' && (
+              <p className="text-xs text-error">{datesState.error}</p>
+            )}
+            <div className="flex gap-2 justify-end">
+              <Button type="button" variant="ghost" onClick={() => setEditingDates(false)}>Annuleren</Button>
+              <Button type="submit">Opslaan</Button>
+            </div>
+          </form>
+        </DialogContent>
+      </Dialog>
+
       {/* Complete sprint dialog */}
       <Dialog open={completeOpen} onOpenChange={setCompleteOpen}>
         <DialogContent className="sm:max-w-2xl">
diff --git a/components/sprint/start-sprint-button.tsx b/components/sprint/start-sprint-button.tsx
index f0b951c..f9c18d6 100644
--- a/components/sprint/start-sprint-button.tsx
+++ b/components/sprint/start-sprint-button.tsx
@@ -75,6 +75,23 @@ export function StartSprintButton({ productId }: StartSprintButtonProps) {
               )}
             </div>
 
+            <div className="grid grid-cols-2 gap-3">
+              <div className="space-y-1.5">
+                <label className="text-sm font-medium text-foreground">Startdatum</label>
+                <input type="date" name="start_date" className="w-full rounded-md border border-border bg-surface-container px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-primary" />
+                {typeof state?.error === 'object' && (state.error as Record<string, string[]>).start_date && (
+                  <p className="text-xs text-error">{(state.error as Record<string, string[]>).start_date[0]}</p>
+                )}
+              </div>
+              <div className="space-y-1.5">
+                <label className="text-sm font-medium text-foreground">Einddatum</label>
+                <input type="date" name="end_date" className="w-full rounded-md border border-border bg-surface-container px-3 py-2 text-sm focus:outline-none focus:ring-1 focus:ring-primary" />
+                {typeof state?.error === 'object' && (state.error as Record<string, string[]>).end_date && (
+                  <p className="text-xs text-error">{(state.error as Record<string, string[]>).end_date[0]}</p>
+                )}
+              </div>
+            </div>
+
             {globalError && (
               <div className="bg-error-container text-error-container-foreground rounded-lg px-3 py-2 text-sm border-l-4 border-error">
                 {globalError}
diff --git a/lib/chart-colors.ts b/lib/chart-colors.ts
new file mode 100644
index 0000000..561d4dc
--- /dev/null
+++ b/lib/chart-colors.ts
@@ -0,0 +1,39 @@
+// Mapping van MD3-tokens naar CSS-var-strings voor Recharts fill/stroke.
+// Recharts accepteert gewone strings — 'var(--status-done)' werkt direct.
+export const STATUS_COLORS = {
+  TO_DO: 'var(--status-todo)',
+  IN_PROGRESS: 'var(--status-in-progress)',
+  REVIEW: 'var(--status-in-progress)',
+  DONE: 'var(--status-done)',
+} as const
+
+export const PRIORITY_COLORS = {
+  1: 'var(--priority-critical)',
+  2: 'var(--priority-high)',
+  3: 'var(--priority-medium)',
+  4: 'var(--priority-low)',
+} as const
+
+export const VERIFY_COLORS = {
+  ALIGNED: 'var(--status-done)',
+  PARTIAL: 'var(--priority-medium)',
+  EMPTY: 'var(--priority-critical)',
+  DIVERGENT: 'var(--priority-high)',
+} as const
+
+export const JOB_STATUS_COLORS = {
+  queued: 'var(--muted-foreground)',
+  claimed: 'var(--status-in-progress)',
+  running: 'var(--status-in-progress)',
+  done: 'var(--status-done)',
+  failed: 'var(--priority-critical)',
+  cancelled: 'var(--muted-foreground)',
+} as const
+
+export const SERIES_COLORS = [
+  'var(--chart-1)',
+  'var(--chart-2)',
+  'var(--chart-3)',
+  'var(--chart-4)',
+  'var(--chart-5)',
+] as const
diff --git a/prisma/migrations/20260502132322_add_sprint_dates_and_jobs_index/migration.sql b/prisma/migrations/20260502132322_add_sprint_dates_and_jobs_index/migration.sql
new file mode 100644
index 0000000..c73d025
--- /dev/null
+++ b/prisma/migrations/20260502132322_add_sprint_dates_and_jobs_index/migration.sql
@@ -0,0 +1,6 @@
+-- AlterTable
+ALTER TABLE "sprints" ADD COLUMN     "end_date" DATE,
+ADD COLUMN     "start_date" DATE;
+
+-- CreateIndex
+CREATE INDEX IF NOT EXISTS "claude_jobs_status_finished_at_idx" ON "claude_jobs"("status", "finished_at");
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 820695b..4beb4f4 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -223,6 +223,8 @@ model Sprint {
   product_id   String
   sprint_goal  String
   status       SprintStatus @default(ACTIVE)
+  start_date   DateTime?    @db.Date
+  end_date     DateTime?    @db.Date
   created_at   DateTime     @default(now())
   completed_at DateTime?
   stories      Story[]

From 219d54b3e5586a84494f440d55c3571808c847ae Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 16:07:57 +0200
Subject: [PATCH 03/17] =?UTF-8?q?feat(insights):=20add=20getVelocity=20hel?=
 =?UTF-8?q?per=20=E2=80=94=20DONE-tasks=20per=20completed=20sprint=20(#47)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Aggregates task.status=DONE counts across last N completed sprints
(default 5), filtered by productAccessFilter and returned in
chronological order for x-axis rendering.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 __tests__/lib/insights/velocity.test.ts | 77 +++++++++++++++++++++++++
 lib/insights/velocity.ts                | 57 ++++++++++++++++++
 2 files changed, 134 insertions(+)
 create mode 100644 __tests__/lib/insights/velocity.test.ts
 create mode 100644 lib/insights/velocity.ts

diff --git a/__tests__/lib/insights/velocity.test.ts b/__tests__/lib/insights/velocity.test.ts
new file mode 100644
index 0000000..535c1fa
--- /dev/null
+++ b/__tests__/lib/insights/velocity.test.ts
@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest'
+
+const { mockFindMany } = vi.hoisted(() => ({ mockFindMany: vi.fn() }))
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    sprint: { findMany: mockFindMany },
+  },
+}))
+
+vi.mock('@/lib/product-access', () => ({
+  productAccessFilter: () => ({ some: 'filter' }),
+}))
+
+import { getVelocity } from '@/lib/insights/velocity'
+
+const completedAt = (iso: string) => new Date(iso)
+
+function makeSprint(id: string, goal: string, productId: string, productName: string, doneCounts: number, completedIso: string) {
+  const tasks = Array.from({ length: doneCounts }, () => ({ status: 'DONE' }))
+  return {
+    id,
+    sprint_goal: goal,
+    completed_at: completedAt(completedIso),
+    product: { id: productId, name: productName },
+    tasks,
+  }
+}
+
+describe('getVelocity', () => {
+  it('returns 3 sprints in chronological order with correct done counts', async () => {
+    // DB returns newest-first (orderBy: completed_at desc), getVelocity reverses to oldest-first
+    mockFindMany.mockResolvedValue([
+      makeSprint('s3', 'Sprint C', 'p1', 'Prod A', 3, '2024-03-01T00:00:00.000Z'),
+      makeSprint('s2', 'Sprint B', 'p1', 'Prod A', 5, '2024-02-01T00:00:00.000Z'),
+      makeSprint('s1', 'Sprint A', 'p1', 'Prod A', 2, '2024-01-01T00:00:00.000Z'),
+    ])
+
+    const result = await getVelocity('user-1')
+
+    expect(result.sprints).toHaveLength(3)
+    expect(result.sprints.map(s => s.doneCount)).toEqual([2, 5, 3])
+    expect(result.sprints.map(s => s.sprintId)).toEqual(['s1', 's2', 's3'])
+  })
+
+  it('deduplicates productNames from sprints', async () => {
+    mockFindMany.mockResolvedValue([
+      makeSprint('s2', 'Sprint B', 'p2', 'Prod B', 1, '2024-02-01T00:00:00.000Z'),
+      makeSprint('s1', 'Sprint A', 'p1', 'Prod A', 2, '2024-01-01T00:00:00.000Z'),
+    ])
+
+    const result = await getVelocity('user-1')
+
+    const ids = result.productNames.map(p => p.id)
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(result.productNames).toHaveLength(2)
+  })
+
+  it('returns empty sprints and productNames when no completed sprints exist', async () => {
+    mockFindMany.mockResolvedValue([])
+
+    const result = await getVelocity('user-1')
+
+    expect(result.sprints).toEqual([])
+    expect(result.productNames).toEqual([])
+  })
+
+  it('passes sprintsBack as take parameter', async () => {
+    mockFindMany.mockResolvedValue([])
+
+    await getVelocity('user-1', 3)
+
+    expect(mockFindMany).toHaveBeenCalledWith(
+      expect.objectContaining({ take: 3 }),
+    )
+  })
+})
diff --git a/lib/insights/velocity.ts b/lib/insights/velocity.ts
new file mode 100644
index 0000000..528b321
--- /dev/null
+++ b/lib/insights/velocity.ts
@@ -0,0 +1,57 @@
+import { prisma } from '@/lib/prisma'
+import { productAccessFilter } from '@/lib/product-access'
+
+export interface VelocitySprint {
+  sprintId: string
+  sprintGoal: string
+  productId: string
+  productName: string
+  doneCount: number
+  completedAt: string
+}
+
+export interface VelocityData {
+  sprints: VelocitySprint[]
+  productNames: { id: string; name: string }[]
+}
+
+export async function getVelocity(userId: string, sprintsBack = 5): Promise<VelocityData> {
+  const sprints = await prisma.sprint.findMany({
+    where: {
+      status: 'COMPLETED',
+      product: productAccessFilter(userId),
+    },
+    orderBy: { completed_at: 'desc' },
+    take: sprintsBack,
+    select: {
+      id: true,
+      sprint_goal: true,
+      completed_at: true,
+      product: { select: { id: true, name: true } },
+      tasks: { select: { status: true } },
+    },
+  })
+
+  // Reverse to chronological order (oldest first, for x-axis)
+  const chronological = [...sprints].reverse()
+
+  const result: VelocitySprint[] = chronological.map(sprint => ({
+    sprintId: sprint.id,
+    sprintGoal: sprint.sprint_goal,
+    productId: sprint.product.id,
+    productName: sprint.product.name,
+    doneCount: sprint.tasks.filter(t => t.status === 'DONE').length,
+    completedAt: sprint.completed_at!.toISOString(),
+  }))
+
+  const seen = new Set<string>()
+  const productNames: { id: string; name: string }[] = []
+  for (const s of result) {
+    if (!seen.has(s.productId)) {
+      seen.add(s.productId)
+      productNames.push({ id: s.productId, name: s.productName })
+    }
+  }
+
+  return { sprints: result, productNames }
+}

From af775534071f195be8824f2c232600788bfa7020 Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 16:17:03 +0200
Subject: [PATCH 04/17] =?UTF-8?q?feat(insights):=20add=20getBacklogHealth?=
 =?UTF-8?q?=20helper=20=E2=80=94=20stuck=20tasks=20+=20missing=20AC/plan?=
 =?UTF-8?q?=20counts=20(#48)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three read-only counters: stories without acceptance_criteria, tasks without
implementation_plan, and top-10 IN_PROGRESS tasks stuck >7 days. All scoped
via productAccessFilter.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 __tests__/lib/insights/backlog-health.test.ts | 82 +++++++++++++++++++
 lib/insights/backlog-health.ts                | 69 ++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 __tests__/lib/insights/backlog-health.test.ts
 create mode 100644 lib/insights/backlog-health.ts

diff --git a/__tests__/lib/insights/backlog-health.test.ts b/__tests__/lib/insights/backlog-health.test.ts
new file mode 100644
index 0000000..f74bfe3
--- /dev/null
+++ b/__tests__/lib/insights/backlog-health.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { mockStoryCount, mockTaskCount, mockTaskFindMany } = vi.hoisted(() => ({
+  mockStoryCount: vi.fn(),
+  mockTaskCount: vi.fn(),
+  mockTaskFindMany: vi.fn(),
+}))
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    story: { count: mockStoryCount },
+    task: { count: mockTaskCount, findMany: mockTaskFindMany },
+  },
+}))
+
+vi.mock('@/lib/product-access', () => ({
+  productAccessFilter: () => ({ some: 'filter' }),
+}))
+
+import { getBacklogHealth } from '@/lib/insights/backlog-health'
+
+function makeTask(id: string, daysAgo: number) {
+  const updatedAt = new Date(Date.now() - daysAgo * 86_400_000)
+  return {
+    id,
+    title: `Task ${id}`,
+    updated_at: updatedAt,
+    story: {
+      product: { id: 'prod-1', name: 'My Product' },
+      sprint: { sprint_goal: 'Sprint goal' },
+    },
+  }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('getBacklogHealth', () => {
+  it('returns all zeros when backlog is healthy', async () => {
+    mockStoryCount.mockResolvedValue(0)
+    mockTaskCount.mockResolvedValue(0)
+    mockTaskFindMany.mockResolvedValue([])
+
+    const result = await getBacklogHealth('user-1')
+
+    expect(result.storiesWithoutAc).toBe(0)
+    expect(result.tasksWithoutPlan).toBe(0)
+    expect(result.stuckTasks).toEqual([])
+  })
+
+  it('returns counts and stuck tasks when everything is flagged', async () => {
+    mockStoryCount.mockResolvedValue(5)
+    mockTaskCount.mockResolvedValue(3)
+    mockTaskFindMany.mockResolvedValue([makeTask('t1', 10), makeTask('t2', 8)])
+
+    const result = await getBacklogHealth('user-1')
+
+    expect(result.storiesWithoutAc).toBe(5)
+    expect(result.tasksWithoutPlan).toBe(3)
+    expect(result.stuckTasks).toHaveLength(2)
+    expect(result.stuckTasks[0].taskId).toBe('t1')
+    expect(result.stuckTasks[0].daysStuck).toBeGreaterThanOrEqual(10)
+    expect(result.stuckTasks[0].productName).toBe('My Product')
+    expect(result.stuckTasks[0].sprintGoal).toBe('Sprint goal')
+  })
+
+  it('mixed: some counters non-zero, one stuck task, no sprint', async () => {
+    mockStoryCount.mockResolvedValue(2)
+    mockTaskCount.mockResolvedValue(0)
+    const task = makeTask('t3', 14)
+    task.story.sprint = null as unknown as { sprint_goal: string }
+    mockTaskFindMany.mockResolvedValue([task])
+
+    const result = await getBacklogHealth('user-1')
+
+    expect(result.storiesWithoutAc).toBe(2)
+    expect(result.tasksWithoutPlan).toBe(0)
+    expect(result.stuckTasks[0].sprintGoal).toBeNull()
+    expect(result.stuckTasks[0].daysStuck).toBeGreaterThanOrEqual(14)
+  })
+})
diff --git a/lib/insights/backlog-health.ts b/lib/insights/backlog-health.ts
new file mode 100644
index 0000000..5dc0ef2
--- /dev/null
+++ b/lib/insights/backlog-health.ts
@@ -0,0 +1,69 @@
+import { prisma } from '@/lib/prisma'
+import { productAccessFilter } from '@/lib/product-access'
+
+export interface StuckTask {
+  taskId: string
+  title: string
+  productId: string
+  productName: string
+  sprintGoal: string | null
+  daysStuck: number
+  updatedAt: string
+}
+
+export interface BacklogHealth {
+  storiesWithoutAc: number
+  tasksWithoutPlan: number
+  stuckTasks: StuckTask[]
+}
+
+const SEVEN_DAYS_MS = 7 * 86_400_000
+
+export async function getBacklogHealth(userId: string): Promise<BacklogHealth> {
+  const now = new Date()
+  const stuckCutoff = new Date(now.getTime() - SEVEN_DAYS_MS)
+
+  const [storiesWithoutAc, tasksWithoutPlan, rawStuck] = await Promise.all([
+    prisma.story.count({
+      where: {
+        OR: [{ acceptance_criteria: null }, { acceptance_criteria: '' }],
+        product: productAccessFilter(userId),
+      },
+    }),
+    prisma.task.count({
+      where: {
+        implementation_plan: null,
+        story: { product: productAccessFilter(userId) },
+      },
+    }),
+    prisma.task.findMany({
+      where: {
+        status: 'IN_PROGRESS',
+        updated_at: { lt: stuckCutoff },
+        story: { product: productAccessFilter(userId) },
+      },
+      orderBy: { updated_at: 'asc' },
+      take: 10,
+      include: {
+        story: {
+          include: {
+            product: { select: { id: true, name: true } },
+            sprint: { select: { sprint_goal: true } },
+          },
+        },
+      },
+    }),
+  ])
+
+  const stuckTasks: StuckTask[] = rawStuck.map(t => ({
+    taskId: t.id,
+    title: t.title,
+    productId: t.story.product.id,
+    productName: t.story.product.name,
+    sprintGoal: t.story.sprint?.sprint_goal ?? null,
+    daysStuck: Math.floor((now.getTime() - t.updated_at.getTime()) / 86_400_000),
+    updatedAt: t.updated_at.toISOString(),
+  }))
+
+  return { storiesWithoutAc, tasksWithoutPlan, stuckTasks }
+}

From 739037a60b53c010acc18c950b3a8f344f4c91ac Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 16:30:06 +0200
Subject: [PATCH 05/17] Agent throughput: jobs per dag stacked bar + KPI-strip
 (#49)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(insights): add getJobsPerDay helper — agent throughput per day + KPIs

Raw SQL aggregation of claude_jobs by day and status over 14 days with
zero-fill for missing days. KPIs: todayCount, successRate7d, avgDurationSeconds7d.
Optional productId filter.

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

* feat(insights): add AgentThroughputCard — stacked BarChart + KPI-strip + product filter

KPI strip (jobs today, 7d success rate, 7d avg duration), 14-day stacked
BarChart with JOB_STATUS_COLORS, and URL-bookmarkable product dropdown via
useTransition + router.replace. Empty-state when no activity.

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../lib/insights/agent-throughput.test.ts     |  82 +++++++++++
 .../insights/components/agent-throughput.tsx  | 133 ++++++++++++++++++
 lib/insights/agent-throughput.ts              | 118 ++++++++++++++++
 3 files changed, 333 insertions(+)
 create mode 100644 __tests__/lib/insights/agent-throughput.test.ts
 create mode 100644 app/(app)/insights/components/agent-throughput.tsx
 create mode 100644 lib/insights/agent-throughput.ts

diff --git a/__tests__/lib/insights/agent-throughput.test.ts b/__tests__/lib/insights/agent-throughput.test.ts
new file mode 100644
index 0000000..3465dd4
--- /dev/null
+++ b/__tests__/lib/insights/agent-throughput.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { mockQueryRaw } = vi.hoisted(() => ({ mockQueryRaw: vi.fn() }))
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: { $queryRaw: mockQueryRaw },
+}))
+
+import { getJobsPerDay } from '@/lib/insights/agent-throughput'
+
+// Build a date string for N days ago (UTC)
+function daysAgo(n: number): Date {
+  const d = new Date()
+  d.setUTCDate(d.getUTCDate() - n)
+  return d
+}
+
+function toUTCDate(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('getJobsPerDay', () => {
+  it('returns a 14-day array zero-filled for missing days', async () => {
+    // Only 3 days have data; the rest should be 0
+    const day0 = toUTCDate(daysAgo(0))
+    const day3 = toUTCDate(daysAgo(3))
+    const day7 = toUTCDate(daysAgo(7))
+
+    const dayRows = [
+      { day: day0, status: 'done', count: BigInt(2) },
+      { day: day3, status: 'failed', count: BigInt(1) },
+      { day: day7, status: 'done', count: BigInt(5) },
+    ]
+
+    const kpiRows = [
+      { today_count: BigInt(2), done_7d: BigInt(7), terminal_7d: BigInt(10), avg_seconds: 120 },
+    ]
+
+    mockQueryRaw.mockResolvedValueOnce(dayRows).mockResolvedValueOnce(kpiRows)
+
+    const result = await getJobsPerDay('user-1')
+
+    expect(result.perDay).toHaveLength(14)
+
+    // All days should have zero counts except the three we seeded
+    const nonZero = result.perDay.filter(
+      d => d.done + d.failed + d.queued + d.claimed + d.running + d.cancelled > 0,
+    )
+    expect(nonZero).toHaveLength(3)
+
+    // Today's done count should be 2
+    const today = result.perDay[result.perDay.length - 1]
+    expect(today.done).toBe(2)
+  })
+
+  it('calculates KPIs correctly', async () => {
+    mockQueryRaw.mockResolvedValueOnce([]).mockResolvedValueOnce([
+      { today_count: BigInt(3), done_7d: BigInt(7), terminal_7d: BigInt(10), avg_seconds: 90 },
+    ])
+
+    const result = await getJobsPerDay('user-1')
+
+    expect(result.kpi.todayCount).toBe(3)
+    expect(result.kpi.successRate7d).toBe(0.7)
+    expect(result.kpi.avgDurationSeconds7d).toBe(90)
+  })
+
+  it('returns zero successRate and null avgDuration when no terminal jobs', async () => {
+    mockQueryRaw.mockResolvedValueOnce([]).mockResolvedValueOnce([
+      { today_count: BigInt(0), done_7d: BigInt(0), terminal_7d: BigInt(0), avg_seconds: null },
+    ])
+
+    const result = await getJobsPerDay('user-1')
+
+    expect(result.kpi.successRate7d).toBe(0)
+    expect(result.kpi.avgDurationSeconds7d).toBeNull()
+  })
+})
diff --git a/app/(app)/insights/components/agent-throughput.tsx b/app/(app)/insights/components/agent-throughput.tsx
new file mode 100644
index 0000000..820e64f
--- /dev/null
+++ b/app/(app)/insights/components/agent-throughput.tsx
@@ -0,0 +1,133 @@
+'use client'
+
+import { useRouter, usePathname, useSearchParams } from 'next/navigation'
+import { useTransition } from 'react'
+import {
+  BarChart,
+  Bar,
+  XAxis,
+  YAxis,
+  Tooltip,
+  ResponsiveContainer,
+} from 'recharts'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import type { JobsPerDayResult } from '@/lib/insights/agent-throughput'
+import { JOB_STATUS_COLORS } from '@/lib/chart-colors'
+
+interface Props {
+  data: JobsPerDayResult
+  productList: { id: string; name: string }[]
+  currentProductId?: string
+}
+
+function formatDuration(seconds: number | null): string {
+  if (seconds === null) return '—'
+  const m = Math.floor(seconds / 60)
+  const s = seconds % 60
+  return m > 0 ? `${m}m ${s}s` : `${s}s`
+}
+
+const STACKED_STATUSES = ['queued', 'claimed', 'running', 'done', 'failed', 'cancelled'] as const
+
+export function AgentThroughputCard({ data, productList, currentProductId }: Props) {
+  const router = useRouter()
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+  const [isPending, startTransition] = useTransition()
+
+  const { perDay, kpi } = data
+
+  const isEmpty = perDay.every(
+    d => d.done + d.failed + d.queued + d.claimed + d.running + d.cancelled === 0,
+  )
+
+  function handleProductChange(value: string | null) {
+    if (value === null) return
+    startTransition(() => {
+      const params = new URLSearchParams(searchParams.toString())
+      if (value === '__all__') {
+        params.delete('product')
+      } else {
+        params.set('product', value)
+      }
+      router.replace(`${pathname}?${params.toString()}`)
+    })
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* KPI strip + product filter */}
+      <div className="flex items-start justify-between gap-4 flex-wrap">
+        <div className="flex gap-6">
+          <div>
+            <div className="text-2xl font-semibold text-foreground">{kpi.todayCount}</div>
+            <div className="text-xs text-muted-foreground">Jobs vandaag</div>
+          </div>
+          <div>
+            <div className="text-2xl font-semibold text-foreground">
+              {kpi.successRate7d === 0 ? '—' : `${Math.round(kpi.successRate7d * 100)}%`}
+            </div>
+            <div className="text-xs text-muted-foreground">Success-rate (7d)</div>
+          </div>
+          <div>
+            <div className="text-2xl font-semibold text-foreground">
+              {formatDuration(kpi.avgDurationSeconds7d)}
+            </div>
+            <div className="text-xs text-muted-foreground">Avg duration (7d)</div>
+          </div>
+        </div>
+
+        {productList.length > 0 && (
+          <Select
+            value={currentProductId ?? '__all__'}
+            onValueChange={handleProductChange}
+          >
+            <SelectTrigger className="w-44" disabled={isPending}>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="__all__">Alle producten</SelectItem>
+              {productList.map(p => (
+                <SelectItem key={p.id} value={p.id}>{p.name}</SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        )}
+      </div>
+
+      {/* Chart */}
+      {isEmpty ? (
+        <p className="text-sm text-muted-foreground py-4 text-center">
+          Geen agent-activiteit in de laatste 2 weken
+        </p>
+      ) : (
+        <ResponsiveContainer width="100%" height={240}>
+          <BarChart data={perDay}>
+            <XAxis
+              dataKey="day"
+              tick={{ fontSize: 11 }}
+              tickFormatter={v => (v as string).slice(5)}
+            />
+            <YAxis allowDecimals={false} tick={{ fontSize: 11 }} />
+            <Tooltip />
+            {STACKED_STATUSES.map(status => (
+              <Bar
+                key={status}
+                dataKey={status}
+                stackId="status"
+                fill={JOB_STATUS_COLORS[status]}
+                name={status}
+              />
+            ))}
+          </BarChart>
+        </ResponsiveContainer>
+      )}
+    </div>
+  )
+}
diff --git a/lib/insights/agent-throughput.ts b/lib/insights/agent-throughput.ts
new file mode 100644
index 0000000..ecc97ac
--- /dev/null
+++ b/lib/insights/agent-throughput.ts
@@ -0,0 +1,118 @@
+import { prisma } from '@/lib/prisma'
+
+export interface DayCount {
+  day: string
+  queued: number
+  claimed: number
+  running: number
+  done: number
+  failed: number
+  cancelled: number
+}
+
+export interface ThroughputKpi {
+  todayCount: number
+  successRate7d: number
+  avgDurationSeconds7d: number | null
+}
+
+export interface JobsPerDayResult {
+  perDay: DayCount[]
+  kpi: ThroughputKpi
+}
+
+const STATUSES = ['queued', 'claimed', 'running', 'done', 'failed', 'cancelled'] as const
+
+type RawDayRow = { day: Date; status: string; count: bigint }
+type RawKpiRow = { today_count: bigint; done_7d: bigint; terminal_7d: bigint; avg_seconds: number | null }
+
+function toDateStr(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+export async function getJobsPerDay(
+  userId: string,
+  days = 14,
+  productId?: string,
+): Promise<JobsPerDayResult> {
+  const [dayRows, kpiRows] = await Promise.all([
+    productId
+      ? prisma.$queryRaw<RawDayRow[]>`
+          SELECT DATE(created_at) AS day, LOWER(status::text) AS status, COUNT(*) AS count
+          FROM claude_jobs
+          WHERE user_id = ${userId}
+            AND product_id = ${productId}
+            AND created_at > NOW() - (${days} || ' days')::INTERVAL
+          GROUP BY DATE(created_at), status
+          ORDER BY day ASC
+        `
+      : prisma.$queryRaw<RawDayRow[]>`
+          SELECT DATE(created_at) AS day, LOWER(status::text) AS status, COUNT(*) AS count
+          FROM claude_jobs
+          WHERE user_id = ${userId}
+            AND created_at > NOW() - (${days} || ' days')::INTERVAL
+          GROUP BY DATE(created_at), status
+          ORDER BY day ASC
+        `,
+    productId
+      ? prisma.$queryRaw<RawKpiRow[]>`
+          SELECT
+            COUNT(*) FILTER (WHERE DATE(created_at) = CURRENT_DATE) AS today_count,
+            COUNT(*) FILTER (WHERE status = 'DONE' AND created_at > NOW() - INTERVAL '7 days') AS done_7d,
+            COUNT(*) FILTER (WHERE status IN ('DONE','FAILED','CANCELLED') AND created_at > NOW() - INTERVAL '7 days') AS terminal_7d,
+            AVG(EXTRACT(EPOCH FROM (finished_at - claimed_at))) FILTER (WHERE status = 'DONE' AND created_at > NOW() - INTERVAL '7 days') AS avg_seconds
+          FROM claude_jobs
+          WHERE user_id = ${userId}
+            AND product_id = ${productId}
+        `
+      : prisma.$queryRaw<RawKpiRow[]>`
+          SELECT
+            COUNT(*) FILTER (WHERE DATE(created_at) = CURRENT_DATE) AS today_count,
+            COUNT(*) FILTER (WHERE status = 'DONE' AND created_at > NOW() - INTERVAL '7 days') AS done_7d,
+            COUNT(*) FILTER (WHERE status IN ('DONE','FAILED','CANCELLED') AND created_at > NOW() - INTERVAL '7 days') AS terminal_7d,
+            AVG(EXTRACT(EPOCH FROM (finished_at - claimed_at))) FILTER (WHERE status = 'DONE' AND created_at > NOW() - INTERVAL '7 days') AS avg_seconds
+          FROM claude_jobs
+          WHERE user_id = ${userId}
+        `,
+  ])
+
+  // Build lookup: dayStr → status → count
+  const lookup = new Map<string, Map<string, number>>()
+  for (const row of dayRows) {
+    const d = toDateStr(row.day)
+    if (!lookup.has(d)) lookup.set(d, new Map())
+    lookup.get(d)!.set(row.status, Number(row.count))
+  }
+
+  // Generate full date range with zero-fills
+  const now = new Date()
+  const perDay: DayCount[] = []
+  for (let i = days - 1; i >= 0; i--) {
+    const d = new Date(now)
+    d.setUTCDate(d.getUTCDate() - i)
+    const key = toDateStr(d)
+    const statusMap = lookup.get(key) ?? new Map()
+    perDay.push({
+      day: key,
+      queued: statusMap.get('queued') ?? 0,
+      claimed: statusMap.get('claimed') ?? 0,
+      running: statusMap.get('running') ?? 0,
+      done: statusMap.get('done') ?? 0,
+      failed: statusMap.get('failed') ?? 0,
+      cancelled: statusMap.get('cancelled') ?? 0,
+    })
+  }
+
+  const kpiRow = kpiRows[0]
+  const done7d = Number(kpiRow?.done_7d ?? 0)
+  const terminal7d = Number(kpiRow?.terminal_7d ?? 0)
+
+  return {
+    perDay,
+    kpi: {
+      todayCount: Number(kpiRow?.today_count ?? 0),
+      successRate7d: terminal7d === 0 ? 0 : Math.round((done7d / terminal7d) * 100) / 100,
+      avgDurationSeconds7d: kpiRow?.avg_seconds != null ? Math.round(Number(kpiRow.avg_seconds)) : null,
+    },
+  }
+}

From d93c91c38633989f69a6e99325222482891faf3c Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 17:23:03 +0200
Subject: [PATCH 06/17] fix(insights): integrate all 5 sections in /insights +
 add missing components (#50)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The /insights page was rendering only Sprint Health (2 charts).
PRs #47/#48/#49 delivered helpers + tests for Velocity, Backlog health
and Agent throughput, but Velocity and Backlog never produced their
UI components, and none of the four new sections were wired into
page.tsx. Result: user sees 2 charts where 5 sections were promised.

This PR fills the gaps:

- New `app/(app)/insights/components/velocity-chart.tsx` — Recharts
  grouped BarChart with optional ReferenceLine for the average. Empty
  state when <2 completed sprints.
- New `app/(app)/insights/components/backlog-health.tsx` — counters
  (stories sans AC / tasks sans plan / stuck>7d) + stuck-tasks table
  with severity-coded days-stuck cell.
- `app/(app)/insights/page.tsx` rewritten as 5 sections:
  Sprint Health, Plan-quality (donut + alignment-trend), Agent
  throughput, Velocity, Backlog health. Helpers run in one
  Promise.all so the page renders in a single tick.

Tests: 314/314 green, tsc clean, lint 0 errors.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../insights/components/backlog-health.tsx    |  90 +++++++++++
 .../insights/components/velocity-chart.tsx    |  92 ++++++++++++
 app/(app)/insights/page.tsx                   | 141 +++++++++++++-----
 3 files changed, 283 insertions(+), 40 deletions(-)
 create mode 100644 app/(app)/insights/components/backlog-health.tsx
 create mode 100644 app/(app)/insights/components/velocity-chart.tsx

diff --git a/app/(app)/insights/components/backlog-health.tsx b/app/(app)/insights/components/backlog-health.tsx
new file mode 100644
index 0000000..193efe9
--- /dev/null
+++ b/app/(app)/insights/components/backlog-health.tsx
@@ -0,0 +1,90 @@
+'use client'
+
+import Link from 'next/link'
+import { CheckCircle2, AlertTriangle } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import type { BacklogHealth, StuckTask } from '@/lib/insights/backlog-health'
+
+interface Props {
+  data: BacklogHealth
+}
+
+function Counter({ count, label }: { count: number; label: string }) {
+  const ok = count === 0
+  return (
+    <div className="flex items-center gap-2 rounded-md border border-border px-3 py-2 text-sm">
+      {ok ? (
+        <CheckCircle2 className="size-4 text-status-done shrink-0" />
+      ) : (
+        <AlertTriangle className="size-4 text-priority-medium shrink-0" />
+      )}
+      <span className={cn('font-semibold', ok && 'text-status-done')}>{count}</span>
+      <span className="text-muted-foreground">{label}</span>
+    </div>
+  )
+}
+
+function StuckRow({ task }: { task: StuckTask }) {
+  const severity =
+    task.daysStuck >= 14
+      ? 'bg-priority-critical/10 text-priority-critical'
+      : task.daysStuck >= 7
+        ? 'bg-priority-high/10 text-priority-high'
+        : ''
+  return (
+    <tr className="border-b border-border last:border-0">
+      <td className="py-1 pr-2">
+        <Link
+          href={`/products/${task.productId}/solo?task=${task.taskId}`}
+          className="text-primary underline line-clamp-1"
+        >
+          {task.title}
+        </Link>
+      </td>
+      <td className="py-1 pr-2 text-muted-foreground whitespace-nowrap">
+        {task.productName}
+      </td>
+      <td className={cn('py-1 px-2 text-right whitespace-nowrap rounded font-medium', severity)}>
+        {task.daysStuck}d
+      </td>
+      <td className="py-1 pl-2 text-muted-foreground whitespace-nowrap">
+        {task.sprintGoal ?? '—'}
+      </td>
+    </tr>
+  )
+}
+
+export function BacklogHealthCard({ data }: Props) {
+  const { storiesWithoutAc, tasksWithoutPlan, stuckTasks } = data
+  const allClear =
+    storiesWithoutAc === 0 && tasksWithoutPlan === 0 && stuckTasks.length === 0
+
+  return (
+    <div className="rounded-lg border border-border p-4 space-y-3">
+      <h2 className="text-sm font-medium">Backlog health</h2>
+
+      <div className="flex flex-wrap gap-2">
+        <Counter count={storiesWithoutAc} label="stories zonder AC" />
+        <Counter count={tasksWithoutPlan} label="tasks zonder plan" />
+        <Counter count={stuckTasks.length} label="stuck > 7d" />
+      </div>
+
+      {allClear ? (
+        <p className="text-sm text-status-done">Geen stuck tasks 🎉</p>
+      ) : stuckTasks.length > 0 ? (
+        <div>
+          <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wide mb-1">
+            Stuck tasks (top {stuckTasks.length})
+          </p>
+          <table className="w-full text-sm">
+            <tbody>
+              {stuckTasks.map(t => (
+                <StuckRow key={t.taskId} task={t} />
+              ))}
+            </tbody>
+          </table>
+        </div>
+      ) : null}
+    </div>
+  )
+}
diff --git a/app/(app)/insights/components/velocity-chart.tsx b/app/(app)/insights/components/velocity-chart.tsx
new file mode 100644
index 0000000..7cd2d9e
--- /dev/null
+++ b/app/(app)/insights/components/velocity-chart.tsx
@@ -0,0 +1,92 @@
+'use client'
+
+import {
+  BarChart,
+  Bar,
+  XAxis,
+  YAxis,
+  Tooltip,
+  Legend,
+  ReferenceLine,
+  ResponsiveContainer,
+} from 'recharts'
+import type { VelocityData } from '@/lib/insights/velocity'
+import { SERIES_COLORS } from '@/lib/chart-colors'
+
+interface Props {
+  data: VelocityData
+}
+
+export function VelocityChart({ data }: Props) {
+  const { sprints, productNames } = data
+
+  if (sprints.length < 2) {
+    return (
+      <div className="rounded-lg border border-border p-4 space-y-2">
+        <h2 className="text-sm font-medium">Velocity</h2>
+        <p className="text-sm text-muted-foreground">
+          Velocity wordt zichtbaar na 2+ voltooide sprints (nu: {sprints.length}).
+        </p>
+      </div>
+    )
+  }
+
+  // Reshape: [{ sprintLabel, [productName1]: count, [productName2]: count, ... }]
+  type Row = { sprintLabel: string } & Record<string, number | string>
+  const grouped = new Map<string, Row>()
+  for (const s of sprints) {
+    const label =
+      s.sprintGoal.length > 14 ? s.sprintGoal.slice(0, 14) + '…' : s.sprintGoal
+    const key = `${s.sprintId}`
+    if (!grouped.has(key)) {
+      grouped.set(key, { sprintLabel: label })
+    }
+    grouped.get(key)![s.productName] = s.doneCount
+  }
+  const rows = Array.from(grouped.values())
+
+  // Average across all bars (used for ReferenceLine)
+  const allCounts = sprints.map(s => s.doneCount)
+  const avg = allCounts.length > 0 ? allCounts.reduce((a, b) => a + b, 0) / allCounts.length : 0
+
+  return (
+    <div className="rounded-lg border border-border p-4 space-y-2">
+      <h2 className="text-sm font-medium">Velocity (laatste {sprints.length} sprints)</h2>
+      <ResponsiveContainer width="100%" height={240}>
+        <BarChart data={rows}>
+          <XAxis
+            dataKey="sprintLabel"
+            tick={{ fontSize: 11 }}
+            stroke="var(--muted-foreground)"
+          />
+          <YAxis tick={{ fontSize: 11 }} stroke="var(--muted-foreground)" />
+          <Tooltip
+            contentStyle={{
+              background: 'var(--popover)',
+              border: '1px solid var(--border)',
+              borderRadius: 6,
+              fontSize: 12,
+            }}
+          />
+          <Legend wrapperStyle={{ fontSize: 12 }} />
+          {productNames.map((p, i) => (
+            <Bar
+              key={p.id}
+              dataKey={p.name}
+              fill={SERIES_COLORS[i % SERIES_COLORS.length]}
+              radius={[2, 2, 0, 0]}
+            />
+          ))}
+          {avg > 0 && (
+            <ReferenceLine
+              y={avg}
+              stroke="var(--muted-foreground)"
+              strokeDasharray="3 3"
+              label={{ value: `avg ${avg.toFixed(1)}`, fontSize: 10, fill: 'var(--muted-foreground)' }}
+            />
+          )}
+        </BarChart>
+      </ResponsiveContainer>
+    </div>
+  )
+}
diff --git a/app/(app)/insights/page.tsx b/app/(app)/insights/page.tsx
index 64e16af..77164d5 100644
--- a/app/(app)/insights/page.tsx
+++ b/app/(app)/insights/page.tsx
@@ -5,32 +5,53 @@ import { prisma } from '@/lib/prisma'
 import { productAccessFilter } from '@/lib/product-access'
 import { getBurndownData } from '@/lib/insights/burndown'
 import { getSprintStatusBreakdown } from '@/lib/insights/sprint-status'
+import { getVerifyResultStats, getAlignmentTrend } from '@/lib/insights/verify-stats'
+import { getJobsPerDay } from '@/lib/insights/agent-throughput'
+import { getVelocity } from '@/lib/insights/velocity'
+import { getBacklogHealth } from '@/lib/insights/backlog-health'
 import { SprintInfoStrip } from './components/sprint-info-strip'
 import { BurndownChart } from './components/burndown-chart'
 import { SprintStatusDonut } from './components/sprint-status-donut'
+import { PlanQualityCard } from './components/plan-quality'
+import { AlignmentTrend } from './components/alignment-trend'
+import { AgentThroughputCard } from './components/agent-throughput'
+import { VelocityChart } from './components/velocity-chart'
+import { BacklogHealthCard } from './components/backlog-health'
 
 const DAY_MS = 86_400_000
 const ASSUMED_SPRINT_DAYS = 14
 
+interface InsightsPageProps {
+  searchParams: Promise<{ product?: string }>
+}
+
 function MissingDatesNotice({ productId, productName }: { productId: string; productName: string }) {
   return (
     <p className="text-muted-foreground text-sm">
       {productName} — sprint heeft geen datums.{' '}
-      <a
-        href={`/products/${productId}/sprint`}
-        className="underline text-primary"
-      >
+      <a href={`/products/${productId}/sprint`} className="underline text-primary">
         Stel datums in
       </a>
     </p>
   )
 }
 
-export default async function InsightsPage() {
+export default async function InsightsPage({ searchParams }: InsightsPageProps) {
   const session = await getIronSession<SessionData>(await cookies(), sessionOptions)
   const userId = session.userId!
+  const { product: filterProductId } = await searchParams
 
-  const [burndownSprints, statusBreakdown, activeSprints] = await Promise.all([
+  const [
+    burndownSprints,
+    statusBreakdown,
+    activeSprints,
+    productList,
+    verifyStats,
+    alignmentTrend,
+    jobsPerDay,
+    velocity,
+    backlogHealth,
+  ] = await Promise.all([
     getBurndownData(userId),
     getSprintStatusBreakdown(userId),
     prisma.sprint.findMany({
@@ -43,20 +64,21 @@ export default async function InsightsPage() {
         tasks: { select: { id: true } },
       },
     }),
+    prisma.product.findMany({
+      where: productAccessFilter(userId),
+      select: { id: true, name: true },
+      orderBy: { name: 'asc' },
+    }),
+    getVerifyResultStats(userId, 30),
+    getAlignmentTrend(userId, 5),
+    getJobsPerDay(userId, 14, filterProductId),
+    getVelocity(userId, 5),
+    getBacklogHealth(userId),
   ])
 
-  if (activeSprints.length === 0) {
-    return (
-      <div className="p-6 max-w-4xl mx-auto w-full">
-        <h1 className="text-xl font-medium text-foreground mb-6">Sprint Health</h1>
-        <p className="text-muted-foreground">
-          Geen active sprints — start er een via /products/[id]/sprint
-        </p>
-      </div>
-    )
-  }
-
-  const nowMs = new Date().getTime()
+  // Date.now is an impure call but used once per request — safe in a Server Component.
+  // eslint-disable-next-line react-hooks/purity
+  const nowMs = Date.now()
   const sprintInfos = activeSprints.map(s => ({
     sprintId: s.id,
     productId: s.product.id,
@@ -65,33 +87,72 @@ export default async function InsightsPage() {
     taskCount: s.tasks.length,
     daysLeft: ASSUMED_SPRINT_DAYS - Math.floor((nowMs - s.created_at.getTime()) / DAY_MS),
   }))
-
   const burndownMap = new Map(burndownSprints.map(b => [b.sprintId, b]))
 
   return (
-    <div className="p-6 space-y-6 max-w-4xl mx-auto w-full">
-      <h1 className="text-xl font-medium text-foreground">Sprint Health</h1>
+    <div className="p-6 space-y-8 max-w-6xl mx-auto w-full">
+      <h1 className="text-2xl font-semibold text-foreground">Insights</h1>
 
-      <SprintInfoStrip sprints={sprintInfos} />
+      {/* Sprint Health */}
+      <section className="space-y-3">
+        <h2 className="text-lg font-medium text-foreground">Sprint Health</h2>
+        {activeSprints.length === 0 ? (
+          <p className="text-muted-foreground text-sm">
+            Geen active sprints — start er een via /products/[id]/sprint.
+          </p>
+        ) : (
+          <>
+            <SprintInfoStrip sprints={sprintInfos} />
+            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+              <div className="space-y-4">
+                {sprintInfos.map(s => {
+                  const burndown = burndownMap.get(s.sprintId)
+                  if (!burndown || burndown.days.length === 0) {
+                    return (
+                      <MissingDatesNotice
+                        key={s.sprintId}
+                        productId={s.productId}
+                        productName={s.productName}
+                      />
+                    )
+                  }
+                  return <BurndownChart key={s.sprintId} sprint={burndown} />
+                })}
+              </div>
+              <SprintStatusDonut data={statusBreakdown} />
+            </div>
+          </>
+        )}
+      </section>
 
-      <div className="grid grid-cols-2 gap-4">
-        <div className="space-y-4">
-          {sprintInfos.map(s => {
-            const burndown = burndownMap.get(s.sprintId)
-            if (!burndown || burndown.days.length === 0) {
-              return (
-                <MissingDatesNotice
-                  key={s.sprintId}
-                  productId={s.productId}
-                  productName={s.productName}
-                />
-              )
-            }
-            return <BurndownChart key={s.sprintId} sprint={burndown} />
-          })}
-        </div>
-        <SprintStatusDonut data={statusBreakdown} />
-      </div>
+      {/* Plan-quality */}
+      <section className="space-y-3">
+        <h2 className="text-lg font-medium text-foreground">Plan-quality</h2>
+        <PlanQualityCard stats={verifyStats} nowMs={nowMs} />
+        {alignmentTrend.length > 0 && <AlignmentTrend trend={alignmentTrend} />}
+      </section>
+
+      {/* Agent throughput */}
+      <section className="space-y-3">
+        <h2 className="text-lg font-medium text-foreground">Agent throughput</h2>
+        <AgentThroughputCard
+          data={jobsPerDay}
+          productList={productList}
+          currentProductId={filterProductId}
+        />
+      </section>
+
+      {/* Velocity */}
+      <section className="space-y-3">
+        <h2 className="text-lg font-medium text-foreground">Velocity</h2>
+        <VelocityChart data={velocity} />
+      </section>
+
+      {/* Backlog health */}
+      <section className="space-y-3">
+        <h2 className="text-lg font-medium text-foreground">Backlog health</h2>
+        <BacklogHealthCard data={backlogHealth} />
+      </section>
     </div>
   )
 }

From ced0a8a4c0212174ecca91c9965442eaa4ff9560 Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 17:45:19 +0200
Subject: [PATCH 07/17] Verify-gate uitbreiden: DIVERGENT/PARTIAL vereist
 agent-acknowledgement (#53)

* feat(schema): add Task.verify_required enum (ALIGNED / ALIGNED_OR_PARTIAL / ANY)

Adds VerifyRequired enum and verify_required field (default ALIGNED_OR_PARTIAL)
to the Task model. Also declares the claude_jobs_status_finished_at_idx index
in the schema to match the live DB. Applied via db execute + migrate resolve.

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

* feat(ui): add verify_required select to TaskDetailDialog

SoloTask interface, solo page mapping, solo store, PATCH route handler
and TaskDetailDialog all updated to expose the three-level verify gate
(ALIGNED / ALIGNED_OR_PARTIAL / ANY) as a native select. Disabled with
DemoTooltip in demo mode.

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../solo/task-detail-dialog.test.tsx          |  1 +
 __tests__/stores/solo-store-realtime.test.ts  |  1 +
 app/(app)/products/[id]/solo/page.tsx         |  1 +
 app/api/tasks/[id]/route.ts                   | 18 +++++--
 components/solo/solo-board.tsx                |  1 +
 components/solo/task-detail-dialog.tsx        | 52 ++++++++++++++++++-
 .../migration.sql                             |  5 ++
 prisma/schema.prisma                          | 12 ++++-
 stores/solo-store.ts                          |  4 ++
 9 files changed, 87 insertions(+), 8 deletions(-)
 create mode 100644 prisma/migrations/20260502153500_add_task_verify_required/migration.sql

diff --git a/__tests__/components/solo/task-detail-dialog.test.tsx b/__tests__/components/solo/task-detail-dialog.test.tsx
index 0a6d34f..3b767fc 100644
--- a/__tests__/components/solo/task-detail-dialog.test.tsx
+++ b/__tests__/components/solo/task-detail-dialog.test.tsx
@@ -60,6 +60,7 @@ const baseTask: SoloTask = {
   sort_order: 1,
   status: 'TO_DO',
   verify_only: false,
+  verify_required: 'ALIGNED_OR_PARTIAL',
   story_id: 'story-1',
   story_code: 'ST-100',
   story_title: 'Test Story',
diff --git a/__tests__/stores/solo-store-realtime.test.ts b/__tests__/stores/solo-store-realtime.test.ts
index b2f42cf..f61a7f8 100644
--- a/__tests__/stores/solo-store-realtime.test.ts
+++ b/__tests__/stores/solo-store-realtime.test.ts
@@ -12,6 +12,7 @@ const baseTask = (id: string, overrides: Partial<SoloTask> = {}): SoloTask => ({
   sort_order: 1,
   status: 'TO_DO',
   verify_only: false,
+  verify_required: 'ALIGNED_OR_PARTIAL',
   story_id: 'story-1',
   story_code: 'ST-100',
   story_title: 'Original Story',
diff --git a/app/(app)/products/[id]/solo/page.tsx b/app/(app)/products/[id]/solo/page.tsx
index 3c9cf86..3ad8a25 100644
--- a/app/(app)/products/[id]/solo/page.tsx
+++ b/app/(app)/products/[id]/solo/page.tsx
@@ -83,6 +83,7 @@ export default async function SoloProductPage({ params }: Props) {
       sort_order: t.sort_order,
       status: t.status as SoloTask['status'],
       verify_only: t.verify_only,
+      verify_required: t.verify_required as SoloTask['verify_required'],
       story_id: t.story.id,
       story_code: t.story.code,
       story_title: t.story.title,
diff --git a/app/api/tasks/[id]/route.ts b/app/api/tasks/[id]/route.ts
index dd38055..b80a811 100644
--- a/app/api/tasks/[id]/route.ts
+++ b/app/api/tasks/[id]/route.ts
@@ -10,18 +10,22 @@ import { updateTaskStatusWithStoryPromotion } from '@/lib/tasks-status-update'
 // drive tasks into a state the shared UI can't display.
 const PATCHABLE_TASK_STATUS = TASK_STATUS_API_VALUES.filter((s) => s !== 'review')
 
+const VERIFY_REQUIRED_VALUES = ['ALIGNED', 'ALIGNED_OR_PARTIAL', 'ANY'] as const
+
 const patchSchema = z
   .object({
     status: z.enum(PATCHABLE_TASK_STATUS as [string, ...string[]]).optional(),
     implementation_plan: z.string().optional(),
     verify_only: z.boolean().optional(),
+    verify_required: z.enum(VERIFY_REQUIRED_VALUES).optional(),
   })
   .refine(
     (data) =>
       data.status !== undefined ||
       data.implementation_plan !== undefined ||
-      data.verify_only !== undefined,
-    { message: 'Geef minimaal status, implementation_plan of verify_only mee' },
+      data.verify_only !== undefined ||
+      data.verify_required !== undefined,
+    { message: 'Geef minimaal status, implementation_plan, verify_only of verify_required mee' },
   )
 
 export async function PATCH(
@@ -88,19 +92,21 @@ export async function PATCH(
     }
   }
 
-  // Combine simple field writes (plan, verify_only) into one update call
-  const simpleData: { implementation_plan?: string; verify_only?: boolean } = {}
+  // Combine simple field writes (plan, verify_only, verify_required) into one update call
+  const simpleData: { implementation_plan?: string; verify_only?: boolean; verify_required?: typeof VERIFY_REQUIRED_VALUES[number] } = {}
   if (parsed.data.implementation_plan !== undefined)
     simpleData.implementation_plan = parsed.data.implementation_plan
   if (parsed.data.verify_only !== undefined)
     simpleData.verify_only = parsed.data.verify_only
+  if (parsed.data.verify_required !== undefined)
+    simpleData.verify_required = parsed.data.verify_required
 
   const updated = await prisma.$transaction(async (tx) => {
     const simpleUpdate = Object.keys(simpleData).length > 0
       ? await tx.task.update({
           where: { id },
           data: simpleData,
-          select: { id: true, status: true, implementation_plan: true, verify_only: true },
+          select: { id: true, status: true, implementation_plan: true, verify_only: true, verify_required: true },
         })
       : null
 
@@ -111,6 +117,7 @@ export async function PATCH(
         status: result.task.status,
         implementation_plan: result.task.implementation_plan,
         verify_only: simpleUpdate?.verify_only,
+        verify_required: simpleUpdate?.verify_required,
       }
     }
 
@@ -125,5 +132,6 @@ export async function PATCH(
     status: taskStatusToApi(updated.status),
     implementation_plan: updated.implementation_plan,
     ...(updated.verify_only !== undefined && { verify_only: updated.verify_only }),
+    ...(updated.verify_required !== undefined && { verify_required: updated.verify_required }),
   })
 }
diff --git a/components/solo/solo-board.tsx b/components/solo/solo-board.tsx
index 4524d9b..54ee48e 100644
--- a/components/solo/solo-board.tsx
+++ b/components/solo/solo-board.tsx
@@ -26,6 +26,7 @@ export interface SoloTask {
   sort_order: number
   status: 'TO_DO' | 'IN_PROGRESS' | 'REVIEW' | 'DONE'
   verify_only: boolean
+  verify_required: 'ALIGNED' | 'ALIGNED_OR_PARTIAL' | 'ANY'
   story_id: string
   story_code: string | null
   story_title: string
diff --git a/components/solo/task-detail-dialog.tsx b/components/solo/task-detail-dialog.tsx
index 953c614..a7f3147 100644
--- a/components/solo/task-detail-dialog.tsx
+++ b/components/solo/task-detail-dialog.tsx
@@ -55,16 +55,24 @@ const VERIFY_RESULT_CONFIG: Record<string, { label: string; className: string }>
 
 type SaveState = 'idle' | 'saving' | 'saved'
 
+const VERIFY_REQUIRED_LABELS: Record<string, string> = {
+  ALIGNED: 'Strikt — alleen ALIGNED',
+  ALIGNED_OR_PARTIAL: 'Standaard — ALIGNED of PARTIAL met uitleg',
+  ANY: 'Vrij — geen verify-eis',
+}
+
 function TaskDetailContent({ task, productId, isDemo, repoUrl, onClose }: TaskDetailContentProps) {
-  const { updatePlan, updateVerifyOnly } = useSoloStore()
+  const { updatePlan, updateVerifyOnly, updateVerifyRequired } = useSoloStore()
   const job = useSoloStore(s => s.claudeJobsByTaskId[task.id])
   const connectedWorkers = useSoloStore(s => s.connectedWorkers)
   const [localPlan, setLocalPlan] = useState(task.implementation_plan ?? '')
   const [localVerifyOnly, setLocalVerifyOnly] = useState(task.verify_only)
+  const [localVerifyRequired, setLocalVerifyRequired] = useState(task.verify_required)
   const [saveState, setSaveState] = useState<SaveState>('idle')
   const [, startTransition] = useTransition()
   const [jobPending, startJobTransition] = useTransition()
   const [verifyOnlyPending, startVerifyOnlyTransition] = useTransition()
+  const [verifyRequiredPending, startVerifyRequiredTransition] = useTransition()
   const fadeTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
   const savedPlanRef = useRef(task.implementation_plan ?? '')
 
@@ -145,6 +153,32 @@ function TaskDetailContent({ task, productId, isDemo, repoUrl, onClose }: TaskDe
     })
   }
 
+  function handleVerifyRequiredChange(e: React.ChangeEvent<HTMLSelectElement>) {
+    if (isDemo) return
+    const newValue = e.target.value as typeof localVerifyRequired
+    const prevValue = localVerifyRequired
+    setLocalVerifyRequired(newValue)
+    startVerifyRequiredTransition(async () => {
+      try {
+        const res = await fetch(`/api/tasks/${task.id}`, {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          credentials: 'include',
+          body: JSON.stringify({ verify_required: newValue }),
+        })
+        if (!res.ok) {
+          setLocalVerifyRequired(prevValue)
+          toast.error('Verify-required bijwerken mislukt')
+          return
+        }
+        updateVerifyRequired(task.id, newValue)
+      } catch {
+        setLocalVerifyRequired(prevValue)
+        toast.error('Verify-required bijwerken mislukt')
+      }
+    })
+  }
+
   return (
     <>
       <DialogHeader>
@@ -220,6 +254,22 @@ function TaskDetailContent({ task, productId, isDemo, repoUrl, onClose }: TaskDe
         <span className="text-xs text-muted-foreground">Alleen verifiëren (niet implementeren)</span>
       </div>
 
+      <div className="flex items-center gap-2">
+        <span className="text-xs text-muted-foreground shrink-0">Verify-gate:</span>
+        <DemoTooltip show={isDemo}>
+          <select
+            value={localVerifyRequired}
+            onChange={handleVerifyRequiredChange}
+            disabled={isDemo || verifyRequiredPending}
+            className="text-xs rounded-md border border-border bg-surface-container px-2 py-1 text-foreground focus:outline-none focus:ring-1 focus:ring-primary disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            {(['ALIGNED', 'ALIGNED_OR_PARTIAL', 'ANY'] as const).map(v => (
+              <option key={v} value={v}>{VERIFY_REQUIRED_LABELS[v]}</option>
+            ))}
+          </select>
+        </DemoTooltip>
+      </div>
+
       <div className="-mx-4 -mb-4 flex flex-wrap items-center gap-2 border-t bg-muted/50 px-4 py-3 rounded-b-xl">
         <Link
           href={`/products/${productId}/sprint/planning`}
diff --git a/prisma/migrations/20260502153500_add_task_verify_required/migration.sql b/prisma/migrations/20260502153500_add_task_verify_required/migration.sql
new file mode 100644
index 0000000..003e798
--- /dev/null
+++ b/prisma/migrations/20260502153500_add_task_verify_required/migration.sql
@@ -0,0 +1,5 @@
+-- CreateEnum
+CREATE TYPE "VerifyRequired" AS ENUM ('ALIGNED', 'ALIGNED_OR_PARTIAL', 'ANY');
+
+-- AlterTable
+ALTER TABLE "tasks" ADD COLUMN     "verify_required" "VerifyRequired" NOT NULL DEFAULT 'ALIGNED_OR_PARTIAL';
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 4beb4f4..1c9c121 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -45,6 +45,12 @@ enum VerifyResult {
   DIVERGENT
 }
 
+enum VerifyRequired {
+  ALIGNED
+  ALIGNED_OR_PARTIAL
+  ANY
+}
+
 enum TaskStatus {
   TO_DO
   IN_PROGRESS
@@ -246,8 +252,9 @@ model Task {
   priority            Int
   sort_order          Float
   status              TaskStatus @default(TO_DO)
-  verify_only         Boolean    @default(false)
-  created_at          DateTime   @default(now())
+  verify_only         Boolean        @default(false)
+  verify_required     VerifyRequired @default(ALIGNED_OR_PARTIAL)
+  created_at          DateTime       @default(now())
   updated_at          DateTime   @updatedAt
   claude_questions    ClaudeQuestion[]
   claude_jobs         ClaudeJob[]
@@ -285,6 +292,7 @@ model ClaudeJob {
   @@index([user_id, status])
   @@index([task_id, status])
   @@index([status, claimed_at])
+  @@index([status, finished_at])
   @@map("claude_jobs")
 }
 
diff --git a/stores/solo-store.ts b/stores/solo-store.ts
index 7c14661..592976e 100644
--- a/stores/solo-store.ts
+++ b/stores/solo-store.ts
@@ -69,6 +69,7 @@ interface SoloStore {
   rollback: (taskId: string, prevStatus: TaskStatus) => void
   updatePlan: (taskId: string, plan: string | null) => void
   updateVerifyOnly: (taskId: string, value: boolean) => void
+  updateVerifyRequired: (taskId: string, value: 'ALIGNED' | 'ALIGNED_OR_PARTIAL' | 'ANY') => void
 
   markPending: (taskId: string) => void
   clearPending: (taskId: string) => void
@@ -112,6 +113,9 @@ export const useSoloStore = create<SoloStore>((set, get) => ({
   updateVerifyOnly: (taskId, value) =>
     set((s) => ({ tasks: { ...s.tasks, [taskId]: { ...s.tasks[taskId], verify_only: value } } })),
 
+  updateVerifyRequired: (taskId, value) =>
+    set((s) => ({ tasks: { ...s.tasks, [taskId]: { ...s.tasks[taskId], verify_required: value } } })),
+
   markPending: (taskId) =>
     set((s) => {
       if (s.pendingOps.has(taskId)) return s

From bae0d478eacbd42250f9a40209fb3108277e4a0d Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 17:45:37 +0200
Subject: [PATCH 08/17] docs: add story-with-ui-component pattern + CLAUDE.md
 reference (#51)

Documents the mandatory 3-task pattern (Helper / Component / Integration)
for stories introducing UI components. Cites the 2026-05-02 Velocity story
as the anti-pattern and the Foundation Sprint Health story as the blueprint.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md                                |  1 +
 docs/patterns/story-with-ui-component.md | 64 ++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 docs/patterns/story-with-ui-component.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 010083b..621104c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,6 +112,7 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
 | QR-pairing (unauth-SSE + pre-auth cookie) | `docs/patterns/qr-login.md` |
 | Bidirectionele async-comms MCP-agent ↔ user | `docs/patterns/claude-question-channel.md` |
 | **Entity Dialog (verplicht voor élke create/edit/detail-dialog)** | `docs/patterns/dialog.md` — bron-of-truth; per entiteit één profile-doc (bv. `docs/scrum4me-task-dialog.md`) |
+| **Story met UI-component (verplicht 3-task-patroon: Helper / Component / Integration)** | `docs/patterns/story-with-ui-component.md` — elke story met een `*-component.tsx` vereist een afsluitende Integration-task die de component in `page.tsx` wirt |
 | Status-enum mapping (DB ↔ API) | `lib/task-status.ts` |
 | Client/server module-boundary | `*-server.ts` bevat DB-calls of node-only deps; `*.ts` is pure (client-safe). Nooit `import { ... } from '@/lib/foo-server'` in een client-component, anders krijg je `Module not found: 'dns'`/`'pg'`-style runtime fouten |
 
diff --git a/docs/patterns/story-with-ui-component.md b/docs/patterns/story-with-ui-component.md
new file mode 100644
index 0000000..ea0ad82
--- /dev/null
+++ b/docs/patterns/story-with-ui-component.md
@@ -0,0 +1,64 @@
+# Patroon: Story met UI-component
+
+## Probleemstelling
+
+Zonder een afsluitende Integration-task leverden agent-batches helpers en components die nooit in de UI verschenen. De Velocity-story (`cmomu4xpq001obortc9enpvfa`) van 2 mei 2026 is het concrete incident: Helper (`getVelocity`) en Component (`VelocityChart`) werden gebouwd en getest, maar zonder Integration-task bleef de `/insights`-pagina leeg.
+
+## Verplicht patroon
+
+Elke story die een `*-component.tsx` introduceert **moet** minimaal drie tasks bevatten:
+
+| # | Type | Doel | Bestand |
+|---|---|---|---|
+| 1 | **Helper** | Data-aggregatie of business-logic | `lib/<domain>/<helper>.ts` |
+| 2 | **Component** | Presentational layer | `app/.../<component>.tsx` |
+| 3 | **Integration** | Wire component in page + verify renders | `app/.../<route>/page.tsx` |
+
+De Integration-task heeft `verify_required: ALIGNED` — de agent-verify moet de page.tsx in de diff terugzien voordat de job als `done` wordt geaccepteerd.
+
+## Blueprint: Foundation Sprint Health-story
+
+De story `cmomu0txi0016borthlautjjp` ("Foundation: route, recharts, sprint-dates migration, chart-colors helper") volgt dit patroon correct:
+
+- **Tasks 1–3** — Helper-tasks (sprint-dates migration, chart-colors, route scaffolding)
+- **Task 4** — "Sprint-info-strip + integratie in /insights page" — sluit de loop: component wordt in `page.tsx` geïmporteerd en gerenderd
+
+Gebruik deze story als blueprint bij het aanmaken van nieuwe PBI's met UI-componenten.
+
+## Anti-patroon
+
+De Velocity-story had alleen Helper + Component. De Integration-task ontbrak:
+
+```
+✅ cmomu54pw001pbortedjhg2l8  Helper: getVelocity
+✅ cmomu5bht001qbortlcq15arc  Component: VelocityChart
+❌ (ontbreekt)                Integration: wire VelocityChart into /insights page
+```
+
+Resultaat: de component bestaat en compileert, maar is nergens te zien.
+
+## Reviewchecklist bij PBI-creatie
+
+Voordat een PBI met UI-features naar de backlog gaat:
+
+- [ ] Elke story die een `*-component.tsx` introduceert heeft een Integration-task
+- [ ] Integration-task raakt minimaal `app/(app)/<route>/page.tsx`
+- [ ] Integration-task heeft `verify_required: ALIGNED` (of een equivalent verify-gate)
+- [ ] Integration-task title volgt het formaat: `Integration: wire <ComponentName> into <route>`
+
+## Template (kopieer bij elke nieuwe UI-story)
+
+```
+Task 1 — Helper: <beschrijving data-aggregatie>
+  Bestand: lib/<domain>/<helper>.ts
+  Tests: minimaal 3 scenario's
+
+Task 2 — Component: <beschrijving component>
+  Bestand: app/(app)/<route>/components/<component>.tsx
+  Tests: TypeScript + render-smoke
+
+Task 3 — Integration: wire <ComponentName> into /<route> page
+  Bestanden: app/(app)/<route>/page.tsx
+  verify_required: ALIGNED
+  Done when: component verschijnt in de browser zonder empty-state op dev-data
+```

From e02c6ff9d9eef142cd72011d46f565a10e4b23ac Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 17:45:51 +0200
Subject: [PATCH 09/17] docs(CLAUDE.md): add Integration-task smoke-test
 section (#52)

Documents the bash curl-check recipe agents must run before marking an
Integration-task done: start dev server, curl the route, grep for expected
sections, fail if any are missing.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 621104c..9726c82 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -118,6 +118,37 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
 
 ---
 
+## Integration-task verificatie (smoke-test)
+
+Voor stories met `*-component.tsx`: de Integration-task moet vóór
+`update_job_status(done)` een smoke-test draaien op de daadwerkelijke
+HTML-render:
+
+```bash
+# In de worktree — pas ROUTE en SECTIONS aan per story
+ROUTE="/insights"
+SECTIONS=("Sprint Health" "Plan-quality" "Agent throughput" "Velocity" "Backlog health")
+
+npm run dev > /tmp/dev.log 2>&1 &
+DEV_PID=$!
+sleep 8  # wacht tot Next.js compiled
+
+curl -s http://localhost:3000${ROUTE} > /tmp/page.html
+
+SMOKE_FAIL=
+for section in "${SECTIONS[@]}"; do
+  grep -q "$section" /tmp/page.html || { echo "MISSING: $section"; SMOKE_FAIL=1; }
+done
+
+kill $DEV_PID
+[ -z "$SMOKE_FAIL" ]  # exit-code 1 als iets miste
+```
+
+Als de smoke-test faalt: pas `page.tsx` aan zodat alle secties renderen, herhaal.
+Markeer Integration-task DONE pas wanneer alle verwachte sections in de HTML zitten.
+
+---
+
 ## Env vars
 
 ```bash

From a754acf13ba68c411d73060537ef356037230065 Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 18:02:01 +0200
Subject: [PATCH 10/17] =?UTF-8?q?feat(schema):=20Task.repo=5Furl=20?=
 =?UTF-8?q?=E2=80=94=20cross-repo=20override=20for=20agent=20worktree=20(#?=
 =?UTF-8?q?54)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a task targets a different repo than its parent product (e.g. an
MCP-server task tracked under the main product's PBI), product.repo_url
points to the wrong place. Result observed in story 'Verify-gate'
batch (2 May): agent's gate-task work failed to push because product
was Scrum4Me but the code lives in scrum4me-mcp.

Add optional `Task.repo_url` (TEXT, nullable). scrum4me-mcp's
`resolveRepoRoot` will read this in a follow-up PR — null falls back
to product.repo_url, preserving current behaviour for the 99% case.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../20260502175000_add_task_repo_url/migration.sql           | 4 ++++
 prisma/schema.prisma                                         | 5 +++++
 2 files changed, 9 insertions(+)
 create mode 100644 prisma/migrations/20260502175000_add_task_repo_url/migration.sql

diff --git a/prisma/migrations/20260502175000_add_task_repo_url/migration.sql b/prisma/migrations/20260502175000_add_task_repo_url/migration.sql
new file mode 100644
index 0000000..779dc9f
--- /dev/null
+++ b/prisma/migrations/20260502175000_add_task_repo_url/migration.sql
@@ -0,0 +1,4 @@
+-- AlterTable: optional repo_url override on Task. Used when an MCP-server
+-- task is tracked under a different product's PBI (cross-repo support).
+-- Falls back to product.repo_url when NULL.
+ALTER TABLE "tasks" ADD COLUMN "repo_url" TEXT;
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 1c9c121..599cdc2 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -254,6 +254,11 @@ model Task {
   status              TaskStatus @default(TO_DO)
   verify_only         Boolean        @default(false)
   verify_required     VerifyRequired @default(ALIGNED_OR_PARTIAL)
+  // Override product.repo_url for branch/worktree/push purposes. Set when
+  // a task targets a different repo than its parent product (e.g. an
+  // MCP-server task tracked under the main product's PBI). Falls back to
+  // product.repo_url when null.
+  repo_url            String?
   created_at          DateTime       @default(now())
   updated_at          DateTime   @updatedAt
   claude_questions    ClaudeQuestion[]

From b2427fd07b3aba46e4b24438190c5f1582305833 Mon Sep 17 00:00:00 2001
From: janpeter visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 18:12:35 +0200
Subject: [PATCH 11/17] fix(insights): skip sprints with null completed_at in
 velocity

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 lib/insights/velocity.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/insights/velocity.ts b/lib/insights/velocity.ts
index 528b321..7cf123e 100644
--- a/lib/insights/velocity.ts
+++ b/lib/insights/velocity.ts
@@ -33,7 +33,7 @@ export async function getVelocity(userId: string, sprintsBack = 5): Promise<Velo
   })
 
   // Reverse to chronological order (oldest first, for x-axis)
-  const chronological = [...sprints].reverse()
+  const chronological = [...sprints].filter(s => s.completed_at != null).reverse()
 
   const result: VelocitySprint[] = chronological.map(sprint => ({
     sprintId: sprint.id,
@@ -41,7 +41,7 @@ export async function getVelocity(userId: string, sprintsBack = 5): Promise<Velo
     productId: sprint.product.id,
     productName: sprint.product.name,
     doneCount: sprint.tasks.filter(t => t.status === 'DONE').length,
-    completedAt: sprint.completed_at!.toISOString(),
+    completedAt: sprint.completed_at.toISOString(),
   }))
 
   const seen = new Set<string>()

From a11b4709a7680d6eee7a48660fae7cbe0eca8dcb Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 20:21:30 +0200
Subject: [PATCH 12/17] fix(insights): narrow Sprint.completed_at to Date in
 velocity.ts (#56)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Vercel build was failing with TS18047 — `sprint.completed_at` is
possibly `null`. The earlier `.filter(s => s.completed_at != null)`
runtime-filtered the nulls out but did NOT narrow the element type;
TypeScript still saw `Date | null` on the result.

Add a user-defined type guard `(s): s is SprintWithCompletedAt =>` so
the narrowed array carries `completed_at: Date`. No runtime change.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 lib/insights/velocity.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/lib/insights/velocity.ts b/lib/insights/velocity.ts
index 7cf123e..c01c45e 100644
--- a/lib/insights/velocity.ts
+++ b/lib/insights/velocity.ts
@@ -33,7 +33,12 @@ export async function getVelocity(userId: string, sprintsBack = 5): Promise<Velo
   })
 
   // Reverse to chronological order (oldest first, for x-axis)
-  const chronological = [...sprints].filter(s => s.completed_at != null).reverse()
+  // Type-guard so the narrowed array carries `completed_at: Date` (not Date | null).
+  // A `.filter(s => s.completed_at != null)` alone does NOT narrow the element type.
+  type SprintWithCompletedAt = (typeof sprints)[number] & { completed_at: Date }
+  const chronological = [...sprints]
+    .filter((s): s is SprintWithCompletedAt => s.completed_at != null)
+    .reverse()
 
   const result: VelocitySprint[] = chronological.map(sprint => ({
     sprintId: sprint.id,

From 311f413e24be334dd991e9202899d9129c6e39d2 Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 20:24:46 +0200
Subject: [PATCH 13/17] Twee markdown-bestanden in docs/docker-smoke/ aanmaken
 (#55)

* docs: add docs/docker-smoke/2-mei-task-1.md smoke test file

* docs: add docs/docker-smoke/2-mei-task-2.md smoke test file
---
 docs/docker-smoke/2-mei-task-1.md | 5 +++++
 docs/docker-smoke/2-mei-task-2.md | 6 ++++++
 2 files changed, 11 insertions(+)
 create mode 100644 docs/docker-smoke/2-mei-task-1.md
 create mode 100644 docs/docker-smoke/2-mei-task-2.md

diff --git a/docs/docker-smoke/2-mei-task-1.md b/docs/docker-smoke/2-mei-task-1.md
new file mode 100644
index 0000000..bba1393
--- /dev/null
+++ b/docs/docker-smoke/2-mei-task-1.md
@@ -0,0 +1,5 @@
+# Docker smoke test — task 1
+
+Created by the agent running in a Docker container on the NAS.
+Validates that the worktree-isolation + branch-per-story flow works
+end-to-end from the containerised environment.
diff --git a/docs/docker-smoke/2-mei-task-2.md b/docs/docker-smoke/2-mei-task-2.md
new file mode 100644
index 0000000..b7e3269
--- /dev/null
+++ b/docs/docker-smoke/2-mei-task-2.md
@@ -0,0 +1,6 @@
+# Docker smoke test — task 2
+
+Second sub-task in the same story. The agent should land this commit
+on the SAME `feat/story-<id>` branch as task 1 (sibling-reuse), and
+the existing PR should accumulate this commit instead of opening a
+new one.

From 6375ed6949fc31f7e4813e2e70136e5334e6392a Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 21:09:37 +0200
Subject: [PATCH 14/17] End-to-end smoke-test: PBI/Story/Task verschijnen
 zonder refresh (#57)

* fix(backlog-store): make INSERT handlers idempotent to prevent duplicate entries on duplicate SSE-events

* docs(realtime-smoke): add manual smoke-checklist for PBI/Story/Task realtime end-to-end verification

---------

Co-authored-by: Scrum4Me Agent <30029041+madhura68@users.noreply.github.com>
---
 __tests__/realtime/payload-contract.test.ts | 160 ++++++++++++++++++++
 docs/realtime-smoke.md                      |  79 ++++++++++
 stores/backlog-store.ts                     |   9 +-
 3 files changed, 245 insertions(+), 3 deletions(-)
 create mode 100644 __tests__/realtime/payload-contract.test.ts
 create mode 100644 docs/realtime-smoke.md

diff --git a/__tests__/realtime/payload-contract.test.ts b/__tests__/realtime/payload-contract.test.ts
new file mode 100644
index 0000000..b36bc09
--- /dev/null
+++ b/__tests__/realtime/payload-contract.test.ts
@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useBacklogStore } from '@/stores/backlog-store'
+import type { BacklogPbi, BacklogStory, BacklogTask } from '@/stores/backlog-store'
+
+const PBI: BacklogPbi = {
+  id: 'pbi-1',
+  code: 'PBI-1',
+  title: 'Realtime PBI',
+  priority: 2,
+  description: 'desc',
+  created_at: new Date('2024-01-01T00:00:00Z'),
+  status: 'ready',
+}
+
+const STORY: BacklogStory = {
+  id: 'story-1',
+  code: 'ST-1',
+  title: 'Realtime story',
+  description: null,
+  acceptance_criteria: null,
+  priority: 2,
+  status: 'OPEN',
+  pbi_id: 'pbi-1',
+  created_at: new Date('2024-01-01T00:00:00Z'),
+}
+
+const TASK: BacklogTask = {
+  id: 'task-1',
+  title: 'Realtime task',
+  description: null,
+  priority: 2,
+  status: 'TO_DO',
+  sort_order: 1,
+  story_id: 'story-1',
+  created_at: new Date('2024-01-01T00:00:00Z'),
+}
+
+beforeEach(() => {
+  useBacklogStore.setState({ pbis: [], storiesByPbi: {}, tasksByStory: {} })
+})
+
+// ---------------------------------------------------------------------------
+// PBI
+// ---------------------------------------------------------------------------
+
+describe('PBI payload contract', () => {
+  it('INSERT: entity appears in pbis with correct title and status', () => {
+    useBacklogStore.getState().applyChange('pbi', 'I', { ...PBI })
+    const state = useBacklogStore.getState()
+    expect(state.pbis).toHaveLength(1)
+    expect(state.pbis[0].id).toBe('pbi-1')
+    expect(state.pbis[0].title).toBe('Realtime PBI')
+    expect(state.pbis[0].status).toBe('ready')
+  })
+
+  it('INSERT is idempotent: duplicate SSE-event does not add a second entry', () => {
+    useBacklogStore.getState().applyChange('pbi', 'I', { ...PBI })
+    useBacklogStore.getState().applyChange('pbi', 'I', { ...PBI })
+    expect(useBacklogStore.getState().pbis).toHaveLength(1)
+  })
+
+  it('UPDATE: changed_fields partial merges into existing entity', () => {
+    useBacklogStore.setState({ pbis: [{ ...PBI }], storiesByPbi: {}, tasksByStory: {} })
+    useBacklogStore.getState().applyChange('pbi', 'U', { id: 'pbi-1', title: 'Updated PBI', status: 'in_sprint' as const })
+    const pbi = useBacklogStore.getState().pbis[0]
+    expect(pbi.title).toBe('Updated PBI')
+    expect(pbi.status).toBe('in_sprint')
+    expect(pbi.priority).toBe(2) // unchanged field retained
+  })
+
+  it('DELETE: entity is removed from pbis', () => {
+    useBacklogStore.setState({ pbis: [{ ...PBI }], storiesByPbi: {}, tasksByStory: {} })
+    useBacklogStore.getState().applyChange('pbi', 'D', { id: 'pbi-1' })
+    expect(useBacklogStore.getState().pbis).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Story
+// ---------------------------------------------------------------------------
+
+describe('Story payload contract', () => {
+  it('INSERT: entity appears in storiesByPbi[pbi_id] with correct title and status', () => {
+    useBacklogStore.setState({ pbis: [], storiesByPbi: { 'pbi-1': [] }, tasksByStory: {} })
+    useBacklogStore.getState().applyChange('story', 'I', { ...STORY })
+    const bucket = useBacklogStore.getState().storiesByPbi['pbi-1']
+    expect(bucket).toHaveLength(1)
+    expect(bucket[0].id).toBe('story-1')
+    expect(bucket[0].title).toBe('Realtime story')
+    expect(bucket[0].status).toBe('OPEN')
+  })
+
+  it('INSERT: creates bucket when pbi_id was not yet in storiesByPbi', () => {
+    useBacklogStore.getState().applyChange('story', 'I', { ...STORY })
+    expect(useBacklogStore.getState().storiesByPbi['pbi-1']).toHaveLength(1)
+  })
+
+  it('INSERT is idempotent: duplicate SSE-event does not add a second entry', () => {
+    useBacklogStore.getState().applyChange('story', 'I', { ...STORY })
+    useBacklogStore.getState().applyChange('story', 'I', { ...STORY })
+    expect(useBacklogStore.getState().storiesByPbi['pbi-1']).toHaveLength(1)
+  })
+
+  it('UPDATE: changed_fields partial merges into existing story', () => {
+    useBacklogStore.setState({ pbis: [], storiesByPbi: { 'pbi-1': [{ ...STORY }] }, tasksByStory: {} })
+    useBacklogStore.getState().applyChange('story', 'U', { id: 'story-1', title: 'Updated story', status: 'IN_SPRINT' })
+    const story = useBacklogStore.getState().storiesByPbi['pbi-1'][0]
+    expect(story.title).toBe('Updated story')
+    expect(story.status).toBe('IN_SPRINT')
+    expect(story.priority).toBe(2) // unchanged field retained
+  })
+
+  it('DELETE: entity is removed from its pbi bucket', () => {
+    useBacklogStore.setState({ pbis: [], storiesByPbi: { 'pbi-1': [{ ...STORY }] }, tasksByStory: {} })
+    useBacklogStore.getState().applyChange('story', 'D', { id: 'story-1' })
+    expect(useBacklogStore.getState().storiesByPbi['pbi-1']).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Task
+// ---------------------------------------------------------------------------
+
+describe('Task payload contract', () => {
+  it('INSERT: entity appears in tasksByStory[story_id] with correct title and status', () => {
+    useBacklogStore.setState({ pbis: [], storiesByPbi: {}, tasksByStory: { 'story-1': [] } })
+    useBacklogStore.getState().applyChange('task', 'I', { ...TASK })
+    const bucket = useBacklogStore.getState().tasksByStory['story-1']
+    expect(bucket).toHaveLength(1)
+    expect(bucket[0].id).toBe('task-1')
+    expect(bucket[0].title).toBe('Realtime task')
+    expect(bucket[0].status).toBe('TO_DO')
+  })
+
+  it('INSERT: creates bucket when story_id was not yet in tasksByStory', () => {
+    useBacklogStore.getState().applyChange('task', 'I', { ...TASK })
+    expect(useBacklogStore.getState().tasksByStory['story-1']).toHaveLength(1)
+  })
+
+  it('INSERT is idempotent: duplicate SSE-event does not add a second entry', () => {
+    useBacklogStore.getState().applyChange('task', 'I', { ...TASK })
+    useBacklogStore.getState().applyChange('task', 'I', { ...TASK })
+    expect(useBacklogStore.getState().tasksByStory['story-1']).toHaveLength(1)
+  })
+
+  it('UPDATE: changed_fields partial merges into existing task', () => {
+    useBacklogStore.setState({ pbis: [], storiesByPbi: {}, tasksByStory: { 'story-1': [{ ...TASK }] } })
+    useBacklogStore.getState().applyChange('task', 'U', { id: 'task-1', title: 'Updated task', status: 'IN_PROGRESS' })
+    const task = useBacklogStore.getState().tasksByStory['story-1'][0]
+    expect(task.title).toBe('Updated task')
+    expect(task.status).toBe('IN_PROGRESS')
+    expect(task.sort_order).toBe(1) // unchanged field retained
+  })
+
+  it('DELETE: entity is removed from its story bucket', () => {
+    useBacklogStore.setState({ pbis: [], storiesByPbi: {}, tasksByStory: { 'story-1': [{ ...TASK }] } })
+    useBacklogStore.getState().applyChange('task', 'D', { id: 'task-1' })
+    expect(useBacklogStore.getState().tasksByStory['story-1']).toHaveLength(0)
+  })
+})
diff --git a/docs/realtime-smoke.md b/docs/realtime-smoke.md
new file mode 100644
index 0000000..28f87cd
--- /dev/null
+++ b/docs/realtime-smoke.md
@@ -0,0 +1,79 @@
+# Realtime smoke-checklist — PBI / Story / Task
+
+Manuele checklist voor story "End-to-end smoke-test: PBI/Story/Task verschijnen zonder refresh".
+Uitvoeren na deployment van de realtime-feature (SSE-keten: DB-trigger → pg NOTIFY → SSE → store → render).
+
+## Voorbereiding
+
+1. Open twee browser-tabs op hetzelfde product:
+   - **Tab A** — `/backlog?product=<product_id>` (read-only observatie)
+   - **Tab B** — zelfde URL; gebruik dit tabblad voor create/edit/delete-acties
+2. Zorg dat je **niet** refresht in tab A tijdens het testen.
+3. Controleer in de DevTools-console van tab A dat de SSE-verbinding actief is
+   (`EventSource` connected, geen foutmeldingen).
+
+---
+
+## Checklist
+
+### PBI
+
+- [ ] **1. PBI aanmaken in tab B**
+  Maak een nieuwe PBI aan (bijv. titel "Smoke PBI").
+  → Tab A toont de nieuwe PBI **binnen 1 seconde** zonder refresh.
+  → Geen dubbele entry (PBI verschijnt precies één keer).
+
+- [ ] **2. PBI titel bewerken in tab B**
+  Pas de titel van de PBI aan naar "Smoke PBI — updated".
+  → Tab A reflecteert de nieuwe titel **binnen 1 seconde**.
+  → Geen dubbele entry, geen flickering.
+
+- [ ] **3. PBI verwijderen in tab B**
+  Verwijder de PBI.
+  → Tab A verwijdert de PBI **binnen 1 seconde**.
+
+---
+
+### Story
+
+- [ ] **4. Story aanmaken in tab B**
+  Maak een story aan onder een bestaande PBI (bijv. "Smoke Story").
+  → Tab A toont de story in de juiste PBI-rij **binnen 1 seconde**.
+  → Geen dubbele entry.
+
+- [ ] **5. Story titel bewerken in tab B**
+  Pas de titel aan naar "Smoke Story — updated".
+  → Tab A reflecteert de nieuwe titel.
+  → Geen dubbele entry, geen flickering.
+
+- [ ] **6. Story verwijderen in tab B**
+  Verwijder de story.
+  → Tab A verwijdert de story uit de lijst.
+
+---
+
+### Task (solo-paneel + backlog drie-paneel)
+
+- [ ] **7. Task aanmaken via solo-paneel**
+  Maak een task aan onder een story in het solo-paneel.
+  → De task verschijnt in het solo-paneel **en** in het backlog drie-paneel **binnen 1 seconde**.
+  → Geen dubbele entry.
+
+- [ ] **8. Task status bijwerken**
+  Verander de status van de task (bijv. TO_DO → IN_PROGRESS).
+  → Beide panelen reflecteren de nieuwe status.
+
+- [ ] **9. Task verwijderen**
+  Verwijder de task.
+  → Verdwijnt uit beide panelen.
+
+---
+
+## Pass-criteria
+
+Alle 9 items afgevinkt = smoke geslaagd.
+
+Bij een mislukking: noteer welk item faalde en controleer:
+1. De SSE-stream (`/api/realtime/backlog?product_id=...`) in de DevTools-netwerktab.
+2. De Zustand-store via Redux DevTools of een debug-breakpoint in `applyChange`.
+3. De DB-trigger op de relevante tabel (`pg_notify` op INSERT/UPDATE/DELETE).
diff --git a/stores/backlog-store.ts b/stores/backlog-store.ts
index 67daa62..16a584b 100644
--- a/stores/backlog-store.ts
+++ b/stores/backlog-store.ts
@@ -69,7 +69,8 @@ export const useBacklogStore = create<BacklogStore>((set) => ({
             ),
           }
         }
-        // I
+        // I — idempotent: skip if already present (optimistic update may have arrived first)
+        if (state.pbis.some((p) => p.id === id)) return {}
         return { pbis: [...state.pbis, data as unknown as BacklogPbi] }
       }
 
@@ -95,8 +96,9 @@ export const useBacklogStore = create<BacklogStore>((set) => ({
           }
           return { storiesByPbi }
         }
-        // I
+        // I — idempotent: skip if already present
         const pbiId = data.pbi_id as string
+        if ((state.storiesByPbi[pbiId] ?? []).some((s) => s.id === id)) return {}
         return {
           storiesByPbi: {
             ...state.storiesByPbi,
@@ -127,8 +129,9 @@ export const useBacklogStore = create<BacklogStore>((set) => ({
         }
         return { tasksByStory }
       }
-      // I
+      // I — idempotent: skip if already present
       const storyId = data.story_id as string
+      if ((state.tasksByStory[storyId] ?? []).some((t) => t.id === id)) return {}
       return {
         tasksByStory: {
           ...state.tasksByStory,

From dc3832ad547d14a2c155798aa39b9dfa06276dbe Mon Sep 17 00:00:00 2001
From: Janpeter Visser <janpetervisser2@gmail.com>
Date: Sat, 2 May 2026 21:10:03 +0200
Subject: [PATCH 15/17] feat(schema): add notify_pbi_change trigger so PBI
 INSERT/UPDATE/DELETE emits NOTIFY on scrum4me_changes (#58)

Co-authored-by: Scrum4Me Agent <30029041+madhura68@users.noreply.github.com>
---
 .../migration.sql                             | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 prisma/migrations/20260502190200_add_pbi_notify_trigger/migration.sql

diff --git a/prisma/migrations/20260502190200_add_pbi_notify_trigger/migration.sql b/prisma/migrations/20260502190200_add_pbi_notify_trigger/migration.sql
new file mode 100644
index 0000000..8ade1a9
--- /dev/null
+++ b/prisma/migrations/20260502190200_add_pbi_notify_trigger/migration.sql
@@ -0,0 +1,53 @@
+-- Add notify_pbi_change() function and pbis_notify_change trigger so that
+-- INSERT/UPDATE/DELETE on pbis emits a pg_notify on 'scrum4me_changes'.
+-- Payload field names match BacklogPbi directly (no client-side rename needed).
+
+CREATE OR REPLACE FUNCTION notify_pbi_change() RETURNS trigger AS $$
+DECLARE
+  rec record;
+  payload jsonb;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    rec := OLD;
+  ELSE
+    rec := NEW;
+  END IF;
+
+  payload := jsonb_build_object(
+    'op', CASE TG_OP
+            WHEN 'INSERT' THEN 'I'
+            WHEN 'UPDATE' THEN 'U'
+            WHEN 'DELETE' THEN 'D'
+          END,
+    'entity', 'pbi',
+    'id', rec.id,
+    'product_id', rec.product_id,
+    'title', rec.title,
+    'code', rec.code,
+    'priority', rec.priority,
+    'status', rec.status,
+    'sort_order', rec.sort_order,
+    'created_at', rec.created_at
+  );
+
+  IF TG_OP = 'UPDATE' THEN
+    payload := payload || jsonb_build_object(
+      'changed_fields',
+      COALESCE((
+        SELECT jsonb_agg(n.key)
+        FROM jsonb_each(to_jsonb(NEW)) n
+        JOIN jsonb_each(to_jsonb(OLD)) o USING (key)
+        WHERE n.value IS DISTINCT FROM o.value
+      ), '[]'::jsonb)
+    );
+  END IF;
+
+  PERFORM pg_notify('scrum4me_changes', payload::text);
+  RETURN rec;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS pbis_notify_change ON pbis;
+CREATE TRIGGER pbis_notify_change
+  AFTER INSERT OR UPDATE OR DELETE ON pbis
+  FOR EACH ROW EXECUTE FUNCTION notify_pbi_change();

From e10f8f81bcdec6a9f1c5a3f2292ee31d2e028c45 Mon Sep 17 00:00:00 2001
From: Janpeter Visser <30029041+madhura68@users.noreply.github.com>
Date: Sun, 3 May 2026 03:00:47 +0200
Subject: [PATCH 16/17] =?UTF-8?q?Phase=202=20=E2=80=94=20Normalize=20file?=
 =?UTF-8?q?=20naming=20(#59)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(naming): drop scrum4me- prefix from doc filenames

Rename 10 docs/scrum4me-*.md files to unprefixed kebab-case names.
Update every internal link in docs/, CLAUDE.md, AGENTS.md, README.md.

* docs(naming): lowercase API.md and MD3 filenames

Rename docs/API.md → docs/api.md and
docs/MD3_Color_Scheme_Documentation.md → docs/md3-color-scheme.md.
Update all internal links across 7 files.

* docs(naming): rename plan file to kebab-case ASCII

Rename "docs/plans/Tweede Claude Agent — Planning Agent.md"
→ docs/plans/tweede-claude-agent-planning.md. No external links needed updating.

* docs(naming): rename middleware.md to proxy.md (next 16)

docs/patterns/middleware.md → docs/patterns/proxy.md following
the Next.js 16 proxy.ts rename. Update link in CLAUDE.md.

* docs(naming): polish CLAUDE.md doc-index after renames

Fix doubled scrum4me-scrum4me-mcp repo references (cascade from
prior sed) in CLAUDE.md, docs/architecture.md, backlog.md,
agent-instruction-audit.md, and plans/ST-1109. Update
'Middleware' label to 'Proxy middleware' in patterns table.
---
 AGENTS.md                                     |  4 +-
 CLAUDE.md                                     | 36 +++++++++---------
 README.md                                     |  8 ++--
 docs/agent-instruction-audit.md               | 38 +++++++++----------
 docs/{API.md => api.md}                       |  4 +-
 ...rum4me-architecture.md => architecture.md} |  2 +-
 docs/{scrum4me-backlog.md => backlog.md}      | 18 ++++-----
 ...um4me-functional-spec.md => functional.md} |  0
 ...e_Documentation.md => md3-color-scheme.md} |  0
 docs/patterns/claude-question-channel.md      |  4 +-
 docs/patterns/dialog.md                       | 14 +++----
 docs/patterns/iron-session.md                 |  2 +-
 docs/patterns/{middleware.md => proxy.md}     |  0
 docs/patterns/qr-login.md                     |  4 +-
 .../{scrum4me-pbi-dialog.md => pbi-dialog.md} |  4 +-
 docs/{scrum4me-personas.md => personas.md}    |  0
 docs/plans/M10-qr-pairing-login.md            | 20 +++++-----
 docs/plans/M11-claude-questions.md            | 16 ++++----
 docs/plans/M9-active-product-backlog.md       |  2 +-
 docs/plans/ST-1110-demo-readonly.md           |  2 +-
 ...Agent.md => tweede-claude-agent-planning.md} | 14 +++----
 ...-product-backlog.md => product-backlog.md} |  0
 docs/solo-paneel-spec.md                      |  2 +-
 ...rum4me-story-dialog.md => story-dialog.md} |  4 +-
 docs/{scrum4me-styling.md => styling.md}      |  0
 ...scrum4me-task-dialog.md => task-dialog.md} |  4 +-
 docs/{scrum4me-test-plan.md => test-plan.md}  |  0
 27 files changed, 101 insertions(+), 101 deletions(-)
 rename docs/{API.md => api.md} (98%)
 rename docs/{scrum4me-architecture.md => architecture.md} (99%)
 rename docs/{scrum4me-backlog.md => backlog.md} (98%)
 rename docs/{scrum4me-functional-spec.md => functional.md} (100%)
 rename docs/{MD3_Color_Scheme_Documentation.md => md3-color-scheme.md} (100%)
 rename docs/patterns/{middleware.md => proxy.md} (100%)
 rename docs/{scrum4me-pbi-dialog.md => pbi-dialog.md} (97%)
 rename docs/{scrum4me-personas.md => personas.md} (100%)
 rename docs/plans/{Tweede Claude Agent — Planning Agent.md => tweede-claude-agent-planning.md} (96%)
 rename docs/{scrum4me-product-backlog.md => product-backlog.md} (100%)
 rename docs/{scrum4me-story-dialog.md => story-dialog.md} (98%)
 rename docs/{scrum4me-styling.md => styling.md} (100%)
 rename docs/{scrum4me-task-dialog.md => task-dialog.md} (97%)
 rename docs/{scrum4me-test-plan.md => test-plan.md} (100%)

diff --git a/AGENTS.md b/AGENTS.md
index d097267..186e2d4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,8 +22,8 @@ Read `CLAUDE.md` and the relevant files in `docs/` before changing behavior. The
 When changing behavior, API responses, dependencies, environment variables, deployment behavior, or analytics, update the matching docs in the same change:
 
 - `README.md` for setup, dependencies, deployment, and API overview.
-- `docs/scrum4me-functional-spec.md` for user-facing/API requirements.
-- `docs/scrum4me-architecture.md` for stack, access model, data model, env vars, and deployment.
+- `docs/functional.md` for user-facing/API requirements.
+- `docs/architecture.md` for stack, access model, data model, env vars, and deployment.
 - `docs/patterns/` when a reusable implementation rule changes.
 - `CLAUDE.md` and this file when an agent instruction would have prevented the issue.
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 9726c82..b129147 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,13 +16,13 @@ Lees het relevante document voordat je aan een feature begint. Nooit gokken over
 
 | Document | Gebruik voor |
 |---|---|
-| `docs/scrum4me-functional-spec.md` | Acceptatiecriteria, randgevallen, user flows |
-| `docs/scrum4me-architecture.md` | Stack, datamodel, Prisma schema, Zustand stores |
-| `docs/scrum4me-backlog.md` | Welke task bouwen, volgorde, "done when"-criteria |
-| `docs/scrum4me-personas.md` | Lars (primair), Dina, Remi — gebruik bij UI-beslissingen |
-| `docs/scrum4me-product-backlog.md` | Historische domein-backlog (referentie); seed wordt sinds ST-004 gegenereerd uit `scrum4me-backlog.md` via `prisma/seed-data/parse-backlog.ts` |
-| `docs/API.md` | REST-API contract voor Claude Code — endpoints, status-enums, foutcodes, voorbeeld-curls |
-| `docs/scrum4me-styling.md` | **Lees dit voor elk component** — MD3-kleuren, shadcn patronen |
+| `docs/functional.md` | Acceptatiecriteria, randgevallen, user flows |
+| `docs/architecture.md` | Stack, datamodel, Prisma schema, Zustand stores |
+| `docs/backlog.md` | Welke task bouwen, volgorde, "done when"-criteria |
+| `docs/personas.md` | Lars (primair), Dina, Remi — gebruik bij UI-beslissingen |
+| `docs/product-backlog.md` | Historische domein-backlog (referentie); seed wordt sinds ST-004 gegenereerd uit `backlog.md` via `prisma/seed-data/parse-backlog.ts` |
+| `docs/api.md` | REST-API contract voor Claude Code — endpoints, status-enums, foutcodes, voorbeeld-curls |
+| `docs/styling.md` | **Lees dit voor elk component** — MD3-kleuren, shadcn patronen |
 | `docs/agent-instruction-audit.md` | Waarom de agent-instructies zijn aangescherpt; checklist voor toekomstige wijzigingen |
 | `docs/plans/<milestone-key>-*.md` | Implementatieplan per milestone — Bestanden, Stappen, Aandachtspunten, Verificatie. Lees vóór je aan een ST begint. Milestone-key matcht backlog-header (`M9`, `M3.5`, `PBI-9`, …). |
 | [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) | MCP-server repo: native tools voor Claude Code, schema-sync via git submodule |
@@ -51,9 +51,9 @@ Werken aan een task kan via twee tracks. Track A heeft de voorkeur als je in Cla
 
 ### Track B — manueel (Codex of zonder MCP)
 
-1. Lees de task in `scrum4me-backlog.md`
-2. Zoek de bijbehorende feature-spec in `scrum4me-functional-spec.md`
-3. Lees het relevante patroon in `docs/patterns/` en styling in `docs/scrum4me-styling.md` als dat van toepassing is
+1. Lees de task in `backlog.md`
+2. Zoek de bijbehorende feature-spec in `functional.md`
+3. Lees het relevante patroon in `docs/patterns/` en styling in `docs/styling.md` als dat van toepassing is
 4. Bouw — test — verifieer de "Done when"-criteria
 5. Vraag of de code correct is
 6. Commit (zie Commit Strategy hieronder)
@@ -79,7 +79,7 @@ Vercel Analytics (@vercel/analytics/next)
 
 > ⚠️ **Stylingregel:** Gebruik **nooit** `bg-blue-500` of willekeurige Tailwind-kleuren.
 > Gebruik altijd semantische MD3-tokens: `bg-primary`, `bg-status-done`, `bg-priority-critical`.
-> Zie `scrum4me-styling.md` voor alle patronen.
+> Zie `styling.md` voor alle patronen.
 
 > ⚠️ **Next.js-versie:** Lees `node_modules/next/dist/docs/` bij twijfel — API's kunnen afwijken van trainingsdata.
 
@@ -108,10 +108,10 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
 | Route Handler (REST API) | `docs/patterns/route-handler.md` |
 | Zustand optimistische update + rollback | `docs/patterns/zustand-optimistic.md` |
 | Float sort_order drag-and-drop | `docs/patterns/sort-order.md` |
-| Middleware (route protection) | `docs/patterns/middleware.md` |
+| Proxy middleware (route protection) | `docs/patterns/proxy.md` |
 | QR-pairing (unauth-SSE + pre-auth cookie) | `docs/patterns/qr-login.md` |
 | Bidirectionele async-comms MCP-agent ↔ user | `docs/patterns/claude-question-channel.md` |
-| **Entity Dialog (verplicht voor élke create/edit/detail-dialog)** | `docs/patterns/dialog.md` — bron-of-truth; per entiteit één profile-doc (bv. `docs/scrum4me-task-dialog.md`) |
+| **Entity Dialog (verplicht voor élke create/edit/detail-dialog)** | `docs/patterns/dialog.md` — bron-of-truth; per entiteit één profile-doc (bv. `docs/task-dialog.md`) |
 | **Story met UI-component (verplicht 3-task-patroon: Helper / Component / Integration)** | `docs/patterns/story-with-ui-component.md` — elke story met een `*-component.tsx` vereist een afsluitende Integration-task die de component in `page.tsx` wirt |
 | Status-enum mapping (DB ↔ API) | `lib/task-status.ts` |
 | Client/server module-boundary | `*-server.ts` bevat DB-calls of node-only deps; `*.ts` is pure (client-safe). Nooit `import { ... } from '@/lib/foo-server'` in een client-component, anders krijg je `Module not found: 'dns'`/`'pg'`-style runtime fouten |
@@ -170,13 +170,13 @@ Volledige Zod-schema in `lib/env.ts`. `.env.example` is de canonieke lijst voor
 - **Toegangsmodel:** product-scoped resources gebruiken `productAccessFilter(userId)` tenzij het expliciet een eigenaarsactie is
 - **Bulk-ID's:** reorder- en beslissingsacties valideren dat alle meegegeven IDs binnen dezelfde parent-scope vallen voordat er geschreven wordt
 - **Foreign keys:** denormalized keys zoals `story.product_id` worden afgeleid uit de database-parent (`pbi.product_id`), nooit uit client-input
-- **Demo-check (drie lagen — ST-1110):** write-acties zijn drielaags afgedekt: (1) middleware-guard in `proxy.ts` blokkeert non-GET op `/api/*` voor demo; (2) elke Server Action / Route Handler controleert `session.isDemo` vóór schrijven; (3) write-knoppen in UI zijn `disabled` met `<DemoTooltip show={isDemo}>`. Zie `docs/scrum4me-architecture.md#demo-user-policy` en `docs/plans/ST-1110-demo-readonly.md`
+- **Demo-check (drie lagen — ST-1110):** write-acties zijn drielaags afgedekt: (1) middleware-guard in `proxy.ts` blokkeert non-GET op `/api/*` voor demo; (2) elke Server Action / Route Handler controleert `session.isDemo` vóór schrijven; (3) write-knoppen in UI zijn `disabled` met `<DemoTooltip show={isDemo}>`. Zie `docs/architecture.md#demo-user-policy` en `docs/plans/ST-1110-demo-readonly.md`
 - **Foutberichten:** Nederlands voor eindgebruikers — comments in code: Engels
 - **Dependencies:** elke geïmporteerde runtime package staat direct in `dependencies`, niet alleen transitief in `package-lock.json`
 - **Docs-sync:** elke gedrags-, dependency-, API- of deploymentwijziging werkt README, relevante docs en patterns bij in dezelfde change
 - **Entity codes:** gebruik product/PBI/story-codes in commit-titles wanneer aanwezig (`feat(ST-356.2): ...`); branchnaam blijft `feat/ST-XXX-slug`
 - **Status-enums op API:** lowercase (`todo|in_progress|review|done`, `open|in_sprint|done`); DB houdt UPPER_SNAKE; conversie uitsluitend via `lib/task-status.ts`-mappers — nooit ad-hoc `.toLowerCase()` elders
-- **Foutcodes API:** `400` alleen voor malformed JSON-body (parse-fout via `request.json()`); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteer per endpoint in `docs/API.md`
+- **Foutcodes API:** `400` alleen voor malformed JSON-body (parse-fout via `request.json()`); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteer per endpoint in `docs/api.md`
 - **Tests volgen contract:** bij een API-contract-wijziging (status, foutcode, response-shape) MOET in dezelfde commit ook `__tests__/api/` mee — een test die rood gaat omdat de oude waarde wordt verwacht is een onvolledige wijziging, niet een "kapotte test"
 - **Dev port:** `npm run dev` draait altijd op **3000**. Een `predev`-hook killt vooraf elk proces op 3000 (stale Next.js dev-server, vorige sessie) zodat sessies, cookies en MCP-config consistent op één poort werken. Wijk hier niet van af — geen `-p 3001` o.i.d. tenzij je expliciet twee dev-servers naast elkaar wil draaien
 
@@ -352,7 +352,7 @@ Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuh
 
 - **Sharp** moet Linux-binaries hebben voor de Vercel-runtime: `npm i --include=optional sharp` of platform-specifieke deps configureren in `package.json`
 - **Externe image hostnames** in `next.config.js` `images.remotePatterns` configureren *vóór* `next/image` op die hosts wijst — anders 500 in productie
-- **Vercel cron**: Hobby-plan staat alleen daily crons toe (max 1×/dag); Pro ondersteunt fijnmaziger. Bij wijziging van `vercel.json` `crons` ook `docs/API.md` + relevante pattern-docs updaten
+- **Vercel cron**: Hobby-plan staat alleen daily crons toe (max 1×/dag); Pro ondersteunt fijnmaziger. Bij wijziging van `vercel.json` `crons` ook `docs/api.md` + relevante pattern-docs updaten
 - **`CRON_SECRET`** moet als env-var op de Vercel-project-omgeving staan vóór de eerste cron-run, anders 401 op `/api/cron/*`-endpoints
 - **Preflight** vóór deploy: `npm run lint && npm test && npm run build` — falende build laat een PR niet door (CI blokkeert merge per ST-610)
 
@@ -360,11 +360,11 @@ Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuh
 
 ## Definition of Done (MVP)
 
-M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/scrum4me-backlog.md`.
+M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/backlog.md`.
 
 - [ ] Alle 62 tasks (ST-001 t/m ST-612) afgerond
 - [ ] Volledige Lars-flow zonder fouten (ST-612)
-- [ ] Alle gedocumenteerde API-endpoints werken via curl (zie `docs/API.md`)
+- [ ] Alle gedocumenteerde API-endpoints werken via curl (zie `docs/api.md`)
 - [ ] Demo-gebruiker heeft geen schrijfrechten
 - [ ] App opzetbaar via README zonder extra hulp
 - [ ] CI/CD actief — falende build blokkeert merge
diff --git a/README.md b/README.md
index 9f86591..a24dc15 100644
--- a/README.md
+++ b/README.md
@@ -155,7 +155,7 @@ Verwacht: alle 69 tests slagen, 0 failures.
 bash scripts/test-api.sh
 ```
 
-De curl-tests dekken alle 7 API-endpoints: auth (401), demo-blokkering (403), inputvalidatie (400) en happy paths. Zie `docs/scrum4me-test-plan.md` voor het volledige testplan.
+De curl-tests dekken alle 7 API-endpoints: auth (401), demo-blokkering (403), inputvalidatie (400) en happy paths. Zie `docs/test-plan.md` voor het volledige testplan.
 
 ## Database
 
@@ -279,7 +279,7 @@ De productieomgeving is gericht op Vercel + Neon.
 
 ### Documentatie
 
-- [Functionele specificatie](docs/scrum4me-functional-spec.md)
-- [Technische architectuur](docs/scrum4me-architecture.md)
-- [Backlog](docs/scrum4me-backlog.md)
+- [Functionele specificatie](docs/functional.md)
+- [Technische architectuur](docs/architecture.md)
+- [Backlog](docs/backlog.md)
 - [Agent-instructie audit](docs/agent-instruction-audit.md)
diff --git a/docs/agent-instruction-audit.md b/docs/agent-instruction-audit.md
index 1cd185f..bc5d1a9 100644
--- a/docs/agent-instruction-audit.md
+++ b/docs/agent-instruction-audit.md
@@ -15,13 +15,13 @@ Dit document legt vast welke wijzigingen zijn gecontroleerd, welke documentatie
 
 | Wijziging | Code-locatie | Documentatie bijgewerkt |
 |---|---|---|
-| Reorder-acties valideren alle IDs binnen de juiste parent-scope | `actions/stories.ts`, `actions/sprints.ts` | `docs/scrum4me-architecture.md`, `docs/patterns/server-action.md`, `docs/patterns/sort-order.md`, `CLAUDE.md`, `AGENTS.md` |
-| Sprint afronden accepteert alleen stories uit de actieve sprint | `actions/sprints.ts` | `docs/scrum4me-architecture.md`, `docs/patterns/server-action.md`, `AGENTS.md` |
-| Todo-promotie gebruikt scoped todo lookup en `pbi.product_id` als bron van waarheid | `actions/todos.ts` | `docs/scrum4me-architecture.md`, `docs/patterns/server-action.md`, `CLAUDE.md`, `AGENTS.md` |
-| `GET /api/products` retourneert ook gedeelde producten via `product_members` | `app/api/products/route.ts` | `README.md`, `docs/scrum4me-functional-spec.md`, `docs/scrum4me-backlog.md`, `docs/patterns/route-handler.md` |
-| `sharp` is directe runtime dependency | `package.json`, `package-lock.json` | `README.md`, `docs/scrum4me-architecture.md`, `CLAUDE.md` |
-| Vercel Analytics is toegevoegd aan de root layout | `app/layout.tsx`, `package.json`, `package-lock.json` | `README.md`, `docs/scrum4me-architecture.md`, `CLAUDE.md` |
-| `.env.example` ontbrak ondanks verwijzingen in architectuurdocs | `.env.example` | `README.md`, `docs/scrum4me-architecture.md` |
+| Reorder-acties valideren alle IDs binnen de juiste parent-scope | `actions/stories.ts`, `actions/sprints.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `docs/patterns/sort-order.md`, `CLAUDE.md`, `AGENTS.md` |
+| Sprint afronden accepteert alleen stories uit de actieve sprint | `actions/sprints.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `AGENTS.md` |
+| Todo-promotie gebruikt scoped todo lookup en `pbi.product_id` als bron van waarheid | `actions/todos.ts` | `docs/architecture.md`, `docs/patterns/server-action.md`, `CLAUDE.md`, `AGENTS.md` |
+| `GET /api/products` retourneert ook gedeelde producten via `product_members` | `app/api/products/route.ts` | `README.md`, `docs/functional.md`, `docs/backlog.md`, `docs/patterns/route-handler.md` |
+| `sharp` is directe runtime dependency | `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` |
+| Vercel Analytics is toegevoegd aan de root layout | `app/layout.tsx`, `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` |
+| `.env.example` ontbrak ondanks verwijzingen in architectuurdocs | `.env.example` | `README.md`, `docs/architecture.md` |
 
 ## Preventieve regels
 
@@ -44,9 +44,9 @@ Concrete regels:
 Een codewijziging is niet klaar als de documentatie een oud contract beschrijft. Agents moeten bij elke wijziging nagaan of deze plekken geraakt worden:
 
 - `README.md`: setup, scripts, dependencies, deployment, API-overzicht.
-- `docs/scrum4me-functional-spec.md`: functionele eisen en API-contracten.
-- `docs/scrum4me-architecture.md`: stack, datamodel, securitymodel, env vars, deployment.
-- `docs/scrum4me-backlog.md`: "done when"-criteria en scope van backlog-items.
+- `docs/functional.md`: functionele eisen en API-contracten.
+- `docs/architecture.md`: stack, datamodel, securitymodel, env vars, deployment.
+- `docs/backlog.md`: "done when"-criteria en scope van backlog-items.
 - `docs/patterns/`: herbruikbare implementatiepatronen.
 - `CLAUDE.md` en `AGENTS.md`: agent-regels die de fout in de toekomst voorkomen.
 
@@ -100,7 +100,7 @@ Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow
 - **ST-509** Todo description (max 2000)
 - **ST-511** Entity codes voor Product/PBI/Story (auto-default + manual override + retry op race condition)
 - **ST-512** REST API uitgebreid met `code`, `description`, `implementation_plan` in alle endpoints
-- **ST-513** API hardening voor Claude Code: `GET /api/health`, `GET /api/products/:id/claude-context`, lowercase status-enums op de API-grens, `StoryLog.metadata` JSONB, validatie-fouten van `400` → `422`, nieuwe `docs/API.md`
+- **ST-513** API hardening voor Claude Code: `GET /api/health`, `GET /api/products/:id/claude-context`, lowercase status-enums op de API-grens, `StoryLog.metadata` JSONB, validatie-fouten van `400` → `422`, nieuwe `docs/api.md`
 - **PR #2 Codex-review-saga** — 8 testbestanden faalden bij de contract-flip; tests werden niet meebijgewerkt. Twee P2-issues van Codex: malformed JSON moet `400` blijven (P2.1), en `status: review` werd geaccepteerd terwijl de sprint-UI er niet mee om kan gaan (P2.2)
 - **M7: scrum4me-mcp** — aparte MCP-server repo (`madhura68/scrum4me-mcp`) met 9 tools en 1 prompt voor Claude Code, schema gedeeld via git submodule
 - **lib/code.ts vs lib/code-server.ts** — gesplitst om client-bundle vrij te houden van `pg` (gaf eerst `Module not found: 'dns'` build-error)
@@ -110,13 +110,13 @@ Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow
 
 | Wijziging | Code-locatie | Documentatie bijgewerkt |
 |---|---|---|
-| Lowercase status-enums op REST-grens, mappers naar DB-enum | `lib/task-status.ts`, `app/api/tasks/[id]/route.ts`, `app/api/sprints/[id]/tasks/route.ts`, `app/api/products/[id]/next-story/route.ts` | `docs/API.md`, `CLAUDE.md` |
-| 400 (malformed JSON) gescheiden van 422 (zod-validatie) | `app/api/tasks/[id]/route.ts`, `app/api/stories/[id]/tasks/reorder/route.ts`, `app/api/todos/route.ts`, `app/api/stories/[id]/log/route.ts` | `docs/API.md`, `CLAUDE.md` |
-| `status: review` geweigerd door PATCH `/api/tasks/:id` zolang sprint-UI geen REVIEW rendert | `app/api/tasks/[id]/route.ts` | `docs/API.md` |
-| Entity codes (Product/PBI/Story) met auto-default + retry-on-P2002 | `actions/products.ts`, `actions/pbis.ts`, `actions/stories.ts`, `lib/code.ts`, `lib/code-server.ts` | `docs/scrum4me-backlog.md` (ST-511) |
-| `StoryLog.metadata` JSONB | `prisma/schema.prisma`, `prisma/migrations/20260426214905_add_story_log_metadata/`, `app/api/stories/[id]/log/route.ts` | `docs/API.md` |
-| Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/API.md`, `CLAUDE.md` |
-| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/scrum4me-backlog.md` (M7) |
+| Lowercase status-enums op REST-grens, mappers naar DB-enum | `lib/task-status.ts`, `app/api/tasks/[id]/route.ts`, `app/api/sprints/[id]/tasks/route.ts`, `app/api/products/[id]/next-story/route.ts` | `docs/api.md`, `CLAUDE.md` |
+| 400 (malformed JSON) gescheiden van 422 (zod-validatie) | `app/api/tasks/[id]/route.ts`, `app/api/stories/[id]/tasks/reorder/route.ts`, `app/api/todos/route.ts`, `app/api/stories/[id]/log/route.ts` | `docs/api.md`, `CLAUDE.md` |
+| `status: review` geweigerd door PATCH `/api/tasks/:id` zolang sprint-UI geen REVIEW rendert | `app/api/tasks/[id]/route.ts` | `docs/api.md` |
+| Entity codes (Product/PBI/Story) met auto-default + retry-on-P2002 | `actions/products.ts`, `actions/pbis.ts`, `actions/stories.ts`, `lib/code.ts`, `lib/code-server.ts` | `docs/backlog.md` (ST-511) |
+| `StoryLog.metadata` JSONB | `prisma/schema.prisma`, `prisma/migrations/20260426214905_add_story_log_metadata/`, `app/api/stories/[id]/log/route.ts` | `docs/api.md` |
+| Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/api.md`, `CLAUDE.md` |
+| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/backlog.md` (M7) |
 
 ## Nieuwe preventieve regels
 
@@ -140,7 +140,7 @@ API exposeert lowercase, DB houdt UPPER_SNAKE. Conversie uitsluitend via `lib/ta
 - `400`: parse-fout op `request.json()` — wikkel altijd in `try/catch`
 - `422`: zod-validatie of well-formed-maar-niet-acceptabel (bv. `task_id` van andere story)
 - `403`: demo-token op write
-- Documenteer per endpoint in `docs/API.md`
+- Documenteer per endpoint in `docs/api.md`
 
 ### Client/server module-boundary
 
diff --git a/docs/API.md b/docs/api.md
similarity index 98%
rename from docs/API.md
rename to docs/api.md
index bfda532..8fccadb 100644
--- a/docs/API.md
+++ b/docs/api.md
@@ -393,13 +393,13 @@ curl -N -i -b /tmp/jar http://localhost:3000/api/auth/pair/stream/<pairingId>
 ### `POST /api/auth/pair/claim`
 
 Cookie-auth. Atomisch consume van een approved pairing → schrijft de echte
-`scrum4me-session` cookie zodat de desktop is ingelogd.
+`session` cookie zodat de desktop is ingelogd.
 
 **Auth:** `s4m_pair`-cookie.
 **Body:** `{ "pairingId": "cmoh..." }`.
 
 **Response 200:** `{ "ok": true }` plus
-- `Set-Cookie: scrum4me-session=...; HttpOnly; SameSite=Lax` — paired-sessie met `paired: true` en `pairedExpiresAt = now + 8h` payload-velden.
+- `Set-Cookie: session=...; HttpOnly; SameSite=Lax` — paired-sessie met `paired: true` en `pairedExpiresAt = now + 8h` payload-velden.
 - `Set-Cookie: s4m_pair=...; Max-Age=0` — pre-auth cookie wordt gewist.
 
 **Foutcodes:**
diff --git a/docs/scrum4me-architecture.md b/docs/architecture.md
similarity index 99%
rename from docs/scrum4me-architecture.md
rename to docs/architecture.md
index 12085c9..be21af7 100644
--- a/docs/scrum4me-architecture.md
+++ b/docs/architecture.md
@@ -564,7 +564,7 @@ sequenceDiagram
   D->>S: POST /api/auth/pair/claim<br/>Cookie: s4m_pair, body: { pairingId }
   S->>S: atomic UPDATE WHERE status=approved AND token-hash<br/>→ status=consumed
   S->>S: getIronSession.save { userId, paired: true, pairedExpiresAt }
-  S-->>D: 200, Set-Cookie: scrum4me-session<br/>+ s4m_pair cleared
+  S-->>D: 200, Set-Cookie: session<br/>+ s4m_pair cleared
   D->>D: redirect /dashboard
 ```
 
diff --git a/docs/scrum4me-backlog.md b/docs/backlog.md
similarity index 98%
rename from docs/scrum4me-backlog.md
rename to docs/backlog.md
index 689063a..8424cc0 100644
--- a/docs/scrum4me-backlog.md
+++ b/docs/backlog.md
@@ -409,8 +409,8 @@ De MVP is klaar wanneer Lars — de primaire persona — de volledige cyclus kan
   - **`PATCH /api/tasks/:id`:** accepteert lowercase `status` via mapper; retourneert lowercase
   - **Story-log metadata:** nieuwe optionele `metadata Json?` kolom op `StoryLog`; `POST /api/stories/:id/log` accepteert per type een optioneel `metadata`-veld (bv. `{ branch: 'feat/x' }`); bestaande velden ongewijzigd → backwards-compatible
   - **Foutcodes:** Zod-validatie geeft `422` (was `400`); `400` blijft voor malformed body; `401`/`403`/`404`/`500` ongewijzigd
-  - **API-documentatie:** nieuwe `docs/API.md` met endpoints, request/response, foutcodes, status-enums en curl-voorbeelden; `CLAUDE.md` verwijst ernaar
-  - Done when: `curl /api/health` werkt zonder auth; `curl /api/products/:id/claude-context` retourneert bundled JSON; PATCH/PUT routes accepteren lowercase status en geven 422 bij ongeldige body; story-log POST bewaart `metadata`; `docs/API.md` is gepubliceerd
+  - **API-documentatie:** nieuwe `docs/api.md` met endpoints, request/response, foutcodes, status-enums en curl-voorbeelden; `CLAUDE.md` verwijst ernaar
+  - Done when: `curl /api/health` werkt zonder auth; `curl /api/products/:id/claude-context` retourneert bundled JSON; PATCH/PUT routes accepteren lowercase status en geven 422 bij ongeldige body; story-log POST bewaart `metadata`; `docs/api.md` is gepubliceerd
   - **`GET /api/products`:** voeg `code` toe (naast `id`, `name`, `repo_url`); optioneel `description` en `definition_of_done`
   - **`GET /api/products/:id/next-story`:** voeg `code` toe op story; voeg per task `code` (derived `${story.code}.${index_in_story}`) en `implementation_plan` toe
   - **`GET /api/sprints/:id/tasks`:** voeg `description`, `implementation_plan` en `story_code` toe per task; voeg een derived `code`-veld per task toe (`${story.code}.${index_in_story}`)
@@ -547,7 +547,7 @@ Filtering server-side: alleen events binnen de actieve sprint van een product wa
   - Done when: twee tabs van Solo Paneel — mutatie in tab A komt binnen 1–2s in tab B zonder refresh
 
 - [x] **ST-806** Documentatie + acceptatietest
-  - Sectie "Realtime updates" in `docs/scrum4me-architecture.md` met diagram en filtering-regels; vermelding in `CLAUDE.md`; korte note over `/api/realtime/solo` in `docs/API.md`; handmatig E2E-scenario's gedraaid (zelfde gebruiker twee tabs, MCP-write, REST-write, story-claim, network-flap)
+  - Sectie "Realtime updates" in `docs/architecture.md` met diagram en filtering-regels; vermelding in `CLAUDE.md`; korte note over `/api/realtime/solo` in `docs/api.md`; handmatig E2E-scenario's gedraaid (zelfde gebruiker twee tabs, MCP-write, REST-write, story-claim, network-flap)
   - Done when: alle scenario's lopen door zonder onverwachte gedragingen
 
 Volledig plan in `.Plans/2026-04-27-m8-realtime-solo.md` (lokaal, niet gecommit).
@@ -641,13 +641,13 @@ Volledige flow + threat-model: `docs/patterns/qr-login.md` (op te leveren in ST-
 - [ ] **ST-1007** Desktop UI: QR-render + SSE-listener op `/login`
   - **Dependency:** `qrcode.react` (client SVG; mobileSecret blijft op desktop in JS-geheugen)
   - **`app/login/qr-login-button.tsx`:** Client Component; klik → POST `pair/start` (`credentials: 'same-origin'` zodat `s4m_pair`-cookie wordt geaccepteerd) → render QR met `qrUrl` (fragment-URL) → open `EventSource('/api/auth/pair/stream/<pairingId>', { withCredentials: true })` → bij `approved` event POST `pair/claim` (cookie-only) → bij succes `router.push('/dashboard')`; aftellende timer (2 min); bij timeout "Vernieuwen"-knop; cleanup bij unmount/redirect
-  - **`app/login/page.tsx`:** knop "Inloggen via mobiel" naast bestaande wachtwoord-form (MD3-tokens uit `docs/scrum4me-styling.md`)
+  - **`app/login/page.tsx`:** knop "Inloggen via mobiel" naast bestaande wachtwoord-form (MD3-tokens uit `docs/styling.md`)
   - A11y: QR heeft alt-tekst met de URL voor screenreaders/copy-paste (de hash-suffix is onderdeel van die alt-tekst, niet van de page-URL die in browsergeschiedenis komt)
   - Done when: end-to-end happy path werkt op localhost (twee browsers): A toont QR → B scant + bevestigt → A redirect naar `/dashboard` met `session.paired === true`; QR vernieuwt na expiry; geen secret zichtbaar in DevTools Network-tab onder URL-kolommen
 
 - [ ] **ST-1008** Documentatie + acceptatietest
-  - **`docs/API.md`:** drie nieuwe endpoints (start/stream/claim) met request/response, cookie-mechaniek, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`
-  - **`docs/scrum4me-architecture.md`:** sectie "QR-pairing flow" met sequence-diagram + threat-model; expliciete subsectie *"Waarom geen secret in URL"* — fragments worden niet naar server gestuurd; SSE/claim authenticeren via HttpOnly cookie zodat secret-materiaal niet in access logs / reverse-proxy logs / observability-tools / browsergeschiedenis kan belanden
+  - **`docs/api.md`:** drie nieuwe endpoints (start/stream/claim) met request/response, cookie-mechaniek, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`
+  - **`docs/architecture.md`:** sectie "QR-pairing flow" met sequence-diagram + threat-model; expliciete subsectie *"Waarom geen secret in URL"* — fragments worden niet naar server gestuurd; SSE/claim authenticeren via HttpOnly cookie zodat secret-materiaal niet in access logs / reverse-proxy logs / observability-tools / browsergeschiedenis kan belanden
   - **`docs/patterns/qr-login.md`:** nieuw pattern-doc voor toekomstige features die hetzelfde unauth-SSE-via-pre-auth-cookie-patroon willen hergebruiken
   - **`CLAUDE.md`:** verwijzing naar het nieuwe pattern-doc in de patterns-tabel
   - **Acceptatietest:** zeven scenario's handmatig: happy path, demo-block, replay, expiry tijdens pending, expiry tussen approve+claim, ontbrekende cookie op SSE/claim, secret niet aanwezig in `nginx`/Vercel access logs (controle via runtime-logs MCP-tool)
@@ -694,7 +694,7 @@ Persistent vraag-antwoord-kanaal tussen Claude Code (via MCP) en de actieve Scru
   - **`stores/notifications-store.ts`** — Zustand store volgens `solo-store.ts`-patroon: `init`, `add`, `update`, `remove`, `optimisticAnswer`, `rollbackAnswer`; selectors `openCount`, `forYouCount`
   - **`lib/realtime/use-notifications-realtime.ts`** — analoog aan `useSoloRealtime`; EventSource op `/api/realtime/notifications` met reconnect-backoff
   - **`components/notifications/notifications-bridge.tsx`** — Server Component die initial-data fetcht en aan store geeft; mount in `app/(app)/layout.tsx` naast `<SoloRealtimeBridge />`
-  - **`components/shared/notifications-bell.tsx`** — Bell-icon (Lucide) met badge in NavBar (links van avatar); MD3-tokens uit `docs/scrum4me-styling.md`
+  - **`components/shared/notifications-bell.tsx`** — Bell-icon (Lucide) met badge in NavBar (links van avatar); MD3-tokens uit `docs/styling.md`
   - **`components/notifications/notifications-sheet.tsx`** — shadcn Sheet van rechts; lijst gegroepeerd per product; story-assignee krijgt visuele *"wacht op jou"*-emphase
   - **`components/notifications/answer-modal.tsx`** — shadcn Dialog; story-context-link, vraag-tekst, RadioGroup (als options) of Textarea (free-text), submit via `useTransition` + Server Action; demo-blok met tooltip
   - Done when: bell + badge zichtbaar; klik opent Sheet met items; submit verwijdert item optimistisch; tweede tab van zelfde user ziet nieuwe vraag binnen 1-2s; demo-modus rendert maar Verstuur disabled
@@ -713,8 +713,8 @@ Persistent vraag-antwoord-kanaal tussen Claude Code (via MCP) en de actieve Scru
   - Done when: handmatige `curl -X POST` met secret expireert oude rijen; Vercel-dashboard toont cron-config na deploy; onbevoegde call → 401
 
 - [ ] **ST-1108** Documentatie + acceptatietest
-  - **`docs/API.md`:** secties "SSE — Notifications" + "Cron — Expire questions" met curl-voorbeelden
-  - **`docs/scrum4me-architecture.md`:** sectie "Vraag-antwoord-kanaal Claude ↔ user" met Mermaid sequence-diagram + threat-model + "Waarom hergebruik scrum4me_changes-kanaal"
+  - **`docs/api.md`:** secties "SSE — Notifications" + "Cron — Expire questions" met curl-voorbeelden
+  - **`docs/architecture.md`:** sectie "Vraag-antwoord-kanaal Claude ↔ user" met Mermaid sequence-diagram + threat-model + "Waarom hergebruik scrum4me_changes-kanaal"
   - **`docs/patterns/claude-question-channel.md`:** nieuw herbruikbaar pattern-doc voor toekomstige bidirectionele async-communicatie tussen MCP-agents en interactieve users
   - **`CLAUDE.md`:** rij in Implementatiepatronen-tabel voor het nieuwe pattern
   - **Acceptatietest** zes scenario's: sync happy (wait_seconds), async happy (geen wait), demo-block, access-isolation, expiry via cron, race op double-submit
diff --git a/docs/scrum4me-functional-spec.md b/docs/functional.md
similarity index 100%
rename from docs/scrum4me-functional-spec.md
rename to docs/functional.md
diff --git a/docs/MD3_Color_Scheme_Documentation.md b/docs/md3-color-scheme.md
similarity index 100%
rename from docs/MD3_Color_Scheme_Documentation.md
rename to docs/md3-color-scheme.md
diff --git a/docs/patterns/claude-question-channel.md b/docs/patterns/claude-question-channel.md
index d451e41..dc5daa9 100644
--- a/docs/patterns/claude-question-channel.md
+++ b/docs/patterns/claude-question-channel.md
@@ -137,9 +137,9 @@ Specifiek voor M11. Kopieer en pas aan:
 
 ## Referenties
 
-- Volledige flow + threat-model: `docs/scrum4me-architecture.md` § Vraag-
+- Volledige flow + threat-model: `docs/architecture.md` § Vraag-
   antwoord-kanaal Claude ↔ user
-- Endpoint-contract: `docs/API.md` § Notifications + Cron
+- Endpoint-contract: `docs/api.md` § Notifications + Cron
 - LISTEN/NOTIFY-pattern: `app/api/realtime/solo/route.ts` (M8 ST-802) — zelfde
   ReadableStream + heartbeat + hard-close + abort-cleanup
 - M10 vs M11 keuze tussen eigen/gedeeld kanaal: zie threat-model-tabel
diff --git a/docs/patterns/dialog.md b/docs/patterns/dialog.md
index 9bf4682..7657bd2 100644
--- a/docs/patterns/dialog.md
+++ b/docs/patterns/dialog.md
@@ -4,7 +4,7 @@ Deze pagina is **bindend** voor elke create/edit/detail-dialog in Scrum4Me, onge
 
 > **Doel:** elke dialog voelt identiek aan voor de gebruiker, hergebruikt dezelfde primitives, en heeft de drielaagse demo-policy + auth-scoping standaard ingebakken.
 
-Voor entity-specifieke afwijkingen of velden: schrijf één begeleidende doc per entiteit (zie sectie [§ Per-entiteit profile](#per-entiteit-profile-verplicht)). Voorbeeld: `docs/scrum4me-task-dialog.md` is het Task-profiel.
+Voor entity-specifieke afwijkingen of velden: schrijf één begeleidende doc per entiteit (zie sectie [§ Per-entiteit profile](#per-entiteit-profile-verplicht)). Voorbeeld: `docs/task-dialog.md` is het Task-profiel.
 
 ---
 
@@ -16,10 +16,10 @@ Voor entity-specifieke afwijkingen of velden: schrijf één begeleidende doc per
 | 1.2 | Gebruik composition via de **`render`-prop** (zie `CLAUDE.md` "UI Library Conventions"). Nooit Radix' `asChild`. | Project gebruikt `@base-ui/react`, niet Radix |
 | 1.3 | Mode (`create` vs `edit` vs `detail`) wordt afgeleid uit één input — een prop, een `state`-object of een `searchParam`. **Niet** twee aparte componenten. | Voorkomt code-duplicatie en inconsistente labels/footer-layouts |
 | 1.4 | Auth-scoping op elke server action via `productAccessFilter(userId)` (of het scope-helper-equivalent). Cross-tenant writes mogen onmogelijk zijn. | `CLAUDE.md` "Toegangsmodel" + `docs/patterns/server-action.md` |
-| 1.5 | **Drielaagse demo-policy** (verplicht — zie § 6) op elke write-actie. | `CLAUDE.md` "Demo-check" + `docs/scrum4me-architecture.md#demo-user-policy` |
+| 1.5 | **Drielaagse demo-policy** (verplicht — zie § 6) op elke write-actie. | `CLAUDE.md` "Demo-check" + `docs/architecture.md#demo-user-policy` |
 | 1.6 | Validatie via één gedeeld zod-schema (`lib/schemas/<entity>.ts`) — gebruikt door zowel form als server action. | `CLAUDE.md` "Validatie" |
 | 1.7 | Foutcodes volgen de project-conventie (§ 5). | `CLAUDE.md` "Foutcodes API" |
-| 1.8 | Geen willekeurige Tailwind-kleuren (`bg-blue-500` etc.). Alleen MD3-tokens uit `app/styles/theme.css`. | `docs/scrum4me-styling.md` |
+| 1.8 | Geen willekeurige Tailwind-kleuren (`bg-blue-500` etc.). Alleen MD3-tokens uit `app/styles/theme.css`. | `docs/styling.md` |
 
 ---
 
@@ -295,7 +295,7 @@ Voor state-based pattern: het record komt al uit de parent (in-memory store of s
 
 ## 12 — Per-entiteit profile (verplicht)
 
-Voor elke entiteit met een dialog hoort één profiel-doc te bestaan: `docs/<scrum4me-<entity>-dialog>.md` (of vergelijkbaar). Het profiel **vult de generieke spec aan** en bevat **alleen** de entity-specifieke onderdelen.
+Voor elke entiteit met een dialog hoort één profiel-doc te bestaan: `docs/<<entity>-dialog>.md` (of vergelijkbaar). Het profiel **vult de generieke spec aan** en bevat **alleen** de entity-specifieke onderdelen.
 
 ### Verplichte secties van het entity-profile
 
@@ -380,8 +380,8 @@ Reviewer en bouwer lopen deze door vóór merge:
 ## 15 — Referenties
 
 - `CLAUDE.md` — UI Library Conventions, Demo-check, Foutcodes API, Validatie
-- `docs/scrum4me-styling.md` — MD3-tokens, kleurklassen
-- `docs/scrum4me-architecture.md` — Demo user policy, scope-helpers
+- `docs/styling.md` — MD3-tokens, kleurklassen
+- `docs/architecture.md` — Demo user policy, scope-helpers
 - `docs/patterns/server-action.md` — Server Action template (auth + Zod)
 - `docs/patterns/zustand-optimistic.md` — voor lijst-views die de dialog aanroepen
-- `docs/scrum4me-task-dialog.md` — voorbeeld-profile voor entiteit "Task"
+- `docs/task-dialog.md` — voorbeeld-profile voor entiteit "Task"
diff --git a/docs/patterns/iron-session.md b/docs/patterns/iron-session.md
index f979904..b8abe16 100644
--- a/docs/patterns/iron-session.md
+++ b/docs/patterns/iron-session.md
@@ -12,7 +12,7 @@ export interface SessionData {
 
 export const sessionOptions: SessionOptions = {
   password: process.env.SESSION_SECRET!,
-  cookieName: 'scrum4me-session',
+  cookieName: 'session',
   cookieOptions: {
     secure: process.env.NODE_ENV === 'production',
     httpOnly: true,
diff --git a/docs/patterns/middleware.md b/docs/patterns/proxy.md
similarity index 100%
rename from docs/patterns/middleware.md
rename to docs/patterns/proxy.md
diff --git a/docs/patterns/qr-login.md b/docs/patterns/qr-login.md
index 183c749..d27279b 100644
--- a/docs/patterns/qr-login.md
+++ b/docs/patterns/qr-login.md
@@ -89,7 +89,7 @@ Drie tijden in escalerende volgorde, alle korter dan de reguliere sessie:
 
 ## Referenties
 
-- Volledige flow + threat-model: `docs/scrum4me-architecture.md` § QR-pairing flow
-- Endpoint-contract: `docs/API.md` § Auth — QR-pairing
+- Volledige flow + threat-model: `docs/architecture.md` § QR-pairing flow
+- Endpoint-contract: `docs/api.md` § Auth — QR-pairing
 - LISTEN/NOTIFY-pattern: `app/api/realtime/solo/route.ts` (M8 ST-802) — zelfde
   ReadableStream + heartbeat + hard-close + abort-cleanup, alleen ander channel
diff --git a/docs/scrum4me-pbi-dialog.md b/docs/pbi-dialog.md
similarity index 97%
rename from docs/scrum4me-pbi-dialog.md
rename to docs/pbi-dialog.md
index 79fb5ae..bc85ae1 100644
--- a/docs/scrum4me-pbi-dialog.md
+++ b/docs/pbi-dialog.md
@@ -116,5 +116,5 @@ Specifiek voor PbiDialog (boven op de algemene out-of-scope-lijst in `docs/patte
 - `components/shared/pbi-status-select.tsx` — PBI-status-select
 - `lib/task-status.ts` — `PbiStatusApi`-mapper
 - `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
-- `docs/scrum4me-architecture.md` — datamodel `Pbi`
-- `docs/scrum4me-styling.md` — MD3-tokens, status- en priority-kleuren
+- `docs/architecture.md` — datamodel `Pbi`
+- `docs/styling.md` — MD3-tokens, status- en priority-kleuren
diff --git a/docs/scrum4me-personas.md b/docs/personas.md
similarity index 100%
rename from docs/scrum4me-personas.md
rename to docs/personas.md
diff --git a/docs/plans/M10-qr-pairing-login.md b/docs/plans/M10-qr-pairing-login.md
index eef1dcc..0778073 100644
--- a/docs/plans/M10-qr-pairing-login.md
+++ b/docs/plans/M10-qr-pairing-login.md
@@ -7,8 +7,8 @@ Inloggen op een (publieke) desktop zonder wachtwoord: desktop toont QR, telefoon
 - `desktopToken` reist alleen via HttpOnly cookie `s4m_pair` met `Path=/api/auth/pair`, `Max-Age=120`, `SameSite=Lax`
 - Twee gescheiden hashes in DB scheiden mobiel-bewijs (`secret_hash`) van desktop-bewijs (`desktop_token_hash`)
 
-Backlog-entries: zie [scrum4me-backlog.md § M10](../scrum4me-backlog.md#m10-password-loze-inlog-via-qr-pairing).
-Functional spec: zie [scrum4me-functional-spec.md § F-01b](../scrum4me-functional-spec.md#f-01b-inloggen-via-mobiel-qr-pairing).
+Backlog-entries: zie [backlog.md § M10](../backlog.md#m10-password-loze-inlog-via-qr-pairing).
+Functional spec: zie [functional.md § F-01b](../functional.md#f-01b-inloggen-via-mobiel-qr-pairing).
 
 **Implementatie-volgorde** (commit-strategy uit CLAUDE.md):
 
@@ -652,7 +652,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
 - De `session.isDemo` check overneemt: als de approver een demo-user is — wat ST-1005 al blokkeert — komen we hier niet eens, maar `is_demo` doorzetten is een extra vangnet.
 
 **Verificatie**
-- Handmatig: na approve in mobiele tab, POST naar `/api/auth/pair/claim` met de cookie van start → 200 + `Set-Cookie: scrum4me-session=...`
+- Handmatig: na approve in mobiele tab, POST naar `/api/auth/pair/claim` met de cookie van start → 200 + `Set-Cookie: session=...`
 - `curl -X POST` zonder cookie → 401
 - Tweede claim → 410
 
@@ -767,7 +767,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
     <QrLoginButton />
     ```
 
-    MD3-tokens uit `docs/scrum4me-styling.md`; geen willekeurige Tailwind-kleuren.
+    MD3-tokens uit `docs/styling.md`; geen willekeurige Tailwind-kleuren.
 
 4. **A11y**: QR-component krijgt `aria-label="QR-code voor mobiel inloggen"` en de URL wordt visueel als kopieer-bare tekst onder de QR getoond zodat screenreaders en gebruikers met cameraproblemen de URL handmatig kunnen openen.
 
@@ -788,17 +788,17 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
 ## ST-1008 — Documentatie + acceptatietest
 
 **Bestanden**
-- `docs/API.md` — drie nieuwe endpoints
-- `docs/scrum4me-architecture.md` — sectie "QR-pairing flow" + threat-model
+- `docs/api.md` — drie nieuwe endpoints
+- `docs/architecture.md` — sectie "QR-pairing flow" + threat-model
 - `docs/patterns/qr-login.md` — nieuw pattern-doc
 - `CLAUDE.md` — verwijzing naar het pattern-doc in de patterns-tabel
 - `__tests__/integration/qr-pairing-e2e.test.ts` — optioneel, alleen als de test-infra het toelaat
 
 **Stappen**
 
-1. **`docs/API.md`** — drie endpoints documenteren met request/response, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`. Voeg een sectie *"Cookie-mechaniek"* toe die uitlegt dat `s4m_pair` een tijdelijke pre-auth cookie is, anders dan de iron-session cookie.
+1. **`docs/api.md`** — drie endpoints documenteren met request/response, foutcodes (400/401/403/404/410/422/429), curl-voorbeelden inclusief `--cookie-jar`. Voeg een sectie *"Cookie-mechaniek"* toe die uitlegt dat `s4m_pair` een tijdelijke pre-auth cookie is, anders dan de iron-session cookie.
 
-2. **`docs/scrum4me-architecture.md`** — sectie *"QR-pairing flow"* met:
+2. **`docs/architecture.md`** — sectie *"QR-pairing flow"* met:
     - Sequence-diagram (mermaid of ASCII analoog aan M8)
     - Threat-model:
         - **Replay**: atomic `updateMany` met `status='approved'` voorkomt dubbele claim
@@ -826,7 +826,7 @@ ST-1006 staat bij de API-laag (niet bij UI) omdat het een Route Handler is; ST-1
     7. **Secret niet in access logs** — controleer Vercel runtime-logs (via `mcp__a1fa0fcf-…__get_runtime_logs`) en lokale dev-logs; zoek op de secret-string en op `s=`-substrings; verwacht: 0 hits
 
 **Aandachtspunten**
-- Zorg dat de runtime-logs MCP-controle in `docs/scrum4me-test-plan.md` belandt zodat hij bij elke release herhaalbaar is.
+- Zorg dat de runtime-logs MCP-controle in `docs/test-plan.md` belandt zodat hij bij elke release herhaalbaar is.
 - `docs/patterns/qr-login.md` mag refereren naar bestaande pattern-docs (iron-session, route-handler) zonder ze te dupliceren.
 
 **Verificatie**
@@ -857,7 +857,7 @@ feat(ST-1005): add mobile pair confirmation page with hash-fragment client islan
 feat(ST-1006): add /api/auth/pair/claim with atomic consume
 chore(ST-1007): add qrcode.react dependency
 feat(ST-1007): add QR login button on /login with SSE listener
-docs(ST-1008): document QR-pairing endpoints in API.md
+docs(ST-1008): document QR-pairing endpoints in api.md
 docs(ST-1008): add QR-pairing flow and threat-model to architecture
 docs(ST-1008): add qr-login pattern doc
 ```
diff --git a/docs/plans/M11-claude-questions.md b/docs/plans/M11-claude-questions.md
index ce5ce90..f485f4d 100644
--- a/docs/plans/M11-claude-questions.md
+++ b/docs/plans/M11-claude-questions.md
@@ -4,7 +4,7 @@ Persistent vraag-antwoord-kanaal tussen Claude Code (via MCP) en de actieve Scru
 
 Eerste concrete uitwerking van strategische **richting B** (verdiepen van de unieke AI-driven dev-flow).
 
-Backlog-entries: zie [scrum4me-backlog.md § M11](../scrum4me-backlog.md#m11-claude-vraagt-gebruiker-antwoordt) (op te leveren in ST-1108).
+Backlog-entries: zie [backlog.md § M11](../backlog.md#m11-claude-vraagt-gebruiker-antwoordt) (op te leveren in ST-1108).
 
 **Beveiligingsuitgangspunten:**
 - Atomic answer via `updateMany WHERE status='open'` — concurrent dubbele submit kan niet
@@ -279,7 +279,7 @@ Backlog-entries: zie [scrum4me-backlog.md § M11](../scrum4me-backlog.md#m11-cla
 
 **Aandachtspunten**
 - Bell-icon en avatar moeten visueel balanceren — hoogte/padding gelijktrekken
-- MD3-tokens uit `docs/scrum4me-styling.md`: badge `bg-error text-error-foreground` voor critical-count, `bg-primary` voor neutraal. Geen willekeurige Tailwind-kleuren
+- MD3-tokens uit `docs/styling.md`: badge `bg-error text-error-foreground` voor critical-count, `bg-primary` voor neutraal. Geen willekeurige Tailwind-kleuren
 - Optimistic-answer in store: voor het Server Action-resultaat zet item op pending; bij error rollback met sonner-error-toast
 - Sheet-content blijft open zodat de user meerdere vragen achter elkaar kan beantwoorden (zelfde patroon als ST-358 openstaande-stories-sheet)
 - ARIA: bell-icon heeft `aria-label="Notificaties — N open vragen"`, badge `role="status"`
@@ -369,18 +369,18 @@ Backlog-entries: zie [scrum4me-backlog.md § M11](../scrum4me-backlog.md#m11-cla
 ## ST-1108 — Documentatie + acceptatietest
 
 **Bestanden**
-- `docs/API.md` — secties "SSE — Notifications" + "Cron — Expire questions"
-- `docs/scrum4me-architecture.md` — sectie "Vraag-antwoord-kanaal" met sequence-diagram
+- `docs/api.md` — secties "SSE — Notifications" + "Cron — Expire questions"
+- `docs/architecture.md` — sectie "Vraag-antwoord-kanaal" met sequence-diagram
 - `docs/patterns/claude-question-channel.md` — herbruikbaar pattern-doc
-- `docs/scrum4me-backlog.md` — M11-tabel-rij + M11-sectie
+- `docs/backlog.md` — M11-tabel-rij + M11-sectie
 - `prisma/seed-data/parse-backlog.ts` — `M11: 'ACTIVE'`, `M10: 'COMPLETED'`, `M3.5: 'COMPLETED'`
 - `CLAUDE.md` — pattern-doc verwijzing in Implementatiepatronen-tabel
 
 **Stappen**
 
-1. Backlog-tabel-rij + M11-sectie in `docs/scrum4me-backlog.md` (mirror M10-format met **Implementatieplan:** verwijzing naar dit doc)
+1. Backlog-tabel-rij + M11-sectie in `docs/backlog.md` (mirror M10-format met **Implementatieplan:** verwijzing naar dit doc)
 
-2. `docs/scrum4me-architecture.md` § "Vraag-antwoord-kanaal":
+2. `docs/architecture.md` § "Vraag-antwoord-kanaal":
    - Mermaid sequence-diagram: Claude → MCP → DB → trigger → SSE → user → Server Action → DB → trigger → polling-tool
    - Threat-model-tabel (replay, demo-block, access-leak, expiry, race)
    - "Waarom hergebruik scrum4me_changes-kanaal" sub-sectie
@@ -430,7 +430,7 @@ feat(ST-1105): add NotificationsBell + Sheet + AnswerModal
 chore(ST-1107): add CRON_SECRET to env schema
 feat(ST-1107): add /api/cron/expire-questions handler
 feat(ST-1107): wire vercel.ts cron entry
-docs(ST-1108): document notifications SSE + cron in API.md
+docs(ST-1108): document notifications SSE + cron in api.md
 docs(ST-1108): add vraag-antwoord-kanaal flow to architecture
 docs(ST-1108): add claude-question-channel pattern doc
 chore(ST-1108): backlog M11 + parser ACTIVE-flip
diff --git a/docs/plans/M9-active-product-backlog.md b/docs/plans/M9-active-product-backlog.md
index 9a79a80..af818b5 100644
--- a/docs/plans/M9-active-product-backlog.md
+++ b/docs/plans/M9-active-product-backlog.md
@@ -2,7 +2,7 @@
 
 Eén "actief Product Backlog" per gebruiker, persistent op `User.active_product_id`. NavBar wordt: Producten | Product Backlog | Sprint | Solo | Todo's. Zonder actief PB zijn Backlog/Sprint/Solo disabled. Sprint is alleen klikbaar als er een sprint met status `ACTIVE` bestaat. Vervangt de bestaande `last_product`-cookieflow.
 
-Backlog-entries: zie [scrum4me-backlog.md § M9](../scrum4me-backlog.md#m9-actief-product-backlog).
+Backlog-entries: zie [backlog.md § M9](../backlog.md#m9-actief-product-backlog).
 
 ---
 
diff --git a/docs/plans/ST-1110-demo-readonly.md b/docs/plans/ST-1110-demo-readonly.md
index 5cca907..68513e1 100644
--- a/docs/plans/ST-1110-demo-readonly.md
+++ b/docs/plans/ST-1110-demo-readonly.md
@@ -52,7 +52,7 @@ Drie-laagse bescherming:
 | ST-1110.5 | `feat(ST-1110.5)` | 12 component/pagina-bestanden |
 | ST-1110.5 tests | `test(ST-1110.5)` | `__tests__/api/pair-claim.test.ts`, `__tests__/api/pair-start.test.ts` |
 | ST-1110.6 | `test(ST-1110.6)` | `__tests__/proxy/demo-guard.test.ts` |
-| ST-1110.7 | `docs(ST-1110.7)` | `docs/scrum4me-architecture.md`, dit bestand |
+| ST-1110.7 | `docs(ST-1110.7)` | `docs/architecture.md`, dit bestand |
 
 ## Aandachtspunten toekomstige stories
 
diff --git a/docs/plans/Tweede Claude Agent — Planning Agent.md b/docs/plans/tweede-claude-agent-planning.md
similarity index 96%
rename from docs/plans/Tweede Claude Agent — Planning Agent.md
rename to docs/plans/tweede-claude-agent-planning.md
index 7775d60..5d3cada 100644
--- a/docs/plans/Tweede Claude Agent — Planning Agent.md	
+++ b/docs/plans/tweede-claude-agent-planning.md
@@ -202,10 +202,10 @@ Korte prompt-flow:
 1. `wait_for_job({ accept_kinds: ['PLANNING'], wait_seconds: 600 })` — claim
 2. Lees `planning_target` uit response (PBI of STORY) + `existing_*`
 3. **Lees lokale docs uit Scrum4Me-checkout:**
-   - `docs/scrum4me-functional-spec.md` (functioneel kader)
-   - `docs/scrum4me-architecture.md` (technisch kader)
+   - `docs/functional.md` (functioneel kader)
+   - `docs/architecture.md` (technisch kader)
    - `docs/patterns/*.md` (relevante patterns op basis van target-titel/-beschrijving)
-   - `docs/scrum4me-styling.md` als target UI-werk betreft
+   - `docs/styling.md` als target UI-werk betreft
 4. Bedenk children:
    - Voor `STORY`-target: 3-7 taken met titel, korte beschrijving, `implementation_plan` (verwijst naar relevante patterns + bestanden), priority
    - Voor `PBI`-target: 2-5 stories met titel, beschrijving in user-story-format, acceptance_criteria, priority
@@ -251,10 +251,10 @@ MCP-tools testen in `scrum4me-mcp` repo (aparte PR).
 | `components/backlog/pbi-list.tsx` | MODIFY | Status-pill op pbi-card |
 | `components/shared/planning-job-pill.tsx` | NEW | Generic pill-component |
 | `docs/patterns/claude-agent-roles.md` | NEW | Pattern-doc: één table, kind-enum, accept_kinds-arg, lokale agent-prompts |
-| `docs/scrum4me-architecture.md` | MODIFY | Sectie "Claude Agents" uitbreiden — twee rollen, schema, queue, prompts |
-| `docs/scrum4me-pbi-dialog.md` | MODIFY | Sectie "Speciale gedragingen → Planning-trigger" toevoegen |
-| `docs/scrum4me-story-dialog.md` | MODIFY | Idem |
-| `docs/scrum4me-task-dialog.md` | MODIFY | Vermelden dat tasks ook door planning-agent kunnen ontstaan |
+| `docs/architecture.md` | MODIFY | Sectie "Claude Agents" uitbreiden — twee rollen, schema, queue, prompts |
+| `docs/pbi-dialog.md` | MODIFY | Sectie "Speciale gedragingen → Planning-trigger" toevoegen |
+| `docs/story-dialog.md` | MODIFY | Idem |
+| `docs/task-dialog.md` | MODIFY | Vermelden dat tasks ook door planning-agent kunnen ontstaan |
 | `__tests__/actions/claude-jobs-planning.test.ts` | NEW | |
 | `__tests__/lib/claude-job-status.test.ts` | MODIFY | `kind`-mapping testen |
 | `__tests__/api/realtime-solo-planning.test.ts` | NEW | |
diff --git a/docs/scrum4me-product-backlog.md b/docs/product-backlog.md
similarity index 100%
rename from docs/scrum4me-product-backlog.md
rename to docs/product-backlog.md
diff --git a/docs/solo-paneel-spec.md b/docs/solo-paneel-spec.md
index 949776c..ec21f5b 100644
--- a/docs/solo-paneel-spec.md
+++ b/docs/solo-paneel-spec.md
@@ -4,7 +4,7 @@
 >
 > **Scope v1:** geen REVIEW-status, geen multi-product aggregatie, geen taak-level overrides. Story-level assignment volstaat. Desktop-first conform ST-606 — onder 1024px tonen we dezelfde "te smal scherm"-melding als de rest van de app.
 >
-> **Versie:** v2 — verwerkt antwoorden uit `scrum4me-backlog.md` over sessie-flag, bestaande Server Actions en desktop-first scope.
+> **Versie:** v2 — verwerkt antwoorden uit `backlog.md` over sessie-flag, bestaande Server Actions en desktop-first scope.
 
 ---
 
diff --git a/docs/scrum4me-story-dialog.md b/docs/story-dialog.md
similarity index 98%
rename from docs/scrum4me-story-dialog.md
rename to docs/story-dialog.md
index 250dec0..1b11d59 100644
--- a/docs/scrum4me-story-dialog.md
+++ b/docs/story-dialog.md
@@ -159,5 +159,5 @@ Specifiek voor StoryDialog (boven op de algemene out-of-scope-lijst in `docs/pat
 - `components/markdown.tsx` — gedeelde markdown-wrapper
 - `lib/task-status.ts` — status-enum-mapper
 - `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
-- `docs/scrum4me-architecture.md` — datamodel `Story`
-- `docs/scrum4me-styling.md` — MD3-tokens, status- en priority-kleuren
+- `docs/architecture.md` — datamodel `Story`
+- `docs/styling.md` — MD3-tokens, status- en priority-kleuren
diff --git a/docs/scrum4me-styling.md b/docs/styling.md
similarity index 100%
rename from docs/scrum4me-styling.md
rename to docs/styling.md
diff --git a/docs/scrum4me-task-dialog.md b/docs/task-dialog.md
similarity index 97%
rename from docs/scrum4me-task-dialog.md
rename to docs/task-dialog.md
index c2ecca1..49d1f91 100644
--- a/docs/scrum4me-task-dialog.md
+++ b/docs/task-dialog.md
@@ -122,6 +122,6 @@ Specifiek voor TaskDialog (boven op de algemene out-of-scope-lijst in `docs/patt
 ## Referenties
 
 - `docs/patterns/dialog.md` — generieke spec (bron-of-truth voor alles wat hier niet beschreven is)
-- `docs/scrum4me-architecture.md` — datamodel `Task`
-- `docs/scrum4me-styling.md` — MD3-tokens, status- en priority-kleuren
+- `docs/architecture.md` — datamodel `Task`
+- `docs/styling.md` — MD3-tokens, status- en priority-kleuren
 - `lib/task-status.ts` — enum-mapper DB ↔ API
diff --git a/docs/scrum4me-test-plan.md b/docs/test-plan.md
similarity index 100%
rename from docs/scrum4me-test-plan.md
rename to docs/test-plan.md

From 289bcf9bf004bdf3f280dc6ddc59e1eb06dfae3e Mon Sep 17 00:00:00 2001
From: Janpeter Visser <30029041+madhura68@users.noreply.github.com>
Date: Sun, 3 May 2026 03:01:06 +0200
Subject: [PATCH 17/17] =?UTF-8?q?Phase=203=20=E2=80=94=20Move=20docs=20int?=
 =?UTF-8?q?o=20topical=20folders=20(#60)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(taxonomy): scaffold topical folders under docs/

Create empty folder structure: architecture/, specs/, specs/dialogs/,
design/, api/, runbooks/, decisions/, backlog/, qa/, assets/ — each
with a .gitkeep so git tracks the directories.

* docs(taxonomy): add placeholder comment to .gitkeep files
---
 docs/api/.gitkeep           | 1 +
 docs/architecture/.gitkeep  | 1 +
 docs/assets/.gitkeep        | 1 +
 docs/backlog/.gitkeep       | 1 +
 docs/decisions/.gitkeep     | 1 +
 docs/design/.gitkeep        | 1 +
 docs/qa/.gitkeep            | 1 +
 docs/runbooks/.gitkeep      | 1 +
 docs/specs/.gitkeep         | 1 +
 docs/specs/dialogs/.gitkeep | 1 +
 10 files changed, 10 insertions(+)
 create mode 100644 docs/api/.gitkeep
 create mode 100644 docs/architecture/.gitkeep
 create mode 100644 docs/assets/.gitkeep
 create mode 100644 docs/backlog/.gitkeep
 create mode 100644 docs/decisions/.gitkeep
 create mode 100644 docs/design/.gitkeep
 create mode 100644 docs/qa/.gitkeep
 create mode 100644 docs/runbooks/.gitkeep
 create mode 100644 docs/specs/.gitkeep
 create mode 100644 docs/specs/dialogs/.gitkeep

diff --git a/docs/api/.gitkeep b/docs/api/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/api/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/architecture/.gitkeep b/docs/architecture/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/architecture/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/assets/.gitkeep b/docs/assets/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/assets/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/backlog/.gitkeep b/docs/backlog/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/backlog/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/decisions/.gitkeep b/docs/decisions/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/decisions/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/design/.gitkeep b/docs/design/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/design/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/qa/.gitkeep b/docs/qa/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/qa/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/runbooks/.gitkeep b/docs/runbooks/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/runbooks/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/specs/.gitkeep b/docs/specs/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/specs/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added
diff --git a/docs/specs/dialogs/.gitkeep b/docs/specs/dialogs/.gitkeep
new file mode 100644
index 0000000..94f7de9
--- /dev/null
+++ b/docs/specs/dialogs/.gitkeep
@@ -0,0 +1 @@
+# placeholder — remove when first file is added