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

In the world of coding, agents are increasingly writing persistent knowledge in markdown format, such as CLAUDE.md files, memory directories, and runbooks. While these agents can be helpful, they can also produce incorrect information. The main concern is that this information may not be verified or updated over time, leading to a phenomenon known as "knowledge rot" where incorrect data is treated as factual and built upon by subsequent sessions.

A tempting fix to address this issue is to add a trust score to the markdown files, but this approach has several problems. First, the trust score is still an opinion and does not indicate who assigned it. Second, it is not portable, meaning that a score assigned by one person may not be the same as another person's score. Lastly, it rots silently, meaning that if the content changes, the score remains unchanged.

Instead of adding a trust score, the Open Knowledge Format (OKF) takes a different approach. The OKF is an open, vendor-neutral specification that allows for the creation of a directory of markdown concepts, versioned next to the code it describes. The key to the OKF is that the frontmatter of the markdown file only records observable events, such as who wrote the content and when it was last modified.

For example, the frontmatter might include fields such as "generated" which shows who produced the current content and when it was last meaningfully changed, "verified" which shows who confirmed the content against its sources and when, and "stale_after" which specifies the date after which the content is considered stale.

By deriving trust tiers through these facts, rather than storing them, the trust model is more robust and flexible. The trust tier can be recomputed at any time, taking into account the current date and the latest frontmatter information. This approach ensures that the trust tier is always up-to-date and reflects the current state of the content.

To implement this trust model, a repository can be maintained with the necessary skills and validation tools. For example, the "okf-skills" repository contains tools for producing, maintaining, validating, and visualizing bundles of knowledge created with Claude Code. A GitHub Action can gate these bundles in CI, ensuring that they meet certain standards. The validator enforces the frontmatter families and warns on potential errors, such as typos in actor names.

The benefit of this trust model extends beyond just making agent-written knowledge more auditable. It ensures that any team reading the knowledge can be confident in its accuracy and relevance. By asking agents to leave evidence of who wrote and verified the content, as well as until when it holds, the trust model promotes transparency and accountability in the knowledge creation process.