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

docs(okf): retract false okr verdict-parity claim + fold in 7 distilled notes

Browse source 
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:
Kjell Tore Guttormsen 2026-07-23 22:05:13 +02:00
commit 548a9abab3
4 changed files with 68 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

24
docs/okf-second-brain/spec.md
View file

@ -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.