stardust:replica — same-design migration
Same pages, same content, same design — new platform. replica migrates a
site to AEM Edge Delivery (or just re-platforms its front end) keeping the
current design near pixel-perfect: the target spec IS the captured current
state, the only permitted deltas are the entries of an explicit
inconsistency register, and every archetype must pass a measured
source-fidelity gate against the live site before anything ships.
Two properties make this a different animal from the redesign pipeline:
- No creative decisions. The direction step is mechanical promotion of
the captured spec — the stardust
direct skill is never invoked. Every judgment
call in a replica run is a measurement-policy call, not a taste call.
- Recreation, not copying. Archetypes are authored as clean semantic
HTML/CSS from captured content + values lifted from the source site's own
CSS — never DOM copies, never ported page-level stylesheets. Fidelity is
proven by instruments, not asserted by construction.
Validated end-to-end (a typographic retail home page, 2026-07-03): 8.31% → 2.93% → 1.31%
pixel diff in 3 measured iterations, height Δ 0, content-diff "findings:
none" (198/198 nodes). Every fix came off the instruments, never off
eyeballing.
Inputs
<URL> — required. The site to migrate.
--breakpoints <list> — optional. Gate widths, default 1440,360; each
gets its own gate pass (mobile is not free — gate doc § Per-breakpoint).
--target-breakpoints <list> — optional. Mobile-first min-width steps
(e.g. 600,900,1200) the delivered site switches layout at instead of the
source's. Absent = source breakpoints kept, every target step below
skipped. Persisted in DESIGN.json extensions.breakpoints.target.
--register <file> — optional. User-supplied inconsistency items to seed
the register (see Phase 2). Without it and without an audit, the register
is empty — a pure replica.
--first-page <url|home> — optional; hands-off home. The page a
full-site run delivers first (reference/first-page-first.md).
Setup
- Run the master skill's setup (
../stardust/SKILL.md § Setup): context
loader, state read. Flow guard. If state.json.flow is
redesign, refuse: print the never-mix line and the switch command
($stardust replica --switch-flow, which marks the redesign flow's
prototyped and migrated pages stale — master skill § Two migration
flows). If flow is absent, stamp flow: "replica",
flowSource: "user-phrase" (../stardust/reference/state-machine.md
§ Flow keys): invoking replica is the choice.
- Verify Playwright is importable from the project root (extract needs it;
so do the gate scripts).
- Probe the gate's deps from the project root first —
node -e "import('pixelmatch').then(()=>process.exit(0))" (and playwright,
pngjs, cheerio) — and only on failure install them AS devDependencies,
never --no-save: npm i -D playwright pixelmatch pngjs cheerio --legacy-peer-deps (../extract/SKILL.md § Setup). A harness that already
resolves them leaves the delivered code repo untouched; the
devDependencies otherwise land in the repo the skills push. Run every
probe from the project root: ESM resolves playwright from the script's
own location.
- Copy scripts into the project and run them from there, not from the
plugin: this skill's whole
scripts/ dir to
stardust/scripts/replica/, the master skill's ../stardust/scripts/
(ledger.mjs, state.mjs) to stardust/scripts/stardust/, the migrate
skill's ../migrate/scripts/ (migrate.mjs) to stardust/scripts/migrate/,
AND the whole
../diff/scripts/ dir to stardust/scripts/diff/ (the diff scripts
import diff-profiles.mjs, and ALL live-target hardening — including
stitch-shot's — lives in its live-session.mjs; stitch-shot resolves it
from stardust/scripts/diff/ next to stardust/scripts/replica/, so
keep the two dirs siblings). Never copy into the project-root
scripts/ — that is the EDS boilerplate's directory (master skill
§ Artifacts, the write boundary).
Reading and inspection discipline — the context is the budget
(reference/reading-discipline.md, read it once at Setup). Every byte a
step prints is re-read on every later model call (recorded: 750k characters
of tool output in one 77-minute session). The rules in one line each:
reference docs by section (section.mjs <doc> --list, then one heading, one
section per call); captured CSS through css-rules.mjs, capture JSON through
json-query.mjs (values that feed a command from --tsv/--path, never the
table), captured HTML through html-slice.mjs; instrument output through
run-bg.mjs wait and log --grep, never cat; live-vs-prototype boxes
through measure.mjs, never an authored probe; images one crop per fact,
never a stitched page or the live/build/diff triplet (the extract thumbnail,
thumb.mjs, is the one exception); script flags from
../stardust/reference/scripts-index.md first, then --help, never the
source. Write anything you will need again to a file under stardust/ and
read it back by query.
Procedure
Five phases. Phases 1 and 5 delegate to existing skills unchanged; phases
2–4 are owned by replica. A full-site run opens first page first:
reference/first-page-first.md.
Phase 1 — EXTRACT (delegate to $stardust extract --prep --dynamics)
Invoke $stardust extract <URL> --prep, unchanged. Prep mode is required —
replica consumes the full migration inventory, not the discovery cap:
stardust/current/pages/<slug>.json — per-page structure + content
(verbatim source of every string the prototypes will carry).
stardust/current/assets/screenshots/ — per-page captures (ground truth
for recreation, alongside the gate's own stitched shots).
stardust/current/assets/ — fonts (network-intercepted woff2), logo, media.
stardust/current/PRODUCT.md, DESIGN.md, DESIGN.json — the descriptive
current state (Phase 2 promotes these verbatim).
state.json.pages[].type — page types (each becomes one archetype).
DESIGN.json.extensions.modules[] — module candidates (become blocks).
When extract's summary comes back, surface it with the flow line first —
"Flow: replica — the design is kept. Say switch to redesign now if it is
to change." — so the first thing the user sees in this flow is the choice
it rests on. switch to redesign runs $stardust prepare-migration --switch-flow; the extract is reused, nothing else is.
Bounded/single-page entry (one-page or pilot runs). --prep is the
site-wide contract; it is NOT the only way in. When the ask is "replicate
just this page" — or the user wants to pilot one archetype before committing
to a full migration — invoke $stardust extract <URL> --single --dynamics
(or --pages <slug,...> --dynamics for a short list) instead. This is a first-class entry,
not an improvisation: the recreation phase needs, per page, the captured
page JSON (verbatim content), the per-page screenshot (ground truth), and
the captured fonts — all of which a bounded extract provides; the source-CSS
harvest and per-breakpoint computed styles come from Phase 3's CSS lifting
either way. What a bounded run skips is the prep-only inventory (page
typing, module detection), which is only needed when Phase 5 fans out to
siblings, and the descriptive synthesis (Phase 2 takes the bounded
promotion branch, reference/preserve-direction.md § 1a).
Extract's failure modes apply as-is (bot-management headed fallback, consent
handling, no-synthesis rule). If extract had to fall back to headed Chrome,
expect the gate captures to need the same treatment.
Phase 2 — PRESERVE DIRECTION (mechanical — never invoke the stardust direct skill)
Full contract: reference/preserve-direction.md. Summary:
Promote stardust/current/PRODUCT.md, DESIGN.md, DESIGN.json
verbatim to the project root as the target spec. No divergence roll, no
re-direction, no Mode A/B — the current state IS the target. Bounded
entry (--single/--pages): those files don't exist — take the
bounded promotion branch instead (reference/preserve-direction.md
§ 1a): synthesize a minimal descriptive spec from the captured page JSON
- the Phase-3 CSS lift (palette, type ramp, container, buttons — exactly
the values the lift produces anyway), provenance
bounded-single. Never
mix the branches: if current/PRODUCT.md exists, promotion is verbatim
(first page first's Track A excepted).
Write stardust/direction.md recording preserve mode: what was
promoted, from where, provenance (verbatim --prep promotion vs
bounded-single synthesis), and the register pointer. This is what
tells downstream skills "the direction step happened".
Build the inconsistency register at
stardust/replica/inconsistency-register.md — the ONLY permitted design
deltas, the "almost" in almost-pixel-perfect. Sources: the stardust audit skill
design findings (run audit only if the user wants improvement candidates)
and/or user-supplied items (--register). Every entry needs captured
evidence + the minimal change + a status. Empty register = pure
replica — that is a valid and common outcome, not a failure.
Target breakpoints (only with --target-breakpoints), before any
CSS exists (reference/preserve-direction.md § 4): persist the list, map
each source breakpoint to a step by intent in
stardust/replica/breakpoint-map.md, seed the ONE register entry. Phase 3
and C0 apply the map; they never decide it.
Dynamic surface (migration gate — the stardust dynamics skill Phases 1–3).
Phase 1 must have run extract --dynamics. Run the detector on the
archetypes, draft the triage (--target-origin when the EDS host is
known), curate stardust/dynamic-features.md + -plan.md. Every row
gets a disposition; the static recreation continues regardless. This is
what surfaces modals, players, forms, search, tags and host-bound APIs
that pixel gates certify as correct. Contract:
skills/dynamics/reference/triage.md.
Anything not in the register is out of scope for change. When a recreation
choice would "improve" something not registered, it is a fidelity bug.
Phase 3 — RECREATE (one archetype per page type)
Full method: reference/recreation-procedure.md. For each page type in the
inventory (archetype: the type's rep_url in a spec's archetypes.json), author stardust/prototypes/<slug>-proposed.html (+ per-page CSS)
as clean semantic HTML/CSS from three sources, in this order:
(a) Captured page JSON content — verbatim. Headings, body, CTAs+hrefs,
alt text, metadata from current/pages/<slug>.json. The migrate
content-preservation rules (../migrate/reference/content-preservation.md)
apply from the first line: no rewording, no fabrication.
(b) Exact values lifted from the source site's own CSS. Fetch the live
stylesheets; lift the type ramp, button specs, section paddings, radii,
shadows, hero heights. The container model is measured, not lifted —
DESIGN.json extensions.breakpoints (extract's cap-probe.mjs run; a bounded
entry runs cap-probe.mjs <live-url> --write-design stardust/current/DESIGN.json first).
Fidelity values come from the original site's CSS, not the eye — this
converts 3–4 guess-and-screenshot loops into one. Box-by-box comparison of
the live page against the served prototype goes through the shipped
measure.mjs (node stardust/scripts/replica/measure.mjs <live-url> --against <prototype-url> --selectors "<css>,…" — rect + computed values
per selector per width, one delta line each), never through an authored
probe.
(c) The captured screenshot as ground truth for everything CSS doesn't
name (composition, image crops, paint effects).
With a target set, every @media rule and JS width threshold
(matchMedia, innerWidth) is authored on the target steps from the first
line per breakpoint-map.md, never fixed later (a retrofit costs a full
re-gate); breakpoint-lint.mjs exits 0 on a prototype before its gate.
Every archetype gets its own standalone prototype — cumulative, never
skipped. Never skip to direct platform authoring for a new archetype:
prototyped archetypes stayed the quality ceiling in the field (3.5%/5.6%)
while direct-authored pages plateaued at 8–16%. Each new prototype imports
the shared layers earlier ones already gated (shared canon CSS + a
per-archetype file) and iterates only on its NEW modules — full contract:
reference/recreation-procedure.md § Cumulative archetype prototypes.
This is recreation, not redesign — do NOT delegate to impeccable craft.
Impeccable's redesign gates (critique, anti-template, divergence) do not
apply; the source-fidelity gate (Phase 4) replaces them entirely. A
"tastefully improved" section is a failing section.
Fonts: use the same public source when available (extract's intercepted
woff2 for open/self-hostable faces). For licensed commercial kits: never
rehost on the new domain — pick a metric-matched substitute, keep the brand
family name first in the font stack so a licensed drop-in later wins, and
surface the substitution to the user. (Prior art: an earlier airport-site migration's improvement notes, §3.7.)
CSS-portation is the per-section fallback only — paint-level effects not
recoverable from computed styles, JS-hydrated commerce widgets, video or
animated heroes. Port the minimal source rules for that section, scoped;
never page-level. Criteria in reference/recreation-procedure.md § Fallback.
Phase 4 — SOURCE-FIDELITY GATE (the heart — measured, per breakpoint)
Full contract: reference/source-fidelity-gate.md. Run per archetype, per
breakpoint (default 1440 AND 360), live URL as source vs served prototype:
PROTO="http://localhost:8791/<slug>-proposed.html" # python3 -m http.server from the prototypes dir
# ONE server, ONE port — probe with curl first (gate doc § Per-breakpoint procedure): no answer →
# start yours; answers but not your file → foreign server, never kill it, take a per-project port
curl -sI localhost:8791/<slug>-proposed.html | head -1 # 200 = it serves YOUR dir: reuse it
LIVE="https://<site>/<path>"
# One command per round — gate.sh, through run-bg. The FIRST round of a breakpoint and the
# CONFIRMATION round after the last fix run `--full` (pixel probe — stitched captures, NEVER
# fullPage:true — plus content-diff, visual-diff and chrome-parity under deadlines, one verdict
# line each, reports in the gate dir); rounds in between are pixel rounds. Never hand-write a
# wrapper around the instruments (a recorded one lost the deadlines; a round took 15 minutes).
# content-diff inside --full compares --main AND the header/footer roots by default — no chrome flag.
node stardust/scripts/replica/run-bg.mjs start --name <slug>-1440-iter1 -- \
stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 1440 iter1 --full --main "<content-root>"
node stardust/scripts/replica/run-bg.mjs start --name <slug>-360-iter1 -- \
stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 360 iter1 --full --main "<content-root>"
# A consent manager the built-in candidates miss: add --consent "<accept selector>" to every gate.sh
# round — it reaches both stitched captures and the probes alike (gate doc § Hardening rule 6).
node stardust/scripts/replica/run-bg.mjs wait # verdict lines: pixel %, height delta, hot bands, structural 🔴, flags, chrome deltas
# Iteration inner loop (gate doc § Band breakdown): anchor probe + pixel round
G=stardust/replica/gates/<slug>-1440
node stardust/scripts/replica/anchor.mjs "$LIVE" --width 1440 --cache $G/anchor-live.json # live side: probed once, reused
node stardust/scripts/replica/anchor.mjs "$PROTO" --width 1440 # build-side runs are free
# Chrome: computed-style parity BEFORE any pixel round on header/footer/strips
node stardust/scripts/replica/chrome-parity.mjs "$LIVE" "$PROTO" --width 1440 --live-cache $G/chrome-live.json # exit 0 = quiet, then crop-compare
# Every instrument runs real Chrome headless with its real user agent and client hints (#151); existing automation-signal handling stays on unless STARDUST_STEALTH=0; STARDUST_HEADED_WINDOW=1 opens the --headed window (#125).
# gate.sh: live.png cached, every step under a deadline (exit 124 = re-run, not FAIL). Rounds run in
# the BACKGROUND: start every round at once (the slots pace the Chromiums — no `sleep N;` staggering),
# then `wait` prints verdict lines only; exit 75 = still going → `wait` again as your NEXT step, never
# in a shell loop, never after a `sleep` (gate doc § Iteration discipline). A propagation wait is a
# bounded inline poll (`curl -sf` ≤ 5 s apart, capped), never a fixed sleep.
node stardust/scripts/replica/run-bg.mjs start --name <slug>-1440-iter2 -- stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 1440 iter2
node stardust/scripts/replica/run-bg.mjs start --name <slug>-360-iter2 -- stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 360 iter2
node stardust/scripts/replica/run-bg.mjs wait # returns within 100 s; full output: run-bg.mjs log <job> --grep <re>
# Content-cap row — once per archetype after the 1440 pass, at DESIGN.json's derived probeWidth (never a pinned 1920)
node stardust/scripts/replica/cap-probe.mjs "$LIVE" --against "$PROTO" --design DESIGN.json --slug <slug> --main "<content-root>"
gate.sh --help lists the flags and exit codes (124 = deadline, re-run, not
a verdict; 0 only when all four ran and passed).
Pass bar (all four per breakpoint, plus the content-cap row):
- content-diff: 0 🔴 and 0 nothing-lost 🟡 on the main and chrome roots (gate doc § Pass bar item 1);
- visual-diff: flags none or justified;
- pixel diff: ≤ 10% full-page, with no per-500px band left unexplained
(the band breakdown is the navigation instrument — fix the first hot band,
top-down; everything below it is offset-contaminated);
- height delta |Δ| ≤ 8px (pixel-compare's own warning bar);
- content-cap row:
cap-probe.mjs … --against prints cap-probe: PASS
(gate doc § Pass bar item 6 — every live cap held within ±20 px by kind,
nothing capped only on the prototype; a ✗ names the sizing rule, no pixel iteration);
- clip-probe:
Clipped: 0 on the build side (a --full round runs it; cut or hidden
text / controls fail the round like an over-threshold pixel diff — #125); a
declared repeated-unit family (stardust/replica/units.json, gate doc item 7)
within 4 px;
- and, outside the bar and outside the cap, the horizontal-overflow assert:
document.documentElement.scrollWidth within 4 px of the viewport
(integer rounding; GATE_OVERFLOW_TOLERANCE) at every breakpoint on the
build side — gate.sh fails the round on more whatever the pixel number
says; a capture failed (exit 1) round (after gate.sh's one
retry) is re-queued, never counted.
With a target set (#131): gate widths add each target step; inside a
shifted band a pixel failure is tier-shift (logged against the register
entry, never iterated) or a defect (still fails) — gate doc § Target
breakpoints.
Every prototype is a row (#125). When the archetypes pass, one run per width
writes the prototype table — node stardust/scripts/replica/gate-all.mjs --stage prototype --proto-base "$PROTO_BASE" --width 1440 (then 360) through run-bg.mjs;
it reuses each archetype's cached live.png. gate-evidence.mjs reads it as the
source of record: a prototype without a row is ungated.
Iteration discipline: hard cap 3 iterations per breakpoint. Each
iteration's fixes come off the instruments, never off eyeballing. After 3,
log the residuals in the ledger and move on — a documented 2% residual beats
an undocumented fourth loop. No single step waits longer than the context
cache lives: long instruments go through run-bg.mjs (start, then wait
in ≤ 100-second slices), main agent and subagents alike — a long instrument
in the foreground, or two as parallel tool calls in one turn, is the same
blocked step (reference doc § Iteration discipline).
Hardening (each is a recorded false-measurement trap — see the reference
doc for the full list): real Chrome headless with its own identity plus
the standard request headers on every capture, live navigations paced per
host (built into the shared diff/scripts/live-session.mjs); a
challenge/blocked interstitial or a
2xx denial page fails loud (exit 3), never measured — escalate with
--headed, and a site that still blocks needs crawl.mjs-class capture;
domcontentloaded on live targets, never networkidle;
symmetric --main scoping on both sides (--main body is never valid);
both overlay classes dismissed via --dismiss (consent AND timed marketing
modals); animations frozen for capture; the pointer parked after any
dismissal click; fixed/sticky chrome replicated fixed, with its
scroll-state morph (reference/recreation-procedure.md § Fixed and sticky
chrome);
granularity-parity policy for JOIN/SPLIT false-reds (#87); capture-state
policy for CDN-403 images and hydration placeholders (replicate as captured
- log). Two defect classes only the gate catches — DOM/style capture misses
them: rendered-face font forks on inner spans (width probe) and overlay
scrims invisible to computed styles (recover by per-row luminance fitting).
The live-target hardening ships as flags on the diff scripts (--ua,
--wait-until, --dismiss, --headed, --locale, visual-diff --main)
backed by live-session.mjs — copy the scripts and pass flags; a project
copy carrying hand-edits is a defect
(reference/source-fidelity-gate.md § Script adaptations).
After the static gate passes, interaction parity is a REQUIRED gate
output per archetype — not a post-pass
(reference/recreation-procedure.md § Interaction parity). Motion is OBSERVED,
never inferred from static classes or CSS: run
stardust/scripts/replica/motion-observe.mjs per archetype live URL →
stardust/replica/motion/<slug>.json, implement ONLY behaviors that
fired (dead classes = NOT implemented), then observe the served prototype
with the same --click/--hover pokes in the same order (→
stardust/replica/motion/<slug>-build.json) and compare the two files with
stardust/scripts/replica/motion-compare.mjs, a reporter, not a gate (the
header's behaviour is the header contract's): a MISSING or EXTRA line is
confirmed on the class lines (the sampler misses class-toggled and
pseudo-element mechanics) and resolved in the prototype or recorded as dead.
Record
motion: {observed, implemented, dead[]} in progress.json, and re-run
pixel-compare — the number must return to the gated value.
Widgets are implemented, not justified away — on EDS as widgets/<path>/<name>
when the component carries no authored content, never a block with empty rows.
Timer-driven media counts as fired (autoplay/loop video, auto-advancing
slides — the observe JSON's media block): the capture freeze is logged as
captureState[].restoreAtDelivery and delivered, never shipped as the spec.
Fan-out briefs carry the
evidence rule + instrument invocation verbatim.
When all breakpoints pass, present the archetype + its gate metrics for
approval per the standard prototype approval flow (hands-off mode records
approvedBy: "hands-off" per ../stardust/reference/state-machine.md).
Bookkeeping is one command each, never a hand-built JSON line or an inline
node -e edit of state.json: node stardust/scripts/stardust/state.mjs advance <slug> --to approved --by hands-off --prototype stardust/prototypes/<slug>-proposed.html
and node stardust/scripts/stardust/ledger.mjs replica source-fidelity-gate end --detail "<per-breakpoint numbers>". Resuming a run starts with
ledger.mjs tail and state.mjs summary --slugs, not cat.
Every phase of this skill — extract and preserve-direction included — opens
with node stardust/scripts/stardust/ledger.mjs replica <phase> start as its
FIRST command, before any script of the phase runs (a recorded hands-off run
wrote a phase's start beside its end after 109 minutes of work and read
as idle to its supervisor; ledger.mjs refuses an end without an open
start under --strict), and closes with the end line plus a section in
stardust/journal.md headed ## <Phase name> — <what happened> (<date>) —
the section is part of the phase end, and ledger.mjs … end warns when it
is missing (a recorded run's journal began at its second session; another's
had one section for the whole run).
Phase 5 — HANDOFF (delegate — migrate → deploy → rollout, unchanged)
- Read the contract card first:
reference/handoff-contract.md — the
distilled migrate/deploy/rollout rules this phase needs, the exact rollout
ledger phase strings (A-inventory … I-dashboard), one usage line per
deploy and rollout script, and the bookkeeping commands. Never read the
sibling SKILL.md files whole (one recorded session read 260k characters
of them, then re-read the overflow, before its first Phase 5 output);
fetch a cited section with section.mjs only when a step needs depth.
- Pages beyond the archetypes go through the stardust
migrate skill at
sibling tier (../migrate/reference/fidelity-tiers.md) — and only
AFTER their archetype is live and gated at the published origin (contract
§ 3 row C, unit C-archetype; #126): structural clone as the encoder's
input + content-fidelity + delivery-lint + media-reconcile; the sibling's
only counting number is its gate row after PUT + preview (no local pixel
bar). Siblings inherit the archetype's proven encoder — never re-author one. Template constancy is measured, not
assumed: before cloning, run stardust/scripts/replica/sibling-variance.mjs <archetype> <siblings…> --probe <block>=<sel> … once per template and
budget every delta as a block VARIANT class on the sibling's content (same
file, § Sibling variance probe). Content-fidelity is
measured per page at import time (same file, § Content-count
acceptance) so importer bugs surface while cheap to fix.
- Delivery via the stardust
deploy skill per page. Bias the decode tier toward
template-slotted for fixed-composition sections (deploy #95): replica
sections are fixed compositions matched to a live original.
Repeat groups (cards, listings) stay reconstructive. Blocks
obey the Experience Workspace editability contract (deploy § 8, EW1–EW10:
node-slotting, never value-slotting) and pass block-roundtrip --ew.
- Site-wide rollout via the stardust
rollout skill, unchanged — its block dedup
is what implements "same blocks across the whole site".
- Target breakpoints: C0 authors the foundation and reused blocks on
the target steps and wires
breakpoint-lint.mjs into npm run lint
(reference/handoff-contract.md), so every deploy and rollout lint pass
enforces it.
- C-deliver runs in units (
reference/handoff-contract.md § 3, row C +
Fan-out discipline): C0 — ONE foundation subagent authors AND deploys the
foundation; the main agent gates the shell on the published origin, the
header contract included (chrome-compare exit 0, ../diff/SKILL.md
§ The header contract), then foundation-freeze.mjs freeze + commit; C-archetype — per template, the
gated archetype is deployed and passes its full gate row on the preview URL
(cap 3 fix rounds, then the re-prototype decision) BEFORE its siblings
render; C1…Cn — one subagent per template
cluster runs the whole chain, PUT → preview → published-origin gates
included, with its own batch ledger (deploy-batch.mjs --ledger …,
lock-safe) and reports one verdict line; the main agent only coordinates
and records; C-final — check, the queued foundation-requests.md lines
applied once, C-deliver end. Each unit is recorded in
stardust/rollout/progress.json and committed — a safe resume point,
never by itself a reason to end the session; no frozen file is edited
mid-wave.
- The final gate runs against the PUBLISHED origin — not the harness
(
reference/source-fidelity-gate.md § The published-origin gate): deploy
first (PUT → preview), then gate.sh <slug> "$LIVE" "<preview-url>" <width> pub1 --full --marker "<brand or domain string>" through
run-bg.mjs, in the ordinary gates/<slug>-<width>/ dir under the pub<N>
label (a new dir would force a fresh live capture). Nothing pixel-shaped
runs on the local harness — it feeds qa-gate/block-roundtrip only.
- The delivery gate is the ALL-PAGES run, four criteria — not the pixel
number alone (
reference/source-fidelity-gate.md § The all-pages
published-origin gate, #125): node stardust/scripts/replica/gate-all.mjs [--only <slug,…>] [--skip-existing] [--eds-host <host>] through run-bg.mjs.
DELIVERED = pixel % ≤ 10 AND |Δh| ≤ 5 % AND 0 clipped text / controls
(clip-probe) AND 0 MISSING / HIDDEN links / headings (content-presence);
a recorded page passed the pixel bar with all of its cards clipped. Evidence
and sidecars: stardust/replica/gates/all-<width>/; with the Phase 4
prototypes-<width>/ table it is the pair gate-evidence.mjs reads (a page
without a row is ungated). Each cluster subagent runs --only over its own
pages inside the fan-out; C-final's roster run is the recorded unit
gate-all (--skip-existing, captures reused) followed by
update-coverage.mjs --gate (handoff contract § 3, row C).
State: replica writes its own state under stardust/replica/ — the
inconsistency register, progress.json (one map: types.<archetype> —
page type, iterations used, per-breakpoint gate results, residuals, motion
inventory — beside gate-evidence.mjs's siblings / migrate; extended
per entry, never replaced), motion/<slug>.json, and gates/<slug>-<width>/ evidence.
The delivery gate (#125) adds gates/all-<width>/: one dir per deployed page,
summary.{json,md}, runs/ and the sidecars (gate-all.mjs --help).
Phase 5 adds three files under stardust/rollout/: progress.json (the
C-deliver unit ledger — status, gates and verdict per unit),
foundation-freeze.json (the sha256 manifest of the frozen foundation) and
foundation-requests.md (queued foundation change requests, applied once at
C-final). Pipeline status (extracted → prototyped →
approved → migrated) stays in the core state.json per the standard state
machine — replica never redefines it.
What replica never does
- No redesign. No new palette, type, spacing, composition, motion. The
target spec is the captured current state.
- No content rewriting. Captured strings are verbatim; placeholders and
hydration states are replicated as captured, not "fixed".
- No invented improvements. A change without an inconsistency-register
entry is a defect, however tasteful.
- No DOM copying. Never paste the live DOM or port page-level CSS as the
prototype (that's the snowflake escape hatch, not this skill). Clean
re-authoring is the point — byte-fidelity without re-implementation value
defeats the migration.
Outputs
stardust/
├── state.json ← core state machine (unchanged contract)
├── direction.md ← preserve-mode record (Phase 2)
├── current/ ← from extract --prep
├── prototypes/<slug>-proposed.html ← gated archetypes (one per page type)
├── replica/
│ ├── inconsistency-register.md ← the ONLY permitted design deltas
│ ├── breakpoint-map.md ← source → target breakpoint map (only with --target-breakpoints)
│ ├── progress.json ← per-page-type ledger: iterations, gate results, residuals, motion inventory
│ ├── motion/<slug>.json ← motion-observe evidence
│ └── gates/<slug>-<width>/ ← live.png, build.png, the latest round's diff, probe outputs per round
├── migrated/ ← from migrate (Phase 5)
└── rollout/ ← from rollout (Phase 5); coverage/, plan.json … per its SKILL.md
├── progress.json ← C-deliver unit ledger: status, gates, verdict per unit
├── foundation-freeze.json ← sha256 manifest of the frozen foundation (C0 → C-final)
└── foundation-requests.md ← queued foundation change requests, applied once at C-final
PRODUCT.md / DESIGN.md / DESIGN.json ← promoted verbatim from current/ (Phase 2)
References
reference/preserve-direction.md — mechanical promotion contract +
inconsistency-register entry schema.
reference/recreation-procedure.md — CSS-lifting method (per gate
breakpoint), fonts policy, scrim/luminance recovery, span-face forks,
capture-state policy, wrap-junction margins, fixed/sticky chrome,
granularity parity, role parity (mirror the live look per string),
interaction parity (motion observed, never inferred; Swiper-lock),
CSS-portation fallback criteria.
reference/source-fidelity-gate.md — full gate contract: commands,
thresholds, per-breakpoint procedure, hardening rules, band-breakdown
reading guide (+ the section-anchor inner loop), iteration discipline,
the published-origin gate (EDS pipeline deltas), residual logging format.
../diff/SKILL.md — the two probes replica reuses (--profile generic);
reading content-diff output; the #87 JOIN/SPLIT limitation.
../extract/SKILL.md § Prep mode — what Phase 1 provides.
reference/reading-discipline.md — the reading and inspection rules in
full: which helper reads what, the image rule, the evidence behind them.
reference/handoff-contract.md — Phase 5 contract card: sibling-tier
steps, deploy editability/decode/DA protocols, rollout phases A–I with
their ledger phase strings, one usage line per deploy and rollout
script, bookkeeping commands.
../stardust/scripts/ledger.mjs, ../stardust/scripts/state.mjs — the
ledger and state writers (project copies under
stardust/scripts/stardust/); --help on each.
../migrate/reference/fidelity-tiers.md — archetype/sibling model Phase 5
hands off to.
../deploy/SKILL.md § decode tiers (#95) — template-slotted bias.
../stardust/reference/scripts-index.md — every shipped script on one line
(what it does, key flags); read it before any --help.
1---2name: replica-23description: Same-design migration — re-platform a site to AEM Edge Delivery (or any clean front end) keeping its current design near pixel-perfect. Recreates key pages (one archetype per page type) as clean re-authored HTML/CSS (never DOM copies), verifies each against the live site with a measured source-fidelity gate (structural + visual + stitched pixel diff per breakpoint), then hands off to migrate/deploy/rollout for site-wide delivery (subsumes prepare-migration's prep cascade — never chain the two). The only permitted design changes are entries in an explicit inconsistency register. Use when the user says "migrate this site keeping its current design", "same-design migration", "pixel-perfect replatform to AEM", or "keep the design, change the platform". NOT for redesigns — those are the stardust core pipeline (direct/prototype) or uplift.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/replica-28---910# stardust:replica — same-design migration1112Same pages, same content, same design — new platform. `replica` migrates a13site to AEM Edge Delivery (or just re-platforms its front end) keeping the14current design **near pixel-perfect**: the target spec IS the captured current15state, the only permitted deltas are the entries of an explicit16**inconsistency register**, and every archetype must pass a **measured17source-fidelity gate** against the live site before anything ships.1819Two properties make this a different animal from the redesign pipeline:20211. **No creative decisions.** The direction step is mechanical promotion of22 the captured spec — the stardust `direct` skill is never invoked. Every judgment23 call in a replica run is a *measurement-policy* call, not a taste call.242. **Recreation, not copying.** Archetypes are authored as clean semantic25 HTML/CSS from captured content + values lifted from the source site's own26 CSS — never DOM copies, never ported page-level stylesheets. Fidelity is27 proven by instruments, not asserted by construction.2829Validated end-to-end (a typographic retail home page, 2026-07-03): 8.31% → 2.93% → **1.31%**30pixel diff in 3 measured iterations, height Δ 0, content-diff "findings:31none" (198/198 nodes). Every fix came off the instruments, never off32eyeballing.3334## Inputs3536- `<URL>` — required. The site to migrate.37- `--breakpoints <list>` — optional. Gate widths, default `1440,360`; each38 gets its own gate pass (mobile is not free — gate doc § Per-breakpoint).39- `--target-breakpoints <list>` — optional. Mobile-first `min-width` steps40 (e.g. `600,900,1200`) the delivered site switches layout at instead of the41 source's. Absent = source breakpoints kept, every target step below42 skipped. Persisted in `DESIGN.json` `extensions.breakpoints.target`.43- `--register <file>` — optional. User-supplied inconsistency items to seed44 the register (see Phase 2). Without it and without an audit, the register45 is empty — a pure replica.46- `--first-page <url|home>` — optional; hands-off `home`. The page a47 full-site run delivers first (`reference/first-page-first.md`).4849## Setup50511. Run the master skill's setup (`../stardust/SKILL.md` § Setup): context52 loader, state read. **Flow guard.** If `state.json.flow` is53 `redesign`, refuse: print the never-mix line and the switch command54 (`$stardust replica --switch-flow`, which marks the redesign flow's55 prototyped and migrated pages stale — master skill § Two migration56 flows). If `flow` is absent, stamp `flow: "replica"`,57 `flowSource: "user-phrase"` (`../stardust/reference/state-machine.md`58 § Flow keys): invoking `replica` is the choice.592. Verify Playwright is importable from the project root (extract needs it;60 so do the gate scripts).613. Probe the gate's deps from the project root first —62 `node -e "import('pixelmatch').then(()=>process.exit(0))"` (and playwright,63 pngjs, cheerio) — and only on failure install them AS devDependencies,64 never `--no-save`: `npm i -D playwright pixelmatch pngjs cheerio65 --legacy-peer-deps` (`../extract/SKILL.md` § Setup). A harness that already66 resolves them leaves the delivered code repo untouched; the67 devDependencies otherwise land in the repo the skills push. Run every68 probe from the project root: ESM resolves `playwright` from the script's69 own location.704. Copy scripts into the project and run them from there, not from the71 plugin: this skill's whole `scripts/` dir to72 `stardust/scripts/replica/`, the master skill's `../stardust/scripts/`73 (ledger.mjs, state.mjs) to `stardust/scripts/stardust/`, the migrate74 skill's `../migrate/scripts/` (migrate.mjs) to `stardust/scripts/migrate/`,75 AND the whole76 `../diff/scripts/` dir to `stardust/scripts/diff/` (the diff scripts77 import diff-profiles.mjs, and ALL live-target hardening — including78 stitch-shot's — lives in its live-session.mjs; stitch-shot resolves it79 from `stardust/scripts/diff/` next to `stardust/scripts/replica/`, so80 keep the two dirs siblings). Never copy into the project-root81 `scripts/` — that is the EDS boilerplate's directory (master skill82 § Artifacts, the write boundary).8384**Reading and inspection discipline — the context is the budget**85(`reference/reading-discipline.md`, read it once at Setup). Every byte a86step prints is re-read on every later model call (recorded: 750k characters87of tool output in one 77-minute session). The rules in one line each:88reference docs by section (`section.mjs <doc> --list`, then one heading, one89section per call); captured CSS through `css-rules.mjs`, capture JSON through90`json-query.mjs` (values that feed a command from `--tsv`/`--path`, never the91table), captured HTML through `html-slice.mjs`; instrument output through92`run-bg.mjs wait` and `log --grep`, never `cat`; live-vs-prototype boxes93through `measure.mjs`, never an authored probe; images one crop per fact,94never a stitched page or the live/build/diff triplet (the extract thumbnail,95`thumb.mjs`, is the one exception); script flags from96`../stardust/reference/scripts-index.md` first, then `--help`, never the97source. Write anything you will need again to a file under `stardust/` and98read it back by query.99100## Procedure101102Five phases. Phases 1 and 5 delegate to existing skills unchanged; phases1032–4 are owned by `replica`. A full-site run opens **first page first**:104`reference/first-page-first.md`.105106### Phase 1 — EXTRACT (delegate to `$stardust extract --prep --dynamics`)107108Invoke `$stardust extract <URL> --prep`, unchanged. Prep mode is required —109replica consumes the full migration inventory, not the discovery cap:110111- `stardust/current/pages/<slug>.json` — per-page structure + content112 (verbatim source of every string the prototypes will carry).113- `stardust/current/assets/screenshots/` — per-page captures (ground truth114 for recreation, alongside the gate's own stitched shots).115- `stardust/current/assets/` — fonts (network-intercepted woff2), logo, media.116- `stardust/current/PRODUCT.md`, `DESIGN.md`, `DESIGN.json` — the descriptive117 current state (Phase 2 promotes these verbatim).118- `state.json.pages[].type` — page types (each becomes one archetype).119- `DESIGN.json.extensions.modules[]` — module candidates (become blocks).120121When extract's summary comes back, surface it with the flow line first —122"Flow: replica — the design is kept. Say `switch to redesign` now if it is123to change." — so the first thing the user sees in this flow is the choice124it rests on. `switch to redesign` runs `$stardust prepare-migration125--switch-flow`; the extract is reused, nothing else is.126127**Bounded/single-page entry (one-page or pilot runs).** `--prep` is the128site-wide contract; it is NOT the only way in. When the ask is "replicate129just this page" — or the user wants to pilot one archetype before committing130to a full migration — invoke `$stardust extract <URL> --single --dynamics`131(or `--pages <slug,...> --dynamics` for a short list) instead. This is a first-class entry,132not an improvisation: the recreation phase needs, per page, the captured133page JSON (verbatim content), the per-page screenshot (ground truth), and134the captured fonts — all of which a bounded extract provides; the source-CSS135harvest and per-breakpoint computed styles come from Phase 3's CSS lifting136either way. What a bounded run skips is the prep-only inventory (page137typing, module detection), which is only needed when Phase 5 fans out to138siblings, and the descriptive synthesis (Phase 2 takes the bounded139promotion branch, `reference/preserve-direction.md` § 1a).140141Extract's failure modes apply as-is (bot-management headed fallback, consent142handling, no-synthesis rule). If extract had to fall back to headed Chrome,143expect the gate captures to need the same treatment.144145### Phase 2 — PRESERVE DIRECTION (mechanical — never invoke the stardust `direct` skill)146147Full contract: `reference/preserve-direction.md`. Summary:1481491. **Promote** `stardust/current/PRODUCT.md`, `DESIGN.md`, `DESIGN.json`150 verbatim to the project root as the target spec. No divergence roll, no151 re-direction, no Mode A/B — the current state IS the target. **Bounded152 entry (`--single`/`--pages`): those files don't exist** — take the153 bounded promotion branch instead (`reference/preserve-direction.md`154 § 1a): synthesize a minimal descriptive spec from the captured page JSON155 + the Phase-3 CSS lift (palette, type ramp, container, buttons — exactly156 the values the lift produces anyway), provenance `bounded-single`. Never157 mix the branches: if `current/PRODUCT.md` exists, promotion is verbatim158 (first page first's Track A excepted).1592. **Write `stardust/direction.md`** recording preserve mode: what was160 promoted, from where, provenance (verbatim `--prep` promotion vs161 `bounded-single` synthesis), and the register pointer. This is what162 tells downstream skills "the direction step happened".1633. **Build the inconsistency register** at164 `stardust/replica/inconsistency-register.md` — the ONLY permitted design165 deltas, the "almost" in almost-pixel-perfect. Sources: the stardust `audit` skill166 design findings (run audit only if the user wants improvement candidates)167 and/or user-supplied items (`--register`). Every entry needs captured168 evidence + the minimal change + a status. **Empty register = pure169 replica** — that is a valid and common outcome, not a failure.1704. **Target breakpoints (only with `--target-breakpoints`)**, before any171 CSS exists (`reference/preserve-direction.md` § 4): persist the list, map172 each source breakpoint to a step by intent in173 `stardust/replica/breakpoint-map.md`, seed the ONE register entry. Phase 3174 and C0 apply the map; they never decide it.1751765. **Dynamic surface (migration gate — the stardust `dynamics` skill Phases 1–3).**177 Phase 1 must have run `extract --dynamics`. Run the detector on the178 archetypes, draft the triage (`--target-origin` when the EDS host is179 known), curate `stardust/dynamic-features.md` + `-plan.md`. Every row180 gets a disposition; the static recreation continues regardless. This is181 what surfaces modals, players, forms, search, tags and host-bound APIs182 that pixel gates certify as correct. Contract:183 `skills/dynamics/reference/triage.md`.184185Anything not in the register is out of scope for change. When a recreation186choice would "improve" something not registered, it is a fidelity bug.187188### Phase 3 — RECREATE (one archetype per page type)189190Full method: `reference/recreation-procedure.md`. For each page type in the191inventory (archetype: the type's `rep_url` in a spec's `archetypes.json`), author `stardust/prototypes/<slug>-proposed.html` (+ per-page CSS)192as **clean semantic HTML/CSS** from three sources, in this order:193194(a) **Captured page JSON content — verbatim.** Headings, body, CTAs+hrefs,195 alt text, metadata from `current/pages/<slug>.json`. The migrate196 content-preservation rules (`../migrate/reference/content-preservation.md`)197 apply from the first line: no rewording, no fabrication.198(b) **Exact values lifted from the source site's own CSS.** Fetch the live199 stylesheets; lift the type ramp, button specs, section paddings, radii,200 shadows, hero heights. The container model is measured, not lifted —201 DESIGN.json `extensions.breakpoints` (extract's `cap-probe.mjs` run; a bounded202 entry runs `cap-probe.mjs <live-url> --write-design stardust/current/DESIGN.json` first).203 **Fidelity values come from the original site's CSS, not the eye** — this204 converts 3–4 guess-and-screenshot loops into one. Box-by-box comparison of205 the live page against the served prototype goes through the shipped206 `measure.mjs` (`node stardust/scripts/replica/measure.mjs <live-url>207 --against <prototype-url> --selectors "<css>,…"` — rect + computed values208 per selector per width, one delta line each), never through an authored209 probe.210(c) **The captured screenshot as ground truth** for everything CSS doesn't211 name (composition, image crops, paint effects).212213**With a target set, every `@media` rule and JS width threshold214(`matchMedia`, `innerWidth`) is authored on the target steps from the first215line** per `breakpoint-map.md`, never fixed later (a retrofit costs a full216re-gate); `breakpoint-lint.mjs` exits 0 on a prototype before its gate.217218**Every archetype gets its own standalone prototype — cumulative, never219skipped.** Never skip to direct platform authoring for a new archetype:220prototyped archetypes stayed the quality ceiling in the field (3.5%/5.6%)221while direct-authored pages plateaued at 8–16%. Each new prototype imports222the shared layers earlier ones already gated (shared canon CSS + a223per-archetype file) and iterates only on its NEW modules — full contract:224`reference/recreation-procedure.md` § Cumulative archetype prototypes.225226**This is recreation, not redesign — do NOT delegate to impeccable craft.**227Impeccable's redesign gates (critique, anti-template, divergence) do not228apply; the source-fidelity gate (Phase 4) replaces them entirely. A229"tastefully improved" section is a failing section.230231**Fonts:** use the same public source when available (extract's intercepted232woff2 for open/self-hostable faces). For licensed commercial kits: never233rehost on the new domain — pick a metric-matched substitute, keep the brand234family name first in the font stack so a licensed drop-in later wins, and235surface the substitution to the user. (Prior art: an earlier airport-site migration's improvement notes, §3.7.)236237**CSS-portation is the per-section fallback only** — paint-level effects not238recoverable from computed styles, JS-hydrated commerce widgets, video or239animated heroes. Port the minimal source rules for that section, scoped;240never page-level. Criteria in `reference/recreation-procedure.md` § Fallback.241242### Phase 4 — SOURCE-FIDELITY GATE (the heart — measured, per breakpoint)243244Full contract: `reference/source-fidelity-gate.md`. Run per archetype, per245breakpoint (default 1440 AND 360), live URL as source vs served prototype:246247```bash248PROTO="http://localhost:8791/<slug>-proposed.html" # python3 -m http.server from the prototypes dir249# ONE server, ONE port — probe with curl first (gate doc § Per-breakpoint procedure): no answer →250# start yours; answers but not your file → foreign server, never kill it, take a per-project port251curl -sI localhost:8791/<slug>-proposed.html | head -1 # 200 = it serves YOUR dir: reuse it252LIVE="https://<site>/<path>"253254# One command per round — gate.sh, through run-bg. The FIRST round of a breakpoint and the255# CONFIRMATION round after the last fix run `--full` (pixel probe — stitched captures, NEVER256# fullPage:true — plus content-diff, visual-diff and chrome-parity under deadlines, one verdict257# line each, reports in the gate dir); rounds in between are pixel rounds. Never hand-write a258# wrapper around the instruments (a recorded one lost the deadlines; a round took 15 minutes).259# content-diff inside --full compares --main AND the header/footer roots by default — no chrome flag.260node stardust/scripts/replica/run-bg.mjs start --name <slug>-1440-iter1 -- \261 stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 1440 iter1 --full --main "<content-root>"262node stardust/scripts/replica/run-bg.mjs start --name <slug>-360-iter1 -- \263 stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 360 iter1 --full --main "<content-root>"264# A consent manager the built-in candidates miss: add --consent "<accept selector>" to every gate.sh265# round — it reaches both stitched captures and the probes alike (gate doc § Hardening rule 6).266node stardust/scripts/replica/run-bg.mjs wait # verdict lines: pixel %, height delta, hot bands, structural 🔴, flags, chrome deltas267268# Iteration inner loop (gate doc § Band breakdown): anchor probe + pixel round269G=stardust/replica/gates/<slug>-1440270node stardust/scripts/replica/anchor.mjs "$LIVE" --width 1440 --cache $G/anchor-live.json # live side: probed once, reused271node stardust/scripts/replica/anchor.mjs "$PROTO" --width 1440 # build-side runs are free272# Chrome: computed-style parity BEFORE any pixel round on header/footer/strips273node stardust/scripts/replica/chrome-parity.mjs "$LIVE" "$PROTO" --width 1440 --live-cache $G/chrome-live.json # exit 0 = quiet, then crop-compare274# Every instrument runs real Chrome headless with its real user agent and client hints (#151); existing automation-signal handling stays on unless STARDUST_STEALTH=0; STARDUST_HEADED_WINDOW=1 opens the --headed window (#125).275# gate.sh: live.png cached, every step under a deadline (exit 124 = re-run, not FAIL). Rounds run in276# the BACKGROUND: start every round at once (the slots pace the Chromiums — no `sleep N;` staggering),277# then `wait` prints verdict lines only; exit 75 = still going → `wait` again as your NEXT step, never278# in a shell loop, never after a `sleep` (gate doc § Iteration discipline). A propagation wait is a279# bounded inline poll (`curl -sf` ≤ 5 s apart, capped), never a fixed sleep.280node stardust/scripts/replica/run-bg.mjs start --name <slug>-1440-iter2 -- stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 1440 iter2281node stardust/scripts/replica/run-bg.mjs start --name <slug>-360-iter2 -- stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 360 iter2282node stardust/scripts/replica/run-bg.mjs wait # returns within 100 s; full output: run-bg.mjs log <job> --grep <re>283# Content-cap row — once per archetype after the 1440 pass, at DESIGN.json's derived probeWidth (never a pinned 1920)284node stardust/scripts/replica/cap-probe.mjs "$LIVE" --against "$PROTO" --design DESIGN.json --slug <slug> --main "<content-root>"285```286287`gate.sh --help` lists the flags and exit codes (124 = deadline, re-run, not288a verdict; 0 only when all four ran and passed).289290**Pass bar (all four per breakpoint, plus the content-cap row):**291- content-diff: **0 🔴 and 0 nothing-lost 🟡** on the main and chrome roots (gate doc § Pass bar item 1);292- visual-diff: flags none or justified;293- pixel diff: **≤ 10%** full-page, with no per-500px band left unexplained294 (the band breakdown is the navigation instrument — fix the first hot band,295 top-down; everything below it is offset-contaminated);296- height delta **|Δ| ≤ 8px** (pixel-compare's own warning bar);297- **content-cap row: `cap-probe.mjs … --against` prints `cap-probe: PASS`**298 (gate doc § Pass bar item 6 — every live cap held within ±20 px by kind,299 nothing capped only on the prototype; a ✗ names the sizing rule, no pixel iteration);300- **clip-probe: `Clipped: 0`** on the build side (a `--full` round runs it; cut or hidden301 text / controls fail the round like an over-threshold pixel diff — #125); a302 declared repeated-unit family (`stardust/replica/units.json`, gate doc item 7)303 within 4 px;304- and, outside the bar and outside the cap, the horizontal-overflow assert:305 `document.documentElement.scrollWidth` within 4 px of the viewport306 (integer rounding; `GATE_OVERFLOW_TOLERANCE`) at every breakpoint on the307 build side — gate.sh fails the round on more whatever the pixel number308 says; a `capture failed (exit 1)` round (after gate.sh's one309 retry) is re-queued, never counted.310311**With a target set (#131):** gate widths add each target step; inside a312shifted band a pixel failure is **tier-shift** (logged against the register313entry, never iterated) or a **defect** (still fails) — gate doc § Target314breakpoints.315316**Every prototype is a row (#125).** When the archetypes pass, one run per width317writes the prototype table — `node stardust/scripts/replica/gate-all.mjs --stage318prototype --proto-base "$PROTO_BASE" --width 1440` (then 360) through `run-bg.mjs`;319it reuses each archetype's cached `live.png`. `gate-evidence.mjs` reads it as the320source of record: a prototype without a row is ungated.321322**Iteration discipline: hard cap 3 iterations per breakpoint.** Each323iteration's fixes come off the instruments, never off eyeballing. After 3,324log the residuals in the ledger and move on — a documented 2% residual beats325an undocumented fourth loop. **No single step waits longer than the context326cache lives:** long instruments go through `run-bg.mjs` (`start`, then `wait`327in ≤ 100-second slices), main agent and subagents alike — a long instrument328in the foreground, or two as parallel tool calls in one turn, is the same329blocked step (reference doc § Iteration discipline).330331**Hardening (each is a recorded false-measurement trap — see the reference332doc for the full list):** real Chrome headless with **its own identity plus333the standard request headers** on every capture, live navigations paced per334host (built into the shared `diff/scripts/live-session.mjs`); a335challenge/blocked interstitial or a3362xx denial page **fails loud (exit 3)**, never measured — escalate with337`--headed`, and a site that still blocks needs crawl.mjs-class capture;338`domcontentloaded` on live targets, never `networkidle`;339symmetric `--main` scoping on both sides (`--main body` is never valid);340both overlay classes dismissed via `--dismiss` (consent AND timed marketing341modals); animations frozen for capture; the pointer parked after any342dismissal click; fixed/sticky chrome replicated fixed, with its343scroll-state morph (`reference/recreation-procedure.md` § Fixed and sticky344chrome);345granularity-parity policy for JOIN/SPLIT false-reds (#87); capture-state346policy for CDN-403 images and hydration placeholders (replicate as captured347+ log). Two defect classes only the gate catches — DOM/style capture misses348them: rendered-face font forks on inner spans (width probe) and overlay349scrims invisible to computed styles (recover by per-row luminance fitting).350351The live-target hardening ships as flags on the diff scripts (`--ua`,352`--wait-until`, `--dismiss`, `--headed`, `--locale`, visual-diff `--main`)353backed by `live-session.mjs` — copy the scripts and pass flags; a project354copy carrying hand-edits is a defect355(`reference/source-fidelity-gate.md` § Script adaptations).356357**After the static gate passes, interaction parity is a REQUIRED gate358output per archetype — not a post-pass**359(`reference/recreation-procedure.md` § Interaction parity). Motion is OBSERVED,360never inferred from static classes or CSS: run361`stardust/scripts/replica/motion-observe.mjs` per archetype live URL →362`stardust/replica/motion/<slug>.json`, implement ONLY behaviors that363fired (dead classes = NOT implemented), then observe the served prototype364with the same `--click`/`--hover` pokes in the same order (→365`stardust/replica/motion/<slug>-build.json`) and compare the two files with366`stardust/scripts/replica/motion-compare.mjs`, a reporter, not a gate (the367header's behaviour is the header contract's): a MISSING or EXTRA line is368confirmed on the class lines (the sampler misses class-toggled and369pseudo-element mechanics) and resolved in the prototype or recorded as dead.370Record371`motion: {observed, implemented, dead[]}` in `progress.json`, and re-run372pixel-compare — the number must return to the gated value.373Widgets are implemented, not justified away — on EDS as `widgets/<path>/<name>`374when the component carries no authored content, never a block with empty rows.375Timer-driven media counts as fired (`autoplay`/`loop` video, auto-advancing376slides — the observe JSON's `media` block): the capture freeze is logged as377`captureState[].restoreAtDelivery` and delivered, never shipped as the spec.378Fan-out briefs carry the379evidence rule + instrument invocation verbatim.380381When all breakpoints pass, present the archetype + its gate metrics for382approval per the standard prototype approval flow (hands-off mode records383`approvedBy: "hands-off"` per `../stardust/reference/state-machine.md`).384Bookkeeping is one command each, never a hand-built JSON line or an inline385`node -e` edit of state.json: `node stardust/scripts/stardust/state.mjs advance <slug> --to386approved --by hands-off --prototype stardust/prototypes/<slug>-proposed.html`387and `node stardust/scripts/stardust/ledger.mjs replica source-fidelity-gate388end --detail "<per-breakpoint numbers>"`. Resuming a run starts with389`ledger.mjs tail` and `state.mjs summary --slugs`, not `cat`.390Every phase of this skill — extract and preserve-direction included — opens391with `node stardust/scripts/stardust/ledger.mjs replica <phase> start` as its392FIRST command, before any script of the phase runs (a recorded hands-off run393wrote a phase's `start` beside its `end` after 109 minutes of work and read394as idle to its supervisor; `ledger.mjs` refuses an `end` without an open395`start` under `--strict`), and closes with the `end` line plus a section in396`stardust/journal.md` headed `## <Phase name> — <what happened> (<date>)` —397the section is part of the phase `end`, and `ledger.mjs … end` warns when it398is missing (a recorded run's journal began at its second session; another's399had one section for the whole run).400401### Phase 5 — HANDOFF (delegate — migrate → deploy → rollout, unchanged)402403- **Read the contract card first: `reference/handoff-contract.md`** — the404 distilled migrate/deploy/rollout rules this phase needs, the exact rollout405 ledger phase strings (`A-inventory` … `I-dashboard`), one usage line per406 deploy and rollout script, and the bookkeeping commands. Never read the407 sibling SKILL.md files whole (one recorded session read 260k characters408 of them, then re-read the overflow, before its first Phase 5 output);409 fetch a cited section with `section.mjs` only when a step needs depth.410- **Pages beyond the archetypes** go through the stardust `migrate` skill at411 **sibling tier** (`../migrate/reference/fidelity-tiers.md`) — and only412 AFTER their archetype is live and gated at the published origin (contract413 § 3 row C, unit `C-archetype`; #126): structural clone as the encoder's414 input + content-fidelity + delivery-lint + media-reconcile; the sibling's415 only counting number is its gate row after PUT + preview (no local pixel416 bar). Siblings inherit the archetype's proven encoder — never re-author one. **Template constancy is measured, not417 assumed**: before cloning, run `stardust/scripts/replica/sibling-variance.mjs418 <archetype> <siblings…> --probe <block>=<sel> …` once per template and419 budget every delta as a block VARIANT class on the sibling's content (same420 file, § Sibling variance probe). Content-fidelity is421 **measured per page at import time** (same file, § Content-count422 acceptance) so importer bugs surface while cheap to fix.423- **Delivery** via the stardust `deploy` skill per page. Bias the decode tier toward424 **template-slotted** for fixed-composition sections (deploy #95): replica425 sections are fixed compositions matched to a live original.426 Repeat groups (cards, listings) stay reconstructive. **Blocks427 obey the Experience Workspace editability contract (deploy § 8, EW1–EW10:428 node-slotting, never value-slotting) and pass `block-roundtrip --ew`.**429- **Site-wide rollout** via the stardust `rollout` skill, unchanged — its block dedup430 is what implements "same blocks across the whole site".431- **Target breakpoints:** C0 authors the foundation and reused blocks on432 the target steps and wires `breakpoint-lint.mjs` into `npm run lint`433 (`reference/handoff-contract.md`), so every deploy and rollout lint pass434 enforces it.435- **C-deliver runs in units** (`reference/handoff-contract.md` § 3, row C +436 Fan-out discipline): C0 — ONE foundation subagent authors AND deploys the437 foundation; the main agent gates the shell on the published origin, the438 header contract included (`chrome-compare` exit 0, `../diff/SKILL.md`439 § The header contract), then `foundation-freeze.mjs freeze` + commit; C-archetype — per template, the440 gated archetype is deployed and passes its full gate row on the preview URL441 (cap 3 fix rounds, then the re-prototype decision) BEFORE its siblings442 render; C1…Cn — one subagent per template443 cluster runs the whole chain, PUT → preview → published-origin gates444 included, with its own batch ledger (`deploy-batch.mjs --ledger …`,445 lock-safe) and reports one verdict line; the main agent only coordinates446 and records; C-final — `check`, the queued `foundation-requests.md` lines447 applied once, `C-deliver end`. Each unit is recorded in448 `stardust/rollout/progress.json` and committed — a safe resume point,449 never by itself a reason to end the session; no frozen file is edited450 mid-wave.451- **The final gate runs against the PUBLISHED origin — not the harness**452 (`reference/source-fidelity-gate.md` § The published-origin gate): deploy453 first (`PUT → preview`), then `gate.sh <slug> "$LIVE" "<preview-url>"454 <width> pub1 --full --marker "<brand or domain string>"` through455 `run-bg.mjs`, in the ordinary `gates/<slug>-<width>/` dir under the `pub<N>`456 label (a new dir would force a fresh live capture). Nothing pixel-shaped457 runs on the local harness — it feeds `qa-gate`/`block-roundtrip` only.458- **The delivery gate is the ALL-PAGES run, four criteria — not the pixel459 number alone** (`reference/source-fidelity-gate.md` § The all-pages460 published-origin gate, #125): `node stardust/scripts/replica/gate-all.mjs461 [--only <slug,…>] [--skip-existing] [--eds-host <host>]` through `run-bg.mjs`.462 DELIVERED = pixel % ≤ 10 AND |Δh| ≤ 5 % AND 0 clipped text / controls463 (`clip-probe`) AND 0 MISSING / HIDDEN links / headings (`content-presence`);464 a recorded page passed the pixel bar with all of its cards clipped. Evidence465 and sidecars: `stardust/replica/gates/all-<width>/`; with the Phase 4466 `prototypes-<width>/` table it is the pair `gate-evidence.mjs` reads (a page467 without a row is ungated). Each cluster subagent runs `--only` over its own468 pages inside the fan-out; C-final's roster run is the recorded unit469 `gate-all` (`--skip-existing`, captures reused) followed by470 `update-coverage.mjs --gate` (handoff contract § 3, row C).471472**State:** replica writes its own state under `stardust/replica/` — the473inconsistency register, `progress.json` (one map: `types.<archetype>` —474page type, iterations used, per-breakpoint gate results, residuals, motion475inventory — beside `gate-evidence.mjs`'s `siblings` / `migrate`; extended476per entry, never replaced), `motion/<slug>.json`, and `gates/<slug>-<width>/` evidence.477The delivery gate (#125) adds `gates/all-<width>/`: one dir per deployed page,478`summary.{json,md}`, `runs/` and the sidecars (`gate-all.mjs --help`).479Phase 5 adds three files under `stardust/rollout/`: `progress.json` (the480C-deliver unit ledger — status, gates and verdict per unit),481`foundation-freeze.json` (the sha256 manifest of the frozen foundation) and482`foundation-requests.md` (queued foundation change requests, applied once at483C-final). Pipeline status (extracted → prototyped →484approved → migrated) stays in the core `state.json` per the standard state485machine — replica never redefines it.486487## What replica never does488489- **No redesign.** No new palette, type, spacing, composition, motion. The490 target spec is the captured current state.491- **No content rewriting.** Captured strings are verbatim; placeholders and492 hydration states are replicated as captured, not "fixed".493- **No invented improvements.** A change without an inconsistency-register494 entry is a defect, however tasteful.495- **No DOM copying.** Never paste the live DOM or port page-level CSS as the496 prototype (that's the snowflake escape hatch, not this skill). Clean497 re-authoring is the point — byte-fidelity without re-implementation value498 defeats the migration.499500## Outputs501502```503stardust/504├── state.json ← core state machine (unchanged contract)505├── direction.md ← preserve-mode record (Phase 2)506├── current/ ← from extract --prep507├── prototypes/<slug>-proposed.html ← gated archetypes (one per page type)508├── replica/509│ ├── inconsistency-register.md ← the ONLY permitted design deltas510│ ├── breakpoint-map.md ← source → target breakpoint map (only with --target-breakpoints)511│ ├── progress.json ← per-page-type ledger: iterations, gate results, residuals, motion inventory512│ ├── motion/<slug>.json ← motion-observe evidence513│ └── gates/<slug>-<width>/ ← live.png, build.png, the latest round's diff, probe outputs per round514├── migrated/ ← from migrate (Phase 5)515└── rollout/ ← from rollout (Phase 5); coverage/, plan.json … per its SKILL.md516 ├── progress.json ← C-deliver unit ledger: status, gates, verdict per unit517 ├── foundation-freeze.json ← sha256 manifest of the frozen foundation (C0 → C-final)518 └── foundation-requests.md ← queued foundation change requests, applied once at C-final519520PRODUCT.md / DESIGN.md / DESIGN.json ← promoted verbatim from current/ (Phase 2)521```522523## References524525- `reference/preserve-direction.md` — mechanical promotion contract +526 inconsistency-register entry schema.527- `reference/recreation-procedure.md` — CSS-lifting method (per gate528 breakpoint), fonts policy, scrim/luminance recovery, span-face forks,529 capture-state policy, wrap-junction margins, fixed/sticky chrome,530 granularity parity, role parity (mirror the live look per string),531 interaction parity (motion observed, never inferred; Swiper-lock),532 CSS-portation fallback criteria.533- `reference/source-fidelity-gate.md` — full gate contract: commands,534 thresholds, per-breakpoint procedure, hardening rules, band-breakdown535 reading guide (+ the section-anchor inner loop), iteration discipline,536 the published-origin gate (EDS pipeline deltas), residual logging format.537- `../diff/SKILL.md` — the two probes replica reuses (`--profile generic`);538 reading content-diff output; the #87 JOIN/SPLIT limitation.539- `../extract/SKILL.md` § Prep mode — what Phase 1 provides.540- `reference/reading-discipline.md` — the reading and inspection rules in541 full: which helper reads what, the image rule, the evidence behind them.542- `reference/handoff-contract.md` — Phase 5 contract card: sibling-tier543 steps, deploy editability/decode/DA protocols, rollout phases A–I with544 their ledger phase strings, one usage line per deploy and rollout545 script, bookkeeping commands.546- `../stardust/scripts/ledger.mjs`, `../stardust/scripts/state.mjs` — the547 ledger and state writers (project copies under548 `stardust/scripts/stardust/`); `--help` on each.549- `../migrate/reference/fidelity-tiers.md` — archetype/sibling model Phase 5550 hands off to.551- `../deploy/SKILL.md` § decode tiers (#95) — template-slotted bias.552- `../stardust/reference/scripts-index.md` — every shipped script on one line553 (what it does, key flags); read it before any `--help`.