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>
