agentproof-cli 0.3.0__py3-none-any.whl

agentproof/__init__.py

@@ -0,0 +1,2 @@
+"""AgentProof: evidence for AI coding tasks."""
+__version__ = "0.3.0"

agentproof/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

agentproof/cli.py

@@ -0,0 +1,513 @@
+"""Dependency-free local task evidence. Never interprets model claims as proof."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import time
+import uuid
+
+from . import __version__
+
+STORE = ".agentproof"
+MAX_FILE = 10 * 1024 * 1024
+MAX_TOTAL = 100 * 1024 * 1024
+
+
+def terminate_process_group(proc):
+    """Terminate a timed-out command on POSIX and Windows."""
+    if os.name == "nt":
+        proc.kill()
+    else:
+        import signal
+        os.killpg(proc.pid, signal.SIGKILL)
+    proc.wait()
+
+
+def now():
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def save(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+def load(path):
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def git(root, *args):
+    result = subprocess.run(["git", "-C", str(root), *args], capture_output=True)
+    if result.returncode:
+        raise ValueError(result.stderr.decode(errors="replace").strip())
+    return result.stdout
+
+
+def safe_path(root, name):
+    p = Path(name)
+    if p.is_absolute() or ".." in p.parts or not p.parts or p.parts[0] in (".git", STORE):
+        raise ValueError(f"Unsafe snapshot path: {name}")
+    target = root / p
+    # Reject symlinks in every component, including the file itself.
+    if any(x.is_symlink() for x in [target, *target.parents] if x != root.parent):
+        raise ValueError(f"Symlink path is not supported: {name}")
+    if not target.resolve().is_relative_to(root.resolve()):
+        raise ValueError(f"Path escapes repository: {name}")
+    return target
+
+
+def sensitive(name):
+    p = Path(name)
+    return (p.name == ".env" or p.name.startswith(".env.") or
+            p.suffix.lower() in (".pem", ".key", ".p12", ".pfx") or
+            p.name in ("id_rsa", "id_ed25519", "credentials.json"))
+
+
+def inventory(root):
+    names = git(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard")
+    files, omitted, total = {}, [], 0
+    for name in sorted(set(os.fsdecode(x) for x in names.split(b"\0") if x)):
+        if Path(name).parts[0] == STORE:
+            continue
+        if sensitive(name):
+            omitted.append({"path": name, "reason": "sensitive filename"})
+            continue
+        try:
+            path = safe_path(root, name)
+        except ValueError:
+            omitted.append({"path": name, "reason": "symlink or unsafe path"})
+            continue
+        if not path.exists():
+            continue
+        if not path.is_file():
+            omitted.append({"path": name, "reason": "not a regular file (possibly submodule)"})
+            continue
+        if path.stat().st_size > MAX_FILE:
+            raise ValueError(f"File exceeds 10 MiB snapshot limit: {name}")
+        data = path.read_bytes()
+        total += len(data)
+        if total > MAX_TOTAL:
+            raise ValueError("Workspace exceeds 100 MiB snapshot limit")
+        files[name] = {"sha256": hashlib.sha256(data).hexdigest(),
+                       "mode": path.stat().st_mode & 0o777}
+    return files, omitted
+
+
+def fingerprint(files, omitted):
+    return hashlib.sha256(json.dumps([files, omitted], sort_keys=True).encode()).hexdigest()
+
+
+def checkpoint(root, state, label):
+    files, omitted = inventory(root)
+    ident = uuid.uuid4().hex[:12]
+    directory = root / STORE / "snapshots" / ident
+    directory.mkdir(parents=True)
+    for name, info in files.items():
+        data = safe_path(root, name).read_bytes()
+        if hashlib.sha256(data).hexdigest() != info["sha256"]:
+            raise ValueError("Workspace changed during snapshot; retry when edits stop")
+        dest = directory / "files" / name
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(data)
+    snap = {"id": ident, "label": label, "time": now(), "files": files,
+            "omitted": omitted, "fingerprint": fingerprint(files, omitted)}
+    save(directory / "manifest.json", snap)
+    state["checkpoints"].append({k: snap[k] for k in ("id", "label", "time")})
+    save(root / STORE / "task.json", state)
+    return snap
+
+
+def get_snapshot(root, state, ident):
+    if ident not in {x["id"] for x in state["checkpoints"]}:
+        raise ValueError("Unknown checkpoint ID")
+    return load(root / STORE / "snapshots" / ident / "manifest.json")
+
+
+def import_session(path):
+    metrics = {"records": 0, "malformed_lines": 0, "tool_calls": 0,
+               "tool_errors": 0, "compactions": 0, "truncation_markers": 0}
+    with path.open(encoding="utf-8") as source:
+        for line in source:
+            if not line.strip():
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                metrics["malformed_lines"] += 1
+                continue
+            if not isinstance(record, dict):
+                metrics["malformed_lines"] += 1
+                continue
+            metrics["records"] += 1
+            if record.get("type") == "system" and record.get("subtype") == "compact_boundary":
+                metrics["compactions"] += 1
+            # Codex rollout response items wrap API events in payload.
+            payload = record.get("payload")
+            if record.get("type") == "response_item" and isinstance(payload, dict):
+                if payload.get("type") in {"function_call", "custom_tool_call"}:
+                    metrics["tool_calls"] += 1
+                elif payload.get("type") in {"function_call_output", "custom_tool_call_output"}:
+                    output = payload.get("output", "")
+                    # Do not infer errors from prose; rollout output is opaque.
+                    metrics["tool_errors"] += bool(payload.get("is_error"))
+                    if re.search(r"\btruncated\b", str(output), re.I):
+                        metrics["truncation_markers"] += 1
+            if record.get("type") == "compacted":
+                metrics["compactions"] += 1
+            message = record.get("message")
+            content = message.get("content", []) if isinstance(message, dict) else []
+            if not isinstance(content, list):
+                content = []
+            # Codex, Cline and other clients often store tool events as top-level
+            # records instead of Claude's message.content blocks. Count only the
+            # event metadata; raw prompts and outputs are never persisted.
+            top_level_type = str(record.get("type", "")).lower()
+            if top_level_type in {"tool_use", "tool_call", "function_call"}:
+                metrics["tool_calls"] += 1
+            if top_level_type in {"tool_result", "tool_output", "function_result"}:
+                metrics["tool_errors"] += bool(record.get("is_error") or record.get("error"))
+                if re.search(r"\btruncated\b", json.dumps(record, ensure_ascii=False), re.I):
+                    metrics["truncation_markers"] += 1
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") == "tool_use":
+                    metrics["tool_calls"] += 1
+                if block.get("type") == "tool_result":
+                    metrics["tool_errors"] += bool(block.get("is_error"))
+                    if re.search(r"\btruncated\b", json.dumps(block.get("content", "")), re.I):
+                        metrics["truncation_markers"] += 1
+    return metrics
+
+
+def report(root, state):
+    current, omitted = inventory(root)
+    baseline = get_snapshot(root, state, state["checkpoints"][0]["id"])["files"]
+    changed = [("added" if p not in baseline else "deleted" if p not in current else "modified", p)
+               for p in sorted(set(baseline) | set(current)) if baseline.get(p) != current.get(p)]
+    current_fp = fingerprint(current, omitted)
+    lines = ["# AgentProof task evidence", "", f"Goal: {state['goal']}", "",
+             f"Generated: {now()}", "", "This report records evidence; it does not certify correctness or task completion.",
+             "", "## Changes since task start", ""]
+    lines += [f"- {kind}: `{name}`" for kind, name in changed] or ["No captured file changes."]
+    lines += ["", "## Verification", ""]
+    if not state["checks"]:
+        lines += ["No verification commands recorded."]
+    for check in state["checks"]:
+        fresh = check["before"] == check["after"] == current_fp
+        status = "PASS" if check["exit_code"] == 0 else "FAIL"
+        command = check["command"]
+        preview = " ".join(command.split())
+        expanded = "\n" in command or len(preview) > 120
+        if len(preview) > 120:
+            preview = preview[:117] + "..."
+        ticks = "`" * (max((len(x) for x in re.findall(r"`+", preview)), default=0) + 1)
+        lines += [f"- **{status}** {ticks} {preview} {ticks} — exit {check['exit_code']}; "
+                  f"{'matches current captured files' if fresh else 'STALE / files changed'}; "
+                  f"log: `{check['log']}`"]
+        if check.get("timed_out"):
+            lines += ["  Timed out; the process group was terminated."]
+        if expanded:
+            fence = "`" * max(3, max((len(x) for x in re.findall(r"`+", command)), default=0) + 1)
+            lines += ["", "<details>", "<summary>Full command</summary>", "",
+                      fence + "sh", command, fence, "", "</details>", ""]
+    lines += ["", "## Imported session signals", ""]
+    for session in state["sessions"]:
+        lines += ["- " + "; ".join(f"{k}: {v}" for k, v in session["metrics"].items())]
+    if not state["sessions"]:
+        lines += ["No session imported."]
+    lines += ["", "Signals are heuristic observations, not proof of lost context or model errors.",
+              "Imported sessions are not automatically correlated with this task's file changes.",
+              "", "## Scope and limitations", "",
+              "- Snapshots cover Git-tracked and non-ignored untracked regular files, including initial local edits.",
+              "- Git index, ignored files, symlinks, submodules and external services are not restored or verified.",
+              "- Sensitive filenames are excluded; this is not a secret scanner.",
+              "- A passing command proves its exit status, not test coverage or requirements satisfaction.",
+              "- Work concurrently edited while checking may invalidate evidence; stop edits before verification."]
+    lines += [f"- Omitted `{x['path']}`: {x['reason']}" for x in omitted]
+    lines += ["", "## Checkpoints", ""]
+    lines += [f"- `{s['id']}` — {s['label']} ({s['time']})" for s in state["checkpoints"]]
+    if state.get("reviews"):
+        lines += ["", "## Claim review", ""]
+        for review in state["reviews"]:
+            lines += [f"Reviewed: `{review['source']}` ({review['time']})", ""]
+            latest = review_claims(root, state, [x["claim"] for x in review["items"]], review["source"])
+            for item in latest["items"]:
+                lines.append(f"- **{item['status']}** {item['claim']} — {item['reason']}")
+            if latest.get("questions"):
+                lines += ["", "### Human confirmation", ""]
+                lines += [f"- {question}" for question in latest["questions"]]
+    return "\n".join(lines) + "\n"
+
+
+def review_claims(root, state, claims, source):
+    """Match plain-language completion claims to observed local evidence.
+
+    This deliberately uses transparent rules instead of another model. A claim is
+    never upgraded to VERIFIED just because it sounds confident.
+    """
+    current, omitted = inventory(root)
+    current_fp = fingerprint(current, omitted)
+    baseline = get_snapshot(root, state, state["checkpoints"][0]["id"])["files"]
+    changed = [p for p in sorted(set(baseline) | set(current)) if baseline.get(p) != current.get(p)]
+    checks = state.get("checks", [])
+    fresh_pass = [c for c in checks if c["exit_code"] == 0 and c["before"] == c["after"] == current_fp]
+    items, questions = [], []
+    for raw in claims:
+        claim = " ".join(raw.strip().split())
+        if not claim:
+            continue
+        lower = claim.lower()
+        kind = next((k for k, pattern in (
+            ("test", r"\b(?:tests?|pytest|unittest)\b|测试"),
+            ("lint", r"\blint\b|静态检查"),
+            ("build", r"\bbuild\b|构建")) if re.search(pattern, lower)), None)
+        says_pass = bool(re.search(r"\b(?:pass|passed|passing|success|successful|green)\b|通过|成功", lower))
+        says_change = bool(re.search(r"\b(?:fix|fixed|change|changed|implement|implemented)\b|修复|修改|实现", lower))
+        negated = bool(re.search(r"\b(?:not|never|no|failed)\b|未|没有|失败|不", lower))
+        if negated:
+            items.append({"status": "UNVERIFIED", "claim": claim,
+                          "reason": "Negative or qualified statement; inspect the original evidence."})
+            questions.append(f"Confirm the stated limitation: {claim}")
+        elif kind and says_pass:
+            matching = [c for c in fresh_pass if c.get("kind") == kind]
+            evidence = []
+            for c in matching:
+                log = root / c["log"]
+                if (c.get("log_sha256") and log.is_file() and
+                        hashlib.sha256(log.read_bytes()).hexdigest() == c["log_sha256"]):
+                    evidence.append(c)
+            if evidence:
+                items.append({"status": "OBSERVED", "claim": claim,
+                              "reason": "Recorded exit 0 for: " + "; ".join(c["command"] + " [log: " + c["log"] + "]" for c in evidence)
+                              + ". This does not prove test count, coverage, or the full claim."})
+            else:
+                items.append({"status": "UNVERIFIED", "claim": claim,
+                              "reason": "No fresh successful check of the declared type with intact log evidence."})
+            questions.append(f"Confirm scope and actual output for: {claim}")
+        elif says_change:
+            if changed:
+                items.append({"status": "OBSERVED", "claim": claim,
+                              "reason": f"检测到 {len(changed)} 个文件相对任务起点发生变化"})
+            else:
+                items.append({"status": "CONFLICT", "claim": claim, "reason": "当前工作区没有相对任务起点的文件变化"})
+                questions.append("确认修改是否写入了另一个目录、分支或工作树。")
+        else:
+            items.append({"status": "UNVERIFIED", "claim": claim, "reason": "没有可匹配的本地证据规则"})
+            questions.append("为这条声明指定可复现的文件、命令或外部结果证据。")
+    return {"time": now(), "source": source, "items": items, "questions": list(dict.fromkeys(questions))}
+
+
+def log_tail(path):
+    """Bound memory and terminal output even when a check writes a huge log."""
+    with path.open("rb") as source:
+        size = source.seek(0, os.SEEK_END)
+        source.seek(max(0, size - 8192))
+        text = source.read(8192).decode("utf-8", errors="replace")
+    lines = text.splitlines()
+    tail = "\n".join(lines[-12:])
+    truncated = size > 8192 or len(lines) > 12 or len(tail) > 4000
+    tail = tail[-4000:]
+    # Do not emit terminal control sequences from command output.
+    tail = "".join(c for c in tail if c in "\n\t" or (ord(c) >= 32 and ord(c) != 127))
+    return ("[earlier output omitted]\n" if truncated else "") + (tail or "(no command output)")
+
+
+def run(args, root):
+    store = root / STORE
+    if args.action == "init":
+        if (store / "task.json").exists():
+            raise ValueError("Task already exists; use a separate repository/worktree for another task")
+        # Keep local evidence out of commits without editing the shared .gitignore.
+        exclude_path = Path(os.fsdecode(git(root, "rev-parse", "--git-path", "info/exclude")).strip())
+        if not exclude_path.is_absolute():
+            exclude_path = root / exclude_path
+        exclude_path.parent.mkdir(parents=True, exist_ok=True)
+        with exclude_path.open("a", encoding="utf-8") as f:
+            f.write("\n/.agentproof/\n")
+        state = {"version": 1, "goal": args.goal, "created": now(),
+                 "checkpoints": [], "checks": [], "sessions": []}
+        snap = checkpoint(root, state, "task start")
+        print(f"Task initialized. Baseline: {snap['id']} ({len(snap['files'])} files)")
+        return 0
+    if not (store / "task.json").exists():
+        raise ValueError("Run agentproof init --goal '...' first")
+    state = load(store / "task.json")
+    if args.action == "checkpoint":
+        snap = checkpoint(root, state, args.label)
+        print(f"Checkpoint: {snap['id']} ({len(snap['files'])} files)")
+    elif args.action == "import-session":
+        metrics = import_session(Path(args.path))
+        state["sessions"].append({"imported": now(), "metrics": metrics})
+        save(store / "task.json", state)
+        print(json.dumps(metrics, indent=2))
+    elif args.action == "review":
+        claims = list(args.claim or [])
+        if args.summary:
+            summary_path = Path(args.summary)
+            if not summary_path.is_file():
+                raise ValueError(f"Summary file not found: {args.summary}")
+            claims.extend(summary_path.read_text(encoding="utf-8", errors="replace").splitlines())
+        if not claims:
+            raise ValueError("Provide --summary FILE or at least one --claim")
+        review = review_claims(root, state, claims, args.summary or "command line claims")
+        state.setdefault("reviews", []).append(review)
+        save(store / "task.json", state)
+        for item in review["items"]:
+            print(f"{item['status']}: {item['claim']} — {item['reason']}")
+        if review["questions"]:
+            print("\nHuman confirmation:")
+            for question in review["questions"]:
+                print(f"- {question}")
+    elif args.action == "verify":
+        command = args.command
+        if command and command[0] == "--":
+            command = command[1:]
+        if not command:
+            raise ValueError("Provide a command after --")
+        before = fingerprint(*inventory(root))
+        log = Path(STORE) / "checks" / (uuid.uuid4().hex[:12] + ".log")
+        (root / log).parent.mkdir(parents=True, exist_ok=True)
+        timed_out = False
+        with (root / log).open("wb") as output:
+            try:
+                popen_kwargs = {"cwd": root, "stdout": output, "stderr": subprocess.STDOUT}
+                if os.name != "nt":
+                    popen_kwargs["start_new_session"] = True
+                else:
+                    popen_kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+                proc = subprocess.Popen(command, **popen_kwargs)
+                try:
+                    code = proc.wait(timeout=args.timeout)
+                except subprocess.TimeoutExpired:
+                    terminate_process_group(proc)
+                    code, timed_out = 124, True
+                except KeyboardInterrupt:
+                    terminate_process_group(proc)
+                    code = 130
+            except OSError as exc:
+                output.write(f"{command[0]}: {exc}".encode())
+                code = 127
+        after = fingerprint(*inventory(root))
+        import shlex
+        state["checks"].append({"command": shlex.join(command), "exit_code": code,
+                                "time": now(), "before": before, "after": after,
+                                "log": str(log), "timed_out": timed_out, "kind": args.kind,
+                                "argv": command,
+                                "log_sha256": hashlib.sha256((root / log).read_bytes()).hexdigest()})
+        save(store / "task.json", state)
+        print(f"{'PASS' if code == 0 else 'FAIL'} (exit {code}). Log: {log}")
+        if code != 0:
+            if timed_out:
+                print(f"Timed out after {args.timeout:g}s; the process group was terminated.")
+            print("Last command output:")
+            print(log_tail(root / log))
+        return 0 if code == 0 else 1
+    elif args.action in ("report", "status"):
+        result = report(root, state)
+        if args.action == "report":
+            path = store / "report.md"
+            path.write_text(result, encoding="utf-8")
+            print(path)
+        else:
+            print(result)
+    elif args.action == "restore":
+        snap = get_snapshot(root, state, args.id)
+        pending = []
+        for name, info in snap["files"].items():
+            target = safe_path(root, name)
+            source = safe_path(store / "snapshots" / args.id / "files", name)
+            data = source.read_bytes()
+            if hashlib.sha256(data).hexdigest() != info["sha256"]:
+                raise ValueError(f"Corrupted snapshot file: {name}")
+            if target.exists() and not target.is_file():
+                raise ValueError(f"Restore conflicts with directory: {name}")
+            for parent in target.parents:
+                if parent == root:
+                    break
+                if parent.exists() and not parent.is_dir():
+                    raise ValueError(f"Restore path blocked by non-directory: {parent.relative_to(root)}")
+            if (not target.exists() or hashlib.sha256(target.read_bytes()).hexdigest() != info["sha256"]
+                    or target.stat().st_mode & 0o777 != info["mode"]):
+                pending.append((name, data, info["mode"]))
+        print(f"Restore {len(pending)} files from {args.id}. Files created later remain; Git index stays unchanged.")
+        for name, _, _ in pending:
+            print(f"  {name}")
+        if not args.apply:
+            print("Preview only. Use --apply to write files (automatic pre-restore backup).")
+        elif pending:
+            backup = checkpoint(root, state, "before restore " + args.id)
+            for name, _, _ in pending:
+                target = safe_path(root, name)
+                if target.exists() and (name not in backup["files"] or
+                        hashlib.sha256(target.read_bytes()).hexdigest() != backup["files"][name]["sha256"]):
+                    raise ValueError(f"Cannot safely back up {name}; restore aborted before writing")
+            for name, data, mode in pending:
+                target = safe_path(root, name)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(data)
+                target.chmod(mode)
+            print(f"Restored. Backup checkpoint: {backup['id']}")
+    return 0
+
+
+def main(argv=None):
+    # Windows consoles may default to a legacy code page that cannot render the
+    # bilingual review questions. Keep reports and diagnostics lossless.
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8", errors="replace")
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version", action="version", version=f"AgentProof {__version__}")
+    sub = parser.add_subparsers(dest="action", required=True)
+    p = sub.add_parser("init", help="Start a task and capture its baseline")
+    p.add_argument("--goal", required=True)
+    p = sub.add_parser("checkpoint", help="Capture current files without changing Git history")
+    p.add_argument("--label", default="manual checkpoint")
+    p = sub.add_parser("import-session", help="Import Claude Code JSONL signal counts")
+    p.add_argument("path")
+    p = sub.add_parser("review", help="Match AI completion claims to recorded local evidence")
+    p.add_argument("--summary", help="Text file containing one completion claim per line")
+    p.add_argument("--claim", action="append", help="A completion claim; repeat for multiple claims")
+    p = sub.add_parser("verify", help="Run a command, capture output and record workspace fingerprints")
+    p.add_argument("--kind", choices=["test", "lint", "build", "other"], default="other",
+                   help="Declared check type, not a correctness certification")
+    p.add_argument("--timeout", type=float, default=300)
+    p.add_argument("command", nargs=argparse.REMAINDER)
+    sub.add_parser("report", help="Write .agentproof/report.md")
+    sub.add_parser("status", help="Print current evidence report")
+    p = sub.add_parser("restore", help="Preview file restoration; new files are retained")
+    p.add_argument("id")
+    p.add_argument("--apply", action="store_true")
+    args = parser.parse_args(argv)
+    lock = None
+    try:
+        root = Path(os.fsdecode(git(Path.cwd(), "rev-parse", "--show-toplevel")).strip()).resolve()
+        store = root / STORE
+        if store.is_symlink():
+            raise ValueError("Evidence directory must not be a symlink")
+        store.mkdir(exist_ok=True, mode=0o700)
+        candidate = store / "lock"
+        try:
+            candidate.mkdir()
+        except FileExistsError:
+            raise ValueError("Another AgentProof command is running. If interrupted, remove .agentproof/lock manually.")
+        lock = candidate
+        return run(args, root)
+    except (ValueError, OSError, json.JSONDecodeError) as exc:
+        print(f"agentproof: {exc}", file=sys.stderr)
+        return 2
+    finally:
+        if lock is not None:
+            lock.rmdir()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentproof_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: agentproof-cli
+Version: 0.3.0
+Summary: Local evidence, checkpoints, and verification for AI coding tasks
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AgentProof
+
+**Evidence for AI coding tasks. Local checkpoints, real command results, honest handoff reports.**
+
+[中文说明](README.zh-CN.md) · [Five-minute start](docs/quickstart.md) · [Example report](examples/report.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · MIT license
+
+AI says “done.” What actually changed? Which checks ran, and do they still match the code?
+AgentProof answers those questions without another model or an API key.
+
+```text
+$ agentproof init --goal "Fix payment retries"
+Task initialized. Baseline: ... (42 files)
+$ agentproof verify --kind test -- python -m unittest discover -s tests
+PASS (exit 0). Log: .agentproof/checks/....log
+$ agentproof report
+/path/to/project/.agentproof/report.md
+```
+
+## Install
+
+Requires Python 3.10+, Git, and macOS, Linux, or Windows.
+This project is not published to PyPI yet.
+
+With [pipx installed and on PATH](https://pipx.pypa.io/stable/installation/), install directly from GitHub:
+
+```bash
+pipx install 'git+https://github.com/bzwei58/agentproof.git@main'
+```
+
+Then run `agentproof --version` from any project. If the command is missing, run
+`pipx ensurepath` and reopen your terminal. The package is named `agentproof-cli`, while
+the command is `agentproof`; remove it with `pipx uninstall agentproof-cli`.
+This installs the current main branch, not a versioned release.
+
+If you do not use pipx, create a virtual environment and install the same Git URL with its
+Python: `python3 -m venv /your/chosen/venv`, then
+`/your/chosen/venv/bin/python -m pip install 'git+https://github.com/bzwei58/agentproof.git@main'`.
+Use `/your/chosen/venv/bin/agentproof` or activate that environment.
+
+Start with the [five-minute walkthrough](docs/quickstart.md): one failing test, a fix,
+a stale check and a report, all in a disposable directory. For a real project, follow the workflow below.
+
+## Workflow
+
+Run from any directory inside the Git repository you want to inspect. Commands execute at
+that repository's root. One active task is supported per checkout; use a worktree for another task.
+
+1. **Start before AI edits.** `agentproof init --goal "Fix payment retries"` captures initial
+   local changes too, without creating commits or touching the Git index.
+2. Let your existing coding agent work. AgentProof does not launch or intercept it.
+3. **Save a milestone.** `agentproof checkpoint --label "first implementation"`.
+4. **Run real checks.** `agentproof verify --kind test -- python -m unittest discover -s tests`.
+   Run each test, lint or build command separately. Shell operators are not interpreted;
+   explicitly use `sh -c '...'` if you need shell syntax. Only run commands you trust.
+5. **Optionally import session signals.** `agentproof import-session /path/to/session.jsonl`.
+6. **Review AI claims.** `agentproof review --summary ai-summary.txt` (one claim per line), or repeat
+   `--claim "All tests passed"`. It reports `OBSERVED`, `UNVERIFIED` and `CONFLICT`; natural-language claims are not certified.
+7. **Review.** `agentproof status` prints evidence; `agentproof report` writes Markdown.
+8. **Recover selected snapshot contents.** `agentproof restore CHECKPOINT_ID` previews changes;
+   add `--apply` to write them, after an automatic backup checkpoint.
+
+`verify --timeout 60 -- COMMAND ...` sets a timeout in seconds (default 300).
+A nonzero command result returns CLI exit code 1; usage/operational errors return 2.
+Command stdout and stderr are retained in `.agentproof/checks/`. On failure, the terminal
+also shows the last 12 lines, capped at 4,000 characters, plus an explicit timeout message
+when applicable. Successful commands stay quiet. The full log is always retained locally.
+
+## What is recorded
+
+- SHA-256 fingerprints and modes of captured files, plus full file checkpoints.
+- Added, modified and deleted files relative to the task's initial checkpoint.
+- Actual verification command, exit status, output log and before/after fingerprints.
+- Whether each check still matches the current captured files. Editing code after a check
+  or having a check modify files marks it **STALE**.
+- Long or multiline commands have compact report summaries; expand **Full command** to
+  inspect the exact recorded invocation.
+- Optional Claude Code JSONL counts: tool calls, error results, compaction boundaries,
+  truncation markers and malformed records. Raw imported messages are not copied.
+- Claim review matches completion statements to local file changes and fresh checks using transparent rules.
+
+## Boundaries
+
+This is an **evidence recorder and claim-gap detector**, not an automatic correctness judge. A passing check does
+not prove requirements satisfaction, coverage or absence of bugs. There is no model-based
+risk scoring, live session watcher, automatic test discovery or cross-agent correlation yet.
+Claim review never calls a model and cannot decide whether a requirement is substantively correct.
+Session import is best-effort for Claude Code-style `message.content` blocks and
+`system/compact_boundary` records. Other formats and future schema changes may not be counted.
+Truncation text is a heuristic signal, not proof that important context was lost.
+
+Snapshots include Git-tracked and non-ignored untracked regular files. Ignored files,
+symlinks, submodule contents, Git index state, external services and environment variables
+are outside the captured scope. Known secret filenames (`.env*`, private-key extensions,
+`credentials.json`) are excluded and listed; **this is not secret detection**. Verification
+logs can contain secrets printed by your own commands. Keep `.agentproof/` private.
+Initialization adds a local Git exclusion, and evidence is stored with a private directory mode.
+
+A file over 10 MiB or total captured content over 100 MiB aborts snapshotting. Avoid concurrent
+edits while capturing or verifying. Only one AgentProof command can run per checkout.
+After an interrupted process, inspect and remove a stale `.agentproof/lock` manually.
+
+Restore rewrites files present in the target snapshot. **Files added later remain**; this is
+file recovery, not an exact whole-workspace rollback. It leaves Git history and staging alone.
+It rejects symlink paths, verifies snapshot content hashes and preflights file/directory
+conflicts, including blocked parent paths, before changing files.
+It is not a filesystem transaction; concurrent changes or I/O errors can still interrupt writes.
+Restore does not recover excluded files or delete newly created ones. A pre-restore checkpoint lets you
+recover overwritten captured content. Do not manually edit snapshot manifests or files.
+
+## Development
+
+```bash
+git clone https://github.com/bzwei58/agentproof.git
+cd agentproof
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+python3 -m unittest discover -s tests -v
+python3 -m agentproof --help
+```
+
+Want to try it on two real tasks? See the [pilot guide and feedback form](docs/pilot.md).
+
+Tests use disposable Git repositories and cover stale evidence, nonzero exits, timeout,
+initial uncommitted edits, restoration backups, symlink rejection, secret exclusions and
+partial session logs. GitHub Actions runs them on macOS/Linux and Python 3.10/3.12/3.13.
+
+Ideas for later: task history, more session adapters, configurable snapshot scope, optional
+CI handoff artifacts. Contributions should preserve the distinction between observed facts
+and model-generated claims. Please include a reproducible example and tests for behavior changes.
+
+## Evidence matching in 0.3.0
+
+Declare each check with `verify --kind test|lint|build|other -- COMMAND`. This is a
+user-supplied category, not a certification. Old records remain usable as command
+history but do not acquire a check category automatically.
+
+Natural-language completion claims are never certified as `VERIFIED`. `OBSERVED`
+means a corresponding category of command exited 0 with an intact log and matching
+captured files; inspect the named command and output to confirm scope and test count.
+A build cannot support a test claim. Missing, stale, failed, or modified evidence leaves
+the claim `UNVERIFIED`. Reviews are recalculated on every `status` or `report` call.
+Already exported Markdown is a static snapshot and must be regenerated after changes.
+External services, ignored dependencies and environment changes remain outside the fingerprint.
+
+Session import recognizes Claude message blocks and Codex rollout `response_item.payload`
+tool events plus `compacted` records. Opaque outputs do not establish command success.
+Cline and Cursor native formats are not yet validated; generic top-level event counting
+must not be interpreted as full client support.

agentproof_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentproof/__init__.py,sha256=weCpZThFYepfPsU670_rKFrBIbL_s2sOBkW4wsXVbVQ,70
+agentproof/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+agentproof/cli.py,sha256=cnpiZrRT_mcCUCXbxurEtu0uFsBJnHgDXRXWGGDBtLA,25552
+agentproof_cli-0.3.0.dist-info/licenses/LICENSE,sha256=OaQW2-AB2EVeDF-1u7pfHGI6037r7gF8ltZCoAqA9aM,1080
+agentproof_cli-0.3.0.dist-info/METADATA,sha256=uuTKoOA05bAjLRIHk_ykRT-1QvDYQAVOaKGJXQbmMSM,8918
+agentproof_cli-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+agentproof_cli-0.3.0.dist-info/entry_points.txt,sha256=zdOItEhd5Fg6-KtoyjJpE8UVGBcZI-0W-f1HzwoTRUg,51
+agentproof_cli-0.3.0.dist-info/top_level.txt,sha256=y-s9bo8mLoN7E-rGjL5Ff3E65l6U0YGhkpqOXrYiwFk,11
+agentproof_cli-0.3.0.dist-info/RECORD,,

agentproof_cli-0.3.0.dist-info/WHEEL

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

agentproof_cli-0.3.0.dist-info/entry_points.txt

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

agentproof_cli-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentProof contributors
+
+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.

agentproof_cli-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentproof