From ca5aa0020a4110ceab369ca274dc31d147179a32 Mon Sep 17 00:00:00 2001 From: Caihaohan Date: Sat, 28 Mar 2026 16:34:43 +0800 Subject: [PATCH] chore: align task1 spec compliance --- ...-28-binance-event-contract-agent-design.md | 400 ++++++++++ ...2026-03-28-binance-event-contract-agent.md | 748 ++++++++++++++++++ package.json | 2 +- packages/shared/package.json | 2 +- scripts/test-root.mjs | 9 - 5 files changed, 1150 insertions(+), 11 deletions(-) create mode 100644 docs/plans/2026-03-28-binance-event-contract-agent-design.md create mode 100644 docs/plans/2026-03-28-binance-event-contract-agent.md delete mode 100644 scripts/test-root.mjs diff --git a/docs/plans/2026-03-28-binance-event-contract-agent-design.md b/docs/plans/2026-03-28-binance-event-contract-agent-design.md new file mode 100644 index 0000000..c030d6c --- /dev/null +++ b/docs/plans/2026-03-28-binance-event-contract-agent-design.md @@ -0,0 +1,400 @@ +# Binance Event Contract Agent Design + +## Summary + +Build a high-cohesion single-project quantitative agent platform for Binance event contracts with: + +- modular-monolith backend +- React frontend for live visibility and operator control +- multi-agent orchestration built on deepagents +- parallel dry-run strategy execution +- backtesting and experiment management +- self-optimization through validated strategy iteration +- OpenAI-compatible model abstraction for provider-agnostic model switching +- manual confirmation gate for any live order + +The system starts as a local development project and should later deploy to a personal cloud server without architectural rework. + +## Product Goals + +- Focus only on Binance event contracts for up/down prediction markets. +- Support `dry-run` simulation for multiple strategies at the same time. +- Support historical backtesting and forward-style evaluation. +- Support continuous self-improvement through AI-proposed strategy variants that are validated before promotion. +- Avoid single-agent lock-in; the architecture must support multiple cooperating agents. +- Keep deployment simple by using a single repository and a single deployable application. +- Provide a React frontend that exposes data, strategy performance, experiments, and live confirmation actions in real time. + +## Non-Goals For V1 + +- Fully automatic live trading without human approval +- Multi-exchange support +- External sentiment, news, or on-chain data ingestion +- Multi-service microservice deployment +- Complex user/team management + +## Architectural Direction + +Use a modular monolith: + +- one repository +- one backend application process boundary +- one frontend application +- shared database and cache + +Internally, split responsibilities into modules rather than services. This preserves simple deployment while keeping agent logic, experiment logic, data ingestion, and execution control from collapsing into one code path. + +## Core Modules + +### Frontend + +React application for: + +- live market and strategy monitoring +- experiment visibility +- model/config management +- manual live trade confirmation + +### API/App + +Single backend entrypoint exposing: + +- HTTP APIs +- WebSocket streams +- job scheduling entrypoints +- configuration management +- audit/log access + +### Agent Runtime + +deepagents-based orchestration layer responsible for: + +- agent role definitions +- shared context passing +- structured outputs +- task lifecycle management +- strategy run coordination + +### Strategy Lab + +Holds the strategy lifecycle: + +- strategy definitions +- candidate generation +- dry-run execution +- backtest execution +- scoring +- promotion/demotion states + +### Market Data + +Responsible for: + +- Binance market/event contract data ingestion +- normalization +- snapshot/versioning +- storage and replay support + +V1 uses only base market data and event-contract-related inputs, while preserving extension points for future external datasets. + +### Execution Ledger + +Responsible for: + +- simulated orders +- live trade proposals +- manual confirmation workflow +- trade and position records +- audit logs + +## Multi-Agent Design + +V1 uses five agent roles. + +### Orchestrator Agent + +Coordinates runs and experiments. It starts tasks, routes context, and manages the lifecycle of research, dry-run, and backtest sessions. It does not directly own execution rights. + +### Signal Agent + +Produces directional predictions, confidence, and structured rationale from standardized market inputs for a specific strategy instance. + +### Risk Agent + +Evaluates whether a signal should be reduced, skipped, or flagged as unsafe based on explicit risk rules and uncertainty markers. + +### Evaluator Agent + +Analyzes dry-run and backtest outcomes to explain where a strategy is performing well or degrading. + +### Optimizer Agent + +Proposes new strategy variants by changing prompts, thresholds, feature windows, risk parameters, model profiles, or role bindings. It cannot bypass validation. + +## Control Boundaries + +- Agents are proposers, not final executors. +- System state transitions control promotion and execution. +- Live trading always requires explicit human confirmation. +- Invalid model outputs are rejected instead of being silently interpreted. + +## Strategy Model + +Treat every strategy as a versioned experiment unit with: + +- strategy id +- version +- agent composition +- model profile bindings +- feature configuration +- risk configuration +- scoring configuration +- current state: `draft`, `candidate`, `dry-run`, `approved-for-live`, `archived` +- result summaries and experiment lineage + +This enables many strategies to run in parallel without losing comparability. + +## Time Horizon Design + +Binance event contracts impose a minimum short-horizon decision cycle around 10 minutes. The system should therefore: + +- align decision opportunities with event contract timing constraints +- keep the trade decision cycle centered on supported market windows such as `10m` +- allow feature observation windows to vary and be optimized experimentally + +The optimization process may test different observation horizons such as `5m`, `15m`, `30m`, and longer context windows, but the underlying tradeable event window remains grounded in exchange constraints. + +## Optimization Objective + +The primary optimization target is risk-adjusted return, not raw profit or hit rate. + +Recommended scoring inputs: + +- net return +- max drawdown penalty +- stability across windows +- minimum sample sufficiency +- overtrading penalty + +This prevents the optimizer from overfitting to noisy short-term gains. + +## Data Scope + +V1 implements only core market data and event-contract-relevant inputs, while preserving extension points for future external sources. + +This means: + +- ingest and store normalized core market data first +- do not block the architecture on sentiment/news/on-chain feeds +- model the feature pipeline so external factors can be added later without redesign + +## Core Pipelines + +### 1. Real-Time Observation Pipeline + +`market-data -> normalization -> storage/cache -> websocket/frontend` + +This pipeline produces trustworthy current-state inputs and never fabricates strategy outputs. + +### 2. Dry-Run Decision Pipeline + +For every active strategy and decision point: + +`market-data snapshot -> Signal Agent -> Risk Agent -> simulated order -> settlement -> ledger` + +Parallel dry-run strategies are a first-class feature. + +### 3. Backtest and Experiment Pipeline + +For every proposed candidate variant: + +`historical window selection -> replay -> scoring -> ranking -> persistence` + +Backtest results determine candidate quality but do not directly authorize live trading. + +### 4. Optimization Feedback Loop + +`Evaluator Agent -> structured diagnosis -> Optimizer Agent proposal -> backtest queue -> candidate promotion` + +AI proposes changes. The platform validates them. Validated results become future input to the AI. This closed loop is central to the project. + +## Versioning Requirements + +The platform should version at least: + +- market data snapshots +- strategy definitions +- prompt templates +- model profiles +- experiment runs +- evaluation outputs + +Without versioning, later comparisons and regressions become untrustworthy. + +## Model Abstraction + +Use OpenAI-compatible APIs behind a provider-agnostic model profile layer. + +Each `LLM Profile` should include: + +- profile name +- provider name +- API base URL +- API key reference +- model name +- generation parameters +- timeout/retry metadata +- structured output capability flags +- optional cost metadata +- optional tags such as `fast`, `cheap`, `reasoning`, `production` + +## Model Configuration Layers + +### Global Defaults + +Project-wide fallbacks for model behavior and timeouts. + +### Agent-Level Binding + +Specific agents bind to specific model profiles. + +### Strategy-Level Override + +Individual strategy experiments may override model profile bindings to support controlled comparisons. + +This structure supports systematic experiments such as swapping only the `Signal Agent` model while keeping all else fixed. + +## Frontend Views + +V1 should provide five core views. + +### Dashboard + +Shows: + +- current market state +- event contract timing +- active strategy counts +- recent signals +- recent simulated outcomes +- alerts and runtime health + +### Strategies + +Shows: + +- strategy version metadata +- current state +- recent performance metrics +- drawdown +- hit rate +- score trend + +### Experiments + +Shows: + +- queued/running/completed backtests +- ranking tables +- parameter deltas +- model comparisons +- promotion decisions + +### Live Confirm + +Shows: + +- proposed live trade +- confidence +- risk summary +- recent comparable performance +- explicit confirm/reject actions + +This screen is the manual gate for all live execution. + +### Models & Config + +Shows and edits: + +- OpenAI-compatible model profiles +- agent bindings +- optimization parameters +- risk limits + +## Realtime Communication + +Use: + +- HTTP for CRUD and historical queries +- WebSocket for streaming market updates, strategy events, experiment progress, and alerts + +## Safety, Risk, and Promotion Rules + +- Dry-run may be automatic. +- Live execution may not be automatic. +- No strategy may enter live use without explicit human confirmation. +- Candidate promotion requires minimum sample size and drawdown/stability gates. +- Missing or stale data causes a skip, not a fabricated signal. + +## Error Handling + +The platform must explicitly handle: + +- market data gaps or staleness +- malformed or timed-out model responses +- replay/backtest alignment failures +- frontend/backend state drift + +Rule: when reliability is uncertain, skip the decision and record why. + +## Testing and Trustworthiness + +V1 should include: + +- unit tests for scoring, validation, and risk rules +- replay tests for deterministic historical decision reproduction +- integration tests for end-to-end dry-run flow +- benchmark comparisons against simple baselines + +Required baselines: + +- random direction baseline +- simple momentum baseline +- simple mean-reversion baseline + +Any AI-generated strategy must outperform relevant baselines on risk-adjusted criteria before it is considered useful. + +## Backtest Integrity Rules + +- separate training, validation, and forward evaluation windows +- no future leakage +- feature construction only from historically available data +- sample-out performance matters more than in-sample optimization +- strategy promotion uses risk-adjusted metrics, not only peak profit + +## Deployment Direction + +The project should be designed so that: + +- local development is straightforward +- later deployment to a personal cloud server does not require architecture changes +- packaging can converge toward a single-command local start and a simple containerized deployment path + +## Delivery Guidance + +V1 should prioritize a narrow but rigorous vertical slice: + +- data ingestion +- one decision cycle +- multi-strategy dry-run +- backtest loop +- optimizer proposal loop +- React visibility +- manual live-confirm screen + +This is enough to validate the platform without prematurely building a broad trading system. + +## Constraints And Open Preconditions + +- Current workspace is not a Git repository, so the design document cannot be committed yet. +- The implementation plan should assume repository initialization or placement inside a real project repository before coding begins. diff --git a/docs/plans/2026-03-28-binance-event-contract-agent.md b/docs/plans/2026-03-28-binance-event-contract-agent.md new file mode 100644 index 0000000..c8de15a --- /dev/null +++ b/docs/plans/2026-03-28-binance-event-contract-agent.md @@ -0,0 +1,748 @@ +# Binance Event Contract Agent Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Build a modular-monolith quantitative agent platform for Binance event contracts with multi-agent dry-run, backtesting, self-optimization, OpenAI-compatible model switching, and a React monitoring/confirmation console. + +**Architecture:** Use a single repository with a backend app, React frontend, shared persistence, and deepagents-based orchestration. Keep execution control in explicit system state machines while agents act only as structured proposers whose outputs are validated, persisted, replayed, and compared. + +**Tech Stack:** TypeScript, Node.js, React, deepagents, PostgreSQL, Redis, WebSocket, OpenAI-compatible SDK/client, Vitest, Playwright + +--- + +### Task 1: Initialize repository and workspace structure + +**Files:** +- Create: `package.json` +- Create: `pnpm-workspace.yaml` +- Create: `tsconfig.base.json` +- Create: `.gitignore` +- Create: `apps/api/package.json` +- Create: `apps/web/package.json` +- Create: `packages/shared/package.json` +- Create: `packages/agent-runtime/package.json` +- Create: `packages/strategy-lab/package.json` +- Create: `packages/market-data/package.json` +- Create: `packages/execution-ledger/package.json` +- Create: `docs/architecture/README.md` + +**Step 1: Write the failing workspace smoke test** + +Create a simple test in `packages/shared` that imports a constant from another package path that does not exist yet. + +**Step 2: Run test to verify it fails** + +Run: `pnpm test --filter shared` +Expected: FAIL because the workspace package export is missing. + +**Step 3: Write minimal workspace scaffolding** + +Create the monorepo package manifests, base TypeScript config, and initial package exports so the smoke test can resolve imports. + +**Step 4: Run test to verify it passes** + +Run: `pnpm test --filter shared` +Expected: PASS + +**Step 5: Commit** + +```bash +git add . +git commit -m "chore: initialize workspace structure" +``` + +### Task 2: Create shared domain schemas and enums + +**Files:** +- Create: `packages/shared/src/domain/strategy.ts` +- Create: `packages/shared/src/domain/experiment.ts` +- Create: `packages/shared/src/domain/model-profile.ts` +- Create: `packages/shared/src/domain/trade.ts` +- Create: `packages/shared/src/domain/market.ts` +- Create: `packages/shared/src/index.ts` +- Test: `packages/shared/src/domain/strategy.test.ts` + +**Step 1: Write the failing test** + +Write tests that assert strategy states, model profile parsing, and dry-run trade records conform to explicit schemas. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/shared/src/domain/strategy.test.ts` +Expected: FAIL because the schemas and enums do not exist. + +**Step 3: Write minimal implementation** + +Create versioned domain types and validation schemas for: + +- strategy lifecycle states +- model profiles +- market snapshots +- dry-run/live trade proposals +- experiment results + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/shared/src/domain/strategy.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/shared +git commit -m "feat: add shared domain schemas" +``` + +### Task 3: Build configuration loading and model profile registry + +**Files:** +- Create: `apps/api/src/config/env.ts` +- Create: `apps/api/src/config/model-profile-registry.ts` +- Create: `apps/api/src/config/config.test.ts` +- Modify: `packages/shared/src/domain/model-profile.ts` + +**Step 1: Write the failing test** + +Write tests that load sample OpenAI-compatible profiles and assert agent bindings resolve correctly. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest apps/api/src/config/config.test.ts` +Expected: FAIL because the registry and loader do not exist. + +**Step 3: Write minimal implementation** + +Implement: + +- env loading +- model profile parsing +- profile lookup by name +- agent-to-profile binding resolution + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest apps/api/src/config/config.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add apps/api/src/config packages/shared/src/domain/model-profile.ts +git commit -m "feat: add model profile registry" +``` + +### Task 4: Implement market data ingestion interfaces and normalized snapshot storage + +**Files:** +- Create: `packages/market-data/src/provider/binance.ts` +- Create: `packages/market-data/src/service/normalizer.ts` +- Create: `packages/market-data/src/service/market-store.ts` +- Create: `packages/market-data/src/index.ts` +- Test: `packages/market-data/src/service/normalizer.test.ts` + +**Step 1: Write the failing test** + +Write tests that feed raw market payloads and assert normalized snapshots are created with timestamps and versioned identifiers. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/market-data/src/service/normalizer.test.ts` +Expected: FAIL because normalization/storage code does not exist. + +**Step 3: Write minimal implementation** + +Implement: + +- Binance market data adapter interface +- normalized snapshot builder +- in-memory repository abstraction for snapshots + +Keep transport and persistence separated. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/market-data/src/service/normalizer.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/market-data +git commit -m "feat: add market snapshot normalization" +``` + +### Task 5: Create execution ledger primitives for simulated and proposed live trades + +**Files:** +- Create: `packages/execution-ledger/src/service/trade-ledger.ts` +- Create: `packages/execution-ledger/src/service/state-machine.ts` +- Create: `packages/execution-ledger/src/index.ts` +- Test: `packages/execution-ledger/src/service/trade-ledger.test.ts` + +**Step 1: Write the failing test** + +Write tests covering: + +- dry-run trade creation +- settlement updates +- live proposal creation +- manual confirm/reject transitions + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/execution-ledger/src/service/trade-ledger.test.ts` +Expected: FAIL because the ledger/state machine does not exist. + +**Step 3: Write minimal implementation** + +Implement trade lifecycle handling with explicit state transitions and audit timestamps. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/execution-ledger/src/service/trade-ledger.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/execution-ledger +git commit -m "feat: add execution ledger state machine" +``` + +### Task 6: Create agent runtime contracts and structured-output adapters + +**Files:** +- Create: `packages/agent-runtime/src/contracts/agent-task.ts` +- Create: `packages/agent-runtime/src/contracts/agent-output.ts` +- Create: `packages/agent-runtime/src/runtime/orchestrator.ts` +- Create: `packages/agent-runtime/src/runtime/output-validator.ts` +- Create: `packages/agent-runtime/src/index.ts` +- Test: `packages/agent-runtime/src/runtime/output-validator.test.ts` + +**Step 1: Write the failing test** + +Write tests that assert malformed agent responses are rejected and valid structured responses are accepted. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/agent-runtime/src/runtime/output-validator.test.ts` +Expected: FAIL because runtime contracts and validation do not exist. + +**Step 3: Write minimal implementation** + +Define agent task payloads and implement structured output validation around deepagents integration boundaries. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/agent-runtime/src/runtime/output-validator.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/agent-runtime +git commit -m "feat: add agent runtime contracts" +``` + +### Task 7: Implement first-pass agent roles + +**Files:** +- Create: `packages/agent-runtime/src/agents/orchestrator-agent.ts` +- Create: `packages/agent-runtime/src/agents/signal-agent.ts` +- Create: `packages/agent-runtime/src/agents/risk-agent.ts` +- Create: `packages/agent-runtime/src/agents/evaluator-agent.ts` +- Create: `packages/agent-runtime/src/agents/optimizer-agent.ts` +- Test: `packages/agent-runtime/src/agents/signal-agent.test.ts` + +**Step 1: Write the failing test** + +Write tests for: + +- signal agent structured output shape +- risk agent skip decisions +- optimizer proposal schema + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/agent-runtime/src/agents/signal-agent.test.ts` +Expected: FAIL because agent role implementations do not exist. + +**Step 3: Write minimal implementation** + +Implement lightweight role wrappers that: + +- prepare prompts/messages +- call the model profile client +- validate structured output +- return domain-safe results + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/agent-runtime/src/agents/signal-agent.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/agent-runtime/src/agents +git commit -m "feat: add core agent roles" +``` + +### Task 8: Build strategy registry and lifecycle state handling + +**Files:** +- Create: `packages/strategy-lab/src/registry/strategy-registry.ts` +- Create: `packages/strategy-lab/src/service/strategy-state-service.ts` +- Create: `packages/strategy-lab/src/index.ts` +- Test: `packages/strategy-lab/src/registry/strategy-registry.test.ts` + +**Step 1: Write the failing test** + +Write tests for: + +- strategy version creation +- state transitions +- immutable result history + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/strategy-lab/src/registry/strategy-registry.test.ts` +Expected: FAIL because registry/state handling does not exist. + +**Step 3: Write minimal implementation** + +Implement versioned strategy registration and lifecycle transitions for `draft`, `candidate`, `dry-run`, `approved-for-live`, and `archived`. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/strategy-lab/src/registry/strategy-registry.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/strategy-lab +git commit -m "feat: add strategy registry lifecycle" +``` + +### Task 9: Implement dry-run engine for parallel strategy evaluation + +**Files:** +- Create: `packages/strategy-lab/src/dry-run/dry-run-engine.ts` +- Create: `packages/strategy-lab/src/dry-run/dry-run-scheduler.ts` +- Test: `packages/strategy-lab/src/dry-run/dry-run-engine.test.ts` +- Modify: `packages/agent-runtime/src/runtime/orchestrator.ts` +- Modify: `packages/execution-ledger/src/service/trade-ledger.ts` + +**Step 1: Write the failing test** + +Write tests that run multiple strategy definitions against the same market snapshot and assert isolated simulated trades are produced. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/strategy-lab/src/dry-run/dry-run-engine.test.ts` +Expected: FAIL because the dry-run engine does not exist. + +**Step 3: Write minimal implementation** + +Implement the dry-run pipeline: + +- snapshot intake +- signal evaluation +- risk filtering +- simulated order write + +Ensure each strategy instance is isolated and parallel-safe. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/strategy-lab/src/dry-run/dry-run-engine.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/strategy-lab packages/agent-runtime/src/runtime/orchestrator.ts packages/execution-ledger/src/service/trade-ledger.ts +git commit -m "feat: add parallel dry-run engine" +``` + +### Task 10: Implement historical replay and backtest runner + +**Files:** +- Create: `packages/strategy-lab/src/backtest/replay-runner.ts` +- Create: `packages/strategy-lab/src/backtest/backtest-runner.ts` +- Create: `packages/strategy-lab/src/backtest/windowing.ts` +- Test: `packages/strategy-lab/src/backtest/backtest-runner.test.ts` + +**Step 1: Write the failing test** + +Write tests that replay a fixed sequence of market snapshots and assert repeatable outcomes for a test strategy. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/strategy-lab/src/backtest/backtest-runner.test.ts` +Expected: FAIL because the replay/backtest runner does not exist. + +**Step 3: Write minimal implementation** + +Implement deterministic replay with explicit training, validation, and forward windows. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/strategy-lab/src/backtest/backtest-runner.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/strategy-lab/src/backtest +git commit -m "feat: add backtest replay runner" +``` + +### Task 11: Implement scoring and baseline comparison + +**Files:** +- Create: `packages/strategy-lab/src/scoring/risk-adjusted-score.ts` +- Create: `packages/strategy-lab/src/scoring/baselines.ts` +- Test: `packages/strategy-lab/src/scoring/risk-adjusted-score.test.ts` + +**Step 1: Write the failing test** + +Write tests that assert: + +- drawdown penalizes score +- higher stability improves score +- candidate strategies are compared against random, momentum, and mean-reversion baselines + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/strategy-lab/src/scoring/risk-adjusted-score.test.ts` +Expected: FAIL because scoring and baselines do not exist. + +**Step 3: Write minimal implementation** + +Implement the risk-adjusted score and baseline evaluators. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/strategy-lab/src/scoring/risk-adjusted-score.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/strategy-lab/src/scoring +git commit -m "feat: add strategy scoring and baselines" +``` + +### Task 12: Implement experiment store and optimizer feedback loop + +**Files:** +- Create: `packages/strategy-lab/src/experiments/experiment-store.ts` +- Create: `packages/strategy-lab/src/experiments/optimizer-loop.ts` +- Test: `packages/strategy-lab/src/experiments/optimizer-loop.test.ts` +- Modify: `packages/agent-runtime/src/agents/evaluator-agent.ts` +- Modify: `packages/agent-runtime/src/agents/optimizer-agent.ts` + +**Step 1: Write the failing test** + +Write tests that verify evaluator summaries can produce optimizer proposals which enqueue backtest candidates without changing live state. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest packages/strategy-lab/src/experiments/optimizer-loop.test.ts` +Expected: FAIL because the loop/store do not exist. + +**Step 3: Write minimal implementation** + +Implement: + +- experiment persistence +- evaluator summary ingestion +- optimizer proposal creation +- candidate queueing for backtest + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest packages/strategy-lab/src/experiments/optimizer-loop.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add packages/strategy-lab/src/experiments packages/agent-runtime/src/agents/evaluator-agent.ts packages/agent-runtime/src/agents/optimizer-agent.ts +git commit -m "feat: add optimizer feedback loop" +``` + +### Task 13: Build backend app shell with HTTP and WebSocket APIs + +**Files:** +- Create: `apps/api/src/server.ts` +- Create: `apps/api/src/routes/strategies.ts` +- Create: `apps/api/src/routes/experiments.ts` +- Create: `apps/api/src/routes/models.ts` +- Create: `apps/api/src/routes/live-confirm.ts` +- Create: `apps/api/src/ws/events.ts` +- Test: `apps/api/src/server.test.ts` + +**Step 1: Write the failing test** + +Write tests that assert the API exposes strategy, experiment, model, and live-confirm endpoints and emits socket events for updates. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest apps/api/src/server.test.ts` +Expected: FAIL because the server and routes do not exist. + +**Step 3: Write minimal implementation** + +Implement the backend shell with: + +- route registration +- in-process service wiring +- WebSocket event publishing + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest apps/api/src/server.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add apps/api +git commit -m "feat: add backend api shell" +``` + +### Task 14: Build React console shell and live dashboards + +**Files:** +- Create: `apps/web/src/app/router.tsx` +- Create: `apps/web/src/pages/dashboard.tsx` +- Create: `apps/web/src/pages/strategies.tsx` +- Create: `apps/web/src/pages/experiments.tsx` +- Create: `apps/web/src/pages/live-confirm.tsx` +- Create: `apps/web/src/pages/models-config.tsx` +- Create: `apps/web/src/lib/api.ts` +- Create: `apps/web/src/lib/socket.ts` +- Test: `apps/web/src/pages/dashboard.test.tsx` + +**Step 1: Write the failing test** + +Write tests that assert each core page renders expected panels from mocked API/WebSocket data. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest apps/web/src/pages/dashboard.test.tsx` +Expected: FAIL because the UI shell does not exist. + +**Step 3: Write minimal implementation** + +Implement a simple but usable React console with the five approved views. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest apps/web/src/pages/dashboard.test.tsx` +Expected: PASS + +**Step 5: Commit** + +```bash +git add apps/web +git commit -m "feat: add monitoring console shell" +``` + +### Task 15: Add manual live-confirm workflow end to end + +**Files:** +- Modify: `apps/api/src/routes/live-confirm.ts` +- Modify: `packages/execution-ledger/src/service/state-machine.ts` +- Modify: `apps/web/src/pages/live-confirm.tsx` +- Test: `apps/api/src/live-confirm-flow.test.ts` + +**Step 1: Write the failing test** + +Write an integration test that creates a live proposal, confirms it, and rejects another proposal with audit metadata. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest apps/api/src/live-confirm-flow.test.ts` +Expected: FAIL because the full flow is incomplete. + +**Step 3: Write minimal implementation** + +Implement explicit confirm/reject endpoints and UI actions, persisting actor and timestamp metadata. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest apps/api/src/live-confirm-flow.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add apps/api/src/routes/live-confirm.ts packages/execution-ledger/src/service/state-machine.ts apps/web/src/pages/live-confirm.tsx +git commit -m "feat: add manual live confirmation flow" +``` + +### Task 16: Add persistence adapters for PostgreSQL and Redis + +**Files:** +- Create: `apps/api/src/db/schema.sql` +- Create: `apps/api/src/db/repositories/strategy-repository.ts` +- Create: `apps/api/src/db/repositories/experiment-repository.ts` +- Create: `apps/api/src/db/repositories/trade-repository.ts` +- Create: `apps/api/src/cache/redis-client.ts` +- Test: `apps/api/src/db/repositories/strategy-repository.test.ts` + +**Step 1: Write the failing test** + +Write repository tests using a test database or local containerized database. + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest apps/api/src/db/repositories/strategy-repository.test.ts` +Expected: FAIL because persistence adapters do not exist. + +**Step 3: Write minimal implementation** + +Implement persistence adapters and map domain entities to database records. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest apps/api/src/db/repositories/strategy-repository.test.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add apps/api/src/db apps/api/src/cache +git commit -m "feat: add persistence adapters" +``` + +### Task 17: Add deterministic replay fixtures and integration coverage + +**Files:** +- Create: `tests/fixtures/market/window-10m.json` +- Create: `tests/integration/dry-run-replay.test.ts` +- Create: `tests/integration/backtest-candidate-promotion.test.ts` + +**Step 1: Write the failing test** + +Write integration tests that: + +- replay a fixed 10-minute market sequence through multiple strategies +- assert repeatable results +- assert candidate promotion refuses failing risk-adjusted baselines + +**Step 2: Run test to verify it fails** + +Run: `pnpm vitest tests/integration` +Expected: FAIL because the end-to-end integration path is incomplete. + +**Step 3: Write minimal implementation** + +Fill missing wiring required to make deterministic replay and promotion gates pass. + +**Step 4: Run test to verify it passes** + +Run: `pnpm vitest tests/integration` +Expected: PASS + +**Step 5: Commit** + +```bash +git add tests +git commit -m "test: add deterministic replay integration coverage" +``` + +### Task 18: Add local developer experience and deployment packaging + +**Files:** +- Create: `docker-compose.yml` +- Create: `.env.example` +- Create: `README.md` +- Create: `scripts/dev.ps1` +- Create: `scripts/test.ps1` +- Create: `scripts/start-local.ps1` + +**Step 1: Write the failing test** + +Write a smoke-check script or README verification checklist that fails when required env variables or services are missing. + +**Step 2: Run test to verify it fails** + +Run: `powershell -File scripts/test.ps1` +Expected: FAIL because scripts and packaging do not exist. + +**Step 3: Write minimal implementation** + +Add: + +- local startup instructions +- containerized dependencies +- environment template +- developer scripts + +**Step 4: Run test to verify it passes** + +Run: `powershell -File scripts/test.ps1` +Expected: PASS + +**Step 5: Commit** + +```bash +git add docker-compose.yml .env.example README.md scripts +git commit -m "chore: add local dev and deployment packaging" +``` + +### Task 19: Verify the whole vertical slice + +**Files:** +- Modify: `README.md` +- Modify: `docs/architecture/README.md` + +**Step 1: Run the focused test suites** + +Run: + +```bash +pnpm vitest packages/shared packages/market-data packages/execution-ledger packages/agent-runtime packages/strategy-lab +pnpm vitest apps/api apps/web tests/integration +``` + +Expected: PASS + +**Step 2: Run the app smoke start** + +Run: + +```bash +powershell -File scripts/start-local.ps1 +``` + +Expected: API starts, web starts, database/cache dependencies become reachable. + +**Step 3: Verify manual live-confirm flow** + +Run the app and manually confirm: + +- market data appears +- multiple dry-run strategies render +- experiments show history +- a proposed live trade can be confirmed/rejected + +**Step 4: Update docs** + +Document: + +- how strategy versions move through states +- how model profiles are configured +- how to add a new agent role + +**Step 5: Commit** + +```bash +git add README.md docs/architecture/README.md +git commit -m "docs: finalize vertical slice verification notes" +``` diff --git a/package.json b/package.json index 4cfb42f..922dad9 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,6 @@ "version": "0.0.0", "packageManager": "pnpm@10.18.3", "scripts": { - "test": "node scripts/test-root.mjs" + "test": "pnpm --filter @aiquant/shared test" } } diff --git a/packages/shared/package.json b/packages/shared/package.json index 5f3eec0..818736d 100644 --- a/packages/shared/package.json +++ b/packages/shared/package.json @@ -4,7 +4,7 @@ "private": true, "type": "module", "scripts": { - "test": "vitest run" + "test": "vitest run --" }, "dependencies": { "@aiquant/agent-runtime": "workspace:*" diff --git a/scripts/test-root.mjs b/scripts/test-root.mjs deleted file mode 100644 index 7cfd81f..0000000 --- a/scripts/test-root.mjs +++ /dev/null @@ -1,9 +0,0 @@ -import { spawnSync } from "node:child_process"; - -const result = spawnSync("pnpm", ["--filter", "@aiquant/shared", "test"], { - cwd: process.cwd(), - stdio: "inherit", - shell: true -}); - -process.exit(result.status ?? 1);