@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/known-failure-modes.md

@@ -11,23 +11,23 @@ gate but still requires consent (D-11).
 
 Each entry is a single fenced ```yaml block with this flat key:value shape.
 
-### Schema v1 (Phase 30, matcher-consumed) — original 6 fields
+### Schema v1 (Phase 30, matcher-consumed) - original 6 fields
 
 These six fields are consumed by `scripts/lib/issue-reporter/triage-matcher.cjs`
 (`matchKnownFailure(errorContext)`). The matcher reads ONLY these fields and
 ignores everything else gracefully (D-04 backward-compat).
 
-- `id` — stable identifier (kebab-case or `KFM-NNN` numeric). Required.
-- `pattern` — JavaScript regex string. Matched against
+- `id` - stable identifier (kebab-case or `KFM-NNN` numeric). Required.
+- `pattern` - JavaScript regex string. Matched against
   `[error.message, error.stack].filter(Boolean).join("\n")`. Required.
-- `diagnosis` — one-sentence plain-English root cause. Required.
-- `remedy` — one-sentence user-runnable action. Required.
-- `severity` — advisory only, one of `low` / `medium` / `high`. Required.
-- `propose_report` — boolean. If `true`, this mode is on the D-11
+- `diagnosis` - one-sentence plain-English root cause. Required.
+- `remedy` - one-sentence user-runnable action. Required.
+- `severity` - advisory only, one of `low` / `medium` / `high`. Required.
+- `propose_report` - boolean. If `true`, this mode is on the D-11
   whitelist: 30-04 may *propose* `--report` at error time for this
   class. Defaults to `false`. Advisory; the matcher does not act on it.
 
-### Schema v2 (Phase 30.5 D-02) — additive fields
+### Schema v2 (Phase 30.5 D-02) - additive fields
 
 These five fields are required on every entry from Phase 30.5 onward.
 They are NOT consumed by the Phase 30 matcher (D-04 backward-compat
@@ -36,22 +36,22 @@ future tooling (e.g. the Phase 30.5-02 fuzzy matcher, the Phase 30.5-03
 reflector incubator). Adding them does not change the matcher's
 behaviour for the original 6 fields.
 
-- `symptom` — string, 1–3 sentences. Plain-English description of what
+- `symptom` - string, 1–3 sentences. Plain-English description of what
   the user sees when this failure mode hits. Required.
   *Example:* `'Build fails with EUSAGE about a missing or stale lockfile after a package.json edit.'`
-- `root_cause` — string, 1–2 sentences. Technical explanation of why
+- `root_cause` - string, 1–2 sentences. Technical explanation of why
   the failure happens. Required.
   *Example:* `'npm ci enforces lockfile parity with package.json; manually editing one without the other breaks parity.'`
-- `fix` — string (single line; multi-step encoded as `1) … 2) … 3) …`).
+- `fix` - string (single line; multi-step encoded as `1) … 2) … 3) …`).
   Step-by-step user-runnable remedy. The original `remedy` field stays
   as the short matcher-consumed one-liner; `fix` is the fuller version
   with prerequisites and verification steps. The two MAY differ. Required.
   *Example:* `1) Run npm install once locally. 2) Stage the updated package-lock.json. 3) Commit and re-run npm ci.`
-- `related_phases` — number[] (YAML flow style: `[12, 24]`). Phase numbers
+- `related_phases` - number[] (YAML flow style: `[12, 24]`). Phase numbers
   this mode touches. Empty array `[]` is allowed when the mode is
   cross-cutting and not tied to a specific phase. Required.
   *Example:* `[12, 14.6, 24]`
-- `first_observed_cycle` — string. Cycle slug like `cycle-2026-05`, or
+- `first_observed_cycle` - string. Cycle slug like `cycle-2026-05`, or
   `pre-30.5` for entries harvested from before this catalogue formalised
   the schema. Required.
   *Example:* `'cycle-2026-05'`
@@ -77,7 +77,7 @@ Consumed by `scripts/lib/issue-reporter/triage-matcher.cjs`
 
 ## Entries
 
-### KFM-001 — EACCES on `.design/` write
+### KFM-001 - EACCES on `.design/` write
 
 Permission failure when the plugin writes into `.design/`. Common after
 `sudo`-cloning a repo or running CI as a user without write access to
@@ -97,7 +97,7 @@ related_phases: [11, 22, 29]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-002 — `gh` CLI not on PATH
+### KFM-002 - `gh` CLI not on PATH
 
 The Phase 30 outbound submission path requires the user's `gh` CLI
 (D-05). If it's missing, Plan 30-06 falls back to clipboard + URL.
@@ -117,7 +117,7 @@ related_phases: [30]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-003 — Node.js version mismatch
+### KFM-003 - Node.js version mismatch
 
 `package.json` declares `engines.node: ">=22"`. Older Node versions
 crash on the `--experimental-strip-types` test runner, or fail subtle
@@ -137,7 +137,7 @@ related_phases: [12, 14.6, 24]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-004 — Figma token missing
+### KFM-004 - Figma token missing
 
 Figma-aware flows expect `FIGMA_TOKEN` (or the documented env-var alias)
 to be present. The 401/missing-env error class is recognisable.
@@ -156,7 +156,7 @@ related_phases: [13.2, 18, 19.6]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-005 — Git working tree dirty
+### KFM-005 - Git working tree dirty
 
 Several phase-tooling commands assume a clean working tree (clean
 checkpoints between cycles). A dirty tree surfaces as a stderr line
@@ -176,7 +176,7 @@ related_phases: [22, 23.5, 25]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-006 — `.planning/` directory missing
+### KFM-006 - `.planning/` directory missing
 
 GSD/GDD project commands assume `.planning/` has been initialised by
 `/gsd:new-project`. A bare ENOENT on that path is a clear self-fix.
@@ -195,7 +195,7 @@ related_phases: [22, 23.5]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-007 — `reference/registry.json` invalid JSON
+### KFM-007 - `reference/registry.json` invalid JSON
 
 The Phase 14.5 registry is hand-edited; a stray trailing comma or
 unquoted key surfaces here. Self-fixable, not a maintainer issue.
@@ -214,7 +214,7 @@ related_phases: [14.5, 25]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-008 — MCP server unreachable
+### KFM-008 - MCP server unreachable
 
 When the Figma / GDD MCP servers are not running, commands depending
 on them fail with a clear connection-refused class of error.
@@ -233,10 +233,10 @@ related_phases: [27.7, 33.6]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-009 — Plugin file accidentally deleted
+### KFM-009 - Plugin file accidentally deleted
 
 A user-side `git clean -fdx` or aggressive editor refactor can remove
-plugin files. This is a re-install path, not a bug report path — but
+plugin files. This is a re-install path, not a bug report path - but
 it's on the whitelist because users typically can't tell it apart from
 an upstream regression.
 
@@ -254,7 +254,7 @@ related_phases: [24, 25]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-010 — Disk full / ENOSPC
+### KFM-010 - Disk full / ENOSPC
 
 Out-of-space failures masquerade as obscure write errors. Self-fixable
 by freeing space; not a maintainer report path.
@@ -273,7 +273,7 @@ related_phases: [22, 24, 29]
 first_observed_cycle: 'pre-30.5'
 ```
 
-### KFM-011 — `validate-skill-length` pre-commit hook fails
+### KFM-011 - `validate-skill-length` pre-commit hook fails
 
 The local pre-commit hook `scripts/validate-skill-length.cjs` rejects
 SKILL.md files exceeding the agentskills.io length budget. A commit is
@@ -294,7 +294,7 @@ related_phases: [28.5, 28.6]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-012 — `npm ci` lockfile drift
+### KFM-012 - `npm ci` lockfile drift
 
 `npm ci` enforces strict parity between `package.json` and
 `package-lock.json`. A manual edit to one without the other surfaces as
@@ -314,7 +314,7 @@ related_phases: [25]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-013 — lychee transient SSL failure on whitelisted hosts
+### KFM-013 - lychee transient SSL failure on whitelisted hosts
 
 The link-check job (lychee) reports intermittent TLS errors on a small
 set of well-known authority hosts (`heydonworks.com`,
@@ -335,7 +335,7 @@ related_phases: [13.2, 18]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-014 — `gh pr merge` fast-forward warning (cosmetic)
+### KFM-014 - `gh pr merge` fast-forward warning (cosmetic)
 
 GitHub's CLI surfaces a "Not possible to fast-forward" warning after a
 successful server-side merge in some workflow combinations. The merge
@@ -355,7 +355,7 @@ related_phases: [25]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-015 — CodeQL `js/incomplete-sanitization` false positive
+### KFM-015 - CodeQL `js/incomplete-sanitization` false positive
 
 CodeQL flags `js/incomplete-sanitization` on regex-based input that
 operates on an enum-constrained value. The alert is a false positive in
@@ -375,7 +375,7 @@ related_phases: [25, 27.5]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-016 — `gitleaks` false positive on documentation examples
+### KFM-016 - `gitleaks` false positive on documentation examples
 
 `gitleaks` flags literal example tokens (`ghp_…`, `sk-ant-…`) in
 `reference/*.md` documentation. These are educational examples, not real
@@ -395,7 +395,7 @@ related_phases: [25]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-017 — `release.yml` version mismatch with `plugin.json`
+### KFM-017 - `release.yml` version mismatch with `plugin.json`
 
 The Phase 25 release safeguard rejects a `workflow_dispatch` invocation
 whose input version doesn't match the version declared in `plugin.json`.
@@ -415,7 +415,7 @@ related_phases: [25]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-018 — `npm publish` 404 after `NPM_TOKEN` rotation
+### KFM-018 - `npm publish` 404 after `NPM_TOKEN` rotation
 
 `npm publish` returns `404 Not Found` from the registry when the
 `NPM_TOKEN` secret has been rotated upstream but the GitHub repo secret
@@ -436,7 +436,7 @@ related_phases: [25]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-019 — macOS symlinked tmpdir comparison failure
+### KFM-019 - macOS symlinked tmpdir comparison failure
 
 Tests that compare a tmpdir-derived path against an expected absolute
 path fail on macOS because `/var/folders/...` is a symlink to
@@ -457,7 +457,7 @@ related_phases: [12, 14.6]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-020 — Windows CRLF vs LF byte-comparison mismatch
+### KFM-020 - Windows CRLF vs LF byte-comparison mismatch
 
 Tests that byte-compare file contents fail on Windows because
 `git show HEAD:<file>` returns LF line endings while
@@ -478,7 +478,7 @@ related_phases: [12, 14.6, 24]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-021 — Skill name contains colon (agentskills.io slug regex)
+### KFM-021 - Skill name contains colon (agentskills.io slug regex)
 
 Skills named with a colon (e.g. `get-design-done:foo`) fail the
 agentskills.io spec validator. The spec reserves colons for namespace
@@ -499,12 +499,12 @@ related_phases: [28.5, 28.6]
 first_observed_cycle: 'cycle-2026-05'
 ```
 
-### KFM-022 — Dependabot alert on transitive optional peer not in resolved tree
+### KFM-022 - Dependabot alert on transitive optional peer not in resolved tree
 
 Dependabot opens an alert for a vulnerable transitive dependency that is
 declared as an optional or peer dep upstream and is NOT actually
 installed (`npm ls <dep>` shows nothing). The alert is dismissible with
-"not vulnerable — not in resolved tree".
+"not vulnerable - not in resolved tree".
 
 ```yaml
 id: KFM-022

package/reference/meta-rules.md

@@ -2,13 +2,13 @@
 
 These rules are framework-invariant across the GDD pipeline. They do not change between cycles, phases, or tasks. Every agent imports `reference/shared-preamble.md`, which aggregates `reference/meta-rules.md` first.
 
-**Tier: L0** (frozen prefix; stabilizes the Anthropic 5-min prompt-cache prefix across agent spawns — the churning L2 body below does NOT invalidate this).
+**Tier: L0** (frozen prefix; stabilizes the Anthropic 5-min prompt-cache prefix across agent spawns - the churning L2 body below does NOT invalidate this).
 
 ---
 
 ## Required Reading Discipline
 
-When the orchestrator's prompt contains a `<required_reading>` block, you MUST read every file it lists with the `Read` tool before taking any other action. Paths prefixed with `@` are file paths — pass them directly to `Read`. Skipping required reading is a hard violation: you will produce stale output that the downstream verifier catches, wasting a full spawn cycle.
+When the orchestrator's prompt contains a `<required_reading>` block, you MUST read every file it lists with the `Read` tool before taking any other action. Paths prefixed with `@` are file paths - pass them directly to `Read`. Skipping required reading is a hard violation: you will produce stale output that the downstream verifier catches, wasting a full spawn cycle.
 
 ## Writes Protocol
 
@@ -52,14 +52,14 @@ resume-hint: <one-sentence instruction for a resumption spawn>
 </context-exhaustion>
 ```
 
-…before your completion marker. The hook captures this into STATE.md so the orchestrator can re-spawn you with a narrower scope. Do not guess when you're near exhaustion — only emit when a concrete obstacle (file too large to read, required diff too wide) forced the call.
+…before your completion marker. The hook captures this into STATE.md so the orchestrator can re-spawn you with a narrower scope. Do not guess when you're near exhaustion - only emit when a concrete obstacle (file too large to read, required diff too wide) forced the call.
 
 A PreToolUse hook at `hooks/budget-enforcer.js` intercepts every `Task` spawn (including the one that invoked you). The hook may:
-- **Short-circuit** your spawn with a cached result from `.design/cache-manifest.json` (transparent — you never run).
+- **Short-circuit** your spawn with a cached result from `.design/cache-manifest.json` (transparent - you never run).
 - **Downgrade** your tier to Haiku at the 80% per-task cap soft-threshold, silently (`auto_downgrade_on_cap: true` in `.design/budget.json`, D-03).
 - **Hard-block** your spawn at the 100% per-task or per-phase cap with an actionable error (D-02).
 
-Implication for you as the agent: **do not assume a specific model tier is live.** Your output must be correct whether you run on Haiku, Sonnet, or Opus. If a task genuinely requires reasoning density beyond Haiku, the `size_budget` + `default-tier` combination should have been set at authoring time so the router routes it correctly — the remedy is a frontmatter update (a Phase 11 reflector proposal), not a mid-run assumption.
+Implication for you as the agent: **do not assume a specific model tier is live.** Your output must be correct whether you run on Haiku, Sonnet, or Opus. If a task genuinely requires reasoning density beyond Haiku, the `size_budget` + `default-tier` combination should have been set at authoring time so the router routes it correctly - the remedy is a frontmatter update (a Phase 11 reflector proposal), not a mid-run assumption.
 
 ---
 

package/reference/migrations/material-3-to-4.md

@@ -1,17 +1,17 @@
-# Material Design Token Migration (M3 → next) — Rule Library
+# Material Design Token Migration (M3 → next) - Rule Library
 
-Honest framing: Google has **not** released a "Material Design 4" spec — Material publicly evolved M2 → M3 (Material You), and there is no public M4. This library is therefore a **forward-looking rule set for migrating a Material-token-based design system to the next Material major**, grounded entirely in the **real, well-documented M2 → M3 token migration** (the `--mdc-*` → `--md-sys-*` reshape, color-role expansion, reference-vs-system token split, typescale rename, and `mwc-*` → `md-*` component rename). Those concrete patterns are the migration *shape* the next major will most plausibly follow; nothing below invents tokens from a fictional spec. GDD never auto-applies — these rules feed `ds-migration-planner` and template `codemod-gen.cjs` output that the USER reviews and runs.
+Honest framing: Google has **not** released a "Material Design 4" spec - Material publicly evolved M2 → M3 (Material You), and there is no public M4. This library is therefore a **forward-looking rule set for migrating a Material-token-based design system to the next Material major**, grounded entirely in the **real, well-documented M2 → M3 token migration** (the `--mdc-*` → `--md-sys-*` reshape, color-role expansion, reference-vs-system token split, typescale rename, and `mwc-*` → `md-*` component rename). Those concrete patterns are the migration *shape* the next major will most plausibly follow; nothing below invents tokens from a fictional spec. GDD never auto-applies - these rules feed `ds-migration-planner` and template `codemod-gen.cjs` output that the USER reviews and runs.
 
 ## Detection
 
 Detect a Material-token design system from `package.json` **only** (no lockfile, no source scan at this stage):
 
 - **Dependencies** (`dependencies` / `devDependencies` / `peerDependencies`):
-  - `@material/web` — Material Web Components (M3-era; the forward-migration target surface).
-  - `@material/*` MDC packages — `@material/button`, `@material/textfield`, `@material/theme`, `@material/typography`, etc. (M2-era MDC Web). Presence of many `@material/<component>` entries strongly signals an M2 MDC system.
-  - `material-components-web` — the MDC Web umbrella package (M2-era).
-  - `@angular/material` — read the **major** version: `<= 14` ≈ M2 theming API, `>= 15` ≈ M3 / MDC-backed components, `>= 17` ≈ M3 tokens default. Pair with `@angular/cdk` major as a cross-check.
-- **Signal strength**: treat as a migration candidate when (a) at least one package above is present **and** (b) the manifest shows Material token usage intent — e.g. a `@material/theme` / `@material/tokens` dep, a `"material"` config block, or MDC/M3 packages pinned to a pre-target major. Manifest-only detection — defer actual token-occurrence scanning to the planner's codemod-gen pass.
+  - `@material/web` - Material Web Components (M3-era; the forward-migration target surface).
+  - `@material/*` MDC packages - `@material/button`, `@material/textfield`, `@material/theme`, `@material/typography`, etc. (M2-era MDC Web). Presence of many `@material/<component>` entries strongly signals an M2 MDC system.
+  - `material-components-web` - the MDC Web umbrella package (M2-era).
+  - `@angular/material` - read the **major** version: `<= 14` ≈ M2 theming API, `>= 15` ≈ M3 / MDC-backed components, `>= 17` ≈ M3 tokens default. Pair with `@angular/cdk` major as a cross-check.
+- **Signal strength**: treat as a migration candidate when (a) at least one package above is present **and** (b) the manifest shows Material token usage intent - e.g. a `@material/theme` / `@material/tokens` dep, a `"material"` config block, or MDC/M3 packages pinned to a pre-target major. Manifest-only detection - defer actual token-occurrence scanning to the planner's codemod-gen pass.
 
 ## Migration rules
 
@@ -30,24 +30,24 @@ Detect a Material-token design system from `package.json` **only** (no lockfile,
 | MD-11 | token-rename | `--mdc-elevation-*` / elevation z-values → `--md-sys-elevation-level0..level5` | Numeric dp elevations become a 6-step token scale; pair with surface-container roles. |
 | MD-12 | token-rename | `--mdc-shape-medium` / corner radii → `--md-sys-shape-corner-medium` (`-small` / `-large` / `-extra-large` / `-full`) | Shape scale renamed and bucketed into corner roles. |
 | MD-13 | new-default | *(opt-in)* → dynamic color enabled (`md.sys.color.*` derived from a seed/source color) | M3 default theming model; replaces a static brand palette. Highest visual delta. |
-| MD-14 | remove-component | `mwc-button` → `md-filled-button` (and `md-outlined-button` / `md-text-button` / `md-tonal-button`) | `@material/web` element rename; one MWC element fans out to explicit M3 variants — no clean 1:1 transform, pick a variant by hand (manual TODO). |
-| MD-15 | remove-component | `mwc-textfield` → `md-filled-text-field` / `md-outlined-text-field` | `mwc-*` → `md-*` rename; one element fans out to 2 variants — appearance now encoded in the element name, choose by hand (manual TODO). |
+| MD-14 | remove-component | `mwc-button` → `md-filled-button` (and `md-outlined-button` / `md-text-button` / `md-tonal-button`) | `@material/web` element rename; one MWC element fans out to explicit M3 variants - no clean 1:1 transform, pick a variant by hand (manual TODO). |
+| MD-15 | remove-component | `mwc-textfield` → `md-filled-text-field` / `md-outlined-text-field` | `mwc-*` → `md-*` rename; one element fans out to 2 variants - appearance now encoded in the element name, choose by hand (manual TODO). |
 | MD-16 | rename-prop | `?outlined` / `?raised` boolean attrs → variant element (per MD-14/MD-15) | Style-toggle props removed; pick the right `md-*` element instead of toggling a flag. |
-| MD-17 | remove-component | `mwc-icon-button-toggle` → *(removed)* — compose `md-icon-button` + `toggle` selected state | Dedicated toggle element dropped; rebuild with base icon-button + selected state. |
+| MD-17 | remove-component | `mwc-icon-button-toggle` → *(removed)* - compose `md-icon-button` + `toggle` selected state | Dedicated toggle element dropped; rebuild with base icon-button + selected state. |
 | MD-18 | rename-class | `.mdc-button` / `.mdc-card` (BEM CSS classes) → web-component element + part styling | M3 Web moves from BEM-class theming to custom-element `::part()` / token styling. |
 
 ## Impact notes
 
-**High visual delta — design + QA review required, do not ship blind:**
+**High visual delta - design + QA review required, do not ship blind:**
 - **Dynamic color (MD-13)**: switching from a fixed brand palette to seed-derived `md.sys.color.*` changes nearly every on-screen color. Confirm seed source, contrast pairs (`on-*` roles), and light/dark tonal output before adopting.
 - **Surface-container roles (MD-05, MD-07)**: replacing elevation-overlay surfaces with tonal containers visibly alters card/sheet/menu backgrounds and divider weight. Audit layering after migration.
-- **Typescale (MD-09, MD-10)**: M2 named styles do not map 1:1 to M3 role sizes — size, weight, line-height, and tracking all move. Expect reflow; review dense text and truncation.
+- **Typescale (MD-09, MD-10)**: M2 named styles do not map 1:1 to M3 role sizes - size, weight, line-height, and tracking all move. Expect reflow; review dense text and truncation.
 
-**Mechanical — codemod-templatable, low judgment per occurrence:**
+**Mechanical - codemod-templatable, low judgment per occurrence:**
 - Pure custom-property renames (MD-01–MD-04, MD-06, MD-08, MD-11, MD-12) are string-substitution-shaped. `codemod-gen.cjs` can template these as find/replace with a token map; still diff-review for false positives in comments, strings, and unrelated `--mdc-*` namespaces.
 
-**Manual-review items — never auto-apply:**
-- **Component renames + fan-out (MD-14, MD-15)**: one source element maps to several target variants; the correct target depends on the original prop set — a human (or planner) must choose. Generated templates should emit a *candidate* mapping plus a TODO, not a committed rename.
-- **Removed components (MD-17)** and **prop→variant collapse (MD-16)**: require reconstructing behavior (selected/toggle state, layout) — flag for hand-editing.
+**Manual-review items - never auto-apply:**
+- **Component renames + fan-out (MD-14, MD-15)**: one source element maps to several target variants; the correct target depends on the original prop set - a human (or planner) must choose. Generated templates should emit a *candidate* mapping plus a TODO, not a committed rename.
+- **Removed components (MD-17)** and **prop→variant collapse (MD-16)**: require reconstructing behavior (selected/toggle state, layout) - flag for hand-editing.
 - **Class→element migration (MD-18)**: BEM-class theming → custom-element `::part()` is a structural rewrite, not a rename; scope as its own task.
-- **Angular major bumps**: when detection keys off `@angular/material`, the framework upgrade (DI, theming mixins, component API) dwarfs the token rename — sequence the framework migration first, tokens second.
+- **Angular major bumps**: when detection keys off `@angular/material`, the framework upgrade (DI, theming mixins, component API) dwarfs the token rename - sequence the framework migration first, tokens second.

package/reference/migrations/mui-v6.md

@@ -1,16 +1,16 @@
-# MUI (Material UI) v5 → v6 — Migration Rule Library
+# MUI (Material UI) v5 → v6 - Migration Rule Library
 
-A proposal-only rule library that `agents/ds-migration-planner.md` reads to draft a v5→v6 migration plan, and that the pure `scripts/lib/migration/codemod-gen.cjs` uses to template codemods the USER reviews and runs. GDD never auto-applies any rule here — every entry is a *proposal* with a human in the loop. v6 is mostly mechanical (import + prefix renames) with two high-visual-delta areas: the `Grid` overhaul and the CSS-theme-variables adoption.
+A proposal-only rule library that `agents/ds-migration-planner.md` reads to draft a v5→v6 migration plan, and that the pure `scripts/lib/migration/codemod-gen.cjs` uses to template codemods the USER reviews and runs. GDD never auto-applies any rule here - every entry is a *proposal* with a human in the loop. v6 is mostly mechanical (import + prefix renames) with two high-visual-delta areas: the `Grid` overhaul and the CSS-theme-variables adoption.
 
 ## Detection
 
-Detect MUI and the v5→v6 boundary from `package.json` only — no lockfile read, no source scan. The planner classifies the project from the dependency graph alone:
+Detect MUI and the v5→v6 boundary from `package.json` only - no lockfile read, no source scan. The planner classifies the project from the dependency graph alone:
 
 - **Is MUI?** `dependencies` / `devDependencies` contains `@mui/material`. Treat the presence of any of these companion packages as corroborating evidence: `@mui/system`, `@mui/icons-material`, `@mui/lab`, `@mui/styled-engine` (or the styled-components variant `@mui/styled-engine-sc`), `@mui/base`.
-- **On v5 (migration applies)?** The `@mui/material` semver range resolves to a `^5` / `5.x` major. Treat `~5`, `>=5 <6`, and a pinned `5.x.y` the same way. A `^6` / `6.x` range means the project is already on v6 — emit no rules. A `^7` range means it has moved past the scope of this library (defer to a v6→v7 library).
-- **Companion-major skew (flag, do not migrate):** if `@mui/material` is `^5` but `@mui/system` or `@mui/styled-engine` resolves to `^6` (or vice-versa), the install is half-upgraded. Surface this as a blocker for the planner — every rule below assumes a coherent v5 baseline, and a mixed graph produces unreliable codemod output.
+- **On v5 (migration applies)?** The `@mui/material` semver range resolves to a `^5` / `5.x` major. Treat `~5`, `>=5 <6`, and a pinned `5.x.y` the same way. A `^6` / `6.x` range means the project is already on v6 - emit no rules. A `^7` range means it has moved past the scope of this library (defer to a v6→v7 library).
+- **Companion-major skew (flag, do not migrate):** if `@mui/material` is `^5` but `@mui/system` or `@mui/styled-engine` resolves to `^6` (or vice-versa), the install is half-upgraded. Surface this as a blocker for the planner - every rule below assumes a coherent v5 baseline, and a mixed graph produces unreliable codemod output.
 - **Peer majors to record** (planner notes, not rules in this library): `@mui/x-data-grid`, `@mui/x-date-pickers`, `@mui/x-charts`, `@mui/x-tree-view`. MUI X tracks its own v5→v6/v7 line on a separate cadence, but a Core v6 bump usually forces an X major bump too. Flag the Core/X pair so the planner sequences both migrations together rather than leaving the graph inconsistent.
-- **Styled engine:** record whether `@mui/styled-engine-sc` (styled-components) is present — it changes how MUI6-19 (`styled`/`deepmerge`) is reviewed versus the default Emotion engine.
+- **Styled engine:** record whether `@mui/styled-engine-sc` (styled-components) is present - it changes how MUI6-19 (`styled`/`deepmerge`) is reviewed versus the default Emotion engine.
 - **Runtime gates:** read `engines.node` and the `typescript` devDependency. v6 requires Node 14+ and TypeScript 4.7+ and drops IE 11 (see MUI6-17); a lower floor in `package.json` is itself a migration task.
 
 ## Migration rules
@@ -21,13 +21,13 @@ Kinds are constrained to: `rename-class`, `rename-prop`, `remove-component`, `to
 |---|---|---|---|
 | MUI6-01 | rename-class | `import { Unstable_Grid2 as Grid2 } from '@mui/material'` → `import { Grid2 } from '@mui/material'` | The `Unstable_` prefix is dropped; `Grid2` is now stable and is slated to become the default `Grid` in the next major. |
 | MUI6-02 | rename-prop | `<Grid item xs={12} sm={6}>` → `<Grid size={{ xs: 12, sm: 6 }}>` | Grid2's per-breakpoint props collapse into one object `size` prop; the standalone `item` prop is gone (every non-container is implicitly an item). |
-| MUI6-03 | rename-prop | `<Grid xs={6}>` → `<Grid size={6}>` | When the value is identical across breakpoints, `size` takes a single number instead of an object — shorthand for the MUI6-02 object form. |
+| MUI6-03 | rename-prop | `<Grid xs={6}>` → `<Grid size={6}>` | When the value is identical across breakpoints, `size` takes a single number instead of an object - shorthand for the MUI6-02 object form. |
 | MUI6-04 | rename-prop | `xsOffset={2} smOffset={3}` → `offset={{ xs: 2, sm: 3 }}` | Per-breakpoint `*Offset` props collapse into one object `offset` prop (single-value form `offset={2}` also allowed). |
 | MUI6-05 | new-default | `<Grid xs>` (boolean auto-grow) → `<Grid size="grow">` | The boolean `true` size value is renamed to the string `"grow"`; a bare boolean breakpoint prop no longer compiles. |
 | MUI6-06 | new-default | `<Grid2 disableEqualOverflow>` → (prop removed) | `disableEqualOverflow` is deleted; v6 Grid2 lays out spacing with CSS `gap`, so the old negative-margin overflow workaround is unnecessary. |
 | MUI6-07 | rename-class | `experimental_extendTheme` → `extendTheme` (from `@mui/material/styles`) | The CSS-vars theme factory leaves experimental status; import the stable name. The `experimental_` alias is removed, not deprecated-with-shim. |
 | MUI6-08 | rename-class | `Experimental_CssVarsProvider as CssVarsProvider` → `CssVarsProvider` | Drop the `Experimental_` prefix. Preferred end-state: v6 `ThemeProvider` now subsumes every CssVarsProvider feature, so consolidating onto a single `ThemeProvider` is the recommended target. |
-| MUI6-09 | new-default | `createTheme({ ... })` → `createTheme({ cssVariables: true, ... })` | Opt-in flag that emits CSS custom properties for the theme; required to read `theme.vars.*` and to get SSR-safe, flash-free dark mode. Off by default — adding it is a proposal, never automatic. |
+| MUI6-09 | new-default | `createTheme({ ... })` → `createTheme({ cssVariables: true, ... })` | Opt-in flag that emits CSS custom properties for the theme; required to read `theme.vars.*` and to get SSR-safe, flash-free dark mode. Off by default - adding it is a proposal, never automatic. |
 | MUI6-10 | token-rename | `theme.palette.primary.main` (in `styled`/`sx`) → `theme.vars.palette.primary.main` | Under `cssVariables: true`, read palette tokens through `theme.vars.*` (CSS-var references) so values resolve per color scheme at runtime instead of being baked in at build time. Plain `theme.palette.*` still returns a value but won't switch schemes via CSS. |
 | MUI6-11 | token-rename | `theme.palette.mode === 'dark' ? a : b` → `theme.applyStyles('dark', { ... })` | Replace color-mode ternaries in `styled`/`sx` with `applyStyles`; ternaries break under CSS-vars dark mode because both schemes are emitted into one stylesheet and the JS branch resolves only once. |
 | MUI6-12 | remove-component | `import { LoadingButton } from '@mui/lab'` → `import { Button } from '@mui/material'` + `loading` / `loadingPosition` props | `LoadingButton` is merged into the core `Button`; the `@mui/lab` export is deprecated. Move `loading`, `loadingPosition`, and `loadingIndicator` onto `Button`. |
@@ -35,24 +35,24 @@ Kinds are constrained to: `rename-class`, `rename-prop`, `remove-component`, `to
 | MUI6-14 | rename-class | `listItemClasses` (e.g. `.Mui-selected`, `.Mui-focusVisible` keys) → `listItemButtonClasses` | Companion to MUI6-13: the interactive state class keys move from the `ListItem` class object to `ListItemButton`, so any `styleOverrides` or CSS targeting those keys must be re-pointed. |
 | MUI6-15 | new-default | `<Divider orientation="vertical" />` renders an `hr` element → renders a `div` | A vertical `Divider` now emits a `div` carrying a separator ARIA role (an `hr` cannot be vertical/inline). Update any CSS or test selector that assumed an `hr` element. |
 | MUI6-16 | new-default | `AccordionSummary` content is bare → wrapped in an `h3` heading element | The summary is wrapped in a heading by default; override the level via `slotProps={{ heading: { component: 'h4' } }}`. Affects heading-order audits and heading-based selectors/queries. |
-| MUI6-17 | new-default | Node 12 / TS 3.5 / IE 11 baseline → Node 14+, TS 4.7+, IE 11 dropped | Raise `engines.node`, bump the `typescript` devDependency, and remove IE-11 polyfills / transpile targets. Pure compatibility surface — no component code shape change. |
+| MUI6-17 | new-default | Node 12 / TS 3.5 / IE 11 baseline → Node 14+, TS 4.7+, IE 11 dropped | Raise `engines.node`, bump the `typescript` devDependency, and remove IE-11 polyfills / transpile targets. Pure compatibility surface - no component code shape change. |
 | MUI6-18 | remove-component | UMD bundle (`@mui/material/umd`, CDN `<script>` usage) → (removed) | The pre-bundled UMD build is dropped (~2.5 MB saved). Move CDN/`<script>` consumers to a bundler or native ESM; pure-ESM package `exports` are enforced, so deep internal `lib/` import paths also stop resolving. |
-| MUI6-19 | token-rename | `import { deepmerge } from '@mui/utils'`; deep-spread of `theme.palette` in `styleOverrides` → re-verify against `@mui/utils` v6 | `styled` and `deepmerge` internals were reworked for the CSS-vars theme. Custom `styleOverrides` that mutated or deep-merged `theme.palette` should be re-tested (especially alongside MUI6-10). Flag for manual review; do not auto-rewrite — behavior, not just the import path, may differ. |
+| MUI6-19 | token-rename | `import { deepmerge } from '@mui/utils'`; deep-spread of `theme.palette` in `styleOverrides` → re-verify against `@mui/utils` v6 | `styled` and `deepmerge` internals were reworked for the CSS-vars theme. Custom `styleOverrides` that mutated or deep-merged `theme.palette` should be re-tested (especially alongside MUI6-10). Flag for manual review; do not auto-rewrite - behavior, not just the import path, may differ. |
 | MUI6-20 | rename-prop | `components={{ ... }}` / `componentsProps={{ ... }}` (on slotted components) → `slots={{ ... }}` / `slotProps={{ ... }}` | v6 finalizes the slot-API standardization: the legacy `components`/`componentsProps` pair is deprecated in favor of `slots`/`slotProps` across Modal, Popper, Autocomplete, Badge, Tooltip, and friends. Note that slot *names* are lowercased (e.g. `Backdrop` → `backdrop`). |
-| MUI6-21 | remove-component | `import { Hidden } from '@mui/material'` → `sx` display utilities or `useMediaQuery` | The `Hidden` helper is removed; replace `<Hidden smDown>` with responsive `sx={{ display: { xs: 'none', sm: 'block' } }}` or a `useMediaQuery` guard. There is no drop-in component — this is a manual rewrite. |
+| MUI6-21 | remove-component | `import { Hidden } from '@mui/material'` → `sx` display utilities or `useMediaQuery` | The `Hidden` helper is removed; replace `<Hidden smDown>` with responsive `sx={{ display: { xs: 'none', sm: 'block' } }}` or a `useMediaQuery` guard. There is no drop-in component - this is a manual rewrite. |
 | MUI6-22 | rename-class | `createMuiTheme` / `adaptV4Theme` (lingering v4 aliases) → `createTheme` | Any remaining v4-era `createMuiTheme` alias and the `adaptV4Theme` shim are removed in v6; collapse onto `createTheme`. Surfaces mainly in codebases that did a partial v4→v5 pass and left the aliases in place. |
 
 ## Impact notes
 
-High visual delta — these require human review of the rendered result, not just a green diff:
+High visual delta - these require human review of the rendered result, not just a green diff:
 
 - **Grid overhaul (MUI6-01…06):** moving off the `item xs={}` layout model to `size={{}}` *plus* the switch to CSS `gap` spacing can shift column widths, gutters, and wrap behavior. Generate the codemod proposal, then require a side-by-side visual diff before accepting. The official `v6.0.0/grid-v2-props` codemod covers the prop rename but not bespoke spacing/negative-margin math.
-- **CSS theme variables (MUI6-09…11):** enabling `cssVariables: true` together with the `theme.vars.*` and `applyStyles` migration changes how *every* themed color resolves and how dark mode flips. This touches the whole surface at once — stage it behind a feature flag and review color and contrast holistically, not file-by-file.
+- **CSS theme variables (MUI6-09…11):** enabling `cssVariables: true` together with the `theme.vars.*` and `applyStyles` migration changes how *every* themed color resolves and how dark mode flips. This touches the whole surface at once - stage it behind a feature flag and review color and contrast holistically, not file-by-file.
 - **Structural DOM rules (MUI6-13…16):** `ListItemButton` nesting, the vertical `Divider` → `div`, and the Accordion `h3` wrap all change the rendered DOM and heading order. Re-run accessibility and heading-order audits and fix brittle element/heading selectors in tests.
 
-Mechanical — low risk, but still proposal-only (the USER reviews every generated patch):
+Mechanical - low risk, but still proposal-only (the USER reviews every generated patch):
 
 - **Import / prefix / class renames** (MUI6-01, MUI6-07, MUI6-08, MUI6-12, MUI6-14) and the **engine bumps** (MUI6-17) are find-and-replace–class changes that `codemod-gen.cjs` can template safely. MUI6-18 is mechanical to detect but its *fix* (re-tooling a CDN consumer onto a bundler) is a build-system change, so route it to manual.
-- **MUI6-19** looks mechanical (one import) but hides a behavior change — always tag it manual-review, never auto-apply.
+- **MUI6-19** looks mechanical (one import) but hides a behavior change - always tag it manual-review, never auto-apply.
 
-Sequencing: do the prefix/import/class renames first (smallest blast radius), then the Grid pass, then the CSS-vars pass last (largest blast radius, and it interacts with MUI6-19). Resolve any companion-major skew and the peer MUI X majors surfaced in Detection *before* starting — a Core v6 bump typically drags an `@mui/x-*` major along with it.
+Sequencing: do the prefix/import/class renames first (smallest blast radius), then the Grid pass, then the CSS-vars pass last (largest blast radius, and it interacts with MUI6-19). Resolve any companion-major skew and the peer MUI X majors surfaced in Detection *before* starting - a Core v6 bump typically drags an `@mui/x-*` major along with it.

package/reference/migrations/shadcn-v2.md

@@ -1,31 +1,31 @@
-# shadcn/ui v1 → v2 — Migration Rule Library
+# shadcn/ui v1 → v2 - Migration Rule Library
 
 This library encodes the concrete, mechanical changes a project must make when moving a shadcn/ui codebase from the v1 era (Tailwind v3, HSL CSS variables, Radix `forwardRef`) to the v2 era (Tailwind v4 CSS-first theming, OKLCH variables, React 19 ref-as-prop). It is consumed by `agents/ds-migration-planner.md` to scope a migration and by `scripts/lib/migration/codemod-gen.cjs` to emit jscodeshift / ast-grep templates.
 
-Every rule below is **proposal-only**. GDD never auto-applies a migration: the codemod generator emits reviewable templates, and the user inspects and runs each one before it touches the working tree. Treat the rules as a checklist the planner reasons over, not an executable patch — the planner's job is to scope, order, and impact-score, not to mutate code.
+Every rule below is **proposal-only**. GDD never auto-applies a migration: the codemod generator emits reviewable templates, and the user inspects and runs each one before it touches the working tree. Treat the rules as a checklist the planner reasons over, not an executable patch - the planner's job is to scope, order, and impact-score, not to mutate code.
 
 ## Detection
 
-shadcn/ui is **CLI-managed copy-in source**, not a versioned runtime dependency — the component code lives in the repo (`components/ui/*`), so there is no `shadcn` line in `dependencies` to read a version from. The planner therefore infers the era from `package.json` plus the project's `components.json`.
+shadcn/ui is **CLI-managed copy-in source**, not a versioned runtime dependency - the component code lives in the repo (`components/ui/*`), so there is no `shadcn` line in `dependencies` to read a version from. The planner therefore infers the era from `package.json` plus the project's `components.json`.
 
 Primary boundary signals, strongest first:
 
 - **`tailwindcss` major in `package.json`** is the single strongest signal: `^3.x` → v1 era; `^4.x` → v2 era. Almost everything else follows from this.
-- **`components.json` shape** — its presence confirms a shadcn project. A non-empty `tailwind.config` key (a path to a JS/TS config) signals v1; an empty `tailwind.config` string plus a `tailwind.css` pointing at a file that opens with `@import "tailwindcss"` signals v2.
-- **`react` / `react-dom` major** — `^19` indicates the project can use ref-as-prop and is on the v2 track; `^18` means `forwardRef` shims in the component source are still load-bearing.
+- **`components.json` shape** - its presence confirms a shadcn project. A non-empty `tailwind.config` key (a path to a JS/TS config) signals v1; an empty `tailwind.config` string plus a `tailwind.css` pointing at a file that opens with `@import "tailwindcss"` signals v2.
+- **`react` / `react-dom` major** - `^19` indicates the project can use ref-as-prop and is on the v2 track; `^18` means `forwardRef` shims in the component source are still essential.
 
 Supporting (corroborating, not decisive) signals:
 
-- **`@radix-ui/*` versions** — v1 pins per-primitive packages (e.g. `@radix-ui/react-dialog`); late-v2 projects often consolidate onto the unified `radix-ui` package. Either pattern is acceptable; the version floor matters more than the package name.
-- **Animation dep** — `tailwindcss-animate` present → v1; `tw-animate-css` → v2.
-- **`tailwind-merge` major** — `^2` → v1; `^3` → v2.
-- **Neutral deps** — `next-themes`, `lucide-react`, `class-variance-authority`, `clsx` appear in both eras and are **not** boundary signals.
+- **`@radix-ui/*` versions** - v1 pins per-primitive packages (e.g. `@radix-ui/react-dialog`); late-v2 projects often consolidate onto the unified `radix-ui` package. Either pattern is acceptable; the version floor matters more than the package name.
+- **Animation dep** - `tailwindcss-animate` present → v1; `tw-animate-css` → v2.
+- **`tailwind-merge` major** - `^2` → v1; `^3` → v2.
+- **Neutral deps** - `next-themes`, `lucide-react`, `class-variance-authority`, `clsx` appear in both eras and are **not** boundary signals.
 
-Version detection is **from `package.json` only** — never execute the shadcn CLI, hit a network registry, or shell out to resolve versions. If `tailwindcss` is absent or unparseable, the planner reports "era undetermined" rather than guessing.
+Version detection is **from `package.json` only** - never execute the shadcn CLI, hit a network registry, or shell out to resolve versions. If `tailwindcss` is absent or unparseable, the planner reports "era undetermined" rather than guessing.
 
 ## Migration rules
 
-Each row is one codemod target. `Kind` is drawn from the `codemod-gen.cjs` enum: `rename-class` | `rename-prop` | `remove-component` | `token-rename` | `new-default`. Rule IDs are stable — the planner references them in its impact report and the generator names emitted templates after them.
+Each row is one codemod target. `Kind` is drawn from the `codemod-gen.cjs` enum: `rename-class` | `rename-prop` | `remove-component` | `token-rename` | `new-default`. Rule IDs are stable - the planner references them in its impact report and the generator names emitted templates after them.
 
 | Rule ID | Kind | From → To | Note |
 |---|---|---|---|
@@ -38,11 +38,11 @@ Each row is one codemod target. `Kind` is drawn from the `codemod-gen.cjs` enum:
 | SHADCN-07 | remove-component | `components/ui/toast.tsx` + `hooks/use-toast.ts` + Radix `<Toaster/>` → `sonner` `<Toaster/>` + `toast` import | The Radix-based toast and the `useToast` hook are removed in favor of Sonner. Imports of `useToast` / `@/components/ui/use-toast` must be rewritten to `import { toast } from "sonner"`. Behavioral + public-API change. |
 | SHADCN-08 | rename-prop | `useToast()` call sites `toast({ title, description, variant })` → sonner `toast(title, { description })` / `toast.error(…)` | Sonner's signature differs from the v1 hook object form; `variant: "destructive"` maps to `toast.error`. Every call site needs reshaping. Pairs with SHADCN-07. |
 | SHADCN-09 | token-rename | `tailwindcss-animate` plugin + dep → `tw-animate-css` via `@import "tw-animate-css"` in the CSS entry | The animation-utilities package is renamed. Remove the old devDependency and its plugin entry, add the new CSS import. Utility class names (`animate-in`, `fade-in-0`, `zoom-in-95`) are preserved. |
-| SHADCN-10 | new-default | `components.json` `"style": "default"` → `"style": "new-york"` | The `default` style is removed in v2; `new-york` is the only remaining style, so any re-added component pulls new-york source. Some spacing, border, and icon-size defaults shift — moderate visual delta. |
+| SHADCN-10 | new-default | `components.json` `"style": "default"` → `"style": "new-york"` | The `default` style is removed in v2; `new-york` is the only remaining style, so any re-added component pulls new-york source. Some spacing, border, and icon-size defaults shift - moderate visual delta. |
 | SHADCN-11 | rename-class | paired `h-4 w-4`, `h-6 w-6` icon sizing → `size-4`, `size-6` | v2 source adopts the `size-*` shorthand (Tailwind ≥3.4). Safe equivalent of matched `h-*`/`w-*`; mechanical, no visual delta. Only collapse pairs where the two values are equal. |
 | SHADCN-12 | rename-prop | `cn()` relying on `tailwind-merge@^2` → `^3` | `tailwind-merge` v3 changes some merge-conflict resolution internals. Bump the dependency and re-verify `cn()` output where custom classes overlap component defaults. The `lib/utils.ts` `cn` body itself is unchanged. |
 | SHADCN-13 | remove-component | per-primitive `@radix-ui/react-*` imports → unified `radix-ui` namespace imports | Optional in v2: `import * as DialogPrimitive from "@radix-ui/react-dialog"` → `import { Dialog as DialogPrimitive } from "radix-ui"`. Removes many small deps; not required for correctness, so flag as opt-in only. |
-| SHADCN-14 | rename-class | `focus:ring-2 ring-offset-2` focus styles → `focus-visible:ring-[3px] focus-visible:ring-ring/50` | v2 components standardize on `focus-visible` plus a softened ring (`ring/50`, 3px). Visible focus-state change — moderate visual delta, and accessibility-relevant, so it cannot be silently dropped. |
+| SHADCN-14 | rename-class | `focus:ring-2 ring-offset-2` focus styles → `focus-visible:ring-[3px] focus-visible:ring-ring/50` | v2 components standardize on `focus-visible` plus a softened ring (`ring/50`, 3px). Visible focus-state change - moderate visual delta, and accessibility-relevant, so it cannot be silently dropped. |
 | SHADCN-15 | token-rename | add v2 chart + sidebar tokens (`--chart-1..5`, `--sidebar`, `--sidebar-foreground`, …) absent in v1 themes | v2 ships extra semantic variables. If the project uses the Chart or Sidebar components, the `@theme` / `:root` block must gain these tokens or those components render unstyled. No-op for projects that use neither. |
 | SHADCN-16 | new-default | `tailwind.config` `darkMode: ["class"]` → CSS `@custom-variant dark (&:is(.dark *))` | v4 expresses the dark variant in CSS rather than JS config; the `darkMode` array key is dropped and replaced by a `@custom-variant` declaration in the stylesheet entry. |
 
@@ -50,27 +50,27 @@ Each row is one codemod target. `Kind` is drawn from the `codemod-gen.cjs` enum:
 
 The planner scores each rule as **visual-delta × usage × tests** to order the migration and decide what needs human eyes before the user runs the codemod.
 
-**High visual-delta — review with screenshots / visual diff:**
+**High visual-delta - review with screenshots / visual diff:**
 
-- SHADCN-02 + SHADCN-03 — the whole HSL→OKLCH color move. Intended to be visually neutral, but it rewrites every color value, so it must be *proven* neutral against a baseline, not assumed.
-- SHADCN-10 — `default`→`new-york` shifts spacing, radius, and icon defaults across the component set.
-- SHADCN-14 — the focus-ring restyle changes a visible interaction state.
-- SHADCN-15 — missing chart/sidebar tokens make those components render wrong (unstyled), which reads as a large visual delta where they're used.
+- SHADCN-02 + SHADCN-03 - the whole HSL→OKLCH color move. Intended to be visually neutral, but it rewrites every color value, so it must be *proven* neutral against a baseline, not assumed.
+- SHADCN-10 - `default`→`new-york` shifts spacing, radius, and icon defaults across the component set.
+- SHADCN-14 - the focus-ring restyle changes a visible interaction state.
+- SHADCN-15 - missing chart/sidebar tokens make those components render wrong (unstyled), which reads as a large visual delta where they're used.
 
-**High behavioral / API delta — manual review required:**
+**High behavioral / API delta - manual review required:**
 
-- SHADCN-07 + SHADCN-08 — toast → Sonner changes a public API and runtime behavior. Call-site reshaping cannot be fully mechanical (variant mapping, return values), so every notification flow should be re-tested by hand.
-- SHADCN-12 — `tailwind-merge` v3 can silently change which class wins in a merge. Review anywhere custom classes are layered over component defaults.
+- SHADCN-07 + SHADCN-08 - toast → Sonner changes a public API and runtime behavior. Call-site reshaping cannot be fully mechanical (variant mapping, return values), so every notification flow should be re-tested by hand.
+- SHADCN-12 - `tailwind-merge` v3 can silently change which class wins in a merge. Review anywhere custom classes are layered over component defaults.
 
-**Structural, low visual-delta — codemod-friendly, light review:**
+**Structural, low visual-delta - codemod-friendly, light review:**
 
-- SHADCN-01, SHADCN-04, SHADCN-16 relocate theming from JS config into CSS. Mechanical once the target `@theme` shape is fixed, but they touch the build entry — a single broken import fails the whole stylesheet, so verify the app boots rather than diffing pixels.
+- SHADCN-01, SHADCN-04, SHADCN-16 relocate theming from JS config into CSS. Mechanical once the target `@theme` shape is fixed, but they touch the build entry - a single broken import fails the whole stylesheet, so verify the app boots rather than diffing pixels.
 
-**Purely mechanical — auto-generatable templates, spot-check only:**
+**Purely mechanical - auto-generatable templates, spot-check only:**
 
 - SHADCN-05 (`forwardRef`→ref-as-prop), SHADCN-06 (`data-slot`), SHADCN-09 (`tailwindcss-animate`→`tw-animate-css`), SHADCN-11 (`h-*/w-*`→`size-*`). Deterministic AST rewrites with no intended visual change. Weight **usage** (file count) heavily here, since these fan out across every component file and dominate the diff size.
 
-**Opt-in — never blocking:**
+**Opt-in - never blocking:**
 
 - SHADCN-13 (Radix package consolidation) is dependency hygiene only. Gate it behind explicit user opt-in; never hold up a migration on it.