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

• 2026-07-24 — STEG 0: nav-golden fixture class consumed + thin corpus gate landed (test/nav-golden-corpus/ + scripts/check-nav-golden.mjs + check-nav-golden.test.mjs). commons authored a nav-golden fixture class — each fixture is an OKF bundle paired with a committed byte-exact expected-read-context.md golden (the fasit a conformant read-context navigator, commons method-spec.md §3 Step 1 + §11 Navigation boundary, must produce). Consumed byte-exact from portfolio-optimiser-commons b641741 (nav-golden-hierarchy positive + nav-golden-escape boundary; diff -r identical; .gitattributes -text pins bytes; manifest carries source repo+SHA per vendoring rule #7). Scope decision (operator, thin): the catalog is the convention owner and holds no consumer (null konsument), and the shared retrieval skill is deferred (spec §10 Stage 3, "do not build before Stage 2 says so") — so the gate does not run a navigator and does not assert the goldens byte-exact. It asserts only what the catalog owns: each fixture bundle/ is a conformant OKF bundle under the existing §3 checkBundle (every concept typed + root okf_version), and the committed golden is present + non-empty. Byte-exact navigator conformance stays a consumer concern (okr STEG 4 / the deferred Stage 3 skill). Naming correction (relayed to + confirmed by commons via coord): the earlier record's "§5 pts 1-5" read-context label was stale — the settled normative location is method-spec §3 Step 1's five read-context bullets (commons 9801d35); there is no open §5 dependency (current spec §5 = extension keys). commons confirmed both prerequisites: Q1 b641741 is the complete nav-golden set (future cases additive, non-moving); Q2 the goldens derive from settled §3 Step 1. Verified: check-nav-golden 10/10; gate CLI → exit 0 (2 fixtures PASS — hierarchy 5 concepts / escape 1, okf_version 0.1, goldens present); full suite 73/73 across the six test files. (catalog session.)

• 2026-07-25 — STEG 4: §3 tightened (non-enforcing) on the okf_version / okf_layout split. §3's okf_version MUST now states the value is the upstream version alone, with a plugin's own layout revision belonging in the optional okf_layout marker (§12) — and marks itself not yet enforced: no checker validates the value's shape, so an emitter still carrying a layout string conforms today. No convention version bump — §12 ties a bump to a change in the §3 floor, and the set of conforming bundles is unchanged (a clarification, deliberately non-enforcing). Why non-enforcing (okr's answer, received via coord): okr ratified the split and owns the migration, but scripts/okf-* is file-fenced frozen through their 1.8.0 consolidation (Wave 4/6); the migration runs as scoped work right after release. It is an ETA, not an open blocker — their field is pure echo text with no validation semantics, so they do not fail the gate meanwhile. Making §3 enforce okf_layout presence now would redden the STEG 3 parity gate on okr with nothing they could do until 1.8.0 ships. Enforcement is therefore a separate scoped step, after their migration. Also settled this round (all verified against ground truth, not accepted as asserted): (a) D2 roll-up carrier is a no-op for the public-mirror class — build-rollup-register.mjs defaults carrierMode to absent and only committed reaches output B, so okr, ms-ai-architect and claude-code-llm-wiki are excluded by design, never reported as missing/malformed; no code change. (b) The catalog runs no index.md generator — read-side only (okf-check.mjs:45, check-nav-golden.mjs:48); commons' inherited "catalog regenerates index.md" item (ingest-spec §6) is stale and needs no §6 ruling. (c) okf_version ruling already existed — spec §12 (lines 174–186) settled it; llm-ingestion-okf was pointed at the written text rather than issued a new one. (d) Correction issued to llm-ingestion-okf: their premise that the catalog's okf-check.mjs is "vendored byte-identical from okr" — and thus their Phase 4 conformance oracle — is false (141 diff lines; okr's copy adds strictIngest, files scoping, innboks/dot-dir exclusion and lib/ deps). Parity here is behavioural on the §3 floor in default read-mode, gated by check-okf-parity.mjs, never byte identity; their impl's real entry point is that gate's n-way IMPLS registry behind available(), not a catalog ref (they are not a marketplace plugin, and check-versions.mjs/release-plugin.mjs operate only over marketplace.json entries). Verified: full suite 73/73 across the six test files; check-versions 11 OK · 0 WARN · 0 ERROR. (catalog session.)

• 2026-07-25 — STEG 5 (installation root) settled as descriptive, not normative: the sample does not support a mandated path form. The ecosystem was asked where each consumer installs its bundle. Every answer was given against code, not docs, and each was re-verified here before being acted on:

  • okr — the only real installation. Two roots: project .claude/okr/ ahead of home ~/.claude/okr/org/, each checked per-root (okr scripts/okf-check.mjs:11, lib/innboks-write.mjs:44).
  • portfolio-optimiser-commons — declined, correctly. Spec owner with no runnable pipeline; its only bundle-shaped bytes are conformance fixtures, so answering would have codified a test artifact as an installation site.
  • portfolio-optimiser — no root. --bundle-dir defaults to None (run.py:653); absent it, the feature is simply off. Verified here: 0 hits for expanduser|Path.home|.claude/ across src/.
  • portfolio-optimiser-claude — no root. --bundle defaults to None (run.py:554); bundle_dir is a required non-empty config field (contracts.py:81). Verified here: 0 hits for the same patterns across src/.

  One installation, three non-installations — so the standing acceptance criterion ("three installations before normative text") is not merely unmet, it is unmeetable from this population. Landed in spec.md as exactly two things: the §1 in-scope example corrected (it showed a lone ~/.claude/<plugin>/… form that misstates okr's project-first precedence), and a new §8 bullet naming placement unmandated, "no installation root" a conforming consumer shape, and installing vs. writing separate axes (a consumer may write into a bundle it never placed). No normative path form was written.

  Two things the responses did not supply, both found here: (a) neither portfolio-optimiser repo reads okf_version at all (0 hits in src/ for both), so neither is evidence for or against marker-based discovery — though p-o-claude's fixture carries the marker, so a marker-based reader would still recognise it. (b) p-o-claude's own account ("two entry points, both with no default") is inexact: run_s10.py:46 is a third --bundle entry point and it does carry a default — parents[2]/shared/examples/bygg-energi-mikro, a repo-relative fixture. That leaves their headline standing (no ~/$HOME/.claude anywhere in src/) but it is the same fixture-as-location class commons declined to answer from; returned to them.

  This confirms distilled note 3 ("discovery, not placement") rather than extending it — the measured population is dominated by that chain's first link, an explicit caller-supplied param. It also bears on Stage 2 (§10): the evidence points away from a Stage-3 discovery convention, since three of four consumers have nothing to discover. (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.