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

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

View file

@ -25,7 +25,8 @@ pattern):
(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.
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).
@ -147,6 +148,19 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
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.)_
## Distilled architecture notes (OKF round, 2026-07)