Metadata-Version: 2.4
Name: scopeledger
Version: 0.1.0
Summary: Run commands inside a declared scope and emit independently verifiable receipts.
Author: Yohei Watanabe
License: MIT
Project-URL: Homepage, https://github.com/you1208/scopeledger
Project-URL: Documentation, https://github.com/you1208/scopeledger#readme
Project-URL: Issues, https://github.com/you1208/scopeledger/issues
Project-URL: Changelog, https://github.com/you1208/scopeledger/blob/main/CHANGELOG.md
Keywords: ai-agents,evidence,governance,receipts,cli
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ScopeLedger

[![CI](https://github.com/you1208/scopeledger/actions/workflows/ci.yml/badge.svg)](https://github.com/you1208/scopeledger/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Run commands inside a declared scope. Keep receipts that can be checked without trusting the runner.**

ScopeLedger is a small, model-agnostic CLI for coding-agent and automation workflows. It does not run an AI agent. It wraps one command, records the exact before/after workspace state, checks effects against a policy, and writes an append-only `PASS`, `HOLD`, or `STOP` receipt.

The first release deliberately has no service, account, API key, model dependency, plugin system, or automatic retry.

## Why

An agent saying “tests passed” is a claim. ScopeLedger turns a narrow class of those claims into inspectable evidence:

- Was this command allowed to start?
- What files actually changed?
- Did anything outside the declared scope change?
- Were required outputs produced?
- Does the receipt still match its evidence?
- Has earlier history been removed or rewritten?

## Quick start

Requires Python 3.11 or newer.

```bash
git clone https://github.com/you1208/scopeledger.git
cd scopeledger
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
scopeledger run --policy scopeledger.toml -- python examples/write_result.py
scopeledger verify --policy scopeledger.toml
```

On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1`.

For an existing repository, the [adoption guide](docs/adoption-guide.md) shows a commit-pinned installation. Once the package is published, `python -m pip install scopeledger` will be the normal installation path.

The included example permits changes only under `demo-output/`. A successful run writes evidence and a receipt beneath `.scopeledger/` and prints a compact result:

```json
{"status":"PASS","receipt":".../.scopeledger/receipts/<run-id>.json","findings":[]}
```

## Policy

```toml
version = 1

[scope]
root = "."
allow_changes = ["build/**"]
deny_changes = ["src/**", ".github/**"]
ignore = [".git/**", ".venv/**", "**/__pycache__/**"]

[command]
executables = ["python", "python3"]
timeout_seconds = 30

[checks]
require_exit_code = 0
required_files = ["build/result.json"]

[receipts]
directory = ".scopeledger"
```

Commands are executed directly, never through an implicit shell. `executables` matches the first command argument exactly; listing `python` does not allow `/some/path/python`. File patterns use case-sensitive glob matching with explicit `directory/**` subtree support.

## Decisions

| Status | Meaning |
| --- | --- |
| `PASS` | The command ran and every declared check passed. |
| `HOLD` | The command ran, but its result or effects did not satisfy policy. Human review is required. |
| `STOP` | Preflight refused execution, so the command did not run. |

ScopeLedger never changes a `HOLD` into a `PASS` by retrying. Recovery belongs to a new, separately receipted run.

## Evidence model

Each evidence document contains the policy, policy digest, command arguments, timestamps, exit result, stdout/stderr digests and sizes, before/after file manifests, the resulting change set, and required-output facts. Command output contents are not stored.

Each receipt binds to its evidence digest and the prior receipt file digest. `scopeledger verify` recomputes those bindings and independently derives the expected decision from recorded facts. Records use exclusive creation and are never updated by ScopeLedger.

This provides tamper evidence, not tamper prevention. Anyone who can replace the entire ledger and all external copies can create a new history. Signed checkpoints and external anchoring are possible future work, not v0.1 claims.

## Security boundary

ScopeLedger is a policy and evidence layer, **not a sandbox**. An allowed command runs with the current user's permissions and environment. Use an OS/container sandbox for untrusted code. A command may also access network resources unless your execution environment prevents it.

See [SECURITY.md](SECURITY.md) for reporting and the v0.1 threat boundary.

## Project status

v0.1 is intentionally narrow: one local command, one workspace, deterministic file-effect checks, local receipts. Feedback is welcome, especially from maintainers using coding agents in real repositories.

- Follow the [adoption guide](docs/adoption-guide.md) to add ScopeLedger to an existing repository.
- Read the [design and trust model](docs/design.md) before relying on receipts.
- See the [public roadmap](ROADMAP.md) and open an issue with a real workflow that ScopeLedger should support.

## License

MIT © Yohei Watanabe
