Developers
Quickstart
Four steps from an unverified repository to a run that cannot close itself. Nothing here requires a deployment, an account or write credentials.
- Verify
- Classify
- Execute
- Attest
Before you start
What you need
A local Node.js toolchain and a repository you can read. The verifier runs read-only, so it needs no write credentials and performs no deployment, database or restart actions.
Exact command surfaces evolve with the repositories. Where this page and a repository’s README disagree, the repository is authoritative.
Steps
From unverified to attested
01
Verify something you already trust
Start with a repository whose state you believe you understand. The useful signal is the gap between what you assume is proven and what can actually be evidenced.
step 01$ cd your-repository$ npx opstruthinspecting repo, stack, tests, build, CI, secrets, config, routes02
Read the classification, not the score
Every check resolves to Verified, Risky or Unproven. Unproven is not a failure — it means no evidence was available, which is a different problem from evidence of a fault.
step 02VERIFIED build reproduces at commitRISKY declared route returns error statusUNPROVEN no deployment evidence available03
Put a run under durable control
Install DoneState and give it an outcome plus an authority envelope. The run records durable transitions and halts at AWAITING_VERIFICATION rather than declaring itself complete.
step 03$ npm install -g donestate$ donestate run --outcome ./outcome.md --envelope ./authority.jsonAWAITING_VERIFICATION04
Close the run with an attestation
Verification is what moves a run to VERIFIED. Feed the verifier's report back as the attestation, and confirm that nothing inside the execution path could have produced it.
step 04$ npx opstruth --report ./report.json$ donestate attest run/7c41 --report ./report.jsonVERIFIED
What you get
A report you can argue with
Rows, surfaces and classifications — not a confidence score.
| Check | Surface | State |
|---|---|---|
Build reproduces at commit Artefact matches source tree | build | verified |
Test suite executed Exit status recorded in CI evidence | tests | verified |
No credentials in tracked files Scan clean at this commit | secrets | verified |
Declared routes respond One route returns an error status | runtime | risky |
Deployed artefact matches commit No deployment evidence available | deployment | unproven |
Give agents authority. Keep the proof.
If the report surprises you, that is the point of running it.