# 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. |
| D5 | **90%-prinsipp** | Sluttproduktet funker aldri 100 % for noen. Bygg ~90 % generisk kjerne + tydelige extension points; jakt IKKE de siste 10 %. Kompetente folk konfigurerer siste mil per kunde. |
| D6 | **Kostnadsdisiplin** | Privat MS-tenant tilgjengelig (gjør Azure/Foundry-profilen testbar), MEN kostnadstak: utvikle primært på **lokal profil** (gratis); Foundry/Azure kun til målrettet, minimal verifisering; spikes på billigste modeller + bittesmå syntetiske data + harde token-/runde-tak. Ingen tunge test-kjøringer. |

## 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).
- **Kostnadsdisiplin (D6):** lokal profil er default under utvikling; Foundry-kjøringer er målrettede og minimale. Hver spike måler og rapporterer tokenforbruk; harde tak håndheves.
- 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.