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

docs(okf): split okf_version/okf_layout in spec §12 (STEG 2)

Browse source 
okf_version had been carrying two unrelated concerns — the upstream OKF
version and a plugin's own layout revision. Split into two markers:
okf_version stays the upstream Google OKF version alone (currently 0.1,
value set owned by Google, single-valued bundle-root marker); a new
optional okf_layout marker holds a plugin's layout-revision snapshot.

Verified against ground truth: okr 056b652 stamps
okf_version: kb-layout-2026-06 (fixtures + bundle roots) — a known
deviation okr itself flagged, and it proposed exactly this okf_layout split.

Lands only the decision + spec text — NOT enforcement (§3 tightening stays
deferred to its own step, so okr's current value isn't flipped to a gate
failure yet; its migration is cheap since the field is pure echo today).
Additive + disambiguating: §3 floor unchanged, okf_layout optional, so the
convention version stays 0.1 — no re-ratification triggered.

- spec.md §12: rewrite defining the split
- log.md: protocol §5 clarified (third non-version marker) + dated change-log entry

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NeK9hkxrU9wFPBYGYnSV1V
This commit is contained in:
Kjell Tore Guttormsen 2026-07-23 22:29:29 +02:00
commit 3be4321a79
2 changed files with 30 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -163,12 +163,21 @@ Ground-truth-checked against the live `GoogleCloudPlatform/knowledge-catalog` re
## 12. Versioning
Two independent version markers:
Markers are kept deliberately separate. A single field must not carry two unrelated concerns — the
upstream OKF version *and* a plugin's own layout revision — so those are two distinct markers:
- **`okf_version`** in each bundle-root `index.md` — the upstream Google OKF version the bundle targets
(currently `0.1`). When Google bumps OKF, each plugin re-checks conformance.
- **This convention's version** (top of this file) — bumped when the shared form changes. `log.md`
records both. Hooks are offline (no auto-poll); version drift is caught by human review + the
- **`okf_version`** — a marker line in each bundle-root `index.md` (§6); the upstream Google OKF version
the bundle targets (currently `0.1`). **Required (§3).** Its value set is owned by Google, so the field
has exactly one meaning and stays single-valued — the bundle-root marker (§6) relies on that. When
Google bumps OKF, each plugin re-checks conformance.
- **`okf_layout`** — an *optional* marker line alongside it; a plugin's own layout-revision snapshot
(e.g. `kb-layout-2026-06`). Its value set is owned by the emitting plugin — not by OKF, not by this
convention. It is **not** a version marker, never triggers a cross-plugin re-check, and a consumer that
doesn't recognize it ignores it. This is where a plugin stamps its own layout revision, keeping
`okf_version` reserved for the upstream version alone.
- **This convention's version** (top of this file) — bumped when the shared *form* (the §3 floor)
changes. `log.md` records bumps of the two versions (`okf_version` and this one); each triggers a
per-plugin re-check. Hooks are offline (no auto-poll); version drift is caught by human review + the
`okf_version` echo in `okf-check`.
## 13. Success criterion