From ec88dadae2b02d9ea284eaea36331771fbcb2b78 Mon Sep 17 00:00:00 2001 From: Khalim Conn-Kowlessar Date: Tue, 23 Jun 2026 22:15:08 +0000 Subject: [PATCH] docs: record effective-as-canonical-current decision + provenance terms ADR-0002: Effective performance is the canonical "current" for display and reporting; lodged shown alongside (supersedes the mid-migration "reporting stays lodged" note). CONTEXT.md gains EPC-provenance and provenance-signal terms, and flags that the UI "Current EPC" surfaces show Effective. Co-Authored-By: Claude Opus 4.8 (1M context) --- CONTEXT.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index c2073354..cdd69ab7 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -124,6 +124,14 @@ _Avoid_: current performance, adjusted performance The act of substituting a corrected set of performance metrics in place of the Lodged values. Recorded on `property_baseline_performance` with a `rebaseline_reason` enum value: `none`, `pre_sap10`, `physical_state_changed`, or `both`. _Avoid_: override, adjustment, correction +**EPC provenance** (`epc_property.source`): +Whether a property's EPC picture is a real certificate or a gap-fill. `lodged` = a real public/landlord EPC exists; `predicted` = no certificate, so the EPC was estimated from nearby properties (EPC Prediction gap-fill). Independent of Rebaseline: a `lodged` property may still be rebaselined, and a `predicted` property still carries Lodged-performance figures (mirrored estimates), so the presence of `lodged_*` columns does **not** imply a real certificate — only `source = lodged` does. +_Avoid_: estimated EPC (reserve "estimated" for the UI signal), source EPC + +**Provenance signal** (UI): +What the user is told about an EPC's trustworthiness, derived from EPC provenance and Rebaseline together: **Estimated** (`source = predicted` — dominant; "estimated based on nearby homes") › **Re-modelled** (`source = lodged AND rebaseline_reason != none` — effective diverged from the lodged certificate under SAP 10) › **none** (`source = lodged AND rebaseline_reason = none` — effective equals lodged). Estimated always wins when both could apply. +_Avoid_: estimation notification, banner (those are component names) + ## Example dialogue > **Dev:** "If the **Combiner** finishes but the user hasn't clicked Finalise, what does the user see?" @@ -136,5 +144,6 @@ _Avoid_: override, adjustment, correction ## Flagged ambiguities +- The UI surfaces labelled **"Current EPC"** and **"Current Efficiency State"** (property table, building-passport card) show **Effective performance**, not Lodged — despite the glossary advising against "current performance" for Effective. The label is a product choice ("current" = the property's true present-day modelled state); the underlying datum is still **Effective performance**. The **"Lodged EPC"** column/badge is the only surface showing **Lodged performance**, and only when a real certificate exists (`source = lodged`). - "Upload" is used in the codebase to mean both the file-on-S3 and the BulkUpload row. We standardise on **BulkUpload** for the row; the file is just "the source file." - "Onboarding" appears in some route paths (`bulk_onboarding_inputs/...`) but isn't part of this glossary — we use **BulkUpload** end-to-end.