Proof-Driven Development for Go.
ProofSteer checks decision rules in production Go code, runs tests for the surrounding behavior, and writes a receipt you can bring to code review.
Start with one decision in an existing Go project. The core workflow works without an LLM account.
View live report examples · Try the login example · Use it in your project · Download pdd
AI agents can write code quickly. Human review can become the bottleneck when someone has to trace each branch of an authorization or payment rule and check it against the intended behavior. Passing tests confirm the cases they exercise.
Start by describing the rule in plain language. An agent can draft a Go contract, and a human reviewer approves the contract and its assumptions. After implementation, pdd runs Gobra to verify that the Go function satisfies the contract for every input it covers.
Consider a withdrawal rule with a balance of 100. Two authentication states, two lock states, and four withdrawal amounts (0, 1, 100, and 101) give 16 cases.
| Review task | Manual code review | Proof-driven review |
|---|---|---|
| Is this the intended rule, and are its assumptions sound? | Reviewer checks the specification | Reviewer checks the specification |
| Does the Go function make the right decision for these 16 inputs? | Reviewer traces the code | Gobra checks the contract |
| Do HTTP handling and the browser flow behave as expected? | Reviewer checks test coverage and results | Reviewer checks test coverage and results |
Suppose the requirement is allow a login exactly when the account exists, the password matches, and the account is unlocked. The specification lives beside the production code in a Go comment that Gobra reads.
// @ ensures allowed == (accountExists && passwordMatches && !locked)
func DecideLogin(accountExists, passwordMatches, locked bool) (allowed bool) {
return accountExists && passwordMatches && !locked
}An implementation that always returns false satisfies a rejection-only rule. It violates this contract because valid logins must succeed. The demo asks Gobra to check the real function and then reject three deliberate changes in scratch copies: ignore a bad password, ignore a locked account, and deny everyone. It also runs a named Go test for the boundary cases. The proof starts with the three booleans; the accuracy of account lookup and password checking remains a caller assumption. Production function · Login plan
Use Go 1.20 or newer and Docker on a 64-bit host. Put the Go install directory on your PATH, or use the checksummed binaries. To use a local Gobra JAR, see troubleshooting.
go install github.com/cruskell/proofsteer-go/cmd/pdd@v0.4.0
pdd demopdd demo writes the bundled login example into a new pdd-demo directory,
imports its demonstration approval, and runs the real Gobra and Go checks.
Docker pulls the pinned Gobra image on the first run. The command prints the
HTML report and receipt paths. Choose another empty name with --out DIR.
The report shows the same two requirement results that pdd prove prints.
login-decision: proved (formal)
login-boundary: evidenced (empirical)
Open the report path to see the two results, three rejected mutations, and links
to the saved logs. Explore the source and review with pdd --cwd pdd-demo plan.
After edits, rerun pdd --cwd pdd-demo prove and regenerate the HTML with
pdd --cwd pdd-demo report --out .pdd/results/demo.html.
Pick a production function that makes an important decision. For a runnable walkthrough in a separate Go module, see prove one function. Keep the rule in the Go core and use named Go tests where the application connects it to HTTP, storage, or external libraries.
- Run
pdd initin your repository. Add// @ ensurescontracts to the production.gofiles and fill in.pdd/plan.jsonwith the rule, checks, trust assumptions, and a deliberate negative mutation for each formal clause. Plan format - Run
pdd lintandpdd plan. Usepdd plan --diffwhen revisiting an approved contract. Record which guarantees and assumptions a reviewer accepts withpdd approve --reviewer "$REVIEWER" --accept-tcb "$TRUST_IDS" --expect-digest "$REVIEWED_DIGEST", substituting your reviewer, comma-separated trust IDs, and the digest from the plan they inspected. Signed reviews - Run
pdd proveand attach the receipt to the change. In CI, import the saved approval before running the same checks. Use named plans to adopt the workflow one component at a time. CI adoption · Named plans
If you already work with a coding agent, pdd draft can turn a request into an editable plan and decision cards using Codex or an external JSON worker. Two separate advisory reviews help check the intent and guarantees before human approval. After approval, pdd build can propose repairs in a scratch copy, run the approved checks, and request an advisory gap review. pdd pr prepares a PR description from current evidence. Agent workflow
| Example | What to look at |
|---|---|
| HTTP wallet | A real HTTP handler calls a proved withdrawal rule. Go tests exercise the HTTP boundary and concurrent withdrawals. The optional browser check submits an overdraft and confirms the balance remains available. |
| Multi-package authorization | A handler calls local policy methods. PDD checks the dependency package before the caller. |
| Slice validation | A production loop proves a property over every element using permissions, a quantified contract, and loop invariants. |
- Formal proofs cover stated contracts. Gobra checks supported Go functions and methods, including supported calls across packages in one module. External and standard-library imports in proof packages remain outside the supported scope. Supported proof inputs
- Go and browser tests provide evidence for the cases they run. The receipt labels them separately from proofs. Each planned negative mutation must fail on the intended postcondition. A missing test, tool failure, or inconclusive mutation fails verification. Design
- Receipts tie the result to the reviewed change. Machine-readable JSON and Markdown include the plan and source digests, commands, outcomes, trust assumptions, and links or references to saved logs.
statusrejects stale evidence. Use Ed25519 approvals with a trusted policy when CI needs to verify reviewer authority. JSON protocol · Signed reviews
ProofSteer is an independent implementation of ideas from the Proof-Driven Development Kit research prototype. Its Go verifier is Gobra. Original PDD Kit · Feature comparison and limits
go test ./...
go test -race ./...
go vet ./...
PDD_INTEGRATION=1 go test ./internal/pdd -run 'TestGobra.*Integration' -v -count=1The Check workflow runs race tests across Linux, macOS, and Windows and runs the Gobra integrations on Linux. Check workflow · Build and distribution · Troubleshooting · MIT license