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/specs/dialogs/pbi.md

@@ -0,0 +1,128 @@
+---
+title: "PbiDialog Profiel"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-03
+---
+
+# PbiDialog Profiel
+
+> Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me).
+> Dit document beschrijft alleen de PBI-specifieke afwijkingen en keuzes — alle gedeelde regels (layout, motion, demo-policy, foutcodes, validatie, theming, dialog-gedrag) staan in de generieke spec en worden hier niet herhaald.
+
+> **Belangrijk:** als een regel in dit profiel botst met de generieke spec, wint de generieke spec. Documenteer hier de afwijking + reden, of pas de generieke spec aan.
+
+---
+
+## Velden
+
+| Veld | Type | Mode | Validatie |
+|---|---|---|---|
+| `code` | `string \| null` | beide | optional, max 30 chars, mono-font, placeholder `auto` op create (server kent dan zelf een code toe) |
+| `title` | `string` (required) | beide | trim, 1-200 chars |
+| `priority` | `int` (1-4, P1 = hoogste) | beide | int 1-4, default 2 (kan via `defaultPriority`-prop bij create) |
+| `status` | `PbiStatusApi` enum | beide | enum, default `'ready'` |
+| `description` | `string \| null` | beide | optional, max 2000 chars, plain textarea (geen markdown rendering binnen de dialog) |
+
+`PbiStatusApi` enum (lowercase, mapped via `lib/task-status.ts`): zie `<PbiStatusSelect>` voor de waarden.
+
+### Veld-specifiek gedrag
+
+- **Code + Titel** in één rij (`grid-cols-[6rem_1fr]`)
+- **Prioriteit + Status** in één rij (`grid-cols-2`)
+- **Prioriteit** via `<PrioritySelect>` (gedeelde primitive, géén segmented buttons in deze dialog)
+- **Status** via `<PbiStatusSelect>` (PBI-specifieke wrapper rond gedeelde select)
+- **Description** is `<Textarea rows={3} resize-none>` — géén auto-grow, géén markdown-hint, géén char-counter (afwijking van generieke spec; rationale: PBI-descriptions zijn doorgaans kort en richtinggevend)
+
+---
+
+## URL- of state-pattern
+
+- **Gekozen:** state-based (`state: PbiDialogState | null` prop, gerendeerd binnen `PbiList`)
+- **Reden:** PBI-dialog leeft altijd binnen `PbiList` op de product-backlog-pagina; deep-linking is niet vereist en zou een tweede edit-flow toevoegen.
+- **State-shape:**
+  ```ts
+  type PbiDialogState =
+    | { mode: 'create'; productId: string; defaultPriority?: number }
+    | { mode: 'edit'; pbi: PbiDialogPbi; productId: string }
+  ```
+- **Sluiten:** `onClose()` callback uit de parent — `setState(null)` in `PbiList`.
+
+---
+
+## Status-veld
+
+- **Default bij create:** `'ready'` (PBI-default state)
+- **Geen verberging in create-mode** — anders dan TaskDialog wordt status hier wél getoond bij create, omdat een PBI zonder expliciete status onhandig is voor backlog-grooming
+
+---
+
+## Server actions
+
+| Actie | Locatie | Form-binding | Revalidatie |
+|---|---|---|---|
+| `createPbiAction` | `actions/pbis.ts` | via `useActionState` + `<form action>` (FormData) | server-side `revalidatePath` op product-backlog |
+| `updatePbiAction` | `actions/pbis.ts` | idem | idem |
+| ~~`deletePbiAction`~~ | **(ontbreekt)** | n.v.t. | n.v.t. |
+
+Beide acties moeten de drielaagse demo-policy volgen (zie § Bekende gaps).
+
+---
+
+## Speciale gedragingen
+
+### Form-state via `useActionState`
+
+PbiDialog gebruikt het `useActionState` + `useFormStatus`-patroon (Server Actions / native React), niet `react-hook-form`. Dit is een toegestaan alternatief volgens de generieke spec § 2. Field-errors worden gemapt via een lokale `fieldError(field)`-helper die `result.error` als `Record<string, string[]>` interpreteert wanneer 'm geen string is.
+
+### `key`-prop op `<form>`
+
+Het `<form>`-element heeft `key={isEdit ? pbi!.id : 'create'}` — dit reset native form-state (defaultValues) wanneer de dialog tussen create en edit wisselt of wanneer een ander record bewerkt wordt.
+
+### Hidden inputs voor server-binding
+
+`priority` en `status` worden via `<input type="hidden">` doorgegeven aan de Server Action (de UI-controls zijn JS-state, niet directe form-fields).
+
+---
+
+## Triggers
+
+- **Create-trigger:** `+ PBI`-knop in `PanelNavBar` van `PbiList` → `setPbiDialogState({ mode: 'create', ... })`
+- **Edit-trigger:** edit-icoon op een PBI-rij in `PbiList` → `setPbiDialogState({ mode: 'edit', pbi, ... })`
+
+---
+
+## Bekende gaps t.o.v. generieke spec
+
+> Deze items wijken af van `docs/patterns/dialog.md` en horen in een vervolg-PR rechtgezet (niet onderdeel van de huidige docs-introductie).
+
+- ❌ **Geen `<DemoTooltip>`** rond submit-knop — laag 3 van de drielaagse demo-policy ontbreekt voor PBI-create/update. Dat betekent dat een demo-user de knop kan klikken; de server action blokkeert nog steeds (laag 2), maar de UX is suboptimaal.
+- ❌ **Geen delete-knop / `deletePbiAction`** — alleen create + update. Of dat bewust is (PBI's worden nooit verwijderd, alleen status veranderd) of een gat, moet expliciet worden besloten en in dit profiel vastgelegd.
+- ❌ **Geen dirty-close-guard** — Esc / backdrop / Cancel sluiten direct, ook met onopgeslagen wijzigingen. Generieke spec § 8.1 vereist een AlertDialog bij `isDirty`.
+- ❌ **Geen Cmd/Ctrl+Enter shortcut** — alleen klik op submit-knop.
+- ❌ **Geen char-counter / markdown-hint** op description — bewust weggelaten omdat PBI-descriptions kort zijn, maar verdient expliciete bevestiging.
+- ⚠️ **Layout wijkt af** van de generieke responsive-tabel: `sm:max-w-md` i.p.v. de `max-w-[50vw]` / `90vw` / full-screen-progressie uit § 4.
+
+---
+
+## Bewust NIET in v1
+
+Specifiek voor PbiDialog (boven op de algemene out-of-scope-lijst in `docs/patterns/dialog.md` § 13):
+
+- ❌ Inline aanmaken van child-stories binnen de PBI-dialog (gebeurt via StoryDialog vanuit `StoryPanel`)
+- ❌ Bulk-status-update over meerdere PBI's
+- ❌ PBI-templates / kopiëren
+
+---
+
+## Referenties
+
+- `components/backlog/pbi-dialog.tsx` — implementatie
+- `actions/pbis.ts` — server actions
+- `components/shared/priority-select.tsx` — gedeelde priority-control
+- `components/shared/pbi-status-select.tsx` — PBI-status-select
+- `lib/task-status.ts` — `PbiStatusApi`-mapper
+- `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
+- `docs/architecture.md` — datamodel `Pbi`
+- `docs/design/styling.md` — MD3-tokens, status- en priority-kleuren

docs/specs/dialogs/story.md

@@ -0,0 +1,171 @@
+---
+title: "StoryDialog Profiel"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-03
+---
+
+# StoryDialog Profiel
+
+> Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me).
+> Dit document beschrijft alleen de Story-specifieke afwijkingen en keuzes — alle gedeelde regels (layout, motion, demo-policy, foutcodes, validatie, theming, dialog-gedrag) staan in de generieke spec en worden hier niet herhaald.
+
+> **Belangrijk:** als een regel in dit profiel botst met de generieke spec, wint de generieke spec. Documenteer hier de afwijking + reden, of pas de generieke spec aan.
+
+---
+
+## Velden
+
+| Veld | Type | Mode | Validatie |
+|---|---|---|---|
+| `code` | `string \| null` | beide | optional, max 30 chars, mono-font, placeholder `auto` op create |
+| `title` | `string` (required) | beide | trim, 1-200 chars |
+| `priority` | `int` (1-4, P1 = hoogste) | beide | int 1-4, default 2 (overschrijfbaar via `defaultPriority`-prop bij create) |
+| `description` | `string \| null` | beide | optional, plain textarea, placeholder `Als… wil ik… zodat…` (user-story-template) |
+| `acceptance_criteria` | `string \| null` | beide | optional, plain textarea, placeholder `- Gegeven… Als… Dan…` (Gherkin-template) |
+| `status` | `StoryStatus` enum | alleen edit | read-only badge in header, niet bewerkbaar in deze dialog |
+
+`StoryStatus` enum: `OPEN | IN_SPRINT | DONE` (uppercase in DB).
+
+### Veld-specifiek gedrag
+
+- **Code + Titel** in één rij (`grid-cols-[6rem_1fr]`)
+- **Prioriteit** via `<PrioritySelect>` (gedeelde primitive)
+- **Description** als `<Textarea rows={3} resize-none>` — géén auto-grow, géén markdown-hint binnen de dialog (afwijking van generieke spec; rationale: stories zijn meestal één zin)
+- **Acceptatiecriteria** idem — géén auto-grow, géén char-counter
+- **Status** wordt **niet bewerkt** vanuit deze dialog. Status verandert via lijst-acties (sleep naar sprint = IN_SPRINT, taak-completion = DONE). Read-only badge in dialog-header.
+
+---
+
+## URL- of state-pattern
+
+- **Gekozen:** state-based (`state: StoryDialogState | null` prop, gerendeerd binnen `StoryPanel`)
+- **Reden:** StoryDialog leeft binnen `StoryPanel` met live-store-data (geselecteerde PBI bepaalt zichtbare stories); deep-linking zou parallelle data-fetch-paden vereisen.
+- **State-shape:**
+  ```ts
+  type StoryDialogState =
+    | { mode: 'create'; pbiId: string; productId: string; defaultPriority?: number }
+    | { mode: 'edit'; story: Story; productId: string }
+  ```
+- **Sluiten:** `onClose()` callback uit de parent — `setState(null)` in `StoryPanel`.
+
+---
+
+## Status-veld
+
+- **Niet bewerkbaar in deze dialog** — alleen weergegeven als badge in de header (edit-mode)
+- **Default bij create:** `OPEN` (server-default, niet expliciet gezet vanuit form)
+- Status-overgangen lopen via:
+  - `OPEN → IN_SPRINT` — drag-and-drop naar een sprint of `sprint-id` zetten via story-actions
+  - `IN_SPRINT → DONE` — alle taken op `DONE` zetten triggert auto-promotion (zie story-status-logic in `actions/stories.ts`)
+
+---
+
+## Server actions
+
+| Actie | Locatie | Form-binding | Revalidatie |
+|---|---|---|---|
+| `createStoryAction` | `actions/stories.ts` | via `useActionState` + `<form action>` (FormData) | server-side `revalidatePath` op product-backlog |
+| `updateStoryAction` | `actions/stories.ts` | idem | idem |
+| `deleteStoryAction` | `actions/stories.ts` | aangeroepen vanuit `useTransition` (geen form) | server-side `revalidatePath` |
+| `getStoryLogsAction` | `actions/stories.ts` | aangeroepen on-mount in edit-mode | n.v.t. (read-only) |
+
+Alle write-acties zijn drielaags afgedekt (proxy-guard + server-action-check + DemoTooltip op submit-knop).
+
+---
+
+## Speciale gedragingen
+
+### Header-presentatie (afwijking van generieke spec)
+
+In edit-mode toont de dialog-header **drie elementen** boven op de standaard titel:
+
+1. Story-titel als dialog-title (groot)
+2. Story-code als monospace-badge rechtsboven (klein)
+3. Twee badges direct onder de titel: priority-badge (kleur via `PRIORITY_COLORS`) en status-badge (kleur via `STATUS_COLORS`)
+
+Generieke spec gaat uit van een sobere header met alleen `headline-small` titel + optioneel een `created_at`-meta-string. StoryDialog wijkt hier bewust van af omdat status + priority belangrijke context zijn voor de gebruiker bij het openen van een story (vaak wisselt iemand vlot tussen meerdere stories).
+
+### Demo-modus = read-only weergave
+
+Wanneer `isDemo === true` én `isEdit === true`, wordt het form **vervangen** door een read-only weergave:
+
+- `description` via gedeelde `<Markdown>`-wrapper (`react-markdown` + `remark-gfm`)
+- `acceptance_criteria` als plain whitespace-pre-line tekst
+
+In create-mode is er voor demo-users niets te tonen — de dialog wordt alsnog geopend maar de submit-knop is `disabled` met `<DemoTooltip>`.
+
+> Dit "read-only-fallback"-patroon is uniek voor StoryDialog tot nu toe. Het zou geadopteerd kunnen worden door andere edit-dialogs zodra demo-flow-vereisten dat rechtvaardigen.
+
+### Activity-log (StoryLog) inline
+
+In edit-mode wordt onder het form een `<StoryLog>`-paneel getoond met de chronologische logs van deze story (commit-hashes, status-transitions, etc.). Logs worden lazy-fetched via `getStoryLogsAction(story.id)` zodra de dialog opent.
+
+Dit is een **read-only side-panel** en valt binnen de uitzondering die de generieke spec § 13 maakt voor `<StoryLog>`-style activity-rendering.
+
+### Delete-flow (afwijking van generieke spec)
+
+Generieke spec § 10.4 vereist een **`AlertDialog`** voor delete-confirmatie. StoryDialog gebruikt in plaats daarvan een **inline-confirm** in dezelfde footer-rij:
+
+```
+[ Weet je het zeker? Taken worden ook verwijderd.   [Verwijderen]  [Annuleren] ]
+```
+
+Een `AlertDialog` zou een tweede modale laag toevoegen die in deze context onhandig voelt (de dialog zelf is al een interruptive overlay). De inline-confirm is een **bewuste afwijking** van de generieke spec.
+
+### Form-state via `useActionState`
+
+Net als PbiDialog gebruikt StoryDialog `useActionState` + `useFormStatus`, niet `react-hook-form`. Dit is een toegestaan alternatief volgens de generieke spec § 2.
+
+### `key`-prop op `<form>`
+
+Het `<form>` heeft `key={isEdit ? story!.id : 'create'}` — reset native form-state bij record-wissel of mode-switch.
+
+---
+
+## Triggers
+
+- **Create-trigger:** `+ Story`-knop in `PanelNavBar` van `StoryPanel` → `setStoryDialogState({ mode: 'create', pbiId, productId, defaultPriority: 2 })`
+- **Edit-trigger:** edit-icoon op een story-card in `StoryPanel` → `setStoryDialogState({ mode: 'edit', story, productId })`
+- **Empty-state-trigger:** `Maak je eerste story aan`-knop in `EmptyPanel` (zelfde state als create-trigger)
+
+---
+
+## Bekende gaps t.o.v. generieke spec
+
+> Deze items wijken af van `docs/patterns/dialog.md` en horen in een vervolg-PR rechtgezet (niet onderdeel van de huidige docs-introductie).
+
+- ❌ **Geen dirty-close-guard** — Esc / backdrop / Cancel sluiten direct, ook met onopgeslagen wijzigingen. Generieke spec § 8.1 vereist een AlertDialog bij `isDirty`.
+- ❌ **Geen Cmd/Ctrl+Enter shortcut** — alleen klik op submit-knop.
+- ❌ **Geen char-counter / markdown-hint** op description / acceptance_criteria — bewust weggelaten, maar verdient expliciete bevestiging als design-keuze.
+- ⚠️ **Inline-delete-confirm** in plaats van AlertDialog (zie § Speciale gedragingen). Bewuste afwijking; de generieke spec mag deze variant expliciet toestaan, of dit profile moet als precedent gelden voor toekomstige dialogen.
+- ⚠️ **Header-layout** met meerdere badges wijkt af van de sobere header in § 4. Bewuste afwijking — context-zwaar bij story-wisselen.
+- ⚠️ **Layout wijkt af** van de generieke responsive-tabel: `sm:max-w-lg` met eigen `max-h-[90vh]` + `flex flex-col` i.p.v. de exacte `max-w-[50vw]` / `90vw` / full-screen-progressie uit § 4.
+
+---
+
+## Bewust NIET in v1
+
+Specifiek voor StoryDialog (boven op de algemene out-of-scope-lijst in `docs/patterns/dialog.md` § 13):
+
+- ❌ Status bewerken vanuit de dialog (gebeurt via lijst-acties / drag-and-drop / auto-promotion)
+- ❌ Inline aanmaken van child-tasks (gebeurt via TaskDialog vanuit `TaskPanel`)
+- ❌ Bulk-edit over meerdere stories
+- ❌ Story-templates
+- ❌ Linking aan externe issues (GitHub / Linear) — staat op v1.1+ roadmap
+
+---
+
+## Referenties
+
+- `components/backlog/story-dialog.tsx` — implementatie
+- `actions/stories.ts` — server actions (incl. `getStoryLogsAction`)
+- `components/shared/priority-select.tsx` — gedeelde priority-control
+- `components/shared/story-log.tsx` — activity-log paneel
+- `components/shared/demo-tooltip.tsx` — demo-policy laag 3
+- `components/markdown.tsx` — gedeelde markdown-wrapper
+- `lib/task-status.ts` — status-enum-mapper
+- `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
+- `docs/architecture.md` — datamodel `Story`
+- `docs/design/styling.md` — MD3-tokens, status- en priority-kleuren

docs/specs/dialogs/task.md

@@ -0,0 +1,135 @@
+---
+title: "TaskDialog Profiel"
+status: active
+audience: [ai-agent, contributor]
+language: nl
+last_updated: 2026-05-03
+---
+
+# TaskDialog Profiel
+
+> Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me).
+> Dit document beschrijft alleen de Task-specifieke afwijkingen en keuzes — alle gedeelde regels (layout, motion, demo-policy, foutcodes, validatie, theming, dialog-gedrag) staan in de generieke spec en worden hier niet herhaald.
+
+> **Belangrijk:** als een regel in dit profiel botst met de generieke spec, wint de generieke spec. Documenteer hier de afwijking + reden, of pas de generieke spec aan.
+
+---
+
+## Velden
+
+| Veld | Type | Mode | Validatie |
+|---|---|---|---|
+| `title` | `string` (required) | beide | trim, 1-120 chars |
+| `description` | `string \| null` | beide | optional, max 2.000 chars, markdown |
+| `implementation_plan` | `string \| null` | beide | optional, max 10.000 chars, markdown |
+| `priority` | `int` (1-4, P1 = hoogste) | beide | int 1-4, default 3 |
+| `status` | `TaskStatus` enum | alleen edit (default `TO_DO` op create, niet getoond) | enum |
+| `created_at` | `Date` | alleen edit | read-only metadata in header |
+
+`TaskStatus` enum: `TO_DO | IN_PROGRESS | REVIEW | DONE`.
+
+### Veld-specifiek gedrag
+
+- **Auto-grow textareas** (`description`, `implementation_plan`) via `react-textarea-autosize`. Max 6 regels (description) / 12 regels (implementation_plan), daarna `overflow-y-auto`.
+- **Karakter-counter** vanaf 75% van de limiet, klein, rechtsonder, `text-muted-foreground`. Bv. `1547 / 2000`.
+- **Markdown-hint** onder elk textarea: `Markdown ondersteund (lijstjes, **vet**, \`code\`)`.
+- **Priority** als segmented buttons via `<PrioritySelect>` / `<PrioritySegmented>`. Default P3 (Medium).
+- **Status** met gekleurde dot:
+  - `TO_DO` — grijs
+  - `IN_PROGRESS` — `status-in-progress` (blauw)
+  - `REVIEW` — paars
+  - `DONE` — `status-done` (groen)
+- **`created_at` als header-metadata** in edit-mode, naast de titel: `Aangemaakt: 23 apr 2026`. Klein, `muted-foreground`, géén form-veld.
+
+---
+
+## URL- of state-pattern
+
+- **Gekozen:** URL-based (`searchParams`)
+- **Reden:** TaskDialog wordt geopend vanuit twee context-pagina's (sprint-detail en product-backlog) en moet deep-linkable zijn voor share/refresh-scenario's. Suspense + skeleton voor edit-mode loading is gewenst.
+- **Routes:**
+  ```
+  /sprint/<sprintId>?newTask=1                      → create
+  /sprint/<sprintId>?editTask=<taskId>              → edit
+  /products/<productId>/backlog?newTask=1           → create
+  /products/<productId>/backlog?editTask=<taskId>   → edit
+  ```
+- **Sluiten:** `router.push(<base-route>)` zonder query-params.
+- **Server-side fetch in edit-mode:** server component fetcht de taak vóór render mét `productAccessFilter(userId)`. Bestaat de taak niet of valt 'm buiten scope → toast + redirect naar de context-route.
+- Optioneel: `nuqs` als de query-state-handling te omslachtig wordt — pas introduceren als losse refactor-task, niet inline.
+
+---
+
+## Status-veld
+
+Verberg `status` in **create-mode** (default = `TO_DO` is genoeg). Toon alleen in edit-mode als `<Select>` met gekleurde dot per optie.
+
+---
+
+## Server actions
+
+| Actie | Locatie | Context-arg | Revalidatie |
+|---|---|---|---|
+| `saveTask` | `app/actions/tasks.ts` | `{ sprintId?: string; productId?: string }` | `revalidatePath('/sprint/<sprintId>')` óf `revalidatePath('/products/<productId>/backlog')` afhankelijk van context |
+| `deleteTask` | `app/actions/tasks.ts` | idem | idem |
+
+Beide acties volgen de drielaagse demo-policy + auth-scoping uit `docs/patterns/dialog.md` § 6–7.
+
+---
+
+## Speciale gedragingen
+
+### Triggers (bestaande UI vervangen)
+
+Deze TaskDialog is de **enige** create/edit-flow voor taken in beide contexten (sprint én backlog). Bestaande inline-edit-paden in `components/sprint/task-list.tsx` en het backlog-equivalent worden vervangen, niet ernaast geplaatst.
+
+- **Create-trigger:** filled button `+ Nieuwe taak` in tasklist-header → zet `?newTask=1` op huidige route
+- **Edit-trigger:** klik op de hele rij in de tasklist (geen apart edit-icoon) → zet `?editTask=<id>` op huidige route
+- **Loading edit-mode:** Suspense met minimale skeleton (3 grijze balken), `200ms`-delay zodat snelle fetches geen flicker tonen
+
+### Markdown-rendering elders
+
+`description` en `implementation_plan` worden buiten de dialog (taakdetail, hover-card) gerenderd via de gedeelde `<Markdown>`-wrapper (`react-markdown` + `remark-gfm`). Niet in de dialog zelf.
+
+---
+
+## Implementatie-volgorde (suggestie)
+
+Hergebruik dit als checklist bij het bouwen of refactoren van TaskDialog:
+
+1. Dependencies in `package.json` (zie `docs/patterns/dialog.md` § 2)
+2. zod-schema in `lib/schemas/task.ts` — gedeeld door form en action
+3. `productAccessFilter`-helper checken in `lib/auth/`
+4. `saveTask` / `deleteTask` in `app/actions/tasks.ts` met auth-scoping + demo-check (laag 2)
+5. `proxy.ts`-guard voor demo-write-routes (laag 1) — alleen als nog niet aanwezig
+6. Eventueel ontbrekende MD3-tokens in `app/styles/theme.css` aanvullen
+7. `<DemoTooltip>` rond submit/delete-knoppen (laag 3)
+8. TaskDialog — create-mode eerst (minder edge cases)
+9. Edit-mode toevoegen (status, delete, `created_at`-metadata)
+10. URL-state via native `searchParams` op beide context-pagina's
+11. Bestaande task-row trigger refactoren (klikbaar maken naar dialog)
+12. Suspense + skeleton voor edit-mode + scope-check op fetch
+13. Dirty-close-guard
+14. Keyboard shortcuts (Cmd+Enter)
+
+---
+
+## Bewust NIET in v1
+
+Specifiek voor TaskDialog (boven op de algemene out-of-scope-lijst in `docs/patterns/dialog.md` § 13):
+
+- ❌ Sub-tasks / parent-child relaties tussen taken
+- ❌ Tags / labels / categorieën op taken
+- ❌ Due dates / reminders per taak
+- ❌ Time tracking (uren-registratie) — wel relevant voor inspannings-monitor, eigen feature
+- ❌ Sharing / collaboration per taak
+- ❌ Templates voor terugkerende taken
+
+---
+
+## Referenties
+
+- `docs/patterns/dialog.md` — generieke spec (bron-of-truth voor alles wat hier niet beschreven is)
+- `docs/architecture.md` — datamodel `Task`
+- `docs/design/styling.md` — MD3-tokens, status- en priority-kleuren
+- `lib/task-status.ts` — enum-mapper DB ↔ API

docs/specs/personas.md

@@ -0,0 +1,146 @@
+---
+title: "DevPlanner — User Personas"
+status: active
+audience: [maintainer]
+language: nl
+last_updated: 2026-05-03
+---
+
+# DevPlanner — User Personas
+
+**Versie:** 0.1 — april 2026
+**Volgt op:** Concept & Feature Brainstorm v0.3
+
+---
+
+## Persona-overzicht
+
+| Naam | Leeftijd | Situatie | Primaire behoefte |
+|---|---|---|---|
+| Lars | 34 | Solo developer, 4 eigen SaaS-projecten naast zijn dagtaak | Overzicht houden zonder planningssysteem te worden |
+| Dina | 28 | Freelance developer, werkt voor 3 klanten tegelijk | Klantprojecten gescheiden houden en voortgang aantonen |
+| Remi | 41 | Lead van een klein team (3 personen), geen dedicated PM | Scrum licht toepassen zonder Jira-overhead |
+
+---
+
+## Lars
+
+**Leeftijd:** 34 — **Situatie:** Solo developer met 4 actieve side projects naast een fulltime baan
+
+### Achtergrond
+
+Lars werkt overdag als backend developer bij een middelgroot bedrijf en bouwt 's avonds en in het weekend aan zijn eigen projecten: een SaaS-tool voor factuurverwerking, een open-source CLI-utility, een persoonlijk dashboard en een experimenteel AI-project. Hij werkt alleen, heeft geen teamleden en geen deadlines die van buitenaf worden opgelegd. Alles loopt via zijn hoofd of verspreide markdown-bestanden in de repositories zelf.
+
+### Een typische slechte avond
+
+Hij opent zijn laptop na het werk en weet niet meer waar hij gebleven was. In welk project zat hij? Wat stond er open? Hij herinnert zich dat er vorige week een bug was gerapporteerd in de factuur-tool, maar hij weet niet meer of hij die heeft gefixt of alleen heeft opgeschreven. Hij besteedt twintig minuten aan het doorzoeken van commit-logs en README's voordat hij kan beginnen. Als Claude Code dan eindelijk een taak oppakt, is de context al kwijt.
+
+### Hoe hij het nu oplost
+
+Elke repository heeft een `TODO.md` die hij bijhoudt zolang een project actief is. Als hij een week niet heeft gekeken, is het bestand achterhaald. Prioritering is impliciet — hij werkt aan wat op dat moment het interessantst voelt, niet aan wat het belangrijkst is. Jira heeft hij één keer geprobeerd voor zijn side projects: duurde twee uur om in te richten en stopte na drie weken.
+
+### Doelen met deze app
+
+- Elke avond binnen één minuut weten welke taak het meest urgent is per project
+- Claude Code laten oppakken wat open staat zonder zelf de context te hoeven herstellen
+- Achteraf kunnen zien wat er gedaan is en hoe (implementatieplan, commit, testresultaat)
+- Op klantbezoek of bij familie zijn side projects kunnen demonstreren op een geleende laptop, zonder dat hij zijn wachtwoord op een vreemd toetsenbord hoeft te typen — door zijn telefoon (waar hij al ingelogd is) een QR-code op het scherm te laten scannen
+
+### Frustraties om te vermijden
+
+- Verplichte velden en formulieren die langer duren dan de taak zelf
+- Systemen die vragen om updates die hij toch niet bijhoudt (daily standup-achtige inputs)
+- Alles wat aanvoelt als "project management voor grote teams" — hij is de enige gebruiker
+
+### Relatie met technologie
+
+Power user. Leeft in de terminal, gebruikt Claude Code dagelijks, bouwt zijn eigen tooling als iets hem niet bevalt. Wil een app die hij ook via een API kan aansturen.
+
+---
+
+## Dina
+
+**Leeftijd:** 28 — **Situatie:** Freelance full-stack developer, werkt parallel voor drie klanten
+
+### Achtergrond
+
+Dina werkt als zelfstandige en heeft op dit moment drie lopende klantprojecten: een e-commerceplatform in onderhoudsfase, een nieuw admin-dashboard voor een logistiek bedrijf en een kleine MVP voor een startup. Elk project heeft zijn eigen ritme, zijn eigen repo en zijn eigen verwachtingen. Ze werkt alleen maar heeft per klant een contactpersoon die wil weten wat er gedaan is.
+
+### Een typische slechte dag
+
+Ze heeft drie context-switches voor de lunch. Het logistiek-dashboard heeft een bugmelding binnengekomen, de startup wil een update, en de e-commerce klant heeft een vraag over iets wat twee Sprints geleden geleverd is. Ze heeft geen centraal overzicht — ze zoekt in Slack-threads, e-mails en commit-logs om te reconstrueren wat er wanneer gedaan is. Aan het eind van de dag heeft ze productief werk gedaan maar kan ze niet meer zeggen wat precies.
+
+### Hoe ze het nu oplost
+
+Elk klantproject heeft een Notion-pagina met een ruwe takenlijst. Notion is flexible maar heeft geen structuur die Scrum-begrippen begrijpt. Ze heeft geprobeerd Trello te gebruiken maar het mist de hiërarchie die ze nodig heeft (project → feature → taak). Ze voelt dat ze iets robuusters nodig heeft nu het derde project erbij is gekomen.
+
+### Doelen met deze app
+
+- Per klant een gestructureerde Product Backlog bijhouden zonder overlap
+- Snel kunnen antwoorden op "wat heb je de afgelopen week gedaan?" met concrete verwijzingen naar commits en stories
+- Claude Code gebruiken voor routinetaken zodat zij zich kan richten op complexere beslissingen
+
+### Frustraties om te vermijden
+
+- Systemen waarbij klantdata vermengd raakt (ze wil strikte projectscheiding)
+- Dashboards die statistieken tonen die ze niet nodig heeft (velocity, burndown)
+- Alles wat ze verplicht dagelijks bij te houden — ze heeft soms een dag vrij of ziek
+
+### Relatie met technologie
+
+Comfortabel maar niet fanatiek. Gebruikt VS Code, GitHub en een handvol SaaS-tools. Geen terminal-purist zoals Lars — ze gebruikt liever een goede UI dan een CLI als beide beschikbaar zijn.
+
+---
+
+## Remi
+
+**Leeftijd:** 41 — **Situatie:** Lead developer van een team van drie, zonder dedicated projectmanager
+
+### Achtergrond
+
+Remi werkt bij een klein softwarebedrijf met in totaal acht mensen. Zijn team bestaat uit hemzelf en twee juniordevelopers. Ze bouwen interne tools voor twee afdelingen en onderhouden drie legacy-systemen. Er is geen Scrum Master, geen Product Owner en geen projectmanager — Remi doet dat er allemaal bij. Hij heeft Scrum gelezen en wil het toepassen, maar Jira is te zwaar en te duur voor hun schaal. Ze werken nu met een gedeeld Excel-bestand dat niemand consequent bijhoudt.
+
+### Een typische slechte week
+
+Ze beginnen maandagochtend zonder duidelijk Sprint-doel. Iedereen werkt aan wat binnenkomt. Woensdag vraagt zijn manager naar de status van het rapportage-dashboard. Remi weet dat er aan gewerkt is maar niet hoe ver het is. Hij moet twee junioren ondervragen en drie feature-branches bekijken om een antwoord te kunnen geven. Vrijdagmiddag hebben ze een "retrospective" die eigenlijk een statusmeeting is.
+
+### Hoe hij het nu oplost
+
+Excel voor taakregistratie, Teams-kanalen per project voor communicatie, GitHub Issues voor bugs. Drie systemen die niet met elkaar praten. Hij heeft Linear geprobeerd maar de leercurve was te groot voor de junioren. Hij zoekt iets dat hij in een middag kan inrichten en dat zijn teamleden zonder training kunnen gebruiken.
+
+### Doelen met deze app
+
+- Elke Sprint starten met een duidelijk Sprint Goal dat iedereen ziet
+- Wekelijks in één scherm kunnen zien wat open staat, wat in progress is en wat klaar is
+- In de toekomst rollen kunnen toewijzen aan teamleden zodat de Product Owner (hijzelf) en de Developers (de junioren) gescheiden rechten hebben
+
+### Frustraties om te vermijden
+
+- Alles wat de junioren extra werk geeft zonder directe waarde voor hen
+- Rapportages en grafieken die hij niet nodig heeft
+- Systemen waarbij hij afhankelijk is van een externe SaaS die duur wordt bij groei
+
+### Relatie met technologie
+
+Ervaren developer, maar kiest bewust voor eenvoud. Wil een tool die hij zelf kan hosten als dat goedkoper uitpakt. Waardeert open source maar heeft geen tijd om een tool te onderhouden die hij zelf gebouwd heeft.
+
+---
+
+## Persona-spanningen
+
+| Spanning | Lars wil | Dina wil | Remi wil | Oplossing |
+|---|---|---|---|---|
+| API vs. UI | Alles via API en Claude Code | Goede UI, API is bonus | UI eerst, team moet het kunnen gebruiken | UI is primair; API is volwaardige burgerklasse, niet bijzaak |
+| Eén vs. meerdere gebruikers | Altijd solo | Solo maar met klantcontext | Team van 3 met rolscheiding | v1 is solo; rolbeheer is v1-fundament voor v2-teamuitbreiding |
+| Scrum-striktheid | Licht, pragmatisch | Structuur helpt maar geen dogma | Wil Scrum leren toepassen | Scrum-terminologie consistent; events zijn optioneel, niet verplicht |
+| Zichtbaarheid voortgang | Eigen overzicht, geen rapportages | Klantverantwoording via commits | Teamstatus in één scherm | Activiteitenlog per story volstaat voor alle drie; aparte rapportagelaag is v2 |
+
+---
+
+## Primaire persona
+
+**Lars** is de primaire designtarget voor v1.
+
+Rationale: Lars vertegenwoordigt de meest veeleisende gebruiker in termen van API-integratie en Claude Code-koppeling — de kern-differentiator van DevPlanner. Als de app goed werkt voor Lars (solo, API-gedreven, meerdere projecten, minimale overhead), werkt het ook voor Dina (zelfde gebruik, lichtere techvoorkeur). Remi's behoeften — teamgebruik en rolscheiding — zijn bewust naar v2 verschoven; het fundament (rolmodel in de datastructuur) wordt in v1 al gelegd.
+
+Een feature die Lars zou doen stoppen — verplichte velden, trage UI, geen API — wordt niet gebouwd, ook niet als Remi er baat bij zou hebben.