From ff251b5ace8010de64e21c83a0ddf139aa1b733d Mon Sep 17 00:00:00 2001 From: Bu5hm4nn Date: Sat, 28 Mar 2026 08:53:02 +0100 Subject: [PATCH] docs: add GLD pricing and underlying selector roadmap items --- docs/roadmap/ROADMAP.yaml | 12 +++++++-- ...TA-004-underlying-instrument-selector.yaml | 25 +++++++++++++++++++ .../PRICING-001-gld-expense-ratio-decay.yaml | 21 ++++++++++++++++ .../PRICING-002-gld-gcf-basis-display.yaml | 23 +++++++++++++++++ ...ICING-003-hedge-strike-gld-correction.yaml | 20 +++++++++++++++ 5 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 docs/roadmap/backlog/DATA-004-underlying-instrument-selector.yaml create mode 100644 docs/roadmap/backlog/PRICING-001-gld-expense-ratio-decay.yaml create mode 100644 docs/roadmap/backlog/PRICING-002-gld-gcf-basis-display.yaml create mode 100644 docs/roadmap/backlog/PRICING-003-hedge-strike-gld-correction.yaml diff --git a/docs/roadmap/ROADMAP.yaml b/docs/roadmap/ROADMAP.yaml index dcdbc31..f4a6ea3 100644 --- a/docs/roadmap/ROADMAP.yaml +++ b/docs/roadmap/ROADMAP.yaml @@ -1,5 +1,5 @@ version: 1 -updated_at: 2026-03-26 +updated_at: 2026-03-27 structure: backlog_dir: docs/roadmap/backlog in_progress_dir: docs/roadmap/in-progress @@ -13,9 +13,13 @@ notes: - Pre-alpha policy: we may cut or replace old features without backward compatibility until alpha is declared. - Alpha migration policy: once alpha is declared, compatibility only needs to move forward; backward migrations are not required. priority_queue: + - PRICING-001 + - PRICING-003 - EXEC-002 + - PRICING-002 - DATA-002A - DATA-001A + - DATA-004 - OPS-001 - BT-003 - BT-002A @@ -39,10 +43,14 @@ recently_completed: - CORE-002B states: backlog: + - PRICING-001 + - PRICING-003 + - PRICING-002 + - EXEC-002 - DATA-002A - DATA-001A + - DATA-004 - OPS-001 - - EXEC-002 - BT-003 - BT-002A in_progress: [] diff --git a/docs/roadmap/backlog/DATA-004-underlying-instrument-selector.yaml b/docs/roadmap/backlog/DATA-004-underlying-instrument-selector.yaml new file mode 100644 index 0000000..d81b422 --- /dev/null +++ b/docs/roadmap/backlog/DATA-004-underlying-instrument-selector.yaml @@ -0,0 +1,25 @@ +id: DATA-004 +title: Underlying Instrument Selector +status: backlog +priority: P2 +size: L +depends_on: + - PRICING-001 +acceptance_criteria: + - User can choose underlying instrument for options evaluation (GLD vs GC=F) + - Settings page exposes underlying selector with brief descriptions + - Workspace-scoped preference persisted + - Overview and Hedge pages reflect chosen underlying for price display and options strategy + - GC=F options data source placeholder exists (not yet wired to live data) + - UI clearly indicates which underlying is active and whether data is live or placeholder +notes: + - GLD is the MVP supported underlying with live data via yfinance + - GC=F futures options will require a new data source (future roadmap item) + - For now, GC=F selection can show "coming soon" or use estimated/stubbed pricing + - Each underlying has different contract specs (100 shares vs futures contract multiplier) +implementation_hints: + - Add underlying field to workspace/portfolio settings + - Extend app/domain/instruments.py with GC=F metadata (futures contract specs) + - Add underlying selector UI in settings + - DataService routes quote/options requests based on selected underlying + - For GC=F, stub with estimated pricing or clear "data source needed" state \ No newline at end of file diff --git a/docs/roadmap/backlog/PRICING-001-gld-expense-ratio-decay.yaml b/docs/roadmap/backlog/PRICING-001-gld-expense-ratio-decay.yaml new file mode 100644 index 0000000..557a64a --- /dev/null +++ b/docs/roadmap/backlog/PRICING-001-gld-expense-ratio-decay.yaml @@ -0,0 +1,21 @@ +id: PRICING-001 +title: GLD Expense Ratio Decay Correction +status: backlog +priority: P0 +size: S +depends_on: [] +acceptance_criteria: + - GLD weight_per_share uses the current expense-adjusted backing (~0.0919 oz/share in 2026), not the naive 0.1 oz/share + - Expense ratio decay formula implemented: ounces_per_share = 0.10 * e^(-0.004 * years_since_2004) + - All GLD conversions throughout the app use the corrected rate + - Domain tests prove conversion math matches research document examples + - Existing GLD-based tests updated to use corrected backing +notes: + - See docs/GLD_BASIS_RESEARCH.md for the research basis + - Current hardcoded 0.1 oz/share in app/domain/instruments.py is incorrect + - This is a data/modeling fix, not a UI change + - Should be implemented before any GC=F comparison features +implementation_hints: + - Update app/domain/instruments.py to compute GLD backing dynamically + - Add a data source for GLD NAV/ounce (can start with hardcoded 0.0919 approximation) + - Verify app/domain/portfolio_math.py and app/domain/backtesting_math.py use corrected conversions \ No newline at end of file diff --git a/docs/roadmap/backlog/PRICING-002-gld-gcf-basis-display.yaml b/docs/roadmap/backlog/PRICING-002-gld-gcf-basis-display.yaml new file mode 100644 index 0000000..03b2a53 --- /dev/null +++ b/docs/roadmap/backlog/PRICING-002-gld-gcf-basis-display.yaml @@ -0,0 +1,23 @@ +id: PRICING-002 +title: GLD/GC=F Basis Display +status: backlog +priority: P1 +size: M +depends_on: + - PRICING-001 +acceptance_criteria: + - Overview page shows both GLD implied spot and GC=F adjusted for comparison + - Basis indicator visible with threshold-based coloring (green < 25bps, yellow 25-50bps, red > 50bps) + - Warning displayed when basis exceeds normal bounds + - After-hours pricing gap noted when GLD is stale vs GC=F + - Display "last regular session close" vs "current futures indication" where appropriate +notes: + - GLD only trades US market hours (9:30 AM - 4 PM ET) + - GC=F trades 23 hours/day, 6 days/week + - Contango is typically ~$10/oz, causing GLD to appear at "discount" vs GC=F/10 + - During stress (backwardation), GLD can appear at "premium" +implementation_hints: + - Add basis calculation to price display logic + - Use GLD price / GLD_OUNCES_PER_SHARE for implied spot + - Use GC=F - contango_estimate for fair value comparison + - Consider adding a small info tooltip explaining basis \ No newline at end of file diff --git a/docs/roadmap/backlog/PRICING-003-hedge-strike-gld-correction.yaml b/docs/roadmap/backlog/PRICING-003-hedge-strike-gld-correction.yaml new file mode 100644 index 0000000..fea9e57 --- /dev/null +++ b/docs/roadmap/backlog/PRICING-003-hedge-strike-gld-correction.yaml @@ -0,0 +1,20 @@ +id: PRICING-003 +title: Hedging Strike Calculation Using True GLD Price +status: backlog +priority: P0 +size: S +depends_on: + - PRICING-001 +acceptance_criteria: + - Hedge page strike selection uses true GLD price, not converted from GC=F + - Contract count calculation uses corrected GLD backing: ceil(gold_ounces / (100 * GLD_OUNCES_PER_SHARE)) + - ATM/OTM strike calculations use GLD current price times backing ratio + - UI shows correct "contracts needed" for user's gold ounce exposure +notes: + - Previous naive calculation assumed 10 shares per ounce + - Correct ratio is ~10.9 shares per ounce (1 / 0.0919) in 2026 + - Do NOT convert from GC=F to GLD for hedging — use GLD price directly +implementation_hints: + - Update app/pages/hedge.py strike calculations + - Update app/services/strategy_templates.py estimated contract calculations + - Verify app/components/strategy_panel.py displays correct contract count \ No newline at end of file