Plumb

Proof that a story is done — verified, not asserted.

Bring your own spec, or write one with goldspec.

One line proves it.

Python

@pytest.mark.proves("ORD-1", depth="wiring")
def test_an_order_gets_a_queue():
    assert run("A-1")["queue"] == "standard"

Java

@Test
@Proves(value = "ORD-1", depth = "wiring")
void anOrderGetsAQueue() {
    assertEquals("standard", api.handle("A-1").queue());
}

That test is one you were writing anyway. The highlighted line says which requirement it is about. Plumb runs the suite, watches what actually executed, and derives whether ORD-1 is proven — there is no status for anyone to type.

This is alpha software. It is pre-1.0 and published for trusted testers. Interfaces, the manifest format and the command line may all change between versions without notice, and there is no support commitment. Pin a version if you depend on one.

What it does

A green test suite tells you your tests pass. It does not tell you that the requirement you wrote down is actually implemented, or that the code you tested is reachable from the running system. Plumb checks the link that everyone assumes and nobody verifies.

A story counts as proven only when two things hold:

A test citing it ran and passed — not skipped, not aborted, in this run.
That test's execution reached the wired system — it went through a production entry point you declared, rather than calling an isolated function.

The second check is the one that finds things. Code no entry point reaches cannot prove a story however green its tests are, so a passing test over orphaned code stops reading as done. Status is derived from each run and never stored, so a proof that later breaks un-proves its story and nothing can go stale.

Optionally, and off by default, Plumb will also mutate the code a story's tests drove and report how many of those mutants the tests noticed — which is the only thing here that looks at whether your tests check anything, rather than merely running it.

Writing the thing that gets proven

Plumb never asks you for a spec. plumb init writes none, there is no plumb spec command, and a project with nothing but citations in its test suite gets a complete, correct board. How you capture requirements — or whether you write them down at all — stays yours, and nothing here will ever check.

If you would rather not start from a blank page, the methodology is a separate product and it is the one we recommend: goldspec — process flows with IPO, data definitions, stories, decisions and unknowns, and the gates that keep them honest. Installed separately, run as goldspec, and what Plumb uses for its own specification.

Recommended is not required, and it is not a one-way door. Its conventions are settings rather than a format — a project whose ids read REQ or sh, whose flows live somewhere else, says so in a goldspec.toml and is checked just the same. Adopting it later costs nothing you did today, because citations are the only thing you write by hand for Plumb and goldspec neither replaces nor rewrites them.

Install

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

One file, both language adapters inside it. No package index, no account, and nothing added to your project's dependencies. Then, in a project with a plumb.toml:

plumb board

Python and Java are supported today, by the same command and the same config file. Installing Plumb covers what you need, how to verify the signature on what you downloaded, how to pin a version, and how to remove it. The changelog says what each release changed, and whether taking it asks anything of you.

Licence

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