portfolio-optimiser/docs/plan/2026-07-02-sesjonsplan.md

# Sesjonsplan — fra statusanalyse til sammenligning (2026-07-02)

> **Hva dette er:** Program-nivåets øktkart fra statusanalysen 2026-07-02 (full gjennomgang av
> levert kode mot [målbildet](2026-06-26-maalbilde-agentic-loop.md), verifisert mot ground truth:
> suite 152/4 grønn, mypy/ruff rene, alle 8 loop-steg wiret + load-bearing). Målbildet forblir
> FROSSEN nordstjerne; denne planen erstatter ingen §-definisjoner — den sekvenserer veien til
> program-målet (§1: rettferdig sammenligning av to stacker på identisk delt kjerne).
> Hver økt under er scoped til å **fullføres innenfor én sesjon**.

## Rammer (gjelder alle økter)

- **Modell (operatørdirektiv 2026-07-02):** planens økter kjøres på **Opus 4.8 med xhigh
  reasoning effort** — også alle subagenter. (Scoped unntak fra Fable-5-defaulten satt samme dag;
  gjelder øktene i denne planen.)
- **Én økt = én lukket leveranse:** grønn suite, STATE.md overskrevet, commit + push til Forgejo
  før økta slutter. Aldri broken state over en øktgrense.
- **Kode-økter:** stram Plan-modus + TDD (Iron Law: ingen produksjonskode uten rød test først).
  Større faser kjører Voyage (`/trekbrief → /trekplan → /trekexecute → /trekreview`).
- **Kostnadsdisiplin (D6):** alt offline/deterministisk — unntatt S10 (den ene minimale
  API-kjøringen på Claude-siden) og S11s bruk av dens artefakter. MAF kjøres ALDRI mot ekte
  modell (låst 2026-06-30).
- **Operatør-gates:** S4 og S5 er repo-skapende → plan presenteres og bekreftes FØR utførelse.
  S12 gates på «ingen release før operatør er 100 % enig».
- **D7-øktene (S5–S10)** er et estimat på snittet; hver får egen `/trekbrief` som kan re-scope
  innenfor rammen «én økt = én lukket leveranse».

## Avhengigheter

S1 (uavhengig, tas først) → S2 og S3 (vilkårlig innbyrdes rekkefølge) → S4 → S5 → S6 → S7 → S8
→ S9 → S10 → S11. S12 sist, når operatør ønsker.

---

## S1 — Sannhetsvedlikehold (funn 4–7 + dokumenterte kutt)

**Mål:** Fjerne all dokumentasjons-usannhet og støy før noe ekstraheres eller deles. Kirurgisk —
ingen kodeatferd endres.

**Innhold:**
1. `CHANGELOG.md` omskrives sannferdig (sier i dag «Plan phase — no framework code yet» i et repo
   med 2 593 linjer kjerne og 152 tester).
2. `README.md` Stack-linje: meta-pakken `agent-framework` → de faktiske split GA-pakkene.
3. Prosjekt-`CLAUDE.md`: MCP-konvensjonen nedjusteres til det koden gjør («MCP = extension point,
   demonstrert via `build_mcp_server`; in-process `FunctionTool` er default-søm»).
4. Konfliktsemantikk for dommer dokumenteres som valgt (README-avsnitt + docstring i
   `verdicts.py`): store er first-write-wins per id; wiki-promotering er last-write-wins per fil.
   Full B10-taksonomi forblir bevisst utsatt til ekte eksperter finnes.
5. `docs/extending.md`: eksplisitt 90 %-kuttliste — B10 full taksonomi, B11 varsling
   (`notify`-stub i `run.py`), U12 checkpointing, U14 OTEL, concurrent fan-out.
6. `ruff format` på de 4 driftede filene (`backends.py`, `budget.py`, `verdicts.py`,
   `test_contracts.py`) som egen `chore:`-commit.
7. `git rm --cached docs/.DS_Store`; `.gitignore`-regel som dekker `.trekexecute-progress-*`.

**Verifisering:** `uv run pytest` 152/4 grønn · `uv run ruff format --check .` 0 filer ·
`git status` rent · grep bekrefter at stale CHANGELOG-linja og meta-pakke-referansen er borte ·
CLAUDE.md-diff viser MCP-omformuleringen.

## S2 — Metode-spec i `shared/` (målbilde §8, den fjerde delte artefakten)

**Mål:** Metoden skal kunne implementeres fra spec alene — D7 skal ikke reverse-engineere
MAF-koden. Lukker funn 1 (spec står som «(planned)» i `shared/README.md`).

**Innhold:** Forfatt `shared/method-spec.md`, framework-nøytral (prosaen nevner aldri et konkret
framework — samme regel som persona-SKILL.md): 8-stegs-loopen normativt; verdict-JSON-kontrakten
(binær decision på run-stien); inbox/outbox-mappekontrakten (tolerant last, id verbatim, systemet
leser / eksperten skriver); promoteringsgate-semantikk (fail-closed, nøytral index-label, minimal
promotert fil); IR-projeksjon + golden-suite som eneste fasit; budsjett-/stopp-krav (fail-fast);
provenance-krav (validator_decision speiler kun validatoren). Verifiseringsplikt: hver normativ
påstand kryss-sjekkes mot eksisterende load-bearing tester/kode. Oppdater `shared/README.md`.

**Verifisering:** ny test i stil med persona-trioen: spec-fila finnes med gyldig struktur, og
framework-nøytralitets-guarden dekker den (grep-formet, rød på framework-navn i `shared/`) ·
kryss-sjekk-tabell i spec: felt i `example-verdict.json` ↔ spec-avsnitt, komplett.

## S3 — R1-forberedelse: konsummekanisme + sammenligningsprotokoll

**Mål:** De-riske ekstraksjonen (funn 2) og definere målestokken for sluttleveransen (funn 3) FØR
noe repo opprettes.

**Innhold:**
1. Konfigurerbar shared-rot: én resolver (env `PORTFOLIO_SHARED_ROOT`, default = dagens
   `parents[2]/shared`) brukt av både `persona.py:22` og `simulation.py:44`. Ny load-bearing
   test: override mot en tmp-kopi → markøren følger kopien (rød uten resolver).
2. `docs/plan/`-sammenligningsprotokoll (1–2 sider, framework-nøytral): metrikker
   (validator-samsvar mot golden, konvergens/runder, tokenforbruk, kvalitativ vurdering),
   identisk input = pinned commons-ref, og **eksplisitt liveness-asymmetri-erklæring** (MAF =
   skriptet offline-bevis; Claude-siden = minimal ekte API-kjøring) + hvordan LLM-ikke-determinisme
   håndteres i S10/S11.
3. Lokal dry-run av split (nøkkelantakelse 1): `git subtree split -P shared -b _dryrun` —
   ingen remote opprettes.

**Verifisering:** suite grønn + ny override-test bevist RØD ved detach ·
`git ls-tree -r _dryrun --name-only | wc -l` = 12 (nøyaktig de 12 rene datafilene) ·
protokoll-doc committet med asymmetri-erklæringen ordrett.

## S4 — R1: ekstraksjon av `shared/` → `portfolio-optimiser-commons` **[GATED]**

**Mål:** Delt kjerne som eget Forgejo-repo (besluttet R1, §9) — født komplett med alle fire
§8-artefakter (bundle, golden-suite, persona, metode-spec fra S2).

**Innhold:** Opprett `portfolio-optimiser-commons` på Forgejo; push split-historikken fra S3;
re-innfør `shared/` i dette repoet som **subtree av commons** (anbefalt over submodule:
offline-vennlig, stien uendret → testene upåvirket; commons = source of truth). Dokumentér
synk-kommandoene (subtree pull/push) i `shared/README.md`; oppdater prosjekt-CLAUDE.md.

**Verifisering:** commons-repo på Forgejo viser 12 filer + historikk (`git log` i commons ikke
tom) · i dette repoet: `uv run pytest` grønn UTEN testendringer · MAF-frihets-guarden fortsatt
grønn · én subtree-synk (pull ELLER push) demonstrert og loggført.

## S5 — D7-oppstart: søskenrepo på Claude Agents SDK **[GATED]**

**Mål:** Søskenrepoet eksisterer, konsumerer commons, og har kontraktene på plass — ingen
agent-kjøring ennå.

**Innhold:** Nytt Forgejo-repo (repo-init-skill); Python-scaffold med Claude Agent SDK
(søk-først: verifiser gjeldende SDK-API mot offisiell doc FØR skriving; grunnlag i
[MAF vs Claude Agent SDK](../research/2026-06-24-maf-vs-claude-agent-sdk.md)); egen CLAUDE.md +
STATE.md; commons inn som subtree; fail-fast oppstartskontrakter (speiler `contracts.py`-rollen:
data-source, modell-map, terminering, feedback).

**Verifisering:** `uv run pytest` kjører grønt · commons-innhold på plass (12 filer) ·
kontrakts-tester grønne (avvis manglende tak, avvis tredje decision-verdi) · ingen API-nøkkel
nødvendig for suiten.

## S6 — D7 deterministisk ryggrad

**Mål:** Egen validator-implementasjon + budsjett-tak + provenance, med golden-suiten som eneste
fasit (nøkkelantakelse 3).

**Innhold:** TDD mot `validator-input.json`/`golden.json`: IR-projeksjon → deterministisk solve +
Monte Carlo (eller ekvivalent deterministisk metode som reproduserer golden-utfallene);
`Rejection` som egen ukonsumerbar type; budsjett nektes uten positive tak; provenance-stamp.

**Verifisering:** golden-suite-test grønn på alle besluttede felt · mutasjonskontroll: én endret
parameter i input → rød · tak-test: oppstart uten budsjett feiler fail-fast.

## S7 — D7 kontekst-søm (OKF-navigasjon + ExpeL-fold)

**Mål:** Steg 1 på Claude-siden: kontekst ved navigasjon (aldri stuffing), verdict-laget gated ut,
tidligere dommer når prompten KUN via folden.

**Innhold:** Port av `okf.py`-metoden (ren stdlib, D7-portabel by design) til søskenrepoet;
`bundle_context`-ekvivalent + seed-fra-bundle + fold-før-generering.

**Verifisering:** speilpar av MAF-ens load-bearing-tester: (a) realiseringsmarkør når prompten via
folden, rød ved detach; (b) verdict-laget lekker aldri via lese-konteksten; tom-store-kontroll.

## S8 — D7 agentisk loop (maker-checker + gate + informert refinement)

**Mål:** Steg 2–5 på Claude Agents SDK: hypotese-generering, maker/checker-debatt der checkeren
faktisk gater (VERDICT-markør, opt-in-reject), og validator-grunn inn i neste forsøk under
eksisterende tak. Offline (skriptet klient-stand-in for test, som MAF-siden).

**Verifisering:** speiltester: checker-REJECT flipper et ellers validert utfall (rød uten
override) · refinement-testen: forrige `Rejection.reason` verbatim i neste prompt + utfallet
flipper (rød ved detach) · tak-kontroll: løkka stopper på max_attempts.

## S9 — D7 læringssløyfe (inbox + promoteringsgate + persona)

**Mål:** Steg 7+8 på Claude-siden, med personaen instansiert fra den DELTE `SKILL.md`-artefakten
via egen loader (beviser at delt kjerne faktisk deles).

**Innhold:** verdict-inbox (tolerant last, merge, aldri skriv tilbake); fail-closed
promoteringsgate mot commons-bundelen; persona-loader mot `example-verdict.json`; to-runs
offline-bevis (sim-ekvivalent).

**Verifisering:** speiltester av step7/step8/persona-trioen (hver bevist RØD på sin detach) ·
to-runs-bevis: dom droppet etter Run A når Run B's prompt med fersk store; tom-inbox-kontroll.

## S10 — D7 minimal ekte API-kjøring (den genuine modell-atferden)

**Mål:** Den ENE ekte modell-kjøringen i hele programmet (per beslutning 2026-06-30 lever
genuint modell-bevis på Claude-siden): mikro-bundelen, billigste egnede Claude-modell (slås opp
via claude-api-skill i økta), harde token-tak.

**Innhold:** kjør loopen live én gang; fang artefakter (forslag-JSON, checker-dom, tokenforbruk,
validator-utfall) til S11; loggfør kost.

**Verifisering:** kjøringen fullfører innenfor forhåndssatt tak (taket + faktisk forbruk logget) ·
artefakter persistert i output-laget · determinisme-grensene håndtert slik protokollen (S3)
foreskriver · kost rapportert i STATE.

## S11 — Sammenligningen + rapport

**Mål:** Program-leveransen (§1): begge stacker målt på identisk commons-ref etter protokollen
fra S3; norsk rapport (forretningsdokument).

**Innhold:** kjør MAF offline-sim + D7 offline-speil på samme pinned commons-ref; sammenstill med
S10-artefaktene; rapport: metode-samsvar, validator-samsvar mot golden, utviklings-/
kompleksitetssammenligning, tokenkost, og asymmetri-erklæringen ordrett.

**Verifisering:** rapporten har verifiseringslogg (hver tallpåstand → kommando/kilde som
reproduserer den) · begge repo grønne på pinned ref · ingen påstand om live-atferd på MAF-siden.

## S12 — Release-hygiene begge repo **[INGEN HAST — GATED på 100 % enighet]**

**Innhold:** prepare-release-løpet: LICENSE, `[project.scripts]` (`run:main` + `simulation:main`),
CHANGELOG-poler, CONTRIBUTING/SECURITY, prominent D3-disclaimer, gitleaks-sjekk.

**Verifisering:** fersk klon + README alene → kjørbar simulering · gitleaks rent · inkrementell
plans Fase 4-kriterier grønne.

---

## Nøkkelantakelser (med eksplisitt test)

1. **`git subtree split` bevarer historikk og tar nøyaktig de 12 rene datafilene** → testes lokalt
   i S3 (dry-run branch) FØR noe remote opprettes i S4.
2. **Claude Agent SDK dekker primitivene** (subagenter, verktøy, budsjett-hooks) → grunnlag i
   research-doc 2026-06-24; re-verifiseres søk-først mot gjeldende SDK-doc i S5 (risiko: API-drift
   siden research).
3. **Golden-suiten er framework-nøytral fasit** → allerede bevist (MAF-testene konsumerer
   `validator-input.json`/`golden.json`); S6 gjenbruker uendret.
4. **Konfigurerbar shared-sti brekker ingen tester** → S3 beviser med grønn suite + ny
   load-bearing override-test før S4 flytter noe.

## Verifisering (planen som helhet)

- Ingen økt erklæres ferdig uten at øktas verifiseringskriterier over er kjørt og grønne.
- Program-sluttkriterium: S11-rapport levert med begge stacker på identisk delt kjerne,
  liveness-asymmetrien eksplisitt erklært, alle repo grønne — og ingen artefakt (README,
  CHANGELOG, CLAUDE.md, spec) påstår mer enn koden gjør.