fable-anti-churn

Fable Anti-Churn

目的

fable-anti-churn は、get-fable における重複作業とエビデンス再利用を防止するための信頼できるエンジンです。ネイティブの Rust エンジン（crates/fable-anti-churn）とローカル CLI スクリプトの両方を活用し、作業リクエストを暗号学的にフィンガープリント化（RFC 8785 JCS + SHA-256）します。予約レシートを追跡し、過去に合格した同一のエビデンスを再利用し、重複アクションをブロックし、繰り返し発生する決定論的な失敗を停止し、ミリ秒未満の実行時間で昇格の証明を検証します。

使用する場面

• テストコマンド、ビルドスクリプト、静的解析ツールを繰り返し実行する前。
• サブエージェント、バックグラウンドワークフロー、外部ツール呼び出しを開始する前。
• アクションまたはコマンドが決定論的に失敗し、無条件の再試行ではなくローカルでの修正が必要な場合。
• 候補の昇格ゲート（パッケージの整合性、テスト合格、権限の検証）を評価する場合。
• すべてのライフサイクルフック（SessionStart、PreToolUse、PostToolUse、PostToolUseFailure、Stop）で使用する場合。

使用しない場面

• ユーザーのタスク全体をキャンセルまたは終了するためには使用しないでください。ゲートが対象とするのは、特定の重複するローカルアクションのみです。
• 有効なコード変更の代替として使用しないでください。コードが変更されたら、型付き無効化（candidate_changed など）を計算して、あらためて実行してください。
• 実際の人間による承認やセキュリティ境界を回避するためには使用しないでください。

入力

• action_event：action_kind、action_scope_digest、requirements_digest、candidate_digest、および環境ハッシュを含む正規 JSON ペイロード。
• prior_receipts：NDJSON 形式の過去のレシート台帳（.fable/anti-churn/receipts.ndjson）。
• core_policy：介入レベルのしきい値と再試行予算のパラメーターを含むポリシー設定。

期待される出力

• decision_receipt：35 個の正規フィールド、decision、reason_code、evidence_digest を含む、暗号学的に署名されたレシート。
• evidence_acceptance：検証済みの結果を反映し、保留中の予約を更新する、スタンプ付きのエビデンス受け入れ記録。
• churn_status：レシート総数、保留中の予約、合格したエビデンス、ブロックされたチャーンのサイクルを報告するリアルタイム台帳ステータス。

手順

1. 作業の識別情報をフィンガープリント化する： RFC 8785 の正規 JSON と SHA-256 を使用して、スコープ、要件、候補パッチ、依存関係、ポリシー、評価器をハッシュ化します。
2. 過去の台帳を参照する： .fable/anti-churn/receipts.ndjson をスキャンし、一致する予約または合格済みのエビデンスを確認します。
3. 冪等性を評価する：
   • 無効化情報がなく、完全に一致する合格済みエビデンスがある場合：reuse_prior_evidence を出力します。
   • 保留中の実行中予約がある場合：block_this_local_action を出力します（競合状態を防止します）。
   • ワークスペースに変更がなく、決定論的なローカル失敗がある場合：local_fix_required を出力します。
   • 有効な型付き無効化によって作業が変更された場合：allow_reexecution を出力します。
   • 同等のアクションが初回の場合：allow を出力し、予約レシートを記録します。
4. 実行して結果を記録する：
   • 成功した場合：accept を実行して、予約を pass に移行します。
   • ローカルで失敗した場合：local_failure レシートを記録して、直後の重複実行を防ぎます。
5. フックの不変条件を適用する： ライフサイクルイベントをインターセプトし、ターン完了時に未受理の予約やチャーンループが残らないようにします。

判断ルール

• ALLOW： 過去の予約がない、同等のアクションの初回実行。保留中のレシートで枠を予約します。
• ALLOW_REEXECUTION： 有効で未消費の型付き無効化を消費した後の再実行を許可します。
• ALLOW_WITH_ADVISORY： 作業の識別情報が不完全な場合に許可します（レートに関するアドバイザリを出力します）。
• REUSE_PRIOR_EVIDENCE： 完全に一致する作業に過去の合格済みエビデンスがある場合。トークンのオーバーヘッドなしで、保存済みの evidence_digest を返します。
• LOCAL_FIX_REQUIRED： 決定論的なローカル失敗を検出しました。コードが編集されるまで実行をブロックします。
• BLOCK_THIS_LOCAL_ACTION： 重複した保留中のアクション、無効なファンアウト、または型付き無効化を伴わない作業の変更。

ツールポリシー

• 確認および検証の手順では、読み取り専用のクエリを優先します。
• サブミリ秒で実行するため、ネイティブの Rust エンジンバイナリ（fable-anti-churn または get-fable-native anti-churn）を使用します。
• NDJSON 状態ファイルへの直接更新は、アトミックなファイルシステムロック（fs2）で保護します。
• 過去のレシートは削除も破損もさせず、不変の追記専用台帳を維持します。

エビデンス要件

• 35 個すべての正規フィールドを含み、禁止キーが 0 個の、有効なレシート。
• sha256:[0-9a-f]{64} 形式に準拠する SHA-256 ダイジェスト。
• 23/23 のシナリオ検証を確認する、合格済みのセルフテストコーパスレポート。
• ライフサイクルフェーズを完了としてマークする前に、保留中の予約がないことを確認します。

失敗時の処理

• local_fix_required または deterministic_local_failure が発生した場合：対象のソースコードを編集して不具合を解消します。ワークスペースを変更すると、失敗ロックが解除されます。
• 無効化が拒否された場合：無効化対象のレシートを調べ、理由コードが変更されたフィールドと一致していることを確認します。
• 失敗の連続回数が 2 に達した場合：コードの編集を試みる前に、根本原因を診断するために fable-recover に回します。

完了条件

• すべての未完了予約が pass または明示的な終端結果に移行していること。
• .fable/anti-churn/receipts.ndjson に未解決の保留中予約が 0 件であること。
• 状態台帳で anti-churn verify を実行し、検証エラーが 0 件であること。
• 現在の変更世代に一致する新しいエビデンスでテストの合格が確認されていること。

CLI コマンド

# Evaluate an action event against receipts ledger
bun ./bin/get-fable.js anti-churn decide event.json

# Accept passing evidence for an open reservation
bun ./bin/get-fable.js anti-churn accept <receipt-id> <evidence-digest> [pass|local_failure]

# Quick zero-latency check if an action/command is duplicate
bun ./bin/get-fable.js anti-churn check --action-kind targeted_test --target src/core.ts --command "bun test"

# Verify receipts ledger integrity
bun ./bin/get-fable.js anti-churn verify

# Run native 23-fixture self-test corpus
bun ./bin/get-fable.js anti-churn self-test

# Check anti-churn status & metrics
bun ./bin/get-fable.js anti-churn status

ライフサイクルフックの適用

1. SessionStart：.fable/anti-churn/receipts.ndjson をスキャンし、未完了の予約や継続的なローカル失敗ループを確認します。
2. PreToolUse (Bash / Agent)：アクションキーを計算します。無効化なしで重複している場合は、処理を傍受してブロックします。
3. PostToolUse (Write / Edit)：新しい候補ハッシュを計算し、ローカル失敗ロックを解除します。
4. PostToolUse (Bash Success)：失敗の追跡を無効化します。
5. PostToolUseFailure (Bash Failure)：決定論的なローカル失敗ループを検出し、盲目的な再試行をブロックします。
6. Stop：ターンを終了する前に、未解決の予約や破損したレシートがないことを確認します。

段階的なリソース

• 判断とレシートのアーキテクチャ — レシートスキーマと 35 個の正規フィールドの仕様を詳しく説明します。
• 脅威モデル — セキュリティ境界、信頼ドメイン、改ざん防止について説明します。
• プライバシーポリシー — 禁止フィールドとシークレットのマスキングを徹底します。
• 評価プロトコル — 23 シナリオの検証マトリクスとベースラインのアサーションについて説明します。
• ドクトリンのレビュー — 重複作業を防止するための数学的およびアーキテクチャ上の基盤について説明します。
• Claude との統合 — Claude Code 用のホストライフサイクルフックの設定について説明します。
• Codex との統合 — OpenAI Codex 用のホストライフサイクルフックの設定について説明します。
• イベントテンプレート — 標準的なアクションイベント JSON テンプレートです。
• レシートテンプレート — 正規の判断レシート JSON テンプレートです。