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>
2026-04-27 00:28:58 +02:00 · 2026-04-27 00:28:58 +02:00 · 86a5397517
commit 86a5397517
parent c8bab7396a
2 changed files with 130 additions and 2 deletions
--- a/CLAUDE.md
+++ b/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)
--- a/docs/agent-instruction-audit.md
+++ b/docs/agent-instruction-audit.md
@ -86,3 +86,88 @@ Bij securitywijzigingen hoort minimaal een test die laat zien dat cross-user of
 - verificatiecommands.

 Deze regels zijn korter dan `CLAUDE.md`, maar bewust dwingend: ze moeten direct gelezen worden bij elke Codex-taak in deze repo.
+
+---
+
+# Agent Instruction Audit — Round 2
+
+Datum: 2026-04-27
+
+## Aanleiding
+
+Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow raakt:
+
+- **ST-509** Todo description (max 2000)
+- **ST-511** Entity codes voor Product/PBI/Story (auto-default + manual override + retry op race condition)
+- **ST-512** REST API uitgebreid met `code`, `description`, `implementation_plan` in alle endpoints
+- **ST-513** API hardening voor Claude Code: `GET /api/health`, `GET /api/products/:id/claude-context`, lowercase status-enums op de API-grens, `StoryLog.metadata` JSONB, validatie-fouten van `400` → `422`, nieuwe `docs/API.md`
+- **PR #2 Codex-review-saga** — 8 testbestanden faalden bij de contract-flip; tests werden niet meebijgewerkt. Twee P2-issues van Codex: malformed JSON moet `400` blijven (P2.1), en `status: review` werd geaccepteerd terwijl de sprint-UI er niet mee om kan gaan (P2.2)
+- **M7: scrum4me-mcp** — aparte MCP-server repo (`madhura68/scrum4me-mcp`) met 9 tools en 1 prompt voor Claude Code, schema gedeeld via git submodule
+- **lib/code.ts vs lib/code-server.ts** — gesplitst om client-bundle vrij te houden van `pg` (gaf eerst `Module not found: 'dns'` build-error)
+- **Wekelijkse schema-drift cron** (`trig_015FFUnxjz9WMuhhWNGBQKFD`) — remote agent die ma 08:00 Amsterdam de MCP-submodule syncet en typecheckt
+
+## Gecontroleerde wijzigingen
+
+| Wijziging | Code-locatie | Documentatie bijgewerkt |
+|---|---|---|
+| Lowercase status-enums op REST-grens, mappers naar DB-enum | `lib/task-status.ts`, `app/api/tasks/[id]/route.ts`, `app/api/sprints/[id]/tasks/route.ts`, `app/api/products/[id]/next-story/route.ts` | `docs/API.md`, `CLAUDE.md` |
+| 400 (malformed JSON) gescheiden van 422 (zod-validatie) | `app/api/tasks/[id]/route.ts`, `app/api/stories/[id]/tasks/reorder/route.ts`, `app/api/todos/route.ts`, `app/api/stories/[id]/log/route.ts` | `docs/API.md`, `CLAUDE.md` |
+| `status: review` geweigerd door PATCH `/api/tasks/:id` zolang sprint-UI geen REVIEW rendert | `app/api/tasks/[id]/route.ts` | `docs/API.md` |
+| Entity codes (Product/PBI/Story) met auto-default + retry-on-P2002 | `actions/products.ts`, `actions/pbis.ts`, `actions/stories.ts`, `lib/code.ts`, `lib/code-server.ts` | `docs/scrum4me-backlog.md` (ST-511) |
+| `StoryLog.metadata` JSONB | `prisma/schema.prisma`, `prisma/migrations/20260426214905_add_story_log_metadata/`, `app/api/stories/[id]/log/route.ts` | `docs/API.md` |
+| Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/API.md`, `CLAUDE.md` |
+| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/scrum4me-backlog.md` (M7) |
+
+## Nieuwe preventieve regels
+
+### Test-pariteit bij contract-wijziging
+
+Een wijziging die een API-contract aanraakt (status, foutcode, response-shape, request-shape) is pas klaar als `__tests__/api/` in dezelfde commit meegaat. Wat NIET acceptabel is:
+
+- "Tests gaan rood maar de implementatie is correct" — herstel óf implementatie óf test, niet later
+- Stilletjes 8 testbestanden laten breken zoals in PR #2 — Codex/CI vangt het, maar te laat in de cyclus
+
+### Status-enums boundary-conversie
+
+API exposeert lowercase, DB houdt UPPER_SNAKE. Conversie uitsluitend via `lib/task-status.ts`-mappers (`taskStatusToApi`, `taskStatusFromApi`, `storyStatusToApi`, `storyStatusFromApi`). Verboden:
+
+- Ad-hoc `status.toLowerCase()` of `status.toUpperCase()` in route handlers
+- Direct vergelijken van API-input met DB-enum (`if (body.status === 'IN_PROGRESS')`) — input is altijd lowercase
+- Een nieuwe enum-waarde toevoegen zonder de mapper bij te werken
+
+### Error-code split 400/422
+
+- `400`: parse-fout op `request.json()` — wikkel altijd in `try/catch`
+- `422`: zod-validatie of well-formed-maar-niet-acceptabel (bv. `task_id` van andere story)
+- `403`: demo-token op write
+- Documenteer per endpoint in `docs/API.md`
+
+### Client/server module-boundary
+
+`lib/foo-server.ts` mag DB-calls (`prisma`), node-only deps (`pg`, `crypto.createHash`) en server-actions doen. `lib/foo.ts` is pure helpers, client-veilig. Een client-component (`'use client'`) mag nooit uit een `*-server.ts`-module importeren — dat haalt `pg` of `dns` mee de bundle in en breekt de build.
+
+### Verplichte verificatie vóór oplevering
+
+Naast bestaande lint/test/build-stappen voor MCP-relevante wijzigingen ook:
+
+```bash
+# In scrum4me-mcp na een schema-wijziging in Scrum4Me:
+npm run sync-schema && npm run prisma:generate && npm run typecheck
+```
+
+De wekelijkse cron doet dit automatisch, maar ad-hoc checken is nog steeds verstandig vóór een Scrum4Me-PR met migratie naar productie gaat.
+
+## Claude Code
+
+`CLAUDE.md` is uitgebreid met:
+
+- Specificatiedocumenten-rij voor `madhura68/scrum4me-mcp`
+- Dual-track workflow (Track A: MCP-prompt; Track B: manueel)
+- Twee patroon-rijen: `lib/task-status.ts` en client/server module-boundary
+- Vier nieuwe conventies: entity codes in commits, lowercase API-status, error-code split, test-pariteit
+- Nieuwe sectie "MCP-integratie" met tools, prompt en schema-drift cron
+- Definition of Done expliciet als MVP-scope; M7 is post-MVP
+
+## Codex
+
+`AGENTS.md` is in deze ronde **niet** bijgewerkt — Codex heeft geen MCP-toegang en de Track B-workflow daar werkt nog. Bij volgende ronde apart uitbreiden met de status-enum/error-code/test-pariteit regels (die zijn ook voor Codex relevant).