/migrate

name: migrate
description: 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.
license: Apache-2.0

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

0. **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. 1. Run the master skill's setup (`skills/stardust/SKILL.md` § Setup). 2. Verify `stardust/state.json` exists with at least one `directed` page. 3. Verify project-root `DESIGN.md` and `DESIGN.json` exist with `DESIGN.json.extensions.canon` populated. 4. 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. 5. Verify `stardust/direction.md` has an active (not pending) direction. 6. 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.

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