DoneState docs / Objectives
Describe outcomes, not vague permission
A DoneState objective binds a repository subject, a concrete goal, acceptance criteria, consequence authority, validation, publication mode, verifier requirements, and execution budgets.
What makes a good objective
- 01
Name one repository outcome
Prefer a result that can be judged from code, checks, or another explicit observable instead of an open-ended instruction to improve the project. - 02
Write observable acceptance criteria
Each criterion should describe something a reviewer or verifier can inspect without trusting DoneState's prose summary. - 03
Grant only needed consequence classes
If the objective does not need a push, do not grant push. If it does not need secrets, do not grant secret_access. - 04
Bound time and change size
Use maxDurationMs and maxChangedFiles as objective-specific safety budgets, not merely performance knobs. - 05
Choose how the result may leave the workspace
Use branch or pull_request publication explicitly. A pull request still leaves merge authority with the repository owner.
Hosted objective shape
Illustrative create_objective input
{
"repository": "owner/repository",
"baseRef": "main",
"goal": "Add validation for malformed configuration.",
"acceptanceCriteria": [
"Malformed configuration is rejected.",
"Existing valid configuration remains accepted.",
"Required CI checks pass on the exact PR head."
],
"authorities": ["local_read", "local_write", "test", "commit", "push", "open_pr"],
"publication": "pull_request",
"validationProfile": "auto",
"trustedVerifierFingerprints": [],
"verificationRequirements": [],
"maxChangedFiles": 25,
"maxDurationMs": 1800000,
"autoStart": true
}Publication and validation
- pull_request
- Prepare the remote result for normal GitHub review. This is the default hosted publication mode.
- branch
- Publish the authorised branch without opening a pull request.
- validationProfile: auto
- Let DoneState select from its supported deterministic repository validation profiles.
- node | python | rust | go
- Request a supported language-specific validation profile explicitly.
- none
- Skip the built-in validation profile. This does not make an unverified run independently proven.
Hosted input limits that shape an objective
- Goal
- 1 to 20,000 characters.
- Acceptance criteria
- 1 to 20 entries; each up to 2,000 characters.
- Verifier fingerprints
- Up to 20 pinned SHA-256 fingerprints.
- Verification requirements
- Up to 100 machine-checkable requirements.
- Changed-file budget
- 1 to 500 files; default 100.
- Duration budget
- 60 seconds to 2 hours; default 30 minutes.
Objective lifecycle
Keep the returned runId. It is the durable handle used bystart_objective, get_objective,cancel_objective, delete_objective, verification handoff, and OpsTruth verification.