OKF Conformance

How this workspace maps onto OKF v0.2 — Google’s Open Knowledge Format — what conforms, and what is deliberately left outside.

Spec: GoogleCloudPlatform/knowledge-catalog → okf/SPEC.md, v0.2, Apache 2.0. Announced 12 June 2026. Related: KNOWLEDGE-GRAPH for the link/graph layer.

Why adopt it at all

OKF formalises the same raw → compiled → schema pattern this workspace already runs, and it cites Karpathy’s LLM-wiki pattern by name. The value here is not interoperability — this bundle has exactly one consumer. It is that a published spec supplies vocabulary we were improvising: a type field, an actor convention for authoring, and stale_after for expiry.

The bundle

/home/joe/workspace is the bundle. Its root index carries okf_version: "0.2". Conformance requires exactly three things (§11):

1. parseable YAML frontmatter on every non-reserved .md;
2. a non-empty type field;
3. index.md / log.md following their defined shapes.

Links are optional (§6), so [[wiki-links]] remain legal and the graph tooling is unaffected. Both link syntaxes are now parsed identically by scripts/wiki-graph.py, scripts/wiki-backlinks.py and scripts/wiki-lint.py.

Outside the bundle — deliberate carve-outs

These are excluded on purpose, and the linter skips rather than pretends:

• diary/, memory/ — append-only raw layers. Adding frontmatter would mean editing records that are immutable by convention.
• therapy/Session 2026-08-25.md, therapy/Session 2026-08-28.md — the two pre-OKF session notes, exempt by name, not by pattern. Every session note written from 2026-09-10 carries type: Session frontmatter at creation, so this gap closes forward rather than by rewriting history.
• AGENTS.md, SOUL.md, USER.md — the convention layer. Karpathy’s original architecture puts the schema file alongside the bundle; these are configuration, not knowledge concepts. They also load into an agent’s system prompt, where injected frontmatter would be noise.
• .hermes/, trashed/ — tooling state and cold storage.
• README.md in project folders — software project docs, not notes.

Type vocabulary

OKF registers no central type list, but a closed set makes drift visible. The linter rejects anything outside this set:

Type	Used for
Tracker	Living state, overwritten in place; rows deleted when done
Register	Lists that accrete: bills, people, subscriptions
Log	Append-only sequences of dated events
Report	Point-in-time analysis and snapshots of a period
Reference	Stable factual lookups (device maps, data inventories)
Research	Question-driven findings with a shelf life
Guide	How-to and explanatory documentation
Synthesis	Compiled knowledge distilled from raw sources
Index	Catalogs pointing at other notes
Note	Everything else, single-subject
Inbox	Untriaged capture
Open Questions	Unresolved threads awaiting evidence
Template	Note skeletons
Generated	Machine-written from a structured source; never edited by hand

Field conventions

• type — required, from the table above.
• title / description — one line each, propagated into the indexes.
• status — draft while a page is provisional; absent means stable.
• stale_after — an absolute instant after which the note should be re-verified. Set on fare snapshots, price research and device inventories. The linter reports anything past its date.
• sources — url + note pairs, for notes derived from a document or page. Attribution is keyed, not positional, because agents reorder lists.
• generated — by uses an actor prefix (human:joe, hermes/<model>) so machine-written text is never mistaken for Joe’s own. The therapy and compiled layers especially depend on this line.
• refresh — hourly / daily / weekly / monthly / on-write, on a page a scheduled script rewrites wholesale. It tells wiki-lint.py that this page’s mtime moves on its own, so a later mtime is not evidence that the folder’s index has gone stale. on-write is for a generator with no fixed cadence (a regenerator run after each import, say). Only that closed set counts (a typo fails loud rather than silently buying an exemption). The generator that owns the page must emit the field itself — frontmatter pasted onto a generated page is deleted by the next rebuild.

Set only when known. An absent generated block is honest; a guessed one is not.

Not adopted

• Full trust tiers (§5.3 machine-confirmed vs human-reviewed) — designed for multi-party bundles; overhead without a second party.
• Attested Computation (§10) — genuinely relevant to the cron-script layer, but v0.2 defers the receipt and verdict wire formats. Revisit at v1.
• Contradiction handling — OKF does not attempt it. Nothing here would have caught the ha-device-map.md 586-vs-1066 entity conflict; wiki-lint.py did. Format conformance is not a substitute for the compile step.

Enforcing it

scripts/wiki-lint.py checks all of the above — frontmatter presence, type vocabulary, reserved-file shape, log.md ordering, expired stale_after — and runs daily inside the wiki-graph-refresh cron. Silent when clean; exit 1 when drifted.