Covenant v1

1. Purpose

covenant.yml is a deterministic governance contract for repositories. It defines what human contributors, software agents, and manager actors may do across repository interaction surfaces.

The policy is machine-readable and schema-validated. No enforcement decision depends on natural language interpretation.

Read this page as an implementation guide: sections 2-5 define the contract and evaluation pipeline, sections 6-11 define behavior and interfaces, and sections 12-14 define compliance and shared terminology.

2. Canonical Location

The policy file must be placed at the repository root:

/covenant.yml

No alias locations are part of Covenant v1.

3. Decision Model

Covenant uses three outcomes:

• allow: action is accepted
• warn: action is accepted but flagged
• deny: action is rejected

Strictness ordering: deny > warn > allow

In practice, this means any failing requirement can only keep or increase strictness. A decision never becomes less strict later in evaluation.

4. Top-Level Contract

Think of top-level keys as contract modules: each one controls a different stage of evaluation, verification, or enforcement.

Unknown top-level keys are invalid.

4.1 Policies

The policies section defines cross-cutting constraints that are evaluated before rule matching.

agent_eligible_labels restricts agents to issues carrying at least one eligible label.

policies:
  agent_eligible_labels:
    labels: [agent-friendly, good-first-bot-issue]
    actions: [issue.solve, issue.comment]
    on_missing: deny

• labels: at least one of these labels must be present on the issue.
• actions: optional list limiting which canonical issue actions the gate applies to.
• on_missing: decision used when labels are missing (allow, warn, or deny).

This gate only affects agents. Humans and managers are not subject to it.

5. Deterministic Resolution Algorithm

Input event envelope:

{
  "action": "pull_request.open",
  "actor": { "id": "ci-agent[bot]", "kind": "agent" },
  "repository": { "name": "acme/project", "visibility": "public" },
  "target": { "branch": "main", "thread_mode": "mixed", "labels": ["ai"] },
  "evidence": {
    "model": "gpt-5",
    "provider": "openai",
    "prompt_record": "prompt://123",
    "test_proof": "tests://ci/123"
  },
  "attestation": {}
}

Resolution steps:

1. Normalize incoming platform event into canonical action and envelope.
2. Apply policies gates (for example agent_eligible_labels) before rule matching.
3. Match candidate rules by actor, action, target, and conditions.
4. Compute specificity tuple: actor specificity, action specificity, target specificity, condition count.
5. Select highest tuple.
6. If tie: apply strictness tie-break (deny > warn > allow).
7. If no rule matches: use defaults.unmatched.
8. Apply requirements checks.
9. Apply attestation checks when required.
10. Compute final decision as the maximum strictness of rule outcome and requirement/attestation failures.
11. Compute reason codes and emit enforcement action plan.

Think of the algorithm as a fixed pipeline: normalize -> gate -> match -> escalate -> enforce. Because the order is fixed, identical inputs always produce identical outputs.

6. Interaction Matrix

The matrix below maps each canonical action to expected decision ranges per actor kind. Hover selected headers and action names for field-level guidance.

This is a capability map, not a direct allow-list. The final decision for a given event still depends on your concrete rules, policies gates, and requirement failures.

Thread modes are explicit: human, agent, mixed.

7. Attestation Contract

Attestation version: covenant.attestation.v1

The signed payload binds identity, action, repository context, policy revision, and freshness controls into one verifiable artifact.

Verification key registry: actors.agents[].verification

Minimum controls:

• Signature verification
• Timestamp freshness (attestation.max_age_seconds)
• Replay protection (attestation.nonce_ttl_seconds)
• Policy hash equality

A valid signature is necessary but not sufficient: freshness, nonce reuse, and policy-hash checks must all pass.

8. Enforcement Operations

Enforcement operations are deterministic side effects. They explain, route, or block actions based on the final decision.

Actions are planned deterministically from enforcement.<decision> and optional routing rules.

9. Canonical Actions

Canonical actions are normalized event names used by rules. Platform-specific event payloads should map to one of these before evaluation.

Wildcards supported in rules: * and <surface>.* (e.g., pull_request.*)

Use exact actions when you need strict control, and surface wildcards when you want broader but still explicit policy coverage.

10. Resolution Flow

Incoming platform event
  -> Normalize to canonical action
  -> Apply policies gates
  -> Match candidate rules
  -> Compute specificity tuple
  -> Select rule or defaults.unmatched
  -> Apply provenance requirements
  -> Apply attestation checks
  -> Finalize decision and reason codes
  -> Plan enforcement operations
  -> Emit CI outputs and badges

This condensed flow mirrors the algorithm in section 5 and is useful as a debugging checklist when a decision looks unexpected.

11. Public Interfaces

These interfaces are the stable integration points for local tooling, CI workflows, and policy-aware automation.

CLI

covenant validate [policy-path]
covenant eval --event <json|path> [--policy <path>]
covenant badge --format json|shields [--policy <path>]

GitHub Action

Inputs: policy-path, event-json, mode

Outputs: decision, reason_codes, enforcement_actions

Schema

schema/covenant.schema.json

Integrators should treat CLI output and action outputs as machine contracts, and use the schema for validation before policy evaluation.

12. Conformance

A Covenant v1 implementation is conformant if:

• Identical event + identical policy always produce identical output.
• Unsupported keys are rejected.
• No decision depends on free-text interpretation.
• Decision and reason codes are emitted in machine-readable form.

Conformance is about behavior, not language. If two engines disagree on a decision for the same input, at least one is non-conformant.

13. Reason Codes

Conformant engines emit machine-readable reason codes with each decision.

Treat reason codes as your debugging API: they explain exactly which gate, rule, or verification check influenced the final outcome.

Rule Selection

Policies Gate

Provenance / Evidence

Attestation

14. Glossary

Use this glossary as the canonical meaning of terms used across policy files, CLI output, and documentation.