feat(catalog): shared OKF conformance checker + wire as cross-plugin acceptance gate

Lift okr's reference okf-check.mjs into the catalog as the single cross-plugin
acceptance gate for the OKF-compatible second-brain form (spec §3):

- scripts/okf-check.mjs (+ vendored okf-frontmatter.mjs): verdict logic
  byte-identical to okr's reference impl, English output, zero deps, self-contained.
- scripts/okf-check.test.mjs: 5 self-contained tests (temp-dir bundles).
- spec §7 + §14: the shared checker now lives here; only TS/mjs reconciliation
  remains Stage-3, not required for the gate. log.md protocol §6: conformance is
  verified by the gate, not asserted — a plugin moves to 🟢 only after passing it.

Verified: 33/33 catalog tests green (canonical glob form); verdict parity with
okr's checker on okr fixtures (positive + negative missing-type); a scaffolded
linkedin-studio brain/ validates clean (exit 0).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012GqEHp4uDiivfrAUjw4BdE
This commit is contained in:
Kjell Tore Guttormsen 2026-06-29 10:27:05 +02:00
commit c06e4d7b55
5 changed files with 262 additions and 6 deletions

View file

@ -26,6 +26,9 @@ pattern):
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
@ -35,7 +38,7 @@ distinct from conformance (code landed), which `linkedin-studio` alone holds so
| 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; okr's `okf-check` validates `brain/` → exit 0 (also mid-propose with a pending-diff present). | 🟢 conformant @ linkedin-studio `da0a16a` (2026-06-26) |
| **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 |
@ -79,3 +82,10 @@ distinct from conformance (code landed), which `linkedin-studio` alone holds so
`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.)_

View file

@ -84,10 +84,22 @@ only `type` required (missing → fail + names the files), recommended fields
npm dependencies, only couples to a ~55-line `frontmatter.mjs`. The shared spec **generalizes okr's
semantics; it does not reinvent them.** Reading okr's code is fine; **writing okr is a separate go.**
A **single shared checker** is a Stage-3 item (§10), deferred until measured need — note that
linkedin-studio already has a parallel **TypeScript** conformance implementation (`scripts/brain/`), so
a shared checker means reconciling two language implementations of the same convention. Cross-tool
interop is already proven: okr's `okf-check.mjs` validates linkedin-studio's `brain/` → exit 0.
A **shared checker now lives here:** `catalog/scripts/okf-check.mjs` (+ vendored
`okf-frontmatter.mjs`), lifted faithfully from okr's reference impl — verdict logic byte-identical,
output in English, zero deps, self-contained. It is the **canonical cross-plugin acceptance gate**: a
bundle's pass/fail is the same here as under okr's checker. Run it per bundle root:
```
node catalog/scripts/okf-check.mjs <bundle-root>
```
Verdict parity is verified — identical exit codes to okr's checker on okr's own fixtures
(`okf-minimal`, `okf-realistic`), positive and negative (injected missing-`type`) — and a scaffolded
linkedin-studio `brain/` validates clean ("OK: valid OKF bundle", exit 0). Each plugin may keep its own
dev-loop check (linkedin-studio's TypeScript impl under `scripts/brain/` stays for its own suite); the
catalog `.mjs` is the shared gate all three are measured by. The only Stage-3 remainder is *reconciling*
the two language implementations into one — deferred until measured need, and **not** required for the
gate to function.
## 8. Deliberately NOT mandated
@ -163,6 +175,8 @@ commands?) + **maintenance reliability** — **not** against formal OKF conforma
(12 June 2026, "a starting point, not a finished standard").
- **Per-plugin design notes:** linkedin-studio `docs/okf-convergence-brief.md`; okr
`docs/okf-second-brain-note-2026-06.md`; ms-ai-architect `docs/okf-second-brain-brief-2026-06.md`.
- **Reference checker:** okr `scripts/okf-check.mjs` (+ `okf-index.mjs`, `lib/frontmatter.mjs`).
- **Shared checker (the cross-plugin gate):** `catalog/scripts/okf-check.mjs` (+ `okf-frontmatter.mjs`,
`okf-check.test.mjs`) — lifted from okr's reference impl `okr/scripts/okf-check.mjs`
(+ `okf-index.mjs`, `lib/frontmatter.mjs`).
- **Reference design:** linkedin-studio `docs/second-brain/architecture.md`; engine `scripts/brain/`.
- **Coordination + rollout status:** `log.md` (this directory).