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, 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); 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.