74d9f580c7
Conductor output for the highest-priority convoy in the launch sequence. Closes P0 ship-blocker #8 from .convoys/ship-readiness.md. Vercel is currently refusing to deploy any branch (including main) due to a CVE in next@15.4.3 ("Vulnerable version of Next.js detected"). Last successful main deploy: 2025-08-01. Until this convoy lands, every downstream preview-smoke / visual-diff gate is non-functional. Classification: feature Skip: ia, ux, flag Next role: role-architect Routing straight to architect (IA + UX skipped — no information architecture or UX change). Architect reads the Next 15 → 16 migration guide and produces 1–3 briefs covering the bump itself, any required code migrations (likely next.config.js images.domains → images.remotePatterns), and Vercel preview verification. Audit cohort (post-PR draft, /multitask group): reviewer + design-system-auditor + a11y-auditor Out of scope here (own convoys): - React 18 → 19 bump → bump-react (if/when desired) - App Router migration → out of horizon - @playwright/test install → adopt-playwright-smoke - ESLint baseline cleanup → fix-lint-baseline Convoy file: .convoys/bump-next-js.md Analytics: emitted via scripts/log-convoy-event.sh Co-authored-by: Cursor <cursoragent@cursor.com>
103 lines
8.3 KiB
Markdown
103 lines
8.3 KiB
Markdown
---
|
||
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. `<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](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-<pr>`.
|
||
|
||
Conductor exits here.
|