The Plan

One page — the v3 build plan, the 11 runtime stages it ships, and the 109 bots assigned to each. The earlier four roadmap pages have been folded into this one.

How to read this page

Phases (P1–P8) are the build order. Each phase has an exit gate that must be green before the next phase starts.
Stages (S1–S11) are the runtime loop — instrument truth → ingestion → state → signals → fair value → execution estimate → decision → OMS → inventory → replay → monitoring.
Phases ship stages. Most phases unlock multiple stages — the matrix below shows which.
Bots are the 109 decision modules. Each bot lives in exactly one phase and one or more stages. We never call a bot "done" — nothing is production-live.
Done · In progress · Locked · Pending apply to phases. Demo-wired applies to bots (reference impl exists against the synthetic feed; no fixtures yet).

Phase × Stage matrix

Each ● marks a phase that advances a runtime stage. Cell colour reflects phase state.

Phase ↓ · Stage →	S1	S2	S3	S4	S5	S6	S7	S8	S9	S10	S11	Bots
P1 Shared contracts	●		●									0 bots
P2 Data normalisation	●	●	●									26 bots
P3 Reporting & event store			●						●		●	6 bots
P4 Core risk							●					17 bots
P5 Execution rails						●	●	●				24 bots
P6 One simple strategy				●	●	●	●	●				1 bot
P7 Governance & replay									●	●	●	12 bots
P8 Additional strategies				●	●		●					23 bots

The eight phases in detail

Phase 1

Shared contracts

in progress ◀ we are here

Frozen typed wire objects and the reason-code registry. Every other phase imports from here.

Runtime stages advanced

Stage 1 Market registry Stage 3 Canonical state

Bots in this phase · no bots in this phase

15/17 infra tasks done

Exit gate

Contracts package verifies green. Schemas page renders from manifest. Mock adapter validates fixtures against the published schemas.

Infra tasks (15/17)

State	ID	Task
done	`p1.contracts-package`	Create packages/polytraders-contracts with TS + JSON schemas
done	`p1.schema-manifest`	schemas/manifest.json is the single source of truth for the dev guide
done	`p1.verify-script`	tests/verify-contracts.js — every TS file pairs with a schema, every schema has $id/title/description
done	`p1.dev-guide-reads-manifest`	/standards/schemas reads from the manifest, not from inline strings
done	`p1.reason-code-pattern`	All reason codes match ^(INTEL\|DISC\|STRAT\|RISK\|EXEC\|SEC\|GOV)_[A-Z0-9_]+$ — enforced by schema
done	`p1.three-score-model`	Three-score model (docs/impl/runtime) added to every bot page
done	`p1.capital-impact-field`	capital_impact added to every bot — Critical / Direct / Indirect
done	`p1.quarantine-mode`	Quarantine mode added to risk/exec/sec bot mode_support
done	`p1.deprecated-status`	Deprecated status supported with tombstone renderer
done	`p1.status-board`	/roadmap/status — by-bot, by-phase, by-task views
done	`p1.v3-plan-page`	/roadmap/v3 — 8-phase timeline with done / in-progress / locked / pending pills
done	`p1.system-health-bar`	Thin strip under topnav showing v3 phase + counts on every page
done	`p1.definition-of-done`	/standards/definition-of-done — what counts as readiness, what does not
done	`p1.forbidden-pattern-docs`	Forbidden pattern: do not score documentation completeness as readiness
done	`p1.forbidden-pattern-risk`	Forbidden pattern: do not allow risk to evaluate orders before strategy emits an OrderIntent
pending	`p1.cli-bot-new`	CLI: pt-bot new <slug> — scaffolds a bot from the matching class template
pending	`p1.mock-adapter`	Mock CLOB v2 adapter playing recorded fixtures through the contracts

Phase 2

Data normalisation

locked

Every consumer reads MarketSnapshot, OrderBookSnapshot and the freshness/quality wrappers. No bot consumes raw payloads.

Runtime stages advanced

Stage 1 Market registry Stage 2 Ingestion & book Stage 3 Canonical state

Bots in this phase · 3 demo-wired of 26

market_halt_detector · demo marketqualityranker · demo stale_book_guard · demo view all 26 →

disc: 6 · gov: 1 · intel: 17 · risk: 2

0/4 infra tasks done

Exit gate

All Intelligence and Discovery bots read normalised objects only. Three Risk overrides (stale_book, market_halt, api_degradation) cleared.

Infra tasks (0/4)

State	ID	Task
pending	`p2.contracts-imports`	Reference Intel and Discovery bots import from @polytraders/contracts
pending	`p2.fixture-pack`	Recorded CLOB v2 fixture pack covering normal / warning / hard / failure
pending	`p2.freshness-budgets`	Per-source freshness budgets enforced at adapter boundary
pending	`p2.provenance-hash`	Every normalised object carries the source response hash

Phase 3

Reporting & event store

locked

ReportEnvelope is the only emit shape. Audit log, builder attribution, heartbeat, SLA, PnL all read from the envelope stream.

Runtime stages advanced

Stage 3 Canonical state Stage 9 Inventory Stage 11 Monitoring & rollout

Bots in this phase · 0 wired of 6

attributionrevenuereporter builderattribution health-heartbeat view all 6 →

gov: 6

0/3 infra tasks done

Exit gate

Every bot in the reference set emits via the envelope. Free-text logging removed.

Infra tasks (0/3)

State	ID	Task
pending	`p3.envelope-runtime`	Runtime emits envelopes with botVersion + configVersion auto-populated
pending	`p3.audit-log-consumer`	gov.audit_log consumes the envelope stream end-to-end
pending	`p3.lint-no-freetext`	CI lint rule: no console.log / no free-text logger calls in bot code

Phase 4

Core risk

locked

Kill switch, compliance gate, drawdown, exposure, market quality, stale book, market halt — the pipeline that blocks bad intents before they sign.

Runtime stages advanced

Stage 7 Decision & risk

Bots in this phase · 4 demo-wired of 17

compliancegate · demo killswitch · demo portfolioguard · demo view all 17 →

risk: 17

0/3 infra tasks done

Exit gate

Every Risk bot emits a RiskVote against valid fixtures. Killswitch + compliance + walletpermissionguard enforced in shadow against last 7 days of intents.

Infra tasks (0/3)

State	ID	Task
pending	`p4.risk-pipeline-runtime`	Runtime applies Risk bots in declared order and short-circuits on REJECT
pending	`p4.killswitch-shadow`	risk.killswitch running in shadow against historical intents
pending	`p4.compliance-shadow`	risk.compliance_gate running in shadow against historical intents

Phase 5

Execution rails

locked

Smart router, order shaper, fee/slippage estimator, order lifecycle manager, signing service, wallet permission guard.

Runtime stages advanced

Stage 6 Execution estimate Stage 7 Decision & risk Stage 8 Orders & OMS

Bots in this phase · 1 demo-wired of 24

smartrouter · demo allowancemonitor antitoxicfill view all 24 →

exec: 15 · sec: 9

0/2 infra tasks done

Exit gate

An OrderIntent can become a SignedOrderRequest end-to-end through the mock adapter with builderCode populated.

Infra tasks (0/2)

State	ID	Task
pending	`p5.exec-plan-end-to-end`	OrderIntent → ExecutionPlan → SignedOrderRequest path through the mock adapter
pending	`p5.builder-code-coverage`	100% builderCode coverage — emit fails closed if builderCode is missing

Phase 6

One simple strategy

locked

strat.maker_tight end-to-end. Proves the full Discovery → Intel → Strategy → Risk → Execution → Lifecycle → Governance pipeline.

Runtime stages advanced

Stage 4 Signals Stage 5 Fair value Stage 6 Execution estimate Stage 7 Decision & risk Stage 8 Orders & OMS

Bots in this phase · 1 demo-wired of 1

maker-tight · demo

strat: 1

0/1 infra tasks done

Exit gate

strat.maker_tight produces OrderIntents in shadow for 24 hours of fixtures with zero schema-validation failures.

Infra tasks (0/1)

State	ID	Task
pending	`p6.maker-tight-shadow`	strat.maker_tight emits valid OrderIntents in shadow

Phase 7

Governance & replay

locked

Reconciler, replay simulator, config drift detector, incident commander, attribution reporter, PnL reporter, SLA reporter.

Runtime stages advanced

Stage 9 Inventory Stage 10 Replay & validation Stage 11 Monitoring & rollout

Bots in this phase · 0 wired of 12

backtester config_drift_detector cron-runner view all 12 →

gov: 12

0/2 infra tasks done

Exit gate

Replay simulator can re-derive every decision from the envelope stream alone.

Infra tasks (0/2)

State	ID	Task
pending	`p7.replay-from-envelope`	gov.replay_simulator reconstructs decisions from the envelope stream alone
pending	`p7.reconcile-heartbeat`	gov.reconciler runs on heartbeat against on-chain state

Phase 8

Additional strategies

locked

Only after every other phase is locked. Adding strategies before this point is the most common build-order mistake.

Runtime stages advanced

Stage 4 Signals Stage 5 Fair value Stage 7 Decision & risk

Bots in this phase · 0 wired of 23

basistrader breakout-follower bregman-projection-arb view all 23 →

strat: 23

0/1 infra tasks done

Exit gate

Three additional Strategy bots in shadow, each emitting through the same pipeline as strat.maker_tight with no special-cased code paths.

Infra tasks (0/1)

State	ID	Task
pending	`p8.no-new-strategies`	Hard rule: no new Strategy bots until phases 1–7 lock

Stage → phase reverse lookup

If you’re looking at a stage page and want to know which phase ships it, this is the table. Each stage page also carries this card inline.

Stage	Runtime layer	Shipped by phases
Stage 1	Market registry	P1 P2
Stage 2	Ingestion & book	P2
Stage 3	Canonical state	P1 P2 P3
Stage 4	Signals	P6 P8
Stage 5	Fair value	P6 P8
Stage 6	Execution estimate	P5 P6
Stage 7	Decision & risk	P4 P5 P6 P8
Stage 8	Orders & OMS	P5 P6
Stage 9	Inventory	P3 P7
Stage 10	Replay & validation	P7
Stage 11	Monitoring & rollout	P3 P7

What replaced what

This page consolidates four prior pages — they now redirect here:

~~/roadmap/v3~~ → phases below
~~/roadmap/status~~ → the bot chips inside each phase card, plus the full status board (kept as a detail view)
~~/roadmap/build-order~~ → the phase order itself is the build order
~~/roadmap/build-tiers~~ → the phase grouping