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 §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.