# repo-contract — AI Agent Governance Layer

[![PyPI](https://img.shields.io/pypi/v/repo-contract.svg)](https://pypi.org/project/repo-contract/)
[![Python versions](https://img.shields.io/pypi/pyversions/repo-contract.svg)](https://pypi.org/project/repo-contract/)
[![CI](https://github.com/dager23/RepoContract/actions/workflows/ci.yml/badge.svg)](https://github.com/dager23/RepoContract/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

`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

```bash
pip install repo-contract
```

Requires Python 3.11 or newer. This installs the `repo-contract` command along with the MCP server.

<details>
<summary>Installing from source (for development)</summary>

```bash
git clone https://github.com/dager23/RepoContract.git
cd RepoContract
pip install -e ".[dev]"
pytest
```

</details>

---

## Quick Start

### 1. Initialize the Contract
Create a default configuration file in your repository:
```bash
repo-contract init
# Generates repo-contract.yaml
```

### 2. Configure Rules
Modify `repo-contract.yaml` (or TOML equivalent) to define your rules:

```yaml
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:
```bash
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:
```bash
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:
```bash
# 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:

```json
{
  "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) © Yash Shah