feat(okf): enforce §3 okf_version shape, bump convention 0.1 -> 0.2

The 2026-07-23 reservation said enforcement waits until "the emitters have
migrated". Measured rather than assumed, and the emitter set turned out to be
TWO, not three:

  okr @0059da7       okf_version: 0.1 + okf_layout: kb-layout-2026-06. Migrated.
  linkedin-studio    scaffold.ts:38 -> okf_version: 0.1. Never carried a layout
                     string; has no okf_layout and needs none.
  ms-ai-architect    NOT an emitter. Zero index.md in the repo; okf_version
                     appears in one planning doc. The status table already said
                     "designed, not built" -- only the word "emitters" implied it.

Swept the whole marketplace plus the sibling consumer repos: every live
okf_version value is 0.1. The flip is a no-op today and locks the invariant.

The gate checks SHAPE (/^\d+(\.\d+)*$/), never membership: the upstream value
set is Google's (spec §12), so a bundle targeting a newer version passes. A
membership check would be the convention claiming a set it says it does not own
-- the over-reach class this round has corrected three times. Presence stays
unenforced (reported, not failed) as a separate §3 MUST.

Convention bumped 0.1 -> 0.2 by this log's own criterion: the set of conforming
bundles changed (the spec explicitly said a layout string "conforms today", and
rollout rule 6 defines conformance as gate output). The §12 per-plugin re-check
is pre-measured as finding zero violations.

Also closes a parity blind spot found while landing this: check-okf-parity
compared the okf_version VALUE, which is identical exactly when two impls
disagree about whether it is acceptable -- a false "agree" on the axis the gate
exists to watch. The signature now carries a boolean shape verdict, with
red-marker-layout as the committed red proof. Its "diverge" expectation encodes
okr's lag (they still pure-echo) and flips to "agree" when they mirror it.

And a correction the round earned: portfolio-optimiser enumerated their own
bundle surface and it is four, not three. The dormant fourth
(reference_domain.py:49 -> package data at :70) has no flag form at all, so our
published claim that the re-measurement surfaced "one" unreported entry was
itself one-of-two. Sharpens the standing rule: a search shaped like one entry
type cannot see another; install-vs-fixture is one instance, not the class.

Suite 73 -> 78. coord: PO replied, okr + llm-ingestion-okf notified (the latter
under the standing promise to flag any okf-check.mjs change).
This commit is contained in:
Kjell Tore Guttormsen 2026-07-25 20:32:30 +02:00
commit 6a72b26985
9 changed files with 227 additions and 11 deletions

View file

@ -8,7 +8,10 @@
// >= 1 file without type -> exit 1, count + names the files; 0 -> exit 0.
// - recommended fields (resource/title/description/timestamp) -> WARNING, not error.
// - the bundle-root index.md's `okf_version` is echoed for human comparison
// (no auto-fetch — offline by design).
// (no auto-fetch — offline by design), and its VALUE must be version-shaped:
// a plugin's own layout revision belongs in `okf_layout` (§12). Shape only —
// the upstream value set is Google's, not this convention's. Absence is still
// echoed, not failed.
//
// Provenance: lifted from okr/scripts/okf-check.mjs (the de-facto reference
// implementation; spec §7) at c06e4d7 (2026-06-29), with English output + a vendored
@ -48,6 +51,18 @@ function rootOkfVersion(root) {
return m ? m[1].trim() : null;
}
// spec §3: the value is the upstream OKF version ALONE; a plugin's own layout revision
// belongs in `okf_layout` (§12). This checks only that the value is version-SHAPED — it is
// deliberately NOT a claim about which upstream versions exist, because that value set is
// owned by Google (§12), not by this convention. Absence is a separate §3 MUST and stays
// unenforced here (echoed as MISSING). null when there is nothing to complain about.
const UPSTREAM_VERSION_SHAPE = /^\d+(\.\d+)*$/;
function okfVersionShapeError(value) {
if (value === null || UPSTREAM_VERSION_SHAPE.test(value)) return null;
return `root index.md: okf_version "${value}" is not upstream-version-shaped; `
+ "a plugin's own layout revision belongs in okf_layout (spec §12)";
}
export function checkBundle(root) {
const concepts = walkConcepts(root);
const missingType = [];
@ -63,11 +78,13 @@ export function checkBundle(root) {
if (!get(field)) warnings.push(`${rel}: missing recommended field "${field}"`);
}
}
const okfVersion = rootOkfVersion(root);
return {
scanned: concepts.length,
missingType,
warnings,
okfVersion: rootOkfVersion(root),
okfVersion,
okfVersionError: okfVersionShapeError(okfVersion),
};
}
@ -91,9 +108,13 @@ if (isMain) {
out.push(` ${r.missingType.length} files without type:`);
for (const f of r.missingType) out.push(` - ${f}`);
out.push(` okf_version: ${r.okfVersion || 'MISSING (root index without okf_version)'}`);
if (r.okfVersionError) out.push(` - ${r.okfVersionError}`);
out.push(` Warnings (recommended fields): ${r.warnings.length}`);
for (const w of r.warnings) out.push(` ! ${w}`);
out.push(r.missingType.length === 0 ? 'OK: valid OKF bundle' : `FAIL: ${r.missingType.length} file(s) missing type:`);
const failures = [];
if (r.missingType.length > 0) failures.push(`${r.missingType.length} file(s) missing type:`);
if (r.okfVersionError) failures.push('okf_version is not upstream-version-shaped');
out.push(failures.length === 0 ? 'OK: valid OKF bundle' : `FAIL: ${failures.join('; ')}`);
process.stdout.write(`${out.join('\n')}\n`);
process.exit(r.missingType.length === 0 ? 0 : 1);
process.exit(failures.length === 0 ? 0 : 1);
}