sb-audit

sb-audit — ドリフト調査と意思決定ボード

定期的なゲートです。カタログを調査し、台帳を準備し、統合候補を特定します。

実行する

SKILL=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
"$SKILL/scripts/audit-drift.sh"                 # naming drift across stories
"$SKILL/scripts/audit-archived.sh"              # L1/L2/L3 preservation surveillance (HEAVY warning)
"$CORE/scripts/find-stories-by-tag.sh" decision:pending   # stale decisions needing a nudge
"$CORE/scripts/extract-component-usage.sh"      # REFRESH real prop-usage → component-usage.json (auto, no hand-edits)
"$SKILL/scripts/audit-controls.sh" .            # Controls-panel coverage: component stories missing argTypes + manager showPanel
"$CORE/scripts/refresh-usage.sh" --docs .       # ONE-COMMAND refresh: components + tokens + routes + health JSON + re-stamp per-component usage MDX

# App flow + component lists: re-run the repo-local app-graph extractor if present, then VALIDATE it
[ -f .storybook/scripts/extract-app-graph.mjs ] && node .storybook/scripts/extract-app-graph.mjs   # refresh app-graph.json + component-pages.json
[ -f .storybook/app-graph.json ] && node -e 'const g=require("./.storybook/app-graph.json"); const by={}; for(const e of g.edges) by[e.attribution]=(by[e.attribution]||0)+1; console.log("flow edges by attribution:", by, "| unresolved:", g.unresolvedEdges.length); for (const u of g.unresolvedEdges) console.log("  UNRESOLVED", u.provenance, "→", u.to, "—", u.reason)'

実行順 — いきなり6つすべてを実行しないでください。 まず audit-drift.sh を実行します（低コストで、統合候補を特定します）。負荷の高い audit-archived.sh による L1／L2／L3 スキャンは、カタログが十分な規模になってからでないと、コストに見合いません。選定済みストーリーが約20件未満なら実行しないでください（まだ整理するものがありません）。カバレッジを確認するときは audit-controls.sh と extract-component-usage.sh を実行します。refresh-usage.sh --docs は、レンダリング済みファイル全体をまとめて更新します。個別の抽出スクリプトの代わりに、最後に実行してください。

1コマンドで使用状況を更新。 refresh-usage.sh は4つの抽出スクリプト（インベントリ／トークンマップ、コンポーネントの prop 使用状況、ルート、デザインシステムの健全性 — すべてのレンダリング済みファイル。CONTEXT.md の§STORAGE MAPを参照）を実行し、--docs を付けるとすべての <Name>.usage.mdx のスタンプも更新します。autodocs は JSON をインポートするため、これを実行した後に Storybook を再ビルドすると、手作業で編集しなくても最新の状況が反映されます。実行するタイミングは3通りです。スクリプトごと（ここで実行するか、個々の抽出スクリプトを直接呼び出す）、各監査時（このステップ）、または CI で storybook build の前です。StateGrid／StateMatrix の usage prop は同じ JSON を読み込み、各バリアントセルに実際の呼び出し箇所数をバッジ表示します（宣言済みだが未使用の場合は取り消し線）。

使用状況の自動更新（人手による記述は不要）。 ここで extract-component-usage.sh を再実行すると、アプリの変更に合わせて component-usage.json が最新の状態に保たれます。usage-profile.mdx の autodocs はビルド時にその JSON を読み込むため、「このアプリでの実際の使用状況」テーブルは次回の Storybook ビルド時に自動更新されます。常に最新の状態を保ちたいリポジトリでは、同じ1行のコマンドを CI に組み込んでください。使用状況に変化があった場合（declaredButUnused だったバリアントがリリースされた場合、またはその逆）は、該当ストーリーの usage:unused タグをドリフトの検出結果として報告してください。

判断する（自問してください）

• ドリフト — 「空の状態」を表す名前が17種類 → 統合候補。クラスターが1つだけ → ノイズなので無視します。
• アーカイブ — audit-archived.sh が選定済みストーリーを20件超と報告した場合は、templates/design-decisions.md から準備した永続的な台帳に合わせて整理します（$SKILL/scripts/prune-to-ledger.sh）。それ以外の場合はそのままにします。
• 未決定の項目 — 古い decision:pending が残っていれば、関係者にリマインドします。
• Controls のカバレッジ — audit-controls.sh は、args を渡しているのに argTypes を設定せず、Controls を無効化してもいないコンポーネントストーリーにフラグを立てます（利用可能な Controls パネルが表示されません）。また、.storybook/manager.ts で showPanel が設定されていない場合にも警告します。Controls パターンに従って、argTypes を設定する（ユニオン型 → select、フラグ → boolean、table.category でグループ化、シリアライズできない prop は非表示にする）か、レンダリング専用ストーリーでは Controls を無効化してください。sb-stories の Controls パターン（without-mcp リファレンスの§13）を参照してください。
• フロー／アプリグラフのドリフト — 上記の検証ステップでは、帰属情報別のエッジと、すべての UNRESOLVED が出力されます。unresolvedEdges が増えた場合、または新しい項目の理由が「動的ディスパッチ」や抽出スクリプトで解析できないナビゲーションの慣用表現だった場合は、実際のエッジが欠落しています。アプリに、スクリプトが見逃すナビゲーションパターンが追加されています。sb-flows の過少抽出対応ループ（flow-capture.md）に沿って作業し、リポジトリ固有の extract-app-graph.mjs を拡張してから、再検証してください。マップが気付かないうちに縮小するのを決して許容しないでください。ソースのないエッジは未解決であり、存在しないわけではありません。（同じ JSON はコンポーネント一覧にも使われます。parents／pages がすべて失われたコンポーネントは、未使用コンポーネントまたはインポート追跡に関する検出結果です。）

TagGallery を作成する場合は references/galleries-and-tags.md、アーカイブ／非推奨化の場合は references/lifecycle-tags.md、整理候補が出てきた場合は references/propagate-workflow.md、AI 生成ストーリーをレビューする場合は references/anti-patterns.md（メガストーリー、インラインモック、CSF2、疑似クラスの誤用など、完全な一覧）を読み込みます。判明した内容に応じて選び、4つすべてを読み込まないでください。

台帳（操作する永続メモリー）

調査結果を .storybook/audit/findings.md に追記します（タイムスタンプ付き、追記専用）。記録のみのルール： ストーリーパスの対象外となる実際の本番環境の問題（未関連付けの <label>、AA 未満のコントラスト、ヘッドレス環境でのクラッシュ）には LOG-ONLY: マーカーを付けて記録し、そのまま作業を続けます。依頼がない限り、アプリのコードには手を加えません。台帳を作成したら、コミットするよう促します（git add .storybook/audit/）。未コミットの台帳は、git clean を実行するだけで消えてしまいます。

次のステップ

/sb-hub → 通常は sb-stories で統合パスを実施するか、卒業した Explore に対して sb-ship を実施します。