Nexus/docs/showcase-execution-batches.md

Showcase Execution Batches

Date: 2026-04-01 Purpose: Canonical execution list for the remaining work to turn Nexus 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 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
• 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.