precheck 0.1.0__py3-none-any.whl

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/__main__.py

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

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())

precheck/core.py

@@ -0,0 +1,173 @@
+"""precheck core: commitments, the hash chain, and verification.
+
+The rule this tool exists to enforce:
+
+    The check must exist BEFORE the work it judges, and the actor under
+    judgement must not be able to edit it afterwards.
+
+So: the commitment file is frozen by hash at registration time, and every
+later verdict is appended to a hash-chained ledger. Editing either one is
+detectable by a third party who has nothing but the repo.
+"""
+import hashlib, json, os, time
+
+DIRNAME = ".precheck"
+COMMITMENTS = "commitments.json"
+LEDGER = "ledger.jsonl"
+MARKER = b"# precheck ledger v1\n"
+
+
+class PrecheckError(Exception):
+    pass
+
+
+def canonical(obj) -> bytes:
+    """Deterministic bytes for hashing. Key order and spacing fixed."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False).encode("utf-8")
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def store_dir(root: str = ".") -> str:
+    return os.path.join(root, DIRNAME)
+
+
+def commitments_path(root: str = ".") -> str:
+    return os.path.join(store_dir(root), COMMITMENTS)
+
+
+def ledger_path(root: str = ".") -> str:
+    return os.path.join(store_dir(root), LEDGER)
+
+
+def load_commitments(root: str = ".") -> dict:
+    p = commitments_path(root)
+    if not os.path.exists(p):
+        raise PrecheckError(
+            "no commitments file at %s -- run `precheck init` then edit it" % p)
+    with open(p, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict) or "commitments" not in data:
+        raise PrecheckError("commitments file must be an object with a "
+                            "'commitments' list")
+    return data
+
+
+def save_commitments(root: str, data: dict) -> None:
+    os.makedirs(store_dir(root), exist_ok=True)
+    with open(commitments_path(root), "w", encoding="utf-8", newline="\n") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2, sort_keys=False)
+        f.write("\n")
+
+
+def commitments_hash(root: str = ".") -> str:
+    """Hash of the commitments file on disk, right now."""
+    return sha256_file(commitments_path(root))
+
+
+def read_ledger(root: str = ".") -> list:
+    p = ledger_path(root)
+    if not os.path.exists(p):
+        return []
+    out = []
+    with open(p, "r", encoding="utf-8") as f:
+        for lineno, line in enumerate(f, 1):
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            try:
+                out.append(json.loads(line))
+            except ValueError as e:
+                raise PrecheckError("ledger line %d is not valid JSON: %s"
+                                    % (lineno, e))
+    return out
+
+
+def _entry_hash(entry: dict) -> str:
+    body = {k: v for k, v in entry.items() if k != "hash"}
+    return sha256_bytes(canonical(body))
+
+
+def append(root: str, kind: str, payload: dict) -> dict:
+    """Append one hash-chained entry to the ledger. Returns the entry."""
+    os.makedirs(store_dir(root), exist_ok=True)
+    entries = read_ledger(root)
+    entry = {
+        "seq": len(entries) + 1,
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "kind": kind,
+        "prev": entries[-1]["hash"] if entries else None,
+    }
+    entry.update(payload)
+    entry["hash"] = _entry_hash(entry)
+    p = ledger_path(root)
+    new = not os.path.exists(p)
+    with open(p, "a", encoding="utf-8", newline="\n") as f:
+        if new:
+            f.write(MARKER.decode())
+        f.write(json.dumps(entry, sort_keys=True, ensure_ascii=False) + "\n")
+    return entry
+
+
+def verify(root: str = ".") -> dict:
+    """Walk the chain and compare the frozen commitments to the live file.
+
+    Returns {"ok": bool, "entries": int, "findings": [...]}.
+    A finding is a question for a human, not a verdict: this function only
+    reports what it can check mechanically.
+    """
+    findings = []
+
+    def add(level, code, msg):
+        findings.append({"level": level, "code": code, "message": msg})
+
+    entries = read_ledger(root)
+    if not entries:
+        add("high", "NO_LEDGER",
+            "no ledger yet -- nothing has been registered or settled")
+        return {"ok": False, "entries": 0, "findings": findings}
+
+    for i, e in enumerate(entries):
+        if e.get("seq") != i + 1:
+            add("high", "SEQ_GAP",
+                "entry %d has seq=%r, expected %d" % (i + 1, e.get("seq"), i + 1))
+        if e.get("hash") != _entry_hash(e):
+            add("high", "HASH_MISMATCH",
+                "entry %d does not hash to its own recorded hash "
+                "(the entry body was edited)" % (i + 1))
+        want = entries[i - 1]["hash"] if i else None
+        if e.get("prev") != want:
+            add("high", "BROKEN_LINK",
+                "entry %d points at prev=%r but the previous entry's hash is %r"
+                % (i + 1, e.get("prev"), want))
+
+    regs = [e for e in entries if e.get("kind") == "register"]
+    if not regs:
+        add("high", "NOT_REGISTERED",
+            "no register entry -- checks were never frozen before the run")
+    else:
+        frozen = regs[-1].get("commitments_sha256")
+        live = commitments_hash(root)
+        if frozen != live:
+            add("high", "COMMITMENTS_MODIFIED",
+                "commitments file hash is %s but %s was frozen at seq=%s; "
+                "every verdict recorded after that point is void"
+                % (live[:12], (frozen or "?")[:12], regs[-1].get("seq")))
+        else:
+            add("info", "COMMITMENTS_FROZEN",
+                "commitments unchanged since seq=%s (%s)"
+                % (regs[-1].get("seq"), (frozen or "")[:12]))
+
+    ok = not any(f["level"] == "high" for f in findings)
+    return {"ok": ok, "entries": len(entries), "findings": findings}

precheck/runtime.py

@@ -0,0 +1,19 @@
+"""Running a check command and capturing its verdict."""
+import subprocess
+
+
+def run_check(cmd, cwd=".", timeout=600):
+    """Run one check command through the shell.
+
+    Returns (exit_code, output). exit_code is None when the check timed out --
+    that is deliberately distinct from a non-zero failure, because "did not
+    finish" and "said no" are different facts.
+    """
+    try:
+        p = subprocess.run(cmd, shell=True, cwd=cwd, timeout=timeout,
+                           stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+        return p.returncode, p.stdout.decode("utf-8", "replace")
+    except subprocess.TimeoutExpired:
+        return None, "TIMEOUT after %ss" % timeout
+    except OSError as e:
+        return 127, "could not start check: %s" % e

precheck/vacuity.py

@@ -0,0 +1,210 @@
+"""Vacuity audit -- a check that cannot fail proves nothing.
+
+Settle answers "did the check pass?". This module answers the harder
+question: "could it have failed at all?"
+
+For each declared artifact we apply a small, deterministic mutation
+(drop a line, blank a value, change a number, truncate a file), re-run the
+check, and restore the file byte-for-byte. A check that still passes on
+mutated input did not distinguish good from broken.
+
+Findings here are QUESTIONS, not accusations. A surviving mutation is often
+legitimate: the mutated line may be irrelevant to that particular claim.
+The tool reports what it saw and leaves the judgement to a human -- it never
+labels a check "useless" on its own.
+"""
+import json
+import os
+import random
+import re
+
+MUTATIONS = ("drop-line", "blank-value", "flip-number", "truncate")
+
+_FIELD = re.compile(r"^(\s*[\w.\-]+\s*[:=]\s*)(.+)$", re.M)
+_STRING = re.compile(r'"[^"\n]*"')
+_NUMBER = re.compile(r"(?<![\w.])-?\d+(?:\.\d+)?(?![\w.])")
+
+
+def decode(data: bytes):
+    """Text of a file, or None if it is not text (we never mutate binary)."""
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def _blank_like(value):
+    """Neuter a scalar: empty, zero, false -- but keep its type."""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return 0
+    if isinstance(value, str):
+        return ""
+    if isinstance(value, list):
+        return []
+    if isinstance(value, dict):
+        return {}
+    return None
+
+
+def _pick_json_scalar(obj, rng, path=()):
+    """Choose one leaf of a JSON document, deterministically."""
+    leaves = []
+
+    def walk(node, cur):
+        if isinstance(node, dict):
+            for k, v in node.items():
+                if isinstance(v, (dict, list)):
+                    walk(v, cur + (k,))
+                else:
+                    leaves.append((cur, k))
+        elif isinstance(node, list):
+            for i, v in enumerate(node):
+                if isinstance(v, (dict, list)):
+                    walk(v, cur + (i,))
+                else:
+                    leaves.append((cur, i))
+
+    walk(obj, ())
+    if not leaves:
+        return None
+    parent_path, key = rng.choice(leaves)
+    parent = obj
+    for step in parent_path:
+        parent = parent[step]
+    return parent, key
+
+
+def mutate(kind: str, text: str, rng: random.Random):
+    """Apply one mutation.
+
+    Returns (mutated_text, detail) or (None, None) if not applicable.
+    `detail` is the human-readable change, e.g. "replicas: 3 -> 0" -- it is the
+    whole point of the audit, because it is what a reader can act on.
+    """
+    lines = text.split("\n")
+    filled = [i for i, l in enumerate(lines) if l.strip()]
+
+    if kind == "drop-line":
+        if not filled:
+            return None, None
+        i = rng.choice(filled)
+        detail = "dropped line %d: %s" % (i + 1, lines[i].strip()[:60])
+        del lines[i]
+        return "\n".join(lines), detail
+
+    if kind == "truncate":
+        if len(filled) < 2:
+            return None, None
+        keep = max(1, len(lines) // 2)
+        return ("\n".join(lines[:keep]) + "\n",
+                "truncated to the first %d of %d lines" % (keep, len(lines)))
+
+    if kind == "blank-value":
+        try:
+            obj = json.loads(text)
+        except ValueError:
+            obj = None
+        if isinstance(obj, (dict, list)):
+            target = _pick_json_scalar(obj, rng)
+            if target is None:
+                return None, None
+            parent, key = target
+            old = parent[key]
+            parent[key] = _blank_like(old)
+            return (json.dumps(obj, ensure_ascii=False, indent=2) + "\n",
+                    "%s: %r -> %r" % (key, old, parent[key]))
+        hits = list(_FIELD.finditer(text))
+        if hits:
+            h = rng.choice(hits)
+            return (text[:h.start(2)] + '""' + text[h.end(2):],
+                    "%s: %r -> \"\"" % (h.group(1).strip(), h.group(2)[:40]))
+        hits = list(_STRING.finditer(text))
+        if hits:
+            h = rng.choice(hits)
+            return (text[:h.start()] + '""' + text[h.end():],
+                    "%s -> \"\"" % h.group(0)[:40])
+        return None, None
+
+    if kind == "flip-number":
+        hits = list(_NUMBER.finditer(text))
+        if not hits:
+            return None, None
+        h = rng.choice(hits)
+        raw = h.group(0)
+        try:
+            value = float(raw) if "." in raw else int(raw)
+        except ValueError:
+            return None, None
+        new = value + (1 if value == 0 else (7 if value > 0 else -7))
+        new_text = text[:h.start()] + str(new) + text[h.end():]
+        start = text.rfind("\n", 0, h.start()) + 1
+        end = text.find("\n", h.start())
+        if end == -1:
+            end = len(text)
+        delta = len(str(new)) - len(raw)
+        return (new_text,
+                "%s -> %s" % (text[start:end].strip()[:60],
+                              new_text[start:end + delta].strip()[:60]))
+
+    return None, None
+
+
+def audit(root, commitments, mutations=MUTATIONS, seed=0, timeout=600,
+          runner=None, on_event=None):
+    """Mutate each declared artifact, re-run each check, restore, report.
+
+    A check that exits 0 on mutated input is recorded as ESCAPED: we could
+    not make it say no, so it is not yet evidence for the claim.
+    """
+    if runner is None:
+        from .runtime import run_check as runner
+
+    escaped = []
+    examined = 0
+    skipped = []
+
+    for c in commitments.get("commitments", []):
+        cid = c.get("id") or c.get("statement", "?")[:24]
+        for art in c.get("artifacts", []):
+            path = os.path.join(root, art)
+            if not os.path.isfile(path):
+                skipped.append({"id": cid, "artifact": art,
+                                "why": "artifact not found"})
+                continue
+            with open(path, "rb") as f:
+                original = f.read()
+            text = decode(original)
+            if text is None:
+                skipped.append({"id": cid, "artifact": art,
+                                "why": "not a text file"})
+                continue
+            for kind in mutations:
+                rng = random.Random("%s|%s|%s|%s" % (seed, cid, art, kind))
+                mutated, detail = mutate(kind, text, rng)
+                if mutated is None:
+                    continue
+                examined += 1
+                try:
+                    with open(path, "w", encoding="utf-8", newline="") as f:
+                        f.write(mutated)
+                    code, out = runner(c["check"], cwd=root, timeout=timeout)
+                finally:
+                    with open(path, "wb") as f:
+                        f.write(original)
+                if on_event:
+                    on_event(cid, art, kind, code, detail)
+                if code == 0:
+                    escaped.append({
+                        "id": cid, "artifact": art, "mutation": kind,
+                        "detail": detail,
+                        "statement": c.get("statement", ""),
+                        "check": c["check"],
+                        "question": ("%s -- and the check still passed. Either "
+                                     "that line does not matter to the claim, "
+                                     "or the check would pass on broken input."
+                                     % detail),
+                    })
+
+    return {"examined": examined, "escaped": escaped, "skipped": skipped}

precheck-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+precheck/__init__.py,sha256=5Je6kXewdbhaKP8U3_ZV9rCdwXM7GsrkGnE6CI6MFRo,193
+precheck/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+precheck/cli.py,sha256=GBOwjlnMIOX6HGST2cQYIo_oQ3VaV0vf4Z5PQf0YoSM,7962
+precheck/core.py,sha256=-sE-S8hMLjm4DZmwCpTlNccpTjk3bA3lWXwIbYli6dE,5991
+precheck/runtime.py,sha256=JVHwfYfP_c_0aZDW71SjnO_mc8pC-r11Iq5-lIjVXNI,765
+precheck/vacuity.py,sha256=ACHxu4C2m8MUXdh3hhSCTVyohkjL-AWZcfgvrdWCWZE,7541
+precheck-0.1.0.dist-info/licenses/LICENSE,sha256=tUi9TGPPA2R_6XEKLiH99YG2h-nCZCI4jO0aQj2RrN4,1067
+precheck-0.1.0.dist-info/METADATA,sha256=JFqxZTr-El8yemtjMBIj45uDntnjAwJWINulYXt6sjg,8384
+precheck-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+precheck-0.1.0.dist-info/entry_points.txt,sha256=gz5Sm9P59qYqSUpLtzgv0MjXW0KAMZoJbZKhnbdC8GA,47
+precheck-0.1.0.dist-info/top_level.txt,sha256=oNtdDWmkxOPJtmWpo2p0gQnarhS0hvQukgybIWIre60,9
+precheck-0.1.0.dist-info/RECORD,,

precheck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

precheck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+precheck = precheck.cli:main

precheck-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+precheck