feat(okf): §6 placement follows upstream — okf_version in root frontmatter (spec 0.2 -> 0.3)

Upstream (~/repos/_okf-upstream @ 3fcbb9f, okf/SPEC.md) is unambiguous: a bundle-root
index.md MAY carry okf_version in a FRONTMATTER block, "the only place frontmatter is
permitted in an index.md" (§8:509-510 + §12:773-775). Through 0.2 this convention said
the opposite — no frontmatter, marker in body text. The divergence was OURS against
upstream, so 0.3 removes it rather than documenting it. Operator ruling, 2026-07-31.

Measured before deciding (date pinned to every number):
  - emitters: okr (body, okf-index.mjs:204) · linkedin-studio (body, scaffold.ts:38)
    · commons (FRONTMATTER, examples/nav-golden-*/bundle/index.md)
  - this repo already carried BOTH forms, both green: okf-parity-corpus (9, body) and
    nav-golden-corpus (4, frontmatter, byte-exact from commons @ b641741). Invisible
    because the marker regex was unanchored /m, i.e. placement-blind.

THE READER IS TRANSITIONAL BY DESIGN, NOT BY OMISSION. check-okf-parity.mjs:36-39 runs
okr's LIVE checker and compares conceptCount|untyped|okfVersion|okfVersionAccepted. A
frontmatter-only reader reports null here and 0.1 there, splitting the signature on all
9 body-text fixtures — a red gate produced by a doc change, with no bundle having become
less conformant. So both placements are read, one is canonical, and placement is
DECLARED, NOT ENFORCED — the same shape §3 presence has carried since 07-23.

QUOTING WAS UPSTREAM'S OWN FORM, NOT A CORNER CASE. §12:773 is the only place in the
upstream spec showing the key with a value, and it is quoted: okf_version: "0.2". The
0.2 gate ran the shape regex on the RAW string and failed upstream's canonical example.
Fixed by unquoting BEFORE the shape check. Implemented by reusing okf-frontmatter.mjs's
existing get(), which already unquoted (lines 22-26) — no new parsing code.

okf_layout STAYS IN BODY TEXT (§12). Upstream's exception is enumerated to one key, so
the block exists by upstream's leave and for upstream's key; our own extension marker
stays outside it. Asymmetric on purpose: it survives either construction of upstream's
parenthesis — a question okr has flagged as open and we do not own.

MEASURED CONSEQUENCE, REPORTED NOT HIDDEN: okr v1.8.2 fixed their PRODUCER, not their
checker (rootMarkers/pick returns the raw string). On a quoted fixture the two impls now
diverge on the VALUE — catalog 0.2 vs okr "0.2" — measured directly via evaluateBundle.
No existing gate is affected because the corpus carries no quoted fixture, which also
means the parity gate's green does NOT cover the quoting axis: "not run", not "as
expected". The shared unquote-before-compare decision has to reach okr's CHECKER too.

Verification: suite 90 -> 98/98 (8 new; written red first — 6 genuinely failed, 2 were
regression guards already correct). Parity 9/9, red-marker-layout still diverging per
its manifest. nav-golden 2/2. git status test/ clean: NO fixture migrated — the 9
body-text fixtures are now the coverage for the transitional path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRhqgd8hws7SxT3mC4Lm4U

scripts/okf-check.test.mjs

@@ -165,3 +165,137 @@ test('checkBundle(): the shape verdict is on the return object', () => {
     rmSync(good, { recursive: true, force: true });
   }
 });
+
+// --- spec §6 v0.3: FRONTMATTER is the canonical placement (2026-07-31 operator ruling) ---
+// Upstream is unambiguous (~/repos/_okf-upstream @ 3fcbb9f, okf/SPEC.md §8:509-510 + §12:773-775):
+// a bundle-root index.md MAY carry `okf_version` in a frontmatter block, and that block is the
+// only place frontmatter is permitted in an index.md. This convention had said the opposite.
+//
+// The reader is TRANSITIONAL by design, not by omission: two marketplace emitters still write
+// the body-text form (okr scripts/okf-index.mjs:204, linkedin-studio scaffold.ts:38, both measured
+// 2026-07-31), and check-okf-parity compares this very value against okr's LIVE checker. A
+// frontmatter-only reader would report null here and 0.1 there, splitting the parity signature on
+// every body-text fixture before a single emitter had migrated. So both placements are read;
+// only one is canonical.
+
+test('§6 v0.3: okf_version in the root frontmatter block is read, and reported as frontmatter', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(join(dir, 'index.md'), '---\nokf_version: 0.2\n---\n\n# Bundle\n');
+    const r = checkBundle(dir);
+    assert.equal(r.okfVersion, '0.2');
+    assert.equal(r.okfVersionPlacement, 'frontmatter', 'the canonical placement must be reported as such');
+    assert.equal(r.okfVersionError, null, 'a version-shaped value in the canonical place is not an error');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// THE decisive case: upstream shows the key with a value in exactly one place in the whole spec
+// (okf/SPEC.md:773) and the value is QUOTED — `okf_version: "0.2"`. The pre-0.3 gate ran the shape
+// regex on the raw captured string, saw the quote characters, and failed upstream's own canonical
+// example. Quotes are YAML syntax, not value: unquote FIRST, then check shape. The shape rule
+// itself (/^\d+(\.\d+)*$/) is unchanged and still correct.
+test('§3 v0.3: a QUOTED value passes — upstream SPEC.md:773 writes okf_version: "0.2"', () => {
+  for (const line of ['okf_version: "0.2"', "okf_version: '0.2'"]) {
+    const dir = tmpRoot();
+    try {
+      writeValidBundle(dir);
+      writeFileSync(join(dir, 'index.md'), `---\n${line}\n---\n\n# Bundle\n`);
+      const { status, stdout } = runCheck(dir);
+      assert.equal(status, 0, `${line} is upstream's own canonical form and must pass`);
+      assert.match(stdout, /okf_version:\s*0\.2/, 'the echo must show the unquoted value');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+test('§3 v0.3: unquoting applies to the body-text form too, not just frontmatter', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(join(dir, 'index.md'), '# Bundle\n\nokf_version: "0.2"\n');
+    const { status, stdout } = runCheck(dir);
+    assert.equal(status, 0, 'the quoting fix is about the value, not about where it sits');
+    assert.match(stdout, /okf_version:\s*0\.2/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('§6 v0.3: the body-text form still passes, but is reported as the pre-0.3 placement', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir); // writeValidBundle uses the body-text form
+    const r = checkBundle(dir);
+    assert.equal(r.okfVersion, '0.1', 'body text must keep working — okr and linkedin-studio emit it');
+    assert.equal(r.okfVersionPlacement, 'body');
+    assert.equal(r.okfVersionError, null, 'placement is declared, NOT enforced — it is not a failure');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('§6 v0.3: body-text placement is visible in the CLI output (declared, not enforced)', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    const { status, stdout } = runCheck(dir);
+    assert.equal(status, 0, 'a note must not change the verdict');
+    assert.match(stdout, /okf_version:\s*0\.1/, 'the existing echo format must survive');
+    assert.match(stdout, /frontmatter/, 'the note must point at the canonical placement');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('§6 v0.3: when both placements carry a value, frontmatter wins', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(join(dir, 'index.md'), '---\nokf_version: 0.2\n---\n\n# Bundle\n\nokf_version: 0.1\n');
+    const r = checkBundle(dir);
+    assert.equal(r.okfVersion, '0.2', 'the canonical placement is authoritative');
+    assert.equal(r.okfVersionPlacement, 'frontmatter');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// §12 ruling (2026-07-31): okf_layout stays in BODY TEXT. Upstream's carved exception is
+// enumerated to ONE key ("an okf_version key", §8:509-510), so this convention's own extension
+// marker stays out of the block upstream governs. Consequence for the reader: okf_layout must
+// never be mistaken for okf_version, wherever either one sits.
+test('§12 v0.3: okf_layout in body text is not read as okf_version', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(
+      join(dir, 'index.md'),
+      '---\nokf_version: 0.2\n---\n\n# Bundle\n\nokf_layout: kb-layout-2026-06\n',
+    );
+    const { status } = runCheck(dir);
+    const r = checkBundle(dir);
+    assert.equal(r.okfVersion, '0.2', 'okf_layout must not shadow or corrupt okf_version');
+    assert.equal(status, 0, 'the two markers coexisting is the §12 v0.3 shape, not a failure');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Regression guard on the quoting fix: unquoting must NOT weaken the shape rule. A layout
+// snapshot that happens to be quoted is still a layout snapshot in the wrong field.
+test('§3 v0.3: unquoting does not weaken the shape rule — a quoted layout string still fails', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(join(dir, 'index.md'), '---\nokf_version: "kb-layout-2026-06"\n---\n\n# Bundle\n');
+    const { status, stdout } = runCheck(dir);
+    assert.notEqual(status, 0, 'unquoting is about syntax, not about accepting non-versions');
+    assert.match(stdout, /okf_layout/, 'the failure must still name the marker it belongs in');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});