Kjell Tore Guttormsen
b27905303c
The shared gate enforces only the `type:` MUST, not §3's okf_version / per-level index.md MUSTs nor §6's index.md-no-frontmatter (inherited faithfully from okr's reference semantics). So "passes the gate" is a necessary-but-partial §3 signal. Surfaced by the portfolio-optimiser bundle (index.md with frontmatter) passing. Deferred to Stage 2 / a spec<->gate reconciliation — not changed now, since tightening would break the proven verdict-parity with okr's checker. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012GqEHp4uDiivfrAUjw4BdE
137 lines
11 KiB
Markdown
137 lines
11 KiB
Markdown
# 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.
|