A spec that cannot lie

August 6, 2026

anchor was specified before it was written. The document said what the tool would do, what it would refuse to do, and which sections had to exist before there could be a first release.

A document like that has one failure mode, and it is not being wrong at the start. It is being right at the start and drifting afterwards, one commit at a time, until it describes a program nobody has.

How it drifts

The specification of the parser underneath anchor once claimed about a dozen constructs that did not exist. Nothing dishonest happened. The document was written first, its own marker scheme said that an unmarked entry was fully supported, and entries went in unmarked because at the time of writing they were the plan. Reading it a month later, it described a parser that had never been built.

anchor's own specification did the same thing in miniature, repeatedly:

It described head tags as a list of functions when they were a fixed block of markup.
It listed a duplicate-slug condition that could not occur, because a URL is a directory's path and two directories cannot share one.
It named a :description: attribute that nothing read.
It opened by saying that nothing in it was implemented yet, months after everything in it was.

Each of those was true when written.

Making the claim checkable

The line that mattered most was this one, near the top of the specification:

This file restricts itself to the AsciiDoc subset cl-adoc parses. anchor must be able to render its own specification.

That is a good claim precisely because it can be tested. So it is tested. The test suite renders the specification, the README and the changelog, and fails if any block delimiter survives into the output — because a delimiter in the output is the signature of a construct the parser did not recognise, whatever that construct turns out to be.

It caught something immediately. The claim had been verified by checking description lists and nothing else, and literal blocks written .... had been rendering as paragraphs with their delimiters showing the whole time. Three of them in the specification and four in the README.

Note

The fix was to use the delimiter that already existed rather than to add one to the parser. A tool that grows a construct every time a document wants one is not finite for very long.

The freeze

The specification defines 1.0 as every section it marks v1, and says that when the last of them ships the project is finished: bug fixes and whatever it takes to track the parser underneath, and nothing else.

That was written down rather than intended privately for the same reason as the rendering claim. An intention cannot be checked. A sentence in a versioned document can.