feat: add SOXL volatility scaling research overlay

[Pigbibi]

Summary

• publication-only replacement for closed PR feat: add SOXL volatility scaling research overlay #287 after a PR-object/ref-binding anomaly
• publish the existing same-repo branch at exact commit 2f7693c1e3b5b5424fca1c2bb6f32d756c755eb9
• no code edit, amend, recommit, force-push, new branch, or new worktree was performed for this recovery

Recorded validation evidence

• focused starting-peak regression: 1 passed
• focused SOXL/R3 suite: 19 passed
• compileall: passed
• exact two-file scope and diff-check: passed
• Ruff unavailable in the existing environment; no install performed

Research-only; no provider/data/optimization run or live adoption.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f7693c1e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

🤖 Codex PR Review

✅ Merge allowed: 1 finding(s) reported but none are blocking

ℹ️ Other Findings

1. 🟡 [MEDIUM] Logic in src/us_equity_strategies/research/soxl_core_optimization.py

The partial-sell rebalance path computes traded_quantity from the raw notional gap divided only by execution.open, then subtracts slippage and commission afterward. In run_soxl_volatility_scaling, every non-zero-cost scenario (C1_2, C2_5, C5_10_STRESS) uses this simulator, so whenever the SMA signal stays risk-on but the volatility multiplier decreases without going to zero, the remaining position ends up larger than the requested multiplier because post-trade equity is reduced by costs. That biases the candidate's return, drawdown, expected-shortfall, and turnover metrics, and can change winner selection or evidence gates. (line 250)

Suggestion: Solve the sell size against post-cost equity instead of the raw open price gap. For example, derive traded_quantity so that the remaining open notional matches the target after accounting for slippage and commission, or recompute the target from post-trade equity and iterate until the exposure ratio is within a small tolerance.

---

Review by Codex PR Review bot • PR