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.
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.
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.
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.
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.
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>
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>
Three SSE-routes (solo, backlog, notifications) each create a long-
running pg.Client that LISTENs on scrum4me_changes. On abrupt close
(Fast Refresh, browser refresh, Vercel function recycle) the
pgClient.end()-await sometimes hangs silently, leaving the underlying
socket connected to Postgres. The connection stays in 'idle' on Neon's
side and after ~10-20 reconnects the connection-pool fills up — new
SSE connects fail with ERR_INCOMPLETE_CHUNKED_ENCODING in the browser.
Fix: shared `closePgClientSafely` helper that races client.end()
against a 2 s timeout; on timeout it force-destroys the underlying
socket so the OS releases the FD and Postgres notices the disconnect.
Validated by direct DB inspection: 18 stale 'idle LISTEN'-connections
were piled up before the fix; after manual pg_terminate_backend cleanup
the SSE-stream stabilised. This change makes the pile-up impossible
going forward.
- new lib/realtime/pg-client-cleanup.ts
- 3 routes use the helper instead of bare `await pgClient.end()`
- 3 unit tests for the helper (timely-end, hang-falls-back-to-destroy,
end-rejection-is-swallowed)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
These three docs/smoke-test-*.md files were created by the
branch-per-story flow smoke-test (PR #42, story cmon1q0do0023bortliq2tae9).
The flow worked correctly — confirmed in DB: 1 branch + 1 PR for 3
tasks, verify_result populated, worktree-cleanup deferred until the
last sub-task. Files served their purpose and can now be removed.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Re-introduce the 3 unique files from closed PRs #37 and #40 that
overlap-merged with already-landed sub-PRs (#34, #35, #36, #38, #39):
- app/(app)/insights/page.tsx — Server Component dat alle helpers
parallel aanroept en de 5 sectie-Cards rendert (Sprint Health,
Plan-quality, Agent throughput, Velocity, Backlog health)
- app/(app)/insights/components/sprint-info-strip.tsx — chips per
active sprint met productname + goal + dagen-over + taakcount
- app/(app)/insights/components/alignment-trend.tsx — Recharts
LineChart die % ALIGNED jobs per sprint over laatste 5 sprints toont
- lib/insights/verify-stats.ts — TrendPoint type + getAlignmentTrend
helper (uitgebreid van PR #38)
Plus dependency: recharts (was in package.json van #37/#40 die we
sloten).
Tests: 290/290 groen, tsc clean, lint clean.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: voeg recharts toe aan dependencies
Vereist door PlanQualityCard component.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: getVerifyResultStats helper (lib/insights/verify-stats.ts)
Aggregeert verify_result counts en top-5 EMPTY/DIVERGENT jobs over de laatste N dagen.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: PlanQualityCard — verify_result donut + top-5 EMPTY/DIVERGENT tabellen
PieChart (donut) met ALIGNED/PARTIAL/EMPTY/DIVERGENT verdeling, MD3-kleuren.
Twee tabellen rechts met Next.js Link deeplinks naar TaskDetailDialog.
Empty-state met link naar Plan-verify gating story.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Aggregeert verify_result counts (ALIGNED/PARTIAL/EMPTY/DIVERGENT) en top-5 EMPTY/DIVERGENT
jobs over de laatste N dagen voor de ingelogde gebruiker.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: voeg recharts toe aan dependencies
Vereist door SprintStatusDonut component.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: SprintStatusDonut + getSprintStatusBreakdown helper
PieChart (donut) met TO_DO/IN_PROGRESS/DONE verdeling over alle active sprints.
REVIEW wordt samengevoegd in IN_PROGRESS. MD3 status-kleuren via CSS-variabelen.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: getBurndownData helper + computeBurndownDays (lib/insights/burndown.ts)
Server-side aggregatie per active sprint: bouwt time-series met remaining en ideal per dag.
Inclusief 4 Vitest-unit-tests voor de pure computeBurndownDays functie.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: voeg recharts toe aan dependencies
Vereist door BurndownChart component in lib/insights.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: BurndownChart component (Recharts LineChart, ideal vs remaining)
LineChart met two series: ideal (grijs, dashed) en remaining (status-in-progress blauw).
ResponsiveContainer 100% x 240px, empty-state bij lege days-array.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Server-side aggregatie per active sprint: bouwt time-series met remaining en ideal per dag.
Inclusief 4 Vitest-unit-tests voor de pure computeBurndownDays functie.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update CLAUDE.md worker-presence batch-loop notitie
* chore: voeg .mcp.json, .codex/ en Brainstro toe aan .gitignore
Voorkomt dat lokale MCP-credentials en scratch-bestanden per ongeluk gecommit worden.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: update allowed-tools in settings.local.json
Voegt MCP- en bash-permissies toe die tijdens M13-implementatie gebruikt zijn.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: add pushed_at field to ClaudeJob schema
Nullable DateTime column to record when the agent's feature branch was
pushed to origin. Enables the UI to show a 'pushed' state independently
of DONE status.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(db): promote task naar IN_PROGRESS bij ClaudeJob CLAIMED/RUNNING
Solo-kaart bleef in 'Te doen'-kolom staan terwijl de agent al bezig
was — alleen DONE was via een trigger gekoppeld (vorige migration).
Nieuwe Postgres-trigger claude_job_claim_to_task: bij INSERT of
UPDATE OF status naar CLAIMED|RUNNING promoot de bijbehorende task
van TO_DO naar IN_PROGRESS. Forceert niet vanuit andere status —
handmatige overrides (REVIEW, DONE) blijven staan.
De bestaande notify_task_change-trigger op tasks zorgt automatisch
voor de pg_notify zodat de Solo-paneel-UI direct synct.
- migration: 20260501130000_promote_task_to_in_progress_on_claim
- doc: architecture.md sectie 'Auto-promote task-status op job-overgangen' uitgebreid
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: SoloBoard layout naar SplitPane met cookie-persistentie en tab-collapse
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: verplaats Live + agent-status indicators naar NavBar
Live-dot (SSE-status) en "Agent verbonden / Geen agent" indicator zijn
verhuisd van de SoloBoard-header naar de NavBar (rechts, voor de
notifications-bell). Data blijft uit useSoloStore komen, gevoed door
SoloRealtimeBridge in de (app)-layout. Indicators tonen alleen op
/products/[id]/solo — buiten die route is de SSE-stream inactief.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: open SoloRealtimeBridge globaal voor active product
SoloRealtimeBridge gated nu op active-product i.p.v. /solo-pad. Live-dot
en worker-presence werken daardoor op alle (app)-pagina's
(Producten/PB/Sprint/Solo/Todo's). Buiten /solo is de solo-store leeg en
zijn task-events no-ops, dus de stream gedraagt zich automatisch als
lichte presence-stream tot SoloBoard mount.
- realtime-bridge: productId-prop i.p.v. usePathname
- (app)/layout: activeProduct?.id doorgegeven aan bridge
- nav-status-indicators: pathname-check vervangen door hasActiveProduct prop
- nav-bar: hasActiveProduct={!!activeProduct} doorgegeven
- architecture-doc: realtime connection lifecycle bijgewerkt
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: enqueueAllTodoJobsAction voor batch-queueing van TO_DO-taken
Nieuwe Server Action die alle TO_DO-taken van een product zonder
actieve ClaudeJob in één $transaction als QUEUED jobs aanmaakt en
voor elk een pg_notify('claude_job_enqueued') stuurt zodat de SSE-
stream de UI live bijwerkt.
- Auth + demo-blokkade + product-access via productAccessFilter
- Idempotent: tasks met status QUEUED/CLAIMED/RUNNING worden overgeslagen
- 4 nieuwe tests (happy path, count=0, demo-blokkade, geen toegang)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: 'Start agents (n)'-knop in Solo header, productname weg
SoloBoard-header toont nu een primary button die het aantal queueable
TO_DO-taken telt (TO_DO zonder actieve ClaudeJob via
claudeJobsByTaskId-store) en bij klik de nieuwe
enqueueAllTodoJobsAction aanroept. Toast geeft het aantal gestarte
agents terug.
- productname-h1 verwijderd (staat al in NavBar-dropdown, dubbel)
- sprintdoel blijft naast de knop
- 'Toon openstaande stories'-link blijft rechts
- demo-modus disabled met DemoTooltip
- batch-pending state voorkomt dubbele klikken
- productName-prop weg uit SoloBoard + page.tsx (was alleen voor h1)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: scope enqueueAllTodoJobsAction op actieve sprint + assignee
De action queue'de eerder ALLE TO_DO-taken van een product, ongeacht
sprint of assignee — terwijl de 'Start agents (n)'-knop in de UI
alleen de taken telt die de gebruiker ziet (actieve sprint, eigen
stories). Daardoor kreeg een klik op de knop veel meer jobs aangemaakt
dan de count suggereerde (62 i.p.v. de getoonde n).
Server-filter komt nu overeen met page.tsx solo-query:
story: { sprint_id: <activeSprint>, assignee_id: userId }
Edge case: geen actieve sprint → success met count=0 (geen error).
Tests aangepast + nieuwe test voor 'geen actieve sprint'-pad.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(db): trigger sync_task_status_from_claude_job promote task naar DONE
Postgres AFTER-trigger op claude_jobs.status zet de bijbehorende
task automatisch op DONE zodra de job DONE wordt — werkt ongeacht
welke client de update doet (MCP-server, Server Action, raw SQL).
Idempotent: WHERE status <> 'DONE' voorkomt no-op updates die de
bestaande notify_task_change-trigger zouden doen vuren. Die laatste
verzorgt de pg_notify naar /api/realtime/solo zodat de UI synct.
- migration: prisma/migrations/20260501110000_sync_task_status_from_claude_job
- doc: nieuwe sectie 'Auto-promote task naar DONE' in architecture.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(ui): vul SoloColumn-kolommen volledige paneelhoogte
Buitenste flex-container van SoloColumn miste h-full, waardoor het
kader op content-hoogte bleef hangen i.p.v. de hele pane (binnen
SplitPane) te vullen. Drop-target was daardoor ook beperkt tot het
kleine kader bovenin een lege kolom.
Auto-toegepast door een ClaudeJob-agent op task
cmomoayt10002bortgp27jwma; co-auteurschap hieronder.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: agent-batch-loop verplichte flow in CLAUDE.md
Na een 'pak de volgende job'-instructie liep de agent één job en sloot
de turn af, waardoor de gebruiker handmatig opnieuw 'wait_for_job'
moest aanroepen voor elke volgende job in de queue.
Voeg een expliciete loop-instructie toe onder de MCP-tools-sectie:
na elke update_job_status moet de agent opnieuw wait_for_job
aanroepen, totdat die na de full block-time terugkomt zonder claim.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: add plan_snapshot field to ClaudeJob schema
Nullable String? column on claude_jobs captures the task's
implementation_plan at claim time — immutable baseline for drift detection.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: update ClaudeJob lifecycle with plan_snapshot
Document state machine snapshot capture/reset, plan_snapshot field
rationale, and drift-detection baseline semantics.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor: remove duplicate header labels on backlog page
Both the product H1 + description in the page header and the
"Product Backlog" panel-title in the PBI panel duplicated info
already visible in the NavBar. Removed both, keeping the right-aligned
action bars (activate/sprint/settings, plus filters/+PBI) intact.
PanelNavBar component is unchanged — Stories and Taken panels keep
their titles.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore(ST-1112): add deps for task dialog
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): add shared zod schema for task dialog
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): add missing MD3 tokens for task dialog
outline-variant, on-error-container, status-review (light + dark)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): add saveTask and deleteTask server actions for TaskDialog
Unified create/edit action (saveTask) replaces separate formData-based
actions for the new TaskDialog. Uses shared zod schema, structured
SaveTaskResult union type, and context-aware revalidatePath for both
sprint and backlog routes.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): add TaskDialog component (create & edit mode)
Builds the full TaskDialog on top of the existing @base-ui/react
Dialog primitive. Covers create mode, edit mode (status field +
created_at metadata + delete), dirty-check AlertDialog, delete
confirm AlertDialog, Cmd+Enter submit, and per-field char counters.
Uses react-hook-form + zodResolver against the shared taskSchema.
Priority and status are extracted to PrioritySegmented and
StatusSelect sub-components using MD3 tokens throughout.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): refactor task-list to open TaskDialog via URL params
Replaces inline create/edit forms with router.push navigation:
- Clicking a task row → ?editTask=<id>
- "+ Taak" button → ?newTask=1&storyId=<storyId>
Removes CreateTaskForm, EditSubmitButton, updateTaskAction, and
createTaskAction from the component. Status toggle and DnD remain
unchanged. Rows now have cursor-pointer and keyboard a11y.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): wire TaskDialog into sprint page via searchParams
Sprint page now reads ?newTask, ?storyId, and ?editTask query params.
For edit mode: fetches the task server-side with productAccessFilter
scope (invalid/foreign IDs redirect to closePath). Renders TaskDialog
when either param is present. closePath is the sprint route without
query params.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): add Suspense skeleton for edit-mode task loading
Extracts task fetch into EditTaskLoader (async server component) so
the sprint board renders immediately while the task loads.
TaskDialogSkeleton shows 3 grey bars during the fetch. Invalid or
out-of-scope task IDs redirect to closePath.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): render description as markdown in task-detail-dialog
Solo task detail now renders description via react-markdown +
remark-gfm with prose styling. Sanitizes script/iframe elements.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(ST-1112): add saveTask/deleteTask server action tests
Covers all three demo-policy layers and cross-tenant scope:
demo blocked (403), unauthenticated blocked, validation 422,
edit cross-tenant forbidden, create cross-tenant forbidden,
and happy-path for both edit and create.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): add updateTaskStatusWithStoryPromotion helper
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1112): wire story-promotion into saveTask and PATCH /api/tasks/:id
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(ST-1112): add task-dialog doc and architecture note
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: extend allowed tools in settings.local.json
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1113): add 200ms animation-delay to TaskDialogSkeleton to prevent flicker
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1114): add DirtyCloseGuard reusable component for dirty-form close confirmation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(ST-1114): add shared Markdown wrapper, apply to task-detail and story-dialog
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: allow grep -E pattern in settings.local.json
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
