spec

# stardust:spec — the migration spec, before the migration The spec answers the people planning a migration (what to build, reuse, fix or decide) and the agent that runs it (archetypes, block backlog, contracts, redirects, a default for every decision). The agent builds it stage by stage. ## Principles - **Evidence, then judgement.** Stages S1–S6 and S8 measure the live site; S7 and S9 are judgement (mapping, reuse, features, questions) recorded in `judgement/` with a rationale per decision. - **Blind judgement.** Judge from the source site only (reference/judgement.md); state the provenance in `implementation.json#provenance`. - **Variants, not templates.** CMS templates are loose; plan, capture and QA by layout variant (S8). - **Every open question ships a default.** A hands-off migration applies it; a recorded answer replaces it. - **Computed, never typed.** Every figure in findings, feature reach and question impact is a rule (reference/knowledge.md § Rules) the knowledge stage evaluates. ## Setup `stardust/spec/spec.config.json` (reference/config.md): `origin`, `scopePath`, `template` rule, `parser` profile (`aem-classic`, `aem-core`, or `generic` for any other site) + main selector, optional `maxPages`, `rum`, `referenceBlocks`. Copy the spec, diff, dynamics and deploy scripts to `stardust/scripts/<skill>/` (the stages import them). ## Stages | # | Stage | Command (from the project root) | Output | |---|---|---|---| | S1 | Inventory | `spec-inventory.mjs` | `<work>/inventory/` | | S2 | Fetch | `spec-fetch.mjs` | `<work>/fetch/` | | S3 | Parse | `spec-parse.mjs` | `<work>/parse/` | | S4 | Links | `spec-links.mjs`, then `spec-fetch.mjs --urls <work>/links/pages.txt --out <work>/links/pages.jsonl` and `spec-parse.mjs --fetch <work>/links/pages.jsonl --out <work>/links` | `<work>/links/` | | S5 | Real-user data (optional) | `spec-rum.mjs` (key from `$RUM_DOMAIN_KEY`) | `<work>/rum/rum.json` | | S6 | First capture | `spec-pick.mjs --components-only`, `spec-capture.mjs` | `<work>/media/` | | S7 | Judgement: mapping | `spec-profile.mjs`, `spec-sheet.mjs <component>`, write `judgement/mapping.json`, `spec-map.mjs` | `<work>/map/page-blocks.jsonl` | | S8 | Variants + visuals | `spec-variants.mjs`, `spec-pick.mjs`, `spec-capture.mjs` | `<work>/map/variants.json`, `<work>/media/` | | S9 | Implementation | `dynamics-detect.mjs --urls <reps> --out <work>/dynamics`, `spec-martech.mjs`, `chrome-explore.mjs <home> <work>/chrome/header.json`; write `judgement/catalog.json`, `implementation.json`, `findings.json`, `search-probes.json` | `<work>/`, `judgement/` | | S10 | Knowledge | `spec-knowledge.mjs` | `knowledge/` | Each stage logs start and end to `stardust/status.jsonl` (`ledger.mjs spec s1-inventory start`). `<work>` is `stardust/.work/spec/`, never committed. Large sites: S2 runs at 4 parallel requests and is resumable — start it, then write config and judgement scaffolding while it runs. One browser job at a time (S6/S8/S9), two tabs. ## Judgement (S7, S9) Start from `templates/`. `mapping.json` and `catalog.json`: reference/judgement.md. `implementation.json`: reference/implementation.md. `findings.json`: 6–10 plain-text `{ title, text, chapter, rank }` headlines. Recorded answers go in `judgement/answers.json`. ## Outputs `judgement/` and `knowledge/` in `stardust/spec/`, committed; reference/knowledge.md is the contract. Raw material, captures and crops stay in `<work>`. ## Gates - S7 passes when `spec-map.mjs` reports no unmapped component and every block in the page blocks is in `catalog.json` (`spec-knowledge.mjs` warns otherwise). - S10 passes when `spec-knowledge.mjs` exits 0 (every rule computed) and every open question has a default. - A blocked origin (S1 or S2 exit 3: bot challenges or refusals on 10% or more) stops the build: ask the user to allow-list the crawler, or to choose `--headed` (the plugin's stealth real-Chrome tier from the diff skill's `live-session.mjs`, as replica uses) or `--archive <date>` (Internet Archive captures, which the provenance and a finding must disclose). Never choose for them, and never work around a block another way. - Before sharing: no customer secret, internal evaluation or other migration's name in the project or the output. ## References - reference/config.md — `spec.config.json`, template rules, parser profiles. - reference/judgement.md — the blind rule, mapping rules, contact sheets, block families, reuse verdicts. - reference/implementation.md — features, martech, data layer, metadata, indexes, locales, open questions. - reference/knowledge.md — the output contract: files, fields, the rule format. - reference/evaluation.md — scoring a spec against a delivered migration; blind re-judgement.