From 381c908ef3609746835d97007b1c49eb372d8c81 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Mon, 4 May 2026 15:36:37 -0700 Subject: [PATCH] docs: add completion checklist for audit backlog Add an execution-focused checklist that translates the redesign and platform audit ledgers into phases, acceptance criteria, gates, and final quality bars. This gives future work a single playbook while keeping AUDIT_REDESIGN.md and AUDIT_PLATFORM.md as the status sources of truth. Co-Authored-By: GPT-5 Codex --- docs/COMPLETION_CHECKLIST.md | 375 +++++++++++++++++++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 docs/COMPLETION_CHECKLIST.md diff --git a/docs/COMPLETION_CHECKLIST.md b/docs/COMPLETION_CHECKLIST.md new file mode 100644 index 0000000..97d3128 --- /dev/null +++ b/docs/COMPLETION_CHECKLIST.md @@ -0,0 +1,375 @@ +# Trading Redesign + Platform Audit Completion Checklist + +Last updated: 2026-05-04 + +This document is the execution checklist for driving the trading redesign and +platform audit to high-quality completion. The source-of-truth status tables +remain `docs/AUDIT_REDESIGN.md` in this repo and +`/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md` +in the platform repo. Use this checklist to decide what to do next, what "done" +means, and which gates must pass before pushing. + +## Operating Rules + +- Work top-down unless the human explicitly reprioritizes. +- Keep one audit item, or one tightly coupled bucket, per implementation commit. +- Tick the audit table after the implementation commit and record the short hash + of the implementation commit in the audit row. +- Source `~/.zshrc` in every shell before package-manager commands so + `GITEA_NPM_TOKEN` is available. +- Do not touch platform nomgap WIP files: + `docker-compose.ecosystem.yml`, `products/nomgap/product.json`, + `services/platform-service/src/modules/flags/seed.ts`. +- Do not commit incidental lockfile changes except when the audit item + specifically owns the lockfile. +- Do not skip verification gates, even for docs-adjacent changes that alter the + audit workflow. +- If a change alters public API contracts, exported schemas, endpoint payloads, + or auth behavior, pause and confirm unless the audit item explicitly requires + that contract change. + +## Current Snapshot + +Completed in trading: + +- [x] `A1-A6` Critical integration repairs. +- [x] `E2` Root pnpm lockfile includes redesigned web dependencies. +- [x] `F7-F8` Previously known web test failures fixed; web suite is fully green. +- [x] `B1` RSI, MACD, and Bollinger indicator toggles are wired in `StockChart`. + +Open high-priority trading work: + +- [ ] `B2+B3` Wire `TickerHeader` Watchlist/alert buttons and real company name. +- [ ] `C2` Add in-memory FMP cache. +- [ ] `F6` Add backend endpoint coverage for the new market/research endpoints. +- [ ] `C1` Refuse or sandbox code strategy backtests. +- [ ] `B6` Persist `CodeStrategyEditor` saves through canonical profile APIs. +- [ ] `D1` Replace plain loading copy with skeleton loaders. +- [ ] `D5` Add responsive web layout behavior. + +Open platform work: + +- [ ] `P-sweep` Clear the 85 surfaced lint errors package-by-package. +- [ ] `R3-R4` Optional package-manager noise cleanup. + +## Required Gates + +Run these before claiming a trading item is complete: + +```bash +source ~/.zshrc +npm --prefix web run typecheck +npm --prefix web run build +npm --prefix web test +npx tsc --noEmit -p backend/tsconfig.json +``` + +Expected trading result: + +- `web typecheck`: exit 0. +- `web build`: exit 0 and `✓ built`. +- `web test`: 155/155 passing after `F7-F8`. +- `backend tsc`: exit 0. + +Run these before claiming a platform item is complete: + +```bash +source ~/.zshrc +pnpm typecheck +pnpm test +pnpm lint > /tmp/lint.log 2>&1 +``` + +Expected platform result: + +- `pnpm typecheck`: exit 0. +- `pnpm test`: all suites pass. +- `pnpm lint`: error count must go down for the package being fixed and must not + introduce new warnings/errors elsewhere. + +## Priority Work Queue + +### Phase 1 - Finish Web Functional Gaps + +- [ ] `B2` Wire Watchlist button. + Acceptance: button has a real click path, visible active/inactive state, + accessible label/title, and no misleading "saved" state before persistence. + If no backend watchlist endpoint exists, implement a scoped local persistence + path only if the UI copy clearly says local/watchlist preference, otherwise + create or reuse the proper API after confirming contract. + +- [ ] `B3` Pull company name from `fetchResearchProfile`. + Acceptance: `TickerHeader` shows `companyName` when available, falls back to + symbol when unavailable, handles loading/error without layout jump, and avoids + duplicate FMP calls when `ResearchCards` already fetches the same profile. + +- [ ] `B4` Use latest chart bar timestamp for "as of". + Acceptance: header timestamp is derived from market data, not wall-clock + render time. Fallback is explicit when no bars exist. + +- [ ] `B5` Compute QuickStats for searched symbols. + Acceptance: RSI/EMA values populate for tickers not tracked by the bot, using + chart bars or a shared indicator helper. Avoid duplicate indicator math drift + between `StockChart` and `QuickStats`. + +- [ ] `B6` Persist `CodeStrategyEditor` saves. + Acceptance: Save calls canonical profile creation/update API, surfaces backend + errors, preserves local draft behavior only as a draft/recovery mechanism, and + saved code strategies appear where users expect to find them. + +- [ ] `B7` Remove or use unused `editorRef`. + Acceptance: no dead ref remains, or it powers a concrete behavior such as + formatting/focus/save integration. + +- [ ] `B8` Wire visual-builder backtest action. + Acceptance: `ResearchView` passes `onBacktest`, the button appears in the + visual builder, and payload shape matches `/api/backtest/run`. + +- [ ] `B9` Integrate saved visual/code strategies into Strategies tab. + Acceptance: strategies saved in the new builders are discoverable in the + existing Strategies tab without duplicating stores or creating divergent data + models. + +- [ ] `B10` Add React Router catch-all route. + Acceptance: invalid paths show a useful 404/return-home state instead of a + blank screen, with tests if routing tests already exist. + +### Phase 2 - Security, Correctness, and Quota Protection + +- [ ] `C2` Add FMP response cache. + Acceptance: server-side in-memory cache uses full URL as key, TTL is 30 + minutes, concurrent callers do not stampede where reasonable, failed responses + are not cached, and logs/metrics can distinguish cache hit/miss. + +- [ ] `C1` Refuse or sandbox `strategyConfig.type === 'code'`. + Acceptance: `/api/backtest/run` cannot execute arbitrary unsandboxed user JS. + Minimum acceptable fix is a clear 400 response for code strategies with a user + safe error message and a test proving refusal. A sandbox implementation needs + resource limits, timeout, no filesystem/network access, and malicious-code + tests. + +- [ ] `C3` Validate screener sector query. + Acceptance: unsupported sectors are rejected or ignored predictably, FMP calls + receive only allow-listed sector values, and the frontend handles validation + errors cleanly. + +- [ ] `C4` Validate news symbols query. + Acceptance: symbols are normalized, length-limited, and restricted to expected + equity/crypto symbol formats before proxying to Alpaca. + +- [ ] `C5` Pause market-index polling when tab is hidden. + Acceptance: polling stops while `document.visibilityState === 'hidden'`, + resumes on visible, cleans up event listeners, and does not double-create + intervals after route changes. + +- [ ] `C6` Remove FMP demo-key ambiguity. + Acceptance: `.env.example`, runtime config, and server fallback agree on how + missing `FMP_API_KEY` behaves. Prefer explicit missing-key failure for + production and documented demo-only local behavior. + +- [ ] `C7` Mitigate FMP key exposure. + Acceptance: cache from `C2` is in place, logs avoid printing full FMP URLs + with `apikey`, and docs explain that FMP requires query-string auth. + +### Phase 3 - Tests and Regression Nets + +- [ ] `F6` Backend tests for new endpoints. + Acceptance: tests cover `/api/chart/bars`, `/api/news`, + `/api/market/indices`, `/api/research/profile`, `/api/research/metrics`, + `/api/research/earnings`, and `/api/screener`. Include happy path, upstream + failure, auth/validation behavior, and crypto chart routing where applicable. + +- [ ] `F1` Tests for `web/src/lib/marketApi.ts`. + Acceptance: authenticated headers, request-id header, URL encoding, success + parsing, and error body fallback are covered. + +- [ ] `F2` Tests for `VisualRuleBuilder.tsx`. + Acceptance: rule add/remove/reorder/edit flow, save payload shape, validation, + and error state are covered. + +- [ ] `F3` Tests for `CodeStrategyEditor.tsx`. + Acceptance: run-backtest payload shape, save behavior after `B6`, error + display, and local draft/recovery semantics are covered. + +- [ ] `F4` Tests for `HomeView.tsx`. + Acceptance: chart fetch path, indicator toggles from `B1`, profile cards, + loading/error/empty states, and ticker switching are covered without brittle + Recharts internals. + +- [ ] `F5` Tests for `ScreenerView.tsx`. + Acceptance: filter, sort, selected sector, row click, loading/error/empty + states, and validation behavior from `C3` are covered. + +### Phase 4 - UX Polish and Web Quality + +- [ ] `D1` Skeleton loaders. + Acceptance: News, ResearchCards, and Screener use stable skeleton layouts + instead of plain "Loading..." text and avoid layout jump. + +- [ ] `D5` Responsive layout. + Acceptance: below 1024px the sidebar collapses or becomes a top/bottom nav, + the right panel hides or moves behind an affordance, content remains usable at + tablet and phone widths, and no horizontal scroll appears for primary flows. + +- [ ] `D2` Light-theme contrast in legacy tabs. + Acceptance: Settings, Config, and other legacy tabs meet readable contrast in + the redesigned light shell without regressing dark-styled components that are + still intentionally dark. + +- [ ] `D3` Remove hard-coded exchange. + Acceptance: exchange comes from profile/market metadata when available and + falls back to a neutral placeholder, not always `NASDAQ`. + +- [ ] `D4` Highlight selected Screener sector from "More sectors". + Acceptance: the selected sector is visually reflected in pills/select state, + keyboard and screen-reader state remains clear, and sorting/filtering remains + unchanged. + +- [ ] `D6` Clean up editor timers. + Acceptance: `VisualRuleBuilder` and `CodeStrategyEditor` clear any save/status + timers on unmount and do not set state after unmount. + +- [ ] `D7` Keyboard shortcuts. + Acceptance: Cmd/Ctrl-K focuses search, Cmd/Ctrl-S saves in code editor, + Cmd/Ctrl-Enter runs backtest where relevant, shortcuts are discoverable, and + inputs/textareas do not receive surprising global behavior. + +- [ ] `D8` Crypto-aware empty-state ticker chips. + Acceptance: suggested chips reflect the active bot/config market type or use + a mixed set with clear labels. + +- [ ] `D9` Reduced-motion support. + Acceptance: spinners/animations respect `prefers-reduced-motion`, preserving + status clarity without continuous animation. + +### Phase 5 - Build, Docs, and Deployment Hardening + +- [ ] `E1` Lazy-load Monaco. + Acceptance: code editor chunk is loaded only when needed, bundle size drops + meaningfully, loading fallback is polished, and editor tests still pass. + +- [ ] `E3` Bundle Monaco workers locally. + Acceptance: Vite config serves TS/JSON/CSS/HTML workers locally, no runtime + CDN worker dependency remains, and CSP/offline deployment notes are updated. + +- [ ] `E4` Document redesigned web layout and env vars. + Acceptance: README or docs describe routes, env vars including `FMP_API_KEY`, + data providers, local dev setup, and known operational limits. + +- [ ] Handover refresh. + Acceptance: `docs/HANDOVER.md` reflects current reality: E2, F7-F8, and B1 + are done; web tests are 155/155; next item is correct. + +- [ ] Release smoke checklist. + Acceptance: add or refresh a manual smoke checklist for dashboard load, + ticker search, chart periods, indicators, news, research cards, screener, + strategy builder, backtest run, save flows, and auth expiry. + +### Phase 6 - Mobile Parity + +- [ ] `G4` Mobile runtime/client exposes new endpoints. + Acceptance: mobile has a typed way to call news, indices, research, screener, + and chart endpoints without duplicating fragile URL construction. + +- [ ] `G2` Mobile data provider fetches new market context. + Acceptance: `TradingDataProvider` or an equivalent mobile data layer fetches + news, indices, and company profile with loading/error states. + +- [ ] `G1` Mobile tabs for new web features. + Acceptance: Expo app exposes news, research, and screener experiences in a + mobile-native layout. Code editor remains web-only unless explicitly approved. + +- [ ] `G3` Mobile visual strategy builder decision. + Acceptance: either ship a mobile visual-builder MVP or document why it is + deferred, with UX constraints and web handoff path. + +- [ ] Mobile verification. + Acceptance: mobile typecheck/lint pass, major screens render in simulator or + Expo web as appropriate, and no web-only APIs leak into native paths. + +### Phase 7 - Platform Audit Completion + +- [ ] Platform P-sweep package inventory. + Acceptance: regenerate `/tmp/lint.log`, list packages with current lint error + counts, and choose one package at a time. + +- [ ] Platform `services/platform-service` lint fix. + Acceptance: run package-scoped `lint:fix` where safe, eyeball public exports, + manually rename intentionally unused args with `_`, and commit only that + package's owned changes. + +- [ ] Platform `services/extraction-service` lint fix. + Acceptance: same package-scoped workflow; preserve tests and public API. + +- [ ] Platform `services/cowork-service` lint fix. + Acceptance: same package-scoped workflow; no nomgap WIP files touched. + +- [ ] Platform `packages/auth` lint fix. + Acceptance: unused values removed only when not public API; otherwise `_` + prefix or targeted eslint disable with rationale. + +- [ ] Platform `packages/llm` lint fix. + Acceptance: maintain exported interfaces and provider contract behavior. + +- [ ] Platform `packages/cosmos` lint fix. + Acceptance: no data-access behavior changes; tests/typecheck pass. + +- [ ] Platform dashboard lint fixes. + Acceptance: `dashboards/admin-web` and `dashboards/tracker-web` are handled + in separate commits if both need edits. + +- [ ] Platform final lint gate. + Acceptance: workspace lint error count reaches zero, or all remaining errors + are explicitly documented with owner/justification and approved by the human. + +- [ ] Platform R3/R4 cleanup. + Acceptance: `.npmrc` token warning is quieted safely if feasible, and + `@azure/core-client` peer warnings are resolved only if dependency owners + accept the explicit dependency. + +## Quality Bar Before Calling the Work Complete + +- [ ] All trading audit rows are `✅` or explicitly documented as deferred with + owner, reason, and revisit date. +- [ ] All high/critical security rows are either fixed or explicitly refused by + design with tests. +- [ ] Trading web typecheck/build/test and backend typecheck pass from a clean + checkout. +- [ ] Platform typecheck/test pass and lint debt is reduced to zero or a signed + off exception list. +- [ ] No new private registry, lockfile, or vendored-package drift is present. +- [ ] README/HANDOVER/resume prompt reflect current status and no longer mention + stale known failures. +- [ ] Browser smoke pass covers desktop and mobile-width web layouts. +- [ ] Mobile parity gaps are closed or explicitly scoped into a follow-up + milestone with user approval. +- [ ] Production-sensitive configs are documented: Alpaca, FMP, auth runtime, + request IDs, rate limits, and cache behavior. +- [ ] Every pushed chunk has a clear commit hash, audit row update, and gate + output recorded in the handoff conversation or docs. + +## Recommended Next 10 Commits + +1. `fix(B2,B3): wire ticker actions and company profile`. +2. `fix(C2): cache FMP proxy responses`. +3. `test(F6): cover market data proxy endpoints`. +4. `fix(C1): refuse unsafe code strategy backtests`. +5. `fix(B6): persist code strategy saves`. +6. `fix(D1): add dashboard skeleton loaders`. +7. `fix(D5): add responsive dashboard breakpoints`. +8. `fix(B4,B5): derive ticker freshness and quick stats from bars`. +9. `test(F1,F4): cover market client and home chart flows`. +10. `chore(E1): lazy-load Monaco editor`. + +## Notes for Future Agents + +- `docs/AUDIT_REDESIGN.md` is the ledger. This checklist is the playbook. +- Prefer shared helpers for indicator math and market-data normalization if + another item needs the same calculations. +- Keep frontend UI work inside the existing visual language unless explicitly + redesigning a surface. +- The platform repo has unrelated WIP; inspect `git status` before every + platform package sweep and avoid those files. +- If a full recursive pnpm install is blocked by the private registry route, + document the exact error and use the narrowest package-manager command that + satisfies the owned item.