diff --git a/docs/plan/2026-06-26-maalbilde-agentic-loop.md b/docs/plan/2026-06-26-maalbilde-agentic-loop.md new file mode 100644 index 0000000..876b1b5 --- /dev/null +++ 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
OKF-navigasjon: index + frontmatter + cross-links"] + S2["2 · Hypoteser
kandidat-tiltak"] + S3["3 · Debatt
proposer vs checker"] + S5["5 · Forbedre
falsifisering inn i ny hypotese"] + S1 --> S2 --> S3 --> S5 + S5 -.->|"bundet av token- og runde-tak"| S2 + end + + VAL{{"4 · DETERMINISTISK VALIDATOR
CBC + Monte Carlo · BLOKKERENDE
avgjør tallene"}} + + subgraph OUT["OUTPUT-LAG · eksperiment inbox/outbox · mappe"] + direction LR + PROP["6 · Foreslå
pending verdict"] + REJ["6 · Kast
med begrunnelse"] + end + + subgraph HITL["7 · TILBAKEMELDING · fageksperter · persona i sim, menneske i prod"] + direction LR + SHORT["Kort løkke
synkron review"] + LONG["Lang løkke
fil i mappe · dager til uker"] + end + + GATE{{"8 · PROMOTERINGS-GATE
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
realistisk LLM Wiki-eksempel"] + GOLD["Golden-suite
forventede validator-utfall"] + end + SHARED --> MAF["REPO A · MAF
dette repoet
prod: Azure Foundry"] + SHARED --> CL["REPO B · Claude Agents SDK
søsken · bygges i sekvens"] + MAF <-.->|"rettferdig sammenligning:
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.