docs(ST-1115): end-to-end verificatie checklist 1 batch = 1 Vercel-deploy

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

AGENTS.md

@@ -11,3 +11,13 @@ last_updated: 2026-05-03
 This file is a redirect stub. All agent instructions live in **[CLAUDE.md](./CLAUDE.md)**.
 
 For Claude Code specifically, CLAUDE.md is loaded automatically. Start there.
+
+## Branch & PR-flow (quick reference)
+
+| Moment | Actie | Verbod |
+|---|---|---|
+| Start run | `git checkout -b feat/<batch-slug>` | `gh pr create` |
+| Na elke taak | `git add -A && git commit -m "<type>(ST-XXX): <title>"` | `git push` |
+| Queue leeg | `git push -u origin <branch>` + `gh pr create` | — |
+
+Full details: [docs/runbooks/branch-and-commit.md § Agent-batch flow](./docs/runbooks/branch-and-commit.md)

CLAUDE.md

@@ -29,11 +29,14 @@ Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: produ
 ## Hoe werk vinden
 
 **Track A — MCP (aanbevolen):**
-1. `mcp__scrum4me__get_claude_context` → pak de next story
-2. Voer taken uit in `sort_order`; update status per taak
-3. Lees het relevante patroon en styling vóór je begint
-4. Verifieer: `npm run lint && npm test && npm run build`
-5. Commit per laag — zie [docs/runbooks/branch-and-commit.md](./docs/runbooks/branch-and-commit.md)
+1. Branch aanmaken: `git checkout -b feat/<batch-slug>` — nog **geen** `gh pr create`
+2. `mcp__scrum4me__get_claude_context` → pak de next story
+3. Voer taken uit in `sort_order`; update status per taak
+4. Lees het relevante patroon en styling vóór je begint
+5. Verifieer: `npm run lint && npm test && npm run build`
+6. Commit per laag: `git add -A && git commit` — **geen** `git push` — zie [docs/runbooks/branch-and-commit.md](./docs/runbooks/branch-and-commit.md)
+7. Herhaal stap 2–6 per story; branch blijft dezelfde
+8. Queue leeg → `git push -u origin <branch>` + `gh pr create`
 
 **Track B — manueel:**
 1. Lees taak in `docs/backlog/index.md`
@@ -48,7 +51,7 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo
 
 - **Styling:** nooit `bg-blue-500`; altijd MD3-tokens (`bg-primary`, `bg-status-done`, …)
 - **UI:** gebruik `@base-ui/react` met `render`-prop, niet Radix `asChild`
-- **Push:** nooit pushen zonder expliciete gebruikersbevestiging — zie [branch-and-commit.md](./docs/runbooks/branch-and-commit.md)
+- **Push:** commits accumuleren lokaal per taak (`git add -A && git commit`); push + PR pas bij lege queue of na expliciete gebruikersbevestiging — zie [branch-and-commit.md](./docs/runbooks/branch-and-commit.md)
 - **Demo:** drie lagen — proxy.ts + server action + UI disabled knop
 - **Enum:** DB UPPER_SNAKE ↔ API lowercase — uitsluitend via `lib/task-status.ts`
 - **Foutcodes:** 400 = parse-fout, 422 = Zod-validatie, 403 = demo-token

docs/INDEX.md

@@ -61,6 +61,7 @@ Auto-generated on 2026-05-03 from front-matter and headings.
 | [Prisma Client singleton](./patterns/prisma-client.md) | active | 2026-05-03 |
 | [Proxy (route protection)](./patterns/proxy.md) | active | 2026-05-03 |
 | [QR-pairing via unauth-SSE + pre-auth cookie](./patterns/qr-login.md) | active | 2026-05-03 |
+| [Realtime NOTIFY payload — veldnaam-contract](./patterns/realtime-notify-payload.md) | active | 2026-05-03 |
 | [Route Handler (REST API)](./patterns/route-handler.md) | active | 2026-05-03 |
 | [Server Action](./patterns/server-action.md) | active | 2026-05-03 |
 | [Float sort_order (drag-and-drop volgorde)](./patterns/sort-order.md) | active | 2026-05-03 |

docs/runbooks/branch-and-commit.md

@@ -4,7 +4,7 @@ status: active
 audience: [ai-agent, contributor]
 language: nl
 last_updated: 2026-05-03
-when_to_read: "Before creating a branch, commit, or PR."
+when_to_read: "Before creating a branch, commit, or PR. Also before any agent-batch run."
 ---
 
 # Branch, PR & Commit Strategy
@@ -45,6 +45,47 @@ Elke `git push` naar een feature-branch triggert een Vercel preview-deployment.
 
 Zodra het Vercel-account naar Pro (of andere omgeving zonder per-build-kosten) gaat: vervang deze regel door "branch + PR per story" zoals oorspronkelijk in dit document stond. Werk deze sectie bij én documenteer de wijziging in `docs/decisions/agent-instructions-history.md`.
 
+### Agent-batch flow (verplicht voor worker-runs)
+
+Wanneer de NAS-agent (`/opt/agent/`) een batch jobs uitvoert:
+
+| Moment | Actie | Verbod |
+|---|---|---|
+| Start run | `git checkout -b feat/<batch-slug>` lokaal | `gh pr create` |
+| Na elke taak | `git add -A && git commit -m "<type>(ST-XXX): <title>"` | `git push` |
+| Queue leeg | `git push -u origin <branch>` + `gh pr create` | — |
+
+- Alle commits accumuleren op dezelfde branch — lopende state blijft op disk tot de run klaar is.
+- Één PR per batch → één Vercel preview-deployment.
+- Single-task batch (1 job in queue): dezelfde flow — 1 commit → push + PR.
+
+#### End-to-end verificatie: 1 batch = 1 Vercel-deploy
+
+Gebruik deze checklist om te verifiëren dat de batch-flow correct werkt na een agent-run:
+
+**Voorbereiding**
+1. Seed ≥ 2 taken onder één story (bv. README-edits).
+2. Trigger de batch via **"Voer alle uit"** op het Solo Board.
+3. Wacht tot de agent alle jobs als `done` markeert.
+
+**GitHub-checks**
+- [ ] Er is precies **één PR** aangemaakt voor de batch-branch.
+- [ ] De PR bevat **één commit per taak** (geen squash, geen force-push).
+- [ ] Er zijn **geen losse pushes** op de branch vóór de definitieve push (check via `git log --all --graph` of GitHub's "commits" tab).
+
+**Vercel-checks**
+- [ ] In het Vercel-dashboard → **Deployments**: er is **exact één preview-deployment** voor de branch in het run-window.
+- [ ] Geen extra "cancelled" of "building" deployments voor dezelfde branch uit hetzelfde tijdsvenster (zou wijzen op tussentijdse pushes).
+
+**Alternatieve verificatie via Vercel MCP** (indien beschikbaar):
+```
+mcp__<vercel-plugin-id>__list_deployments
+  → filter op branchName = feat/<batch-slug>
+  → verwacht: 1 entry met state = READY of BUILDING
+```
+
+**Race-condition scenario**: als een nieuwe taak in de queue terechtkomt terwijl de agent de queue-check uitvoert, kan er een tweede push volgen. Dit is acceptabel — de tweede push triggert een tweede deployment voor de resterende commits. Documenteer dit afwijkend gedrag in de PR-description als het zich voordoet.
+
 ---
 
 ## Plan Mode