Upgrade docs disagree on breaker count: blog skeleton says 7, canonical guide says 11

[bpamiri]

Describe the issue

The blog skeleton at docs/releases/blog-skeletons/02-upgrading-from-3x.md opens with "Wheels 4.0 lands with seven breaking changes..." and lists 7 items.

The canonical upgrade guide at web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx opens with "The eleven breaking changes" and lists 11.

The stats table in docs/releases/wheels-3.0-vs-4.0.md says Breaking defaults hardened | 7 — agreeing with neither.

The lists don't overlap cleanly:

• In the blog only:
  • cfwheels → wheels namespace rename in active code (chore: rebrand CFWheels → Wheels in active code and metadata #2064)
  • testbox → wheelstest namespace rename (which is not what refactor: rename testbox namespace to wheelstest (WheelsTest) #1889 actually renames — refactor: rename testbox namespace to wheelstest (WheelsTest) #1889 renames wheels.Test → wheels.WheelsTest, the test base class, not the testbox namespace)
• In the canonical guide only:
  • HSTS default-on (fix(middleware): default HSTS header in production #2081)
  • CSRF key + JWT alg validation (fix(controller): enforce csrf key in production and validate jwt algorithm claim #2079, fix(config): use constant-time comparison for JWT signature verification #2086)
  • RateLimiter trustProxy/strategy (fix: change RateLimiter trustProxy default to false #2024, fix(middleware): default rate limiter proxy strategy to last for security #2088)
  • CSRF cookie SameSite (fix(security): add SameSite attribute to CSRF cookie #2035)
  • application.wirebox → application.wheelsdi (refactor: rename application.wirebox to application.wheelsdi #1888)
  • Vite manifest strictness (feat(view): transitive modulepreload and css resolution for vite pipeline #2133)

Why this matters

A team encountering both documents before upgrading will be confused about scope. The blog's "testbox → wheelstest namespace" framing is also misleading — the actual change is to the test base class, not to the testbox package namespace, so anyone search-replacing extends="testbox.system.BaseSpec" to extends="wheelstest.system.BaseSpec" will not get the right result. The right replacement is extends="wheels.WheelsTest".

Suggested fix

Pick one of:

1. Update the blog skeleton to match the canonical guide's 11 items. Choose the most narratively interesting four or five to highlight; reference the canonical guide for the full list.
2. If the blog is intentionally a narrative subset, change the opener. "the eleven breaking changes" → drop the count, e.g., "Wheels 4.0 lands with a handful of breaking changes..." and link to the canonical list. Don't promise a specific count if the blog isn't going to enumerate them all.
3. Either way, fix the testbox → wheelstest framing in blog item 3 — the breaker is wheels.Test → wheels.WheelsTest, not a namespace move on the package itself.
4. Reconcile the stats table in wheels-3.0-vs-4.0.md — Breaking defaults hardened | 7 doesn't match either document and should be checked against the source PRs.

🤖 Filed by Claude Code while assisting with a 4.0 upgrade testbed

[wheels-bot]

Wheels Bot — Triage

Classified as docs-request.

Docs scope

Three release/upgrade docs disagree about how many breaking changes shipped in 4.0 and one of them mis-describes a rename. The work is to reconcile them as a single set of consistent edits:

• web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx — canonical guide, says "eleven breaking changes," enumerates 11. This is the source of truth and should stay authoritative.
• docs/releases/blog-skeletons/02-upgrading-from-3x.md — opens with "seven breaking changes," enumerates 7, and frames item 3 as testbox → wheelstest (a package-namespace move), which is incorrect — the actual breaker is wheels.Test → wheels.WheelsTest (test base class, per refactor: rename testbox namespace to wheelstest (WheelsTest) #1889). Either expand the blog to mirror the canonical 11, or drop the specific count and link out; fix the testbox framing either way.
• docs/releases/wheels-3.0-vs-4.0.md — stats table row Breaking defaults hardened | 7 agrees with neither doc; verify against the source PRs (fix: change RateLimiter trustProxy default to false #2024, fix(security): add SameSite attribute to CSRF cookie #2035, chore: rebrand CFWheels → Wheels in active code and metadata #2064, fix(controller): enforce csrf key in production and validate jwt algorithm claim #2079, fix(middleware): default HSTS header in production #2081, fix(config): use constant-time comparison for JWT signature verification #2086, fix(middleware): default rate limiter proxy strategy to last for security #2088, feat(view): transitive modulepreload and css resolution for vite pipeline #2133, refactor: rename application.wirebox to application.wheelsdi #1888, refactor: rename testbox namespace to wheelstest (WheelsTest) #1889, and the eleventh) and update the count.

Confidence: high

The deliverable is concrete (three named files, specific corrections), the right paths are unambiguous, and the work is reconciliation against an existing source of truth rather than a structural docs-architecture decision.

<!-- wheels-bot:triage:2632 -->
<!-- wheels-bot:triage-class:docs-request -->
<!-- wheels-bot:docs-confidence:high -->

[wheels-bot]

Wheels Bot — Docs proposed

Draft PR: #2644

Pages updated:

• docs/releases/blog-skeletons/02-upgrading-from-3x.md — restructured from 7 to 11 breaking changes, matching the canonical upgrade guide; fixed the wheels.Test → wheels.WheelsTest entry (previously mislabeled as a "testbox namespace" move); added application.wirebox → application.wheelsdi and Vite manifest strictness which were missing; removed the incorrect "not on the canonical list" framing for the security-default items
• docs/releases/wheels-3.0-vs-4.0.md — "At a glance" count corrected from 7 to 11; four detail-row delta labels updated from Changed/Renamed/New → Breaking

Screenshots needed: none

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly.