diff --git a/docs/README.md b/docs/README.md index 560a442..6e70d4f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,7 @@ | Topic | File | Use | |---|---|---| | AI excellence due diligence | [ai-excellence-due-diligence-roadmap.md](/home/hartmut/Documents/Copilot/capakraken/docs/ai-excellence-due-diligence-roadmap.md) | Frank quality assessment and cleanup roadmap toward a showcase AI-built project | +| Showcase quality backlog | [showcase-quality-backlog.md](/home/hartmut/Documents/Copilot/capakraken/docs/showcase-quality-backlog.md) | Consolidated working backlog for the current quality and maintainability north star | | Target CI/CD architecture | [cicd-target-architecture.md](/home/hartmut/Documents/Copilot/capakraken/docs/cicd-target-architecture.md) | Canonical image-based build, deploy, and rollback flow | | Active roadmap and open gaps | [product-roadmap.md](/home/hartmut/Documents/Copilot/capakraken/docs/product-roadmap.md) | Primary backlog and current delivery order | | Estimating system design | [estimating-extension-design.md](/home/hartmut/Documents/Copilot/capakraken/docs/estimating-extension-design.md) | Workbook analysis, field mapping, and implementation plan | diff --git a/docs/showcase-quality-backlog.md b/docs/showcase-quality-backlog.md new file mode 100644 index 0000000..8060166 --- /dev/null +++ b/docs/showcase-quality-backlog.md @@ -0,0 +1,203 @@ +# 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](/home/hartmut/Documents/Copilot/capakraken/docs/ai-excellence-due-diligence-roadmap.md) +- [architecture-hardening-backlog.md](/home/hartmut/Documents/Copilot/capakraken/docs/architecture-hardening-backlog.md) +- [domain-slices-backlog.md](/home/hartmut/Documents/Copilot/capakraken/docs/domain-slices-backlog.md) +- [api-router-procedure-support-backlog.md](/home/hartmut/Documents/Copilot/capakraken/docs/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. +- 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](/home/hartmut/Documents/Copilot/capakraken/docs/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](/home/hartmut/Documents/Copilot/capakraken/docs/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](/home/hartmut/Documents/Copilot/capakraken/docs/api-router-procedure-support-backlog.md) +- [ai-excellence-due-diligence-roadmap.md](/home/hartmut/Documents/Copilot/capakraken/docs/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](/home/hartmut/Documents/Copilot/capakraken/docs/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](/home/hartmut/Documents/Copilot/capakraken/docs/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](/home/hartmut/Documents/Copilot/capakraken/docs/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](/home/hartmut/Documents/Copilot/capakraken/docs/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