OKF Bundle Doctrine

OKF Bundle Doctrine — Canonical platform

Status: RATIFIED (owner, 2026-07-16, idea-refine session) — substrate doc for the implement-okf initiative project. Provenance: bl-465 research closure (4 parallel research passes: source-path, composition, content/naming, gate stress-test) + okf.md spec/examples review + id-71 doc distillation. Owner’s original framing notes: bundle-doctrine-interim-notes. Names previously-implicit posture; supersedes nothing.

Problem statement

How might we define one coherent OKF bundle doctrine — what bundle classes exist, how each is produced and gated, and why (in id-71 outcome terms) — so every id-132+ implementation decision derives from it instead of accreting per-session rulings?

Why OKF (the outcome statement)

Canonical adopts OKF because it is the carrier of the id-71 knowledge affordances for headless, dual-runtime agents (HC-3: Claude runtimes AND goose consume the identical surface, no skill layer required):

id-71 affordance	OKF mechanism	Status
A17 fact-trace / claim verification	# Citations trailer + resource: anchors; seen-anchors provenance discipline	Present (provenance-to-record); live re-verification absent
A19 confidence-posture	per-concept confidence frontmatter field	Ratified 2026-07-16 for BOTH bundle classes (bl-477; joins the {132.35} gate set)
A20 supersession / version lineage	log.md + deprecation markers + supersedes relation + citation-shrink detection	Present
A21 ontology grounding	ontology.json (base ∪ overlay, self-describing) + bl-457 IRI projection	Present (IRI projection ratified, landing)
A22 propose → human confirm	the promotion gate (governance promotion-candidates)	Present — this IS the Path-1 gate

Working back from outcomes (O1 answer-with-citations, O4 briefing, O6 exposure): agents need portable, self-describing, citation-grounded knowledge that survives moving between systems. The format is the contract; tooling at each end is swappable.

Bundle taxonomy — four classes

Class	Repo	Owner	Production path	Gate	Update cadence	Model
Client business	canonical-okf-bundle-cN	Client (DR-016)	Path 1 (refinery)	Human promotion gate	Producer runs	Anthropic
System baseline (bl-465)	canonical-okf-system	Platform	Path 2 (direct)	Born-evaluable: eval round-trip + CI regen + §9 (interim human sign-off until wired)	Platform releases, prove→pin→promote	OpenRouter GLM-5.2
Showcase	canonical-okf-showcase (renamed from canonical-okf-platform at the S487 publish — bl-479 DONE)	Platform	Path 1 over synthetic corpus	§9 + light human sign-off	Ad hoc	OpenRouter GLM-5.2
Internal dev	canonical-okf-internal (bl-478)	Platform (private)	Path 2 over docs-site	§9 + CI regen	Ad hoc	OpenRouter GLM-5.2

Naming rationale: avoid -base (collides with base-ontology/base-namespace terminology). Client pattern unchanged.

Two production paths (named divergence from upstream, per the bl-457 lesson)

• Path 1 — refinery-gated. Client BUSINESS knowledge: evidence → cocoindex sieve → staged proposals → human promotion gate → canonical L-records → id-132 producer → bundle. The gate exists because evidence-derived client canon carries authority. Connectors to client systems feed the PIPELINE (evidence), never the bundle directly.
• Path 2 — direct producer. Platform SYSTEM knowledge: repo/docs → producer (RepoDocsSource, reusing the id-132 Source-ABC spine) → bundle. No human promotion gate; the gate is executable — every MCP-tool/schema concept must round-trip on the Platform corpus (agent reads concept → calls real tool → behaviour matches), regenerated in CI. HC-5 born-evaluable, ratified id-71.
• Upstream OKF has no gate at all (producers point directly at sources). Our Path-1 gate and Path-2 eval gate are deliberate supersets — documented, kept.

Gate rationale: blast radius inverts naive intuition — a wrong system concept misleads EVERY client’s agents; §9/BI-13 gate structure and provenance, never truth. Human review can’t verify tool behaviour by reading; an eval can. Ungated-but-CI-regenerated beats human-gated-going-stale — but ONLY once regeneration + round-trips are actually wired; until then, interim human sign-off.

Composition (ratified after challenge)

Repo = ownership unit · bundle = knowledge-scope unit · deployment mount = consumption union.

• System baseline ships as a SEPARATE platform-owned repo, release-pinned, promoted via the existing prove→pin→promote lane; deployed as a sibling subdirectory under each client’s OKF_BUNDLE_ROOT.
• Consumption is already multi-bundle for free: lib/okf/enumerate-bundles.ts unions all root subdirectories; /okf renders them as one surface. An agent navigating the business bundle finds system knowledge one directory over.
• Cross-bundle identity = bl-457 base-namespace IRIs (OKF has no cross-bundle markdown-link primitive; broken file-links tolerated by spec).
• Deciding factor: update-propagation — system knowledge at platform-release cadence via the promote lane; business knowledge at producer-run cadence via git_sync. Composing into the client bundle would subordinate platform fixes to producer-run cadence inside a client-owned keyset.
• Future growth path (named, not built): multi-bundle-per-repo is format-legal; a multi-source client may hold several bundle dirs in one client-owned repo. Current client lane assumes bundle == repo root (DR-055).

System bundle v1 scope

• Grain: one-per-tool from the start (owner-ratified) — matches upstream ga4/stackoverflow granularity (one file per table/metric/join). ≈68 concepts: ~41 MCP tools, ~10 schema, ~6 api (agent-facing routes only), ~6 navigation, ~5 playbooks. Types are per-bundle-class: schema/tool/api/navigation/playbook (validator’s closed business set does not apply; DR-019’s closed-type posture generalises per class).
• Authoring: okf-skill-assisted drafting on OpenRouter GLM-5.2 (docs-site already carries the OpenRouter config), human sign-off per concept (interim gate), then RepoDocsSource producer makes it regenerable. Producer agent-loop needs an OpenRouter-compatible provider path (current loop is Anthropic tool-use; Gemini fallback was already an id-132 line item).
• Citations: git-pinned public-repo blob URLs / resolvable doc pages (Google BigQuery precedent — live URLs in resource:). System bundle must NEVER cite the private docs-site; only canonical-okf-internal may.
• Change signal: grain-split per the S488 {163.18} G-SPAN-HASH ruling — the E1 code-symbol grain (tool/api/schema pillars) keys its memo-delta lever on a per-span synthetic content hash (sha256 of the matched defineTool(...) span text) so a single-tool edit redrafts exactly that one concept, not every sibling backed by the same .ts file; the E2 markdown-page grain (navigation/playbook pillars) keeps git rev-parse HEAD:<file> because a page IS a whole file, so the file-grained blob digest is already per-concept. Citation pins stay file-blob-based for BOTH grains (the citation pin and the memo lever are separate concerns — only the memo lever is span-scoped). Supersedes the DB-row memo used by the L-records path.

Not doing (and why)

• UA as producer (with ONE exception) — lane-1/2 nodes/edges carry no citation-grade anchors at concept grain; converting = re-grounding by hand. Inventory/taxonomy seeding only. Exception: /understand-knowledge over a real markdown tree at one-concept-per-page grain is a reasonable production alternative for the DOCS-DERIVED slice (the internal dev bundle) — the page path is emitted per node, so the anchor is free; sub-page claims still lack anchors.
• Composing system concepts into client bundles — ownership + cadence inversion (above).
• Per-route API concepts — 170 route.ts; only agent-facing routes concept-worthy.
• Human promotion gate on the system bundle — replaced by the eval gate; blast-radius risk is answered by round-trips, not reading.
• Blocking the {132.35} chain on bl-465 work — parallel lanes; the ONE coupling is A19 (bl-477).

Ledger record (2026-07-16 ratification)

• bl-465 — research closed, ready: system baseline bundle (verdicts in its notes).
• {132.35} — journalled: A19 joins the bundle-shaping gate set as the 5th item ({132.38} + bl-456 + bl-457 + bl-458 + bl-477).
• bl-477 (ready) — A19 confidence-posture frontmatter field, both bundle classes.
• bl-478 (parked) — canonical-okf-internal internal dev bundle.
• bl-479 (DONE, S487 publish) — showcase rename landed (canonical-okf-showcase).
• bl-463 rider (open, unratified): type-grouped no-map index default.

Key assumptions to validate

• Concept eval round-trips are cheap to wire onto the mcp-eval matrix (currently gates PR touchpoints, not concept reads) — validate during bl-465 impl planning.
• GLM-5.2 via OpenRouter produces citation-disciplined drafts under the seen-anchors mechanism — validate on the first 5 system concepts.
• The RepoDocsSource grain (tool/schema/api/nav/playbook) needs ≤2 extractors — if each pillar needs bespoke identity models, Path A balloons.
• A19 value vocabulary (strong/partial/no-content/needs-SME per id-71) fits producer-drafted client concepts — design slice before the {132.35} re-proof.

Open questions

• Whether client-facing system-concept round-trip evals run per-release or nightly (cost/latency call at bl-465 impl).