From aec95eb0da0f3c156c57a8e81b110d7dc26d2e79 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 3 Jul 2026 11:24:24 +0200 Subject: [PATCH] =?UTF-8?q?docs(plan):=20program-brief=20for=20ingest-lag?= =?UTF-8?q?=20=E2=80=94=20tools/konnektorer=20mot=20reelle=20datakilder?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brief (ikke plan) for nytt program etter S11: ingest-steg som materialiserer kildeuttrekk til OKF-bundles (metode-spec forbyr query-time retrieval i løkka), delt manifest-kontrakt i commons, referanseimplementasjon per stack. Inkluderer oppstartsprompt for planleggingssesjonen. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QdSfQdND84oeq2mbjueLTS --- ...-07-03-program-brief-ingest-konnektorer.md | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 docs/plan/2026-07-03-program-brief-ingest-konnektorer.md diff --git a/docs/plan/2026-07-03-program-brief-ingest-konnektorer.md b/docs/plan/2026-07-03-program-brief-ingest-konnektorer.md new file mode 100644 index 0000000..9539fbe --- /dev/null +++ b/docs/plan/2026-07-03-program-brief-ingest-konnektorer.md @@ -0,0 +1,110 @@ +# Program-brief: Ingest-lag — tools og konnektorer for reelle datakilder + +> **Status: BRIEF, ikke plan.** Skrevet 2026-07-03 på operatørs bestilling (fra +> D7-søskensesjonen, etter fullført S10). Dette dokumentet er *input* til et NYTT program; +> programmets to første leveranser er et målbilde-dokument og en gated sesjonsplan — begge +> lages i en egen planleggingssesjon i dette repoet (prompt nederst). Ingenting her er +> besluttet før den sesjonen har kjørt og operatør har godkjent. + +## 1. Behovet (hvorfor programmet må finnes) + +Begge stackene (MAF + D7/Claude Agent SDK) er bevist på kuraterte OKF-bundles +(`shared/examples/bygg-energi-mikro/`). Praktisk anvendbarhet krever at fageksperter kan: + +1. koble rammeverket til reelle datakilder (økonomisystem, prosjektdatabase, FDV-system, + energimålere, dokumentarkiv), og +2. definere *hvilke spørringer* som henter underlaget per kjøring. + +Dagens planverk (S1–S12) dekker ikke dette. Verifisert 2026-07-03: null forekomster av +ingest/konnektor i sesjonsplanen; eneste spor er nordstjernens «MCP/RAG = extension point, +ikke nå» (`2026-06-26-maalbilde-agentic-loop.md` §90%-prinsippet) samt de tekniske krokene +som allerede finnes (`build_mcp_server` i MAF; `@tool`/`create_sdk_mcp_server` i Agent SDK, +verifisert i D7-S5). + +## 2. Arkitektonisk premiss (arvet fra metode-spec — ufravikelig) + +- **Data når modellen KUN via OKF-bundles.** Metode-spec-en forbyr eksplisitt query-time + retrieval-tools pekt mot bundelen: *«never via a query-time retrieval tool pointed at the + bundle (which would re-leak the verdict layer)»*. Konsekvens: konnektorer lever i et + **ingest-steg som kjører FØR optimalisereren** og materialiserer uttrekket som en + OKF-bundle. Ikke RAG, ikke live-oppslag i agent-løkka. +- **Provenance helt tilbake til kilden.** §9-citations peker i dag på fil + span i bundelen. + Ingest-laget må stemple hver generert konseptfil med kilde-system, spørring og tidspunkt, + slik at kjeden ekspert → forslag → bundle-fil → kildesystem er ubrutt. +- **Lokal-only default, ingen stille egress.** Kildekall er både kost og risiko; samme + disiplin som D6 (tak, logging, eksplisitte kjøringer). +- **Deterministisk kjerne røres ikke.** Begge suitene skal fortsatt kjøre uten nøkkel og + uten nettverk; konnektorer testes mot fixtures/golden-uttrekk, aldri mot levende kilder. +- **Ærlighets-regelen (§1)** gjelder også ingest-artefakter: en maskingenerert bundle merkes + som det, med manifest-referanse. + +## 3. Foreslått scope (til vurdering i målbildet — IKKE besluttet) + +- **Delt, stack-nøytral kontrakt i commons:** et «ingest-manifest» (kilde, spørring, + mapping → OKF-typer, provenance-krav) som spec — slik at begge stackene konsumerer samme + format. Endres i commons, subtree-pulles (PULL-ONLY-regimet står). +- **Referanseimplementasjon per stack:** MAF (FunctionTool/MCP-søm) og D7 (in-process MCP / + `@tool`). +- **Kildetyper i prioritert rekkefølge:** (a) filkatalog/CSV — null nettverk, bevis hele + formatet offline først; (b) SQL/database; (c) HTTP/MCP-server mot eksterne systemer. +- **Ekspertens spørringsdefinisjoner som konfig, ikke kode** — validert fail-fast à la + `contracts.py`, med operatør-gate før første kjøring mot en ny kilde. + +## 4. Utenfor scope + +- Ingen endring i agent-atferd eller nye modellkall — ingest er deterministisk. +- Ikke query-time retrieval/RAG (forbudt av metode-spec, se §2). +- DPIA/ROS/behandlingsformål eies fortsatt av deployer (rent teknisk rammeverk). +- Ingen endring i golden-fasiten eller eksisterende suite-invarianter. + +## 5. Avhengigheter og rekkefølge + +- Starter tidligst **etter S11** (rapporten kan påvirke valg av primærstack for + referanseimplementasjonen). S12 (release) er uavhengig og kan gå før eller etter. +- Commons-endringer følger PULL-ONLY; nye spec-avsnitt skrives i commons-repoet. + +## 6. Programmets forventede leveranser + +1. **Målbilde-dokument** (frossen nordstjerne for ingest-laget): arkitektur, kontrakter, + sikkerhetsrammer, provenance-format. +2. **Gated sesjonsplan** i samme form som `2026-07-02-sesjonsplan.md` (mål + innhold + + verifisering per sesjon; operatør-gates ved repo-/spec-endringer og første live-kilde). +3. Deretter implementasjonssesjoner per plan. + +## 7. Åpne spørsmål målbildet MÅ besvare + +- Bor ingest-manifest-spec-en i `method-spec.md` (ny §) eller som egen spec i `shared/`? +- Provenance-format for kilde-stempling — utvidelse av §9 eller eget lag i frontmatter? +- Credential-håndtering (keychain-mønsteret; aldri i manifest/konfig). +- Inkrementell re-ingest vs. full re-materialisering; versjonering av bundles. +- Hvordan HITL-eksperten godkjenner et ingest-manifest før første kjøring (gate-mekanikk). +- Testabilitet: golden-uttrekk per kildetype slik at load-bearing-regelen (§11) også + dekker ingest-sømmen. + +## Verifisering (for planleggingssesjonen som konsumerer denne briefen) + +- [ ] Briefens premisser kontrollert mot `shared/method-spec.md` og nordstjernen FØR noe + skrives (sitatene i §2 gjenfunnet ordrett). +- [ ] Målbilde-dok committet i `docs/plan/` med retrieval-forbudet sitert og adressert. +- [ ] Sesjonsplan der HVER sesjon har mål + verifisering; første implementasjonssesjon er + offline-kildetypen (filkatalog/CSV). +- [ ] Nøkkelantakelser testet eller merket som risiko: (1) en maskingenerert bundle passerer + eksisterende OKF-robusthetsregler — test mot eksisterende OKF-kode med syntetisk + bundle; (2) ingest-manifest kan valideres fail-fast uten nettverk. +- [ ] Suitene i begge repo fortsatt grønne uten nøkkel/nettverk etter evt. commons-pull. + +## Prompt for å starte programmet (kjør i DETTE repoet) + +``` +Les docs/plan/2026-07-03-program-brief-ingest-konnektorer.md. Dette er en +PROGRAM-PLANLEGGINGSSESJON for ingest-laget — den rører IKKE S11/S12-løpet. + +1. Verifiser briefens premisser mot shared/method-spec.md og + docs/plan/2026-06-26-maalbilde-agentic-loop.md (premiss-verifisering før handling). +2. Lag i plan-modus: (a) målbilde-dokument for ingest-laget, (b) gated sesjonsplan — + begge per briefens §6 og verifiseringsliste. Presenter planen for godkjenning FØR + noe committes. +3. Merk: STATE.md her er stale (NESTE peker på S6; S6–S10 er fullført i søskenrepoet, + S10-artefakter ligger i dets runs/s10/). Reconcilier STATE ved sesjonsslutt, og + fjern push-frys-linjen hvis operatør bekrefter at frysen er opphevet. +```