portfolio-optimiser/docs/plan/2026-06-26-maalbilde-agentic-loop.md

# Målbilde — portfolio-optimiser (agentisk kostnadsbesparelses-loop)

> **Status:** KONSENSUS-baseline fra design-samtale 2026-06-26. **Ikke implementert.**
> Dette dokumentet er nordstjernen for det videre arbeidet — en rettesnor mot drift.
> `STATE.md` peker hit; dette endres *bevisst*, ikke ved drift. Historikk i git.
>
> **Forrige grunnlag:** [inkrementell-plan (ryggrad)](2026-06-23-incremental-plan.md) ·
> [fot-i-bakken (levert vs lovet)](../2026-06-26-fot-i-bakken.md) ·
> [research §15](../research/2026-06-23-prior-art-platform.md)

---

## 0. Hva dette dokumentet er (og ikke er)

Dette er **målbildet** for hva løsningen skal *være* når den er sann — ikke en
faseplan. Faseplanlegging skjer per inkrement via Voyage (`/trekbrief → /trekresearch
→ /trekplan → /trekexecute → /trekreview`). Forholdet:

- **Program-nivå = dette dokumentet.** Definerer «ferdig». Endres sjelden.
- **Fase-nivå = Voyage-syklus per inkrement.** `/trekreview` på fase-nivå er anti-drift-
  mekanismen (samme delivered-vs-brief-sjekk som fanget F1/F2, og som fot-i-bakken
  måtte gjøre for hånd fordi syklusen ikke kjørte på de agentiske lagene).

---

## 1. Forretningsmål

**Domeneproblemet:** Et generisk, åpent rammeverk for en organisasjon som driver en
**portefølje av uavhengige prosjekter**, og som vil finne **kostnadsbesparelser/effektivi­
seringer *inne i* hvert enkelt prosjekt** (ikke på tvers). Metoden *er* produktet:

> sverm av agenter genererer kandidat-tiltak → **obligatorisk deterministisk validator
> avgjør verdiene** → fageksperter bedømmer via HITL → **systemet lærer av dommene.**

**To stacker, samme problem (delt eksempel):**
- **Dette repoet:** Microsoft Agent Framework (MAF). Lokal profil for simulering/læring;
  **Azure Foundry er produksjonsmålet** for ekte deployere.
- **Søsken-repo (i sekvens, ikke ennå):** samme metode på **Claude Agents SDK**.

**Leveransen** er en **rettferdig sammenligning** av de to stackene på *identisk* metode +
*identisk* datagrunnlag — der hver implementasjon også står selvstendig som brukbar.

**Formål:** operatørens læring. **Publiseres på Forgejo med høy nok kvalitet til å deles
og brukes.** Kvalitets-grunnregel: **koden får ikke påstå mer enn den gjør.** En docstring
som sier «lærer av dommene» over en usammenkoblet sløyfe er en kvalitetsdefekt i seg selv —
uavhengig av hvor solid validatoren er.

---

## 2. Metoden — 8-stegs sverm-loop

1. **Forstå all kontekst** — naviger prosjektets OKF-bundle (ikke stuff alt inn).
2. **Hypoteser** — generér konkrete kandidat-tiltak.
3. **Diskutér** — maker/checker-debatt (MAF Group Chat, *ikke* Magentic).
4. **Validér / falsifisér** — deterministisk validator på *tallene* (blokkerende);
   debatt/checker på *resonnementet* (kvalitativ falsifisering).
5. **Forbedre** — før falsifiseringen *inn i* neste hypotese (bundet av token-/runde-tak).
6. **Kast / foreslå** — forkast med begrunnelse, eller løft fram som forslag.
7. **Respondér på tilbakemelding** — to tidsskalaer (kort + lang løkke, §3).
8. **Tilbakefør** — promotér *godkjent* kunnskap inn i wikien (valgfritt, gated).

---

## 3. Arkitektur — trelagsmodell + to tilbakemeldings-løkker

**Tre lag, klart adskilt:**
- **Kontekst-lag (OKF-bundle per prosjekt = LLM Wiki):** prosjektdokumenter, metodeverk,
  fagbøker/artikler, constraints, **og godkjente vurderinger**. Kuratert, versjonskontrollert,
  menneske+agent-lesbar. **Det ExpeL-retrieval henter fra.** Read-context ved kjøretid.
- **Output-lag (eksperiment inbox/outbox = mappestruktur):** forslag (pending verdict),
  forkastede + begrunnelse, provenance, rå dommer. Append-tungt, kjøre-scopet, **aldri i wikien.**
- **Promoterings-gate (HITL):** når en ekspert *godkjenner* et utfall, promoteres det fra
  output-laget inn i kontekst-laget som en `type: verdict`-konseptfil.

**To tilbakemeldings-tidsskalaer — filsystemet er sannhetskilden:**
- **Kort løkke:** ekspert vurderer synkront i samme kjøring.
- **Lang løkke:** dager/uker går; eksperten legger vurderingen i en **mappe**, og løsningen
  plukker den opp *når den enn lander* — i en separat kjøring. **Løsningen må være fullt
  gjenopptakbar på tvers av kjøringer adskilt i tid.** Ingen antakelse om en levende sesjon.

I simulering spiller en **dedikert ekspert-persona** (`SKILL.md`-forankret) mennesket; i
produksjon byttes personaen ut med et menneske som bruker **samme mappe-grensesnitt.**

### Diagram — kjøretids-arkitektur

```mermaid
flowchart TB
    subgraph CTX["KONTEKST-LAG · OKF-bundle per prosjekt · LLM Wiki"]
        direction LR
        PD["Prosjektdokumenter"]
        MV["Metodeverk"]
        LIT["Fagbøker og artikler"]
        CON["Constraints"]
        AV["Godkjente vurderinger"]
    end

    subgraph SWARM["AGENT-SVERM · MAF Group Chat · maker / checker"]
        direction TB
        S1["1 · Forstå kontekst<br/>OKF-navigasjon: index + frontmatter + cross-links"]
        S2["2 · Hypoteser<br/>kandidat-tiltak"]
        S3["3 · Debatt<br/>proposer vs checker"]
        S5["5 · Forbedre<br/>falsifisering inn i ny hypotese"]
        S1 --> S2 --> S3 --> S5
        S5 -.->|"bundet av token- og runde-tak"| S2
    end

    VAL{{"4 · DETERMINISTISK VALIDATOR<br/>CBC + Monte Carlo · BLOKKERENDE<br/>avgjør tallene"}}

    subgraph OUT["OUTPUT-LAG · eksperiment inbox/outbox · mappe"]
        direction LR
        PROP["6 · Foreslå<br/>pending verdict"]
        REJ["6 · Kast<br/>med begrunnelse"]
    end

    subgraph HITL["7 · TILBAKEMELDING · fageksperter · persona i sim, menneske i prod"]
        direction LR
        SHORT["Kort løkke<br/>synkron review"]
        LONG["Lang løkke<br/>fil i mappe · dager til uker"]
    end

    GATE{{"8 · PROMOTERINGS-GATE<br/>kun godkjent kunnskap til wiki"}}

    CTX -->|"leses inn i prompt"| S1
    S3 --> VAL
    VAL -->|"validert"| PROP
    VAL -->|"falsifisert"| S5
    VAL -->|"ugyldig"| REJ
    PROP --> SHORT
    PROP --> LONG
    SHORT --> GATE
    LONG --> GATE
    GATE -->|"tilbakeføres som ny kunnskap"| AV
    AV -.->|"neste kjørings ExpeL-retrieval"| S1
```

---

## 4. Datagrunnlaget — OKF / LLM Wiki

**Open Knowledge Format (OKF)** — åpen spesifikasjon fra Google Cloud (v0.1, 2026-06-12),
formaliserer Karpathys «LLM-wiki»-mønster. Verifisert mot
[spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):

- **Bundle = katalog med markdown-filer + YAML frontmatter.** Ett påkrevd felt: `type`.
  Anbefalt: `title, description, resource, tags, timestamp`. **Egendefinerte felt er tillatt
  og konsumenter MÅ bevare dem** → vi kan legge til `constraint`, `verdict`, `methodology`.
- **Reserverte filnavn:** `index.md` (progressiv disclosure), `log.md` (kronologisk historikk).
- **Cross-links** (bundle-relative `/…`) = utypede rettede kanter → emergent graf.
- **Konsumenter MÅ tolerere brutte lenker og ukjente felt** — robusthet i spec.
- **Kontrast til RAG:** kuraterte, versjonskontrollerte konsepter agenten leser/oppdaterer —
  ikke henting over rådokumenter ved query-tid.

**Vendor-nøytral** → samme bundles konsumeres av *både* MAF og Claude SDK uendret. Vi lærer av
Googles referanse-tooling (`okf/src/reference_agent`, `toolbox/`), men **avhenger ikke** av det.

**«Forstå all kontekst» (steg 1) gjøres via OKF-navigasjon** (`index.md` + frontmatter-skann +
cross-links), *ikke* ved å dytte hele bundelen inn i prompten — det er nettopp dette OKF
erstatter stuffing/RAG med, og det som lar det skalere.

---

## 5. Den samlende diagnosen — hvorfor dette ikke er bygget ennå

Fot-i-bakken (verifisert mot kilden) viser at **strukturene og de bundne løkkene finnes — det
som konsekvent mangler er én ting: «tilbakemelding-inn-i-prompt»-dataflyten.**

| Loop-steg | I koden i dag (verifisert 2026-06-26) |
|---|---|
| 1. Forstå all kontekst | Chunk-stuffing fra docs. ExpeL når aldri agentene (`context_providers`=0). Bundle-navigasjon finnes ikke. |
| 2. Hypoteser | ✅ `generate_via_llm` |
| 3. Diskutér | Group Chat finnes, men round-robin + **ugated** (`workflow.py:93`) |
| 4. Validér / falsifisér | Validator **solid ✅** (tall). Checker falsifiserer ikke — ingen gate |
| 5. Forbedre | **Bundet blind-retry finnes** (`generate.py`, `max_attempts=3`); **informert refinement gjør ikke** — avvisningsgrunn/kritikk mates ikke tilbake |
| 6. Kast / foreslå | Rejection-arm finnes (F2); ikke debatt-drevet |
| 7. Tilbakemelding | Kort løkke = dummy inline; lang/async fil-løkke finnes ikke |
| 8. Tilbakefør til wiki | Finnes ikke (integritets-kritisk) |

**Konsekvens:** Remediering er **ikke** åtte separate bygg. Det er **ett manglende mønster**
(få falsifiserings-/kontekst-signalet tilbake inn i neste hypotese) anvendt tre steder
(steg 1, 3, 5), **pluss tre genuint nye kapasiteter** (bundle-navigerende kontekst, lang fil-
feedback-løkke, wiki-promotering). De bundne løkkene som finnes (`meter.tick_round`,
`BudgetExceeded`, `max_attempts`) er stillaset — vi mangler dataflyten *gjennom* det.

---

## 6. Invarianter (ufravikelige — fra CLAUDE.md + låste beslutninger)

- **Deterministisk validator er obligatorisk og blokkerende** — den ene nøytrale (endpoint-frie)
  dommeren. Holder sirkulariteten i sjakk (svermen både foreslår og kritiserer; personaen
  godkjenner — validatoren er ankeret som hindrer sverm-selvbekreftelse).
- **Stoppkriterier + budsjett-tak påkrevd** — forbedrings-løkka (steg 5) kjører under
  *eksisterende* måler med eksplisitt max-runder. «Forbedre til god nok» uten tak er forbudt.
- **Group Chat maker-checker** som debatt-default (IKKE Magentic). Checkeren **må faktisk gate**,
  ELLER vi slutter å kalle det maker-checker.
- **Wiki-promotering (steg 8) er gated:** kun menneske/persona-**godkjent** kunnskap promoteres,
  aldri rå agent-output (ellers selv-forurensning + OKF lint-/motsigelses-eksplosjon).
  Provenance-stemples (hvem godkjente, når, fra hvilket eksperiment).
- **Rent teknisk rammeverk** — deployer eier DPIA/ROS/formål. Bygg kun tekniske forutsetninger.
- **Lokal-only default, ingen stille egress, provenance.** Kostnadsdisiplin D6.
- **90%-prinsipp:** bygg generisk kjerne + extension points (MCP/RAG = extension point, ikke nå).
- **Load-bearing tester:** testene MÅ *feile* når dataflyten detaches (grønn-men-død = Fase-2-fellen).

---

## 7. Testbar «ferdig» (load-bearing)

Per agentisk steg, en test som **feiler når sømmen kobles fra**:

- **Steg 1:** detach ExpeL-retrieval fra prompten → en test som beviser at en tidligere dom
  påvirker neste kjørings hypotese MÅ feile.
- **Steg 3/4:** la checkeren si «avvis» → en test som beviser at kontroll-flyten faktisk gater
  MÅ feile hvis dommen ignoreres.
- **Steg 5:** fjern «kritikk → neste prompt»-dataflyten → en test som beviser at forbedring
  bruker forrige falsifisering MÅ feile.
- **Steg 7 (lang løkke):** en verdict-fil som lander i mappa *etter* kjøringen → en test som
  beviser at en separat, senere kjøring konsumerer den MÅ feile uten fil-løkka.
- **Steg 8:** en *ikke*-godkjent dom → en test som beviser at den IKKE havner i wikien.

---

## 8. Det realistiske eksemplet (delt artefakt)

Eksemplet er en **ekte artefakt** — realistisk nok til ende-til-ende-test, og dogfooding på det
skal forbedre løsningen. **Hele LLM Wiki-eksemplet er felles** mellom de to repoene:

- per-prosjekt **OKF-bundles** (med verifisert litteratur + provenance),
- **golden-suite** (forventede validator-utfall + frøsatte godkjente vurderinger),
- **ekspert-persona** (`SKILL.md`).

AI eier domene-innholdet + korrektheten (operatør er ikke domeneeksperten); hver kilde
verifiseres + provenance-stemples når bundelen forfattes. I simulering spiller operatøren *eller*
personaen fageksperten som gir tilbakemeldinger.

### Diagram — delt kjerne, to stacker

```mermaid
flowchart LR
    subgraph SHARED["DELT KJERNE · framework-nøytral · bygges én gang"]
        direction TB
        SPEC["Metode-spec + målbilde"]
        SKILL["Ekspert-persona · SKILL.md"]
        OKFB["OKF-bundles<br/>realistisk LLM Wiki-eksempel"]
        GOLD["Golden-suite<br/>forventede validator-utfall"]
    end
    SHARED --> MAF["REPO A · MAF<br/>dette repoet<br/>prod: Azure Foundry"]
    SHARED --> CL["REPO B · Claude Agents SDK<br/>søsken · bygges i sekvens"]
    MAF <-.->|"rettferdig sammenligning:<br/>kun framework-forskjell måles"| CL
```

---

## 9. Repo-layout og delt kjerne (anbefaling)

**Ikke opprett søsken-repoet ennå** (D7 + STATE: prematurt til metodens agentiske claims er
sanne/scoped; «i sekvens»). Men bygg den delte kjernen **nå** som en framework-nøytral, klart
separerbar enhet:

- **Nå:** topp-nivå `shared/` (eller `commons/`) i *dette* repoet — **null MAF-imports.**
  Inneholder OKF-bundles + golden-suite + persona. OKFs vendor-nøytralitet garanterer dette.
- **Senere (når søsken-arbeidet starter):** ekstrahér `shared/` til eget Forgejo-repo
  (`portfolio-optimiser-commons` e.l.) via `git subtree split`; begge implementasjons-repo
  konsumerer det. Utsetter cross-repo-plumbing (submodule-friksjon) til det er konkret behov.

> **BESLUTTET (R1, 2026-06-26):** `shared/`-dir nå (null MAF-imports), ekstrahér til eget
> commons-repo via `git subtree split` når søsken-arbeidet faktisk starter.

---

## 10. Utestående beslutninger

- **D-DOMENE:** hvilket fagområde for det realistiske eksemplet?
  **Lener mot energieffektivisering** (energiledelse + M&V). **Avgjørende kriterium (2026-06-26):**
  domenet må ha en **lærings-overflate** — et reelt gap mellom det deterministisk *beregnbare*
  (validator) og det ekspert-*kjennbare* (dommer), ellers har lærings-sløyfa (metodens
  differensiator) ingenting å lære. **FinOps er for deterministisk** — validator ≈ ekspert, så
  ExpeL-sløyfa blir dekorativ. **Energi har et ekte gap:** validatoren regner *modellert*
  besparelse; ekspert-dommen koder **realiserings-gapet** (modellert vs faktisk; måle-, atferds-,
  interaksjons-effekter), og ExpeL lærer korreksjonene på tvers av prosjekter. Infrastruktur har
  også sterk lærings-overflate, men høyere forfatter-risiko for AI. **Bekreft energi neste sesjon.**
- **R2:** rå output-lager — vanlig store (JSON/sqlite, som i dag) vs egen OKF «experiment-log».
  Anbefalt: vanlig for rått, OKF for det promoterte laget.
- **R3:** sverm-roster — 2 roller (proposer/checker, som i dag) vs rikere (proposer/critic/
  domeneekspert/validator-liaison).
- **R4:** wiki-promotering (steg 8) som valgfri+gated kapasitet (anbefalt) vs kjerne.

---

## 11. Fase-nedbrytning (avhengighetsrekkefølge — hver fase = Voyage-syklus)

1. **Kontekst-fundament + realistisk eksempel** — OKF-bundle-struktur, persona, mappe-kontrakt,
   golden-suite-frø. *(Loopen henter fra dette — derfor først.)*
2. **Steg 1-wiring** — OKF-navigasjon + ExpeL-retrieval inn i agent-prompten (lukk #1).
3. **Steg 3/4-semantikk** — bind checker-dommen til gate, ELLER omdøp (lukk #3).
4. **Steg 5** — informert forbedrings-løkke (kritikk → neste hypotese) under eksisterende tak.
5. **Steg 7 lang løkke** — fil-basert, gjenopptakbar async feedback.
6. **Steg 8** — gated wiki-promotering (hvis R4 = ja).
7. **Release-hygiene** — README, `[project.scripts]`, SKILL.md. *Sist, og bare hvis vi er enige.*
8. **Én ekte-modell-kjøring** (lokal Ollama, D6) — ende-til-ende-bevis.

> Rekkefølge og scope per fase låses i fasens `/trekbrief`. Ingen release før operatør er 100% enig.