From db8cb8c7e39ad7f27e358f392a9f37e7f7ac98fc Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 26 Jun 2026 20:57:35 +0200 Subject: [PATCH] =?UTF-8?q?docs(linkedin-studio):=20OKF=20convergence=20br?= =?UTF-8?q?ief=20=E2=80=94=20reference=20design,=20premise=20corrections,?= =?UTF-8?q?=20Stage=201=20outcome?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-plugin second-brain convergence on OKF-compatible form. The brain is the reference design (most mature of the three); OKF is a thin interop veneer. Records: three verified premise corrections (mdcode != OKF; OKF has no document-folder ingest; classify/convert is build-yourself and the sibling docs never asked for it); the three-consumer landscape (okr built, architect designed, linkedin-studio richest); the staged plan (shared spec -> measure -> conditional shared skill); per-repo scope boundaries (each its own go); and the landed Stage-1 outcome with its premise refinement (bundle=brain/, ingest/ excluded as round-trip-critical tributary). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_011vmzxpsFpc8q19LaogAWLD --- docs/okf-convergence-brief.md | 187 ++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 docs/okf-convergence-brief.md diff --git a/docs/okf-convergence-brief.md b/docs/okf-convergence-brief.md new file mode 100644 index 0000000..97f9c95 --- /dev/null +++ b/docs/okf-convergence-brief.md @@ -0,0 +1,187 @@ +# Brief — Cross-plugin second-brain convergence on OKF-compatible form + +> Created 2026-06-26. **Reference-design brief — not an implementation order.** Captures the operator-locked +> direction for converging three plugins' user-owned second brains onto one shared, interoperable form, +> with **linkedin-studio's brain as the reference design** and **Google OKF as a thin interop layer only**. +> Cross-cutting: most rollout lands in sibling repos and requires its own per-repo go (see §8). State-of-play +> in `STATE.md`. Companion design docs (read alongside): `okr/docs/okf-second-brain-note-2026-06.md`, +> `ms-ai-architect/docs/okf-second-brain-brief-2026-06.md`. + +## 1. Locked decision (operator, 2026-06-26) + +Converge on **the user's own context** (not the plugins' domain reference files), driven by **interop** — +**not** standard-adoption for its own sake. + +- **linkedin-studio's brain is the reference design** — the most mature of the three (provenance-weighted + learning, episodic/semantic split, evidence-threshold promotion). The siblings rise toward its maturity; + it is **not** levelled down to bare OKF. +- **OKF is the thin interop veneer** — add `type:` + per-level `index.md`; keep all rich fields as extension + keys (OKF consumers MUST preserve unknown keys). No capability is sacrificed. +- **Staged:** ship a shared **spec/convention first**; build a shared **skill only if measured divergence + justifies it** (okr's retrieval already works — see §4). + +## 2. Premise corrections (verified — these overturn the old STATE/memory framing) + +The pre-existing framing ("greenfield shared ingest skill; inbox→classify→convert→emit OKF; mdcode is the +key tool") rested on three premises that ground-truth checks **disproved**. Verified against the live +`GoogleCloudPlatform/knowledge-catalog` repo (research agent, 2026-06-26, file+URL log retained) and the +sibling repos. + +1. **`mdcode` is NOT an OKF tool.** It is a **Google Cloud Dataplex** git-sync tool whose on-disk `kb` + markdown carries a *different* frontmatter schema (`id`/`resource.name`/`createTime`/`links`) than OKF + (`type`/`title`/`description`/`tags`/`timestamp`). They are not interchangeable. Do **not** plan `kcmd` + to emit or sync OKF bundles. +2. **"OKF has no ingest" is true of the *format*, not the *repo*.** The repo ships an OKF *producer* + (`okf/src/reference_agent`, BigQuery+web→OKF) — but it reads a BigQuery dataset + seed URLs, **not** a + document folder, and is Gemini/GCP-bound. The genuinely reusable, GCP-free parts are the **SPEC**, the + **emit/serialize/validate** core (`OKFDocument`), and the `index.md` synthesis. +3. **Classify/convert of arbitrary documents is exactly what the repo provides *nothing* for** — those + stages are 100% build-yourself. And — decisive — **the sibling design docs never asked for them.** Both + frame the work as *OKF as the storage format for a user-owned second-brain wiki* + a **retrieval skill** + + a **maintenance mechanism**, with ingest being light ("onboarding writes OKF-conformant"), not + auto-classification. + +## 3. Landscape — the three consumers have already diverged + +| Plugin | Second-brain status | Maturity | +|---|---|---| +| **okr** | **Built.** `scripts/okf-index.mjs` + `okf-check.mjs` (conformance checker) + `lib/frontmatter.mjs` + skill `okr-second-brain-search` **v1.6.0** ("OKF-compatible markdown wiki") + tests + fixtures (`okf-minimal/`, `okf-realistic/`) + `inject-okr-context.mjs`. | Structured + retrieval (built) | +| **ms-ai-architect** | **Designed, not built.** `docs/okf-second-brain-brief-2026-06.md` (operator-confirmed) + `ref-kb-direction-note` + `ref-kb-workflow-plan`. No retrieval skill yet. | Designed | +| **linkedin-studio** | **Built, richer non-OKF schema.** `brain/` hub + `ingest/{inbox,published}` + `journal/` (episodic) + two-layer `profile.md` (semantic), provenance-weighting, evidence-threshold promotion, temporal validity. Engine: `scripts/brain/`. | Provenance-weighted learning system (most mature) | + +**Reading of the siblings' own docs:** they chose OKF because their second brains lived in ad-hoc `org/*.md` +**with no retrieval mechanism** — for them OKF (really: *structured markdown + a retrieval skill*) was an +upgrade from nothing. linkedin-studio is already past that point. So the convergence is "siblings rise to +the reference," not "everyone adopts a new format." + +## 4. okr already supplies the reference checker + +`okr/scripts/okf-check.mjs` implements **exactly the minimal contract** this brief recommends, and is the +de-facto reference implementation to align the shared spec with: + +- **Only `type:` is required** on a concept file (`.md` except `index.md`); ≥1 file without `type` → fail. +- Recommended fields (`resource`/`title`/`description`/`timestamp`) → **warnings, not errors**. +- Root `index.md` carries an `okf_version` marker, echoed for human comparison — **no auto-fetch** (hooks + are no-network). + +This means okr has **both** a writer and a checker in production. The shared artifact should generalize +okr's checker semantics, not reinvent them. (Reading okr's code is fine; **writing** okr is a separate go.) + +## 5. OKF v0.1 — verified core contract + +Source: `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md` (v0.1, 12 June 2026, +"a starting point, not a finished standard"). + +- **Bundle** = a directory tree of markdown files, **one concept per file**. **Concept ID** = file path + minus `.md`. +- **Frontmatter:** required `type` (free string); recommended `title`, `description`, `resource` + (canonical source URI), `tags`, `timestamp`. **Consumers MUST preserve unknown keys and tolerate unknown + `type` values.** (Note: the Google *reference producer* is stricter than the spec — it also requires + `title`/`description`/`timestamp`. Build to the spec; supply the rest where cheap.) +- **Reserved filenames:** `index.md` (directory enumeration, **no frontmatter**, progressive disclosure) + and `log.md` (change log). Optional `okf_version` lives in the bundle-root `index.md`. +- **Cross-links:** plain markdown links (bundle-relative `/...` or relative); relation type is conveyed by + prose. **Consumers MUST tolerate broken links.** +- **Permissiveness is the whole point for us:** OKF is a *minimal superset-friendly* contract. Conforming + costs `type` + `index.md`; our rich fields ride along untouched as extension keys. + +## 6. The deliverable — "OKF-compatible second-brain form" + +A spec (document, not code) that all three plugins' user-data conforms to: + +1. **Minimal contract:** every concept file carries `type:`; each directory level has an `index.md`; + bundle-root `index.md` carries `okf_version`. Recommended fields where cheap. (= okr's `okf-check` + semantics, generalized.) +2. **Rich fields survive as extension keys.** linkedin-studio's brain keeps `provenance`, `first_seen`, + `last_seen`, `evidence_count`, `status`, episodic/semantic distinction — all as extra frontmatter keys + OKF must preserve. The model-collapse guard (`provenance=published` only) is unaffected. +3. **Mapping for our brain** (illustrative; verify writers in §10): + - `brain/index.md` → bundle-root index + `okf_version`. + - `brain/profile.md`, `operations.md`, `journal/*.md`, tributary summaries → concept files; each gains a + `type` (e.g. `Profile`, `Operations`, `JournalEntry`, `TributarySummary`) + retains its existing rich + frontmatter. + - `ingest/inbox/` stays the **manual drop-zone** (already exists) — the "inbox folder" mechanism, with + no heavy auto-classifier built now. + +## 7. Staged plan + +- **Stage 1 — Shared spec/convention (cheap, delivers interop).** Author "OKF-compatible second-brain form" + as a cross-cutting document; align it with okr's `okf-check`. Each plugin's user-data conforms; one + reader can traverse all three. **This alone meets the interop goal.** +- **Stage 2 — Measure divergence.** Do the per-plugin retrieval skills (okr's built one; architect's + planned one; linkedin-studio's in-context reads) diverge enough to hurt? Only a *measured* yes justifies + Stage 3 (operator anti-pattern: "ambitious initiatives where a config tweak suffices"). +- **Stage 3 — Conditional shared skill.** If justified: extract/generalize okr's working + `second-brain-search` into one home (see §9), with a discovery convention for where each plugin's brain + lives. + +## 8. Home decisions + +- **The spec** is cross-cutting → **catalog/marketplace level** (owned by no single plugin). +- **A future shared skill** (Stage 3 only) → a **standalone marketplace plugin** (own repo, release-tagged, + catalog-pinned), installable alongside the others, serving **consumer (a) — the user's own context — + directly**. Rejected alternatives: duplicate-per-plugin (drift risk); user-level `~/.claude/skills/` + (unversioned, outside the catalog). + +## 9. Per-repo scope boundaries (each its own explicit go) + +| Repo | This initiative's work | Status | +|---|---|---| +| **linkedin-studio** (here) | (1) Be the reference design (mostly exists in `docs/second-brain/architecture.md`). (2) Make our own brain emit OKF-compatible form (`type` + per-level `index.md` + root `okf_version`) without dropping rich fields. | **In scope — (2) ✅ LANDED 2026-06-26** | + +> **Stage-1 outcome (2026-06-26).** Brain writers now emit OKF-compatible form: `serializeProfile` +> leads with `type: Profile` frontmatter (constant → round-trip-safe), `operations.md` seed leads with +> `type: Operations`, `brain/index.md` carries an `okf_version: 0.1` marker, and `brain/journal/index.md` +> is scaffolded (per-level index). **Premise refinement (verified):** the brain is *deliberately* +> YAML-free with a byte-exact round-trip invariant on `ingest/published/*.md` (SC2) that a frontmatter +> block would break — so the OKF concept-bundle is scoped to **`brain/` only**; the round-trip-critical +> **`ingest/` tributary is excluded** and pointed to from the hub index. We **emit** frontmatter, adding +> no YAML parser. 5 new tests (`tests/okf-conform.test.ts`); full brain suite **132/132**; cross-tool +> proof — `okr/scripts/okf-check.mjs` validates `brain/` (exit 0). **Deferred:** the transient +> `brain/pending-diff.md` (cli propose artifact) is an un-typed `.md`; tag or document-exclude later. +| **okr** | Optional form-conformance alignment (already has writer + checker). | **Separate go** | +| **ms-ai-architect** | Build its retrieval skill against the shared spec. | **Separate go** | +| **catalog** | Host the shared spec. | **Separate go** (catalog only via `release-plugin.mjs`) | +| **new standalone plugin** | Stage-3 shared skill, if justified. | **Separate go** | + +Per scope-guard + "never write in other repos without explicit instruction": this session touches +**linkedin-studio only**. + +## 10. Key assumptions + tests (plan-quality mandate) + +| Assumption | Test (before relying on it) | +|---|---| +| OKF preserves unknown keys → our rich brain fields survive conformance | **✅ Verified:** `okf-check.mjs` exits 0 on `brain/`; `profile.md` round-trips (`parseProfile` skips the frontmatter, `parse ∘ serialize` identity holds). | +| Our brain is already near-OKF (conformance is a small writer change) | **⚠️ Refined → verified:** brain is *deliberately* YAML-free and `ingest/published` is round-trip-critical, so a literal frontmatter target conflicts there → bundle scoped to `brain/`, `ingest/` excluded (tributary). 4 surgical writer touchpoints (3 scaffold seeds + `serializeProfile`); we EMIT frontmatter, add no parser. | +| okr's `okf-check` semantics generalize as the shared conformance contract | Diff okr's contract (only-`type`-required, recommended=warnings, `okf_version` echo) against OKF SPEC §9 conformance → confirm it is a faithful, slightly-laxer subset. | +| A shared skill is *not yet* justified | Stage-2 measurement, deferred — do not build Stage 3 before it. | + +## 11. Open choices (resolve in `/trekbrief` or measurement, not now) + +- **Retrieval mechanism:** native Grep/Glob/Read (skill instruction "search the wiki first, open only + relevant") vs. a dedicated fileskb MCP server. Both sibling docs lean **native** (Claude Code's + Grep/Glob/Read already cover OKF's list/search/read). Genuine doubt → "build both, measure" candidate. +- **Degree of OKF formalism:** full v0.1 conformance vs. "OKF-compatible form" (frontmatter + `index.md` + only). Lean to the lightest that yields smart retrieval. +- **Inbox auto-classify/convert:** **defer.** OKF gives nothing for it; the manual inbox seam already + exists. Build only on demonstrated need. +- **Discovery convention:** how a shared skill finds each plugin's brain root. +- **OKF version-bump tracking:** how to catch v0.1 → later without manual polling (hooks are no-network). + +## 12. Success criterion (operator, inherited from both sibling tracks) + +Measured against **user value** (does the plugin retrieve the right personal/org context in chat and +commands?) + **maintenance reliability** — **not** against formal OKF conformance for its own sake. + +## 13. References + +- OKF SPEC v0.1: `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md` +- Sibling design docs: `okr/docs/okf-second-brain-note-2026-06.md`, + `ms-ai-architect/docs/okf-second-brain-brief-2026-06.md`, + `ms-ai-architect/docs/ref-kb-direction-note-2026-06.md` +- okr reference implementation: `okr/scripts/okf-check.mjs`, `okr/scripts/okf-index.mjs`, + `okr/skills/okr-second-brain-search/SKILL.md` +- Our reference design: `docs/second-brain/architecture.md`; engine `scripts/brain/` +- Verified-OKF research log (files+URLs fetched on `main`): retained in session transcript, 2026-06-26 +- Memory: `google-okf-open-knowledge-format`, `profile-evolution-second-brain`, + `plugin-vs-maskinrommet-division`, `plugin-is-domain-general`