From 691277dea2c92ab2b64cca34f83354d0a826baa0 Mon Sep 17 00:00:00 2001
From: Bu5hm4nn <bu5hm4nn@users.noreply.github.com>
Date: Wed, 25 Mar 2026 10:49:46 +0100
Subject: [PATCH] docs: add instrument-aware quote unit story

---
 docs/CORE-001D_BOUNDARY_CLEANUP_PLAN.md       |  3 +++
 docs/roadmap/ROADMAP.yaml                     |  2 ++
 ...CORE-002-instrument-aware-quote-units.yaml | 23 +++++++++++++++++++
 3 files changed, 28 insertions(+)
 create mode 100644 docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml

diff --git a/docs/CORE-001D_BOUNDARY_CLEANUP_PLAN.md b/docs/CORE-001D_BOUNDARY_CLEANUP_PLAN.md
index d6f20ab..8b85e1b 100644
--- a/docs/CORE-001D_BOUNDARY_CLEANUP_PLAN.md
+++ b/docs/CORE-001D_BOUNDARY_CLEANUP_PLAN.md
@@ -108,6 +108,9 @@ Deliverables:
 - replacing every float in every Pydantic/dataclass immediately
 - redesigning third-party payload models wholesale
 - changing public UI formatting behavior just for type purity
+- solving instrument-level share-to-underlying conversion semantics such as `GLD share = 0.1 ozt` inside this slice alone
+
+That broader instrument-aware unit problem is tracked separately in `CORE-002`.
 
 ## First candidate sub-slices
 
diff --git a/docs/roadmap/ROADMAP.yaml b/docs/roadmap/ROADMAP.yaml
index c883d5d..f9bde08 100644
--- a/docs/roadmap/ROADMAP.yaml
+++ b/docs/roadmap/ROADMAP.yaml
@@ -12,6 +12,7 @@ notes:
   - Priority ordering is maintained here so agents can parse one short file first.
 priority_queue:
   - CORE-001D
+  - CORE-002
   - BT-003B
   - PORT-003
   - BT-002
@@ -42,6 +43,7 @@ states:
     - BT-003B
     - BT-001C
     - CORE-001D
+    - CORE-002
   in_progress: []
   done:
     - DATA-001
diff --git a/docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml b/docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml
new file mode 100644
index 0000000..19bf20a
--- /dev/null
+++ b/docs/roadmap/backlog/CORE-002-instrument-aware-quote-units.yaml
@@ -0,0 +1,23 @@
+id: CORE-002
+title: Instrument-Aware Quote Units and Conversion Multipliers
+status: backlog
+priority: P0
+effort: M
+depends_on:
+  - CORE-001A
+  - CORE-001B
+  - 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.
+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.
+  - Tests cover GLD share <-> troy-ounce conversion and reject unsupported mixed-unit operations.
+technical_notes:
+  - 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.