migrate

stardust:migrate

将 direct 编写的目标规范、prototype --prep 撰写的视觉规范，以及 prepare-migration 提取的品牌模块目录应用到清单中的每个页面。生成独立、可部署的静态 HTML 网站，存放于 stardust/migrated/。按页面执行、增量处理且幂等。

migrate 是 stardust 的最后一个阶段。输出为与平台无关的 HTML——后续转换（AEM EDS、CMS、框架）由单独的插件负责，该插件会使用 migrated/、DESIGN.json 和每页的 _meta.json 附属文件。

输入

• <slug> — 可选的位置参数。仅迁移此页面。若未提供，则迁移状态为 directed、prototyped 或 approved（且非 stale）的所有页面。
• --all — 迁移所有页面，包括过时页面。
• --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 § 过时资源清理。
• --pin-timestamp <ISO8601> — 固定 migrate 来源记录的时间戳，以便在源文件没有更改时，重复运行生成字节完全相同的 HTML。默认使用当前系统时间，这适用于常规使用；CI 部署指纹识别可能需要固定时间戳。

移动端适配审计、内容来源扫描和占位内容拒绝都是强制门控——没有 --skip-* 或 --allow-* 标志可以绕过它们。如果某个门控拒绝了页面，补救方法是修复拟议文件（重新进行原型设计、内联编辑或运行无可挑剔的命令），然后重新调用 migrate。

设置

0. 重新探测 Playwright（必须先执行）。 后续阶段中使用 --no-save 安装的 Playwright 会被之后任何一次实际的 npm i 清除（extract SKILL.md § 设置 → --no-save 安装是临时的）。执行任何渲染步骤前，请从项目根目录运行探测命令 node -e "import('playwright').then(()=>process.exit(0))"；若失败，则重新安装（npm i -D playwright --no-save --legacy-peer-deps）。

1. 运行主技能的设置流程（skills/stardust/SKILL.md § 设置）。流程守卫。 如果 stardust/state.json 存在但没有 flow，且请求是迁移（包含 URL 以及“migrate” / “to EDS” / “re-platform”），则不要运行：打印主技能 § 两种迁移流程中的表格，并交回其路由流程——在任何子技能运行前，必须在那里选择并写入流程（skills/stardust/reference/state-machine.md § Flow keys）：除非请求明确提到重新设计，否则选择 replica。 （记录：将 migrate <url> 作为两次同设计迁移的首条命令，导致手工构建了一个凭目测调整的编译器，而没有经过 replica 门控。）

2. 确认 stardust/state.json 存在，且至少有一个 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（在 6 个端到端测试站点中，有 4 个出现了这种情况；每次都必须手动推导 canon 才能继续——此修复正是为此而设）。当 canon 缺失 且 至少有一个 approved 原型时，不要停止：按照 ../prototype/reference/canon-extraction.md § Five-step procedure，从第一个已批准原型（canon 编写者，默认是 home）内联执行 canon 回写——提取 header.html / footer.html / canon.css 到 stardust/canon/，将 token 和组合方式固定到 DESIGN.json.extensions.canon，并记录 canon.source: "auto-bootstrap: <slug>"。这正是 prototype --prep 首次批准时执行的操作；migrate 会按需执行，以确保核心流程不会陷入死路。只有当 canon 缺失 且 没有已批准原型（没有可用于推导 canon 的内容）时，才停止并建议运行 $stardust prepare-migration。在 state.json.handsOff 模式下，此引导会自动执行并记录；交互模式下，继续之前先用一行提示说明。

5. 验证 stardust/direction.md 中有一个处于生效状态（而非待定）的方向。

6. 读取 state.json.pages[] 并划分为：

   • inScope：状态为 directed、prototyped 或 approved，stale: false（或使用 --all / 显式指定 <slug>）。
   • skipped：其他所有页面，并记录原因。

7. 验证每个范围内页面的来源信息。 按照 skills/stardust/reference/state-machine.md § Provenance validation，对 inScope 中的每个页面调用 validateProvenance(page)。如果任何页面缺少实时渲染证据，则使用该辅助函数的错误中止——迁移合成的页面记录会生成可部署的 HTML，却无法准确呈现源站点；这正是验证器旨在防止的失败模式。在 migrate 计划输出中、Phase 1 之前显示 Provenance OK on N pages。

8. 对每个 Path A / Path A′ 来源执行移动端适配审查。 对渲染分支使用拟定 HTML 文件或原型 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: ...) 规则。
   • 至少有一个面向移动端、断点不高于 640px 的规则。

   拒绝未通过审查的页面——此审查为必需步骤，没有跳过标志。用户修复拟定文件（重新制作原型，或使用由聊天驱动的 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 — 已记录的残余项视为带星号的通过）。未经过关卡检查的原型，或达到门槛但没有残余项记录的原型，都会阻止其页面类型：报告原型 slug 和 $stardust replica <archetype>，且不渲染该类型的任何页面。同一规则也适用于 rollout Setup；已发布来源的重新关卡检查规则不变。阈值以关卡设定为准。

范围较大时，打印计划并等待确认：

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 流程中，只有当 sibling 的原型已部署并在已发布来源通过关卡检查后，才能进行渲染（../replica/reference/handoff-contract.md § 3 row C，单元 C-archetype；#126）；渲染结果是编码器的输入，其关卡检查结果是 PUT 后的下一行。对于范围内的每个页面，请遵循 reference/migration-procedure.md 和 reference/template-and-module-rendering.md：

• 先进行幂等性跳过检查（对比 designMd、designJson、sourceCurrent、sourceProposed、canonShas、archetypeSource 的哈希）。
• 占位符门禁（仅适用于路径 A 和路径 A′——存在提议文件或原型的页面）。若存在 [data-placeholder] 元素或非空的 _provenance.unsourcedContent[]，则拒绝处理——用户需先在提议文件中补齐缺失内容，再次调用 migrate。没有绕过标志：此门禁旨在防止将占位符发布到公共网站。Widget 挂载点是链接（a[data-widget]），而非 data-placeholder，因此不会触发此门禁。
• 选择渲染分支（依据 T&M § 渲染路径选择进行 LLM 判断）：A / A′ / B。根据分支声明页面的 fidelityTier——A → archetype（需通过工艺门禁），A′ → sibling（规范分叉，是以低成本覆盖更多页面的默认选项——克隆前对每个模板执行一次方差探测，参见 reference/fidelity-tiers.md § 同级页面方差探测；差异转为变体类，绝不按页面分叉），B/无正文 → thin——参见 reference/fidelity-tiers.md。在 _meta.json 中记录 fidelityTier、archetypeSource、template（原型的 slug；原型自身的 sidecar 将其留空）、modules[]（页面的区块 ID——仅复合区段）、widgets[]（从页面的 a[data-widget] 挂载点派生）和 gatesPassed[]，以便覆盖情况能够显示哪些页面通过工艺门禁、哪些由克隆生成，并让发布分组和去重依据 sidecar 完成，无需普查。
• 按所选分支在 T&M 中规定的流程进行渲染。
• 应用规范——注入 chrome、注入 canon.css、记录偏差。
• 渲染模块——通过 stardust/canon/modules/<id>.html 渲染模块实例；使用 data-bespoke 标记并记录定制插槽。
• 按照 reference/content-preservation.md 应用内容保留规则。 内部链接重写后始终指向迁移后目录中的路径；缺失的 slug 标记为失效。
• **按 reference/fidelity-tiers.md § 内容计数验收进行内容计数验收：**比较源页面捕获 JSON 与渲染结果中按角色分类的节点数量（标题、正文/列表节点、CTA、图片）。任何类别的计数减少，若无对应的 contentDeviations[] 记录，页面即验收失败——导入器丢失内容的缺陷必须在此处暴露，此时修复导入器的成本仍较低，而不是等到下游保真度门禁才发现。在 _meta.json#gatesPassed[] 中将通过结果记录为 "content-count"。
• 按 reference/metadata-and-jsonld.md 编排 <head> 元数据（五个类别；由页面类型驱动的 JSON-LD）。
• 按 T&M § 验证契约进行验证。 严格契约会拒绝页面；软性契约会记录问题并继续。
• 按 migration-procedure.md § 输出路径映射计算输出路径。
• 资源打包。 扫描最终 HTML，查找资源引用（reference/asset-bundling.md § 检测中列出的六种检测形式），将每个唯一引用的子路径从 stardust/current/assets/<subpath> 复制到 stardust/migrated/assets/<subpath>（保留子目录结构），然后将所有引用重写为根相对形式 /assets/<subpath>。跨页面去重使用模块级 Set，并以 state.json.migrate.bundledAssets[] 初始化。缺失的源资源按 § 边缘情况发出警告并跳过；打包结果仍保持内部一致。
• 媒体协调。 对于每张未打包到同源的图片（Mode A 图片复用下重复使用的源 CDN URL），按 reference/media-reconciliation.md 决定优化/保留/重写/省略。作为源 URL 保留的跨域 <img> 必须跳过 createOptimizedPicture（它会移除 ?v= 键并破坏衍生图）；失效 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 sidecar。将来源信息块作为 <head> 的第一个子元素。在 _meta.json 中记录 assetsBundled（此页面上唯一资源引用的数量）。 此阶段的机制由脚本执行： node skills/migrate/scripts/migrate.mjs render <slug…|--all>（项目副本从 stardust/scripts/migrate/ 运行）会构建页面映射，将每个页面放置在其 URL 字面路径下，重写内部链接，打包资源，组合 <head>（来源信息、:root、规范链接和 JSON-LD 默认值），严格验证并写入 sidecar；输入 SHA 未变化的页面会跳过。脚本无法做出的判断会记录在 sidecar 上，使用同一脚本中的 gate、deviation、decision、variant 和 modules；它绝不会推进 pages[].status。

记录单元。 全站渲染会在 stardust/migrate/progress.json 中按单元记账，格式与 rollout 的 C-deliver 单元账本一致（../replica/reference/handoff-contract.md § 3 row C）： units.<name>: {status: pending|running|done|failed, kind: plan|render|assets|report, templates[], pages: n, startedAt, endedAt, verdict}。包含一个 plan 单元（阶段 1）、每个最多约有 8 个同级页面的模板集群对应一个 render 单元（migrate.mjs render <slug…> 接收该集群的 slug 列表）、一个在阶段 3 重新托管媒体时使用的 assets 单元，以及一个 report 单元（阶段 4）。每个单元都按此顺序执行：写入 progress.json → 提交检查点 → 下一个单元；单元结束是安全的恢复点，不是停止点。在 migrate 内恢复的会话会读取该文件，只运行尚未 done 的单元；遗留为 running 的单元会重新渲染其 slug——驱动程序具有幂等性，未变化的页面会跳过。有一次记录在案的运行通过五个并行构建器，在一个会话中将 31 个同级页面作为一个单元完成渲染——这是开销最大的一次——从计划阶段到最终报告之间没有恢复点。

阶段 3 — 全站资源与打包最终定稿

每页的资源打包已在阶段 2 完成（所有引用的媒体子路径都已写入 stardust/migrated/assets/）。阶段 3 会补齐没有任何单个页面明确引用的全站资源：

1. 将 stardust/current/assets/logo.<ext> 复制到 stardust/migrated/assets/logo.<ext>（仅在文件缺失或过期时）。记录到 state.json.migrate.bundledAssets[]。

2. 验证 favicon 变体和字体文件已由 prepare-migration 阶段 4 生成。如果缺失，记录警告并 继续（迁移后的网站仍可正常渲染，只是缺少一些特定平台的功能）。

3. 根据迁移后的页面清单，添加 stardust/migrated/robots.txt 和 sitemap.xml，具体参见 reference/metadata-and-jsonld.md § Sitemap 条目。

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://、在 Web 服务器根目录下以及任意子路径下运行——“一种形态，处处可用”。运行所有审计；任何非空的 grep 输出或非零的 fixture 退出码都会使本次运行失败，并给出引用的错误消息：

   # 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"
   

   审计是强制的——没有跳过选项。契约要求“自包含、可打包部署”，这些审计就是支撑这一声明的验证程序。

资源迁移具有幂等性——文件会进行内容哈希，仅在缺失时复制；每页打包会在整个运行过程中去重。

阶段 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）。该包采用压缩后部署方式：可将其放到任意静态主机的任意路径下，或直接通过 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	Favicon、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 处理。

幂等与增量

整个流水线围绕两项特性构建：

• 幂等。 在没有任何更改的情况下重新运行 $stardust migrate， 不会写入任何文件。系统会对比每个页面的 sha，包括 designMd、designJson、sourceCurrent、sourceProposed （路径 A）、canonShas、archetypeSource（路径 A′）——如果全部匹配， 则跳过该页面。
• 增量。 今天迁移 5 个页面，明天迁移 20 个页面， 下周修复一个页面的内容——迁移后的目录树始终是截至目前所有成功迁移结果的并集。

即使在运行期间编辑 DESIGN.md、canon 或模块，这些特性依然成立：编辑会改变相关 sha，因此下一次 migrate 运行会重新渲染所有受影响的页面（编辑 canon 和 DESIGN.md 通常会影响每个页面）。

陈旧处理

在部分页面完成迁移后，如果 direction.md、规范或模块目录发生变化：

• 受影响的页面会根据 skills/stardust/reference/state-machine.md § Stale flagging 标记为 stale: true。 在这三种触发情况下，陈旧标记都会考虑内容。
• $stardust migrate（不带标志）会跳过陈旧页面并报告数量。
• $stardust migrate --all 会重新迁移每个陈旧页面，成功后清除标记。
• $stardust migrate <slug> 始终处理指定页面，无论其是否陈旧。

由用户决定是否刷新陈旧页面——方向、规范或模块变更不会使之前迁移的工作失效，只会将其标记为不一致。

失败情况

• 没有已确定方向的页面。 建议运行 $stardust direct（如果没有已提取状态，则运行 $stardust extract）。
• 没有 DESIGN.md 或 DESIGN.json。 建议运行 $stardust direct。
• 没有规范，但存在已批准的原型。 不要停止——从规范作者内联内容自动引导生成规范（Setup 步骤 4）。
• 没有规范，也没有已批准的原型。 建议运行 $stardust prepare-migration（或先批准一个原型）。
• 方向待定。 拒绝执行；用户必须先解决方向问题。
• 单个页面验证失败。 跳过该页面，继续处理，并将失败记录在 state.json.lastRun.failures[] 下。不要中止整个运行。
• 资源复制失败。 继续运行；在页面的 migrationDecisions[] 中记录缺失资源，设为 kind: "asset-missing"。迁移后的 <img src> 会保留原始绝对 URL 作为回退。
• 输出路径冲突。 两个 slug 映射到同一个输出路径。拒绝写入第二个页面并告知用户——需要手动重命名 slug。
• 提议文件／原型文件中含有占位内容。 拒绝执行（Phase 2 占位内容检查）；向用户列出未注明来源的内容，并建议提供真实内容来源（重新制作原型，或直接编辑提议文件）。
• 违反颜色保留规则。 拒绝处理该页面；向用户指出冲突颜色及其保留用途。
• 与品牌忠实反转规则冲突。 根据 T&M § Brand-faithful inversion handling，在验证时豁免 extensions.divergence.brand_faithful_inversions[] 中声明为反转的硬性规则。在运行摘要中输出一行说明，确认已豁免该规则。

migrate 不会做什么

• 批评或审查迁移后的输出。如果想评估质量，请在迁移后运行 $impeccable critique stardust/migrated/。
• 部署。Stardust 不会推送、上传或修改源站。
• 生成 AEM EDS、CMS 载荷或框架组件。输出是与平台无关的静态 HTML；后续转换由单独的插件负责。
• 重新抓取线上网站。extract 的 Phase 1 之后会离线运行。
• 执行任何迭代循环。迭代属于 prototype；migrate 会使用其结果。

参考资料

• reference/migration-procedure.md — 逐页渲染流程、 输出路径映射、验证、溯源结构、幂等跳过机制、 sidecar 架构。
• reference/template-and-module-rendering.md — 详细介绍三种渲染 分支、插槽注入、偏差策略、 验证约定。
• 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 — 页面生命周期、 页面类型判定、过时标记级联。
• skills/stardust/reference/artifact-map.md — 迁移产物的溯源结构；canon 文件； sidecar 结构。
• skills/prototype/reference/canon-extraction.md — canon 的构建方式（migrate 的 输入）。
• skills/prepare-migration/SKILL.md — 生成 migrate 所用全部输入的级联流程。