The Missing Half Of An Agent Contract
Most agent contracts answer an important question:
How should an agent change this repository?
They can protect sensitive directories, ask for smaller diffs, require a handoff, and tell an
agent when to stop and ask a human.
But a repository has a second question:
What must happen before this change counts as accepted?
That is not a writing-style question. It is an execution question: the setup path, the selected
services, the canonical verification lane, the execution mode, and the evidence a green result
actually carries.
An agent contract can guide edits. It cannot, by itself, define repository acceptance.
The Failure Mode
Consider an agent contract that says:
- Do not edit generated clients.
- Keep migrations small and explain them.
- Run tests before handoff.
- Ask before changing infrastructure.
Those are good contribution rules. They do not answer whether “run tests” means pnpm test, a
service-backed workflow, a container lane, or CI's actual verification closure. They do not say
whether dependencies are materialized, a database is ready, or a zero exit proves more than one
narrow check.
The dangerous outcome is a plausible handoff: the agent followed the instructions, ran a command,
and reported success. Nobody can tell whether it used the accepted path.
Ota Defines The Acceptance Path
Ota gives that operational truth a machine-readable home in ota.yaml:
tasks:
setup:
prepare:
kind: dependency_hydration
medium: package_dependencies
source:
kind: node_package_manager
manager: pnpm
mode: install
frozen_lockfile: true
verify:
command:
exe: pnpm
args: [test]
depends_on: [setup]
safe_for_agent: true
agent:
safe_tasks: [verify]
verify_after_changes: [verify]
That is not an instruction to “remember to install dependencies.” It declares one accepted setup
and verification path that Ota can inspect, dry-run, execute, and record.
An agent can discover the declared surface, then execute it through the enforced lane:
ota doctor
ota tasks --safe --use
ota run verify --agent
The important distinction is that --agent asks Ota to resolve the selected task closure before
anything starts. If the requested task, dependency, or workflow path is outside the effective safe
surface, Ota refuses it and emits a structured result rather than relying on the agent to obey
prose.
The Boundary Is Real, But Scoped
Ota does not claim to sandbox every process an agent could launch. An agent with unrestricted shell
access can still bypass Ota by not using it.
The enforcement point is the Ota runner boundary: ota run <task> --agent and, for an
agent-admitted workflow, ota up --workflow <name> --agent. That gives developers and CI fast,
inspectable execution control now. A stronger organization-wide boundary comes when CI gates and
agent harnesses consume the same contract truth.
That honesty matters. A declared safe task is useful; a runner that refuses an unsafe closure is
stronger; an org-level harness or merge gate that requires the same result is stronger again.
Two Contracts, Two Jobs
Use an agent contract for contribution behavior:
- editing and review rules
- sensitive files and escalation
- coding conventions and handoff expectations
Use Ota for repository acceptance:
- dependency hydration and setup order
- services, readiness, tasks, and workflows
- native or container execution selection
- agent-admitted execution paths
- receipts, proof boundaries, and CI drift checks
Neither replaces the other. A repository with only agent guidance still asks the agent to infer
how the software runs. A repository with only Ota can still need human collaboration rules.
The durable model is simple: let the agent contract govern edits, and let Ota govern whether the
repository was prepared, verified, and evidenced through an accepted path.
Originally posted here: https://ota.run/blog/ai-agent-contracts-cannot-define-repository-acceptance
Top comments (0)