Skip to content

Risk and Go Live

Savvas Leousis edited this page Sep 26, 2026 · 2 revisions

Risk and Go-Live

Two guards stand between a strategy and real orders: the risk rules on every tick, and the go-live check before a human promotes.

flowchart LR
  LAB[lab run passes] --> SH[shadow<br/>virtual trading]
  SH --> GL{golive check}
  GL -->|PASS| H[Human runs<br/>registry promote]
  GL -->|FAIL| SH
  GL -.->|FAIL, with --override --reason| H
  H --> AC[active]
  AC --> RL[risk rules<br/>every tick]
  RL --> BR[Broker]
Loading

Risk rules

Risk rules sit between the constructor and the broker. Each rule is a registered class in production/rules/; a new rule is one new file. Clipped or dropped orders are listed in the tick summary under risk_adjustments.

Configured under [production.risk] today:

Setting Default Effect
enabled true false passes orders through untouched
max_open_positions unlimited Drops a buy that would open one position too many
max_weight_per_ticker 1.0 Clips buys so one ticker stays under this share of portfolio value
max_weight_per_asset_class none For example crypto = 0.2; clips buys per class
cash_buffer_fraction 0.0 Keeps this share of value in cash, net of costs
min_order_notional 0.0 Drops buys smaller than this amount

Always on: sells are clipped to what you hold (never a short), and buys need a current price.

Registered but not wired to config yet (off until [production.risk.rules.*] lands):

Rule Guards against
risk_per_position One position carrying too much loss (ATR-based, 2% rule)
portfolio_vol Book volatility above a target
drawdown_scaling Full size while in a drawdown (buys shrink as it deepens)
liquidity Buys too big against daily dollar volume
sector_cap Too much in one sector
max_holding Zombie positions held too long
  • Weights use portfolio value before the tick's orders.
  • Sells go first; buys are re-checked against the post-sell book.
  • Shadow strategies go through the same policy.
[production.risk]
max_open_positions = 10
max_weight_per_ticker = 0.25
cash_buffer_fraction = 0.05

[production.risk.max_weight_per_asset_class]
crypto = 0.2

Go-live check

stonks golive check <id> judges a strategy's paper period: its shadow P&L while shadow, the real simulated or paper book once active. The console shows the same checks (GET /api/strategies/{id}/golive).

uv run stonks golive check <id>
uv run stonks golive check <id> --since 2026-08-01
Check Default limit ([golive])
status shadow or active
min_days 63 days, or MinTRL of the OOS Sharpe if longer (capped at 252)
max_drawdown no fall deeper than 15%
max_drift paper return within 10 points of what the OOS backtest expected
min_trades at least 20 filled trades
survival every stored survival report passed
within_mc_band paper drawdown and return inside the Monte Carlo band of mc_trades
quit_rule paper drawdown under 1.5x the backtest drawdown
promotion_preset every test of the promotion preset has a stored report
nonzero_costs the lab run used a non-zero cost model
hypothesis_recorded a hypothesis of at least 20 characters
backtest_min_trades at least 30 trades in the backtest

The last six belong to the incubation grade (incubation = true, the default). Missing data fails a check. Exit code is 1 when any check fails.

Promotion is always human and audited

  • The lab only registers in shadow.
  • The go-live check only reports; it never changes status.
  • stonks registry promote <id> needs a passing go-live check, or --override --reason "..." (at least 20 characters).
  • Every status change is written to status_changes; see it with stonks registry history <id>.
  • MCP write tools need confirm: true and cannot turn on live trading.
uv run stonks registry list --status shadow
uv run stonks registry show <id>
uv run stonks registry promote <id>
uv run stonks registry shadow <id> --reason "drawdown beyond plan"
uv run stonks registry retire <id> --reason "edge gone"
uv run stonks registry history <id>

Not built yet: a global kill switch and the circuit breaker (roadmap 12.6 and Phase 9 Wave 3).

Clone this wiki locally