docs(maalbilde): konsolidert agentisk-loop baseline + OKF-kontekstarkitektur

Nordstjerne fra design-samtale 2026-06-26. Konsoliderer: 8-stegs sverm-loop, trelagsmodell (OKF-kontekst/output-inbox/promoteringsgate), to feedback- tidsskalaer (kort synkron + lang fil-basert/gjenopptakbar), OKF/LLM-Wiki datagrunnlag (web-verifisert mot Google knowledge-catalog), den samlende diagnosen (tilbakemelding-inn-i-prompt-dataflyt mangler 3 steder), invarianter, testbar "ferdig", delt eksempel for begge repo, fase-nedbrytning. 2 Mermaid- diagrammer. STATE peker hit. R1 besluttet (shared/-dir nå). Domene lener mot energieffektivisering (lærings-overflate > FinOps' for-deterministiske kjerne). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019any9zfGNNwWJPX5Zq2QRz
2026-06-26 20:56:14 +02:00 · 2026-06-26 20:56:14 +02:00 · 7df6a66712
commit 7df6a66712
parent 129a40baea
1 changed files with 300 additions and 0 deletions
--- a/docs/plan/2026-06-26-maalbilde-agentic-loop.md
+++ b/docs/plan/2026-06-26-maalbilde-agentic-loop.md
@ -0,0 +1,300 @@
+# 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.