ktg-plugin-marketplace/docs/okf-second-brain/log.md

OKF second-brain convergence — coordination log

Cross-repo coordination for the OKF-compatible second-brain form (spec.md). This is the one shared place all three plugin sessions read to know where the others are. OKF reserves log.md for change logs; this extends it with rollout status + the coordination protocol.

No writing crosses repo boundaries — each plugin session writes only its own repo (+ the catalog with its own go). Status here is updated via operator relay.

Coordination protocol

The operator runs one Claude session per plugin repo and relays between them. To keep three independent sessions converged without cross-repo writes (mirrors the maskinrommet feedback-register pattern):

1. Single source of truth = spec.md. The convention is defined once, here. No plugin redefines it locally; a plugin's local OKF doc references this file. (Mirrors the global rule: don't invent local mechanisms; extend the shared one.)
2. This log is the cross-repo state. Convention version, decisions, per-plugin conformance status, open coordination items. All three sessions read it.
3. No writing crosses repo boundaries. Each session writes only its own repo. The catalog is shared but needs a per-session go. A plugin records its own conformance in its own STATE/changelog; the operator relays it here.
4. Operator = relay + truth-source. Convention changes are proposed by any session, written here (with go), and the operator carries "convention changed → re-check conformance" to the other sessions.
5. Two version markers (spec §12): okf_version (upstream Google OKF) and this convention's own version. Either bump → log it below → each plugin re-checks.
6. Conformance is verified, not asserted. A plugin's status only moves to 🟢 after its bundle passes the shared acceptance gate catalog/scripts/okf-check.mjs (spec §7) — node catalog/scripts/okf-check.mjs <bundle-root> → exit 0. On a relayed conformance landing, run the gate against that plugin's bundle and record the result here. Evidence-based flips only (operator verification-plikt).

Per-plugin conformance status

Legend: 🔵 not started · 🟡 building / partial · 🟢 conformant (+ commit-ref). Ratification (spec accepted + plan adapted) is recorded in the Status cell with the plugin's own commit-ref — distinct from conformance (code landed), which linkedin-studio alone holds so far.

Plugin	Against minimal contract (spec §3)	Notes	Status
linkedin-studio	type + per-level index.md + root okf_version on brain/; ingest/ excluded (round-trip-critical tributary)	Reference design. Emits frontmatter, adds no parser. Brain suite 134/134; passes the shared gate catalog/scripts/okf-check.mjs (scaffolded brain/ → "OK: valid OKF bundle", exit 0) — same verdict as okr's reference checker.	🟢 conformant @ linkedin-studio da0a16a (2026-06-26)
okr	type required + recommended-as-warnings + okf_version echo	Has the reference writer + checker (okf-check.mjs, okf-index.mjs, lib/frontmatter.mjs) + skill okr-second-brain-search v1.6.1.	🟡 built · spec ratified @ okr 75bfc9b (2026-06-29); conformance-alignment landing = own go
ms-ai-architect	designed, not built	Targets the fuller OKF package + a retrieval skill. Builds against this spec.	🔵 designed · spec ratified @ ms-ai-architect 72a7e2b (2026-06-29); build = own go

Landing protocol — how a sibling records conformance

When your plugin's bundle actually conforms (the work of step 4, done in your own session):

1. Record it in your own repo (STATE/changelog) — as the handoff already instructs.
2. Update THIS file (your own catalog-go): set your row in the status table above to 🟡 → "claims conformant @ <commit>, bundle <path>, awaiting gate-verification".
3. A linkedin-studio session then runs the shared gate against your bundle — node catalog/scripts/okf-check.mjs <path> — and, on exit 0, flips your row to 🟢 with the proof.

This puts the landing signal in the one shared doc, so the operator need not hand-carry status, and any session sees the truth on its next read. Honest limit: there is no live push-notification across separate sessions — a landing is discovered when a session next reads this log (a linkedin-studio session is told to check it at start; see its STATE). Self-flipping straight to 🟢 is not the protocol; 🟢 is reserved for the independent gate-verified step (operator verification-plikt).

Open coordination items (what each session must confirm)

✅ Resolved 2026-06-29 — both siblings ratified. okr (75bfc9b) and ms-ai-architect (72a7e2b) ratified spec.md and adapted their plans. The items below are accepted via ratification; they are kept as the record of what was asked. Any new field-gap, change-proposal, or conformance landing arrives as a fresh item / status bump, not here.

→ okr session:

• Confirm okf-check.mjs semantics are stable enough to stand as the reference contract (spec §3, §7), and that this spec faithfully generalizes them (only-type-required; recommended → warnings; okf_version echo).
• Canonical recommended-field name is resource (OKF), not source — confirm okr uses resource.
• Flag any field okr needs that the minimal contract + recommended set doesn't cover.

→ ms-ai-architect session:

• Confirm the minimal contract + extension-key model (spec §3, §5) supports the planned "full OKF package" KB structure — going fuller is fine; the minimal contract is the floor, not the ceiling.
• Field-name drift: the architect brief writes source/timestamp (line 45); canonical is OKF's resource. Align on resource.
• mdcode is not an OKF tool (spec §9.1) — drop it from the adoption plan. The reference_agent enrichment is GCP/Gemini-bound (spec §9.2) — adopt the prompt patterns, not as drop-in code.

→ both:

• Ratify spec.md as the shared contract, or propose changes here.
• Retrieval-skill naming/home: okr shipped okr-second-brain-search; architect plans second-brain-search. If a shared skill ever happens (Stage 3), converge naming + home (standalone plugin, spec §11) — not now (Stage 2 measurement must justify it first).

Change log

• 2026-06-29 — Convention v0.1 authored (spec.md) + this log. Seeded from the three per-plugin design notes + linkedin-studio's verified premise corrections (mdcode ≠ OKF tool; no reusable OKF ingest code; classify/convert is build-yourself). linkedin-studio recorded 🟢 (brain emits OKF-compatible form, cross-tool-verified against okr's okf-check). okr / ms-ai-architect rollout = separate per-repo go. (Authored by the linkedin-studio session; operator relay to siblings pending.)
• 2026-06-29 — Stage 1 ratification complete across all three tracks. okr ratified spec v0.1 + adapted plan @ okr 75bfc9b; ms-ai-architect ratified spec v0.1 + adapted plan @ ms-ai-architect 72a7e2b (both relayed via operator). The shared contract is now accepted by all three — the interop goal of Stage 1 is met at the convention level. Conformance landings (okr form-alignment, ms-ai-architect build) remain each their own go. (linkedin-studio session, operator relay.)
• 2026-06-29 — Shared acceptance gate landed (catalog/scripts/okf-check.mjs + okf-frontmatter.mjs + okf-check.test.mjs). Lifted faithfully from okr's reference impl; verdict logic byte-identical, English output, zero deps, self-contained. Verified: 33/33 catalog tests green; verdict parity with okr's checker on okr fixtures (positive + negative); a scaffolded linkedin-studio brain/ validates clean (exit 0). Wired as the conformance gate (protocol §6 + spec §7): a plugin only moves to 🟢 after passing it. The only Stage-3 remainder is reconciling the TS/mjs impls — not required for the gate. (linkedin-studio session.)