# 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.