goldspec

Is what we wrote down still coherent?

New here? Write your first chapter — one worked process, part by part, in about twenty minutes.

A specification nothing checks rots, and the rot is silent.

$ goldspec spec
3 fault(s) in spec
  chapter-04-mutation.md: ch4-7 is declared twice
  chapter-02-manifest.md: ch2-9 is declared and never placed in a flow
  chapter-06-support.md: ch6-U2 is in the diagram and not in Open unknowns

Every check is a pure source scan — no build, no network, nothing rendered — which is what makes it cheap enough to actually run, and the only reason a gate ever is.

This is alpha software, pre-1.0 and published for trusted testers. It is versioned independently of Plumb: this version number says nothing about that one. Interfaces may change between versions without notice, and there is no support commitment.

Install

Two forms ship, and which one you want depends on how you intend to run the gates. Both are listed in the same SHA256SUMS and covered by the same signature.

The command — to check a spec by hand

curl -fsSL https://plumbspec.org/gold/install.sh | sh
goldspec <spec-directory>      # defaults to ./spec
goldspec spec --sibling ../other/spec   # when the corpus spans repositories

Use this while you are authoring, or to check a spec before anything is wired up. It verifies the checksum and the signature as it installs, and it needs no project of yours to be a Python one.

The library — to run the gates as tests in your own suite

pip install https://plumbspec.org/gold/latest/goldspec-0.1.1-py3-none-any.whl

This is the form the method is actually delivered in. The gates are tests, so that Plumb observes a test that ran and passed exactly as it observes any other and never learns it was a methodology gate — and a test has to import. It is also the only form that takes conventions other than ours: the command builds them from its own defaults, so a project whose ids are not ch* reaches the gate through a test.

from goldspec.specgate import Conventions, check_spec_directory

def test_the_spec_holds_together():
    report = check_spec_directory(
        SPEC, Conventions(namespace="app", flow_dir="diagrams"), cited_from=REPO)
    assert report.problems == []

To verify the wheel before installing it, fetch it beside SHA256SUMS and SHA256SUMS.asc from the same version directory and check them as you would the command — the library is not the one file you have to trust unchecked.

An unqualified install takes stable — what we run, and what a defect report is taken against. GOLDSPEC_VERSION=edge takes the candidate channel instead, and a version number pins that exact cut. Add GOLDSPEC_REQUIRE_SIGNATURE=1 to refuse the install unless the signature verifies.

Nothing is written into your project. goldspec holds no configuration, has no init, and reads a spec directory you wrote — so there is nothing to undo if you stop using it.

What it checks

• every subject declared once and once only;
• every subject placed in its process flow, so nothing is written down and left out of the picture;
• every open question tracked in both of its homes — the diagram and the list — because one is where it is noticed and the other is where it is answered;
• every flow able to render;
• no citation naming a subject the declared set does not define.

This is not Plumb, and Plumb does not need it

Plumb observes a test run and derives whether a requirement is proven. It has no opinion about how you plan, what you call a requirement, or whether you keep a specification at all — a project with nothing but citations in its test suite gets a complete, correct board. It cannot read a spec, and that is deliberate: to check one, a tool must first decide what a story is and where it lives, which is choosing your method for you.

goldspec is that method, offered separately so that adopting it is a choice you make rather than a condition of using the tool. The two answer different questions and neither is a tier of the other. Nothing under Plumb's src/ may import this package, and a test in its suite fails the build if one ever does.

The conventions it presumes

A subject is declared by its row in a chapter's trace table — the id and what it claims, in one row — so a spec is markdown a person reads rather than modules a runner has to collect. That is what makes it sayable in a project with no Python in it. Process flows with IPO, data definitions, decisions and open unknowns are the rest of the shape.

Adopt these and the checks are yours, not something imposed. Adopt Plumb alone and nothing will ever ask you for any of it.