Kjell Tore Guttormsen
3ccb5f6afa
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
294 lines
25 KiB
Markdown
294 lines
25 KiB
Markdown
# OKF second-brain convergence — coordination log
|
||
|
||
> Cross-repo coordination for the OKF-compatible second-brain form (`spec.md`). This is the **one
|
||
> shared place** all three plugin sessions read to know where the others are. OKF reserves `log.md`
|
||
> for change logs; this extends it with rollout status + the coordination protocol.
|
||
>
|
||
> **No writing crosses repo boundaries** — each plugin session writes only its own repo (+ the catalog
|
||
> with its own go). Status here is updated via operator relay.
|
||
|
||
## Coordination protocol
|
||
|
||
The operator runs one Claude session per plugin repo and relays between them. To keep three
|
||
independent sessions converged **without** cross-repo writes (mirrors the maskinrommet feedback-register
|
||
pattern):
|
||
|
||
1. **Single source of truth = `spec.md`.** The convention is defined once, here. No plugin redefines it
|
||
locally; a plugin's local OKF doc *references* this file. (Mirrors the global rule: don't invent
|
||
local mechanisms; extend the shared one.)
|
||
2. **This log is the cross-repo state.** Convention version, decisions, per-plugin conformance status,
|
||
open coordination items. All three sessions read it.
|
||
3. **No writing crosses repo boundaries.** Each session writes only its own repo. The catalog is shared
|
||
but needs a per-session go. A plugin records its own conformance in its own STATE/changelog; the
|
||
operator relays it here.
|
||
4. **Operator = relay + truth-source.** Convention changes are proposed by any session, written here
|
||
(with go), and the operator carries "convention changed → re-check conformance" to the other
|
||
sessions.
|
||
5. **Two version markers** (spec §12): `okf_version` (upstream Google OKF) and this convention's own
|
||
version. Either bump → log it below → each plugin re-checks. (A third spec-§12 marker, the optional
|
||
`okf_layout`, is a plugin-own layout snapshot — not a version; it triggers no cross-plugin re-check.)
|
||
6. **Conformance is verified, not asserted.** A plugin's status only moves to 🟢 after its bundle passes
|
||
the shared acceptance gate `catalog/scripts/okf-check.mjs` (spec §7) — `node catalog/scripts/okf-check.mjs <bundle-root>` → exit 0. On a relayed conformance landing, run the gate against that
|
||
plugin's bundle and record the result here. Evidence-based flips only (operator verification-plikt).
|
||
|
||
## Per-plugin conformance status
|
||
|
||
Legend: 🔵 not started · 🟡 building / partial · 🟢 conformant (+ commit-ref). **Ratification**
|
||
(spec accepted + plan adapted) is recorded in the Status cell with the plugin's own commit-ref —
|
||
distinct from conformance (code landed), which `linkedin-studio` alone holds so far.
|
||
|
||
| 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). | 🟢 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 |
|
||
|
||
## Landing protocol — how a sibling records conformance
|
||
|
||
When your plugin's bundle actually conforms (the work of step 4, done in your own session):
|
||
|
||
1. **Record it in your own repo** (STATE/changelog) — as the handoff already instructs.
|
||
2. **Update THIS file** (your own catalog-go): set your row in the status table above to
|
||
🟡 → **"claims conformant @ `<commit>`, bundle `<path>`, awaiting gate-verification"**.
|
||
3. A **linkedin-studio session** then runs the shared gate against your bundle —
|
||
`node catalog/scripts/okf-check.mjs <path>` — and, on exit 0, flips your row to 🟢 with the proof.
|
||
|
||
This puts the landing signal in the **one shared doc**, so the operator need not hand-carry status, and
|
||
any session sees the truth on its next read. **Honest limit:** there is no live push-notification across
|
||
separate sessions — a landing is discovered when a session next *reads* this log (a linkedin-studio
|
||
session is told to check it at start; see its STATE). Self-flipping straight to 🟢 is **not** the
|
||
protocol; 🟢 is reserved for the independent gate-verified step (operator verification-plikt).
|
||
|
||
## Open coordination items (what each session must confirm)
|
||
|
||
> **✅ Resolved 2026-06-29 — both siblings ratified.** okr (`75bfc9b`) and ms-ai-architect (`72a7e2b`)
|
||
> ratified `spec.md` and adapted their plans. The items below are **accepted via ratification**; they
|
||
> are kept as the record of what was asked. Any new field-gap, change-proposal, or conformance landing
|
||
> arrives as a **fresh item / status bump**, not here.
|
||
|
||
**→ okr session:**
|
||
- Confirm `okf-check.mjs` semantics are stable enough to stand as the reference contract (spec §3, §7),
|
||
and that this spec faithfully generalizes them (only-`type`-required; recommended → warnings;
|
||
`okf_version` echo).
|
||
- Canonical recommended-field name is **`resource`** (OKF), not `source` — confirm okr uses `resource`.
|
||
- Flag any field okr needs that the minimal contract + recommended set doesn't cover.
|
||
|
||
**→ ms-ai-architect session:**
|
||
- Confirm the minimal contract + extension-key model (spec §3, §5) supports the planned **"full OKF
|
||
package"** KB structure — going fuller is fine; the minimal contract is the **floor, not the ceiling**.
|
||
- **Field-name drift:** the architect brief writes `source`/`timestamp` (line 45); canonical is OKF's
|
||
**`resource`**. Align on `resource`.
|
||
- **mdcode is not an OKF tool** (spec §9.1) — drop it from the adoption plan. The `reference_agent`
|
||
enrichment is GCP/Gemini-bound (spec §9.2) — adopt the *prompt patterns*, not as drop-in code.
|
||
|
||
**→ both:**
|
||
- Ratify `spec.md` as the shared contract, or propose changes here.
|
||
- Retrieval-skill naming/home: okr shipped `okr-second-brain-search`; architect plans
|
||
`second-brain-search`. If a shared skill ever happens (Stage 3), converge naming + home (standalone
|
||
plugin, spec §11) — **not now** (Stage 2 measurement must justify it first).
|
||
|
||
## Deferred decisions
|
||
|
||
- **Spec §3/§6 vs. the gate's actual coverage.** The shared gate `okf-check.mjs` (faithfully lifted from
|
||
okr's reference) fails **only** on a concept file missing `type:`. It does **not** fail on a missing
|
||
root `okf_version` (echoed as `MISSING`, not an error), missing per-level `index.md` (§3 MUST), or an
|
||
`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 (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, 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
|
||
`72a7e2b` (both relayed via operator). The shared contract is now accepted by all three — the
|
||
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 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.)_
|
||
- **2026-06-29** — **Ekstern form-konsument notert: portfolio-optimiser.** Et separat
|
||
Forgejo-rammeverk (MAF kostnads-optimiser, IKKE en marketplace-plugin) adopterte OKF-
|
||
minimal-formen uavhengig for sine per-prosjekt runtime-kunnskapsbundles — en ANNEN scope
|
||
enn denne konvensjonens bruker-second-brain (§1). Bundelen passerer den delte gaten
|
||
(`node catalog/scripts/okf-check.mjs <bundle>` → okf_version 0.1, "OK: valid OKF bundle",
|
||
exit 0) etter å ha lagt til rot-`okf_version`-markøren; commit portfolio-optimiser `812db23`.
|
||
Registrert så on-disk-FORMEN ikke driver fra hverandre i økosystemet (global regel: konformer
|
||
til den delte formen, ikke re-derive). IKKE et 4. konvergens-medlem — ingen bruker-second-brain,
|
||
ingen delt ingestion (spec §8–9: build-yourself), ingen delt retrieval. Eneste framtidige
|
||
overlapp: bygger portfolio-optimiser verdict-promotering (sitt «steg 8»), er den gjenbrukbare
|
||
skrive-primitiven okr's `okf-index.mjs` + frontmatter-skriver. Kjente avvik på bundelen:
|
||
2 `resource`-warnings (utelatelse tillatt, §4); `index.md` beholder frontmatter (avviker fra
|
||
§6 reservert-index, beholdt fordi dens `okf.py`-leser klassifiserer index på type).
|
||
_(Relayet fra portfolio-optimiser-sesjonen; bruk i en catalog-sesjon per protokoll §3.)_
|
||
**Gate re-verifisert i denne catalog-sesjonen (uavhengig):** `shared/examples/bygg-energi-mikro`
|
||
→ 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.)_
|
||
- **2026-07-23** — **`okf_version` / `okf_layout` split (spec §12).** `okf_version` had been carrying two
|
||
unrelated concerns — the upstream OKF version *and* a plugin's own layout revision. okr flagged this as
|
||
a blocker and left the call to the convention owner: its bundle roots + fixtures stamp
|
||
`okf_version: kb-layout-2026-06` (a layout snapshot, not `0.1`) — a known deviation okr already
|
||
documented, and it proposed exactly this two-field split (verified against okr `056b652`). **Decision
|
||
(owner, catalog):** `okf_version` stays the upstream Google OKF version alone (value set owned by
|
||
Google, single-valued — the bundle-root marker relies on that, §6); a new **optional** `okf_layout`
|
||
marker line holds a plugin's own layout-revision snapshot. **This step lands only the decision + spec
|
||
text** (§12) — *not* enforcement. §3 tightening that would flip okr's current value from "echoes an odd
|
||
value" to "fails the gate" stays deferred to its own step; the field's re-check semantics are pure echo
|
||
today, so okr's migration (move the value to `okf_layout`) is cheap when it happens, and it should
|
||
happen before that tightening. Additive + disambiguating: the §3 floor is unchanged and `okf_layout` is
|
||
optional, so **the convention version stays `0.1`** — no re-ratification triggered. _(catalog session.)_
|
||
- **2026-07-23** — **STEG 3: the running parity gate landed** (`scripts/check-okf-parity.mjs` +
|
||
`test/okf-parity-corpus/` + `check-okf-parity.test.mjs`). Parity is now a *running* per-file red/green
|
||
signal over a committed spec-adversarial corpus, not a stale one-shot claim (retracted above). **Verified
|
||
scope blocker (ground-truth this session, 2 independent agents + grep):** the round named ≥3 impls, but
|
||
**only two expose a runnable per-file checker** — catalog + okr. llm-ingestion-okf's Python lib is a
|
||
*producer* (no `check_bundle`, no CLI; checker is fase-2, its own repo); linkedin-studio's TS §3 logic
|
||
lives only in private test helpers (not a participant). **Decision (operator delegated on quality
|
||
grounds):** build the gate **n-way-capable, wire the 2 real impls now**, with a documented availability-
|
||
guarded seam for the Python checker (fase 2) and its Node port (fase 4) — no faked third impl, no
|
||
cross-repo code. Decisions the earlier record left open, now fixed: **(a) per-file contract** = each
|
||
impl's existing `checkBundle(root)` return normalized to `{ conceptCount, untyped[], okfVersion }`,
|
||
compared per file (concept-set + type verdict), over **default read-mode** (strictIngest off, not
|
||
files-scoped); **(b) adapter convention** = JS impls imported directly (both export `checkBundle`), zero
|
||
subprocess/zero dep; cross-repo/other-language impls get a subprocess `--json` adapter when they exist;
|
||
**(c) corpus form** = committed byte-exact fixtures (`.gitattributes -text` pins BOM/CRLF), the inspectable
|
||
"borne proof"; **(d) red-proof** = `expected: "diverge"` fixtures the gate MUST go red on (byte + tree
|
||
axes each carry one; canon = BOM+CRLF concept + `innboks/` raw file, catalog FAIL vs okr OK). Axis
|
||
decisions: IN = byte (BOM/CRLF), tree (innboks, dot-dir, node_modules[shared gap, both descend],
|
||
duplicate-name, hierarchical); **WITHDRAWN** = verbatim/trailing-newline (trinn E §1); **OUT of STEG 3** =
|
||
path-forms (rerouted to §1.2/STEG 5). The git/FS-hostile axes (live symlink, NFC/NFD filename) are
|
||
covered as **runtime-materialized meta-tests** (temp dir), not committed fixtures. The gate does **not**
|
||
claim the two checkers are identical (they provably are not) — it makes their divergence a monitored
|
||
fact. Verified: parity 8/8, `node check-okf-parity.mjs` → exit 0 ("parity holds"); regression 33/33;
|
||
`check-versions` 10 OK. Fixes stay **upstream-first** (patching BOM-norm into the catalog copy would just
|
||
re-diverge in the other direction). _(catalog session.)_
|
||
- **2026-07-24** — **STEG 0: nav-golden fixture class consumed + thin corpus gate landed**
|
||
(`test/nav-golden-corpus/` + `scripts/check-nav-golden.mjs` + `check-nav-golden.test.mjs`). commons
|
||
authored a `nav-golden` fixture class — each fixture is an OKF bundle paired with a committed
|
||
byte-exact `expected-read-context.md` golden (the fasit a conformant read-context navigator, commons
|
||
`method-spec.md §3 Step 1` + §11 Navigation boundary, must produce). **Consumed byte-exact from
|
||
portfolio-optimiser-commons `b641741`** (`nav-golden-hierarchy` positive + `nav-golden-escape`
|
||
boundary; `diff -r` identical; `.gitattributes -text` pins bytes; manifest carries source repo+SHA per
|
||
vendoring rule #7). **Scope decision (operator, thin):** the catalog is the convention owner and holds
|
||
no consumer (null konsument), and the shared retrieval skill is deferred (spec §10 Stage 3, "do not
|
||
build before Stage 2 says so") — so the gate does **not** run a navigator and does **not** assert the
|
||
goldens byte-exact. It asserts only what the catalog owns: each fixture `bundle/` is a conformant OKF
|
||
bundle under the existing §3 `checkBundle` (every concept typed + root `okf_version`), and the committed
|
||
golden is present + non-empty. Byte-exact navigator conformance stays a consumer concern (okr STEG 4 /
|
||
the deferred Stage 3 skill). **Naming correction (relayed to + confirmed by commons via coord):** the
|
||
earlier record's "§5 pts 1-5" read-context label was stale — the settled normative location is
|
||
`method-spec §3 Step 1`'s five read-context bullets (commons `9801d35`); there is no open §5 dependency
|
||
(current spec §5 = extension keys). commons confirmed both prerequisites: Q1 `b641741` is the complete
|
||
nav-golden set (future cases additive, non-moving); Q2 the goldens derive from settled §3 Step 1.
|
||
Verified: `check-nav-golden` 10/10; gate CLI → exit 0 (2 fixtures PASS — hierarchy 5 concepts / escape 1,
|
||
`okf_version` 0.1, goldens present); full suite **73/73** across the six test files. _(catalog session.)_
|
||
- **2026-07-25** — **STEG 4: §3 tightened (non-enforcing) on the `okf_version` / `okf_layout` split.**
|
||
§3's `okf_version` MUST now states the value is the **upstream version alone**, with a plugin's own
|
||
layout revision belonging in the optional `okf_layout` marker (§12) — and marks itself **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 non-enforcing).
|
||
**Why non-enforcing (okr's answer, received via coord):** okr ratified the split and owns the
|
||
migration, but `scripts/okf-*` is file-fenced **frozen** through their 1.8.0 consolidation (Wave 4/6);
|
||
the migration runs as scoped work right after release. It is an **ETA, not an open blocker** — their
|
||
field is pure echo text with no validation semantics, so they do not fail the gate meanwhile. Making
|
||
§3 *enforce* `okf_layout` presence now would redden the STEG 3 parity gate on okr with nothing they
|
||
could do until 1.8.0 ships. Enforcement is therefore a separate scoped step, after their migration.
|
||
**Also settled this round (all verified against ground truth, not accepted as asserted):**
|
||
(a) **D2 roll-up carrier is a no-op for the public-mirror class** — `build-rollup-register.mjs`
|
||
defaults `carrierMode` to `absent` and only `committed` reaches output B, so okr, ms-ai-architect and
|
||
claude-code-llm-wiki are excluded **by design**, never reported as missing/malformed; no code change.
|
||
(b) **The catalog runs no `index.md` generator** — read-side only (`okf-check.mjs:45`,
|
||
`check-nav-golden.mjs:48`); commons' inherited "catalog regenerates index.md" item (ingest-spec §6)
|
||
is **stale** and needs no §6 ruling. (c) **`okf_version` ruling already existed** — spec §12 (lines
|
||
174–186) settled it; llm-ingestion-okf was pointed at the written text rather than issued a new one.
|
||
(d) **Correction issued to llm-ingestion-okf:** their premise that the catalog's `okf-check.mjs` is
|
||
"vendored byte-identical from okr" — and thus their Phase 4 conformance oracle — is **false**
|
||
(141 diff lines; okr's copy adds `strictIngest`, `files` scoping, `innboks`/dot-dir exclusion and
|
||
`lib/` deps). Parity here is **behavioural on the §3 floor in default read-mode**, gated by
|
||
`check-okf-parity.mjs`, never byte identity; their impl's real entry point is that gate's n-way
|
||
`IMPLS` registry behind `available()`, not a catalog `ref` (they are not a marketplace plugin, and
|
||
`check-versions.mjs`/`release-plugin.mjs` operate only over `marketplace.json` entries).
|
||
Verified: full suite **73/73** across the six test files; `check-versions` 11 OK · 0 WARN · 0 ERROR.
|
||
_(catalog session.)_
|
||
- **2026-07-25** — **STEG 5 (installation root) settled as _descriptive_, not normative: the sample
|
||
does not support a mandated path form.** The ecosystem was asked where each consumer installs its
|
||
bundle. Every answer was given **against code, not docs**, and each was re-verified here before
|
||
being acted on:
|
||
- **okr** — the only real installation. Two roots: project `.claude/okr/` **ahead of** home
|
||
`~/.claude/okr/org/`, each checked per-root (okr `scripts/okf-check.mjs:11`,
|
||
`lib/innboks-write.mjs:44`).
|
||
- **portfolio-optimiser-commons** — declined, correctly. Spec owner with no runnable pipeline; its
|
||
only bundle-shaped bytes are conformance fixtures, so answering would have codified a **test
|
||
artifact as an installation site**.
|
||
- **portfolio-optimiser** — **no root.** `--bundle-dir` defaults to `None` (`run.py:653`); absent
|
||
it, the feature is simply off. Verified here: **0 hits** for `expanduser|Path.home|.claude/`
|
||
across `src/`.
|
||
- **portfolio-optimiser-claude** — **no root.** `--bundle` defaults to `None` (`run.py:554`);
|
||
`bundle_dir` is a required non-empty config field (`contracts.py:81`). Verified here: **0 hits**
|
||
for the same patterns across `src/`.
|
||
|
||
**One installation, three non-installations** — so the standing acceptance criterion ("three
|
||
installations before normative text") is not merely unmet, it is **unmeetable from this
|
||
population**. Landed in `spec.md` as exactly two things: the §1 in-scope example corrected (it
|
||
showed a lone `~/.claude/<plugin>/…` form that misstates okr's project-first precedence), and a new
|
||
§8 bullet naming placement unmandated, **"no installation root" a conforming consumer shape**, and
|
||
*installing* vs. *writing* separate axes (a consumer may write into a bundle it never placed).
|
||
**No normative path form was written.**
|
||
|
||
Two things the responses did not supply, both found here: **(a)** neither portfolio-optimiser repo
|
||
reads `okf_version` at all (**0 hits** in `src/` for both), so neither is evidence for *or against*
|
||
marker-based discovery — though p-o-claude's fixture *carries* the marker, so a marker-based reader
|
||
would still recognise it. **(b)** p-o-claude's own account ("two entry points, both with no
|
||
default") is inexact: `run_s10.py:46` is a **third** `--bundle` entry point and it *does* carry a
|
||
default — `parents[2]/shared/examples/bygg-energi-mikro`, a repo-relative fixture. That leaves their
|
||
headline standing (no `~`/`$HOME`/`.claude` anywhere in `src/`) but it is the same
|
||
fixture-as-location class commons declined to answer from; returned to them.
|
||
|
||
This **confirms distilled note 3 ("discovery, not placement") rather than extending it** — the
|
||
measured population is dominated by that chain's first link, an explicit caller-supplied param. It
|
||
also bears on **Stage 2 (§10)**: the evidence points *away* from a Stage-3 discovery convention,
|
||
since three of four consumers have nothing to discover. _(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.
|