migrate

stardust:migrate

direct が作成したターゲット仕様、prototype --prep が記述したビジュアルカノン、および prepare-migration 中に抽出したブランドモジュールカタログを、インベントリ内のすべてのページに適用します。stardust/migrated/ に、自己完結型でデプロイ可能な静的 HTML サイトを生成します。ページ単位で、差分更新可能かつ冪等です。

migrate は stardust の最終フェーズです。出力はプラットフォームに依存しない HTML です。AEM EDS、CMS、フレームワークなどへの後続変換は、migrated/、DESIGN.json、およびページごとの _meta.json サイドカーを使用する別のプラグインが担当します。

入力

• <slug> — 任意の位置引数です。このページだけを移行します。指定しない場合は、ステータスが directed、prototyped、または approved で（かつ stale ではない）すべてのページを移行します。
• --all — stale のページも含め、すべてのページを移行します。
• --force — 冪等性によるスキップの対象となる場合でも、すべてのページを再移行します。
• --require-approved — approved 以外のページの移行を拒否します。デフォルトでは directed のページも移行します（reference/template-and-module-rendering.md に従って Path A′ または Path B を使用）。このフラグを指定すると、承認が必須になります。
• --strict-canon — カノンに反する承認を拒否します。デフォルトでは逸脱をログに記録して続行します。テンプレートごとの柔軟性よりもカノンの遵守を重視するプロジェクトに便利です。
• --clean — 以前にバンドルされたアセットのうち、stardust/migrated/assets/ から参照されなくなったものを削除します。デフォルトでは無効です（migrate は追加のみを行います）。--force を含意します。実行時の bundledAssets Set に、現在参照されているアセットの完全な集合が含まれるよう、すべてのページを再レンダリングします。そうしないと、冪等性によりスキップされたページが引き続き参照しているアセットを --clean が削除するおそれがあります。reference/asset-bundling.md § Stale asset cleanup を参照してください。
• --pin-timestamp <ISO8601> — migrate の来歴タイムスタンプを固定し、ソースに変更がない状態で再実行した場合にバイト単位で同一の HTML を生成します。デフォルトでは現在の時刻を再使用します。通常の使用では問題ありませんが、CI のデプロイフィンガープリントで固定が必要になる場合があります。

モバイル対応監査、コンテンツソースのスキャン、プレースホルダーの拒否は、いずれも必須ゲートです。これらを回避する --skip-* または --allow-* フラグはありません。ゲートがページを拒否した場合は、提案されたファイルを修正し（再プロトタイプ化、インライン編集、または非の打ちどころのないコマンドの実行）、migrate を再度呼び出してください。

セットアップ

0. Playwright の再プローブ（必須の最初の手順）。 以前のフェーズで --no-save を指定してインストールした Playwright は、その後に実行される通常の npm i によって削除されます（extract SKILL.md § Setup → --no-save installs are ephemeral）。レンダリング手順を始める前に、プロジェクトルートで node -e "import('playwright').then(()=>process.exit(0))" を実行して確認し、失敗した場合は再インストールします（npm i -D playwright --no-save --legacy-peer-deps）。

1. マスタースキルのセットアップを実行します （skills/stardust/SKILL.md § Setup）。フローガード。 stardust/state.json が存在し、flow がなく、依頼が移行（URL と「migrate」／「to EDS」／「re-platform」）の場合は、実行してはいけません。マスタースキル § Two migration flows の 2 つのフローの表を表示し、ルーティングに戻してください。フローはサブスキルの実行前にそこで選択され、記録されます （skills/stardust/reference/state-machine.md § Flow keys）。再設計が依頼に明記されていない限り、replica を選択します。 （記録：同じデザインの移行を 2 件行う際、最初のコマンドを migrate <url> とした結果、レプリカゲートではなく、目視で調整した手作りのコンパイラーが作られました。）

2. stardust/state.json が存在し、少なくとも 1 つのページが directed であることを確認します。

3. プロジェクトルートに DESIGN.md と DESIGN.json が存在し、DESIGN.json.extensions.canon が設定されていることを確認します。

4. stardust/canon/ が存在し、少なくとも header.html、footer.html、canon.css が含まれていることを確認します。 Canon の自動ブートストラップ（手順 3～4 で Canon が見つからない場合）。 ドキュメントに記載された prototype → migrate → deploy の標準的な手順では prepare-migration を実行しないため、初回の migrate で Canon が存在しないのは正常です（E2E サイト 6 件中 4 件で確認されており、いずれも続行するには毎回手作業で Canon を導出する必要がありました。この問題を解決するための修正です）。Canon が存在せず、かつ approved のプロトタイプが 1 つ以上ある場合は、停止しないでください。最初の approved プロトタイプ（Canon の作成元。既定では home）から、../prototype/reference/canon-extraction.md § Five-step procedure に従って、Canon の書き戻しをインラインで実行します。header.html／footer.html／canon.css を stardust/canon/ に抽出し、トークンと構成パターンを DESIGN.json.extensions.canon に固定し、canon.source: "auto-bootstrap: <slug>" を記録します。これは、初回承認時に prototype --prep が実行する処理とまったく同じです。migrate は必要に応じてこれを実行し、コアパイプラインが行き詰まらないようにします。Canon が存在せず、かつ approved のプロトタイプもない場合（Canon を導出する元がない場合）に限り、停止して $stardust prepare-migration を推奨します。state.json.handsOff が設定されている場合、ブートストラップは自動実行され、ログに記録されます。対話型の場合は、続行する前に 1 行の通知として表示します。

5. stardust/direction.md に有効な（保留中ではない）方向性があることを確認します。

6. state.json.pages[] を読み込み、次のように分類します。

   • inScope：ステータスが directed、prototyped、または approved で、stale: false（または --all／明示的な <slug>）。
   • skipped：それ以外すべて。理由も記録します。

7. 対象範囲内のすべてのページで来歴を検証します。 inScope の各ページに対して、skills/stardust/reference/state-machine.md § Provenance validation に従い、validateProvenance(page) を呼び出します。いずれかのページにライブレンダリングの証拠がない場合は、ヘルパーのエラーで中断します。合成されたページレコードを migrate すると、デプロイ可能な HTML が生成されますが、これは元のサイトを誤って表現します。この問題こそが、バリデーター導入のきっかけとなった障害モードです。Phase 1 の前に、migrate 計画の出力へ Provenance OK on N pages を表示します。

8. Path A／Path A′ のすべてのソースでモバイル対応を監査します。 レンダリング分岐で提案済みまたはアーキタイプの HTML ファイルを使用するすべてのページ（reference/template-and-module-rendering.md § Render path selection における Path A、Path A′）について、skills/prototype/SKILL.md § Mobile-adapt audit に従って監査を実行します。

   • <meta name="viewport" content="width=device-width, ..."> が存在し、幅が固定ピクセル値に固定されていないこと。
   • @media (max-width: ...) ルールが 1 つ以上あること。
   • モバイル向けのブレークポイントが 640px 以下に 1 つ以上あること。

   条件を満たさないページは拒否します。この監査は必須であり、スキップ用のフラグはありません。ユーザーは提案ファイルを修正し（再度プロトタイプを作成するか、チャットで impeccable コマンドを実行し）、migrate を再実行します。監査結果を、migrate レポートとレンダリング後の _meta.json#audit.adapt サイドカーにページごとに記録します。Path B（独自レンダリング）は、これらのページでは adapt が実行されていないため監査をスキップします。モバイル対応が必要な Path B のページは、ユーザーが $impeccable adapt を別途実行して対応します。スキップが黙って行われたと誤解されないよう、この違いをレポートに明記します。

手順

フェーズ 1 — 計画

動的サーフェスの前提条件（セーフティネット）。
stardust/dynamic-features.md が見つからない場合、手動実行のフロー （extract → direct → prototype → migrate）ではインポート前の ゲートを通過していません。ページをレンダリングする前に、stardust の dynamics スキルのフェーズ 1〜3 を今すぐ実行してください（必要に応じて到達範囲を調べる extract --dynamics、アーキタイプへの検出器の実行、トリアージの下書き、整理）。 動的な各行の判断なしに、サイトを静的なものとしてインポートしてはいけません。ページごとに、そのページに関わるインベントリの行を contentDeviations[] の kind: "dynamic-dependency" エントリにします （reference/content-preservation.md § Dynamic dependencies）。

ゲート対象アーキタイプの前提条件（flow: replica）。
sibling 階層のページをレンダリングする前に、stardust/replica/progress.json を読み込みます。ページタイプのアーキタイプは、設定済みのすべてのブレークポイントで、pass: true のゲート結果を持つか、基準を超え、すべての残差に cause が付いている必要があります（../replica/reference/source-fidelity-gate.md § Residual logging format — 残差が文書化されていれば、アスタリスク付きの合格です）。アーキタイプが一度もゲートされていない場合、または基準を超えているのに残差エントリがない場合、そのページタイプはブロックされます。アーキタイプのスラッグと $stardust replica <archetype> を報告し、そのタイプのページは何もレンダリングしないでください。同じルールが rollout のセットアップにも適用されます。公開オリジンでの再ゲートに変更はありません。しきい値はゲートの設定に従います。

対象範囲が大きい場合は、計画を出力して確認を待ちます。

migrate plan
============

In scope: 127 pages
  Path A  (approved)                6 pages: home, news/post-housing-summit, news, ...
  Path A' (template-applied)      118 pages: 84 article, 5 listing, 11 program, 2 form, 16 static
  Path B  (unique)                  3 pages: 404, search, faq

Skipped:  0 stale, 0 unscoped

DESIGN.md sha:    1a2b3c4
DESIGN.json sha:  5d6e7f8
Canon shas:       header:7g8h9i  footer:9i0j1k  css:1k2l3m

Output:           stardust/migrated/  +  per-page _meta.json sidecars
Idempotent skip:  enabled (run with --force to override)

Reply "go" to proceed.

1〜3 ページの場合、または <slug> を指定して実行する場合は、確認を省略します。

フェーズ 2 — ページごとのレンダリング

レプリカフローでは、アーキタイプがデプロイされ、公開オリジンでゲートを通過した後にのみ、兄弟ページをレンダリングします（../replica/reference/handoff-contract.md § 3 row C, unit C-archetype。#126）。レンダリング結果はエンコーダーへの入力であり、そのゲートは PUT の後の行です。対象範囲内の各ページについて、 reference/migration-procedure.md と reference/template-and-module-rendering.md に従ってください：

• 冪等性のスキップチェックを最初に行います（designMd、designJson、sourceCurrent、sourceProposed、canonShas、archetypeSourceをSHA比較します）。
• プレースホルダーゲート（Path AとPath A′のみ — 提案ファイルまたはアーキタイプがあるページ）。[data-placeholder]要素または空でない_provenance.unsourcedContent[]がある場合は拒否します。ユーザーはmigrateを再実行する前に、提案ファイルの不足コンテンツを補完します。バイパスフラグはありません。公開サイトにプレースホルダーを公開することこそ、このゲートが防ぐべき失敗です。ウィジェットのマウントはリンク（a[data-widget]）であり、data-placeholderではないため、このゲートの対象にはなりません。
• レンダリング分岐の選択（T&M § Render path selectionに基づくLLMの判断）：A／A′／B。分岐に基づいてページのfidelityTierを宣言します。A → archetype（クラフトゲート対象）、A′ → sibling（canon-fork。幅広く対応するための低コストなデフォルト。クローン作成前にテンプレートごとに一度だけ分散を調査します。reference/fidelity-tiers.md § Sibling variance probeを参照。差分はバリアントクラスになり、ページごとのフォークにはなりません）、B／本文なし → thin（reference/fidelity-tiers.mdに準拠）。_meta.jsonにfidelityTier、archetypeSource、template（アーキタイプのスラッグ。アーキタイプ自身のサイドカーではnullのままです）、modules[]（ページのブロックID。複合セクションのみ）、widgets[]（ページのa[data-widget]マウントから導出）およびgatesPassed[]を記録します。これにより、網羅的な調査を行わなくても、どのページがクラフトゲートを通過し、どのページがクローンされたかがカバレッジに表示され、サイドカーからロールアウトのグループ化と重複排除を行えます。
• T&Mで選択した分岐の手順に従ってレンダリングします。
• Canonの適用 — クロームの挿入、canon.cssの挿入、差分の記録を行います。
• モジュールのレンダリング — stardust/canon/modules/<id>.htmlを使ってモジュールのインスタンスをレンダリングします。特注スロットはdata-bespokeで記録します。
• reference/content-preservation.mdに従ってコンテンツ保持ルールを適用します。内部リンクの書き換えでは、常に移行後ツリーのパスを出力します。見つからないスラッグにはbrokenのフラグを付けます。
• reference/fidelity-tiers.md § Content-count acceptanceに従ってコンテンツ数の受け入れ判定を行います。キャプチャしたソースページのJSONとレンダリング結果の間で、役割ごとに分類したノード数（見出し、本文／リストのノード、CTA、画像）を比較します。ログに記録されたcontentDeviations[]エントリで説明されていないクラスで数が減少した場合、そのページは不合格です。コンテンツを落とすインポーターの不具合は、下流の忠実度ゲートではなく、修正がまだ容易なこの段階で検出される必要があります。合格を_meta.json#gatesPassed[]に"content-count"として記録します。
• reference/metadata-and-jsonld.md（5つのカテゴリ、ページタイプに基づくJSON-LD）に従って<head>のメタデータを構成します。
• T&M § Validation contractsに従って検証します。厳格なコントラクトではページを拒否し、ソフトコントラクトではログに記録して処理を続行します。
• migration-procedure.md § Output path mappingに従って出力パスを計算します。
• アセットのバンドル。 最終的なHTMLからアセット参照をスキャンし（reference/asset-bundling.md § Detectionに記載された6種類の検出形式）、参照されている一意のサブパスをそれぞれstardust/current/assets/<subpath>からstardust/migrated/assets/<subpath>にコピーします（サブディレクトリ構造を維持）。その後、すべての参照をルート相対形式/assets/<subpath>に書き換えます。ページ間の重複排除には、state.json.migrate.bundledAssets[]をシード値とするモジュールレベルのSetを使用します。ソースアセットが見つからない場合は、§ Edge casesに従って警告してスキップします。バンドルの内部整合性は維持されます。
• メディアの調整。 同一オリジンにバンドルされていないすべての画像（Mode Aの画像再利用で再利用されるソースCDNのURL）について、reference/media-reconciliation.mdに従って最適化／維持／書き換え／除外を判断します。ソースURLのまま維持するクロスオリジンの<img>には、?v=キーが削除されてバリアントが破損するため、createOptimizedPictureを適用してはいけません。壊れたURLは修復する（?区切り文字の欠落、ホストの誤り）か除外し、about:errorのまま公開することはありません。rolloutでは、配信時に権威あるネットワーク解決を再実行します（media-reconcile.mjs）。
• シネマティックな兄弟ページ（<slug>-cinematic.htmlが存在する場合）。 migrateが使用するのは静的なプロトタイプのみで、シネマティックレイヤーが統合されることはありません。後続の利用者が使えるよう、モーションアセット（lenis.min.js、lenis.min.css）をstardust/prototypes/からstardust/migrated/assets/motion/にコピーします（冪等です）。これらを組み込むかどうかはdeploy／rolloutで判断し、ページの_meta.json#migrationDecisions[]にcinematic-variant-not-consumedを記録します。
• 移行後のindex.htmlと_meta.jsonサイドカーを同じディレクトリに書き込みます。プロヴェナンスブロックは<head>の最初の子要素とします。_meta.jsonにassetsBundled（このページで参照される一意のアセット数）を記録します。 このフェーズの処理はスクリプト化されています。 node skills/migrate/scripts/migrate.mjs render <slug…|--all>（プロジェクトのコピーでは stardust/scripts/migrate/ から実行します）がページマップを作成し、各ページを URL のリテラルパスに配置して、内部リンクを書き換え、アセットをバンドルし、<head>（出典情報、:root、canonical および JSON-LD のデフォルト値）を構成し、厳密に検証してサイドカーを書き込みます。入力の SHA が変更されていないページはスキップします。判断できない事項は、同じスクリプトでサイドカーに gate、deviation、decision、variant、modules として記録されます。pages[].status が先に進むことはありません。

記録単位。 サイト全体のレンダリングは、ロールアウトの C-deliver 単位台帳（../replica/reference/handoff-contract.md § 3 row C）の形式に沿って、stardust/migrate/progress.json に単位として記録されます。 units.<name>: {status: pending|running|done|failed, kind: plan|render|assets|report, templates[], pages: n, startedAt, endedAt, verdict}。plan 単位が 1 つ（フェーズ 1）、最大約 8 個の兄弟ページからなるテンプレートクラスターごとに render 単位が 1 つ（migrate.mjs render <slug…> にはクラスターの slug リストを渡します）、フェーズ 3 でメディアを再ホストする場合に assets 単位が 1 つ、report 単位が 1 つ（フェーズ 4）です。各単位では、この順序で処理します。progress.json への書き込み → チェックポイントのコミット → 次の単位。単位の終了は安全に再開できる地点であり、停止地点ではありません。migrate の途中でセッションを再開すると、ファイルを読み込んで done ではない単位だけを実行します。running のままの単位はその slug を再レンダリングします。ドライバーは冪等で、変更されていないページはスキップされます。記録された実行例では、最もコストのかかる単位として、1 つのセッションで 5 つのビルダーを並列実行し、31 個の兄弟ページをレンダリングしました。計画から最終レポートまでの間に再開地点はありませんでした。

フェーズ 3 — サイト全体のアセットとバンドルの最終処理

ページごとのアセットのバンドルはフェーズ 2 ですでに完了しています（参照されているメディアのサブパスはすべて stardust/migrated/assets/ にあります）。フェーズ 3 では、個々のページから明示的に参照されないサイト全体のアセットを補完します。

1. stardust/current/assets/logo.<ext> を stardust/migrated/assets/logo.<ext> にコピーします（存在しない、または古い場合のみ）。state.json.migrate.bundledAssets[] に記録します。

2. ファビコンの各バリエーションとフォントファイルが prepare-migration のフェーズ 4 で生成されていることを確認します。存在しない場合は警告を記録して続行します（移行後のサイトはそれらなしでもレンダリングされますが、プラットフォーム固有の機能の一部は利用できません）。

3. 移行済みページの一覧から生成した stardust/migrated/robots.txt と sitemap.xml を追加します。reference/metadata-and-jsonld.md § Sitemap entry を参照してください。

4. --clean が渡された場合は、 state.json.migrate.bundledAssets[] から stale = priorBundle.filter(p => !bundledAssets.has(p)) を計算し、stardust/migrated/assets/ から古いサブパスを削除します。削除項目は state.json.migrate.cleanedAssets[] に記録します。reference/asset-bundling.md § Stale asset cleanup を参照してください。

5. 移植性を確認します。バンドルは file:// 経由、ウェブサーバーのルート、および任意のサブパスで動作する必要があります。「1 つの形式で、どこでも動作」です。すべての監査を実行します。grep の出力が空でない場合、またはフィクスチャの終了コードが 0 以外の場合は、引用されたエラーメッセージを示して実行を失敗させます。

   # No source-tree escapes
   find stardust/migrated/ -type f -name '*.html' -exec grep -l '\.\./current/' {} +
   # Error: "asset still points outside the migrated tree; rewrite via the
   #   asset-bundling pass per reference/asset-bundling.md § Detection"
   
   # No absolute internal references in attribute values (404 on file:// and subpath)
   grep -rE '(href|src)="/[^/]' stardust/migrated/ --include='*.html'
   # Error: "absolute href `/beers/` will 404 on file:// and on subpath hosts;
   #   rewrite via the page map per migration-procedure.md § Reference shape"
   
   # No absolute internal references in url() (inline style, <style> blocks, CSS)
   grep -rE 'url\(\s*["'\'']?\s*/[^/]' stardust/migrated/ --include='*.html' --include='*.css'
   # Error: "absolute url(/...) reference will 404 on file:// and on subpath hosts;
   #   rewrite via the asset-bundling pass per asset-bundling.md § Rewrite"
   
   # No directory-only nav (doesn't resolve on file://). Pattern accepts
   # only relative or root-absolute hrefs (./, ../, /, or bare segment)
   # so external URLs like https://google.com/ aren't false-flagged.
   grep -rE 'href="(\.{0,2}/|[a-zA-Z0-9_-])[^:"#?]*/"' stardust/migrated/ --include='*.html'
   # Error: "directory-only href `./beers/` won't resolve on file://;
   #   append the explicit index.html (or the source URL's .html leaf)
   #   per § Reference shape"
   
   # pageMap consistency — every internal href appears as an outputPath
   node skills/migrate/fixtures/pagemap-audit.mjs stardust/migrated/ stardust/state.json
   # Error: "internal href has no pageMap entry; link rewriting bypassed the
   #   page map per § Page map (build once, use everywhere)"
   
   # Headless file:// round-trip — the test that proves zip-and-deploy works
   node skills/migrate/fixtures/file-protocol-audit.mjs stardust/migrated/
   # Error: "<offending file> linked <ref> that 404s under file://; see the
   #   Playwright network log printed above"
   

   監査は必須で、スキップフラグはありません。契約は「自己完結型で、zip してデプロイ可能」であり、これらの監査はその主張を裏付ける検証手段です。

アセットの移行は冪等です。ファイルはコンテンツハッシュで管理され、存在しない場合にのみコピーされます。ページごとのバンドルでは、実行全体を通して重複が排除されます。

フェーズ 4 — 状態の更新と報告

state.json を更新します。

• 正常に移行された各ページについて、status を migrated に進め、履歴エントリを追加し、stale フラグを クリアして、migratedPath を設定します。
• 冪等性によるスキップの対象となったページについては、状態を 変更しません。
• 検証に失敗したページについては、状態を変更せず、 失敗を state.json.lastRun.failures[] に記録します。
• skills/stardust/reference/migrate-output-format.md § State.json contract に従って、トップレベルの migrate ブロックを書き込みます。内容は selfContained: true、outputDir、 totalAssetsBundled、bundledAssets[]、ページごとの assetsBundled 件数、missingAssets[]、cleanedAssets[] です。 これは、下流のコンシューマーがテストする前方互換性のシグナルです。

実行の概要を出力します。

migrate complete
================

 122 migrated         home, about, news/post-housing-summit, ...
   3 unchanged        about, programs/shelter, news/post-old (idempotent skip)
   2 failed           contact (validation: required slot missing),
                      legal/privacy (validation: color-reservation violated)
   0 stale skipped

Render branches:
  Path A   6   approved-from-prototype
  Path A'  116 template-applied (84 article, 5 listing, 11 program, 2 form, 14 static)
  Path B   3   unique-render (404, search, faq)

Pages with non-trivial decisions: 12
  about            canon-deviation: footer carries financials disclaimer
  donate           template-adapted: amount-pills slot moved above headline
  ...

Broken internal links: 5
  /events       referenced by 2 pages; not in inventory
  /press        referenced by 1 page; not in inventory
  ...

Bespoke slots crossing promotion threshold: 1
  hotline-211: "state"  (3 instances) — consider `$stardust prepare-migration --refine-module`

Missing assets: 2
  generated/orphan-1.jpg     referenced by 1 page  (home)
  generated/orphan-2.jpg     referenced by 2 pages (about, contact)
  (Re-extract or accept the gap — bundle is deployable; refs 404 at view time.)

Output:  stardust/migrated/  (122 pages, 47 bundled assets, 4.2 MB) — self-contained, zip-and-deploy

Next:
  - Review:    open stardust/migrated/index.html in a browser
  - Audit:     $impeccable critique stardust/migrated/
  - Deploy:    cd stardust/migrated && zip -r ../site.zip .
               upload the zip to any static host that serves at the host root
  - Refine:    edit DESIGN.md or canon files, then re-run $stardust migrate

出力

パス	目的
stardust/migrated/<source-url-path>	移行されたページです。出力パスはソース URL をそのまま反映します（reference/migration-procedure.md § Output path mapping を参照）。バンドルはzip-and-deploy形式です。任意の静的ホストの任意のパスに配置するか、file:// 経由で index.html を直接開けます。内部参照はすべて、それを出力するページからの相対パスです。ナビゲーション先には index.html（またはソース URL の文字どおりのファイル名）が明示されるため、サーバーなしで file:// から解決できます。
_meta.json サイドカー	移行された各ページの隣に配置されます。<dir>/index.html のサイドカーは <dir>/_meta.json、<dir>/<name>.html のサイドカーは <dir>/<name>._meta.json です。これにより、複数の .html ファイルが同じディレクトリにあっても衝突しません。reference/migration-procedure.md § _meta.json sidecar に従います。
stardust/migrated/index.html	ホームページ（特別なケース）です。
stardust/migrated/_meta.json	ホームページのサイドカーです。
stardust/migrated/assets/logo.<ext>	ブランドロゴ（サイト全体）です。
stardust/migrated/assets/<subpath>	移行されたページで参照されるすべてのアセットをバンドルします。ソースのサブディレクトリ構造はそのまま保持されます。
stardust/migrated/assets/favicon.<ext> + variants	ファビコン、apple-touch-icon、マニフェストアイコンです。
stardust/migrated/assets/fonts/...	ダウンロードされたフォントファイル（正規の @font-face URL から）です。
stardust/migrated/robots.txt	最小限の robots.txt です。
stardust/migrated/sitemap.xml	移行されたインベントリとページタイプから生成されたサイトマップです。
stardust/state.json	migrated ステータス、履歴、および migrate ブロック（selfContained: true、アセット数）で更新されます。

ドライバー（node stardust/scripts/migrate/migrate.mjs render …）は、 上記のページごとのファイル（index.html / <name>.html、_meta.json、 バンドルされた assets/**）と、state.json の migrate ブロック（pageMap[]、 bundledAssets[]、pages[]、missingAssets[]、lastRun）を書き込みます。 ステータスの変更、robots.txt、sitemap.xml はフェーズ 3〜4 で処理します。

冪等性と増分処理

パイプライン全体は、次の 2 つの特性を中心に構築されています。

• 冪等性。 変更なしで $stardust migrate を再実行すると、 ファイルへの書き込みはゼロになります。各ページについて、 designMd、designJson、sourceCurrent、sourceProposed （パス A）、canonShas、archetypeSource（パス A′）を対象に SHA を比較し、 すべて一致した場合はスキップします。
• 増分処理。 今日 5 ページ、明日 20 ページを移行し、 来週 1 ページのコンテンツを修正しても、移行済みツリーには、 これまでに正常に移行されたすべてのページが常に含まれます。

この特性は、実行中に DESIGN.md、canon、またはモジュールが編集された場合でも維持されます。編集によって該当する SHA が変わるため、次回の migrate 実行時に、影響を受けるすべてのページが再レンダリングされます（canon と DESIGN.md の編集は、通常すべてのページに影響します）。

古い状態への対応

一部のページを移行した後で direction.md、カノン、またはモジュールカタログが変更された場合：

• 影響を受けるページには、skills/stardust/reference/state-machine.md § 古い状態のフラグ付けに従って stale: true のフラグが付けられます。古い状態のフラグ付けは、3つのトリガーケースすべてでコンテンツを考慮します。
• $stardust migrate（フラグなし）は古いページをスキップし、その件数を報告します。
• $stardust migrate --all は古いページをそれぞれ再移行し、成功するとフラグを解除します。
• $stardust migrate <slug> は、指定されたページが古いかどうかにかかわらず、常に処理します。

古いページを更新するかどうかはユーザーが決定します。direction／カノン／モジュールの変更によって、以前に移行した成果が無効になるわけではなく、変更内容と整合しなくなったことを示すだけです。

失敗時の動作

• direction 済みのページがありません。 $stardust direct（抽出済み状態がない場合は $stardust extract）を推奨します。
• DESIGN.md または DESIGN.json がありません。 $stardust direct を推奨します。
• カノンはありませんが、承認済みのプロトタイプがあります。 停止しないでください。カノン作成者のインラインからカノンを自動的にブートストラップします（Setup の手順 4）。
• カノンも承認済みのプロトタイプもありません。 $stardust prepare-migration を推奨します（または、先にプロトタイプを承認します）。
• direction が未確定です。 拒否します。ユーザーは先に direction を解決する必要があります。
• 単一ページの検証に失敗しました。 そのページをスキップして続行し、失敗を state.json.lastRun.failures[] に記録します。実行全体を中断しないでください。
• アセットのコピーに失敗しました。 実行を続行し、欠落したアセットをページの migrationDecisions[] に kind: "asset-missing" として記録します。移行後の <img src> には、フォールバックとして元の絶対 URL が保持されます。
• 出力パスが衝突しました。 2つのスラッグが同じ出力パスに対応しています。2つ目の書き込みを拒否し、ユーザーに通知します。スラッグを手動で変更する必要があります。
• 提案ファイル／アーキタイプファイルにプレースホルダーのコンテンツがあります。 拒否します（Phase 2 のプレースホルダーゲート）。出典のない項目をユーザーに提示し、実際のコンテンツの調達を推奨します（プロトタイプを再作成するか、提案ファイルを直接編集します）。
• 色の予約ルールに違反しています。 ページを拒否し、違反した色と予約対象のコンテキストをユーザーに提示します。
• ブランドに忠実な反転との競合があります。 extensions.divergence.brand_faithful_inversions[] で反転が宣言されたハードルールは、T&M § ブランドに忠実な反転の処理に従って検証対象から除外されます。除外したことを示す1行の注記を実行概要に出力します。

migrate が行わないこと

• 移行後の出力を批評または監査すること。品質評価が必要な場合は、移行後に $impeccable critique stardust/migrated/ を実行してください。
• デプロイ。Stardust はオリジンへのプッシュ、アップロード、変更を行いません。
• AEM EDS、CMS ペイロード、またはフレームワークコンポーネントの生成。出力はプラットフォームに依存しない静的 HTML です。後続の変換は別のプラグインが行います。
• ライブサイトの再取得。extract の Phase 1 以降はオフラインです。
• 反復ループの実行。反復は prototype の役割です。migrate はその結果を使用します。

参考資料

• reference/migration-procedure.md — ページ単位のレンダリング手順、 出力パスのマッピング、検証、プロベナンスの形式、冪等な スキップ、サイドカーのスキーマ。
• reference/template-and-module-rendering.md — 3 つのレンダリング 分岐の詳細、スロットへの挿入、逸脱ポリシー、 検証の契約。
• reference/metadata-and-jsonld.md — head の構成、ページタイプごとの JSON-LD、 canonical の方針。
• reference/content-preservation.md — 保持、変換、削除する内容、 内部リンクの書き換え、アセットパスの書き換え、 フォームの処理。
• reference/asset-bundling.md — ページ単位のアセットバンドルフェーズにおける 検出／コピー／書き換えの契約。
• skills/stardust/reference/migrate-output-format.md — 下流の利用側が依存できる 自己完結型バンドルの契約（アセット参照の形式、ディレクトリ構成、 state.json.migrate ブロック）。
• skills/stardust/reference/token-contract.md — レンダリングのたびに DESIGN.md から更新される :root ブロック。
• skills/stardust/reference/data-attributes.md — data-template、data-module、 data-slot、data-canon、data-deviation、data-bespoke、 data-broken-link などの構造属性。
• skills/stardust/reference/state-machine.md — ページのライフサイクル、 ページの型判定、stale フラグ付けの連鎖。
• skills/stardust/reference/artifact-map.md — 移行されたアーティファクトのプロベナンスの形式、 canon ファイル、サイドカーの形式。
• skills/prototype/reference/canon-extraction.md — canon の構築方法（migrate への入力）。
• skills/prepare-migration/SKILL.md — migrate が使用するすべての入力を 生成する連鎖。