已有 DESIGN/canon/modules 与页面…

适用于原型已批准后、部署/上线前的整站页面渲染迁移，按页增量、幂等地生成自包含静态 HTML。

适用场景

解决思路

1. Setup 0：先做 Playwright 重新探测；在项目根运行 `node -e "import('playwright').then(()=>process.exit(0))"`，失败则用 `npm i -D playwright --no-save --legacy-peer-deps` 重装。
2. Setup 1：运行 master skill 的 setup；执行 flow guard——若 `stardust/state.json` 存在但没有 `flow` 且请求是迁移（URL 加 migrate/to EDS/re-platform），不要运行，打印 master skill 的两流表并交还 routing；hands-off 时按 master 默认（keep-design 短语→replica，否则 redesign）并在 `direction.md` 记录。
3. Setup 2：验证 `stardust/state.json` 存在且至少有一个 `directed` 页面。
4. Setup 3：验证项目根 `DESIGN.md` 与 `DESIGN.json` 存在，且 `DESIGN.json.extensions.canon` 已填充。
5. Setup 4：验证 `stardust/canon/` 存在且至少有 `header.html`、`footer.html`、`canon.css`。
6. Setup 4（canon 自动 bootstrap）：当 steps 3–4 找不到 canon 且至少有一个 `approved` prototype 存在时，不要停止；从第一个 approved prototype（canon-author，默认 `home`）按 `../prototype/reference/canon-extraction.md` 的 Five-step procedure 内联执行 canon 写回：提取 `header.html`/`footer.html`/`canon.css` 到 `stardust/canon/`，把 tokens 与 compositional moves pin 到 `DESIGN.json.extensions.canon`，记录 `canon.source: "auto-bootstrap: <slug>"`；只有 canon 缺失且没有 approved prototype 时才停止并推荐 `$stardust prepare-migration`；handsOff 下自动记录，交互式先给一行提示。
7. Setup 5：验证 `stardust/direction.md` 有 active（非 pending）direction。
8. Setup 6：读取 `state.json.pages[]` 并分区：inScope 为 status `directed`、`prototyped` 或 `approved` 且 `stale: false`（或 `--all` / 显式 `<slug>`）；skipped 为其他所有并记录原因。
9. Setup 7：对每个 in-scope page 调用 `validateProvenance(page)`（按 `skills/stardust/reference/state-machine.md` § Provenance validation）；任何页面缺 live-render evidence 就按 helper 错误中止；在 Phase 1 前在 migrate-plan 输出中显示 `Provenance OK on N pages`。
10. Setup 8：对每个 Path A / Path A′ source 做 mobile-adapt audit：检查 `<meta name="viewport" content="width=device-width, ...">` 存在且 width 未固定为像素值；至少一个 `@media (max-width: ...)` 规则；至少一个 ≤ 640px 的 mobile-targeted breakpoint。失败页面拒绝；审计强制且无 skip flag；用户修 proposed file 后重新调用 migrate；把审计结果记录到 migrate report 与渲染后 `_meta.json#audit.adapt` sidecar；Path B（unique-renders）跳过审计，因为那些页面未跑 adapt；需要移动覆盖的 Path B 页面由用户另行调用 `$impeccable adapt`；在报告中说明此区别以免被读成静默跳过。
11. Phase 1（dynamic-surface precondition）：若 `stardust/dynamic-features.md` 缺失，说明 hand-run flow（`extract → direct → prototype → migrate`）从未过 pre-import gate；在渲染任何页前运行 stardust `dynamics` skill Phases 1–3（需要 reach 时 `extract --dynamics`、对 archetypes 跑 detector、triage draft、curate）；绝不在没有逐 dynamic row 决策时把站点作为 static import；每页 inventory 中触及它的 row 变成 `contentDeviations[]` 的 `kind: "dynamic-dependency"` 条目。
12. Phase 1（gated-archetype precondition，`flow: replica`）：渲染任何 `sibling`-tier 页面前，读 `stardust/replica/progress.json`；该页面类型的 archetype 必须在每个配置 breakpoint 有 gate result 且 `pass: true`，或 over the bar 且每个 residual 带 `cause`（按 `../replica/reference/source-fidelity-gate.md` § Residual logging format，有记录的 residual 算带星通过）；从未 gate 的 archetype，或 over the bar 但无 residual entries，阻止其页面类型：报告 archetype slug 和 `$stardust replica <archetype>`，该类型不渲染任何内容；同一规则保护 `rollout` Setup，published-origin re-gate 不变，阈值以 gate 为准。
13. Phase 1：打印 migrate plan（in scope 页数、Path A/A′/B 分组、skipped、DESIGN.md/DESIGN.json/canon shas、output、idempotent skip 状态）；scope 大时等待确认；1–3 页或 `<slug>` 调用跳过确认。
14. Phase 2（每页渲染）：先做 idempotent skip check（对 `designMd`、`designJson`、`sourceCurrent`、`sourceProposed`、`canonShas`、`archetypeSource` 做 sha 比较）。
15. Phase 2（placeholder gate）：Path A 与 Path A′ 页面（有 proposed file 或 archetype）中，若存在 `[data-placeholder]` 元素或非空 `_provenance.unsourcedContent[]`，拒绝；用户需先补内容再重调 migrate；无 bypass flag。
16. Phase 2（render branch selection）：按 T&M § Render path selection 用 LLM 判断选 A / A′ / B；从 branch 声明页面 `fidelityTier`：A→`archetype`（craft-gated），A′→`sibling`（canon-fork，breadth 的廉价默认；克隆前每模板做一次 variance-probed，按 `reference/fidelity-tiers.md` § Sibling variance probe；deltas 变成 variant classes，绝不做 per-page forks），B/bodyless→`thin`；在 `_meta.json` 记录 `fidelityTier`、`archetypeSource`、`gatesPassed[]` 以显示 coverage 中哪些是 craft-gated、哪些是 cloned。
17. Phase 2（render）：按所选 branch 在 T&M 中的 procedure 渲染。
18. Phase 2（canon application）：注入 chrome、注入 canon.css、记录 deviation。
19. Phase 2（module rendering）：通过 `stardust/canon/modules/<id>.html` 渲染 module 实例；bespoke slots 用 `data-bespoke` 记录。
20. Phase 2（内容保留）：按 `reference/content-preservation.md` 应用保留规则；内部链接重写始终输出 migrated-tree 路径；缺失 slug 标记 broken。
21. Phase 2（内容数量验收）：按 `reference/fidelity-tiers.md` § Content-count acceptance，比较 captured source page JSON 与渲染结果中 role-classified 节点数（headings、body/list nodes、CTAs、images）；任何类别数量下降且没有对应已记录 `contentDeviations[]` 条目则页面失败；通过后记录到 `_meta.json#gatesPassed[]` 为 `"content-count"`。
22. Phase 2（head 元数据）：按 `reference/metadata-and-jsonld.md` 组合 `<head>` 元数据（五类；page-type-driven JSON-LD）。
23. Phase 2（validation）：按 T&M § Validation contracts 验证；strict contracts 拒绝页面；soft contracts 记录并继续。
24. Phase 2（输出路径）：按 `reference/migration-procedure.md` § Output path mapping 计算输出路径。
25. Phase 2（资产打包）：扫描最终 HTML 的 asset references（六种 detection shapes per `reference/asset-bundling.md` § Detection）；把每个唯一引用 subpath 从 `stardust/current/assets/<subpath>` 复制到 `stardust/migrated/assets/<subpath>`（保留子目录结构）；把所有引用重写为 root-relative `/assets/<subpath>`；跨页去重用 module-level Set，初始来自 `state.json.migrate.bundledAssets[]`；缺失源资产 warn-and-skip，保持 bundle 内部一致。
26. Phase 2（媒体调和）：对每个未 bundled 到 same-origin 的图像（Mode A image-reuse 下复用的 source-CDN URL），按 `reference/media-reconciliation.md` 决定 optimize/keep/rewrite/omit；保留为 source URL 的 cross-origin `<img>` 必须跳过 `createOptimizedPicture`（它会丢掉 `?v=` key 并破坏 rendition）；坏 URL 修复（缺 `?`-delimiter、错 host）或 omit，绝不输出 `about:error`；`rollout` 在 delivery 时重跑权威 network resolve（`media-reconcile.mjs`）。
27. Phase 2（cinematic sibling）：若存在 `<slug>-cinematic.html`，migrate 只消费 STATIC prototype，绝不合并 cinematic layer；把 motion assets（`lenis.min.js`、`lenis.min.css`）从 `stardust/prototypes/` 复制到 `stardust/migrated/assets/motion/`（幂等）供下游消费；在页面 `_meta.json#migrationDecisions[]` 记录 `cinematic-variant-not-consumed`。
28. Phase 2（写盘）：在同一目录写迁移后的 `index.html` 与 `_meta.json` sidecar；provenance block 作为 `<head>` 第一个子节点；在 `_meta.json` 记录 `assetsBundled`（本页唯一资产引用数）。
29. Phase 3：补全站点级资产——复制 `stardust/current/assets/logo.<ext>` 到 `stardust/migrated/assets/logo.<ext>`（仅当缺失或 stale），记录到 `state.json.migrate.bundledAssets[]`；验证 `prepare-migration` Phase 4 生成的 favicon variants 与 font files，缺失则警告并继续；添加 `stardust/migrated/robots.txt` 和 `sitemap.xml`；若 `--clean`，计算 `stale = priorBundle.filter(p => !bundledAssets.has(p))` 并删除每个 stale subpath，记录 `state.json.migrate.cleanedAssets[]`。
30. Phase 3（portability 验证）：运行强制审计，任何非空 grep 输出或非零 fixture 退出都会以引用错误信息使运行失败：`find stardust/migrated/ -type f -name '*.html' -exec grep -l '../current/' {} +` 检查无 source-tree escapes；`grep -rE '(href|src)="/[^/]' stardust/migrated/ --include='*.html'` 检查属性值无绝对内部引用；用 `grep -rE` 对 `*.html` 与 `*.css` 检查 `url(` 后跟 `/` 的绝对内部引用；用 `grep -rE` 检查 directory-only nav（模式只接受 relative 或 root-absolute hrefs）；`node skills/migrate/fixtures/pagemap-audit.mjs stardust/migrated/ stardust/state.json` 检查 pageMap 一致性；`node skills/migrate/fixtures/file-protocol-audit.mjs stardust/migrated/` 做 headless file:// round-trip；审计强制，无 skip flag；契约是 self-contained、zip-and-deploy。
31. 资产迁移幂等：文件按内容哈希，只在缺失时复制；每次运行内每页打包会跨页去重。
32. Phase 4（状态更新）：成功迁移页 `status` 前进到 `migrated`、追加 history entry、清除 `stale`、设置 `migratedPath`；idempotent skip 的页面保持不变；validation 失败页保持不变并记录到 `state.json.lastRun.failures[]`。
33. Phase 4（写 migrate block）：按 `skills/stardust/reference/migrate-output-format.md` § State.json contract 写顶层 `migrate` block：`selfContained: true`、`outputDir`、`totalAssetsBundled`、`bundledAssets[]`、每页 `assetsBundled` 计数、`missingAssets[]`、`cleanedAssets[]`；这是下游消费者测试的 forward-compat 信号。
34. Phase 4（打印摘要）：打印 run summary，包括 migrated/unchanged/failed/stale skipped 数量，render branches 的 Path A/A′/B 计数，non-trivial decisions，broken internal links，crossing promotion threshold 的 bespoke slots 与建议 `$stardust prepare-migration --refine-module`，missing assets，输出目录与 self-contained zip-and-deploy 说明，以及 next steps（review/audit/deploy/refine）。
35. 输出位置：迁移页面写到 `stardust/migrated/<source-url-path>`；每页旁写 `_meta.json` sidecar（`<dir>/index.html` 对应 `<dir>/_meta.json`，`<dir>/<name>.html` 对应 `<dir>/<name>._meta.json`）；首页特殊为 `stardust/migrated/index.html` 与 `stardust/migrated/_meta.json`；站点资产写到 `stardust/migrated/assets/...`，包括 `logo.<ext>`、favicon variants、fonts、每个页面引用的资产；还要生成 `stardust/migrated/robots.txt`、`sitemap.xml`；更新 `stardust/state.json` 的 `migrated` 状态、history 和 `migrate` block。
36. 幂等与增量：无变化重跑 `$stardust migrate` 应零文件写入；每页对 `designMd`、`designJson`、`sourceCurrent`、`sourceProposed`（Path A）、`canonShas`、`archetypeSource`（Path A′）做 sha 比较，全匹配则跳过；今天迁移 5 页、明天 20 页、下周修一页，迁移树始终是迄今所有成功迁移的并集；即使 DESIGN.md/canon/modules 中途编辑，相关 sha 变化会让下次 migrate 重渲染受影响页（canon 和 DESIGN.md 编辑通常影响所有页）。
37. Stale 处理：当 `direction.md`、canon 或 module catalog 在部分页面迁移后变化，按 state-machine 标记受影响页面 `stale: true`（三类触发都内容感知）；`$stardust migrate` 默认跳过 stale 并报告数量；`$stardust migrate --all` 重新迁移每个 stale 页并在成功时清除标记；`$stardust migrate <slug>` 总是操作指定页，无论是否 stale；由用户决定是否刷新，变化只标记 out-of-step 不使先前迁移失效。
38. 失败模式：无 directed 页面时推荐 `$stardust direct`（若无 extracted state 则 `$stardust extract`）。
39. 失败模式：无 `DESIGN.md` 或 `DESIGN.json` 时推荐 `$stardust direct`。
40. 失败模式：无 canon 但有 approved prototype 时不要停止，按 Setup step 4 内联 auto-bootstrap canon。
41. 失败模式：无 canon 且无 approved prototype 时推荐 `$stardust prepare-migration`（或先 approve prototype）。
42. 失败模式：pending direction 时拒绝；用户必须先解决 direction。
43. 失败模式：单页 validation 失败时跳过该页继续，记录到 `state.json.lastRun.failures[]`；不要中止整次运行。
44. 失败模式：asset copy 失败时继续运行；在页面 `migrationDecisions[]` 记录 `kind: "asset-missing"`；迁移后的 `<img src>` 保留原始绝对 URL 作为 fallback。
45. 失败模式：output path collision 时，两个 slug 映射同一输出路径；拒绝写第二个并告知用户需要手动 slug rename。
46. 失败模式：proposed/archetype 文件中有 placeholder 时，拒绝发布含 `[data-placeholder]` 的页面；展示 unsourced list 并推荐来源真实内容；无 bypass flag。
47. 失败模式：color reservation violated 时拒绝页面；把 offending color 与 reserved-for context 告知用户。
48. 失败模式：brand-faithful inversion conflict 时，`extensions.divergence.brand_faithful_inversions[]` 中声明为 inverted 的 hard rule 从 validation 中 lift；在运行摘要中一行说明该 lift。

适用边界 · 注意事项

• 不要用它做迁移输出的 critique/audit；需要质量评估应运行 `$impeccable critique stardust/migrated/`。
• 不要用它部署、push、upload 或修改 origin；也不要指望它生成 AEM EDS、CMS payload 或 framework components——输出只是平台无关静态 HTML，下游转换是独立插件的工作。
• 不要用它重新抓取 live site（extract Phase 1 后离线），也不要把它当迭代循环；迭代属于 `prototype`，migrate 只消费结果。