docs(plan): session-by-session execution plan from the 2026-07-02 status analysis

Sequences the decided arc (R1 extraction -> D7 sibling -> comparison) into
12 single-session increments (S1-S12), folding in the analysis findings:
truth maintenance (S1), the missing shared method spec (S2), extraction
de-risking + comparison protocol (S3), and per-session verification
criteria + key-assumption tests. Target picture stays the frozen north star.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PAnzFPa9KXqjQEkw9q5Zs

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

@@ -0,0 +1,222 @@
+# 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.