migration

AEM as a Cloud Service — コード移行

移行元 → 移行先： レガシーな AEM 6.x / AMS / オンプレミス → AEM as a Cloud Service。Edge Delivery や 6.5 LTS と混同しないよう、skills/aem/cloud-service/skills/migration/ の配下に配置されています。

このスキルは、移行ワークフロー（BPA データ、CAM/MCP、1 セッションにつき 1 パターン、移行先の調査）を支援します。変換ルールと手順は code-assessment スキルにあります。検出事項のパターンが特定されたら、{code-assessment}/<pattern>/SKILL.md（または {code-assessment}/references/ 配下の関連する共有リファレンス）に引き継いでください。

セットアップ： aem-cloud-service のインストールを使用してください（リポジトリのルートにある README を参照）。これにより、migration と code-assessment の両方のパスを利用できます。解決可能な {code-assessment} パスを含むモノレポをすでに開いている場合は、別途インストールする必要はありません。

クイックスタート（エージェントを操作する人向け）

チャット／セッションごとに 1 パターンです。「すべて修正して」と依頼した場合、このスキルはまずパターンを選ぶよう求めます（例：scheduler、replication、htlLint）。

お持ちのもの…	次のように伝えてください…	実行されること
評価対象のプロジェクト全体	"AEMaaCS 移行に向けてコードをレビューして"	読み取り専用の migration-runbook.md を生成します — 移行パターン（Java カスケード + htlLint + osgiConfig）、影響を受けるファイル、サンプルプロンプトのすべてが含まれます。編集は行いません。
BPA CSV	"./path/to/bpa.csv を使って scheduler の指摘を修正して"	最短の手順です。CSV → キャッシュされたコレクション → ファイル
CAM + MCP のみ	"CAM から scheduler の指摘を取得して。プロジェクトは一覧表示された後に選ぶよ。"	エージェントがプロジェクトを一覧表示 → 確認 → MCP で取得（cam-mcp.md）
少数のファイルのみ	"core/.../MyJob.java の scheduler を移行して"	手動のフローです。BPA は不要です
OSGi → Cloud Manager	"設定ファイルをスキャンして、Cloud Manager の環境シークレットまたは変数を作成して。"	エージェントが references/osgi-cfg-json-cloud-manager.md を自動的に読み込みます（Adobe のガイドラインに準拠したルールがすべて記載されています）。BPA パターン ID は不要です
HTL lint 警告	"ui.apps の htlLint の問題を修正して"	rg で積極的に検出し、HTL lint リファレンスに従って修正します
Vault パッケージの依存関係	"vault-package-dependencies の指摘を修正して" / "AEMaaCS でパッケージのインストールに失敗する。"	エージェントが references/vault-package-dependencies.md を読み込みます — content-package-maven-plugin 内のインストール時依存関係 day/cq60/product:* を対象に、ヒューリスティックな pom.xml スキャンを実行します（BPA サブタイプもアナライザーも不要）。<dependencies> ブロック全体を削除します。code-assessment パターンではありません — この依存関係の形式は、ネイティブの AEMaaCS コードには存在しません。
テンプレートのモダナイゼーション	"静的テンプレートを編集可能テンプレートに移行して、Modernize Tools のルールを生成して。" / "静的テンプレートから編集可能テンプレートを作成して。" / "AEM Modernize Tools の structure/component/policy ルールを生成して。"	エージェントが references/template-modernization/template-modernization-context.md を自動的に読み込みます（共通の検出と構造化コンテキスト）。テンプレートごとの計画表を作成し、editable-template-creation.md と aem-modernization.md を使用して計画を実行し、template-modernization-validation.md で検証します。BPA パターン ID は不要です。
ダイアログの移行	"Classic UI / ExtJS のダイアログを Touch UI に変換して。" / "Coral 2 のダイアログを Coral 3 にアップグレードして。" / "LUI ダイアログの指摘を修正して。"	エージェントが references/legacy-ui/dialog/context.md を読み込みます — BPA の LUI をダイアログのサブタイプに絞り込み、extjs-to-coral3.md または coral2-to-coral3.md を使って変換し、validation.md で検証します。BPA パターン ID：lui。
カスタムウィジェットの移行	"CDW の指摘を修正して。" / "カスタム ExtJS ウィジェットを Coral 3 に移行して。"	エージェントが references/legacy-ui/cdw/context.md を読み込みます — xtype を一覧化し、conversion.md を使って Granite UI コンポーネントに対応付けるか、ひな形を生成し、validation.md で検証します。BPA パターン ID：cdw。両方が必要な場合は、ダイアログの移行より先に CDW を実行してください。
Guava キャッシュの警告	"BPA CSV を使って guavaCache の指摘を修正して。" / "Guava キャッシュを Caffeine に置き換えて。"	エージェントが references/guava-cache.md を読み込みます — BPA が信頼できる情報源です（サブタイプ custom.guava.cache）。指摘は Guava 内部クラスの行ごとではなく、バンドルごとに1件です。BPA パターン ID：guavaCache。code-assessment パターンではありません — Guava キャッシュの使用は移行前のコードにのみ存在し、ネイティブの AEMaaCS コードには存在しません。
Dispatcher の変換	"AMS / オンプレミスの Dispatcher 設定を AEM as a Cloud Service に変換して。"	エージェントが references/dispatcher/context.md を読み込みます — 設定のモードを検出し、ツール設定を生成し、Adobe の dispatcher-converter を実行し、出力を検証（filter/ACL のハードゲート）してから、最終検証を行います。ブランチ E。 Runbook のパターン ID：dispatcherConversion（ヒューリスティック）。
スタータープロンプト（コピーして貼り付け） — 上記のクイックスタートの表では各パターンを個別に扱っています。以下では、プロジェクト全体のエントリーポイント、ソース固有の実行方法（CSV／CAM／手動）、複数ステップの組み合わせを示します。

• 「AEMaaCS への移行に向けてコードをレビューして」 — 変更を加える前に、完全な手順書を実行する場合はここから開始してください。
• 「移行スキルを使って、スケジューラーのみを対象にしてください。BPA CSV は ./reports/bpa.csv です。」
• 「CAM からレプリケーションのみを対象にしてください。まずプロジェクトの一覧を表示し、どれかを選びます。」
• 「手動： .../Listener.java のイベントリスナーを移行してください。」
• 「Classic UI とカスタムウィジェットのすべての指摘を修正してください。まず CDW、その後にダイアログをお願いします。」
• 「BPA CSV ./reports/bpa.csv を使って、guavaCache の指摘を修正してください。」

パス規約（Adobe Skills モノレポ）

skills/ ディレクトリの親であるリポジトリルートから：

記号	パス
{code-assessment}	skills/aem/cloud-service/skills/code-assessment/

例：{code-assessment}/SKILL.md、{code-assessment}/scheduler/SKILL.md、{code-assessment}/references/scr-to-osgi-ds.md。

ワークスペースの範囲（IDE）— ユーザーのコードのみ

ユーザーの AEM プロジェクト（Java、バンドル、設定、HTL）の検索と編集に適用されます。{code-assessment} の下にインストールされたスキルファイルの読み取りには適用されません。

• 検索、glob、grep、移行対象のファイルの読み書きでは、現在の IDE ワークスペースのルートフォルダー（単一ルートまたは複数ルート）のみを対象範囲とします。
• ユーザーがパスを明示的に指定するか、対象に含めるよう依頼しない限り、ソースを「見つける」ために親ディレクトリ、ディスク上の隣接フォルダー、~、他のクローン、任意の絶対パスを検索してはいけません。
• BPA CSV／CAM の対象： filePath またはクラスとファイルの対応先がワークスペースルート内に解決できない場合は、そこで停止し、見つからないパスをユーザーに伝えてください。ファイルシステム内の別の場所を探してはいけません。IDE で正しいプロジェクトを開くか、パスを調整するよう依頼してください。
• 手動フロー： ワークスペース内にある、ユーザーが指定したファイルのみを移行します（または、ユーザーが明示的に指定したパスのみを対象にします）。ワークスペース外を検索して対象範囲を広げてはいけません。

必須の委任（最初に実施）

ブランチ A — OSGi 設定 → Cloud Manager（このセッションでは Java BPA パターンなし）：ユーザーが設定ファイルのスキャン、Cloud Manager 環境のシークレットまたは変数の作成／設定、OSGi／.cfg.json／ui.config からのパスワードまたはシークレットの移動を依頼するか、AEM CS の $[secret:]／$[env:] に言及した場合は、ただちに references/osgi-cfg-json-cloud-manager.md を読み、そのファイルに定められた製品ルールとワークフローに従ってください（Adobe AEM as a Cloud Service の OSGi と Cloud Manager の動作はそのファイルに記載されているため、外部ドキュメントの URL は不要です）。簡潔なプロンプトで十分です。参照ファイル名を指定する必要はありません。この作業ではブランチ B をスキップしてください。

ブランチ B — Java／HTL／BPA パターンの移行：

1. **{code-assessment}/SKILL.md**を読みます。重要なルール、Java のベースラインへのリンク、パターンガイドの表、手動パターンのヒントが記載されています。
2. 現在有効な単一のパターンに対応するパターンガイド（またはリファレンス）を読みます。
   • scheduler → {code-assessment}/scheduler/SKILL.md (パターンガイド)
   • resourceChangeListener → {code-assessment}/resource-change-listener/SKILL.md (パターンガイド)
   • replication → {code-assessment}/replication/SKILL.md (パターンガイド)
   • eventListener / eventHandler → {code-assessment}/event-migration/SKILL.md (パターンガイド — JCR と OSGi Event Admin の両方のパス)
   • assetApi → {code-assessment}/asset-manager/SKILL.md (パターンガイド)
   • htlLint → {code-assessment}/references/data-sly-test-redundant-constant.md (リファレンス — HTL lint は専用のパターンガイドではなく、共通の単一リファレンスです)
   • vault-package-dependencies → references/vault-package-dependencies.md (リファレンス — ヒューリスティックな pom.xml スキャンです。この依存関係の形態はネイティブの AEMaaCS コードには存在しないため、code-assessment ではなく migration のみにあります)
   • guavaCache → references/guava-cache.md (リファレンス — Guava キャッシュから Caffeine への置き換えです。Guava キャッシュの使用はネイティブの AEMaaCS コードにはなく、レガシー AEM から引き継いだコードにのみ存在するため、code-assessment ではなく migration のみにあります)
3. コードで SCR、ResourceResolver、またはコンソールログを使用している場合は、{code-assessment}/references/scr-to-osgi-ds.md と {code-assessment}/references/resource-resolver-logging.md（またはハブ {code-assessment}/references/aem-cloud-service-pattern-prerequisites.md）を読みます。

パターンガイド（またはリファレンス）を読むまでは、Java または HTL を変換しないでください（ブランチ B）。ブランチ A では {code-assessment} のパターンガイダンスは必要ありません。

ブランチ C — テンプレートのモダナイゼーション（BPA なし）：静的テンプレートから編集可能テンプレートへの移行、および／または AEM Modernize Tools のルール（構造／コンポーネント／ポリシー）。3 つのフェーズ（コンテキスト → テンプレートごとの実行 → 検証）で進めます。references/template-modernization/template-modernization-context.md から開始します。ジェネレーターは editable-template-creation.md と aem-modernization.md です。生成後のチェックは template-modernization-validation.md にあります。ブランチ B はスキップしてください。

ブランチ D — レガシー UI の移行（legacy-ui/ のサブフォルダー）：ユーザーが Classic UI／ExtJS ダイアログの変換、Coral 2 ダイアログのアップグレード、カスタム ExtJS ウィジェットの移行、LUI または CDW BPA の検出結果の修正を依頼した場合、または cq:Dialog／xtype／cq:Widget に言及した場合：

• ダイアログの検出結果の場合のみ（lui パターン、または legacy.dialog.classic／legacy.dialog.coral2 のみ）：
  1. references/legacy-ui/dialog/context.md を読みます — getBpaFindings('lui', …) を使用し、ダイアログのサブタイプに絞り込み、それ以外はすべて注記を付けてスキップします。
  2. convert-extjs → references/legacy-ui/dialog/extjs-to-coral3.md。
  3. upgrade-coral2 → references/legacy-ui/dialog/coral2-to-coral3.md。
  4. 検証：references/legacy-ui/dialog/validation.md。
• カスタムウィジェットの検出結果（cdw パターン）の場合：
  1. references/legacy-ui/cdw/context.md を読みます — getBpaFindings('cdw', …)、xtype の一覧。
  2. xtype ごとに：references/legacy-ui/cdw/conversion.md（マッピングを適用するか、Granite UI コンポーネントのひな形を作成します）。
  3. 検証：references/legacy-ui/cdw/validation.md。
  4. 同じコンポーネントに LUI legacy.dialog.classic の検出結果もある場合は、その後にダイアログの移行を実行します — これですべての xtype が解決済みになります。

両方が必要な場合の実行順序：まず CDW、その後にダイアログです。 CDW によってカスタム xtype が解決されるため、ダイアログ変換を中断せずに進められます。ブランチ B はスキップします。ブランチ C はスキップします。

ブランチ E — Dispatcher 変換（AMS／オンプレミスの Apache httpd ＋ Dispatcher から AEMaaCS への移行；今回のセッションでは Java BPA パターンはありません）：

ユーザーが Dispatcher 設定を AEM as a Cloud Service に変換／移行するよう求めた場合は、6 フェーズのフローに従います。このフローでは、Adobe がメンテナンスする @adobe/aem-cs-source-migration-dispatcher-converter を変換エンジンとして使用し、その上に検出、設定生成、出力検証、判定、検証を追加します。まず references/dispatcher/context.md を読みます。ブランチ B はスキップします。

1. インベントリ作成 — scripts/dispatcher-inventory.js（buildInventory）を実行し、モード（standard / flexible / ams / already-cloud / not-dispatcher / v1 / unknown）を検出して、フィルター／書き換え／キャッシュルールの数を数えます。（ams はモノリシックな AMS オンプレミス設定で、flexible と同じオンプレミス実行ツールで変換しますが、実態に即したラベルが付けられています。）モードとシグナルの定義については、references/dispatcher/context.md を参照してください。モードが already-cloud、not-dispatcher、または unknown の場合は、その結果をもって停止してください。最初の 2 つは変換対象がなく、unknown はレイアウトが曖昧または不完全なため、コンテンツを参照しないツールを実行する前に（resolveExecutor は unknown をオンプレミス実行ツールに渡すため、ここではエージェントがゲートとなります）、ユーザーに確認する必要があります。
2. 計画を立てて config.yaml を生成 — references/dispatcher/config-generation.md に従ってコンバーター設定を作成します（モードごとのマッピング。variablesToReplace はフラットなマッピング、portsToMap はリスト、appendToVhosts はファイルパスです）。
3. 実行 — ensureToolInstalled を実行して（初回使用時に Adobe ツールを Git で無視される scripts/dispatcher-tool/node_modules/ に自動インストール）、続いて runConverter（scripts/dispatcher-run.js）を実行します。実行ツールはモードに応じて選択されます（standard → main.js、flexible / オンプレミス → singleFileMain.js）。
4. 検証して正規化 — scripts/dispatcher-verify.js を実行し、references/dispatcher/output-verification.md を適用します。filter-acl-loss の場合は必ず停止してください（ベースラインにフィルタールールがあったにもかかわらず filters.any が空の場合）。解決するまで変換結果は使用できません。
5. 判断と境界をまたぐ引き継ぎ — references/dispatcher/conversion-patterns.md の判断カタログを適用します。Cloud Manager の環境変数はすべて Branch A に引き継ぎ、CDN 候補のルールにはフラグを付けます。目標とする最終状態の規約については、references/dispatcher/current-sdk-conventions.md を参照してください。この引き継ぎを実行するには、scripts/dispatcher-crossboundary.js を実行して Cloud Manager 変数の引き継ぎアーティファクトを作成し、references/dispatcher/cross-boundary.md を適用して各懸案事項の担当先を割り当てます。CM 変数 → Branch A、変更不可の鮮度 → dispatcher スキルの sdk(diff-baseline)、セキュリティヘッダー／エッジ → security-hardening、検証 → config-authoring。
6. 検証 — references/dispatcher/validation.md に従って変換後の src を検証します（dispatcher スキルの SDK バリデーターとガードレールに委任）。問題がなくなるまで繰り返します。検証に失敗した場合、結果を完了済みとして提示しないでください。検証後、scripts/dispatcher-report.js（renderReport → writeReport）を実行して統合レポートを conversion-report.md として出力します。レポートには対象範囲の件数、CM への引き継ぎ、委任先での次の確認項目のチェックリストが含まれます。

このスキルを使用するタイミング

• レガシーな AEM Java を Cloud Service 互換のパターン（スケジューラー、ResourceChangeListener、レプリケーション、EventListener/EventHandler、AssetManager）へ移行する
• **HTL（Sightly）**のリント警告（data-sly-test: redundant constant value comparison）を修正する
• AEMaaCS でのパッケージインストールを妨げる Vault パッケージのインストール時依存関係（day/cq60/product:*）を修正する
• Guava キャッシュ（com.google.common.cache.*）を Caffeine（guavaCache）に置き換える
• OSGi → Cloud Manager のシークレット／変数の外部化（ブランチ A）、テンプレートのモダナイゼーション（ブランチ C）、レガシー UI のダイアログ／CDW 移行（ブランチ D）
• BPA（CSV またはキャッシュ済みコレクション）または MCP 経由の CAM を使って作業を進める。1 セッションにつき 1 つのパターン
• Dispatcher の変換： ブランチ E — Adobe の dispatcher-converter を使い、AMS／オンプレミスの Apache+Dispatcher 設定を AEMaaCS 向けに変換します。モードの検出、設定の生成、出力の検証（filter／ACL の必須チェック）、境界をまたぐ引き継ぎ、SDK による検証を行います。参考資料：references/dispatcher/。

上記の各項目のブランチ振り分けと、最初に委任する作業については 必須の委任 で一元的に定義しています。このリストは「使用するタイミング」のみを示します。

前提条件

• プロジェクトのソースと Maven／Gradle ビルド
• BPA CSV または MCP へのアクセス（任意ですが、推奨）
• htlLint の場合：.html HTL テンプレートを含む ui.apps または同等のコンテンツパッケージ

BPA の検出結果 — フロー

スクリプトは getBpaFindings 経由で実行します（ヘルパーの呼び出しを参照）。ヘルパーが利用できない場合を除き、コレクションのロジックを手作業で再実装しないでください。

ヘルパーには、呼び出し元の設定に応じて選択される、互いに独立した 2 つの経路 があります。

1. MCP が設定されている（mcpFetcher と projectId が渡されている）→ 最初の呼び出しで MCP からすべての検出結果を取得し、<collectionsDir>/mcp/<projectId>/<pattern>.json にキャッシュします。 最初とそれ以降のすべての呼び出しで MCP キャッシュから読み込み、1 バッチを返します。
2. MCP が設定されておらず、BPA CSV が指定されている → 最初の呼び出しで CSV を解析し、統合コレクションの JSON を <collectionsDir>/unified-collection.json に書き込みます。 すべての呼び出しで CSV キャッシュから読み込み、1 バッチを返します。

2 つのキャッシュは独立しています。MCP セッションが CSV セッションを上書きすることも、その逆もありません。どちらも設定されていない場合、ヘルパーは no-source を報告し、エージェントはソースを提示するようユーザーに尋ねます。

すべての経路でバッチ処理が必須です：getBpaFindings は 5 件のバッチ（result.targets）と、{ total, returned, offset, limit, nextOffset, hasMore } 形式の result.paging エンベロープを返します。1 バッチを処理して報告したら停止し、ユーザーの許可を得てから再開してください。詳しいルールは、以下の バッチ処理（バッチサイズ 5） を参照してください。

注： htlLint は BPA CSV には含まれません。代わりに rg による事前の検出を使用します。以下の htlLint フロー を参照してください。

MCP 経由の CAM（概要）

コード変換パターンのフロー（scheduler、assetApi、eventListener、resourceChangeListener、eventHandler、guavaCache、lui、cdw）には fetch-cam-bpa-findings-by-pattern を使用します。ユーザーが代わりに「critical／major／advisory／info の検出結果は何か」と尋ねた場合は、fetch-cam-bpa-findings-by-importance を使用します。このツールは、最新の BPA レポートから、指定された重要度の正式な _COUNT_<code> 行を取得し、件数の降順で返します。どちらのツールも、呼び出す前にプロジェクトについてユーザーの明示的な確認が必要です。ユーザーに CAM プロジェクト名または ID を尋ねてください。ツールが内部で解決するため、確認されていないプロジェクト名の文字列を渡してはいけません。判明している場合は projectId を優先してください。ツールの完全なスキーマ、REST に関する注記、再試行、エラー処理： references/cam-mcp.md。

ヘルパーの呼び出し

スクリプトは、この SKILL.md と同じ階層の ./scripts/ にあります。

const { getBpaFindings } = require('./scripts/bpa-findings-helper.js');

// First batch (defaults: limit=5, offset=0)
const result = await getBpaFindings(pattern, {
  bpaFilePath: './cleaned_file6.csv',
  collectionsDir: './unified-collections',
  projectId: '...',
  mcpFetcher: mcpFunction
  // limit: 5,   // implicit default
  // offset: 0,  // implicit default
});

// Next batch — only after the user says to continue
if (result.paging?.hasMore) {
  const next = await getBpaFindings(pattern, {
    bpaFilePath: './cleaned_file6.csv',
    collectionsDir: './unified-collections',
    projectId: '...',
    mcpFetcher: mcpFunction,
    offset: result.paging.nextOffset
  });
}

result:

• success、source（'unified-collection' | 'bpa-file' | 'mcp-server' | …）
• message（人が読めるバッチのステータスを含みます）
• targets — 現在のバッチ（長さは <= limit）
• paging: { total, returned, offset, limit, nextOffset, hasMore } — 成功した呼び出しでは常に含まれます

単発のプログラムからの呼び出しでバッチ処理を無効にするには、limit: null を渡します。スキルのワークフローでは、これを決して行いません。

コレクションのキャッシュ

コレクションは ./unified-collections/ にあります。コレクションが存在し、ユーザーが新しい CSV を指定した場合は、再利用するか再処理するかを尋ねます。

BPA CSV の読み込み

pattern がセッションのパターンと一致する行をフィルタリングします。一般的な列は pattern、filePath、message です。

MCP エラーとフォールバック

重要： MCP の呼び出しに失敗した場合は、ワークフローを直ちに停止し、"not found" や 404 形式のプロジェクトエラーを含め、ツールのエラーメッセージをそのまま正確にユーザーに伝えます。移行手順を続行したり、ワークスペースから別の CAM プロジェクトを推測したり、独断で手動／ローカル移行に切り替えたりしないでください。

例外： 有効化制限エラー（プレフィックスは references/cam-mcp.md に記載されています）は、言い換えずにそのまま正確に表示し、ユーザーが対処するまで自動フォールバックを行わないでください。

停止後は、何に失敗したかを平易な言葉で要約してもかまいません。必要であれば、list-projects のプロジェクトを再表示してもかまいません。次のステップをユーザーが明示的に指示した場合（例：一覧にある正しいプロジェクト ID／名前、BPA CSV のパス、または手動フローで使う特定の Java ファイル）のみ、続行します。

再試行、エラーの分類、ユーザーの指示による CSV／手動パスを許可する条件については、references/cam-mcp.md に従ってください。それでも、無言でフォールバックしてはいけません。ツールのエラーをユーザーに隠してはいけません。

停止後に提示する任意のプロンプト（ユーザーの返信が必要です）： 「使用する CAM プロジェクト（一覧にある ID または名前）、BPA CSV のパス、または手動移行を行う Java ファイルを返信してください。」

パターンガイド

ここにパターンの表を重複して記載しないでください。{code-assessment}/SKILL.md → Pattern Guides を使用してください。5 つのパターンにはそれぞれパターンガイド（{code-assessment}/<pattern>/SKILL.md）があります。共通トピック（SCR→DS、ResourceResolver／SLF4J、HTL lint、prerequisites hub）は参照資料（{code-assessment}/references/<file>.md）のままにします。vault-package-dependencies は migration 専用の参照資料（references/vault-package-dependencies.md）であり、{code-assessment} のパターンガイドではありません。パターンごとのルーティング表については、上記の Branch B step 2 を参照してください。

ワークフロー

Step 0：移行ランブック（レビュー／スキャンの開始地点）

ユーザーが「AEMaaCS への移行に向けてコードをレビューして」「プロジェクトをスキャンして AEM への移行に備えて」など、広範なレビュー／スキャンを依頼し、特定のパターンを 1 つ指定していない場合は、適用作業を始める前に、読み取り専用の移行ランブックを作成します。

ランブックでは、移行スキルが対応できるすべてのパターンを扱います。各パターンでは検出戦略を指定します。CSV に対応するパターンでは優先順位カスケードを実行し、それ以外のパターンでは既存の検出方法を維持します。

パターン	戦略	検出方法
scheduler, resourceChangeListener, event-migration, assetApi	cascade	BPA/CAM → CSV → アナライザー → LLM スキャン（優先順位リスト）
replication	cascade	アナライザー → LLM スキャン（BPA/CSV のサブタイプマッピングなし）
htlLint	html-scan	.html のヒューリスティックな正規表現スキャン（純粋な Node — rg バイナリは不要）
osgiConfig	config-scan	OSGi 設定ファイルをヒューリスティックにスキャンし、シークレットらしきキー／$[secret:]／$[env:] プレースホルダーを検出します — キー名と場所のみを対象とし、シークレットの値は決して取得しません
vault-package-dependencies	pom-scan	Maven の有効な POM（mvn help:effective-pom。リアクタールートごとに 1 回実行）を優先します。<pluginManagement> の継承や、実行ごとの <configuration> とプラグインレベルの <configuration> の違いは Maven の処理であり、こちらの問題ではありません。Maven がモジュールを解決できない場合（親リポジトリの消失、オフライン状態 — レガシー AEM 6.x／AMS のコードベースではよくあります）は、未加工の pom.xml テキストスキャンにフォールバックします。BPA サブタイプもアナライザーもありません。pom.xml のインストール時依存関係宣言は、デプロイ済みアーティファクトの BPA スキャンでは検出できず、コンパイル済みの検出器も存在しないためです。有効な POM の処理失敗はすべて警告として表示されるため、低下した状態のスキャンがクリーンな結果として黙って報告されることはありません。
lui, cdw, templateModernization	BPA cascade → content-scan フォールバック	BPA CSV/CAM ソースがある場合は、これらは BPA から取得されます（サブタイプ custom.classic.widget、legacy.dialog.classic／.coral2、legacy.static.template + custom.static.template）。BPA ソースがない場合は、ヒューリスティックな .content.xml スキャンにフォールバックします。templateModernization では、apps/<appId>/templates/** を任意の深さまで走査し（ネストされたテンプレートやグループ化されたテンプレートも含む）、各静的テンプレートをページコンポーネントのリソースタイプに基づいて custom.static.template または legacy.static.template に分類します。そのため、BPA レポートがなくてもカスタムとレガシーの区別が保たれます。サンプルプロンプトはコード評価ではなく、Branch D（legacy-ui）／Branch C（templates）に振り分けられます
guavaCache	bpa-only（アナライザーも content-scan もなし）	BPA が唯一の信頼できる情報源です（サブタイプ custom.guava.cache）。検出結果はバンドルごとに 1 件です。このサブタイプの identifier は顧客のクラスではなく Guava 内部のクラスであるため、生の行は行ごとに表示せず、メッセージに記載されたバンドルにまとめます。BPA ソースがない場合、guavaCache には確定的なフォールバックがなく、Tier 4 — LLM スキャンに表示されます。エージェントはモジュールごとに .java ファイルから import com.google.common.cache を grep し、references/guava-cache.md に従って結果に confidence: llm のタグを付けます。このパターンには意図的にコンパイル済みアナライザー検出器を設けていません。これは code-assessment 自体の検出処理では実行されないためです。
dispatcherConversion	content-scan	AMS／オンプレミスの Dispatcher 設定レイアウト（モノリシックな dispatcher.any + conf.vhost.d/、または conf.dispatcher.d/ の AMS ツリー）をヒューリスティックにスキャンします。dispatcher-inventory.js が検出し、サンプルプロンプトは Branch E に振り分けられます。

htlLint、osgiConfig、vault-package-dependencies、および lui／cdw／templateModernization の content-scan フォールバックはヒューリスティックです（キャッシュ内で confidence: heuristic のタグが付与されます）。これらは候補の一致であり、コンパイラーによる検証はされていません。BPA から取得した lui／cdw／templateModernization／replication／guavaCache の検出結果は信頼できる情報です。対象外：inject-in-sling-model と outdated-dependencies（これらは移行ではなく、code-assessment 自体の実行手順書の対象です）。 レポートがある場合は、BPA が信頼できる唯一の情報源です。 lui/cdw/templateModernization/replication は BPA の CSV/CAM から読み取られます（パーサーはこれらのサブタイプを抽出し、_COUNT_*/_STAT の集計行を除外するようになりました）。そのため、実行手順書の件数は BPA レポートの LUI ダイアログ／CDW／静的テンプレート／REP の集計値と一致します。lui にはダイアログのサブタイプのみが含まれます（legacy.custom.component → コンポーネント作成。legacy.static.template は templateModernization に計上されます）。.content.xml のスキャンは BPA のソースがない場合に限り、代替手段として使用されます。ただし、フラグが付いたレガシーノードがプロジェクトのソースに含まれないパッケージ（例：acs-commons）に存在する場合、BPA に比べて過少計上になることがあります。replication：レポートがある場合は BPA の replication.agent の検出結果を使用し、それ以外の場合はアナライザーがソースから Replicator の使用を検出します。

1つのコマンドとして実行する（こちらを実行してください。ジェネレーターのソースは読まないでください）

ランブックは1つの CLI コマンドで生成されます。このコマンドは、ローカルアナライザーとすべてのスキャナーを実行し、migration-runbook.md とサイドカーキャッシュの両方を書き込み、概要行を出力します。ジェネレーターを require() したり、内部の仕組みを調べたり、プロセス内 MCP ブリッジを書いたりする必要はありません。

1. 基本（常に実行）：

   node scripts/runbook-generator.js <workspaceRoot> --out ./migration-runbook.md --cache ./migration-runbook.json
   

   これだけで、ローカルアナライザー（Java のカスケードパターン）、html-scan、config-scan、pom-scan、および content-scan のパターンを網羅できます。

2. BPA CSV がある場合： --csv ./reports/bpa.csv を追加します。

3. CAM/MCP が設定されている場合： いずれにしても実行するBPAフェッチを1回行います。関連する各スラッグ（scheduler、resourceChangeListener、eventListener、eventHandler、assetApi、replication、lui、cdw、templateModernization、guavaCache、urc）について CAM MCP ツールを呼び出し、生のターゲットをスラッグをキーとする JSON ファイルに書き込み、それを渡します。

   # bpa.json shape: { "<slug>": [ <raw BPA target>, ... ], ... }   (a slug you omit = "not in report", treated as clean)
   node scripts/runbook-generator.js <workspaceRoot> --bpa-json ./bpa.json --out ./migration-runbook.md --cache ./migration-runbook.json
   

アナライザーの結果は常に BPA の結果と統合されます。BPA のソースがカスケードパターンを問題なしと報告していても、実際のソースコードが存在する場合は、ローカルアナライザーの検出結果が追加されます（クラス名で重複排除され、Detected via: BPA / CAM + analyzer と表示されます）。そのため、「BPA では問題なし」という結果をソースコードと手作業で照合する必要はありません。スクリプトがすでに処理しています。

Tier 4 — LLM スキャン（コマンドが ⚠️ Needs LLM scan: … と出力した場合のみ）。これは、決定論的なスキャナーではスキャンできない cascade／bpa-only パターンがある場合に発生します（例：BPA ソースも JDK もない guavaCache）。パターンガイドの {code-assessment}/<pattern>/ にあるヒントに従って検索します（guavaCache の場合は import com.google.common.cache。詳しくは references/guava-cache.md を参照）。ヒットした箇所を JSON ファイルに書き込み、--llm-findings を指定して同じコマンドを再実行します。

# llm.json shape: { "<pattern>": [ { "file": "...", "line": 42, "snippet": "..." }, ... ] }
node scripts/runbook-generator.js <workspaceRoot> --bpa-json ./bpa.json --llm-findings ./llm.json --out ./migration-runbook.md --cache ./migration-runbook.json

ジェネレーターはこの1回の処理で結果を統合し、再レンダリングして、キャッシュを書き換えます。内部オブジェクトを手作業で編集する必要はありません。

コマンドの完了後、ユーザーに次のように伝えます（数値は出力された概要行から取得します）。

「migration-runbook.md を作成しました。{N} 個のパターンにわたる**{totalFindings} 件の検出結果**です（検出元：{sources}）。読み取り専用です。最初に移行したいパターン（例：scheduler）を返信してください。そのパターンですでに検出した結果を再利用するため、再スキャンは不要です。セッションごとに1パターンを適用するワークフローを実行します。」

このコマンドは、Markdown と同じ場所にサイドカーの検出結果キャッシュ（既定値：./migration-runbook.json）も書き込みます。このファイルには、各パターンの生の検出結果とその検出元が格納されます。以下のステップ3では、ライブの BPA／アナライザー／スキャンによる検索にフォールバックする前に、まずこのキャッシュを読み込みます。

ユーザーが最初から特定のパターンを指定している場合（例：「scheduler の検出結果を修正して」、「ui.apps の htlLint を修正して」、「Cloud Manager のシークレットがないか config ファイルをスキャンして」）は、ステップ0をスキップし、該当する適用フローに進みます。ステップ0を実行するのは、対象パターンが指定されていない広範なレビュー／スキャンの依頼のみです。

上級者向け（プログラムからの利用）。 同じ動作を API からも利用できます。プロセス内で実行する必要がある呼び出し元（例：--bpa-json の代わりにセッション内の mcpFetcher を使う場合）は、./scripts/runbook-generator.js の generateRunbook({ workspaceRoot, bpaFilePath, preFetchedBpa, llmByPattern, outputPath, cachePath }) および mergeLlmFindings(gathered, llmByPattern) を使用できます。上記の CLI を優先し、必要な処理を CLI で表現できない場合に限り API を使用してください。

---

セッションごとに1パターン

ユーザーがすべての修正を依頼した場合や、BPA の結果に複数のパターンが混在している場合は、最初にどのパターンを対象にするか尋ねてください。パターンごとに1つのコミットを作成することを推奨します。

Step 1: パターン ID

まず、Java 以外の分岐（Required delegation で全面的に振り分けられます）を確認してください。これらには BPA パターン ID は不要です。

• OSGi configs → Cloud Manager → Branch A。
• Template modernization（「create editable templates」、「generate /conf templates」、「static to editable」、「structure/component/policy rewrite rules」、「parsys to container」、「AEM Modernize Tools」）→ Branch C。
• Legacy UI（Classic UI/Coral 2 ダイアログ、カスタム ExtJS ウィジェット、LUI/CDW の検出結果）→ Branch D（lui → dialog、cdw → cdw）。

リクエストが Dispatcher の変換（AMS またはオンプレミスの Dispatcher 設定を AEM as a Cloud Service に変換または移行すること）の場合は、Branch E に従ってください。Java パターンモジュールは不要です。Branch B はスキップしてください。

それ以外の場合は、リクエストをパターン ID に対応付けます：scheduler、resourceChangeListener、replication、eventListener、eventHandler、assetApi、htlLint、lui、cdw。判断できない場合は、{code-assessment}/SKILL.md の Manual Pattern Hints を使うか、ユーザーにいずれかを選んでもらってください。

Step 2: 対応状況

ID が code-assessment カタログ（{code-assessment}/references/patterns.md）にない場合は、そのパターンはまだサポートされていないと伝えてください。

Step 3: 対象

まずキャッシュされたランブックを確認してください。 ./migration-runbook.json（または generateRunbook の cachePath オプションに渡されたパス）が存在し、findingsByPattern[<active pattern>] 配列が空でない場合は、検出結果を再導出する代わりに再利用します。

• キャッシュファイルから { generatedAt, workspaceRoot, sourceByPattern, findingsByPattern } を読み込みます。
• allFindings = findingsByPattern[<active pattern>] を取得します。各エントリーは { pattern, file, line, snippet } です。file はキャッシュの workspaceRoot からの相対パスです（path.join(workspaceRoot, file) で解決します）。パターンのソースが mcp／csv の場合、line／snippet は null です（BPA 由来の検出結果には line／snippet は含まれません。これらが含まれるのは analyzer、html-scan、config-scan ソースのみです）。osgiConfig の検出結果にはさらに kind が含まれ、already-placeholdered の行には informational: true が含まれます。修正作業リストを作成する際は、これらをスキップしてください。
• このファイル内の他の場所で使われているものと同じ paginate ヘルパーを使って、バッチを分割します：

  const { paginate } = require('./scripts/unified-collection-reader.js');
  const { targets, paging } = paginate(allFindings, { offset, limit: 5 });
  

  これにより、以下の getBpaFindings のライブ処理とまったく同じ { targets, paging } エンベロープ、デフォルトの 5 件単位のバッチ、paging.nextOffset のセマンティクスが維持されます。異なるのはデータソースのみです。配列全体がすでにメモリ内にあるからといって、5 件単位のバッチ処理を省略しないでください。
• ユーザーに次のように伝えます："既存のランブックから <pattern> の検出結果 N 件を再利用します（生成日時：<generatedAt>）。"
• バッチを with_findings (pre-resolved) の呼び出しとして code-assessment に渡します（{code-assessment}/references/runbook.md を参照）。line／snippet がすでに入力されている検出結果では、analyzer の再実行は完全に省略されます。file のみが入力されている検出結果（BPA 由来）では、編集計画を作成する前に line／snippet を解決するため、code-assessment 内で analyze.sh --files <paths> の呼び出しが 1 回実行されます。
• キャッシュがない場合、現在のパターンのエントリーがない場合、またはユーザーが明示的に「re-scan」／「refresh」と指示した場合は、以下のライブ処理に変更を加えず進んでください。

BPA パターン（scheduler、resourceChangeListener、replication、eventListener、eventHandler、assetApi、lui、cdw）で、使用可能なキャッシュがない場合：getBpaFindings を実行します（bpaFilePath が指定されている場合は渡します）。内部では、各ステップが該当し、かつ成功した場合に限り、キャッシュ → CSV → MCP → 手動の順で処理します。MCP が失敗した場合は、MCP errors and fallback に従ってください（停止し、暗黙に次の手段へ進まないでください）。MCP の詳細は references/cam-mcp.md を参照してください。 lui の検出結果では、各ターゲットの identifier は JCR コンポーネントパス（例：/apps/myapp/components/content/mycomp）であり、Java クラス名ではありません。ファイルを開く前に、JCR → ファイルシステムのマッピングを使ってファイルシステムのパスに解決してください。注： luiCoral2 は単独の BPA パターン ID ではありません。Coral 2 ダイアログは、lui の結果内でサブタイプ legacy.dialog.coral2 として表示されます。getBpaFindings('luiCoral2', …) を単独で呼び出さないでください。getBpaFindings('lui', …) を呼び出し、分岐 D の内部でサブタイプを絞り込んでください。

dispatcherConversion の場合、ターゲットは BPA ではなく、dispatcher-inventory.js スキャン（ステップ 0 のランブックに表示）で検出された Dispatcher 設定ルートとモードです。分岐 E に直接進んでください。

getBpaFindings は、paging エンベロープとともに、5 件の検出結果（バッチ）（デフォルトは limit=5）を返します。エージェントはそのバッチだけを処理し、ユーザーが続行を指示するまで次のバッチを要求しません。以下の**バッチ処理（バッチサイズ 5）**を参照してください。

htlLint の場合：BPA／CSV／MCP はスキップしてください。キャッシュ済みのランブックエントリに htlLint の検出結果がすでに含まれている場合（"confidence": "heuristic" を伴い、コンパイラーによる検証ではなく正規表現の一致を示します）、上記のキャッシュ優先ルールに従って再利用します。ただし、編集する前に、各該当箇所を {code-assessment}/references/data-sly-test-redundant-constant.md のパターンと照合し、再度確認してください。キャッシュがない場合、ターゲットは rg によるプロアクティブな検出から取得します。以下のhtlLint のフローを参照してください。

osgiConfig（OSGi → Cloud Manager）の場合：キャッシュには、ヒューリスティックに基づくレビュー専用の検出結果（"confidence": "heuristic"。キー名と場所のみで、シークレットの値は含まれません）が保存されています。これらを最初のチェックリストとして使用し、分岐 A と references/osgi-cfg-json-cloud-manager.md に従って各値を分類してください（実際のシークレットか？ Adobe 所有の PID なら needs_user_review）。確認せずにヒューリスティックな plaintext-secret ラベルを信頼しないでください。

ステップ 4：編集前に読む

停止してください。 {code-assessment}/SKILL.md と、対象パターン用のパターンガイド（またはリファレンス）を読んでください。パターンからファイルへの振り分け表については、上記の分岐 B のステップ 2を参照してください。

ステップ 5：バッチを処理する

返されたバッチ内の各検出結果のみ（最大 5 件）について、次の手順を実行します。

1. IDE ワークスペース内でターゲットを解決します（IDE のワークスペース範囲を参照）。
2. ソースを読み、パターンガイド（またはリファレンス）に従って分類し、手順を順番どおりに適用して、リンターを確認し、次のファイルに進みます。

ステップ 6：バッチを報告して待機する

バッチの処理後、このバッチのみについて、paging.total 件中 paging.returned 件を処理したこと（クラス名を含む）、変更したファイル、スキップや失敗があればその内容を要約します。paging.hasMore が true の場合は、ユーザーに "Processed batch of N (offset {offset}–{offset + returned − 1} of {total}). Reply continue for the next batch, or name specific classes." と伝えます。そうでなければ、このパターンの処理が完了したことを伝え、セッションレポートに進みます。

その後、停止して待機します。バッチ処理のルールに従い、ユーザーが明示的に指示した場合にのみ再開してください。

手動フロー（BPA なし）

ユーザーが指定したファイル → 分類（code-assessment の手動パターンヒントを使うか、ユーザーに確認）→ パターンガイドまたはリファレンスが存在することを確認 → {code-assessment}/SKILL.md とパターンガイド（またはリファレンス）を読む（振り分けについては分岐 B のステップ 2 を参照）→ 変換 → 報告。

OSGi → Cloud Manager のフロー

収集に BPA CSV、CAM／MCP、code-assessment のパターンガイドは使用しません。必要な委任の分岐 Aと、references/osgi-cfg-json-cloud-manager.md のワンプロンプトワークフローに従ってください。

テンプレートのモダナイゼーションフロー（ブランチ C）

BPA／MCP は使用しません。コンテキスト → テンプレートごとの実行 → 検証の 3 つのフェーズについて、references/template-modernization/template-modernization-context.md で詳しく説明しています。確認済みのコンテキストとテンプレートごとの計画表を最初に使用し、references/template-modernization/editable-template-creation.md と references/template-modernization/aem-modernization.md に従ってジェネレーターを実行した後、references/template-modernization/template-modernization-validation.md を実行してください。検証に失敗した場合はコミットしないでください。

htlLint フロー

htlLint は BPA CSV や CAM／MCP を使用しません。代わりに、次の手順を実行します。

1. {code-assessment}/references/data-sly-test-redundant-constant.md を読みます。ここには Workflow、Proactive Discovery の rg パターン、および 4 つすべての修正パターンが記載されています。（HTL lint は専用のパターンガイドではなく、共有リファレンスとして用意されています。）
2. リファレンスの Proactive Discovery テーブルにある rg コマンドを使用して、対象を検出します（対象範囲：ui.apps/**/jcr_root/**/*.html またはユーザーのコンテンツパッケージのパス）。
3. 該当箇所をファイルごとにグループ化し、それぞれをパターン（ブール値リテラル、生の文字列、数値、分割式）に分類します。
4. リファレンスの対応するパターンのセクションに従って、各該当箇所を修正します。
5. 結果を報告し、警告が残っていないことを確認するために mvn clean install または HTL validate を実行するようユーザーに勧めます。

バッチ処理（バッチサイズ 5）

ソース（MCP または CSV）に関係なく、検出結果はデフォルトで 5 件ずつエージェントに渡されます。バッチ処理はクライアント側で行われます。負荷の高い取得処理（MCP 呼び出しまたは CSV の解析）は一度だけ実行され、ローカルの JSON キャッシュに保存されます。その後の各バッチでは、キャッシュの一部を切り出すだけなので、処理負荷は軽くなります。

ルール

1. デフォルトの limit は 5 で、1 回の呼び出しにつき 1 バッチだけを処理します。処理して報告したら停止してください。メモリに一度に 1 バッチを超えて保持したり、先読みしたり、複数のバッチを結合したりしないでください。スキルのフローでは limit: null を渡さないでください（このオプションは、全件取得を希望するプログラムからの呼び出し用です）。
2. オフセットは 0 から開始し、前回の呼び出しの result.paging.nextOffset で進めます。nextOffset を読み取り、offset + limit を自分で計算しないでください。
3. 順序は安定しています。 各キャッシュファイルは決定的な順序で一度だけ書き込まれるため、切り出される範囲は安定して連続します。
4. 再開はステートレスです。 進捗ファイルはありません。再開するには offset: previous.paging.nextOffset を指定して再度呼び出します。同じ pattern と offset を指定すれば、後のセッションでも同じバッチが取得されます。完了条件は paging.hasMore === false（または nextOffset === null）です。
5. 最初の呼び出しでキャッシュし、後続のバッチではキャッシュを読み込みます。MCP による取得／CSV 解析はバッチごとではなく、合計 1 回です。更新するには、キャッシュファイルを削除します。CSV の場合：<collectionsDir>/unified-collection.json、MCP の場合：<collectionsDir>/mcp/<projectId>/<pattern>.json。

エージェントに表示されるフロー

[User] "Fix scheduler findings using ./reports/bpa.csv"   (MCP path: pass { mcpFetcher, projectId } instead of bpaFilePath)
[Agent] getBpaFindings('scheduler', { bpaFilePath, limit: 5, offset: 0 })
        // first call parses CSV (or fetches MCP once) → writes cache → slices
        → paging: { total: 137, returned: 5, offset: 0, nextOffset: 5, hasMore: true }
        Processes 5 findings, reports: "Processed 5 of 137 (offset 0–4). Reply `continue`."
[User] "continue"
[Agent] getBpaFindings('scheduler', { bpaFilePath, limit: 5, offset: 5 })   // reads cache — no re-parse / no new MCP call
        → paging: { ..., offset: 5, nextOffset: 10, hasMore: true }
...

クイックリファレンス

ソースの優先順位（BPA パターン）： unified collection → BPA CSV → MCP → 手動パスの順です。MCP エラー後に自動的に次のソースへ進むわけではありません（MCP が失敗した場合は停止します。「MCP errors and fallback」を参照）。すべての BPA ソースでバッチサイズは 5 です。htlLint、OSGi→Cloud Manager、Template Modernization（C）、Legacy UI（D）では BPA／MCP を使用しません。「Required delegation」の各ブランチを参照してください。

ユーザー向けの文言： 「既存の BPA コレクションを使用しています（N 件の検出結果）…」／「BPA レポートを処理しています…」／「CAM から検出結果を取得しました。」／「data-sly-test の lint の問題を検出するため HTL テンプレートをスキャンしています…」／上記の MCP 停止後に表示する任意のプロンプト。

CLI（開発時のみ）

このスキルのディレクトリから：

# First batch (default offset=0, limit=5)
node scripts/bpa-findings-helper.js scheduler ./unified-collections
node scripts/bpa-findings-helper.js scheduler ./unified-collections ./cleaned_file6.csv

# Next batch: offset=5, limit=5
node scripts/bpa-findings-helper.js scheduler ./unified-collections ./cleaned_file6.csv 5 5

# Full unbounded listing (development / debugging only — skill never does this)
node scripts/bpa-findings-helper.js scheduler ./unified-collections ./cleaned_file6.csv 0 all

# Same batching on the low-level reader
node scripts/unified-collection-reader.js all ./unified-collections 0 5