[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11259":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":8,"rankLanguage":8,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":8,"pushedAt":8,"updatedAt":28,"readmeContent":29,"aiSummary":30,"trendingCount":14,"starSnapshotCount":14,"syncStatus":12,"lastSyncTime":31,"discoverSource":32},11259,"ProofFlow-v0.1","Hyperion-GPU\u002FProofFlow-v0.1","Hyperion-GPU",null,"Python",108,8,2,3,0,6,40.46,"MIT License",false,"main",[21,22,23,24,25,26,27],"agent-safety","ai-agents","audit","code-review","codex","developer-tools","mcp","2026-06-12 04:00:54","# 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,\nsnapshot the code state, bind claims to evidence, evaluate done criteria, then\nexport an auditable packet.\n\n**Latest release:** [v0.1.8 - Agent Work Ledger for AI coding](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Freleases\u002Ftag\u002Fv0.1.8)\n\n▶ **Watch the 72s demo:** [From AI agent claims to verifiable Proof Packets](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Freleases\u002Ftag\u002Fv0.1.3)\u003Cbr>\n📦 **Example Proof Packets:** [`code review`](docs\u002Fexamples\u002Fproof_packet_codex_review.md) · [`issue triage`](docs\u002Fexamples\u002Fproof_packet_issue_triage.md) · [`agent work ledger`](docs\u002Fexamples\u002Fproof_packet_agent_work_ledger.md) · [`ledger dogfood`](docs\u002Fexamples\u002Fproof_packet_agent_work_ledger_dogfood.md)\n\n**Maintainer workflow:** [`docs\u002Fmaintainer_evidence_workflow.md`](docs\u002Fmaintainer_evidence_workflow.md)\n\n**Agent Work Ledger guide:** [`docs\u002Fagent_work_ledger.md`](docs\u002Fagent_work_ledger.md)\n\n**5-minute MCP quickstart:** [`docs\u002Fledger_quickstart_mcp.md`](docs\u002Fledger_quickstart_mcp.md)\n\n**Ledger PR comment template:** [`docs\u002Fexamples\u002Fpr_comment_agent_work_ledger.md`](docs\u002Fexamples\u002Fpr_comment_agent_work_ledger.md)\n\n**AgentGuard semantic rules:** [`docs\u002Fagentguard_semantic_rules.md`](docs\u002Fagentguard_semantic_rules.md)\n\n[![ProofFlow demo thumbnail](docs\u002Fassets\u002Fproofflow-demo-thumbnail.png)](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Freleases\u002Ftag\u002Fv0.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, and evidence requirements.\n2. **Snapshot** - capture the git diff, changed files, HEAD SHA, base ref, and\n   diff hash so reviewers know exactly what code state was examined.\n3. **Evidence** - store command output, test output, diffs, notes, screenshots,\n   or other artifacts as searchable evidence.\n4. **Claim** - require every agent claim to bind to evidence before it is\n   trusted.\n5. **Evaluation** - deterministically check required tests, scope boundaries,\n   missing evidence, and unaccepted risks.\n6. **Proof Packet** - export the contract, timeline, snapshots, claims,\n   evidence, evaluation, decisions, and remaining risks into markdown.\n\nMain chain: Work Contract -> Snapshot -> Evidence -> Claim -> Evaluation ->\nProof Packet. This keeps the core product invariant sharp: no Case, no\nworkflow; no Evidence, no trusted Claim; no done criteria evaluation, no quiet\nsuccess.\n\nSee [`docs\u002Fagent_work_ledger.md`](docs\u002Fagent_work_ledger.md) for the full\narchitecture and evaluation model, or\n[`docs\u002Fledger_quickstart_mcp.md`](docs\u002Fledger_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\u002Fassets\u002Fproofflow-pr94-agentguard-comment.svg)](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Fpull\u002F94#issuecomment-4465608299)\n\n- Real PR: [#94 Dogfood v0.1.6 CI review story](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Fpull\u002F94)\n- Review run: [ProofFlow PR Review #25953071865](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Factions\u002Fruns\u002F25953071865)\n- Patch release from dogfood feedback: [v0.1.6.1](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Freleases\u002Ftag\u002Fv0.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:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Factions\u002Fworkflows\u002Fbackend.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Factions\u002Fworkflows\u002Fbackend.yml)\n[![Frontend](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Factions\u002Fworkflows\u002Ffrontend.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Factions\u002Fworkflows\u002Ffrontend.yml)\n[![MCP Server](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Factions\u002Fworkflows\u002Fmcp-server.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1\u002Factions\u002Fworkflows\u002Fmcp-server.yml)\n[![VS Code Marketplace](https:\u002F\u002Fimg.shields.io\u002Fvisual-studio-marketplace\u002Fv\u002Fhyperion-gpu.proofflow?label=VS%20Code&logo=visualstudiocode)](https:\u002F\u002Fmarketplace.visualstudio.com\u002Fitems?itemName=hyperion-gpu.proofflow)\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fproofflow-mcp?logo=pypi&logoColor=white)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fproofflow-mcp\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\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\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FHyperion-GPU\u002FProofFlow-v0.1.git\ncd ProofFlow-v0.1\ndocker compose up\n```\n\nBackend: http:\u002F\u002Flocalhost:8787 | Frontend: http:\u002F\u002Flocalhost: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\n```bash\n# Backend\ncd backend && pip install -r requirements.txt\npython -m uvicorn proofflow.main:app --port 8787\n\n# Frontend\ncd frontend && npm ci && npm run dev\n```\n\n### MCP Integration (Claude Code \u002F 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:\u002F\u002F127.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\u002Fproofflow-maintainer`](plugins\u002Fproofflow-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:\u002F\u002F127.0.0.1:8787`.\nSee the public-safe\n[`Agent Work Ledger` example](docs\u002Fexamples\u002Fproof_packet_agent_work_ledger.md)\nfor the expected handoff shape.\n\n## Architecture\n\n```\nAI Agent (Claude Code \u002F Codex \u002F Custom)\n    |\n    | MCP Protocol (stdio)\n    v\nProofFlow MCP Server (20 tools)\n    |\n    | HTTP REST API\n    v\nProofFlow Backend (FastAPI + SQLite)\n    |\n    |--- Agent Work Ledger: Contract > 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 -> Snapshot -> Evidence -> Claim -> Evaluation -> Proof Packet, so\nmaintainers can see what the agent promised, what changed, what evidence backs\nits claims, and whether the done criteria were satisfied.\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 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 (20 tools)\n`health` · `scan` · `suggest` · `review` · `triage_issue` · `status` · `approve_execute` · `export_packet` · `search` · `list_cases` · `list_actions` · `undo` · `decide`\n\n## Technical Stack\n\n| Layer | Technology | Tests |\n|-------|-----------|-------|\n| Backend | Python 3.12, FastAPI, SQLite | 300 |\n| Frontend | React 19, TypeScript, Vite | 25 |\n| MCP Server | Python, MCP SDK, httpx | 26 |\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\u002FArtifact\u002FClaim\u002FEvidence) | 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\u002FCodex | Done |\n| Backup\u002Frestore 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:\u002F\u002Fmarketplace.visualstudio.com\u002Fitems?itemName=hyperion-gpu.proofflow))\n- [ ] Cloud sync option for team workflows\n- [ ] Webhook notifications for policy gate decisions\n\n## Development\n\n```bash\n# Run all tests\ncd backend && python -m pytest          # 295 tests\ncd frontend && npm run test             # 25 tests\ncd mcp-server && pip install -e \".[dev]\" && python -m pytest  # 24 tests\n\n# End-to-end smoke test\npython scripts\u002Fmcp_smoke.py --cleanup\n\n# Demo workflow\npython scripts\u002Fdemo_workflow.py\n```\n\nLocal backend data defaults to `backend\u002Fdata\u002F`. 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:\u002F\u002Fgithub.com\u002FHyperion-GPU) — making AI agent workflows auditable, safe, and provable.\n","ProofFlow 是一个用于AI编码工作的代理工作账本，它使得AI生成的工作可审查、可追踪和可逆。该项目通过记录从工作合同到证明包的全过程，确保每个步骤都有据可查，包括但不限于工作合同、代码快照、证据绑定、完成标准评估等环节。采用Python开发，并遵循MIT许可证，具备良好的开源社区支持度。适用于需要对AI辅助编程过程进行严格审计与控制的场景，如企业级软件开发中的代码审查、问题分类等工作流管理。","2026-06-11 03:31:34","CREATED_QUERY"]