# 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.
- 2026-04-01: timeline SSE now pauses while the tab is hidden and reconnects with a one-shot resync after visibility returns, which reduces background reconnect churn without trusting missed live events to self-heal.

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.
