feat: initial scaffold (Python framework on Microsoft Agent Framework)

Plan-fase: repo-skjelett, dokumentasjon (research + inkrementell plan), Python/uv-oppsett, MAF-avhengighet. Ingen rammeverkskode ennå. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H9FyyENxebxVThjrn9et8C
2026-06-23 22:01:22 +02:00 · 2026-06-23 22:01:22 +02:00 · ec9ac74976
commit ec9ac74976
10 changed files with 575 additions and 0 deletions
--- a/docs/plan/2026-06-23-incremental-plan.md
+++ b/docs/plan/2026-06-23-incremental-plan.md
@ -0,0 +1,68 @@
+# Inkrementell plan: Generisk porteføljeoptimerer på MAF
+
+**Dato:** 2026-06-23 · **Fase:** Plan (avventer godkjenning før koding) · **Grunnlag:** `docs/research/2026-06-23-prior-art-platform.md`
+
+## Låste beslutninger (2026-06-23)
+| # | Beslutning | Konsekvens |
+|---|-----------|-----------|
+| D1 | **Python-først** | Stabil `agent-framework` 1.8.0; Functional API, `McpSkillsSource`, Neo4j-memory tilgjengelig. C# utsettes. |
+| D2 | **To profiler: Azure/Foundry (full) + lokal (fallback)** | Full: Cosmos, AI Search agentic retrieval, Durable Task, Foundry-modeller. Lokal: fil-checkpointing, SQLite/Chroma, lokale embeddings. Samme kjerne-API, pluggbar backend. |
+| D3 | **Rent teknisk rammeverk** | Deployer eier behandlingsformål/DPIA/ROS. Vi bygger IKKE compliance-funksjoner (anti-scope A-ny). Vi leverer tekniske forutsetninger (lokal-only, provenance, ingen stille egress) + tydelig disclaimer. |
+| D4 | **Generisk kjerne + 1 syntetisk referanse-domene** | Referanse-domenet er nøytralt/syntetisk (ikke SVV-data) — beviser kjernen uten datasensitivitet, i tråd med D3. |
+
+## Designprinsipper (fra research)
+- **Single-agent baseline → eskalér bevisst** til Group Chat maker-checker kun ved dokumentert behov (token-disiplin).
+- **Deterministisk validator er obligatorisk og blokkerende** (ikke plugin).
+- **Stoppkriterier + budsjett-tak påkrevd ved oppstart** (fail-fast).
+- **Metode = Agent Skill** (`agentskills.io`). **Datatilgang = MCP**. **Læring = VerdictStore + ExpeL-retrieval** (ingen fine-tuning tidlig).
+- Sporbarhet til implementeringsregister: ID-er (U/B/G/R/A/F) refererer rapportens §15.
+
+---
+
+## Fase 0 — Skjelett & beslutnings-lås *(liten)*
+- Init git-repo + Forgejo-remote (avventer ditt OK; bruk `repo-init`-skill).
+- Python-scaffold (`uv`, `agent-framework`), repo-struktur, prosjekt-`CLAUDE.md`, `.gitignore` (STATE.md local-only — offentlig remote senere).
+- Definer det syntetiske referanse-domenet (D4): et lite, fiktivt sett «anleggskostnad»-prosjekter med dummy-data.
+- Pluggbar backend-abstraksjon (profil: `azure` | `local`) som tomt skall (D2).
+
+**Verifisering:** `uv run` importerer `agent_framework`; én triviell agent svarer via `FoundryChatClient` (full) ELLER lokal modell (fallback); `pytest` kjører (0 tester OK); repo pushet til Forgejo (i push-vindu).
+
+## Fase 1 — De-risk spikes *(throwaway, validerer farligste antakelser)*
+- **Spike A (U3):** 3-agent Group Chat maker-checker (proposer · critic · validator) vs single-agent baseline på ett syntetisk prosjekt. Mål: konvergensrate, stall-frekvens, tokenforbruk.
+- **Spike B (G1, G2):** footgun-test — (a) Magentic-terminering når limits=`None`; (b) state-isolasjon i `ConcurrentBuilder` fan-out fra delt builder.
+- **Spike C (B1):** hybrid-validator-skive — LLM → Pydantic-IR → én solver-kall (`mcp-solver`/OR-Tools) → Monte Carlo P10/P50/P90, blokkerende + self-repair (maks N).
+- **Spike D (B2):** VerdictStore + ExpeL-retrieval på 10–20 syntetiske dommer via custom `ContextProvider`.
+
+**Verifisering (målbart pass/fail per spike):** A: maker-checker konvergerer ≤ N runder OG hard cap respekteres; rapport billigere/bedre enn baseline dokumentert. B: ubundet Magentic stopper IKKE → bekreftet at eksplisitt limit kreves; fan-out viser null state-bleed. C: et out-of-range-forslag blir strukturelt blokkert; gyldig forslag passerer med P10/P50/P90. D: retrieval henter den relevante historiske dommen for et likt nytt forslag.
+
+## Fase 2 — Vertikal skive: ett prosjekt ende-til-ende *(MVP-ryggrad)*
+- Onboarding-konfig (B5/B9/B10/B12): data-source-skjema (JSON Schema, diskriminert union) + modell-map + termineringskontrakt + feedback-skjema — **fail-fast** validering.
+- Én Agent Skill koder én metode (U5): `SKILL.md` + deterministisk `scripts/`-validator (B8: minimal sandbox-holdning dokumentert).
+- Datatilgang (U6/U11/B5): `local_folder`-MCP + citation-aware `AIContextProvider`.
+- Per-prosjekt-workflow (U2/U3/B4): single-agent → Group Chat maker-checker + deterministisk termineringskontrakt.
+- Blokkerende hybrid-validator (B1) som middleware/eksekutor (U8).
+- To-lags HITL (B3/U13) + provenance-stamping (B6) + varslings-stub (B11).
+- Observabilitet (U14) + checkpointing (U12, profil-avhengig).
+
+**Verifisering:** ett syntetisk prosjekt kjører ende-til-ende → produserer ett validert, provenance-stemplet besparelsesforslag → ekspertdom fanges → neste kjøring henter dommen (ExpeL). Ingen kjøring starter uten kontrakter. Hard-stopp respektert. Kjører i begge profiler (Azure + lokal).
+
+## Fase 3 — Generalisering & referanse-domene-pakke
+- Orkestrator fan-out over N prosjekter med state-isolasjon (U1/B7).
+- Pakk det syntetiske domenet som referanse-eksempel (D4).
+- Dokumentasjon: «legg til egen metode (skill) / egne datakilder / egen modell-map».
+
+**Verifisering:** et ANNET syntetisk prosjekt legges til **kun via konfig** (ingen kjerne-kodeendring) og kjører gjennom; fan-out over begge isolerer state; begge backend-profiler eksersert.
+
+## Fase 4 — Open-source-klargjøring
+- `prepare-release`: LICENSE, CONTRIBUTING, SECURITY, README, CHANGELOG; rens sensitive filer; **prominent D3-disclaimer**; dokumentér tekniske compliance-forutsetninger (lokal-only, audit/provenance, dataresidens-konfig) uten å påstå compliance.
+- Publiser på Forgejo.
+
+**Verifisering:** fersk klon installerer og kjører referanse-domenet etter README alene; disclaimer synlig; ingen secrets/intern state i historikken.
+
+---
+
+## Risiko / åpne (annenrangs §12 — avklares underveis, blokkerer ikke Fase 0–1)
+- Review-latens (synkron vs async + varsling) → påvirker Fase 2 HITL-design.
+- Antall/variabilitet prosjekter (fast vs dynamisk topologi) → påvirker Fase 3.
+- Skjema-eierskap (definere selv nå vs vente på MAF-native) → vi definerer selv nå, migrerer ved behov.
+- Foundry-memory Preview (G5) → ikke primær verdict-store i prod uten egen vurdering.
--- a/docs/research/2026-06-23-prior-art-platform.md
+++ b/docs/research/2026-06-23-prior-art-platform.md
@ -0,0 +1,358 @@
+# Research-rapport: Generisk porteføljeoptimerer på Microsoft Agent Framework
+
+**Dato:** 2026-06-23
+**Fase:** Decision-grade research (plan-fase — ingen kode skrevet)
+**Metode:** Dynamisk multi-agent research-sweep i Claude Code — 7 grunngitte grener (MAF-plattform · Claude Agent SDK-mønstre å porte · prior art · neuro-symbolsk hybrid · dataintegrasjon · HITL/læring · feilmoduser) → adversariell verifisering av plattform-kritiske påstander mot offisiell dokumentasjon → syntese. 22 agenter, ~1.4M tokens, 228 verktøykall, ~9 min.
+**Kilder:** Microsoft Learn (offisiell MAF-dok), web/Tavily, akademiske preprints (arXiv, MDPI). Gemini Deep Research-trianguleringen falt bort (MCP-serveren kjører på et API deaktivert av Google mai 2026).
+**Verifisering:** Plattform-kritiske MAF-påstander adversarielt re-sjekket mot offisiell dok — 8 av 14 bekreftet uten forbehold; 6 korrigert (se §11 Verifiseringslogg). Praktiker-tall (hallusinasjons-%, FinOps-besparelser, «16 %»-tallet) er medium/lav confidence og merket.
+**Låste premisser (bruker, 2026-06-23):** (B) optimering INNI hvert prosjekt; multi-agent samarbeid à la «dynamic workflows»; hybrid AI + deterministisk verifisering; metode oppgis av bruker (helst som «skill»); bruker oppgir datatilgang, trigger og stoppkriterier; HITL-læringssløyfe = nøkkel-suksesskriterium; modell-backend = Microsoft/Azure AI Foundry med per-agent modellvalg.
+
+> **Lesehjelp:** §1 er sammendraget (hva researchen endrer). §13 er anbefalt arkitektur + neste steg. §14 (Foundry-binding) er lagt til etter syntesen fra egen grunngitt sjekk. §11 (verifiseringslogg) og §12 (åpne spørsmål) er de viktigste for beslutninger.
+
+---
+
+## 1. Sammendrag — hva researchen ENDRER om designet vårt
+
+Researchen bekrefter at MAF er en levedyktig plattform for dette systemet, men flytter flere antakelser. De viktigste endringene, viktigst først:
+
+1. **«Skills» er IKKE et gap — det er en åpen, kryss-vendor standard MAF allerede implementerer.** MAF Agent Skills følger samme `agentskills.io`-spesifikasjon som Claude Agent SDK. Brukerens kjernekrav (brukerleverte, kodifiserbare, gjenbrukbare analysemetoder) løses direkte med `SKILL.md`-pakker (instruksjoner + `scripts/` + `references/`) — uten egen plugin-arkitektur. Verifisert med én korreksjon: progressiv disclosure er **fire** stadier (Advertise → Load → Read resources → Run scripts), ikke tre. Kilde: https://learn.microsoft.com/agent-framework/agents/skills
+
+2. **Magentic (LLM-orkestrert debatt) skal IKKE være default for kjerneflyten.** Microsoft flagger den eksplisitt som eksperimentell og «untested outside the original Magentic-One design». Den anbefalte primærflyten for «agenter som debatterer mot et forslag» er **Group Chat med maker-checker-loop** og deterministisk termineringskontrakt — ikke Magentic. Magentic reserveres for genuint åpne delsteg med harde rundetak. Kilde: https://learn.microsoft.com/agent-framework/workflows/orchestrations/magentic
+
+3. **Læringssløyfen (suksesskriteriet) er ikke en MAF-primitiv og MÅ bygges eksternt.** MAF har ingen innebygd mekanisme for å persistere ekspertfeedback til fremtidige kjøringer (verifisert). Den anbefalte tilnærmingen er **«experience distillation uten fine-tuning»** (ExpeL/ERL-mønster): lagre (forslag, ekspertdom, begrunnelse)-tripler, embed dem, hent topp-K ved kjøretid via en custom `ContextProvider`. Fine-tuning utsettes til retrieval-taket er nådd og ≥~1000 stabile merkede dommer finnes.
+
+4. **Hybrid AI + deterministisk verifisering er et arkitektonisk KRAV, ikke et tillegg.** Mønsteret «LLM foreslår, solver/validator avgjør» er verifisert og implementerbart i dag via MAF Function Tools + en obligatorisk valideringsekzekutor. Forslag som ikke passerer deterministisk validering skal **strukturelt blokkeres** fra å nå eksperten.
+
+5. **Start single-agent per prosjekt, eskalér bevisst.** Microsofts egen Cloud Adoption Framework råder til å prototype med én agent først; MAF-overview sier «if you can write a function to handle the task, do that instead». Multi-agent-debatt innføres kun der single-agent dokumentert svikter. Dette demper kostnads- og loop-risiko som adversarial-grenen dokumenterer (Uber brente hele 2026-AI-budsjettet på 4 mnd; én ukontrollert loop kostet $47 000 på 11 dager).
+
+6. **Språkvalg: Python for første bygg.** Python er på stabil 1.8.0, har Functional `@workflow`-API, `McpSkillsSource` og `intermediate_output_from`; C# er fortsatt `1.0.0-rc2` (`--prerelease` kreves). (Merk: én kilde feilattribuerte `HarnessAgent`/`A2AAgentSession` til 1.8.0 — de kom i 1.7.0.)
+
+## 2. MAF-plattformen i praksis — kapabiliteter og GAP
+
+**Verifiserte kapabiliteter vi kan stole på (high confidence, offisielle kilder):**
+
+| Kapabilitet | Status | Kilde |
+|---|---|---|
+| Fem orkestreringsmønstre (Sequential, Concurrent, Handoff, Group Chat, Magentic) | Verifisert | learn.microsoft.com/agent-framework/workflows/orchestrations/ |
+| Graf-workflow (fan-out/fan-in, conditional/switch-case-edges, superstep-eksekvering, typesikkerhet) | Verifisert | .../workflows/edges |
+| Checkpointing (InMemory/File/Cosmos), pending HITL re-emitteres ved resume | Verifisert | .../workflows/checkpoints |
+| HITL: tool approval + RequestPort/`request_info()` + Magentic plan review | Verifisert (se korreksjon under) | .../workflows/human-in-the-loop |
+| Magentic stoppkriterier: `max_round_count`, `max_stall_count`, `max_reset_count` + progress ledger | Verifisert | .../orchestrations/magentic |
+| MCP-integrasjon native (stdio/HTTP/WebSocket); agent kan eksponeres som MCP-server | Verifisert | .../agents/tools/local-mcp-tools |
+| Function Tools på alle store providere (inkl. Anthropic) | Verifisert | .../agents/tools/ |
+| Middleware-pipeline (intercept input/output per tool/run) | Verifisert | .../agents/middleware/ |
+| Agent-as-tool (`AsAIFunction()` / `as_tool()`) | Verifisert (se korreksjon) | .../agents/tools/ |
+| ContextProvider/HistoryProvider; vector-store-abstraksjoner (Azure AI Search, Cosmos, Qdrant, Redis, Postgres m.fl.) | Verifisert | .../integrations/ |
+| OpenTelemetry-observabilitet (GenAI-konvensjoner) | Verifisert | .../agents/observability |
+| Innebygd evaluering (LocalEvaluator, `evaluate_workflow()`) | Verifisert | .../agents/evaluation |
+| Durable Task-extension (kræsj-overlevende sesjoner, langvarig HITL) | Verifisert | learn.microsoft.com/azure/durable-task/... |
+
+**GAP-er (verifisert):**
+- **Ingen innebygd feedback-til-fremtidige-kjøringer.** Må bygges på ContextProvider + ekstern verdict-store (Cosmos/Neo4j/vektorstore). (high)
+- **Ingen Claude-style «Stop hook»** (rejiser respons + tving fortsettelse) i MAF-kjernen. Nærmeste er Magentic stall-detection eller eksplisitt while-loop i Functional API. (Merk: Azure SRE Agent — eget produkt — har en slik hook, men det er ikke MAF-SDK.)
+- **Ingen modell-generert orkestrering ved kjøretid** (Claudes «dynamic workflows»). MAF-workflows er utviklerdefinert ved design-tid. (Verifisert)
+- **Ingen MAF-native provenance-standard.** Må bygges på melding-source-stamping + egen logg.
+- **Functional `@workflow` og Magentic er eksperimentelle**; Functional er Python-only.
+- **State-isolasjon er en footgun:** gjenbruk av én `WorkflowBuilder`-instans på tvers av kjøringer korrumperer state — krever helper-method-mønster og `IResettableExecutor`. Kritisk i fan-out.
+
+**Korreksjoner fra verifiseringen (eksplisitt):**
+- Påstanden «limit group chat to three or fewer agents» finnes **IKKE** i offisiell MAF-dok — behandle som ikke-verifisert/sannsynlig hallusinasjon. Det finnes ingen tallfestet agent-grense i Group Chat-doken.
+- «All HITL resume via `SendResponseAsync`» er feil: `SendResponseAsync` er C#-workflow-resume; Python bruker `responses={request_id: ...}` til `workflow.run(...)`; standalone-agenter svarer via ny melding.
+- Magentic er «based on / inspired by» Magentic-One, **ikke** en «direct port».
+
+## 3. Støtter MAF «skills» / kodifiserte metoder?
+
+**Ja — direkte og uten gap.** Dette var brukerens eksplisitte spørsmål, og svaret er positivt med høy konfidens.
+
+MAF har et førsteklasses **Agent Skills**-konsept som følger den åpne `agentskills.io`-spesifikasjonen — samme spec som Claude Agent SDK. Struktur: `skills/<navn>/SKILL.md` (frontmatter med navn+beskrivelse, ~100 tokens, injiseres ved oppstart) + body (lastes ved trigger) + `references/` + `scripts/` + `assets/`. Innebygde providere finnes for både Python (`SkillsProvider`) og C# (`AgentSkillsProvider`). Kilde: https://learn.microsoft.com/agent-framework/agents/skills
+
+**Korreksjon (verifisert):** Progressiv disclosure er **fire** stadier, ikke tre: (1) Advertise (~100 tokens), (2) Load (full SKILL.md-body), (3) Read resources (references/assets on demand), (4) Run scripts (on demand).
+
+**Konsekvens for designet:** Hver brukerlevert analysemetode kodifiseres som én skill. `SKILL.md` beskriver *når* metoden gjelder; `scripts/` holder de **deterministiske validatorene** (Python som regner tallene); `references/` holder metodikk. Dette er den direkte implementasjonen av «kodifiserbar gjenbrukbar modul»-kravet. To uavklarte punkter (åpne spørsmål): (a) `agentskills.io`-spec'ens versjonerings-/governance-modell, og (b) riktig granularitet — én skill per metode vs. per delsteg. Sandboxing av brukerleverte scripts er IKKE løst av rammeverket: `SubprocessScriptRunner` er eksplisitt «demonstration only» — produksjonssandboxing er utviklerens ansvar.
+
+## 4. Orkestreringsmønster for «agenter som debatterer mot et forslag» + stoppkriterier
+
+**Anbefalt primærmønster: Group Chat som maker-checker-loop.** Offisiell dok beskriver Group Chat som ideell for «Iterative Refinement, Collaborative Problem-Solving, Multi-Perspective Analysis», og anbefaler eksplisitt maker-checker-loops (generator-verifier) som en Group Chat-variant. Én agent foreslår (maker), én validerer mot definerte kriterier (checker); loopen fortsetter til checker godkjenner eller hard grense nås. Kilde: https://learn.microsoft.com/agent-framework/workflows/orchestrations/group-chat
+
+**Hvorfor ikke Magentic som default:** Magentic er kraftigere for åpne oppgaver (dynamisk manager + replanlegging), men flagget eksperimentell og utestet utenfor original-designet, og doken sier selv «if your scenario requires simpler coordination without complex planning, consider Group Chat instead». Reserver Magentic for genuint åpne delsteg, med harde rundetak satt.
+
+**Stoppkriterier — uttrykk dem på to nivåer (deterministisk, ikke LLM-styrt):**
+1. **Hard loop-guard (rammeverk):** Group Chat `MaximumIterationCount` (C#) eller `termination_condition`-lambda (Python, verifisert: `lambda conversation: len(conversation) >= 4`); eller for Magentic: `max_round_count`, `max_stall_count` (utløser replan), `max_reset_count` (hard stopp). Progress ledger sporer `IsRequestSatisfied`, `IsInLoop`, `IsProgressBeingMade`.
+2. **Domene-konvergens (eksekutor):** en Checker-ekzekutor hvis output (`APPROVED`/`REVISE`) trigger en conditional edge til «done» vs «iterate». LLM-en skal **aldri** selv avslutte loopen.
+
+**Designkrav (fra adversarial-grenen):** Magentic-parametrene defaulter til `None` (ubegrenset) i Python-API-et. Systemet må kreve eksplisitte tallverdier ved oppstart — manglende verdi skal feile ved start, ikke ved $10 000 i tokenforbruk. Legg til `cost_budget_tokens` og wall-clock-timeout som ekstra stoppkriterier. Alle stoppkriterie-brudd skal emittere et strukturert event (ikke stille stopp).
+
+## 5. Hybrid AI + deterministisk verifisering — anbefalt mønster
+
+**Kjernemønster: «LLM-as-modeler → solver/validator disposes», med en mellomliggende typed representasjon (IR).** LLM-en produserer aldri validerte tall eller solver-kode direkte; den produserer en **strukturert, typet forslagsrepresentasjon** (vår ekvivalent av ORPilots IR — solver-agnostisk JSON: sets, parameters, variables, objective, constraints), der hver tallstørrelse har deklarert kilde. En deterministisk modul kompilerer/validerer/eksekverer. Kilder: https://arxiv.org/html/2503.10009v1 (OR-LLM-Agent, 85 % løsningsnøyaktighet); https://towardsdatascience.com/the-secret-to-reproducible-and-portable-optimization-orpilots-intermediate-representation-ir
+
+**Konkret pipeline (per forslag):**
+1. **Generér** kandidat (Group Chat maker) → strukturert forslag.
+2. **Skjema-validér** med Pydantic field-validators (`ge`/`le`, kryss-felt `@model_validator` for f.eks. `savings <= total_cost`) — billigste førstelinje, fanger out-of-range før downstream.
+3. **Solver/validér** der relevant: registrer OR-Tools/PuLP/Z3 eller `mcp-solver` (MIT, MiniZinc/Z3/PySAT via MCP) som Function Tool / Local MCP Tool. Solver returnerer verifisert feasible løsning eller infeasibility-grunn. La aldri LLM gjette feasibility. Kilde: https://github.com/szeider/mcp-solver
+4. **Monte Carlo** som obligatorisk steg for kostnadsanslag: wrap numpy-MC som Function Tool, returnér P10/P50/P90 — aldri punktanslag. Kilde: https://riskonnect.com/reporting-analytics/monte-carlo-analysis-a-powerful-tool-for-risk-management
+5. **Self-repair-loop:** ved solver-feil/infeasibility, mat feilmelding tilbake til LLM (maks N forsøk, så eskalér), à la OR-LLM-Agent.
+
+**Plassering i MAF:** valideringen legges som FunctionMiddleware (intercepts hver tool-call) og/eller en dedikert Verifier-agent kalt via agent-as-tool. **Arkitektonisk regel:** forslag som ikke passerer validatoren skal strukturelt blokkeres fra å nå eksperten. Stoppkriteriene for loopen skal være deterministiske (`max_iterations`, solver `OPTIMAL`, validator-pass, MC P50 under terskel) — sjekket ved superstep-grense.
+
+## 6. Heterogen dataintegrasjon — anbefalt tilnærming + skisse til konfig
+
+**Anbefalt tilnærming: MCP som universelt data-source-abstraksjonslag + AIContextProvider som RAG-injeksjonspunkt.** Hver datakilde (lokal mappe, SQL, REST, RAG-plattform) pakkes som en MCP-server; agenten auto-oppdager tools via `tools/list`. Dette gjør N×M-integrasjonsproblemet til N+M. Citation-aware RAG injiseres via `TextSearchProvider` (C#, `SourceName`/`SourceLink`) eller Azure AI Search-provider. Kilder: https://learn.microsoft.com/agent-framework/agents/tools/local-mcp-tools ; https://learn.microsoft.com/en-us/agent-framework/agents/rag
+
+**Konkrete valg:**
+- **Lokale filer (vanligste prosjektdata):** wrap filsystemet med en lokal MCP-server (`modelcontextprotocol/server-filesystem` finnes), pluss en ingestion-pipeline (recursive chunking ~400–512 tokens, 10–20 % overlap som praktisk default; semantisk/seksjonsbevisst chunking ved behov) til lokal vektorstore (SQLite/Chroma). RAG-grensesnittet blir uniformt uavhengig av lokal/remote.
+- **Enterprise-korpus i Azure:** Azure AI Search agentic retrieval (GA 2026-04-01) — query-dekomponering, semantisk reranking, per-chunk source-referanser + activity log.
+- **Per-prosjekt data-access som custom AIContextProvider:** leser prosjektets data-source-config, henter chunks fra rett backend, injiserer med kilde-metadata (source-stamping via `AgentRequestMessageSourceType` for audit).
+
+**Skisse til generisk data-source-konfig (gjenbruk MCP Claude-Desktop-formatet, utvid med RAG-felt; valider med JSON Schema, fail fast):**
+
+```yaml
+project:
+  id: "prosjekt-A"
+  data_sources:
+    - type: local_folder        # diskriminator
+      path: "./docs"
+      glob: "**/*.{pdf,xlsx,md}"
+      chunking: { size: 512, overlap: 64, embedding_model: "..." }
+    - type: mcp_server
+      command: "uvx"
+      args: ["my-connector"]
+      env: { API_KEY: "${SECRET}" }
+    - type: azure_ai_search
+      endpoint: "https://..."
+      index: "prosjekt-A-idx"
+      semantic_config: "default"
+    - type: rag_api
+      url: "https://..."
+      auth_type: "oauth"
+      query_template: "..."
+```
+
+Diskriminert union på `type`; type-spesifikk connection-blokk + valgfri ingestion-seksjon. **Åpent:** eierskap til dette skjemaet (definere selv vs. vente på MAF-native format), og inkrementell re-ingestion av lokale mapper (ikke støttet out-of-the-box).
+
+## 7. HITL læringssløyfe — anbefaling (suksesskriteriet)
+
+**Anbefaling: «experience distillation uten fine-tuning» (ExpeL/ERL-mønster) over en custom VerdictStore-ContextProvider.** Dette lærer av ekspertdommer uten full re-trening og er state-of-the-art-validert. Kilder: https://arxiv.org/html/2308.10144v2 (ExpeL, AAAI 2024); https://www.langchain.com/resources/llm-as-a-judge (data-flywheel).
+
+**Mekanikk:**
+1. **To-lags HITL i flyten:** (a) pre-eksekusjon plan-godkjenning via `MagenticPlanReviewRequest` (eksperten godkjenner/reviderer analyseplanen før dyre analyser kjøres); (b) post-eksekusjon forslagsgodkjenning via `request_info()`-gate (suspenderer hele workflow ved definert checkpoint) eller tool approval på `emit_savings_proposal`. Eksperten bryter aldri flyten — den gater progresjonen.
+2. **Persistér** hver dom (`approve`/`reject`/`revise` + begrunnelse + forslags-embedding + prosjekttype + domene) til ekstern store (Cosmos med vektorindeks, eller Neo4j memory provider — sistnevnte Python-only, «preference learning»).
+3. **Distillér + retrieve:** LLM ekstraherer NL-heuristikker fra (dom, forslag)-par; ved start av hver per-prosjekt-kjøring hentes topp-5 mest like historiske dommer og injiseres som few-shot via VerdictStore-ContextProvider. Ingen parameter-oppdatering.
+4. **Kalibrér LLM-as-judge mot menneskedommer** (LangSmith-flywheel): menneskelige korreksjoner forbedrer evaluatoren, ikke modellvektene. Spotify-produksjon (>1500 PR-er) validerte hybrid deterministisk + LLM-judge: judge fanget ~25 % problematiske, hvorav ~50 % korrigerbare. Kilde: https://www.zenml.io/llmops-database/...
+
+**Persistens:** all HITL-state til `CosmosCheckpointStorage` for fler-dagers review-sykluser uten compute-kost (pending requests re-emitteres ved resume). **Fine-tuning-trigger-policy:** ikke fine-tune før (a) ≥~1000 stabile merkede dommer, (b) retrieval+few-shot har platået i A/B-test, (c) shadow-mode-datasett er akkumulert. Kilde: https://www.truefoundry.com/blog/prompting-fine-tuning-or-rag
+
+**Åpne risikoer (verifisert/flagget):** Foundry-memory er preview (ikke primær verdict-store for produksjon, sjekk GDPR/dataresidens for norsk offentlig sektor); konfliktende ekspertdommer trenger en konfliktløsningsregel før de entrer storen; små-N-feedback kan forsterke ekspertbias.
+
+## 8. Claude Agent SDK-mønstre å porte → MAF
+
+| Claude-mønster | MAF-ekvivalent | Status / korreksjon |
+|---|---|---|
+| Skills (folder, progressiv disclosure) | Agent Skills (`agentskills.io`) | Direkte. Men **fire** stadier, ikke tre |
+| Subagents (Task/Agent) | Agent-as-tool (`AsAIFunction()`/`as_tool()`) eller Concurrent | Mønster OK. **Korreksjon:** `AIFunctionFactory.Create()` er for vanlige funksjoner, IKKE agent-registrering |
+| Hooks (PreToolUse/PostToolUse) | Middleware (`.Use()`) + ContextProvider (`InvokingAsync`/`InvokedAsync`) | Verifisert. Ingen filsystem-hooks i MAF |
+| Stop hook (tving fortsettelse) | **Gap** — Magentic stall-detection / while-loop i Functional API | Delvis gap. «BUILD 2026 HarnessAgent»-attribusjonen er delvis uverifisert |
+| Dynamic workflows (modell skriver orkestrering) | Graf-WorkflowBuilder (fan-out/fan-in) + Durable Task | Fixed-topologi dekket; **runtime-modellgenerert orkestrering: ingen ekvivalent** |
+| Adversarial verify | Group Chat / sequential handoff | Achievable, må kodes eksplisitt |
+| MCP-integrasjon | `MCPStdioTool`/`MCPStreamableHTTPTool`/`MCPWebsocketTool` + `as_mcp_server()` | Verifisert |
+| Context compaction | `CompactionProvider` (SlidingWindow/Truncation/summarization) | Verifisert |
+| Agent harness loop | Agent Harness (ShellExecutor, FileMemoryStore, ToolApprovalAgent) | Verifisert (BUILD 2026, 3. juni); HITL-komponenten heter `ToolApprovalAgent` |
+| Magentic-style manager | Magentic (`MagenticBuilder`, `StandardMagenticManager`) | Verifisert. **«based on», ikke «direct port»**. Eksperimentell |
+| A2A interop | `A2AAgent` / `A2AExecutor` | Verifisert; pakke pre-release. Hver A2A-kall = HTTP-latency + distribuert feilhåndtering |
+| Session-management | `AgentSession` + ContextProvider | Verifisert |
+
+## 9. Prior art — gjenbruk vs. unngå
+
+**Gjenbruk:**
+- **FinOps-mønsteret** (Azure Cost Management + Copilot, Anodot, CloudZero): modnest hybrid AI + deterministisk anomalideteksjon; MCP mot billing-API-er. Gjenbruk hybrid-separasjonen. (Merk: tunet for strukturert, uniform billing-data — ikke direkte overførbart til heterogen prosjektdata uten redesign.) Kilde: https://wjaets.com/sites/default/files/fulltext_pdf/WJAETS-2025-0218.pdf
+- **Multi-agent debatt-forskning** (Du et al. 2024 ICML; Yin 2025 bygg/kost): trust-vektet konsensus med terskel θ∈[0.6, 0.7], trust-vekter som evolverer på historisk pålitelighet. Gjenbruk som aggregeringsmekanisme for checker-konvergens. Kilde: https://www.sciexplor.com/jbde/articles/jbde.2025.0018
+- **OR-LLM-Agent / ORPilot IR / mcp-solver / ProofOfThought (Z3)**: gjenbruk LLM→IR→deterministisk-kompilering direkte.
+- **ExpeL/ERL + LangSmith-flywheel + Spotify hybrid-verify**: gjenbruk for læringssløyfen.
+
+**Unngå:**
+- **Lukkede PPM/PMO-verktøy** (Epicflow, Planview, Celoxis): ingen agent-API, ingen brukerleverte metoder, behandler porteføljen som ett system. Unngå arkitektur-modellen; vårt premiss er *uavhengige* prosjekter med brukerleverte metoder.
+- **Akademisk RL-portefølje-optimering** (MDPI 2025): «tacit knowledge»-state-vektor er ikke praktisk operasjonaliserbar i software i dag. Unngå for MVP.
+- **Tunge abstraksjonslag** (LangChain-stil): hvert ekstra «pluggbart modul-lag» obskurerer debugging. Hold abstraksjonene tynne.
+
+## 10. Feilmoduser & hva vi BEVISST IKKE skal bygge (anti-scope)
+
+**Dokumenterte feilmoduser (baseline å slå):** 88 % av enterprise-AI-agenter når aldri produksjon; Gartner: >40 % av agentiske prosjekter kanselleres innen utgangen av 2027 (årsaker: infrastruktur/observabilitet, governance, uklar ROI — ikke modellkvalitet). Token-blow-up er strukturelt undervurdert. Multi-agent kontekstvinduer vokser multiplikativt per handoff. Hallusinasjon på finans/numerikk er strukturelt uunngåelig (9–88 % avhengig av domene). Kilde: https://www.gartner.com/en/newsroom/press-releases/2025-06-25-gartner-predicts-over-40-percent-of-agentic-ai-projects-will-be-canceled-by-end-of-2027
+
+**BEVISST IKKE bygge (anti-scope):**
+- **Ikke** en generisk «analysemodul-markedsplass» der brukere komponerer fritt uten å oppgi termineringskontrakt, feedback-skjema og data-access på forhånd. Onboarding skal være et konfigurasjons-intervju som tvinger frem disse FØR noen agent kjører.
+- **Ikke** Magentic som default multi-agent-mønster (eksperimentell, ingen hard terminering by default).
+- **Ikke** A2A som default for kryss-prosjekt-orkestrering med mindre prosjektene trenger sikkerhets-/compliance-grense (HTTP-latency, state-tap ved restart). Bruk in-process agent-as-tool først.
+- **Ikke** budsjett-circuit-breakers som valgfri brukerkonfig — rammeverket skal nekte å starte uten eksplisitte token/kost-tak.
+- **Ikke** la deterministisk validering være en anbefalt plugin — den skal være arkitektonisk obligatorisk og blokkerende.
+- **Ikke** et generisk «plug in your HITL»-hook — feedback-skjemaet er den mest domenespesifikke delen og MÅ være brukerlevert og strukturert.
+- **Ikke** fine-tuning før retrieval-taket er nådd.
+
+## 11. Verifiseringslogg — nøkkelpåstander med verdikt
+
+| # | Påstand | Verdikt |
+|---|---|---|
+| 1 | Fem orkestreringsmønstre; Group Chat/Magentic for debatt; maker-checker-loops anbefalt | **Verifisert** |
+| 2 | Group Chat-mekanikk (delt historikk, `ShouldTerminateAsync`/`MaximumIterationCount`, Python-lambda) | **Verifisert** — MEN «limit to ≤3 agents» er **IKKE verifisert / sannsynlig hallusinasjon** |
+| 3 | Magentic eksperimentell/utestet utenfor Magentic-One | **Verifisert** |
+| 4 | Magentic stoppkriterier (`max_round/stall/reset_count`) + progress ledger | **Verifisert** |
+| 5 | HITL-mekanikk (tool approval, RequestPort, plan review) | **Delvis** — «all resume via `SendResponseAsync`» er **feil** (C#-only; Python bruker `responses={...}`) |
+| 6 | MAF har INGEN innebygd feedback-persistering til fremtidige kjøringer | **Verifisert** |
+| 7 | Python 1.8.0 stabil / C# rc2; Python foran på Functional API m.m. | **Delvis** — `HarnessAgent`/`A2AAgentSession` kom i **1.7.0**, ikke 1.8.0 (feilattribusjon) |
+| 8 | Skills: identisk progressiv disclosure med Claude | **Delvis** — er **fire** stadier, ikke tre; «GitHub Copilot Cowork» som produktnavn **uverifisert** (heter «GitHub Copilot») |
+| 9 | Subagents → agent-as-tool | **Delvis** — `AIFunctionFactory.Create()`-detaljen er **feil** (bruk `AsAIFunction()`/`as_tool()`) |
+| 10 | Hooks → middleware + context providers | **Verifisert** (nyanse: `ApprovalRequiredAIFunction` er kooperativ markør, ikke hard enforcement) |
+| 11 | Stop hook → ingen direkte MAF-ekvivalent | **Delvis** — gapet er reelt; «BUILD 2026»-kilde-URL og -attribusjon **uverifisert**; SRE Agent har slik hook (ikke MAF-SDK) |
+| 12 | Dynamic workflows → fan-out/fan-in + Durable Task; ingen runtime-modellgenerering | **Verifisert** |
+| 13 | Agent Harness (ShellExecutor, FileMemoryStore, ToolApprovalAgent) | **Verifisert** |
+| 14 | Magentic = MAF-port av Magentic-One | **Verifisert med korreksjon** — «based on / inspired by», IKKE «direct port» |
+
+**Uverifiserte påstander brukt i kontekst som bør kildes før de går i arkitekturdokument:** «kun ~16 % av enterprise-deployeringer er ekte agenter» (ikke funnet i primærkilde; nær-data finnes: Gartner <5 % apps med innebygde agenter i 2025). Praktiker-tall (chunking-nøyaktighet, hallusinasjons-prosenter, FinOps-besparelser) er **medium confidence** (ikke Microsoft-primærkilder).
+
+## 12. Åpne spørsmål til bruker
+
+1. **Språkstack:** Python-først (anbefalt) godtatt, eller kreves .NET (f.eks. enterprise-interop)? Påvirker tilgang til Functional API, Neo4j-memory (Python-only) og `intermediate_output_from`.
+2. **Deploy-mål:** Selvhostet/open-source-only, eller er Azure (Cosmos, AI Search, Durable Task, Foundry) tilgjengelig? Mye av produksjons-persistens og agentic retrieval er Azure-sentrisk. Påvirker også om YAML-deklarative workflows kan kjøres uten Foundry.
+3. **Review-latensbudsjett:** Svarer eksperten innen minutter (synkron HITL) eller timer/dager (checkpoint-basert async + varsling via e-post/Teams/webhook — som MAF ikke gir nativt)?
+4. **Antall/variabilitet av prosjekter:** Kjent og fast ved design-tid (fast Group Chat/Concurrent-topologi holder), eller ukjent/sterkt varierende (kan kreve dynamisk orkestrering — et reelt gap)?
+5. **Datasensitivitet:** Norsk offentlig-sektor-data — kreves minimum-eksponering (lokal-only stdio-MCP, lokale embeddings)? Påvirker hele dataintegrasjonslaget.
+6. **Skjema-eierskap:** Skal vi definere og eie data-source- og feedback-skjemaet selv nå, eller vente på et MAF-native prosjekt-config-format?
+7. **Feedback-skjema:** Hvem (rolle/antall eksperter per domene) leverer dommer, og finnes en omforent rejection-taksonomi (`wrong_assumption`, `overestimated_savings`, `constraint_violation`, `out_of_scope`)?
+
+## 13. Anbefalt høynivå-arkitektur + neste steg
+
+**Arkitektur (ett avsnitt):** En MAF-orkestrator fan-out-er per uavhengig prosjekt via `ConcurrentBuilder` (eller Durable Task fan-out), med streng state-isolasjon (fersk `WorkflowBuilder`-instans per kjøring via helper-method). Hvert prosjekt kjører en per-prosjekt-workflow som starter single-agent-baseline og eskalerer til en **Group Chat maker-checker-debatt** kun ved dokumentert behov. Brukerleverte analysemetoder lastes som **Agent Skills** (`SKILL.md` + deterministiske `scripts/`). Data nås via **MCP-servere** og injiseres som citation-aware RAG via en custom **AIContextProvider**. AI genererer kandidater som en **typet IR**; en **obligatorisk, blokkerende deterministisk valideringsekzekutor** (Pydantic + OR-Tools/`mcp-solver`/Z3 + Monte Carlo P10/P50/P90) avgjør tallene. Validerte forslag gates av en **to-lags HITL** (plan review + forslagsgodkjenning); ekspertdommer persisteres til en ekstern **VerdictStore** og hentes som few-shot ved neste kjøring (**ExpeL-læring uten fine-tuning**). Harde, deterministiske **stoppkriterier** og **budsjett-circuit-breakers** er obligatoriske ved oppstart; alt instrumenteres med **OpenTelemetry** og **checkpointing** (Cosmos) for fler-dagers HITL.
+
+**Komponenter:**
+- **Orchestrator:** `ConcurrentBuilder` fan-out per prosjekt + FanIn-aggregering; state-isolasjon enforced.
+- **Per-prosjekt-workflow:** single-agent-baseline → (ved behov) Group Chat maker-checker; deterministisk termineringskontrakt.
+- **Skill-loader:** Agent Skills-provider; brukerleverte `SKILL.md` + sandboxet script-runner (IKKE `SubprocessScriptRunner` i prod).
+- **Data-access-lag:** MCP-servere per kilde + custom AIContextProvider (citation-aware) + JSON-Schema-validert data-source-config.
+- **Hybrid-validator:** Pydantic-skjema → solver/Z3/MC som Function Tools → blokkerende valideringsekzekutor + self-repair-loop.
+- **HITL-gate:** plan review + `request_info()`/tool approval; Cosmos-checkpointing; ekstern varsling.
+- **VerdictStore + ContextProvider:** vektor-embeddede dommer; topp-K-retrieval; LLM-as-judge kalibrert mot menneskedommer.
+- **Guardrails:** budsjett-circuit-breaker, stoppkriterie-event-emittering, OpenTelemetry-tracing som deploy-gate, provenance-logg (source-stamping).
+
+**Anbefalt NESTE steg (i rekkefølge):**
+1. **Prototype-test (ukritisk for hele designet):** bygg en 3-agent Group Chat maker-checker (proposer, critic, validator) i Python på ett syntetisk prosjekt; mål konvergensrate, stall-frekvens og tokenforbruk mot single-agent-baseline. Dette validerer kjernevalget Group Chat-over-Magentic empirisk.
+2. **Kode-test av footguns:** verifiser (a) Magentic-terminering når alle limits er `None`, og (b) state-isolasjon i `ConcurrentBuilder` fan-out fra delt builder.
+3. **Spike VerdictStore-ContextProvider** med ExpeL-retrieval på 10–20 syntetiske dommer.
+4. **Definer data-source- og feedback-skjema** (JSON Schema) + onboarding-intervjuet som tvinger frem termineringskontrakt, feedback-skjema og data-access.
+5. **Avklar de syv åpne spørsmålene** (særlig språkstack, deploy-mål og datasensitivitet) før arkitekturen låses.
+
+---
+
+## 14. Modell-backend: Foundry-binding og per-agent modellvalg
+
+*(Lagt til etter syntesen, fra egen grunngitt sjekk mot offisiell MAF-dok — dekker brukerkravet om Microsoft Foundry + modellvalg, som ikke var en egen research-gren.)*
+
+**Kjernefunn (high confidence):** En MAF-agent er ikke en modell — den **bindes til en chat-client**, og modellen er en parameter på klienten. Det gjør modellvalg førsteklasses og per-agent.
+
+- **Python:** `FoundryChatClient(project_endpoint=..., model="gpt-4o-mini", credential=...)` kobler mot en deployert modell i et Foundry-prosjekt (Responses-endpoint). Støtter tools, structured outputs, streaming. Kilde: https://learn.microsoft.com/agent-framework/agents/providers/microsoft-foundry
+- **To Foundry-mønstre (reelt arkitekturvalg):**
+  - **Responses Agent** (`ChatClientAgent` via `AsAIAgent(...)`): appen eier modell + instruksjoner + tools på runtime; ingen server-side agent-ressurs. Brukt i de fleste eksempler — fleksibelt.
+  - **Foundry Agent** (`FoundryAgent`, versjonert): server-styrt; agentdefinisjoner opprettes/versjoneres i Foundry-portalen eller via `AgentAdministrationClient`. For streng, versjonert governance.
+- **Modellkatalog:** Modeller deployes/velges fra Foundry-modellkatalogen (`ai.azure.com/catalog/models`): Azure-OpenAI (GPT-4.x/5.x), partner/community, Hugging Face managed compute, og BYOM-endpoints. `azd ai agent init` spør eksplisitt om hvilken modell.
+- **Provider-bredde:** MAF-oversikten lister Foundry, Azure OpenAI, OpenAI, Ollama og Anthropic. **Forbehold (ikke fullt verifisert):** AutoGen-migreringstabellen merker Anthropic/Ollama som «🚧 Planned» — Foundry/Azure OpenAI/OpenAI er solide; Anthropic/Ollama-direkte må sjekkes mot gjeldende versjon før det loves. (Function tools fungerer på Anthropic per §11.)
+
+**Konsekvens for designet:** Siden modellen settes per chat-client, kan **hver agent i samarbeidet bruke sin egen modell** — billig modell til ruting/henting, sterk modell til den tunge resonneringen, evt. en egen til den deterministiske validatoren. Dette blir en **eksplisitt, brukerkonfigurerbar del av onboardingen**: en «modell-map» (rolle → Foundry-deployment) ved siden av data-source-konfigen (§6). Det gjør kost/kvalitet til en knapp brukeren kan vri på uten kodeendring, og speiler prinsippet om å matche modell til oppgavekompleksitet.
+
+**Åpent (kobler til §12):** Responses Agent vs Foundry Agent (governance-behov), og om deploy-målet overhodet har Foundry tilgjengelig (selvhostet open-source vs Azure).
+
+---
+
+## 15. Implementeringsregister — alt vi må BRUKE, BYGGE, VOKTE, GJENBRUKE eller UNNGÅ
+
+Sporbar sjekkliste. Status: **USE** = MAF-konstrukt vi bygger på · **BUILD** = gap vi må implementere selv · **GUARD** = footgun/risiko å sikre · **REUSE** = ekstern lib/spec · **AVOID** = anti-scope · **FIX** = korreksjon fra verifisering (ikke kod feil variant). Verifisert = bekreftet mot offisiell primærkilde i §11.
+
+### 15.1 MAF-kapabiliteter vi SKAL BRUKE (USE — verifisert)
+
+| ID | Kapabilitet | MAF-konstrukt / API | Kilde | Verifisert |
+|----|-------------|---------------------|-------|:---------:|
+| U1 | Orkestrator fan-out per prosjekt | `ConcurrentBuilder` / `AgentWorkflowBuilder.BuildConcurrent()` + FanIn-aggregering | …/workflows/orchestrations/concurrent | ✅ |
+| U2 | Per-prosjekt graf-workflow | `WorkflowBuilder` (fan-out/fan-in, conditional/switch-case-edges, superstep, typesikkerhet) | …/workflows/edges | ✅ |
+| U3 | Debatt-mønster (maker-checker) | `GroupChatBuilder`; C# `RoundRobinGroupChatManager.ShouldTerminateAsync` + `MaximumIterationCount`; Python `termination_condition`-lambda | …/orchestrations/group-chat | ✅ |
+| U4 | Åpne delsteg (kun ved behov) | Magentic: `MagenticBuilder`/`StandardMagenticManager`; `max_round_count`/`max_stall_count`/`max_reset_count`; progress ledger | …/orchestrations/magentic | ✅ |
+| U5 | Brukerleverte metoder | Agent Skills: `skills/<navn>/SKILL.md` + `scripts/` + `references/` + `assets/`; `SkillsProvider` (Py) / `AgentSkillsProvider` (C#); `McpSkillsSource` (Py 1.8.0) | …/agents/skills | ✅ (4 stadier, se F1) |
+| U6 | Datatilgang | MCP-tools: `MCPStdioTool` / `MCPStreamableHTTPTool` / `MCPWebsocketTool`; eksponer agent som server via `as_mcp_server()` | …/agents/tools/local-mcp-tools | ✅ |
+| U7 | Solver/validator/Monte Carlo som verktøy | Function Tools (alle store providere, inkl. Anthropic) | …/agents/tools/ | ✅ |
+| U8 | Intercept av tool-calls (blokkerende validator) | Middleware-pipeline `.Use()`; `FunctionMiddleware` (`InvokingAsync`/`InvokedAsync`) | …/agents/agent-pipeline | ✅ |
+| U9 | Læringssløyfe-injeksjon | Custom `ContextProvider` / `HistoryProvider` | …/agents/conversations/context-providers | ✅ |
+| U10 | Vektorlagre | Azure AI Search, Cosmos, Qdrant, Redis, Postgres (innebygde abstraksjoner) | …/integrations/ | ✅ |
+| U11 | Citation-aware RAG-injeksjon | Custom `AIContextProvider`; `TextSearchProvider` (C#, `SourceName`/`SourceLink`); Azure AI Search agentic retrieval (GA 2026-04-01) | …/agents/rag | ✅ |
+| U12 | Persistens / kræsj-overlevelse | Checkpointing (InMemory/File/Cosmos), pending HITL re-emitteres ved resume; Durable Task-extension for langvarig HITL | …/workflows/checkpoints | ✅ |
+| U13 | HITL-gates | Tool approval (`@tool(approval_mode='always_require')` Py / `ApprovalRequiredAIFunction` C#); `RequestPort`/`request_info()`; `MagenticPlanReviewRequest`/`.approve()`/`.revise()` | …/workflows/human-in-the-loop | ✅ (se F2) |
+| U14 | Observabilitet (deploy-gate) | OpenTelemetry (GenAI-konvensjoner) | …/agents/observability | ✅ |
+| U15 | Evaluering | `LocalEvaluator`, `evaluate_workflow()`, Foundry Adaptive Evals | …/agents/evaluation | ✅ |
+| U16 | Kontekst-kompaktering | `CompactionProvider` (SlidingWindow/Truncation/summarization) | …/integrations/ | ✅ |
+| U17 | Agent-som-verktøy | `AsAIFunction()` (C#) / `as_tool()` (Py) — IKKE `AIFunctionFactory.Create()` | …/agents/tools/ | ✅ (se F3) |
+| U18 | Modell-backend + per-agent modellvalg | `FoundryChatClient(project_endpoint, model, credential)`; Responses Agent vs Foundry Agent | …/agents/providers/microsoft-foundry | ✅ (§14) |
+| U19 | Harness-mønstre (bakgrunn/loop) | Agent Harness: `ShellExecutor`, `FileMemoryStore`, `ToolApprovalAgent` (Py 1.7.0) | python-2026-significant-changes | ✅ |
+
+### 15.2 Mønstre vi MÅ BYGGE SELV (BUILD — gap, ikke i rammeverket)
+
+| ID | Hva | Hvorfor (gap) | Skisse |
+|----|-----|---------------|--------|
+| B1 | **Blokkerende hybrid-validator** | Deterministisk verdikontroll er ikke en MAF-primitiv | LLM → typet IR (Pydantic) → skjema-validering (field + kryss-felt `@model_validator`) → solver (OR-Tools/PuLP/Z3 / `mcp-solver`) → Monte Carlo P10/P50/P90 → self-repair (maks N forsøk). Forslag som feiler **blokkeres strukturelt** fra eksperten. |
+| B2 | **VerdictStore + ExpeL-læringssløyfe** | MAF har INGEN feedback-til-fremtidige-kjøringer (verifisert) | Persistér (forslag, dom, begrunnelse, embedding, prosjekttype, domene) → topp-K-retrieval via custom `ContextProvider` → few-shot-injeksjon. LLM-as-judge kalibrert mot menneskedommer. Ingen fine-tuning før ≥~1000 stabile dommer + retrieval-platå. |
+| B3 | **To-lags HITL** | Sammenstilling av plan-review + forslagsgate er vår logikk | (a) pre-eksekusjon plan-godkjenning; (b) post-eksekusjon forslagsgate (`request_info()` / tool approval på `emit_savings_proposal`). |
+| B4 | **Termineringskontrakt + budsjett-circuit-breakers** | Magentic-limits defaulter til `None` (ubegrenset); ingen kost-tak by default | Krev eksplisitte verdier ved oppstart (fail-fast hvis mangler): `max_iterations`, `max_stall`, `cost_budget_tokens`, wall-clock-timeout. Alle brudd → strukturert event (aldri stille stopp). |
+| B5 | **Generisk data-source-konfig** | Ingen MAF-native prosjekt-config | JSON Schema, diskriminert union på `type` (`local_folder`/`mcp_server`/`azure_ai_search`/`rag_api`) + ingestion-blokk (chunking ~400–512 tokens, 10–20 % overlap). Valider, fail fast. |
+| B6 | **Provenance / sporbarhet** | Ingen MAF-native provenance-standard | Melding-source-stamping (`AgentRequestMessageSourceType`) + egen logg; hvert forslag sporer til kildedata. |
+| B7 | **State-isolasjon i fan-out** | Delt `WorkflowBuilder` korrumperer state | Fersk builder-instans per kjøring via helper-method + `IResettableExecutor`. |
+| B8 | **Sandboxing av brukerleverte skill-scripts** | `SubprocessScriptRunner` er «demonstration only» | Egen produksjons-sandbox (container/jail) for `scripts/` i brukerleverte skills. |
+| B9 | **Onboarding-intervju** | Tvinger frem kontrakter FØR noen agent kjører | Samle: termineringskontrakt, feedback-skjema, data-access, modell-map. |
+| B10 | **Feedback-skjema + rejection-taksonomi + konfliktregel** | Mest domenespesifikke delen; må være brukerlevert og strukturert | Taksonomi (`wrong_assumption`/`overestimated_savings`/`constraint_violation`/`out_of_scope`) + regel for konfliktende ekspertdommer før de entrer storen. |
+| B11 | **Ekstern varsling for async HITL** | MAF gir ikke varsling nativt | E-post/Teams/webhook ved pending review (fler-dagers sykluser). |
+| B12 | **Modell-map (rolle → Foundry-deployment)** | Per-agent modellvalg som brukerknapp | Konfig ved siden av data-source-config; billig modell til ruting, sterk til resonnering. |
+
+### 15.3 Footguns / risikoer å VOKTE (GUARD — verifisert)
+
+| ID | Risiko | Tiltak |
+|----|--------|--------|
+| G1 | Magentic-limits = `None` (ubegrenset) | B4: krev eksplisitte verdier, fail-fast |
+| G2 | Delt `WorkflowBuilder` → state-korrupsjon i fan-out | B7: fersk instans + `IResettableExecutor` |
+| G3 | `SubprocessScriptRunner` = demo-only | B8: ekte sandbox |
+| G4 | `ApprovalRequiredAIFunction` er **kooperativ markør**, ikke hard enforcement | Håndhev godkjenning i invoker-koden, ikke stol på markøren |
+| G5 | Foundry-memory er **Preview** | Ikke primær verdict-store i prod; sjekk GDPR/dataresidens for norsk offentlig sektor |
+| G6 | Små-N-feedback forsterker ekspertbias | Konfliktregel (B10) + terskel før heuristikk-distillering |
+| G7 | Token-blow-up vokser multiplikativt per handoff | Single-agent-baseline først; budsjett-breakers (B4); kontekst-kompaktering (U16) |
+| G8 | Functional `@workflow` og Magentic er **eksperimentelle**; Functional er Python-only | Ikke bygg kjerneflyt på eksperimentelle API uten fallback |
+
+### 15.4 Eksterne biblioteker / spec å GJENBRUKE (REUSE)
+
+| ID | Ressurs | Bruk | Kilde |
+|----|---------|------|-------|
+| R1 | `mcp-solver` (MIT) | MiniZinc/Z3/PySAT som MCP-verktøy — solver-i-loopen | github.com/szeider/mcp-solver |
+| R2 | OR-Tools / PuLP / Z3 | Optimering/feasibility som Function Tool | — |
+| R3 | OR-LLM-Agent + ORPilot IR | LLM→typet IR→deterministisk kompilering (85 % løsningsnøyaktighet) | arxiv.org/html/2503.10009v1 |
+| R4 | ExpeL (AAAI 2024) | Erfarings-distillering uten fine-tuning | arxiv.org/html/2308.10144v2 |
+| R5 | `agentskills.io`-spec | Kryss-vendor skill-format (samme som Claude Code) | learn.microsoft.com/agent-framework/agents/skills |
+| R6 | `modelcontextprotocol/server-filesystem` | Lokale filer som MCP-kilde | — |
+| R7 | LangSmith LLM-as-judge-flywheel | Kalibrere judge mot menneskedommer | langchain.com/resources/llm-as-a-judge |
+| R8 | Multi-agent debatt-konsensus (Du et al. 2024; Yin 2025) | Trust-vektet konsensus (θ≈0.6–0.7) for checker-konvergens | sciexplor.com/jbde/articles/jbde.2025.0018 |
+
+### 15.5 Anti-scope — BEVISST IKKE bygge (AVOID)
+
+| ID | Ikke bygg | Hvorfor |
+|----|-----------|---------|
+| A1 | Fri «analysemodul-markedsplass» uten påkrevd kontrakt | Onboarding må tvinge termineringskontrakt + feedback-skjema + data-access FØR kjøring |
+| A2 | Magentic som default multi-agent-mønster | Eksperimentell; ingen hard terminering by default |
+| A3 | A2A som default for kryss-prosjekt | HTTP-latency + state-tap; bruk in-process agent-as-tool først (kun A2A ved sikkerhets-/compliance-grense) |
+| A4 | Budsjett-breakers som valgfri konfig | Rammeverket skal NEKTE å starte uten token/kost-tak |
+| A5 | Deterministisk validering som «anbefalt plugin» | Skal være arkitektonisk obligatorisk og blokkerende |
+| A6 | Generisk «plug in your HITL»-hook | Feedback-skjemaet er domenespesifikt og MÅ være brukerlevert |
+| A7 | Fine-tuning før retrieval-taket er nådd | Premaur kostnad; ExpeL-retrieval først |
+| A8 | Lukket-PPM-arkitektur (Epicflow/Planview-modell) | Behandler porteføljen som ett system; vårt premiss er uavhengige prosjekter |
+
+### 15.6 Korreksjoner fra verifisering — ikke implementér feil variant (FIX)
+
+| ID | Feil påstand (forkast) | Riktig (implementér dette) |
+|----|------------------------|----------------------------|
+| F1 | Skills = 3 stadier progressiv disclosure | **4 stadier:** Advertise → Load → Read resources → Run scripts |
+| F2 | All HITL-resume via `SendResponseAsync` | C# workflow: `SendResponseAsync`; **Python: `responses={request_id: ...}` til `workflow.run(...)`**; standalone-agent: ny melding |
+| F3 | Agent-som-verktøy via `AIFunctionFactory.Create()` | **`AsAIFunction()` (C#) / `as_tool()` (Py)**; `AIFunctionFactory.Create()` er for vanlige funksjoner |
+| F4 | «Begrens Group Chat til ≤3 agenter» (offisiell warning) | **Finnes ikke i dok** — sannsynlig hallusinasjon; ingen tallfestet agent-grense |
+| F5 | `HarnessAgent`/`A2AAgentSession` kom i Python 1.8.0 | Kom i **1.7.0**; 1.8.0 = `McpSkillsSource`, Foundry Adaptive Evals m.m. |
+| F6 | Magentic = «direct port» av Magentic-One | «**based on / inspired by**»; eksperimentell, utestet utenfor original-design |
+| F7 | «BUILD 2026 HarnessAgent»-devblog som kilde | Kilde-URL **ikke verifiserbar**; Azure SRE Agent (eget produkt, ikke MAF-SDK) har Stop-hook-ekvivalent |
+| F8 | «~16 % av enterprise-deployeringer er ekte agenter» | **Ikke funnet i primærkilde** (medium/lav confidence); nær-tall: Gartner <5 % apps med innebygde agenter 2025 |