chore(knowledge): make the knowledge bundle actually OKF v0.2 conformant

[chaliy]

What changed

The specs/ → knowledge/ migration (#2202) adopted OKF in name only. This makes the bundle conform to OKF v0.2 and adds a gate so it stays that way.

Four spec violations, every one of which made the bundle non-conformant:

Violation	Spec	Fix
No type on any concept — the only always-required key, so zero documents conformed	§4.1, §11	type on all 31 concepts
summary: — not an OKF field	§4.1	renamed to description:
Both index.md files carried title/summary/tags frontmatter	§8 — index files carry no frontmatter; root may carry only okf_version	stripped; root declares okf_version: "0.2"
Index bodies were prose + a table, not directory listings	§8 — * [Title](url) - description sections	reshaped

Alongside that:

• Maintenance rules moved out of index.md (prose does not belong in a reserved index) into knowledge/knowledge-contract.md, which also records the OKF rules and the type vocabulary. AGENTS.md points there.
• knowledge/status/builtins.json was an unreferenced blob; it is now described by a Generated Inventory concept with resource: pointing at it.
• Added knowledge/log.md (§9 date-grouped history).

Enforcement is two checks that cover different things:

• okf-lint 0.1.1 (crates.io, pinned) — upstream spec gate. It enforces the reserved index.md/log.md structures and cites the spec section in every diagnostic.
• scripts/check_okf.py — no dependencies, covers the bundle-local conventions okf-lint does not: description (not summary), and every concept listed in its directory's index.md.

Both run in the CI lint job and in just check-okf (wired into just check).

Why

An OKF bundle that no OKF consumer would accept is worse than not claiming the format: agents and tooling route on type, and every document was missing it. Nothing validated the bundle, so the defects shipped silently.

Before / After

Conformance, checked with the upstream linter:

# before
$ okf-lint knowledge --max-line-length 10000
index.md:1: root index.md frontmatter may only contain 'okf_version' (spec: …#6-index-files)
architecture.md:1: frontmatter missing required non-empty 'type' field (spec: …#4.1-frontmatter)
… 31 concepts, all missing 'type'
exit=1

# after
$ just check-okf
knowledge: OKF v0.2 conformant (31 concepts, 2 index files, 1 log file)
okf-lint 0.1.1: knowledge conforms to OKF v0.2
exit=0

Four OKF implementations were built and run against the bundle and against a fixture per regression class, to pick the gate. fail = regression caught, pass = slipped through:

Regression	okf	okftool	okf-lint	check_okf.py
Concept missing type	fail	fail	fail	fail
summary instead of description	pass	pass	pass	fail
Frontmatter on index.md	pass	pass	fail	fail
Concept absent from index.md	pass	pass	pass	fail
log.md heading not YYYY-MM-DD	pass	pass	fail	fail

okf-lint is the strongest available and is adopted. It does not subsume the local check: the two rows it lets through are bundle-local conventions, and the first is exactly the defect #2202 shipped. The rejected alternatives are recorded with rationale in knowledge/knowledge-contract.md — okftool treats everything but type as advisory, okf implements OKF v0.1 (wrong revision for this bundle), and okflint validates against a hand-authored manifest rather than the spec and needs Python 3.12+ against this repo's 3.9 floor.

No runtime behavior changes: no .rs files are touched. just pre-pr green, including cargo vet.

Risk

• Low
• Documentation and CI only — no library, CLI, or binding code changes.
• New CI dependency: cargo install okf-lint --version 0.1.1 --locked in the lint job. It is a lint tool, not a workspace dependency, so deny.toml/cargo vet are unaffected. Failure mode is a red lint job; removing the two lines reverts it. The version is pinned in both ci.yml and the justfile and must be bumped together.
• --max-line-length 10000 effectively disables okf-lint's line-length rule; knowledge docs wrap prose at author discretion, and the rule otherwise fires 183 times.

Checklist

• Tests added or updated — scripts/tests/test_check_okf.py, one case per rejection class plus a positive control, as unittest.TestCase so unittest discover actually executes them
• Backward compatibility considered — internal knowledge/tooling only; no public surface

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	bashkit	890bc7b	Commit Preview URL Branch Preview URL	Jul 26 2026, 12:40 AM