update-dependencies

依存関係の更新

依存関係のメンテナンスは一括作業として扱います。管理対象のバージョン宣言を一覧化し、リポジトリのパッケージマネージャーにパッケージグラフを解決させたうえで、結果を検証して記録します。

リポジトリ内のすべてのパッケージマネージャールートとワークスペースを対象とするのがデフォルトです。依頼に応じて、対象を選択したパッケージに絞ることも、最新のメジャーバージョンまで更新することもできます。

依頼内容から承認モードを判断します。

• 監査：ファイルを変更せずに更新内容を一覧化し、評価します。
• 改善：デフォルトです。ポリシーに適合する更新を適用し、検証したうえで、未コミットの状態にします。
• 公開：改善を行った後、依頼された公開を実施します。プルリクエストの依頼には、作成に必要なブランチ、コミット、プッシュが含まれます。

プロジェクトのポリシーは、リポジトリの指示、マニフェスト、メンテナンス設定に従います。このスキルは、それらに沿って作業を進める手順を定めます。適用される権威ある情報源の内容が食い違い、リポジトリの最新の証拠からも解決できない場合は、見解の分かれる更新を保留し、明確な作業は続行します。

1. メンテナンスの契約を確認する

Git ルート、現在のブランチ、ワークツリーの状態、リポジトリ内のすべてのパッケージマネージャールートを確認します。適用される AGENTS.md と同等の指示を、広い範囲から狭い範囲へ順に読み、依存関係、セキュリティ、リリース、CI、生成コード、検証に関する指針に従います。

各パッケージマネージャールートについて、宣言とロックファイルからパッケージマネージャーとそのバージョンを特定します。ワークスペースの境界、必須スクリプト、更新自動化、バージョン範囲とピア依存関係のポリシー、パッチ適用済みまたは生成済みの成果物、ツールチェーンの宣言、デフォルトブランチ、公開ルールを記録します。依存関係の解決と検証には、リポジトリで指定されているパッケージマネージャーとそのバージョンを使用します。

既存のユーザー変更は、明確な境界として保護します。監査モードでは、実行中のすべてのコマンドを読み取り専用にします。

完了条件： すべての JavaScript または TypeScript のパッケージマネージャールートについて、適用されるポリシーとコマンドの情報源が特定されていること。既存の変更済みファイルがすべて、意図を明確にして対象に含めるか除外されていること。また、独立したルートの作業を妨げることなく、サポート対象外または競合しているルートが特定されていること。

2. すべての検出された対象を洗い出す

references/dependency-surfaces.md をすべて読み、各パッケージマネージャーのルートにすべてのセクションを適用します。対象が存在しない場合も、黙って省略せず、不在として記録してください。

古いパッケージの確認、監査、依存関係グラフ、ピア依存関係の診断に使用するコマンドを選ぶ前に、インストール済みのパッケージマネージャーのヘルプを確認してください。ピア依存関係の問題が失敗を引き起こすのか、警告にとどまるのか、別途確認が必要なのかを確認します。pnpm のルートでは、コマンドを選ぶ前、またはピア依存関係の診断結果を解釈する前に、references/pnpm-resolution.md を読んでください。ルートの要約だけに頼らず、所有するすべてのワークスペースマニフェストを調べます。動的バージョンは、その値を指定している宣言までたどり、その宣言を 1 回だけ数えます。

パッケージマネージャーがサポートするチェックを使って、ベースラインのピア依存関係診断を取得します。取得にファイルを書き換える解決処理が必要な場合は、Improve または Publish モードで、現在のマニフェスト、ロックファイル、設定の分離コピーを使用してください。Audit モードでは、取得できない診断を検証上の不足として記録します。該当する検証ゲートでのベースラインの失敗も記録してください。

次の項目を含む作業用の台帳を維持します。

対象	現在	更新候補	リスク	方針または根拠	判断
パッケージ、アクション、イメージ、またはツールチェーン	exact ref	exact ref または current	パッチ、マイナー、メジャー、非 SemVer、セキュリティ、または関連付け	リポジトリまたは一次情報源	現状維持、対象に含める、保留、または分割

ユーザーが成果物を求めない限り、台帳は作業メモとして維持します。ワークスペース内の複数の利用先で、パッケージとリリースに関する根拠を再利用します。更新候補や方針が異なる場合は、別途記録してください。

完了条件： 検出されたすべての対象に台帳の項目または所有元を記載した文書があり、ベースラインのピア依存関係診断と該当するチェックが取得済みであるか、取得できない理由を具体的に記録していること。

3. 更新対象を決める

SemVer が適用される場合は SemVer 上の差分で候補を分類し、ランタイム、ツール、CI、ツールチェーン、セキュリティへの影響も考慮します。メジャーアップデート、比較できない参照、ランタイムに影響するライブラリ、セキュリティ修正、パッケージマネージャーまたはランタイムのアップグレード、移行手順が記載された変更は慎重に扱います。

パッケージ候補は、ワークスペースを考慮するパッケージマネージャーのコマンドでビルドします。既存の設定に基づいて、適格なバージョンの選択と宣言済みピア範囲の評価は、パッケージマネージャーのリゾルバーに任せます。コマンドが適格性チェックを強制する場合は、設定済みのチェックを正式な判断基準とします。これには pnpm の minimumReleaseAge も含まれます。手動チェックを追加するのは、パッケージマネージャーが適用できないポリシーがある場合、またはリポジトリの指示で明示的に求められている場合に限ります。

提案するすべての直接依存関係、カタログ項目、オーバーライド、および明示的に対象とする推移的更新について、現在のバージョンから対象バージョンまでの公式変更履歴とリリースノートを調査します。その調査結果は、複数の利用箇所や関連パッケージ群で再利用します。付随的な推移的変更は、所有元の更新を通じて確認します。診断結果、アドバイザリ、またはリリースノートでリスクが示された場合は、個別に調査します。リポジトリで指定されたドキュメント検索手段を使用します。リリースノートが見つからない場合は、その旨と、代わりに使用した一次情報源を記録します。

慎重に扱う更新については、必要な移行とランタイムまたはツールチェーンの制約も特定します。互換性調査では、ピア依存関係の診断結果を手がかりにします。メジャーバージョンの違いだけでは、ピア依存関係の競合があるとは判断できません。パッケージマネージャーによる解決結果は、ステップ 5 でアプリケーションの動作を検証するまで暫定扱いです。

各候補に、次のいずれかの判定を割り当てます。

• 含める：リポジトリのポリシーに適合しており、解決と検証に進める状態です。
• 保留：互換性の問題、ポリシー上の制限、または具体的な証拠不足が確認されたため、変更しません。
• 分離：独立した移行としてスコープを分ける必要があるため、今回の更新では変更しません。
• 現行：すでに最新である、ローカルで導出されている、またはそれ以外の理由で更新が不要です。

関連する宣言は、ひとまとまりの判断として扱います。これには、ローカルツールと CI のランタイムバージョン、マニフェストとブートストラップファイルにあるパッケージマネージャーの固定バージョン、参照元と利用側の間で動的に導出されるイメージが含まれます。

含める更新が Ultracite、リンターまたはフォーマッターのバックエンド、React Doctor、読み込まれる JavaScript リンタープラグイン、共有リンター設定パッケージに影響する場合は、リンター設定を変更する前に /linting-alignment スキルを実行します。そのスキルを利用できない場合は、設定を維持し、設定移行の安全性に依存する更新を保留します。

完了条件： すべての候補についてポリシーとリリース調査の判定があり、慎重に扱う対象として含める更新には移行計画と検証計画があり、保留または分離のすべてに明確な理由があり、検出されたリンタースタックの変更について調整への引き継ぎが完了しているか、安全に延期されていること。

4. 含まれる更新を適用する

Audit モードでは、ワークツリーを変更せず、検証と報告に進みます。

Improve モードまたは Publish モードでは、リポジトリのパッケージマネージャーを使用して、まとまりのあるグループごとに更新し、グループ間の差分を確認します。中間状態でバージョンが混在して障害にならないよう、ワークスペースとカタログの所有者をまたいで、依存関係のあるパッケージをまとめて解決します。

• パッケージマネージャーのルートに対して広範な更新コマンドを使用できるのは、選択される候補がすべて Include の場合に限ります。
• 候補に Hold または Split が含まれる場合は、依存関係セレクター、除外指定、ワークスペースフィルターを使って、保留中の宣言を維持しながら、対象の更新をまとめて適用します。対応しているセレクターでグループを分離できない場合は、対象を絞るか、分離できないグループを保留します。
• バージョン範囲のポリシー、ワークスペースとカタログのプロトコル、エイリアス、オーバーライドまたは解決設定、ロックファイルの所有権、パッケージマネージャーの設定、パッチ、自動化におけるピン留めの形式、コンテナのタグまたはダイジェストのポリシーを維持します。宣言された範囲を超える更新を選択するのは、リクエストまたはポリシーに含まれている場合に限ります。
• ランタイムとパッケージマネージャーのアップグレードを適用するのは、リクエストまたはリポジトリのポリシーに明確に含まれている場合に限ります。
• 却下した調査や、無関係な生成済みファイルまたはソース管理対象の変更を最終差分に含めないでください。

各パッケージグループの適用後、リゾルバーの警告をピア依存関係チェックと照合し、診断結果をベースラインと比較します。矛盾する出力がある場合は、依存関係グラフがクリーンだと判断する前に調査します。マネージャーが宣言範囲を評価した結果と、リポジトリで確立された例外を、互換性を示す証拠として扱います。報告された問題を分類します。

• ピア要件がリポジトリのポリシーに基づいて解決される更新は維持し、そのうえでアプリケーションの動作を検証します。
• ベースラインから変わらない警告と既存のスコープ付き例外は、新たなリグレッションとして扱わずに記録します。公開を妨げるかどうかは、リポジトリのポリシーに従います。
• 新たに発生した問題や悪化した問題については、影響を受ける利用側、必要な範囲、解決されたプロバイダー、ワークスペースのスコープを追跡します。影響を受けるグループを保留する前に、スコープ内での連携した更新、または対応している互換バージョンの適用を試します。
• 新たに範囲外となった警告を維持できるのは、対象を絞った上流の互換性に関する証拠があり、既存のピア依存関係ポリシーで許可され、影響を受けるチェックに合格した場合に限ります。それ以外の場合は、そのグループを保留または分割し、独立した更新を続けます。

受け入れポリシーと例外は、リポジトリのポリシーに従って維持します。チェックの無効化、リゾルバーエラーの強制的な無視、またはピア依存関係の抑制設定の追加には、対象を明示したポリシー変更が必要です。マネージャーが無効なピア依存関係について警告しか出さない場合、インストールが終了コード 0 で完了しただけでは不十分です。

実際に選択されたバージョンを台帳およびリリース調査の内容と照合します。変更された宣言がすべて Include に対応し、Hold または Split の宣言がすべて元の値のままであることを確認します。

完了条件： Audit モードでは依存関係グラフを変更せず、提案するグループと診断上の不足を記録します。Improve モードまたは Publish モードでは、含めるすべてのパッケージグループについてピア依存関係の証拠があり、報告されたすべての問題への対応が記録され、保留および分割した宣言が変更されず、差分には対象の更新とそれに必要な成果物のみが含まれています。

5. 結果を検証する

Audit モードでは、リポジトリで承認されている読み取り専用のチェックのみを実行します。インストール、修正やフォーマットを行うコマンド、ジェネレーター、出力を作成するビルド、作業ツリーを変更する可能性がある検証のエントリーポイントはスキップします。スキップした各ゲートを記録し、最終的なファイルシステムの状態が初期状態と一致することを確認します。

Improve モードまたは Publish モードでは、解決済みの依存関係グラフをインストールし、ロックファイルの整合性チェックと、変更対象に適用される、ドキュメントに記載されたフォーマット、リント、型チェック、テスト、ビルド、生成、検証の各ゲートを実行します。モノレポでは、影響を受ける依存先と、変更された共有カタログまたはツールチェーンパッケージを使用するすべてのコンシューマーを含めます。対象を絞ったチェックに合格していても、リポジトリ全体に必要なゲートに従ってください。すべてのモードで、さらに次を実施します。

• Git のワークツリーでは git diff --check を実行します。
• 依存関係の棚卸しとピアチェックを再実行し、残っている古い項目とピアに関する問題をすべて台帳と照合します。
• セキュリティ対応後は、該当するセキュリティ監査を再実行します。
• 変更した自動化、コンテナー、パッチ、生成アーティファクトの各対象を、リポジトリ独自のツールまたは確立されたチェックで検証します。
• リントスタックを変更した場合は、/linting-alignment で必要とされる検証を実行します。
• インストールやジェネレーターによって追加の変更が発生する可能性があるため、検証後にステータスを再確認します。

チェックに失敗した場合は、含めた更新が原因かどうかを確認します。更新を修正するか、保留するか、分割してください。無関係な既存の失敗を一連の更新に含めず、正確な根拠を記録します。ブロックされた更新は公開できません。

完了条件： Audit モードでは、提案されたすべての適用対象について必要な検証を記録し、初期状態のファイルシステムを維持していること。Improve モードまたは Publish モードでは、適用したすべての対象が該当するゲートに合格しているか、正確なブロッカーを記録して除外されていること。最終台帳がファイルシステムと一致し、ワークツリーに許可された変更のみが含まれていること。

6. 要求された場合にのみ報告し、公開する

最初に、リポジトリがすでに最新だったのか、更新に成功したのか、またはブロックされたままなのかを示します。適用、保留、分割した候補、機微な更新の根拠、変更した対象、セキュリティ上の指摘、各検証の結果を要約します。ホスト側のチェックが保留中である状態と、失敗を区別します。

Audit モードでは、変更のないワークツリーで終了します。Improve モードでは、検証済みの変更をコミットも公開もせずに残します。

Publish モードでは、リポジトリのガイダンスとハーネスの制約に従います。これらの規則に適合する現在のブランチがあれば、そのまま使用します。公開に新しいブランチが必要で、どちらの規則にも名前の指定がない場合は、代替名として agent/YYYY-MM-DD-update-dependencies を使用します。要求された範囲と、その前提条件を実行します。

• コミットまたはプルリクエストが要求された場合は、この更新一式のファイルのみをステージングしてコミットします。
• プッシュまたはプルリクエストが要求された場合は、プッシュします。
• プルリクエストが要求された場合は、検出したベースブランチを対象に、要求されたプルリクエストを作成または更新します。説明文は /pr を通じて作成し、リリース元へのリンク、適用した更新と延期した更新、ピア診断への対応、検証結果を含めます。URL と保留中のホスト側チェックを報告します。

変更が残っていない場合、または検証がブロックされている場合は、公開の前に停止します。

完了条件： ユーザーが、把握済みの対象全体、適用・保留・分割の各判断、正確な検証状況、および要求された公開の結果か、公開を停止した正確な理由を確認できること。