docs(linkedin-studio): OKF convergence brief — reference design, premise corrections, Stage 1 outcome

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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011vmzxpsFpc8q19LaogAWLD

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`