ms-ai-architect/docs/okf-second-brain-brief-2026-06.md

# Brief — Google OKF for brukerens «second brain» (LLM-wiki), IKKE for skill-refs

_Notert 2026-06-26. Fremtidig initiativ — IKKE implementer før operatør sier fra. Bygger på research av GoogleCloudPlatform/knowledge-catalog (spec + samples + toolbox). State-of-play i `STATE.md`._

## Delt spec er nå kilden (2026-06-29, ratifisert)
Konvensjonen er **ikke lenger definert lokalt** — den bor i `catalog/docs/okf-second-brain/spec.md` (v0.1, eid av ingen enkelt plugin; linkedin-studios `brain/` er referansedesign, okrs `okf-check.mjs` referanse-checker; rollout/koordinering i samme mappes `log.md`). Denne brief-en er nå **plugin-spesifikk plan**, ikke konvensjonsdefinisjon — den *refererer* spec-en. Bekreftet for ms-ai-architect: minimal kontrakt (spec §3: `type` per konseptfil + `index.md` per nivå + `okf_version` i rot-`index.md`) er **gulvet, ikke taket** — vår «fulle OKF-pakke» rir over som **extension keys** (spec §5), ikke nivellert ned til bar OKF.

**Premiss-korreksjoner (spec §9, ground-truth mot live repo — overstyrer økosystem-digesten under):**
1. **`mdcode`/`kcmd` er IKKE et OKF-verktøy** — det er et Dataplex git-sync-verktøy med annet frontmatter-schema. **Droppet** fra adopsjonsplanen.
2. **Ingen gjenbrukbar OKF-*ingest*-kode finnes** — `reference_agent` er BigQuery+Gemini/GCP-bundet. Adopter *prompt-mønstrene*, ikke koden. Classify/convert = bygg-selv.
3. **Kanonisk anbefalt feltnavn er `resource`** (ikke `source`).

## Implementasjonskilde: delt bibliotek, ikke lokal bygging (2026-07-19, verifisert)
Tooling-en under «Hva som må bygges» **bygges ikke lokalt her**. Den kommer fra det delte biblioteket `~/repos/llm-ingestion-okf` (offentlig Forgejo `open/`), som syv repo skal konsumere — så standard-forbedringer arver alle, i stedet for at hver plugin drifter sin egen kopi.

**Tre-delt eierskap (hold dem fra hverandre):**
- **Konvensjon** → `catalog/docs/okf-second-brain/spec.md` (uendret, se over).
- **Implementasjon** → `llm-ingestion-okf` fase 4 = `node/`-halvdelen: zero-dep ESM, importerbar + CLI-invokerbar, **vendret per plugin** (ikke npm). Python- og Node-halvdelen deler kontrakt + fixtures, aldri kode.
- **Sikkerhet** → alltid `llm-ingestion-guard`. Fase 4 leverer kun hook-punktet ved persist (guard-as-contract); scan-/sanitize-logikk hører ALDRI hjemme her. Vår `docs/ingestion-security-brief-2026-07.md`-ambisjon om Node Layer-B-scan er guard-territorium.

**Vår rolle er greenfield-konsument, ikke migrering.** `llm-ingestion-okf/docs/plan/phase-4-node-half.md` koordineringspunkt 5: pluginens designet-men-ubygde behov (writer, indeksgenerator, checker, retrieval-støtte) er **akseptanse-skissen for pakkens API-flate**. Vi har null OKF-kode i dag — det er en fordel her, ikke en gjeld.

**Tidshorisont og gate (per 2026-07-19):** `node/` finnes ikke ennå; biblioteket er ren Python (v0.3.0, fase 1 levert). Fase 4 ← fase 3 ← fase 2, og fase 2 er **blokkert på avklaring B2** (guard-distribusjonskanal for CI — operatørbeslutning, `phase-2-doors-b-c.md:96`). Fase 4 starter dessuten med sign-off-kjede, ikke kode, der vi er punkt 5 av 5: *«okr/ms-ai-architect adopterer i egne repo (egne sesjoner, eksplisitt instruks per repo)»*. **Konsekvens: ikke start S-OKF-implementasjon før B2 er avklart og fase 4 har levert `node/`.**

## Scope-grense + ambisjon (ufravikelig, operatør-bekreftet 2026-06-26)
- **OKF gjelder KUN brukerens egen kontekst/data** — hans person- og organisasjonsspesifikke «second brain» / LLM-wiki (i dag onboarding-output i `~/.claude/ms-ai-architect/org/*.md`).
- **For dette sporet kjøres FULL Google OKF-pakke** (ikke bare lån av mønstre): frontmatter-kontrakt + `index.md`-progressiv-disclosure + retrieval + vedlikeholds-/enrichment-mekanisme, modellert på `samples/` + `toolbox/`. **Og adopsjonen holdes oppdatert etter hvert som OKF-standarden utvikler seg** (v0.1 → senere versjoner; fang `okf_version`-bump). Operatør-direktiv 2026-06-26.
- **OKF gjelder IKKE de 389 skill-reference-filene.** De forblir Claude Code skill-references (native mekanisme, Anthropic-anbefalt flat/progressiv-disclosure-struktur). Begrunnelse: se `docs/ref-kb-direction-note-2026-06.md` + rekonsidererings-konklusjon i memory `okf-scope-second-brain-only`.

## Hvorfor OKF passer second brain (men ikke skill-refs)
Avgjørende skille er **ikke** «er det en LLM-wiki» (begge er det) — men **«finnes det allerede en native, anbefalt mekanisme?»**:
- **Skill-refs:** JA — Claude Code skills + references + progressiv disclosure, allerede Anthropic-best-practice (flat, ett nivå dypt, store filer lastet on-demand, SKILL.md-hub + domene-mapper + grep). OKF ville erstattet et fungerende native system med et ekvivalent fremmed (OKFs retrieval-verdi over skills ≈ null; Grep/Glob/Read dekker allerede OKFs list/search/read).
- **Second brain:** NEI — bor i dag i ad-hoc `org/*.md` uten retrieval-mekanisme under chat. OKF fyller et reelt tomrom: struktur + retrieval + vedlikeholds-tooling, vendor-nøytralt, portabelt, bruker-eid.

## Lastemodell-skifte (operatør-presisering 2026-06-26 — reverserer tidligere antakelse)
- **Før (antatt):** all kontekst injiseres når hver `/architect:*`-kommando kjøres.
- **Nå (mål):** kontekst hentes **smart/selektivt** per kommando *og per interaksjon* — fordi de fleste ganger **chatter** brukeren med pluginen lastet, uten å kjøre kommandoer. Konteksten må være tilgjengelig i fri chat, hentet on-demand, ikke forhåndsinjisert.
- Implikasjon: «second brain» trenger en **retrieval-skill** (list → search → read) som er aktiv uavhengig av kommandoer, + en **vedlikeholds-mekanisme** som holder wikien oppdatert etter hvert som brukeren tilfører kontekst OG etter hvert som OKF-standarden utvikler seg.

## OKF v0.1 — kjernekontrakt (verifisert mot spec)
- Bundle = katalogtre av markdown-filer, ett konsept per fil. Påkrevd frontmatter-felt: `type`. Anbefalt: `title`, `description`, `resource` (kilde-URI), `tags`, `timestamp`. Konsumenter MÅ bevare ukjente felt.
- Reserverte filnavn: `index.md` (katalog-enumerasjon, ingen frontmatter, progressiv disclosure), `log.md` (endringslogg).
- Kryss-lenking: bundle-relativ (`/...`) eller relativ markdown; relasjonstype utledes av prosa. Konsumenter må tolerere brutte lenker.
- v0.1 (12. juni 2026), «starting point, not finished standard» → hold OKF-adopsjonen oppdatert ettersom standarden bumpes (`okf_version` i rot-`index.md`).
- Kilde: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

## Økosystem-digest (les disse FØRST ved implementasjon)
Repo: `GoogleCloudPlatform/knowledge-catalog`. Mye er GCP/Dataplex/Gemini-bundet (ikke direkte gjenbrukbart); de **rene mønstrene** vi adopterer er markert.

**Konsum / smart retrieval (kjernen — ADOPTER MØNSTERET):**
- `samples/enrichment/sample/config/skills/kb-search/SKILL.md` — kanonisk skill-basert henteguide. Eksponerer trioen `list_contents` / `read_file` / `search_content` (= progressiv disclosure: finn → åpne kun relevant). **Mest verdifulle fil å lese først.**
- `samples/enrichment/sample/config/mcp.json` + `samples/enrichment/src/tools/fileskb/{README.md,main.py}` — minimal stdio-MCP-server som eksponerer list/search/read over en markdown-katalog. _NB: i Claude Code dekker Grep/Glob/Read dette allerede — egen MCP-server er trolig unødvendig; SKILL-instruksen («søk wikien først, åpne kun relevant») er det bærende._
- `samples/discovery/*` — Dataplex-bundet søke-agent (Google ADK + CatalogServiceClient). IKKE gjenbrukbart; kun mønster-referanse.

**Struktur / frontmatter-eksempler:**
- `okf/bundles/ga4/index.md` + `okf/bundles/ga4/references/metrics/avg_pageviews.md` — ekte `index.md`-hierarki + leaf-konsept med frontmatter (`type`/`resource`/`title`/`description`/`tags`/`timestamp`) + `# Citations`-seksjon. Kopier som mal.

**Produksjon / vedlikehold (ADOPTER MØNSTERET, ikke koden):**
- `okf/src/reference_agent/prompts/web_ingestion_instruction.md` — kilde-drevet oppdatering: `list_concepts → fetch → enrich/mint/skip` med strenge frontmatter-/heading-bevaringsregler. Moden mal for «hold wikien oppdatert fra kilder».
- `okf/src/reference_agent/prompts/reference_instruction.md` — deterministisk konsept-syntese (frontmatter + fast body-rekkefølge).
- `okf/src/reference_agent/cli.py` — `enrich` / `visualize`-kommandoer (Gemini/BQ-bundet impl).
- ~~`toolbox/mdcode/...`~~ — **DØDT SPOR (spec §9.1):** `mdcode`/`kcmd` er IKKE et OKF-verktøy, men et Dataplex git-sync-verktøy med et annet frontmatter-schema (`id`/`resource.name`/`createTime`/`links`). Ikke planlegg OKF-emit/sync via det.

## Hva som må bygges (fremtidige faser — ikke nå)
> **Leses sammen med «Implementasjonskilde» over:** punkt 1–3 beskriver *behovet*, ikke et byggeoppdrag her. Tooling-en leveres av `llm-ingestion-okf` fase 4 (writer/inbox-primitiver, `okf index`, `okf check`, retrieval-støtte). Vår jobb ved adopsjon er konfigurasjon + vendring + å prøve API-flaten mot behovene under — ikke implementasjon.

1. **Frontmatter-/struktur-konvensjon** for second brain: bygg mot delt spec §3 (`type` påkrevd + `index.md` per nivå + `okf_version` i rot). Anbefalte felt (spec §4): **`resource`** (kanonisk kilde-URI — IKKE `source`), `title`, `description`, `tags`, `timestamp`. Migrer dagens `org/*.md` (de mangler bare `type:` — nær OKF allerede).
2. **Retrieval-skill** («second-brain-search» e.l.): list → search → read over `~/.claude/ms-ai-architect/org/`, aktiv i fri chat (ikke bare kommandoer). Avgjør: ren SKILL+Grep/Glob/Read vs. dedikert MCP-server (build-both-and-measure-kandidat — se under).
3. **Vedlikeholds-mekanisme**: hvordan wikien oppdateres når brukeren tilfører kontekst (onboarding-agent skriver OKF-konform), + en oppdaterings-rutine når OKF-standarden bumpes.

## Åpne valg (operatør / måling)
- **Retrieval-mekanisme:** SKILL + native Grep/Glob/Read vs. dedikert fileskb-MCP-server. Ekte tvil → kandidat for «implementer begge, mål hvilken gir best kontekst-treff for brukeren» (operatørs faktabasert-prinsipp).
- **Hvor mye av OKF formaliseres:** full v0.1-konformitet vs. «OKF-kompatibel form» (frontmatter + index.md uten resten). Lén mot det letteste som gir smart retrieval.
- **Oppdaterings-kadens mot standarden:** hvordan fange OKF-versjonsbump (v0.1 → …) uten manuell polling.

## Suksesskriterium (per operatør 2026-06-26)
Det viktigste er **ikke teknologien**, men at second brain blir **så bra som mulig for brukeren** og at **oppdateringsmekanismene fungerer veldig bra**. Mål mot brukerverdi (henter pluginen riktig personlig/org-kontekst i chat?) + vedlikeholds-pålitelighet — ikke mot formell OKF-konformitet i seg selv.

## Fase-4-kartlegging: hva vi faktisk trenger fra biblioteket (2026-07-20, verifisert)

Svar på koordineringspunkt 5 (vi = akseptanse-skisse for Node-API-flaten). Markørlinje satt i `STATE.md`: **`planned`**.

**Ground truth denne kartleggingen hviler på (verifisert, ikke antatt):**
- `~/repos/llm-ingestion-okf`: v0.3.1, `node/` finnes **ikke** (kun `src/` = Python). `docs/plan/phase-4-node-half.md:12,49-62` planlegger `okf check|index|inbox|convert` — altså writer/index/checker uten connector-krav.
- `~/.claude/ms-ai-architect/org/` **finnes ikke på denne maskinen** — second brain er designet (6 filslots konsumert av `research-agent`, `adr-writer-agent`, `architecture-review-agent` m.fl.) men aldri materialisert. Vi er greenfield i bokstavelig forstand.
- `scripts/kb-update/` er **ikke** en OKF-flate (se under).

### kb-update-pipelinen: generisk mekanikk vs. MS Learn-domenelogikk
Deteksjonslaget er 100 % deterministisk node (null modellkall, strukturelt garantert i `run-detection.mjs:6-9`); apply-laget er LLM/MCP og alltid manuelt in-session.

| Generisk ingestion-mekanikk | MS Learn-domenelogikk |
|---|---|
| `lib/atomic-write.mjs` (tmp+rename), `lib/backup.mjs` (scoped restore + sentinel) | `lib/sitemap-stream.mjs` (hardkodet `learn.microsoft.com/_sitemaps/`), `lib/url-normalize.mjs` (locale-stripping) |
| `lib/registry-io.mjs`, `lib/decisions-io.mjs` (manifest + ledger/idempotens) | `data/domain-taxonomy.json` (sitemap-prefikser → category → skill-routing) |
| `lib/verified-staleness.mjs`, `lib/full-pass-worklist.mjs` (kilde-timestamp vs. verifisert-timestamp) | `lib/kb-headers.mjs` + `lib/transform.mjs` (bold-label-header-kontrakten), `lib/verify-out.mjs` (GA/preview/pris-regexer), `lib/learn-api.mjs` |
| Invarianten «pure lib skriver aldri; kun gated caller skriver» | `transform-prompt.md` + `kb-eval/judge-claim-prompt-v3.1.md` (claim/judge-format) |

Den generiske kolonnen overlapper reelt med det fase 4 skal levere (atomisk write, manifest, ledger, ferskhet). **Men den flytter vi ikke** — se «Aldri hit» under.

### Vår adopsjonsflate = second brain, og den trenger ikke dør A
Second brain-filene fødes av et **onboarding-intervju** (LLM → `Write`), ikke av en kildekonnektor. Det finnes ingen manifest, ingen CSV, ingen SQL, ingen URL å hente. Dør A (manifest → connector → materialisering) er derfor **irrelevant for oss** — vi trenger den *bakre halvdelen* av dør A, frikoblet fra connector-halvdelen.

**Konkret krav til Node-API-flaten (punkt (b) i rapporteringen):**
1. **Writer uten connector.** `writeConcept({path, frontmatter, body})` må være kallbar direkte med LLM-forfattet innhold — ikke bak et manifest/connector-krav. Deterministisk frontmatter-emit (`type` påkrevd, `resource`/`title`/`description`/`tags`/`timestamp`), ukjente felt bevart, atomisk skriv, idempotent re-kjøring.
2. **`okf index` som bibliotekfunksjon, ikke bare CLI.** Vi må regenerere `index.md` per nivå fra en in-process hook (onboarding-agent skriver én fil → indeks oppdateres i samme operasjon), uten å shelle ut.
3. **`okf check` med maskinlesbar exit + funn-struktur.** Vi har allerede create-guard-mønsteret (`validate-kb-file.mjs`, exit≠0 = stopp) og vil speile det for OKF-flaten.
4. **Guard-hook ved persist, ikke i biblioteket.** `free-context.md` er den ene slotten der brukeren limer inn vilkårlig eksternt innhold — der må `llm-ingestion-guard` kalles på kallstedet. Vi leser IKKE «security is delegated» som «trygt by default» (jf. v0.3.1-presiseringen).
5. **Fritekst-kravet (F1) gjelder oss, men via dør B — ikke dør A.** Om `free-context.md`-inntak skal formaliseres, er innboks-mønsteret (split → frontmatter → write) riktig form, ikke en connector.
6. **Vendring, ikke npm** — zero-dep ESM som kan sjekkes inn under `scripts/`, konsistent med at pluginen distribueres offentlig og må kjøre uten install-steg.

### Aldri hit (punkt (c))
- **De 389 skill-reference-filene.** Stående operatør-direktiv (§ «Scope-grense»); native Claude Code-mekanisme dekker allerede OKFs list/search/read.
- **Hele MS Learn KB-refresh-pipelinen.** Header-kontrakt, judge/claim-format, GA/preview-semantikk og Layer A/B-plassering er domenelogikk med egen testsuite — en delt ingestion-standard ville verken forstå eller forbedre den.
- **All sikkerhetslogikk.** Eies av `llm-ingestion-guard` (vårt repo er `guard: active`, Layer A+B live). Ambisjonen i `docs/ingestion-security-brief-2026-07.md` om Node Layer-B-scan er guard-territorium, ikke OKF-territorium.

### Gate før implementasjon (uendret)
Fase 4 ← fase 3 ← fase 2, og fase 2 er blokkert på **avklaring B2** (guard-distribusjonskanal for CI, operatørbeslutning). Ingen S-OKF-kode skrives her før `node/` er levert.

## Referanser
- **Delt konvensjon (KILDEN):** `catalog/docs/okf-second-brain/spec.md` (v0.1) + `log.md` (koordinering/rollout) — les FØRST.
- OKF upstream-spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
- Samples: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/samples
- Toolbox: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox
- Relatert (skill-ref-sporet, separat): `docs/ref-kb-direction-note-2026-06.md`, `docs/ref-kb-audit-2026-06.md`