docs: AI-optimized docs restructure (Phases 1–8) (#61)

* docs(dialog-pattern): add generic entity-dialog spec

Introduceert docs/patterns/dialog.md als bron-of-truth voor elke
create/edit/detail-dialog in Scrum4Me, ongeacht het achterliggende
dataobject. Bevat 14 secties: uitgangspunten, stack, component-
architectuur, layout, validatie, drielaagse demo-policy, submission,
dialog-gedrag, theming, footer, triggers/URL-state, per-entiteit
profile-template, out-of-scope, en een verificatie-checklist.

Registreert het patroon in CLAUDE.md "Implementatiepatronen"-tabel
zodat Claude (en mensen) de spec verplicht raadplegen voor elke
nieuwe dialog.

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

* docs(dialog-pattern): convert task spec + add pbi/story entity-profiles

Reduceert docs/scrum4me-task-dialog.md van 507 naar ~140 regels: alle
gedeelde regels verhuisd naar docs/patterns/dialog.md, dit document
bevat nu alleen Task-specifieke velden, URL-pattern, status-veld,
server actions, triggers en bewuste out-of-scope-keuzes.

Voegt twee nieuwe entity-profielen toe voor bestaande dialogen:
- docs/scrum4me-pbi-dialog.md (PbiDialog: state-based, code+title-rij,
  PbiStatusSelect, geen delete in v1)
- docs/scrum4me-story-dialog.md (StoryDialog: state-based, header met
  status/priority badges, inline activity-log, demo-readonly-fallback,
  inline-delete-confirm i.p.v. AlertDialog)

Beide profielen documenteren expliciet de "Bekende gaps t.o.v.
generieke spec" zodat opvolgende PR's de afwijkingen kunnen
rechtzetten of bewust kunnen accorderen.

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

* Added pdevelopment docs

* docs(plans): add docs-restructure plan for AI-optimized lookup

Audit of existing 39 doc files (~10.700 lines) and a phased restructure
proposal aimed at minimising the tokens an AI agent has to read to find
the right reference. Captures resolved decisions on language (English),
ADR template (Nygard default with MADR escape-hatch), index generator
(node script), and folder taxonomy. Proposal status — fase 1 to follow.

* docs(adr): add ADR scaffolding (templates, README, meta-ADR)

Set up docs/adr/ as the canonical home for architecture decisions:

- templates/nygard.md — default four-section format (Status, Context,
  Decision, Consequences) for one-way-door decisions.
- templates/madr.md — MADR v4 with YAML front-matter and explicit
  Considered Options for decisions where rejected alternatives matter.
- README.md — naming convention (NNNN-kebab-case), template-selection
  guidance (Nygard default; MADR for auth, queue mechanics, agent
  integration), status lifecycle, and ADR roster.
- 0000-record-architecture-decisions.md — meta-ADR establishing the
  practice itself, in Nygard format.

Backfilling existing implicit decisions (base-ui-over-radix, float
sort_order, demo-user three-layer policy, etc.) is fase 6 of the
docs-restructure plan.

* feat(docs): add docs index generator + initial INDEX.md

scripts/generate-docs-index.mjs walks docs/**/*.md, parses YAML
front-matter (or first H1 fallback) and a Nygard-style ## Status
section, then writes docs/INDEX.md with grouped tables for ADRs,
Specs, Plans (with archive subsection), Patterns, and Other.

Pure Node 20 (no external deps); idempotent — running it twice
produces byte-identical output. Excludes adr/templates/, the ADR
README, INDEX.md itself, and any *_*.md sidecar file.

Wire-up:
- package.json: docs:index → node scripts/generate-docs-index.mjs

Initial run indexed 35 docs across the existing structure; the
generated INDEX.md is committed so the table is reviewable in the
PR before hooking generation into a pre-commit step.

* chore: ignore Obsidian vault and personal sidecar files

Add .obsidian/ (Obsidian vault config) and _*.md (personal sidecar
notes) to .gitignore so the docs/ tree can serve as canonical source
of truth while still being usable as an Obsidian vault for personal
authoring. The docs index generator already excludes the same _*.md
pattern from INDEX.md.

* docs(plans): add PBI bulk-create spec for docs-restructure

Machine-parseable spec for an executor that calls the scrum4me MCP
(create_pbi → create_story → create_task) to seed the docs-restructure
work into the DB.

- Section 1 (Context) is the PBI description; serves as task-context
  via mcp__scrum4me__get_claude_context.
- Section 2 lists the 6 resolved decisions (English, MD3+styling
  merged, solo-paneel merged, .Plans archived, Nygard ADR default,
  node index script).
- Section 3 records what already shipped on this branch so the
  executor doesn't duplicate the ADR scaffolding or index generator.
- Section 4 carries the structured YAML graph: 1 PBI, 8 stories
  (one per phase), 39 tasks. product_id is REPLACE_ME — fill before
  running.
- YAML validated with PyYAML; field schema sanity-checked.

* docs(junk-cleanup): remove stub patterns/test.md

* docs(junk-cleanup): archive .Plans/ to docs/plans/archive/

* docs(front-matter): add YAML front-matter to docs/ root

* docs(front-matter): add YAML front-matter to patterns/

* docs(front-matter): add YAML front-matter to plans + agent files

* docs(index): regenerate INDEX.md after front-matter pass

* docs(naming): drop scrum4me- prefix from doc filenames

* docs(naming): lowercase API.md and MD3 filenames

* docs(naming): rename plan file to kebab-case ASCII

* docs(naming): rename middleware.md to proxy.md (next 16)

* docs(naming): polish CLAUDE.md doc-index after renames

* docs(taxonomy): scaffold topical folders under docs/

* docs(taxonomy): move spec files into docs/specs/

* docs(taxonomy): move design/api/qa/backlog/assets into folders

* docs(taxonomy): move agent-instruction-audit into decisions/

* docs(split): break architecture.md into 6 topical files

* docs(split): merge solo-paneel-spec into specs/functional.md

* docs(split): merge md3-color-scheme into design/styling

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

* docs(trim): extract MCP integration into runbook

* docs(adr): add 0001-base-ui-over-radix

* docs(adr): add 0002-float-sort-order

* docs(adr): add 0003-one-branch-per-milestone

* docs(adr): add 0004-status-enum-mapping

* docs(adr): add 0005-iron-session-over-nextauth

* docs(adr): add 0006-demo-user-three-layer-policy

* docs(adr): add 0007-claude-question-channel-design

* docs(adr): add 0008-agent-instructions-in-claude-md + update README index

* docs(index): regenerate after ADR 0001-0008

* docs(glossary): add docs/glossary.md

* chore(docs): regenerate INDEX.md in pre-commit hook

* docs(readme): link INDEX + glossary + agent instructions

* feat(docs): add doc-link checker script

* chore(docs): wire docs:check-links and docs npm scripts

* ci(docs): block merge on broken doc links

* docs(links): fix broken cross-references after restructure

---------

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

docs/decisions/agent-instructions-history.md

@@ -0,0 +1,181 @@
+---
+title: "Agent Instruction Audit"
+status: active
+audience: [maintainer]
+language: en
+last_updated: 2026-05-03
+---
+
+# 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/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/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/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/specs/functional.md`, `docs/backlog/index.md`, `docs/patterns/route-handler.md` |
+| `sharp` is directe runtime dependency | `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` |
+| Vercel Analytics is toegevoegd aan de root layout | `app/layout.tsx`, `package.json`, `package-lock.json` | `README.md`, `docs/architecture.md`, `CLAUDE.md` |
+| `.env.example` ontbrak ondanks verwijzingen in architectuurdocs | `.env.example` | `README.md`, `docs/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/specs/functional.md`: functionele eisen en API-contracten.
+- `docs/architecture.md`: stack, datamodel, securitymodel, env vars, deployment.
+- `docs/backlog/index.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.
+
+---
+
+# 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/rest-contract.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: 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/rest-contract.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/rest-contract.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/rest-contract.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/backlog/index.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/rest-contract.md` |
+| Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/api/rest-contract.md`, `CLAUDE.md` |
+| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/backlog/index.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/rest-contract.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 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).