docs(cleanup): archief verouderde plannen, backlog en root-duplicaten (#191)

* docs(cleanup): archief verouderde plannen, backlog en root-duplicaten - 6 plans naar docs/old/plans/ (PBI-11/75/78, user-settings-store, Local github setup, lees-de-readme — laatste was verkeerde repo) - docs/backlog/ naar docs/old/backlog/ (pre-MCP statische registry; live werk loopt via Scrum4Me-MCP) - 6 root-level duplicaten naar docs/old/ (functional, {pbi,story,task}-dialog, product-backlog, backlog) - 2 landing plans (niet uitgevoerd) krijgen archived: true frontmatter — blijven op plek maar uit INDEX - scripts/generate-docs-index.mjs: skip docs/old/** + skip archived: true - CLAUDE.md: rijen docs/backlog/, docs/plans/<key>-*.md, docs/manual/ weg; Track B-sectie verwijderd - README.md / CHANGELOG.md / docs/plans/v1-readiness.md: link-fixes naar nieuwe locaties Verify groen (lint + typecheck + 718 tests). docs/INDEX.md geregenereerd. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(cleanup): registreer handmatige verplaatsingen en fix referenties - 4 plans verplaatst naar docs/old/plans/ (M10-qr-pairing-login, auto-pr-deploy-sync, docs-restructure-ai-lookup, v1-readiness) - 3 archive-plans verplaatst naar docs/old/plans/ (archive-map nu leeg) - ST-1114-copilot-reviews + 3 research-docs naar nieuwe docs/Ideas/ map - Duplicaat docs/old/2026-04-27-m8-realtime-solo.md verwijderd (origineel zit in docs/old/plans/) - Link-fixes naar nieuwe locaties: - CHANGELOG.md → docs/old/plans/v1-readiness.md - docs/runbooks/deploy-control.md → docs/old/plans/auto-pr-deploy-sync.md (2x) - docs/runbooks/worker-idempotency.md → docs/old/plans/auto-pr-deploy-sync.md - docs/plans/docs-restructure-pbi-spec.md → docs/old/plans/docs-restructure-ai-lookup.md (4x text + 2x href) - docs/INDEX.md geregenereerd (96 docs, was 100) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 19:46:00 +02:00 · 2026-05-11 19:46:00 +02:00 · b39c3ec2e1
commit b39c3ec2e1
parent d587be2fb3
36 changed files with 1068 additions and 49 deletions
--- a/docs/Ideas/ST-1114-copilot-reviews.md
+++ b/docs/Ideas/ST-1114-copilot-reviews.md
@ -0,0 +1,142 @@
+---
+title: "ST-1114 — Copilot reviews op dashboard"
+status: active
+audience: [maintainer, contributor]
+language: nl
+last_updated: 2026-05-03
+applies_to: [ST-1114]
+---
+
+# 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)
--- a/docs/Ideas/ai-driven-scrum-planning-research.md
+++ b/docs/Ideas/ai-driven-scrum-planning-research.md
@ -0,0 +1,306 @@
+---
+title: "Onderzoek — AI-gedreven programmeren en Scrum planning"
+status: draft
+audience: [product, ai-agent]
+language: nl
+last_updated: 2026-05-11
+---
+
+# Onderzoek — AI-gedreven programmeren en Scrum planning
+
+## Vraag
+
+Wat is het effect van AI-assisted / AI-driven programming op de manier waarop we Scrum toepassen, als werk niet meer in 1-2 weekse sprints hoeft te worden gepland maar in meerdere uitvoercycli per dag kan worden gerealiseerd? Wat gebeurt er met burndown, velocity en planning als tokengebruik, verificatie en agent-efficiency belangrijker worden?
+
+## Korte conclusie
+
+AI maakt Scrum niet overbodig, maar verandert waar Scrum op moet sturen.
+
+Traditionele sprintplanning gebruikt vaak velocity/story points als proxy voor menselijke uitvoercapaciteit. In AI-gedreven ontwikkeling wordt menselijke typ-/bouwtijd veel minder voorspelbaar als bottleneck. De nieuwe bottlenecks zijn:
+
+- helderheid van productbeslissingen;
+- kwaliteit van backlog-items en acceptatiecriteria;
+- beschikbare context voor agents;
+- verificatiecapaciteit: tests, review, security, deploy;
+- tokenkosten en modelkeuze;
+- rework door foutieve of half-passende AI-output.
+
+Daarom moet planning verschuiven van "hoeveel story points kunnen we in twee weken doen?" naar "welke waardevolle hypothese kunnen we nu veilig laten uitvoeren, verifieren en leren, binnen een token- en reviewbudget?"
+
+## Wat de bronnen laten zien
+
+### 1. Het empirische bewijs is gemengd
+
+Onderzoek naar Copilot liet in een gecontroleerde programmeertaak zien dat deelnemers met Copilot de taak 55,8% sneller voltooiden. Een latere Microsoft-studie met drie field experiments bij 4.867 developers vond gemiddeld 26,08% meer voltooide taken bij developers met AI-code-completion.
+
+Tegelijk vond METR in 2025 in een realistische RCT met ervaren open-source developers dat AI-tools taken juist 19% langzamer maakten. De taken waren echte issues in grote codebases die developers goed kenden. METR waarschuwt zelf tegen te brede generalisatie, maar het resultaat is belangrijk: AI-snelheid hangt sterk af van taaktype, codebase-context, kwaliteitslat en meetmethode. In 2026 gaf METR bovendien aan dat het meten van AI-uplift lastiger wordt doordat developers liever niet meer zonder AI werken en doordat sommige developers meerdere agents tegelijk gebruiken.
+
+Implicatie: Scrum4Me moet geen vaste productiviteitsfactor aannemen. Meet per product, per agent-run en per taaktype.
+
+### 2. DORA: AI is een versterker, geen oplossing
+
+DORA 2025 concludeert dat AI vooral een amplifier is: het versterkt bestaande sterke en zwakke punten. Google rapporteert bijna universele adoptie, veel ervaren individuele productiviteitswinst, maar ook een vertrouwensparadox en complexere effecten op organisatorische performance.
+
+DORA's AI Capabilities Model noemt zeven randvoorwaarden die AI-effecten versterken:
+
+- duidelijke AI-stance/policy;
+- gezonde data-ecosystemen;
+- AI-toegankelijke interne data;
+- sterke version-control-praktijken;
+- kleine batches;
+- user-centric focus;
+- kwalitatieve interne platforms.
+
+Voor Scrum betekent dit: de sprint moet niet groter worden omdat agents sneller code schrijven. De batch moet kleiner worden, met scherpere feedback.
+
+### 3. Agile verschuift naar outcome- en governance-gedreven planning
+
+Digital.ai's 18th State of Agile beschrijft AI als een verschuiving van ondersteunende tool naar orchestrator van de delivery lifecycle. Tegelijk noemt het rapport hogere ROI-druk, governance-lag en de noodzaak om Agile-investeringen aan meetbare business outcomes te koppelen.
+
+Implicatie: velocity en burndown zijn onvoldoende als hoofdmetrics. Ze laten activiteit zien, geen waarde, geen kosten en geen risico.
+
+### 4. Tokengebruik wordt economisch relevant, maar is geen doel op zichzelf
+
+Stanford Digital Economy Lab vond in 2026 dat agentic coding tasks veel token-intensiever zijn dan code chat/reasoning, dat inputtokens de kosten domineren, dat runs op dezelfde taak tot 30x kunnen verschillen in tokengebruik, en dat meer tokens niet automatisch meer accuracy opleveren.
+
+Jellyfish analyseerde 12.000 developers bij 200 bedrijven en vond dat meer tokengebruik wel met meer output correleert, maar disproportioneel duurder wordt. De topgebruikers haalden ongeveer twee keer zoveel PR-throughput, maar met ongeveer tien keer zoveel tokens per PR.
+
+Implicatie: tokenusage is een cost/efficiency-signaal, geen prestatiebadge. "Tokenmaxxing" is net zo gevaarlijk als velocity maximaliseren.
+
+## Wat verandert aan Scrum?
+
+### Sprint
+
+De Sprint blijft nuttig als container voor focus, inspectie en adaptatie. Maar bij AI-gedreven werk is een sprint minder een capaciteitsmandje voor menselijke arbeid en meer een beslis- en leerhorizon.
+
+Advies:
+
+- Gebruik "Sprint" voor productfocus en Sprint Goal.
+- Gebruik "AI runs" of "execution cycles" binnen de sprint voor 1-4 uitvoercycli per dag.
+- Noem 4 cycli per dag liever geen 4 Scrum-sprints, tenzij je ook echt 4 keer Sprint Planning, Review en Retrospective wilt doen. Dat levert ceremonie-overhead op.
+
+### Sprint Planning
+
+Planning verschuift van effort forecast naar control loop.
+
+Oude vraag:
+
+- Hoeveel werk kunnen we deze sprint doen?
+
+Nieuwe vraag:
+
+- Welke waardevolle slice is klaar voor agent-uitvoering?
+- Welke context en tests maken het veilig?
+- Welk model/mode/budget past bij risico en complexiteit?
+- Hoe weten we binnen 30-120 minuten of dit goed genoeg is?
+- Wat is de maximale token- en reviewspend voor deze poging?
+
+### Daily Scrum
+
+Daily Scrum wordt minder statusmeeting en meer flow-control:
+
+- Welke agent-runs zijn afgerond, geblokkeerd of failed?
+- Waar zit de verificatiequeue?
+- Welke Product Owner-beslissing ontbreekt?
+- Welke context ontbreekt waardoor tokens of rework oplopen?
+- Moeten we scope heronderhandelen zonder het Sprint Goal te beschadigen?
+
+Bij 4 runs per dag kan een korte "run review" na elke run de Daily Scrum deels vervangen.
+
+### Sprint Review
+
+Review wordt frequenter en meer outcome-gericht:
+
+- Wat is echt geaccepteerd en bruikbaar?
+- Welke hypothese is gevalideerd?
+- Wat is alleen code-output maar nog geen waarde?
+- Welke user feedback of runtime data hebben we?
+
+### Retrospective
+
+Retrospective moet expliciet AI-systemen verbeteren:
+
+- Welke prompts, contextbestanden of specs verminderden rework?
+- Welke modelkeuzes waren te duur of te zwak?
+- Waar faalden tests/reviews te laat?
+- Welke taken waren slecht voorbereid voor agents?
+- Waar waren menselijke beslissingen de bottleneck?
+
+## Nieuwe planningshiërarchie
+
+Een praktisch model voor Scrum4Me:
+
+| Laag | Cadans | Doel | Output |
+|---|---:|---|---|
+| Product Goal / roadmap | weken-maanden | richting en waarde | product outcomes, prioriteiten |
+| Sprint | 1 dag tot 1 week | focus en leerdoel | Sprint Goal, selected PBIs/stories, budget |
+| AI execution run | 1-3 uur | concrete slice bouwen/verifieren | PR/diff, testresultaat, token/cost telemetry |
+| Agent job | minuten-uren | taak uitvoeren | logs, patch, status, vragen |
+
+Voor solo/kleine teams met Scrum4Me is een dag-sprint of week-sprint met meerdere AI runs realistischer dan 4 volledige Scrum-sprints per dag.
+
+## Nieuwe metrics
+
+### Behoud, maar herinterpreteer
+
+- Lead time: idee/story -> geaccepteerde productie-wijziging.
+- Cycle time: taak/run start -> done.
+- Deployment frequency.
+- Change failure rate.
+- MTTR.
+- Escaped defects.
+
+Deze blijven belangrijker dan velocity.
+
+### Vervang velocity als hoofdmetric
+
+Velocity/story points kunnen nog gespreksmateriaal zijn voor complexiteit en onzekerheid, maar niet meer als centrale capaciteitsmetric.
+
+Betere hoofdmetrics:
+
+- accepted increments per dag/week;
+- validated outcomes per week;
+- lead time per PBI/story;
+- verification queue time;
+- change failure rate na AI-runs;
+- rework rate na review;
+- human intervention rate;
+- agent first-pass success rate.
+
+### Voeg token-economie toe
+
+Nuttige tokenmetrics:
+
+- tokens per accepted task;
+- tokens per merged PR;
+- tokens per validated outcome;
+- tokens per failed/abandoned run;
+- input/output/cache-token mix;
+- cost per accepted task;
+- cost per defect fixed;
+- review minutes per 1M tokens;
+- token spend by model/mode/job-kind;
+- wasted tokens: output niet gebruikt, failed loops, repeated context discovery.
+
+Belangrijke waarschuwing: tokens zijn een input-cost, geen output-value. Gebruik ze als budget en efficiency-signaal, niet als score.
+
+### Nieuwe samengestelde metric
+
+Voor Scrum4Me zou een nuttige metric kunnen zijn:
+
+```text
+AI Delivery Efficiency =
+  accepted value units
+  / (token cost + human review time + elapsed time + rework penalty)
+```
+
+In de praktijk kan dit simpeler:
+
+```text
+accepted_tasks_per_euro
+accepted_tasks_per_1M_tokens
+merged_PRs_per_review_hour
+validated_outcomes_per_day
+```
+
+## Definition of Ready voor AI
+
+Een story/task is AI-ready als:
+
+- het gewenste gedrag concreet is;
+- acceptatiecriteria testbaar zijn;
+- relevante files, patronen en docs bekend of vindbaar zijn;
+- non-goals en scopegrenzen expliciet zijn;
+- risico duidelijk is: laag/middel/hoog;
+- vereiste verificatie bekend is;
+- tokenbudget/model/mode is gekozen;
+- open productvragen zijn beantwoord of expliciet buiten scope gezet.
+
+## Definition of Done voor AI
+
+Done betekent niet "agent heeft code geschreven". Done betekent:
+
+- diff/PR is geaccepteerd;
+- tests/lint/typecheck/build passend bij risico zijn groen;
+- security/privacy/demo-mode checks zijn gedaan waar relevant;
+- menselijke review is gedaan voor risicovolle of user-facing wijzigingen;
+- tokenusage/cost is gelogd;
+- rework/lessons zijn teruggekoppeld naar prompt, docs of backlog;
+- productwaarde is zichtbaar of meetbaar.
+
+## Voorstel voor Scrum4Me planning
+
+### 1. Sprint als focuscontainer
+
+Maak een sprint niet langer primair een verzameling werk voor 1-2 weken, maar een focuscontainer:
+
+- Sprint Goal;
+- geselecteerde PBI's/stories;
+- AI-run budget;
+- verificatie-WIP-limiet;
+- risico-policy.
+
+### 2. AI Runs binnen de sprint
+
+Voeg of gebruik een concept als `SprintRun`:
+
+- `PLANNED -> RUNNING -> VERIFYING -> ACCEPTED | REWORK | FAILED | ABANDONED`
+- gekoppelde `ClaudeJob`s / agent jobs;
+- model/mode snapshot;
+- tokenbudget en werkelijk tokengebruik;
+- affected stories/tasks;
+- testresultaat;
+- reviewbeslissing.
+
+### 3. Planningproces per run
+
+1. Selecteer een kleine slice uit de Sprint Backlog.
+2. Controleer AI-ready criteria.
+3. Kies model/mode/tokenbudget.
+4. Start agent jobs.
+5. Verzamel patch, logs, testresultaten en tokenusage.
+6. Verifieer.
+7. Accepteer, stuur terug voor rework, of stop de run.
+8. Update backlog en metrics.
+
+### 4. Dashboard-shift
+
+Vervang klassieke burndown als primaire grafiek door:
+
+- token burnup vs accepted outcomes;
+- verification queue;
+- accepted/rework/failed runs;
+- lead time distribution;
+- cost per accepted task;
+- change failure / rollback rate;
+- remaining uncertainty per Sprint Goal.
+
+Burndown kan blijven als "remaining selected stories/tasks", maar niet als performance-meter.
+
+## Productimplicaties voor Scrum4Me
+
+1. Voeg token/cost telemetry toe aan `ClaudeJob` en `SprintRun`.
+2. Maak AI-run planning zichtbaar op de Sprint-pagina.
+3. Voeg `AI Ready` checks toe aan story/task dialogs of een planning pane.
+4. Maak verification WIP expliciet: niet meer agents starten dan je kunt verifieren.
+5. Voeg budgetrails toe: per sprint, per run, per task, per model.
+6. Rapporteer tokenusage altijd naast outcome: token-only dashboards sturen verkeerd gedrag.
+7. Maak retrospectives data-driven: prompt/context/model/test-strategie verbeteren.
+
+## Bronnen
+
+- Scrum Guide 2020 — Sprint Planning, Sprint Backlog, Sprint Goal: https://scrumguides.org/scrum-guide.html
+- Microsoft Research — GitHub Copilot controlled experiment: https://www.microsoft.com/en-us/research/publication/the-impact-of-ai-on-developer-productivity-evidence-from-github-copilot/
+- Microsoft Research — three field experiments, 4.867 developers: https://www.microsoft.com/en-us/research/publication/the-effects-of-generative-ai-on-high-skilled-work-evidence-from-three-field-experiments-with-software-developers/
+- METR 2025 — experienced open-source developer RCT: https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/
+- METR 2026 — measurement redesign and concurrent-agent measurement issues: https://metr.org/blog/2026-02-24-uplift-update/
+- DORA 2025 — State of AI-assisted Software Development: https://dora.dev/research/2025/dora-report/
+- Google Research publication page for DORA 2025: https://research.google/pubs/dora-2025-state-of-ai-assisted-software-development-report/
+- Google Cloud — DORA AI Capabilities Model: https://cloud.google.com/blog/products/ai-machine-learning/introducing-doras-inaugural-ai-capabilities-model/
+- Google blog summary of DORA 2025: https://blog.google/innovation-and-ai/technology/developers-tools/dora-report-2025/
+- Digital.ai — 18th State of Agile press release: https://digital.ai/press-releases/digital-ais-18th-state-of-agile-report-marks-the-start-of-the-fourth-wave-of-software-delivery/
+- Stanford Digital Economy Lab — token consumption in agentic coding tasks: https://digitaleconomy.stanford.edu/publication/how-do-ai-agents-spend-your-money-analyzing-and-predicting-token-consumption-in-agentic-coding-tasks/
+- GitHub Docs — Copilot usage metrics: https://docs.github.com/en/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics/copilot-usage-metrics
+- Jellyfish — tokenmaxxing and token ROI analysis: https://jellyfish.co/blog/is-tokenmaxxing-cost-effective-new-data-from-jellyfish-explains/
+- Microsoft Research — LLM metric framework and token utilization: https://www.microsoft.com/en-us/research/articles/how-to-evaluate-llms-a-complete-metric-framework/
+
--- a/docs/Ideas/beelink-scrum4me-server-install-and-worker-plan.md
+++ b/docs/Ideas/beelink-scrum4me-server-install-and-worker-plan.md
@ -0,0 +1,605 @@
+---
+title: "Installatieplan — Beelink Ubuntu Scrum4Me server en worker-aanpassingen"
+status: draft
+audience: [maintainer, operator, ai-agent]
+language: nl
+last_updated: 2026-05-10
+---
+
+# Installatieplan — Beelink Ubuntu Scrum4Me server en worker-aanpassingen
+
+## Doel
+
+Deze notitie beschrijft de huidige Beelink-installatie en het vervolgplan om de Scrum4Me workers geschikt te maken voor drie rollen:
+
+```text
+worker-idea
+worker-implementation
+worker-orchestrator
+```
+
+De server draait nu als LAN-host voor Scrum4Me. Productie-internettoegang met domein en HTTPS is nog een latere stap.
+
+## Hardware
+
+| Onderdeel | Waarde |
+|---|---|
+| Machine | Beelink mini-PC |
+| CPU | Intel Core i5-12450H |
+| RAM zichtbaar in Ubuntu | 16 GB |
+| Max RAM volgens hardware | 32 GB |
+| Disk | 468 GB bruikbaar na Ubuntu-installatie |
+| IP | `192.168.0.154` |
+
+Opmerking: Ubuntu ziet momenteel ongeveer 16 GB RAM. De hardware meldt een maximum van 32 GB, maar dat betekent niet dat 32 GB bruikbaar/geplaatst is.
+
+## Huidige Installatie
+
+### Ubuntu
+
+Ubuntu Server is geïnstalleerd op de hele disk.
+
+Belangrijke keuzes:
+
+- Ubuntu Server 24.04 LTS.
+- Geen Ubuntu Desktop.
+- Geen LVM.
+- Geen aparte GPU-drivers.
+- Geen Windows dual boot meer.
+- Hostname: `scrum4me-server`.
+- Sleep/hibernate uitgeschakeld.
+- Swapfile vergroot naar 16 GB.
+
+Controle:
+
+```bash
+hostnamectl
+free -h
+swapon --show
+df -h
+```
+
+### Directorystructuur
+
+Alle service-data staat onder:
+
+```text
+/srv/scrum4me
+```
+
+Structuur:
+
+```text
+/srv/scrum4me/postgres       database data
+/srv/scrum4me/repos          GitHub clones
+/srv/scrum4me/worker-cache   worker caches
+/srv/scrum4me/worker-logs    worker logs
+/srv/scrum4me/worker-state   worker state
+/srv/scrum4me/backups        Postgres backups
+/srv/scrum4me/compose        Docker Compose files
+/srv/scrum4me/caddy          Caddy config/data
+```
+
+### Docker
+
+Docker Engine draait native op Ubuntu.
+
+Controle:
+
+```bash
+docker run hello-world
+docker compose version
+```
+
+### Postgres
+
+Postgres draait als Docker container:
+
+```text
+container: scrum4me-postgres
+image: postgres:17
+```
+
+Host mapping:
+
+```text
+127.0.0.1:5432 -> postgres:5432
+```
+
+Host-app gebruikt:
+
+```env
+DATABASE_URL="postgresql://scrum4me:<password>@127.0.0.1:5432/scrum4me"
+DIRECT_URL="postgresql://scrum4me:<password>@127.0.0.1:5432/scrum4me"
+```
+
+Containers gebruiken:
+
+```env
+DATABASE_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
+DIRECT_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
+```
+
+DB-test:
+
+```bash
+docker exec -e PGPASSWORD="$DBPASS" scrum4me-postgres \
+  psql -h 127.0.0.1 -U scrum4me -d scrum4me \
+  -c "select current_user, current_database();"
+```
+
+### Scrum4Me Web
+
+Repo:
+
+```text
+/srv/scrum4me/repos/Scrum4Me
+```
+
+Build:
+
+```bash
+cd /srv/scrum4me/repos/Scrum4Me
+rm -rf .next
+npm run build
+```
+
+Runtime:
+
+```text
+systemd service: scrum4me-web
+```
+
+Service startcommand:
+
+```bash
+npm run start -- -H 0.0.0.0
+```
+
+Controle:
+
+```bash
+systemctl status scrum4me-web --no-pager
+curl -I http://127.0.0.1:3000/login
+```
+
+### Caddy
+
+Caddy draait als Docker container:
+
+```text
+container: scrum4me-caddy
+```
+
+Caddy reverse proxyt:
+
+```text
+http://192.168.0.154 -> Caddy -> 172.18.0.1:3000 -> Scrum4Me web
+```
+
+Caddyfile:
+
+```caddyfile
+:80 {
+  reverse_proxy 172.18.0.1:3000
+}
+```
+
+Controle:
+
+```bash
+curl -I http://192.168.0.154/login
+docker logs --tail=50 scrum4me-caddy
+```
+
+### LAN Session Config
+
+Omdat de server nu via HTTP op LAN draait, is secure session cookie tijdelijk uitgezet.
+
+Env:
+
+```env
+SESSION_COOKIE_SECURE="false"
+```
+
+Code-aanpassing:
+
+```ts
+secure: process.env.SESSION_COOKIE_SECURE === 'true',
+```
+
+Later, bij domein + HTTPS:
+
+```env
+SESSION_COOKIE_SECURE="true"
+```
+
+Daarna:
+
+```bash
+rm -rf .next
+npm run build
+sudo systemctl restart scrum4me-web
+```
+
+### Migrations
+
+De database is gemigreerd.
+
+Belangrijke migration-notitie:
+
+`20260506101436_restore_todos_table` kan op een bestaande DB falen met:
+
+```text
+relation "todos" already exists
+```
+
+Voor deze server is de juiste aanpak:
+
+```bash
+npx prisma migrate resolve --applied 20260506101436_restore_todos_table
+npx prisma migrate deploy
+```
+
+Controle:
+
+```bash
+npx prisma migrate status
+docker exec -it scrum4me-postgres psql -U scrum4me -d scrum4me -c "\dt public.users"
+```
+
+### Admin en Product
+
+Admin user is aangemaakt via:
+
+```bash
+npx tsx scripts/create-admin.ts janpeter '<password>'
+```
+
+Login werkt.
+
+Product aanmaken werkt.
+
+### Backups
+
+Backup-script:
+
+```text
+/srv/scrum4me/backup-postgres.sh
+```
+
+Script:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+BACKUP_DIR="/srv/scrum4me/backups"
+STAMP="$(date +%Y%m%d-%H%M%S)"
+FILE="$BACKUP_DIR/scrum4me-$STAMP.sql.gz"
+
+mkdir -p "$BACKUP_DIR"
+
+docker exec scrum4me-postgres pg_dump -U scrum4me scrum4me | gzip > "$FILE"
+
+find "$BACKUP_DIR" -type f -name 'scrum4me-*.sql.gz' -mtime +14 -delete
+
+echo "backup written: $FILE"
+```
+
+Test:
+
+```bash
+/srv/scrum4me/backup-postgres.sh
+ls -lh /srv/scrum4me/backups
+```
+
+Cron:
+
+```cron
+15 3 * * * /srv/scrum4me/backup-postgres.sh >> /srv/scrum4me/backups/backup.log 2>&1
+```
+
+## Worker-Idea Installatie
+
+Worker compose-service:
+
+```text
+worker-idea
+container: scrum4me-worker-idea
+health: http://127.0.0.1:18081/health
+```
+
+Belangrijke env-waarden:
+
+```env
+SCRUM4ME_BASE_URL=http://caddy
+SCRUM4ME_TOKEN=<raw Scrum4Me API token>
+
+DATABASE_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
+DIRECT_URL=postgresql://scrum4me:<password>@postgres:5432/scrum4me
+
+GH_TOKEN=<GitHub token>
+GH_PRECLONE_REPOS=madhura68/Scrum4Me,madhura68/scrum4me-mcp,madhura68/scrum4me-docker
+
+CLAUDE_CODE_OAUTH_TOKEN=<Claude Code OAuth token>
+```
+
+Token-validatie:
+
+```bash
+read -s -p "Scrum4Me token: " TOKEN; echo
+curl -i -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3000/api/products
+unset TOKEN
+```
+
+Verwacht:
+
+```text
+HTTP/1.1 200 OK
+```
+
+Worker health:
+
+```bash
+curl http://127.0.0.1:18081/health
+```
+
+Gezonde idle-output bevat:
+
+```json
+{
+  "status": "idle",
+  "heartbeatAgeSeconds": 1,
+  "consecutiveFailures": 0
+}
+```
+
+## Huidige Worker-Beperking
+
+De Docker worker is gezond, maar Scrum4Me UI toont mogelijk nog:
+
+```text
+geen Claude worker actief
+```
+
+Oorzaak:
+
+- De Docker health-server draait altijd.
+- De daemon-loop draait altijd.
+- Maar de DB-tabel `claude_workers` wordt nu alleen bijgewerkt door de MCP stdio-server.
+- Die MCP stdio-server start pas binnen een echte Claude/MCP job-run.
+- Bij een lege queue is de Docker worker dus idle en gezond, maar verschijnt hij niet als actieve worker in de UI.
+
+Controle:
+
+```bash
+docker exec -it scrum4me-postgres psql -U scrum4me -d scrum4me \
+  -c "select t.id, t.label, w.id as worker_id, w.last_seen_at from api_tokens t left join claude_workers w on w.token_id=t.id order by t.created_at desc;"
+```
+
+Gezonde Docker-worker maar lege presence:
+
+```text
+label       | worker_id | last_seen_at
+worker-idea |           |
+```
+
+## Worker Aanpassingsplan
+
+### Doelrollen
+
+```text
+worker-idea
+  IDEA_GRILL
+  IDEA_MAKE_PLAN
+  PLAN_CHAT
+
+worker-implementation
+  TASK_IMPLEMENTATION
+  SPRINT_IMPLEMENTATION
+  later STORY_IMPLEMENTATION
+
+worker-orchestrator
+  PR_REVIEW
+  CI_TRIAGE
+  MERGE_CONFLICT_RESOLUTION
+  REPAIR_FAILED_JOB
+  CONTEXT_SUMMARY
+```
+
+## Fase 1 — Presence Fix
+
+### Probleem
+
+Worker-health is nu container-lokaal, maar UI-presence is DB-gebaseerd.
+
+Nu:
+
+```text
+curl :18081/health -> online
+claude_workers     -> leeg
+UI                 -> offline
+```
+
+### Gewenst gedrag
+
+Zolang de Docker daemon-loop draait, moet `claude_workers.last_seen_at` vers blijven, ook als de queue leeg is.
+
+### Aanpassing
+
+Verplaats worker-presence naar `scrum4me-docker/bin/run-one-job.ts` of naar een kleine runner-level heartbeat naast `run-agent.sh`.
+
+Aanbevolen: in `run-one-job.ts`, direct na `getAuth()`:
+
+```ts
+const { userId, tokenId } = await getAuth()
+await registerWorker({ userId, tokenId })
+const heartbeat = startHeartbeat({ userId, tokenId, intervalMs: 10_000 })
+```
+
+In `finally`:
+
+```ts
+heartbeat.stop()
+```
+
+Niet unregisteren bij normale idle-exit. Anders gaat de UI-indicator flikkeren tussen iteraties.
+
+### Acceptatie
+
+Bij lege queue:
+
+```bash
+curl http://127.0.0.1:18081/health
+```
+
+toont:
+
+```text
+status idle
+```
+
+En:
+
+```sql
+select token_id, last_seen_at, now() - last_seen_at from claude_workers;
+```
+
+toont een recente `last_seen_at`.
+
+## Fase 2 — Role-Aware Workers
+
+### Probleem
+
+De huidige worker claimt elke job die beschikbaar is. Daardoor kan `worker-idea` ook implementation jobs claimen.
+
+### Nieuwe env
+
+```env
+SCRUM4ME_WORKER_ROLE=idea
+```
+
+Toegestane waarden:
+
+```text
+idea
+implementation
+orchestrator
+```
+
+### Claimfilter
+
+`tryClaimJob` krijgt een role/capability-filter.
+
+Mapping:
+
+```text
+idea:
+  IDEA_GRILL
+  IDEA_MAKE_PLAN
+  PLAN_CHAT
+
+implementation:
+  TASK_IMPLEMENTATION
+  SPRINT_IMPLEMENTATION
+
+orchestrator:
+  PR_REVIEW
+  CI_TRIAGE
+  MERGE_CONFLICT_RESOLUTION
+  REPAIR_FAILED_JOB
+  CONTEXT_SUMMARY
+```
+
+### Acceptatie
+
+Test:
+
+- Queue bevat één `IDEA_GRILL` en één `TASK_IMPLEMENTATION`.
+- Alleen `worker-idea` actief: claimt alleen `IDEA_GRILL`.
+- Alleen `worker-implementation` actief: claimt alleen `TASK_IMPLEMENTATION`.
+- Beide actief: ieder claimt eigen jobtype.
+
+## Fase 3 — DB/UI Uitbreiding
+
+Breid `claude_workers` uit met:
+
+```text
+role
+worker_name
+container_name
+last_status
+last_job_id
+last_error
+```
+
+UI toont dan:
+
+```text
+Idea worker            online / idle
+Implementation worker  offline
+Orchestrator           online / idle
+```
+
+## Fase 4 — Orchestrator Jobs
+
+Nieuwe job kinds:
+
+```text
+PR_REVIEW
+CI_TRIAGE
+MERGE_CONFLICT_RESOLUTION
+REPAIR_FAILED_JOB
+CONTEXT_SUMMARY
+```
+
+Orchestrator mag:
+
+- PR's inspecteren.
+- CI-fouten samenvatten.
+- Merge conflicts analyseren.
+- Repair jobs aanmaken.
+- Context capsules schrijven.
+- Human escalation vragen.
+- Draft PR naar ready begeleiden.
+
+Orchestrator mag niet:
+
+- Vrij featurewerk implementeren.
+- Dezelfde branch tegelijk wijzigen als implementation-worker.
+- Auto-mergen zonder checks.
+- Secrets of tokens loggen.
+
+## Fase 5 — Deployment
+
+Na code-aanpassing:
+
+```bash
+cd /srv/scrum4me/repos/scrum4me-docker
+git pull
+cd /srv/scrum4me/compose
+docker compose build worker-idea
+docker compose up -d --force-recreate worker-idea
+```
+
+Checks:
+
+```bash
+curl http://127.0.0.1:18081/health
+docker logs -f scrum4me-worker-idea
+docker exec -it scrum4me-postgres psql -U scrum4me -d scrum4me \
+  -c "select token_id, last_seen_at from claude_workers;"
+```
+
+## Aanbevolen Volgorde Vanaf Nu
+
+1. Test één `IDEA_GRILL` job met de huidige worker.
+2. Implementeer Fase 1: runner-level presence.
+3. Rebuild `worker-idea`.
+4. Verifieer UI online/idle bij lege queue.
+5. Implementeer Fase 2: role-aware claiming.
+6. Voeg `worker-implementation` toe.
+7. Voeg pas daarna `worker-orchestrator` toe.
+
+Niet meteen drie workers starten zonder role-aware claimfilter.
--- a/docs/Ideas/sprint-page-backlog-relationship-research.md
+++ b/docs/Ideas/sprint-page-backlog-relationship-research.md
@ -0,0 +1,135 @@
+---
+title: "Advies — Product Backlog en Sprint-pagina workflow"
+status: draft
+audience: [product, ai-agent]
+language: nl
+last_updated: 2026-05-11
+---
+
+# Advies — Product Backlog en Sprint-pagina workflow
+
+## Aanleiding
+
+Het bestaande plan `dit-verhaal-gaat-over-dazzling-mccarthy.md` beschrijft een nieuwe Product Backlog-workflow waarin sprint-membership via vinkjes wordt beheerd. De vraag is hoe de Sprint-pagina daarop moet aansluiten, met als doel om de huidige sprint verder samen te stellen.
+
+## Korte conclusie
+
+Maak de Product Backlog-pagina de brede plek voor backlog-refinement en sprint-scope selectie, en maak de Sprint-pagina de werkomgeving voor de huidige sprint: scope bijstellen, volgorde bepalen, taken uitwerken, assignees zetten, capaciteit bewaken en afronden.
+
+De twee pagina's mogen dezelfde onderliggende membership-acties gebruiken, maar ze moeten niet dezelfde primaire UI dupliceren. De Product Backlog is de product-brede selectie- en overzichtslaag. De Sprint-pagina is de sprint-specifieke uitwerkingslaag.
+
+## Verhouding tussen de pagina's
+
+| Pagina | Primaire vraag | Scope | Hoofdhandeling |
+|---|---|---|---|
+| Product Backlog `/products/[id]` | Wat is waardevol, wat is klaar, wat hoort bij welke sprint? | Alle PBI's/stories van het product | Refinen, ordenen, nieuwe sprintdraft maken, sprint-membership bulk selecteren |
+| Sprint-pagina `/products/[id]/sprint/[sprintId]` | Hoe maken we deze sprint uitvoerbaar en af? | Een gekozen sprint | Sprint Backlog ordenen, stories aanvullen/verwijderen, taken maken, eigenaarschap/capaciteit/voortgang beheren |
+
+## Aanbevolen workflow
+
+1. Product Backlog zonder actieve sprint: klassieke refinement-view zonder vinkjes.
+2. Product Backlog met nieuwe sprintdraft: metadata invullen, PBI's/stories selecteren via vinkjes, sprint aanmaken.
+3. Product Backlog met actieve sprint: product-breed zien welke PBI's/stories in de sprint zitten en membership in batches aanpassen.
+4. Sprint-pagina: huidige sprint verder samenstellen en uitvoeren. Het middenpaneel is de waarheid voor de huidige Sprint Backlog. Het backlogpaneel is alleen toevoer/context.
+
+## Consequenties voor de Sprint-pagina
+
+Aanbevolen aanpassing:
+
+- Header toont Sprint Goal, dates, status, switcher, scope-dirty teller en afronden-flow.
+- Linkerpaneel hernoemen van `Product Backlog` naar iets als `Aanvullen uit backlog`; standaard filter op eligible stories: `OPEN`, niet `DONE`, geen andere `OPEN` sprint.
+- Middenpaneel blijft `Sprint Backlog`: geselecteerde stories, sortering, assignee, task-progress, remove.
+- Rechterpaneel blijft `Taken`: taakdecompositie, taakvolgorde, status, implementatieplan.
+- Membership-mutaties op de Sprint-pagina gebruiken dezelfde serveractie als de Product Backlog: `commitSprintMembershipAction(activeSprintId, adds, removes)`.
+- Scopewijzigingen zijn pending/dirty tot `Scope opslaan (N)`. Story/task-field edits blijven direct opslaan.
+- Cross-sprint conflicts tonen als disabled story met tooltip. Server blijft autoritatief.
+- Na start van een sprint markeer je add/remove visueel als scopewijziging, omdat dat gevolgen heeft voor burndown/rapportage.
+
+Wat je juist niet moet doen:
+
+- Geen tweede volledige PBI-tri-state bulkselectie bouwen op de Sprint-pagina. Dat hoort op de Product Backlog.
+- Geen aparte sprint-membership semantiek naast het plan. `story.sprint_id` blijft unit-of-truth.
+- Geen nieuwe afrondactie. De bestaande `completeSprintAction` blijft de sprint-completion-flow.
+
+## Andere methoden uit websearch
+
+### 1. Scrum Guide: why / what / how
+
+De Scrum Guide beschrijft Sprint Planning als drie onderwerpen: waarom is deze sprint waardevol, wat kan deze sprint gedaan worden, en hoe wordt het gekozen werk gedaan. De Sprint Backlog bestaat uit Sprint Goal, geselecteerde PBIs en een uitvoerbaar plan.
+
+Impliceert voor Scrum4Me:
+
+- Product Backlog-pagina: vooral `what`.
+- Sprint-pagina: vooral `how`, plus gecontroleerde bijstelling van `what`.
+
+Bron: https://scrumguides.org/scrum-guide.html
+
+### 2. Jira-methode: sprints plannen vanuit backlog, board voor active sprint
+
+Jira plant sprints op het Backlog-scherm. De backlog toont werk gegroepeerd in backlog en sprints; items kunnen naar sprints worden gesleept. Na start verschijnt de sprint op het board. Jira waarschuwt ook dat add/remove in een actieve sprint scope change is.
+
+Impliceert voor Scrum4Me:
+
+- De richting van het plan is marktconform: sprint-samenstelling vanuit de backlog.
+- De Sprint-pagina mag scope aanpassen, maar moet dat als scopewijziging behandelen.
+
+Bronnen:
+
+- https://support.atlassian.com/jira-software-cloud/docs/use-your-scrum-backlog/
+- https://support.atlassian.com/jira-software-cloud/docs/enable-sprints/
+- https://support.atlassian.com/jira-software-cloud/docs/plan-a-sprint/
+
+### 3. Azure Boards-methode: eerst items toewijzen, daarna capaciteit checken
+
+Azure Boards beschrijft sprintplanning in twee delen: eerst backlog items selecteren, daarna bepalen hoe het team ontwikkelt/test, taken definiëren en capaciteit controleren. Azure toont geplande effort en capaciteit om onder- of overbelasting zichtbaar te maken.
+
+Impliceert voor Scrum4Me:
+
+- Voeg op de Sprint-pagina een lichte capacity/forecast-strip toe zodra story points, effort of taakminuten beschikbaar zijn.
+- Laat de Sprint-pagina na selectie vooral helpen met taakdecompositie en load balancing.
+
+Bronnen:
+
+- https://learn.microsoft.com/en-us/azure/devops/boards/sprints/assign-work-sprint
+- https://learn.microsoft.com/en-us/azure/devops/boards/sprints/adjust-work
+
+### 4. Backlog refinement als aparte continue praktijk
+
+Atlassian beschrijft refinement als doorlopend reviewen, rangschikken en verduidelijken van de Product Backlog zodat Sprint Planning soepeler loopt.
+
+Impliceert voor Scrum4Me:
+
+- Houd refinement-controls op de Product Backlog: PBI/story details, status, priority, split/merge later.
+- Maak de Sprint-pagina niet de primaire plek voor product-brede refinement.
+
+Bron: https://www.atlassian.com/agile/scrum/backlog-refinement
+
+### 5. Linear cycles / Scrumban-achtige methode
+
+Linear cycles zijn time-boxed perioden met een vooraf bepaalde set werk, inclusief automatiseringen zoals rollover en auto-add van actieve issues. Dit is minder strikt Scrum, maar nuttig voor solo/kleine teams.
+
+Impliceert voor Scrum4Me:
+
+- Eventueel later: optionele automation "carry over unfinished stories to next sprint".
+- Niet als basis voor de huidige Scrum4Me-flow, omdat Scrum4Me al Sprint Goal, Sprint Backlog en completion-semantiek heeft.
+
+Bron: https://linear.app/docs/use-cycles
+
+## Aanbevolen ontwerpkeuze
+
+Kies voor een hybride die dicht bij Scrum/Jira/Azure ligt:
+
+- Product Backlog = refinement + sprint-scope bulkselectie.
+- Sprint-pagina = huidige sprint afmaken: ordenen, decomponeren, capaciteit en uitvoering.
+- Eén gedeelde membership-laag in code: dezelfde conflictregels, task cascade, statusmutaties en affected-id returns.
+
+Dit houdt het mentale model simpel: je kunt overal zien wat in de sprint zit, maar elke pagina heeft een eigen reden om te bestaan.
+
+## Implementatie-notities
+
+1. Hergebruik `commitSprintMembershipAction` op de Sprint-pagina voor add/remove.
+2. Vervang directe `addStoryToSprintAction` / `removeStoryFromSprintAction` in `SprintBoardClient` geleidelijk door een pending scope-buffer, of laat ze intern dezelfde transactiesemantiek gebruiken als tijdelijke tussenstap.
+3. Fix bij die refactor ook task-cascade consistentie: remove moet `task.sprint_id = null` zetten voor taken onder verwijderde stories.
+4. Gebruik de nieuwe `cross-sprint-blocks` en `sprint-membership-summary` endpoints ook op de Sprint-pagina, maar gescoped op zichtbare PBI's.
+5. Voeg later capacity toe als aparte story, niet als voorwaarde voor de eerste workflow-migratie.
+