migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

stardust:migrate

Apply the target spec authored by

direct

, the visual canon written by

prototype --prep

, and the brand-module catalog extracted during

prepare-migration

to every page in the inventory. Produces a self-contained, deployable static HTML site under

stardust/migrated/

. Per-page, incremental, idempotent.

migrate

is the final stardust phase. Output is platform- agnostic HTML — downstream conversion (AEM EDS, a CMS, a framework) is the job of a separate plugin that consumes

migrated/

plus

DESIGN.json

plus the per-page

_meta.json

sidecars.

将

direct

生成的目标规格、

prototype --prep

编写的视觉canon，以及

prepare-migration

过程中提取的品牌模块目录应用到库存中的每个页面。在

stardust/migrated/

目录下生成一个独立的、可部署的静态HTML站点。按页面增量处理、幂等。

migrate

是stardust的最终阶段。输出为平台无关的HTML——下游转换（如AEM EDS、CMS、框架）由单独的插件负责，该插件会读取

migrated/

目录、

DESIGN.json

以及每个页面的

_meta.json

辅助文件。

Inputs

输入参数

```
<slug>
```
— optional positional. Migrate just this page. Without it, migrate every page whose status is
```
directed
```
,
```
prototyped
```
, or
```
approved
```
(and not
```
stale
```
).
```
--refresh-stale
```
— re-migrate every page flagged
```
stale
```
. Default skips stale pages and surfaces the count.
```
--all
```
— migrate every page including stale ones.
```
--force
```
— re-migrate every page even when the idempotent skip would skip them.
```
--require-approved
```
— refuse to migrate any non-
```
approved
```
page. Default behaviour migrates
```
directed
```
pages too (using Path A′ or Path B per
```
reference/template-and-module-rendering.md
```
); this flag flips approval-gating on.
```
--allow-placeholder
```
— allow migration of pages whose proposed/archetype files contain
```
[data-placeholder]
```
elements (per
```
skills/prototype/reference/before-after-shell.md
```
§ Content sourcing hierarchy). Default refuses; use this flag only when shipping placeholders is intentional (internal staging review).
```
--strict-canon
```
— refuse approvals that conflict with canon. Default logs the deviation and continues. Useful for projects where canon discipline matters more than per-template flexibility.
```
--skip-adapt-audit
```
— skip the mobile-adapt audit at per-page render time. Default refuses pages whose proposed / approved file has no
```
<meta viewport>
```
, zero
```
@media (max-width: ...)
```
rules, or no mobile-targeted breakpoint at ≤ 640px (per
```
skills/prototype/SKILL.md
```
§ Mobile-adapt audit). Use this flag for an explicit desktop-only demo deploy; the failure is real and the override is recorded in the per-page
```
_meta.json#audit.adapt
```
.

```
<slug>
```
— 可选位置参数。仅迁移此页面。若未指定，则迁移所有状态为
```
directed
```
、
```
prototyped
```
或
```
approved
```
（且非
```
stale
```
）的页面。
```
--refresh-stale
```
— 重新迁移所有标记为
```
stale
```
的页面。默认会跳过过期页面并显示数量。
```
--all
```
— 迁移所有页面，包括过期页面。
```
--force
```
— 重新迁移所有页面，即使幂等检查会跳过它们。
```
--require-approved
```
— 拒绝迁移任何非
```
approved
```
的页面。默认行为也会迁移
```
directed
```
页面（根据
```
reference/template-and-module-rendering.md
```
使用路径A′或路径B）；此标志启用批准闸门机制。
```
--allow-placeholder
```
— 允许迁移其拟议/原型文件包含
```
[data-placeholder]
```
元素的页面（参考
```
skills/prototype/reference/before-after-shell.md
```
§ 内容源层级）。默认会拒绝；仅当有意部署占位符（如内部 staging 评审）时使用此标志。
```
--strict-canon
```
— 拒绝与canon冲突的批准内容。默认会记录偏差并继续执行。适用于canon纪律比模板灵活性更重要的项目。
```
--skip-adapt-audit
```
— 在每页渲染时跳过移动端适配审计。默认会拒绝那些拟议/批准文件中没有
```
<meta viewport>
```
、零个
```
@media (max-width: ...)
```
规则，或没有≤640px移动端断点的页面（参考
```
skills/prototype/SKILL.md
```
§ 移动端适配审计）。使用此标志进行明确的仅桌面端演示部署；失败是真实存在的，覆盖操作会记录在每页的
```
_meta.json#audit.adapt
```
中。

Setup

准备步骤

Run the master skill's setup (
```
skills/stardust/SKILL.md
```
§ Setup).
Verify
```
stardust/state.json
```
exists with at least one
```
directed
```
page.
Verify project-root
```
DESIGN.md
```
and
```
DESIGN.json
```
exist with
```
DESIGN.json.extensions.canon
```
populated. If canon is empty, recommend
```
$stardust prepare-migration
```
and stop.
Verify
```
stardust/canon/
```
exists with at least
```
header.html
```
,
```
footer.html
```
,
```
canon.css
```
. Otherwise prep hasn't completed; recommend
```
$stardust prepare-migration
```
and stop.
Verify
```
stardust/direction.md
```
has an active (not pending) direction.
Read
```
state.json.pages[]
```
and partition into:
- inScope: status
```
directed
```
  ,
```
prototyped
```
  , or
```
approved
```
  ,
```
stale: false
```
  (or
```
--all
```
  /
```
--refresh-stale
```
  / explicit
```
<slug>
```
  ).
- skipped: everything else, with reason captured.
Validate provenance on every in-scope page. Call
```
validateProvenance(page)
```
per
```
skills/stardust/reference/state-machine.md
```
§ Provenance validation for every page in
```
inScope
```
. Abort with the helper's error when any page lacks live-render evidence — migrating a synthesized page record produces deployable HTML that misrepresents the source site, the exact failure mode that motivated the validator. Surface
```
Provenance OK on N pages
```
in the migrate-plan output before Phase 1.
Mobile-adapt audit on every Path A / Path A′ source. For every page whose render branch consumes a proposed or archetype HTML file (Path A, Path A′ per
```
reference/template-and-module-rendering.md
```
§ Render path selection), run the audit per
```
skills/prototype/SKILL.md
```
§ Mobile-adapt audit:
- ```
<meta name="viewport" content="width=device-width, ...">
```
  present, width not pinned to a fixed pixel value.
- At least one
```
@media (max-width: ...)
```
  rule.
- At least one mobile-targeted breakpoint at ≤ 640px.
Refuse pages that fail unless
```
--skip-adapt-audit
```
was passed. Record the audit result per page in the migrate report and in the post-render
```
_meta.json#audit.adapt
```
sidecar. Path B (unique-renders) skips the audit because adapt hasn't run on those pages — a Path B page that needs mobile coverage gets it via
```
$impeccable adapt
```
invoked separately by the user. Surface this distinction in the report so it's not read as a silent skip.

运行主技能的设置流程（
```
skills/stardust/SKILL.md
```
§ Setup）。
确认
```
stardust/state.json
```
存在且至少包含一个
```
directed
```
页面。
确认项目根目录下的
```
DESIGN.md
```
和
```
DESIGN.json
```
存在，且
```
DESIGN.json.extensions.canon
```
已填充。若canon为空，建议运行
```
$stardust prepare-migration
```
并终止流程。
确认
```
stardust/canon/
```
目录存在且至少包含
```
header.html
```
、
```
footer.html
```
、
```
canon.css
```
。否则说明准备步骤未完成；建议运行
```
$stardust prepare-migration
```
并终止流程。
确认
```
stardust/direction.md
```
包含有效（非待处理）的方向指令。
读取
```
state.json.pages[]
```
并划分为：
- 范围内页面：状态为
```
directed
```
  、
```
prototyped
```
  或
```
approved
```
  ，且
```
stale: false
```
  （或使用
```
--all
```
  /
```
--refresh-stale
```
  /显式
```
<slug>
```
  参数）。
- 跳过页面：所有其他页面，并记录跳过原因。
验证所有范围内页面的来源。对
```
inScope
```
中的每个页面调用
```
validateProvenance(page)
```
（参考
```
skills/stardust/reference/state-machine.md
```
§ 来源验证）。若任何页面缺少实时渲染证据，则终止流程并返回辅助工具的错误——迁移合成的页面记录会生成误导源站点的可部署HTML，这正是验证器要避免的故障模式。在第一阶段前，在迁移计划输出中显示“N个页面来源验证通过”。
对所有路径A/路径A′来源进行移动端适配审计。对于每个渲染分支使用拟议或原型HTML文件的页面（路径A、路径A′参考
```
reference/template-and-module-rendering.md
```
§ 渲染路径选择），按照
```
skills/prototype/SKILL.md
```
§ 移动端适配审计执行检查：
- 存在
```
<meta name="viewport" content="width=device-width, ...">
```
  ，且宽度未固定为像素值。
- 至少包含一个
```
@media (max-width: ...)
```
  规则。
- 至少包含一个≤640px的移动端断点。
除非传入
```
--skip-adapt-audit
```
，否则会拒绝未通过检查的页面。在迁移报告和渲染后的
```
_meta.json#audit.adapt
```
辅助文件中记录每页的审计结果。路径B（独特渲染）会跳过审计，因为这些页面尚未执行适配操作——需要移动端覆盖的路径B页面由用户单独调用
```
$impeccable adapt
```
来处理。在报告中明确区分这一点，避免被误认为静默跳过。

Procedure

执行流程

Phase 1 — Plan

第一阶段 — 计划

Print the plan and wait for confirmation when the scope is large:

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.

For 1-3 pages or

<slug>

invocation, skip the confirmation.

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

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>

调用，则跳过确认步骤。

Phase 2 — Per-page render

第二阶段 — 逐页渲染

For each page in scope, follow

reference/migration-procedure.md

and

reference/template-and-module-rendering.md

Idempotent skip check first (sha-compare across

designMd

designJson

sourceCurrent

sourceProposed

canonShas

archetypeSource

Placeholder gate (Path A and Path A′ only — pages with a proposed file or archetype). Refuse without
```
--allow-placeholder
```
when
```
[data-placeholder]
```
elements or non-empty
```
_provenance.unsourcedContent[]
```
are present.
Render branch selection (LLM judgment per T&M § Render path selection): A / A′ / B.
Render per the chosen branch's procedure in T&M.
Canon application — chrome injection, canon.css injection, deviation logging.
Module rendering — render module instances via
```
stardust/canon/modules/<id>.html
```
; bespoke slots logged with
```
data-bespoke
```
.
Apply content-preservation rules per
```
reference/content-preservation.md
```
. Internal-link rewriting always emits migrated-tree paths; missing slugs flagged broken.
Compose
<head>
metadata per
```
reference/metadata-and-jsonld.md
```
(five categories; page-type-driven JSON-LD).
Validate per T&M § Validation contracts. Strict contracts refuse the page; soft contracts log and continue.
Compute output path per migration-procedure.md § Output path mapping.
Write the migrated
```
index.html
```
and the
```
_meta.json
```
sidecar in the same directory. Provenance block as first child of
```
<head>
```
.

对每个范围内的页面，遵循

reference/migration-procedure.md

和

reference/template-and-module-rendering.md

：

首先执行幂等跳过检查（对
```
designMd
```
、
```
designJson
```
、
```
sourceCurrent
```
、
```
sourceProposed
```
、
```
canonShas
```
、
```
archetypeSource
```
进行sha对比）。
占位符检查（仅路径A和路径A′——包含拟议文件或原型的页面）。若存在
```
[data-placeholder]
```
元素或非空的
```
_provenance.unsourcedContent[]
```
，且未使用
```
--allow-placeholder
```
，则拒绝迁移。
渲染分支选择（根据模板与模块渲染文档的LLM判断：A / A′ / B）。
按所选分支的流程渲染（参考模板与模块渲染文档）。
应用canon规范——注入框架代码、canon.css，记录偏差。
模块渲染——通过
```
stardust/canon/modules/<id>.html
```
渲染模块实例；自定义插槽会标记
```
data-bespoke
```
并记录。
应用内容保留规则（参考
```
reference/content-preservation.md
```
）。内部链接重写始终输出迁移后的路径；缺失的slug会标记为损坏。
组合
<head>
元数据（参考
```
reference/metadata-and-jsonld.md
```
，分为五类；基于页面类型的JSON-LD）。
验证（参考模板与模块渲染文档的验证契约）。严格契约拒绝页面；宽松契约记录并继续执行。
计算输出路径（参考迁移流程文档的输出路径映射）。
写入文件——在同一目录下生成迁移后的
```
index.html
```
和
```
_meta.json
```
辅助文件。来源信息块作为
```
<head>
```
的第一个子元素。

Phase 3 — Asset migration

第三阶段 — 资源迁移

Once page-level migration is done, ensure

stardust/migrated/assets/

is consistent:

Copy

stardust/current/assets/logo.<ext>

stardust/migrated/assets/logo.<ext>

(only if missing or stale).

Copy each referenced media file from
```
stardust/current/assets/media/
```
to
```
stardust/migrated/assets/media/
```
(only files referenced by migrated pages).
Verify favicon variants and font files were generated by
```
prepare-migration
```
Phase 4. If absent, log a warning and continue (the migrated site renders without them, just missing some platform-specific affordances).

Add

stardust/migrated/robots.txt

and

sitemap.xml

derived from the migrated page inventory per

reference/metadata-and-jsonld.md

§ Sitemap entry.

Asset migration is idempotent — files are content-hashed and copied only when missing.

页面级迁移完成后，确保

stardust/migrated/assets/

目录一致：

将

stardust/current/assets/logo.<ext>

复制到

stardust/migrated/assets/logo.<ext>

（仅当文件缺失或过期时执行）。

将每个被迁移页面引用的媒体文件从

stardust/current/assets/media/

复制到

stardust/migrated/assets/media/

。

确认favicon变体和字体文件已由
```
prepare-migration
```
第四阶段生成。若缺失，记录警告并继续执行（迁移后的站点仍可渲染，仅缺少部分平台特定功能）。
添加
```
stardust/migrated/robots.txt
```
和
```
sitemap.xml
```
，根据迁移后的页面库存生成（参考
```
reference/metadata-and-jsonld.md
```
§ 站点地图条目）。

资源迁移是幂等的——文件会进行内容哈希，仅当缺失时才会复制。

Phase 4 — State and report

第四阶段 — 状态更新与报告

Update

state.json

For each successfully migrated page:
```
status
```
advances to
```
migrated
```
, append a history entry, clear any
```
stale
```
flag, set
```
migratedPath
```
.
For pages skipped via idempotent skip: leave state unchanged.
For pages that failed validation: leave state unchanged, log the failure in
```
state.json.lastRun.failures[]
```
.

Print the run summary:

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`

Output:  stardust/migrated/  (122 pages, 47 assets, 4.2 MB)

Next:
  - Review:    open stardust/migrated/index.html in a browser
  - Audit:     $impeccable critique stardust/migrated/
  - Deploy:    upload stardust/migrated/ to any static host
  - Refine:    edit DESIGN.md or canon files, then re-run $stardust migrate

更新

state.json

：

对于成功迁移的页面：将
```
status
```
更新为
```
migrated
```
，添加历史记录条目，清除
```
stale
```
标记，设置
```
migratedPath
```
。
对于因幂等跳过的页面：保持状态不变。
对于验证失败的页面：保持状态不变，在
```
state.json.lastRun.failures[]
```
中记录失败信息。

打印运行摘要：

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`

Output:  stardust/migrated/  (122 pages, 47 assets, 4.2 MB)

Next:
  - Review:    open stardust/migrated/index.html in a browser
  - Audit:     $impeccable critique stardust/migrated/
  - Deploy:    upload stardust/migrated/ to any static host
  - Refine:    edit DESIGN.md or canon files, then re-run $stardust migrate

Outputs

输出内容

Path	Purpose
`stardust/migrated/<slug-path>/index.html`	Migrated page (one per slug, nested for URL fidelity).
`stardust/migrated/<slug-path>/_meta.json`	Sidecar with full reasoning trace per page.
`stardust/migrated/index.html`	The home page (special case).
`stardust/migrated/_meta.json`	Home sidecar.
`stardust/migrated/assets/logo.<ext>`	Brand logo.
`stardust/migrated/assets/media/...`	Referenced page media.
`stardust/migrated/assets/favicon.<ext>` + variants	Favicon and apple-touch-icon, manifest icons.
`stardust/migrated/assets/fonts/...`	Downloaded font files (from canon @font-face URLs).
`stardust/migrated/robots.txt`	Minimal robots.txt.
`stardust/migrated/sitemap.xml`	Sitemap derived from migrated inventory + page types.
`stardust/state.json`	Updated with `migrated` status and history.

路径	用途
`stardust/migrated/<slug-path>/index.html`	迁移后的页面（每个slug对应一个，按URL层级嵌套）。
`stardust/migrated/<slug-path>/_meta.json`	包含每页完整推理轨迹的辅助文件。
`stardust/migrated/index.html`	首页（特殊情况）。
`stardust/migrated/_meta.json`	首页辅助文件。
`stardust/migrated/assets/logo.<ext>`	品牌logo。
`stardust/migrated/assets/media/...`	页面引用的媒体文件。
`stardust/migrated/assets/favicon.<ext>` + variants	Favicon和apple-touch-icon、manifest图标。
`stardust/migrated/assets/fonts/...`	下载的字体文件（来自canon的@font-face URL）。
`stardust/migrated/robots.txt`	极简版robots.txt。
`stardust/migrated/sitemap.xml`	根据迁移后的库存和页面类型生成的站点地图。
`stardust/state.json`	更新后的状态文件，包含 `migrated` 状态和历史记录。

Idempotent and incremental

幂等与增量特性

The whole pipeline is built around two properties:

Idempotent. Re-running
```
$stardust migrate
```
with no changes produces zero file writes. Every page is sha-compared across designMd, designJson, sourceCurrent, sourceProposed (Path A), canonShas, archetypeSource (Path A′) — and skipped if all match.
Incremental. Migrate 5 pages today, 20 pages tomorrow, fix one page's content next week — the migrated tree is always the union of every successful migration to date.

These properties hold even when DESIGN.md, canon, or modules are edited mid-run: the edit changes the relevant sha, so the next migrate run re-renders every affected page (canon and DESIGN.md edits typically affect every page).

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

幂等性：在无任何更改的情况下重新运行
```
$stardust migrate
```
不会写入任何文件。每个页面都会对比designMd、designJson、sourceCurrent、sourceProposed（路径A）、canonShas、archetypeSource（路径A′）的sha值——若全部匹配则跳过。
增量性：今天迁移5个页面，明天迁移20个，下周修复一个页面的内容——迁移后的目录始终是所有成功迁移结果的合集。

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

Stale handling

过期页面处理

When

direction.md

, canon, or the module catalog changes after some pages have been migrated:

Affected pages are flagged
```
stale: true
```
per
```
skills/stardust/reference/state-machine.md
```
§ Stale flagging. Stale-flagging is content-aware in all three trigger cases.
```
$stardust migrate
```
(no flags) skips stale pages and reports the count.
```
$stardust migrate --refresh-stale
```
re-migrates each stale page, clearing the flag on success.
```
$stardust migrate <slug>
```
always operates on the named page, stale or not.

The user decides whether stale pages should be refreshed — direction/canon/module changes don't invalidate prior migrated work, they just mark it as out-of-step.

当

direction.md

、canon或模块目录在部分页面已迁移后发生变化时：

根据
```
skills/stardust/reference/state-machine.md
```
§ 过期标记规则，受影响的页面会被标记为
```
stale: true
```
。过期标记在三种触发场景下都是内容感知的。
```
$stardust migrate
```
（无标志）会跳过过期页面并报告数量。
```
$stardust migrate --refresh-stale
```
会重新迁移每个过期页面，成功后清除标记。
```
$stardust migrate <slug>
```
始终处理指定页面，无论其是否过期。

用户决定是否刷新过期页面——方向/canon/模块的更改不会使之前的迁移工作失效，仅标记其为不同步。

Failure modes

故障模式

No directed pages. Recommend
```
$stardust direct
```
(or
```
$stardust extract
```
if no extracted state).
No DESIGN.md, DESIGN.json, or canon. Recommend
```
$stardust prepare-migration
```
.
Pending direction. Refuse; user must resolve direction first.
Validation failure on a single page. Skip that page, continue, log the failure under
```
state.json.lastRun.failures[]
```
. Do not abort the whole run.
Asset copy failure. Continue the run; record the missing asset in the page's
```
migrationDecisions[]
```
with
```
kind: "asset-missing"
```
. The migrated
```
<img src>
```
keeps the original absolute URL as a fallback.
Output path collision. Two slugs mapping to the same output path. Refuse to write the second one and surface to the user — manual slug rename needed.
Placeholder content in proposed/archetype file. Without
```
--allow-placeholder
```
, refuse to ship a page whose source contains
```
[data-placeholder]
```
elements. Surface the unsourced list and recommend either sourcing real content (re-prototype) or re-running with
```
--allow-placeholder
```
for staging review.
Color reservation violated. Refuse the page; surface to user with the offending color and the reserved-for context.
Brand-faithful inversion conflict. A hard rule declared inverted in
```
extensions.divergence.brand_faithful_inversions[]
```
is lifted from validation per T&M § Brand-faithful inversion handling. Emit a one-line note in the run summary acknowledging the lift.

无directed页面：建议运行
```
$stardust direct
```
（若没有提取状态则运行
```
$stardust extract
```
）。
无DESIGN.md、DESIGN.json或canon：建议运行
```
$stardust prepare-migration
```
。
待处理的方向指令：拒绝执行；用户必须先解决方向指令。
单个页面验证失败：跳过该页面，继续执行，在
```
state.json.lastRun.failures[]
```
中记录失败信息。不会终止整个运行。
资源复制失败：继续运行；在页面的
```
migrationDecisions[]
```
中记录缺失的资源，标记
```
kind: "asset-missing"
```
。迁移后的
```
<img src>
```
会保留原始绝对URL作为回退。
输出路径冲突：两个slug映射到同一输出路径。拒绝写入第二个页面并通知用户——需要手动重命名slug。
拟议/原型文件中包含占位符内容：若未使用
```
--allow-placeholder
```
，拒绝部署包含
```
[data-placeholder]
```
元素的页面。显示未来源内容列表，并建议要么补充真实内容（重新执行原型步骤），要么使用
```
--allow-placeholder
```
重新运行以用于staging评审。
违反颜色保留规则：拒绝页面；向用户显示违规颜色及其保留上下文。
品牌忠实反转冲突：
```
extensions.divergence.brand_faithful_inversions[]
```
中声明的硬规则会从验证中解除（参考模板与模块渲染文档的品牌忠实反转处理）。在运行摘要中输出一行说明确认解除操作。

What migrate does NOT do

migrate不执行的操作

Critique or audit the migrated output. Run
```
$impeccable critique stardust/migrated/
```
after migration if you want a quality assessment.
Deploy. Stardust does not push, upload, or modify origin.
Generate AEM EDS, a CMS payload, or framework components. The output is platform-agnostic static HTML; downstream conversion is a separate plugin's job.
Re-fetch the live site. Offline after extract Phase 1.
Run
```
$impeccable live
```
or any iteration loop. Iteration belongs to
```
prototype
```
; migrate consumes the result.

评估或审计迁移后的输出。若需要质量评估，迁移后运行
```
$impeccable critique stardust/migrated/
```
。
部署。Stardust不会推送、上传或修改源站。
生成AEM EDS、CMS负载或框架组件。输出为平台无关的静态HTML；下游转换是单独插件的工作。
重新获取实时站点。提取第一阶段后处于离线状态。
运行
```
$impeccable live
```
或任何迭代循环。迭代属于
```
prototype
```
阶段；migrate会消费其结果。

References

参考文档

```
reference/migration-procedure.md
```
— per-page render procedure, output path mapping, validation, provenance shape, idempotent skip, sidecar schema.
```
reference/template-and-module-rendering.md
```
— three render branches in detail, slot injection, deviation policy, validation contracts.
```
reference/metadata-and-jsonld.md
```
— head composition, JSON-LD per page-type, canonical strategy.
```
reference/content-preservation.md
```
— what's kept, transformed, dropped; internal-link rewriting; asset path rewriting; form handling.
```
skills/stardust/reference/token-contract.md
```
—
```
:root
```
block refreshed from DESIGN.md on every render.

skills/stardust/reference/data-attributes.md

— structural attributes including

data-template

data-module

data-slot

data-canon

data-deviation

data-bespoke

data-broken-link

```
skills/stardust/reference/state-machine.md
```
— page lifecycle, page typing, stale-flagging cascade.
```
skills/stardust/reference/artifact-map.md
```
— provenance shape for migrated artifacts; canon files; sidecar shape.

skills/prototype/reference/canon-extraction.md

— how canon is built (input to migrate).

```
skills/prepare-migration/SKILL.md
```
— the cascade that produces every input migrate consumes.

```
reference/migration-procedure.md
```
— 逐页渲染流程、输出路径映射、验证、来源格式、幂等跳过、辅助文件 schema。
```
reference/template-and-module-rendering.md
```
— 三种渲染分支的详细说明、插槽注入、偏差策略、验证契约。
```
reference/metadata-and-jsonld.md
```
— head组合、基于页面类型的JSON-LD、规范策略。
```
reference/content-preservation.md
```
— 保留、转换、丢弃的内容；内部链接重写；资源路径重写；表单处理。

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
```
— 页面生命周期、页面类型、过期标记 cascade。
```
skills/stardust/reference/artifact-map.md
```
— 迁移工件的来源格式；canon文件；辅助文件格式。
```
skills/prototype/reference/canon-extraction.md
```
— canon的构建方式（migrate的输入）。
```
skills/prepare-migration/SKILL.md
```
— 生成migrate所有输入的流程。