chore: publish from staged

plugins/react18-upgrade/skills/react18-dep-compatibility/references/router-migration.md

@@ -0,0 +1,87 @@
+# React Router v5 → v6 - Scope Assessment
+
+## Why This Is a Separate Sprint
+
+React Router v5 → v6 is a complete API rewrite. Unlike most React 18 upgrade steps which touch individual patterns, the router migration affects:
+
+- Every `<Route>` component
+- Every `<Switch>` (replaced by `<Routes>`)
+- Every `useHistory()` (replaced by `useNavigate()`)
+- Every `useRouteMatch()` (replaced by `useMatch()`)
+- Every `<Redirect>` (replaced by `<Navigate>`)
+- Nested route definitions (entirely new model)
+- Route parameters access
+- Query string handling
+
+Attempting this as part of the React 18 upgrade sprint will scope-creep the migration significantly.
+
+## Recommended Approach
+
+### Option A - Defer Router Migration (Recommended)
+
+Use `react-router-dom@5.3.4` with `--legacy-peer-deps` during the React 18 upgrade. This is explicitly documented as a supported workaround by the react-router team for React 18 compatibility on legacy root.
+
+```bash
+# In the React 18 dep surgeon:
+npm install react-router-dom@5.3.4 --legacy-peer-deps
+```
+
+Document in package.json:
+
+```json
+"_legacyPeerDepsReason": {
+  "react-router-dom@5.3.4": "Router v5→v6 migration deferred to separate sprint. React 18 peer dep mismatch only - no API incompatibility on legacy root."
+}
+```
+
+Then schedule the v5 → v6 migration as its own sprint after the React 18 upgrade is stable.
+
+### Option B - Migrate Router as Part of React 18 Sprint
+
+Only choose this if:
+
+- The app has minimal routing (< 10 routes, no nested routes, no complex navigation logic)
+- The team has bandwidth and the sprint timeline allows it
+
+### Scope Assessment Scan
+
+Run this to understand the router migration scope before deciding:
+
+```bash
+echo "=== Route definitions ==="
+grep -rn "<Route\|<Switch\|<Redirect" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l
+
+echo "=== useHistory calls ==="
+grep -rn "useHistory()" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l
+
+echo "=== useRouteMatch calls ==="
+grep -rn "useRouteMatch()" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l
+
+echo "=== withRouter HOC ==="
+grep -rn "withRouter" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l
+
+echo "=== history.push / history.replace ==="
+grep -rn "history\.push\|history\.replace\|history\.go" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l
+```
+
+**Decision guide:**
+
+- Total hits < 30 → router migration is feasible in this sprint
+- Total hits 30–100 → strongly recommend deferring
+- Total hits > 100 → must defer - separate sprint required
+
+## v5 → v6 API Changes Summary
+
+| v5 | v6 | Notes |
+|---|---|---|
+| `<Switch>` | `<Routes>` | Direct replacement |
+| `<Route path="/" component={C}>` | `<Route path="/" element={<C />}>` | element prop, not component |
+| `<Route exact path="/">` | `<Route path="/">` | exact is default in v6 |
+| `<Redirect to="/new">` | `<Navigate to="/new" />` | Component rename |
+| `useHistory()` | `useNavigate()` | Returns a function, not an object |
+| `history.push('/path')` | `navigate('/path')` | Direct call |
+| `history.replace('/path')` | `navigate('/path', { replace: true })` | Options object |
+| `useRouteMatch()` | `useMatch()` | Different return shape |
+| `match.params` | `useParams()` | Hook instead of prop |
+| Nested routes inline | Nested routes in config | Layout routes concept |
+| `withRouter` HOC | `useNavigate` / `useParams` hooks | HOC removed |