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).

Deferred decisions

• Spec §3/§6 vs. the gate's actual coverage. The shared gate okf-check.mjs (faithfully lifted from okr's reference) fails only on a concept file missing type:. It does not fail on a missing root okf_version (echoed as MISSING, not an error), missing per-level index.md (§3 MUST), or an index.md that carries frontmatter (§6 says it should not). So "passes the gate" = "every concept file has type:" — a necessary but partial §3 signal, not full §3/§6 conformance. Surfaced when portfolio-optimiser's bundle (index.md with frontmatter) passed. To resolve in Stage 2 / a spec↔gate reconciliation: either tighten the gate to enforce more of §3/§6 (costs the proven verdict-parity with okr's checker) or relax the spec's MUSTs to match what the gate actually enforces. Not changed now — tightening would silently break okr parity. (linkedin-studio session, 2026-06-29.)

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.)
• 2026-06-29 — Ekstern form-konsument notert: portfolio-optimiser. Et separat Forgejo-rammeverk (MAF kostnads-optimiser, IKKE en marketplace-plugin) adopterte OKF- minimal-formen uavhengig for sine per-prosjekt runtime-kunnskapsbundles — en ANNEN scope enn denne konvensjonens bruker-second-brain (§1). Bundelen passerer den delte gaten (node catalog/scripts/okf-check.mjs <bundle> → okf_version 0.1, "OK: valid OKF bundle", exit 0) etter å ha lagt til rot-okf_version-markøren; commit portfolio-optimiser 812db23. Registrert så on-disk-FORMEN ikke driver fra hverandre i økosystemet (global regel: konformer til den delte formen, ikke re-derive). IKKE et 4. konvergens-medlem — ingen bruker-second-brain, ingen delt ingestion (spec §8–9: build-yourself), ingen delt retrieval. Eneste framtidige overlapp: bygger portfolio-optimiser verdict-promotering (sitt «steg 8»), er den gjenbrukbare skrive-primitiven okr's okf-index.mjs + frontmatter-skriver. Kjente avvik på bundelen: 2 resource-warnings (utelatelse tillatt, §4); index.md beholder frontmatter (avviker fra §6 reservert-index, beholdt fordi dens okf.py-leser klassifiserer index på type). (Relayet fra portfolio-optimiser-sesjonen; bruk i en catalog-sesjon per protokoll §3.) Gate re-verifisert i denne catalog-sesjonen (uavhengig): shared/examples/bygg-energi-mikro → exit 0, 5 konsepter, 0 uten type, okf_version 0.1, nøyaktig de 2 resource-warnings nevnt (kilder-realiseringsgap.md, metode-ipmvp-a.md); index.md bærer frontmatter (type: index); commit 812db23 finnes lokalt. Påstandene stemmer.