Don't store trust, derive it: a trust model for agent-written docs

A developer proposed a trust model for agent-written documentation that derives trust from observable events rather than storing it. The Open Knowledge Format (OKF), now at v0.2, uses frontmatter to record who generated and verified content, with consumers applying four rules at read time to determine trust. This approach avoids stale stored scores and supports the common case of agent generation with human verification.

Your coding agent writes persistent knowledge now. CLAUDE.md files, memory directories, runbooks, "what I learned about this codebase" notes. If you use Claude Code, Cursor, or Codex daily, a growing share of the markdown in your repos was written by something that is not you. The dangerous part is not that agents write wrong things. Humans do too. The dangerous part is that six weeks later, nothing in the file answers three basic questions: When the answers are missing, an agent that reads its own unverified guess treats it as ground truth and builds on top of it. The next session inherits the error with more confidence than the first one had. That is knowledge rot with a feedback loop. First instinct: add a field. trusted: true confidence: 0.87 A stored trust score has three problems: It's a cache without an invalidation strategy. Same bug, different costume. The Open Knowledge Format https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing OKF: an open, vendor-neutral spec announced by Google Cloud in June 2026, plain markdown + YAML frontmatter, no runtime, no SDK takes the other route. I covered the format itself in a previous post https://dev.to/scaccogatto/okf-for-claude-code-structured-portable-memory-your-agent-and-team-can-read-4ocn : knowledge as a directory of markdown concepts, versioned next to the code it describes. Since then the spec moved to v0.2, and v0.2 is about exactly this problem. Frontmatter stores only observable events . Every consumer derives the judgment at read time. --- type: Service title: "Auth API" description: "Issues and verifies short-lived access tokens." status: stable generated: { by: doc agent/1.0, at: 2026-06-14T10:00:00Z } verified: { by: human:dana, at: 2026-06-20T09:00:00Z } stale after: 2026-09-23 sources: - id: auth-readme resource: https://github.com/acme/auth readme author: team:auth last modified: 2026-06-01 --- Everything here is a fact you could check: | Field | The fact it records | |---|---| generated: {by, at} | Who produced the current content, and when it last meaningfully changed. | verified: {by, at} | Who confirmed it against its sources, and when. A list: a human sign-off plus a nightly process are independent events. | status , stale after | Lifecycle: draft / stable / deprecated , and an absolute date after which the content is stale. | sources | What it derives from, with per-source credibility signals author , last modified , usage count . | The load-bearing detail is the actor convention : human:dana for people, process:finance-nightly for automation, doc agent/1.0 for agents and tools. The prefix is the machine-parseable part. Who wrote a concept and who checked it are deliberately separate fields, because the writer need not be the checker: an agent generating and a human confirming is the normal case, not the exception. The whole trust model is four rules a consumer applies at read time: verified key ⇒ human: actors only ⇒ human: verifier ⇒ today = stale after ⇒ That's it. No score, no registry, nothing to keep in sync. And because generated.at and the latest verified .at are both plain timestamps, a consumer can also see the case that stored scores hide: content that changed after its last verification. The check is still a fact; it just visibly no longer covers the current text. Deriving instead of storing is not a new idea. Git does not store "this branch is merged": it derives it from the commit graph, so it can never be stale. A stored trust tier is a stored opinion, and it goes stale the moment anything around it moves. A derived tier is recomputed against today's date and the current frontmatter on every read. One failure mode is worth automating away: humans:dana a typo is a non- human: actor, so a real human review silently downgrades to machine-confirmed. It's the one typo that changes a trust tier without breaking anything visibly, which is exactly the kind of bug that deserves a linter, not a code review. We maintain okf-skills https://github.com/scaccogatto/okf-skills , the Claude Code-native OKF toolchain: skills to produce, maintain, validate, and visualize bundles, plus a GitHub Action to gate them in CI with no agent at all. The graph renderer computes the trust tier and staleness badges at render time and stores neither. The validator enforces the frontmatter families and warns on actor near-misses like the humans: typo above. The repo also documents itself in OKF, so you can browse a real bundle with derived trust signals as a live interactive graph https://scaccogatto.github.io/okf-skills/self.html : architecture, decisions, and the update log, each node showing who generated it and what tier that earns. One thing we deliberately don't claim: that bundles make agents cheaper. We benchmarked a bundle's effect on agent answers early on +8 points of claim coverage on "why" questions, no token savings and then deleted the benchmark from the repo, because it measured an adoption pitch, not the standard. The trust model is the part we'd defend on its own: it makes agent-written knowledge auditable , and that property doesn't depend on a benchmark. as a Claude Code plugin /plugin marketplace add scaccogatto/okf-skills /plugin install okf@scaccogatto as agent skills Claude Code, Cursor, Codex, 20+ agents npx skills add scaccogatto/okf-skills validate any bundle, zero config uv run skills/validate/scripts/okf validate.py .okf --strict Then ask your agent to "document the auth service in OKF", and check the frontmatter it writes. If your agents write knowledge your team reads, don't ask them to be right. Ask them to leave evidence: who wrote it, who checked it, until when it holds. Trust is not a field. It's a query.