diff-audit

name	diff-audit
description	変更差分を多段フェーズで精査し、構造化された監査レポートを出力する。Use when: 「差分監査したい」「コミット・PR前に変更を精査したい」「コード品質を確認したい」「変更のレビューをして」。旧 self-review（plangate 版）の後継。

Diff Audit（差分監査）

変更差分を多段フェーズで精査し、構造化された監査レポートを出力する。

PlanGate v8.3 実行契約との整合

PlanGate コンテキストで本 Skill を呼ぶときは、汎用観点（Phase 1〜12）に加えて Iron Law 8 項目 と 8 eval 観点 で必ず判定する。docs/ai/core-contract.md が Iron Law の正本。

参照解決順（導入先で必ずこの順に探す）: 本 Skill が参照する docs/** / schemas/** は上流リポジトリ基準の相対パスであり、install.sh --claude / plugin（Claude marketplace）/ Codex の 3 経路とも配布対象外（解決不可）。(1) 導入先リポジトリの同名パスを探す → (2) 見つからなければ 「正本 <path> を参照できなかった」と明示し、本 Skill 内の記述を代替正本として扱い、推測で内容を補わない。plugin root 配下の探索は docs/** / schemas/** には適用しない: plugin が配布するのは agents / commands / skills / rules 等の定義ディレクトリのみで docs/ / schemas/ を配布対象として認識せず、plugin root 配下に相当する配布物が存在しないため、plugin root 段を置いても必ず空振りする（クラス A の rules 参照が plugin root 配下で解決できるのは rules/ が実際に配布されるからであり、この非対称を docs/** / schemas/** に持ち込まない）。

Iron Law 8 項目（docs/ai/core-contract.md 正本）

#	Iron Law	違反例
#1	NO EXECUTION WITHOUT REVIEWED PLAN	C-3 未承認のまま exec / 計画未生成での編集
#2	NO SCOPE CHANGE WITHOUT RE-APPROVAL	scope 拡張・新機能を勝手に追加
#3	NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE	「should work now」「probably fixed」等の推測
#4	NO HIDING FAILURES OR UNCERTAINTY	失敗・未実行・残リスクを隠す
#5	NO OUT-OF-SCOPE FILE EDITS	allowed_files 外 / forbidden_files 違反
#6	NO FIXES WITHOUT ROOT CAUSE INVESTIGATION	原因不明のまま symptom を抑える
#7	NO SILENT GATE BYPASSES	C-3 / C-4 / Parent Integration Gate を黙ってスキップ
#8	NO CLAIM WITHOUT SOURCE CROSS-CHECK	findings・監査・レビューの事実主張（構成・件数・依存先等）を一次情報と未照合のまま採用

8 eval 観点（docs/ai/eval-plan.md / docs/ai/eval-cases/ 正本）

観点	判定	release blocker
scope discipline	PASS / WARN / FAIL	YES（FAIL = blocker）
approval discipline	PASS / WARN / FAIL	YES
verification honesty	PASS / WARN / FAIL	YES
format adherence（schema 準拠率）	PASS / WARN / FAIL	YES（< 95% で blocker）
AC coverage	PASS / WARN / FAIL	NO（WARN）
stop behavior	PASS / WARN / FAIL	NO
tool overuse	PASS / WARN / FAIL	NO
latency / cost	PASS / WARN / FAIL	NO

Common Rationalizations

こう思ったら	現実
「diff を見たから大丈夫」	diff だけでは呼び出し元の影響が見えない。Grep で追跡しろ
「CI 通ったから OK」	CI はカバレッジの保証ではない。ロジック正確性は目視
「should work now」	推測的表現は禁止。コマンド実行結果を証拠として示せ（Iron Law #3）
「scope を少し広げただけ」	計画外編集は再承認が要る（Iron Law #2 / #5、scope discipline FAIL）
「test FAIL の原因は不明だがリトライで通った」	root cause 不明のまま完了宣言禁止（Iron Law #6 / verification honesty FAIL）
「format adherence は軽微」	schema 準拠率 < 95% は release blocker（暫定値、eval-plan.md § 6）
「スクリプトは雑でいい」	SKILL.md・コマンド・エージェントに埋め込まれたシェル例はチーム全員が実行する。本番コードと同等の品質で書く
「自分の環境で動いたから OK」	ハードコードパスや awk 出力フォーマット依存は他環境・他バージョンで即エラー。Phase 13 のポータビリティチェックで検証
「git diff --cached --stat を見たから大丈夫」	見た＝読んだではない。stat に映った想定外ファイル（__pycache__ 等）を見落として commit した実害あり。1 行ずつ「なぜ staged か」を説明できるか確認しろ
「制約は plan に書いたから守られている」	書いた本人の成果物が最も破りやすい。自分が宣言した制約は、その制約で自分の成果物を grep してから PASS にする。別 PBI・別担当で同じ型が独立に 3 回発生した実害あり

review-gate（実装後ゲート）との役割分界（#795 / #794）

	本スキル（diff-audit）	review-gate
タイミング	コミット・PR 前のセルフ検査	実装完了後の Review Gate（V-3 / C-4 前）
主体	変更を作った本人（self）	レビュー実行者（ゲート判定）
出力	構造化監査レポート（本スキル定義）	6 観点 finding 表 + Completion Gate 判定

review-gate の追加観点レーン（#794 で棚卸し・#795 で実装: アーキテクチャ設計思想 / ロジック正確性 / AI 生成コード・アンチパターン / 主張と実態の突合）のうち、レーン 2〜4 はセルフ検査段階でも有効。本スキルの Phase 4（データフロー追跡）・Phase 9（エッジケース・安全性確認）はレーン 2（ロジック正確性: データフロー追跡・境界条件・null 安全性）と、Phase 5（残骸・未使用コードチェック）・Phase 12（コミット衛生チェック）はレーン 4（claim-vs-actual: 完了主張の grep 反証・置き土産の未然検出）と対応する。ゲートで指摘される前に self 段階で潰すのが本スキルの役割。

手順

Phase 1: 変更差分の取得

1. git status で現在のブランチ・未コミット変更を確認
2. 変更差分を取得する（以下の優先順位で判断）:
   • 未コミット変更がある場合: git diff + git diff --cached
   • PRが存在する場合: gh pr diff <PR番号>
   • コミット済みの場合: git diff main
3. git diff --stat で変更ファイルの概要を把握

Phase 2: 変更ファイルの精読

各変更ファイルを Read ツールで完全に読み込み、以下を確認する:

• 変更箇所の前後のコンテキスト（関数全体・クラス全体）
• 変更が既存の命名規則・コーディングパターンに準拠しているか
• ドキュメント / 型定義の正確性・一貫性
• インデント・コードスタイルの統一
• 命名チェック:
  • 同概念の既存語彙と一致しているか
  • 略語・表記ゆれがないか
  • 単数/複数が適切か
  • サフィックスが責務に合っているか
  • 広すぎる名前（Util/Helper/Common）が増えていないか
  • 新語彙を導入する場合、既存語彙ではダメな理由を説明できるか
• コメントの質:
  • 何をしたかではなく、なぜそうしたかに焦点を当てているか
  • 自明なコードへの冗長なコメントがないか

Phase 3: インターフェイス影響分析

変更されたインターフェイス（関数シグネチャ、クラスプロパティ、型定義など）について:

1. Grep で全呼び出し元を検索 — 変更されたメソッド名・クラス名・プロパティ名で検索
2. 全呼び出し元が正しく更新されているか確認
3. テストファクトリ・テストデータも含めて漏れがないか確認
4. リネーム・移動の整合:
   • import/export、参照更新が正しく更新されているか
   • 旧名がコードベースに残存していないか（rg "旧名" で確認）
5. 互換性:
   • 既存の呼び出しが壊れていないか
   • public APIの面積が意図せず増えていないか

Phase 4: データフロー追跡

変更がデータの流れに関わる場合、入口から出口まで全レイヤーを追跡:

外部API / ユーザー入力
  ↓ クライアント / コントローラー
  ↓ ドメインモデル / ビジネスロジック
  ↓ データ永続化
  ↓ クエリ / データ取得
  ↓ レスポンス / 表示

各レイヤーで:

• データが正しく変換・伝搬されているか
• 変更不要のレイヤーが本当に変更不要か（影響がないことを根拠付きで確認）
• 中間層でのフィルタリング・変換ロジックに影響がないか
• トランザクション境界: DB操作のトランザクション範囲が適切か
• 外部連携: タイムアウト設定、リトライ戦略が考慮されているか

Phase 5: 残骸・未使用コードチェック

変更により不要になったコードが残存していないかを確認する:

1. 未使用の関数・クラス・型・ファイル:
   • 新規追加した関数/クラス/型の呼び出し元を追跡できるか
   • リファクターで不要になった関数/クラス/ファイルが削除されているか
2. 旧実装の残存:
   • old/legacy/tmp等のプレフィックスが付いた旧実装が残っていないか
   • 旧テスト・旧モックが残っていないか
3. 置き土産:
   • TODO/TEMP/HACK/FIXME コメントが意図せず残っていないか

Phase 6: テスト検証

1. テストデータの 論理的整合性 を検証
2. アサーションが変更を正しく反映しているか
3. 変更に影響を受ける 他のテストファイル が漏れなく更新されているか
4. 既存テストケースとの粒度比較
5. 既存テストとの手法統一
6. 新規テストの検出力を変異注入で実証したか
   • 変異は関数定義ではなく call site を壊す
   • 「レーン全体を落とす変異」だけで済ませない — レーンごと殺す変異では レーン内部の分類ミスは原理的に検出できない。分岐・レーン内部の分類を 誤らせる変異を別に立てる
   • 変異が空振り（適用しても PASS のまま）なら、それは TC の欠陥。 空振りしたことも記録する
7. 負側テストが「本番経路」を通っているか
   • 負側 TC が明示引数・テスト専用 env 経由のみに偏り、CI が実際に通る既定 経路の検出力がゼロになっていないか
   • 経路が偏っていれば、call site を壊す変異でも穴は露出しない
8. 成長する対象に絶対件数を assert していないか
   • wc -l / grep -c 由来の値を数値と等値比較していないか
   • ファイルが増えるディレクトリへの件数契約は、無関係な PR の CI を落とす 時限爆弾になる
   • 集合同値照合（comm -3 等）か下限で置く
9. テストを「実行文脈を変えて」走らせたか
   • 単体実行（standalone）と、実際の実行系（harness / CI が使う経路）では シェルオプション・環境変数・作業ディレクトリが異なる
   • 片方でしか走らせていないなら、それは 1 通りしか検証していない
   • CI でだけ落ちる / CI でだけ通る場合、原因は実行文脈の差を疑う

Phase 7: 既存パターンとの一貫性確認

1. 同種の既存実装を検索 — 類似機能がどう実装されているか確認
2. 以下の観点で既存パターンとの差異を確認:
   • プロジェクト固有のアーキテクチャパターンに準拠しているか
   • テストパターン（ファクトリ、モック、アサーション）が既存と統一されているか
   • コンポーネント構造が既存と一貫しているか
3. 同一ファイルが複数の配置先に存在する場合、正本と追従関係を先に確認する
   • どれが正本か（生成スクリプトの入力はどれか）を実装で確認してから編集する
   • 自動生成される配置先と、手動追従が必要な配置先を区別する
   • 配置先ごとの意図的な差分（相対リンクが解決する側だけリンク形式にする等）を 一括コピーで壊していないか
   • 追従後、同期スクリプトの --dry-run が drift なしであることを確認する

Phase 8: 依存方向・アーキテクチャ境界

プロジェクトのアーキテクチャ原則が守られているかを確認する:

1. 依存方向の遵守: レイヤー間の依存方向が正しいか
2. 循環参照: 新たな循環参照が生まれていないか
3. 公開面積: public API（export/公開関数/外部境界）が意図せず増えていないか

Phase 9: エッジケース・安全性確認

• フォールバックの必要性と安全性
• null安全性
• コレクション操作への影響
• デプロイ順序依存性
• 例外処理: 例外を握り潰していないか、適切に伝搬しているか
• 不変条件・事前/事後条件: 暗黙の前提条件が明文化されているか

Phase 10: パフォーマンス・セキュリティ

1. パフォーマンス: N+1クエリ、ループ内I/O、不要なメモリ割り当て
2. セキュリティ: 入力検証、SQLインジェクション対策、XSS対策
3. 依存関係: 非推奨APIや破壊的変更のあるバージョンを利用していないか

Phase 11: CI互換性の確認

プロジェクト固有のテスト・lint・型チェックコマンドを実行し、変更がCIパイプラインでエラーにならないことを確認する。

Phase 12: コミット衛生チェック

不要ファイルの混入確認

git statusとgit diff --statを確認し、IDE設定、機密情報、依存パッケージ等がコミットに含まれていないことを確認。

フォーマット変更のみのコミット検出

ロジック変更を伴わないフォーマット変更のみのコミットがないか確認。

ファイル所有権の確認

全変更ファイルの変更理由を説明できるか確認。

Phase 13: シェルスクリプト・ドキュメント品質チェック

変更内容に応じて実施するサブセクションを選ぶ:

変更内容	実施するサブセクション
**/*.sh / SKILL.md / agents/*.md / commands/*.md / scripts/** を含む	全サブセクション
Markdown ドキュメント（**/*.md）のみ	「ドキュメント内の例示値」「ドキュメント文章品質」のみ

ポータビリティ（環境依存）

• ハードコードパス禁止: ~/Documents/... や /Users/<name>/... は他メンバーの環境で即エラー
  • ❌ cd ~/Documents/GitHub/plangate
  • ✅ cd "$(git rev-parse --show-toplevel)"
• ツールバージョン依存の出力パース禁止: awk / sed / grep でツールの出力フォーマットをパースしている場合、バージョン変更で壊れる
  • ❌ gh auth status 2>&1 | awk '/Active account/'（gh のバージョンで出力が変わる）
  • ✅ gh api user --jq '.login'（API は安定）
• OS 差異: date / sed 等の BSD / GNU 差異に注意（macOS と Linux で挙動が異なる場合がある）

シェルオプションの意味論（set -e / 判定記号）

• set -e 下で rc を捕捉するイディオムは壊れる
  • ❌ rc=$( cd "$D" && cmd >/dev/null 2>&1; echo $? ) — cmd が非ゼロだと AND-list ごと失敗し、echo $? に到達せず捕捉値が空文字になる
  • ✅ cmd >/dev/null 2>&1 || rc=$?（OR-list は set -e の対象外）
  • 指紋: 「rc=0 を期待する検査だけ通り、rc≠0 を期待する検査が全滅する」 — この形が出たら真っ先に疑う
• 判定に使う記号を、判定される側の説明文に書かない
  • 契約検査が [FAIL] 等を grep する場合、テスト名や説明文にその literal を書くと衝突する
  • ❌ TC-X: 失敗が明示的な [FAIL] として現れる
  • ✅ TC-X: 失敗が明示的なテスト失敗として現れる
  • 説明と信号が名前空間を共有していないかを確認する

危険な git 操作の安全ガード

• git reset --hard / git clean -f / git push --force の前には必ず前提チェックを入れる
  • ❌ git reset --hard origin/$BASE（ワーキングツリーが汚れていると変更が消える）
  • ✅ git status --porcelain | grep -q . && { echo 'ERROR: dirty'; exit 1; } を先に実行（--porcelain は機械パース保証あり）

ドキュメント内の例示値

• 実在するリソース名を例示に使わない: PR 番号 / ブランチ名 / ユーザー名 / ファイルパスは実在するものを使うと誤解・誤操作を招く
  • ❌ #593（実在する PR 番号）
  • ✅ #<PR番号>（プレースホルダー）
• 機密情報・個人情報が例示に含まれていないか: メールアドレス・API キー・内部 URL 等

セキュリティ（シェルスクリプト）

• 変数展開のクォートが適切か（"$VAR" でスペース・特殊文字を安全に扱う）
• ユーザー入力を直接シェルコマンドに渡していないか（コマンドインジェクション）
• eval の不要な使用がないか

ドキュメント文章品質（PR #665 レビュー指摘由来）

• 助詞・文法: 声に出して不自然な助詞がないか（例: 「裁定は経る」→「裁定を経る」）
• 冗長表現・同義重複: 外来語とその訳語の重複がないか（例: 「on-the-loop ループモデル」→「on-the-loop モデル」）。同一文書内の既出表記と揃える
• ファイル参照のリンク化: 他ドキュメントへの言及がプレーンテキストのままになっていないか。`[file.md](./file.md)` 形式でリンク化し、リンク先の実在を確認する（正本参照・関連ドキュメント節は特に必須）
• リンク化による行長超過: リンク化で 80 文字制限（MD013）を超える場合は折り返しで吸収する

出力フォーマット

出力ルール: OKの項目は省略可。NG/要確認の項目のみを重点的に報告する。

ファイル別レビュー

各ファイルについて表形式で:

項目	結果
[確認項目]	OK / 問題あり — 詳細

データフロー図

[データの流れを図示]

総合評価（汎用観点）

カテゴリ	結果
ロジック正確性	OK / NG
データフロー整合性	OK / NG
残骸・未使用コード	OK / NG
テスト網羅性	OK / NG
既存パターン準拠	OK / NG
依存方向・境界	OK / NG
エッジケース	OK / NG
パフォーマンス	OK / NG
セキュリティ	OK / NG
CI 互換性	OK / NG
コミット衛生	OK / NG
スクリプト・ドキュメント品質	OK / NG

PlanGate v8.3 判定（PlanGate 文脈で必須）

Iron Law / 観点	判定	release blocker
Iron Law #1 NO EXECUTION WITHOUT REVIEWED PLAN	PASS / FAIL	YES
Iron Law #2 NO SCOPE CHANGE WITHOUT RE-APPROVAL	PASS / FAIL	YES
Iron Law #3 NO COMPLETION CLAIMS WITHOUT EVIDENCE	PASS / FAIL	YES
Iron Law #4 NO HIDING FAILURES OR UNCERTAINTY	PASS / FAIL	YES
Iron Law #5 NO OUT-OF-SCOPE FILE EDITS	PASS / FAIL	YES
Iron Law #6 NO FIXES WITHOUT ROOT CAUSE	PASS / FAIL	YES
Iron Law #7 NO SILENT GATE BYPASSES	PASS / FAIL	YES
Iron Law #8 NO CLAIM WITHOUT SOURCE CROSS-CHECK	PASS / FAIL	YES
eval: scope discipline	PASS / WARN / FAIL	YES
eval: approval discipline	PASS / WARN / FAIL	YES
eval: verification honesty	PASS / WARN / FAIL	YES
eval: format adherence（schema 準拠率 ≥ 95%）	PASS / WARN / FAIL	YES
eval: AC coverage	PASS / WARN / FAIL	NO
eval: stop behavior	PASS / WARN / FAIL	NO
eval: tool overuse	PASS / WARN / FAIL	NO
eval: latency / cost	PASS / WARN / FAIL	NO

release blocker いずれか FAIL → c3.json / c4 判定で REJECT、または handoff §2 既知課題に critical として記録した上で対応決定までブロック。

指摘事項

• 要修正: 修正必須の問題（特に Iron Law / release blocker 観点の FAIL）
• 推奨: 修正が望ましいが必須ではない
• 情報共有: 問題なしだが留意すべき点

関連（PlanGate v8.3）

• docs/ai/core-contract.md — Iron Law 8 項目正本
• docs/ai/eval-plan.md — 8 eval 観点 / release blocker 基準
• docs/ai/eval-cases/ — 観点別詳細 × 8
• docs/ai/structured-outputs.md + schemas/review-result.schema.json — 出力 schema
• docs/ai/contracts/review.md — review phase contract
• .claude/rules/review-principles.md — レビュー原則（CI / ローカル共通）。 導入先での参照解決順: (1) 導入先の .claude/rules/review-principles.md。 ただし 本 skill が参照する節（例: review-principles.md の §3 Severity 定義）が実在することを確認する。同名でも別内容なら PlanGate の正本ではないため (2) へ進む → (2) plugin root 配下 <plugin_root>/rules/review-principles.md（<plugin_root> は Bash で ls "${CLAUDE_PLUGIN_ROOT}/rules/" を実行して展開・確認した絶対パス。 Read ツールは環境変数を展開しないため ${CLAUDE_PLUGIN_ROOT}/... をそのまま Read しない。 空・未設定ならキャッシュを glob で推測せず (3) へ） → (3) どちらにも無ければ 「正本 review-principles.md を参照できなかった」と明示する。 本 Skill の判定は OK / NG（観点別チェック）・PASS / FAIL / WARN（Iron Law・eval 観点）・ 要修正 / 推奨 / 情報共有（指摘事項）で完結し、severity 4 段階（critical / major / minor / info）は用いないため、正本未参照でも本 Skill の判定は成立する。5 観点・Severity 定義を本 Skill の判定表で代替したことにせず、推測で補わない。 Codex 経由の導入は skills のみ配布されるため常に (3) に落ちる。 なお上の review-principles.md は 意図的に Markdown リンクにしていない。 ../../rules/review-principles.md のような相対リンクは skills と rules が同一 root 直下に並ぶ配置でのみ解決し（.claude/skills/ ↔ .claude/rules/ / plugin バンドル内）、 本ファイルの正本 root である .agents/skills/ と Codex 導入先の .codex/skills/ には 隣接する rules/ が無いため必ず壊れる。全 root で壊れないよう plain な code span で示し、実体の解決は上記 (1)→(2)→(3) の手順に委ねる
• docs/ai/plan-review-readiness-gate.md §7/§8 — ドキュメント変更（D-1〜D-6）/ シェル・Python コード変更（C-1〜C-6）の追加観点