open/llm-ingestion-okf
1
0
Fork 0
Code Issues Pull requests Releases Activity

docs(okf-v0.2): GA is not done when the code ships, but when consumers know

Browse source 
Operator directive: when the v0.2 implementation is ready, every OKF-consuming
repo is told through the coord mailbox what to do or test. That was a step title
in the runbook and is now a table with content -- nine repos, each with the
action asked of them and, more importantly, what happens if they do nothing.

For most the honest answer is "nothing changes", and saying that plainly is more
useful than an open invitation to review. That is the black-box commitment made
checkable rather than asserted.

Two new GA exit criteria: every repo in the table has been sent its message and
the table was re-derived rather than reused; and the security repo's section 10
boundary questions are either answered or their being open is recorded as an
accepted, stated limit. The second matters because Door C is the path an
external bundle's executable attester would take into a consumer's tree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2aKJxLejT9S8jYwoZ9fut
This commit is contained in:
Kjell Tore Guttormsen 2026-07-26 19:34:18 +02:00
commit b541e794a9
1 changed files with 38 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

38
docs/plan/okf-v0.2-alignment.md
View file

@ -684,6 +684,38 @@ request says so explicitly — otherwise a consumer who sees something odd but
passing has no reason to mention it. A clean run confirms what we already believed;
a differed expectation is the only thing that can change the design.
### The GA notification — what each repo is told to do or test
Operator directive 2026-07-26: when the v0.2 implementation is ready, every
OKF-consuming repo is told **through the coord mailbox** what they should do or
test. Not a status update — an instruction with a verdict attached.
It is a **bounded loop of directed messages, never a broadcast**: a broadcast is
inherited by every future repo, which is the wrong lifetime for a version-specific
notice.
Each message carries the same four parts: the version and its pinned upstream
commit; what we are asking of them; **what happens if they do nothing**; and the
black-box statement with its boundary. The third part is what makes the list below
honest — for most repos the answer is genuinely "nothing changes", and saying so
plainly is more useful than an invitation to review.
| Repo | What they do or test | If they do nothing |
|---|---|---|
| `portfolio-optimiser-claude` | Re-run their existing manifest under `DEFAULT` and confirm byte-identity with their frozen golden. Optionally adopt `OKF_V0_2` | Nothing changes. Their pin is explicit and `DEFAULT` is byte-stable |
| `catalog` | Re-run `okf-check.mjs` on a bundle emitting `OKF_V0_2`. Decide whether `MISSING` should keep conflating "absent", "BOM-eaten" and "MAY exercised" (U1) | Nothing changes. Their gate is version-shape-keyed, not value-keyed |
| `claude-code-llm-wiki` | Read the Test C expressiveness report (via coord, per their condition) and say whether any field we classed optional is load-bearing for them | Nothing changes. `STRICT_V1` is untouched by design |
| `portfolio-optimiser` | Re-run their golden suite against the new release. Confirm `DEFAULT` byte-stability from the sibling implementation's side | Nothing changes |
| `portfolio-optimiser-commons` | Nothing testable here — but the V1 outcome decides whether `DEFAULT`'s `generated` shape changes, and that is theirs to ratify | `DEFAULT` keeps emitting a v0.2-reserved key with a v1-era value |
| `llm-ingestion-pipeline-security` | Answer the §10 boundary questions: whether a non-`.md` code file inside a bundle is within `okf.import_bundle`'s mandate, and whether Door C should refuse bundles referencing `executor.resource` / `attester.resource` | We ship no Attested Computation fixture and implement no runtime, so the gap stays unexercised rather than unguarded |
| `okr` | Nothing at GA. The v0.2 contract reaches them in phase 4 when the Node half lifts their reference implementations | Nothing changes |
| `linkedin-studio` | Nothing. They measured zero exposure to both breaking changes and are deliberately staying at `0.1` | Nothing changes |
| `ms-ai-architect` | Nothing measured yet — the general notice went out 2026-07-26; re-derive their exposure at GA rather than assuming it is still zero | Unknown, which is why the re-derivation is on the list |
**Re-derive this table at GA rather than trusting it.** It is a premise like any
other, and consumer trees move — the wiki's document count moved by two between our
reading and their reply.
### GA exit criteria
1. Every P1–P3 finding is either fixed or explicitly accepted with the reason
@ -696,6 +728,12 @@ a differed expectation is the only thing that can change the design.
end-to-end.
6. `OKF_LATEST` flips to v0.2 in its own release, with a CHANGELOG entry stating
what changed for anyone bound to the alias.
7. **Every repo in the notification table has been sent its message** and the
table was re-derived rather than reused. GA is not done when the code ships;
it is done when the consumers know what it means for them.
8. The `llm-ingestion-pipeline-security` §10 boundary questions are answered, or
their being open is recorded as an accepted, stated limit — never left silent,
since Door C is the path an external bundle's executable attester would take.
**One honest limit on what GA can mean.** A three-repo pilot exercises only what
those three repos use. `sources` with `usage_window`, multi-verifier `verified`,