# 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. ## Fresh-Agent Start Procedure Every agent should do this before writing code: 1. Read `docs/CODEX_RESUME_PROMPT.md` in full. 2. Read `docs/AUDIT_REDESIGN.md` and this checklist. 3. If touching platform, also read `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/HANDOVER.md` and `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md`. 4. Run `source ~/.zshrc && export GITEA_NPM_TOKEN`. 5. Run `git status --short`; stop if there are unexpected local edits in files you need to touch. 6. Run `git pull --ff-only` so the local branch includes any other agent's completed rows and commits. 7. Confirm the target audit row is still open and no other agent has pushed it. If the row is already `✅`, skip it and take the next assigned row. 8. Inspect the files you expect to edit and confirm they do not overlap with an active parallel stream. 9. Run the relevant baseline gates before making code changes when the work is not docs-only. 10. Implement only the assigned item or bucket. 11. Run the full relevant gates again. 12. Commit the implementation first. 13. Run `git pull --rebase --autostash` again before editing audit docs. If it conflicts, resolve only if the conflict is simple and in docs; otherwise stop. If a rebase applies remote code changes, rerun gates before the doc tick. Recompute the implementation hash after any rebase. 14. Update the audit row status and fix commit with the final short implementation hash, then commit the doc tick separately. 15. Run final gates after both commits. 16. Run `git pull --rebase --autostash` one last time before `git push`. If it applies remote commits, rerun the final gates before pushing. 17. Push both commits. 18. Report the item id, implementation commit hash, doc tick commit hash, and gate output in three sentences or fewer. ## Work Claiming and Collision Handling - The assignment prompt is the claim. Do not create a claim-only commit unless the human explicitly asks for one. - Before starting, check `git log --oneline -10` and the audit table. Another agent may have finished the item while your session was idle. - If another agent lands the same item first, do not duplicate it. Pull, verify the row is `✅`, and move to the next assigned item only if the prompt allows continuing. - If your implementation files overlap with another active stream, pause and ask for an integrator decision. The most common overlap files are `web/src/views/HomeView.tsx`, strategy-builder components, backend API route helpers, and audit docs. - If only the audit doc conflicts, preserve all completed rows and all commit hashes. Never erase another agent's row update. - If a package manager changes a lockfile you do not own, revert only that incidental lockfile hunk before committing. Do not revert unrelated human or agent edits. ## Report Format After Each Push Use this exact shape: ```text pushed: implementation , docs . Gates: ; ; ; . Next: . ``` Example: ```text B2+B3 pushed: implementation abc1234, docs def5678. Gates: web typecheck exit 0; web build ✓ built; web test 155/155; backend tsc exit 0. Next: C2 FMP cache. ``` ## Multi-Row and Newly Discovered Work - If one cohesive fix closes multiple audit rows, commit it once with all IDs in the subject, for example `fix(B2,B3): wire ticker header actions`. - In the audit table, put the same implementation hash in each closed row. - If you discover a real issue that is not in the audit, do not quietly broaden scope. Add a new audit row or a checklist note in a docs commit, then ask the human to prioritize it unless it blocks the current item. - If an item's acceptance criteria are ambiguous, inspect existing code and docs first. If still ambiguous and the fix changes user-visible behavior or public contracts, pause and ask. ## Exact Commit and Audit Update Loop Use this loop for every trading audit item: ```bash source ~/.zshrc export GITEA_NPM_TOKEN git status --short git pull --ff-only # Baseline gates before substantial code changes npm --prefix web run typecheck npm --prefix web run build npm --prefix web test npx tsc --noEmit -p backend/tsconfig.json # Edit files, then repeat gates npm --prefix web run typecheck npm --prefix web run build npm --prefix web test npx tsc --noEmit -p backend/tsconfig.json git add git commit -m "fix(B2,B3): short description" \ -m "Present-tense why paragraph." \ -m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \ -m "Co-Authored-By: GPT-5 Codex " git pull --rebase --autostash # If the rebase applies remote code changes, rerun the relevant gates before editing docs. IMPLEMENTATION_HASH="$(git rev-parse --short HEAD)" # Edit docs/AUDIT_REDESIGN.md: ⬜ -> ✅ and Fix commit -> $IMPLEMENTATION_HASH git add docs/AUDIT_REDESIGN.md git commit -m "docs(B2,B3): tick ticker header audit rows" \ -m "Record the implementation commit in the redesign audit table." \ -m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \ -m "Co-Authored-By: GPT-5 Codex " # Final gates after both commits npm --prefix web run typecheck npm --prefix web run build npm --prefix web test npx tsc --noEmit -p backend/tsconfig.json git pull --rebase --autostash # If the rebase applies remote commits, rerun the final gates before pushing. git push ``` Do not amend the implementation commit to include the audit-row hash after the hash is written into the table. That creates a self-referential hash loop. The preferred pattern is one implementation commit plus one small docs tick commit. For docs-only work, use the same commit style but run at least `git diff --check` and the trading gates unless the human explicitly waives them. ## Parallelization Rules Maximum parallel streams: 3 agents. - Parallel streams must own disjoint files or clearly disjoint repos. - Only one agent may edit `docs/AUDIT_REDESIGN.md` at a time. If multiple agents finish together, each should pull/rebase first, then update only its own rows. - Do not parallelize two items that both touch `web/src/views/HomeView.tsx`, shared strategy-builder files, or backend route helpers unless one agent is explicitly acting as integrator. - Prefer one frontend feature stream, one backend/security/test stream, and one platform-lint stream. - Each agent must push incremental commits for its owned item before taking the next item. - If a gate fails in code outside the agent's touched files, stop and report instead of masking the failure. - If merge conflicts appear in audit docs only, resolve by preserving all completed rows and commit hashes. Recommended three-way split for the current backlog: | Stream | Owns | Avoids | | --- | --- | --- | | Agent 1 - Web feature | `B2+B3`, then `B4+B5`, then `B6-B10` | Backend route/cache files and platform repo | | Agent 2 - Backend/security/tests | `C2`, `F6`, `C1`, then `C3-C7` | `TickerHeader`, layout polish, platform repo | | Agent 3 - Platform/infra/docs | Platform `P-sweep`, then `E1/E3/E4` if platform is blocked | nomgap WIP files and active trading feature files | If only two agents are available, run Agent 1 and Agent 2. If only one agent is available, follow the recommended next commits top-down. ## One-Line Parallel Agent Prompts Agent 1: ```text In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement B2+B3 only: wire TickerHeader Watchlist/alert actions and company name from fetchResearchProfile; run all trading gates, commit implementation, tick only B2/B3 rows with the implementation hash in a docs commit, push, and report hashes plus gate output. ``` Agent 2: ```text In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement C2 only: add a 30-minute in-memory FMP cache keyed by full upstream URL with tests where practical; run all trading gates, commit implementation, tick only C2 with the implementation hash in a docs commit, push, and report hashes plus gate output. ``` Agent 3: ```text In /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat, read docs/HANDOVER.md and docs/AUDIT_PLATFORM.md plus the trading docs/COMPLETION_CHECKLIST.md, then do one package-scoped P-sweep lint fix only without touching nomgap WIP or platform pnpm-lock.yaml; run platform typecheck/test/lint, commit that package only, update AUDIT_PLATFORM.md if applicable, push, and report hashes plus before/after lint error count. ``` ## 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. - [x] `B4` Use latest chart bar timestamp for "as of". Implementation: `311d79c`. Acceptance: header timestamp is derived from market data, not wall-clock render time. Fallback is explicit when no bars exist. - [x] `B5` Compute QuickStats for searched symbols. Implementation: `27b3d1a`. 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. - [x] `B7` Remove or use unused `editorRef`. Implementation: `1fd1bf3`. Acceptance: no dead ref remains, or it powers a concrete behavior such as formatting/focus/save integration. - [x] `B8` Wire visual-builder backtest action. Implementation: `1cd23f3`. Acceptance: `ResearchView` passes `onBacktest`, the button appears in the visual builder, and payload shape matches `/api/backtest/run`. - [x] `B9` Integrate saved visual/code strategies into Strategies tab. Implementation: `70db4c9`. Acceptance: strategies saved in the new builders are discoverable in the existing Strategies tab without duplicating stores or creating divergent data models. - [x] `B10` Add React Router catch-all route. Implementation: `ee7404a`. 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. - [x] `C7` Mitigate FMP key exposure. Implementation: `e2e189e`. 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. - [x] `D2` Light-theme contrast in legacy tabs. Implementation: `5ca8183`. 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. - [x] `D3` Remove hard-coded exchange. Implementation: `1e502b9`. Acceptance: exchange comes from profile/market metadata when available and falls back to a neutral placeholder, not always `NASDAQ`. - [x] `D4` Highlight selected Screener sector from "More sectors". Implementation: `3bf1ca7`. Acceptance: the selected sector is visually reflected in pills/select state, keyboard and screen-reader state remains clear, and sorting/filtering remains unchanged. - [x] `D6` Clean up editor timers. Implementation: `2089b9a`. Acceptance: `VisualRuleBuilder` and `CodeStrategyEditor` clear any save/status timers on unmount and do not set state after unmount. - [x] `D7` Keyboard shortcuts. Implementation: `1b2130e`. 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. - [x] `D8` Crypto-aware empty-state ticker chips. Implementation: `b1f872f`. Acceptance: suggested chips reflect the active bot/config market type or use a mixed set with clear labels. - [x] `D9` Reduced-motion support. Implementation: `fce0228`. Acceptance: spinners/animations respect `prefers-reduced-motion`, preserving status clarity without continuous animation. ### Phase 5 - Build, Docs, and Deployment Hardening - [x] `E1` Lazy-load Monaco. Implementation: `8a8c313`. Acceptance: code editor chunk is loaded only when needed, bundle size drops meaningfully, loading fallback is polished, and editor tests still pass. - [x] `E3` Bundle Monaco workers locally. Implementation: `e8b3c9c`, `e266a8b`. 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.