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