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) · fot-i-bakken (levert vs lovet) · research §15

---

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

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:

• 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

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.