open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Releases Activity

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

Browse source 
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
This commit is contained in:
Kjell Tore Guttormsen 2026-07-31 17:36:15 +02:00
commit 1ca27f6507
4 changed files with 289 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

61
docs/okf-second-brain/log.md
View file

@ -433,6 +433,67 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
opposite construction rule underneath. That is a better argument for splitting *scope* from
*construction* than the one we gave them. _(catalog session, on llm-ingestion-okf's measurement.)_
- **2026-07-31** — **§6 placement corrected to match upstream; convention version 0.2 → 0.3.**
Four operator rulings in one round, on a decision base that was measured, not inherited.
**The divergence was ours, and it was real.** Upstream (`~/repos/_okf-upstream` @ `3fcbb9f` =
`GoogleCloudPlatform/knowledge-catalog`, `okf/SPEC.md`) says 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 `index.md` carries **no**
frontmatter and the marker is a **body-text line**. Not a divergence to document — one to remove.
**What the emitter sweep actually found (measured 2026-07-31, date pinned to the numbers):**
| Emitter | Placement | Markers | Source |
|---|---|---|---|
| okr | body text | `okf_version` + `okf_layout` | `okr/scripts/okf-index.mjs:204` |
| linkedin-studio | body text | `okf_version` | `scaffold.ts:38` |
| portfolio-optimiser-commons | **frontmatter** | `type` + `okf_version` + `title` | `examples/nav-golden-*/bundle/index.md` |
**This repo already carried both forms, and both were green.** `test/okf-parity-corpus/` (9 files,
body text) and `test/nav-golden-corpus/` (4 files, frontmatter — consumed **byte-exact** from
commons @ `b641741`). Nobody had noticed because `okf-check.mjs`'s marker regex was **unanchored**
`/m` and therefore placement-blind. The convention had a placement rule its own gate could not see.
**Why the reader is transitional, and why that is a design and not a hedge.**
`check-okf-parity.mjs:36-39` runs **okr's live checker** from the sibling repo and compares the
signature `conceptCount|untyped|okfVersion|okfVersionAccepted`. A frontmatter-only reader reports
`null` here and `0.1` there, so the signature splits on all 9 body-text fixtures — a red parity
gate produced by a doc change, with no bundle anywhere 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 2026-07-23. Enforcement needs the emitters migrated first,
and that is their work, not the catalog's.
**The quoting hole was upstream's own form, not a corner case.** §12:773 is the only place in the
whole upstream spec that shows the key with a value, and the value is quoted: `okf_version: "0.2"`.
The 0.2 gate ran `/^\d+(\.\d+)*$/` on the **raw captured string**, saw the quote characters, and
failed upstream's canonical example. Fixed by unquoting **before** the shape check — quotes are
YAML syntax, not value. The shape rule is unchanged, and a quoted layout snapshot still fails.
Implemented by reusing `okf-frontmatter.mjs`'s existing `get()`, which already unquoted
(lines 22-26); no new parsing code was written.
**`okf_layout` stays in body text.** Upstream's exception is enumerated to one key («an
`okf_version` key»), so the frontmatter block in an `index.md` exists by upstream's leave and for
upstream's key; this convention's own extension marker stays outside it. Asymmetric on purpose:
it is the reading that survives either construction of upstream's parenthesis. okr had flagged
that the parenthesis may bound *where* a block may appear rather than *which* keys it carries, and
that question is not ours to settle — so 0.3 takes the placement that does not depend on settling it.
**Cross-repo (from okr, verified here).** okr reported the same raw-string-as-parsed-scalar pattern
in their producer, where it is worse than ours: their migration path moves the quoted value into
`okf_layout` and overwrites `okf_version` with their own constant, corrupting **both** markers
irrecoverably. Measured on our side: `okf-check.mjs` has **zero** write operations, so the same
pattern yields a false FAIL here and data loss there. One pattern, two places, asymmetric severity
— their fix sequences first. Also carried forward: §11 forbids consumers rejecting a bundle for
*missing optional frontmatter fields* or *missing `index.md` files*, so §3 presence enforcement
stays stopped on **spec grounds**, not on timing.
**Verification.** Suite 90 → **98/98** (8 new tests, written red first — 6 genuinely failed, 2 were
regression guards that were already correct and are recorded as such). Parity gate 9/9 with
`red-marker-layout` still diverging as its manifest requires; nav-golden 2/2. `git status test/`
clean: **no fixture was migrated**, deliberately — the 9 body-text fixtures are now the coverage
for the transitional path. _(catalog session, økt 9.)_
## Distilled architecture notes (OKF round, 2026-07)
Durable conclusions from the cross-repo round (full working context retained by the catalog session):