ref-integrity-scan

name	ref-integrity-scan
description	ファイル（スキル/ルール/フック/設定/ドキュメント）を削除・移動・改名する前後に、リポジトリ内の被参照（ダングリング参照）を全走査して修正候補を提示する。Use when: PlanGate 資産（4 配置 sync を持つスキル/ルール/コマンド）の削除・移動・改名時、git rm / git mv の前後、スキル・ルールのパス変更時、『削除前にチェックして』『参照切れを探して』。出典: growth-core deletion-reference-scan 由来（#798）。

Ref Integrity Scan

Provenance（出典・vendoring 規約）: growth-core deletion-reference-scan （upstream: Growth-Teams-Agent@5219642 / 2026-07-03 時点）を PlanGate 向けに 汎用化して取り込み（#798）。上流への自動追従はしない — 上流更新の反映は 意図的に diff をレビューして行う（provenance 追跡 + 意図的更新の vendoring 標準）。

ファイル・ディレクトリを削除・移動・改名する前後に、リポジトリ全体を対象に被参照（そのパスを指している箇所）を洗い出し、ダングリング参照を防ぐための手順スキル。

#691（check-stale-skill-refs.py）との相補関係

スキル/スクリプト	走査方向	検出対象
scripts/check-stale-skill-refs.py（#691）	outbound（発信）	スキル/コマンド/エージェントが参照している先が実在しない（stale）
本スキル（ref-integrity-scan）	inbound（被参照）	削除・移動・改名する対象への参照が他のどこかに残っている

#691 は「自分が指している先が消えていないか」、本スキルは「自分を消したときに誰かが迷子にならないか」を確認する。両方向を揃えることで参照整合を守る。

実害事例（動機）

2026-07-10、self-review スキルを diff-audit へ改名した際（#796）、削除・改名前の被参照スキャンを行わなかったため、以下が事後検出になった:

• acceptance-review からのリンク切れ（RiverReview レビューで major 指摘として検出）
• .cursor 配下の壊れた symlink（旧パス self-review を指したまま。Codex 側レビューで検出）

いずれも事前に inbound スキャンを行っていれば着手前に判明していた。本スキルはこの再発防止策として新設する。

When NOT to use

• コード内の import / require 参照の整合性チェック → 型チェッカー / linter を使う
• 外部サイトへのリンク切れ（http/https URL）のチェック → 対象外（本スキルはリポジトリ内参照のみ）

手順

Step 1: 対象パスの確認

削除・移動・改名する対象パスを列挙する（複数可）。例:

対象: .claude/skills/self-review/  (旧名)
対象: .claude/skills/self-review/SKILL.md

移動・改名の場合は「旧パス」と「新パス」の両方を把握しておく（新パスは対象外、旧パスのみスキャン対象）。

Step 2: スキャン実行

フルパスとファイル名のみの 2 パターンで grep する。参照形式が ./ 省略・相対パス表記・単純なファイル名参照など様々なため、片方だけでは取りこぼす。

対象ディレクトリ・ファイル: docs/ .claude/ .agents/ .codex/ .cursor/ plugin/ bin/ scripts/ CLAUDE.md AGENTS.md README*.md 対象拡張子: *.md *.json *.sh *.yaml *.yml

TARGET_FULL="path/to/target"          # フルパス（削除・移動対象）
TARGET_NAME="$(basename "$TARGET_FULL")"  # ファイル名のみ

# プレースホルダのまま実行すると全行マッチで大量出力になるためガードする
if [ -z "$TARGET_FULL" ] || [ "$TARGET_FULL" = "path/to/target" ]; then
  echo "Error: TARGET_FULL を実際の対象パスに設定してください" >&2
else
  # git grep は .gitignore を尊重し高速。--untracked で未コミットの新規ファイルも対象に含める
  # パターン1: フルパスでの参照
  git grep -n -F --untracked -- "$TARGET_FULL" -- '*.md' '*.json' '*.sh' '*.yaml' '*.yml'

  # パターン2: ファイル名のみでの参照（誤検出が出やすいので手動で絞り込む）
  git grep -n -F --untracked -- "$TARGET_NAME" -- '*.md' '*.json' '*.sh' '*.yaml' '*.yml'
fi

加えて symlink 走査を行う。macOS の xargs は空入力（一致ゼロ件）で待機してハングすることがあるため、find | xargs ではなく while-read 形式を使う:

if [ -n "$TARGET_NAME" ] && [ "$TARGET_NAME" != "target" ]; then
  find . -type l 2>/dev/null | while IFS= read -r _link; do
    _resolved="$(readlink "$_link")"
    case "$_resolved" in
      *"$TARGET_NAME"*) printf 'SYMLINK: %s -> %s\n' "$_link" "$_resolved" ;;
    esac
  done
fi

Step 3: ヒットの分類

grep / symlink 走査で出たヒットを 3 種に分類する:

分類	内容	扱い
(a) 追従更新すべき参照	現行の手順・設定・リンクが対象パスを指している	修正候補として提示、原則反映
(b) 履歴として不変にすべきもの	CHANGELOG.md、docs/working/ 配下の過去記録、過去のレビューレポート等	機械置換しない（当時の記録を保存する）
(c) 概念の同名異義	例: 「C-1 セルフレビュー」という概念への言及と、self-review というスキル名への言及が同じ文字列でヒットする場合	文脈で判定し、機械置換しない

(b) (c) を機械置換しないことを規約とする。 2026-07-10 の self-review → diff-audit 改名（#796）で、Codex のレビューにより誤って書き換えられた箇所が 4 件検出された教訓による。

Step 4: 修正候補の提示と再スキャン

• 分類 (a) について file:line + 具体的な置換案（before/after）を提示する
• 実際の置換後、同じ Step 2 のスキャンを再実行し、ヒット 0 件（または (b)(c) のみ残存）であることを確認する
• 削除・移動を伴う commit には、再スキャン結果（0 件確認 or 残存理由）を明記する

関連

• scripts/check-stale-skill-refs.py（#691・outbound: スキルが参照する先の stale 検出）
• diff-audit（Phase 5 残骸チェック。旧 self-review）
• docs/ai/skill-collision-detection.md（名前衝突検出。本スキルは被参照検出で観点が異なる。配布対象外。上流リポジトリで作業する場合のみ解決する）