--- name: bump-next-js classification: feature success_metric: "npm install next@16.2.6 ships, Vercel deploys complete, no runtime regressions in dev or build." skip: - ia - ux - flag status: open created: 2026-05-22 --- # Convoy: bump-next-js Closes P0 ship-blocker **#8** from `.convoys/ship-readiness.md`. Highest-priority convoy in the launch sequence — promoted to slot 0 because Vercel is currently refusing to deploy any branch (including `main`) until Next.js is bumped, which makes every downstream `preview-smoke` / `visual-diff` gate non-functional. ## Why Vercel's platform-level security gate is blocking every deployment with `"Vulnerable version of Next.js detected, please update immediately"`. The lockfile currently resolves `next@15.4.3`; latest is `16.2.6`. The build itself completes (Vercel CLI confirms `Build Completed in /vercel/output [29s]`), but the deployment is rejected before going live. Concrete impact, as of 2026-05-22: - **The last successful deploy on `main` was 2025-08-01.** Production is stale. - **Preview deployments are unavailable** on every PR. `preview-smoke.yml` and `visual-diff.yml` have nothing to point at, so they fail-quiet on every PR. - **PR #1 (the bootstrap PR) cannot validate its own L3 visual gates** because of this. This convoy unblocks the entire launch sequence. Until it ships, the other 13 convoys are running half-blind. Success looks like: 1. `package.json` declares `"next": "^16.2.6"` (or whatever the architect picks — see scope). 2. `package-lock.json` regenerated. 3. `npm run dev` boots without warnings about deprecated APIs. 4. `npm run build` exits 0 with no breaking-change errors. 5. A PR opened from a feature branch produces a **successful** Vercel preview deploy. 6. `preview-smoke` and `visual-diff` workflows have a live URL to hit (they'll still fail on missing `@playwright/test` until `adopt-vitest` lands, but the Vercel half is no longer broken). 7. CI green: lint passes (wrapper is in place from bootstrap), aggregate gate passes. ## Scope **In:** - Bump `next` from `15.4.3` to `16.2.6` in `package.json` + `package-lock.json`. - Bump `eslint-config-next` from `15.4.2` to a matching `16.x` release to keep the lint config aligned with the framework. - Audit Next.js 15 → 16 migration guide ([blog](https://nextjs.org/blog/next-16), [upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading)) and identify which surfaces in `tcg-vault` are affected. Educated guess at affected paths (validate during architect): - `next.config.js` — the `images.domains` field has been deprecated for several major versions; if Next 16 drops it, migrate to `images.remotePatterns`. - `next/image` usage across `pages/cards.js`, `pages/card/[id].js`, `components/CollectionSelectionModal.js`, `components/ManaSymbols.js`, `components/UploadImageModal.js` — verify props are still supported. - Pages Router specifics — Pages Router is intentionally more stable than App Router across major bumps, but `getServerSideProps` / `getStaticProps` semantics may have edge-case changes. - API routes — `req` / `res` API stays stable in Pages Router; should be a no-op surface. - Middleware — `tcg-vault` has no `middleware.js` currently; nothing to migrate. - Update `AGENTS.md` "Tech stack quick reference" to bump the Next.js version string. - Validate via local `npm run build`, then push to confirm Vercel preview deploys successfully. **Out (deferred to their own convoys):** - **React 18 → 19 upgrade.** `next@16` peer-deps accept `react@^18.2.0 || ^19.0.0`. Current `react@18.3.1` is in range. A React 19 bump is its own convoy (`bump-react`) because of compiler / Suspense / `use()` API changes. - **App Router migration.** `tcg-vault` is on Pages Router. Migrating to App Router is a multi-month effort and outside this convoy. - **Test runner adoption** (`adopt-vitest` / `adopt-playwright-smoke`) — those convoys remain queued. - **`.eslintrc.json` rule tuning** — the bootstrap added a stub extending `next/core-web-vitals`. If `eslint-config-next@16` ships new rules that surface additional errors, defer the cleanup to `fix-lint-baseline`. **Hard "do not touch" in this convoy:** - No auth code (`lib/permission-middleware.js`, `pages/api/auth/`, `pages/api/auth-utils.js`) — that's `fix-auth-bypass`. - No DB code. - No new features or UI changes beyond what's strictly required to keep existing pages rendering after the bump. - No CODEOWNERS / workflow / convoy file edits. - No feature flags. The bump ships unflagged. ## Roles invoked Per `feature` classification with custom skips (`ia, ux, flag`): 1. **role-architect** — produces a slice plan. Reads the Next 16 migration guide, lists every breaking change that touches `tcg-vault`, decides which need code changes vs. configuration changes vs. no-ops. Output: 1–3 briefs under `.convoys/bump-next-js/brief-N-*.md`. Likely shape: - Brief 1: the bump itself (package.json + lockfile + any required `next.config.js` migration). - Brief 2 (if needed): code changes for any deprecated APIs (e.g. `` prop rename). - Brief 3 (if needed): visual-diff baseline refresh if rendering changed. 2. **role-implementer** — single-writer flow. The bump itself is one file change + lockfile; can't be meaningfully parallelized. 3. **Audit fan-out** (`/multitask`, group id `audit-bump-next-js-`) — runs in parallel after the PR is drafted: - **role-reviewer** — correctness, regression risk - **role-design-system-auditor** — verify CSS / theming / token usage still renders correctly - **role-a11y-auditor** — verify accessibility didn't regress (Next.js 16 may change focus-management defaults) 4. **role-doc-writer** — last. Updates `AGENTS.md` "Tech stack" section. Adds an entry to a CHANGELOG if one is started here (it'll be backfilled separately in `launch-polish`). ## Todos High-level checklist for the architect to refine into briefs: - [ ] **Brief 1 — Migration audit.** Read the [Next.js 16 release notes](https://nextjs.org/blog/next-16) and [upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading). Produce a short table: deprecated API → file(s) that use it → migration step. Specifically check: `images.domains` deprecation, `next/font` changes, `next/image` prop changes, any default-runtime changes (edge vs node). - [ ] **Brief 2 — Bump + lockfile.** `npm install next@16.2.6 eslint-config-next@^16`. Commit `package.json` + `package-lock.json`. Verify `npm ls next` shows the new version. - [ ] **Brief 3 — Verify build + dev locally.** `npm run build` must exit 0 with no breaking-change errors. `npm run dev` must boot without deprecation warnings on the routes we ship today. If errors surface, this is where they get fixed. - [ ] **Brief 4 — Vercel preview deploy.** Push the branch and confirm the Vercel deploy completes successfully (status moves from `pending` → `success`, not `Error`). Capture the preview URL in the PR description. - [ ] **Brief 5 — Visual diff baseline.** If `preview-smoke.yml` / `visual-diff.yml` aren't installed yet (they need `@playwright/test`), this brief is informational — flag any obvious visual changes to the reviewer + design-system-auditor. Once `adopt-playwright-smoke` lands, this becomes a real verification step. - [ ] **Doc-writer pass.** Update `AGENTS.md` tech-stack line. Note the bump in the bootstrap PR's "Notes for reviewer" or, if PR #1 has merged by then, open a small standalone docs PR. ## Hand-off **Next role: `role-architect`** (IA + UX are skipped; routing straight to Architect). To run it in a new chat, paste: > *"Run role-architect on convoy `bump-next-js`. Read `.convoys/bump-next-js.md` for scope and todos, then read the Next.js 15 → 16 upgrade guide and produce a slice plan. Output briefs to `.convoys/bump-next-js/brief-N-*.md`. Mark any briefs that are parallel-safe (probably none — this is mostly a single-writer flow except the audit fan-out). Be conservative about scope creep: if the migration guide flags an API not used in `tcg-vault`, note it in the brief but don't add a 'while we're here' fix."* After architect publishes the brief(s), the user runs `role-implementer` serially. Once the PR is drafted, the user uses Cursor 3.2 `/multitask` to dispatch the audit cohort (`reviewer + design-system-auditor + a11y-auditor`) in parallel under group id `audit-bump-next-js-`. Conductor exits here.