docs(okf): retract false okr verdict-parity claim + fold in 7 distilled notes
The shared checker (scripts/okf-check.mjs) was lifted from okr once (c06e4d7,
2026-06-29) and never updated; okr hardened its checker afterward (skip
innboks/dot-dirs + scoped checkBundle @ 3b45be7, 2026-06-30; BOM/CRLF
normalization @ 482effb, 2026-07-17). The two have diverged and are NOT
verdict-identical. Retract the "byte-identical / verdict parity is verified"
claim everywhere it stood (spec.md section 7, log.md incl. a handed-out
conformance flag, and both script headers), replacing it with a precise, dated
provenance note. Establishing parity is tracked separate work
(check-okf-parity.mjs); fixes go upstream-first (drift is two-way). No code
behavior changed. Also folds the round's 7 distilled architecture notes into
log.md. Tests 33/33.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
1675ca36cf
commit
548a9abab3
4 changed files with 68 additions and 24 deletions
|
|
@ -38,7 +38,7 @@ distinct from conformance (code landed), which `linkedin-studio` alone holds so
|
|||
|
||||
| Plugin | Against minimal contract (spec §3) | Notes | Status |
|
||||
|---|---|---|---|
|
||||
| **linkedin-studio** | `type` + per-level `index.md` + root `okf_version` on `brain/`; `ingest/` excluded (round-trip-critical tributary) | Reference design. Emits frontmatter, adds no parser. Brain suite 134/134; passes the **shared gate** `catalog/scripts/okf-check.mjs` (scaffolded `brain/` → "OK: valid OKF bundle", exit 0) — same verdict as okr's reference checker. | 🟢 conformant @ linkedin-studio `da0a16a` (2026-06-26) |
|
||||
| **linkedin-studio** | `type` + per-level `index.md` + root `okf_version` on `brain/`; `ingest/` excluded (round-trip-critical tributary) | Reference design. Emits frontmatter, adds no parser. Brain suite 134/134; passes the **shared gate** `catalog/scripts/okf-check.mjs` (scaffolded `brain/` → "OK: valid OKF bundle", exit 0). | 🟢 conformant @ linkedin-studio `da0a16a` (2026-06-26) |
|
||||
| **okr** | `type` required + recommended-as-warnings + `okf_version` echo | Has the reference **writer + checker** (`okf-check.mjs`, `okf-index.mjs`, `lib/frontmatter.mjs`) + skill `okr-second-brain-search` v1.6.1. | 🟡 built · **spec ratified @ okr `75bfc9b` (2026-06-29)**; conformance-alignment landing = own go |
|
||||
| **ms-ai-architect** | designed, not built | Targets the fuller OKF package + a retrieval skill. Builds against this spec. | 🔵 designed · **spec ratified @ ms-ai-architect `72a7e2b` (2026-06-29)**; build = own go |
|
||||
|
||||
|
|
@ -94,16 +94,18 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
|
|||
`index.md` that carries frontmatter (§6 says it should not). So **"passes the gate" = "every concept
|
||||
file has `type:`"** — a necessary but **partial** §3 signal, not full §3/§6 conformance. Surfaced when
|
||||
portfolio-optimiser's bundle (index.md with frontmatter) passed. **To resolve in Stage 2 / a spec↔gate
|
||||
reconciliation:** either tighten the gate to enforce more of §3/§6 (costs the proven verdict-parity
|
||||
with okr's checker) or relax the spec's MUSTs to match what the gate actually enforces. **Not changed
|
||||
now** — tightening would silently break okr parity. _(linkedin-studio session, 2026-06-29.)_
|
||||
reconciliation:** either tighten the gate to enforce more of §3/§6 (diverges this copy further from
|
||||
okr — drift is two-way; fixes go upstream-first) or relax the spec's MUSTs to match what the gate
|
||||
actually enforces. **Not changed now** — there is no established okr parity to protect (see the
|
||||
2026-07-23 correction below); the fix belongs upstream, then re-vendored. _(linkedin-studio session,
|
||||
2026-06-29; parity framing corrected 2026-07-23.)_
|
||||
|
||||
## Change log
|
||||
|
||||
- **2026-06-29** — Convention **v0.1** authored (`spec.md`) + this log. Seeded from the three per-plugin
|
||||
design notes + linkedin-studio's verified premise corrections (mdcode ≠ OKF tool; no reusable OKF
|
||||
ingest code; classify/convert is build-yourself). linkedin-studio recorded **🟢** (brain emits
|
||||
OKF-compatible form, cross-tool-verified against okr's `okf-check`). okr / ms-ai-architect rollout =
|
||||
OKF-compatible form, validated by the shared gate `okf-check`). okr / ms-ai-architect rollout =
|
||||
separate per-repo go. _(Authored by the linkedin-studio session; operator relay to siblings pending.)_
|
||||
- **2026-06-29** — **Stage 1 ratification complete across all three tracks.** okr ratified spec v0.1 +
|
||||
adapted plan @ okr `75bfc9b`; ms-ai-architect ratified spec v0.1 + adapted plan @ ms-ai-architect
|
||||
|
|
@ -111,9 +113,9 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
|
|||
interop goal of Stage 1 is met at the convention level. Conformance *landings* (okr form-alignment,
|
||||
ms-ai-architect build) remain each their own go. _(linkedin-studio session, operator relay.)_
|
||||
- **2026-06-29** — **Shared acceptance gate landed** (`catalog/scripts/okf-check.mjs` +
|
||||
`okf-frontmatter.mjs` + `okf-check.test.mjs`). Lifted faithfully from okr's reference impl; verdict
|
||||
logic byte-identical, English output, zero deps, self-contained. Verified: 33/33 catalog tests green;
|
||||
verdict parity with okr's checker on okr fixtures (positive + negative); a scaffolded linkedin-studio
|
||||
`okf-frontmatter.mjs` + `okf-check.test.mjs`). Lifted from okr's reference impl at `c06e4d7`; English
|
||||
output, zero deps, self-contained. Verified: 33/33 catalog tests green; the gate's own §3 verdicts held
|
||||
on okr fixtures (positive + negative) at lift-time; a scaffolded linkedin-studio
|
||||
`brain/` validates clean (exit 0). Wired as the conformance gate (protocol §6 + spec §7): a plugin
|
||||
only moves to 🟢 after passing it. The only Stage-3 remainder is reconciling the TS/mjs impls — not
|
||||
required for the gate. _(linkedin-studio session.)_
|
||||
|
|
@ -135,3 +137,32 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
|
|||
→ exit 0, 5 konsepter, 0 uten type, okf_version 0.1, nøyaktig de 2 `resource`-warnings nevnt
|
||||
(`kilder-realiseringsgap.md`, `metode-ipmvp-a.md`); `index.md` bærer frontmatter (`type: index`);
|
||||
commit `812db23` finnes lokalt. Påstandene stemmer.
|
||||
- **2026-07-23** — **Parity claim retracted (drift correction).** Earlier entries and `spec.md` §7
|
||||
stated the catalog gate is "byte-identical" to / "in verdict parity with" okr's checker. That is
|
||||
**false against okr's current checker.** The copy was lifted once (`c06e4d7`, 2026-06-29) and never
|
||||
updated; okr began hardening the next day (`3b45be7`, 2026-06-30: skip `innboks/`+dot-dirs, scoped
|
||||
`checkBundle(root, { strictIngest, files })`) and added BOM/CRLF normalization weeks later
|
||||
(`482effb`, 2026-07-17; `lib/frontmatter.mjs:23`) — none of which the catalog copy has. The two can
|
||||
already diverge on the same input. The lift-time parity run was green but narrow (okr's own fixtures,
|
||||
bundle-verdict) and is now stale. Establishing parity is tracked separate work: a CI-run gate over a
|
||||
spec-derived adversarial corpus (`check-okf-parity.mjs`). Fixes go **upstream-first** — drift is
|
||||
two-way; re-copying okr is the cause, not the cure. _(catalog session.)_
|
||||
|
||||
## Distilled architecture notes (OKF round, 2026-07)
|
||||
|
||||
Durable conclusions from the cross-repo round (full working context retained by the catalog session):
|
||||
|
||||
1. **One form, two depths.** A flat bundle is a degenerate depth-1 of the spec §3 tree, not a
|
||||
separate form.
|
||||
2. **A shared fixture-suite is blocked** on three things: a sibling's golden-test invariant, a
|
||||
commons-owned ingest spec, and this convention's own unimplemented per-level rule.
|
||||
3. **Discovery, not placement.** The bundle marker is the root `index.md` + `okf_version`; resolution
|
||||
is explicit param → plugin config → environment → search root. The marker itself is inert.
|
||||
4. **A closed `type` vocabulary is a writer requirement, not a form requirement** — it constrains the
|
||||
`type` value, not the field-set.
|
||||
5. **The parity check was actually run and was green** — but at lift-time, against okr's own fixtures,
|
||||
at bundle-verdict granularity. "Spec-derived" is the load-bearing word, not "spec-owned": the
|
||||
corpus is derived from the spec, not certified by any one implementation.
|
||||
6. **No artifact may self-certify parity.** Parity is a gate's output over a corpus, never a claim in a
|
||||
file's header or comment.
|
||||
7. **Vendoring requires** a provenance pointer (source repo + SHA), a CI gate, and upstream-first fixes.
|
||||
|
|
|
|||
|
|
@ -85,19 +85,27 @@ npm dependencies, only couples to a ~55-line `frontmatter.mjs`. The shared spec
|
|||
semantics; it does not reinvent them.** Reading okr's code is fine; **writing okr is a separate go.**
|
||||
|
||||
A **shared checker now lives here:** `catalog/scripts/okf-check.mjs` (+ vendored
|
||||
`okf-frontmatter.mjs`), lifted faithfully from okr's reference impl — verdict logic byte-identical,
|
||||
output in English, zero deps, self-contained. It is the **canonical cross-plugin acceptance gate**: a
|
||||
bundle's pass/fail is the same here as under okr's checker. Run it per bundle root:
|
||||
`okf-frontmatter.mjs`), originally lifted from okr's reference impl at `c06e4d7` (2026-06-29),
|
||||
output in English, zero deps, self-contained. It is the **canonical cross-plugin acceptance gate**
|
||||
for this convention's §3 minimal contract. Run it per bundle root:
|
||||
|
||||
```
|
||||
node catalog/scripts/okf-check.mjs <bundle-root>
|
||||
```
|
||||
|
||||
Verdict parity is verified — identical exit codes to okr's checker on okr's own fixtures
|
||||
(`okf-minimal`, `okf-realistic`), positive and negative (injected missing-`type`) — and a scaffolded
|
||||
linkedin-studio `brain/` validates clean ("OK: valid OKF bundle", exit 0). Each plugin may keep its own
|
||||
dev-loop check (linkedin-studio's TypeScript impl under `scripts/brain/` stays for its own suite); the
|
||||
catalog `.mjs` is the shared gate all three are measured by. The only Stage-3 remainder is *reconciling*
|
||||
**Verdict parity with okr's *current* checker is not established — do not rely on it.** The catalog
|
||||
copy was lifted from okr once (`c06e4d7`); okr began hardening its checker the next day (`3b45be7`,
|
||||
2026-06-30: an `innboks/`+dot-dir walk ignore `okf-check.mjs:37-38`, and a scoped
|
||||
`checkBundle(root, { strictIngest, files })` signature `:73`) and added BOM/CRLF normalization weeks
|
||||
later (`482effb`, 2026-07-17; `lib/frontmatter.mjs:23`), while this copy stayed frozen at the lift — so
|
||||
the two can already diverge on the same input. The one parity check ever run was at lift-time, against
|
||||
okr's *own* fixtures, at bundle-verdict granularity — green then, but stale now and never per-file. A
|
||||
CI-run parity gate over a spec-derived adversarial corpus (`check-okf-parity.mjs`, tracked, not yet
|
||||
built) is what would *establish* parity; until then, treat the catalog checker as its **own**
|
||||
implementation of the §3 floor, not a verified twin of okr's. A scaffolded linkedin-studio `brain/`
|
||||
validates clean under this gate ("OK: valid OKF bundle", exit 0). Each plugin may keep its own dev-loop
|
||||
check (linkedin-studio's TypeScript impl under `scripts/brain/` stays for its own suite); the catalog
|
||||
`.mjs` is the shared gate for this convention's §3 floor. The only Stage-3 remainder is *reconciling*
|
||||
the two language implementations into one — deferred until measured need, and **not** required for the
|
||||
gate to function.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,10 +10,13 @@
|
|||
// - the bundle-root index.md's `okf_version` is echoed for human comparison
|
||||
// (no auto-fetch — offline by design).
|
||||
//
|
||||
// Lifted faithfully from okr/scripts/okf-check.mjs (the de-facto reference
|
||||
// implementation; spec §7), with English output + a vendored frontmatter reader so
|
||||
// the catalog copy is self-contained. Verdict logic is byte-identical, so a bundle's
|
||||
// pass/fail is the same here as under okr's checker. Run per bundle root.
|
||||
// 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
|
||||
// frontmatter reader so the catalog copy is self-contained. okr has since hardened its
|
||||
// checker (skip innboks/dot-dirs + scoped checkBundle @ 3b45be7; BOM/CRLF normalization
|
||||
// @ 482effb); this copy has NOT, so it has DIVERGED and is not verdict-identical with
|
||||
// okr's current checker. Parity is a gate's output over a corpus, not a claim in this
|
||||
// header — see docs/okf-second-brain/log.md. Run per bundle root.
|
||||
// Zero npm dependencies (node: builtins).
|
||||
|
||||
import { readdirSync, readFileSync, existsSync } from 'node:fs';
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
// okf-frontmatter.mjs
|
||||
// Minimal flat-frontmatter reader for the shared OKF conformance checker.
|
||||
// Vendored from okr's lib/frontmatter.mjs (the reference implementation) so the
|
||||
// catalog-hosted checker is self-contained — zero npm dependencies, no cross-repo
|
||||
// import. The checker only reads (never writes), so only parseFrontmatter().get is
|
||||
// vendored. Parsing logic is kept byte-identical to okr's so verdicts stay in parity.
|
||||
// Provenance: vendored from okr's lib/frontmatter.mjs at c06e4d7 so the catalog-hosted
|
||||
// checker is self-contained — zero npm dependencies, no cross-repo import. The checker
|
||||
// only reads (never writes), so only parseFrontmatter().get is vendored. okr has since
|
||||
// added BOM/CRLF normalization here (lib/frontmatter.mjs:23); this copy has not, so the
|
||||
// two have diverged and are no longer byte-identical (parity is the parity-gate's job,
|
||||
// not this file's).
|
||||
|
||||
const FM_RE = /^---\n([\s\S]*?)\n---/;
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue