Polytraders Dev Guide
internal
v3 spine Phase 1 · Shared contracts 9 demo-wired · 0 shadow-ready · 0 production-live · 100 pending · 109 total 15/33 infra tasks the plan status board

First five developer tasks

If you have one week and you want to turn the Polytraders dev guide from a documented system into a working one, do these five things in order. Each one is a single PR. Each one has a clear "done when". Three are shipped, one is in progress, one is pending.

Why this list and not the plan page? The plan is the full backlog — every phase, every bot, every promotion gate. This page is its first page: the smallest concrete list of things you can ship that will materially change the system. After these five, return to the plan and pick up the next ready row.

1

Ship a complete fixture pack for risk.killswitch

shipped

The simplest wired bot. Once the fixture pattern works end-to-end for one bot, every other wired bot copies it. This is the keystone — until it ships, no other fixture work is meaningful.

Files touched

  • packages/polytraders-bots/fixtures/risk.killswitch/normal.json
  • packages/polytraders-bots/fixtures/risk.killswitch/warning.json
  • packages/polytraders-bots/fixtures/risk.killswitch/hard.json
  • packages/polytraders-bots/fixtures/risk.killswitch/failure.json
  • packages/polytraders-bots/fixtures/risk.killswitch/expected.normal.json
  • packages/polytraders-bots/fixtures/risk.killswitch/expected.warning.json
  • packages/polytraders-bots/fixtures/risk.killswitch/expected.hard.json
  • packages/polytraders-bots/fixtures/risk.killswitch/expected.failure.json

Done when

cd packages/polytraders-bots && node tests/verify.js passes with zero warnings, and the killswitch row appears in CI logs as WIRED with a clean replay.

Size: 1–2 hours · single PR

2

Enforce uppercase prefixed reason codes across the registry

shipped

Reason codes are the cross-system vocabulary. Lower-case free-text reason codes drift, get duplicated, and silently change shape. The regex ^(INTEL|DISC|STRAT|RISK|EXEC|SEC|GOV)_[A-Z0-9_]+$ catches every typo for free.

Files touched

  • packages/polytraders-bots/src/risk/*.js
  • packages/polytraders-bots/src/strategy/*.js
  • packages/polytraders-bots/src/exec/*.js
  • packages/polytraders-bots/tests/verify.js (REASON_CODE_RE check)

Done when

Every ctx.emit({reasonCode: ...}) call site uses an uppercase prefixed identifier. verify.js rejects any non-canonical reason code on a wired bot.

Size: 30 min · single PR

3

Add runner integration tests with real bots, not stubs

in progress

The runner is the harness that drives every bot decision in shadow mode. Today we have unit tests at the package level and verify.js at the registry level. We do not have an end-to-end test that says: drive 1000 ticks of a synthetic feed through killswitch + maker_tight + smartrouter and assert the output.

Files touched

  • packages/polytraders-runner/tests/verify.js (extend with mode-behaviour cases)
  • packages/polytraders-runner/tests/integration.js (NEW — full pipeline run)

Done when

Six runner tests pass: happy_path / reject_halts / reshape_replays_risk / quarantine_halts / determinism / max_reshapes. End-to-end integration test reconstructs identical envelopes across two seeded runs.

Size: Half a day · single PR

4

Write a dedicated 27/27 spec page for risk.drawdownguard

pending

Drawdown is its own first-class concept. Today it aliases the portfolioguard spec, which is wrong: portfolioguard is about exposure caps; drawdownguard is about peak-to-trough PnL. Aliasing makes the regression cost of the next change higher than it has to be.

Files touched

  • bots/risk/drawdownguard.json (NEW)
  • Repeat for risk.marketqualityguard and risk.exposureguard
  • Update wired_bots.json to point each registry ID at its own spec

Done when

Each of risk.drawdownguard, risk.marketqualityguard, risk.exposureguard has its own spec page; wired chips drop the alias of … tag.

Size: Half a day · single PR per spec

5

Wire CI: zero warnings is the merge gate

shipped

Discipline is institutional, not personal. Until CI fails on warnings, the warnings will accumulate. The CI workflow is the contract that turns the dev guide from a document into an enforced standard.

Files touched

  • .github/workflows/ci.yml (NEW)
  • package.json (ensure root <code class='mono'>npm test</code> exits non-zero on any package failure)

Done when

Pushing a commit that breaks any test, fails verify.js, or emits a warning fails the green check on the PR. Cannot be merged until clean.

Size: 1 hour · single PR

After these five