diff --git a/docs/roadmap/ROADMAP.yaml b/docs/roadmap/ROADMAP.yaml index 90266d9..4b2fac3 100644 --- a/docs/roadmap/ROADMAP.yaml +++ b/docs/roadmap/ROADMAP.yaml @@ -11,9 +11,10 @@ notes: - One task lives in one YAML file and changes state by moving between status folders. - Priority ordering is maintained here so agents can parse one short file first. priority_queue: - - CORE-002 + - CORE-002B - CORE-001D - BT-003B + - CORE-002 - PORT-003 - BT-002 - BT-001C @@ -24,12 +25,12 @@ priority_queue: - OPS-001 - BT-003 recently_completed: + - CORE-002A - CORE-001D1 - SEC-001 - SEC-001A - CORE-001A - CORE-001B - - CORE-001C states: backlog: - DATA-002A @@ -44,6 +45,7 @@ states: - BT-001C - CORE-001D - CORE-002 + - CORE-002B in_progress: [] done: - DATA-001 @@ -62,5 +64,6 @@ states: - CORE-001A - CORE-001B - CORE-001C + - CORE-002A blocked: [] cancelled: [] diff --git a/docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml b/docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml index 19bf20a..f15a721 100644 --- a/docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml +++ b/docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml @@ -9,15 +9,19 @@ depends_on: - CORE-001C tags: [core, units, pricing, domain] summary: > - Model quoted instruments with explicit asset/share units and conversion multipliers - so prices like GLD are never misinterpreted as physical-gold ounce prices. + Complete the instrument-aware quote-unit rollout so quoted instruments like GLD are + handled explicitly as USD/share and only converted to ounce-equivalent values through + named metadata-backed seams. acceptance_criteria: - GLD quotes are modeled explicitly as prices per share, not as ambiguous gold-ounce prices. - Instrument metadata encodes that 1 GLD share represents 0.1 troy ounces of gold exposure. - Storage/domain value classes know the unit relationship and convert correctly when calculations combine instrument prices with ounce-based quantities. - Cross-unit operations fail closed when no explicit instrument conversion path exists. + - Visible ounce-based pages beyond overview use the explicit conversion seam instead of heuristic fallbacks. - Tests cover GLD share <-> troy-ounce conversion and reject unsupported mixed-unit operations. technical_notes: + - `CORE-002A` is complete: overview now uses explicit GLD share -> USD/ozt conversion with quote-unit metadata and cache normalization. + - Next suggested slice is `CORE-002B`: apply the same explicit quote-unit model to the next visible ounce-based path, especially hedge/runtime portfolio displays that still assume ounce-native spots. - Prefer explicit instrument/unit types over ad hoc scale factors in page/service code. - This should integrate with the Decimal/unit-safe domain model rather than bypass it with raw floats. - Consider extending historical/unit types so both live overview paths and backtesting/event paths can share the same conversion rules. diff --git a/docs/roadmap/backlog/CORE-002B-hedge-quote-unit-rollout.yaml b/docs/roadmap/backlog/CORE-002B-hedge-quote-unit-rollout.yaml new file mode 100644 index 0000000..90fac19 --- /dev/null +++ b/docs/roadmap/backlog/CORE-002B-hedge-quote-unit-rollout.yaml @@ -0,0 +1,23 @@ +id: CORE-002B +title: Hedge and Strategy Runtime Quote Unit Rollout +status: backlog +priority: P0 +effort: M +depends_on: + - CORE-002A + - CORE-001B +tags: + - core + - units + - hedge + - pricing +summary: Apply explicit instrument-aware quote-unit conversions to the next visible ounce-based hedge/runtime paths so they no longer assume ounce-native spot prices. +acceptance_criteria: + - Hedge/runtime displays that consume live or configured GLD spots use explicit share->ozt conversions where needed. + - Visible strategy/hedge labels distinguish converted collateral spot from raw share quotes when relevant. + - Unsupported or missing quote-unit metadata fails closed rather than silently applying raw share prices as ounce prices. + - Tests cover the changed hedge/runtime math and browser-visible route behavior. +technical_notes: + - Likely file targets include `app/pages/hedge.py`, `app/pages/common.py`, and any service/helpers feeding hedge summary/runtime spot values. + - Reuse the new instrument metadata seam rather than introducing new ad hoc scale factors. + - Keep backtesting/event share-based paths compatible while tightening visible ounce-based paths. diff --git a/docs/roadmap/done/CORE-002A-overview-quote-conversion.yaml b/docs/roadmap/done/CORE-002A-overview-quote-conversion.yaml new file mode 100644 index 0000000..0006d33 --- /dev/null +++ b/docs/roadmap/done/CORE-002A-overview-quote-conversion.yaml @@ -0,0 +1,22 @@ +id: CORE-002A +title: Overview GLD Share Quote Conversion Seam +status: done +priority: P0 +effort: S +depends_on: + - CORE-001A + - CORE-001B + - CORE-001C +tags: + - core + - units + - pricing + - overview +summary: Overview now treats GLD quotes explicitly as USD/share and converts them to USD/ozt through instrument metadata. +completed_notes: + - Added `app/domain/instruments.py` with explicit instrument metadata for GLD. + - Encoded `1 GLD share = 0.1 ozt` and fail-closed conversions between share quantities, share prices, and troy-ounce values. + - Updated overview quote resolution to require explicit `quote_unit` metadata before converting share quotes to collateral spot values. + - Added quote payload normalization in `DataService` so cached legacy GLD quotes are upgraded safely with `quote_unit: share`. + - Replaced the previous ratio-based overview fallback heuristic with an explicit metadata-backed conversion seam. + - Added focused unit tests plus live Playwright coverage on `main`.