Frontmatter as a trust layer

Markdown is easy to read, but prose alone does not always reveal how a document should be treated. Is it implemented architecture or a proposal? Was it verified yesterday or merely edited yesterday? Does it replace an older record? Which evidence supports it?

YAML frontmatter gives those questions a compact, consistent answer before either a human or an agent reads the whole document.

---
record_type: architectural
status: current
confidence: high
updated: 2026-07-20
last_updated: 2026-07-20
sources:
  - Source/Example.cpp
  - Tests/ExampleTests.cpp
supersedes: []
---

Why it helps humans

Frontmatter makes important qualifications visible at the top of the note. A reader can quickly tell whether the document is current, speculative, historical, or awaiting verification. Sources offer a direct path back to the evidence, while supersession prevents two plausible-looking documents from silently competing.

Obsidian can expose these properties in its interface, but the metadata remains ordinary text. It can still be reviewed in VS Code, searched from a terminal, and versioned in Git.

Why it helps agents

Agents can use structured metadata before spending tokens on the full body:

• route a note according to its record class;
• avoid treating brainstorms as implemented facts;
• prioritize stale, low-confidence, or widely referenced records for verification;
• follow source paths directly into relevant code or evidence;
• recognize that a newer document supersedes an older one;
• distinguish a content edit from a fresh verification of the claims.

This turns the knowledge base from a pile of equally plausible Markdown files into a set of records with explicit trust signals.

Frontmatter does not make a claim true. It makes the claim’s intended status and evidence legible.

A useful core schema

record_type

Describes the responsibility of the document. Useful categories include:

Value	Use
factual	Current project state, dependencies, interfaces, and constraints.
architectural	Implemented structure, design landmarks, and technical reasoning.
decision	Durable choices, rationale, alternatives, and consequences.
generative	Ideas, proposals, explorations, and plans that may never become true.
operational	Active tasks and other short-lived execution state.
historical	Session summaries and snapshots of what happened at a point in time.

This is often the most valuable field because it stops a proposal from being mistaken for current reality.

status

Describes the record’s lifecycle. A small controlled vocabulary keeps it useful:

• current — intended to describe the present state;
• provisional — usable, but incomplete or awaiting stronger verification;
• stale — known to need review;
• superseded — replaced by a newer record;
• archived — retained for history rather than current guidance.

Operational plans may need a domain-specific state such as active, but new values should be introduced deliberately.

confidence

Use high, medium, or low to describe confidence in the note’s claims—not confidence in the quality of the implementation. Confidence is most useful when paired with sources and a verification date.

updated

The date the claims were last checked against their evidence. Use a stable format such as YYYY-MM-DD.

last_updated

The date the document content last changed. This may be newer than updated when wording or links change without re-verifying every factual claim.

Keeping both dates prevents a cosmetic edit from making old technical information appear freshly verified.

sources

The code, tests, documents, issues, commits, or explicit human decisions supporting the record. These should be useful pointers rather than an exhaustive bibliography.

supersedes

Links or paths to records replaced by this one. It makes changes in understanding explicit and preserves history without leaving agents to guess which account wins.

Optional categories

Add fields only when the workspace has a real workflow that uses them. Depending on the project, useful additions might include:

Field	Useful when
project	Notes can live outside their owning project or appear in aggregated views.
owners	A specific person or team maintains the record.
tags	A small, controlled vocabulary supports cross-project discovery.
applies_to	The guidance is limited to particular versions, platforms, tools, or environments.
related	Important relationships cannot be expressed clearly through links in the body.
review_after	A known release or date should trigger re-verification.
canonical	Several representations exist and readers need to know which one governs.
visibility	The same vault deliberately contains public, internal, or private material.

Avoid fields such as priority, progress, or category unless their allowed values and maintenance responsibility are clear. Free-form metadata tends to drift into near-duplicates that neither people nor automation can trust.

Where frontmatter is worth the cost

Not every Markdown file needs a governance header. Apply it to documents future agents may rely on as factual, architectural, or decision memory. It is also useful for generative notes when they could otherwise be mistaken for approved work.

A temporary scratch note does not need a full evidence model. A landmark that governs a fragile subsystem probably does.

Maintenance rules

• Update last_updated whenever the document changes materially.
• Change updated only after checking the claims against their sources.
• Mark unresolved conflicts instead of silently choosing one account.
• Use supersedes when a later record displaces an earlier one.
• Keep category values controlled and documented.
• Audit metadata as a prompt for review, not as proof that a record is wrong.

The best schema is the smallest one that helps a human or agent make a better decision.