From 2eb9c8d8407c8c9580cf8f2ffe68f957424969ea Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 20 Jul 2026 07:26:10 +0200 Subject: [PATCH] =?UTF-8?q?docs(ms-ai-architect):=20S-OKF=20fase-4-kartleg?= =?UTF-8?q?ging=20=E2=80=94=20adopsjonsflate=20=3D=20second=20brain,=20ikk?= =?UTF-8?q?e=20skill-refs/KB-refresh;=20kravskisse=20til=20Node-API=20(wri?= =?UTF-8?q?ter=20uten=20connector,=20index=20som=20bibliotekfunksjon,=20ch?= =?UTF-8?q?eck=20med=20funn-struktur,=20guard-hook=20ved=20persist);=20mar?= =?UTF-8?q?k=C3=B8r=20satt=20til=20planned=20[skip-docs]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/okf-second-brain-brief-2026-06.md | 40 ++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/okf-second-brain-brief-2026-06.md b/docs/okf-second-brain-brief-2026-06.md index 22350b9..2c2689d 100644 --- a/docs/okf-second-brain-brief-2026-06.md +++ b/docs/okf-second-brain-brief-2026-06.md @@ -76,6 +76,46 @@ Repo: `GoogleCloudPlatform/knowledge-catalog`. Mye er GCP/Dataplex/Gemini-bundet ## 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