bound

BOUND

意味のある実行ステップの後に BOUND を使用し、エージェントが続行、再試行、再計画、またはロールバックすべきかを判断します。BOUND は完了した作業を評価します。どのコードを書くかは判断しません。

エージェント統合の種類

BOUND のエージェント統合はすべて指示のみです。つまり、エージェントが読み、従うプロンプトです。強制される統合はありません（エージェントのイベントシステム、MCP サーバー、ルール、ライフサイクルイベントへのプログラムによるフックはありません）。すべての統合は、エージェントが自発的に指示に従い、BOUND の判断に基づいて動作することを前提とします。

エージェント	ファイル	種類	仕組み
Cline	integrations/cline/INSTALL_BOUND.md	指示のみ	プロンプトベース。エージェントが指示に従います
Codex	integrations/codex/INSTALL_BOUND.md	指示のみ	プロンプトベース。エージェントが指示に従います
Claude Code	integrations/claude-code/INSTALL_BOUND.md	指示のみ	プロンプトベース。エージェントが指示に従います
Hermes Agent	integrations/hermes-agent/INSTALL_BOUND.md	指示のみ	プロンプトベース。エージェントが指示に従います
Kilo Code	integrations/kilo-code/INSTALL_BOUND.md	指示のみ	プロンプトベース。エージェントが指示に従います
汎用	integrations/generic/INSTALL_BOUND.md	指示のみ	プロンプトベース。あらゆるエージェントが指示に従います

重要な違い： 指示のみの統合では、BOUND の制御ループを説明し、各境界で BOUND の CLI または Python API を手動で呼び出すようエージェントに指示します。判断に基づいて動作する責任はエージェントにあります。BOUND がその動作を強制することはありません。将来の強制される統合では、エージェントのイベントシステムにフックして、判断がエージェントに届く前に介入します。

統合前に確認する

1. 最新の安定版パッケージをプロジェクトの環境にインストールします。

   pip install bound-policy
   

2. 記憶しているシグネチャに頼らず、インストールされた API を確認します。

   python -c "import bound; print(bound.__version__); print(bound.__all__)"
   bound integration-spec
   

3. プロジェクトで実際に使用するテスト、リント、型チェック、ビルドのコマンドを確認します。

4. エージェントが実際に備えているフック、モード、指示、コマンド、タスク境界、テレメトリ、チェックポイント機能を確認します。ネイティブの BOUND 統合や、文書化されていないフレームワークの仕組みを捏造しないでください。

5. 既存の INTEGRATION.md、INTEGRATION_REPORT.md、PLAN.md、bound_integration/ ファイルを探します。記録された結果は再現すべき主張として扱い、権威ある証拠とはみなさないでください。

実行の系譜を確立する

複数ステップの作業では、リポジトリのルートに PLAN.md を維持します。1 ステップの小規模なタスクでは、インライン計画を使用できます。意味のある各フェーズに安定した ID を付け、その目標、観測可能な受け入れチェック、リスクチェック、検証コマンド、予算、想定される成果物、担当者、関連する依存関係を定義します。

次の系譜を維持します。

intent -> plan phase -> StepContract -> execution -> ExecutionEvidence
       -> BOUND evaluation -> control action -> integration report

実行後もフェーズを保持します。戦略が大きく変わる場合は、PHASE-002-R1 のような派生 ID を作成し、再計画を隠すために履歴を書き換えないでください。

意味のある境界を選ぶ

実装と検証の後、焦点を絞った再試行の後、同じ目標の改善を続けるか判断する前に BOUND を呼び出します。トークン、ファイル読み取り、シェルコマンド、低レベルのツール呼び出しのたびに呼び出さないでください。

各境界には、観測可能な完了基準が必要です。意味のある成功またはリスクの兆候を観測できない場合は、ステップを統合するか再定義してください。

プロジェクトを変更する前に提案を記録する

実装前に、次の見出しを記録します。

Integration point:
Step boundary:
Available evidence:
Missing evidence:
Control-flow mapping:
Files to modify:

正確な検証コマンドと、削除可能な統合ファイルの最小セットを列挙します。取得できない指標は推定せず、取得できないものとして示してください。

ビルド契約とエビデンス

各フェーズを、少なくとも1つのAcceptanceCheck、任意のRiskCheck、期待される成果物、およびStepBudgetを含むStepContractに対応付けます。ExecutionEvidenceは、実行中に得られた観測結果、すなわちコマンドの終了コード、チェック結果、変更された成果物、再試行、ツール呼び出し、トークン数、実行時間、および提示されている場合はロールバックの可否からのみ収集します。

check_idの値は、契約とエビデンスの間で一致させます。必須チェックのエビデンスが欠けている場合、合格とは見なしません。未設定の予算（None）、測定不能、観測されたゼロを区別します。

インストール済みのevaluate_agent_step(...)ヘルパーを調査し、そのAPIで利用できる場合は優先して使用します。それ以外の場合はBoundWorkflow.evaluate_step(...)を呼び出し、次の内容を厳密に使用します。

ACCEPT   -> continue
RETRY    -> retry
REPLAN   -> replan
ROLLBACK -> rollback

5つ目のアクションを追加したり、BOUNDの採点式や判断式を再現したりしてはいけません。

検証済みエビデンスと来歴（v0.7.0）

BOUND v0.7.0では、エビデンスを報告する主体と検証する主体が分離されています。エージェントは参加者であり、判定者ではありません。

• 来歴の要件も含め、契約を事前に定義します。 各AcceptanceCheck／RiskCheckでは、accepted_provenance（受け入れる信頼できる来歴）、on_missing、on_claimedを指定できます。また、リスクチェックではdecision_criticalも指定できます（エビデンスが欠落または申告のみの場合、保証レベルはINSUFFICIENTとなり、無条件のACCEPTがブロックされます）。

• 許可する収集器を設定し、BOUNDに客観的な検証を実行させます。 BOUNDの収集器（PytestCollector、GitCollector、JUnitCollector、BudgetCollector、ProcessRuntimeCollector、CommandCollectorに加え、ネイティブのRuffEvidence、MypyEvidence、CoverageEvidence）を使用して、BOUNDが制御する検証を実行します。これらは、収集器の名前とバージョン、アーティファクトハッシュ、タイムゾーン対応のタイムスタンプを含むVERIFIED／OBSERVEDの来歴で、evidence.collected監査イベントを記録します。収集器のクラッシュや古いアーティファクトは、検証済みの合格として扱わず、正直に記録されます（evidence.collection_failed／INVALID）。

• エージェントはVERIFIEDの来歴を割り当てられません。 エージェントによる自己申告は常にCLAIMEDであり、VERIFIED／OBSERVEDにはなりません。エージェントは収集器の結果を上書きしたり、抑制したりしてはいけません。MISSINGは「未収集」を意味し、暗黙的に0として扱ってはいけません。テレメトリ指標のNoneは欠落を意味し、測定値のゼロではありません。

• 主観的な基準には別の評価者（EVALUATED）を使用します。 独立して再実行できない基準（UX品質など）はEVALUATEDです。これは正直な評価ですが、決してVERIFIEDではありません。

• BOUNDはエージェントの報告内容を記録し、エージェントは制御アクションを実行します。 BOUNDはaction.reported（reported_provenance=CLAIMED）を記録し、独立したフックによって確認用のobserved_actionを追加できます。制御アクションを実行するのはエージェントです。 BOUNDは薄いハーネスであり、ROLLBACKを出力し、結果の状態を独立して検証する場合があります。以前に確認済みのチェックポイントに対してbound rollback --executeを明示的に実行すれば、ワークスペースをロールバックできますが、明示的なオプトインなしに実行することはありません。

• 保証レベルによって候補の判断が制御されます。 BOUNDは、判断に重要なチェックの来歴からDecisionAssurance（VERIFIED／MIXED／CLAIMED／INSUFFICIENT）を算出します。判断に重要なエビデンスがCLAIMED／MISSINGのみの候補ACCEPTは、契約のon_missing／on_claimedアクションに格下げされます。次のように確認します。

  bound inspect <run_id>                  # per-check provenance + candidate vs final + assurance + coverage
  bound inspect <run_id> --only-unverified # only unverified/claimed/missing/invalid evidence
  bound inspect <run_id> --json           # machine-readable: provenance + assurance + coverage
  

数値評価を永続化する

すべての評価について、返されたBOUNDオブジェクトから数値を読み取り、次のように出力します。

BOUND evaluation
Acceptance (A): <4 decimals>
Influence (I): <4 decimals>
Risk (R): <4 decimals>
Cost (C): <4 decimals>
Score (S): <4 decimals>
Threshold (T): <4 decimals>
Decision: <ACCEPT|RETRY|REPLAN|ROLLBACK>
Next action: <continue|retry|replan|rollback>

また、提示されている重み、重み付けされた内訳、再試行マージン、ロールバックリスクのしきい値、およびスコアの来歴も永続化します。必要なレポート構成についてはreferences/integration-report.mdを参照してください。

以前のスコアを検証する

以前の統合記録がある場合は、その契約、エビデンス、基準、予算、スコア、判定、アクションを現在の実行と比較してください。入力が揃っている場合は、それらを再構成して、BOUND をもう一度呼び出してください。返された A/I/R/C/S/T、判定、アクションを記録と比較します。

• 不完全な過去の結果には not reproducible とマークし、不足しているデータを列挙します。
• エビデンスまたは設定が変更されている場合は、評価に stale とマークします。
• 履歴を暗黙的に上書きするのではなく、新しい評価を追加します。
• 不一致は一貫性チェックの失敗として扱い、続行する前に調査します。
• 数式を独自に実装して、別の評価器として使わないでください。

結果に応じて対応する

• ACCEPT：このフェーズの改善を終了し、次に進みます。
• RETRY：方針を維持し、的を絞った修正を1つ行い、新しいエビデンスを収集して、予算内で再評価します。
• REPLAN：現在の方針を中止し、実質的に異なるアプローチを選び、派生した契約 ID を作成します。
• ROLLBACK：無関係な変更や既存の変更を破棄せず、以前に安全と確認されたチェックポイントのみを復元してから、再計画します。安全なチェックポイントがない場合はその旨を報告し、破壊的な代替策は避けてください。

判定の系譜を記録する（v0.7.0）

BOUND v0.7.0 では、再現可能で追記専用のローカルな系譜として、すべての評価を .bound/runs/<run_id>/ の下に記録できます（契約 → エビデンス → スコア → 判定 → エージェントの結果）。実行ごとにオプトインで、後方互換性があります。実行を開始しなければ、何も記録されません。BOUND_LINEAGE_DISABLED=1 で無効にできます。

BOUND で評価する重要なタスクでは、次のルールに従ってください。

1. タスクごとに実行を1つ開始します。

   bound run start "<task>" --metadata phase=PHASE-001
   

   （Python では、with bound.start_run("<task>") as run: を使います。）

2. 安定したステップ ID／契約 ID を使います。 PLAN.md → StepContract(id=...) → 系譜の順に、同じ ID を引き継ぎます。同じステップを再計画する場合は -R<N> を付加します（PHASE-001 → PHASE-001-R1）。無関係な ID を新たに作成したり、再計画を隠すために履歴を書き換えたりしないでください。

3. 意味のある境界でのみ評価します（すべてのトークン／ファイル／コマンドごとではなく、実装と検証の後）。評価を実行に記録します。

   bound evaluate --run <run_id> --step PHASE-001 --attempt 1 \
       --action "..." --goal "..." \
       --acceptance A --influence I --risk R --cost C \
       --threshold 0.7 --retry-margin 0.1
   

   これにより step_started と evaluation_recorded が書き込まれ、JSON に lineage ブロックが追加されます。

4. 実際に行った後続アクションを記録します。BOUND が生成すべきだったアクションではありません。

   bound outcome --run <run_id> --step PHASE-001 --attempt 1 \
       --decision REPLAN --note "switched strategy to validator + parametrized tests"
   

   省略した場合、--next-action と --reason-code は --decision（ACCEPT|RETRY|REPLAN|ROLLBACK）から導出されます。

5. タスクの終了時に実行を明示的に終了します。

   bound run finish <run_id> --status completed|interrupted|failed --note "..."
   

   run_finished がない場合、実行は未完了／クラッシュとみなされます（ログは引き続き読み取れます）。with bound.start_run(...) を使った場合、コンテキストマネージャーが終了時に中断された実行を自動的に終了します。

6. ローカルな系譜のパス .bound/runs/<run_id>/（run.json と追記専用の events.jsonl）を報告し、判定ツリーを示します。

   bound inspect <run_id>
   

標準的なフローは、1つの実行につき2回の試行です。

Attempt 1  →  evidence 1/3 (A=0.3333)  →  REPLAN  → switch strategy
            (new step PHASE-001-R1, attempt 2)
Attempt 2  →  evidence 3/3 (A=1.0000)  →  ACCEPT  → continue to next step

イベントログは追記専用です。再計画では attempt+1 と -R<N> を付加した契約 ID を持つ新しい step_started が出力されます。以前の試行が書き換えられることはありません。プロンプト、トークン、ソースコードは保存されません。保存されるのは契約 ID、スコア、しきい値、判定、理由コード、後続アクション／メモのみです。データモデルと API の詳細については docs/lineage.md を参照してください。

統合を検証する

実際の契約を作成し、実際に観測されたエビデンスを収集して、BOUND を呼び出し、4つの判定のいずれかであることをアサートするとともに、正確な制御フローへのマッピングをアサートするエンドツーエンドテストを追加します。エビデンスが実際に契約を満たしている場合を除き、ACCEPT をハードコードしないでください。

利用側のリポジトリでは、すべての接続処理を薄く保ち、src/bound/ の外に配置してください。エビデンスを捏造したり、ポリシーロジックを複製したり、最終判定者として LLM を使ったりしないでください。