docs(plan): utrulling D-F–D-I — sesjonsplan (D-F–D-I i §2, S3.5/S3.6/S5.4, graf+T0), roadmap-revisjonsblokk, commons-amendment-utkast (Step-1-analyse: NEI → minimal amendment), toolkit-repo-brief

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

docs/plan/2026-07-14-toolkit-repo-brief.md

@@ -0,0 +1,201 @@
+# Program-brief: `okf-toolkit` — delt OKF-verktøykasse (modul + formatprøve + evaluator + fabrikk)
+
+> **Status: BRIEF, ikke plan.** Skrevet 2026-07-14 som utrulling av
+> [revisjonspakke D-F–D-I](2026-07-14-revisjonspakke-DF-DI.md) §5 pkt. 4. Kilden er pakkas
+> **§0.2** (kryssrepo-OKF-inventar), **§2 D-G** (felles modul + fabrikk + evaluator) og
+> **§3 D-H** (oppsett/oversettelse). Dette dokumentet er *input* til et NYTT, eget repo utenfor
+> dette repoets sesjonskø. Programmets to første leveranser er et repo-init + et målbilde/gated
+> sesjonsplan — lages i det nye repoet, ikke her. Ingenting bygges før den planleggingssesjonen
+> har kjørt og operatør har godkjent.
+>
+> **Provenance:** anbefalinger = AI (Opus, denne økten 2026-07-14); beslutningene D-G/D-H =
+> operatør, protokollert i revisjonspakka. Arbeidstittel `okf-toolkit` — **operatør navngir**.
+> Gjenbruksmal: `llm-ingestion-guard` (verifisert: pip-pakke, `dependencies = []` stdlib-only
+> kjerne, valgfrie extras bak flagg, ærlige begrensninger shippet som kontroll).
+
+## 1. Formål (hvorfor repoet må finnes)
+
+Én delt, **standard-kompatibel OKF-verktøykasse** — for alle repoene i denne familien OG for
+alle som tar i bruk Google Open Knowledge Format (v0.1). I dag rulles formatet ut på ≥6
+kodelokasjoner (revisjonspakke §0.2, verifisert mot ground truth 2026-07-14):
+
+| # | Lokasjon | Størrelse | Delmengde |
+|---|---|---|---|
+| A1 | `portfolio-optimiser/.../okf.py` | 202 l | les + naviger + **skriv** (Steg 8-primitiver) |
+| A2 | `portfolio-optimiser-claude/.../okf.py` | 134 l | **kun les** — mangler skrive-halvdelen |
+| C1 | `claude-code-llm-wiki/tools/wiki_ingest/bundle.py` | 436 l | OKF-produsent (ingest→bundle) |
+| C2 | `llm-ingestion-pipeline-security/.../okf.py` | 579 l | defensiv validator, reject-by-default |
+| B1/B2 | `ktg-plugin-marketplace/` (`.mjs`/`.ts`) | JS/TS | index-generering + conformance |
+
+≥4 uavhengige Python-`parse_frontmatter` + 2 i JS. Konsekvensene (F-INT-2): duplisert
+vedlikehold, og at Claude-søskenet (A2) **mangler skrive-halvdelen** A1 har — så det ikke kan
+være «minst like godt» som MAF-repoet (operatørens favoritt). D-G vedtar én delt modul, og
+**reverserer bevisst** de to tidligere «del spec, ikke kode»-beslutningene (marketplace-brief
+2026-06-26 + D7) for den tolerante kjernen — operatør-godkjent 2026-07-14. Formatlaget ligger
+UNDER det D7-sammenligningen måler, så delt kode her forurenser ikke sammenligningen.
+
+## 2. Arkitektonisk premiss (arvet fra D-G/D-H — ufravikelig)
+
+- **Standard-kompatibel først.** Kjernen retter seg etter Google OKF v0.1 — inkludert
+  `/`-lenkeformen som method-spec i dag avviker fra (review F4 / D-A pkt. 3; D-G pkt. 1
+  forsterker denne). **Egne utvidelser oppå** (innboks-konseptet, ingest-sikkerhet,
+  evaluator-felt) dokumenteres EKSPLISITT som utvidelser og pensjoneres hvis standarden senere
+  løser dem.
+- **Installerbar pakke, avhengighetsfri kjerne, Forgejo** — guard-malen én-til-én:
+  `dependencies = []`, stdlib-only kjerne, valgfrie adaptere bak extras. Potensielt nyttig for
+  ALLE som tar i bruk Google OKF, ikke bare denne familien.
+- **Ren stdlib, framework-nøytral.** Kjernen importerer aldri `agent_framework`/`mcp` (arver
+  A1s `test_okf_is_maf_free`-invariant + guard-malens stdlib-first). Samme modul konsumeres
+  uendret av begge stacker (D7-portabel).
+- **Fabrikken lever UTENFOR optimalisererens deterministiske kjøresti** (ærlighets-grense,
+  §6). Den er et *pre-run ingest-steg* som materialiserer en bundle FØR en kjøring — ikke et
+  query-time-oppslag i agent-løkka (samme grense som ingest-brief §2; ikke RAG).
+- **Guard (C2) konsolideres IKKE inn.** Motsatt sikkerhetsfilosofi by design (reject-by-default
+  vs. tolerant les). Guard forblir eget repo og **brukes som avhengighet** av fabrikkens
+  sikkerhetsvask-steg — komponert, ikke kopiert.
+
+## 3. Scope — to faser
+
+### Fase T1 — `okf-core`-modul + formatprøve (først; liten jobb, fjerner duplikasjonen)
+
+1. **`okf-core`-modul:** tolerant **les / naviger / skriv**-kjerne som erstatter A1/A2/C1-
+   duplikatene. Skrive-halvdelen (`render_frontmatter`, `write_concept_file`, `link_in_index`
+   — verifisert å finnes i A1, fraværende i A2) blir delt, så Claude-søskenet får den det
+   mangler. Pip-pakke, stdlib-only, guard-malen.
+2. **Formatprøve (conformance-testsett):** kjørbart testsett mot Google OKF v0.1 + våre
+   utvidelser, som ALLE konsumenter kan kjøre mot sine egne bundles. Testsettet er
+   **språknøytral data** — så B-paret (JS/TS) kan konsumere formatprøven selv om det ikke kan
+   importere Python-modulen. Load-bearing: en gyldig bundle passerer; en bevisst malformert
+   (feil lenkeform, manglende frontmatter) FEILER.
+
+### Fase T2 — evaluator + fabrikk (bygget mot energi-caset som første kunde)
+
+3. **Bundle-evaluatoren — to jobber** (D-G pkt. 5):
+   - **(a) Teknisk korrekthet (deterministisk):** konformitet, navigerbarhet, lenke-integritet,
+     kildedekning, ferskhet, sikkerhet, sammendragsdisiplin. Samme input → samme score.
+   - **(b) Tilstrekkelighet (AI-vurdert, åpne kriterier):** «omfattende nok til å være nyttig?
+     hva mangler?» — output er fagekspertens arbeidsliste under oppbygging, merket som
+     maskin-vurdering/veiledning, aldri deterministisk fakta.
+4. **Bundle-fabrikken (operatørs viktigste nå):** bruker slipper filer/mapper i en
+   **bundle-innboks** → prosessen strukturerer, oppsummerer, lenker, stempler og
+   **sikkerhetsvasker** (guard som avhengighet) → ferdig base som evaluatoren scorer høyt på de
+   deterministiske dimensjonene. **Dom-oversettelse (D-H pkt. 3):** eksperten leverer
+   fri-format-fil → fabrikken AI-oversetter til det strenge domsformatet; den strukturerte
+   dommen peker **ALLTID på ekspertens originalfil** (provenance), så en stikkprøve kan
+   sammenligne «hva eksperten skrev» mot «hva systemet forsto». Dommen er menneskets; AI er
+   oversetter.
+
+## 4. Konsumenter + migreringsrekkefølge
+
+1. **`portfolio-optimiser` (A1)** → importér `okf-core`; A1s skrive-primitiver flyttes inn i
+   modulen. Full suite (baseline 279/4) skal forbli grønn etter migreringen.
+2. **`portfolio-optimiser-claude` (A2)** → importér `okf-core`; **får skrive-halvdelen det
+   mangler i dag** (Steg 8-primitiver). Dette er hovedgevinsten for D-Gs «minst like godt»-mål.
+3. **`claude-code-llm-wiki` (C1)** → senere; produsent-stien (ingest→bundle) legges på
+   `okf-core` + fabrikken.
+4. **`ktg-plugin-marketplace` (B1/B2)** → forblir JS/TS (kan ikke dele Python-kode), men
+   konsumerer **formatprøven** som delt data.
+5. **`llm-ingestion-guard` (C2)** → migreres IKKE; forblir eget repo og trekkes inn som
+   **avhengighet** i fabrikkens sikkerhetsvask.
+
+Rekkefølge (D-G pkt. 6): modul + formatprøve FØRST (fjerner 6-steders-duplikasjonen), fabrikk +
+evaluator DERETTER — bygget mot energi-caset (D-F pkt. 7) som første kunde. Demo-stien (D-H
+pkt. 4): fersk klon → unzip energi-eksemplet i innboksen → fabrikken bygger → hele sløyfa kjører.
+
+## 5. Ærlighets-grenser (§1 målbilde — ufravikelig)
+
+- **Fabrikken bruker AI og lever utenfor den deterministiske kjøringen.** Alt den produserer
+  merkes maskingenerert (`generated: true` + manifest-ref + provenance til kilden).
+  Kontrollen er evaluatoren + ekspertens stikkprøve — ikke fabrikkens egen tillit.
+- **Evaluatorens (b)-output er maskin-vurdering**, ikke målt fakta. Deterministisk (a) og
+  AI-vurdert (b) holdes tydelig fra hverandre i rapporten.
+- **Dom-oversettelsen endrer aldri hvem dommen tilhører.** Provenance-lenken til originalfila
+  er vaktposten mot at AI-oversettelsen stille forvrenger ekspertens vurdering.
+- **Toolkit-repoet påstår ikke å bevise besparelser.** Det bygger kunnskapsbasen (input til
+  verdibeviset, D-I) — verdipåstanden lever i optimaliserer-repoene, ikke her.
+
+## 6. Ikke-mål (dokumentert grense)
+
+- **Ingen erstatning av C2s reject-by-default-parser.** Den tolerante kjernen og den defensive
+  validatoren er bevisst ULIKE verktøy; fabrikken komponerer begge, den slår dem ikke sammen.
+- **Ingen RAG / query-time-oppslag.** Fabrikken er write-time ingest FØR kjøring (ingest-brief
+  §2-grensen står).
+- **Ingen compliance-funksjoner.** Rent teknisk verktøykasse (DPIA/ROS eies av deployer).
+- **Ingen dedikert lese-visning i første scope.** Obsidian/VS Code holder (bundles er ren
+  markdown, D-H pkt. 5); en dedikert lese-visning er en SENERE byggekloss i repoet, ikke nå.
+- **Ingen endring i optimalisererens agent-atferd eller modell-map.**
+
+## 7. Avhengigheter og blokkeringer
+
+- **Energi-caset er første kunde** (D-F pkt. 7): fabrikk + evaluator bygges og bevises mot
+  energi-eksemplet i tilnærmet realistisk skala. T2 kan derfor koordineres med D-F-innholds-
+  arbeidet, men T1 (modul + formatprøve) er uavhengig og kan starte umiddelbart.
+- **Blokkerer** fabrikk-avhengige deler av D-F (materialisering av dimensjonsbiblioteket) og
+  D-H (demo-stien, dom-oversettelsen).
+- **D7-speiling:** begge stacker skal konsumere `okf-core` uendret; migreringen av A1 og A2 er
+  koblet (ikke uavhengige økter).
+- **Guard-avhengighet:** fabrikkens sikkerhetsvask krever `llm-ingestion-guard` som publisert/
+  installerbar avhengighet.
+
+## 8. Åpne spørsmål til operatør (må avklares før/i repo-init)
+
+- **Navn:** arbeidstittel `okf-toolkit` — operatør fastsetter endelig pakkenavn (påvirker
+  `pip install <navn>` + importsti).
+- **Lisens:** guard-presedens er MIT (S12-linja). Bekreft MIT for toolkit, eller avvik.
+- **Publiseringsrekkefølge:** publiseres `okf-core` (T1) som egen pakke-release FØR fabrikken
+  (T2) finnes, eller samtidig? (Guard-malen taler for tidlig, liten kjerne-release.)
+- **Repo-plassering:** eget Forgejo-repo bekreftes (som guard), ikke undermappe.
+
+## 9. Verifisering (for planleggingssesjonen som konsumerer denne briefen)
+
+**Fase T1:**
+- [ ] Premissene i §1/§2 kontrollert mot ground truth FØR skriving (§0.2-tallene A1=202/
+      A2=134/C1=436/C2=579 gjenfunnet med `wc -l`; A2 mangler `write_concept_file`/`link_in_index`
+      bekreftet med `grep`). ✅ (utført i denne briefen 2026-07-14)
+- [ ] `okf-core` installerbar med null avhengigheter: i rent venv `pip install <navn>` +
+      `python -c "import okf_core"` lykkes; `pyproject.toml` viser `dependencies = []`.
+- [ ] Kjernen framework-nøytral: en `test_okf_is_maf_free`-ekvivalent grønn (`grep -R
+      "agent_framework\|import mcp" src/` tomt).
+- [ ] Formatprøven load-bearing: gyldig energi-bundle passerer HELE settet; en bevisst
+      malformert bundle (feil lenkeform / manglende frontmatter) gjør minst én conformance-test
+      RØD. Standard-kompatibilitet: `/`-lenkeformen passerer, den gamle formen flagges.
+- [ ] Migrering: `portfolio-optimiser` importerer `okf-core`, den lokale `okf.py`-duplikaten er
+      borte/delegerer, og full suite fortsatt grønn (baseline 279/4). Samme for A2 — som nå
+      EKSPONERER skrive-primitivene (verifiser at `write_concept_file`/`link_in_index` er
+      importérbare i Claude-repoet, der de i dag mangler).
+
+**Fase T2:**
+- [ ] Evaluator (a) deterministisk + reproduserbar: samme bundle → samme score to kjøringer; en
+      bundle med én brutt intern lenke scorer lavere på lenke-integritet enn samme bundle uten.
+- [ ] Evaluator (b) merket: tilstrekkelighets-output er tydelig stemplet maskin-vurdering/
+      veiledning, adskilt fra (a) i rapporten.
+- [ ] Fabrikk demo-sti: unzip energi-eksemplet i innboks → kjør fabrikk → resultat-bundle
+      scorer høyt på ALLE deterministiske evaluator-dimensjoner; `grep -RL "generated:"
+      <bundle>/` er tomt (hver fil merket maskingenerert).
+- [ ] Dom-oversettelse provenance load-bearing: gitt en fri-format dom-fil i innboksen, har den
+      genererte strukturerte dommen et provenance-felt = kildefilnavnet (en stikkprøve kan åpne
+      begge). Detach provenance-feltet → testen RØD.
+- [ ] Sikkerhetsvask via guard load-bearing: en innboks-fil med kjent injection-payload fanges
+      (fail-secure) FØR den når bundelen; koble fra guard-avhengigheten → payloaden lander i
+      bundelen (testen RØD).
+- [ ] Ærlighets-grense: optimaliserer-repoenes suiter kjører fortsatt uten nøkkel/nettverk og
+      importerer IKKE fabrikken i kjørestien (`grep -R "import.*factory" src/` i kjørestien tomt).
+
+## 10. Prompt for å starte programmet (kjør i det NYE toolkit-repoet, ikke her)
+
+```
+Les <dette repoets>/docs/plan/2026-07-14-toolkit-repo-brief.md (kopier inn) samt
+revisjonspakke §0.2/§2 D-G/§3 D-H. Dette er repo-init + PROGRAM-PLANLEGGING for
+okf-toolkit — det rører IKKE optimaliserer-repoenes sesjonskø.
+
+1. Verifiser briefens premisser mot ground truth på nytt (§0.2-tallene + at A2 mangler
+   skrive-halvdelen) FØR noe skrives.
+2. repo-init som eget Forgejo-repo etter guard-malen (pip-pakke, dependencies = [],
+   MIT med mindre operatør avviker, stdlib-only kjerne).
+3. Lag i plan-modus: (a) målbilde for okf-toolkit (standard-kompatibilitet + utvidelses-
+   policy + de to fasene), (b) gated sesjonsplan der HVER sesjon har mål + verifisering
+   per §9. T1 (modul + formatprøve) FØR T2 (fabrikk + evaluator). Presenter for
+   godkjenning FØR noe committes.
+4. Avklar de åpne spørsmålene i §8 (navn, lisens, publiseringsrekkefølge) med operatør
+   i klarspråk før repo-init låses.
+```