feat(PBI-74): Zustand product-workspace rearchitecture (Stories 1-8) (#180)

* feat(PBI-74): product-workspace store skelet + test-infra (Story 1) Skelet voor de nieuwe `product-workspace-store` die op termijn de gefragmenteerde `backlog-store`/`planner-store`/`selection-store`/`product-store` vervangt. Deze PR levert alleen het skelet + tests; UI-consumers worden in latere stories omgezet. - vitest naar jsdom + tests/setup.ts (MemoryStorage, default fetch-stub) — G6/G8 - stores/product-workspace/{types,store,selectors,restore}.ts — immer-middleware, alle slices en acties (hydrate, setActive*, ensure*Loaded met activeRequestId- guard, applyRealtimeEvent, resyncActiveScopes/loadedScopes, optimistic mutations). Restore-wiring in setters volgt in Story 4 (T-857/T-858). - selectors gebruiken module-level EMPTY refs (G1) en documenteren useShallow- vereiste (G2) - 34 nieuwe unit-tests dekken §Testing setup-checklist uit het ontwerp: hydrateSnapshot, selection-cascade, applyRealtimeEvent (I/U/D + parent-move + ander-product + unknown-entity → resync), delete-cleanup, race-safe loaders, ensureTaskLoaded _detail-flag, resyncActiveScopes ensure-keten, restore-hints read/write/clear, optimistic mutation rollback/settle/SSE-echo idempotent - docs/api/rest-contract.md: audit-sectie met de vier ontbrekende ensure*Loaded-endpoints (worden toegevoegd in Story 7 / T-870) Refs: PBI-74, ST-1318, T-837..T-843 Bron-ontwerp: docs/plans/zustand-store-rearchitecture.md Implementatieplan: docs/plans/zustand-workspace-store-implementation.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-74): dual-dispatch hydratie + realtime naar workspace-store (Story 2) Story 2 — schaduw-fase: BacklogHydrationWrapper en useBacklogRealtime voeden nu ook de nieuwe product-workspace-store, terwijl de oude useBacklogStore / useProductStore leidend blijft voor componenten. Story 3 verschuift consumers één voor één; Story 8 ruimt de oude stores op. - T-844: BacklogHydrationWrapper roept naast useBacklogStore.setInitialData ook useProductWorkspaceStore.hydrateSnapshot aan. Productname-prop optioneel toegevoegd voor activeProduct-context. - T-845: useBacklogRealtime onmessage dispatcht events naar zowel oude store (applyChange) als nieuwe store (applyRealtimeEvent). Geen wijziging aan reconnect/visibility — Story 5. - T-846: dev-only logWorkspaceFingerprint helper vergelijkt counts tussen oude en nieuwe store na hydrate en na elk realtime-event. console.warn bij mismatch; opt-in debug log via NEXT_PUBLIC_DEBUG_WORKSPACE_FINGERPRINT=1. Bestand TODO-marked voor verwijdering in Story 8 (T-878). - T-847: SetCurrentProduct schrijft naast oude useProductStore ook useProductWorkspaceStore.setActiveProduct({id, name}); cleanup cleart beide. setActiveProduct triggert ensureProductLoaded — fetch-stub tot Story 7 (T-870) de LIST-endpoints toevoegt. Verify: lint+typecheck clean, 636/636 tests groen (geen UI-regressie omdat oude store leidend blijft). Refs: PBI-74, ST-1319, T-844..T-847 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-74): migreer backlog-componenten naar workspace-store (Story 3) Story 3 verplaatst alle UI-consumers van de oude vier stores (useBacklogStore/usePlannerStore/useSelectionStore/useProductStore) naar de nieuwe product-workspace-store. De oude stores blijven nog bestaan voor hydration-wrapper en realtime-hook (dual-dispatch); Story 8 ruimt ze op. - T-848 backlog-split-pane.tsx: leest activePbiId/activeStoryId uit context-slice (primitives, geen useShallow nodig). - T-849 pbi-list.tsx: selectVisiblePbis(useShallow); DnD via applyOptimisticMutation('pbi-order' + optionele 'entity-patch' bij cross-priority drag), met settle/rollback per server-result. - T-850 story-panel.tsx: selectStoriesForActivePbi(useShallow); DnD via applyOptimisticMutation('story-order' + entity-patch bij priority change). - T-851 task-panel.tsx: selectTasksForActiveStory(useShallow); DnD via applyOptimisticMutation('task-order'); detail-view (ensureTaskLoaded + isDetail) zit in de task-dialog (apart component, niet in deze lijst). - T-852 start-sprint-button.tsx: selectActivePbi + selectStoriesForActivePbi voor free-story count. - T-853 set-current-product.tsx: alleen workspace-store.setActiveProduct (oude useProductStore-import verwijderd). - T-854 G1/G2-audit: alle nieuwe selectors gebruiken module-level EMPTY refs (G1) en useShallow voor lijsten (G2). Geen 'Maximum update depth'- warnings tijdens npm test. - T-855 tests bijgewerkt: backlog-split-pane.test, task-panel.test, integration.test gebruiken nu setState op workspace-store (helpers resetWorkspace/setActiveStoryAndTasks/selectPbi/selectStory). Verify: lint+typecheck clean, 636/636 tests groen. UI-consumers van oude stores zijn nu nul (uitgezonderd dual-dispatch in hydration-wrapper en realtime-hook + dev-fingerprint-helper, die in Story 8/T-873/T-878 verdwijnen). Refs: PBI-74, ST-1320, T-848..T-855 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-74): race-safe loaders + restore-hints + URL-prioriteit (Story 4) - T-856: activeRequestId-guard zat al in store.ts uit Story 1; bevestigd door de race-safety test (in-flight ensurePbiLoaded mag niet overschrijven). - T-857: restore-hint flow toegevoegd in setActiveProduct/setActivePbi/ setActiveStory. Async chain: await ensureXxxLoaded → guard check → readHints → valideer hint via entities.byId → setActiveYyy(hint). Geen setTimeout-trick — chain is alleen await-based. - T-858: writeProductHint/writePbiHint/writeStoryHint/writeTaskHint aangeroepen direct na set(...) zodat de hint-persistentie altijd consistent is met de in-store selectie. - T-859: nieuwe components/backlog/url-task-sync.tsx — leest ?editTask=<id> uit useSearchParams, schrijft de hint en roept setActiveTask aan zodat de URL wint boven een eerder gepersisteerde task-hint. Gemount in beide product-pages (desktop + mobile) binnen BacklogHydrationWrapper. - T-860: 6 nieuwe vitest-cases — 4 voor hint-persist per setter, 2 voor de restore-flow chain (hint die niet in entities zit wordt genegeerd; hint die wel in entities zit wordt toegepast). Bestaande race-safety test blijft groen. Verify: lint+typecheck clean, 642/642 tests groen. Refs: PBI-74, ST-1321, T-856..T-860 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-74): hidden-tab + reconnect resync (Story 5) Per ontwerp samen in één commit zodat geen vangnet wegvalt zonder vervanging. - T-861: useBacklogRealtime sluit niet meer op visibilitychange hidden; EventSource blijft open zolang browser/netwerk dit toelaten. Reconnect bij netwerkfout blijft via backoff. visibilitychange fungeert nog wel als re-connect-trigger als de stream tussentijds is gesloten (b.v. 240s hard-close server-side). - T-862: 'ready'-event-handler telt connect-cycles. De eerste 'ready' is de initial connect (geen resync). Bij latere 'ready' (post-reconnect) wordt resyncActiveScopes('reconnect') aangeroepen om gemiste events op te halen. - T-863: nieuwe lib/realtime/use-workspace-resync.ts — luistert op document.visibilitychange (hidden→visible) en window.online; dispatcht resyncActiveScopes('visible') resp. 'reconnect'. Mounted in BacklogHydrationWrapper na useBacklogRealtime. - T-864: 4 nieuwe vitest-cases voor useWorkspaceResync (jsdom): visible→ visible event, online event, hidden negeren, cleanup-bij-unmount. Daarnaast lint-cleanup: ongebruikte 'order'-variabelen in pbi-list en story-panel weggehaald. Verify: lint+typecheck clean, 646/646 tests groen. Refs: PBI-74, ST-1322, T-861..T-864 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-74): unknown-event fallback tests (Story 6) T-865 (isUnknownEntityEvent filter) en T-866 (resync-trigger in applyRealtimeEvent) zijn al in Story 1 geïmplementeerd in store.ts; deze story breidt de test-coverage uit met expliciete negatieve cases voor het type-veld noise pattern. T-867 — 5 nieuwe vitest-cases: - unknown entity met ANDER product_id → geen resync - claude_job_status (type) → geen resync - worker_heartbeat (type) → geen resync - claude_job_enqueued (type) → geen resync - payload zonder entity en zonder type → genegeerd - question-entity (entity-veld, geen type, niet pbi/story/task) → resync trigger Verify: lint+typecheck clean, 651/651 tests groen. Refs: PBI-74, ST-1323, T-865..T-867 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-74): cache-headers + LIST endpoints (Story 7) - T-868: cache: 'no-store' was al ingebouwd in fetchJson helper (Story 1). Bevestigd door bestaande ensureProductLoaded test die de fetch-init controleert. - T-869: force-dynamic toegevoegd op alle vier nieuwe LIST-endpoints. - T-870: vier nieuwe routes voor ensure*Loaded: - GET /api/products/:id/backlog → ProductBacklogSnapshot - GET /api/pbis/:id/stories → BacklogStory[] - GET /api/stories/:id/tasks → BacklogTask[] - GET /api/tasks/:id (nieuwe handler naast bestaande PATCH) → TaskDetail met _detail: true marker Auth via authenticateApiRequest (Bearer of iron-session); access-control via productAccessFilter (gebruiker is owner of member van het product). Statussen worden via taskStatusToApi/storyStatusToApi/pbiStatusToApi vertaald naar lowercase API-vorm. - T-871: SSE-route /api/realtime/backlog stuurt al ready-event direct na LISTEN (regel 106) — geen wijziging nodig. Verify: lint+typecheck clean, 651/651 tests groen. Refs: PBI-74, ST-1324, T-868..T-871 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-74): oude stores opruimen (Story 8) Workspace-store is nu de enige bron voor product-backlog client-state. De vier voorgangers en de dual-dispatch-infrastructuur zijn verwijderd. - T-872: grep over codebase op useBacklogStore/usePlannerStore/ useSelectionStore/useProductStore is leeg. - T-873..T-876: stores/{backlog,planner,selection,product}-store.ts deleted. - T-877: __tests__/realtime/payload-contract.test.ts en __tests__/api/backlog-realtime.test.ts deleted — pbi/story/task I|U|D payload-handling wordt al gedekt door __tests__/stores/product-workspace/store.test.ts (incl. parent-move, idempotent inserts, delete-cleanup). - T-878: lib/realtime/dev-workspace-fingerprint.ts deleted, dual-dispatch uit BacklogHydrationWrapper en lib/realtime/use-backlog-realtime.ts weggehaald. stores/products-store.ts (lijst van producten ≠ active product) blijft ongewijzigd. Bijwerkingen: - BacklogPbi en BacklogStory types in components/backlog/story-panel.tsx en components/sprint/sprint-backlog.tsx krijgen sort_order zodat ze met de workspace-types overeenkomen. - Server-pages /products/[id]/page.tsx (desktop+mobile) en /products/[id]/sprint/[sprintId]/page.tsx selecteren sort_order op story en mappen het door in de hydration-payload. Verify: lint+typecheck clean, 626/626 tests groen (verlies van 25 redundante oude-store tests; workspace-store tests dekken hetzelfde gedrag). Refs: PBI-74, ST-1325, T-872..T-878 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(PBI-74): richtlijn workspace-store + realtime patroon Documenteert het patroon dat in Stories 1-8 is opgeleverd, zodat een volgende workspace-store (sprint, of een nieuwe bounded context) hetzelfde recept volgt. - docs/patterns/workspace-store.md (nieuw): wanneer een workspace-store, de vijf state-slices, selectors-regels (G1/G2), race-safe ensure*Loaded met activeRequestId-guard (G4), SSE-hook + applyRealtimeEvent met unknown-event filter, hidden-tab + reconnect resync via useWorkspaceResync, restore-hint flow met await-chain en URL-prioriteit, optimistic mutations (applyOptimisticMutation/rollback/settle), API endpoint-vereisten (force-dynamic, cache: no-store), test-setup met MemoryStorage + originalActions snapshot + mockImplementation, gotchas G1-G8 als comment-template, en het 8-staps migratiepad. - docs/patterns/zustand-optimistic.md: bijgewerkt voor de nieuwe workspace-store API; verwijst voor het bredere patroon naar workspace-store.md. Voorbeelden voor pbi-order + entity-patch. - CLAUDE.md: patterns quickref aangevuld met workspace-store-rij. Verify: typecheck clean. Refs: PBI-74 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(PBI-74): solo + notifications hooks volgen ook hidden-tab/resync patroon Het uitgangspunt van PBI-74 (robuust tegen gemiste SSE-events, hidden tabs en onbekende notify-vormen) gold universeel — niet alleen voor product-workspace. use-solo-realtime en use-notifications-realtime hadden nog dezelfde bug die use-backlog-realtime in Story 5 al opgelost kreeg: sluit stream op hidden, geen resync. Reproductie (zoals gemeld): solo-screen open in tab A, product-backlog open in tab B; bewerk task-title in tab B → tab A's solo-SSE was gesloten (hidden) en kreeg het NOTIFY-event nooit. Tab terug naar solo → EventSource reconnect maar geen resync → oude title persisteert. Postgres NOTIFY heeft geen replay, dus zonder resync zijn die events permanent verloren. Fix in beide hooks (zelfde patroon als Story 5 voor backlog): - Stream blijft open op visibilitychange hidden — geen close() meer. - Bij hidden→visible én bij window 'online': router.refresh() zodat de server-component opnieuw fetcht en de initial-state-prop ververst (wat voor solo de tasks-record reset via initTasks; voor notifications de questions-bel-state). - Bij latere 'ready'-events na reconnect (use-solo-realtime): zelfde router.refresh() trigger zodat we niet vertrouwen op alleen het visibility-pad. Verify: lint + typecheck clean, 626/626 tests groen. Refs: PBI-74 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: fix broken links in research-repo plan docs/plans/lees-de-readme-md-validated-book.md beschrijft een research- repo migratiepad. De links waren geschreven vanuit het research-repo- perspectief (paden als stores/data-store.ts, ../Scrum4Me/CLAUDE.md, docs/plans/zustand-store-rearchitecture.md zonder relative-prefix), wat de doc-link-checker hier laat falen. - Header-note toegevoegd dat het document voor de research-repo is. - Interne refs (zustand-store-rearchitecture.md, CLAUDE.md) → relatieve paden die in deze repo wél resolven (./zustand-..., ../../CLAUDE.md). - Research-repo-only refs (stores/data-store.ts, hooks/use-event-stream.ts, components/*-select.tsx, etc.) → inline code-tags met "(research-repo)" suffix; de link-checker slaat ze over en de leesbaarheid blijft. Verify: npm run docs:check-links → ✓ All doc links valid (118 files). --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-10 02:25:19 +02:00 · 2026-05-10 02:25:19 +02:00 · 5df04feb11
commit 5df04feb11
parent 0d126695db
46 changed files with 3736 additions and 736 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@ -2,7 +2,7 @@

 # Documentation Index

-Auto-generated on 2026-05-09 from front-matter and headings.
+Auto-generated on 2026-05-10 from front-matter and headings.

 ## Architecture Decision Records

@ -62,6 +62,7 @@ Auto-generated on 2026-05-09 from front-matter and headings.
 | [Tweede Claude Agent — Planning Agent](./plans/tweede-claude-agent-planning.md) | proposal | 2026-05-03 |
 | [Scrum4Me — v1.0 readiness](./plans/v1-readiness.md) | active | 2026-05-04 |
 | [Zustand store rearchitecture - active context, realtime en resync](./plans/zustand-store-rearchitecture.md) | ready-to-execute | 2026-05-09 |
+| [Zustand workspace-store implementatieplan (PBI-74)](./plans/zustand-workspace-store-implementation.md) | ready-to-execute | 2026-05-09 |

 ### Archive

@ -89,7 +90,8 @@ Auto-generated on 2026-05-09 from front-matter and headings.
 | [Float sort_order (drag-and-drop volgorde)](./patterns/sort-order.md) | active | 2026-05-03 |
 | [Story met UI-component](./patterns/story-with-ui-component.md) | active | 2026-05-03 |
 | [Web Push](./patterns/web-push.md) | active | 2026-05-07 |
-| [Zustand optimistische update + rollback](./patterns/zustand-optimistic.md) | active | 2026-05-03 |
+| [Workspace-store + realtime — bounded-context patroon](./patterns/workspace-store.md) | active | 2026-05-10 |
+| [Zustand optimistische update + rollback](./patterns/zustand-optimistic.md) | active | 2026-05-10 |

 ## Other Docs

--- a/docs/api/rest-contract.md
+++ b/docs/api/rest-contract.md
@ -527,6 +527,38 @@ curl -X POST -H "Authorization: Bearer $CRON_SECRET" \

 ---

+## Workspace store endpoint audit (PBI-74)
+
+`product-workspace-store` heeft vier `ensure*Loaded`-loaders. Deze tabel
+documenteert welke routes al bestaan en welke in Story 7 (T-870) toegevoegd
+worden. Tot dan retourneert de stub-default in vitest een lege response.
+
+| Loader | URL | Status | Op te leveren in |
+|---|---|---|---|
+| `ensureProductLoaded(productId)` | `GET /api/products/:id/backlog` | **ontbreekt** | T-870 (Story 7) |
+| `ensurePbiLoaded(pbiId)` | `GET /api/pbis/:id/stories` | **ontbreekt** (en `/api/pbis` route-folder bestaat nog niet) | T-870 (Story 7) |
+| `ensureStoryLoaded(storyId)` | `GET /api/stories/:id/tasks` | **ontbreekt** (alleen `tasks/reorder` bestaat) | T-870 (Story 7) |
+| `ensureTaskLoaded(taskId)` | `GET /api/tasks/:id` | **ontbreekt** (alleen `PATCH` bestaat) | T-870 (Story 7) |
+
+Vereisten voor de toe te voegen routes:
+
+- Auth via `authenticateApiRequest` (Bearer-token), conform bestaande patroon.
+- Access-control via `getAccessibleProduct(productId, userId)` uit
+  `lib/product-access.ts` waar de route product-context heeft.
+- `export const dynamic = 'force-dynamic'` zodat Next geen response-cache
+  introduceert (T-869 in Story 7).
+- Response-shape:
+  - `GET /api/products/:id/backlog` → `ProductBacklogSnapshot` (`{ product?, pbis[], storiesByPbi, tasksByStory }`).
+  - `GET /api/pbis/:id/stories` → `BacklogStory[]`.
+  - `GET /api/stories/:id/tasks` → `BacklogTask[]`.
+  - `GET /api/tasks/:id` → `TaskDetail` (extends `BacklogTask` met `_detail: true` plus extra velden zoals `implementation_plan`, `acceptance_criteria`, `requires_opus`, `estimated_minutes`).
+- Type-bron: `stores/product-workspace/types.ts`.
+
+Auth/access-control wijzigt niet — de rearchitecture raakt alleen
+client-state, niet serverlaag-security.
+
+---
+
 ## Voorbeeldworkflow voor Claude Code

 1. **Probe:** `GET /api/health?db=1` — bevestig dat de service en DB bereikbaar zijn.
--- a/docs/patterns/workspace-store.md
+++ b/docs/patterns/workspace-store.md
@ -0,0 +1,414 @@
+---
+title: "Workspace-store + realtime — bounded-context patroon"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-10
+when_to_read: "When adding a new bounded-context client store backed by SSE, or when modifying product/sprint workspace state."
+---
+
+# Patroon: workspace-store + realtime
+
+Sinds PBI-74 is `product-workspace-store` de blueprint voor client-state op een
+**bounded context** (één coherente workflow). Andere bounded contexts mogen
+hetzelfde patroon volgen — `sprint-workspace-store`, `solo-store`,
+`notifications-store`. Dit document beschrijft wanneer je een workspace-store
+opzet, hoe je 'm structureert, hoe SSE en de store samenwerken, en welke
+gotchas in code-comments hoort.
+
+Bron-ontwerp: [zustand-store-rearchitecture.md](../plans/zustand-store-rearchitecture.md).
+Referentie-implementatie: [stores/product-workspace/](../../stores/product-workspace/).
+
+---
+
+## Wanneer een workspace-store
+
+Eén store **per bounded context**, niet per pagina en niet één megastore.
+
+| Workflow | Store |
+|---|---|
+| Product backlog (PBI/story/task selectie + DnD) | `product-workspace-store` |
+| Sprint board | `sprint-workspace-store` (toekomstig, PBI > 74) |
+| Solo execution | `solo-store` |
+| Notifications/questions | `notifications-store` |
+| Idea grill/plan-flow | `idea-store` |
+| Lijst van producten | `products-store` (≠ active product) |
+
+Splits niet per panel; bundel niet over workflows.
+
+---
+
+## State-shape
+
+Vlak en **genormaliseerd**. Vijf slices:
+
+```ts
+{
+  context:    { active*Id }                  // huidige selectie
+  entities:   { *ById }                      // entity-maps per kind
+  relations:  { ids[], idsByParent }         // gesorteerde id-lijsten
+  loading:    { loaded*Ids, activeRequestId } // race-safe markers
+  sync:       { realtimeStatus, lastResyncAt, resyncReason }
+  pendingMutations: { [id]: { mutation, createdAt } }
+}
+```
+
+**Acties** zijn in dezelfde store:
+`hydrateSnapshot`, `setActive*`, `ensure*Loaded`, `applyRealtimeEvent`,
+`resyncActiveScopes`, `resyncLoadedScopes`,
+`applyOptimisticMutation`/`rollbackMutation`/`settleMutation`.
+
+Gebruik `zustand/middleware/immer`. Mutation-style (G3 — return nooit een
+nieuwe state uit een immer-recipe; muteer de draft).
+
+---
+
+## Selectors
+
+Module-level **`EMPTY`**-refs (G1) en `useShallow` voor lijsten (G2).
+
+```ts
+// stores/product-workspace/selectors.ts
+const EMPTY_PBIS: BacklogPbi[] = []
+
+export function selectVisiblePbis(s: Store): BacklogPbi[] {
+  if (s.relations.pbiIds.length === 0) return EMPTY_PBIS
+  return s.relations.pbiIds.map((id) => s.entities.pbisById[id]).filter(Boolean)
+}
+```
+
+```tsx
+// component
+import { useShallow } from 'zustand/react/shallow'
+import { selectVisiblePbis } from '@/stores/product-workspace/selectors'
+
+const pbis = useStore(useShallow(selectVisiblePbis))
+const activePbiId = useStore((s) => s.context.activePbiId) // primitive — geen useShallow
+```
+
+Single-value selectors (`selectActivePbi`) hebben geen `useShallow` nodig.
+
+---
+
+## ensure*Loaded — race-safe loaders
+
+Elke setter genereert een nieuwe `requestId`, schrijft 'm in
+`loading.activeRequestId`, en triggert de loader. De loader checkt **na de
+fetch** of de guard nog matcht — anders bail-out.
+
+```ts
+setActivePbi(pbiId) {
+  const requestId = newRequestId()
+  set((s) => {
+    s.context.activePbiId = pbiId
+    s.context.activeStoryId = null
+    s.context.activeTaskId = null
+    s.loading.activeRequestId = requestId
+  })
+  if (pbiId) void get().ensurePbiLoaded(pbiId, requestId)
+}
+
+async ensurePbiLoaded(pbiId, requestId) {
+  const stories = await fetchJson(`/api/pbis/${pbiId}/stories`)
+  if (requestId && get().loading.activeRequestId !== requestId) return
+  if (!Array.isArray(stories)) return
+  set((s) => { /* apply */ })
+}
+```
+
+**Belangrijke regels:**
+
+- Gebruik `get().method()` per call (G4) — nooit `state.method()` via een
+  gecaptured snapshot. Method-refs zijn niet stabiel over immer state-versies.
+- `fetch(url, { cache: 'no-store' })` op alle client-fetches.
+- Server read-routes: `export const dynamic = 'force-dynamic'`.
+
+---
+
+## SSE-hook beheert transport, store beheert betekenis
+
+```txt
+useXxxRealtime(activeId)
+-> opent /api/realtime/xxx?...
+-> parsed event
+-> dispatcht naar store.applyRealtimeEvent(event)
+-> beheert reconnect/backoff/status
+-> op 'ready' na (re)connect: telt cycles; latere ready triggert resync('reconnect')
+```
+
+```ts
+// applyRealtimeEvent regels
+known pbi/story/task event
+  → upsert + sort, parent-move bij wijziging parent_id
+  → idempotent: bestaande id bij INSERT → return
+  → DELETE → ruim child entities op + clear actieve selectie als die viel
+
+unknown entity met matching product_id, geen 'type' veld
+  → resyncActiveScopes('unknown-event')
+
+job/worker/heartbeat (heeft 'type' veld)
+  → negeer
+```
+
+**Idempotent:** een event dat al via een optimistic mutation is toegepast,
+mag geen dubbele insert of verkeerde rollback veroorzaken. INSERTs checken
+`if (entity exists) return`. UPDATEs zijn altijd merge-into-existing.
+
+Payload-contract: zie [realtime-notify-payload.md](./realtime-notify-payload.md).
+
+---
+
+## Hidden tab + reconnect resync
+
+EventSource blijft open als de tab `hidden` wordt — gemiste events worden
+opgehaald via een expliciete resync-laag.
+
+```ts
+// In de realtime-hook
+const onVisibility = () => {
+  if (document.visibilityState === 'visible' && sourceRef.current === null) {
+    connect() // alleen als de stream weg is (b.v. server hard-close na 240s)
+  }
+}
+// Geen close() bij hidden.
+
+source.addEventListener('ready', () => {
+  readyCountRef.current += 1
+  if (readyCountRef.current > 1) {
+    void store.resyncActiveScopes('reconnect')
+  }
+})
+```
+
+```ts
+// useWorkspaceResync — visibility + online
+useEffect(() => {
+  const onVisibility = () => {
+    if (document.visibilityState === 'visible') {
+      void store.resyncActiveScopes('visible')
+    }
+  }
+  const onOnline = () => void store.resyncActiveScopes('reconnect')
+
+  document.addEventListener('visibilitychange', onVisibility)
+  window.addEventListener('online', onOnline)
+  return () => { /* remove */ }
+}, [])
+```
+
+**Mount in dezelfde wrapper als de realtime-hook.** Doe nooit alleen het
+sluiten-op-hidden weghalen zonder de resync-laag erbij — dan verlies je het
+vangnet.
+
+`resyncActiveScopes` triggert alleen de loaders die gekoppeld zijn aan de
+huidige selectie:
+
+```ts
+async resyncActiveScopes(reason) {
+  const ctx = get().context
+  const tasks: Promise<void>[] = []
+  if (ctx.activeProduct?.id) tasks.push(get().ensureProductLoaded(ctx.activeProduct.id))
+  if (ctx.activePbiId)       tasks.push(get().ensurePbiLoaded(ctx.activePbiId))
+  if (ctx.activeStoryId)     tasks.push(get().ensureStoryLoaded(ctx.activeStoryId))
+  if (ctx.activeTaskId)      tasks.push(get().ensureTaskLoaded(ctx.activeTaskId))
+  set((s) => { s.sync.lastResyncAt = Date.now(); s.sync.resyncReason = reason })
+  await Promise.allSettled(tasks)
+}
+```
+
+---
+
+## LocalStorage = restore-hint, niet waarheid
+
+Selectie-id's worden gepersisteerd om bij cold reload de vorige selectie te
+herstellen, **maar de hint wordt pas toegepast nadat ensure-load is gelukt
+en de hint-id bevestigd is in `entities.byId`**.
+
+```ts
+setActiveProduct(product) {
+  set((s) => { s.context.activeProduct = product; ... })
+  writeProductHint(product?.id ?? null)
+
+  if (product) {
+    void (async () => {
+      await get().ensureProductLoaded(product.id, requestId)
+      if (get().loading.activeRequestId !== requestId) return
+      const hint = readHints().perProduct[product.id]?.lastActivePbiId
+      if (hint && get().entities.pbisById[hint]) {
+        get().setActivePbi(hint)  // cascade — die doet zelfde voor story
+      }
+    })()
+  }
+}
+```
+
+**Geen `setTimeout(0)` of microtask-trick.** De fetch is dan nog niet klaar,
+de validatie `entities.byId[hint]` faalt altijd. Chain altijd `await
+ensureXxxLoaded` en valideer in dezelfde `requestId`-cycle.
+
+**URL wint van hint.** Maak een client-component (b.v.
+[`UrlTaskSync`](../../components/backlog/url-task-sync.tsx)) die op mount
+`useSearchParams().get('editTask')` leest, de hint overschrijft via
+`writeTaskHint`, en `setActiveTask` aanroept. De restore-flow leest de
+task-hint pas na drie ensure-awaits, dus de URL-write komt altijd eerder.
+
+---
+
+## Optimistic mutations
+
+Voor DnD en status-toggles. De store registreert alleen het rollback-snapshot;
+de component muteert state direct én roept de server aan.
+
+```tsx
+function handleDragEnd(event) {
+  const store = useStore.getState()
+  const prevOrder = [...store.relations.pbiIds]
+  const newOrder = arrayMove(prevOrder, oldIndex, newIndex)
+
+  // 1. Snapshot voor rollback
+  const mutationId = store.applyOptimisticMutation({
+    kind: 'pbi-order',
+    prevPbiIds: prevOrder,
+  })
+
+  // 2. Optimistisch toepassen
+  useStore.setState((s) => { s.relations.pbiIds = newOrder })
+
+  // 3. Server bevestigt (of niet)
+  startTransition(async () => {
+    const result = await reorderPbisAction(productId, newOrder)
+    const st = useStore.getState()
+    if (result.success) {
+      st.settleMutation(mutationId)
+    } else {
+      st.rollbackMutation(mutationId)
+      toast.error('Volgorde opslaan mislukt')
+    }
+  })
+}
+```
+
+**Cross-priority drag** vereist twee mutaties: een `pbi-order` voor de lijst
+plus een `entity-patch` voor de priority op de PBI zelf. Beide settle/rollback
+samen.
+
+**SSE-echo van een net optimistisch toegepaste wijziging** moet idempotent
+zijn — INSERT → bestaat al → return; UPDATE → merge into existing.
+
+---
+
+## API endpoints
+
+Voor elke `ensure*Loaded` een GET-route met:
+
+- Auth via `authenticateApiRequest` (Bearer-token of iron-session cookie).
+- Access-control via `productAccessFilter(userId)` voor product-context;
+  `getAccessibleProduct` voor explicit guards.
+- `export const dynamic = 'force-dynamic'`.
+- Status-vertaling via `taskStatusToApi` / `storyStatusToApi` /
+  `pbiStatusToApi` (DB UPPER_SNAKE → API lowercase).
+
+Referentie:
+[GET /api/products/:id/backlog](../../app/api/products/[id]/backlog/route.ts),
+[GET /api/pbis/:id/stories](../../app/api/pbis/[id]/stories/route.ts),
+[GET /api/stories/:id/tasks](../../app/api/stories/[id]/tasks/route.ts),
+[GET /api/tasks/:id](../../app/api/tasks/[id]/route.ts).
+
+`TaskDetail` shape extends `BacklogTask` met `_detail: true` plus extra
+velden (`implementation_plan`, `acceptance_criteria`, `requires_opus`,
+`verify_only`, `verify_required`). Gebruik de `isDetail()` typeguard om de
+extra velden te tonen.
+
+---
+
+## Tests
+
+Vitest + jsdom; setup in [`tests/setup.ts`](../../tests/setup.ts):
+
+- `MemoryStorage` shim voor localStorage (G6 — vitest 4 + jsdom 29 mist 'm
+  als configurable global).
+- `globalThis.fetch` herconfigureerbaar gemaakt zodat `vi.spyOn` werkt
+  (anders krijg je `Cannot redefine property: fetch`).
+- Default fetch-stub die `null` JSON returnt — voorkomt unhandled rejections
+  uit fire-and-forget `ensure*Loaded` calls die in tests niet expliciet
+  gemockt zijn. Tests overrulen met `vi.spyOn(globalThis, 'fetch')` per case.
+- `mockImplementation` (G8) — niet `mockResolvedValue` — anders is de
+  Response-body na de eerste `.json()` weg.
+
+```ts
+// G5: snapshot original actions module-level, restore in beforeEach
+const originalActions = (() => {
+  const s = useStore.getState()
+  return { /* alle action-refs */ }
+})()
+
+function resetStore() {
+  useStore.setState((s) => {
+    Object.assign(s, initialDataSlices)
+    Object.assign(s, originalActions)
+  })
+}
+
+beforeEach(resetStore)
+```
+
+**Acties mocken:** gebruik `setState((s) => { s.method = vi.fn() })`. Niet
+`vi.spyOn(state, 'method')` — de immer-frozen state is niet redefinable.
+
+**Verplichte test-cases per workspace-store:**
+
+- `hydrateSnapshot` vult entities + relations met sortering.
+- Selection cascade: `setActivePbi` reset story+task; `setActiveStory` reset
+  task.
+- `setActiveProduct(null)` ruimt entities en relations op.
+- `applyRealtimeEvent` pbi/story/task `I|U|D` met sortering en parent-move.
+- Event voor ander `product_id` wordt genegeerd.
+- Unknown entity met matching product → `resyncActiveScopes('unknown-event')`
+  trigger.
+- Job/worker/heartbeat/question events met `type`-veld → geen resync.
+- Delete-cleanup van actieve selectie.
+- Race-safe `ensure*Loaded` met requestId-guard (oude in-flight mag niet
+  nieuwere selectie overschrijven).
+- `ensureTaskLoaded` zet `_detail: true`.
+- `resyncActiveScopes` triggert ensure-keten met juiste URLs en zet
+  `lastResyncAt` + `resyncReason`.
+- localStorage restore-hints per setter.
+- Hint die niet (meer) in entities zit wordt genegeerd.
+- Optimistic mutation rollback/settle/SSE-echo idempotent.
+
+---
+
+## Gotchas — comment-template voor in code
+
+Documenteer deze in code via comments boven de fix.
+
+| # | Symptoom | Fix |
+|---|---|---|
+| **G1** | "Maximum update depth exceeded" — `s.byId[x] ?? []` levert nieuwe array per render | Module-level `EMPTY` const als fallback |
+| **G2** | Component re-rendert op iedere store-mutatie ondanks dat z'n data niet wijzigt | `useShallow(selectXxx)` voor lijsten |
+| **G3** | Hele state lijkt gewist na een `setState((s) => ({ context: ... }))` | Gebruik mutation-style: `setState((s) => { s.context.x = y })` (immer recipe muteert draft) |
+| **G4** | "method is not a function" in async context, of inconsistente state-mutaties | `get().method()` per call; nooit `const m = state.method` cachen |
+| **G5** | Tests beïnvloeden elkaar via `setState({ resyncActiveScopes: vi.fn() })` | `originalActions` snapshot op module-load + restore in `beforeEach` |
+| **G6** | `localStorage.clear is not a function` in vitest | `MemoryStorage` shim in `tests/setup.ts` |
+| **G7** | "Failed to parse URL from /api/..." in test-fetch | Mock fetch via `vi.spyOn(globalThis, 'fetch')` of stub in setup |
+| **G8** | "Body is unusable: Body has already been read" | `vi.fn().mockImplementation(() => Promise.resolve(new Response(...)))` — niet `mockResolvedValue` met een vooraf-gemaakte Response |
+
+---
+
+## Migratiepad voor een nieuwe workspace-store
+
+Volg dezelfde 8 stappen als PBI-74 (zie
+[zustand-workspace-store-implementation.md](../plans/zustand-workspace-store-implementation.md)):
+
+1. Skelet — types, store, selectors, restore + tests; geen UI-impact.
+2. Hydratie overstappen (parallel naast bestaande store).
+3. Componenten omzetten — `useShallow` voor lijsten, `setActiveX` setters.
+4. Race-safe loaders + restore-hints + URL-prioriteit.
+5. Hidden-tab + reconnect-resync (één PR — anders verlies je vangnet).
+6. Unknown-event filter (`isUnknownEntityEvent`).
+7. Cache-headers + LIST-endpoints (`force-dynamic`, `cache: 'no-store'`).
+8. Oude store opruimen.
+
+Stap 9 ("sprint-workspace-store") is de toepassing van dit patroon op de
+sprint-flow — kan starten zodra `product-workspace-store` enkele weken
+stabiel in productie staat.
--- a/docs/patterns/zustand-optimistic.md
+++ b/docs/patterns/zustand-optimistic.md
@ -3,34 +3,99 @@ title: "Zustand optimistische update + rollback"
 status: active
 audience: [ai-agent, contributor]
 language: nl
-last_updated: 2026-05-03
-when_to_read: "When adding client-side state mutations that need optimistic UI and rollback."
+last_updated: 2026-05-10
+when_to_read: "When adding client-side state mutations that need optimistic UI and rollback (DnD, status toggles)."
 ---

 # Patroon: Zustand optimistische update + rollback

-Gebruik dit patroon bij elke dnd-kit `onDragEnd` handler.
+Sinds PBI-74 lopen optimistic mutations via `applyOptimisticMutation`/
+`rollbackMutation`/`settleMutation` op de **workspace-store**. Het bredere
+patroon (store-design, SSE-integratie, restore-hints, tests) staat in
+[workspace-store.md](./workspace-store.md). Dit document beschrijft het
+DnD/status-mutation flow specifiek.

-```ts
-const { pbiOrder, reorderPbis, rollbackPbis } = usePlannerStore()
+## Patroon

-async function handleDragEnd(event: DragEndEvent) {
+1. Snapshot rollback-info via `applyOptimisticMutation` — krijgt `mutationId`.
+2. Pas state direct aan via `setState`.
+3. Server-actie aanroepen.
+4. Op success: `settleMutation(mutationId)` (ruimt pending-record op).
+5. Op error: `rollbackMutation(mutationId)` (herstelt vorige state + toast).
+
+Cross-priority drag vereist twee mutaties (order + entity-patch) die samen
+settlen of rollbacken.
+
+## Voorbeeld — PBI reorder
+
+```tsx
+import { useProductWorkspaceStore } from '@/stores/product-workspace/store'
+
+function handleDragEnd(event: DragEndEvent) {
  const { active, over } = event
  if (!over || active.id === over.id) return

-  const prevOrder = [...pbiOrder[productId]]
-  const newOrder = arrayMove(prevOrder, oldIndex, newIndex)
+  const store = useProductWorkspaceStore.getState()
+  const prevOrder = [...store.relations.pbiIds]
+  const oldIndex = prevOrder.indexOf(active.id as string)
+  const newIndex = prevOrder.indexOf(over.id as string)
+  if (oldIndex === -1 || newIndex === -1) return
+  const newOrder = arrayMove([...prevOrder], oldIndex, newIndex)

-  // 1. Optimistisch updaten (direct zichtbaar voor gebruiker)
-  reorderPbis(productId, newOrder)
+  // 1. Snapshot rollback-info
+  const mutationId = store.applyOptimisticMutation({
+    kind: 'pbi-order',
+    prevPbiIds: prevOrder,
+  })

-  // 2. Persisteren via Server Action
-  const result = await reorderPbisAction(productId, newOrder)
+  // 2. Optimistisch toepassen
+  useProductWorkspaceStore.setState((s) => {
+    s.relations.pbiIds = newOrder
+  })

-  // 3. Rollback bij fout
-  if (!result.success) {
-    rollbackPbis(productId, prevOrder)
-    toast.error('Volgorde opslaan mislukt')
-  }
+  // 3-5. Server bevestigt of niet
+  startTransition(async () => {
+    const result = await reorderPbisAction(productId, newOrder)
+    const st = useProductWorkspaceStore.getState()
+    if (result.success) {
+      st.settleMutation(mutationId)
+    } else {
+      st.rollbackMutation(mutationId)
+      toast.error('Volgorde opslaan mislukt')
+    }
+  })
 }
 ```
+
+## Voorbeeld — entity-patch (priority-wijziging)
+
+```tsx
+const prevPbi = store.entities.pbisById[id]
+const patchMutationId = store.applyOptimisticMutation({
+  kind: 'entity-patch',
+  entity: 'pbi',
+  id,
+  prev: prevPbi,
+})
+useProductWorkspaceStore.setState((s) => {
+  const pbi = s.entities.pbisById[id]
+  if (pbi) pbi.priority = newPriority
+})
+// settle/rollback identiek aan order-flow
+```
+
+## Mutation-soorten
+
+| `kind` | Rollback-data | Use-case |
+|---|---|---|
+| `pbi-order` | `prevPbiIds` | DnD reorder van PBI's |
+| `story-order` | `pbiId` + `prevStoryIds` | DnD reorder van stories binnen een PBI |
+| `task-order` | `storyId` + `prevTaskIds` | DnD reorder van tasks binnen een story |
+| `entity-patch` | `entity` + `id` + `prev` (volledig vorig record of `undefined` voor delete-rollback) | Property-wijzigingen (priority, status), of optimistic delete/undelete |
+
+## SSE-echo idempotent verwerken
+
+Wanneer de server bevestigt en de NOTIFY-trigger het bijbehorende event
+emitteert, mag `applyRealtimeEvent` **geen dubbele insert** veroorzaken en
+**geen rollback triggeren**. INSERTs checken bestaan; UPDATEs mergen
+into-existing. Zie `applyRealtimeEvent` in [`stores/product-workspace/store.ts`](../../stores/product-workspace/store.ts).
--- a/docs/plans/lees-de-readme-md-validated-book.md
+++ b/docs/plans/lees-de-readme-md-validated-book.md
@ -1,8 +1,16 @@
 # Scrum4Me-Research — Zustand rearchitecture (reset + execute)

+> **Scope:** dit plan is geschreven voor de research-repo
+> [`madhura68/Scrum4Me-Research`](https://github.com/madhura68/Scrum4Me-Research),
+> niet voor dit hoofdproject. Bestandsverwijzingen die naar
+> `stores/data-store.ts`, `hooks/use-event-stream.ts`,
+> `components/*-select.tsx` etc. wijzen, bestaan in de research-repo —
+> niet hier. Ze staan in `code`-tags zodat de doc-link-checker ze niet
+> probeert te resolven.
+
 ## Context

-Het bestaande [docs/plans/zustand-store-rearchitecture.md](docs/plans/zustand-store-rearchitecture.md) beschrijft een doel-architectuur (`product-workspace-store` met genormaliseerde entities, race-safe loaders, resync-laag, optimistic mutations). De research-repo is dé plek om dat eerst te testen voordat het in `Scrum4Me/` belandt.
+Het bestaande [zustand-store-rearchitecture.md](./zustand-store-rearchitecture.md) beschrijft een doel-architectuur (`product-workspace-store` met genormaliseerde entities, race-safe loaders, resync-laag, optimistic mutations). De research-repo is dé plek om dat eerst te testen voordat het in `Scrum4Me/` belandt.

 Probleem nu: de research-repo wijkt af van het hoofdproject. Mijn custom `data-store.ts` lijkt qua vorm op de doel-architectuur, maar springt over de baseline heen. We willen aantonen dat de migratie *vanaf* de huidige Scrum4Me-patronen werkt, niet vanaf een verzonnen tussenvorm.

@ -10,8 +18,8 @@ Dus: eerst de research-repo terugbrengen naar dezelfde stores/hooks/routes als S

 ## Bron-documenten

- **Doel-architectuur**: [docs/plans/zustand-store-rearchitecture.md](docs/plans/zustand-store-rearchitecture.md) (in research-repo). Dit plan voert dat document uit; herhaalt het niet.
- **Conventies**: [CLAUDE.md](../Scrum4Me/CLAUDE.md) hoofdproject. Taal NL, MD3 tokens, `@base-ui/react` render-prop, `*-server.ts`, enum UPPER_SNAKE↔lowercase via `lib/task-status.ts`.
+- **Doel-architectuur**: [zustand-store-rearchitecture.md](./zustand-store-rearchitecture.md) (in research-repo). Dit plan voert dat document uit; herhaalt het niet.
+- **Conventies**: [CLAUDE.md](../../CLAUDE.md) hoofdproject. Taal NL, MD3 tokens, `@base-ui/react` render-prop, `*-server.ts`, enum UPPER_SNAKE↔lowercase via `lib/task-status.ts`.

 ## Drie-faseplan

@ -20,10 +28,10 @@ Dus: eerst de research-repo terugbrengen naar dezelfde stores/hooks/routes als S
 Doel: onze research-pagina werkt op exact dezelfde store/hook/route-vorm als het hoofdproject, met identiek gedrag.

 **Verwijderen** (research-repo):
- [stores/data-store.ts](stores/data-store.ts) — mijn megastore
- [hooks/use-event-stream.ts](hooks/use-event-stream.ts) — vervangen door `use-backlog-realtime.ts`
- [hooks/use-browser-presence.ts](hooks/use-browser-presence.ts) — niet in main, drop voor reset
- [app/api/realtime/events/route.ts](app/api/realtime/events/route.ts) — vervangen door `app/api/realtime/backlog/route.ts`
+- `stores/data-store.ts` (research-repo) — mijn megastore
+- `hooks/use-event-stream.ts` (research-repo) — vervangen door `use-backlog-realtime.ts`
+- `hooks/use-browser-presence.ts` (research-repo) — niet in main, drop voor reset
+- `app/api/realtime/events/route.ts` (research-repo) — vervangen door `app/api/realtime/backlog/route.ts`
 - Mijn custom `loadX/resyncAll`-paden in selectie-componenten

 **Kopiëren uit `/Users/janpetervisser/Development/Scrum4Me/`** (1-op-1 of stripped van auth):
@ -48,12 +56,12 @@ Doel: onze research-pagina werkt op exact dezelfde store/hook/route-vorm als het
 - `GET /api/tasks/[id]`

 **Componenten herschrijven**:
- [components/product-select.tsx](components/product-select.tsx) → leest `useProductsStore`, schrijft naar `useProductStore.setCurrentProduct`
- [components/pbi-select.tsx](components/pbi-select.tsx) → leest `useBacklogStore` (filter op currentProduct), `useSelectionStore.selectPbi`. Triggert fetch op product-mount via een `useBacklogLoader`-helper die initial data binnenhaalt.
- [components/story-select.tsx](components/story-select.tsx) → idem voor stories
- [components/tasks-table.tsx](components/tasks-table.tsx) → leest `tasksByStory[selectedStoryId]`. **Max 10 rijen, scrollbaar** (al ingebouwd, behouden)
- [components/task-detail-card.tsx](components/task-detail-card.tsx) → fetcht task detail apart (geen full-fat backlog veld; matcht main's `tasks/[id]` route)
- [components/event-stream-panel.tsx](components/event-stream-panel.tsx) → blijft bestaan voor research-doel (event-tap), maar luistert nu mee op dezelfde EventSource via `use-backlog-realtime` (of een tweede readonly listener); selecteerbare events met JSON-detail rechts blijven. Twee checkboxes (Postgres / Browser). Truncate met ellipsis in de lijst.
+- `components/product-select.tsx` (research-repo) → leest `useProductsStore`, schrijft naar `useProductStore.setCurrentProduct`
+- `components/pbi-select.tsx` (research-repo) → leest `useBacklogStore` (filter op currentProduct), `useSelectionStore.selectPbi`. Triggert fetch op product-mount via een `useBacklogLoader`-helper die initial data binnenhaalt.
+- `components/story-select.tsx` (research-repo) → idem voor stories
+- `components/tasks-table.tsx` (research-repo) → leest `tasksByStory[selectedStoryId]`. **Max 10 rijen, scrollbaar** (al ingebouwd, behouden)
+- `components/task-detail-card.tsx` (research-repo) → fetcht task detail apart (geen full-fat backlog veld; matcht main's `tasks/[id]` route)
+- `components/event-stream-panel.tsx` (research-repo) → blijft bestaan voor research-doel (event-tap), maar luistert nu mee op dezelfde EventSource via `use-backlog-realtime` (of een tweede readonly listener); selecteerbare events met JSON-detail rechts blijven. Twee checkboxes (Postgres / Browser). Truncate met ellipsis in de lijst.

 **Werkwijzen (verifiëren tijdens reset)**:
 - Comments en UI-tekst NL
@ -69,7 +77,7 @@ Doel: onze research-pagina werkt op exact dezelfde store/hook/route-vorm als het

 ### Fase B — Rearchitecture uitvoeren

-Volgt de 15 stappen uit [docs/plans/zustand-store-rearchitecture.md](docs/plans/zustand-store-rearchitecture.md) §Implementatiepad. Concreet voor de research-repo:
+Volgt de 15 stappen uit [zustand-store-rearchitecture.md](./zustand-store-rearchitecture.md) §Implementatiepad. Concreet voor de research-repo:

 1. **Map** `stores/product-workspace/` aanmaken (factory + provider + selectors).
 2. **`activeProduct`** wordt nu nog gespiegeld vanuit `useProductStore`; voor de research-pagina geen layout/server-side bepaling — we lezen het uit de pulldown-state.
@ -134,10 +142,10 @@ Volgt de 15 stappen uit [docs/plans/zustand-store-rearchitecture.md](docs/plans/
 ## Bestandsmutaties (overzicht)

 ### Verwijderen na Fase A
- [stores/data-store.ts](stores/data-store.ts)
- [hooks/use-event-stream.ts](hooks/use-event-stream.ts)
- [hooks/use-browser-presence.ts](hooks/use-browser-presence.ts) — komt deels terug in Fase B als helper voor visibility/online resync trigger
- [app/api/realtime/events/route.ts](app/api/realtime/events/route.ts)
+- `stores/data-store.ts` (research-repo)
+- `hooks/use-event-stream.ts` (research-repo)
+- `hooks/use-browser-presence.ts` (research-repo) — komt deels terug in Fase B als helper voor visibility/online resync trigger
+- `app/api/realtime/events/route.ts` (research-repo)

 ### Toevoegen Fase A (uit Scrum4Me)
 - `stores/backlog-store.ts`
@ -174,7 +182,7 @@ Volgt de 15 stappen uit [docs/plans/zustand-store-rearchitecture.md](docs/plans/
 6. Vergelijk: `diff Scrum4Me/stores/backlog-store.ts Scrum4Me-Research/stores/backlog-store.ts` → identiek (modulo lokale interface-uitbreidingen waar gedocumenteerd)

 ### Na Fase B (target)
-Alle acceptatiecriteria uit [docs/plans/zustand-store-rearchitecture.md §Acceptatiecriteria](docs/plans/zustand-store-rearchitecture.md):
+Alle acceptatiecriteria uit [zustand-store-rearchitecture.md §Acceptatiecriteria](./zustand-store-rearchitecture.md):
 - Eén waarheid per entity in de store ✓
 - Selectors als enige UI-leesweg ✓
 - SSE patcht zonder full-page refresh ✓
--- a/docs/plans/zustand-workspace-store-implementation.md
+++ b/docs/plans/zustand-workspace-store-implementation.md
@ -0,0 +1,177 @@
+---
+title: "Zustand workspace-store implementatieplan (PBI-74)"
+status: ready-to-execute
+audience: [maintainer, contributor, ai-agent]
+language: nl
+last_updated: 2026-05-09
+revision: 1
+---
+
+# Zustand workspace-store implementatieplan
+
+PBI in Scrum4Me-MCP: **PBI-74** — _Zustand store rearchitecture — product- en sprint-workspace_.
+
+Bron-ontwerp (architectuur en gotchas): [zustand-store-rearchitecture.md](./zustand-store-rearchitecture.md) revisie 3.
+
+Dit document koppelt de stories en taken in MCP aan de implementatie. Per story acceptatiecriteria; per taak een concrete deliverable. Alle items staan in MCP op `OPEN`/`TO_DO`. Geen executie tot expliciete trigger ("voer Story 1 uit").
+
+## Context
+
+De client-state ligt over vier los gegroeide stores: `backlog-store`, `planner-store`, `selection-store`, `product-store`. Vier zwakheden:
+
+- SSE sluit op tab `hidden` zonder resync bij `visible` — gemiste events blijven gemist.
+- Geen reconcile bij reconnect (Postgres NOTIFY heeft geen replay).
+- Onbekende entity-events worden stil genegeerd.
+- LocalStorage soms behandeld als waarheid i.p.v. restore-hint.
+- Geen race-safe loaders — trage fetch van oude selectie kan nieuwste overschrijven.
+
+De rearchitecture lost dit op via één `product-workspace-store` (en analoog `sprint-workspace-store`) met genormaliseerde entity-maps, race-safe `ensure*Loaded` met `activeRequestId`-guard, expliciete resync-laag (visible/reconnect/unknown-event), idempotente SSE-application en localStorage als pure restore-hint.
+
+## Aanpak
+
+- Eén PBI ([PBI-74](./zustand-store-rearchitecture.md)).
+- Negen stories die mappen op de stappen 1-9 in het bron-ontwerp.
+- Granulariteit Story 3 = één story met taken per component.
+- Story 5 in één PR (visibility-handling + resync horen samen).
+- Per story: PR, `npm run verify && npm run build` groen, status DONE pas na merge.
+- Branch: `feat/zustand-workspace-store` (één branch voor alle stories).
+
+## Stories en taken
+
+| # | Story | MCP | Taken |
+|---|---|---|---|
+| 1 | Skelet + test-infrastructuur | [ST-1318](./zustand-store-rearchitecture.md) | T-837 … T-843 (7) |
+| 2 | Hydratie overstappen (parallel-running) | ST-1319 | T-844 … T-847 (4) |
+| 3 | Componenten omzetten naar workspace-store | ST-1320 | T-848 … T-855 (8) |
+| 4 | Race-safe loaders en restore-hints | ST-1321 | T-856 … T-860 (5) |
+| 5 | Hidden-tab + reconnect resync (één PR) | ST-1322 | T-861 … T-864 (4) |
+| 6 | Unknown-event fallback | ST-1323 | T-865 … T-867 (3) |
+| 7 | Cache-headers en read-routes | ST-1324 | T-868 … T-871 (4) |
+| 8 | Oude stores opruimen | ST-1325 | T-872 … T-878 (7) |
+| 9 | Sprint-workspace-store | ST-1326 | T-879 … T-884 (6) |
+
+Totaal: 48 taken.
+
+### Story 1 — Skelet + test-infrastructuur
+
+**Doel:** nieuwe store + selectors + restore-utils met volledige unit-test-suite, nog zonder UI-consumenten.
+
+**Belangrijkste taken:**
+- T-837 — Vitest naar jsdom + `tests/setup.ts` met MemoryStorage (G6).
+- T-838/839/840/841 — `stores/product-workspace/{types,store,selectors,restore}.ts`.
+- T-842 — Volledige test-suite per §Testing setup-checklist (G5/G7/G8).
+- T-843 — API endpoint-audit voor `ensure*Loaded` URLs.
+
+**Acceptatie:** alle test-cases groen, geen UI-impact.
+
+### Story 2 — Hydratie overstappen
+
+**Doel:** `BacklogHydrationWrapper` en `useBacklogRealtime` voeden zowel oude store als nieuwe store. Componenten lezen nog uit oude.
+
+**Taken:** T-844 (wrapper dual-dispatch), T-845 (realtime dual-dispatch), T-846 (dev-only fingerprint verifyer), T-847 (productpicker → setActiveProduct).
+
+**Acceptatie:** schaduw-store inhoud matcht oude store na elk SSE-event.
+
+### Story 3 — Componenten omzetten
+
+**Doel:** componenten lezen uit nieuwe workspace-store; oude stores hebben geen UI-consumenten meer.
+
+**Taken per component:** T-848 (split-pane), T-849 (pbi-list), T-850 (story-panel), T-851 (task-panel), T-852 (start-sprint-button), T-853 (set-current-product). Plus T-854 (G1/G2-audit) en T-855 (integration-tests bijwerken).
+
+**Acceptatie:** geen "Maximum update depth" warnings; oude store-imports alleen nog in tests die in Story 8 verdwijnen.
+
+### Story 4 — Race-safe loaders en restore-hints
+
+**Doel:** `ensure*Loaded` met `activeRequestId`-guard; localStorage hints met validatie.
+
+**Taken:** T-856 (guard), T-857 (restore-flow met await ensure-chain), T-858 (hint-persistentie), T-859 (URL-prioriteit), T-860 (race-safety tests).
+
+**Acceptatie:** trage fetch + her-selectie corrumpeert nooit; cold reload restoret zonder fout.
+
+### Story 5 — Hidden-tab + reconnect resync (één PR)
+
+**Doel:** SSE blijft open op hidden; resync via expliciete laag.
+
+**Taken:** T-861 (geen close op hidden), T-862 (ready-event triggert resync na reconnect), T-863 (`useWorkspaceResync` hook), T-864 (tests).
+
+**Acceptatie:** hidden→visible en reconnect herstellen gemiste wijzigingen in één cyclus.
+
+### Story 6 — Unknown-event fallback
+
+**Doel:** onbekende entity-events triggeren resync; job/worker noise wordt genegeerd.
+
+**Taken:** T-865 (`isUnknownEntityEvent` filter), T-866 (resync-trigger), T-867 (negatieve filter-tests).
+
+**Acceptatie:** directe DB UPDATE zonder herkenbare delta-event wordt zichtbaar binnen één resync; job-events triggeren geen resync.
+
+### Story 7 — Cache-headers en read-routes
+
+**Doel:** geen stale data uit Next/browser cache.
+
+**Taken:** T-868 (`cache: 'no-store'`), T-869 (`force-dynamic` audit), T-870 (LIST-endpoints toevoegen waar nodig), T-871 (SSE-route ready-event coverage).
+
+**Acceptatie:** response headers in productie tonen `cache-control: no-store`; LIST-endpoints bestaan voor alle `ensure*Loaded`.
+
+### Story 8 — Oude stores opruimen
+
+**Doel:** vier oude stores verwijderd.
+
+**Taken:** T-872 (grep), T-873/874/875/876 (delete vier files), T-877 (oude tests migreren), T-878 (`stores/products-store.ts` blijft + dev-fingerprint cleanup).
+
+**Acceptatie:** grep `useBacklogStore|usePlannerStore|useSelectionStore|useProductStore` = 0; `npm run verify && npm run build` groen.
+
+### Story 9 — Sprint-workspace-store
+
+**Doel:** zelfde patroon op sprint-workflow toegepast.
+
+**Taken:** T-879 (skelet), T-880 (hydratie+realtime), T-881 (componenten), T-882 (race-safe + restore + resync + unknown-event in één keer), T-883 (cleanup oude sprint-state), T-884 (E2E sprint-board verificatie).
+
+> **Aanbeveling per ontwerpdoc:** start Story 9 pas nadat product-workspace enkele weken stabiel in productie staat. PBI-74 sluit pas wanneer Story 9 ook merged is.
+
+## Critical files
+
+**Te wijzigen:**
+- `vitest.config.ts` — env naar jsdom, setupFiles
+- nieuw: `tests/setup.ts` — MemoryStorage, restoreAllMocks
+- nieuw: `stores/product-workspace/{types,store,selectors,restore}.ts`
+- nieuw: `stores/sprint-workspace/{types,store,selectors,restore}.ts`
+- nieuw: `lib/realtime/use-workspace-resync.ts`
+- `components/backlog/backlog-hydration-wrapper.tsx`
+- `lib/realtime/use-backlog-realtime.ts`
+- `components/backlog/backlog-split-pane.tsx`, `pbi-list.tsx`, `story-panel.tsx`, `task-panel.tsx`
+- `components/.../start-sprint-button.tsx`, `set-current-product.tsx`
+- read-routes onder `app/api/...` voor PBI/story/task LIST + detail
+- te verwijderen in Story 8: `stores/{backlog,planner,selection,product}-store.ts`
+
+**Te hergebruiken (geen wijziging):**
+- `lib/product-access.ts` — `getAccessibleProduct`, blijft auth/access-bron
+- `app/api/realtime/backlog/route.ts` — `ready`-event al aanwezig
+- `docs/patterns/realtime-notify-payload.md` — payload-contract
+- `docs/patterns/route-handler.md` — REST patroon
+- `stores/products-store.ts`, `stores/solo-store.ts`, `stores/notifications-store.ts`, `stores/idea-store.ts`, `stores/jobs-store.ts` — blijven ongewijzigd
+
+## Verificatie per story
+
+- **Story 1:** Vitest groen voor alle test-cases (hydrate, cascade, realtime, ensureLoaded race, resync, restore-hints, optimistic mutation).
+- **Story 2:** dev-server, productpagina, fingerprint match in console.
+- **Story 3:** klik door 3 panels, DnD test, geen "Maximum update depth"-warnings.
+- **Story 4:** staging — cold reload, throttle fetch + her-selecteer.
+- **Story 5:** tab hidden > 30s + terug → resync zichtbaar; netwerk uit/aan → reconnect+resync.
+- **Story 6:** DB UPDATE op story zonder delta-event → zichtbaar binnen 1 resync; job-events negeren resync.
+- **Story 7:** response headers `cache-control: no-store`; tweede pageload toont verse data.
+- **Story 8:** grep oude store-imports = 0; `npm run verify && npm run build` groen.
+- **Story 9:** sprint-board flow analoog Story 1-8 verifications.
+
+**Eind-acceptatie PBI-74:** alle items uit §Acceptatiecriteria van [zustand-store-rearchitecture.md](./zustand-store-rearchitecture.md) (regels 727-746) behaald.
+
+## Workflow per story
+
+1. `git checkout -b feat/zustand-workspace-store` (eerste story); blijf op deze branch tot expliciete cut.
+2. `mcp__scrum4me__get_claude_context` → pak next story uit PBI-74.
+3. Voer taken uit in `sort_order`; update status per taak via `mcp__scrum4me__update_task_status`.
+4. Lees relevante bestanden + patronen vóór begin (zie §Critical files).
+5. `npm run verify && npm run build` per laag.
+6. Commit per laag (`git add -A && git commit`); geen push tussendoor.
+7. Story-status sluit zodra alle taken `DONE`.
+8. Lege story-queue → `git push -u origin feat/zustand-workspace-store` + `gh pr create`.
+9. Per story een eigen PR; merge één voor één.