# Showcase Execution Batches **Date:** 2026-04-01 **Purpose:** Canonical execution list for the remaining work to turn CapaKraken into a clean, deterministic, reviewable reference project for disciplined AI-assisted engineering. ## How To Use This List - Work top to bottom unless a hard blocker forces resequencing. - Keep slices small enough to verify and commit cleanly. - Every touched slice must add at least one non-happy-path regression. - Do not broaden scope while the worktree is dirty. - A batch is done only when code, tests, and documentation for that slice are aligned. ## Batch Status Legend - `todo`: not started - `active`: current execution lane - `blocked`: waiting on a hard external dependency or product decision - `done`: implemented, verified, and committed ## Batch 1: Timeline Stability And Interaction Discipline Status: `active` Why first: the timeline is the highest-risk UX surface and still not boringly reliable enough for the showcase goal. Progress note: - 2026-04-01: overlay cleanup on timeline `viewMode` changes and initial-loading transitions landed with targeted e2e regression coverage for allocation popovers across view switches. - 2026-04-01: viewport-change behavior was tightened so point-anchored timeline popovers close on scroll/resize, while element-anchored hover cards remain repositionable; the viewport regression now passes with a non-happy-path e2e. - 2026-04-01: active timeline gestures now cancel on window blur / hidden-tab transitions instead of leaving drag or resize state stranded; regression coverage verifies a mid-resize focus loss reverts the preview and allows the next interaction to proceed cleanly. - 2026-04-01: timeline SSE reconnect now performs a one-shot catch-up invalidation on the next successful `onopen`, so missed updates during disconnects do not leave the timeline stale until a later event arrives. Slices: - `todo` stabilize popover and hover behavior across scroll, resize, reload, and view switches - `todo` verify drag, resize, and selection interactions do not compete under rapid input changes - `todo` verify SSE first-load, reconnect, and live-update behavior under churn - `todo` close explicit edge/failure test gaps in timeline e2e and targeted component tests - `todo` continue shrinking [TimelineView.tsx](/home/hartmut/Documents/Copilot/capakraken/apps/web/src/components/timeline/TimelineView.tsx) into narrower ownership units without changing behavior Done criteria: - timeline overlays stay anchored under scroll and resize - timeline view switching and first-load state are deterministic - drag and selection paths remain stable under quick repeated interactions - SSE reconnects do not leave stale or empty timeline state - touched timeline slices have non-happy-path regression coverage ## Batch 2: Holiday/Vacation Parity And Explainability Status: `todo` Why next: it is a cross-cutting correctness area that benefits from the same deterministic test discipline without expanding architecture too early. Slices: - `todo` identify remaining parity gaps between API, UI, assistant, widgets, and exports - `todo` unify holiday- and vacation-aware forecast derivations where outputs still diverge - `todo` standardize compact vs detailed explainability surfaces - `todo` add regression coverage for mismatch and boundary scenarios, not only nominal calculations Done criteria: - the same holiday and vacation basis is visible across all user-facing surfaces - explainability is consistent and concise by default - parity is backed by targeted cross-surface tests ## Batch 3: Resource Read Decomposition And Smaller Ownership Surfaces Status: `todo` Why next: this is the lowest-conflict structural cleanup explicitly called out as ready in the API backlog. Slices: - `todo` split resource read orchestration out of `resource-read-shared.ts` into focused read helpers without changing API contracts - `todo` keep router files thin and procedure-support focused - `todo` continue breaking down large frontend ownership surfaces, starting with [ProjectWizard.tsx](/home/hartmut/Documents/Copilot/capakraken/apps/web/src/components/projects/ProjectWizard.tsx) - `todo` add focused tests around extracted helpers before broadening further Done criteria: - `resource-read-shared.ts` no longer acts as a monolithic read hotspot - extracted helpers have narrow responsibilities and direct tests - large frontend modules have smaller reviewable ownership seams ## Batch 4: Notification, Task, And Broadcast Reliability Residuals Status: `todo` Why now: this is important operational hardening, but below timeline and read-surface cleanup in immediate risk. Slices: - `todo` identify remaining missing-reference and retry edge cases - `todo` stabilize error translation so failures stay domain-shaped and predictable - `todo` narrow orchestration helpers where the current flow still mixes concerns - `todo` add regression coverage for retry, missing-target, and partial-failure scenarios Done criteria: - reminder, task, and broadcast flows fail cleanly under race and retry conditions - errors stay stable for callers - touched orchestration surfaces are smaller and easier to review ## Batch 5: CI Guardrails And Measurable Quality Gates Status: `todo` Why now: the goal is a reference project where quality is enforced by CI, not by memory or chat history. Slices: - `todo` add file-size or ownership-surface checks for the next critical hotspots - `todo` strengthen auth and permission regression coverage around sensitive routers - `todo` add package-level quality gates beyond generic pass/fail test runs - `todo` add bundle or route-size monitoring where growth risk is already known Done criteria: - CI fails on structural regressions, not only syntax and test failures - sensitive permission surfaces have explicit regression protection - critical source hotspots are under measurable guardrails ## Batch 6: Operational Standardization Status: `todo` Why now: one production path and one rollback path are core to the showcase goal. Slices: - `todo` make Redis-backed rate limiting the intentional deployed default - `todo` document one deploy path and one rollback path with verification steps - `todo` finish runtime-secret and environment-backed configuration discipline - `todo` verify the documented path against the current CI/CD and deploy docs Done criteria: - production deployment and rollback are documented as single canonical flows - runtime config sources are explicit and consistent - operational defaults match the documented architecture ## Batch 7: Reference Project Artifacts Status: `todo` Why last: these artifacts should capture the standards proven by the earlier technical batches. Slices: - `todo` add `docs/engineering-doctrine.md` - `todo` add `docs/ai-collaboration-standards.md` - `todo` document one exemplary frontend slice and one exemplary backend slice end to end - `todo` align those docs with the actual CI, testing, and ownership guardrails in the repo Done criteria: - the repository explains not only what was built, but how quality is maintained - AI-assisted collaboration standards are explicit, reviewable, and enforceable - at least two reference slices demonstrate the intended discipline end to end ## Immediate Execution Order 1. Batch 1: timeline stability and test closure 2. Batch 2: holiday/vacation parity 3. Batch 3: resource read decomposition 4. Batch 5: CI guardrails 5. Batch 4: notification/task/broadcast residuals 6. Batch 6: operational standardization 7. Batch 7: reference project artifacts ## Working Notes - The demand/assignment migration itself is treated as complete and is not the active blocker anymore. - The current north star is showcase quality, deterministic behavior, and smaller ownership surfaces. - If a new bug appears in a P0/P1 UX surface, fix it before resuming lower-priority batches.