docs(catalog): add OKF second-brain handoff brief for okr + ms-ai-architect

Action brief the operator hands to the two sibling second-brain sessions:
read spec.md + log.md, confirm per-plugin items, update STATE.md, adapt the
plan, and acknowledge back in their own repo (operator relays -> log.md status).
Carries the three verified premise corrections (mdcode != OKF tool; no reusable
OKF ingest; resource not source) and a deterministic acknowledge-back line.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012GqEHp4uDiivfrAUjw4BdE

docs/okf-second-brain/handoff-2026-06-29.md

@@ -0,0 +1,68 @@
+# Handoff — OKF second-brain shared spec landed (→ okr + ms-ai-architect)
+
+> **2026-06-29. From the linkedin-studio session, via operator relay.** Action brief for the two sibling
+> second-brain tracks. Read alongside `spec.md` (normative contract) + `log.md` (coordination protocol +
+> status), same directory. Files are readable on local disk now even though the catalog commit is not yet
+> pushed.
+>
+> **This is a directive to act:** confirm the items for your plugin, **update your STATE.md**, **adapt your
+> plan**, and **acknowledge back in your own repo** (no writing crosses repo boundaries — the operator
+> relays your acknowledgement; linkedin-studio updates `log.md`).
+
+## 1. What changed (both plugins)
+
+- **The shared convention now exists as one cross-cutting catalog doc:** `catalog/docs/okf-second-brain/spec.md`.
+  It is the **single source of truth** for the OKF-compatible second-brain form. Do **not** redefine the
+  convention locally — your plugin's local OKF note should now *reference* the spec, not restate it.
+- **linkedin-studio's brain is the agreed reference design**; OKF is a thin interop veneer. Your rich fields
+  survive as **extension keys** (spec §5) — you rise toward the reference, you are **not** levelled to bare OKF.
+- **The minimal contract is a floor, not a ceiling** (spec §3): `type:` on every concept file + an `index.md`
+  per directory level + `okf_version` in the bundle-root `index.md`. Going fuller is per-plugin and never
+  required by the spec.
+
+## 2. Three verified premise corrections (these may change your plan)
+
+Ground-truth-checked against the live `GoogleCloudPlatform/knowledge-catalog` repo (spec §9):
+
+1. **`mdcode`/`kcmd` is NOT an OKF tool** — it's a Dataplex git-sync tool with a different frontmatter schema.
+   Drop any plan to emit/sync OKF via it.
+2. **No reusable OKF *ingest* code exists** — `reference_agent` is BigQuery+Gemini/GCP-bound. Adopt the
+   *prompt patterns*, not as drop-in code. Classify/convert of documents is build-yourself.
+3. **Canonical recommended-field name is `resource`**, not `source`.
+
+## 3. Your action (both — same five steps)
+
+1. **Read** `spec.md` + `log.md`.
+2. **Confirm** your plugin's items in §4 below (or propose changes in `log.md` via the operator).
+3. **Update your STATE.md** — repoint your «👉 NESTE» block so the OKF work *builds against the shared spec*,
+   and record the premise corrections (§2) so the next session doesn't re-plan against the old framing.
+4. **Adapt your plan** accordingly (see per-plugin notes in §4).
+5. **Acknowledge in your own repo** (STATE/changelog), using this exact line so the relay is deterministic:
+   `OKF second-brain spec v0.1 ratified + plan adapted @ <your-commit-ref> (<date>)`
+   The operator relays it; linkedin-studio flips your row in `log.md` and resolves the open item.
+
+## 4. Per-plugin specifics
+
+### okr
+- **Confirm:** `okf-check.mjs` semantics are stable enough to stand as the reference contract, and spec
+  §3/§7 generalizes them faithfully (only-`type`-required; recommended → warnings; `okf_version` echo).
+- **Confirm:** okr uses `resource` (not `source`).
+- **Flag** any field okr needs that the minimal + recommended set doesn't cover.
+- **Plan impact:** likely small — you already have writer + checker + skill `okr-second-brain-search`
+  v1.6.1. Mostly: ratify the spec + align field naming if needed. (Writing okr is a separate go.)
+
+### ms-ai-architect
+- **Confirm:** the minimal contract + extension-key model (spec §3/§5) supports your planned **full OKF
+  package** — fuller is fine; the minimal contract is the floor.
+- **Adapt:** drop `mdcode` from the adoption plan (§2.1); treat `reference_agent` enrichment as *patterns*,
+  not drop-in code (§2.2); switch `source` → `resource` (brief line 45).
+- **Plan impact:** your "full package" direction stays valid, but **build the retrieval skill against this
+  spec**, and budget the ingest/enrichment as build-yourself (no reusable OKF library). (Building is a
+  separate go.)
+
+## 5. Confirm-back loop
+
+Each plugin acknowledges in its own repo → operator relays → linkedin-studio updates the `log.md` status
+table (🔵/🟡 → ratified/conformant) and closes that plugin's open coordination item. That keeps three
+independent sessions converged with the operator as the single relay, and no writing crossing repo
+boundaries.