Skip to content

Accountability infrastructure for autonomous engineering

DoneState documentation

Guides, concepts, complete references, security boundaries, and operating help.

Hosted liveSource

DoneState docs / Verification

Execution and proof are separate jobs

DoneState is allowed to execute an authorised objective. It is not allowed to declare its own result independently verified.

The verification flow

  1. 01

    Execution reaches a stable subject

    DoneState completes its bounded actions, validates the result, and records the exact base/head and publication evidence.
  2. 02

    DoneState seals a handoff

    create_verification_handoff binds the run, objective, execution snapshot, subject, acceptance criteria, verification requirements, action outcomes, and event-chain head.
  3. 03

    An independent verifier observes the subject

    OpsTruth or another pinned verifier inspects the evidence without becoming DoneState itself.
  4. 04

    The full v2 response is submitted

    New hosted objectives use submit_verifier_response, which validates the report and signed attestation together.
  5. 05

    Only a matching trusted result reaches VERIFIED

    Subject mismatch, incomplete evidence, an untrusted signer, replayed nonce, or an uncertain decision cannot be turned into terminal VERIFIED by DoneState.

Machine-checkable verification requirement types

path_exists
Require a repository path to exist in the observed subject.
path_absent
Require a repository path to be absent.
file_contains
Require a file to contain one or more expected values.
json_equals
Require a JSON Pointer location to equal an expected JSON value.
changed_files
Bound the observed changed-file set and allowed paths.
github_checks_pass
Require named GitHub checks to pass on the exact observed head.

Using OpsTruth

When the hosted service has a configured trusted OpsTruth verifier,request_opstruth_verification asks OpsTruth to re-observe one sealed run and returns the complete versioned verification response. DoneState does not sign that result on OpsTruth's behalf.

How to read outcomes

VERIFIED
A trusted independent response matched the sealed execution subject and satisfied the contract.
AWAITING_VERIFICATION
Execution is complete enough to seal, but terminal independent proof has not been accepted.
uncertain
The verifier could not support or contradict the claim strongly enough. Preserve the uncertainty; do not rewrite it as success.
failed / contradicted
Observed evidence does not support the requirement or subject. Investigate the exact evidence before running new work.

Continue

Authority & run states

Map verification decisions to DoneState lifecycle states.

MCP verification tools

Exact inputs for handoff, response submission, and OpsTruth requests.

Concepts

Why independent proof is structurally separate from execution.

Troubleshooting

What to do with uncertain, blocked, or ambiguous outcomes.