ScopeProof

AI coding agents start focused, then drift. ScopeProof keeps their changes inside your project's scope.

It checks agent-generated diffs for needless modules, duplicate abstractions, scope escape, orphan files, changed-file growth, parse errors, and public API growth.

No LLM required. No cloud. No vendor lock-in.

Problem

Small requested changes can quietly become new service layers, duplicate classes, unrelated file edits, or public APIs that were never part of the task. ScopeProof is a deterministic CLI guardrail for catching those signals before merge.

What ScopeProof Checks

• scope_escape: changed files outside task paths or inside forbidden paths
• module_sprawl: too many new files or suspicious new modules
• changed_file_growth: too many changed files for one task
• parse_error: changed Python files that cannot be parsed
• duplicate_symbol: new public symbols that resemble existing symbols
• orphan_new_file: new production Python files that are not imported or tested
• public_api_growth: excessive public class/function growth for one task

Installation

Install from PyPI (Python 3.11+):

pip install scopeproof

To try the latest unreleased changes from GitHub:

pip install git+https://github.com/SomeTimeDev/scopeproof.git

For local development:

pip install -e ".[dev]"

Quickstart

scopeproof init
scopeproof prompt "Add CSV export support"
scopeproof check --base HEAD

To check exactly what is staged for the next commit:

git add .
scopeproof check --staged

For stricter projects, start with fail-on defaults for every drift check:

scopeproof init --strict

Local working-tree checks include untracked files by default. A new untracked Python module is treated as an added file, so scopeproof check --base HEAD catches drift before you remember to run git add. Use --staged when you want to ignore unstaged/untracked experiments and check only the Git index.

For pull requests:

scopeproof check --base origin/main --head HEAD

Example scopeproof.yml

version: 1
project:
  name: "demo"
  mission: "CLI for exporting structured data."
rules:
  max_changed_files_per_task: 8
  max_new_files_per_task: 1
  duplicate_symbol_similarity: 0.82
  fail_on_module_sprawl: true
  fail_on_changed_file_growth: false
extension_points:
  - name: "Exporters"
    keywords: ["export", "csv"]
    prefer_existing_paths:
      - "src/**/exporters/**"
    allow_new_files_under:
      - "src/**/exporters/**"
      - "tests/**"

Example .scopeproof/task.yml

goal: "Add CSV export support"
allowed_paths:
  - "src/**/exporters/**"
  - "tests/**"
forbidden_paths:
  - "src/**/services/**"
prefer_modify:
  - "src/demo/exporters/base.py"
expected_behavior:
  - "Use the existing exporter interface."
verification:
  - "pytest -q"

Example Report

ScopeProof Report

Project: demo
Task: Add CSV export support
Diff: HEAD -> working tree

FAIL scope_escape
  src/demo/services/csv_export_service.py: Changed file matches a forbidden task path.

FAIL module_sprawl
  src/demo/services/csv_export_service.py: New file was added outside matched extension point paths.

Overall: FAIL

GitHub Actions

name: ScopeProof

on:
  pull_request:

jobs:
  scopeproof:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - run: pip install scopeproof

      - run: scopeproof check --base origin/main --head HEAD --format markdown --output scopeproof-report.md

ScopeProof does not post PR comments yet.

Philosophy And Limitations

ScopeProof does not prove semantic correctness. It catches deterministic drift signals:

• changed files outside allowed paths
• too many files changed for one task
• Python syntax errors in changed files
• suspicious new modules
• duplicated-looking symbols
• orphan new files
• unexpected public API growth

It currently indexes Python with the standard library ast module. Non-Python files can be checked for path scope, but not for symbol-level behavior.

Roadmap

• TypeScript/JavaScript indexing
• GitHub PR comments
• Layer/import violation checks
• Optional hook examples

License

MIT