# Expansion Requirements — Triage & Roadmap

Per docs/EXPANSION_REQUIREMENTS.md's own rule ("research first, recommend,
wait for approval"), this is the analysis and recommendation. Nothing below
in NEEDS APPROVAL is built until you say go.

## Already built ✅

| Feature | Status |
|---|---|
| F3 Options Selection | Built — delta-fit/OI/spread/IV contract scoring. *Gap: POP/POT metrics — small add.* |
| F4 Trade Scoring 0-100 | Built — Trade Readiness Score with configurable thresholds |
| F5 Trade Alerts | Built — email + Telegram with contract, entry/stop/targets, reasoning, dedupe |
| F10 AI Decision Engine | Built — weighted explainable ensemble, conflict penalties, calibration; every signal carries rationale |
| F11 Backtesting | Built — walk-forward, no look-ahead, costs modeled. *Gaps: Sharpe/Sortino, per-sector & per-regime splits — medium add.* |
| F13 Logging | Partial — decisions/gates logged to console; centralized structured logging is audit item H-4 (top observability priority) |
| F12 UI | Largely built (11 pages, auth, rate limiting). *Gaps: password reset, email verification, 2FA, roles → Phase 3 multi-user work, gated by audit C-1* |

## Recommended next builds (NEEDS APPROVAL)

**A. Earnings Prediction Engine (F1+F2)** — the biggest genuinely new feature.
Recommended approach: transparent weighted scoring model (not opaque ML —
insufficient training data exists yet, and the audit requires explainability):
historical surprise rate + estimate revisions + pre-earnings drift + IV
expansion/implied move (needs Tradier for real IV). Outputs Buy Call / Buy
Put / No Trade with confidence + factors; the 2–3-week timing logic and
IV-crush avoidance become part of the earnings guard. Prerequisites:
FINNHUB_API_KEY (earnings history/estimates, free tier) + TRADIER_API_TOKEN
(real IV). ~1 build wave. **No Trade must be the default output** when data
is insufficient.

**B. Backtest metric upgrades** — Sharpe/Sortino/sector/regime breakdowns.
Small, no new data needed. Recommend bundling with A.

**C. SMS alerts (F6)** — research done: Twilio is the reliability/docs
leader (~$0.008/msg + ~$1.15/mo number); Amazon SNS cheapest at scale but
worst DX; Telnyx/Plivo cheaper per-message with thinner docs. **Recommendation:
Telegram (already built, free) covers the need today; add Twilio only if you
need true SMS.** If approved: TWILIO_* env vars, same alert pipeline, the
disclaimer line appended automatically. ~half a wave.

**D. TradingView (F9)** — no official retail API. Recommended pattern:
inbound **webhook receiver** for TradingView alerts (their native feature,
paid TV plan required) feeding the ensemble as one more scored input, never
a sole trigger. Requires the deployed server (public URL) first. ~1 wave
after deployment.

## Gated — do not build yet 🔒

**F7/F8 Broker integration & Schwab/Thinkorswim.** This is the live-trading
path. Research summary: Alpaca (already integrated for data) has the
cleanest API + paper trading; Schwab's API requires an approval process and
OAuth app registration; IBKR is powerful but heaviest to integrate; Tradier
supports options execution with simple auth. **Recommendation when the time
comes: read-only account/position sync first (Alpaca paper), execution
never.** Order execution — even "disabled by default" — violates audit
blocker B-1 until the full Phase 11 order-lifecycle work (idempotency,
reconciliation, kill switches) plus independent review exists. The plugin/
adapter architecture the spec requests already exists (provider factories) —
a broker adapter slots in without core changes when approved.

## Approval checklist

- [ ] A: Earnings Prediction Engine (needs Finnhub + ideally Tradier keys)
- [ ] B: Backtest metrics upgrade
- [ ] C: Twilio SMS (or stay with Telegram)
- [ ] D: TradingView webhooks (after VM deployment)
- [ ] F7 read-only broker sync (recommend deferring until paper track record)