# Agent Instruction Audit

Datum: 2026-04-25

## Aanleiding

Tijdens de code review kwamen twee soorten fouten naar voren:

- Server Actions vertrouwden client-provided IDs te veel nadat alleen de parent-resource was gecontroleerd.
- Documentatie liep achter op dependency-, API- en deploymentwijzigingen.

Dit document legt vast welke wijzigingen zijn gecontroleerd, welke documentatie is bijgewerkt en welke instructies Claude Code en Codex voortaan expliciet moeten volgen.

## Gecontroleerde wijzigingen

| Wijziging | Code-locatie | Documentatie bijgewerkt |
|---|---|---|
| Reorder-acties valideren alle IDs binnen de juiste parent-scope | `actions/stories.ts`, `actions/sprints.ts` | `docs/scrum4me-architecture.md`, `docs/patterns/server-action.md`, `docs/patterns/sort-order.md`, `CLAUDE.md`, `AGENTS.md` |
| Sprint afronden accepteert alleen stories uit de actieve sprint | `actions/sprints.ts` | `docs/scrum4me-architecture.md`, `docs/patterns/server-action.md`, `AGENTS.md` |
| Todo-promotie gebruikt scoped todo lookup en `pbi.product_id` als bron van waarheid | `actions/todos.ts` | `docs/scrum4me-architecture.md`, `docs/patterns/server-action.md`, `CLAUDE.md`, `AGENTS.md` |
| `GET /api/products` retourneert ook gedeelde producten via `product_members` | `app/api/products/route.ts` | `README.md`, `docs/scrum4me-functional-spec.md`, `docs/scrum4me-backlog.md`, `docs/patterns/route-handler.md` |
| `sharp` is directe runtime dependency | `package.json`, `package-lock.json` | `README.md`, `docs/scrum4me-architecture.md`, `CLAUDE.md` |
| Vercel Analytics is toegevoegd aan de root layout | `app/layout.tsx`, `package.json`, `package-lock.json` | `README.md`, `docs/scrum4me-architecture.md`, `CLAUDE.md` |
| `.env.example` ontbrak ondanks verwijzingen in architectuurdocs | `.env.example` | `README.md`, `docs/scrum4me-architecture.md` |

## Preventieve regels

### Access-control regels

Agents mogen nooit aannemen dat een ID veilig is omdat de UI hem normaal gesproken correct doorgeeft. Elke Server Action en Route Handler moet bij writes de volledige resource-scope bewijzen.

Concrete regels:

- Gebruik `productAccessFilter(userId)` voor product-scoped resources waar eigenaar en teamlid toegang hebben.
- Gebruik owner-only filters alleen bij echte eigenaarsacties.
- Valideer bulk-ID's met `id in (...)` plus parent-scope voordat er wordt geschreven.
- Weiger dubbele IDs in reorder- en decision-payloads.
- Leid denormalized foreign keys af van de database-parent, niet van client-input.
- Valideer runtime waarden met Zod of expliciete runtime checks; TypeScript types alleen zijn onvoldoende.
- Gebruik scoped deletes/updates nadat ownership bewezen is.

### Documentatie-regels

Een codewijziging is niet klaar als de documentatie een oud contract beschrijft. Agents moeten bij elke wijziging nagaan of deze plekken geraakt worden:

- `README.md`: setup, scripts, dependencies, deployment, API-overzicht.
- `docs/scrum4me-functional-spec.md`: functionele eisen en API-contracten.
- `docs/scrum4me-architecture.md`: stack, datamodel, securitymodel, env vars, deployment.
- `docs/scrum4me-backlog.md`: "done when"-criteria en scope van backlog-items.
- `docs/patterns/`: herbruikbare implementatiepatronen.
- `CLAUDE.md` en `AGENTS.md`: agent-regels die de fout in de toekomst voorkomen.

### Dependency-regels

- Elke runtime import moet als directe dependency in `package.json` staan.
- Als een dependency aan deploymentgedrag raakt, moet README of architectuurdocs dat noemen.
- Na `npm install` moet `package-lock.json` meegaan in dezelfde change.

### Verification-regels

Voor oplevering:

```bash
npm run lint
npm test
npm run build
```

Bij securitywijzigingen hoort minimaal een test die laat zien dat cross-user of cross-scope input wordt geweigerd. Als die test nog niet bestaat, noteer dat expliciet in de oplevering.

## Claude Code

`CLAUDE.md` is aangescherpt met:

- een verwijzing naar dit auditdocument;
- de directe stackwijzigingen voor Sharp en Vercel Analytics;
- expliciete access-control regels voor `productAccessFilter`, bulk-ID's en foreign-key afleiding;
- een docs-sync regel voor gedrags-, API-, dependency- en deploymentwijzigingen.

## Codex

`AGENTS.md` is uitgebreid van alleen Next.js-waarschuwing naar projectregels voor:

- access control;
- documentatie-sync;
- verificatiecommands.

Deze regels zijn korter dan `CLAUDE.md`, maar bewust dwingend: ze moeten direct gelezen worden bij elke Codex-taak in deze repo.