docs: PARKED math-models contingency reference — no implementation authorization

[Trujillofa]

Summary

Docs-only. Converts docs/MATH_MODELS_ROADMAP.md from an active Now/Next implementation agenda into a PARKED contingency / reference. Updates docs/QUICKREF.md and docs/RESEARCH_FRAMEWORK.md so they link a parked reference, not a build queue.

Human-ratified documentation only. Merging this PR creates no research lane and authorizes no implementation.

What this is / is not

• Is: a parked reference for how GARCH / regime / meta-label / RL overlays would have to attach if a separately scoped program is ever explicitly reopened.
• Is not: a Now/Next schedule, Gate-0 brief, research lane, paper/live-go, or implementation authorization.

Gate 0/1 validate an already authorized lane; they do not authorize reopening. Future use requires explicit human reopening of a separately scoped program with a named differentiated / non-public advantage.

Contracts added (conditional on an authorized reopen)

• Causal inference: freeze fitted parameters at each train boundary (not a precomputed test path); forecast test bar t from observations strictly before t; GARCH may update state sequentially but must not refit on test; HMM filtered probabilities only (no test-window smoothing/Viterbi); causal meta-labels with purge/embargo; future-bar perturbation regression test.
• Risk caps: BacktestEngine does not call RiskManager; BacktestConfig has no max_position_pct. Do not claim the simulator already applies RiskManager caps. Shared pure cap policy or explicit frozen backtest cap config; simulator/paper parity tests for caps, LOT_SIZE truncation, min notional, and fixed-notional interaction.
• Winning by silence: comparable exposure / capital utilization and a minimum notional/exposure floor. Trade count alone is insufficient. Report gross exposure, average notional, capital utilization, notional turnover, return, Sharpe, drawdown, and concentration vs the frozen baseline.

use_atr_sizing is implemented on paper and backtest paths. BacktestConfig defaults use_atr_sizing=false. Active production configs are mixed: settings.sol_1h_trend_pullback_overlay_live.yaml, settings.sol_trend_pullback_sparse.yaml, and settings.sentiment_macro.yaml set false; settings.sol_4h_panic_block_paper.yaml omits the override and therefore inherits use_atr_sizing=true from config/base.yaml.

Type of Change

• Documentation update

Testing

Docs only. No runtime or test changes.

Notes

The crypto research program and public-data book remain sealed (June 23 capstone). Merging this parked reference does not authorize implementation, research, paper/live-go, or deployment.

[Copilot]

🟡 Changes recommended

The new roadmap contains at least one misleading statement about current use_atr_sizing support that should be corrected to avoid inaccurate guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a docs-only roadmap describing the planned implementation order for mathematical model “overlays” (vol sizing, regime flags, meta-labeling, RL execution/sizing) and links it from existing research documentation so it’s discoverable alongside the current WFO/autopilot workflow.

Changes:

• Add docs/MATH_MODELS_ROADMAP.md design note covering model sequencing, integration points, baselines, and kill criteria.
• Link the new roadmap from docs/RESEARCH_FRAMEWORK.md.
• Add a quick reference entry in docs/QUICKREF.md.

File summaries

File	Description
docs/RESEARCH_FRAMEWORK.md	Adds a pointer to the math-model roadmap and lists it in the artifact/location table.
docs/QUICKREF.md	Adds the roadmap to the quick reference list for faster navigation.
docs/MATH_MODELS_ROADMAP.md	Introduces the new roadmap document describing model overlays and how they attach to existing backtest/execution paths.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Trujillofa]

Review: one wording fix, then good to un-draft

Docs-only, 3 files, +155. CI green.

I fact-checked the "Current stack" table against the tree, since a roadmap that misdescribes what exists is worse than no roadmap. Everything holds except one row:

• "No ADX. No GARCH. No HMM." — confirmed, grep -in adx src/features/ returns nothing.
• Next-open fills — confirmed, fill_source="next_bar_open" at src/backtest/engine.py:478,491.
• Corrected cost book (fee 0.0004, slip 0.0002, scaled_8h) — matches src/backtest/cost_overrides.py.
• src/rl/agent.py not wired into src/main.py — confirmed.
• fit_two_state_regime lives in src/backtest/synthetic.py — confirmed, and the warning not to reuse it for live classification is the right call.
• use_atr_sizing "unused" — this one is wrong; see the inline comment. It's implemented on both the paper and backtest paths, just disabled in every active agent config.

Sequencing

The "Costs" row makes this depend on #179: rank only once the cost book is frozen on main. So the order is #180 → #179 → #181, and this staying draft until #179 lands is the right posture.

Substance

The discipline here is the valuable part, and it's consistent with the standing program state rather than a way around it — train-only ranking with the spec frozen before test bars are seen, one model family per PR with a named baseline it must beat after costs, explicit kill criteria per family, and "no live-go from research paths." Two details I'd call out as the ones that will actually do work later:

• "A model that sizes a silent overlay cannot beat a baseline." Given that several production configs currently emit zero fills, this is the sentence that stops the first GARCH PR from being evaluated against nothing. Good that it's near the top.
• The kill criterion "or it only 'wins' by silencing the account (zero trades)" on the regime flag closes the obvious cheat. Worth adding the same clause to the GARCH item — a vol-target sizer can shrink to near-zero notional in high vol and post a flattering Sharpe on almost no exposure, which is the sizing analogue of the same failure. The turnover metric partly catches it, but not the shrink-to-nothing case.

Also right to keep this out of docs/specs/ — it's a design note, not a lane brief, and the closing line correctly subordinates it to Gate 0/1 in RBI_AUTORESEARCH_LOOP.md.

---

Generated by Claude Code