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).
2026-07-25 20:32:30 +02:00 · 2026-07-25 20:32:30 +02:00 · 6a72b26985
commit 6a72b26985
parent 3dad1f51ce
9 changed files with 227 additions and 11 deletions
--- a/docs/okf-second-brain/log.md
+++ b/docs/okf-second-brain/log.md
@ -324,6 +324,79 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
  the narrower one the grep actually proved — **no installation root anywhere in either `src/`**.
  Standing rule for the next round: ask for the enumeration, not the null result — a search shaped
  like an install path cannot see a fixture path. _(catalog session, on p-o-claude's correction.)_
+- **2026-07-25** — **The enumeration above was itself incomplete: two entries were unreported, not
+  one.** portfolio-optimiser answered our published finding by enumerating their own surface, and the
+  count is **four** (verified here against their tree @`9e149c6`, every site re-read):
+  `run.py:679` (`--bundle-dir`, `default=None`), `run.py:249` (library param `run_project(bundle_dir=)`,
+  default `None`), `simulation.py:48` `_default_bundle_dir()` (the fixture default we found), and
+  **`reference_domain.py:49` `Project.bundle_dir`** — a per-project path in the packaged reference
+  portfolio, threaded to `run_project` at `run.py:644` and resolved against **package data**
+  (`reference_domain.py:70`, `files("portfolio_optimiser").joinpath(f"data/{rel}")`). The shipped
+  `reference_projects.json` sets only `docs_dir`, so it is **dormant**: a capability with no value
+  today, and the day it gets one it points into Python package data.
+  - **What this corrects here:** the entry above says our re-measurement "surfaces **one** neither
+    side had reported". It surfaced one **of two**. The claim implied a completeness the enumeration
+    did not have — the same shape of over-reach as the null-result inference it was correcting.
+  - **Why the dormant one is the interesting miss:** it has no flag form at all. It is a key in
+    packaged JSON, so no search shaped like a CLI entry point — ours or theirs — could ever have seen
+    it. That sharpens the standing rule: *a search shaped like one entry type cannot see another*, of
+    which "an install-shaped search cannot see a fixture path" is one instance, not the general case.
+  - **Classification unchanged, and re-verified against their anchors:** `shared_root.py:15`
+    `ENV_VAR = "PORTFOLIO_SHARED_ROOT"`, `:17` `_DEFAULT = Path(__file__).resolve().parents[2]/"shared"`
+    — default *and* override both point at a checked-out spec subtree, never a home directory. The
+    env var exists so `shared/` can be extracted to its own repo without code change; re-pointing it
+    re-points to another spec tree. `expanduser|Path.home|\.claude/` over `src/` still gives **0
+    hits** @`9e149c6`. **One installation against three non-installations stands.** Their own
+    sharper wording, adopted: not "caller-supplied with no default" but **no *installation* default** —
+    a fixture default in the simulation entry, a dormant package-data path in the reference portfolio.
+  _(catalog session, on portfolio-optimiser's unprompted enumeration.)_
+- **2026-07-25** — **STEG 4 completed: §3 `okf_version` is now ENFORCED on shape; convention version
+  0.1 → 0.2.** The reservation added on 2026-07-23 ("enforcement waits until the emitters have
+  migrated") had its condition measured, not assumed. **The emitter set is two, not three:**
+  - **okr** @`0059da7` (v1.8.1) — migrated. `okf-index.mjs` emits `okf_version: 0.1` +
+    `okf_layout: kb-layout-2026-06`, with a verbatim migration path for legacy roots.
+  - **linkedin-studio** — `scripts/brain/src/scaffold.ts:38` emits `okf_version: 0.1`. It never
+    carried a layout string, and has no `okf_layout` (0 hits) because it needs none.
+  - **ms-ai-architect is not an emitter at all** — **zero `index.md` in the repo**; `okf_version`
+    occurs in exactly one planning document. This log's own status table already said so (🔵
+    "designed, not built"), but the reservation's phrase "the emitters" had been read as including
+    it. Nothing to migrate, so it cannot gate enforcement.
+
+  Swept wider than the two named: every `okf_version` value across the marketplace **and** the
+  sibling consumer repos is `0.1`. The only `kb-layout-2026-06` occurrences are okr's own
+  migration-test inputs and prose in these docs. **No live emitter anywhere carries a layout
+  string**, so the flip is a no-op against today's ecosystem and locks the invariant going forward.
+
+  **What the gate does and deliberately does not do.** `okf-check.mjs` rejects a value that is not
+  version-shaped (`/^\d+(\.\d+)*$/`). It asserts **nothing about which upstream versions exist** —
+  that value set is Google's (§12), so a bundle targeting a newer upstream version passes. This
+  matters: a checker that validated *membership* would be the convention claiming ownership of a set
+  §12 says it does not own — the same over-reach class this round corrected three times. **Presence
+  stays unenforced** (absent → reported, not failed); that is a separate §3 MUST and a separate step.
+
+  **Convention version bumped 0.1 → 0.2**, by this log's own stated criterion. The 2026-07-23 entry
+  declined a bump because "the set of conforming bundles is unchanged (a clarification, deliberately
+  non-enforcing)". Here the set **does** change: the spec explicitly declared that an emitter
+  carrying a layout string "conforms today", and rollout rule 6 defines conformance as gate output
+  ("verified, not asserted"). Per §12 the bump triggers a per-plugin re-check — which the sweep above
+  has already pre-measured as finding **zero** violations. Side benefit: the convention version is no
+  longer numerically confusable with upstream OKF v0.1.
+
+  **The parity gate was blind to this axis, and that is now fixed.** `check-okf-parity.mjs` compared
+  the normalized tuple `{conceptCount, untyped, okfVersion}` — the `okf_version` **value**. But when
+  two checkers disagree about whether a value is *acceptable*, the value is identical, so the axis
+  read **agree**. A false green on exactly the drift the gate exists to catch. The signature now
+  carries a boolean shape **verdict** (`okfVersionAccepted`), normalized as a verdict rather than a
+  message so two enforcing impls agree even if they word rejection differently. New corpus fixture
+  **`red-marker-layout`** (`expected: "diverge"`) is the red proof, and the CLI now prints
+  `(accepted)`/`(REJECTED)` because on this axis both impls print the same `okf=` value.
+
+  **Known, deliberate divergence:** catalog now enforces; okr still pure-echoes (their `CHANGELOG.md`
+  for 1.8.1: "verdiene valideres fortsatt ikke, siden spec §3 ennå ikke er håndhevende på form" — a
+  statement that was true when written and is now stale). The `diverge` expectation **encodes okr's
+  lag, not a design split**, and flips to `agree` when they mirror it. okr notified; the standing
+  promise to notify llm-ingestion-okf on any `okf-check.mjs` change was honoured in the same round.
+  Suite **73 → 78** across the six test files. _(catalog session.)_

 ## Distilled architecture notes (OKF round, 2026-07)

--- a/docs/okf-second-brain/spec.md
+++ b/docs/okf-second-brain/spec.md
@ -4,7 +4,10 @@ A cross-plugin convention for how each plugin stores the **user's own context**
 personal/organizational "second brain" / LLM-wiki — as a portable, interoperable markdown
 bundle, compatible with Google's Open Knowledge Format (OKF) v0.1.

-> **Version 0.1 · 2026-06-29 · Cross-cutting catalog artifact, owned by no single plugin.**
+> **Version 0.2 · 2026-07-25 · Cross-cutting catalog artifact, owned by no single plugin.**
+> _(0.2 tightens the §3 floor: `okf_version` is now enforced on shape. Distinct from — and
+> deliberately no longer numerically confusable with — upstream Google OKF v0.1, which this
+> convention targets and does not version.)_
 > Reference design: linkedin-studio's `brain/`. Interop layer: Google OKF v0.1 (thin veneer).
 > Change log + per-plugin rollout status + coordination protocol: `log.md` (same directory).

@ -52,9 +55,12 @@ file path minus `.md`.
  children — **never a filesystem read**; **no frontmatter**, carries progressive-disclosure prose).
 - **MUST** — the bundle-root `index.md` carries an `okf_version` marker (the upstream OKF version the
  bundle targets, currently `0.1`). The value is the **upstream version alone**; a plugin's own layout
-  revision belongs in the optional `okf_layout` marker (§12), never here. **Not yet enforced** — no
-  checker validates the value's shape, so an emitter still carrying a layout string here conforms
-  today. Enforcement waits until the emitters have migrated (`log.md`, STEG 4).
+  revision belongs in the optional `okf_layout` marker (§12), never here. **Enforced on shape** — the
+  gate rejects a value that is not version-shaped (`/^\d+(\.\d+)*$/`), which is what catches a layout
+  snapshot sitting in this field. The check deliberately asserts **nothing about which upstream
+  versions exist**: that value set is Google's (§12), so a bundle targeting a newer upstream version
+  passes. **Presence is not enforced** — an absent marker is reported, not failed; that is a separate
+  step, not this one.
 - **MUST (consumers)** — preserve unknown frontmatter keys, tolerate unknown `type` values, tolerate
  broken cross-links.

--- a/scripts/check-okf-parity.mjs
+++ b/scripts/check-okf-parity.mjs
@ -16,7 +16,8 @@
 //
 // CONTRACT: comparison unit is the PER-FILE outcome, not the bundle verdict — two
 // checkers can both say "OK" while disagreeing on what IS a concept file. Each impl's
-// existing checkBundle(root) return is normalized to { conceptCount, untyped[], okfVersion };
+// existing checkBundle(root) return is normalized to
+// { conceptCount, untyped[], okfVersion, okfVersionAccepted };
 // the gate diverges iff those normalized outcomes are not identical across the
 // available impls. Defined over DEFAULT read-mode (strictIngest OFF, not files-scoped).
 //
@ -59,12 +60,19 @@ export async function normalizedOutcome(impl, root) {
    conceptCount: r.scanned,
    untyped: [...(r.missingType ?? [])].sort(),
    okfVersion: r.okfVersion ?? null,
+    // spec §3 marker axis. Normalized to a BOOLEAN verdict, not the message: two impls that
+    // both enforce must agree even if they word the rejection differently. An impl that does
+    // not check at all reports no error, i.e. "accepts" — which is exactly the signal we want
+    // when one enforces and another still pure-echoes.
+    okfVersionAccepted: !(r.okfVersionError ?? null),
  };
 }

 // Signature over the fields that define per-file parity. Distinct signatures => divergence.
+// The okf_version VALUE alone could not carry the marker axis: when impls disagree about
+// whether a value is acceptable, the value itself is identical, so the axis read as "agree".
 function signature(o) {
-  return `${o.conceptCount}|${o.untyped.join(',')}|${o.okfVersion}`;
+  return `${o.conceptCount}|${o.untyped.join(',')}|${o.okfVersion}|${o.okfVersionAccepted}`;
 }

 // Run all impls on one bundle root; decide agree vs diverge among the comparable ones.
@ -145,7 +153,10 @@ if (isMain) {
      r.status === 'PASS' && r.expected === 'diverge' ? 'PASS (red-proof)' : r.status;
    out.push(`${r.fixture.padEnd(22)} [${(r.axis || '').padEnd(16)}] expect=${(r.expected || '').padEnd(8)} ${tag}`);
    for (const o of r.outcomes ?? []) {
-      out.push(`    ${o.name.padEnd(10)} count=${o.conceptCount}  untyped=[${o.untyped.join(', ')}]  okf=${o.okfVersion}`);
+      // The shape verdict is printed because the value alone cannot show this axis: on a
+      // marker divergence both impls print the SAME okf= value and only the verdict differs.
+      const verdict = o.okfVersionAccepted ? 'accepted' : 'REJECTED';
+      out.push(`    ${o.name.padEnd(10)} count=${o.conceptCount}  untyped=[${o.untyped.join(', ')}]  okf=${o.okfVersion} (${verdict})`);
    }
    if (r.skipped?.length) out.push(`    (skipped, unavailable: ${r.skipped.join(', ')})`);
  }
--- a/scripts/check-okf-parity.test.mjs
+++ b/scripts/check-okf-parity.test.mjs
@ -93,6 +93,31 @@ test('red-proof: BOM+CRLF typed concept diverges; the same file as UTF-8/LF agre
  }
 });

+// --- marker axis: §3 okf_version shape enforcement (catalog enforces, okr echoes) ---
+// This axis was invisible to the gate until the signature carried the shape verdict: the
+// signature compared the okf_version VALUE, which is identical across impls precisely when
+// they disagree about whether it is acceptable. A false "agree" on the one axis the gate
+// exists to watch.
+test('marker axis: a layout string in okf_version diverges; a version-shaped one agrees', async () => {
+  const impls = [CATALOG, OKR];
+  const layout = tmpRoot();
+  const versioned = tmpRoot();
+  try {
+    writeFileSync(join(layout, 'index.md'), 'okf_version: kb-layout-2026-06\n\n# Bundle\n');
+    writeFileSync(join(layout, 'c.md'), TYPED);
+    const evLayout = await evaluateBundle(layout, impls);
+    assert.equal(evLayout.diverges, true, 'catalog enforces the shape, okr still pure-echoes -> diverge');
+
+    writeFileSync(join(versioned, 'index.md'), ROOTINDEX);
+    writeFileSync(join(versioned, 'c.md'), TYPED);
+    const evVersioned = await evaluateBundle(versioned, impls);
+    assert.equal(evVersioned.diverges, false, 'a version-shaped value is accepted by both -> agree');
+  } finally {
+    rmSync(layout, { recursive: true, force: true });
+    rmSync(versioned, { recursive: true, force: true });
+  }
+});
+
 // --- Layer 2b: symlink axis (runtime-materialized; must not hang/crash) ---
 test('symlink axis: symlinked file + dir + loop are skipped by both, no hang, agree', async () => {
  const dir = tmpRoot();
--- a/scripts/okf-check.mjs
+++ b/scripts/okf-check.mjs
@ -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);
 }
--- a/scripts/okf-check.test.mjs
+++ b/scripts/okf-check.test.mjs
@ -102,3 +102,66 @@ test('checkBundle(): recommended-field gaps are warnings, not failures', () => {
    rmSync(dir, { recursive: true, force: true });
  }
 });
+
+// --- spec §3 okf_version shape enforcement (the reservation lifted 2026-07-25) ---
+// The catalog owns the SEPARATION of the two markers (§12), not the upstream value set
+// (owned by Google). So the gate checks that the value is version-SHAPED — never that it
+// is a version that exists upstream.
+
+test('okf_version carrying a layout string -> exit != 0 and points at okf_layout', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(join(dir, 'index.md'), 'okf_version: kb-layout-2026-06\n\n# Bundle\n');
+    const { status, stdout } = runCheck(dir);
+    assert.notEqual(status, 0, 'a layout snapshot in okf_version must fail the gate');
+    assert.match(stdout, /okf_layout/, 'the failure must name the marker it belongs in');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('a version-shaped okf_version passes, including multi-component', () => {
+  for (const value of ['0.1', '1.0', '0.1.2', '12']) {
+    const dir = tmpRoot();
+    try {
+      writeValidBundle(dir);
+      writeFileSync(join(dir, 'index.md'), `okf_version: ${value}\n\n# Bundle\n`);
+      const { status } = runCheck(dir);
+      assert.equal(status, 0, `"${value}" is upstream-version-shaped and must pass`);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+// Scope guard: the reservation covered the value's SHAPE. Presence is a separate §3 MUST
+// that this gate still does not enforce — absent stays a non-failing echo, as before.
+test('absent okf_version is unchanged by shape enforcement (still exit 0 + MISSING echo)', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(join(dir, 'index.md'), '# Bundle\n'); // no marker at all
+    const { status, stdout } = runCheck(dir);
+    assert.equal(status, 0, 'absence must not become an error in this step');
+    assert.match(stdout, /MISSING/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('checkBundle(): the shape verdict is on the return object', () => {
+  const bad = tmpRoot();
+  const good = tmpRoot();
+  try {
+    writeValidBundle(bad);
+    writeFileSync(join(bad, 'index.md'), 'okf_version: kb-layout-2026-06\n');
+    assert.ok(checkBundle(bad).okfVersionError, 'layout string -> an error string');
+
+    writeValidBundle(good);
+    assert.equal(checkBundle(good).okfVersionError, null, '0.1 -> no error');
+  } finally {
+    rmSync(bad, { recursive: true, force: true });
+    rmSync(good, { recursive: true, force: true });
+  }
+});
--- a/test/okf-parity-corpus/manifest.json
+++ b/test/okf-parity-corpus/manifest.json
@ -26,6 +26,12 @@
      "expected": "diverge",
      "note": "The record's canon fixture (svar-catalog.local.md:48): a BOM+CRLF typed concept AND an innboks/ raw file in one bundle -> catalog FAIL(2 untyped) vs okr OK(0 untyped), opposite exit codes. Byte and tree axes each carry their own red proof."
    },
+    "red-marker-layout": {
+      "axis": "marker",
+      "expected": "diverge",
+      "note": "Root index.md carries a layout snapshot (kb-layout-2026-06) in okf_version instead of the upstream version -> catalog enforces the §3 shape rule and FAILs, okr still pure-echoes the value and passes (their CHANGELOG 1.8.1: 'verdiene valideres fortsatt ikke'). Otherwise clean, so the divergence isolates the marker axis. EXPECTED TO FLIP TO 'agree' once okr mirrors the enforcement — this expectation encodes okr's lag, not a permanent design split.",
+      "note2": "This axis was invisible until the parity signature carried the shape VERDICT: comparing the okf_version value alone reads 'agree' precisely when the impls disagree about whether that value is acceptable."
+    },
    "green-hierarchical": {
      "axis": "tree-hierarchical",
      "expected": "agree",
--- a/test/okf-parity-corpus/red-marker-layout/index.md
+++ b/test/okf-parity-corpus/red-marker-layout/index.md
@ -0,0 +1,3 @@
+okf_version: kb-layout-2026-06
+
+# Bundle root
--- a/test/okf-parity-corpus/red-marker-layout/profile.md
+++ b/test/okf-parity-corpus/red-marker-layout/profile.md
@ -0,0 +1,8 @@
+---
+type: Profile
+title: A concept
+description: A typed concept file.
+resource: about
+timestamp: 2026-07-25
+---
+# Profile