Plumb

Plumb

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

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

Install

curl -fsSL https://plumb.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. The current release is 0.8.1 — Installing covers verifying the signature on what you downloaded, pinning a version or a channel, and removing it.

One line proves it

The only thing you write by hand is a citation on a test you were writing anyway:

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

In Java, the same thing:

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

The annotation says which requirement the test 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.

What counts as proven

A story is 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 — 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. Nothing can go stale.

Optionally, and off by default, Plumb will also break the behaviour a story's tests drove and report how many of those breakages the tests noticed — the only part of this that asks 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 method 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, and adopting it later costs nothing you did today: citations are the only thing you write by hand for Plumb, and goldspec neither replaces nor rewrites them.

Where to go next

• Getting started — configure, cite one test, run the board, and get from PASSED to PROVEN.
• What to expect — the board said something surprising and this is the page that explains it.
• The command line — every command, every flag.
• The tool and the method — why Plumb cannot hold the method, and what that means for you.
• Changelog — 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.