portfolio-optimiser/docs/plan/2026-07-03-sesjonsplan-ingest.md

Sesjonsplan — ingest-programmet (2026-07-03)

Hva dette er: Program-nivåets øktkart for ingest-laget, avledet av målbildet for ingest (nordstjernen dette planverket realiserer) og program-briefen. Målbildet definerer «ferdig»; denne planen sekvenserer veien. Hver økt er scoped til å fullføres innenfor én sesjon. Programmet starter først etter operatør-godkjenning av målbildet.

Rammer (gjelder alle økter)

• Modell: Opus 4.8 med xhigh reasoning effort — for ALLE økter og alle subagenter; ingen Fable 5 (heller ikke Sonnet/Haiku). Operatørkorreksjon 2026-07-04: reverserer 2026-07-02-planens Fable-5-default; matcher den globale regelen (~/.claude/CLAUDE.md, «Modellvalg for subagenter»).
• É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). Hver økt får egen /trekbrief som kan re-scope innenfor «én økt = én lukket leveranse».
• Kostnadsdisiplin (D6): ALT offline — null modellkall i hele programmet (ingest er deterministisk; konnektorer testes kun mot fixtures/golden-uttrekk).
• Commons PULL-ONLY: spec-endringer skrives i commons-repoet og subtree-pulles. Enhver commons-/spec-endring utover I1 er en egen GATET runde — aldri foldet inn i en impl-økt.
• Operatør-gates: I1 (spec-/commons-endring), I3 og I5 (søskenrepoet røres), I6 (nettverks-kapabilitet innføres). S12 (release) er uavhengig av dette programmet og forblir gated på egne vilkår.

Avhengigheter

I1 → I2 → I3 → I4 → I5 → I6 → I7. (I6 avhenger teknisk kun av I2, men kjøres lineært etter I5 — enklere statehåndtering. I7 sist, avhenger av alle.)

---

I1 — Ingest-spec i commons [GATET: spec-/commons-endring]

Mål: Den framework-nøytrale kontrakten eksisterer i commons og er guardet i dette repoet — begge stackene kan implementere fra spec alene.

Innhold:

1. I COMMONS-repoet: forfatt shared/ingest-spec.md (framework-nøytral prosa — samme regel som method-spec): polymorft manifest-skjema for alle tre kildetyper (HTTP/MCP-delen som minimum, jf. målbildet §4), credential-referanse-regelen, verdict-lag-reservasjonen + lag-separasjonen (målbildet §3), provenance-frontmatter-kontrakten inkl. eksplisitt timestamp-argument (§5), index-genereringskravet (§2), golden-uttrekk-formatet (§9); kryss-sjekk-tabell felter ↔ avsnitt.
2. I DETTE repoet: git subtree pull --prefix=shared commons main --squash + utvid framework-guarden (tests/test_method_spec_loadbearing.py) til å dekke den nye fila.

Verifisering: guard-utvidelsen bevist RØD mot en throwaway-kopi med framework-navn injisert · begge repos suiter grønne etter pull (søskenets pull kan tas i I3 hvis søskenrepoet ikke røres i I1 — da gjelder «begge grønne» fra I3) · kryss-sjekk-tabellen komplett · uv run ruff check . + mypy grønne.

I2 — MAF-referanseimplementasjon: filkatalog/CSV (offline)

Mål: Første implementasjonsøkt er offline-kildetypen (brief-krav): manifest → CSV-konnektor → materialisert OKF-bundle, hele veien load-bearing-testet. Lukker nøkkelantakelse 2.

Innhold: manifest-kontrakt (pydantic, fail-fast, uten nettverk), CSV-/filkatalog-konnektor, materialisering → OKF-bundle med provenance-frontmatter + index-generering. TDD.

Verifisering: golden-uttrekk-test (fixture + fast timestamp → forventet bundle, bit-deterministisk) · load-bearing: provenance-detach → rød; generert bundle navigerbar via UENDRET okf.py → rød ellers (varig versjon av planleggingsøktas ad hoc-bevis); manifest som mapper til type: verdict → avvist (rød uten reservasjonen); re-ingest over bundle med promotert verdict → verdicten + index-lenken overlever (rød ellers) · suite grønn uten nøkkel/nettverk · mypy/ruff grønne.

I3 — D7-speil: filkatalog/CSV [GATET: annet repo]

Mål: Samme kontrakt konsumert uendret fra commons i søskenrepoet (/Users/ktg/repos/portfolio-optimiser-claude) — beviser at ingest-spec-en faktisk er delt.

Innhold: forankres i søskenets STATE + egen /trekbrief. Commons-pull der; egen impl mot samme spec; speiltester av I2s load-bearing-sett; søskenets framework-guard utvides tilsvarende. Re-verifiser SDK-kroker søk-først (API-drift-risiko).

Verifisering: golden-uttrekk bit-identisk konsumert · speiltester røde ved detach · søskensuite grønn uten nøkkel/nettverk.

I4 — SQL-kilde MAF (sqlite-fixture, null nettverk)

Mål: Andre kildetype på MAF-siden, mot I1-skjemaet uten spec-endring.

Innhold: sqlite-konnektor mot det polymorfe manifest-skjemaet. Ingen spec-endring forventet; hvis drift likevel oppdages: egen GATET commons-runde FØR økta fortsetter (ramme-regelen).

Verifisering: som I2 for SQL: golden-uttrekk (fixture-db + fast timestamp → bit-deterministisk bundle) · load-bearing-settet · suite grønn uten nøkkel/nettverk.

I5 — SQL-kilde D7-speil [GATET: annet repo, som I3]

Mål/Innhold: speiler I4 i søskenrepoet.

Verifisering: som I3 for SQL.

I6 — HTTP/MCP som demonstrert extension point, MAF-only [GATET: nettverks-kapabilitet innføres — lokal mock, ingen live-kilde]

Mål: Extension-point-mønsteret demonstrert ærlig: HTTP/MCP-konnektor mot LOKAL mock, gated bak opt-in-nettverksflagget. Ingen live-kilde — briefens «første live kilde»-gate forblir ukonsumert i hele programmet (målbildet §11).

Innhold: lokal mock i test (in-process/localhost, bak flagget); dokumentér mønsteret i docs/extending.md med D7-krok-pekere (create_sdk_mcp_server).

Verifisering: uten flagg → fail-fast nekt (rød hvis gaten detaches) · suite grønn HELT uten nettverk · ingen artefakt påstår live-integrasjon (grep).

I7 — Program-avslutning: dokumentasjon + statusrapport

Mål: Alt dokumentert sannferdig; programmet lukket med rapport.

Innhold: README/docs/extending.md-oppdatering i begge repo — der D7-omtalen AVGRENSES til det D7 faktisk har (CSV + SQL; HTTP/MCP kun pekere); kort norsk statusrapport (hva er bevist / ikke bevist — ærlighets-regelen).

Verifisering: verifiseringslogg i rapporten (hver påstand → kommando/kilde) · grep-sjekk: ingen artefakt påstår HTTP/MCP-støtte i D7 eller live-kilde-integrasjon · begge repos suiter grønne.

---

Nøkkelantakelser (med eksplisitt test)

1. Maskingenerert bundle passerer eksisterende OKF-kode → testet ad hoc 2026-07-03 (syntetisk bundle med provenance-frontmatter gjennom navigate_bundle/bundle_context: ukjente felt bevart, kontekst rendret). Efemert bevis — den VARIGE load-bearing-testen skrives i I2.
2. Ingest-manifest kan valideres fail-fast uten nettverk → antakelse med belegg (contracts.py-mønsteret er ren in-process), merket RISIKO til I2 lukker den med varig test (rød på malformet manifest, null nettverk).
3. Commons-subtree-flyten fungerer → bevist i S4 (PULL-ONLY-regimet etablert og dokumentert).
4. D7s tekniske kroker dekker behovet (@tool/create_sdk_mcp_server) → verifisert i D7-S5 per briefen; re-verifiseres søk-først i I3 (API-drift-risiko).

Verifisering (planen som helhet)

• Ingen økt erklæres ferdig uten at øktas verifiseringskriterier er kjørt og grønne.
• Program-sluttkriterium: begge stacker materialiserer identiske golden-uttrekk fra delt spec (CSV + SQL); HTTP/MCP demonstrert MAF-only mot mock; alle load-bearing-krav i målbildet §9 bevist røde ved detach; begge repos suiter grønne uten nøkkel/nettverk — og ingen artefakt påstår mer enn koden gjør (live-kilder, D7-HTTP, LLM-atferd).