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.

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 && git status --short.
5. Confirm the target audit row is still open and no other agent has claimed or pushed it.
6. Run the relevant baseline gates before making code changes when the work is not docs-only.
7. Implement only the assigned item or bucket.
8. Run the full relevant gates again.
9. Commit the implementation first.
10. Update the audit row status and fix commit with the short implementation hash, then commit the doc tick separately.
11. Push both commits.
12. Report the item id, implementation commit hash, doc tick commit hash, and gate output in three sentences or fewer.

Exact Commit and Audit Update Loop

Use this loop for every trading audit item:

source ~/.zshrc
export GITEA_NPM_TOKEN
git status --short

# 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 <implementation-files>
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 <noreply@openai.com>"

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 <noreply@openai.com>"

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

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:

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:

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:

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