feat(fase1): assessment-method encoding — persisted dimension-scoped example + validator rule (F1)

src/portfolio_optimiser/data/method_examples/energi/index.md

@@ -0,0 +1,19 @@
+---
+type: index
+okf_version: 0.1
+title: "Energi — vurderingsmetode-encodinger (MAF-repo-lokalt)"
+description: "Persisterte, dimensjon-scopede vurderingsmetode-encodinger for energi-dimensjonen, navigerbare via OKF."
+dimension: energi
+tags: [metode, encoding, energi, IPMVP]
+timestamp: 2026-07-06
+---
+
+# Energi — vurderingsmetode-encodinger
+
+Et persistert, **MAF-repo-lokalt** metode-bundle. Det bor her (ikke i `shared/`) fordi `shared/` er
+et PULL-ONLY subtree som ikke kan bære `dimension:`-frontmatter herfra. Bundelet encoder ≥1
+vurderingsmetode mot referanse-domenet (energieffektivisering), dimensjon-scopet så
+`okf.bundle_context(..., dimension="energi")` navigerer den (progressiv disclosure), og en annen
+dimensjon utelater den.
+
+- [IPMVP Option A — energi-metode](metode-ipmvp-a.md)

src/portfolio_optimiser/data/method_examples/energi/metode-ipmvp-a.md

@@ -0,0 +1,29 @@
+---
+type: methodology
+title: "IPMVP Option A — Retrofit Isolation, Key Parameter Measurement (energi)"
+description: "M&V-metoden for å verifisere energibesparelsen fra ett isolert tiltak: mål nøkkelparameteren (effekt), estimér resten (driftstimer). Dimensjon-scopet encoding."
+dimension: energi
+methodology: IPMVP
+option: A
+tags: [IPMVP, M&V, EVO, energi, retrofit-isolation]
+timestamp: 2026-07-06
+---
+
+# M&V-metode: IPMVP Option A (energi-dimensjon)
+
+ENERGI-METODE-IPMVP-A-SENTINEL — denne encodede metoden er dimensjon-scopet til `energi`, så den
+når kun agent-konteksten når kjøringen scopes til energi-dimensjonen.
+
+**IPMVP** (International Performance Measurement and Verification Protocol) er konsensus-rammeverket
+for å måle og verifisere energibesparelser, eid av **EVO** (Efficiency Valuation Organization).
+Kjerneinnsikten: besparelse er en **kontrafaktisk** størrelse — den *beregnes*
+(`Baseline − Rapportering ± justeringer`), den måles ikke direkte.
+
+## Option A — Retrofit Isolation: Key Parameter Measurement
+
+Måler nøkkelparameteren (typisk effekt) på det berørte utstyret; øvrige parametere (typisk
+driftstimer) **estimeres**. Fordi driftstimene er stipulert — ikke fullmålt — er den forsvarlige
+verifiserte besparelsen **mer konservativ** enn en generisk øvre grense: en andel av tiltakets
+kostnad som ligger UNDER den generiske policy-taket. Denne strammere, metode-spesifikke grensen er
+kodifisert som en egen validator-stage (`validator._ENERGY_METHOD_MAX_FRACTION`), uavhengig av det
+generiske P90-taket.

src/portfolio_optimiser/validator.py

@@ -37,6 +37,15 @@ MAX_SAVING_FRACTION = 0.30
 """Policy cap: at most 30% of an affected item's cost is realistically recoverable as a
 saving. The LP bounds the feasible saving by this fraction."""
 
+_ENERGY_METHOD_MEASURE = "energy_efficiency"
+_ENERGY_METHOD_MAX_FRACTION = 0.15
+"""Step 9 (SC7-B): the IPMVP Option A method-specific cap. Option A measures only the KEY parameter
+and STIPULATES the rest (operating hours), so the defensibly-verifiable saving is more conservative
+than the generic policy cap — deliberately STRICTER than ``MAX_SAVING_FRACTION`` so this rule is an
+INDEPENDENT gate: it can reject a proposal the generic P90 stage passes (not redundant). The concrete
+fraction is calibrated against the reference domain; the CONDITION (a method-scoped stricter cap) is
+the encoded rule. Returns the same ``Rejection`` type — a validator stage, not a new gate."""
+
 _MC_SAMPLES = 512
 _MC_SEED = 20260624
 
@@ -126,6 +135,21 @@ def validate_proposal(proposal: SavingsProposal) -> ValidatedProposal | Rejectio
             proposal=proposal,
             reason=f"claimed saving {proposal.claimed_saving_nok:.0f} exceeds P90 feasible {p90:.0f}",
         )
+    # Stage 5 (Step 9, SC7-B): a method-specific rule STRICTER than the generic cap. A proposal in
+    # the energy method (IPMVP Option A) must clear a lower, method-scoped feasible — an INDEPENDENT
+    # gate that can reject a proposal the P90 stage passed. Same ``Rejection`` type, not a new gate.
+    if proposal.measure == _ENERGY_METHOD_MEASURE:
+        method_feasible = _ENERGY_METHOD_MAX_FRACTION * sum(
+            it.total for it in proposal.affected_items
+        )
+        if proposal.claimed_saving_nok > method_feasible:
+            return Rejection(
+                proposal=proposal,
+                reason=(
+                    f"claimed {proposal.claimed_saving_nok:.0f} exceeds the {_ENERGY_METHOD_MEASURE} "
+                    f"method cap {method_feasible:.0f} (stricter than the generic P90)"
+                ),
+            )
     return ValidatedProposal(proposal=proposal, p10=p10, p50=p50, p90=p90, nominal_feasible=nominal)