From 84aa381bd35cd51718207da70c502846c2d4b5e9 Mon Sep 17 00:00:00 2001 From: Randall Stillwell Date: Fri, 22 May 2026 23:45:14 -0500 Subject: [PATCH] =?UTF-8?q?convoy:=20scope=20bump-next-js=20(P0=20#8=20?= =?UTF-8?q?=E2=80=94=20unblock=20Vercel=20deploys)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .convoys/bump-next-js.md | 103 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 .convoys/bump-next-js.md diff --git a/.convoys/bump-next-js.md b/.convoys/bump-next-js.md new file mode 100644 index 0000000..865ab45 --- /dev/null +++ b/.convoys/bump-next-js.md @@ -0,0 +1,103 @@ +--- +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.