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
This commit is contained in:
parent
3dfc513655
commit
1ca27f6507
4 changed files with 289 additions and 16 deletions
|
|
@ -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):
|
||||
|
|
|
|||
|
|
@ -4,8 +4,12 @@ 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.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
|
||||
> **Version 0.3 · 2026-07-31 · Cross-cutting catalog artifact, owned by no single plugin.**
|
||||
> _(0.3 corrects this convention's placement rule to match upstream: the bundle-root `okf_version`
|
||||
> marker belongs in the root `index.md`'s **frontmatter block**, which is the one place upstream
|
||||
> permits frontmatter in an `index.md` (§6). The value is now **unquoted before** the shape check,
|
||||
> because upstream's own canonical example is quoted. `okf_layout` stays in body text (§12).
|
||||
> 0.2 had tightened the §3 floor: `okf_version` 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).
|
||||
|
|
@ -52,15 +56,21 @@ file path minus `.md`.
|
|||
- **MUST** — every concept file (every `.md` except `index.md`) carries a `type:` frontmatter key
|
||||
(free string, e.g. `Profile`, `Operations`, `JournalEntry`).
|
||||
- **MUST** — every directory level has an `index.md` (an **authored** enumeration of that directory's
|
||||
children — **never a filesystem read**; **no frontmatter**, carries progressive-disclosure prose).
|
||||
children — **never a filesystem read**; carries progressive-disclosure prose). An `index.md` carries
|
||||
**no frontmatter, with one exception**: the bundle-root one MAY carry `okf_version` in a frontmatter
|
||||
block (§6, §12). This mirrors upstream verbatim (`okf/SPEC.md` §8:509-510).
|
||||
- **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. **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.
|
||||
snapshot sitting in this field. The value is **unquoted before** that check (0.3): quotes are YAML
|
||||
syntax, not value, and upstream's own canonical example writes `okf_version: "0.2"`
|
||||
(`okf/SPEC.md:773`) — a gate that rejected it would assert something upstream contradicts.
|
||||
Unquoting does not weaken the rule: a quoted layout snapshot still fails. 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. **Placement is not enforced either**
|
||||
(0.3) — see §6.
|
||||
- **MUST (consumers)** — preserve unknown frontmatter keys, tolerate unknown `type` values, tolerate
|
||||
broken cross-links.
|
||||
|
||||
|
|
@ -92,7 +102,23 @@ levelled down to bare OKF.**
|
|||
## 6. Reserved files & cross-links
|
||||
|
||||
- `index.md` — an **authored** enumeration of the directory's children (**never a filesystem read** —
|
||||
§3), **no frontmatter**, progressive-disclosure prose. The bundle-root one carries `okf_version`.
|
||||
§3), progressive-disclosure prose, and **no frontmatter — with one exception**: the **bundle-root**
|
||||
`index.md` carries `okf_version` in a **frontmatter block**.
|
||||
|
||||
**Canonical placement (0.3):** the frontmatter block. This follows upstream, which is unambiguous
|
||||
on both halves — «Index files contain no frontmatter, with one exception: a bundle-root `index.md`
|
||||
MAY carry an `okf_version` key» (`okf/SPEC.md` §8:509-510), declared «in a bundle-root `index.md`
|
||||
frontmatter block (the only place frontmatter is permitted in an `index.md`)» (§12:773-775). Read
|
||||
at upstream commit `3fcbb9f`. Through 0.2 this convention said the opposite — marker in body text,
|
||||
index files with no frontmatter at all — so the divergence was **ours against upstream**, and 0.3
|
||||
removes it rather than documenting it.
|
||||
|
||||
**The pre-0.3 body-text form is still read and still passes.** Placement is **declared, not
|
||||
enforced**: the gate reports which form it found and does not fail on either. Two marketplace
|
||||
emitters wrote body text when 0.3 was cut (measured 2026-07-31), and the §7 parity gate compares
|
||||
this value against a sibling implementation's live checker — enforcing placement before the
|
||||
emitters migrate would redden that gate without a single bundle having become less conformant.
|
||||
Enforcement is a later step and needs its own ruling, exactly as presence does.
|
||||
- `log.md` — change log (optional per bundle; reserved name).
|
||||
- Cross-links — plain markdown (bundle-relative `/...` or relative); relation type conveyed by prose.
|
||||
Consumers MUST tolerate broken links.
|
||||
|
|
@ -215,15 +241,25 @@ Ground-truth-checked against the live `GoogleCloudPlatform/knowledge-catalog` re
|
|||
Markers are kept deliberately separate. A single field must not carry two unrelated concerns — the
|
||||
upstream OKF version *and* a plugin's own layout revision — so those are two distinct markers:
|
||||
|
||||
- **`okf_version`** — a marker line in each bundle-root `index.md` (§6); the upstream Google OKF version
|
||||
- **`okf_version`** — a key in each bundle-root `index.md`'s frontmatter block (§6); the upstream Google OKF version
|
||||
the bundle targets (currently `0.1`). **Required (§3).** Its value set is owned by Google, so the field
|
||||
has exactly one meaning and stays single-valued — the bundle-root marker (§6) relies on that. When
|
||||
Google bumps OKF, each plugin re-checks conformance.
|
||||
- **`okf_layout`** — an *optional* marker line alongside it; a plugin's own layout-revision snapshot
|
||||
- **`okf_layout`** — an *optional* marker; a plugin's own layout-revision snapshot
|
||||
(e.g. `kb-layout-2026-06`). Its value set is owned by the emitting plugin — not by OKF, not by this
|
||||
convention. It is **not** a version marker, never triggers a cross-plugin re-check, and a consumer that
|
||||
doesn't recognize it ignores it. This is where a plugin stamps its own layout revision, keeping
|
||||
`okf_version` reserved for the upstream version alone.
|
||||
|
||||
**Placement (0.3): body text, not the frontmatter block.** When `okf_version` moved into
|
||||
frontmatter (§6), this marker deliberately did **not** follow it. Upstream's exception is
|
||||
enumerated to a single key — «a bundle-root `index.md` MAY carry **an `okf_version` key**»
|
||||
(`okf/SPEC.md` §8:509-510) — so the frontmatter block in an `index.md` exists by upstream's leave
|
||||
and for upstream's key. `okf_layout` is **this convention's** extension, and it stays outside the
|
||||
block upstream governs. The two markers therefore sit in the same file in different places, which
|
||||
is asymmetric on purpose: it is the reading that holds whichever way upstream's parenthesis is
|
||||
later construed (whether it bounds *where* a frontmatter block may appear or *which* keys it may
|
||||
carry — an open question this convention does not own). The gate does not read this marker at all.
|
||||
- **This convention's version** (top of this file) — bumped when the shared *form* (the §3 floor)
|
||||
changes. `log.md` records bumps of the two versions (`okf_version` and this one); each triggers a
|
||||
per-plugin re-check. Hooks are offline (no auto-poll); version drift is caught by human review + the
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue