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

# 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.
```