open/portfolio-optimiser
1
0
Fork 0
Code Issues Releases 4 Activity

refactor(examples): replace sector-specific example material with generic, fictitious examples

Browse source 
The context sets, the packaged knowledge bases and the example bundles are
replaced by one fictitious example set about IT operations in an invented
organisation: three context sets (serverrom-2027, driftsavtale-2027 and the
two-base drift-og-avtale-2027), two synthetic knowledge bases under
src/portfolio_optimiser/data/kunnskapsbaser and two example bundles under
src/portfolio_optimiser/data/bundles. Numbers, codes and structural values in
tests and fixtures are kept; names, ids and wording change. Dated measurement
documents that only recorded runs on the replaced material are deleted.

Gate figures measured on the new set are not comparable with earlier ones.
The exclusion gate from the previous commit is green: 0 tracked files hit
outside the shared/ subtree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-23 15:04:21 +02:00
commit 37547fe292
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
1147 changed files with 24138 additions and 9503 deletions
Download patch file Download diff file Expand all files Collapse all files

229
docs/kunnskapsbase-for-en-kjoring.md
View file

@ -32,7 +32,7 @@ Tre dokumenter står rundt dette:
| Kategori | Følger | Hvem eier den |
|---|---|---|
| **Prosjektlaget** | prosjektet / anlegget | prosjekteier og driftsorganisasjon |
| **Faglaget** | fagområdet (veglys, tunnel, bygg …) | fagmiljøet |
| **Faglaget** | fagområdet (klientpark, kjøling, bygg …) | fagmiljøet |
| **Erfaringslaget** | organisasjonen, over tid | fagekspertene som avgir dommer |
| **Kjøringslaget** | denne ene bestillingen | bestilleren |
@ -47,10 +47,10 @@ den i, hva loopen bruker den til, og hva som skjer hvis den mangler. Den viktigs
**`cost-baseline.json`**: mangler den, starter kjøringen uten et ord — og validatoren dømmer da bare
mot tall forslaget selv oppga (VERIFISERT ved kjøring, [§4.1](#41-den-skarpeste-mangelen-cost-baselinejson)).
**3. Hvordan ser det ut for et veiprosjekt?** [§5](#5-veiprosjektet-fylkesveg-sør-fra-bestilling-til-kjøreklar-base)
går gjennom en veglysportefølje langs fylkesveg, fra oppdragsfila til en base som består
kjøreklar-sjekken. Basen det ender i finnes og kjører (VERIFISERT: `shared/examples/veglys-fv-soer/`
er den demoen bruker).
**3. Hvordan ser det ut for et konkret prosjekt?** [§5](#5-klientparken-hos-eksempelvirksomheten-fra-bestilling-til-kjøreklar-base)
går gjennom klientparken til den oppdiktede Eksempelvirksomheten, fra oppdragsfila til en
kjøreklar base. Basen det ender i er sjekket inn (VERIFISERT:
`src/portfolio_optimiser/data/bundles/klientpark-energi/`, den leverte basen demoen leser).
## 1. Hva kjøringen leser, og hvorfor det avgjør hva basen må inneholde
@ -86,7 +86,7 @@ nekter kjøringen å starte (VERIFISERT ved kjøring, [§4.1](#41-den-skarpeste-
`cost-baseline.json` er valgfri, og det er nettopp problemet: uten den starter kjøringen som om alt
var i orden.
**Målt på veglys-basen:** mappa har 9 filer. Én er `index.md`, én er dommen, to er tallfiler —
**Målt på klientpark-basen:** mappa har 9 filer. Én er `index.md`, én er dommen, to er tallfiler —
og **5** er det kjøringen faktisk navigerer inn som kontekst (VERIFISERT:
`tests/golden/demo-transcript.stdout` linje 13, «navigerte konseptfiler (5)»).
@ -112,28 +112,30 @@ og **5** er det kjøringen faktisk navigerer inn som kontekst (VERIFISERT:
**Deles metode- og litteraturlaget på tvers?** Svaret er todelt, og begge halvdeler er målt.
*Logisk* er det samme fagstoff: alle tre eksempelbasene (kontorbygg, veglys, tunnel) bærer en
`metode-ipmvp-a.md` og en `kilder-*.md`, og alle tre bygger på samme M&V-rammeverk (IPMVP Option
A). *Fysisk* er det tre ulike filer: 40, 81 og 98 linjer, med hver sin tittel — «for veglys — og
hvorfor de andre opsjonene er stengt», «for tunnelstyring — anlegget måler inngangssignalet, ikke
energien» (VERIFISERT: `wc -l` + `diff` over de tre). Begge veiprosjekt-basene sier det selv i
`index.md`: «metode- og kildelaget er **materialisert inn her**, ikke lenket på tvers av bundler».
*Logisk* er det samme fagstoff: alle tre eksempelbasene (kontorbygg, klientpark, kjøling i
driftssenteret) bærer en `metode-ipmvp-a.md`, og alle tre bygger på samme M&V-rammeverk (IPMVP
Option A). *Fysisk* er det tre ulike filer — målt 2026-08-21 til 40, 81 og 98 linjer — med hver
sin tittel: «for klientparken — og hvorfor de andre opsjonene er stengt», «for kjølestyring —
anlegget måler inngangssignalet, ikke energien» (VERIFISERT: `wc -l` + `diff` over de tre). Begge
de leverte eksempelbasene sier det selv i `index.md`: «metode- og kildelaget er **materialisert
inn her**, ikke lenket på tvers av bundler».
Grunnen er teknisk og ufravikelig: navigasjonen følger aldri en lenke ut av basen
([§1](#1-hva-kjøringen-leser-og-hvorfor-det-avgjør-hva-basen-må-inneholde)). Men det er også
faglig riktig: metoden *for veglys* er ikke metoden *for tunnel*. I veglys er ex-post stengt fordi
anlegget mangler måler; i tunnel er ex-ante stengt fordi anlegget ble bygget før noen målte
(VERIFISERT: de to `index.md`-filene). En delt fil ville måttet si begge deler og dermed ingen av
faglig riktig: metoden *for klientparken* er ikke metoden *for kjøleanlegget*. I klientparken er
ex-post stengt fordi anlegget mangler måler; i kjøleanlegget er ex-ante stengt fordi anlegget ble
bygget før noen målte (VERIFISERT: de to `index.md`-filene). En delt fil ville måttet si begge deler og dermed ingen av
dem.
Praktisk betyr det (ANTATT, anbefaling): fagmiljøet eier en **mal** per fagområde; hver base får
en **tilpasset kopi**; når malen endres, er det en kjent jobb å gå gjennom kopiene. To kopier
drifter — det er prisen, og den skal være uttalt, ikke skjult.
**Prosjektlaget er det som byttes ut.** Begge veiprosjekt-basene er bygget med fiktivt prosjektlag
og ekte litteraturlag, og sier selv hvordan de er ment brukt: «en produksjons-deployer erstatter
prosjektlaget med en ekte kunnskapsbase og beholder litteraturlaget» (VERIFISERT: begge
`index.md`). Det er nøyaktig kategoriskillet over, skrevet fra eksemplenes side.
**Prosjektlaget er det som byttes ut per prosjekt.** Begge de leverte eksempelbasene er fiktive i
begge lag — prosjektet og kildene tilhører den oppdiktede Eksempelvirksomheten — og sier selv
hvordan de er ment brukt: «En produksjons-deployer erstatter begge lagene med en ekte
kunnskapsbase og ekte kilder» (VERIFISERT: begge `index.md`). Kategoriskillet over står likevel:
prosjektlaget skrives fra det ene prosjektets tall, litteraturlaget fra fagområdets kilder.
**Erfaringslaget er reservert.** Ingen automatisk kilde kan skrive en `type: verdict`-fil inn i
basen; den eneste veien dit er en promotering av en dom et menneske har godkjent, eller en
@ -166,7 +168,7 @@ første avgjør om kjøringen i det hele tatt kan starte.
Svaret blir prosjekt-ID-en. Den må være identisk tre steder — kommandolinjen,
`validator-input.json` og `cost-baseline.json` — ellers nektes kjøringen (VERIFISERT:
`run.py` `_project_from_bundle`, «bundle project_id … != requested»). Velg en ID uten mellomrom og
æøå; eksemplene bruker formen `VEGLYS-FV-SOER` (KONVENSJON).
æøå; eksemplene bruker formen `KLIENTPARK-ENERGI` (KONVENSJON).
*Hvis svaret er «flere anlegg»:* én base per prosjekt. En portefølje er flere baser, kjørt i
porteføljemodus.
@ -196,33 +198,33 @@ fortsatt den ene projiserte kandidaten — se
**4. Hvilke harde rammer gjelder?**
Minstekrav som setter et gulv ingen besparelse kan gå under, ting som ikke kan endres, budsjett-
og anskaffelsesrammer. Svaret skrives inn i `type: project`-fila. Veglys-eksempelet har fire:
lystekniske minstekrav, vedlikeholdsfaktoren, at nattslukking ikke kan antas, og at tiltak
vurderes inne i porteføljen (VERIFISERT: `shared/examples/veglys-fv-soer/veglys-fv-soer.md`,
«Rammer»). Agentene leser dem som tekst; koden håndhever dem ikke (ANTATT: det følger av at
og anskaffelsesrammer. Svaret skrives inn i `type: project`-fila. Klientpark-eksempelet har fire
som begrenser tiltakene: ytelseskravene, ytelsesreserven, at nattlig avstenging ikke kan antas,
og at tiltak vurderes inne i porteføljen (VERIFISERT:
`src/portfolio_optimiser/data/bundles/klientpark-energi/klientpark-energi.md`, «Rammer»). Agentene leser dem som tekst; koden håndhever dem ikke (ANTATT: det følger av at
koden bare leser `title` fra fila, men er ikke målt mot en levende modell).
**5. Hvilke tilnærminger vil du ha vurdert, og hvorfor?**
Svaret blir oppdragsfila — se [bestille-en-kjoring.md](bestille-en-kjoring.md). `description`-feltet
mates ordrett inn til modellen; det er der fagkunnskapen om *hvorfor* tiltaket er verdt å prøve
gjør en forskjell. Hver tilnærming bør ha et motstykke i basen: en `type: hypothesis`-fil med
parametere, modellert besparelse og kjent usikkerhet (KONVENSJON: begge veiprosjekt-basene har
én hypothesis-fil per kandidat-tiltak; koden krever det ikke).
parametere, modellert besparelse og kjent usikkerhet (KONVENSJON: begge de leverte eksempelbasene
har én hypothesis-fil per kandidat-tiltak; koden krever det ikke).
**6. Hvordan måles og verifiseres en besparelse i dette faget?**
Svaret blir `type: methodology`-fila. Den forteller agentene *hvorfor* modellert og faktisk
besparelse kan sprike, og hvilken måleopsjon som er åpen for dette anlegget. For veglys er svaret
«IPMVP Option A, ved eliminasjon» fordi anlegget mangler måler (VERIFISERT: veglys
besparelse kan sprike, og hvilken måleopsjon som er åpen for dette anlegget. For klientparken er
svaret «IPMVP Option A, ved eliminasjon» fordi anlegget mangler måler (VERIFISERT: klientparkens
`metode-ipmvp-a.md`).
*Hvis fagmiljøet har en mal:* kopier og tilpass. Tilpasningen er ikke pynt — den delen som
forklarer hvilke opsjoner som er *stengt for dette anlegget* er prosjektspesifikk.
**7. Hva vet litteraturen om gapet mellom modellert og faktisk besparelse her?**
Svaret blir `type: reference`-fila. Skill skarpt mellom det som er målt i vårt eget land/regime
og det som er lånt fra andre program — veglys-eksempelet deler fila i «Del A — norsk materiale»
og «Del B — lånt materiale», og sier hvorfor: «Å blande de to ville gjort et lånt tall til en
norsk måling» (VERIFISERT: `kilder-veglys-realisering.md`).
*Hvis svaret er «det finnes ingen norsk måling»:* skriv det. Et navngitt evidenshull er innhold;
Svaret blir `type: reference`-fila. Skill skarpt mellom det som er målt på eget anlegg og det
som er lånt fra andre program — klientpark-eksempelet deler fila i «Del A — materiale om
klientparken» og «Del B — lånt materiale», og sier hvorfor: «Å blande de to ville gjort et lånt
tall til en måling av klientparken» (VERIFISERT: `kilder-klientpark-realisering.md`).
*Hvis svaret er «det finnes ingen måling på eget anlegg»:* skriv det. Et navngitt evidenshull er innhold;
et oppdiktet tall er forurensning.
**8. Finnes det tidligere erfaring med lignende tiltak — en dom noen faktisk har avgitt?**
@ -291,7 +293,8 @@ Fila forankrer gaten i prosjektets ekte kostlinjer: hvert forslag avstemmes mot
eller enhetspris utenfor 5 % av baselinens verdi (VERIFISERT: `validator.py:154-190`, `:210-214`).
Men fila er **valgfri** på bundle-stien, og fraværet er stille. Målt 2026-08-21 med
`--live-dry-run` på fire kopier av veglys-basen, samme kommando, samme oppdragsfil:
`--live-dry-run` på fire kopier av den forrige eksempelbasen (samme filsett som klientpark-basen
i §5), samme kommando, samme oppdragsfil:
| Variant | Utfall | rc | Melding |
|---|---|---|---|
@ -315,7 +318,7 @@ stammer fra den *samme* oppslagsverdien inne i kjøringen — ikke fra en ny les
skrevet av tørrkjøringen, av den fulle enkeltkjøringen og per prosjekt i porteføljemodus. Er
basen forankret, skrives **ingen linje i det hele tatt** — en linje for noe kjøringen ikke har
utelates, samme regel som resten av kunngjøringen følger (VERIFISERT: kjørt 2026-08-21 mot to
kopier av veglys-basen; intakt kopi er byte-uendret, kopi uten fila bærer linja).
kopier av den forrige eksempelbasen; intakt kopi er byte-uendret, kopi uten fila bærer linja).
Ankeringen er fortsatt **valgfri** — en base skrevet før fila fantes kjører uendret. Dette er
synlighet, ikke en ny nekt. Demoen har sin egen, norske formulering
@ -328,74 +331,80 @@ er det eneste spørsmålet der et «vet ikke» ikke stopper noe — og derfor de
dokumenteres utenfor systemet. En base uten `cost-baseline.json` bør ikke kalles kjøreklar av
noen som vet hva fila gjør (ANTATT: en arbeidsregel; koden lar deg kjøre).
## 5. Veiprosjektet Fylkesveg Sør: fra bestilling til kjøreklar base
## 5. Klientparken hos Eksempelvirksomheten: fra bestilling til kjøreklar base
Eksempelet følger en veglysportefølje langs fylkesveg. Basen det ender i er
`shared/examples/veglys-fv-soer/`, som er sjekket inn, kjører i demoen og er målt med
kjøreklar-sjekken under. Prosjektlaget i den basen er **fiktivt** — porteføljen finnes ikke —
mens litteraturlaget er ekte og kildebelagt (VERIFISERT: basens `index.md`). Det gjør den til et
godt eksempel på nøyaktig det skillet [§2](#2-kategoriene-hva-følger-hva) handler om: et ekte
prosjekt bytter ut prosjektlaget og beholder resten.
Eksempelet følger klientparken — 9 500 stasjonære arbeidsstasjoner — i den oppdiktede
Eksempelvirksomheten. Basen det ender i er `src/portfolio_optimiser/data/bundles/klientpark-energi/`, som er
sjekket inn og er den leverte basen demoen leser. Både prosjektlaget og litteraturlaget er
**fiktive** — porteføljen og kildene finnes ikke (VERIFISERT: basens `index.md`). Skillet
[§2](#2-kategoriene-hva-følger-hva) handler om er likevel synlig i den: prosjektlaget er skrevet
fra porteføljens egne tall, litteraturlaget fra fagområdets kilder, og et ekte prosjekt bytter ut
prosjektlaget.
> **Om målingene i dette kapitlet.** Kjøreklar-sjekken og tørrkjøringene i §4.1 ble målt
> 2026-08-21 på den forrige eksempelbasen, som hadde samme filsett, samme kostlinje og samme tall.
> Basen er siden skrevet om til klientpark-eksempelet; navnene i utskriftene under er byttet til
> eksempelets, og målingene er **ikke** gjentatt på den omskrevne basen.
### 5.1 Bestillingen
En driftsleder i fylkeskommunen vil vite hva LED-utskifting gir på de eldste strekningene, og om
styring oppå det er verdt noe. Oppdragsfila (VERIFISERT: akseptert av kjøringen, kunngjøringen
under er dens faktiske utskrift):
En driftsleder i IT-driftsavdelingen vil vite hva utskifting gir på de eldste maskinene, og om
strømstyring oppå det er verdt noe. Oppdragsfila (VERIFISERT 2026-08-21: en oppdragsfil med samme
form ble akseptert av kjøringen, og kunngjøringen under er dens utskrift, med eksempelets navn):
```json
{
"objective": "Redusere energikostnaden i veglysporteføljen Fylkesveg Sør uten å gå under lystekniske minstekrav, med tiltak som kan bestilles i 2027.",
"objective": "Redusere energikostnaden i klientparken til Eksempelvirksomheten uten å gå under ytelseskravene, med tiltak som kan bestilles i 2027.",
"approaches": [
{
"id": "led-trinn-1",
"label": "LED-utskifting av de 2 500 eldste HPS-punktene",
"description": "Drift melder at armaturene på de eldste strekningene er fra før 2005 og byttes hyppig; vi vil vite hva ren armaturutskifting gir før styring vurderes."
"id": "pc-trinn-1",
"label": "Utskifting av de 2 500 eldste stasjonære PC-ene",
"description": "Drift melder at maskinene på de eldste kontorene er fra før 2015 og byttes hyppig; vi vil vite hva ren maskinutskifting gir før strømstyring vurderes."
},
{
"id": "adaptiv-styring",
"label": "Adaptiv styring på de LED-utskiftede punktene",
"description": "Håndbok V124 tillater MF 0,85; vi tror nye anlegg overdimensjoneres og at marginen kan hentes ut med dimming, men har ingen måling."
"id": "adaptiv-stromstyring",
"label": "Adaptiv strømstyring på de utskiftede maskinene",
"description": "IT-driftshåndboken tillater RF 0,85; vi tror nye maskiner overdimensjoneres og at marginen kan hentes ut med strømsparing, men har ingen måling."
}
],
"allow_own_proposals": true,
"success_criteria": "Minst ett tiltak som passerer validatoren og som driftsavdelingen kan stå inne for."
"success_criteria": "Minst ett tiltak som passerer validatoren og som IT-driftsavdelingen kan stå inne for."
}
```
Bestillingen er den første målingen av basen: hver tilnærming nevner ting basen må kunne svare
på — armaturalder, vedlikeholdsfaktor, lystekniske minstekrav, fravær av måling.
på — maskinalder, ytelsesreserve, ytelseskrav, fravær av måling.
### 5.2 Spørsmålene, besvart for dette prosjektet
| # | Spørsmål | Svar for Fylkesveg Sør | Lander i |
| # | Spørsmål | Svar for klientparken | Lander i |
|---|---|---|---|
| 1 | Prosjekt-ID | `VEGLYS-FV-SOER` — samme streng på kommandolinjen og i begge tallfiler | alle tre |
| 2 | Kostlinjer med ekte tall | én linje: porteføljens årlige energikostnad, `ENERGI-VEGLYS-EL`, 4 386 150 kWh à 1,00 NOK. Investeringskostnad **bevisst utelatt** — ingen kilde gir NOK per lyspunkt | `cost-baseline.json` |
| 3 | Den ene projiserte kandidaten | LED-utskifting trinn 1 (2 500 punkter, 114 → 70 W), modellert 445 500 NOK/år | `validator-input.json` |
| 4 | Harde rammer | lystekniske minstekrav (1,0 cd/m², 5 lx), MF ≤ 0,85, nattslukking kan ikke antas, tiltak vurderes inne i porteføljen | `veglys-fv-soer.md` |
| 1 | Prosjekt-ID | `KLIENTPARK-ENERGI` — samme streng på kommandolinjen og i begge tallfiler | alle tre |
| 2 | Kostlinjer med ekte tall | én linje: porteføljens årlige energikostnad, `ENERGI-KLIENTPARK-EL`, 4 386 150 kWh à 1,00 NOK. Investeringskostnad **bevisst utelatt** — ingen kilde gir NOK per arbeidsstasjon | `cost-baseline.json` |
| 3 | Den ene projiserte kandidaten | PC-utskifting trinn 1 (2 500 maskiner, 114 → 70 W), modellert 445 500 NOK/år | `validator-input.json` |
| 4 | Harde rammer | ytelseskrav (1,0 s responstid, 5 samtidige applikasjoner), RF ≤ 0,85, nattlig avstenging kan ikke antas, tiltak vurderes inne i porteføljen | `klientpark-energi.md` |
| 5 | Tilnærminger | de to i oppdragsfila, pluss systemets egne | oppdragsfila + to `hypothesis`-filer |
| 6 | Målemetode | IPMVP Option A, ved eliminasjon: umålt anlegg stenger B, C og D | `metode-ipmvp-a.md` |
| 7 | Litteratur om gapet | norsk: baseline, regelverk og *årsaken* til at gapet ikke kan ses (mangler måler). Lånt: selve realiseringsgraden (amerikansk programlitteratur, 0,81) | `kilder-veglys-realisering.md` |
| 8 | Tidligere erfaring | én frø-dom: godkjent med realiseringskorreksjon, rate 0,81, **merket som lån** | `verdict-veglys-fro.md` |
| 7 | Litteratur om gapet | om klientparken: baseline, normankere og *årsaken* til at gapet ikke kan ses (mangler måler). Lånt: selve realiseringsgraden (virksomhetens etterevalueringer av et annet program, 0,81) | `kilder-klientpark-realisering.md` |
| 8 | Tidligere erfaring | én frø-dom: godkjent med realiseringskorreksjon, rate 0,81, **merket som lån** | `verdict-klientpark-fro.md` |
| 9 | Avgrensning til kostakse | nei — porteføljen har én kostlinje | — |
| 10 | Kilder som data | nei — anleggsregisteret er levert som tall i et notat; alt er håndkuratert | — |
| 11 | Hvem dømmer | fylkets egen energirådgiver, etter kjøringen, via innboksen | `--verdict-dir` |
| 10 | Kilder som data | nei — utstyrsregisteret er levert som tall i et notat; alt er håndkuratert | — |
| 11 | Hvem dømmer | virksomhetens egen energirådgiver, etter kjøringen, via innboksen | `--verdict-dir` |
(Alle svar i kolonnen «Svar» er VERIFISERT mot filene i `shared/examples/veglys-fv-soer/`; kolonnen
(Alle svar i kolonnen «Svar» er VERIFISERT mot filene i `src/portfolio_optimiser/data/bundles/klientpark-energi/`; kolonnen
«Lander i» er VERIFISERT mot filnavnene der.)
### 5.3 Hva fagpersonene leverer
| Leveranse | Fra | Form de leverer i | Blir til |
|---|---|---|---|
| Anleggsregister: antall lyspunkter, armaturtype, installert effekt | drift | uttrekk fra anleggsdatabasen, regneark | `type: project` (energibaseline) + raden i `cost-baseline.json` |
| Brenntimer og energipris | drift / økonomi | tabellverdi (Håndbok V124) + fakturagrunnlag | samme; prisbåndet i `validator-input.json` |
| Kravgrunnlag: lystekniske minstekrav, vedlikeholdsfaktor | fagmiljø vegbelysning | henvisning til NMFV og Håndbok V124 | «Rammer» i `type: project` |
| Kandidat-tiltak med parametere | drift + fagmiljø | notat: før/etter-effekt, antall, hva som er utledet | to `type: hypothesis`-filer |
| Utstyrsregister: antall arbeidsstasjoner, modell, installert effekt | IT-drift | uttrekk fra utstyrsdatabasen, regneark | `type: project` (energibaseline) + raden i `cost-baseline.json` |
| Driftstimer og energipris | IT-drift / økonomi | tabellverdi (IT-driftshåndboken) + fakturagrunnlag | samme; prisbåndet i `validator-input.json` |
| Kravgrunnlag: ytelseskrav, ytelsesreserve | fagmiljø arbeidsflate | henvisning til innkjøpsspesifikasjonen og IT-driftshåndboken | «Rammer» i `type: project` |
| Kandidat-tiltak med parametere | IT-drift + fagmiljø | notat: før/etter-effekt, antall, hva som er utledet | to `type: hypothesis`-filer |
| M&V-praksis for umålte anlegg | fagmiljø | mal for IPMVP, tilpasset | `type: methodology` |
| Litteratur om realiseringsgap, med kilde | fagmiljø | kildeliste med URL og årstall, merket norsk/lånt | `type: reference` |
| Tidligere vurdering av LED på småveg | energirådgiver | kort notat: «forvent ~80 % av modellert, fordi …» | `type: verdict` (frø) |
| Litteratur om realiseringsgap, med kilde | fagmiljø | kildeliste med URL og årstall, merket eget anlegg/lånt | `type: reference` |
| Tidligere vurdering av utskifting i en mindre klientpark | energirådgiver | kort notat: «forvent ~80 % av modellert, fordi …» | `type: verdict` (frø) |
Leveranseformene er ANTATT — de er det en slik leveranse rimelig ser ut som, ikke noe
eksempelbasen dokumenterer. Det som er VERIFISERT er hva hver leveranse *blir til*.
@ -403,32 +412,32 @@ eksempelbasen dokumenterer. Det som er VERIFISERT er hva hver leveranse *blir ti
### 5.4 Basen som bygges
```
veglys-fv-soer/
klientpark-energi/
├── index.md type: index inngangen; lenker til alt under
├── veglys-fv-soer.md type: project porteføljen, energibaselinen, rammene
├── tiltak-led-utskifting.md type: hypothesis kandidat 1 — den som er projisert
├── tiltak-adaptiv-styring.md type: hypothesis kandidat 2 — svakere kildebelagt, og merket slik
├── klientpark-energi.md type: project porteføljen, energibaselinen, rammene
├── tiltak-pc-utskifting.md type: hypothesis kandidat 1 — den som er projisert
├── tiltak-adaptiv-stromstyring.md type: hypothesis kandidat 2 — svakere kildebelagt, og merket slik
├── metode-ipmvp-a.md type: methodology Option A, og hvorfor de andre er stengt
├── kilder-veglys-realisering.md type: reference Del A norsk / Del B lånt
├── verdict-veglys-fro.md type: verdict frø-dommen — holdes ute av lesekonteksten
├── kilder-klientpark-realisering.md type: reference Del A eget anlegg / Del B lånt
├── verdict-klientpark-fro.md type: verdict frø-dommen — holdes ute av lesekonteksten
├── validator-input.json den projiserte kandidaten
└── cost-baseline.json prosjektets ene kostlinje
```
(VERIFISERT: `ls shared/examples/veglys-fv-soer/` og `grep '^type:'` over filene.)
(VERIFISERT: `ls src/portfolio_optimiser/data/bundles/klientpark-energi/` og `grep '^type:'` over filene.)
`index.md` gjør to jobber i denne basen. Den første er navigasjon: seks lenker, én per fil, med
type og én setning hver. Den andre er å si høyt hva som er fiktivt og hva som er ekte, og
*hvorfor* domenet er valgt — at realiseringsgraden i norsk veglys er «strukturelt usynlig» fordi
*hvorfor* domenet er valgt — at realiseringsgraden i klientparken er «strukturelt usynlig» fordi
anlegget mangler måler. Begge deler går ordrett inn som det første agentene leser.
### 5.5 De to tallfilene — skrevet fra samme linje
Hele basens tallgrunnlag er én linje aritmetikk:
> 9 500 lyspunkter × 114 W × 4 050 t/år ÷ 1 000 = **4 386 150 kWh/år** à 1,00 NOK = 4 386 150 NOK/år
> 9 500 arbeidsstasjoner × 114 W × 4 050 t/år ÷ 1 000 = **4 386 150 kWh/år** à 1,00 NOK = 4 386 150 NOK/år
`cost-baseline.json` bærer den som `ENERGI-VEGLYS-EL: {quantity: 4386150, unit_cost: 1.0}`.
`cost-baseline.json` bærer den som `ENERGI-KLIENTPARK-EL: {quantity: 4386150, unit_cost: 1.0}`.
`validator-input.json` bærer **nøyaktig samme** kode, mengde og pris i `affected_items`, pluss den
modellerte besparelsen for trinn 1 (2 500 × 44 W × 4 050 t ÷ 1 000 = 445 500 kWh ≈ 445 500 NOK)
og prisbåndet 0,70–1,40 NOK/kWh til risikosimuleringen (VERIFISERT: begge filene). De to er ikke
@ -436,9 +445,9 @@ og prisbåndet 0,70–1,40 NOK/kWh til risikosimuleringen (VERIFISERT: begge fil
toleransen på 5 % skal lukkes: ved konstruksjon, ikke ved avstemming etterpå.
**Én beslutning i mappingen er verdt å lære av:** `affected_items` er *hele porteføljens*
energikostnad, ikke de 2 500 berørte punktenes eget forbruk. Hadde det vært det siste, ville
energikostnad, ikke de 2 500 berørte maskinenes eget forbruk. Hadde det vært det siste, ville
besparelsen vært 38,6 % av linjen — over validatorens 30 %-tak — og det riktige forslaget blitt
avvist av en gate som målte feil størrelse (VERIFISERT: `tiltak-led-utskifting.md`, «Mapping til
avvist av en gate som målte feil størrelse (VERIFISERT: `tiltak-pc-utskifting.md`, «Mapping til
validatoren»). Kostlinjen skal være den linjen tiltaket *virker på* i regnskapet.
### 5.6 Frø-dommen
@ -449,14 +458,15 @@ decision: approved_with_adjustment
realization_rate: 0.81
modelled_saving_nok: 445500
expected_actual_saving_nok: 360855
description: "… brenntimene er et nasjonalt tabellanslag, ikke en målt kurve, og anlegget
description: "… driftstimene er et internt tabellanslag, ikke en målt kurve, og klientparken
mangler måler — så avviket kan ikke oppdages i drift. Forventet faktisk besparelse settes til
81 % av modellert, lånt fra belysnings-programlitteratur og merket som lån. …"
provenance: "frø — AI-forfattet. Realiseringsgraden er LÅNT … Det finnes INGEN norsk ex-post-måling
for veglys. Erstattes av ekte HITL i produksjon."
81 % av modellert, lånt fra virksomhetens etterevalueringer av belysningsprogrammer og merket
som lån. …"
provenance: "frø — AI-forfattet, fiktiv virksomhet. Realiseringsgraden er LÅNT … Det finnes INGEN
ex-post-måling for klientparken. Erstattes av ekte HITL i produksjon."
```
(Utdrag; VERIFISERT: `verdict-veglys-fro.md`.) Det som når neste hypotese er `description` pluss
(Utdrag; VERIFISERT: `verdict-klientpark-fro.md`.) Det som når neste hypotese er `description` pluss
`[realiseringsgrad=0.81; forventet_faktisk_NOK=360855]` (VERIFISERT: `verdicts.py`
`_verdict_rationale`). `provenance`-feltet leses ikke av koden — men det er det som gjør at en
fagperson som åpner basen ser at dommen er et frø og raten et lån. I et ekte prosjekt erstattes
@ -469,25 +479,26 @@ Det finnes ingen egen «valider basen»-kommando
bestillingen på plass:
```bash
uv run python -m portfolio_optimiser.run VEGLYS-FV-SOER \
--docs-dir shared/examples/veglys-fv-soer \
--bundle-dir shared/examples/veglys-fv-soer \
uv run python -m portfolio_optimiser.run KLIENTPARK-ENERGI \
--docs-dir src/portfolio_optimiser/data/bundles/klientpark-energi \
--bundle-dir src/portfolio_optimiser/data/bundles/klientpark-energi \
--mandate oppdrag.json \
--live-dry-run
```
Målt 2026-08-21 (VERIFISERT, rc 0):
Målt 2026-08-21 på den forrige eksempelbasen (VERIFISERT, rc 0; navnene byttet til eksempelets,
se notisen øverst i §5):
```
Run mandate for VEGLYS-FV-SOER
Objective: Redusere energikostnaden i veglysporteføljen Fylkesveg Sør uten å gå under lystekniske minstekrav, med tiltak som kan bestilles i 2027.
Run mandate for KLIENTPARK-ENERGI
Objective: Redusere energikostnaden i klientparken til Eksempelvirksomheten uten å gå under ytelseskravene, med tiltak som kan bestilles i 2027.
Evaluates: 2 expert-proposed approach(es) + the system's own proposals
1. led-trinn-1 — LED-utskifting av de 2 500 eldste HPS-punktene
2. adaptiv-styring — Adaptiv styring på de LED-utskiftede punktene
1. pc-trinn-1 — Utskifting av de 2 500 eldste stasjonære PC-ene
2. adaptiv-stromstyring — Adaptiv strømstyring på de utskiftede maskinene
Stops at: 3 rounds / 100000 tokens
Contacts: no external services
Success: Minst ett tiltak som passerer validatoren og som driftsavdelingen kan stå inne for.
VEGLYS-FV-SOER: LIVE-DRY-RUN OK (profile=local, models={'proposer': 'qwen3:4b', 'checker': 'qwen3:4b'}, max_rounds=3, max_tokens=100000, top_k=3) — ingen modellkall gjort (stoppet før første debate.run)
Success: Minst ett tiltak som passerer validatoren og som IT-driftsavdelingen kan stå inne for.
KLIENTPARK-ENERGI: LIVE-DRY-RUN OK (profile=local, models={'proposer': 'qwen3:4b', 'checker': 'qwen3:4b'}, max_rounds=3, max_tokens=100000, top_k=3) — ingen modellkall gjort (stoppet før første debate.run)
```
**Hva `OK` beviser:** basen åpner — `index.md` finnes, `validator-input.json` finnes og bærer
@ -519,8 +530,8 @@ unåbar, og da finnes det ingen lenke å rapportere), eller at innholdet er godt
mappe.
**Det offline ende-til-ende-beviset på denne basen** er demoen:
`uv run python -m portfolio_optimiser.simulation`. Den kjører nøyaktig `veglys-fv-soer`, skriver
«KUNNSKAPSBASE: veglys-fv-soer — kostbaseline erklært (ENERGI-VEGLYS-EL 4386150 x 1)», navigerer
`uv run python -m portfolio_optimiser.simulation`. Den kjører nøyaktig `klientpark-energi`, skriver
«KUNNSKAPSBASE: klientpark-energi — kostbaseline erklært (ENERGI-KLIENTPARK-EL 4386150 x 1)», navigerer
de fem konseptfilene, og viser at en dom avgitt etter kjøring A når kjøring B (VERIFISERT:
`tests/golden/demo-transcript.stdout`, linjene 7, 13 og 50). Agent-svarene i demoen er
skriptede; den beviser dataflyten, ikke modellens dømmekraft.
@ -562,14 +573,14 @@ så dokumentet ikke lover mer enn det som kan leveres.
- **Uforankret kjøring er synlig, men ikke summert.** Feltet og linja finnes per kjøring
([§4.1](#41-den-skarpeste-mangelen-cost-baselinejson)); det finnes ingen rapport som teller opp
hvor mange kjøringer i et porteføljepass som gikk uforankret.
- **Eksempelbasene er ikke ekte prosjekter.** Prosjektlaget er fiktivt; realiseringsgraden i alle
tre frø-dommene er lånt fra utenlandsk programlitteratur fordi ingen norsk ex-post-måling
finnes (VERIFISERT: `provenance`-feltet i de tre dom-filene).
- **Eksempelbasene er ikke ekte prosjekter.** Prosjektlaget er fiktivt; realiseringsgraden i
frø-dommene er lånt fra andre program fordi ingen ex-post-måling av anlegget selv finnes
(VERIFISERT: `provenance`-feltet i dom-filene).
- **De fire innholdstypene er konvensjon**, ikke spesifikasjon
([§4](#4-innholdstypene)).
- **`docs/extending.md` er utdatert på ett punkt:** den sier at ingen eksempelbase shipper
`cost-baseline.json`. Det var sant da den ble skrevet (2026-08-05); begge veiprosjekt-basene har
fått fila siden (VERIFISERT: `ls`, begge datert 2026-08-09). Rettelsen er ikke gjort her, for
`cost-baseline.json`. Det var sant da den ble skrevet (2026-08-05); begge de leverte
eksempelbasene har fått fila siden (VERIFISERT: `ls`, begge datert 2026-08-09). Rettelsen er ikke gjort her, for
den hører hjemme i det dokumentet.
- **1–2 uker.** Oppskriften sier det, og ingenting i dette dokumentet korter det ned. Det som
står her er hva ukene skal brukes til.
@ -606,18 +617,18 @@ ikke fyrer der.
| Prosjektnavn leses fra `type: project`-filas `title`, ellers ID | samme | VERIFISERT |
| Steg 0 avviser ukjent kode og avvik > 5 % | `validator.py:154-190`; `BASELINE_TOLERANCE_DEFAULT = 0.05` | VERIFISERT |
| Manglende `cost-baseline.json` → `None` → steg 0 hoppes over | `okf.py:323-335`; `run.py:516`; `validator.py:213` | VERIFISERT |
| Fire tørrkjøringer: intakt rc 0 · uten IR rc 1 · uten baseline rc 0 uten melding · korrupt baseline rc 1 | kjørt 2026-08-21 på kopier i scratchpad, kommandoen i §5.7 | VERIFISERT |
| Fire tørrkjøringer: intakt rc 0 · uten IR rc 1 · uten baseline rc 0 uten melding · korrupt baseline rc 1 | kjørt 2026-08-21 på kopier av den forrige eksempelbasen i scratchpad, kommandoen i §5.7 | VERIFISERT |
| Ingen artefakt bærer forankret/uforankret | `grep baseline src/portfolio_optimiser/provenance.py src/portfolio_optimiser/outbox.py` — null treff | VERIFISERT |
| Demoen printer forankringsstatus | `simulation.py:791-802`; golden linje 7 | VERIFISERT |
| `--live-dry-run` navigerer basen og laster begge tallfiler før kuttet | `run.py:513-516` vs `:565-588` | VERIFISERT |
| `--docs-dir` påkrevd men ulest på bundle-stien | `run.py:513-530`, `:1504` | VERIFISERT |
| Demoen kjører `veglys-fv-soer`, navigerer 5 konseptfiler, henter 0 så 3 dommer | `tests/golden/demo-transcript.stdout` linjene 7, 13, 14, 50 | VERIFISERT |
| Demoen kjører `klientpark-energi`, navigerer 5 konseptfiler, henter 0 så 3 dommer | `tests/golden/demo-transcript.stdout` linjene 7, 13, 14, 50 | VERIFISERT |
| Frø-rationale = `description` + `[realiseringsgrad=…; forventet_faktisk_NOK=…]` | `verdicts.py` `_verdict_rationale` | VERIFISERT |
| Dom-nøkkel-trioen: alle tre felt eller ingen | `verdicts.py` `_features_from_verdict_frontmatter`; `README.md` | VERIFISERT |
| Veglys-tallene: 9 500 × 114 W × 4 050 t = 4 386 150 kWh; 445 500 NOK modellert; 10,2 % av total; 38,6 % av berørte punkter | `veglys-fv-soer.md`, `tiltak-led-utskifting.md`, begge JSON-filer | VERIFISERT |
| Frø-dommen: rate 0,81, forventet 360 855, lånt | `verdict-veglys-fro.md` frontmatter | VERIFISERT |
| Klientpark-tallene: 9 500 × 114 W × 4 050 t = 4 386 150 kWh; 445 500 NOK modellert; 10,2 % av total; 38,6 % av berørte maskiner | `klientpark-energi.md`, `tiltak-pc-utskifting.md`, begge JSON-filer | VERIFISERT |
| Frø-dommen: rate 0,81, forventet 360 855, lånt | `verdict-klientpark-fro.md` frontmatter | VERIFISERT |
| Fabrikk og fri-format-oversettelse ikke bygget | `docs/knowledge-base-recipe.md`; `docs/plan/2026-07-14-revisjonspakke-DF-DI.md` §3 | VERIFISERT |
| Ingest har ingen CLI; ingen base materialisert fra levende kilde | `grep __main__ src/portfolio_optimiser/ingest.py` — null treff; `README.md` «How it is set up» | VERIFISERT |
| Ingest skriver ikke `validator-input.json` / `cost-baseline.json` | `docs/extending.md`, «Legg til en ingest-kilde» | VERIFISERT |
| `docs/extending.md` sier ingen eksempelbase shipper `cost-baseline.json` | samme dokument; motbevist av `ls shared/examples/{veglys-fv-soer,tunnel-hauglia}/` | VERIFISERT (utdatert) |
| `docs/extending.md` sier ingen eksempelbase shipper `cost-baseline.json` | samme dokument; motbevist av `ls src/portfolio_optimiser/data/bundles/{klientpark-energi,driftssenter-kjoling}/` | VERIFISERT (utdatert) |
| Leveranseformene i §5.3; anbefalingene merket ANTATT | — | ANTATT |