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

Definition of done

A 27/27 docs score does not mean a bot is done. v3 splits readiness into three independent scores; v3.5 adds a fourth. A bot is done only when all four are.

The forbidden shortcut: scoring documentation completeness as readiness. v2 made this mistake. The v3 status board shows docs/impl/runtime separately so it cannot recur.

The four scores

ScoreOut ofWhat it meansWhat it does NOT mean
Docs27The spec is complete: purpose, inputs, parameters, defaults, thresholds, failure modes, wire examples, runbook, promotion gates — all 27 sections.The bot is implemented or running.
Impl15The bot compiles against @polytraders/contracts, validates fixtures (normal/warning/hard/failure), emits ReportEnvelopes with reason codes from the registry, supports its declared modes (including quarantine where applicable), passes against the mock CLOB v2 adapter, and is green in CI.The bot has been observed under live conditions.
Runtime8The bot has been running in shadow mode with clean telemetry, error rate under budget, latency within budget, reject rate calibrated, runbook battle-tested by an on-call rotation, dashboard live, alerts wired, and has been promoted through every gate.That nothing will ever go wrong — only that we have evidence the bot behaves as documented.
Backtest4The bot runs end-to-end against the synthetic feed: a synthetic fixture exists, a recorded ReportEnvelope timeline is checked in, the parameter search space is declared, and at least one optimizer reference run is on file. See the synthetic demo and the optimizer.That backtest results predict live PnL. They do not. Synthetic data only.

Impl checklist (15)

  1. TypeScript compiles against the contracts package.
  2. Implements the Bot<I,O> interface from @polytraders/contracts.
  3. Config validates against the published BotConfig schema.
  4. Default config falls within every declared hard threshold.
  5. Fixture: normal-conditions input passes.
  6. Fixture: warning-conditions input emits the warning reason code.
  7. Fixture: hard-threshold input fires the safe fallback.
  8. Fixture: failure-injection input does not fail open.
  9. Emits ReportEnvelopes on every decision path.
  10. Every reason code emitted is in the registry.
  11. Authority enforced — can only do what the class allows.
  12. Every declared mode_support entry is reachable at runtime.
  13. Mock CLOB v2 adapter passes the bot's full fixture pack.
  14. Standard metrics (decisions_total, decision_latency_ms, heartbeat_age_ms, errors_total, config_version, mode) are emitted.
  15. CI is green — lint, type-check, test, schema validation, contract verification.

Backtest checklist (4)

  1. Synthetic fixture exists in packages/polytraders-bots/fixtures/<bot>/ and is loaded by tests/verify.js.
  2. Recorded ReportEnvelope timeline (deterministic by seed) is checked in alongside the fixture.
  3. The bot exports a SEARCH_SPACE object describing every tunable parameter, range, and step.
  4. At least one optimizer reference run (random or LLM-driven) is on file in packages/polytraders-bots/runs/, with the winning params and the score function it was tuned against.

Honesty rule: Backtest score does not predict live performance. It measures whether the bot is reproducibly tunable against a known feed. Anything stronger than that is a forbidden claim.

Runtime checklist (8)

  1. Shadow telemetry clean for at least 7 days.
  2. Rolling error rate under budget.
  3. p95 latency inside the declared latency budget.
  4. Reject rate within the calibrated band.
  5. Runbook battle-tested by the on-call rotation against a real (or replayed) incident.
  6. Dashboard live in the team Grafana / equivalent.
  7. Alerts wired to the correct severity tier.
  8. Promoted through every gate: stub → shadow → advisory → enforced.

What we do not count