DoneState docs / Understand
Architecture and trust boundaries
DoneState separates intent, authority, execution, publication, and verification so a successful coding action is not mistaken for proof or merge authority.
System map
MCP client / CLI
│
▼
objective + acceptance criteria + authority
│
▼
DoneState durable control plane
│
├──► per-user execution credential vault
├──► repository selection / GitHub App policy
└──► per-run durable coordinator
│
▼
isolated implementation sandbox
│
validate exact result
│
▼
branch / pull request when authorised
│
▼
sealed verification handoff
│
▼
independent verifier (OpsTruth)
│
▼
VERIFIED / failed / uncertain evidenceHuman and agent workflow
Human or agent
│
│ desired outcome + acceptance criteria
▼
Objective admission
│
│ explicit consequence authority
▼
DoneState durable controller
│
├──► implementation harness
├──► deterministic validation
├──► optional branch / pull-request publication
└──► reconciliation + sealed exact subject
│
▼
independent verifier
│
VERIFIED / failed / uncertainHumans and agents use the same consequence model. A human can drive DoneState from a terminal, while a coding agent can use the non-interactive CLI or hosted MCP. Neither interface grants itself authority, and neither execution surface can verify its own result.
Troubleshooting decision flow
donestate status RUN_ID
│
├── BLOCKED_AUTHORITY → inspect authority; never widen silently
├── BLOCKED_CAPABILITY → restore capability; resume only if eligible
├── BLOCKED_SAFETY → inspect invariant or budget
├── FAILED_SAFE → inspect failed action and correct the cause
├── AMBIGUOUS_EFFECT → inspect provider state BEFORE retry
├── AWAITING_VERIFICATION → request or submit independent proof
└── VERIFIED → terminal proven outcomeWhat each layer owns
Client
Collects user intent and invokes public DoneState tools. The client is not the durable source of truth for an executing run.
Control plane
Owns run state, authority checks, effect intent, reconciliation, publication references, and verifier-response acceptance.
Execution sandbox
Performs bounded implementation and deterministic validation in isolation. It does not own merge authority or independent proof.
GitHub
Holds repository state, branches, pull requests, checks, installation scope, and the final human-owned merge decision.
Credential vault
Stores a user-funded OpenAI execution credential encrypted at rest and never returns the secret through status tools.
Independent verifier
Observes the sealed subject and returns evidence. DoneState validates the verifier identity and subject binding but cannot self-verify.
One hosted objective from request to proof
- 01
Admit
DoneState validates the objective, repository, base ref, acceptance criteria, budgets, and explicit consequence authority before work starts. - 02
Pin
The exact base commit is recorded so later work and verification have a stable subject. - 03
Execute
The isolated execution environment receives only the capabilities needed for the admitted work and records consequential action intent durably. - 04
Validate
The configured validation profile and changed-file budget are applied to the resulting workspace. - 05
Publish
If authorised, DoneState creates its branch and can open a pull request. It does not merge that pull request. - 06
Reconcile
Remote effects are reconciled against durable intent. Uncertain mutation outcomes are surfaced rather than blindly retried. - 07
Verify
A sealed handoff binds the exact base, head, criteria, action results, nonce, and event chain for independent observation.
Durable state ownership
Hosted objectives use a per-run durable coordinator. The coordinator owns the current run state, objective, encrypted run-scoped GitHub credential material, action records, publication references, verifier material, and hash-chained events.
User-funded execution credentials live separately in a per-user credential vault. Repository maintenance policy and selected-repository metadata live in the maintenance registry. Keeping these concerns separate prevents one object from becoming an unbounded authority store.
External effects and idempotency
Local reads and writes are different from remote consequences. Pushes, pull-request publication, and other external mutations are represented as explicit authorised actions. DoneState records intent before consequence and records settlement afterward.
If a timeout or interruption makes the outcome uncertain, the run can enterAMBIGUOUS_EFFECT rather than issuing the same mutation again without evidence.