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.
Inputs
<slug> — optional positional. Migrate just this page. Without
it, migrate every page whose status is directed,
prototyped, or approved (and not stale).
--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.
--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.
--clean — delete assets previously bundled but no longer
referenced from stardust/migrated/assets/. Off by default
(migrate is additive). Implies --force: every page is
re-rendered so the run's bundledAssets Set is the complete
union of currently-referenced assets — otherwise --clean
would risk deleting assets still referenced by
idempotent-skipped pages. See
reference/asset-bundling.md § Stale asset cleanup.
--pin-timestamp <ISO8601> — pin the migrate-provenance
timestamp so re-runs without source changes produce byte-
identical HTML. Default re-uses the current wall clock, which
is fine for normal use; CI deployment fingerprinting may want
the pin.
The mobile-adapt audit, content-sourcing scan, and placeholder
refusal are all mandatory gates — there is no --skip-* or
--allow-* flag to bypass them. If a gate refuses a page, the
remediation is to fix the proposed file (re-prototype, edit
inline, or run an impeccable command) and re-invoke migrate.
Setup
Playwright re-probe (mandatory first step). --no-save playwright
installs from earlier phases are pruned by any later real npm i
(extract SKILL.md § Setup → --no-save installs are ephemeral). Before
any rendering step, probe
node -e "import('playwright').then(()=>process.exit(0))" from the
project root and re-install (npm i -D playwright --no-save --legacy-peer-deps) on failure.
Run the master skill's setup
(skills/stardust/SKILL.md § Setup). Flow guard. If
stardust/state.json exists without flow and the ask is a
migration (a URL plus "migrate" / "to EDS" / "re-platform"), do not
run: print the two-flow table from the master skill § Two migration
flows and hand back to its routing — the flow is chosen and stamped
there before any sub-skill runs
(skills/stardust/reference/state-machine.md § Flow keys): replica
unless the ask names a redesign.
(Recorded: migrate <url> as the first command of two same-design
migrations led to a hand-built compiler tuned by eye instead of the
replica gate.)
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.
Verify stardust/canon/ exists with at least
header.html, footer.html, canon.css.
Canon auto-bootstrap (when steps 3–4 find no canon). The
documented prototype → migrate → deploy happy path does not
run prepare-migration, so a first migrate legitimately arrives
with no canon (observed on 4 of 6 e2e sites, where every run had
to derive canon by hand to proceed — this is the fix). When
canon is absent and at least one approved prototype exists,
do not stop: run the canon write-back inline from the first
approved prototype (the canon-author, default home) per
../prototype/reference/canon-extraction.md § Five-step
procedure — extract header.html / footer.html / canon.css
to stardust/canon/, pin tokens + compositional moves to
DESIGN.json.extensions.canon, and record
canon.source: "auto-bootstrap: <slug>". This is exactly what
prototype --prep does on first approval; migrate performs it
on demand so the core pipeline never dead-ends. Only stop and
recommend $stardust prepare-migration when canon is absent
and no approved prototype exists (there is nothing to derive
canon from). Under state.json.handsOff the bootstrap is
automatic and logged; interactively, surface it as a one-line
notice before proceeding.
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 / 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 — the audit is mandatory; there is no
skip flag. The user fixes the proposed file (re-prototype or
chat-driven impeccable command) and re-invokes migrate.
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.
Procedure
Phase 1 — Plan
Dynamic-surface precondition (safety net). If
stardust/dynamic-features.md is missing, the hand-run flow
(extract → direct → prototype → migrate) never passed a pre-import
gate: run the stardust dynamics skill Phases 1–3 now (extract --dynamics
for reach if needed, detector on the archetypes, triage draft, curate)
before rendering any page. Never import a site as static without a
decision per dynamic row. Per page, rows of the inventory that touch it
become contentDeviations[] kind: "dynamic-dependency" entries
(reference/content-preservation.md § Dynamic dependencies).
Gated-archetype precondition (flow: replica). Before rendering any
sibling-tier page, read stardust/replica/progress.json: the page
type's archetype must have a gate result at every configured breakpoint
that is pass: true, or over the bar with every residual carrying a
cause (../replica/reference/source-fidelity-gate.md § Residual
logging format — a documented residual is a pass with an asterisk). An
archetype never gated, or over the bar with no residual entries, blocks
its page type: report the archetype slug and $stardust replica <archetype>, and render nothing for that type. The same rule guards
rollout Setup; the published-origin re-gate is unchanged. Thresholds
are the gate's.
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.
Phase 2 — Per-page render
In the replica flow a sibling renders only after its archetype is deployed and gated at the
published origin (../replica/reference/handoff-contract.md § 3 row C, unit C-archetype; #126);
the render is the encoder's input, its gate is the row after PUT. 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 when
[data-placeholder]
elements or non-empty _provenance.unsourcedContent[] are
present — the user fills the missing content in the proposed
file before re-invoking migrate. No bypass flag: shipping
placeholders to a public site is the failure mode this gate
exists to prevent. Widget mounts are links (a[data-widget]),
never data-placeholder, so the gate does not fire on them.
- Render branch selection (LLM judgment per T&M §
Render path selection): A / A′ / B. Declare the page's
fidelityTier from the branch — A → archetype (craft-gated),
A′ → sibling (canon-fork, the cheap default for breadth — variance-probed
once per template before cloning, reference/fidelity-tiers.md § Sibling
variance probe; deltas become variant classes, never per-page forks),
B/bodyless → thin — per reference/fidelity-tiers.md. Record
fidelityTier, archetypeSource, template (the archetype's slug;
the archetype's own sidecar leaves it null), modules[] (the page's
block ids — composite sections only), widgets[] (derived from the
page's a[data-widget] mounts) and gatesPassed[] in
_meta.json so coverage shows what was craft-gated vs cloned and
rollout groups and dedups from the sidecars, without a census.
- 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.
- Content-count acceptance per
reference/fidelity-tiers.md § Content-count acceptance:
compare role-classified node counts (headings, body/list
nodes, CTAs, images) between the captured source page JSON
and the rendered result. A count drop in any class not
covered by a logged contentDeviations[] entry fails the
page — dropped-content importer bugs must surface here,
while the importer is still cheap to fix, not at a
downstream fidelity gate. Record the pass in
_meta.json#gatesPassed[] as "content-count".
- 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.
- Asset bundling. Scan the final HTML for asset references
(six detection shapes per
reference/asset-bundling.md § Detection), copy each unique
referenced subpath from stardust/current/assets/<subpath> to
stardust/migrated/assets/<subpath> (preserving subdir
structure), then rewrite every reference to the root-relative
form /assets/<subpath>. Cross-page dedup uses a
module-level Set seeded from
state.json.migrate.bundledAssets[]. Missing source assets
warn-and-skip per § Edge cases; the bundle stays internally
consistent.
- Media reconciliation. For every image not bundled to
same-origin (reused source-CDN URLs under Mode A image-reuse),
decide optimize/keep/rewrite/omit per
reference/media-reconciliation.md. Cross-origin <img> kept
as source URLs must skip createOptimizedPicture (it drops
the ?v= key and corrupts the rendition); broken URLs are
repaired (missing ?-delimiter, wrong host) or omitted, never
shipped as about:error. rollout re-runs the authoritative
network resolve at delivery (media-reconcile.mjs).
- Cinematic sibling (when
<slug>-cinematic.html exists).
Migrate consumes the STATIC prototype only — the cinematic layer
is never merged. Copy the motion assets (lenis.min.js,
lenis.min.css) from stardust/prototypes/ to
stardust/migrated/assets/motion/ (idempotent) for downstream
consumers (deploy/rollout decide whether to wire them), and
record cinematic-variant-not-consumed in the page's
_meta.json#migrationDecisions[].
- Write the migrated
index.html and the _meta.json
sidecar in the same directory. Provenance block as first
child of <head>. Record assetsBundled (count of unique
asset refs on this page) in _meta.json.
The mechanics of this phase are scripted:
node skills/migrate/scripts/migrate.mjs render <slug…|--all> (the
project copy runs from stardust/scripts/migrate/) builds the page
map, places each page at its URL-literal path, rewrites internal
links, bundles assets, composes <head> (provenance, :root,
canonical and JSON-LD defaults), validates strictly and writes the
sidecar, skipping pages whose input shas are unchanged. The judgments
it cannot make are recorded on the sidecar with gate, deviation,
decision, variant and modules on the same script; it never
advances pages[].status.
Recorded units. A whole-site render is bookkept as units in
stardust/migrate/progress.json, the shape of rollout's C-deliver unit
ledger (../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}. One plan unit (Phase 1), one render unit per template
cluster of at most ~8 siblings (migrate.mjs render <slug…> takes the
cluster's slug list), one assets unit when Phase 3 rehosts media, one
report unit (Phase 4). Per unit, in this order: the progress.json
write → the checkpoint commit → the next unit; a unit end is a safe
resume point, not a stop. A session resumed inside migrate reads the file
and runs only the units not done; a unit left running re-renders its
slugs — the driver is idempotent, unchanged pages are skipped. A recorded
run rendered 31 siblings through five parallel builders as one unit in
one session — its most expensive — with no resume point between the plan
and the final report.
Phase 3 — Sitewide assets and bundle finalisation
Per-page asset bundling already happened in Phase 2 (every
referenced media subpath is on disk under
stardust/migrated/assets/). Phase 3 fills in the sitewide
assets that no individual page references explicitly:
Copy stardust/current/assets/logo.<ext> to
stardust/migrated/assets/logo.<ext> (only if missing or
stale). Record under state.json.migrate.bundledAssets[].
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.
If --clean was passed, compute
stale = priorBundle.filter(p => !bundledAssets.has(p))
from state.json.migrate.bundledAssets[] and remove each
stale subpath from stardust/migrated/assets/. Record the
deletions under state.json.migrate.cleanedAssets[]. Per
reference/asset-bundling.md § Stale asset cleanup.
Verify portability. The bundle must work via file://,
at a webserver root, and at any subpath — "one shape, works
everywhere". Run every audit; any non-empty grep output or
non-zero fixture exit fails the run with the cited error
message:
# 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"
The audits are mandatory — there is no skip flag. The contract
is "self-contained, zip-and-deploy" and these audits are the
verifiers that back the claim.
Asset migration is idempotent — files are content-hashed and
copied only when missing; per-page bundling deduplicates across
the run.
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[].
- Write the top-level
migrate block per
skills/stardust/reference/migrate-output-format.md
§ State.json contract: selfContained: true, outputDir,
totalAssetsBundled, bundledAssets[], per-page
assetsBundled counts, missingAssets[], cleanedAssets[].
This is the forward-compat signal downstream consumers test
for.
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`
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
Outputs
| Path |
Purpose |
stardust/migrated/<source-url-path> |
Migrated page. Output path mirrors the source URL literally (see reference/migration-procedure.md § Output path mapping). The bundle is zip-and-deploy: drop on any static host at any path, or open index.html directly via file://. Every internal reference is relative to the page that emits it; nav targets carry an explicit index.html (or the source URL's literal filename) so file:// resolves without a server. |
| _meta.json sidecar |
Lives next to each migrated page. For <dir>/index.html the sidecar is <dir>/_meta.json; for <dir>/<name>.html the sidecar is <dir>/<name>._meta.json so multiple .html siblings don't collide. Per reference/migration-procedure.md § _meta.json sidecar. |
stardust/migrated/index.html |
The home page (special case). |
stardust/migrated/_meta.json |
Home sidecar. |
stardust/migrated/assets/logo.<ext> |
Brand logo (sitewide). |
stardust/migrated/assets/<subpath> |
Every asset referenced by any migrated page, bundled. Source subdir structure preserved verbatim. |
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, history, and the migrate block (selfContained: true, asset counts). |
The driver (node stardust/scripts/migrate/migrate.mjs render …) writes
the per-page rows above (index.html / <name>.html, _meta.json,
bundled assets/**) and the migrate block of state.json (pageMap[],
bundledAssets[], pages[], missingAssets[], lastRun); status
changes, robots.txt and sitemap.xml stay with Phases 3–4.
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).
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 --all 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.
Failure modes
- No directed pages. Recommend
$stardust direct (or
$stardust extract if no extracted state).
- No DESIGN.md or DESIGN.json. Recommend
$stardust direct.
- No canon, but an approved prototype exists. Do NOT stop —
auto-bootstrap canon from the canon-author inline (Setup step 4).
- No canon and no approved prototype. Recommend
$stardust prepare-migration (or approve a prototype first).
- 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. Refuse
(Phase 2 placeholder gate); surface the unsourced list and
recommend sourcing real content (re-prototype, or edit the
proposed file directly).
- 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.
What migrate does NOT do
- 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 any iteration loop. Iteration belongs to
prototype;
migrate consumes the result.
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.
reference/asset-bundling.md — detection / copy / rewrite
contract for the per-page asset-bundling phase.
skills/stardust/reference/migrate-output-format.md — the
self-contained-bundle contract downstream consumers can rely
on (asset reference shape, directory layout,
state.json.migrate block).
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.
1---2name: migrate-23description: Apply DESIGN, canon, and modules to every page in the inventory, producing a deployable static HTML site. Use to migrate or render the whole captured site into the redesigned static tree ("migrate the pages", "render the migrated site", "apply the design to all pages", "build the deployable site", "convert the approved prototype into the full site") — the page-rendering step between prototype and deploy/rollout. Three render branches (approved page, template-applied sibling, unique render), with a declared fidelity tier per page. Per-page, incremental, idempotent, content-preserving by default.4license: Apache-2.05compatibility: Requires Node 22+, Playwright with Chromium resolvable from the project, playwright-cli on PATH, and the impeccable skill (github.com/pbakaus/impeccable) installed alongside stardust.6metadata:7 source: https://skillmd.com/skills/adobe/migrate-28---910# stardust:migrate1112Apply the target spec authored by `direct`, the visual canon13written by `prototype --prep`, and the brand-module catalog14extracted during `prepare-migration` to every page in the15inventory. Produces a self-contained, deployable static HTML site16under `stardust/migrated/`. Per-page, incremental, idempotent.1718`migrate` is the final stardust phase. Output is platform-19agnostic HTML — downstream conversion (AEM EDS, a CMS, a20framework) is the job of a separate plugin that consumes21`migrated/` plus `DESIGN.json` plus the per-page `_meta.json`22sidecars.2324## Inputs2526- `<slug>` — optional positional. Migrate just this page. Without27 it, migrate every page whose status is `directed`,28 `prototyped`, or `approved` (and not `stale`).29- `--all` — migrate every page including stale ones.30- `--force` — re-migrate every page even when the idempotent31 skip would skip them.32- `--require-approved` — refuse to migrate any non-`approved`33 page. Default behaviour migrates `directed` pages too (using34 Path A′ or Path B per35 `reference/template-and-module-rendering.md`); this flag flips36 approval-gating on.37- `--strict-canon` — refuse approvals that conflict with canon.38 Default logs the deviation and continues. Useful for projects39 where canon discipline matters more than per-template40 flexibility.41- `--clean` — delete assets previously bundled but no longer42 referenced from `stardust/migrated/assets/`. Off by default43 (migrate is additive). **Implies `--force`**: every page is44 re-rendered so the run's `bundledAssets` Set is the complete45 union of currently-referenced assets — otherwise `--clean`46 would risk deleting assets still referenced by47 idempotent-skipped pages. See48 `reference/asset-bundling.md` § Stale asset cleanup.49- `--pin-timestamp <ISO8601>` — pin the migrate-provenance50 timestamp so re-runs without source changes produce byte-51 identical HTML. Default re-uses the current wall clock, which52 is fine for normal use; CI deployment fingerprinting may want53 the pin.5455The mobile-adapt audit, content-sourcing scan, and placeholder56refusal are all mandatory gates — there is no `--skip-*` or57`--allow-*` flag to bypass them. If a gate refuses a page, the58remediation is to fix the proposed file (re-prototype, edit59inline, or run an impeccable command) and re-invoke migrate.6061## Setup62630. **Playwright re-probe (mandatory first step).** `--no-save` playwright64 installs from earlier phases are pruned by any later real `npm i`65 (extract SKILL.md § Setup → `--no-save` installs are ephemeral). Before66 any rendering step, probe67 `node -e "import('playwright').then(()=>process.exit(0))"` from the68 project root and re-install (`npm i -D playwright --no-save69 --legacy-peer-deps`) on failure.701. Run the master skill's setup71 (`skills/stardust/SKILL.md` § Setup). **Flow guard.** If72 `stardust/state.json` exists without `flow` and the ask is a73 migration (a URL plus "migrate" / "to EDS" / "re-platform"), do not74 run: print the two-flow table from the master skill § Two migration75 flows and hand back to its routing — the flow is chosen and stamped76 there before any sub-skill runs77 (`skills/stardust/reference/state-machine.md` § Flow keys): `replica`78 unless the ask names a redesign.79 (Recorded: `migrate <url>` as the first command of two same-design80 migrations led to a hand-built compiler tuned by eye instead of the81 replica gate.)822. Verify `stardust/state.json` exists with at least one83 `directed` page.843. Verify project-root `DESIGN.md` and `DESIGN.json` exist with85 `DESIGN.json.extensions.canon` populated.864. Verify `stardust/canon/` exists with at least87 `header.html`, `footer.html`, `canon.css`.8889 **Canon auto-bootstrap (when steps 3–4 find no canon).** The90 documented `prototype → migrate → deploy` happy path does not91 run `prepare-migration`, so a first migrate legitimately arrives92 with no canon (observed on 4 of 6 e2e sites, where every run had93 to derive canon by hand to proceed — this is the fix). When94 canon is absent **and** at least one `approved` prototype exists,95 do not stop: run the canon write-back inline from the first96 approved prototype (the canon-author, default `home`) per97 `../prototype/reference/canon-extraction.md` § Five-step98 procedure — extract `header.html` / `footer.html` / `canon.css`99 to `stardust/canon/`, pin tokens + compositional moves to100 `DESIGN.json.extensions.canon`, and record101 `canon.source: "auto-bootstrap: <slug>"`. This is exactly what102 `prototype --prep` does on first approval; migrate performs it103 on demand so the core pipeline never dead-ends. Only stop and104 recommend `$stardust prepare-migration` when canon is absent105 **and** no approved prototype exists (there is nothing to derive106 canon from). Under `state.json.handsOff` the bootstrap is107 automatic and logged; interactively, surface it as a one-line108 notice before proceeding.1095. Verify `stardust/direction.md` has an active (not pending)110 direction.1116. Read `state.json.pages[]` and partition into:112 - **inScope**: status `directed`, `prototyped`, or113 `approved`, `stale: false` (or `--all` / explicit114 `<slug>`).115 - **skipped**: everything else, with reason captured.1167. **Validate provenance on every in-scope page.** Call117 `validateProvenance(page)` per118 `skills/stardust/reference/state-machine.md` § Provenance119 validation for every page in `inScope`. Abort with the120 helper's error when any page lacks live-render evidence —121 migrating a synthesized page record produces deployable HTML122 that misrepresents the source site, the exact failure mode123 that motivated the validator. Surface `Provenance OK on N124 pages` in the migrate-plan output before Phase 1.1258. **Mobile-adapt audit on every Path A / Path A′ source.** For126 every page whose render branch consumes a proposed or127 archetype HTML file (Path A, Path A′ per128 `reference/template-and-module-rendering.md` § Render path129 selection), run the audit per `skills/prototype/SKILL.md`130 § Mobile-adapt audit:131132 - `<meta name="viewport" content="width=device-width, ...">`133 present, width not pinned to a fixed pixel value.134 - At least one `@media (max-width: ...)` rule.135 - At least one mobile-targeted breakpoint at ≤ 640px.136137 Refuse pages that fail — the audit is mandatory; there is no138 skip flag. The user fixes the proposed file (re-prototype or139 chat-driven impeccable command) and re-invokes migrate.140 Record the audit result per page in the migrate report and141 in the post-render `_meta.json#audit.adapt` sidecar. Path B142 (unique-renders) skips the audit because adapt hasn't run143 on those pages — a Path B page that needs mobile coverage144 gets it via `$impeccable adapt` invoked separately by the145 user. Surface this distinction in the report so it's not146 read as a silent skip.147148## Procedure149150### Phase 1 — Plan151152**Dynamic-surface precondition (safety net).** If153`stardust/dynamic-features.md` is missing, the hand-run flow154(`extract → direct → prototype → migrate`) never passed a pre-import155gate: run the stardust `dynamics` skill Phases 1–3 now (`extract --dynamics`156for reach if needed, detector on the archetypes, triage draft, curate)157before rendering any page. Never import a site as static without a158decision per dynamic row. Per page, rows of the inventory that touch it159become `contentDeviations[]` `kind: "dynamic-dependency"` entries160(`reference/content-preservation.md § Dynamic dependencies`).161162**Gated-archetype precondition (`flow: replica`).** Before rendering any163`sibling`-tier page, read `stardust/replica/progress.json`: the page164type's archetype must have a gate result at every configured breakpoint165that is `pass: true`, or over the bar with every residual carrying a166`cause` (`../replica/reference/source-fidelity-gate.md` § Residual167logging format — a documented residual is a pass with an asterisk). An168archetype never gated, or over the bar with no residual entries, blocks169its page type: report the archetype slug and `$stardust replica170<archetype>`, and render nothing for that type. The same rule guards171`rollout` Setup; the published-origin re-gate is unchanged. Thresholds172are the gate's.173174Print the plan and wait for confirmation when the scope is large:175176```177migrate plan178============179180In scope: 127 pages181 Path A (approved) 6 pages: home, news/post-housing-summit, news, ...182 Path A' (template-applied) 118 pages: 84 article, 5 listing, 11 program, 2 form, 16 static183 Path B (unique) 3 pages: 404, search, faq184185Skipped: 0 stale, 0 unscoped186187DESIGN.md sha: 1a2b3c4188DESIGN.json sha: 5d6e7f8189Canon shas: header:7g8h9i footer:9i0j1k css:1k2l3m190191Output: stardust/migrated/ + per-page _meta.json sidecars192Idempotent skip: enabled (run with --force to override)193194Reply "go" to proceed.195```196197For 1-3 pages or `<slug>` invocation, skip the confirmation.198199### Phase 2 — Per-page render200201In the replica flow a sibling renders only after its archetype is deployed and gated at the202published origin (`../replica/reference/handoff-contract.md` § 3 row C, unit `C-archetype`; #126);203the render is the encoder's input, its gate is the row after PUT. For each page in scope, follow204`reference/migration-procedure.md` and205`reference/template-and-module-rendering.md`:206207- **Idempotent skip check** first (sha-compare across208 `designMd`, `designJson`, `sourceCurrent`, `sourceProposed`,209 `canonShas`, `archetypeSource`).210- **Placeholder gate** (Path A and Path A′ only — pages with a211 proposed file or archetype). Refuse when `[data-placeholder]`212 elements or non-empty `_provenance.unsourcedContent[]` are213 present — the user fills the missing content in the proposed214 file before re-invoking migrate. No bypass flag: shipping215 placeholders to a public site is the failure mode this gate216 exists to prevent. Widget mounts are links (`a[data-widget]`),217 never `data-placeholder`, so the gate does not fire on them.218- **Render branch selection** (LLM judgment per T&M §219 Render path selection): A / A′ / B. **Declare the page's220 `fidelityTier`** from the branch — A → `archetype` (craft-gated),221 A′ → `sibling` (canon-fork, the cheap default for breadth — variance-probed222 once per template before cloning, `reference/fidelity-tiers.md` § Sibling223 variance probe; deltas become variant classes, never per-page forks),224 B/bodyless → `thin` — per `reference/fidelity-tiers.md`. Record225 `fidelityTier`, `archetypeSource`, `template` (the archetype's slug;226 the archetype's own sidecar leaves it null), `modules[]` (the page's227 block ids — composite sections only), `widgets[]` (derived from the228 page's `a[data-widget]` mounts) and `gatesPassed[]` in229 `_meta.json` so coverage shows what was craft-gated vs cloned and230 rollout groups and dedups from the sidecars, without a census.231- **Render** per the chosen branch's procedure in T&M.232- **Canon application** — chrome injection, canon.css233 injection, deviation logging.234- **Module rendering** — render module instances via235 `stardust/canon/modules/<id>.html`; bespoke slots logged236 with `data-bespoke`.237- **Apply content-preservation rules** per238 `reference/content-preservation.md`. Internal-link rewriting239 always emits migrated-tree paths; missing slugs flagged240 broken.241- **Content-count acceptance** per242 `reference/fidelity-tiers.md` § Content-count acceptance:243 compare role-classified node counts (headings, body/list244 nodes, CTAs, images) between the captured source page JSON245 and the rendered result. A count drop in any class not246 covered by a logged `contentDeviations[]` entry fails the247 page — dropped-content importer bugs must surface here,248 while the importer is still cheap to fix, not at a249 downstream fidelity gate. Record the pass in250 `_meta.json#gatesPassed[]` as `"content-count"`.251- **Compose `<head>` metadata** per252 `reference/metadata-and-jsonld.md` (five categories;253 page-type-driven JSON-LD).254- **Validate** per T&M § Validation contracts. Strict contracts255 refuse the page; soft contracts log and continue.256- **Compute output path** per migration-procedure.md257 § Output path mapping.258- **Asset bundling.** Scan the final HTML for asset references259 (six detection shapes per260 `reference/asset-bundling.md` § Detection), copy each unique261 referenced subpath from `stardust/current/assets/<subpath>` to262 `stardust/migrated/assets/<subpath>` (preserving subdir263 structure), then rewrite every reference to the root-relative264 form `/assets/<subpath>`. Cross-page dedup uses a265 module-level Set seeded from266 `state.json.migrate.bundledAssets[]`. Missing source assets267 warn-and-skip per § Edge cases; the bundle stays internally268 consistent.269- **Media reconciliation.** For every image **not** bundled to270 same-origin (reused source-CDN URLs under Mode A image-reuse),271 decide optimize/keep/rewrite/omit per272 `reference/media-reconciliation.md`. Cross-origin `<img>` kept273 as source URLs must **skip `createOptimizedPicture`** (it drops274 the `?v=` key and corrupts the rendition); broken URLs are275 repaired (missing `?`-delimiter, wrong host) or omitted, never276 shipped as `about:error`. `rollout` re-runs the authoritative277 network resolve at delivery (`media-reconcile.mjs`).278- **Cinematic sibling (when `<slug>-cinematic.html` exists).**279 Migrate consumes the STATIC prototype only — the cinematic layer280 is never merged. Copy the motion assets (`lenis.min.js`,281 `lenis.min.css`) from `stardust/prototypes/` to282 `stardust/migrated/assets/motion/` (idempotent) for downstream283 consumers (deploy/rollout decide whether to wire them), and284 record `cinematic-variant-not-consumed` in the page's285 `_meta.json#migrationDecisions[]`.286- **Write** the migrated `index.html` and the `_meta.json`287 sidecar in the same directory. Provenance block as first288 child of `<head>`. Record `assetsBundled` (count of unique289 asset refs on this page) in `_meta.json`.290291The mechanics of this phase are scripted:292`node skills/migrate/scripts/migrate.mjs render <slug…|--all>` (the293project copy runs from `stardust/scripts/migrate/`) builds the page294map, places each page at its URL-literal path, rewrites internal295links, bundles assets, composes `<head>` (provenance, `:root`,296canonical and JSON-LD defaults), validates strictly and writes the297sidecar, skipping pages whose input shas are unchanged. The judgments298it cannot make are recorded on the sidecar with `gate`, `deviation`,299`decision`, `variant` and `modules` on the same script; it never300advances `pages[].status`.301302**Recorded units.** A whole-site render is bookkept as units in303`stardust/migrate/progress.json`, the shape of rollout's C-deliver unit304ledger (`../replica/reference/handoff-contract.md` § 3 row C):305`units.<name>: {status: pending|running|done|failed, kind:306plan|render|assets|report, templates[], pages: n, startedAt, endedAt,307verdict}`. One `plan` unit (Phase 1), one `render` unit per template308cluster of at most ~8 siblings (`migrate.mjs render <slug…>` takes the309cluster's slug list), one `assets` unit when Phase 3 rehosts media, one310`report` unit (Phase 4). Per unit, in this order: the `progress.json`311write → the checkpoint commit → the next unit; a unit end is a safe312resume point, not a stop. A session resumed inside migrate reads the file313and runs only the units not `done`; a unit left `running` re-renders its314slugs — the driver is idempotent, unchanged pages are skipped. A recorded315run rendered 31 siblings through five parallel builders as one unit in316one session — its most expensive — with no resume point between the plan317and the final report.318319### Phase 3 — Sitewide assets and bundle finalisation320321Per-page asset bundling already happened in Phase 2 (every322referenced media subpath is on disk under323`stardust/migrated/assets/`). Phase 3 fills in the **sitewide324assets** that no individual page references explicitly:3253261. Copy `stardust/current/assets/logo.<ext>` to327 `stardust/migrated/assets/logo.<ext>` (only if missing or328 stale). Record under `state.json.migrate.bundledAssets[]`.3292. Verify favicon variants and font files were generated by330 `prepare-migration` Phase 4. If absent, log a warning and331 continue (the migrated site renders without them, just332 missing some platform-specific affordances).3333. Add `stardust/migrated/robots.txt` and `sitemap.xml`334 derived from the migrated page inventory per335 `reference/metadata-and-jsonld.md` § Sitemap entry.3364. If `--clean` was passed, compute337 `stale = priorBundle.filter(p => !bundledAssets.has(p))`338 from `state.json.migrate.bundledAssets[]` and remove each339 stale subpath from `stardust/migrated/assets/`. Record the340 deletions under `state.json.migrate.cleanedAssets[]`. Per341 `reference/asset-bundling.md` § Stale asset cleanup.3425. Verify **portability**. The bundle must work via `file://`,343 at a webserver root, and at any subpath — "one shape, works344 everywhere". Run every audit; any non-empty grep output or345 non-zero fixture exit fails the run with the cited error346 message:347348 ```bash349 # No source-tree escapes350 find stardust/migrated/ -type f -name '*.html' -exec grep -l '\.\./current/' {} +351 # Error: "asset still points outside the migrated tree; rewrite via the352 # asset-bundling pass per reference/asset-bundling.md § Detection"353354 # No absolute internal references in attribute values (404 on file:// and subpath)355 grep -rE '(href|src)="/[^/]' stardust/migrated/ --include='*.html'356 # Error: "absolute href `/beers/` will 404 on file:// and on subpath hosts;357 # rewrite via the page map per migration-procedure.md § Reference shape"358359 # No absolute internal references in url() (inline style, <style> blocks, CSS)360 grep -rE 'url\(\s*["''']?\s*/[^/]' stardust/migrated/ --include='*.html' --include='*.css'361 # Error: "absolute url(/...) reference will 404 on file:// and on subpath hosts;362 # rewrite via the asset-bundling pass per asset-bundling.md § Rewrite"363364 # No directory-only nav (doesn't resolve on file://). Pattern accepts365 # only relative or root-absolute hrefs (./, ../, /, or bare segment)366 # so external URLs like https://google.com/ aren't false-flagged.367 grep -rE 'href="(\.{0,2}/|[a-zA-Z0-9_-])[^:"#?]*/"' stardust/migrated/ --include='*.html'368 # Error: "directory-only href `./beers/` won't resolve on file://;369 # append the explicit index.html (or the source URL's .html leaf)370 # per § Reference shape"371372 # pageMap consistency — every internal href appears as an outputPath373 node skills/migrate/fixtures/pagemap-audit.mjs stardust/migrated/ stardust/state.json374 # Error: "internal href has no pageMap entry; link rewriting bypassed the375 # page map per § Page map (build once, use everywhere)"376377 # Headless file:// round-trip — the test that proves zip-and-deploy works378 node skills/migrate/fixtures/file-protocol-audit.mjs stardust/migrated/379 # Error: "<offending file> linked <ref> that 404s under file://; see the380 # Playwright network log printed above"381 ```382383 The audits are mandatory — there is no skip flag. The contract384 is "self-contained, zip-and-deploy" and these audits are the385 verifiers that back the claim.386387Asset migration is idempotent — files are content-hashed and388copied only when missing; per-page bundling deduplicates across389the run.390391### Phase 4 — State and report392393Update `state.json`:394395- For each successfully migrated page: `status` advances to396 `migrated`, append a history entry, clear any `stale` flag,397 set `migratedPath`.398- For pages skipped via idempotent skip: leave state399 unchanged.400- For pages that failed validation: leave state unchanged, log401 the failure in `state.json.lastRun.failures[]`.402- Write the top-level `migrate` block per403 `skills/stardust/reference/migrate-output-format.md`404 § State.json contract: `selfContained: true`, `outputDir`,405 `totalAssetsBundled`, `bundledAssets[]`, per-page406 `assetsBundled` counts, `missingAssets[]`, `cleanedAssets[]`.407 This is the forward-compat signal downstream consumers test408 for.409410Print the run summary:411412```413migrate complete414================415416 122 migrated home, about, news/post-housing-summit, ...417 3 unchanged about, programs/shelter, news/post-old (idempotent skip)418 2 failed contact (validation: required slot missing),419 legal/privacy (validation: color-reservation violated)420 0 stale skipped421422Render branches:423 Path A 6 approved-from-prototype424 Path A' 116 template-applied (84 article, 5 listing, 11 program, 2 form, 14 static)425 Path B 3 unique-render (404, search, faq)426427Pages with non-trivial decisions: 12428 about canon-deviation: footer carries financials disclaimer429 donate template-adapted: amount-pills slot moved above headline430 ...431432Broken internal links: 5433 /events referenced by 2 pages; not in inventory434 /press referenced by 1 page; not in inventory435 ...436437Bespoke slots crossing promotion threshold: 1438 hotline-211: "state" (3 instances) — consider `$stardust prepare-migration --refine-module`439440Missing assets: 2441 generated/orphan-1.jpg referenced by 1 page (home)442 generated/orphan-2.jpg referenced by 2 pages (about, contact)443 (Re-extract or accept the gap — bundle is deployable; refs 404 at view time.)444445Output: stardust/migrated/ (122 pages, 47 bundled assets, 4.2 MB) — self-contained, zip-and-deploy446447Next:448 - Review: open stardust/migrated/index.html in a browser449 - Audit: $impeccable critique stardust/migrated/450 - Deploy: cd stardust/migrated && zip -r ../site.zip .451 upload the zip to any static host that serves at the host root452 - Refine: edit DESIGN.md or canon files, then re-run $stardust migrate453```454455## Outputs456457| Path | Purpose |458|---------------------------------------------------|--------------------------------------------------------|459| `stardust/migrated/<source-url-path>` | Migrated page. Output path mirrors the source URL literally (see `reference/migration-procedure.md` § Output path mapping). The bundle is **zip-and-deploy**: drop on any static host at any path, or open `index.html` directly via `file://`. Every internal reference is relative to the page that emits it; nav targets carry an explicit `index.html` (or the source URL's literal filename) so file:// resolves without a server. |460| _meta.json sidecar | Lives next to each migrated page. For `<dir>/index.html` the sidecar is `<dir>/_meta.json`; for `<dir>/<name>.html` the sidecar is `<dir>/<name>._meta.json` so multiple `.html` siblings don't collide. Per `reference/migration-procedure.md` § `_meta.json` sidecar. |461| `stardust/migrated/index.html` | The home page (special case). |462| `stardust/migrated/_meta.json` | Home sidecar. |463| `stardust/migrated/assets/logo.<ext>` | Brand logo (sitewide). |464| `stardust/migrated/assets/<subpath>` | Every asset referenced by any migrated page, bundled. Source subdir structure preserved verbatim. |465| `stardust/migrated/assets/favicon.<ext>` + variants| Favicon and apple-touch-icon, manifest icons. |466| `stardust/migrated/assets/fonts/...` | Downloaded font files (from canon @font-face URLs). |467| `stardust/migrated/robots.txt` | Minimal robots.txt. |468| `stardust/migrated/sitemap.xml` | Sitemap derived from migrated inventory + page types. |469| `stardust/state.json` | Updated with `migrated` status, history, and the `migrate` block (`selfContained: true`, asset counts). |470471The driver (`node stardust/scripts/migrate/migrate.mjs render …`) writes472the per-page rows above (`index.html` / `<name>.html`, `_meta.json`,473bundled `assets/**`) and the `migrate` block of `state.json` (`pageMap[]`,474`bundledAssets[]`, `pages[]`, `missingAssets[]`, `lastRun`); status475changes, robots.txt and sitemap.xml stay with Phases 3–4.476477## Idempotent and incremental478479The whole pipeline is built around two properties:480481- **Idempotent.** Re-running `$stardust migrate` with no482 changes produces zero file writes. Every page is sha-compared483 across designMd, designJson, sourceCurrent, sourceProposed484 (Path A), canonShas, archetypeSource (Path A′) — and skipped485 if all match.486- **Incremental.** Migrate 5 pages today, 20 pages tomorrow,487 fix one page's content next week — the migrated tree is488 always the union of every successful migration to date.489490These properties hold even when DESIGN.md, canon, or modules are491edited mid-run: the edit changes the relevant sha, so the next492migrate run re-renders every affected page (canon and DESIGN.md493edits typically affect every page).494495## Stale handling496497When `direction.md`, canon, or the module catalog changes after498some pages have been migrated:499500- Affected pages are flagged `stale: true` per501 `skills/stardust/reference/state-machine.md` § Stale flagging.502 Stale-flagging is content-aware in all three trigger cases.503- `$stardust migrate` (no flags) skips stale pages and reports504 the count.505- `$stardust migrate --all` re-migrates each stale page,506 clearing the flag on success.507- `$stardust migrate <slug>` always operates on the named page,508 stale or not.509510The user decides whether stale pages should be refreshed —511direction/canon/module changes don't invalidate prior migrated512work, they just mark it as out-of-step.513514## Failure modes515516- **No directed pages.** Recommend `$stardust direct` (or517 `$stardust extract` if no extracted state).518- **No DESIGN.md or DESIGN.json.** Recommend `$stardust direct`.519- **No canon, but an approved prototype exists.** Do NOT stop —520 auto-bootstrap canon from the canon-author inline (Setup step 4).521- **No canon and no approved prototype.** Recommend522 `$stardust prepare-migration` (or approve a prototype first).523- **Pending direction.** Refuse; user must resolve direction524 first.525- **Validation failure on a single page.** Skip that page,526 continue, log the failure under527 `state.json.lastRun.failures[]`. Do not abort the whole run.528- **Asset copy failure.** Continue the run; record the missing529 asset in the page's `migrationDecisions[]` with530 `kind: "asset-missing"`. The migrated `<img src>` keeps the531 original absolute URL as a fallback.532- **Output path collision.** Two slugs mapping to the same533 output path. Refuse to write the second one and surface to534 the user — manual slug rename needed.535- **Placeholder content in proposed/archetype file.** Refuse536 (Phase 2 placeholder gate); surface the unsourced list and537 recommend sourcing real content (re-prototype, or edit the538 proposed file directly).539- **Color reservation violated.** Refuse the page; surface to540 user with the offending color and the reserved-for context.541- **Brand-faithful inversion conflict.** A hard rule declared542 inverted in543 `extensions.divergence.brand_faithful_inversions[]` is lifted544 from validation per T&M § Brand-faithful inversion handling.545 Emit a one-line note in the run summary acknowledging the546 lift.547548## What migrate does NOT do549550- Critique or audit the migrated output. Run551 `$impeccable critique stardust/migrated/` after migration if552 you want a quality assessment.553- Deploy. Stardust does not push, upload, or modify origin.554- Generate AEM EDS, a CMS payload, or framework components. The555 output is platform-agnostic static HTML; downstream conversion556 is a separate plugin's job.557- Re-fetch the live site. Offline after extract Phase 1.558- Run any iteration loop. Iteration belongs to `prototype`;559 migrate consumes the result.560561## References562563- `reference/migration-procedure.md` — per-page render procedure,564 output path mapping, validation, provenance shape, idempotent565 skip, sidecar schema.566- `reference/template-and-module-rendering.md` — three render567 branches in detail, slot injection, deviation policy,568 validation contracts.569- `reference/metadata-and-jsonld.md` — head composition, JSON-LD570 per page-type, canonical strategy.571- `reference/content-preservation.md` — what's kept,572 transformed, dropped; internal-link rewriting; asset path573 rewriting; form handling.574- `reference/asset-bundling.md` — detection / copy / rewrite575 contract for the per-page asset-bundling phase.576- `skills/stardust/reference/migrate-output-format.md` — the577 self-contained-bundle contract downstream consumers can rely578 on (asset reference shape, directory layout,579 `state.json.migrate` block).580- `skills/stardust/reference/token-contract.md` — `:root` block581 refreshed from DESIGN.md on every render.582- `skills/stardust/reference/data-attributes.md` — structural583 attributes including `data-template`, `data-module`,584 `data-slot`, `data-canon`, `data-deviation`, `data-bespoke`,585 `data-broken-link`.586- `skills/stardust/reference/state-machine.md` — page lifecycle,587 page typing, stale-flagging cascade.588- `skills/stardust/reference/artifact-map.md` — provenance shape589 for migrated artifacts; canon files; sidecar shape.590- `skills/prototype/reference/canon-extraction.md` — how canon591 is built (input to migrate).592- `skills/prepare-migration/SKILL.md` — the cascade that593 produces every input migrate consumes.