open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Releases Activity

docs(okf): run the §12 re-check against Google OKF v0.2 — three corrections, floor unchanged

Browse source 
§12 says "When Google bumps OKF, each plugin re-checks conformance." Google
bumped 2026-07-25; commons ruled the trigger catalog's to pull and the plugin
owners' to perform. This is the pull.

Held: upstream has NOT moved (git ls-remote answers 3fcbb9f, identical to the
mirror the 0.3 round read; SPEC last touched 2026-07-24 in 780fe9d). All seven
upstream anchors resolve exactly, quotes verbatim. The §3 floor is conformant
with upstream §11. No floor change -> the convention stays at 0.3.

Corrected:
1. §14 said "OKF SPEC v0.1" while linking blob/main/okf/SPEC.md, which has
   served v0.2 since 2026-07-24 — a reader following our own reference got
   v0.2 under a v0.1 label.
2. §3 attributed to upstream a rule upstream does not state: "upstream binds
   the index.md requirement to the bundle root alone", cited to commons'
   method-spec.md. Google requires index.md NOWHERE (SPEC :117 "Optional",
   :504 "MAY appear in any directory", :759 consumers MUST NOT reject for
   missing index files). Three rungs, not two; ours is highest either way, so
   only the attribution was wrong.
3. §4 now names v0.2's second breaking change (# Citations -> sources).
   Measured 2026-08-03: no marketplace emitter writes # Citations; the one
   live exposure is a plan, not code — ms-ai-architect's brief still names an
   upstream v0.1 example as the template to copy.

Suites 120/120, 0 fail. check-versions 12/12 OK.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01THEvHPWM11RupX24wBGKLu
This commit is contained in:
Kjell Tore Guttormsen 2026-08-03 20:46:05 +02:00
commit 552784e262
2 changed files with 76 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

43
docs/okf-second-brain/spec.md
View file

@ -74,12 +74,23 @@ file path minus `.md`.
- **MUST (consumers)** — preserve unknown frontmatter keys, tolerate unknown `type` values, tolerate
broken cross-links.
This is a **superset** of upstream OKF, not a restatement of it. The difference is deliberate and
sits in one place: upstream binds the `index.md` requirement to the **bundle root alone** — a nested
directory without its own `index.md` is not an error there (`method-spec.md:81-85`) — whereas the
MUST above binds **every** level. §8 permits a plugin to go further than the floor; this is the
catalog exercising that, and a reader must not take it as upstream's requirement restated. okr's
`okf-check.mjs` (§7) is the reference implementation of *these* semantics.
This is a **superset** of upstream OKF, not a restatement of it — and it is a superset of **two**
contracts, which this document through 0.3 collapsed into one. There are three rungs, not two:
1. **Upstream requires `index.md` nowhere.** Its structure diagram marks the file `# Optional`
(`okf/SPEC.md:117`), §8 opens «An `index.md` file MAY appear in any directory, including the
bundle root» (`:504`), and §11 forbids a consumer to reject a bundle for «Missing `index.md`
files» (`:759`). Read at `3fcbb9f`.
2. **A sibling contract binds the requirement to the bundle root alone** — commons'
`method-spec.md:81-85`: a missing root `index.md` is an error, «this binds the **root alone**»,
and a nested directory without its own `index.md` is not an error.
3. **The MUST above binds every level.** Highest rung; ours.
§8 permits a plugin to go further than the floor, and this is the catalog exercising that. A reader
must not take the MUST as upstream's requirement restated — **nor attribute rung 2 to Google, which
does not state it** (through 0.3 this paragraph did, citing `method-spec.md` for a sentence that
said "upstream"; corrected 2026-08-03 against `3fcbb9f`). okr's `okf-check.mjs` (§7) is the
reference implementation of *these* semantics.
## 4. Recommended fields (warnings, not errors)
@ -94,6 +105,16 @@ marker whose name depends on the bundle's `okf_version` (below). Supply where ch
(`:804`). The gate therefore asks each bundle for the marker its own version names, and never
nags a correct bundle of either version. An absent or non-version-shaped `okf_version` gets
the legacy floor: absence is echoed, not failed (§3), so it still needs a defined list.
- **v0.2's *other* breaking change does not reach this floor — but it reaches a template.** Upstream
also superseded the body `# Citations` list with frontmatter `sources`: consumers «SHOULD read
`sources` and MAY still parse a legacy `# Citations` body list for v0.1 documents»
(`okf/SPEC.md` §13.1:806-808, read at `3fcbb9f`). `sources` is recommended here, never required,
so the §3 floor is untouched whichever form a bundle carries. **Measured 2026-08-03: no
marketplace emitter writes `# Citations`.** The live exposure is a *plan*, not code —
ms-ai-architect's design brief still names an upstream v0.1 example as the template to copy,
carrying both `timestamp` and a `# Citations` section (`ms-ai-architect`
`docs/okf-second-brain-brief-2026-06.md:56`). A bundle built from that template would be
v0.1-shaped on **both** retired fields, which is conformant but ages the day it is written.
- **Canonical name is `resource`** (the OKF spec's name) — **not** `source`.
- A field that would break a plugin's invariant may be omitted. Example: linkedin-studio omits
`timestamp` (its serializer is pure/deterministic — a timestamp would break round-trip) and
@ -282,8 +303,14 @@ commands?) + **maintenance reliability** — **not** against formal OKF conforma
## 14. References
- **OKF SPEC v0.1:** `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`
(12 June 2026, "a starting point, not a finished standard").
- **OKF SPEC:** `github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`. **`main`
has served v0.2 since 2026-07-24** (`780fe9d`, "okf: migrate format and tooling to Open Knowledge
Format v0.2"; the SPEC was last touched at `3fcbb9f` the same day, and upstream had not moved
when this was re-checked on 2026-08-03). Every upstream anchor in this document was read at
`3fcbb9f`. Upstream publishes **no tags**, so the v0.1 text — the version this convention targets
on the `okf_version` axis (§12) — is reachable only through history.
_(Through 0.3 this entry read "OKF SPEC v0.1" while pointing at `main`; label and link had
disagreed since the upstream bump. A reader following it got v0.2 under a v0.1 label.)_
- **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`.
- **Shared checker (the cross-plugin gate):** `catalog/scripts/okf-check.mjs` (+ `okf-frontmatter.mjs`,