Metadata-Version: 2.4
Name: verify-engineer
Version: 0.3.1
Summary: VERIFY Engineer — probabilistic construction; deterministic acceptance.
Author: Devin Bostick
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://verifyrun.com
Keywords: governance,decision,policy,verification,agents,audit
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: verify-run==0.1.0a3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Dynamic: license-file

# VERIFY Engineer

Your software already contains consequential decisions — the places where a proposal becomes a
commitment, and money moves, or a record changes, or something is sent. VERIFY Engineer finds
them, helps make the rules that govern them explicit, and checks what actually changed when you
repair one.

It runs locally. It has no account, no key, and no model of its own.

## Install

```bash
pipx install verify-engineer      # recommended: an isolated environment for the command
pip install verify-engineer       # or into an environment you already have
```

One dependency, `verify-run`, the runtime that settles decisions. Both are public packages.
Nothing else is fetched, and nothing is sent anywhere.

## 30-second start

```bash
verify-engineer inspect .
```

That is the whole first step. It reads your repository with a real parser, reports every place
something could be committed, and says plainly what it could not settle. It writes nothing into
your repository.

Add `--out result.json` and you get the same facts as typed data.

## Use it from Claude Code or Codex

Engineer is a command-line tool with machine-readable output at every step, so a coding agent
that already has your repository can drive it. Paste this:

> Run VERIFY Engineer on this repository. Start by inspecting it. Explain what it finds in
> ordinary language. Follow its typed next actions, and use `--out` so you are reading data
> rather than my terminal. Help me draft the values it says may be drafted. Ask me for the
> decisions it refuses to invent — do not make those for me. When a repair exists, build the
> candidate separately from the current system, run the declared scenarios against both, and
> report VERIFY's comparison and its improvement claim exactly as given. Do not make its claims
> stronger in your own words.

You bring the agent. VERIFY brings the part an agent does not have: a place where construction
stops and a claim becomes checkable. See [AGENT_HOST.md](AGENT_HOST.md).

## What happens

```text
inspect      where in this repository something could be committed
scaffold     turn one of those into a declaration skeleton — every decision marked UNRESOLVED
assist       optionally have a provider draft the fields it is allowed to draft
declare      you declare the rest; Engineer will not fill them in
govern       compile it, and say what is still open
prove        run your own predictions against the real runtime
repair       one typed change, then a second candidate
compare      current against candidate, over the cases they share
```

## What it will not do, stated up front

VERIFY does not discover what your policy ought to be. It reads your repository and finds where
something could be committed; what should happen there is a decision about your institution, and
it is yours. On a repository with no declaration yet, `inspect` and `scaffold` do the mechanical
part in about a second, and `govern` then shows you what remains — on the example below, 24
decisions grouped into 6 questions, every one of them yours to answer. Nothing infers them from
your code, your tests, your comments or your README, and nothing fills them in because a model
sounded confident.

That is the boundary, and it is deliberate: a rule nobody decided, governing real money, is the
failure this tool exists to prevent. Everything after the declaration is proven and automatic.

Once a declaration and a sealed set of scenarios exist, the last four steps are one command:

```text
fix          repair a finding and test whether the repair actually helped
```

`fix` enumerates the repairs your declaration's own structure determines, applies one — and
only if there is exactly one, because choosing between two lawful repairs is your decision —
builds a candidate with its own identity, runs both sides against the same cases and the real
runtime, and compares them. It adopts nothing and deploys nothing. Every command it composes
is still there, and every artifact it produced is written beside the run:

```text
VERIFY found 1 contradiction in store/policy.py.
`past-window-gold` can never run: every case it matches is already handled by
`past-window`, which is declared first.

  repaired the candidate
  re-tested the same 3 cases
  receipts verified
  replay recomputed identically

  s3.past-window-gold: BLOCK → ALLOW

  3 cases compared · 1 disagreement resolved · 0 introduced
  cases settled by a rule somebody wrote: 3/3 → 3/3

Yes — this candidate is better on the decisions we can compare.
Not adopted or deployed.
```

## Example

From a run against a seeded repository, produced by `scripts/zero_to_governed.py`:

```text
7 consequential site(s) across 11 file(s)
24 decision(s) the scaffold left for a person
   17 a provider may draft · 7 it names and refuses, with the reason for each
   grouped into 6 questions, not 24

COMPILED  ct1-d7c1f5f6…
5 of 5 case(s) settled as predicted, against the real runtime

the rule somebody added for this case did not fire; the general one above it did
```

and after a typed repair:

```text
Yes — this candidate is better on the decisions we can compare.
```

or, when a candidate looks better because it stopped governing something:

```text
claim withheld: ['GM.COVERAGE_REDUCED', 'GM.BRANCH_EXCLUDED']
```

Every number above came from executing the thing. None of it is written into a demo script.

## What VERIFY will not decide for you

This is the part that makes the rest worth trusting.

- **It will not invent a missing fact.** A value nobody declared is reported as UNRESOLVED, by
  name, with what would settle it.
- **It will not write a rule's outcome.** A model that can write BLOCK can write ALLOW, and the
  distance between those is somebody's money. Seven of the twenty-four fields above are refused
  for reasons like that one, each stated.
- **It will not rank your findings.** There is no impact score, because a canonical one would
  need a basis nothing here has. Where the structure your declaration already contains puts one
  finding ahead of another, it says so and shows the relation. Where it does not, you get two
  findings and a sentence saying neither comes first.
- **It will not decide whether an action is allowed.** Only the installed `verify-run` runtime
  does that, at the moment the action is attempted.
- **It will not authorize anything.** A met condition is arithmetic. Promotion is authority, and
  it belongs to the people who declared it.
- **It will not tell you a change improved things unless it can.** When the candidate moved the
  population it was measured over, the claim is withheld and the reason is given.

## Local and private

Nothing leaves your machine. There is no telemetry, no account, no key, and no network client
anywhere in the product — proved structurally, by reading the installed package's imports, in
`scripts/release_battery.py`.

Engineer is also disposable on purpose: install a governed boundary, delete Engineer, and
nothing operational changes. The rules keep governing and the records keep verifying. That is a
tested property (`scripts/kill_harness.py`), not a promise.

## VERIFY Platform

Engineer is built for local use by one developer and stays that way.

Teams that need shared decision systems that persist, organizational identity and authority,
lifecycle and promotion controls, managed evidence, centralized history or enterprise deployment
can write to **hello@verifyrun.com** about VERIFY Platform.

## Licence, and what "free" means here

Free to install and use, for anything, including commercially, on as many machines and by as many
people as you like. No account, no key, no payment, and no expiry on a version you have already
installed.

**It is not open source.** The licence does not grant redistribution, republishing, or offering
it to third parties as a service. You may read the source and modify your own copy for your own
use — and you can read it, because a pure-Python package ships the `.py` files that run. Publishing
this package makes the distributed implementation inspectable, which is a deliberate decision and
not an accident of packaging. The canonical repository, its history and its tests remain private.

Full terms in [LICENSE](LICENSE). For anything the licence does not grant: **hello@verifyrun.com**.

## Deeper documentation

| | |
|---|---|
| [AGENT_HOST.md](AGENT_HOST.md) | driving Engineer from a coding agent |
| [PUBLICATION.md](PUBLICATION.md) | the published contract and how to pin it |
| [START_HERE.md](START_HERE.md) | reading order for the whole repository |
| [PRODUCT_BOUNDARY.md](PRODUCT_BOUNDARY.md) | what this is and is not |

Requires Python 3.11 or later.
