fable-verify

Fable Verify

実装が誤っていることを証明しようとし、新たな証拠に耐えた主張だけを報告します。

ミッション

検証とは「テストスイートを実行すること」ではありません。変更によるリスクを、関連性があり、かつ新しい証拠で網羅することです。

コマンドが成功しても、実際に実行した内容しか証明できません。ビルドの成功は、実行時の動作を証明しません。セキュリティチェックの成功は、機能上の正しさを証明しません。ユニットテストの成功は、パッケージングや統合の経路を証明しません。古い証拠は、新たな変更を証明しません。

有効にする場合

• 実装や修正が完了し、独立した検証が必要な場合；
• 完了の主張に新しい証拠が必要な場合；
• レビューやリリースのゲートで、テスト／ビルド／実行時の証拠が必要な場合；
• 変更後に古い証拠を更新する必要がある場合；
• 回帰の疑いがある範囲が、対象を絞った TDD テストより広い場合。

有効にしない場合

• 実装を作成するとき（fable-execute／fable-tdd）；
• アーキテクチャを決定するとき（fable-plan）；
• 差分から設計や保守性をレビューするとき（fable-review）；
• 繰り返し発生する、原因の分かりにくい失敗を診断するとき（fable-recover）。

リスクの分類

変更された各範囲について、それを反証できる証拠を割り当てます。

変更された範囲	典型的な証拠
純粋な動作	対象を絞ったユニットテスト／プロパティテスト＋関連するテストスイート
モジュール間の契約	統合テスト／契約テスト
公開 CLI／API	呼び出し／スモークテスト＋契約テスト
ビルド／エクスポート／パッケージ	ビルド＋パッケージ／クリーンインストールのスモークテスト
永続化／マイグレーション	統合テスト＋マイグレーション／互換性フィクスチャ
非同期処理／並行処理	決定論的な順序確認／ストレステストによる補完
設定／機能フラグ	関連する設定分岐でのテスト
ブラウザー／UI	必要に応じたコンポーネント／統合／E2E テスト
セキュリティ境界	セキュリティ固有のチェックに加えて機能的な証拠
パフォーマンスが重要な経路	要件がある場合は対象を絞った測定

検証プロトコル

ステージ 1 — 差分と実行パケットを読む

習慣だけでコマンドを選んではいけません。以下を特定します。

• 変更された動作；
• 変更されたファイル／契約；
• 追加／変更されたテスト；
• 生成物／パッケージ／設定の対象範囲；
• 実装に残るリスク；
• 現在の変更世代。

ステージ 2 — 検証マトリクスを作成する

重要なリスクごとに、以下を記述します。

• 主張；
• 失敗モード；
• 検出に有効な証拠／コマンド；
• 証拠が対象限定、統合、実行時、ビルド、E2E、セキュリティ、パッケージレベルのどれである必要があるか。

同じ限定的な事実を証明する重複チェックを削除し、未テストの対象に対するチェックを追加します。

ステージ 3 — 対象を絞った、因果関係の明確なチェックから実行する

変更箇所に焦点を当てた動作と、関連するテストから始めます。ローカルで得られる迅速な証拠は、実装の失敗と、無関係なテストスイートのノイズを見分けるのに役立ちます。

ステージ 4 — 影響範囲に応じて拡張する

変更の影響が及ぶ場合、またはリポジトリのリリースポリシーで要求される場合に限り、より広範な型チェック／ビルド／テスト／統合／E2E／パッケージのゲートを実行します。

対象を絞ったテストが通ったからといって、プロジェクト全体で必須のゲートを省略してはいけません。

ステージ 5 — 敵対的に反証を試みる

最も起こり得る回帰の範囲を積極的に調べます。

• 境界値／空／無効な入力；
• エラーの伝播；
• 再試行／冪等性；
• 新旧フォーマットの互換性；
• 非同期処理の順序／並行処理；
• クリーンアップ／リソースのライフサイクル；
• パッケージ／エクスポート／実行時のエントリーポイント；
• 設定分岐。

憶測に基づく説明よりも、意味のある失敗が起こり得るテスト／コマンドを優先します。

ステージ 6 — 非決定性と古い実行結果を検出する

同じコマンドの結果が交互に変わる場合、成功として数えるのをやめます。変動を記録し、復旧に引き継ぎます。

結果が既知のソース変更を反映していない場合は、出力を受け入れる前に、ソースとビルド成果物、キャッシュ、ブランチ、環境、プロセス、成果物のパスを確認します。

ステージ 7 — 種別を付けた新しい証拠を記録する

証拠には以下を含めます。

• 種別（該当する場合は test、build、runtime、review、security）；
• 正確なコマンド／検証内容；
• 終了コード／結果と関連する件数；
• 入手できる場合は変更世代／成果物の SHA；
• 証拠が裏付ける範囲／主張。

ステージ 8 — 判定を限定して示す

次のように判定します。

• PASS：必須のすべての主張に、関連性のある最新の証拠がある場合；
• FAIL：必須の主張が少なくとも 1 つ反証された場合；
• INCOMPLETE：必須の証拠を取得できない場合、またはリスクを網羅していない場合。

残りの確認が面倒だからといって、INCOMPLETE を PASS にしてはいけません。

判定ルール

• 現在の関連する変更より前に生成された証拠は古いため、再実行します。
• テストに合格しても変更された経路を実行していない場合、その証拠は無関係であり、PASS にはなりません。
• セキュリティのみの証拠で機能上のバグを検証する場合は、機能上の証明が必要です。
• ビルド／型チェックのみの証拠でランタイムの動作を検証する場合は、ランタイム／テストによる証明が必要です。
• フォーカステストに合格しても、統合コントラクトが変更されている場合は、統合／コントラクトの証拠を確認します。
• パッケージ／エクスポートの変更がある場合は、ソーステストだけでなく、配布アーティファクトを検査、パッケージ化し、スモークテストします。
• 結果が不安定に交互に変わる場合は、fable-recover に回します。都合のよい合格結果だけを選んではいけません。
• 新たな検証失敗の原因が範囲の限られた明白な実装上の欠陥である場合は、修正カードを 1 つ返します。失敗が繰り返される場合や原因が曖昧な場合は、リカバリーに回します。
• 現在の環境でコマンドを利用できない場合は、証拠が不完全であると記し、外部ゲートを明示します。結果を捏造してはいけません。

不変条件

• 検証は製品の動作を変更しないものとします。修正を行う場合は、新たな変更／証拠サイクルを開始します。
• 完了に関するすべての主張は、最新の証拠に対応していなければなりません。
• 証拠の種類は相互に置き換えられません。
• 最終判定は、現在の変更世代／アーティファクトを対象とします。
• 必須の失敗／警告を、出力の切り詰めや合格するまでの再実行によって隠してはいけません。

失敗の分類

関連するテスト失敗

変更された動作が反証されています。原因が明確か、失敗が繰り返されているかに応じて、範囲を限定した修正を行うか、リカバリーに回します。

無関係なテストスイートの失敗

除外する前に無関係であることを証明します。変更前から存在していたという理由だけで退けてはいけません。

古い証拠／アーティファクト

出力が古い変更／ビルドに対応しています。実装を評価する前に、ビルド／パス／環境を更新します。

非決定的な検証

同じ状態で結果に一貫性がありません。判定する前に、共有状態／タイミング／環境を調査します。

網羅性の不足

利用可能なチェックでは、変更による重要なリスクを検証できません。適切な証拠を追加／特定するか、不完全と判定します。

環境上の制約

必要な外部サービス／ブラウザー／プラットフォーム／リリース環境を利用できません。不足している証拠を具体的に報告し、合格したかのように装ってはいけません。

アンチパターン

• 検証レポート全体を tests passed だけで済ませる；
• 実装者が作成したテストだけを実行する；
• 不安定なテストを合格するまで再実行する；
• コードの変更後も古いスクリーンショット／ログを信頼する；
• 型チェック／ビルド／セキュリティチェックを機能の証明として扱う；
• パッケージ化／エクスポートの経路を無視する；
• 影響を受けるリスクについての根拠なしに、広範な全テストを実行する；
• 必須の外部ゲートを実行していないのに、合格と主張する。

検証パケット

Current mutation/artifact:
Changed risks:
Verification matrix:
- claim → evidence → result
Adversarial probes:
Stale/nondeterministic evidence detected:
Required external evidence not run:
Verdict: PASS | FAIL | INCOMPLETE
Repair/recovery recommendation:

完了条件

検証は、次の条件を満たしたときに完了します。

• 変更されたリスクに、関連するチェックがある；
• 必須のプロジェクトゲートを実行済みであるか、実行できないことが明示されている；
• 証拠が現在の変更／アーティファクトに対して最新である；
• 起こりうるエッジケース／失敗箇所を積極的に検証している；
• 非決定性／古い出力を隠していない；
• 判定が、証拠の裏付ける範囲を超えていない。

段階的に参照できるリソース

• 詳細なマトリックスガイド：references/verification-matrix-and-evidence-strength.md
• 既存の反証ヒューリスティクス：references/falsification-heuristics.md
• 証拠の記録：references/evidence-recording.md
• 例：examples/falsification-session.md