feat(okf): OKF-conformant hubs + freshness provenance

[Connorrmcd6]

Summary

Makes Surface hubs a superset of an Open Knowledge Format (OKF) concept, so every hub is a conformant OKF document any OKF consumer can read — while Surface adds the one thing OKF's spec explicitly omits: freshness. The positioning writes itself: Surface = OKF + the freshness OKF leaves out.

Changes Made

• OKF-conformant schema (surf-core/src/hub.rs): frontmatter is a superset of an OKF concept — type (defaulted to concept, so existing hubs are byte-unchanged and keep working), title/tags/timestamp, and any other key preserved verbatim in a flattened extra (OKF's "consumers MUST preserve unknown keys"). deny_unknown_fields relaxed on the frontmatter only; anchor items stay strict so per-anchor typos still fail closed.
• Freshness provenance + stable claim IDs (surf-cli/src/verify.rs): surf verify stamps a stable per-claim id (written once, never regenerated) plus verified_at/verified_commit — only when the hash actually changes, so a no-op re-verify stays byte-identical. The who is deliberately not stored (git blame on the hub records it), so no author emails land in tracked files. Additive id on the --format json Divergence (no report-version bump).
• OKF bundle layout (surf-core/src/config.rs, surf-cli/src/workspace.rs): a bundles glob governs a directory tree (<root>/**/*.md); reserved files (index.md/log.md) are classified and skipped, never blocking the gate.
• surf lint OKF advisories (surf-cli/src/lint.rs): warns (never blocks) on typo'd frontmatter keys — recovering the fail-closed signal the relaxed schema gave up — on missing headlines, and on dangling OKF cross-links (OKF tolerates broken links).
• Docs: new docs/guides/okf.md; OKF conformance statements in README.md, docs/index.md, docs/reference/configuration.md, and CHANGELOG.md.

Type

Feature

Scope boundary (deliberate)

Only concepts that describe code are fact-checked (Surface hashes an AST span). Anchor-less OKF concepts (a table's business meaning, an RFC) are valid, rendered, and ungoverned — they pass the gate untouched. Non-code-resource verifiers and cross-repo aggregation are left as seams for later, not built here.

Testing

• cargo test --all — all suites pass (new tests: extra-key round-trip, anchor-less pass-through, reserved-file no-block, unknown-claim-key still rejected, provenance-on-change-only, byte-identical re-verify, id stable across re-verify, bundle discovery, OKF cross-link lint, edit-distance).
• cargo clippy --all-targets -- -D warnings clean; cargo fmt --all clean.
• Dogfood: this change diverged the hubs describing check_workspace/hub_paths/etc.; prose re-read, updated, and re-verified — surf check is green.
• End-to-end OKF bundle demo: a bundle with a frontmatter-less index.md and an anchor-less concept passes check; a dangling cross-link warns without blocking.

🤖 Generated with Claude Code