docs: every upstream OKF release runs a runbook, and this repo is a black box

The standing always-latest policy had no procedure, and v0.1 -> v0.2 showed what
that costs: the spec was read, the shipped example bundles were not, and five
findings a spec reading had settled wrongly surfaced only after someone asked
whether we had studied the examples. One of them re-sized the release itself.

docs/upstream-okf-upgrade-runbook.md is that procedure. Every step names the
concrete failure it prevents, and each is a failure that actually happened:

- Pin before reading. Two repos read main independently, which felt like two
  confirmations and was one unstable reference read twice -- and SPEC.md was
  edited after the migration commit, so neither alone was the whole answer.
- Enumerate the whole okf/ tree. bundles/ held the real examples and was on
  nobody's list until the tree was listed.
- Read the shipped examples, not only the normative text. A directory named
  samples/ turned out to be a runner config, not samples of the format. And
  markdown-converting fetch tooling strips exactly the byte-level properties
  (BOM, trailing newline, quoting) that break downstream gates.
- Name fixtures by repo AND path. Two repos had examples/ingest-golden-file/
  holding different fixtures with zero content overlap, and a pilot baseline was
  agreed by a name that pointed at two files.

The black-box commitment is now an invariant in CLAUDE.md rather than an
emergent property: a consumer's cost for an upstream release is a re-run.
Additive profiles, byte-stable existing profiles, keyword-only new parameters so
positional call sites survive, no churn in consumer fixtures. The boundary is
stated rather than glossed -- shape changes are absorbed, upstream changes to
consumer-authored content are not, and those get a measured exposure report per
consumer instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2aKJxLejT9S8jYwoZ9fut

CLAUDE.md

@@ -93,6 +93,23 @@ supported and the unspecified runtime is not; it re-enters scope when upstream
 specifies it. Because "always latest" decays silently, the release checklist
 carries an upstream-version re-check.
 
+**Every upstream release runs `docs/upstream-okf-upgrade-runbook.md`.** Pin the
+commit, enumerate the whole `okf/` tree, **read the shipped example bundles and not
+only `SPEC.md`**, classify the diff, measure our exposure and each consumer's, plan
+additively, pilot before GA, then inform every OKF-consuming repo. The runbook is
+not optional and not a summary of good intentions: each step names the concrete
+failure it prevents, and all of them are failures that happened during v0.1 → v0.2.
+
+**This repo is a black box for its consumers.** The target cost of an upstream
+release to a consuming repo is **a re-run, nothing more**: support is additive
+(a new profile, never a migration), existing profiles stay byte-stable, new public
+parameters are keyword-only with defaults so positional call sites stay
+source-compatible, and consumer golden fixtures must not churn. The boundary is
+stated every time rather than glossed — the library absorbs *shape* changes, not
+upstream changes to content a consumer authored (v0.2's `timestamp` and
+`# Citations` supersessions). For that class the deliverable is a measured exposure
+report per consumer, sent before they ask.
+
 Phase 4 preconditions (coordination, not unilateral moves):
 - Lifts okr's reference implementations (`okf-check.mjs`, `okf-index.mjs`,
   innboks libs) in agreement with okr and the marketplace catalog; the