prepare-migration

stardust:prepare-migration

migrate-prep カスケードを実行します。ユーザーが既存サイトの移行を決めると、このスキルは上流のフェーズ（extract、direct、prototype）を --prep モードで実行し、各ステップで確認ゲートを設けて、推定されたカタログをユーザーが確認または調整できるようにします。

prepare-migration は薄いオーケストレーターです。基盤となるスキルのロジックを重複させず、それらを呼び出して、フェーズごとの概要を仲介します。実質的な作業は以下にあります。

• skills/extract/SKILL.md § Prep mode
• skills/direct/SKILL.md § Prep mode
• skills/prototype/SKILL.md § Prep mode + reference/canon-extraction.md

準備が完了したら、ユーザーは別途 $stardust migrate を実行します。この2段階の境界（prepare-migration の後に migrate）は意図的なものです。「このサイトの移行を実行する」と決断する機会を明確にし、べき等性を分かりやすく保ちます。

入力

• --from <phase> — 任意。指定したフェーズからカスケードを再開します。値：extract | direct | prototype | assets | dynamics。デフォルトでは、未完了のうち最も早いフェーズから開始します。
• --skip-confirm — 任意。フェーズごとの確認ゲートをスキップします。カタログがすでに確定している場合の再実行に便利です。デフォルトでは、すべてのフェーズ境界に確認ゲートを設けます。ハンズオフモード（skills/stardust/SKILL.md § Hands-off mode、つまり state.json.handsOff: true）では --skip-confirm が自動的に適用されます。
• --canon-from <slug> — 任意。このフェーズの実行時に prototype --prep --canon-from <slug> に引き渡します。デフォルトのカノン作成者（home）を上書きします。
• --refine-module <module-id> — 任意。1つのモジュールについて、フェーズ2のモジュールカタログ手順を再度実行します。これは migrate の「特注スロットが昇格のしきい値に達しました」というヒントの対象です。繰り返し使われている特注スロットを、そのモジュールのスロットスキーマ（DESIGN.json.extensions.modules[]）に昇格させ、変更を確認用に提示してから停止します。カスケード全体は再実行しません。影響を受けるページには、skills/stardust/reference/state-machine.md に従い、コンテンツを考慮した古い状態のフラグが付けられます。

セットアップ

1. マスタースキルのセットアップ（skills/stardust/SKILL.md § Setup）を実行します — 依存関係チェック、コンテキストローダー、状態の読み込みを完璧に行います。 フローガード。 これは再設計フローのオーケストレーターです。state.json.flow が replica の場合は拒否し、「prepare-migration を replica の前後に実行しないでください」と切り替えコマンド（$stardust prepare-migration --switch-flow。レプリカのアーティファクトを古い状態としてマークします — マスタースキル § Two migration flows）を表示します。 flow がない場合は、まず解決します。明示的な再設計の表現（「redesign」、「modernise」、「refresh」、「new look」）がある場合に限り、このスキルを選択し、flow: "redesign" を記録します （skills/stardust/reference/state-machine.md § Flow keys）。それ以外の移行の依頼、デザイン維持を示す表現、または単なる「migrate」の場合、このスキルは適用されないことを伝え、replica に引き継ぎます。

2. stardust/state.json が存在し、少なくとも1ページが抽出済みであることを確認します。そうでなければ、$stardust extract <url> を推奨して終了します。

3. stardust/direction.md が存在し、有効な方向性が記載されていることを確認します。そうでなければ、$stardust direct を推奨して終了します。

4. プロジェクトの状態を調べ、完了済みのフェーズを特定します。

   • extract：すべてのページで state.json の type が null 以外であり、current/pages/<slug>.json に slots ブロックがあること。
   • direct：DESIGN.json.extensions.modules[] のすべてのエントリで status: confirmed となっており、colorReservations と metadata のブロックがあること。
   • prototype：各ページタイプに承認済みのアーキタイプが少なくとも1つあり、stardust/canon/ にデータがあり、DESIGN.json.extensions.canon にデータがあること。
   • assets：stardust/migrated/assets/ にファビコンの各種バリエーションがあり、フォントがダウンロード済みであること。
   • dynamics：stardust/dynamic-features.md が存在し、すべての行に処置が記載されていること。インデックスに基づく一覧がある場合は helix-query.yaml が存在すること（ない場合はフェーズ4.5で「none」を記録します）。

   --from による上書きがない限り、最も早い未完了フェーズから再開します。

手順

カスケードは5つのフェーズを順番に実行します。各フェーズでは、ハーネスのスキル呼び出しツールを使って基盤となるスキルを呼び出し（サブスキルの指定方法については、マスタースキル § Routing を参照）、そのフェーズの準備サマリーを提示してから、ユーザーの確認を待って次に進みます（--skip-confirm またはハンズオフモードの場合を除きます）。

フェーズ1 — extract --prep

stardust の extract スキルを引数 --prep で呼び出します。 Claude Code 形式：Skill { skill: "stardust:extract", args: "--prep" }。

基盤となるスキルは、5つの --prep オーバーレイ（上限の引き上げ、ページの分類、モジュール候補、型付きスロット、準備サマリー）を適用して、標準の抽出手順を実行します。

完了したら、サマリーをそのまま提示し、フローの名前を明示してから、確認を求めます — カスケード最初の対話型ゲートでは、維持するか再設計するかの選択肢を示します（ある移行では、このカスケードを3.5時間実行した後、ユーザーがデザイン維持フローを希望したため、作業が破棄されました）。

Flow: redesign — the design changes while migrating. Say `switch to replica` now if it is to be kept.
Confirm and continue? (yes / refine "<phrase>" / switch to replica)

ユーザーの選択肢：

• yes — フェーズ2に進みます。
• switch to replica — デザインを維持します。このカスケードを停止し、$stardust replica <url> --switch-flow を実行します（マスタースキル § Two migration flows）。ここで生成された抽出結果は replica のフェーズ1で再利用されます。それ以外のこのフローの成果物は再利用されません。
• refine "<phrase>" — 修正内容を指定して extract --prep を再度呼び出します（例：「news/* のスラッグを記事ではなく一覧として分類する」、「/search と /404 をインベントリから除外する」）。サマリーを再提示し、繰り返します。

Provenance guard (Phase 1 と Phase 2 の間)

direct --prep を実行する前に、skills/stardust/reference/state-machine.md § Provenance validation に従って validateProvenance(page) を使い、インベントリ内のすべてのページを検証します。ライブレンダリングの証拠がないページが1つでもある場合は、ヘルパーのエラーを返してカスケードを中止します。これは、extract --prep（または委任されたサブエージェント）が1つ以上のページレコードを暗黙に合成してしまうという障害モードに対する、カスケードレベルの防御です。extract の書き込み時の拒否が主なガードですが、カスケードではフェーズ間に2つ目のチェックを追加し、異なる理由で合成バグが再発しても、残りの実行がひそかに汚染されないようにします。

同じガードは Phase 2、3、4 の内部でも暗黙に実行されます（各基盤スキルのセットアップで、それぞれの SKILL.md に従って validateProvenance() が呼び出されます）。ただし、これを明示的なカスケードの手順としてここに示すことで、そうしなければ実行が成功したように見える Phase 2 の準備サマリーをユーザーが目にする前に、中止できます。

カスケードの出力に表示します：

Provenance OK on 127 pages.

チェックに失敗した場合：

Provenance check failed on 20 of 127 pages — see error above.
Cascade aborted between Phase 1 and Phase 2.
   → Re-run extract for the affected slugs:
       $stardust extract --refresh <slug-1>
       $stardust extract --refresh <slug-2>
       ...

Phase 2 — direct --prep

stardust の direct スキルを引数 --prep で実行します。 Claude Code 形式：Skill { skill: "stardust:direct", args: "--prep" }。

基盤スキルでは、5つの --prep オーバーレイ（タイプカタログの確認、モジュールカタログの最終確定、色の予約、方向性の再評価、ブランドメタデータのデフォルト値設定）を実行します。

サマリーと承認ゲートを表示します。ユーザーの選択肢は Phase 1 と同じです（yes / refine "<phrase>"）。

Phase 3 — prototype --prep

stardust の prototype スキルを引数 --prep で実行します。カノンスラッグがすでにわかっている場合は、さらに --canon-from <slug> を指定します。 Claude Code 形式：Skill { skill: "stardust:prototype", args: "--prep --canon-from <slug>" }。

基盤スキルは、ページタイプの不足を補い（タイプごとに承認済みのアーキタイプを1つ作成）、skills/prototype/reference/canon-extraction.md に従ってカノンに書き戻します。最初の承認でカノンが確立され、その後の承認で拡張されます（競合はデフォルトで逸脱として記録されます）。

通常、このフェーズが最も時間がかかります。各アーキタイプでプロトタイプの全工程（形状ブリーフ、作成、ブラウザーで開く、反復、承認）を実行します。各アーキタイプが完成するたびに、進捗をユーザーに伝えます。

サマリーと承認ゲートを表示します。

Phase 4 — assets prep

移行先サイトに必要なアセットのバリエーションを生成またはダウンロードします。このフェーズには基盤となる SKILL はなく、小規模な画像処理とダウンロードのルーチンを実行します。

1. ファビコンのバリエーション。 正規のファビコン stardust/current/assets/favicon.<ext> から、次を生成します：

   • stardust/migrated/assets/favicon-512.png
   • stardust/migrated/assets/apple-touch-icon.png (180×180)
   • stardust/migrated/assets/icon-192.png、 icon-512.png (マニフェストのサイズ)

2. フォントのダウンロード。 stardust/canon/canon.css（および stardust/canon/header.html / footer.html）をスキャンし、外部URLを含む @font-face ルールを探します。それぞれについて：

   • ファイルを stardust/migrated/assets/fonts/<basename-with-hash>.<ext> にダウンロードします。
   • canon ファイル内の @font-face の url(...) 参照をローカルパスに書き換えます。
   • すでにダウンロード済みの場合はスキップします（shaを比較）。
   • ダウンロードに失敗した場合は警告を記録します（フォントは外部URLのままにし、migrate はページごとに metadata-override 警告を記録します）。

3. ブランドアセットの監査。 ロゴ、ファビコン、および canon のモジュールレンダリングから参照されるメディアファイルが stardust/current/assets/ に存在することを確認します。不足しているアセットはユーザーに提示します。

サマリーと承認ゲートを表示します：

assets prep complete
====================

Favicon variants:    favicon-512.png, apple-touch-icon.png, icon-192.png, icon-512.png
Font downloads:      4 files (HarmoniaSans 4 weights)
Brand assets:        all present

Phase 4.5 — 動的サーフェス（インポート前ゲート：dynamics Phase 1〜3）

アセットの準備後、一括インポートの前に実行します。移行に不可欠な工程です。 このステップにより、動的なサイトが静的サイトとしてインポートされるのを防ぎます。 skills/dynamics/SKILL.md に委任します。

1. 検出 — Phase 1 で実行していない場合は extract --dynamics を再実行して （到達範囲を取得）、続いて dynamics-detect.mjs --from-state stardust/state.json --reach stardust/current を実行します（アーキタイプの深度を取得します）。
2. 分類とトリアージ — dynamics-plan.mjs [--target-origin <host>] で各行の4つの軸のドラフトを作成します。内容を stardust/dynamic-features.md（§ Listings contract with helix-query.yaml、§ Features、§ Decision batch、§ Register）と stardust/dynamic-features-plan.md にまとめます。
3. ゲート — すべての行に処置が定まっていれば合格です。両セクションで 「none」とすることも有効な合格です。このゲートが静的パスをブロックすることは ありません。サイレントな後退を防ぎます。

サマリー行：dynamic surface: N findings · self K · owner batch M · host-bound H · listings L dynamic / S static。契約： skills/dynamics/reference/triage.md。

最終レポート

prepare-migration complete
==========================

Phase 1 (extract --prep):      127 pages, 7 types, 8 module candidates
Phase 2 (direct --prep):       types & modules confirmed; metadata set
Phase 3 (prototype --prep):    6 archetypes approved; canon written
Phase 4 (assets prep):         favicon variants + fonts + brand assets ready
Phase 4.5 (dynamic surface):   14 findings · self 6 · owner batch 7 · host-bound 1 · listings 3 index-backed / 1 static

Next: $stardust migrate

出力

prepare-migration 自体は何も書き込みません。すべての成果物は、基盤となるスキル、 または Phase 4／4.5 の処理によって書き込まれます。 一連の処理の実行後、プロジェクトの状態には次のものが含まれます。

成果物	書き込んだ Phase
state.json.pages[].type	extract --prep
current/pages/<slug>.json § slots	extract --prep
DESIGN.json.extensions.modules[] (status: confirmed)	extract --prep + direct --prep
DESIGN.json.extensions.colorReservations[]	direct --prep
DESIGN.json.extensions.metadata	direct --prep
stardust/canon/ (header, footer, css, modules/)	prototype --prep
DESIGN.json.extensions.canon	prototype --prep
stardust/migrated/assets/favicon-*	assets prep
stardust/migrated/assets/fonts/	assets prep
stardust/dynamic-features.md + -plan.md (インベントリ、4つの軸、判断バッチ)	dynamics ゲート（Phase 4.5）
helix-query.yaml (対象を限定したインデックス、EDS プロジェクトルート)	dynamics ゲート（Phase 4.5）
stardust/state.json (ページごとのステータス更新)	各基盤フェーズ

失敗時の動作

• state.json がない、または抽出済みのページがない。
  $stardust extract <url> を推奨して終了します。
• 有効な方針がない。
  $stardust direct を推奨して終了します。
• ユーザーがフェーズを拒否する。
  一連の処理を正常に停止します。状態は整合性のある中間状態のまま残ります （基盤となるスキルの書き込みは反映済みです）。ユーザーは $stardust prepare-migration --from <phase> で再開できます。
• 基盤となるスキルが失敗する。
  失敗内容をそのまま提示し、先へ進みません。ユーザーが問題を修正して再実行します。
• canon の作成者ではないユーザーによる承認時に、Phase 3 で canon の競合が発生する。 reference/canon-extraction.md に従い、デフォルトでは競合を逸脱として記録します。 ユーザーが競合ごとの対応（canon に昇格／却下して反復／逸脱として記録）を希望する場合は、 実行時ではなく、そのフェーズの確認ゲートで提示します。将来的に --strict-canon フラグで競合する承認を拒否できるようにする可能性がありますが、 v0.2 には含まれません。
• Phase 4 でアセットのダウンロードに失敗する。
  実行を続行し、失敗を assets-prep のサマリーに記録します。後の migrate で 該当する各ページに警告を表示します。

並行処理

skills/stardust/reference/state-machine.md § 並行処理に従います。 state.json の書き込みはスラッグごとにマージされるため、カスケードによるページ単位の書き込みは、ほかの並行レーンと共存します。ただし、同じプロジェクトで prepare-migration を2つ同時に実行すると、同じトップレベル成果物（canon、モジュールカタログ）をめぐって競合します。この場合は警告が表示されますが、引き続き後勝ちとなり、canon が破損する可能性があります。カスケードを2つ同時に実行しないでください。ロックを設けて回避しようとする必要はありません。

冪等性

一部完了後に prepare-migration を再実行すると、最も早い未完了フェーズ（または明示的に指定した --from フェーズ）から再開します。各スキル自体も冪等です。すでに型付けされたページは再度型付けされず、確認済みのモジュールは再提案されず、承認済みのアーキタイプは再度プロトタイプ化されず、生成済みのファビコンのバリエーションは再生成されず、既存の dynamic-features.md は書き換えではなく調整されます。

すべて完了した後に再実行しても、入力に変更がない限り何も行われません（extract で新しいページが見つかった、direction が編集された、canon-author のプロトタイプが反復された、などの場合を除きます）。

参考資料

• skills/extract/SKILL.md § 準備モード
• skills/direct/SKILL.md § 準備モード
• skills/prototype/SKILL.md § 準備モード
• skills/prototype/reference/canon-extraction.md — 承認時に prototype --prep が実行する5段階の抽出手順
• skills/dynamics/SKILL.md + reference/triage.md、 reference/listings.md — フェーズ4.5はフェーズ1～3です
• skills/migrate/SKILL.md — このカスケードが準備するすべてのデータ構造を利用します
• skills/stardust/reference/state-machine.md — ページの型付け、古い状態のフラグ付けカスケード
• skills/stardust/reference/artifact-map.md — ファイル構造、DESIGN.json.extensions の形式