goldspec

goldspec

A specification a machine can check.

Most specifications cannot be wrong, because nothing reads them. Goldspec is a format that can be: process flows where every step is an act somebody performs, with the information each step takes and produces, and gates that refuse the shapes a reader cannot test.

Install

curl -fsSL https://gold.plumbspec.org/install.sh | sh

One file, no package index, no account. The current release is 0.3.0. Then, in a project with a goldspec.toml:

goldspec

It reads your chapters and reports what it cannot hold against them.

What it checks

The gates are the half with an invariant. They are not style preferences — each one refuses a shape that cannot be tested afterwards:

• Does a person do it? A node's text is the shortest description of what somebody does. A box stating something about the system is not a step, however true it is — it has no position in a sequence, so it cannot be ordered, chained or tested. This is the single most common defect in a corpus written before the question was asked.
• Prose is a detector. If the story and its requirements are complete, there is no prose left to write. A paragraph inside a node is a requirement that has not been written yet — the fix is to find it and give it an identifier, not to shorten the paragraph.
• A spec states what is. Not what happened, not why, not what was tried. History, argument, anecdote, a chapter describing its own size, and build status all belong somewhere else.
• Identifiers sort. Everything gets one, because the time a design session spends finding what is being discussed is enormous — and they are padded, so a plain sort puts ch-2 before ch-10.

What the gates cannot see is a reader's: altitude, duplication, and whether a claim belongs where it sits. Reviewing a chapter is the rest of it.

What it is for

A specification that can be checked is one an implementation can be measured against. That is the other half: plumb takes a story from a goldspec corpus, finds the tests citing it, and proves the story only if a citing test ran and reached the wired system.

Goldspec is useful on its own — a corpus that holds its own shape is worth having before anybody measures anything against it. Plumb is useful without goldspec too. Together they close the loop from the requirement to the thing that implements it and back.

Where to go next

• Getting started — write a first chapter and run the gates over it.
• Writing a process flow — the format, the node kinds, and the questions that settle most arguments.
• Reviewing a chapter — the judgements a reader has to make, which are the ones no gate can.
• A worked example — a real chapter, as source rather than as output.

Licence

Apache License 2.0. The full text ships in the artifact and with the source.