Deterministic guardrails for non-deterministic agents.
Agent Contract is a runtime for repository governance. It builds deterministic policy enforcement around AI coding agents — not by constraining what models can reason about, but by governing what they can write.
then agent-contract init in any repo · or one-shot with npx @semeton/agent-contract init
Prompts communicate intent. They do not enforce policy.
Today's AI coding workflows rely on instructions the agent is asked — not required — to follow. The model reads a file, interprets it as best it can, and may or may not comply. No enforcement boundary exists before writes occur.
Software engineering has never relied on perfect components. It has relied on deterministic systems surrounding them.
TCP/IP does not fix packet loss. It builds retransmission protocols around it. Paxos does not fix node failures. It builds consensus around them. This principle appears consistently across distributed systems, hardware design, and network architecture: build deterministic infrastructure around unreliable components, and do not assume the components will become reliable.
Probabilistic by nature
Language models produce useful outputs consistently. They do not produce identical outputs deterministically. This property does not change with better prompting — it is a characteristic of the architecture.
Deterministic by boundary
Repositories are deterministic systems. A file is either written or it is not. A path is either in scope or it is not. The enforcement boundary belongs in the repository layer, not the model layer.
Policy in the repository
Policy that exists only in prompts or conversations disappears when the session ends. Policy that lives in the repository is versioned, reviewed, and present in every future execution — by any agent, any provider.
Enforcement before writes
The enforcement boundary belongs before writes reach the codebase. Post-hoc review is not governance. A write that lands outside scope is a governance failure regardless of whether it is caught in review.
From repository policy to verified writes.
Agent Contract is structured as a layered runtime. Each layer has a single responsibility. Policy flows from the repository through the enforcement layer before the language model's outputs reach the codebase.
Policy ownership. Governance lives in the repository alongside the code it governs — versioned, reviewed, discoverable.
Declares roles, file scopes, framework rules, and verification commands. The source of truth for what the agent is permitted to do.
Persistent architectural knowledge. Decisions, state, and context that belong to the repository, not the session.
Bounded authority per task. Each execution receives explicit file scope it cannot widen.
Deterministic enforcement before writes occur. Every file write is checked against the active role's declared scope. Violations exit non-zero.
Operates within governance layer.
Same governance. Different model.
Governance survives model changes.
Only policy-compliant changes reach the codebase. Scope, conventions, and verification confirmed before completion.
The architectural properties of repository governance.
Each property addresses a specific structural gap in how AI coding agents are governed today.
Repository-owned governance
The repository defines policy instead of conversational instructions. Governance is declared in .agent/contract.yaml, versioned with the codebase, and subject to the same review process as any other configuration. Any engineer, any agent, any CI system can find it by reading the project root.
Deterministic enforcement
Repository writes are verified before they land. The enforcement pipeline is structured in layers: contracts define policy, roles define authority, hooks enforce it. The interface is exit codes — not model output, not log messages. Every write exits non-zero on a scope violation, before the change reaches the codebase.
Persistent architectural knowledge
Repository understanding belongs to the repository, not the session. Repository Memory stores architectural decisions, outstanding issues, and session state that persist across executions. The Codebase Map provides an indexed architectural model — modules, entry points, domain boundaries — so each execution begins from existing understanding rather than repeated discovery.
Provider independence
Repository governance is independent of the language model. Contracts, roles, and enforcement hooks operate identically regardless of whether the agent runs Claude, OpenAI, or a future model. Language models change. Repository governance does not migrate with them.
The building blocks of repository governance.
Each component satisfies a specific architectural requirement. Together they form the governance layer between repository policy and agent execution.
Repository Contracts
.agent/contract.yaml is the policy definition. It declares scope, roles, framework rules, and verification commands. Stored in the repository. Idempotent — regenerate any time the stack changes.
Execution Roles
Roles implement the principle of least privilege. Each task receives a role with explicit file scope it cannot widen. A role scoped to src/payments/** cannot write to auth, billing, or infrastructure — regardless of instruction.
Enforcement Pipeline
pre-generate.sh validates the task and arms the active role. The PreToolUse hook checks scope on every write in real time. post-generate.sh runs verification. Three deterministic checkpoints, each with a binary outcome.
Repository Memory
Memory is not conversation history. It is persistent repository knowledge — the cognitive layer of the governance runtime. A Stop hook writes architectural decisions, outstanding issues, and session state after every execution that produces changes. The next execution begins from the last known repository state rather than from discovery. Architectural knowledge accumulates in the repository where it belongs, not in a context window that closes.
Codebase Map
Relational databases rarely perform sequential scans when indexes exist. A query planner traverses an index to locate records without scanning the full table. AI coding agents face an analogous problem: without a structural model, each execution traverses the repository to reconstruct architectural understanding — discovering module boundaries, entry points, and domain structure from scratch. The Codebase Map is an architectural index. It stores a structural model of the repository that the governance runtime reads before the agent reads source files. The primary benefit is eliminating repeated architectural discovery. Each execution begins from an existing model. Token savings are a consequence of that, not the objective.
Provider Independence
Governance contracts are independent of the language model. Claude, OpenAI, and future models operate through the same execution interface. Changing providers does not require rebuilding governance policy.
Framework Detection
The CLI reads project structure and identifies stack, framework, ORM, and test runner automatically. It then configures the correct linter, type-checker, and test runner for post-task verification — across 14+ stacks.
Stack-aware Verification
After a task completes, the contract runs the right tools: eslint + tsc + jest for TypeScript, phpstan + pint + phpunit for Laravel. Verification is specific to the stack, not generic.
A governed execution.
The contract defines policy. The role defines authority. The runtime enforces both — before writes reach the codebase.
Where existing approaches end and enforcement begins.
AGENTS.md and Cursor Rules are persistent and repository-native. The structural gap is enforceability — they rely on the model choosing to cooperate with policy it has read.
| Prompt Engineering | AGENTS.md | Cursor Rules | Agent Contract | |
|---|---|---|---|---|
| Persistent | ✕ | ✓ | ✓ | ✓ |
| Enforceable | ✕ | ✕ | ✕ | ✓ |
| Repository Native | ✕ | ✓ | ✓ | ✓ |
| Role Based | ✕ | ✕ | ✕ | ✓ |
| Verifiable | ✕ | ✕ | ✕ | ✓ |
| Persistent Architecture Memory | ✕ | ✕ | ✕ | ✓ |
| Provider Independent | ✕ | ✕ | ✕ | ✓ |
The engineering properties behind the design.
Each principle reflects a specific decision about where trust is placed and where enforcement is applied.
Deterministic
Governance produces binary outcomes. A write is either within scope or it is not. The enforcement interface is exit codes, not model output. Compliance is not self-reported.
Repository-first
The repository is the unit of trust, not the conversation. Policy that lives in the repository is versioned, reviewed, and present in every future execution. Policy that lives in a conversation is not.
Persistent
Architectural knowledge survives session boundaries. Repository memory and the codebase map ensure each execution begins from existing repository understanding rather than from repeated discovery.
Independent
Governance does not depend on any specific language model. The contract is the constant. The model provider is interchangeable. Switch providers without rebuilding governance policy.