ProofFlow

ProofFlow

English | 简体中文

AI コーディングのためのエージェント作業台帳。

バイブコーディングは高速です。しかし、盲目的に信頼するだけでは不十分です。

ProofFlow は、作業契約から証明パケットに至るまでの全工程を記録することで、AI が生成した作業をレビュー可能、追跡可能、かつ元に戻せるようにします。まず契約を作成し、アルゴリズムの決定を記録し、コスト予算を宣言し、コードの状態をスナップショットとして保存し、主張を証拠に結び付け、完了基準を評価してから、監査可能なパケットとしてエクスポートします。

最新リリース： v0.1.8 - AI コーディングのためのエージェント作業台帳

▶ 72 秒のデモを見る： AI エージェントの主張から検証可能な Proof Packet へ

デモ素材（延期）： エンドツーエンドの dogfood Demo_Asset GIF と、v0.1.x の dogfood-and-channel-polish マイルストーン向けの VSCode_Channel インライン監査／承認ゲートのスクリーンショットは、次回の dogfood サイクルに延期されています（このマイルストーンではキャプチャ可能な VS Code ウィンドウがありません）。PLANS.md#vscode-channel-screenshots-deferred-from-v0-1-x-dogfood で追跡しています。

📦 Proof Packet の例： コードレビュー · イシュートリアージ · エージェント作業台帳 · 台帳の dogfood

メンテナーのワークフロー： docs/maintainer_evidence_workflow.md

エージェント作業台帳ガイド： docs/agent_work_ledger.md

台帳のリスクヒント： docs/ledger_risk_hints.md

5 分で始める MCP： docs/ledger_quickstart_mcp.md

台帳の PR コメントテンプレート： docs/examples/pr_comment_agent_work_ledger.md

AgentGuard のセマンティックルール： docs/agentguard_semantic_rules.md

エージェント作業台帳

ProofFlow は PR レビューを支援するだけではありません。AI コーディング作業のためのローカルファーストな台帳です。Ledger Case には、エージェントがコードを変更する前、変更中、変更後のワークフローを記録します。

1. 作業契約 - 目的、リポジトリのパス、許可する範囲、禁止する操作、必須のテスト、完了条件、必要なエビデンス、アルゴリズムの要件、コスト予算を記録します。
2. アルゴリズムの決定 - 実装前に、選択したアプローチ、その根拠、代替案、不変条件、禁止するアプローチを記録します。
3. コスト予算 - 費用のかかる作業を始める前に、トークン、API、GPU、CPU、実行時間、反復回数の上限を設定します。
4. スナップショット - git diff、変更されたファイル、HEAD SHA、ベース参照、diff ハッシュを取得し、レビュー担当者が検証対象のコードの状態を正確に把握できるようにします。
5. エビデンス - コマンドの出力、テストの出力、差分、メモ、スクリーンショット、その他の成果物を、検索可能なエビデンスとして保存します。
6. 主張 - エージェントのすべての主張にエビデンスとの紐付けを必須とし、紐付けるまでは信頼できないものとして扱います。
7. 評価 - 必須テスト、アルゴリズムの決定、コスト予算、範囲の境界、エビデンスの不足、未承認のリスク、疑わしい経路に関する非ブロッキングのリスクヒントを、決定論的にチェックします。
8. 証明パケット - 契約、アルゴリズムの決定、コスト予算、タイムライン、スナップショット、主張、エビデンス、評価、決定、残存リスクを Markdown にエクスポートします。

主な流れ：作業契約 -> アルゴリズムの決定 -> コスト予算 -> スナップショット -> エビデンス -> 主張 -> 評価 -> 証明パケット。この流れにより、製品の中核となる不変条件を明確に保ちます。Case がなければワークフローはなく、エビデンスがなければ信頼できる主張はなく、完了条件の評価がなければ、気付かれないまま成功扱いされることはありません。

リスクヒントは ProofFlow を自動的なアルゴリズム判定ツールにすることなく、エビデンスの流れを拡張します。マッピングが必要な場面での再生成、予算超過を示すメタデータ、出力は証明しても手法は証明しないテストなど、記録された経路が誤っている可能性や、コストがかかりすぎる可能性がある場合に、メンテナーへ知らせます。

アーキテクチャと評価モデルの詳細は docs/agent_work_ledger.md を、MCP の一連の流れを実行するには docs/ledger_quickstart_mcp.md を参照してください。

ProofFlow のレビュー済み検証

ProofFlow v0.1.6 は、実際のリポジトリの PR で実地検証されました。GitHub Actions のワークフローで AgentGuard が実行され、安定した PR サマリーコメントが投稿され、 summary.json がアップロードされ、ダウンロード可能な Proof Packet がエクスポートされました。

• 実際の PR：#94 Dogfood v0.1.6 CI review story
• レビュー実行：ProofFlow PR Review #25953071865
• 実地検証からのパッチリリース：v0.1.6.1
• 結果：プッシュのたびに更新される安定したコメントが 1 件、Proof Packet と summary.json を含むアーティファクトが 1 件、マージのブロックなし。

課題

AI コーディングエージェント（Claude Code、Codex、Copilot Workspace）は、ファイルを変更したり、コマンドを実行したり、自律的に判断したりできます。しかし、以下を実現する標準的な方法はありません。

• 監査：エージェントが何を行い、その理由は何かを確認する
• 制御：リスクの高いアクションを実行前に制限する
• 証明：コードレビューで、実際に主張どおりの確認が行われたことを証明する
• 取り消し：エージェントが開始した変更を、確信を持って元に戻す

ProofFlow はエージェントとファイルシステムの間に位置し、すべてのアクションとその根拠を結び付けるエビデンスグラフを作成することで、この課題を解決します。

クイックスタート

Docker（推奨）

新しくクローンしたリポジトリの親ディレクトリから実行してください。 Push-Location / Pop-Location の組み合わせにより、docker compose up コマンドの実行中は作業ディレクトリがリポジトリのルートに保たれ、ブロックの 終了後に元の場所へ戻ります。そのため、このスニペットは PowerShell の単一 セッションにそのままコピーして安全に実行できます。

git clone https://github.com/Hyperion-GPU/ProofFlow-v0.1.git
Push-Location ProofFlow-v0.1
docker compose up
Pop-Location

バックエンド：http://localhost:8787 | フロントエンド：http://localhost:5173

Docker は ProofFlow のローカルホスト信頼境界を維持するため、デフォルトで両方の ポートを 127.0.0.1 に公開します。ローカルでの保護を強化するには、起動前に API キーを設定してください。

PROOFFLOW_API_KEY=change-me docker compose up

Docker のフロントエンドでバックエンド認証を有効にする場合は、同じ PROOFFLOW_API_KEY の値をビルド時に使用してください。これにより、Vite が 静的フロントエンドバンドルに VITE_PROOFFLOW_API_KEY を埋め込めます。AgentGuard の test_command 実行はデフォルトで無効です。レビュー中にバックエンドでローカルの テストコマンドを実行する場合に限り、意図的に PROOFFLOW_ENABLE_TEST_COMMANDS=true を設定してください。

手動

PowerShell の単一セッションで、リポジトリのルートから各コンポーネントを 起動してください。Push-Location / Pop-Location によって、バックエンドと フロントエンドのブロック間で作業ディレクトリを予測可能な状態に保てます。 バックエンドのポートは make dev-backend の標準設定に合わせて 8787 に固定 されています。npm run dev は長時間実行されるプロセスです。最初のセッションで バックエンドの uvicorn プロセスを表示したままにする場合は、2 つ目の PowerShell セッションでフロントエンドのブロックを実行してください。

# Backend
Push-Location backend
pip install -r requirements.txt
python -m uvicorn proofflow.main:app --port 8787
Pop-Location

# Frontend (long-running; recommended in a second PowerShell session)
Push-Location frontend
npm ci
npm run dev
Pop-Location

MCP 連携（Claude Code / Codex）

pip install proofflow-mcp

プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "proofflow": {
      "command": "proofflow-mcp",
      "env": { "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787" }
    }
  }
}

これで AI エージェントは、安全ゲートを適用しながら、Agent Work Ledger の維持、ファイルのスキャン、コードレビュー、イシューのトリアージ、アクションの提案、監査レポートのエクスポートを行えるようになります。

Codex メンテナープラグイン

ProofFlow には、リポジトリ内で使用する Codex プラグインも含まれています（plugins/proofflow-maintainer）。次の用途に使えるスタータープロンプトと、メンテナー向けのスキルを提供します。

• ProofFlow を使って現在の差分をレビューする。
• PR 用の Proof Packet を作成する。
• イシューのテキストを ProofFlow Case にトリアージする。
• 複雑なコード作業のために Agent Work Ledger を維持する。

このプラグインは同じローカルの proofflow-mcp サーバーを使用し、バックエンドの信頼境界を http://127.0.0.1:8787 に維持します。 想定される引き継ぎ形式については、公開可能な Agent Work Ledger の例 をご覧ください。

アーキテクチャ

AI Agent (Claude Code / Codex / Custom)
    |
    | MCP Protocol (stdio)
    v
ProofFlow MCP Server (23 tools)
    |
    | HTTP REST API
    v
ProofFlow Backend (FastAPI + SQLite)
    |
    |--- Agent Work Ledger: Contract > Algorithm > Budget > Snapshot > Evidence > Claim > Evaluation > Packet
    |--- Evidence Graph: Cases > Artifacts > Claims > Evidence
    |--- Action Pipeline: Preview > Approve > Execute > Undo
    |--- Policy Gates: Risk classification > Owner decision
    |--- Proof Packets: Exportable markdown audit reports
    v
Local Filesystem (scanned files, git repos)

主な機能

Agent Work Ledger

複雑な AI コーディング作業を、第一級の Case として記録します。主なフローは Work Contract -> Algorithm Decision -> Cost Budget -> Snapshot -> Evidence -> Claim -> Evaluation -> Proof Packet です。これにより、エージェントが何を約束したか、どのアプローチを選んだか、どのコスト上限を受け入れたか、何が変更されたか、主張を裏付ける証拠は何か、完了基準が満たされたか、どの Risk Hint を人間が確認する必要があるかを、メンテナーが把握できます。

証拠に基づくコードレビュー（AgentGuard）

git の差分を分析し、リスクスコア付きの主張を生成して、それぞれの主張を具体的な証拠（変更行、テスト結果）に関連付けます。裏付けとなる証拠がなければ、主張は存在しません。

ファイル監査と整理（LocalProof）

ディレクトリをスキャンし、SHA-256 ハッシュでファイルをインデックス化し、全文検索用のテキストを抽出して、整理アクションを提案します。これらはすべて、監査可能な Case で追跡されます。

イシューのトリアージ

イシューのテキストを、ソース Artifact、決定論的なトリアージ Claim、コンポーネントの推定、ラベルの提案、Proof Packet のエクスポート機能を備えた第一級の Case として記録します。

ポリシーゲートの適用

システムパスへの移動や一括操作など、リスクの高いファイルシステム操作は、自動的に pending_decision ステータスで一時停止されます。実行するには、オーナーによる明示的な承認が必要です。

安全性の不変条件

• Contract がなければ Ledger は作成しない - AI コーディング作業は、明示的なスコープと完了基準から始めます。
• Algorithm Decision がなければ、信頼できる戦略はありません - 重要なアプローチは、実装前に記録する必要があります。
• Cost Budget がなければ、高コストのワークフローは実行しません - コストのかかる操作には、事前に上限を宣言する必要があります。
• Final Snapshot がなければ、完了できません - 完了した Ledger では、レビュー対象のリポジトリの状態を証明する必要があります。
• プレビューがなければ、アクションは実行しません — 破壊的な操作には、2 段階の確認が必要です。
• 証拠がなければ、Claim はありません — すべての主張は検証可能なデータに関連付けられます。
• Ready Evaluation がなければ、問題のない成功とは見なしません - 失敗した Ledger は finished_with_risks として完了します。
• Undo がなければ、破壊的なアクションは実行しません — 実行されたアクションにはロールバックのメタデータが付与されます。
• Case がなければ、ワークフローは実行しません — すべての作業は監査可能なコンテナーで追跡されます。

MCP ツールスイート（23 ツール）

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

explain_risk_hint は、Ledger の Risk Hint を抑制せずに、証拠に基づく Decision を記録します。

技術スタック

レイヤー	テクノロジー	テスト
バックエンド	Python 3.12、FastAPI、SQLite	311
フロントエンド	React 19、TypeScript、Vite	25
MCP サーバー	Python、MCP SDK、httpx	44
CI	GitHub Actions（PR レビュー + リリースゲート）	監査アーティファクト + PR コメント

セキュリティ機能

• オプションの API キー認証（PROOFFLOW_API_KEY）
• レート制限（PROOFFLOW_RATE_LIMIT）
• AgentGuard のテストコマンド実行はオプトイン方式です（PROOFFLOW_ENABLE_TEST_COMMANDS）
• MCP の同時実行ガード（PROOFFLOW_MCP_MAX_CONCURRENT）
• ファイルシステム操作のスコープ制限（allowed_roots）
• CORS は localhost のオリジンに限定されています

プロジェクトの状況

v0.1.0 — 安定版リリース。 コアワークフローはすべて機能し、テストとドキュメント整備が完了しています。

マイルストーン	状況
コア証拠グラフ（Case/Artifact/Claim/Evidence）	完了
LocalProof ファイル監査ワークフロー	完了
AgentGuard コードレビューのワークフロー	完了
Issue トリアージワークフロー	完了
ポリシーゲートの適用	完了
Claude Code/Codex 用 MCP サーバー	完了
安全性プレビュー付きバックアップ／復元	完了
Docker デプロイ	完了
PyPI パッケージ（proofflow-mcp）	完了

ロードマップ

• 複数エージェントの連携（エージェント間で Case を共有）
• セマンティックな証拠検索のためのベクトル RAG
• GitHub Actions との統合（CI によってトリガーされるレビュー）
• VS Code 拡張機能（Marketplace）
• チームのワークフロー向けクラウド同期オプション
• ポリシーゲートの判定に関する Webhook 通知

開発

リポジトリのルートから、1 つの PowerShell セッション内で実行してください。各 Push-Location / Pop-Location ブロックは作業ディレクトリをリポジトリのルートに戻すため、 以下の python scripts/... スモークテストと scripts/demo_workflow.py は同じセッションに貼り付けて実行できます。

# Run all tests
Push-Location backend
python -m pytest          # 311 tests
Pop-Location

Push-Location frontend
npm run test              # 29 tests
Pop-Location

Push-Location mcp-server
pip install -e ".[dev]"
python -m pytest          # 44 tests
Pop-Location

# End-to-end smoke test (cwd: repository root)
python scripts/mcp_smoke.py --cleanup
python scripts/ledger_mcp_smoke.py --cleanup
python scripts/ledger_risk_hints_smoke.py --cleanup
python scripts/ledger_risk_hints_dogfood_matrix.py --cleanup

# Demo workflow (cwd: repository root)
python scripts/demo_workflow.py

ローカルバックエンドのデータは、デフォルトで backend/data/ に保存されます。リポジトリ内の状態に 影響を与えずに dogfood 実行するには、バックエンドを起動する前に PROOFFLOW_DB_PATH と PROOFFLOW_DATA_DIR を一時ディレクトリに設定してください。

貢献

貢献を歓迎します！ガイドラインについては CONTRIBUTING.md をご覧ください。

• 行動規範
• セキュリティポリシー

ライセンス

MIT

---

Hyperion-GPU が開発 — AI エージェントのワークフローを監査可能、安全、かつ検証可能にします。