Agent Operator Guide | Covenant v1

Pre-Contribution Checklist

Fetch the policy file.
Check for /covenant.yml at the repository root. If absent, treat the repository as unspecified (no Covenant governance applies).
```
curl -sf https://raw.githubusercontent.com/{owner}/{repo}/main/covenant.yml
```
Parse and validate the policy.
Use a YAML parser. Validate the structure against the Covenant.yml v1.0.0 JSON Schema.

Determine your intended action.

Map your planned operation to a Covenant canonical action:

Operation	Canonical Action
Open a pull request	`pull_request.open`
Push to an existing PR	`pull_request.update`
Submit a review	`pull_request.review.submit`
Approve a PR	`pull_request.review.approve`
Merge a PR	`pull_request.merge`
Open an issue	`issue.open`
Comment on an issue	`issue.comment`
Label an issue	`issue.label`
Close/fix an issue	`issue.solve`
Comment on a human thread	`conversation.intervene_human_thread`
Comment on an agent thread	`conversation.intervene_agent_thread`
Clean up (close PR, delete branch)	`maintenance.cleanup`
Reroute to develop-bot branch	`routing.to_develop_bot`

Evaluate the policy against your action.

Construct a canonical event envelope and evaluate it against the policy rules. The outcome will be allow, warn, or deny.

{
  "action": "pull_request.open",
  "actor": {
    "id": "your-agent[bot]",
    "kind": "agent"
  },
  "repository": {
    "name": "your-org/your-repo",
    "visibility": "public"
  },
  "target": {
    "branch": "main"
  },
  "evidence": {
    "model": "claude-opus-4-6",
    "provider": "anthropic",
    "prompt_record": "prompt://session/abc123",
    "test_proof": "tests://ci/run/456"
  }
}

Respect the outcome.
- allow — proceed with the action.
- warn — proceed but expect the action to be flagged.
- deny — do not perform the action.

Evidence Fields

When a policy requires provenance, attach these fields to your contribution metadata:

Field	Description	Example
`model`	Exact model identifier used to generate the contribution.	`claude-opus-4-6`
`provider`	The provider or platform hosting the model.	`anthropic`
`prompt_record`	URI or reference to the prompt session that produced this work.	`prompt://session/abc123`
`test_proof`	URI or reference to passing test results.	`tests://ci/run/456`

Attestation

When a policy requires attestation, sign a covenant.attestation.v1 payload before submitting your contribution.

Signed Payload Structure

{
  "version": "covenant.attestation.v1",
  "actor_id": "your-agent[bot]",
  "action": "pull_request.open",
  "repository": "owner/repo",
  "ref": "refs/heads/feature-branch",
  "policy_sha256": "sha256-of-covenant-yml",
  "timestamp": "2026-02-21T00:00:00Z",
  "nonce": "unique-random-string"
}

Verification Requirements

Signature algorithm: Ed25519.
Public key must be registered in actors.agents[].verification in the target repo's covenant.yml.
Timestamp must be within attestation.max_age_seconds of evaluation time.
Nonce must not have been used within attestation.nonce_ttl_seconds.
Policy hash must match the current covenant.yml SHA-256.

Thread Mode Awareness

Repositories may label discussion threads with mode indicators:

thread:human — human-only conversation. Agent intervention typically denied.
thread:agent — agent-primary conversation. Participation typically allowed.
No label — mixed mode. Policy rules determine access.

Before commenting on a thread, check for thread mode labels and evaluate the corresponding canonical action (conversation.intervene_human_thread or conversation.intervene_agent_thread).

Reading Badges

Covenant-governed repositories display CI-verified badges. Use these for quick policy assessment:

Help text below focuses on the four policy-decision badges; covenant-enabled is always enabled when Covenant is active.

`agent-pr-policy`

Shows the strictest policy outcome for agent-authored pull requests.

Practical example: a human asks an agent to open a PR; allow means it can proceed, warn means it opens with policy warnings, and deny means the PR is blocked.

`provenance-policy`

Shows whether a default provenance profile enforces evidence fields.

Practical example: an agent opens a PR; with required it must include evidence like model and provider, while none means those fields are not enforced.

`attestation-required`

Indicates whether cryptographic attestation signatures are required.

Practical example: when an agent submits a PR, required or agents means it must attach a valid signed attestation payload or policy checks fail.

`thread-intervention-policy`

Shows whether intervention in human threads is restricted.

Practical example: in a human-only incident thread, controlled means an agent comment is warned or denied unless explicitly allowed.