{
  "markdown": "# ProofFlow\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\n**Agent Work Ledger for AI coding.**\n\nVibe coding is fast. Blind trust is not enough.\n\nProofFlow makes AI-generated work reviewable, traceable, and reversible by\nrecording the full chain from work contract to proof packet: contract first,\nrecord the algorithm decision, declare the cost budget, snapshot the code state,\nbind claims to evidence, evaluate done criteria, then export an auditable\npacket.\n\n**Latest release:** [v0.1.8 - Agent Work Ledger for AI coding](https://github.com/Hyperion-GPU/ProofFlow-v0.1/releases/tag/v0.1.8)\n\n▶ **Watch the 72s demo:** [From AI agent claims to verifiable Proof Packets](https://github.com/Hyperion-GPU/ProofFlow-v0.1/releases/tag/v0.1.3)<br>\n\n> **Demo asset (deferred)**: The end-to-end dogfood Demo_Asset GIF and the\n> VSCode_Channel inline audit / Approve Gate screenshots for the v0.1.x\n> dogfood-and-channel-polish milestone are deferred to the next dogfood cycle\n> (no capturable VS Code window in this milestone). Tracked in\n> [`PLANS.md#vscode-channel-screenshots-deferred-from-v0-1-x-dogfood`](PLANS.md#vscode-channel-screenshots-deferred-from-v0-1-x-dogfood).\n\n📦 **Example Proof Packets:** [`code review`](docs/examples/proof_packet_codex_review.md) · [`issue triage`](docs/examples/proof_packet_issue_triage.md) · [`agent work ledger`](docs/examples/proof_packet_agent_work_ledger.md) · [`ledger dogfood`](docs/examples/proof_packet_agent_work_ledger_dogfood.md)\n\n**Maintainer workflow:** [`docs/maintainer_evidence_workflow.md`](docs/maintainer_evidence_workflow.md)\n\n**Agent Work Ledger guide:** [`docs/agent_work_ledger.md`](docs/agent_work_ledger.md)\n\n**Ledger Risk Hints:** [`docs/ledger_risk_hints.md`](docs/ledger_risk_hints.md)\n\n**5-minute MCP quickstart:** [`docs/ledger_quickstart_mcp.md`](docs/ledger_quickstart_mcp.md)\n\n**Ledger PR comment template:** [`docs/examples/pr_comment_agent_work_ledger.md`](docs/examples/pr_comment_agent_work_ledger.md)\n\n**AgentGuard semantic rules:** [`docs/agentguard_semantic_rules.md`](docs/agentguard_semantic_rules.md)\n\n[![ProofFlow demo thumbnail](docs/assets/proofflow-demo-thumbnail.png)](https://github.com/Hyperion-GPU/ProofFlow-v0.1/releases/tag/v0.1.3)\n\n## Agent Work Ledger\n\nProofFlow is not only a PR review helper. It is a local-first ledger for AI\ncoding work. A Ledger Case captures the workflow before, during, and after an\nagent changes code:\n\n1. **Work Contract** - record the objective, repo path, allowed scope,\n   forbidden actions, required tests, done criteria, evidence requirements,\n   algorithm requirements, and cost budget.\n2. **Algorithm Decision** - record the selected approach, rationale,\n   alternatives, invariants, and forbidden approaches before implementation.\n3. **Cost Budget** - declare token, API, GPU, CPU, runtime, or iteration limits\n   before expensive work begins.\n4. **Snapshot** - capture the git diff, changed files, HEAD SHA, base ref, and\n   diff hash so reviewers know exactly what code state was examined.\n5. **Evidence** - store command output, test output, diffs, notes, screenshots,\n   or other artifacts as searchable evidence.\n6. **Claim** - require every agent claim to bind to evidence before it is\n   trusted.\n7. **Evaluation** - deterministically check required tests, algorithm decision,\n   cost budget, scope boundaries, missing evidence, unaccepted risks, and\n   non-blocking Risk Hints for suspicious routes.\n8. **Proof Packet** - export the contract, algorithm decision, cost budget,\n   timeline, snapshots, claims, evidence, evaluation, decisions, and remaining\n   risks into markdown.\n\nMain chain: Work Contract -> Algorithm Decision -> Cost Budget -> Snapshot ->\nEvidence -> Claim -> Evaluation -> Proof Packet. This keeps the core product\ninvariant sharp: no Case, no workflow; no Evidence, no trusted Claim; no done\ncriteria evaluation, no quiet success.\n\nRisk Hints extend the evidence flow without turning ProofFlow into an automatic\nalgorithm judge. They tell the maintainer when the recorded route may be wrong\nor too expensive, such as regeneration where mapping was required, budget\noverrun metadata, or tests that prove output but not method.\n\nSee [`docs/agent_work_ledger.md`](docs/agent_work_ledger.md) for the full\narchitecture and evaluation model, or\n[`docs/ledger_quickstart_mcp.md`](docs/ledger_quickstart_mcp.md) to run the\nfull MCP flow.\n\n## ProofFlow Reviewed ProofFlow\n\nProofFlow v0.1.6 was dogfooded on a real repository PR. The GitHub Actions\nworkflow ran AgentGuard, posted a stable PR summary comment, uploaded\n`summary.json`, and exported a downloadable Proof Packet.\n\n[![ProofFlow AgentGuard review comment for PR #94](docs/assets/proofflow-pr94-agentguard-comment.svg)](https://github.com/Hyperion-GPU/ProofFlow-v0.1/pull/94#issuecomment-4465608299)\n\n- Real PR: [#94 Dogfood v0.1.6 CI review story](https://github.com/Hyperion-GPU/ProofFlow-v0.1/pull/94)\n- Review run: [ProofFlow PR Review #25953071865](https://github.com/Hyperion-GPU/ProofFlow-v0.1/actions/runs/25953071865)\n- Patch release from dogfood feedback: [v0.1.6.1](https://github.com/Hyperion-GPU/ProofFlow-v0.1/releases/tag/v0.1.6.1)\n- Result: one stable comment updated across pushes, one artifact containing the\n  Proof Packet and `summary.json`, no merge blocking.\n\n[![Backend](https://github.com/Hyperion-GPU/ProofFlow-v0.1/actions/workflows/backend.yml/badge.svg)](https://github.com/Hyperion-GPU/ProofFlow-v0.1/actions/workflows/backend.yml)\n[![Frontend](https://github.com/Hyperion-GPU/ProofFlow-v0.1/actions/workflows/frontend.yml/badge.svg)](https://github.com/Hyperion-GPU/ProofFlow-v0.1/actions/workflows/frontend.yml)\n[![MCP Server](https://github.com/Hyperion-GPU/ProofFlow-v0.1/actions/workflows/mcp-server.yml/badge.svg)](https://github.com/Hyperion-GPU/ProofFlow-v0.1/actions/workflows/mcp-server.yml)\n[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/hyperion-gpu.proofflow?label=VS%20Code&logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=hyperion-gpu.proofflow)\n[![PyPI](https://img.shields.io/pypi/v/proofflow-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/proofflow-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Problem\n\nAI coding agents (Claude Code, Codex, Copilot Workspace) can modify files, run commands, and make decisions autonomously. But there's no standard way to:\n\n- **Audit** what an agent did and why\n- **Gate** high-risk actions before they execute\n- **Prove** that a code review actually checked what it claims\n- **Undo** agent-initiated changes with confidence\n\nProofFlow solves this by sitting between the agent and the filesystem, creating an evidence graph that links every action to its justification.\n\n## Quickstart\n\n### Docker (recommended)\n\nRun from the parent directory of the freshly cloned repo. The\n`Push-Location` / `Pop-Location` pair keeps the working directory at the\nrepository root for the `docker compose up` command and restores it after the\nblock, so this snippet is copy-paste safe in a single PowerShell session.\n\n```powershell\ngit clone https://github.com/Hyperion-GPU/ProofFlow-v0.1.git\nPush-Location ProofFlow-v0.1\ndocker compose up\nPop-Location\n```\n\nBackend: http://localhost:8787 | Frontend: http://localhost:5173\n\nDocker publishes both ports on `127.0.0.1` by default to preserve ProofFlow's\nlocalhost trust boundary. For stronger local protection, set an API key before\nstarting:\n\n```bash\nPROOFFLOW_API_KEY=change-me docker compose up\n```\n\nIf you enable backend auth for the Docker frontend, use the same\n`PROOFFLOW_API_KEY` value at build time so Vite can embed\n`VITE_PROOFFLOW_API_KEY` in the static frontend bundle. AgentGuard\n`test_command` execution is disabled by default; set\n`PROOFFLOW_ENABLE_TEST_COMMANDS=true` only when you intentionally want the\nbackend to run local test commands during review.\n\n### Manual\n\nStart each component from the repository root in a single PowerShell session.\n`Push-Location` / `Pop-Location` keeps the working directory predictable across\nthe backend and frontend blocks; the backend port is fixed to `8787` to match\nthe `make dev-backend` baseline. `npm run dev` is a long-running process - run\nthe frontend block in a second PowerShell session if you want to keep the\nbackend uvicorn process visible in the first.\n\n```powershell\n# Backend\nPush-Location backend\npip install -r requirements.txt\npython -m uvicorn proofflow.main:app --port 8787\nPop-Location\n\n# Frontend (long-running; recommended in a second PowerShell session)\nPush-Location frontend\nnpm ci\nnpm run dev\nPop-Location\n```\n\n### MCP Integration (Claude Code / Codex)\n\n```bash\npip install proofflow-mcp\n```\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"proofflow\": {\n      \"command\": \"proofflow-mcp\",\n      \"env\": { \"PROOFFLOW_BASE_URL\": \"http://127.0.0.1:8787\" }\n    }\n  }\n}\n```\n\nNow your AI agent can keep an Agent Work Ledger, scan files, review code,\ntriage issues, suggest actions, and export audit reports - all with enforced\nsafety gates.\n\n### Codex Maintainer Plugin\n\nProofFlow also includes a repo-local Codex plugin at\n[`plugins/proofflow-maintainer`](plugins/proofflow-maintainer). It provides\nstarter prompts and a maintainer-focused skill for:\n\n- reviewing the current diff with ProofFlow,\n- creating a Proof Packet for a PR,\n- triaging issue text into a ProofFlow Case,\n- keeping an Agent Work Ledger for complex code tasks.\n\nThe plugin uses the same local `proofflow-mcp` server and keeps the backend\ntrust boundary at `http://127.0.0.1:8787`.\nSee the public-safe\n[`Agent Work Ledger` example](docs/examples/proof_packet_agent_work_ledger.md)\nfor the expected handoff shape.\n\n## Architecture\n\n```\nAI Agent (Claude Code / Codex / Custom)\n    |\n    | MCP Protocol (stdio)\n    v\nProofFlow MCP Server (23 tools)\n    |\n    | HTTP REST API\n    v\nProofFlow Backend (FastAPI + SQLite)\n    |\n    |--- Agent Work Ledger: Contract > Algorithm > Budget > Snapshot > Evidence > Claim > Evaluation > Packet\n    |--- Evidence Graph: Cases > Artifacts > Claims > Evidence\n    |--- Action Pipeline: Preview > Approve > Execute > Undo\n    |--- Policy Gates: Risk classification > Owner decision\n    |--- Proof Packets: Exportable markdown audit reports\n    v\nLocal Filesystem (scanned files, git repos)\n```\n\n## Core Capabilities\n\n### Agent Work Ledger\nRecords complex AI coding work as a first-class Case. The main flow is Work\nContract -> Algorithm Decision -> Cost Budget -> Snapshot -> Evidence -> Claim\n-> Evaluation -> Proof Packet, so maintainers can see what the agent promised,\nwhat approach it chose, what cost limits it accepted, what changed, what\nevidence backs its claims, whether the done criteria were satisfied, and which\nRisk Hints deserve human review.\n\n### Evidence-Backed Code Review (AgentGuard)\nAnalyzes git diffs, generates risk-scored claims, and links each claim to specific evidence (changed lines, test results). No claim exists without supporting evidence.\n\n### File Audit & Organization (LocalProof)\nScans directories, indexes files with SHA-256 hashes, extracts text for full-text search, and suggests organization actions — all tracked in an auditable Case.\n\n### Issue Triage\nCaptures issue text as a first-class Case with source Artifact, deterministic triage Claims, component inference, label suggestions, and Proof Packet export.\n\n### Policy Gate Enforcement\nHigh-risk filesystem actions (moves to system paths, bulk operations) are automatically paused at `pending_decision` status. Requires explicit owner approval before execution.\n\n### Safety Invariants\n- **No Contract, no Ledger** - AI coding work starts with explicit scope and done criteria\n- **No Algorithm Decision, no trusted strategy** - important approaches must be recorded before implementation\n- **No Cost Budget, no expensive workflow** - costly operations need declared limits first\n- **No Final Snapshot, no Finish** - finished ledgers must prove the reviewed repo state\n- **No Preview, no Action** — destructive operations require two-phase confirmation\n- **No Evidence, no Claim** — every assertion links to verifiable data\n- **No Ready Evaluation, no Quiet Success** - failed ledgers finish as `finished_with_risks`\n- **No Undo, no Destructive Action** — executed actions carry rollback metadata\n- **No Case, no Workflow** — all work is tracked in auditable containers\n\n### MCP Tool Suite (23 tools)\n`health` · `scan` · `suggest` · `review` · `triage_issue` · `start_work_contract` · `record_algorithm_decision` · `record_cost_budget` · `capture_snapshot` · `record_evidence` · `record_claim` · `evaluate_contract` · `finish_work_ledger` · `status` · `approve_execute` · `export_packet` · `search` · `list_cases` · `list_actions` · `undo` · `decide`\n\n`explain_risk_hint` records an evidence-backed Decision for a Ledger Risk Hint\nwithout suppressing the hint.\n\n## Technical Stack\n\n| Layer | Technology | Tests |\n|-------|-----------|-------|\n| Backend | Python 3.12, FastAPI, SQLite | 311 |\n| Frontend | React 19, TypeScript, Vite | 25 |\n| MCP Server | Python, MCP SDK, httpx | 44 |\n| CI | GitHub Actions (PR review + release gates) | Audit artifact + PR comment |\n\n## Security Features\n\n- Optional API key authentication (`PROOFFLOW_API_KEY`)\n- Rate limiting (`PROOFFLOW_RATE_LIMIT`)\n- AgentGuard test command execution is opt-in (`PROOFFLOW_ENABLE_TEST_COMMANDS`)\n- MCP concurrency guards (`PROOFFLOW_MCP_MAX_CONCURRENT`)\n- Filesystem action scope restrictions (allowed_roots)\n- CORS locked to localhost origins\n\n## Project Status\n\n**v0.1.0 — Stable release.** All core workflows functional, tested, and documented.\n\n| Milestone | Status |\n|-----------|--------|\n| Core evidence graph (Case/Artifact/Claim/Evidence) | Done |\n| LocalProof file audit workflow | Done |\n| AgentGuard code review workflow | Done |\n| Issue triage workflow | Done |\n| Policy gate enforcement | Done |\n| MCP server for Claude Code/Codex | Done |\n| Backup/restore with safety preview | Done |\n| Docker deployment | Done |\n| PyPI package (`proofflow-mcp`) | Done |\n\n## Roadmap\n\n- [ ] Multi-agent coordination (shared Cases across agents)\n- [ ] Vector RAG for semantic evidence retrieval\n- [x] GitHub Actions integration (CI-triggered reviews)\n- [x] VS Code extension ([Marketplace](https://marketplace.visualstudio.com/items?itemName=hyperion-gpu.proofflow))\n- [ ] Cloud sync option for team workflows\n- [ ] Webhook notifications for policy gate decisions\n\n## Development\n\nRun from the repository root in a single PowerShell session. Each\n`Push-Location` / `Pop-Location` block restores the working directory back to\nthe repository root, so the `python scripts/...` smoke tests and\n`scripts/demo_workflow.py` below can be pasted in the same session.\n\n```powershell\n# Run all tests\nPush-Location backend\npython -m pytest          # 311 tests\nPop-Location\n\nPush-Location frontend\nnpm run test              # 29 tests\nPop-Location\n\nPush-Location mcp-server\npip install -e \".[dev]\"\npython -m pytest          # 44 tests\nPop-Location\n\n# End-to-end smoke test (cwd: repository root)\npython scripts/mcp_smoke.py --cleanup\npython scripts/ledger_mcp_smoke.py --cleanup\npython scripts/ledger_risk_hints_smoke.py --cleanup\npython scripts/ledger_risk_hints_dogfood_matrix.py --cleanup\n\n# Demo workflow (cwd: repository root)\npython scripts/demo_workflow.py\n```\n\nLocal backend data defaults to `backend/data/`. For dogfood runs that should not\ntouch repository-local state, set `PROOFFLOW_DB_PATH` and `PROOFFLOW_DATA_DIR`\nto a temporary directory before starting the backend.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Security Policy](SECURITY.md)\n\n## License\n\nMIT\n\n---\n\nBuilt by [Hyperion-GPU](https://github.com/Hyperion-GPU) — making AI agent workflows auditable, safe, and provable.\n",
  "bytes": 15905,
  "sha": "1677c2d0e1d2a8f72ea64e78561d8ddfab19b420bcac7c1663fe149a5963a925",
  "repo_slug": "hyperion-gpu/proofflow-v0.1",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hyperion_gpu_proofflow_7e2c8fec/readme"
}