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
|
||||
|
|
|
|||
|
|
@ -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}`);
|
||||
|
|
|
|||
|
|
@ -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 });
|
||||
}
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue