learning_ai_invt_trdg/docs/COMPLETION_CHECKLIST.md

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:

• A1-A6 Critical integration repairs.
• E2 Root pnpm lockfile includes redesigned web dependencies.
• F7-F8 Previously known web test failures fixed; web suite is fully green.
• 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:

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:

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.