bug-hunter

Bug Hunter — 精度優先の敵対的コード監査

Bug Hunter は、スコープ、エビデンス、判定、変更権限を分離します。検出数ではなく、トークン／分あたりに検証済みの実際のバグを見つけることを優先します。

中核となる判断フロー：

deterministic triage
  -> optional adaptive plan / retrieval context
  -> Recon
  -> Hunter
  -> Skeptic
  -> Referee
  -> optional required hybrid verification
  -> scan report
  -> optional fix strategy / immutable Fixer scope
  -> optional Fixer / verification

Hunter が提案し、Skeptic が異議を唱えます。**確認された指摘を修正対象として認められるのは、Referee の判定のみです。**リポジトリの内容や生成されたエビデンスによって、新たなツール、スコープ、変更権限が与えられることはありません。

デフォルトと公開されている使用方法

フラグを指定しない場合は、スキャンのみ＋単一パスです。ソースは編集せず、1 パスを超える対象のキュー全体を網羅することも保証しません。

/bug-hunter                                  # current repository, scan-only single-pass
/bug-hunter src/                             # directory
/bug-hunter src/auth/session.ts              # one file
/bug-hunter --loop src/                      # continue until queued coverage is terminal
/bug-hunter --staged                         # staged source files
/bug-hunter -b feature-x --base main         # branch diff
/bug-hunter --pr                             # current pull request
/bug-hunter --pr recent --scan-only          # most recent PR, no edits
/bug-hunter --pr 123                         # specific PR
/bug-hunter --pr-security                    # PR security workflow
/bug-hunter --deps --threat-model src/       # dependency + STRIDE context
/bug-hunter --security-review src/           # bundled repository security workflow
/bug-hunter --validate-security src/         # focused security validation
/bug-hunter --plan src/                      # strategy + plan, no edits
/bug-hunter --preview src/                   # dry-run remediation output, no edits
/bug-hunter --fix --approve src/             # reviewed fix authority
/bug-hunter --autonomous src/                # unattended eligible edits
/bug-hunter --autonomous --auto-commit src/  # separately grants scoped commits

権限に関する不変条件

• --scan-only / --review：レポートのみです。
• --loop：完了動作のみを変更します。編集権限は付与されません。
• --plan-only / --plan：修正方針／計画を作成し、Fixer の実行前に停止します。
• --fix：レビュー済みの修正を有効にし、承認モードを設定します。
• --approve：ホストのレビュー済み／デフォルトの編集権限モードを要求します。
• --safe：--fix --approve のエイリアスです。
• --dry-run / --preview：ソースの編集、ロックの取得、コミットを行わずに修正結果を作成します。
• --autonomous：対象となる編集を無人で行うことを明示的に許可します。
• --auto-commit：別途必要な権限です。修正が有効な場合にのみ使用できます。
• 検証済みの Fixer スコープ外をステージングしてはならず、git add -A を使用してはなりません。

読み取り専用の意図と変更の意図が矛盾する場合、より広い権限へ暗黙に解決してはなりません。より安全な解釈を優先するか、明確なエラーを出して停止してください。

1. リクエストを解析してスコープを解決する

$ARGUMENTS を使用して初期化します：

LOOP_MODE=false
FIX_MODE=false
APPROVE_MODE=false
AUTONOMOUS_MODE=false
AUTO_COMMIT=false
DRY_RUN_MODE=false
PLAN_ONLY_MODE=false
DEP_SCAN=false
THREAT_MODEL_MODE=false
PR_SECURITY_MODE=false
SECURITY_REVIEW_MODE=false
VALIDATE_SECURITY_MODE=false

公開エイリアス／フラグを適用します：

• --loop -> LOOP_MODE=true；--no-loop は単一パス動作を維持します。
• --scan-only または --review -> FIX_MODE=false を維持します。
• --fix -> FIX_MODE=true、APPROVE_MODE=true。
• --approve -> FIX_MODE=true、APPROVE_MODE=true。
• --safe -> --fix --approve と同じです。
• --autonomous -> FIX_MODE=true、AUTONOMOUS_MODE=true、 APPROVE_MODE=false。
• --auto-commit -> AUTO_COMMIT=true；FIX_MODE=true でなければ拒否します。
• --dry-run または --preview -> FIX_MODE=true、DRY_RUN_MODE=true。
• --plan-only または --plan -> PLAN_ONLY_MODE=true。
• --deps -> DEP_SCAN=true。
• --threat-model -> THREAT_MODEL_MODE=true。
• --pr-security -> PR_SECURITY_MODE=true、DEP_SCAN=true、 THREAT_MODEL_MODE=true、FIX_MODE=false；PR セレクターのデフォルトは current です。
• --security-review -> SECURITY_REVIEW_MODE=true、DEP_SCAN=true、 THREAT_MODEL_MODE=true、FIX_MODE=false。
• --validate-security -> VALIDATE_SECURITY_MODE=true。
• --review-pr -> --pr current；引数なしの --pr -> --pr current； --last-pr -> --pr recent。

PR スコープ

--pr <current|recent|N> の場合は、次を実行します：

node "$SKILL_DIR/scripts/pr-scope.cjs" resolve "<selector>" \
  --repo-root "$PWD" [--base <base-branch>]

リゾルバーの結果を .bug-hunter/pr-scope.json に保存し、changedFiles の全内容をスキャンします。信頼できるベースを解決できない場合は、明示的に失敗してください。暗黙にベースを仮定してはなりません。

ステージ済みスコープ

--staged の場合は、git diff --cached --name-only で解決します。ステージ済みの変更がなければ、問題なく停止します。

ブランチスコープ

-b <branch> [--base <base>] の場合は、<base>...<branch> を解決し、結果のソースファイルの全内容をスキャンします。この公開ブランチ形式でベースが明示されていない場合、ドキュメント上のデフォルトは main です。

パススコープ

それ以外の場合、残りの引数をファイル／ディレクトリのパスとして扱います。空の場合は、現在のリポジトリが対象です。

エージェントの推論に独自の拡張子許可リストを重複して作るのではなく、トリアージ／インデックス作成で保守されているソース分類器を使用します。決定的なランタイムのルールに従って、ドキュメント／アセット／ビルド出力／ベンダーコンテンツを除外します。スキャン可能なソースが残らない場合は、その旨を報告して停止します。

2. 事前チェック

可能であれば、この SKILL.md の場所から SKILL_DIR を特定します。フォールバック先には、Claude Code、Codex、Cursor、Kiro、Copilot、Windsurf、OpenCode、Factory Droid CLI 用のエージェント固有のスキルディレクトリや、汎用の ~/.agents/skills が含まれる場合があります。

実行状態を作成する前に、次のことを行います。

1. Node.js 22 以降を必須とします。

2. .bug-hunter/payloads と .bug-hunter/domains を作成します。

3. 必須のロールファイルとランタイムヘルパーが存在することを確認します。

4. 可能であれば、コアの事前チェックを実行します。

   node "$SKILL_DIR/scripts/run-bug-hunter.cjs" preflight --skill-dir "$SKILL_DIR"
   

5. ドキュメントの検索は任意です。scripts/doc-lookup.cjs を優先し、フォールバックとして同梱の Context7 パスを使用します。ドキュメントがない場合、バージョンに依存する主張の確信度は下がりますが、推測が許可されるわけではありません。

6. 実行に使用する、サポート対象のオーケストレーションバックエンドを 1 つ選択します。委任は最適化であり、正確性の要件ではありません。local-sequential も完全なバックエンドとして有効です。

委任バックエンドを使用する場合は、modes/dispatch.md と templates/subagent-wrapper.md に従います。起動前に scripts/payload-guard.cjs でロールのペイロードを検証し、完了後に正規の成果物を検証します。

3. モデル処理前の決定論的なトリアージ

対象を特定した後、トリアージを実行します。

node "$SKILL_DIR/scripts/triage.cjs" scan "<TARGET_PATH>" \
  --output .bug-hunter/triage.json

その strategy、fileBudget、scanOrder、riskMap、domains、needsLoop を使用します。トリアージとインデックス作成では、保守対象のソース分類器を共有します。状態の初期化、インデックス作成、差分スコープ、範囲の拡張を通じて、リスクの優先順位を反映した順序を維持します。

ソーストークンの予算

ランタイムは、実際に割り当てられたファイルのソーストークン推定値の合計に基づいて、リスク順を維持しながら適応型のチャンクを構築します。統合または呼び出し元が明示的に上書きしない限り、ソーストークンのデフォルト予算は 48,000 です。予算を超えるファイルが 1 つある場合は、より大きな混合チャンクに埋もれさせず、単独で分離してマークします。

失敗時に処理を停止する証拠の不変条件の詳細については、docs/precision-protocol.md を参照してください。

単一パスとループ

トリアージが needsLoop: true を報告し、LOOP_MODE=false の場合は、次のように正確に警告します。

This target exceeds one-pass queued coverage. Single-pass mode is active.
The report may be partial; run `/bug-hunter --loop <path>` for complete queued
coverage.

LOOP_MODE=false は、ユーザーが --no-loop を渡したことを意味すると言わないでください。これは通常のデフォルトです。

LOOP_MODE=true の場合は、modes/loop.md（修正時は modes/fix-loop.md）を読み、サポートされているループドライバーを使用します。そこに定義されているガード付きの実験状態を初期化するか、参照します。有効なドライバーがないのにループが続くと装わないでください。

4. 任意の測定可能なコンテキスト

scripts/run-bug-hunter.cjs を実行する統合では、次のスキーマに準拠した情報を提供できます。

• .bug-hunter/benchmark-report.json；
• .bug-hunter/adaptive-plan.json（auto、fast、balanced、assurance）；
• .bug-hunter/retrieval-plan.json；
• 完全一致ハッシュの証拠キャッシュ情報；
• .bug-hunter/verification-plan.json / .bug-hunter/verification-report.json。

これらは限定された証拠／コンテキストのポリシーであり、新たな権限ではありません。呼び出し元が明示的に指定したソース、チャンク、トークン、確信度の設定が優先されます。適応型プランによってリポジトリのスコープを広げたり、変更権限を付与したりすることはできません。

仮説に基づく取得では、まず必須／直接的な証拠を読み込み、ハード予算に余裕がある場合に限り、任意のシンボル、依存関係、被依存関係、相互参照、信頼境界を追加します。

測定可能なアーキテクチャについては、docs/world-class-protocol.md を参照してください。

5. 任意のセキュリティコンテキスト

脅威モデル

THREAT_MODEL_MODE=true の場合は、次を読みます。

skills/threat-model-generation/SKILL.md

そのスキルに従って、Bug Hunter ネイティブの .bug-hunter/threat-model.md と関連するセキュリティ設定を生成するか、再利用します。現行の脅威モデルのコンテキストがすでに存在する場合は、読み取り専用の証拠として再利用できます。

依存関係の証拠

DEP_SCAN=true の場合は、次を実行します。

node "$SKILL_DIR/scripts/dep-scan.cjs" \
  --target "<TARGET_PATH>" --output .bug-hunter/dep-findings.json

現在、サポート対象の解析／到達可能性判定は、npm、pnpm、Yarn、または Bun のロックファイルを使用する JavaScript／TypeScript プロジェクトに限られます。scanner-unsupported は未解決であり、問題がない状態ではありません。

バンドルされたセキュリティワークフロー

これらのフラグは、バンドルされたローカルスキルにルーティングします。

• --pr-security -> skills/commit-security-scan/SKILL.md
• --security-review -> skills/security-review/SKILL.md
• --threat-model -> skills/threat-model-generation/SKILL.md
• --validate-security -> skills/vulnerability-validation/SKILL.md

セキュリティワークフローの意図だけでは、Fixer の権限は付与されません。

6. ロールを段階的に読み込む

ロールの正式な指示は skills/ にあります。prompts/ 内の互換ファイルは生成されたコピーであり、独立した正本ではありません。

各フェーズで必要なロールのみを読み込みます。

フェーズ	正式な指示
Recon	skills/recon/SKILL.md
Hunter	skills/hunter/SKILL.md
Skeptic	skills/skeptic/SKILL.md
Referee	skills/referee/SKILL.md
Fixer	skills/fixer/SKILL.md
Documentation	skills/doc-lookup/SKILL.md

キャリブレーション例は段階的に読み込むもので、すべての割り当てで必須のコンテキストではありません。各ロールのスキル指示に従ってください。曖昧なケースや信頼度の低いケース、または明示的に有用な場合にのみ、Hunter／Skeptic の例を読み込みます。判断が確定したケースでは、例にコンテキストを割かないでください。

委任されたフェーズでは、割り当てられたバグ／ファイルと、必要な先行証拠のみを含めます。統合済みの台帳全体を各ワーカープロンプトにコピーしないでください。

7. 実行モードを選択する

サイズ／分割戦略には triage.strategy を使用します。

• single-file -> modes/single-file.md
• small -> modes/small.md
• parallel -> modes/parallel.md
• extended -> modes/extended.md
• scaled -> modes/scaled.md
• large-codebase -> modes/large-codebase.md

選択されたバックエンドが local-sequential の場合は、トリアージのスコープ／順序／予算を維持しつつ、実行方法として modes/local-sequential.md を使用します。

大規模コードベースのリクエストを自動的にループモードに切り替えないでください。ユーザーが --loop を要求していない場合は、誠実に単一パスを実行し、未完了のキュー対象範囲を報告します。--loop が有効な場合は、サイズモードとループの契約を組み合わせます。

拡張／スケール／永続化された実行では、.bug-hunter/state.json、正確なソースハッシュ、上限付きの再試行、および試行ごとの新しい出力を使用してください。構成ランナーには、要求された正規成果物を書き出す実際のワーカーコマンドが必要です。何もしないワーカーはありません。

8. 証拠とソース整合性の不変条件

これらのルールは、すべてのモードで必ず守る必要があります。

• 割り当てられたパスは実パスを通じて正規化され、リポジトリ内にとどまります。
• ワーカーが報告できるのは、割り当てられた正確なソースファイルに関する指摘のみです。
• ディスパッチ前にソースハッシュを取得し、指摘／ファクトカード／完了状態を確定する直前に再確認します。
• ソースの変更、削除、読み取り不能、またはシンボリックリンクによる範囲外への逸脱があった場合、該当チャンクは失敗としてクローズします。
• 再開時には元のソースベースラインを保持します。中断された実行では、変更後のコンテンツを新しいベースラインとして黙って採用することはできません。
• 正規成果物の欠落または無効化は失敗したフェーズであり、クリーンな証拠として扱いません。
• カバレッジはファイルごとの証拠から導出します。親チャンクを完了済みとしても、ファイルの完了を作り出すことはできません。
• 重複する観察結果では、最も強い証拠と、有用な統合済みの相互参照／セキュリティメタデータを保持します。
• 敵対的レビューが完了していない指摘は unreviewed または manual-review のままとし、修正を許可する根拠にはできません。

9. Hunter -> Skeptic -> Referee

Hunter

割り当てられた本番ソースを、リスク／取得順に読みます。指摘には、具体的なランタイムトリガーとリポジトリ内の証拠が必要です。セキュリティ上の指摘は、必要に応じて実行可能な STRIDE／CWE の証拠を含め、正式な指摘スキーマを満たす必要があります。テストファイルはコンテキストとしてのみ扱います。

正規出力：.bug-hunter/hunter-findings.json。

Skeptic

現在のコードと関連する相互参照から各指摘に異議を唱えます。可能な場合は、フレームワーク依存の反証をドキュメントに対して検証します。一般的なレート制限の提案は棄却するのが容易かもしれませんが、到達可能なクレデンシャルスタッフィング、OTP/リセットの悪用、ロックアウトのバイパス、測定可能な増幅、および攻撃者によって引き起こされる高コストな処理は、通常の分析を受けます。

正規出力: .bug-hunter/skeptic.json。

Referee

Referee は最終的な REAL_BUG、NOT_A_BUG、または MANUAL_REVIEW の判定を独立して所有します。Referee レビューの欠落/失敗は、指摘を未解決かつ書き込み不可のままにします。

正規出力: .bug-hunter/referee.json。

10. ハイブリッド検証

検証計画が提供/要求された場合は、境界付きハイブリッド検証器を通じて実行します。チェックは、リポジトリ封じ込め、シークレットの除去/秘匿化、出力/時間の予算、および shell:false セマンティクスを伴う、不活性な argv 配列として実行されます。

失敗、タイムアウト、または利用不可となった必須チェックは、検証をフェイルクローズドにします。必須検証の失敗は Fixer の承認を妨げます。 成功したテスト/コンパイラ/静的チェックは証拠であり、無関係なバグが存在しないことの証明ではありません。

正規出力: .bug-hunter/verification-report.json。

11. スキャン結果の結合と提示

常に正規の Hunter/Referee 成果物を保持し、結合された .bug-hunter/scan-report.json を構築します。.bug-hunter/report.md を人間向けビューとしてレンダリングします。JSON が自動化の信頼できる情報源です。

最終結果は以下を区別しなければなりません:

• confirmed — Referee が指摘を受理した;
• dismissed — 証拠がそれを否定した;
• manualReview — 人間/より広範な判断が残っている;
• unreviewed — 敵対的レビューが完了しなかった;
• 失敗/保留中のカバレッジ;
• 該当する場合の必須検証の失敗。

要求されたスコープに未解決のレビュー、失敗したカバレッジ、または必須検証の失敗がまだある間は、「監査完了」、「完全なカバレッジ」、または「クリーン」と主張してはなりません。

LOOP_MODE=true の場合、キューに入れられたすべてのソースファイルが終端の結果に到達するか、明示的なハードブロッカー/ユーザーによる停止が実行を終了させるまで、ループ規約に従って続行します。LOOP_MODE=false の場合、1 回のパスがカバーした内容を正確に報告し、完全なキューのカバレッジが望ましい場合は --loop を推奨します。

12. 権限がある場合にのみ計画および修正する

確認されたバグがあり、PLAN_ONLY_MODE=true または FIX_MODE=true の場合、正規の修復戦略/計画成果物を構築します。実行可能な Fixer 作業を作成する前に、指摘を分類します。

検証済みのカナリア/ロールアウト計画における、Referee が確認した、信頼度の対象となる safe-autofix エントリのみが、不変の Fixer スコープに入ることができます。manual-review、larger-refactor、architectural-remediation、競合、またはレポート専用とマークされたエントリは、重大度に関係なく書き込み不可のままです。

正規の修復ファイルには以下が含まれます:

• .bug-hunter/fix-strategy.json
• .bug-hunter/fix-plan.json
• .bug-hunter/fixer-scope.json
• .bug-hunter/fix-report.json

実際の変更については、modes/fix-pipeline.md および skills/fixer/SKILL.md をお読みください。Git/ワークツリー/ロック/カナリア/サーキットブレーカー/ロールバックのセーフガードを保持します。要求されたワークツリー分離は、暗黙に直接編集へフォールバックしてはなりません。AUTO_COMMIT=true の場合にのみ、かつ承認されたパスのみをコミットします。

DRY_RUN_MODE=true の場合、編集/ロック/コミットの前に停止し、計画された出力を適用済みの修正ではなくプレビューとして報告します。

正式成果物

.bug-hunter/ 配下にある、スキーマに基づく重要な成果物は次のとおりです。

成果物	目的
triage.json	リスク／範囲／予算の決定論的な入力
adaptive-plan.json	制限付きの適応型コンテキスト／レビュー方針
recon.json	アーキテクチャ／信頼境界のコンテキスト
retrieval-plan.json	仮説の優先順位に基づく、範囲を限定した証拠
hunter-findings.json	Hunter の主張
skeptic.json	敵対的な異議
referee.json	最終判定
verification-report.json	ハイブリッド検証の証拠
scan-report.json	統合された最終的な機械可読結果
coverage.json	ファイルごとのカバレッジ状態
fix-strategy.json	修正の分類
fix-plan.json	カナリア／ロールアウト計画
fixer-scope.json	不変の変更境界
fix-report.json	修正／検証／ロールバックの結果
benchmark-report.json	適合率／再現率／キャリブレーション／安定性／コスト／レイテンシの指標

品質とベンチマーク

ソース開発で実行する、リポジトリ全体のゲートは次のとおりです。

pnpm quality:world-class

同梱のベンチマーク用フィクスチャは、測定／ゲートの契約を検証します。普遍的な優位性を独立に証明するものではありません。外部向けの主張には、未公開のリポジトリ、ブラインド化されたラベル、繰り返し実行、公開されたモデル／ランタイムのバージョン、比較可能なベースラインが必要です。docs/world-class-protocol.md を参照してください。

セルフテスト

ソースチェックアウトから、開発用フィクスチャを読み取り専用モードでスキャンし、evals/evaluate-fixture.cjs で評価できます。npm ランタイムでは、開発用フィクスチャの回答が除外される場合があります。このスキルに過去のテスト件数を記載するのではなく、決定論的なプロトコルのリグレッション検証にはベンチマークゲートを使用してください。

失敗時の方針

以下の場合はフェイルクローズします。

• 必須の正式成果物が無効または不足している場合
• ソースの整合性またはリポジトリの包含範囲に問題がある場合
• 必須の検証に失敗した場合
• 委譲されたペイロードが無効な場合
• 影響を受ける検出結果について Referee が失敗した場合
• 不変の Fixer 範囲に違反した場合
• Git／ワークツリーの安全な保持状態に問題がある場合

復旧可能なワーカーの失敗は、設定された上限内で、新しい試行出力を使って再試行できます。復旧不可能なチャンクは、失敗または部分完了の状態となり、可視化されます。

証拠を取得できない場合、スキャナーがサポートされていない場合、レビューに失敗した場合、安全性チェックに失敗した場合に、正常な結果へ変換してはなりません。