From 84d19c97d6dfceda32893d084a38ef8e59e48035 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Thu, 2 Jul 2026 17:11:10 +0200 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_015PAnzFPa9KXqjQEkw9q5Zs --- docs/plan/2026-07-02-sesjonsplan.md | 222 ++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 docs/plan/2026-07-02-sesjonsplan.md diff --git a/docs/plan/2026-07-02-sesjonsplan.md b/docs/plan/2026-07-02-sesjonsplan.md new file mode 100644 index 0000000..d860373 --- /dev/null +++ b/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.