gitnexus-review

GitNexus レビュー

要求された変更範囲を、ソースの編集、コミット、プッシュ、投稿、スレッドの解決を行わずにレビューします。後で明示的に要求された場合は、これらの操作が許可されることがあります。構造的な証拠には GitNexus を、証明にはソースの検査を使用してください。どちらも他方を代替するものではありません。

ターゲットの解決

以下の形式を受け付けます。

入力	レビュー範囲
PR URL、owner/repo#42、#42、または番号のみ	GitHub PR
base...head	マージベース範囲
base..head	正確な2点間範囲
ブランチ、タグ、またはコミット	リポジトリのデフォルトブランチに対する ref
local、staged、unstaged、または作業ツリーに関する表現	ローカルの変更
ターゲットなし	現在のブランチのオープン PR。それ以外の場合はローカルの変更。それ以外の場合は現在のブランチ

明示的なターゲットが常に優先されます。番号のみは、gh 認証が機能している GitHub リポジトリの場合にのみ PR として解釈してください。それ以外の場合は ref または URL を尋ねてください。暗黙モードでブランチのコミットとローカルの変更の両方が見つかった場合は、どちらかを黙って破棄したり混ぜ合わせたりするのではなく、2つのラベル付きサーフェスとしてレビューしてください。

解決されたターゲットの種類、リポジトリルート、デフォルトブランチ、ベース SHA、ヘッド SHA、該当する場合はマージベース、および含まれるローカル状態を記録します。デフォルトブランチはリモートメタデータ（refs/remotes/<remote>/HEAD または GitHub リポジトリメタデータ）から解決してください。main または master は明示的なフォールバックとしてのみ使用し、そのようにした場合は明記してください。

PR

gh pr view/gh api を使用して、PR 番号、リポジトリ、タイトル、URL、ベース ref、ベース SHA、ヘッド ref、ヘッド SHA を確定します。ユーザーのブランチを切り替えずに、それらの正確なコミットを取得します。git merge-base <base> <head> を計算し、その SHA をレビューベースとして使用します。GitHub PR の差分はマージベース差分である一方、detect_changes(scope: "compare") は2点間比較です。

ローカルの git diff <merge-base> <head> を、完全な差分の信頼できる唯一の情報源として使用します。PR の事実とレビュー状態には GitHub メタデータを使用します。フォーク PR の場合は、ヘッドブランチが origin に存在すると仮定するのではなく、pull ref またはコントリビューターのリモートを取得してください。

ブランチ、ref、または範囲

レビューする前に、すべての ref をコミットに解決してください。ブランチまたは A...B の場合は、マージベースを比較ベースとして使用します。明示的な A..B の場合は、A を正確なベースとして尊重します。マージベースのセマンティクスが意図されていた場合に、フィーチャーブランチを移動するデフォルトブランチの先端と直接比較しないでください。

ローカルの変更

git status --short、ステージ済み差分、未ステージ差分、およびすべての未追跡ファイルを検査します。要求に応じて staged、unstaged、または all を指定して detect_changes を使用します。未追跡ファイルは Git 差分やグラフマッピングに必ず現れるとは限らないため、直接読み取り、レビューの来歴に記載してください。

チェックアウトとインデックスを揃える

グラフと diff は同じヘッドを記述している必要があります。既存のワークツリーを再利用するのは、それが正確に対象の SHA にある場合だけにしてください。そうでなければ、PR/ref のヘッド用に一時的なデタッチドワークツリーを作成し、そこでレビューを行い、その後、その一時ワークツリーだけを削除します。ユーザーの現在のワークツリーを切り替えたりリセットしたりしないでください。

対象のワークツリーで GitNexus のステータスを確認してください。古い場合は、グラフの結果を信頼する前に node .gitnexus/run.cjs analyze --index-only を実行し（一時ワークツリーには gitignore された run.cjs が含まれることはありません — インストール済みの gitnexus CLI、次に npx gitnexus にフォールバックしてください）、diff が信頼やデータフローの境界に触れている可能性がある場合は、同じリフレッシュに --pdg を含めてください。そうすれば、後述のテイントパスで二度目の完全な analyze を負担せずに済みます。テイントと依存関係のエビデンスにはその PDG レイヤーが必要です。ワークフローのテイントパスでそれが欠けていることが判明した場合は、analyze --pdg --index-only で再構築し、その再構築を来歴に記録してください。ローカルの変更については、新規または変更されたソースが反映されるようにインデックスをリフレッシュしてください。 正確な対象のチェックアウト/インデックスを確立できない場合は、その制約を明示し、グラフに裏付けられた完全なレビューを主張しないでください。

レビューワークフロー

1. 差分全体と変更されたファイルの一覧を確認します。生成ファイル、依存関係の変更、テスト、動作変更を分けて把握します。
2. 対象範囲を正確に指定して detect_changes を実行します。
   • PR／ブランチ／...：scope: "compare"、base_ref: <merge-base SHA>。
   • 明示的な A..B：B にチェックアウトしたワークツリーから、scope: "compare"、base_ref: <A SHA>。
   • ローカル：scope: "staged"、"unstaged"、または "all"。 MCP サーバーが別の場所に接続されている場合は、worktree を指定します。
3. 動作が変更された各シンボルについて、includeTests: true を指定して上流の impact を実行します。公開コントラクト、共有型、制御フロー、永続化、セキュリティ境界、エラー処理を優先し、機械的な変更や生成された変更は除外します。
4. 差分の範囲外にある直接の依存先（d=1）をすべて確認します。差分の範囲外にある依存先は調査の手掛かりであり、自動的にバグと判断するものではありません。ソースコードで変更されたコントラクトと呼び出し側の動作を検証します。
5. 重要なシンボルや曖昧なシンボルに対して context を使用し、影響を受ける実行フローを調べます。引用された箇所の周辺の実装とテストを読みます。
6. 汚染と依存関係の確認。 外部入力、永続化、プロセス実行、ネットワーク、認証など、信頼境界またはデータフロー境界に関わる変更コードについては、変更されたファイルまたはシンボルに対して explain を実行し、検出されたソース→シンクの汚染を差分と照らして判断します。変更によって導入されたフロー、または変更によって削除されたサニタイザー／ガードは検出事項です。既存のフローは背景情報であり、この変更による欠陥ではありません。変更によって何らかのガードやサニタイズを行う場合は、pdg_query で検証し、変更箇所を制御するものと、値の流れ先を確認します。これには --pdg インデックスが必要です。構築できない場合は、網羅性があるかのように示さず、汚染の確認をスキップしたと明記します。
7. テストが変更された動作、境界条件、影響を受けるフローを検証しているか確認します。実用的であれば、対象を絞った読み取り専用の検証を実行します。差分によってコミット済みのベースライン、フィンガープリント、またはゴールデンファイルが更新される場合は、コミットされた値を信頼せず、HEAD に対して CI の正確なチェックコマンドを再実行します。古い成果物は差分からは見えず、CI でのみ失敗するためです。
8. グラフから得られた情報を生の差分と照合します。新しいファイル、動的ディスパッチ、設定、リフレクション、追跡対象外のコンテンツは、グラフの結果が空でも直接レビューが必要になる場合があります。バージョン定数と無効化定数もレビュー対象です。差分によって生成または永続化されるものが変わる場合は、キャッシュ、インクリメンタルな書き戻し、フィンガープリントのベースラインを制御するスキーマ／バージョン定数がすべて更新または再生成されていることを確認します。たとえば GitNexus では、SCHEMA_FINGERPRINT（gitnexus/src/core/lbug/schema.ts）は NODE_SCHEMA_QUERIES と REL_SCHEMA_QUERIES から導出され、自動的に更新されるため、グラフ DDL に手動での更新は不要です。確認すべきなのは、差分によってこれらの配列内の文字列が変更されているか、新しい DDL 配列が追加された場合にその配列がフィンガープリントに組み込まれているかどうかです。パーサーの互換性も自動的に処理されます。gitnexus/src/core/parse-cache-identity.ts にあるベース／PDG の所有境界、インポート／アセットのカバレッジ監査、実際のコールド→ウォームのリプレイテストを確認します。これらの境界外にある新しいパーサー依存関係には、明示的なカバレッジが必要です。コントリビューターがセマンティックカウンターを割り当てる必要はありません。ベースラインを再設定する前に、両方のベンチマークのフィンガープリントセットを意識的に確認する必要があります。自動無効化だけでは、セマンティックな正しさは保証されません。DDL に影響しないその他のセマンティック変更は、インデックスメタデータ内のアナライザー実行環境 ID レシートに依存します。

エキスパートレンズ

深さは、レビュアーを実際に変更されたものに結び付けることから生まれます。汎用主義者による一度のパスからではありません。ワークフローのステップ 2 の後、変更されたファイルとシンボルを、グラフがすでに把握している機能領域ごとにグループ化します。すなわちインデックスのクラスター一覧です。context は各シンボルのクラスターを名付けます。そして、触れた各領域にエキスパートレンズを与えます。それはそのドメインの契約、不変条件、失敗モードを担当するレビュアーであり、diff を判断する前にリポジトリ自身の資料（アーキテクチャドキュメント、エージェントルール、そのドメインのテスト）に根拠を置きます。レンズは読むだけでなく検証します。変更されたコードがリポジトリ自身のツールチェーンから到達可能な純粋関数である場合 — パーサー、抽出器、キャプチャエミッター、フォーマッター — 候補となる失敗形状に対してそれを実行し（スクラッチプローブ、後で削除）、観察された出力を引用します。実証的なプローブは、証拠の階層においてソースの読解より上位に位置します。ロールの入れ替え、デッドブランチ、エラー回復依存の振る舞いは、読解を繰り返し通過し、10 行のプローブで失敗します。番号付きの ワークフローはちょうど一度だけ実行されます。レンズのパスはステップ 6 の後にディスパッチし、各レンズにすでに収集された証拠を渡します。レンズに impact、context、taint の呼び出しを繰り返させないようにします。たとえば GitNexus 自体では、共有インジェスチョンパイプラインの変更にはインジェスチョンエキスパートと、変更された言語抽出器ごとに 1 人の言語エキスパートが付きます。embeddings の変更には embeddings エキスパート、LadybugDB/ストレージの変更には Ladybug エキスパートが付きます。

ドメインに関係なく、4 つの横断的レンズが実行されます。

• アーキテクチャ適合 — 変更は、アーキテクチャがその関心事が存在すべきだと示す場所に収まり、既存のシームを再利用し、並行する構造を追加しません。
• 言語準拠 — 設定されたとおりのリポジトリ自身の型/lint/テスト契約（tsconfig の厳格性、lint ルール、テスト規約）。たとえば厳格な TypeScript リポジトリでは、厳格性が保たれ、any/as any の脱出路がなく、モジュール境界が型付けされていること。判断はリポジトリの契約によって行い、普遍的なスタイル基準によっては決して行いません。
• 完了の定義 — 変更された振る舞いにはテストがあり、変更によって古くなったドキュメントは更新され、同期/ドリフトガード（出荷されたコピー、マニフェスト、変更履歴）は依然として保たれています。
• シンプルさ — YAGNI とクリアコードのチェック：投機的な抽象化、未使用のノブ、過剰なエンジニアリングを指摘します。完了の定義を満たす最小の diff が標準です。

労力を対象面に合わせて調整します。数ファイルの単一ドメインの変更には、そのドメインレンズと 4 つの横断的チェックをカバーする 1 回の統合パスを与えます。マルチドメインの変更には、触れた領域ごとに 1 つのレンズを与えます。ハーネスが対応していれば並列サブエージェントとして実行し、それぞれを自身のファイルと共有グラフの証拠にスコープし、そうでなければ逐次パスとして実行します。diff が触れていないドメインのためにレンズを決して生成しないでください。同じ資料に根拠を置くレンズは統合します。2 つのレンズが同じファイルを読むと、1 回の読解のカバレッジに対して 2 回支払うことになるので、1 人のレビュアーに両方の責務を与えます。ハーネスがモデルまたは労力の階層を提供する場合、機械的なレンズ（リネームの掃討、ドキュメント整合性チェック）は安価な階層で実行し、最強のエンジンは敵対的な判断のために取っておきます。すべてのレンズは以下の Finding 標準を通じて報告します。評決の前にマージして重複排除し、具体的な失敗シナリオを持たないものはすべて除外します。

Swarm レーン

このスキルには ci-personas/ 内に 6 つのディスパッチ可能なレーン定義が同梱されています — ファイル読み取りと安全なグラフツールのみに制限された読み取り専用のレビュアーです。5 つはファインダーレーンです: ci-correctness-lens、ci-security-lens、 ci-blast-radius-lens、ci-coverage-lens、および ci-adversarial-lens (これは変更が壊れていると仮定し、パターンチェックでは見逃される到達可能な障害 シナリオを構築します)。これらは、影響を受けるすべてのドメインにわたって番号付き ワークフローの検証次元を担います。ドメインのグループ化と上記の 4 つの横断的チェックは オーケストレーターの責務のままです。6 番目の ci-critic-lens はファインダーではなく ゲートです — 完成したドラフトを監査します。

ハーネスがサブエージェントをサポートし、これらのレーンがエージェントとして登録されている場合 (CI レビューワークフローは信頼されたコントロールチェックアウトからそれらをインストールします。 ローカルハーネスでは ci-personas/*.md を ~/.claude/agents/ またはプロジェクトの .claude/agents/ にコピーして登録できます)、次のようにエキスパートレンズパスを実行します。 まず、自分自身のグラフ証拠を確立してください — レーンをディスパッチする前に、変更されたシンボルに対して少なくとも 1 回は実質的な コンテキスト呼び出しを自分で行ってください。レーンの呼び出しは、このスキルまたはその ランナーが要求する証拠を決して満たさないからです。次に、5 つのファインダーレーンすべてを 単一のメッセージで並列にディスパッチします。各レーンに、diff、変更ファイルのマニフェスト、 正確なベースとヘッドの識別子、チェックアウトパス、およびその責務に一致する変更ファイルの スライスを渡します。

すべてのレーン報告を未検証の主張として扱ってください。レビューに入る前に、各所見を diff、ソース、または自分自身のグラフクエリに再アンカーしてください。レーン間で重複を 排除し、具体的な失敗シナリオのないものはすべて破棄してください。レーンのツール呼び出しは、 このスキルまたはそのランナーがオーケストレーションする会話自体に要求する証拠の 代わりには決してなりません。

完全なドラフトレビューを構成した後、完全なドラフト本文と同一のコンテキストを添えて ci-critic-lens をディスパッチします。DEFECTS の場合、ドラフトを修復し、クリティックを 一度再ディスパッチします。2 回目のパスの後も欠陥が残る場合は、受け入れるものを修正し、 未解決のクリティックの異議をカバレッジセクションに記録して、続行します — クリティックは レビューを強化するものであり、決してブロックするものではありません。このフェイルオープンは 意図的なものです。クリティックは 2 パスに制限されているため、デッドロックや実行の 停滞を引き起こすことはできず、レビューは依然としてランナー自身の証拠とスキーマチェックに よってゲートされます。(これは別個の gitnexus-pr-swarm-review スキルとは異なります。 そちらの対話型名簿では、クリティックを出力前にクリアしなければならないハードゲートとして 扱います。この CI レーンは常にレビューまたはクリーンな失敗を出力しなければなりません。) サブエージェントのディスパッチが利用できない場合、またはいずれかのレーンが失敗した場合は、 そのレーンの責務をインラインで実行してください — レーンは作業を構造化するものであり、 決してゲートするものではありません。

所見の基準

レビュー対象の変更が、具体的な欠陥、リグレッション、セキュリティ問題、互換性の破壊、 重大なカバレッジのギャップ、または具体的な保持シナリオ(死んだノブ、重複した契約、 ドリフトしやすいコピー)を伴う保守性コストをもたらす場合にのみ、所見を報告してください。 各所見には以下を含める必要があります:

• 重大度と正確な path:line アンカー;
• 失敗シナリオまたは契約;
• 該当する場合の GitNexus 証拠(依存シンボル/プロセス);
• 既存のコードやテストがそれを緩和しない理由;
• 簡潔な修復または不足しているテスト。

スタイルの好み、既存の問題、生のリスクカウント、または推測を欠陥として報告しないでください。 グラフヒットがゼロであることから安全を推測しないでください。全体のリスクは、変更された シンボルの数のみからではなく、結果、到達可能性、可逆性、およびテスト証拠から 較正してください。

出力

重大度順に所見を先頭に示してください。所見がない場合は、その旨を明示してください。 次に、以下を提供してください:

## Review: <target>

### Findings

- [HIGH|MEDIUM|LOW] `path:line` — <problem, evidence, impact, remediation>

### Change and blast-radius summary

- Target/base/head/merge-base and local states reviewed
- Changed symbols and affected execution flows

### Coverage and residual risk

- Tests present, tests missing, graph/diff limitations

### Verdict

APPROVE | REQUEST CHANGES | NEEDS DISCUSSION

ブランチまたはローカルレビューの場合は、PR 承認アクションの代わりに READY、NOT READY、 または NEEDS DISCUSSION を使用してください。後続の実行で証拠が古くなっているかどうかを 判断できるよう、正確なターゲット SHA を含めてください。