docs(trim): extract branch/commit rules into runbook

docs/runbooks/branch-and-commit.md

@@ -0,0 +1,104 @@
+---
+title: "Branch, PR & Commit Strategy"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-03
+when_to_read: "Before creating a branch, commit, or PR."
+---
+
+# Branch, PR & Commit Strategy
+
+## Branch & PR Strategy (STRICT — kostenbeheersing)
+
+> **Core rule: één branch per milestone, PR alleen na gebruikerstest**
+
+Elke `git push` naar een feature-branch triggert een Vercel preview-deployment. Op het huidige Hobby-account zijn die schaars en kosten geld; we minimaliseren preview-builds tot er werkelijk iets te reviewen valt.
+
+### Wel doen
+
+- Eén branch voor de hele milestone — `feat/M{N}-{slug}` (bv. `feat/M10-qr-login`); voor losse stories zonder milestone blijft `feat/ST-XXX-{slug}` geldig
+- Commits accumuleren lokaal volgens de Commit Strategy hieronder — één commit per stap, ST-code in de titel
+- Pushen + PR openen **pas nadat de gebruiker de milestone handmatig heeft getest en goedgekeurd** — vraag expliciet om bevestiging vóór `git push`
+- Tussentijdse "klaar voor jouw test"-momenten markeren met een lokale tag of een berichtje in chat, niet met een push
+
+### Niet doen
+
+- Pushen na elke story of commit
+- Een PR per story openen tijdens de implementatie
+- "Just-in-case" pushen om backup te hebben — gebruik `git stash`, een lokale tag, of meerdere lokale branches
+- `--force-push` om eerdere preview-builds "weg te toveren" (kost dezelfde build opnieuw bij hercreatie)
+- **Direct pushen naar `main`** — die branch heeft protection rules; gebruik altijd een PR
+
+### Wanneer wel commit-zonder-vragen, wanneer niet
+
+- **Tijdens een directed sprint-flow** (Track A: `mcp__scrum4me__implement_next_story` of een expliciete *"implementeer M{N}"*-opdracht): commit-per-laag conform de Commit Strategy hieronder is impliciet geautoriseerd — niet per commit vragen
+- **Bij ad-hoc / out-of-band werk** (bug-fix tussendoor, refactor, kleine wijziging op verzoek): toon de diff + voorgestelde commit-message en wacht op `"commit it"` voordat je `git commit` draait
+- **`git push` is altijd expliciet** — de scope van de policy gaat over preview-builds, dus push gebeurt alleen na gebruiker-test, ongeacht commit-context
+
+### Uitzonderingen op de push-regel
+
+- Een **planning-PR** zonder code-wijzigingen (alleen docs in `docs/plans/` of `docs/`) mag direct gepusht worden — die triggert geen functional regressie en is goedkoop te bouwen
+- Een **bugfix-hotfix** op `main` met aantoonbare productie-impact mag direct gepusht worden (via een PR — zie boven)
+
+### Wanneer aanpassen
+
+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`.
+
+---
+
+## Plan Mode
+
+- Voor simpele, goed-afgebakende file-edits: **niet** in plan mode gaan — gewoon de wijziging maken
+- Reserveer plan mode voor multi-step refactors, ambigue verzoeken, of milestone-planning waarbij design-keuzes vooraf bevestigd moeten worden
+- Plannen die uit plan mode komen: opslaan als `docs/plans/M{N}-{slug}.md` (zie memory `feedback_plan_location`), niet als ephemeral systeem-bestand
+
+---
+
+## Commit Strategy (STRICT)
+
+> **Core rule: één commit = één verantwoordelijkheid**
+
+### Nooit doen
+
+- Database + API + UI in één commit mengen
+- Feature + documentatie combineren
+- Grote "alles gewijzigd" commits
+- Vage berichten zoals "update stuff"
+
+### Verplichte structuur
+
+Splits werk op in logische lagen:
+
+1. Database / Prisma
+2. API / server actions
+3. UI / components
+4. Config / infra
+5. Documentatie
+
+### Commit-formaat
+
+```
+feat(ST-XXX): korte beschrijving
+fix(ST-XXX): korte beschrijving
+chore(ST-XXX): korte beschrijving
+docs(ST-XXX): korte beschrijving
+```
+
+### Voorbeeld (verplicht patroon)
+
+In plaats van:
+
+```bash
+feat: add profile system
+```
+
+Splits altijd op in:
+
+```bash
+feat(ST-XXX): add user profile fields to Prisma schema
+feat(ST-XXX): add avatar upload endpoint
+feat(ST-XXX): add profile editor component
+chore(ST-XXX): configure sharp for avatar processing
+docs(ST-XXX): document profile feature
+```

docs/runbooks/deploy-vercel.md

@@ -0,0 +1,16 @@
+---
+title: "Vercel Deployment"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-03
+when_to_read: "Before deploying to Vercel or modifying cron/image/env config."
+---
+
+# Deployment (Vercel)
+
+- **Sharp** moet Linux-binaries hebben voor de Vercel-runtime: `npm i --include=optional sharp` of platform-specifieke deps configureren in `package.json`
+- **Externe image hostnames** in `next.config.js` `images.remotePatterns` configureren *vóór* `next/image` op die hosts wijst — anders 500 in productie
+- **Vercel cron**: Hobby-plan staat alleen daily crons toe (max 1×/dag); Pro ondersteunt fijnmaziger. Bij wijziging van `vercel.json` `crons` ook `docs/api/rest-contract.md` + relevante pattern-docs updaten
+- **`CRON_SECRET`** moet als env-var op de Vercel-project-omgeving staan vóór de eerste cron-run, anders 401 op `/api/cron/*`-endpoints
+- **Preflight** vóór deploy: `npm run lint && npm test && npm run build` — falende build laat een PR niet door (CI blokkeert merge per ST-610)

docs/runbooks/mcp-integration.md

@@ -0,0 +1,62 @@
+---
+title: "MCP Integration — Scrum4Me Tools"
+status: active
+audience: [ai-agent]
+language: nl
+last_updated: 2026-05-03
+when_to_read: "When using MCP tools to interact with the Scrum4Me backlog."
+---
+
+# MCP-integratie
+
+Scrum4Me heeft een eigen MCP-server in repo [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) die de REST-API als native tools voor Claude Code aanbiedt. Schema's worden gedeeld via een git submodule (`vendor/scrum4me`), niet gedupliceerd.
+
+## Tools beschikbaar in Claude Code (18)
+
+**Read / context:**
+- `mcp__scrum4me__health` — service + DB ping
+- `mcp__scrum4me__list_products` — producten waar de tokengebruiker toegang tot heeft
+- `mcp__scrum4me__get_claude_context` — bundled product / actieve sprint / next story (met tasks) / open todos
+
+**Authoring (PBI/Story/Task aanmaken):**
+- `mcp__scrum4me__create_pbi` — `{ product_id, title, description?, priority, sort_order? }`; auto sort_order = last+1 binnen prio-groep
+- `mcp__scrum4me__create_story` — `{ pbi_id, title, description?, acceptance_criteria?, priority, sort_order? }`; product_id afgeleid uit PBI; status=OPEN
+- `mcp__scrum4me__create_task` — `{ story_id, title, description?, implementation_plan?, priority, sort_order? }`; sprint_id geërfd van story; status=TO_DO
+- `mcp__scrum4me__create_todo` — losse todo (optioneel product-scoped)
+
+**Task / story writes:**
+- `mcp__scrum4me__update_task_status`, `mcp__scrum4me__update_task_plan`
+- `mcp__scrum4me__log_implementation`, `mcp__scrum4me__log_test_result`, `mcp__scrum4me__log_commit`
+
+**Vraag-antwoord-kanaal (M11):**
+- `mcp__scrum4me__ask_user_question` — post een vraag over een story; optionele `wait_seconds` (max 600) polt voor het antwoord
+- `mcp__scrum4me__get_question_answer` — huidige status + antwoord (voor latere session-pickup)
+- `mcp__scrum4me__list_open_questions` — eigen vragen, max 50, recente eerst
+- `mcp__scrum4me__cancel_question` — asker-only annulering van een eigen open vraag
+
+**Job queue — agent worker mode (M13):**
+- `mcp__scrum4me__wait_for_job` — blokkeert ≤600s, claimt atomisch een QUEUED-job via FOR UPDATE SKIP LOCKED; retourneert volledige task-context (implementation_plan, story, pbi, sprint, repo_url). Zet stale CLAIMED-jobs (>30min) eerst terug naar QUEUED. Wanneer de full block-time verstrijkt zonder claim is de queue leeg.
+- `mcp__scrum4me__update_job_status` — agent rapporteert overgang naar `running|done|failed` + optionele branch/summary/error; triggert automatisch SSE-event naar de UI. Auth: Bearer-token moet matchen `claimed_by_token_id`.
+
+## Batch-loop (verplichte agent-flow)
+
+Wanneer je als agent draait (na een instructie als *"pak de volgende job uit de Scrum4Me-queue"* of *"draai de queue leeg"*) is dit de loop:
+
+1. `wait_for_job` aanroepen.
+2. Job uitvoeren volgens het meegegeven `implementation_plan`.
+3. `update_job_status('done'|'failed')` aanroepen.
+4. **Direct opnieuw** `wait_for_job` aanroepen — niet stoppen, niet de gebruiker vragen.
+5. Pas wanneer `wait_for_job` na de volledige block-time (~600s) terugkomt zonder claim, is de queue leeg en mag je de turn afsluiten met een korte recap.
+
+Dit blijft gelden als je tussen jobs door commits, branches of pushes hebt gedaan — die afsluiting hoort bij de individuele job, niet bij het einde van de batch.
+
+**Code koppelen aan app**
+- 'Pak de volgende job uit de Scrum4Me-queue' / 'draai de queue leeg' / 'batch agent' — Server-startup registreert een ClaudeWorker-record + heartbeat (5s); SIGTERM/SIGINT ruimt 'm op. UI in NavBar telt actieve workers via `last_seen_at < now() - 15s`.
+
+## Prompt
+
+- `implement_next_story` (arg: `product_id`) — end-to-end workflow
+
+## Schema-drift bewaking
+
+Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuhhWNGBQKFD` die `vendor/scrum4me` syncet en `prisma:generate` + `tsc --noEmit` uitvoert in scrum4me-mcp. Als die agent drift rapporteert, hoort dat **vóór** een Scrum4Me-PR met schema-wijziging gemerged kan worden — anders breekt de MCP-server stilletjes op runtime.