Metadata-Version: 2.4
Name: proofofcontext
Version: 0.3.0
Summary: Decision-aware context injection for an existing repo: scaffold, deliver, and enforce project decisions with a human approve step. Stdlib only, offline, no per-commit LLM cost.
Author: ProofOfContext
Project-URL: Homepage, https://github.com/prove-ai/proof-of-context
Project-URL: Repository, https://github.com/prove-ai/proof-of-context
Project-URL: Changelog, https://github.com/prove-ai/proof-of-context/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/prove-ai/proof-of-context/issues
Keywords: context,memory,agents,pre-commit,decisions
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: web
Requires-Dist: fastapi<1.0,>=0.110; extra == "web"
Requires-Dist: uvicorn[standard]<1.0,>=0.29; extra == "web"
Requires-Dist: gunicorn<24,>=21.2; extra == "web"

# ProofOfContext

The memory that stops AI agents — and engineers in fresh sessions — from silently
contradicting decisions your team already made: the wrong database, a banned
dependency, an architecture call quietly reversed.

`brain.md` and the decision log are the source of truth. ProofOfContext records a
project's decisions once, **feeds them to a fresh agent before it writes**, and
**enforces them when code lands**.

---

**Not a security scanner.** A scanner asks *"is this code insecure?"* from a shared
rule library. ProofOfContext asks *"does this contradict a decision **we** made?"* —
Postgres-not-Mongo, one billing source of truth, stdlib-only core. Those aren't
vulnerabilities and aren't in anyone's library; they live in your team's head.
**Security is a library problem; architectural intent is a memory problem.**

## Trust

Nothing is taken on faith: the package ships as readable source, makes no
network calls, and sends no telemetry — and every one of those claims comes
with a command you can run against your installed copy to verify it. See
**[TRUST.md](TRUST.md)**.

## Install

The CLI is pure standard library — no runtime dependencies — and runs on
**Python 3.8+**, tested through 3.14. End-of-life interpreters are supported
deliberately: the stdlib-only core makes them nearly free to keep, and the
repos that most need a decision gate are often pinned to older Pythons.

```bash
pipx install proofofcontext   # recommended: puts `poc` on your PATH everywhere
# or: pip install proofofcontext
```

For development, install from source instead:

```bash
git clone https://github.com/prove-ai/proof-of-context.git
cd proof-of-context
pip install -e .
```

Uninstall leaves zero trace:

```bash
rm -f .git/hooks/pre-commit && rm -rf .context/ && pip uninstall proofofcontext
```

(Details and what each piece is in [TRUST.md](TRUST.md).)

## Commands

```
poc init              scaffold .context/ + a pre-commit hook (with human approval)
poc decide [flags]    record one human-approved decision (appended to the log)
poc context "<task>"  emit a paste-ready context package for a fresh agent session
poc why "<question>"  answer "why did we decide X?" from the decision log
poc check <path>...   fail if a file contradicts a recorded decision (deterministic, offline)
poc evaluate "<rule>" advisory KEEP / REVISIT / RETIRE verdict on a rule (never blocks)
poc skill [refresh]   keep the generated Claude skills in sync with .context/
poc stats             summarize the decision-collision ledger

# operational assumptions — beliefs about the codebase, recomputed from real git history
poc assume scan <repo>     compute the assumption portfolio (coupling, stability, debt)
poc assume show "<pair>"   render one belief's claim card (trend, sparkline, real-SHA evidence)
poc assume update <repo>   recompute the assumptions new commits touched; report the move
poc assume verify "<pair>" re-derive a belief's confidence from git a second way to prove it
```

## Try it

Follow **[docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)** — a 5-minute first run. You
install `poc`, open the governed example in
[`examples/billing-service/`](examples/billing-service/), and watch an AI-written
MongoDB change get **blocked at `git commit`** because it contradicts the team's
recorded PostgreSQL decision — then fix it and watch the commit pass. It's the real
workflow, not a script.

## How it works

Team memory lives in `.context/` (`brain.md`, `decisions.md`, `ledger.jsonl`,
`graph.md`). `poc check` runs deterministically and offline — token matching with
comments and strings ignored, no LLM, no network, no per-commit cost — so it runs
identically in a pre-commit hook, in CI (GitHub Action), and by hand. Nothing is
written to `.context/` without a human accept / edit / reject step.

## Docs

- [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) — 5-minute first run
- [TRUST.md](TRUST.md) — verify the no-network / no-telemetry claims yourself
- [docs/FAQ.md](docs/FAQ.md) — trust and verification, false positives, monorepos, `--no-verify`, other hooks, pricing
- [docs/WRITING-RULES.md](docs/WRITING-RULES.md) — writing `Forbids:` lines that catch what you mean
- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — hook not firing, PATH, merge conflicts, local-vs-CI
- [docs/ASSUMPTIONS-LIMITS.md](docs/ASSUMPTIONS-LIMITS.md) — honest limits of the assumptions engine
- [CHANGELOG.md](CHANGELOG.md) — release history (semver)

## Repo layout

The repo root is the product: the `proofofcontext/` package, the `poc` CLI,
`.context/` (this repo's own decision memory — the tool dogfoods itself),
`demo-sample/`, `docs/`, and the web pitch (`app.py`, deployed to Render via
`render.yaml` / `Dockerfile` — `pip install .[web]`).
