repo-contract — AI Agent Governance Layer

repo-contract is a lightweight, portable Python package and command-line tool that acts as an enforceable governance layer for AI coding agents (such as Claude Code, Cursor, Codex, Windsurf, Aider, etc.).

It allows repositories to declare machine-checkable architectural, safety, and workflow rules. The engine deterministically validates proposed agent plans (pre-edit) and git diff patches (post-edit) to ensure compliance before code is modified or merged.

Why Governance?

AI agents are excellent at generating edits, but often fail to respect repository-specific constraints:

• Scope Creep: Editing unrelated components or refactoring large sub-systems.
• Architectural Regressions: Importing internal database handlers directly into view controllers.
• Workflow Breaches: Editing crucial functionality without adding corresponding tests.
• Safety Violations: Reading/modifying forbidden files (.env, secrets/) or sensitive directories.

Rather than trying to help agents "understand more code" or storing synthetic meaning, repo-contract focuses on enforcing negative constraints, which empirical studies show is the most effective way to shape safe agent workflows.

Key Features

• YAML/TOML Contracts: Declarative policy schema containing architecture layers, safety paths, agent limits, and test mappings.
• Python Module Inspector: AST-based import resolution (both absolute and relative package paths).
• Plan Validation: Pre-checks an agent's text/markdown plan block, extracting planned files and verifying safety boundaries before edits begin.
• Diff Validation: Analyzes git patches/diffs to catch forbidden imports, path violations, test gaps, and file counts.
• Dependency Guard: Warns when a diff adds imports of external packages that are not declared in pyproject.toml / requirements.txt / setup.py — a common AI-agent failure mode.
• Unrelated Refactor Detection: Identifies whether modifications span disjoint, unconnected modules in the import graph (connected components analysis).
• Deterministic Engine: 100% deterministic rules with clear, human-readable explanations and JSON-RPC outputs.
• MCP Server Integration: Stdio-based Model Context Protocol (MCP) server wrapper that exposes validators directly as tools for AI assistants.

Installation

# Clone the repository
git clone https://github.com/your-org/repo-contract.git
cd repo-contract

# Install in editable mode
pip install -e .

Quick Start

1. Initialize the Contract

Create a default configuration file in your repository:

repo-contract init
# Generates repo-contract.yaml

2. Configure Rules

Modify repo-contract.yaml (or TOML equivalent) to define your rules:

version: 1

project:
  name: my-app
  src_root: "my_app"  # Directory containing python package modules

architecture:
  layers:
    - name: ui
      paths: ["my_app/ui/**"]
      # Entries may be layer names ("db"), dotted module prefixes ("my_app.db"),
      # or path prefixes ("my_app/db") — all three are equivalent.
      cannot_import: ["my_app/db"] # UI layer cannot import DB layer directly
    - name: db
      paths: ["my_app/db/**"]
      cannot_import: ["my_app/ui"]

workflow:
  required_tests:
    # Require corresponding test file to be modified when source is modified
    - when_paths_match: ["my_app/**/*.py"]
      require: ["tests/**/test_*.py"]

safety:
  forbidden_paths:
    - ".env"
    - "secrets/**"
  approval_required_for:
    - "my_app/auth/**"

agent:
  max_files_per_change: 6
  forbid_unrelated_refactors: true

dependencies:
  # Warn when a diff adds imports of packages not declared in the
  # project's dependency files (pyproject.toml / requirements.txt / setup.py)
  check_undeclared: true

3. Run Validation

Scan Codebase

Scan the entire repository for static layer boundary violations or missing tests:

repo-contract scan

Validate Agent Plan (Pre-edit)

Pass the agent's proposed plan (as raw text or from a file) to ensure they aren't touching forbidden files or planning changes that are too broad:

repo-contract check-plan "I will edit my_app/auth/login.py and .env to configure authentication."
# Fails because .env is forbidden and auth/ requires approval.

# Or validate a plan saved to a file:
repo-contract check-plan plan.md

If the argument is a path to an existing file it is read as a plan file; otherwise it is treated as raw plan text (use --text to force raw-text interpretation).

Validate Git Diff (Post-edit / CI Gate)

Check uncommitted working tree edits, a specific git commit range, or a patch file:

# Validate local uncommitted edits
repo-contract check-diff

# Validate staging changes
repo-contract check-diff --staged

# Validate range (e.g. CI run)
repo-contract check-diff HEAD~1..HEAD

# Validate a patch file
repo-contract check-diff my-change.patch

Model Context Protocol (MCP) Integration

You can run repo-contract as a stdio-based MCP Server in your favorite editor (like Cursor, Claude Desktop, or Windsurf) by adding this command to your configuration:

{
  "mcpServers": {
    "repo-contract": {
      "command": "python",
      "args": ["-m", "repo_contract.mcp.server"],
      "cwd": "/path/to/your/project"
    }
  }
}

Exposed Tools

• scan_repository: Runs structural checks on the current workspace.
• check_plan: Analyzes the agent's textual/markdown plan, extracting planned files and validating bounds before edits begin.
• check_diff: Checks current uncommitted working directory edits.

License

MIT License.