---
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: shipped
created: 2026-05-22
---

# Convoy: bump-next-js

**As-shipped:** squash commit `e57ea17` (merged pre-PR-21, 2026-05-23). Closes P0 #8 (Next.js 15.4.3 → 16.2.6).

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.

## Architecture

_Produced by `role-architect` on 2026-05-22 against Next.js 16.2.6 (latest stable; verified via `npm view next version`). Updated 2026-05-23 after four gate-1 scope changes (A, B, C, D — see Decisions log below):_

- _A: scope expanded to include the ESLint v8 → v9 + flat-config migration so `eslint-config-next` can move to `^16` matching `next`._
- _B: pivoted from ESLint v9 to v10 (then-`latest`) after gate-1 re-review of risk R14._
- _C: added `typescript@^5.9.3` as a devDep after an implementer escalation surfaced that `eslint-config-next@16`'s `peerDependenciesMeta.typescript.optional: true` annotation does not make `typescript` runtime-optional._
- _D: reverted the v10 pivot back to v9.39.4 after a pass-2 implementer escalation showed Risk R15 firing empirically (`TypeError: scopeManager.addGlobals is not a function` from `@typescript-eslint/scope-manager@8.59.4` predating v10 GA). v10 deferred to the upstream-blocked `bump-eslint-10` follow-up convoy._

### File plan

| File | Action | Purpose |
| --- | --- | --- |
| `package.json` | modified | Bump `dependencies.next` from `^15.4.2` to `^16.2.6`. Bump `devDependencies.eslint` from `^8` to `^9.39.4` (npm's `maintenance` dist-tag; per Decisions log entry D, reverted from the v10 pin set under entry B after R15 fired empirically). Bump `devDependencies.eslint-config-next` from `15.4.2` to `^16.2.6` to match `next` — peer-dep `eslint: >=9.0.0` accepts v9.39.4 trivially. **Add `devDependencies.typescript: "^5.9.3"`** (per Decisions log entry C — `eslint-config-next@16` bundles `typescript-eslint`, which hard-requires `typescript` at module load under both v9 and v10; the `peerDependenciesMeta.typescript.optional: true` flag only suppresses npm's install-time warning, not the runtime require). Replace `scripts.lint` from `next lint` to `eslint .` (Next 16 removed the `next lint` command). React, react-dom, and all other packages stay unchanged. |
| `package-lock.json` | modified | Regenerated by `npm install`. Reflects the new `next@16.2.6`, `eslint@^9.39.4`, `eslint-config-next@^16.2.6`, and `typescript@^5.9.3` resolutions. Under Decision D the lockfile stays on the v9 dep-tree (`@eslint/eslintrc` is still a v9 transitive dep; the v10 dep-tree changes that would have removed it are deferred to the queued `bump-eslint-10` follow-up convoy). The new `typescript` subtree is small — `typescript` itself has no `dependencies` and no `peerDependencies`. Do not hand-edit. |
| `next.config.js` | modified | Migrate `images.domains: [...]` (deprecated in 16, deprecation warning at startup) to `images.remotePatterns: [...]`. Three patterns, one per CDN currently in `images.domains`. |
| `.eslintrc.json` | **deleted** | The 40-byte legacy stub (`{"extends": "next/core-web-vitals"}`) is replaced by `eslint.config.mjs` because `eslint-config-next@16` only supports flat config. Leaving both files in place would be a footgun. |
| `eslint.config.mjs` | **new** | Flat-config replacement for `.eslintrc.json`. Reproduces the prior `next/core-web-vitals` extends behavior using the verbatim shape from the official Next.js docs (`defineConfig([...nextVitals, globalIgnores([...])])`). `globalIgnores` covers the no-go-zone paths the user specified at gate 1 plus `eslint-config-next`'s documented defaults. |

Doc-writer's `AGENTS.md` "Tech stack" string update is a separate PR by `role-doc-writer` after this one merges (per the convoy's Roles list).

### API surface

**No API changes.** This convoy does not touch `pages/api/**`. The Next.js 16 upgrade guide does not change the Pages-Router `req`/`res` handler signature; `tcg-vault`'s ~30 API handlers all use the legacy `(req, res) => { ... }` shape and continue to work unchanged.

### Schema diff

**No schema changes.** This convoy does not touch the database. Neon Postgres + `scripts/setup-neon-db.js` are out of scope.

### Test plan

`tcg-vault` has no automated test runner installed yet (vitest + Playwright adoption is tracked under `adopt-vitest` and `adopt-playwright-smoke` convoys). For this convoy:

- **Manual smoke per `TESTING_GUIDE.md`** is the verification mechanism. Specifically: home (`/`), login (`/login`), signup (`/signup`), browse (`/cards`), and `/collections` must render without runtime errors after the bump.
- **`npm run build` exiting 0** is the integration test for the Turbopack default-bundler change. No custom webpack config exists in `next.config.js`, so Turbopack should "just work."
- **`npm run lint` running to completion** (regardless of the error count) is the integration test for the ESLint v8 → v9 + flat-config migration (per Decision D — Decision B's pivot to v10 was reverted after R15 fired empirically). The pre-existing baseline of ~100 errors is expected to shift modestly under v9 due to plugin major bumps (`eslint-plugin-react-hooks` v5 → v7, `@next/eslint-plugin-next` 15 → 16) but **not** to shift the way v10 would have (no new `eslint:recommended` rules, no JSX reference tracking, no `no-shadow-restricted-names.reportGlobalThis: true` default — those land later under `bump-eslint-10`). CI's `|| true` wrapper continues to tolerate any non-zero exit. **Counting baseline drift is `fix-lint-baseline`'s job, not this convoy's.** **If `npm run lint` does not run to completion under v9.39.4** — e.g. it crashes with a `TypeError` — see Brief 1's failure-mode classifier under "Local verification." Decision D's expectation is that R15's empirical signature (`scopeManager.addGlobals is not a function`) does NOT recur on v9 because v9 doesn't call `addGlobals`. If a different `TypeError` fires on v9, escalate rather than patching transitive deps.
- **Vercel preview deploy reaching Success state** is the end-to-end integration test. The convoy's `success_metric` ("npm install next@16.2.6 ships, Vercel deploys complete, no runtime regressions in dev or build") is exactly this.
- **Audit fan-out (`/multitask`, group id `audit-bump-next-js-<pr>`)** is the qualitative gate: `role-reviewer` for correctness, `role-design-system-auditor` for token rendering, `role-a11y-auditor` for focus / scroll-behavior regression. They run AFTER the PR is drafted, not as part of this brief.
- Once `adopt-vitest` lands, retrofit a smoke test for `next.config.js` parsing and one for `<img>` (or future `<Image>`) rendering against a fixture page.

### Risk list

- **R1: Turbopack-by-default may surface unexpected build/runtime differences vs webpack.** Per gate-1 decision: accept the default. tcg-vault has no `webpack:` block in `next.config.js`, no custom loaders/aliases, no Sass tilde imports, no `resolve.fallback` workarounds. Likelihood of regression: low. **Fallback per command:** `next build --webpack` and `next dev --webpack`. **If a regression appears, the implementer should reproduce on both bundlers** (run the failing flow once with the default, once with `--webpack`) **before deciding whether to revert the bump or pin the script to webpack.** Capture the reproduction in the PR description for `role-reviewer` to triage. Do not pre-emptively add `--webpack` to the scripts.
- **R2 — RESOLVED at gate 1, via the A → B → D path.** Originally: "`eslint-config-next` cannot be bumped to `^16` in this convoy." Gate-1 decision A expanded scope to include the ESLint v8 → v9 + flat-config migration. Decision B pivoted from v9 to v10. Decision D reverted v10 → v9.39.4 after R15 fired empirically on the implementer's pass-2 lint run. **Final pins:** `eslint@^9.39.4`, `eslint-config-next@^16.2.6`, `typescript@^5.9.3`, `.eslintrc.json` deleted, `eslint.config.mjs` created. See R12, R13, R14, R15 below for the residual + reinstated risks. The deferred `migrate-to-eslint-flat-config` convoy is **closed before opening** — its work has been folded in. The `bump-eslint-10` follow-up convoy is **queued as upstream-blocked** — see "Follow-up convoys queued" section.
- **R3: `next lint` removal hard-breaks `npm run lint`.** Without the `scripts.lint` change, both local devs and CI's `npm run lint --if-present` job would invoke a removed command. Mitigation: change script to `eslint .`. CI's existing `|| true` wrapper continues to tolerate the pre-existing lint baseline (~100 errors, tracked under `fix-lint-baseline`).
- **R4: `images.domains` is in `next.config.js` but `next/image` isn't actually used.** Strictly speaking, the migration is preemptive — silences the deprecation warning but adds no functional change. Acceptable: keeps the config valid for the eventual `next/image` adoption. Don't delete the block; that would force re-adding it later.
- **R5: `images.minimumCacheTTL` default changed from 60s to 4h.** Behavior change. Not impactful in `tcg-vault` because `next/image` isn't used. No mitigation required; flag here only so future readers don't re-investigate.
- **R6: Vercel deploy might fail for an unrelated reason.** The convoy's premise is that the platform-level "Vulnerable version" gate is the sole blocker. If the build itself fails on 16 (e.g. an undocumented Turbopack edge case), the fix lands in this brief. If the failure is environmental (env vars, build settings), escalate — that's a different convoy.
- **R7: React 18 stays — intentional.** `next@16` peer-dep accepts `react ^18.2.0 || ^19.0.0`. Current `18.3.1` is in range. **Do not bump React in this convoy.** React 19 has compiler / Suspense / `use()` API changes and is its own convoy (`bump-react`).
- **R8: TypeScript >=5.1.0 required by Next 16.** Partially applicable. **`tcg-vault` source code remains plain JavaScript** — no `tsconfig.json`, no `.ts`/`.tsx` files, no source migration in this convoy. **However, per Decision C (2026-05-23), `typescript@^5.9.3` is now installed as a devDep** because `eslint-config-next@16`'s bundled `typescript-eslint` chain hard-`require`s it at module load. The original parenthetical claim — "`eslint-config-next@16` lists `typescript` as an optional peer (`peerDependenciesMeta.typescript.optional: true`) so JS-only consumers are fine" — was wrong: that flag only suppresses npm's install-time warning; the transitive `@typescript-eslint/typescript-estree@8.59.4` (a regular `dependency`, not a peer) does an unconditional `require('typescript')` at module load. See R16 for the full devDep impact analysis.
- **R9: Node.js floor — DEFANGED under Decision D.** Originally elevated under Decision B because ESLint v10 raised the floor to `^20.19.0 || ^22.13.0 || >=24`. **Under Decision D's v9.39.4 pin**, the ESLint floor reverts to `^18.18.0 || ^20.9.0 || >=21.1.0` (Next 16 also requires `>=20.9.0` — the same floor). CI's `setup-node@v4` `node-version: '20'`, local `node@22.14.0`, and Vercel's default Node 22 all satisfy with margin to spare. The "moving target on `node-version: '20'`" concern from Decision B is inert under v9. **The constraint will reactivate when `bump-eslint-10` lands**; the queued follow-up convoy should pick up the CI pin question (`node-version: '20.19'` or `'lts/iron'`) at that point.
- **R10: `next dev` and `next build` now use separate output dirs (`.next/dev/` vs `.next/`).** `.gitignore` line 28 has `/.next/`, which is a directory rule that covers both subdirs. No `.gitignore` change needed.
- **R11: Convoy file's audit list (line 45) is wrong about `next/image` usage.** Pages listed (`pages/cards.js`, `pages/card/[id].js`, etc.) use plain `<img>` tags, not `<Image>`. Architect verified via `rg "from ['\"]next/image['\"]"` — zero hits in `pages/`, `components/`, `lib/`. Surface this to the convoy author so future planning is not based on the same assumption.
- **R12 (post-gate-1 expansion; revised under Decision D): ESLint flat-config migration + plugin major bumps will shift the lint baseline modestly.** Drivers under v9.39.4: `eslint-config-next@16.2.6` bundles `eslint-plugin-react-hooks@^7` (vs v5) and `@next/eslint-plugin-next@16` (vs 15.4.2). **The v10-specific drivers from Decision B's wording are deferred to the queued `bump-eslint-10` follow-up** (the three new `eslint:recommended` rules, JSX reference tracking, `no-shadow-restricted-names.reportGlobalThis: true` default). `eslint-env` comments would be errors under v10 — we have zero (`rg "eslint-env"` returned zero hits, ✓), so the `bump-eslint-10` follow-up will not snag here either. **The ~100-error baseline is approximate and will move modestly under v9, more substantially when v10 lands.** CI's `|| true` wrapper tolerates any non-zero exit, so this is non-blocking either way. **Do not "fix while we're here."** `fix-lint-baseline` will reconcile against whichever baseline is current.
- **R13: Native flat-config import path is verbatim from Next.js docs — no `FlatCompat` shim added.** Boot-the-brief verified by extracting the published tarball that `eslint-config-next/core-web-vitals` exports a flat-config array (`module.exports = config`). Under Decision D's v9 pin, `@eslint/eslintrc` is still part of v9's own dep tree (v10 dropped it), so the lockfile retains it as a transitive dep — but we still don't import `FlatCompat` from it. If for any reason the native flat-config export resolution fails at install time (e.g. a transitive dep mismatch), the implementer should NOT swap in `@eslint/eslintrc`'s `FlatCompat` — instead, raise it in the PR description and the architect will revisit.
- **R14 — REINSTATED under Decision D (2026-05-23).** ESLint v10.4.0 is the current `latest` dist-tag; this convoy pins `eslint@^9.39.4` (the `maintenance` dist-tag) per Decision D until upstream `eslint-config-next` ships a release that bundles a v10-tested `typescript-eslint`. **Tracked under follow-up convoy `bump-eslint-10` (currently upstream-blocked)** — see "Follow-up convoys queued" section. The previous "RESOLVED at gate 1 (Decision B)" framing was correct given Boot-the-brief evidence at the time; Decision D reverses it specifically because empirical lint runs surfaced R15 firing. **Cost of pinning to maintenance:** small. v9.39.4 still receives security backports if any are needed during the window before `bump-eslint-10` lands; the v9 → v10 jump is a single-line `package.json` edit when prerequisites are met (no flat-config edits required — same `defineConfig` + `globalIgnores` shape works on both majors).
- **R15 — FIRED EMPIRICALLY (pass-2 implementer run, 2026-05-23); RESOLVED BY DECISION D.** Originally framed as: "`eslint-config-next@16.2.6`'s bundled plugin set was published before ESLint v10 (Oct 2025 vs Feb 2026); v10 runtime compatibility is statically unprovable." **What actually fired** was a different (and worse) failure mode than the originally feared `context.getCwd()` / `SourceCode#getJSDocComment()` deprecated-API removals:
  - **Crash signature:** `TypeError: scopeManager.addGlobals is not a function`
  - **Call site:** ESLint v10's `lib/source-code/source-code.js:221` calls `scopeManager.addGlobals(...)` as part of v10's redesigned global-ingestion path.
  - **Missing-method site:** `@typescript-eslint/scope-manager@8.59.4` (transitive dep of `typescript-eslint@8.59.4`, which `eslint-config-next@16.2.6` bundles as a regular `dependency`) does not implement `addGlobals` on its `ScopeManager` class. The method is a v10-introduced extension; v9 used a different ingestion path that `typescript-eslint@8.x` was authored against.
  - **Why bundled-plugin set didn't help:** `@typescript-eslint/scope-manager@8.x` was published Oct/Nov 2025; v10 GA was 2026-02-06. `typescript-eslint` has not yet shipped a v10-tested release. The peer-dep range `eslint: >=9.0.0` is technically satisfied by v10, but the runtime compatibility was not.
  - **Resolution (Decision D):** revert `eslint` to `^9.39.4`. The same `typescript-eslint@8.59.4` works correctly on v9 because v9 doesn't call `addGlobals`. `typescript@^5.9.3` (Decision C) is retained — that install was confirmed correct on pass 2 and is required under both v9 and v10.
  - **R15 stays in the convoy's risk list as FIRED-RESOLVED** so the historical record is preserved and so the queued `bump-eslint-10` follow-up convoy inherits the diagnostic verbatim. The originally feared deprecated-API removals (`context.getCwd()`, etc.) are still live risks for the eventual v10 cutover, but they did not fire on pass 2 — `addGlobals` fired first.
- **R16 (new, post-gate-1 Decision C; status unchanged under Decision D): Adding `typescript` as a devDep brings `typescript@^5.x` and its tooling into the dep tree.** This is universally how JS-only Next.js projects handle `eslint-config-next@16` — the package's `typescript-eslint` transitive dep (specifically `@typescript-eslint/typescript-estree@8.59.4`'s `dist/convert.js:40`) hard-requires `typescript` at runtime despite being flagged `peerDependenciesMeta.optional: true` at the `eslint-config-next` wrapper level (the `optional` annotation only suppresses npm's install-time warning, not the runtime require). **Confirmed correct under Decision D's v9 pin** — pass-2 implementer evidence shows the `typescript` install resolved the original `Cannot find module 'typescript'` crash; the residual `addGlobals` crash was a different failure mode (R15) and is the reason for the v9 revert. No downstream impact expected: `typescript` only runs when lint runs (the JS source code is unchanged, no `tsconfig.json` is created, no `.js` files are renamed); `fix-lint-baseline` and `adopt-vitest` convoys will not be affected. **Engines:** `typescript@5.9.3` requires `node >= 14.17`, well below ESLint v9's `^18.18.0` floor (and v10's `^20.19.0` floor when `bump-eslint-10` lands) — no new Node constraint introduced. **Lockfile impact:** small — `typescript` has no `dependencies` and no `peerDependencies`. **Verified runtime require evidence:** see Brief 1's Boot-the-brief finding #17 for the verbatim 9-site grep of `require('typescript')` in the published `typescript-estree@8.59.4` tarball, all unconditional (no `try/catch`, no dynamic import, no `require.resolve` guard).
### Decomposition

| Brief # | Title | Files | Depends on | Estimated PR size |
| --- | --- | --- | --- | --- |
| 1 | Bump Next.js to 16.2.6 + migrate `next.config.js`, ESLint flat config, and lint script | `package.json` (mod — `next`, `eslint`, `eslint-config-next` bumps + new `typescript` devDep per Decision C), `package-lock.json` (mod), `next.config.js` (mod), `eslint.config.mjs` (new), `.eslintrc.json` (deleted) | _(none)_ | 5 files touched (3 mod, 1 new, 1 deleted), lockfile regen (large auto-diff). True non-lockfile diff: ~31 LOC (~12 of which is the new `eslint.config.mjs`; +1 LOC for the `typescript` devDep line in `package.json`). |

**Still one brief, even after four gate-1 scope changes (A, B, C, D).** Both the Next bump and the ESLint migration touch `package.json`, so they cannot run in parallel anyway — keeping them in one brief gives reviewers one PR, one Vercel preview, and one revert boundary if anything regresses. The cumulative expansion adds ~21 LOC (delete a 40-byte file, add a ~12-LOC `eslint.config.mjs`, three devDep changes in `package.json` — two version bumps for `eslint`/`eslint-config-next` and one new line for `typescript@^5.9.3`). Decision D does not change the LOC count — it re-pins an existing line (`devDependencies.eslint`) from `^10.4.0` back to `^9.39.4`, no addition or deletion. Total non-lockfile diff stays well under the 400-LOC guideline. Decisions C and D do not change the brief count, the brief's `files:` set, or the `slice_dependencies` graph — `package.json` and `package-lock.json` were already in scope from the start. Doc-writer's `AGENTS.md` pass remains a separate PR by `role-doc-writer` per the convoy's Roles list.

The audit fan-out (`role-reviewer` + `role-design-system-auditor` + `role-a11y-auditor`) is **parallel via `/multitask`**, but that's a downstream concern triggered by the conductor after the PR is drafted — not part of the implementer decomposition.

### Slice dependencies (multitask-ready)

```yaml
slice_dependencies:
  - brief: 1
    depends_on: []
    files:
      - package.json
      - package-lock.json
      - next.config.js
      - eslint.config.mjs
    deletes:
      - .eslintrc.json
```

Single brief, no parallelization opportunity at the implementer stage. The conductor should dispatch `role-implementer` serially (no `/multitask` fan-out for the implementer phase). The audit-cohort fan-out happens later, after PR draft, under group id `audit-bump-next-js-<pr>`.

## Decisions (post-IA round)

### A — 2026-05-23: Expand convoy scope to include ESLint v8 → v9 + flat-config migration

**Context.** During the architect's initial Boot-the-brief check, two findings landed at human gate 1:

1. `eslint-config-next@16.2.6` requires `eslint >= 9.0.0` (flat config). The convoy file (line 42) prescribed bumping `eslint-config-next` to `^16` "matching next" but didn't account for this peer-dep cliff. The architect's first-pass plan pinned `eslint-config-next@15.4.2` and flagged the deviation.
2. `next lint` was removed in Next 16. `package.json`'s `lint` script and CI's `npm run lint` both invoke a removed command in 16.

**Decision.** Expand this convoy to include the ESLint v9 + flat-config migration, rather than spinning out a separate `migrate-to-eslint-flat-config` convoy. Rationale: both the Next bump and the ESLint migration touch `package.json`, so they cannot ship in parallel anyway; one PR gives reviewers a single revert boundary; the expansion adds only ~20 LOC of non-lockfile diff (delete `.eslintrc.json`, add `eslint.config.mjs`, two devDep version bumps); and `eslint-config-next@16` ships native flat-config exports so no `FlatCompat` shim or `@eslint/eslintrc` install is needed.

**Specific changes baked into Brief 1:**

- Bump `devDependencies.eslint` from `^8` to `^9.39.4` (latest 9.x; ESLint v10 was released between convoy authoring and now — see Boot-the-brief #5 — but per this decision we stay on 9.x).
- Bump `devDependencies.eslint-config-next` from `15.4.2` to `^16.2.6`.
- Change `scripts.lint` from `"next lint"` to `"eslint ."`.
- Delete `.eslintrc.json` (40-byte stub: `{"extends": "next/core-web-vitals"}`).
- Add `eslint.config.mjs` using the verbatim shape from the [official Next.js docs](https://nextjs.org/docs/app/api-reference/config/eslint): `defineConfig([...nextVitals, globalIgnores([...])])`. Imports come from `eslint/config` (built-in helpers since 9.21.0) and `eslint-config-next/core-web-vitals`.
- `globalIgnores` covers `.next/**`, `node_modules/**`, `out/**`, `build/**`, `next-env.d.ts`, and `scripts/migrations/**` per gate-1 instruction.

**Out-of-scope (still deferred):**

- Fixing the ~100-error pre-existing lint baseline. Stays under `fix-lint-baseline`. CI's `npm run lint || true` wrapper continues to tolerate non-zero exit; the baseline number will shift with the v9 plugin upgrades but counting that drift is `fix-lint-baseline`'s job.
- Bumping ESLint to v10. Surfaced as Risk R14; revisit in a later `bump-eslint-10` convoy if desired.
- Bumping React 18 → 19. Stays under `bump-react`.
- App Router migration, test-runner adoption, auth fixes, schema migrations — all unchanged from the original convoy scope.

**Canonical authority.** `tcg-vault` does not maintain `docs/04-architecture/*.md` files, so this Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`. Boot-the-brief recheck performed against this decision before publishing the revised Brief 1.

**Consequences for downstream roles.**

- `role-implementer`: must run `npm install next@^16.2.6 eslint@^9.39.4 eslint-config-next@^16.2.6` (the three explicit version pins), then delete `.eslintrc.json`, write `eslint.config.mjs` per the verbatim shape in Brief 1, and update `package.json`'s `scripts.lint`. No mid-flight scope decisions.
- `role-reviewer`: includes the ESLint config change in correctness review. Verify `npm run lint` runs (regardless of error count); verify the lockfile diff is consistent with the three version pins.
- `role-design-system-auditor` and `role-a11y-auditor`: unchanged. The lint config doesn't affect render output.
- `role-doc-writer`: still updates `AGENTS.md` "Tech stack" string (Next.js 15 → 16) in a separate PR. May optionally also update the line that says "JavaScript (not TypeScript)" remains accurate; no change needed there.

> **Superseded by Decision B (2026-05-23, same day).** The implementer command above changed from `eslint@^9.39.4` to `eslint@^10.4.0`. See entry B below for details.

### B — 2026-05-23: Pivot ESLint pin from v9.x to v10.x

**Context.** Decision A (above, same day) expanded scope to include the ESLint v8 → v9 + flat-config migration, with `eslint` pinned to `^9.39.4`. During the architect's Boot-the-brief recheck of A, finding #5 surfaced that **ESLint v10.4.0 had been released to the `latest` dist-tag on 2026-02-06** — between when this convoy was authored (2026-05-22) and when gate 1 was reached (2026-05-23). v9.39.4 had moved to the `maintenance` tag. The architect surfaced this as Risk R14 with a "stay conservative on v9" recommendation. On gate-1 re-review, the user pivoted to v10 to avoid a back-to-back `bump-eslint-10` convoy.

**Decision.** Pin `devDependencies.eslint` to `^10.4.0` (current `latest`) instead of `^9.39.4`. All other pins from Decision A stand: `next@^16.2.6`, `eslint-config-next@^16.2.6`, `.eslintrc.json` deleted, `eslint.config.mjs` created with the same verbatim shape (no v10-specific signature change in `defineConfig` or `globalIgnores`).

**Boot-the-brief recheck against v10 (no blocker found):**

1. **Peer-dep compatibility.** `npm view eslint-config-next@16.2.6 peerDependencies` returns `{"eslint": ">=9.0.0", ...}` with **no `<10` upper bound**. v10 is accepted.
2. **Node engine compatibility.** `eslint@10.4.0` engines: `node ^20.19.0 || ^22.13.0 || >=24` (tighter floor than v9's `^18.18.0 || ^20.9.0 || >=21.1.0`). CI's `setup-node@v4` with `node-version: '20'` resolves to latest 20.x ≥ 20.19; local `node@22.14.0` is in `^22.13.0`; Vercel default Node 22 is ≥ 22.13. All ✓. Residual concern (CI's "latest 20.x" is a moving target) is documented as Risk R9; pinning CI to `node-version: '20.19'` would eliminate it but is out of scope per the convoy's "Hard do not touch" list.
3. **`eslint/config` exports retained.** Extracted `eslint@10.4.0` tarball, opened `lib/config-api.js`: still re-exports `defineConfig` and `globalIgnores` from `@eslint/config-helpers`. The brief's verbatim shape is unchanged.
4. **`eslint-env` comments are errors in v10.** `rg "eslint-env"` returned zero hits in `tcg-vault` source. ✓
5. **No App-Router-only or Cache-Components surfaces affected.** v10's `eslint:recommended` updates, JSX reference tracking, and `no-shadow-restricted-names.reportGlobalThis: true` will shift the lint baseline more than v9 would have, but that's `fix-lint-baseline`'s problem (Risk R12, expanded).

**The one new risk v10 surfaces (R15 in the convoy file's Risk list):** `eslint-config-next@16.2.6` was published before ESLint v10. Its bundled plugin set (`@next/eslint-plugin-next@16.2.6`, `eslint-plugin-react@^7.37.0`, `eslint-plugin-react-hooks@^7.0.0`, `eslint-plugin-import@^2.32.0`, `eslint-plugin-jsx-a11y@^6.10.0`, `typescript-eslint@^8.46.0`) was not statically vetted against v10. If any plugin uses a v9-deprecated API that v10 removed (`context.getCwd()`, `SourceCode#getJSDocComment()`, etc.), `npm run lint` will throw `TypeError`. **Acceptance criterion: `npm run lint` runs to completion.** If it crashes, the implementer escalates and we revert to v9 (one-line change). Cost of being wrong: small.

**Out-of-scope (still deferred):**

- All items deferred under Decision A remain deferred.
- CI workflow changes (e.g. pinning `node-version: '20.19'` for ESLint v10's stricter floor) — see Risk R9 residual concern. Pickup point: next CI-touching convoy (`adopt-vitest`).
- Any `bump-eslint-10` convoy is now **closed before opening** — its work is folded into this one.

**Canonical authority.** Same as Decision A — this Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`, immediately after Decision A's gate-1 review surfaced finding R14.

**Updated consequences for downstream roles** (delta from Decision A):

- `role-implementer`: command becomes `npm install next@^16.2.6 eslint@^10.4.0 eslint-config-next@^16.2.6`. The `eslint.config.mjs` shape is unchanged. New explicit acceptance check: `npm run lint` running to completion (escalate on `TypeError`, do not patch transitive deps).
- `role-reviewer`: lockfile diff will additionally show `@eslint/eslintrc` being removed from the dep tree (v10 dropped it). Lint baseline will shift more than under v9; `|| true` wrapper still tolerates.
- `role-design-system-auditor`, `role-a11y-auditor`, `role-doc-writer`: unchanged from Decision A.

### C — 2026-05-23: Add `typescript` as a devDep (narrow scope expansion in response to implementer escalation)

**Context.** After Decisions A and B were applied, `role-implementer` ran the migration locally and `npm run lint` immediately crashed with `Cannot find module 'typescript'` during config load — before any rule executed. The implementer escalated. Root-cause diagnosis: `eslint-config-next/core-web-vitals` → `typescript-eslint@^8.46.0` → `@typescript-eslint/typescript-estree@8.59.4` does an unconditional `require('typescript')` at module load (verified after the fact by extracting the published `typescript-estree` tarball — `dist/convert.js:40` and 8 other sites are top-level `require('typescript')` calls, none gated on `try/catch` or `require.resolve`). The `peerDependenciesMeta.typescript.optional: true` annotation in `eslint-config-next@16.2.6`'s `package.json` only suppresses npm's install-time peer-dep warning; it does NOT make `typescript` runtime-optional. **The architect's Boot-the-brief finding #8 misread this annotation** and stated "tcg-vault is JS-only, no `typescript` install needed." That assumption was wrong, and the implementer caught it on first run.

This is **NOT** a manifestation of Risk R15 (no `TypeError` on a deprecated v9 API; the crash happened before any rule loaded). Reverting to ESLint v9 would not have fixed it — the same `typescript-eslint` chain ships with `eslint-config-next@16` regardless of the ESLint major version.

**The decision.** User chose **option (a) — add `typescript` as a devDep** at the gate. One-line scope expansion, ~minimal-risk:

- `package.json` adds `devDependencies.typescript: "^5.9.3"`.
- `package-lock.json` regenerates accordingly. The new `typescript` subtree is small (TypeScript itself has no `dependencies` and no `peerDependencies`).
- Pin choice: `^5.9.3`. **Note:** `npm view typescript@latest version` returns `6.0.3` (TypeScript 6 is the current `latest` major, contrary to the gate's parenthetical claim that 5 was latest). Latest 5.x is `5.9.3`. Two reasons to pin `^5.9.3` and defer v6: (1) honor the literal gate-1 instruction (`^5`); (2) `typescript-eslint@8.59.4`'s peer range is `>=4.8.4 <6.1.0` — strictly, `typescript@6.0.3` is in range, but `typescript-eslint@8.x` was published before TS 6 GA and has not advertised explicit v6 support, so staying inside the well-trodden 5.x range is safer until a future convoy bumps `typescript-eslint`. `^5.9.3` resolves to the latest 5.x patch.
- Pin range scope: full SemVer caret (`^5.9.3`), matching the convention used by `next` (`^15.4.2` → `^16.2.6`) and `react` (`^18.3.1`) elsewhere in `package.json`.
- No new files. No `tsconfig.json`. No `.js` → `.ts` migration. The brief's `files:` set is unchanged (`package.json` and `package-lock.json` were already in scope as modifications). The `slice_dependencies` graph is unchanged.
- No `eslint.config.mjs` change. The flat-config shape is independent of whether `typescript` is installed.

**Why option b (replace `eslint-config-next` with a JS-only ESLint preset) was dismissed.** `eslint-config-next@16` does not ship a JS-only entry point. Its `core-web-vitals` export bundles `typescript-eslint` as a regular dependency (not a peer), so consumers cannot opt out without forking the package or reimplementing the rule set. Maintaining a fork is a much larger scope expansion than adding `typescript` as a devDep, and gives up the upstream guarantee that the rule set tracks Next.js best practices.

**Why option c (keep things broken; CI's `|| true` wrapper tolerates lint failures) was dismissed.** CI's `|| true` wrapper tolerates a non-zero exit code from `eslint`, but it does NOT tolerate a `MODULE_NOT_FOUND` thrown during config load — the crash happens before ESLint emits any structured output, and the wrapper still passes the exit code to the shell, but **lint stops being a useful signal entirely**. Every CI lint run would be a no-op pass. That regresses the lint surface to "always green, regardless of code quality" and silently invalidates the `fix-lint-baseline` convoy's premise (which assumes lint at least executes). Unacceptable.

**Out-of-scope (still deferred):**

- All items deferred under Decisions A and B remain deferred.
- TypeScript adoption as a project language (no `tsconfig.json`, no `.ts`/`.tsx` source files, no `// @ts-check` directives, no `.d.ts` declaration files). `typescript` is installed purely so `eslint-config-next`'s lint chain can load. If the team later decides to migrate to TypeScript, that's an explicit, separate convoy — not a "while we're here."
- Adding `@typescript-eslint/parser` or `@typescript-eslint/eslint-plugin` directly. They're already pulled in transitively by `eslint-config-next@16`; no direct dep needed.
- CI workflow changes (still per Decision B's deferral note — pickup point is `adopt-vitest`).

**Canonical authority.** This Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`, immediately after the implementer's escalation on first lint run. Boot-the-brief #8's misreading of `peerDependenciesMeta.optional` is corrected in place in `brief-1-bump-next-and-migrate-config.md` (finding #8 marked "🔴 SUPERSEDED by Decision C"; new findings #16–#18 added under "Decision C narrow recheck").

**Updated consequences for downstream roles** (delta from Decision B):

- `role-implementer`: command becomes `npm install next@^16.2.6 eslint@^10.4.0 eslint-config-next@^16.2.6 typescript@^5.9.3` (or equivalently, run the previous three-package install, then run `npm install --save-dev typescript@^5.9.3` as a follow-up — order doesn't matter; the lockfile is regenerated either way). Re-run `npm run lint` after the install; expectation is now that lint completes with the pre-existing baseline of errors (no `Cannot find module 'typescript'` crash). Failure-mode classification: see Brief 1's "Local verification" section — `Cannot find module 'typescript'` post-install means the install didn't take and is not R15; a `TypeError: context.getCwd is not a function` (or similar v9-deprecated-API error) is R15 and triggers a v9 fallback (keeping the `typescript` install).
- `role-reviewer`: lockfile diff will now additionally show the `typescript` package being added. The diff is small (TypeScript has no transitive deps). Verify the brief's no-scope-expansion guardrails were respected — specifically that no `tsconfig.json` was created and no `.js` files were renamed to `.ts`/`.tsx`.
- `role-design-system-auditor`, `role-a11y-auditor`, `role-doc-writer`: unchanged from Decisions A and B.

### D — 2026-05-23: Revert ESLint v10 → v9.39.4 after R15 fired empirically; queue `bump-eslint-10` as upstream-blocked follow-up

**Context.** After Decisions A, B, and C were applied, `role-implementer` ran the migration locally a second time (pass 2). The Decision-C `typescript` install resolved the original `Cannot find module 'typescript'` crash from pass 1 — but the lint run then surfaced a different `TypeError`:

- **Crash signature:** `TypeError: scopeManager.addGlobals is not a function`
- **Call site:** ESLint v10's `lib/source-code/source-code.js:221` calls `scopeManager.addGlobals(...)` as part of v10's redesigned global-ingestion path.
- **Missing-method site:** `@typescript-eslint/scope-manager@8.59.4` (transitive dep of `typescript-eslint@8.59.4`, which `eslint-config-next@16.2.6` bundles as a regular `dependency`) does not implement `addGlobals` on its `ScopeManager` class.
- **Why:** `@typescript-eslint/scope-manager@8.x` was published Oct/Nov 2025; ESLint v10 GA was 2026-02-06. The `addGlobals` method is a v10-introduced extension of the `ScopeManager` interface; v9 used a different ingestion path. `typescript-eslint` has not yet shipped a v10-tested release that adds the method.

This is **the empirical firing of Risk R15**, in a different shape than originally feared. The principal failure mode anticipated at Decision B was a v9-deprecated-API removal (`context.getCwd()`, `SourceCode#getJSDocComment()`, etc.); the actual failure was a v10-introduced-method gap on the typescript-eslint side. Either way, the diagnosis is the same: `eslint-config-next@16.2.6`'s pre-v10-GA bundled plugin set is not runtime-compatible with v10. Reverting `eslint` to v9 is the only working option until upstream catches up.

**The decision.** User chose **option (a) — execute the brief's documented v9 fallback path AND formally queue a follow-up `bump-eslint-10` convoy** at the gate. This partially reverses Decision B's "avoid back-to-back convoys" rationale, but **Decision B was correct given Boot-the-brief evidence at the time** — the v10 incompat was statically unprovable until a real lint run hit `addGlobals`. Empirical evidence from pass 2 reverses the call.

Specific changes:

- `package.json`: re-pin `devDependencies.eslint` from `"^10.4.0"` back to `"^9.39.4"` (npm's `maintenance` dist-tag).
- **`devDependencies.typescript: "^5.9.3"` (Decision C) is RETAINED.** Boot-the-brief recheck #17 confirmed at Decision C, and the implementer's pass-2 evidence reconfirmed, that the same `typescript-eslint@8.59.4` chain hard-`require`s `typescript` under v9 too. The typescript install is correct independent of the eslint pin.
- **`eslint-config-next@^16.2.6` is unchanged** — its peer-dep `eslint: ">=9.0.0"` accepts v9.39.4 trivially; no `<10` upper bound shift since Decision B's verification.
- **`next@^16.2.6` is unchanged.**
- **`eslint.config.mjs` shape is unchanged.** `defineConfig` and `globalIgnores` from `eslint/config` were introduced in 9.21.0 and retained in v10.4.0; the same import line resolves correctly on both v9.39.4 and v10.4.0. **This is the load-bearing reason Decision D is a one-line `package.json` re-pin and not a multi-file rollback.** When `bump-eslint-10` lands, this file should not need to change.
- Install command for the implementer: `npm install --save-dev eslint@^9.39.4 eslint-config-next@^16.2.6 typescript@^5.9.3` (single atomic command preferred; running them separately is equivalent — the lockfile regenerates either way).

**Why option b (npm overrides to force a v10-compat `@typescript-eslint/scope-manager`) was dismissed.** The brief explicitly forbids transitive patching ("do NOT patch the plugin or pin transitive deps mid-flight"). There's no guarantee that any released version of `@typescript-eslint/scope-manager` exists with the v10 fix at a version `eslint-config-next@16.2.6` will resolve to under its bundled `typescript-eslint@^8.46.0` constraint. Even if such a version existed, npm overrides bypass the upstream maintainer's compatibility testing entirely — we'd be hand-rolling a custom dep tree that no other project uses, which moves the maintenance burden to us.

**Why option c (wait for upstream) was dismissed.** Doesn't unblock the Vercel deploys gate that's the convoy's success metric ("npm install next@16.2.6 ships, Vercel deploys complete, no runtime regressions in dev or build"). The convoy's premise is that Vercel was rejecting `next@^15.4.2` as a "Vulnerable version of Next.js"; we have to ship `next@^16.2.6` now. Pinning `eslint` to v9 lets us do that today; v10 can land later when prerequisites are met.

**Why option d (ship with the lint crash) was dismissed.** Same reasoning as Decision C's option-c dismissal: CI's `|| true` wrapper tolerates a non-zero exit code, but a `TypeError` crash before any rule executes means lint emits no useful signal at all — every CI lint run becomes a no-op pass, and `fix-lint-baseline`'s premise (lint at least executes) collapses. Unacceptable.

**Reversal of Decision B's "avoid back-to-back `bump-eslint-10` convoy" rationale.** Acknowledged. Decision B's argument was: pivot to v10 now to avoid a follow-up convoy. That argument was correct given the static evidence available at the time of Decision B (peer-dep ranges accepted v10; Boot-the-brief found no obvious incompatibilities). Decision D's empirical evidence — a `TypeError` from a real lint run — supersedes the static evidence. The follow-up `bump-eslint-10` convoy is now formally queued (see "Follow-up convoys queued" section below); it will land as a single-brief mechanical bump once upstream prerequisites are met.

**Out-of-scope (still deferred):**

- All items deferred under Decisions A, B, and C remain deferred.
- The `bump-eslint-10` follow-up is queued, not authored. The conductor will materialize a convoy file when a human authors one (likely after `typescript-eslint` ships a v10-tested release and `eslint-config-next` bundles it).
- npm `overrides` field manipulation, transitive-dep pinning, plugin forking — all forbidden as scope expansion under both this convoy and the future `bump-eslint-10`.

**Canonical authority.** This Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`, immediately after the pass-2 implementer escalation surfaced R15's `addGlobals` firing.

**Updated consequences for downstream roles** (delta from Decision C):

- `role-implementer`: re-run `npm install --save-dev eslint@^9.39.4` (the other three packages — `next@^16.2.6`, `eslint-config-next@^16.2.6`, `typescript@^5.9.3` — are already at correct versions from Decision C's run); re-run `npm run lint`. **Expectation:** exit code 1 or 2 (baseline lint errors present) is fine; exit code 0 is improbable until `fix-lint-baseline`. **NOT expected:** a `TypeError` crash. R15's `scopeManager.addGlobals` signature should not recur on v9 because v9 doesn't call `addGlobals`. If a different `TypeError` fires on v9, escalate via the brief's failure-mode classifier.
- `role-reviewer`: lockfile diff under Decision D stays on the v9 dep-tree; `@eslint/eslintrc` (a v9 transitive) remains present. Verify that `package.json` has `eslint: "^9.39.4"` (not `^10.x`), `typescript: "^5.9.3"`, `eslint-config-next: "^16.2.6"`, and `next: "^16.2.6"`.
- `role-design-system-auditor`, `role-a11y-auditor`, `role-doc-writer`: unchanged from Decisions A, B, C. Doc-writer's `AGENTS.md` pass should mention the `bump-eslint-10` queued convoy if the doc-writer pass surfaces lint-toolchain documentation.
- **Future `bump-eslint-10` implementer:** inherits R15's diagnostic verbatim. The convoy will become a single-brief mechanical bump once `typescript-eslint` ships v10 support and `eslint-config-next` bundles it; until then, the convoy is upstream-blocked and not authored.

## Follow-up convoys queued

The following convoys are formally queued by `role-architect` as upstream-blocked follow-ups to this convoy. They are NOT authored as convoy files yet — they exist in this list only. The conductor will materialize a convoy file when a human authors one and the upstream prerequisites are met.

### `bump-eslint-10` — upstream-blocked

- **Origin.** Queued under Decision D (2026-05-23) after R15 fired empirically. Decision B's pivot to v10 was reverted; v10 is still the supported `latest` and we want to land it eventually.
- **Prerequisites (both must be met before the convoy can run):**
  1. `typescript-eslint` ships a v10-tested release. Likely shape: `@typescript-eslint/scope-manager` adds the `addGlobals` method (and any other v10-introduced `ScopeManager` interface members) on the v8.x line as a backport, OR the typescript-eslint v9 line ships and adds them. Either way, the release notes will explicitly mention ESLint v10 compatibility.
  2. `eslint-config-next` bundles a v10-tested `typescript-eslint`. Likely shape: a `16.3+` release that bumps the `typescript-eslint` direct dependency. Confirmed by reading the `eslint-config-next` `package.json` `dependencies.typescript-eslint` range and cross-referencing typescript-eslint's release notes.
- **Convoy shape (when materialized):** single-brief mechanical bump matching this convoy's Brief 1 shape. Files: `package.json` (re-pin `eslint` from `^9.39.4` to `^10.x.y`; re-pin `eslint-config-next` if a new minor bundles the v10-tested typescript-eslint), `package-lock.json` (regenerate). No code-shape changes expected — `eslint.config.mjs` is verified compatible on both v9 and v10. No CI workflow changes unless the Node-version pin question (originally raised under R9) bites at v10's stricter floor.
- **Risks inherited from this convoy:** R12's "lint baseline shifts more under v10" warning resurfaces; the three new `eslint:recommended` rules, JSX reference tracking, `no-shadow-restricted-names.reportGlobalThis: true` default, and `eslint-env`-comments-as-errors transition all happen at this convoy. CI's `|| true` wrapper still tolerates. R9's CI moving-target concern (`node-version: '20'` resolution) reactivates under v10's `^20.19.0` floor; the `bump-eslint-10` brief should pin CI to `node-version: '20.19'` or `'lts/iron'` if the target convoy permits CI workflow changes.
- **Cost of being wrong about prerequisites:** small. If `typescript-eslint` ships a v10-tested release and `eslint-config-next` bundles it but `bump-eslint-10` still surfaces a different incompat at runtime, the convoy itself documents another decision letter and re-pins back to v9 again. The cost is one extra Boot-the-brief recheck and one extra Decisions entry.

### `bump-typescript-6` — upstream-blocked

- **Origin.** Queued under Decision D (2026-05-23). Surfaced during Decision C's Boot-the-brief recheck (#16): `npm view typescript@latest` returned `6.0.3` (latest major), but `^5.9.3` was pinned because `typescript-eslint@8.59.4`'s peer range `>=4.8.4 <6.1.0` accepts but doesn't certify v6.
- **Prerequisites:**
  1. `typescript-eslint` advertises explicit v6 support in a release. Currently the peer range accepts `<6.1.0` (so `typescript@6.0.x` is technically in range) but typescript-eslint has not announced v6 testing. Likely shape: a release-notes entry titled "TypeScript 6 support" or a peer-range bump to `<7.0.0` once they're confident.
  2. (Optional) `eslint-config-next` bundles a `typescript-eslint` version that advertises v6 support. Not strictly required — `typescript@^5.x` in `bump-eslint-10` and `typescript@^6.x` here can be re-pins on different days.
- **Convoy shape (when materialized):** single-brief mechanical bump. Files: `package.json` (re-pin `typescript` from `^5.9.3` to `^6.x.y`), `package-lock.json` (regenerate). No code-shape changes — TypeScript is only used by ESLint's lint chain, not by source files (no `tsconfig.json`, no `.ts` files; the `bump-typescript-6` convoy must preserve those guardrails).
- **Risks inherited from this convoy:** none specific. The verified runtime require evidence in Brief 1 #17 stays valid (typescript-estree's `require('typescript')` sites are unconditional regardless of TS major).
- **Cost of being wrong about prerequisites:** small. Same fallback shape as `bump-eslint-10`.

### Notes on materialization

These two convoys can land independently, in either order. Neither blocks the other. The conductor should expect a human to author the convoy file (frontmatter + IA + UX) when they decide to land the upgrade; `role-architect` does not pre-author convoy files for upstream-blocked follow-ups (no Boot-the-brief evidence exists yet to verify against).

