open/ms-ai-architect
1
0
Fork 0
Code Issues Pull requests Releases Activity
ms-ai-architect/docs/okf-second-brain-brief-2026-06.md

16 KiB
Raw Blame History

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