Two findings from the inbox, both re-verified against the other repo's code
rather than its summary.
§8 -- the "contradiction" we flagged was ours to misread. We had SKILL.md:94
(union) against CLAUDE.md:67 (precedence) and asked okr to adjudicate, assuming
SKILL.md because it describes actual procedure. Right, and right for the stated
reason. Verified @52129b5: SKILL.md:35-36 "always search both, project first",
:46-47 "overrides ... ON CONFLICT", :94-95 "Glob both roots". Union is the
search SPACE; precedence is a tie-break that fires only when the same content
sits in both roots -- orthogonal, which is why one file carries both without
contradicting itself. okr fixed CLAUDE.md:67 ("else" implied a lookup stopping
at the first root). §8 stays OPEN at the convention level; only its description
of okr is refined -- retrieval carries union AND precedence as two layers, not
one axis each.
The wiki -- llm-ingestion-okf reported, unprompted, that claude-code-llm-wiki
requires exactly the construction rule §3/§6 forbids. Re-read here @59ef033:
validate.py:74 puts BUNDLE_INDEX_COMPLETE at ERROR, :1097-1104 derives expected
from the directory and demands bidirectional match, bundle.py:498 generates
indexes machine-side. This is not our trap sprung -- it is its mirror image,
chosen: we forbid derivation because a derived index CANNOT DISAGREE with the
directory and so hides what is missing, while they make "cannot disagree" an
enforced invariant with a loud outcome. Our index is a curated selection that
must be able to disagree; theirs must not be. Neither is incoherent.
Consequence (theirs): authored-vs-derived cannot be a library invariant in
either direction; it becomes policy. And the sharpest argument came back at us
-- a field carrying only "per-directory: yes" would have hidden the difference
entirely. That is a better case for splitting scope from construction than the
one we gave them.
Suite 78/78. Inbox emptied: 4 in, 2 replies, 2 closed without reply.
The 2026-07-23 reservation said enforcement waits until "the emitters have
migrated". Measured rather than assumed, and the emitter set turned out to be
TWO, not three:
okr @0059da7 okf_version: 0.1 + okf_layout: kb-layout-2026-06. Migrated.
linkedin-studio scaffold.ts:38 -> okf_version: 0.1. Never carried a layout
string; has no okf_layout and needs none.
ms-ai-architect NOT an emitter. Zero index.md in the repo; okf_version
appears in one planning doc. The status table already said
"designed, not built" -- only the word "emitters" implied it.
Swept the whole marketplace plus the sibling consumer repos: every live
okf_version value is 0.1. The flip is a no-op today and locks the invariant.
The gate checks SHAPE (/^\d+(\.\d+)*$/), never membership: the upstream value
set is Google's (spec §12), so a bundle targeting a newer version passes. A
membership check would be the convention claiming a set it says it does not own
-- the over-reach class this round has corrected three times. Presence stays
unenforced (reported, not failed) as a separate §3 MUST.
Convention bumped 0.1 -> 0.2 by this log's own criterion: the set of conforming
bundles changed (the spec explicitly said a layout string "conforms today", and
rollout rule 6 defines conformance as gate output). The §12 per-plugin re-check
is pre-measured as finding zero violations.
Also closes a parity blind spot found while landing this: check-okf-parity
compared the okf_version VALUE, which is identical exactly when two impls
disagree about whether it is acceptable -- a false "agree" on the axis the gate
exists to watch. The signature now carries a boolean shape verdict, with
red-marker-layout as the committed red proof. Its "diverge" expectation encodes
okr's lag (they still pure-echo) and flips to "agree" when they mirror it.
And a correction the round earned: portfolio-optimiser enumerated their own
bundle surface and it is four, not three. The dormant fourth
(reference_domain.py:49 -> package data at :70) has no flag form at all, so our
published claim that the re-measurement surfaced "one" unreported entry was
itself one-of-two. Sharpens the standing rule: a search shaped like one entry
type cannot see another; install-vs-fixture is one instance, not the class.
Suite 73 -> 78. coord: PO replied, okr + llm-ingestion-okf notified (the latter
under the standing promise to flag any okf-check.mjs change).
commons reviewed the STEG 5 text at 3ccb5f6 against their own anchors.
Both questions we asked passed; the findings we did not ask about are
the ones that mattered. All four anchors re-verified here against their
files before acting — including their own mid-review correction, which
was right (the "never by directory enumeration" clause is
method-spec.md:82-83, not :70-73; :68-73 is the escape-not-depth rule).
3(b) — §3's "(directory enumeration)" was ambiguous against a rule that
forbids navigating by directory enumeration. Now "an authored
enumeration of that directory's children — never a filesystem read".
Fixed at BOTH sites: §3 and §6 (commons flagged one; the second was
found here). Their reason for flagging it hard holds: code written
against the wrong reading passes every test you would think to write.
3(a) — "This is exactly okr's okf-check.mjs semantics, generalized" read
as a restatement of upstream while being stricter than it. Upstream
binds index.md to the bundle root alone (method-spec.md:81-85); we bind
every level. That is a legitimate floor of our own under §8, but it must
not borrow upstream's authority. Now stated as a superset, with the
single point of difference named. This was also the catalog's own
longest-open proposed correction, independently confirmed.
Q2 — the precedence hole is now named OPEN in §8. The two shapes were
installed and not-installed; okr is a third, two marked roots at once,
and the marker predicate cannot say which is read. okr's answer is that
there is no single answer: precedence for the org profile
(inject-okr-context.mjs:54-56), union for retrieval
(okr-second-brain-search/SKILL.md:94), because the roots carry different
content. Free while placement is descriptive; the first question a
second implementer asks if marker-based discovery ever goes normative.
Q1 hygiene — "root" carries four specified meanings across this
ecosystem. §1's bare uses are now qualified, with the other three named
and anchored so a reader arriving from method-spec cannot misparse.
Nothing normative changed for consumers: placement stays unmandated, the
§3 floor is unchanged in substance, and no path form is mandated.
Verified: suite 73/73; check-versions 11 OK · 0 WARN · 0 ERROR. The
okf-check FAIL on docs/okf-second-brain is structural and pre-existing
(the spec directory is not itself a bundle) — confirmed identical at
HEAD before this change.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CPHvLhn2U3j2XD3Cn8zeYa
The reference impl read the STEG 5 text and objected to one word: §1 said
okr "runs per-root over a project root … ahead of a home root". Verified
here against their code rather than their report, the objection holds —
that phrasing fused three distinct behaviours into one.
- profile axis is precedence (inject-okr-context.mjs:54-56 short-circuits
on the project hit)
- retrieval axis is union (okr-second-brain-search/SKILL.md:94 globs both
roots; they carry different content — project is cwd-bound cycle/work
data, home is org identity that survives reinstall)
- checking is neither (okf-check.mjs:11 runs each root independently)
So "ahead of" was true of exactly one axis and false as a statement about
the only implementation §1 describes.
Fixed by deletion, not elaboration: §1's job is that placement is not in
this contract, and that claim never needed an ordering. The axis detail
goes to log.md instead — naming one consumer's internal resolution order
in a scope section is the same class of leak the format exists to keep
out.
Placement remains unmandated (§8); nothing in the contract changed.
Verified: suite 73/73 across the six test files; check-versions 11 OK ·
0 WARN · 0 ERROR (okr released v1.8.0 mid-session and bumped the catalog
ref themselves in 8afd4f0).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CPHvLhn2U3j2XD3Cn8zeYa
The sample does not support a mandated path form. Of the four consumers
polled, exactly one installs a bundle anywhere (okr: project .claude/okr/
ahead of home ~/.claude/okr/org/); the other three install none — the
bundle dir is a caller-supplied argument per run, with no default, no
discovery, and no $HOME/~ expansion in their sources (verified by grep in
each repo, not taken from their reports).
One installation and three non-installations makes the standing criterion
("three installations before normative text") unmeetable from this
population, so no normative path form was written.
- spec.md §1: correct the in-scope example. A lone `~/.claude/<plugin>/…`
misstates okr's project-first precedence, i.e. it contradicts the only
real implementation — a fix that stands on its own regardless of n.
- spec.md §8: placement unmandated; "no installation root" named a
conforming consumer shape; installing vs. writing marked separate axes
(a consumer may write into a bundle it never placed).
- log.md: the measured sample with file:line evidence, plus two findings
the responses did not supply — neither portfolio-optimiser repo reads
okf_version at all (so neither is evidence for or against marker-based
discovery), and p-o-claude has a third --bundle entry point that does
carry a fixture default, contra its own account.
Confirms distilled note 3 ("discovery, not placement") rather than
extending it, and bears on Stage 2 (§10): three of four consumers have
nothing to discover.
Verified: suite 73/73 across the six test files; check-versions 10 OK ·
1 WARN · 0 ERROR (okr 1.8.0 untagged — their release is still in flight).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CPHvLhn2U3j2XD3Cn8zeYa
§3's okf_version MUST now states the value is the upstream OKF version alone;
a plugin's own layout revision belongs in the optional okf_layout marker (§12).
Marked explicitly NOT YET ENFORCED — no checker validates the value's shape, so
an emitter still carrying a layout string conforms today.
No convention version bump: §12 ties a bump to a change in the §3 floor, and the
set of conforming bundles is unchanged (a clarification, deliberately inert).
Non-enforcing is the deliberate shape. okr ratified the split and owns the
migration, but their scripts/okf-* are file-fenced frozen through the 1.8.0
consolidation. Enforcing okf_layout presence now would redden the STEG 3 parity
gate on okr with nothing they could do until that ships. Enforcement is a
separate scoped step after their migration lands.
log.md records the round's other settled items, each verified against ground
truth rather than accepted as asserted: the roll-up carrier is a no-op for the
public-mirror class (builder tolerates absence by design); the catalog runs no
index.md generator (read-side only), so commons' inherited item is stale; the
okf_version ruling already existed in §12; and the catalog's okf-check.mjs is
NOT byte-identical to okr's (141 differing lines), so parity here is behavioural
over the §3 floor in default read-mode via check-okf-parity.mjs — never byte
identity.
Verified: suite 73/73, check-okf-parity 8/8 exit 0, check-versions 11 OK/0 WARN/
0 ERROR.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CPHvLhn2U3j2XD3Cn8zeYa
Make OKF §3 checker parity a RUNNING per-file red/green signal instead of a
stale one-shot claim. The catalog and okr checkers provably diverge on the same
input (catalog walks everything + no BOM/CRLF norm; okr skips innboks/dot-dirs +
normalizes); this gate turns that divergence into a monitored, tested fact.
- scripts/check-okf-parity.mjs: n-way runner, zero-dep. Normalizes each impl's
existing checkBundle(root) return to {conceptCount, untyped[], okfVersion} and
compares per file over default read-mode. Impl registry is availability-guarded
so a catalog-only checkout degrades gracefully; a documented subprocess seam
awaits llm-ingestion-okf's Python checker (fase 2) + Node port (fase 4).
- test/okf-parity-corpus/: committed byte-exact adversarial corpus + manifest.
Red-proof fixtures (expected: diverge) the gate MUST go red on — byte axis
(BOM+CRLF) and tree axis (innboks, dot-dir) each carry one; canon = both.
.gitattributes -text pins the BOM/CRLF bytes. Green fixtures pin agreement
incl. a SHARED gap (both descend into node_modules).
- check-okf-parity.test.mjs: 8/8. Corpus assertions + byte-tracking red-proof +
runtime-materialized symlink/NFC-NFD meta-tests + graceful-skip seam.
Honest scope: only 2 impls expose a runnable per-file checker today, so the gate
runs 2-way and is architected n-way — no faked third impl, no cross-repo code.
spec §7 + log.md updated (no self-certified parity; fixes stay upstream-first).
Verified: parity 8/8, CLI exit 0; regression 33/33; check-versions 10 OK.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NeK9hkxrU9wFPBYGYnSV1V
okf_version had been carrying two unrelated concerns — the upstream OKF
version and a plugin's own layout revision. Split into two markers:
okf_version stays the upstream Google OKF version alone (currently 0.1,
value set owned by Google, single-valued bundle-root marker); a new
optional okf_layout marker holds a plugin's layout-revision snapshot.
Verified against ground truth: okr 056b652 stamps
okf_version: kb-layout-2026-06 (fixtures + bundle roots) — a known
deviation okr itself flagged, and it proposed exactly this okf_layout split.
Lands only the decision + spec text — NOT enforcement (§3 tightening stays
deferred to its own step, so okr's current value isn't flipped to a gate
failure yet; its migration is cheap since the field is pure echo today).
Additive + disambiguating: §3 floor unchanged, okf_layout optional, so the
convention version stays 0.1 — no re-ratification triggered.
- spec.md §12: rewrite defining the split
- log.md: protocol §5 clarified (third non-version marker) + dated change-log entry
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NeK9hkxrU9wFPBYGYnSV1V
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>
Lift okr's reference okf-check.mjs into the catalog as the single cross-plugin
acceptance gate for the OKF-compatible second-brain form (spec §3):
- scripts/okf-check.mjs (+ vendored okf-frontmatter.mjs): verdict logic
byte-identical to okr's reference impl, English output, zero deps, self-contained.
- scripts/okf-check.test.mjs: 5 self-contained tests (temp-dir bundles).
- spec §7 + §14: the shared checker now lives here; only TS/mjs reconciliation
remains Stage-3, not required for the gate. log.md protocol §6: conformance is
verified by the gate, not asserted — a plugin moves to 🟢 only after passing it.
Verified: 33/33 catalog tests green (canonical glob form); verdict parity with
okr's checker on okr fixtures (positive + negative missing-type); a scaffolded
linkedin-studio brain/ validates clean (exit 0).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012GqEHp4uDiivfrAUjw4BdE
