portfolio-optimiser/docs/plan/2026-07-06-reell-kjoring-analyse-plan.md

# Analyse & plan — første reelle virksomhetskjøring

> **Status:** UNDER UTFØRELSE — revidert 2026-07-10. **Fase 1 (klynge A) EKSEKVERT**
> (`a44256a`→`847ed90`, 10/10 steg, 279/4 grønn). Kryssmodell-review 2026-07-09
> ([funn](../review-2026-07.md)) injiserte endringer i Fase 2–6; den detaljerte, gjeldende
> per-sesjons-planen er [sesjonsplanen 2026-07-10](2026-07-10-sesjonsplan-fase2-6.md)
> (S2.0–S5.3 + beslutnings-kø D-A–D-E + operatør-milepæler M1–M3). Denne fila forblir
> task-definisjonen/gap-analysen; sesjonsplanen er utførelses-nivået.
>
> **Revisjon 2026-07-14:** en intensjonsanalyse (utover F1–F14) ga fem intensjonsfunn F-INT-1–5 +
> fire operatør-beslutninger D-F–D-I, protokollert i
> [revisjonspakka](2026-07-14-revisjonspakke-DF-DI.md), innplassert i planverket 2026-07-15 (se §5).
>
> **Kilde:** operatør-scenario 2026-07-06 + [gap-analyse](#) forankret i målbilde §2–§4,
> ingest-målbilde §11/§12, research §15. Ingen modell-kostnad påløpt.

## 1. Scenariet (operatørens ord, presisert)

Et team i en virksomhet starter en seriøs kjøring over en portefølje av flere uavhengige
prosjekter. Hvert prosjekt skal kostnadsreduseres innenfor **flere dimensjoner** (anta ~10 per
prosjekt), og det kjøres typisk **én dimensjon per prosjekt per kjøring**. Inn i systemet legges
i tillegg **all relevant kontekst**:

- faglig kunnskap + faglige vurderingsmetoder,
- tidligere vurderinger (både **godkjente og forkastede**),
- hvor mye som er **spart så langt**,
- **målsetning** per prosjekt og totalt for porteføljen,
- + øvrig relevant kontekst.

Data er en blanding av **eksterne og interne** kilder, lagt inn enten **manuelt** eller **hentet**
fra databaser, rapporter, **MCP-servere** og annet.

## 2. Hva som gjenbrukes (bygget + load-bearing-testet)

Ikke bygg på nytt. Dette står og er dekket av detach-bevisende tester:
8-stegs-loopen (kontekst→hypotese→debatt→validér→forbedre→foreslå→feedback→promotér), den
**blokkerende deterministiske validatoren** (solver + Monte Carlo), budsjett-/stopp-tak,
provenance-stempling, ingest-kjernen (CSV + SQL på begge stacker; HTTP MAF-demo), gated
wiki-promotering (fail-closed), async verdict-inbox, ExpeL-folden, og den delte framework-nøytrale
kjernen (`shared/` = OKF + golden-suite + ekspert-persona-skill).

## 3. Gap-analyse: scenario → dagens tilstand → gap

Fem gap-klynger. Kostnad er konsentrert i C og D.

### A. Domenemodellering (offline, gratis, load-bearing-testbar)
- **Dimensjon som begrep.** I dag: kandidat-tiltak per prosjekt. Trengs: «dimensjon» som
  førsteklasses scoping av hypoteserommet (hvilken kostnadsakse en kjøring adresserer) + IR/config
  for det + orkestrering av N prosjekter × 10 dimensjoner (hvilken dimensjon når, dedup på tvers).
- **Mål + besparelses-hovedbok.** I dag: ingen. Trengs: persistent, provenance-stemplet hovedbok
  over *realiserte* besparelser per prosjekt + portefølje, mål-tilstand per prosjekt + totalt, og
  «stopp når mål nådd»-logikk (distinkt fra token-budsjett-taket).
- **Faglige vurderingsmetoder.** I dag: deterministisk validator + persona. Trengs: encoding av
  domenets faktiske metoder — dels som kunnskap i OKF-bundelen, dels evt. som validator-regler.

### B. Datainntak for virkeligheten
- **MCP wiret i kjørestien.** I dag: extension-point-demo (`build_mcp_server`), ikke wiret.
  Trengs: MCP som en ekte ingest-kilde (bygg extension-punktet du eksplisitt vil bruke).
- **Dokument/rapport-connector.** I dag: ingen (kun CSV/SQL/HTTP). Trengs: PDF/DOCX/rapport →
  OKF-bundle med provenance.
- **Live-kilde-herding.** I dag: alt mot committede fixtures / lokal mock — ingen bundle er
  materialisert fra en ekte kilde, noensinne. Trengs: credentials-håndtering, feilhåndtering,
  live-provenance, inkrementell re-ingest.

### C. Skala + henting (kostnad begynner her)
- **Semantisk henting.** I dag: feature-key-match. Ved «all faglig kunnskap + alle tidligere
  dommer» blir dette utilstrekkelig — embeddings/vektor-henting (B2/R4/U10) blir load-bearing.
- **Concurrency + kostnadsstyring.** I dag: sekvensiell `run_portfolio` + per-kjøring token-tak.
  N×10 kjøringer krever concurrent fan-out (U1, bevisst kuttet) + kostnadsstyring på tvers av mange
  kjøringer.

### D. Kjøretid mot ekte modell (kostnad + tenant)
- **Azure/Foundry-profil eksersert.** I dag: kun lokal/offline; azure-blokk i `model_map.json` er
  placeholders. Trengs: ekte deployments i virksomhetens tenant.
- **Live-modell-kjøring.** I dag: alt ende-til-ende er skriptet offline-sim (bevis for plumbing,
  ikke for at en levende LLM produserer forslaget/dommen). Trengs: første genuine kjøring, validert
  i liten skala før full portefølje.

### E. HITL-operasjoner i skala
- **Verdict-ruting + -sporing.** I dag: én mappe-inbox. Ved mange kandidater trengs ruting til rett
  fagekspert, sporing av utestående dommer, oversikt for teamet.
- **Varsling.** I dag: `notify=`-stub. Trengs: ekte leveranse (e-post/Teams/webhook — B11).

## 4. Åpne designbeslutninger (må avklares i Fase 0, ikke av meg nå)

> **Status 2026-07-10 (post Fase 1 + review):** (1) dimensjonsmodell **AVKLART** av Fase 1
> (både kontekst-subsett OG kandidat-constraint; dobbelttelling løst av ledgerens dimensjonsfrie
> sum-nøkkel). (2) hovedbok-sannhet **I HOVEDSAK AVKLART** (typet `SavingsLedger` + fail-closed
> `realize`-ekspertgate; driftskonvensjon gjenstår). (3) mål-semantikk **DELVIS** (absolutt +
> prosent + hard/soft bygget; prosent-BASELINE uavklart → beslutning **D-E**). (4) første
> live-kilde **ÅPEN** → **D-B** (NB: krever samtidig bevisst amendment av frossen
> ingest-målbilde §8/§11 — review P1). (5) vektor-store **ÅPEN** → **D-C** (research-grunnlag
> klart: numpy brute-force > sqlite-vec; LanceDB utelukket på Intel-Mac). (6) stack-paritet
> **ÅPEN** → **D-E**. D-referanser: [sesjonsplanen §2](2026-07-10-sesjonsplan-fase2-6.md).

1. **Dimensjon-modell:** er en dimensjon en delmengde av bundle-konteksten, en constraint på
   kandidat-typer, eller begge? Hvordan unngås dobbelttelling av besparelser på tvers av dimensjoner?
2. **Besparelses-hovedbok:** hvor bor sannheten om «realisert» besparelse — en ny RAW-fil-lag à la
   verdicts, eller en egen typet store? Hvem stempler «realisert» (ekspert-gate, som promotering)?
3. **Mål-semantikk:** absolutt beløp, prosent, eller per-dimensjon-vekting? Stopp-adferd ved nådd mål.
4. **Første live-kilde:** hvilken (DB / rapport / MCP) er tryggest å herde først?
5. **Vektor-store-valg:** hvilken embeddings-backend passer begge stacker + kostnadsdisiplinen?
6. **Rettferdig stack-paritet:** kjører den ekte kjøringen på MAF, Claude-SDK, eller begge for
   sammenligning? (påvirker hvor Azure/Foundry vs. Claude-API-kostnaden lander)

## 5. Faset plan (roadmap)

Hver fase er uavhengig verifiserbar; kostnad konsentreres i Fase 4+. Utføres via Voyage-pipeline
(`/trekbrief → /trekresearch → /trekplan → /trekexecute → /trekreview`) per fase — én fase per
større arbeidsbolk, aldri one-shot.

> **Revisjon 2026-07-10 (etter kryssmodell-review):** Fase 1 EKSEKVERT (`847ed90`). Fase 2–6 er
> detaljert og REVIDERT i [sesjonsplanen](2026-07-10-sesjonsplan-fase2-6.md) — viktigste
> endringer: «MCP wiret i kjørestien» presisert til **MCP-ingest-konnektor** (method-spec §3
> forbyr query-time retrieval); live-kilde-herding **gated på bevisst ingest-målbilde-amendment**
> (D-B — konflikt med frossen §8/§11, review P1); concurrent fan-out krever beslutning **D-D**
> først (determinisme-modell, review F6); nye funn-injiserte sesjoner **S2.0**
> (portefølje-læringssløyfe, F1), **S2.1** (outbox/output-laget, P4), **S2.5** (inbox-herding,
> F7/F11), **S2.7** (validator-stramming, F2), **S4.0** (kostbaseline-forankring, F3); Fase 4/6
> splittet i offline-sesjoner (S4.0–S4.2) + operatør-milepæler **M1–M3**.

> **Revisjon 2026-07-14 (intensjonsanalyse → planverk-oppgradering):** En intensjonsnivå-analyse
> (utover F1–F14) fant fem intensjonsfunn **F-INT-1–5** — kunnskapsinnholdet underspesifisert
> (kaldstart), OKF-duplikasjon på 6 kodesteder + spec-avvik, manglende «ferdig»-definisjon,
> «betydelig verdi» ikke operasjonalisert, kjøringskost = CFO-beslutning — og fire
> operatør-beslutninger **D-F–D-I**, protokollert i
> [revisjonspakka](2026-07-14-revisjonspakke-DF-DI.md):
>
> - **D-F — Kunnskapsinnholdsmodell:** delt, kildebelagt dimensjonsbibliotek (tiltaksmønstre/
>   erfaringer/råd) som KUN lesestoff for forslagsstilleren, materialisert inn i hver bundle via
>   ingest, trinnvis lesing (sammendrag-først); shipped energi-eksempel i realistisk skala med rådata.
> - **D-G — OKF felles modul + fabrikk + evaluator i eget repo (`okf-toolkit`):**
>   standard-kompatibel; bundle-innboks → AI-fabrikk bygger base → evaluator scorer teknisk
>   korrekthet + tilstrekkelighet.
> - **D-H — Oppsett + brukervennlighet:** en **oppskrift** (dokumentert team-prosess), ikke
>   veiviser; fagpersonen leverer filer i egne formater, fabrikken AI-oversetter dommer til strengt
>   format (stikkprøve-godkjenning).
> - **D-I — Verdibevis + kostnadsstyring:** nivå-2-påstand (modellerte tall); **verdirapport per
>   kjøring** (hovedbok-basert, læringseffekt tallfestet) + **kostnadssimulering FØR kjøring**
>   (what-if over modell-map, MÅ-krav).
>
> Innplassert 2026-07-15 (revisjonspakka §5): nye sesjoner **S3.5**
> (bibliotek/innholdsmodell, D-F), **S3.6** (kostnadssimulering, D-I) og **S5.4** (verdirapport,
> D-I) + eget **toolkit-repo** (D-G) i [sesjonsplanen](2026-07-10-sesjonsplan-fase2-6.md); D-H
> utvider S5.3 (oppskrift-dok); commons-amendment (D-F/D-G) via PULL-ONLY. **S2.0/S2.1/S2.5 forblir
> uendret byggbare.**

- **Fase 0 — Dyp planlegging + research.** Voyage trekbrief/trekplan per etterfølgende fase; ekstern
  research på vektor-stores, MCP-connector-mønstre, Foundry-deployment. Avklar §4-beslutningene.
  *Output:* per-fase-briefer. *Kostnad:* ingen (planlegging).
- **Fase 1 — Domenemodellering (klynge A).** Dimensjon-begrep, mål + besparelses-hovedbok,
  vurderingsmetode-encoding. Offline, fixtures, load-bearing. *Kostnad:* ingen.
- **Fase 2 — Datainntak for virkeligheten (klynge B).** MCP-wiring, dokument-connector,
  live-kilde-herding (mot én kontrollert kilde). *Kostnad:* minimal.
- **Fase 3 — Skala + henting (klynge C).** Embeddings/semantisk henting, concurrent fan-out,
  kostnadsstyring på tvers av kjøringer. *Kostnad:* lav (embeddings).
- **Fase 4 — Kjøretid mot ekte modell (klynge D).** Eksersér Azure/Foundry-profil i tenant; første
  live-modell-kjøring i liten skala. *Kostnad:* reell API — hardt tak, minimal verifisering.
- **Fase 5 — HITL-operasjoner i skala (klynge E).** Verdict-ruting/-sporing + varsling (B11).
- **Fase 6 — Pilot.** Én ekte kjøring: **én dimensjon, ett prosjekt**, live kilde + live modell +
  ekte ekspert. Verifiser hele sløyfa mot virkeligheten FØR skalering til full N×10-portefølje.
- **Deretter:** skaler til full portefølje.

## 6. Verifisering (suksesskriterier, testbare)

- **Fase 1:** en dimensjon-scopet kjøring produserer kun kandidater innen dimensjonen (test);
  hovedboken akkumulerer realisert besparelse med provenance og respekterer et mål-stopp (test).
- **Fase 2:** en bundle materialiseres fra en live kilde via MCP + via dokument-connector, med
  korrekt provenance (golden mot kontrollert kilde).
- **Fase 3:** semantisk henting returnerer relevant tidligere dom over en syntetisk stor base;
  concurrent portefølje-kjøring gir identisk resultat som sekvensiell (determinisme bevart).
- **Fase 4:** én dokumentert live-modell-kjøring innen token-tak; Azure/Foundry-profil grønn.
- **Fase 6:** pilot-kjøringen lukker sløyfa (forslag → validér → ekspert-dom → promotering →
  neste kjørings kontekst bærer dommen) mot ekte modell + ekte kilde.

## 7. Grenser (uendret, gjelder også her)

Rent teknisk rammeverk (deployer eier DPIA/ROS/formål). 90%-prinsipp: bygg generisk kjerne +
extension points, ikke de siste 10 %. Deterministisk validator forblir obligatorisk + blokkerende.
Kostnadsdisiplin: offline/lokal primært; ekte modell kun målrettet minimal verifisering, harde tak.
`shared/` forblir framework-nøytralt; commons PULL-ONLY.