docs(workflow): align CLAUDE.md with M7 and post-PR-#2 contract (#4)

Update agent-facing docs to match the workflow that actually shipped
in ST-509/511/512/513 and M7 (scrum4me-mcp).

CLAUDE.md
- Spec-tabel: link toegevoegd naar de scrum4me-mcp repo
- Waar te beginnen: dual-track — Track A via mcp__scrum4me__implement_
  next_story (aanbevolen), Track B is de bestaande manuele 7-stappen
  loop voor Codex/zonder MCP
- Implementatiepatronen: rijen voor lib/task-status.ts mappers en
  client/server module-boundary (bv. lib/code.ts vs lib/code-server.ts)
- Conventies: entity codes in commit-titles, lowercase API-status,
  400/422 error-code split, verplichte test-pariteit bij contract-
  wijziging
- Nieuwe sectie "MCP-integratie" — alle 9 tools + prompt +
  schema-drift cron (trig_015FFUnxjz9WMuhhWNGBQKFD, ma 08:00 Amsterdam)
- Definition of Done expliciet als MVP; M7 is post-MVP

agent-instruction-audit.md
- Round 2 (2026-04-27) sectie met aanleiding, gecontroleerde
  wijzigingen en nieuwe preventieve regels (test-pariteit,
  status-enum boundary, error-code split, module-boundary)

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

CLAUDE.md

@@ -24,6 +24,7 @@ Lees het relevante document voordat je aan een feature begint. Nooit gokken over
 | `docs/API.md` | REST-API contract voor Claude Code — endpoints, status-enums, foutcodes, voorbeeld-curls |
 | `docs/scrum4me-styling.md` | **Lees dit voor elk component** — MD3-kleuren, shadcn patronen |
 | `docs/agent-instruction-audit.md` | Waarom de agent-instructies zijn aangescherpt; checklist voor toekomstige wijzigingen |
+| [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) | MCP-server repo: native tools voor Claude Code, schema-sync via git submodule |
 
 ---
 
@@ -37,7 +38,18 @@ M0 (ST-001–008) → M1 (ST-101–110) → M2 (ST-201–210)
 → M6 (ST-601–612)
 ```
 
-Per task:
+Werken aan een task kan via twee tracks. Track A heeft de voorkeur als je in Claude Code zit; Track B is voor Codex of omgevingen zonder MCP.
+
+### Track A — via Claude Code MCP (aanbevolen)
+
+1. Roep `mcp__scrum4me__implement_next_story` aan met `product_id` (gebruik `mcp__scrum4me__list_products` als je het id niet weet)
+2. De prompt orkestreert: `get_claude_context` → `log_implementation` → per task `update_task_status(in_progress)` → bouw → `update_task_status(done)` → `log_test_result` → `log_commit`
+3. Bouw de tasks in volgorde van `sort_order`; lees per task de relevante pattern-doc en styling
+4. Verifieer: `npm run lint && npm test && npm run build`
+5. Commit per laag (zie Commit Strategy)
+
+### Track B — manueel (Codex of zonder MCP)
+
 1. Lees de task in `scrum4me-backlog.md`
 2. Zoek de bijbehorende feature-spec in `scrum4me-functional-spec.md`
 3. Lees het relevante patroon in `docs/patterns/` en styling in `docs/scrum4me-styling.md` als dat van toepassing is
@@ -85,6 +97,8 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
 | Zustand optimistische update + rollback | `docs/patterns/zustand-optimistic.md` |
 | Float sort_order drag-and-drop | `docs/patterns/sort-order.md` |
 | Middleware (route protection) | `docs/patterns/middleware.md` |
+| Status-enum mapping (DB ↔ API) | `lib/task-status.ts` |
+| Client/server module-boundary | `*-server.ts` bevat DB-calls of node-only deps; `*.ts` is pure (client-safe). Nooit `import { ... } from '@/lib/foo-server'` in een client-component, anders krijg je `Module not found: 'dns'`/`'pg'`-style runtime fouten |
 
 ---
 
@@ -110,6 +124,10 @@ SESSION_SECRET=""      # openssl rand -base64 32
 - **Foutberichten:** Nederlands voor eindgebruikers — comments in code: Engels
 - **Dependencies:** elke geïmporteerde runtime package staat direct in `dependencies`, niet alleen transitief in `package-lock.json`
 - **Docs-sync:** elke gedrags-, dependency-, API- of deploymentwijziging werkt README, relevante docs en patterns bij in dezelfde change
+- **Entity codes:** gebruik product/PBI/story-codes in commit-titles wanneer aanwezig (`feat(ST-356.2): ...`); branchnaam blijft `feat/ST-XXX-slug`
+- **Status-enums op API:** lowercase (`todo|in_progress|review|done`, `open|in_sprint|done`); DB houdt UPPER_SNAKE; conversie uitsluitend via `lib/task-status.ts`-mappers — nooit ad-hoc `.toLowerCase()` elders
+- **Foutcodes API:** `400` alleen voor malformed JSON-body (parse-fout via `request.json()`); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteer per endpoint in `docs/API.md`
+- **Tests volgen contract:** bij een API-contract-wijziging (status, foutcode, response-shape) MOET in dezelfde commit ook `__tests__/api/` mee — een test die rood gaat omdat de oude waarde wordt verwacht is een onvolledige wijziging, niet een "kapotte test"
 
 ---
 
@@ -174,7 +192,32 @@ docs(ST-XXX): document profile feature
 
 ---
 
-## Definition of Done
+## 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
+
+- `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
+- `mcp__scrum4me__update_task_status`, `mcp__scrum4me__update_task_plan`
+- `mcp__scrum4me__log_implementation`, `mcp__scrum4me__log_test_result`, `mcp__scrum4me__log_commit`
+- `mcp__scrum4me__create_todo`
+
+### 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.
+
+---
+
+## Definition of Done (MVP)
+
+M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/scrum4me-backlog.md`.
 
 - [ ] Alle 62 tasks (ST-001 t/m ST-612) afgerond
 - [ ] Volledige Lars-flow zonder fouten (ST-612)