portfolio-optimiser-commons/docs/plan/2026-07-25-amendment-underlag.md

# Amendment-underlag — hva frossen tekst sier i dag, per køpunkt

**Status:** underlag. Spec-en er IKKE endret, og dette dokumentet foreslår INGEN ny tekst.
Ny tekst er pakken operatøren ratifiserer, og den eies oppstrøms (`portfolio-optimiser`,
sammen med `portfolio-optimiser-claude`s tekstforslag). Dette dokumentet svarer bare på
spørsmålet commons kan svare på uten å foregripe ratifiseringen: **hvilke seksjoner røres,
hva står der i dag (fil + linje), og hva koster endringen mot fasit-bundelen.**

**Foranledning:** `portfolio-optimiser` klarerte 2026-07-25 (05:09Z, punkt 3) generelt
underlag som trygt arbeid som ikke invalideres av at pakken deres holdes: *«preparing GENERAL
underlag (which spec sections those five stories touch, what the frozen text says today) is
safe work that will not be invalidated»*. Dette er det arbeidet.

**Grunnlag:** commons HEAD `a67a243`. Normativ spec-tekst er uendret siden `bfa5a9b`
(ingest-spec, D1-stempelmodellen) / `9801d35` (method-spec §3 Steg 1, Q3-navigasjonen) /
`b641741` (nav-golden-fixtures) — alle 2026-07-21. Hver sitat-blokk under er hentet fra HEAD
og linjeankeret verifisert, ikke gjengitt fra hukommelse.

---

## 0. Køen, avstemt

To korreksjoner fra `portfolio-optimiser` (16:11Z) er **godtatt**, begge verifisert:

1. **Tittel-whitespace er ikke et eget punkt** — det ER amendment-innholdet i S3.5. Vår
   telling dobbeltførte det. (Deres kø-linje `(a) commons-amendment tittel-whitespace → S3.5`
   ble lest som «punkt ved siden av», ikke «innholdet i».)
2. **B1 er ute av pakken** — commons-eid, ingen adferds-interesse oppstrøms. Bæres separat
   (§8 her).

Én korreksjon går **tilbake** oppstrøms, og den er grunnen til at underlaget er verdt å
skrive før pakken lukkes:

3. **De to oppstrøms-enumerasjonene er ikke den samme mengden.** `portfolio-optimiser`
   teller fem *stories* (S2.7 / S2.2–2.4 / S3.2 / S3.5 / S4.0); `portfolio-optimiser-claude`
   teller fem *D-A-punkter*. Bare tre par binder (S2.7 = D-A#1, S3.2 = D-A#4, S4.0 = D-A#2).
   De to gjenstående D-A-punktene har **ingen story-etikett** oppstrøms:
   - **D-A#3 (ledende `/`)** — trenger ingen amendment i det hele tatt. Frossen tekst sier
     allerede det punktet ber om (§1.3 under). Dette er en konformitets-sak i implementasjonen,
     ikke en spec-endring.
   - **D-A#5 (hovedbok-projeksjoner)** — er reell og har ingen tekst å endre (§6 under), men
     mangler story-etikett. Ratifiserer operatøren «pakken» slik `portfolio-optimiser`
     beskriver den, faller D-A#5 utenfor.

   Netto, fra commons' side: pakken er deres seks **pluss** hovedbok-kontrakten = **sju
   ratifiserbare punkter**, med D-A#3 strøket som amendment. B1 utenfor, som avtalt.
   Tallet er ikke poenget — membership er.

**S2.2–2.4 (D-B)** er det ene punktet commons ikke kan ankre: substansen er aldri meldt hit
(§7 under). Ingen gjetning føres her.

---

## 1. S2.7 / D-A#1 — nominal feasibility skal GATE, + IR-invariant `low ≤ unit_cost ≤ high`

**Seksjoner:** `method-spec.md` §3 Steg 4 (`:150-166`), §7.1 (`:335-346`), §7.2 (`:348-365`),
§12 (`:458`).

**Hva frossen tekst sier i dag.** Den nominale grensen *beregnes*, og bare `p90` *blokkerer*:

> **`method-spec.md:157-160`** (§3 Steg 4, punkt 2)
> 2. **Feasibility bound:** the maximum feasible saving is capped at a policy fraction
>    (0.30) of the affected items' total cost. *(reference: computed with an LP solve whose
>    closed form here is `0.30 × Σ quantity·unit_cost`; a missing solver MUST escalate, never
>    silently fall back.)*

> **`method-spec.md:163-166`** (§3 Steg 4, punkt 4)
> 4. **Structural block:** a claim above the optimistic feasible bound (`p90`) yields a
>    **rejection that is a distinct type from a validated proposal** …

Punkt 2 sier `capped at`, men gir ingen avvisningsregel; punkt 4 er den ENESTE blokkeringen
og bruker `p90`. Påstanden «beregnes, men bare p90 blokkerer» holder altså mot teksten.

§7.2 sier det samme eksplisitt om hva assertionen betyr:

> **`method-spec.md:356-358`** (§7.2)
> … The meaningful assertion is `validates` = true (claimed ≤ `p90`); the frozen numbers are
> the regression net.

`nominal_feasible` er et frosset felt (`:352-356`, kryssjekk `:458`) — det er allerede
normativt *rapportert*, bare ikke *gatende*.

**IR-invarianten finnes ikke.** §7.1 har én construction-time-invariant, og den handler om
noe annet:

> **`method-spec.md:343-344`** (§7.1)
> - Construction-time invariant: the claimed saving MUST NOT exceed the affected items' own
>   total (`Σ quantity·unit_cost`); violation is a schema error, not a validator rejection.

`assumptions` er definert som band per kostkode (`:341-342`), men ingenting binder
`unit_cost` til å ligge INNI sitt eget band. Hullet er reelt.

**Målt mot fasit-bundelen (`examples/bygg-energi-mikro/`) — begge endringene er byte-nøytrale:**

| Sjekk | Verdi i fasit | Konsekvens |
|---|---|---|
| `claimed_saving_nok` vs. `nominal_feasible` | `30000` vs. `90000.0` | claimed ≤ nominal → en nominal gate endrer ikke `validates` (fortsatt `true`) |
| `unit_cost` vs. eget band | `1.0` i `[0.70, 1.40]` | invarianten er allerede oppfylt → fixture trenger ingen endring |

Kilder: `examples/bygg-energi-mikro/golden.json` (validator-blokken),
`examples/bygg-energi-mikro/validator-input.json` (`affected_items[0]`, `assumptions`).

**Klassifisering:** ekte hull i frossen tekst (begge deler). Gratis mot goldenbytene.
**Operatør-spørsmålet:** skal nominal-grensen gi samme *type* avvisning som p90-blokket
(`:163-166` sier «distinct type … carrying the claimed and feasible figures … and no
percentiles») eller en egen? Teksten har i dag én avvisningsform, og den er definert av p90.

---

## 2. S3.2 / D-A#4 — seedet dom skal nøkles på SINE EGNE features

**Seksjoner:** `method-spec.md` §3 Steg 1, experience fold (`:105-123`).

> **`method-spec.md:108-114`**
> - The retrieval query key is the bundle's candidate features, read from the IR projection
>   (§7.1) — available *before* any proposal exists.
> - Seeding: every `type: verdict` file in the bundle becomes a store entry keyed on those
>   candidate features, with `decision` from frontmatter (default `approved`) …

`those candidate features` refererer tilbake til forrige kulepunkt — bundelens ENE
IR-projeksjon. Frossen tekst sier altså eksplisitt det punktet vil bort fra: hver seedet dom
arver bundelens projeksjonsnøkkel, ikke sin egen. Hullet er reelt og teksten er entydig.

**Berøringsflate videre:** nøkkelen er det rangeringen (`:115-120`) og id-mintingen
(§4.2 `:254-260`) hviler på. `affected_codes` / `measure_type` / `claimed_saving_nok` er
feltene en «egen-features»-nøkling må komme fra, og §4.2 `:250-252` sier at `description`
bevisst er utenfor både likhet og minting. En amendment her må si hvor en seed-fils egne
features LESES fra (frontmatter? egen projeksjon?) — det er den åpne enden, ikke prinsippet.

**Målt:** fasit-bundelen har én seed (`verdict-led-fro.md`) og én projeksjon, så
`golden.json` kan ikke skille gammel og ny nøkling. Endringen er byte-nøytral her, og
fasiten er derfor ikke et vern mot regresjon på dette punktet.

**Klassifisering:** ekte hull. **Operatør-spørsmålet:** kilden for en seeds egne features.

---

## 3. D-A#3 — ledende `/` : INGEN amendment nødvendig

**Dette punktet er allerede normativt i commons HEAD** (landet `9801d35`, 2026-07-21):

> **`method-spec.md:67-71`** (§3 Steg 1)
> - Navigation starts at `index.md` and follows its intra-bundle markdown cross-links
>   (`](target.md)`). A target is resolved **relative to the bundle** and boundary-checked
>   fail-closed (below): a leading `/` denotes the **bundle root** (NEVER a filesystem-absolute
>   path), any other form is relative to the linking file's own directory — so a target MAY
>   address a nested directory (`sub/index.md`, `/a/b.md`).

Og §11 har allerede rød-betingelsen som feiler hvis en implementasjon hopper over den:

> **`method-spec.md:425`** (§11, «Navigation boundary»)
> … an escaping cross-link (`..`, a filesystem-absolute path, or a bundle-root `/` read as
> filesystem-absolute) is followed, a malformed target … is raised instead of skipped, or a
> legitimate nested in-bundle link is skipped

Teksten sier også selv at den ERSTATTET den gamle skip-heuristikken (`:73-74`).

**Klassifisering:** konformitetsgap i implementasjonen, ikke spec-hull. Ligger et forslag om
å «endre» §3 Steg 1 her, endrer det tekst som allerede sier det forslaget vil oppnå — og
risikoen er at ratifiseringen omformulerer en fungerende regel. **Meldt oppstrøms.**

---

## 4. S4.0 / D-A#2 — kostbaseline-forankring (`cost-baseline.json`)

**Seksjoner:** `method-spec.md` §7 (`:330-333`), §7.1 (`:335-346`), §12 (`:441-464`).

**Frossen tekst har ingen baseline-forankring** — `grep -c 'cost-baseline'` over begge
spec-er: **0 treff**. Det som finnes, og som en ubetinget baseline kolliderer med:

> **`method-spec.md:332-333`** (§7)
> The shared example bundle ships two JSON files that are **the only ground truth** ("fasit")
> for cross-implementation equivalence. Implementations MUST consume them unchanged.

**Målt:** `examples/bygg-energi-mikro/` inneholder nøyaktig to JSON-filer
(`validator-input.json`, `golden.json`) og seks markdown-filer. Ingen baseline. Et ubetinget
krav gjør en tredje fil til ground truth og gjør setningen over usann samtidig — pluss at
fasit-bundelen må utvides, hvilket er en fixture-endring, ikke bare en tekstendring.
`portfolio-optimiser-claude`s egen formulering («åpent om den skal være obligatorisk … et
ubetinget krav endrer golden-bytene») treffer riktig, og §7:332-333 er ankeret som gjør det
konkret.

**Presedens for hvordan en required input formuleres**, hvis den blir obligatorisk:

> **`method-spec.md:345-346`** (§7.1)
> - Loading the IR projection from a bundle is FAIL-FAST: a missing file raises (required
>   input — contrast the tolerant inbox, §5).

**Klassifisering:** ekte hull, men det eneste punktet i køen som (hvis ubetinget) **endrer
fasit-bundelen** og ikke bare prosa. **Operatør-spørsmålet:** obligatorisk for alle kjøringer
(→ fixture-endring + §7-setningen må omskrives), eller opsjonell med fail-fast-semantikk kun
når den finnes (→ ren prosa-utvidelse, fasiten uendret)?

---

## 5. S3.5 / D-F — tittel-whitespace

**Seksjoner:** `ingest-spec.md` §4 (`:125`), §5 (`:149-161`), §6 (`:194-197`), §11 (`:278`),
§12 (`:301`).

> **`ingest-spec.md:125`** (§4, extraction-tabellen)
> | `title` | Human-readable title; … Single-line, and MUST NOT contain `[` or `]` … Validated
> fail-fast at manifest load — rendered verbatim thereafter (§5, §6). |

> **`ingest-spec.md:158-161`** (§5, frontmatter-kulepunktet)
> … All values MUST be single-line; `title` is emitted **verbatim** (it is `[`/`]`-free by §4,
> so verbatim rendering is safe — the invariant is met by validation, not repair); the
> materializer MUST collapse whitespace runs (including newlines) in `source_query` to single
> spaces.

Formen på hullet, presist: **collapse er scoped til `source_query` alene**, og `title` er
uttrykkelig `verbatim` med invarianten «met by validation, not repair». En tittel med interne
whitespace-runs er derfor ikke normalisert noe sted — den er bare «single-line», og hva
`single-line`-valideringen dekker (bare `\n`? `\r`? ledende/etterfølgende blanke?) står ikke.
Amendment-punktet ligger i den sømmen, og valget er **validere hardere** vs. **reparere** —
teksten har i dag valgt validering for `title` og reparasjon for `source_query`.

**⚠ Anker-avvik oppstrøms (viktig for denne teksten spesielt).** `portfolio-optimiser` ankret
sitatet til `shared/ingest-spec.md:140`. Det linjenummeret er commons ved **`7aa53fc`**, ikke
HEAD:

- ved `7aa53fc`, linje 140: `` `generated`. All values MUST be single-line; the materializer MUST collapse whitespace runs ``
- ved HEAD (`bfa5a9b`): samme setning er splittet over `:158` og `:160-161`, og `title is
  emitted verbatim` + «validation, not repair» er **ny tekst** fra `bfa5a9b`.

`bfa5a9b` (+39/−9) skrev om nettopp dette kulepunktet OG `title`-raden i §4 (som gikk fra
bare «Single-line.» til dagens `[`/`]`-forbud + fail-fast + verbatim). Deres `shared/`-kopi
ser altså ut til å ligge ett commons-commit bak, fra FØR D1-stempelmodellen landet. Det
betyr at S3.5 kan være formulert mot tekst som ikke lenger finnes i den formen — og det er
samme risiko de selv navnga («pullen må være koordinert, samme commons-commit»). **Meldt
oppstrøms.**

**Klassifisering:** ekte, men smal søm. Ingen fasit-effekt her (våre fixtures har ingen
ingest-manifester; goldenbundlene for ingest bor i implementasjonene, jf. §11 `:259-261`).

---

## 6. D-A#5 — projeksjoner over besparelses-hovedboken (INGEN eksisterende tekst)

**Målt:** `grep -ci 'ledger'` og `grep -ci 'hovedbok'` over `method-spec.md` +
`ingest-spec.md` → **0 og 0**. Ingen monetær avrundingsregel finnes heller: alle 13
forekomster av `round` (12 linjer: 9 i method-spec, 3 i ingest-spec) er andre ting
(`round-capped` debatt `:141`/`:386`, `max_rounds` `:378`/`:385`, `shortest round-trip
decimal` `ingest-spec.md:165`, `round-trip` `ingest-spec.md:85`, `around` `:323`).

Nærmeste eksisterende flater, som en ny kontrakt må forholde seg til uten å kollidere:

- **`method-spec.md:367-372`** (§7.2 `learning_surface`) — de monetære feltene som ER frosset
  (`modelled_saving_nok`, `expected_actual_saving_nok`, intern konsistens påkrevd).
- **`method-spec.md:199-202`** (§3 Steg 6) — råresultater er output-laget, «plain JSON», og
  bruker bevisst IKKE wiki-formatet.
- **`method-spec.md:250-252`** (§4.2) — `claimed_saving_nok` som tall i verdict-kontrakten,
  og `description` bevisst utenfor likhet/minting.
- **`method-spec.md:436-464`** (§12) — kryssjekk-tabellen er *fullstendighets-håndhevet* av
  spec-integritetstesten (§11 `:434`), så en ny kontrakt med nye felter MÅ inn her, ellers
  feiler den testen. Dette er den mekaniske konsekvensen ingen av oppstrøms-meldingene nevner.

**Klassifisering:** ny seksjon, ikke en amendment. Dette er køens største punkt (den eneste
som utvider spec-ens virkeområde) og samtidig den uten story-etikett oppstrøms — mest utsatt
for å falle mellom de to enumerasjonene. **Meldt oppstrøms.**

**Note, videreformidlet ikke verifisert her:** `portfolio-optimiser` melder (16:11Z, pkt. 4)
at forslagets A5-regel 1 («Monetary figures MUST NOT be rounded in the projection») treffer
en persisterings-kant hos dem (NOK→øre-kvantisering) og bør skille projeksjons-aritmetikk fra
enhets-kvantisering. Commons har ikke lest deres kode og fører det som deres måling, ikke som
vårt faktum.

---

## 7. S2.2–2.4 / D-B — substansen er ikke ankret hos commons

Punktet er kjent bare som etikett. Vi leste det ut av `portfolio-optimiser`s STATE
(GATES-blokk) 2026-07-25 04:05Z og har aldri fått innholdet. `grep -rn 'D-B'` over dette
repoet gir **0 treff** — heller ikke i vår egen STATE, som bare bærer story-etiketten
`S2.2-2.4`. Koblingen `S2.2–2.4 (D-B)` finnes utelukkende i coord-arkivet
(`20260725T040535Z`, vår egen melding), ikke i noen commons-tekst.

Commons kan derfor ikke si hvilken seksjon det rører. **Ingen antakelse føres.** Dette er den
ene raden i underlaget som er blank av en grunn — og den blir stående blank til substansen
kommer. **Etterspurt oppstrøms.**

---

## 8. B1 — nav-golden-klassen (utenfor pakken, commons-eid)

Ankret, etter å ha vært et etikett-punkt i tre uker. `llm-ingestion-okf` svarte
`portfolio-optimiser` 2026-07-25 04:19Z at «B1 bundle class» ikke finnes hos dem, og at
beskrivelsen matcher **D4 fra OKF-runden, ratifisert i trinn F 2026-07-21**: commons eier
nav-golden-bundleklassen + forventet utfall og leverer den inn; catalog eier
korpus-containeren, de adversarielle aksene og runner/gate.

**Commons-halvdelen er levert** (`b641741`, 2026-07-21):

| Case | Innhold |
|---|---|
| `examples/nav-golden-escape/` | `bundle/`, `expected-read-context.md`, `README.md`, `SHOULD-NOT-BE-READ.md` |
| `examples/nav-golden-hierarchy/` | `bundle/` (nestet `a/b/`, `c/orphan.md`), `expected-read-context.md`, `README.md` |

**Det åpne spørsmålet er ett, og det er vårt:** `grep -rn 'nav-golden' *.md` → **0 treff**.
Klassen er levert som fixture, men ingen normativ seksjon peker på den — i motsetning til
`validator-input.json` / `golden.json` (navngitt i §7 `:330-346`) og
`examples/ingest-golden-{source type}/` (navngitt som konvensjon i `ingest-spec.md:259-261`).
§11-raden «Navigation boundary» (`:425`) beskriver rød-betingelsen, men nevner ikke fixturene
som beviser den.

**Operatør-spørsmålet:** skal nav-golden-klassen få en normativ referanse (§7 ground truth
og/eller §11-raden), eller forbli en informativ fixture? Dette er commons' eget punkt, ingen
venter på oss, og det hører IKKE inn i oppstrøms-pakken.

---

## 9. Sammendrag

| # | Punkt | Fil + seksjoner | Klassifisering | Fasit-effekt |
|---|---|---|---|---|
| 1 | S2.7 / D-A#1 nominal gate + IR-band | method §3.4 `:157-166`, §7.1 `:339-346`, §7.2 `:352-358` | ekte hull | ingen (målt) |
| 2 | S3.2 / D-A#4 seed-nøkkel | method §3.1 `:108-114` | ekte hull | ingen (fasiten skiller ikke) |
| 3 | D-A#3 ledende `/` | method §3.1 `:67-71`, §11 `:425` | **allerede normativt** | — |
| 4 | S4.0 / D-A#2 kostbaseline | method §7 `:332-333`, §7.1 `:345-346` | ekte hull | **endrer fasit hvis ubetinget** |
| 5 | S3.5 / D-F tittel-whitespace | ingest §4 `:125`, §5 `:158-161`, §6 `:194-197`, §11 `:278` | ekte, smal søm | ingen |
| 6 | D-A#5 hovedbok-projeksjoner | ingen tekst; naboer method §7.2 `:367-372`, §12 `:436-464` | **ny seksjon** | ingen direkte; §12 må utvides |
| 7 | S2.2–2.4 / D-B | ukjent | **ikke ankret** | ukjent |
| 8 | B1 / D4 nav-golden | levert `b641741`; 0 spec-referanser | commons-eget, utenfor pakken | — |

Commons' rolle er uendret: vi forbereder underlaget, operatøren ratifiserer, og frossen tekst
endres ikke uten den ratifiseringen.

---

## Verifiseringslogg

| Påstand | Sjekk | Resultat |
|---|---|---|
| Spec-tekst uendret siden 2026-07-21 | `git log -- method-spec.md ingest-spec.md` | `9801d35` / `bfa5a9b`, begge 07-21 |
| Bare p90 blokkerer i dag | lest `method-spec.md:150-166` i sin helhet | punkt 2 «capped», punkt 4 eneste blokk |
| Ingen `low ≤ unit_cost ≤ high`-invariant | lest §7.1 `:339-346` | én invariant, om claimed vs. total |
| Nominal gate er byte-nøytral | `golden.json`: claimed `30000` ≤ nominal `90000.0` | `validates` uendret `true` |
| IR-band-invarianten er alt oppfylt i fasit | `validator-input.json`: `1.0` ∈ `[0.70, 1.40]` | ingen fixture-endring |
| Seeding nøkles på bundelens projeksjon | lest `:108-114` | «keyed on those candidate features» |
| Ledende `/` alt normativt | `git log -S'denotes the **bundle root**'` | `9801d35`, 2026-07-21 |
| §11 har alt rød-betingelsen | `method-spec.md:425` | «bundle-root `/` read as filesystem-absolute» |
| Ingen hovedbok-/baseline-tekst | `grep -ci ledger\|hovedbok\|cost-baseline` | 0 / 0 / 0 |
| Ingen monetær avrundingsregel | `grep -n round` begge spec-er, alle 18 treff lest | alle urelaterte |
| Fasit-bundelen har to JSON-filer | `ls examples/bygg-energi-mikro/` | `validator-input.json`, `golden.json` |
| Oppstrøms-anker `:140` er stale | `git show 7aa53fc:ingest-spec.md \| grep -n` | treff på `:140` ved `7aa53fc`, `:158/:160` ved HEAD |
| `bfa5a9b` rørte nettopp den teksten | `git show bfa5a9b -- ingest-spec.md` | +39/−9; §5-kulepunkt + §4 `title`-rad omskrevet |
| Multi-manifest er extension point | `ingest-spec.md:173-174` | «Version 1 assumes ONE manifest per bundle» |
| B1 = D4, ikke okf-eid | `~/.claude/coord/portfolio-optimiser/archive/20260725T041948Z-*` | okf: «never owned here; it is D4» |
| nav-golden levert | `git log -- examples/nav-golden-*` | `b641741`, 2026-07-21 |
| nav-golden ikke normativt referert | `grep -rn 'nav-golden' *.md` | 0 treff |
| D-B ikke ankret hos commons | `grep -rn 'D-B'` | 0 treff utenfor STATE |