precheck 0.1.0__tar.gz

precheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simin Yuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

precheck-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: precheck
+Version: 0.1.0
+Summary: Make an agent prove its claims with checks it was not allowed to write. The check is frozen before the run, and audited for the ability to fail at all.
+Author: Simin Yuan
+License: MIT
+Project-URL: Homepage, https://github.com/simin-yuan/precheck
+Project-URL: Issues, https://github.com/simin-yuan/precheck/issues
+Keywords: agents,ai-agents,verification,audit,mutation-testing,llm,ci,trust,evidence
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/banner.svg" alt="precheck" width="880">
+</p>
+
+<h1 align="center">precheck</h1>
+
+<p align="center"><b>Make an agent prove its claims with checks it was not allowed to write.</b></p>
+
+<p align="center">
+  <a href="https://github.com/simin-yuan/precheck/actions/workflows/tests.yml"><img alt="tests" src="https://github.com/simin-yuan/precheck/actions/workflows/tests.yml/badge.svg"></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue">
+  <img alt="python" src="https://img.shields.io/badge/python-3.8%2B-blue">
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen">
+  <img alt="network" src="https://img.shields.io/badge/network-none-lightgrey">
+</p>
+
+---
+
+An agent finishes and reports success. Today you can believe it, or re-read
+every diff yourself. `precheck` is a third option.
+
+It does two things a test runner does not:
+
+1. **It freezes the check before the run.** The acceptance check is written and
+   hash-locked *before* the work happens, so the actor cannot tailor the test to
+   whatever it ended up producing. Edit the check afterwards and every verdict
+   after that point is void — provably, not by convention.
+2. **It asks whether the check could have failed at all.** After a check passes,
+   `precheck` mutates the artifact it was judging and runs it again. A check that
+   still passes on broken input was never evidence for anything.
+
+## What that looks like
+
+Every line below is real output from `python demo.py` in this repository. (The
+trailing `(exit N)` annotations it prints, and its temp-directory line, are
+omitted here.)
+
+```
+$ precheck register
+froze 1 commitment(s) at seq=1  sha256=e2d4561aa9f0
+
+$ precheck settle
+PASS  the deployment config is valid and safe to ship
+
+1/1 passed  (seq=2)
+
+$ precheck audit
+ran 4 mutation(s) across the declared artefacts
+
+2 check/mutation pair(s) survived -- these prove nothing yet:
+  ? C1  [blank-value on config.json]
+      replicas: 3 -> 0
+      the check still exited 0
+  ? C1  [flip-number on config.json]
+      "replicas": 3, -> "replicas": 10,
+      the check still exited 0
+
+This is a question list, not a bug list. Some survivors are legitimate.
+
+$ precheck verify
+. commitments unchanged since seq=1 (e2d4561aa9f0)
+
+3 entries; chain consistent
+```
+
+The check caught a broken file. It did not catch a config that would take
+production down: `replicas: 3` became `0` and the check still said yes. That is
+the failure mode this tool exists for.
+
+## Install
+
+Not on PyPI yet. Two ways to use it today, both of which work right now:
+
+```
+# install straight from the repository
+pip install git+https://github.com/simin-yuan/precheck.git
+
+# or run it in place -- it is pure standard library, no install needed
+git clone https://github.com/simin-yuan/precheck
+cd precheck && python demo.py
+```
+
+Zero runtime dependencies, standard library only, no network calls.
+Python 3.8+.
+
+## Use it
+
+Three commands you run in order, and one anyone can run afterwards.
+
+```
+precheck init          # writes .precheck/commitments.json
+#   ... edit it: state the claim, the check, and the artifacts it is about
+precheck register      # freeze it -- do this BEFORE the work runs
+#   ... whatever produces the artifact runs here ...
+precheck settle        # run the frozen checks, record PASS / FAIL / TIMEOUT
+precheck audit         # mutate the artifacts; find checks that cannot fail
+precheck verify        # walk the hash chain; detect edited history
+```
+
+`settle` exits `2` on any failure. `audit --strict` exits `3` if a check survived
+a mutation. `verify` exits `1` if the chain is broken. All three drop straight
+into CI.
+
+### As a GitHub Action
+
+```yaml
+jobs:
+  verify-the-agent:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: simin-yuan/precheck@main
+        with:
+          command: audit     # settle, then mutate and re-run
+          strict: "true"     # fail the job if a check could not fail
+```
+
+Put `precheck register` in the job *before* the step that produces the artifact.
+A check frozen after the fact is reported as `NOT_REGISTERED`, and `verify` fails.
+
+### The commitments file
+
+```json
+{
+  "version": 1,
+  "commitments": [
+    {
+      "id": "C1",
+      "statement": "the deployment config is valid and safe to ship",
+      "check": "python check_config.py",
+      "artifacts": ["config.json"]
+    }
+  ]
+}
+```
+
+`check` is any shell command whose exit code decides the claim. `artifacts` are
+the files that claim is about — the audit mutates those.
+
+### Mutations
+
+`drop-line` · `blank-value` · `flip-number` · `truncate`
+
+Deterministic given `--seed`, so a survivor is reproducible and can be argued
+about. Binary files are never mutated.
+
+## Why not just use pytest?
+
+`pytest` asks *is the code right?* `precheck` asks *is your proof right?* They
+are different questions, and the second one currently has no tooling:
+
+- `pytest` has no opinion on who wrote the test, or when. `precheck` refuses a
+  check that was written after the result it judges.
+- `pytest` cannot tell you that a passing test would also pass on a broken
+  file. `precheck` mutates and re-runs to find out.
+- `pytest` results live in your terminal. `precheck` records them in a chain a
+  third party can verify without trusting you.
+
+You keep using pytest. You point `precheck` at it.
+
+## How the tamper-evidence works
+
+Each ledger entry is canonical JSON (sorted keys, fixed separators), and holds
+`prev` — the previous entry's sha256 — plus its own hash. Editing any byte of any
+entry re-hashes to something different, and deleting an entry breaks the link
+after it. `verify` re-walks the whole file and reports:
+
+| finding | meaning |
+|---|---|
+| `HASH_MISMATCH` | an entry's body was edited |
+| `BROKEN_LINK` | an entry was deleted, or its predecessor was replaced |
+| `SEQ_GAP` | entries were removed from the middle |
+| `COMMITMENTS_MODIFIED` | the check was rewritten after it was frozen |
+| `NOT_REGISTERED` | checks were never frozen at all |
+
+Commit `.precheck/` with your code. That is the point — a reader can re-run
+`precheck verify` on your repository and see for themselves.
+
+## Limits — read this before you trust it
+
+- **A surviving mutation is a question, not a bug.** The mutated line may be
+  genuinely irrelevant to the claim. `precheck` will not tell you which; a human
+  decides.
+- **Surviving every mutation is not proof that a check is vacuous.** The
+  mutations are a fixed sample of four. A check can be useless in ways this
+  sample never touches.
+- **The chain proves history was not edited after the fact. It does not prove
+  the first entry was honest.** Whoever writes the first `register` entry can
+  still write a weak check. Pre-registration raises the cost of gaming the
+  result; it does not make gaming impossible.
+- **A weak artifact list defeats it.** If you declare no artifacts, there is
+  nothing to mutate and `audit` will honestly report that it examined nothing.
+  Declare the files the claim is actually about.
+- **Exit codes only.** `precheck` has no idea what your check *means*. A check
+  that prints a lie and exits 0 is a check that passes.
+
+## Status
+
+Alpha. 19 unit tests over the chain, the freeze, and the audit; a runnable
+end-to-end demo; no dependencies. The audit's mutation set is deliberately small
+and readable — adding mutations that you cannot explain to a reader would make
+the output less trustworthy, not more.
+
+## License
+
+MIT © 2026 Simin Yuan
+

precheck-0.1.0/README.md

@@ -0,0 +1,207 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="precheck" width="880">
+</p>
+
+<h1 align="center">precheck</h1>
+
+<p align="center"><b>Make an agent prove its claims with checks it was not allowed to write.</b></p>
+
+<p align="center">
+  <a href="https://github.com/simin-yuan/precheck/actions/workflows/tests.yml"><img alt="tests" src="https://github.com/simin-yuan/precheck/actions/workflows/tests.yml/badge.svg"></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue">
+  <img alt="python" src="https://img.shields.io/badge/python-3.8%2B-blue">
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen">
+  <img alt="network" src="https://img.shields.io/badge/network-none-lightgrey">
+</p>
+
+---
+
+An agent finishes and reports success. Today you can believe it, or re-read
+every diff yourself. `precheck` is a third option.
+
+It does two things a test runner does not:
+
+1. **It freezes the check before the run.** The acceptance check is written and
+   hash-locked *before* the work happens, so the actor cannot tailor the test to
+   whatever it ended up producing. Edit the check afterwards and every verdict
+   after that point is void — provably, not by convention.
+2. **It asks whether the check could have failed at all.** After a check passes,
+   `precheck` mutates the artifact it was judging and runs it again. A check that
+   still passes on broken input was never evidence for anything.
+
+## What that looks like
+
+Every line below is real output from `python demo.py` in this repository. (The
+trailing `(exit N)` annotations it prints, and its temp-directory line, are
+omitted here.)
+
+```
+$ precheck register
+froze 1 commitment(s) at seq=1  sha256=e2d4561aa9f0
+
+$ precheck settle
+PASS  the deployment config is valid and safe to ship
+
+1/1 passed  (seq=2)
+
+$ precheck audit
+ran 4 mutation(s) across the declared artefacts
+
+2 check/mutation pair(s) survived -- these prove nothing yet:
+  ? C1  [blank-value on config.json]
+      replicas: 3 -> 0
+      the check still exited 0
+  ? C1  [flip-number on config.json]
+      "replicas": 3, -> "replicas": 10,
+      the check still exited 0
+
+This is a question list, not a bug list. Some survivors are legitimate.
+
+$ precheck verify
+. commitments unchanged since seq=1 (e2d4561aa9f0)
+
+3 entries; chain consistent
+```
+
+The check caught a broken file. It did not catch a config that would take
+production down: `replicas: 3` became `0` and the check still said yes. That is
+the failure mode this tool exists for.
+
+## Install
+
+Not on PyPI yet. Two ways to use it today, both of which work right now:
+
+```
+# install straight from the repository
+pip install git+https://github.com/simin-yuan/precheck.git
+
+# or run it in place -- it is pure standard library, no install needed
+git clone https://github.com/simin-yuan/precheck
+cd precheck && python demo.py
+```
+
+Zero runtime dependencies, standard library only, no network calls.
+Python 3.8+.
+
+## Use it
+
+Three commands you run in order, and one anyone can run afterwards.
+
+```
+precheck init          # writes .precheck/commitments.json
+#   ... edit it: state the claim, the check, and the artifacts it is about
+precheck register      # freeze it -- do this BEFORE the work runs
+#   ... whatever produces the artifact runs here ...
+precheck settle        # run the frozen checks, record PASS / FAIL / TIMEOUT
+precheck audit         # mutate the artifacts; find checks that cannot fail
+precheck verify        # walk the hash chain; detect edited history
+```
+
+`settle` exits `2` on any failure. `audit --strict` exits `3` if a check survived
+a mutation. `verify` exits `1` if the chain is broken. All three drop straight
+into CI.
+
+### As a GitHub Action
+
+```yaml
+jobs:
+  verify-the-agent:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: simin-yuan/precheck@main
+        with:
+          command: audit     # settle, then mutate and re-run
+          strict: "true"     # fail the job if a check could not fail
+```
+
+Put `precheck register` in the job *before* the step that produces the artifact.
+A check frozen after the fact is reported as `NOT_REGISTERED`, and `verify` fails.
+
+### The commitments file
+
+```json
+{
+  "version": 1,
+  "commitments": [
+    {
+      "id": "C1",
+      "statement": "the deployment config is valid and safe to ship",
+      "check": "python check_config.py",
+      "artifacts": ["config.json"]
+    }
+  ]
+}
+```
+
+`check` is any shell command whose exit code decides the claim. `artifacts` are
+the files that claim is about — the audit mutates those.
+
+### Mutations
+
+`drop-line` · `blank-value` · `flip-number` · `truncate`
+
+Deterministic given `--seed`, so a survivor is reproducible and can be argued
+about. Binary files are never mutated.
+
+## Why not just use pytest?
+
+`pytest` asks *is the code right?* `precheck` asks *is your proof right?* They
+are different questions, and the second one currently has no tooling:
+
+- `pytest` has no opinion on who wrote the test, or when. `precheck` refuses a
+  check that was written after the result it judges.
+- `pytest` cannot tell you that a passing test would also pass on a broken
+  file. `precheck` mutates and re-runs to find out.
+- `pytest` results live in your terminal. `precheck` records them in a chain a
+  third party can verify without trusting you.
+
+You keep using pytest. You point `precheck` at it.
+
+## How the tamper-evidence works
+
+Each ledger entry is canonical JSON (sorted keys, fixed separators), and holds
+`prev` — the previous entry's sha256 — plus its own hash. Editing any byte of any
+entry re-hashes to something different, and deleting an entry breaks the link
+after it. `verify` re-walks the whole file and reports:
+
+| finding | meaning |
+|---|---|
+| `HASH_MISMATCH` | an entry's body was edited |
+| `BROKEN_LINK` | an entry was deleted, or its predecessor was replaced |
+| `SEQ_GAP` | entries were removed from the middle |
+| `COMMITMENTS_MODIFIED` | the check was rewritten after it was frozen |
+| `NOT_REGISTERED` | checks were never frozen at all |
+
+Commit `.precheck/` with your code. That is the point — a reader can re-run
+`precheck verify` on your repository and see for themselves.
+
+## Limits — read this before you trust it
+
+- **A surviving mutation is a question, not a bug.** The mutated line may be
+  genuinely irrelevant to the claim. `precheck` will not tell you which; a human
+  decides.
+- **Surviving every mutation is not proof that a check is vacuous.** The
+  mutations are a fixed sample of four. A check can be useless in ways this
+  sample never touches.
+- **The chain proves history was not edited after the fact. It does not prove
+  the first entry was honest.** Whoever writes the first `register` entry can
+  still write a weak check. Pre-registration raises the cost of gaming the
+  result; it does not make gaming impossible.
+- **A weak artifact list defeats it.** If you declare no artifacts, there is
+  nothing to mutate and `audit` will honestly report that it examined nothing.
+  Declare the files the claim is actually about.
+- **Exit codes only.** `precheck` has no idea what your check *means*. A check
+  that prints a lie and exits 0 is a check that passes.
+
+## Status
+
+Alpha. 19 unit tests over the chain, the freeze, and the audit; a runnable
+end-to-end demo; no dependencies. The audit's mutation set is deliberately small
+and readable — adding mutations that you cannot explain to a reader would make
+the output less trustworthy, not more.
+
+## License
+
+MIT © 2026 Simin Yuan
+

precheck-0.1.0/precheck/__init__.py

@@ -0,0 +1,5 @@
+"""precheck -- make an agent prove its claims with checks it was not allowed
+to write. The check is frozen before the run, and audited for the ability to
+fail at all.
+"""
+__version__ = "0.1.0"

precheck-0.1.0/precheck/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

precheck-0.1.0/precheck/cli.py

@@ -0,0 +1,210 @@
+"""precheck command line.
+
+    precheck init                    write a commitments template
+    precheck register                freeze the commitments, before the run
+    precheck settle                  run the frozen checks, record verdicts
+    precheck audit                   mutate artefacts, find checks that can't fail
+    precheck verify                  walk the chain, detect edited history
+    precheck status                  one-screen summary
+"""
+import argparse
+import json
+import os
+import sys
+
+from . import core
+from .core import PrecheckError
+from .runtime import run_check
+from .vacuity import MUTATIONS, audit
+
+TEMPLATE = {
+    "version": 1,
+    "note": ("Write the check BEFORE the work it judges. `check` is a shell "
+             "command whose exit code decides the claim; `artifacts` are the "
+             "files that claim is about (used by `precheck audit`)."),
+    "commitments": [
+        {
+            "id": "C1",
+            "statement": "replace me: what is being claimed",
+            "check": "replace me: a command that exits non-zero if it is false",
+            "artifacts": ["replace/me.txt"],
+        }
+    ],
+}
+
+
+def _fail(msg, code=1):
+    print(msg, file=sys.stderr)
+    return code
+
+
+def cmd_init(args):
+    p = core.commitments_path(args.root)
+    if os.path.exists(p):
+        return _fail("%s already exists -- not overwriting" % p)
+    core.save_commitments(args.root, TEMPLATE)
+    print("wrote %s" % p)
+    print("edit it, then: precheck register")
+    return 0
+
+
+def cmd_register(args):
+    data = core.load_commitments(args.root)
+    if not data.get("commitments"):
+        return _fail("commitments list is empty -- nothing to freeze")
+    h = core.commitments_hash(args.root)
+    entry = core.append(args.root, "register",
+                        {"commitments_sha256": h,
+                         "count": len(data["commitments"]),
+                         "ids": [c.get("id") for c in data["commitments"]]})
+    print("froze %d commitment(s) at seq=%s  sha256=%s"
+          % (len(data["commitments"]), entry["seq"], h[:12]))
+    return 0
+
+
+def cmd_settle(args):
+    data = core.load_commitments(args.root)
+    results = []
+    for c in data.get("commitments", []):
+        cid = c.get("id", "?")
+        code, out = run_check(c["check"], cwd=args.root, timeout=args.timeout)
+        if code is None:
+            verdict = "TIMEOUT"
+        elif code == 0:
+            verdict = "PASS"
+        else:
+            verdict = "FAIL"
+        results.append({"id": cid, "verdict": verdict, "exit": code,
+                        "statement": c.get("statement", ""),
+                        "check": c["check"]})
+        print("%-5s %s" % (verdict, c.get("statement") or cid))
+        if verdict != "PASS" and args.verbose:
+            print("      $ %s\n      exit=%s\n%s" % (c["check"], code, out.rstrip()))
+
+    entry = core.append(args.root, "settle", {"results": results})
+    bad = [r for r in results if r["verdict"] != "PASS"]
+    print("\n%d/%d passed  (seq=%s)" % (len(results) - len(bad), len(results),
+                                        entry["seq"]))
+    if args.json:
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    return 0 if not bad else 2
+
+
+def cmd_audit(args):
+    data = core.load_commitments(args.root)
+    kinds = tuple(k.strip() for k in args.mutations.split(",") if k.strip())
+    bad = [k for k in kinds if k not in MUTATIONS]
+    if bad:
+        return _fail("unknown mutation(s): %s (known: %s)"
+                     % (", ".join(bad), ", ".join(MUTATIONS)))
+
+    def on_event(cid, art, kind, code, detail):
+        if args.verbose:
+            print("   %s %s on %s -> exit=%s  [%s]" % (cid, kind, art, code, detail))
+
+    res = audit(args.root, data, mutations=kinds, seed=args.seed,
+                timeout=args.timeout, on_event=on_event)
+    entry = core.append(args.root, "audit",
+                        {"examined": res["examined"],
+                         "escaped": res["escaped"],
+                         "skipped": res["skipped"],
+                         "seed": args.seed,
+                         "mutations": list(kinds)})
+
+    print("ran %d mutation(s) across the declared artefacts" % res["examined"])
+    for s in res["skipped"]:
+        print("  skipped %s (%s: %s)" % (s["artifact"], s["why"], s["id"]))
+    if res["escaped"]:
+        print("\n%d check/mutation pair(s) survived -- these prove nothing yet:"
+              % len(res["escaped"]))
+        for e in res["escaped"]:
+            print("  ? %s  [%s on %s]" % (e["id"], e["mutation"], e["artifact"]))
+            print("      %s" % e.get("detail", ""))
+            print("      the check still exited 0")
+        print("\nThis is a question list, not a bug list. Some survivors are "
+              "legitimate.")
+    else:
+        print("every mutation was caught by its check.")
+    print("(seq=%s)" % entry["seq"])
+    if args.strict and res["escaped"]:
+        return 3
+    return 0
+
+
+def cmd_verify(args):
+    res = core.verify(args.root)
+    for f in res["findings"]:
+        mark = {"high": "!", "info": "."}.get(f["level"], ".")
+        print("%s %s" % (mark, f["message"]))
+    print("\n%d %s; chain %s"
+          % (res["entries"], "entry" if res["entries"] == 1 else "entries",
+             "consistent" if res["ok"] else "BROKEN"))
+    return 0 if res["ok"] else 1
+
+
+def cmd_status(args):
+    try:
+        data = core.load_commitments(args.root)
+        n = len(data.get("commitments", []))
+    except PrecheckError as e:
+        return _fail(str(e))
+    entries = core.read_ledger(args.root)
+    kinds = {}
+    for e in entries:
+        kinds[e.get("kind")] = kinds.get(e.get("kind"), 0) + 1
+    last = entries[-1] if entries else None
+    print("commitments : %d" % n)
+    print("ledger      : %d entries %s" % (len(entries), kinds or ""))
+    if last:
+        print("head        : seq=%s kind=%s %s" % (last.get("seq"),
+                                                   last.get("kind"),
+                                                   (last.get("hash") or "")[:12]))
+    v = core.verify(args.root)
+    print("chain       : %s" % ("ok" if v["ok"] else "BROKEN"))
+    for f in v["findings"]:
+        if f["level"] == "high":
+            print("  ! %s" % f["message"])
+    return 0 if v["ok"] else 1
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="precheck", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--root", default=".", help="repository root (default: .)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("init", help="write a commitments template").set_defaults(
+        func=cmd_init)
+    sub.add_parser("register", help="freeze commitments before the run"
+                   ).set_defaults(func=cmd_register)
+
+    s = sub.add_parser("settle", help="run the frozen checks")
+    s.add_argument("--timeout", type=int, default=600)
+    s.add_argument("--json", action="store_true")
+    s.add_argument("-v", "--verbose", action="store_true")
+    s.set_defaults(func=cmd_settle)
+
+    a = sub.add_parser("audit", help="find checks that cannot fail")
+    a.add_argument("--mutations", default=",".join(MUTATIONS))
+    a.add_argument("--seed", type=int, default=0)
+    a.add_argument("--timeout", type=int, default=600)
+    a.add_argument("--strict", action="store_true",
+                   help="exit non-zero if any mutation survived (for CI)")
+    a.add_argument("-v", "--verbose", action="store_true")
+    a.set_defaults(func=cmd_audit)
+
+    sub.add_parser("verify", help="walk the chain").set_defaults(func=cmd_verify)
+    sub.add_parser("status", help="summary").set_defaults(func=cmd_status)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except PrecheckError as e:
+        return _fail("precheck: %s" % e)
+
+
+if __name__ == "__main__":
+    sys.exit(main())