Stardust Consumer Upgrade

Announce

At the start, say: "Using the stardust-consumer-upgrade skill for a safe Stardust upgrade in {repo_name}." For fleet mode, say: "Using the stardust-consumer-upgrade skill for fleet upgrade — {n} repos across {n_waves} waves."

When to Use

• Upgrading @multiverse-io/stardust-react and/or @multiverse-io/stardust in any Multiverse consumer app.
• Preparing a consumer for a design system milestone (rebrand, token migration, etc.).
• Running any risk-tiered upgrade that needs visual confidence.
• Upgrading multiple repos in a coordinated wave sequence (fleet mode).

Inputs (Resolve Before Starting)

The agent MUST know or discover these before proceeding:

Consumer Registry

All known Stardust consumers with current versions, risk tiers, and repo structure. The agent should confirm versions at runtime via the discovery step — repos may change.

Critical Changelog Boundaries

The agent MUST check whether the repo's current version is below each boundary. If the upgrade crosses a boundary, flag it to Sasha before continuing.

HIGH severity — visual or behavioral breaking potential

MEDIUM severity — behavioral or a11y change

For the full changelog and risk scoring rubric, see ~/LangolfVault/Multiverse/Stardust/Plans/Stardust Consumer Upgrade Investigation.md.

Mandatory Guardrails

1. Pull fresh changes before version bump.
2. Ensure there are no untracked files before starting upgrade work.
3. Use Linear branch naming: feat/<linear_issue>-stardust-upgrade-<repo_name>.
4. Keep screenshot artifacts untracked (.artifacts/ or similar, gitignored).
5. If PR scope is component-only, remove tooling/config changes before opening PR.

Workflow — Single Repo

1) Discovery — Detect Repo Structure

Do NOT assume the registry is current. Run these checks in the target repo:

repo_root={repo_name}

# Detect package manager
ls "$repo_root"/yarn.lock "$repo_root"/pnpm-lock.yaml "$repo_root"/package-lock.json 2>/dev/null

# Detect monorepo structure
ls "$repo_root"/turbo.json "$repo_root"/lerna.json 2>/dev/null
cat "$repo_root"/package.json | jq -r '.workspaces // empty' 2>/dev/null

# Find all package.json files that reference stardust
rg -l "stardust" --glob "package.json" "$repo_root"

# Check current installed versions
rg '"@multiverse-io/stardust' --glob "package.json" "$repo_root"

Record:

• Package manager (yarn / npm / pnpm)
• Monorepo? (turbo.json / workspaces field / lerna.json)
• Package path(s) containing Stardust deps
• Current version(s) of stardust-react and stardust
• Version delta to target
• Changelog boundaries crossed (check against Critical Changelog Boundaries above)

If the repo has a lockfile in a subdirectory (e.g. js/yarn.lock), the install command must run from that subdirectory.

2) Preflight — Clean Branch

git -C "$repo_root" fetch origin
git -C "$repo_root" status --short

• If clean on main: create branch from origin/main.
• If dirty or detached: create a worktree.

# Worktree (use when main is dirty)
git -C "$repo_root" worktree add _wt_{repo_name}_{linear_issue} -b feat/{linear_issue}-stardust-upgrade-{repo_name} origin/main

3) Bump Stardust

Run the install command appropriate for the detected package manager and package path.

yarn (root-level or workspace):

yarn add @multiverse-io/stardust-react@{target_version}
# or for workspaces:
yarn workspace {workspace_name} add @multiverse-io/stardust-react@{target_version}

npm:

npm install @multiverse-io/stardust-react@{target_version} @multiverse-io/stardust@{core_target}

For core-only consumers (guide-allocation-engine, sync-sessions): bump only @multiverse-io/stardust.

For monorepos with multiple workspaces (atlas): bump in each workspace that has the dep.

4) Risk Check

Cross-reference the repo's current version against the Critical Changelog Boundaries table above. For each crossed boundary:

• List the affected component + change
• Check if the repo uses that component: rg -l "ComponentName" --type ts --type tsx "$repo_root"
• If the component is in use AND the boundary is HIGH severity: stop and flag to Sasha
• If MEDIUM severity: note in PR body, proceed with extra validation

For deeper risk assessment, read Stardust Consumer Upgrade Investigation.md.

5) Validate

Run checks appropriate for the repo:

• Always run TypeScript check first for repos crossing the 4.3.0 Button typing boundary.
• Confirm lockfile updates only where expected (no unrelated dep changes).
• If env validation blocks local build, use SKIP_ENV_VALIDATION=1 or equivalent.

6) Visual Validation (Optional but Recommended for Tier 1-3)

• Capture Storybook screenshots or app screenshots before/after for Stardust-affected surfaces.
• Generate side-by-side comparison: Before | After | Diff highlight.
• Keep artifacts local in .artifacts/ (gitignored).

7) Regression Fix Track

If regressions appear:

• Prefer a small shared wrapper component in app code over patching Stardust.
• Apply scoped CSS override only for the wrapper class.
• Update affected usage sites to wrapper imports.
• Re-capture and verify diff.

8) Scope Cleanup

Before PR, enforce the agreed scope:

• Component-only PR: keep only component/style/import fixes + version bump.
• Remove Storybook/VRT setup files if not part of final scope.
• Remove unrelated lockfile changes if any snuck in.

9) PR + Review Request

PR body template:

## What changed
- Bumped `@multiverse-io/stardust-react` from {old_version} to {target_version}
- [list any regression fixes or wrapper components added]

## Why
{upgrade_reason}

## Scope
{describe what's included and explicitly what's excluded}

## Changelog boundaries crossed
{list each boundary version + component + whether the component is in use}

## Validation
- [ ] `tsc --noEmit` passed
- [ ] Lint passed
- [ ] Build passed
- [ ] Visual comparison: [attach or link artifacts]
- [ ] Risk signals addressed: [list]

## Risk tier
{tier} — score {score}/5 (from Consumer Registry)

Workflow — Fleet Mode (Multi-Repo Wave Upgrade)

Use when upgrading multiple repos in a coordinated sequence. Fleet mode runs the single-repo workflow per repo but enforces wave ordering to catch regressions early in low-risk repos before touching high-risk ones.

Wave sequence

Fleet execution steps

1. Confirm target version and linear issue — single linear issue can cover fleet, or one per wave.
2. Run Wave 0 — core-only bumps. Validates that @multiverse-io/stardust@{core_target} is clean.
3. Run Wave 1 — one repo at a time. Each repo follows the full single-repo workflow (Steps 1-9). Open PRs but don't merge until all Wave 1 PRs pass.
4. Gate check — review Wave 1 results. If any unexpected regressions, assess whether they'll compound in Wave 2/3.
5. Run Wave 2 — design review required for Choicebox/Badge surfaces. Flag visual diffs to Sasha.
6. Gate check — all Wave 2 PRs pass CI + design sign-off.
7. Run Wave 3 — pre-work required before bump:
   • hello_app + evidence_management: run tsc --noEmit against current code first to establish baseline error count
   • ariel: check Switch size usage (rg 'size="medium"' --glob '*.tsx') and SegmentedControl usage
8. Report — summary table of all PRs with status, risk tier, and any regressions found.

Fleet parallelization

Within a wave, repos can be upgraded in parallel (separate worktrees or separate agent instances). Never run repos from different waves in parallel — wave ordering is the safety gate.

Rollback

If an upgrade causes issues after merge:

repo_root={repo_name}

# Revert the upgrade commit
git -C "$repo_root" revert {upgrade_commit_sha} --no-edit

# Reinstall to restore lockfile
cd {package_path} && {pm} install

# Verify build passes at old version
{pm} run build

If the revert is complex (multiple commits, wrapper components added):

• Create a new branch from main
• Manually set the version back in package.json
• Run full install + validate cycle
• Open a revert PR referencing the original upgrade PR

Definition of Done

• Fresh base pulled, clean branch hygiene confirmed.
• Stardust versions updated correctly in all relevant package paths.
• Changelog boundaries checked and flagged if crossed.
• Validation commands completed (or blockers clearly documented).
• Risk signals from the investigation doc addressed or explicitly deferred.
• Final PR contains only intended files for the agreed scope.
• PR posted with clear what/why and changelog boundaries section.