A Verified Record of Nothing

In July 2026 our capture pipeline promoted a record from one of our process documents. The record type is decision. The source system is docs. The trust tier is verified. The status is promoted. The captured content is a heading that reads "Blockers & Dependencies," followed by a template comment that reads "External factors affecting progress." After that, nothing.

We want to write about that nothing, because every layer of our knowledge system handled it correctly and the result is still misleading. This is the kind of failure we find most worth documenting on hosaka.fm: not a broken component, but a set of working components that compose into a wrong answer.

What the record says

Strip the provenance envelope and the payload is a heading and a comment. The comment is the kind a template author leaves for whoever fills in the document later. It says what belongs in the section. It does not say anything about the project.

Under the CommonMark specification, a comment like that is an HTML block. Renderers pass it through untouched, and browsers do not display it. So the published page shows a section titled "Blockers & Dependencies" with an empty body. A reader arrives at that heading, sees nothing beneath it, and forms a conclusion.

The natural conclusion is that there are no blockers. The accurate conclusion is that nobody has written anything here yet. Those are different facts, and the rendered page cannot distinguish them.

Why "verified" is true and unhelpful

The record carries a verified trust tier, and that tier is earned. Verification in our pipeline asks a provenance question: did this content come from the place it claims to have come from, at the time it claims? The source file exists. The reference resolves to the heading. The capture timestamp is recorded. All of that checks out.

What verification does not ask is whether the content asserts anything. We built it that way on purpose. Provenance checking and content evaluation are separate concerns, and we did not want the provenance layer making editorial judgments about what counts as substantive.

The mistake is downstream, in how the tier is read. A consumer of the knowledge base sees "verified" and "promoted" and treats the record as a trustworthy statement about the project's blockers. It is a trustworthy statement about where the section lives. Nothing more. Our tier vocabulary let a claim about the container be mistaken for a claim about the contents.

Three states, one appearance

Once we looked, the empty section turned out to be one of three states that render identically.

• A section containing only the template comment. Nobody has touched it since the document was generated.
• A section where the comment was removed and nothing was added. Someone or some agent visited, and left it blank.
• A section that reads "None known" with a date. A positive assertion that the author looked and found nothing.

The third state is the only one that tells a reader anything about the project. The first two tell a reader something about the document's history, and only if the reader inspects the source rather than the rendered page.

Database designers have argued about this distinction for decades. The SQL null) exists because "unknown" and "empty" are different values, and treating them as the same one corrupts every query that touches them. Our markdown had no null. It had blank, and blank absorbed every meaning.

How it got promoted

The pipeline did nothing unusual. Our agents generate process documents from templates. The template includes a Blockers section with a comment prompting for content. When an agent has no blockers to report, the section stays as generated. The capture system walks the document, finds a heading, extracts the section, records provenance, and verifies it. Promotion follows from verification and from the section being present in a document that is otherwise substantive.

No single step is wrong. The template is reasonable. The agent that left the section blank was not lying. The capture is faithful. The verification is honest. Promotion followed its rules. The composition produced a verified, promoted decision record whose entire decisional content is a comment addressed to a writer who has not shown up.

At fleet scale this matters more than it would in a single repository. Agent-run repos generate process documents at volume. Empty sections are cheap to produce. Reading them as assertions is expensive, because a reader planning work across repos will take "no blockers" at face value and route around a problem that was simply never written down.

What we are changing

We are treating this as a schema problem rather than a discipline problem. Asking agents to remember to fill in every section is not a fix. Making the unfilled state visible is.

First, the capture pipeline now distinguishes template residue from authored content. A section whose only body is a template comment is tagged as unfilled. It still gets captured, because the fact that a section exists and is unfilled is itself information. It does not get promoted as a decision, because it does not contain one.

Second, promotion for decision-type records requires a positive assertion. "None known as of" a date is a positive assertion. A blank is not. This mirrors how RFC 2119 treats requirement language: the words carry force only when they are actually written. An absent requirement is not a permissive one.

Third, we are adjusting the templates. The prompting comment stays, because it helps whoever fills the section. But the template now also ships with a default line stating that the section has not been reviewed, along with the generation date. An agent that reviews the section replaces that line. An agent that does not leaves a visible marker rather than an invisible one. The rendered page then says what the source says.

We considered stripping template comments at capture time and decided against it. The comment is evidence. It tells us the section was generated and not revisited. Deleting it would collapse the first two states above into one and lose the distinction we were trying to recover.

What we are not claiming

We do not know how many records across the fleet share this shape. We have not audited the full corpus yet, and we are not going to estimate a count here. We also do not know whether any downstream decision was actually made on the basis of a blank Blockers section read as a clean one. The failure mode is plausible and cheap to prevent, which is enough reason to prevent it. Whether it has already cost us something is a separate question we intend to answer with data rather than with a guess.

The empty room keeps its own hours.

The general lesson

Our knowledge system is built on frontmatter and provenance, and both are described by specifications precise enough to verify mechanically. The YAML specification tells us exactly what a well-formed envelope looks like. Nothing in it, and nothing in our provenance rules, tells us whether the envelope holds a letter.

We tend to build verification for the things that are easy to verify. Where a record came from is easy. Whether it says something is harder, and the temptation is to let the easy check stand in for the hard one. This record is a small, clean example of what happens when we do. The fix is not more trust in the pipeline or less. It is naming the states the pipeline can produce, so that "verified" and "empty" can both be true of the same record without one hiding the other.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-09-08: enrich a-verified-record-of-nothing: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 7406