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. (A third spec-§12 marker, the optional okf_layout, is a plugin-own layout snapshot — not a version; it triggers no cross-plugin re-check.)
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).	🟢 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 (diverges this copy further from okr — drift is two-way; fixes go upstream-first) or relax the spec's MUSTs to match what the gate actually enforces. Not changed now — there is no established okr parity to protect (see the 2026-07-23 correction below); the fix belongs upstream, then re-vendored. (linkedin-studio session, 2026-06-29; parity framing corrected 2026-07-23.)

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, validated by the shared gate 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 from okr's reference impl at c06e4d7; English output, zero deps, self-contained. Verified: 33/33 catalog tests green; the gate's own §3 verdicts held on okr fixtures (positive + negative) at lift-time; 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.
• 2026-07-23 — Parity claim retracted (drift correction). Earlier entries and spec.md §7 stated the catalog gate is "byte-identical" to / "in verdict parity with" okr's checker. That is false against okr's current checker. The copy was lifted once (c06e4d7, 2026-06-29) and never updated; okr began hardening the next day (3b45be7, 2026-06-30: skip innboks/+dot-dirs, scoped checkBundle(root, { strictIngest, files })) and added BOM/CRLF normalization weeks later (482effb, 2026-07-17; lib/frontmatter.mjs:23) — none of which the catalog copy has. The two can already diverge on the same input. The lift-time parity run was green but narrow (okr's own fixtures, bundle-verdict) and is now stale. Establishing parity is tracked separate work: a CI-run gate over a spec-derived adversarial corpus (check-okf-parity.mjs). Fixes go upstream-first — drift is two-way; re-copying okr is the cause, not the cure. (catalog session.)
• 2026-07-23 — okf_version / okf_layout split (spec §12). okf_version had been carrying two unrelated concerns — the upstream OKF version and a plugin's own layout revision. okr flagged this as a blocker and left the call to the convention owner: its bundle roots + fixtures stamp okf_version: kb-layout-2026-06 (a layout snapshot, not 0.1) — a known deviation okr already documented, and it proposed exactly this two-field split (verified against okr 056b652). Decision (owner, catalog): okf_version stays the upstream Google OKF version alone (value set owned by Google, single-valued — the bundle-root marker relies on that, §6); a new optional okf_layout marker line holds a plugin's own layout-revision snapshot. This step lands only the decision + spec text (§12) — not enforcement. §3 tightening that would flip okr's current value from "echoes an odd value" to "fails the gate" stays deferred to its own step; the field's re-check semantics are pure echo today, so okr's migration (move the value to okf_layout) is cheap when it happens, and it should happen before that tightening. Additive + disambiguating: the §3 floor is unchanged and okf_layout is optional, so the convention version stays 0.1 — no re-ratification triggered. (catalog session.)
• 2026-07-23 — STEG 3: the running parity gate landed (scripts/check-okf-parity.mjs + test/okf-parity-corpus/ + check-okf-parity.test.mjs). Parity is now a running per-file red/green signal over a committed spec-adversarial corpus, not a stale one-shot claim (retracted above). Verified scope blocker (ground-truth this session, 2 independent agents + grep): the round named ≥3 impls, but only two expose a runnable per-file checker — catalog + okr. llm-ingestion-okf's Python lib is a producer (no check_bundle, no CLI; checker is fase-2, its own repo); linkedin-studio's TS §3 logic lives only in private test helpers (not a participant). Decision (operator delegated on quality grounds): build the gate n-way-capable, wire the 2 real impls now, with a documented availability- guarded seam for the Python checker (fase 2) and its Node port (fase 4) — no faked third impl, no cross-repo code. Decisions the earlier record left open, now fixed: (a) per-file contract = each impl's existing checkBundle(root) return normalized to { conceptCount, untyped[], okfVersion }, compared per file (concept-set + type verdict), over default read-mode (strictIngest off, not files-scoped); (b) adapter convention = JS impls imported directly (both export checkBundle), zero subprocess/zero dep; cross-repo/other-language impls get a subprocess --json adapter when they exist; (c) corpus form = committed byte-exact fixtures (.gitattributes -text pins BOM/CRLF), the inspectable "borne proof"; (d) red-proof = expected: "diverge" fixtures the gate MUST go red on (byte + tree axes each carry one; canon = BOM+CRLF concept + innboks/ raw file, catalog FAIL vs okr OK). Axis decisions: IN = byte (BOM/CRLF), tree (innboks, dot-dir, node_modules[shared gap, both descend], duplicate-name, hierarchical); WITHDRAWN = verbatim/trailing-newline (trinn E §1); OUT of STEG 3 = path-forms (rerouted to §1.2/STEG 5). The git/FS-hostile axes (live symlink, NFC/NFD filename) are covered as runtime-materialized meta-tests (temp dir), not committed fixtures. The gate does not claim the two checkers are identical (they provably are not) — it makes their divergence a monitored fact. Verified: parity 8/8, node check-okf-parity.mjs → exit 0 ("parity holds"); regression 33/33; check-versions 10 OK. Fixes stay upstream-first (patching BOM-norm into the catalog copy would just re-diverge in the other direction). (catalog session.)

Distilled architecture notes (OKF round, 2026-07)

Durable conclusions from the cross-repo round (full working context retained by the catalog session):

1. One form, two depths. A flat bundle is a degenerate depth-1 of the spec §3 tree, not a separate form.
2. A shared fixture-suite is blocked on three things: a sibling's golden-test invariant, a commons-owned ingest spec, and this convention's own unimplemented per-level rule.
3. Discovery, not placement. The bundle marker is the root index.md + okf_version; resolution is explicit param → plugin config → environment → search root. The marker itself is inert.
4. A closed type vocabulary is a writer requirement, not a form requirement — it constrains the type value, not the field-set.
5. The parity check was actually run and was green — but at lift-time, against okr's own fixtures, at bundle-verdict granularity. "Spec-derived" is the load-bearing word, not "spec-owned": the corpus is derived from the spec, not certified by any one implementation.
6. No artifact may self-certify parity. Parity is a gate's output over a corpus, never a claim in a file's header or comment.
7. Vendoring requires a provenance pointer (source repo + SHA), a CI gate, and upstream-first fixes.