deckhearth/.convoys/bump-next-js.md

name	classification	success_metric	skip	status	created
bump-next-js	feature	npm install next@16.2.6 ships, Vercel deploys complete, no runtime regressions in dev or build.	ia ux flag	open	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, upgrade guide) 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. <Image> 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-<pr>) — 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 and upgrade guide. 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-<pr>.

Conductor exits here.