DoneState

View saved version →

---
name: maintain-repository
description: Use when a user wants DoneState to select one GitHub repository for recurring read-only maintenance discovery or opt-in PR-only repairs.
---

# Maintain a selected repository

Start with `get_github_app_status`. If the private DoneState GitHub App is not configured, call `create_github_app_setup` only for the Proof & State platform owner, provide its single-use link, and wait. After creation, the owner installs the App on selected repositories only.

Use `select_maintenance_repository` for one exact `owner/name`. Explain the policy as one boundary:

- `observe` records bounded findings and never repairs;
- `pr_only` permits a repair branch and pull request but never approval or merge;
- scheduling requires an installed GitHub App;
- automatic repair also requires scheduling, `pr_only`, and at least one exact required CI check name;
- only open issues explicitly labeled `donestate:repair` are repair-eligible;
- failing workflow runs are evidence only.

Do not infer selection from repository visibility, OAuth access, organization membership, or a request to inspect. Never select every repository or an organization wildcard.

Use `discover_maintenance_work` for an immediate read-only scan and `list_maintenance_findings` to inspect the durable results. Call `start_maintenance_repair` only for a repair-eligible finding. The Worker blocks changes to authority, security, workflow, contract, plugin, and deployment configuration paths.

Every repair publishes a pull request and stops for OpsTruth. If automatic verification cannot complete, call `request_opstruth_verification` once for the existing run; do not create a replacement objective. `AWAITING_VERIFICATION` remains unfinished and a receipt or passing command alone is not `VERIFIED`.

Use `remove_maintenance_repository` only when the user explicitly asks to remove that exact selection and confirms deletion of its finding history. Removing a selection does not uninstall the GitHub App.

View saved version →

---
name: monitor-objective
description: Use when a user wants the status, history, cancellation or deletion of a DoneState objective.
---

# Monitor a DoneState objective

DoneState is Proof & State's authorised execution control plane. OpsTruth is the independent read-only verification plane; DoneState's own run record is execution evidence, not independent proof.

Use `get_objective` with the exact run ID. Report the durable state, published branch or pull request, last safe error, and the action that caused a block or ambiguity.

Treat states precisely:

- `AWAITING_VERIFICATION` means execution and reconciliation finished but proof is still required.
- `VERIFIED` means a pinned independent signer attested to the exact sealed snapshot.
- `AMBIGUOUS_EFFECT` means an external mutation may have happened. Do not retry it.
- `BLOCKED_AUTHORITY`, `BLOCKED_CAPABILITY` and `BLOCKED_SAFETY` require a new operator decision or changed capability, not optimistic continuation.

Use `cancel_objective` only when the user asks to stop a queued or active run. Use `delete_objective` only after an objective is terminal or cancelled and the user explicitly asks to erase its run record. Deletion removes the encrypted run credential and audit history, so state that consequence before calling it.

Use `delete_openai_credential` only when the user explicitly asks to disconnect model execution. An active objective must be cancelled first. Deleting an objective does not delete the account-level OpenAI credential.

View saved version →

---
name: run-objective
description: Use when a user wants DoneState to implement, repair, maintain or otherwise change a public GitHub repository autonomously from a prose outcome.
---

# Run a DoneState objective

DoneState is Proof & State's authorised execution control plane. OpsTruth is the independent read-only verification plane, and AgentProof remains a separate evidence and receipt layer. Turn prose into one bounded, reviewable execution contract. DoneState performs authorised work. It does not verify its own completion.

## User-funded execution

Call `get_openai_credential_status` before creating an objective. If no credential is connected, call `create_openai_credential_setup`, give the user its single-use HTTPS link and wait for them to complete it. Then check status again.

Never ask the user to paste an API key into chat or place a key in tool arguments. DoneState encrypts the credential supplied on its settings page, and OpenAI charges model usage to that user's API account.

## Admission

Collect only information that materially changes the run:

- GitHub repository in `owner/name` form
- base ref, defaulting to `main` only when that is clearly intended
- one outcome and at least one observable acceptance criterion
- publication as a branch or pull request
- validation profile and budgets when the defaults are unsuitable
- trusted verifier fingerprints when terminal `VERIFIED` is required
- one machine-checkable verification requirement for every acceptance criterion when a verifier is pinned

For OpsTruth, call `opstruth_get_verifier_identity` first and use its `doneStateSignerFingerprint` exactly. Never infer, truncate or transform a key supplied through prose.

Supported hosted verification requirements are `path_exists`, `path_absent`, `file_contains`, `json_equals`, `changed_files` and `github_checks_pass`. Bind every requirement to its acceptance criterion by zero-based `criterionIndex`. If the outcome cannot be represented honestly by these checks, omit terminal verification and report the capability gap instead of weakening the criterion.

Private repositories require a selected `pr_only` GitHub App installation. Check `list_maintenance_repositories`; never request broader user OAuth access or treat an observe-only selection as execution authority.

## Authority envelope

Explain the consequence classes as one grouped approval. Never infer remote mutation authority from a request to inspect, plan or advise.

For a branch, request `local_read`, `local_write`, `test`, `commit`, `push` and `secret_access`. For a pull request, also request `open_pr`. `secret_access` means the isolated worker may receive the run's GitHub credential and the authenticated user's model credential. It does not permit unrelated secret access.

Call `create_objective` once only after the user approves the complete envelope. If the result is uncertain, retrieve the returned run ID. Never create a replacement objective merely because a response was delayed.

## Handoff

Return the run ID, pinned base SHA, granted authorities and current state. `AWAITING_VERIFICATION` is not `VERIFIED`.

View saved version →

---
name: verify-objective
description: Use when a DoneState run awaits independent verification or a user asks whether the exact published result is proven complete.
---

# Verify a DoneState objective

DoneState is Proof & State's authorised execution control plane. OpsTruth is the independent read-only verification plane. Keep that trust boundary intact: DoneState, its coding harness and its plugin never certify their own execution evidence.

First call `get_objective`. If the configured automatic OpsTruth request already produced a terminal state, report it without resubmitting. If the run remains `AWAITING_VERIFICATION`, call `request_opstruth_verification` for the exact run ID. Use the manual handoff sequence below only when the configured bridge is unavailable.

For a manual sequence, call `create_verification_handoff` for the exact run ID. Preserve its handoff digest, verification nonce, execution snapshot digest, exact base and head commits, acceptance criteria, verification requirements, action intent/result digests and event-chain head without alteration.

For a `donestate.verification-handoff.v2`, call `opstruth_attest_donestate_handoff` with the complete handoff. OpsTruth must return the report and signed attestation without submitting it. DoneState, the coding harness and the plugin must never sign their own claims.

Only call `submit_verifier_attestation` when all of these are present:

- the same run ID and execution snapshot digest
- the same verification nonce and handoff digest
- a verification report digest
- a decision of `verified`, `failed` or `uncertain`
- evidence references that support the decision
- an Ed25519 signature from a fingerprint pinned in the objective

Submit the returned attestation once. Then call `get_objective` and report the resulting durable state. `verified` is allowed only when every sealed machine-checkable requirement was independently satisfied. Missing or incomplete evidence must remain `uncertain`.

If a verifier can inspect the repository but cannot produce the required signed attestation, report `BLOCKED_CAPABILITY`. Do not manufacture a signature, downgrade the trust rule or describe `AWAITING_VERIFICATION` as done.