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.mjs

@@ -11,7 +11,12 @@
 //     (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.
+//     echoed, not failed. The value is unquoted before the shape check (spec 0.3):
+//     quotes are YAML syntax, and upstream's own example is quoted.
+//   - PLACEMENT (spec §6, 0.3): frontmatter is canonical, body text is the pre-0.3
+//     form. Both are read; which one was found is reported as `okfVersionPlacement`
+//     and noted in the output. Declared, not enforced — see rootOkfVersion() for
+//     why enforcing it here would red the parity gate.
 //
 // 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
@@ -43,12 +48,44 @@ function walkConcepts(root) {
   return out;
 }
 
-// Read the root's okf_version (markdown text in index.md, not frontmatter). null if absent.
+// Strip one matched pair of surrounding quotes. YAML quotes are SYNTAX, not value — upstream's
+// only example of the key with a value writes `okf_version: "0.2"` (okf/SPEC.md:773), and 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. Unquote FIRST, then check shape; the shape rule itself
+// is unchanged and still rejects everything it rejected before.
+function unquote(value) {
+  const m = value.match(/^(["'])([\s\S]*)\1$/);
+  return m ? m[2] : value;
+}
+
+// Read the bundle-root's okf_version. Returns { value, placement }; value is null when no marker.
+//
+// spec §6 (v0.3): the CANONICAL placement is the root index.md's FRONTMATTER block — upstream's
+// single carved exception to "index files contain no frontmatter" (okf/SPEC.md §8:509-510 +
+// §12:773-775, read at 3fcbb9f). This convention previously said the opposite.
+//
+// The pre-0.3 body-text form is still READ and still passes. That is deliberate, not leftover:
+// two marketplace emitters write it today (okr scripts/okf-index.mjs:204 and linkedin-studio
+// scaffold.ts:38, both measured 2026-07-31), and check-okf-parity compares this very value
+// against okr's LIVE checker. Reading frontmatter alone would report null here and 0.1 there,
+// splitting the parity signature on every body-text bundle before a single emitter had migrated.
+// So placement is DECLARED, not enforced: the gate reports which form it found and moves on.
+//
+// okf_layout is deliberately NOT read here. §12 (v0.3) keeps it in body text, because upstream's
+// exception is enumerated to ONE key ("an okf_version key"); this convention's own extension
+// marker stays out of the block upstream governs.
 function rootOkfVersion(root) {
   const idx = join(root, 'index.md');
-  if (!existsSync(idx)) return null;
-  const m = readFileSync(idx, 'utf8').match(/^okf_version:\s*(.+)$/m);
-  return m ? m[1].trim() : null;
+  if (!existsSync(idx)) return { value: null, placement: null };
+  const content = readFileSync(idx, 'utf8');
+
+  const fromFrontmatter = parseFrontmatter(content).get('okf_version');
+  if (fromFrontmatter !== null) {
+    return { value: unquote(fromFrontmatter), placement: 'frontmatter' };
+  }
+
+  const m = content.match(/^okf_version:\s*(.+)$/m);
+  return m ? { value: unquote(m[1].trim()), placement: 'body' } : { value: null, placement: null };
 }
 
 // spec §3: the value is the upstream OKF version ALONE; a plugin's own layout revision
@@ -78,12 +115,13 @@ export function checkBundle(root) {
       if (!get(field)) warnings.push(`${rel}: missing recommended field "${field}"`);
     }
   }
-  const okfVersion = rootOkfVersion(root);
+  const { value: okfVersion, placement: okfVersionPlacement } = rootOkfVersion(root);
   return {
     scanned: concepts.length,
     missingType,
     warnings,
     okfVersion,
+    okfVersionPlacement,
     okfVersionError: okfVersionShapeError(okfVersion),
   };
 }
@@ -108,6 +146,10 @@ 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.okfVersionPlacement === 'body') {
+    out.push('    note: pre-0.3 body-text placement; spec §6 canonical is the root index.md '
+      + 'frontmatter block. Read and accepted — not a failure.');
+  }
   if (r.okfVersionError) out.push(`    - ${r.okfVersionError}`);
   out.push(`  Warnings (recommended fields): ${r.warnings.length}`);
   for (const w of r.warnings) out.push(`    ! ${w}`);

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 });
+  }
+});