Metadata-Version: 2.4
Name: scopeproof
Version: 0.1.5
Summary: A tiny scope and architecture guardrail for AI coding agents.
Author: ScopeProof Contributors
Maintainer: SomeTimeDev
License-Expression: MIT
Project-URL: Homepage, https://github.com/SomeTimeDev/scopeproof
Project-URL: Repository, https://github.com/SomeTimeDev/scopeproof
Project-URL: Issues, https://github.com/SomeTimeDev/scopeproof/issues
Keywords: ai-agents,coding-agents,codex,guardrails,code-review,static-analysis,git,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: pathspec>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# 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](https://pypi.org/project/scopeproof/) (Python 3.11+):

```bash
pip install scopeproof
```

To try the latest unreleased changes from GitHub:

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

For local development:

```bash
pip install -e ".[dev]"
```

## Quickstart

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

To check exactly what is staged for the next commit:

```bash
git add .
scopeproof check --staged
```

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

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

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

## Example `scopeproof.yml`

```yaml
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`

```yaml
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

```text
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

```yaml
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
