prepare-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

stardust:prepare-migration

Orchestrate the migrate-prep cascade. When the user commits to migrating an existing site, this skill runs the upstream phases (

extract

direct

prototype

) in their

--prep

modes, sequenced with confirmation gates so the user can confirm or refine the inferred catalog at each step.

prepare-migration

is a thin orchestrator — it does not duplicate logic from the underlying skills; it invokes them and brokers the per-phase summaries. The substantive work lives in:

```
skills/extract/SKILL.md
```
§ Prep mode
```
skills/direct/SKILL.md
```
§ Prep mode

skills/prototype/SKILL.md

§ Prep mode +

reference/canon-extraction.md

When prep is complete, the user runs

$stardust migrate

separately. The two-step boundary (

prepare-migration

then

migrate

) is intentional: it makes "I'm committing to migrate this site" a conscious gesture and keeps idempotency obvious.

协调迁移准备流程（migrate-prep cascade）。当用户决定迁移现有站点时，该skill会以

--prep

模式运行上游阶段（

extract

、

direct

、

prototype

），各阶段之间设有确认关卡，以便用户在每一步确认或优化推断出的目录。

prepare-migration

是一个轻量协调器——它不会重复底层skill的逻辑；它只是调用这些skill并传递各阶段的总结。实质性工作由以下部分完成：

```
skills/extract/SKILL.md
```
§ Prep模式
```
skills/direct/SKILL.md
```
§ Prep模式

skills/prototype/SKILL.md

§ Prep模式 +

reference/canon-extraction.md

准备完成后，用户需单独运行

$stardust migrate

。分为两步（先

prepare-migration

再

migrate

）是有意为之：这让“我确认要迁移此站点”成为一个有意识的操作，同时保持幂等性清晰。

Inputs

输入参数

```
--from <phase>
```
— optional. Resume the cascade from a specific phase. Values:
```
extract | direct | prototype | assets | dynamic-blocks
```
. Default starts from the earliest incomplete phase.
```
--skip-confirm
```
— optional. Skip the per-phase confirmation gates. Useful for re-runs where the catalog is already settled. Default is to gate at every phase boundary. Hands-off mode (
```
skills/stardust/SKILL.md
```
§ Hands-off mode, i.e.
```
state.json.handsOff: true
```
) implies
```
--skip-confirm
```
.
```
--canon-from <slug>
```
— optional. Forward to
```
prototype --prep --canon-from <slug>
```
when that phase runs. Override the default canon-author (which is
```
home
```
).
```
--refine-module <module-id>
```
— optional. Re-enter Phase 2's module-catalog step for one module — the target of
```
migrate
```
's "bespoke slot crossing promotion threshold" hint. Promotes the recurring bespoke slot into that module's slot schema (
```
DESIGN.json.extensions.modules[]
```
), surfaces the change for confirmation, then stops; it does not re-run the full cascade. Affected pages are stale-flagged content-aware per
```
skills/stardust/reference/state-machine.md
```
.

```
--from <phase>
```
— 可选。从指定阶段恢复流程。可选值：
```
extract | direct | prototype | assets | dynamic-blocks
```
。默认从最早未完成的阶段开始。
```
--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>
```
— 可选。重新进入阶段2的模块目录步骤，针对单个模块——即
```
migrate
```
提示中“定制插槽超过升级阈值”的目标模块。将重复出现的定制插槽升级到该模块的插槽架构（
```
DESIGN.json.extensions.modules[]
```
），展示变更供确认，然后停止；不会重新运行整个流程。受影响的页面会根据
```
skills/stardust/reference/state-machine.md
```
标记为内容过时。

Setup

前置准备

Run the master skill's setup (
```
skills/stardust/SKILL.md
```
§ Setup) — impeccable dep check, context loader, state read.
Verify
```
stardust/state.json
```
exists with at least one extracted page. If not, recommend
```
$stardust extract <url>
```
and stop.
Verify
```
stardust/direction.md
```
exists with an active direction. If not, recommend
```
$stardust direct
```
and stop.
Determine which phases are already complete by inspecting project state:
- extract: every page has a non-null
```
type
```
  in
```
state.json
```
  and
```
current/pages/<slug>.json
```
  carries a
```
slots
```
  block.
- direct:
```
DESIGN.json.extensions.modules[]
```
  entries all have
```
status: confirmed
```
  ;
```
colorReservations
```
  and
```
metadata
```
  blocks present.
- prototype: every page-type has at least one approved archetype;
```
stardust/canon/
```
  populated;
```
DESIGN.json.extensions.canon
```
  populated.
- assets: favicon variants in
```
stardust/migrated/assets/
```
  ; fonts downloaded.
- dynamic-blocks:
```
stardust/dynamic-blocks-map.md
```
  and
```
helix-query.yaml
```
  present — only required when the inventory contains listing blocks (Phase 4.5 records "none" otherwise).
Resume from the earliest incomplete phase unless
```
--from
```
overrides.

运行主skill的设置流程（
```
skills/stardust/SKILL.md
```
§ Setup）——完成依赖检查、上下文加载、状态读取。
验证
```
stardust/state.json
```
存在且至少包含一个已提取的页面。如果不存在，建议运行
```
$stardust extract <url>
```
并终止流程。
验证
```
stardust/direction.md
```
存在且包含有效迁移方向。如果不存在，建议运行
```
$stardust direct
```
并终止流程。
通过检查项目状态确定哪些阶段已完成：
- extract：
```
state.json
```
  中每个页面的
```
type
```
  字段非空，且
```
current/pages/<slug>.json
```
  包含
```
slots
```
  块。
- direct：
```
DESIGN.json.extensions.modules[]
```
  的所有条目均有
```
status: confirmed
```
  ；存在
```
colorReservations
```
  和
```
metadata
```
  块。
- prototype：每种页面类型至少有一个已批准的原型；
```
stardust/canon/
```
  目录已填充；
```
DESIGN.json.extensions.canon
```
  已填充。
- assets：
```
stardust/migrated/assets/
```
  目录中有不同尺寸的favicon；字体已下载。
- dynamic-blocks：存在
```
stardust/dynamic-blocks-map.md
```
  和
```
helix-query.yaml
```
  ——仅当页面清单包含列表块时需要（否则阶段4.5会记录“none”）。
除非通过
```
--from
```
指定，否则从最早未完成的阶段恢复流程。

Procedure

执行流程

The cascade runs five phases sequentially. Each phase invokes its underlying skill via the Skill tool, surfaces the phase's prep summary, then waits for user confirmation (unless

--skip-confirm

or hands-off mode) before advancing.

流程会按顺序运行五个阶段。每个阶段通过Skill工具调用底层skill，展示该阶段的准备总结，然后等待用户确认（除非启用

--skip-confirm

或无人干预模式）后再进入下一阶段。

Phase 1 — extract --prep

阶段1 — extract --prep

Invoke:

Skill {
  skill: "stardust:extract",
  args: "--prep"
}

The underlying skill runs the standard extract procedure with the five

--prep

overlays (lift cap, page typing, module candidates, typed slots, prep summary).

On completion, surface the summary verbatim and gate:

Confirm and continue? (yes / refine "<phrase>")

User options:

yes
— advance to Phase 2.
refine "<phrase>"
— re-invoke
```
extract --prep
```
with the refinement (e.g., "type news/* slugs as listing not article", "exclude /search and /404 from inventory"). Re-surface summary; loop.

调用：

Skill {
  skill: "stardust:extract",
  args: "--prep"
}

底层skill会运行标准提取流程，并叠加五个

--prep

模式的逻辑（提升限制、页面分类、模块候选、带类型插槽、准备总结）。

完成后，原样展示总结并等待确认：

Confirm and continue? (yes / refine "<phrase>")

用户可选操作：

yes
— 进入阶段2。
refine "<phrase>"
— 传入优化指令重新调用
```
extract --prep
```
（例如："将news/*路径的页面分类为listing而非article"、"排除/search和/404页面"）。重新展示总结；循环此步骤。

Provenance guard (between Phase 1 and Phase 2)

来源验证（阶段1与阶段2之间）

Before invoking

direct --prep

, validate every page in the inventory via

validateProvenance(page)

per

skills/stardust/reference/state-machine.md

§ Provenance validation. Abort the cascade with the helper's error if any page lacks live-render evidence. This is the cascade-level defense against the failure mode where

extract --prep

(or its delegated sub-agent) silently synthesized one or more page records — extract's own write-time refusal is the primary guard, but the cascade adds a second check between phases so the synthesis bug recurring under a different rationale cannot quietly contaminate the rest of the run.

The same guard runs implicitly inside Phase 2, 3, and 4 (each underlying skill's setup calls

validateProvenance()

per its own SKILL.md) — but surfacing it here as an explicit cascade step makes the abort happen before the user sees the Phase 2 prep summary, which would otherwise look like a successful run.

Surface in the cascade output:

Provenance OK on 127 pages.

When the check fails:

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>
       ...

在调用

direct --prep

之前，根据

skills/stardust/reference/state-machine.md

§ 来源验证中的

validateProvenance(page)

验证清单中的每个页面。如果任何页面缺少实时渲染证据，终止流程并显示助手错误信息。这是流程层面的防御机制，防止

extract --prep

（或其委托的子代理）静默合成一个或多个页面记录——extract自身的写入时拒绝是主要防御，但流程在阶段之间添加二次检查，避免合成漏洞在不同逻辑下悄悄污染后续运行。

阶段2、3、4内部也会隐式运行相同的验证（每个底层skill的设置步骤会根据自身SKILL.md调用

validateProvenance()

）——但在此处作为显式流程步骤展示，可在用户看到阶段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

阶段2 — direct --prep

Invoke:

Skill {
  skill: "stardust:direct",
  args: "--prep"
}

The underlying skill runs five

--prep

overlays (type catalog confirmation, module catalog finalization, color reservations, direction re-evaluation, brand metadata defaults).

Surface the summary and gate. User options match Phase 1 (

yes

refine "<phrase>"

调用：

Skill {
  skill: "stardust:direct",
  args: "--prep"
}

底层skill会运行五个

--prep

模式的逻辑（类型目录确认、模块目录最终确定、颜色预留、迁移方向重评估、品牌元数据默认值设置）。

展示总结并等待确认。用户可选操作与阶段1相同（

yes

refine "<phrase>"

）。

Phase 3 — prototype --prep

阶段3 — prototype --prep

Invoke:

Skill {
  skill: "stardust:prototype",
  args: "--prep" + (canonFromSlug ? " --canon-from " + canonFromSlug : "")
}

The underlying skill fills page-type gaps (one approved archetype per type) and writes canon back per

skills/prototype/reference/canon-extraction.md

. First approval establishes canon; subsequent approvals extend it (with conflicts logged as deviations by default).

This phase typically takes the longest — each archetype goes through the full prototype loop (shape brief, craft, open in browser, iterate, approve). Stream progress to the user as each archetype lands.

Surface the summary and gate.

调用：

Skill {
  skill: "stardust:prototype",
  args: "--prep" + (canonFromSlug ? " --canon-from " + canonFromSlug : "")
}

底层skill会填补页面类型的空白（每种类型一个已批准的原型），并根据

skills/prototype/reference/canon-extraction.md

写入设计规范。首次批准会确立规范；后续批准会扩展规范（默认将冲突记录为偏差）。

此阶段通常耗时最长——每个原型都要经过完整的原型循环（形状概要、制作、在浏览器中打开、迭代、批准）。随着每个原型完成，向用户实时展示进度。

展示总结并等待确认。

Phase 4 — assets prep

阶段4 — 资产准备

Generate or download asset variants needed for the migrated site. This phase has no underlying SKILL — it runs as a small image- processing + download routine.

Favicon variants. From the canonical favicon at

stardust/current/assets/favicon.<ext>

, generate:

stardust/migrated/assets/favicon-512.png

stardust/migrated/assets/apple-touch-icon.png

(180×180)

stardust/migrated/assets/icon-192.png

icon-512.png

(manifest sizes)

Font downloads. Scan
```
stardust/canon/canon.css
```
(and
```
stardust/canon/header.html
```
/
```
footer.html
```
) for
```
@font-face
```
rules with external URLs. For each:
- Download the file to
```
stardust/migrated/assets/fonts/<basename-with-hash>.<ext>
```
  .
- Rewrite the
```
@font-face
```
```
url(...)
```
  reference in canon files to the local path.
- Skip if already downloaded (sha-compared).
- Log a warning if download fails (font keeps external URL; migrate logs a
```
metadata-override
```
  warning per page).
Brand-asset audit. Verify the logo, favicon, and any media files referenced by canon module renderings are present in
```
stardust/current/assets/
```
. Surface missing assets to the user.

Surface summary and gate:

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

生成或下载迁移站点所需的各种资产。此阶段没有底层SKILL——它作为一个小型图像处理+下载例程运行。

Favicon多尺寸版本。从

stardust/current/assets/favicon.<ext>

的标准favicon生成：

stardust/migrated/assets/favicon-512.png

stardust/migrated/assets/apple-touch-icon.png

（180×180）

stardust/migrated/assets/icon-192.png

、

icon-512.png

（适配manifest尺寸）

字体下载。扫描
```
stardust/canon/canon.css
```
（以及
```
stardust/canon/header.html
```
/
```
footer.html
```
）中的外部URL的
```
@font-face
```
规则。对于每个规则：
- 将文件下载到
```
stardust/migrated/assets/fonts/<basename-with-hash>.<ext>
```
  。
- 将规范文件中
```
@font-face
```
  的
```
url(...)
```
  引用重写为本地路径。
- 如果已下载（通过sha校验）则跳过。
- 如果下载失败则记录警告（字体保留外部URL；migrate会在每个受影响页面记录
```
metadata-override
```
  警告）。
品牌资产审核。验证规范模块渲染引用的logo、favicon和所有媒体文件是否存在于
```
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 — Dynamic-blocks pre-import gate

阶段4.5 — 动态块预导入关卡

Runs after assets prep and before any bulk import downstream (

migrate

at scale,

rollout

Phase C). The ordering is the point: what a dynamic listing block can show is bounded by what each page emits, and retrofitting metadata across thousands of already-live pages is a second migration. Mechanics live in

skills/rollout/reference/dynamic-listings.md

; this phase runs them at prep time so the contract exists before the first bulk import (

rollout

Phase B2 then verifies it rather than redoing it).

Map every block that LISTS other pages (directories, news/event feeds, "related" rails) — these must read an EDS query-index, not static cards.
Classify each field a listing needs by tier:
- Tier 1 — page-intrinsic DOM (
```
h1
```
  ,
```
og:image
```
  , authored links): the index extracts them via CSS selectors — zero content change.
- Tier 2 — page metadata (dates, locations, categories): must be emitted as
```
<meta>
```
  via each page's metadata block at author time; retrofitting across live pages is the expensive path.
- Tier 3 — relationships (many-to-many): need an explicit join field + the related items must themselves be indexed pages. Those blocks stay static until modeled — record the decision in the map, don't fake it.
Write
stardust/dynamic-blocks-map.md
— dynamic vs static per listing block, the index each reads, and the metadata contract per content type (the concrete
```
<meta name="…">
```
fields).
Author
helix-query.yaml
(scoped indexes: include globs,
```
target
```
, properties) from the same contract, so selectors and emitted meta names line up.

When the inventory has no listing blocks, record "none" in the map and pass the gate. Surface summary and final gate:

dynamic-blocks prep complete
============================

Listing blocks:      3 dynamic (news-feed, events, related-treatments) · 1 static (Tier-3: specialists rail)
Metadata contract:   news → PublishDate, Category · event → EventDate, Location
Indexes authored:    helix-query.yaml (2 scoped indexes)

Migrate-readiness: confirmed
   → Run `$stardust migrate` to apply canon to every page in inventory.

在资产准备完成后、下游批量导入之前运行（大规模

migrate

、

rollout

阶段C）。顺序很重要：动态列表块能展示的内容受限于每个页面输出的数据，而在数千个已上线页面中追溯添加元数据相当于二次迁移。具体机制在

skills/rollout/reference/dynamic-listings.md

中；此阶段在准备阶段运行，以便在首次批量导入前确立契约（

rollout

阶段B2会验证而非重新执行此操作）。

映射所有列出其他页面的块（目录、新闻/事件Feed、“相关内容”栏）——这些块必须读取EDS查询索引，而非静态卡片。
按层级分类列表所需的每个字段：
- 层级1 — 页面固有DOM（
```
h1
```
  、
```
og:image
```
  、作者链接）：索引通过CSS选择器提取这些内容——无需修改内容。
- 层级2 — 页面元数据（日期、地点、分类）：必须在作者创作时通过每个页面的元数据块以
```
<meta>
```
  标签输出；在已上线页面中追溯添加成本很高。
- 层级3 — 关联关系（多对多）：需要显式关联字段 + 关联项本身必须是已索引页面。这些块在建模完成前保持静态——在映射中记录决策，不要伪造。
写入
stardust/dynamic-blocks-map.md
——每个列表块的动态/静态状态、读取的索引、以及每种内容类型的元数据契约（具体的
```
<meta name="…">
```
字段）。
编写
helix-query.yaml
（范围索引：包含通配符、
```
target
```
、属性），确保选择器与输出的元数据名称一致。

如果页面清单中没有列表块，在映射中记录“none”并通过关卡。展示总结和最终确认：

dynamic-blocks prep complete
============================

Listing blocks:      3 dynamic (news-feed, events, related-treatments) · 1 static (Tier-3: specialists rail)
Metadata contract:   news → PublishDate, Category · event → EventDate, Location
Indexes authored:    helix-query.yaml (2 scoped indexes)

Migrate-readiness: confirmed
   → Run `$stardust migrate` to apply canon to every page in inventory.

Final report

最终报告

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 blocks):    3 dynamic listings mapped; metadata contract + indexes authored

Next: $stardust migrate

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 blocks):    3 dynamic listings mapped; metadata contract + indexes authored

Next: $stardust migrate

Outputs

输出

prepare-migration

writes nothing directly — every artifact is written by the underlying skill or by the Phase 4 / 4.5 routines. After the cascade runs, the project state has:

Artifact	Phase that wrote it
`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-blocks-map.md` (metadata contract)	dynamic-blocks prep (Phase 4.5)
`helix-query.yaml` (scoped indexes, EDS project root)	dynamic-blocks prep (Phase 4.5)
`stardust/state.json` (per-page status updates)	each underlying phase

prepare-migration

不会直接写入任何内容——所有产物都由底层skill或阶段4/4.5的例程写入。流程运行完成后，项目状态包含以下产物：

产物	写入阶段
`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-blocks-map.md` (metadata contract)	dynamic-blocks prep (Phase 4.5)
`helix-query.yaml` (scoped indexes, EDS project root)	dynamic-blocks prep (Phase 4.5)
`stardust/state.json` (per-page status updates)	each underlying phase

Failure modes

失败场景

No state.json or no extracted pages. Recommend
```
$stardust extract <url>
```
and stop.
No active direction. Recommend
```
$stardust direct
```
and stop.
User refuses a phase. Stop the cascade cleanly. State is left in a consistent intermediate (the underlying skill's writes have landed); the user can resume with
```
$stardust prepare-migration --from <phase>
```
.
Underlying skill fails. Surface the failure verbatim; do not advance. User fixes and re-runs.
Phase 3 canon conflict during a non-canon-author approval. Conflicts log as deviations by default per
```
reference/canon-extraction.md
```
. If the user wants to override per-conflict (promote to canon / reject and re-iterate / log as deviation), surface during the phase's confirmation gate rather than at runtime. A future
```
--strict-canon
```
flag could refuse approvals that conflict; not in v0.2.
Phase 4 asset download failure. Continue the run; log the failure in the assets-prep summary. Migrate later surfaces a warning per affected page.

无state.json或无已提取页面。建议运行
```
$stardust extract <url>
```
并终止流程。
无有效迁移方向。建议运行
```
$stardust direct
```
并终止流程。
用户拒绝某个阶段。干净地终止流程。状态会保留在一致的中间状态（底层skill的写入已完成）；用户可通过
```
$stardust prepare-migration --from <phase>
```
恢复流程。
底层skill运行失败。原样展示失败信息；不进入下一阶段。用户修复问题后重新运行。
阶段3中非规范作者批准时出现规范冲突。默认根据
```
reference/canon-extraction.md
```
将冲突记录为偏差。如果用户想要针对每个冲突进行覆盖（升级为规范/拒绝并重新迭代/记录为偏差），在阶段确认关卡展示，而非运行时展示。未来的
```
--strict-canon
```
标志可拒绝存在冲突的批准；v0.2版本暂不支持。
阶段4资产下载失败。继续运行；在资产准备总结中记录失败。Migrate后续会在每个受影响页面展示警告。

Concurrency

并发

Per

skills/stardust/reference/state-machine.md

§ Concurrency:

state.json

writes merge by slug, so the cascade's per-page writes coexist with other parallel lanes. But two concurrent

prepare-migration

runs on the same project race on the same top-level artifacts (canon, module catalog) — that remains last-write-wins with a warning, and is likely to corrupt canon. Don't run two cascades at once; do not engineer a lock around it.

根据

skills/stardust/reference/state-machine.md

§ 并发：

state.json

按路径合并写入，因此流程的每页写入可与其他并行流程共存。但同一项目上两个并发的

prepare-migration

运行会在顶级产物（规范、模块目录）上产生竞争——仍采用最后写入获胜规则并记录警告，可能会破坏规范。不要同时运行两个流程；无需为此设计锁机制。

Idempotency

幂等性

Re-running

prepare-migration

after partial completion resumes from the earliest incomplete phase (or the explicit

--from

phase). Each underlying skill is itself idempotent — already- typed pages are not re-typed, already-confirmed modules are not re-proposed, already-approved archetypes are not re-prototyped, already-generated favicon variants are not re-generated, and an existing

dynamic-blocks-map.md

is refined rather than rewritten.

Re-running after full completion is a no-op unless inputs changed (extract found new pages, direction was edited, the canon-author prototype was re-iterated, etc.).

在部分完成后重新运行

prepare-migration

会从最早未完成的阶段（或指定的

--from

阶段）恢复。每个底层skill本身具有幂等性——已分类的页面不会重新分类，已确认的模块不会重新提议，已批准的原型不会重新制作，已生成的favicon多尺寸版本不会重新生成，已存在的

dynamic-blocks-map.md

会被优化而非重写。

在完全完成后重新运行是无操作，除非输入发生变化（extract发现新页面、迁移方向被编辑、规范作者原型被重新迭代等）。

References

参考文档

```
skills/extract/SKILL.md
```
§ Prep mode
```
skills/direct/SKILL.md
```
§ Prep mode
```
skills/prototype/SKILL.md
```
§ Prep mode
```
skills/prototype/reference/canon-extraction.md
```
— the five-step extraction procedure prototype --prep performs on approval
```
skills/rollout/reference/dynamic-listings.md
```
— metadata contract + query-index mechanics Phase 4.5 runs at prep time
```
skills/migrate/SKILL.md
```
— the consumer of every data structure this cascade prepares

notes/migrate-template-canon-refactor.md

— design plan and rationale

skills/stardust/reference/state-machine.md

— page typing, stale-flagging cascade

```
skills/stardust/reference/artifact-map.md
```
— file structure, DESIGN.json.extensions shape

```
skills/extract/SKILL.md
```
§ Prep模式
```
skills/direct/SKILL.md
```
§ Prep模式
```
skills/prototype/SKILL.md
```
§ Prep模式
```
skills/prototype/reference/canon-extraction.md
```
— prototype --prep在批准时执行的五步提取流程
```
skills/rollout/reference/dynamic-listings.md
```
— 阶段4.5在准备阶段运行的元数据契约+查询索引机制
```
skills/migrate/SKILL.md
```
— 此流程准备的所有数据结构的消费方

notes/migrate-template-canon-refactor.md

— 设计方案和原理

skills/stardust/reference/state-machine.md

— 页面分类、过时标记流程

```
skills/stardust/reference/artifact-map.md
```
— 文件结构、DESIGN.json.extensions格式