CapaKraken/docs/showcase-quality-backlog.md

Showcase Quality Backlog

Date: 2026-04-01 Purpose: Canonical working backlog for the current north star: turn CapaKraken into a clean, reviewable, deterministic reference project for disciplined AI-assisted software engineering.

North Star

The goal is not "ship more code at any cost". The goal is:

• small ownership surfaces
• deterministic behavior and repeatable tests
• explicit permission and runtime boundaries
• clean deploy and rollback discipline
• documentation that makes the structure explainable
• visible engineering quality that holds up under fast AI-assisted change

Canonical Inputs

This backlog consolidates the still-relevant work from:

• ai-excellence-due-diligence-roadmap.md
• architecture-hardening-backlog.md
• domain-slices-backlog.md
• api-router-procedure-support-backlog.md

Working Rules

• Every touched slice must gain regression coverage for edge, guard, or failure cases, not only happy paths.
• Prefer narrow, verifiable slices over broad refactors.
• Keep public contracts stable unless a product decision explicitly changes them.
• Avoid expanding architecture surface area while the current worktree is dirty or shared ownership is unclear.

Current Baseline

Already materially improved:

• SSE audience scoping is under CI guardrails.
• repo script guardrails are now test-backed in CI
• critical narrow ownership surfaces now have explicit maxLines architecture checks
• runtime secret handling is environment-first
• assistant-tool and several router monoliths were decomposed
• image-based CI/CD and deploy flow exists
• focused test coverage around several high-risk paths has been expanded

Still open at the quality-showcase level:

• Timeline UX and live-update stability are not yet "boringly reliable".
• Some large frontend/API ownership surfaces are still too wide.
• measurable architecture and quality guardrails are not complete yet
• operational discipline still depends too much on convention and current context

Priority Stack

P0. Worktree Hygiene And Deterministic Test Discipline

Status: active, always-on

Done means:

• no generated or accidental artifacts stay tracked
• shared worktree changes are either validated, isolated, or explicitly left untouched
• every touched regression suite covers at least one non-happy-path case
• time- and timezone-sensitive tests are stabilized

Immediate checks:

• keep the current timeline WIP isolated until it is either validated or cleaned
• continue tightening router/read-model tests where fragile assumptions still exist

P1. Timeline Interaction, Overlay, And SSE Stability

Status: active Source: domain-slices-backlog.md

Remaining work:

• finish popover, hover, drag, and overlay stability across scroll, resize, reload, and view changes
• verify first-load, reconnect, and live-update behavior under SSE churn
• close remaining timeline test gaps with explicit edge/failure cases
• clean up the current timeline component worktree safely before broadening scope

Definition of done:

• timeline popovers and overlays behave consistently under scroll/resize/reload
• drag and selection interactions do not fight each other
• SSE reconnects do not leave the UI in a stale or empty state

P2. Holiday/Vacation Correctness And Explainability Parity

Status: active Source: domain-slices-backlog.md

Remaining work:

• close the remaining forecast/widget parity gaps for holiday-/vacation-aware derivations
• ensure UI, assistant, dashboard detail, and export views expose the same calculation basis
• keep explainability compact by default and detailed only when explicitly requested

Definition of done:

• the same holiday/vacation logic is visible and test-backed across API, assistant, widgets, and exports

P3. Resource Read Decomposition And Smaller Ownership Surfaces

Status: next structural cleanup Sources:

• api-router-procedure-support-backlog.md
• ai-excellence-due-diligence-roadmap.md

Remaining work:

• split resource-read-shared.ts into focused read helpers without changing public contracts
• continue shrinking large timeline/frontend modules into easier ownership units
• keep top-level routers/components thin and orchestration-only

Definition of done:

• the next deep read-model hotspot is decomposed
• large ownership surfaces become easier to review and test in isolation

P4. Notification/Task/Broadcast Reliability Residuals

Status: active but below timeline/resource cleanup Source: domain-slices-backlog.md

Remaining work:

• close the last persistence and fanout edge cases
• keep error translation stable and domain-shaped under missing-reference races
• continue moving complex orchestration toward narrower support helpers where useful

Definition of done:

• reminder, broadcast, and task workflows fail cleanly and predictably under missing-reference and retry scenarios

P5. Measurable Guardrails In CI

Status: open Source: ai-excellence-due-diligence-roadmap.md

Remaining work:

• add file-size or ownership-surface guardrails for critical source files
• add stronger auth/permission regression coverage around sensitive routers
• add measurable package-level quality gates beyond "tests pass"
• monitor web bundle or route size where growth risk is known

Definition of done:

• CI can fail for structural regressions, not only syntax or unit failures

P6. Operational Standardization

Status: open Source: ai-excellence-due-diligence-roadmap.md

Remaining work:

• make Redis-backed rate limiting an intentional deployed default, not a best-effort fallback
• document and rehearse one rollback path
• finish deploy/bootstrap/cleanup discipline around runtime secrets and environment-backed config

Definition of done:

• one production path, one rollback path, one runtime config source of truth

P7. Reference-Project Artifacts

Status: open Source: ai-excellence-due-diligence-roadmap.md

Remaining work:

• add an engineering doctrine for AI-assisted changes
• add explicit AI collaboration standards for file growth, tests, and docs
• curate a small set of exemplary slices that demonstrate the intended standards end to end

Suggested artifacts:

• docs/engineering-doctrine.md
• docs/ai-collaboration-standards.md
• reference-slice documentation for one API slice and one frontend slice

Practical Order From Here

If the goal is to keep momentum without widening risk, the recommended execution order is:

1. finish or safely isolate the current Timeline worktree changes
2. continue non-happy-path coverage on touched timeline/resource reads
3. complete the remaining holiday/vacation parity gaps
4. decompose resource-read-shared.ts
5. return to residual notification reliability edges
6. add the next CI guardrail instead of another broad refactor

Exit Criteria For This Backlog

This backlog is complete when:

• the main UX-critical surfaces are stable under edge conditions
• the next major oversized ownership surfaces are reduced
• quality is enforced by CI guardrails, not memory
• operations are repeatable and documented
• the repository visibly demonstrates disciplined AI-assisted engineering rather than just fast iteration