docs(web/guides): document allowCorsRequests global setting still works in 4.0

[wheels-bot]

Summary

The 3.x → 4.0 upgrade guide only described the wheels.middleware.Cors path for CORS configuration, leaving apps that use the global set(allowCorsRequests=true) setting with no guidance. This PR adds a new sub-section directly under the CORS breaking change (section 1) in both the v4-0-0 and v4-0-1-snapshot upgrade guides clarifying:

• The global set(allowCorsRequests=true) and the full accessControlAllow* settings family are still honored in 4.0 — no migration required.
• A comparison table showing how the two paths differ (where they run in the request lifecycle, OPTIONS preflight handling, per-route scoping, Access-Control-Max-Age).
• The precedence when both are active simultaneously: the global setting wins OPTIONS (because it fires abort in onRequestStart before the middleware pipeline runs); the middleware wins all other requests (because cfheader calls in the middleware overwrite what the global setting emitted).
• A recommendation: leave existing global-setting config unchanged; prefer the middleware for new CORS configuration.

Fixes #2633

Files changed

• web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx — new #### CORS — two paths in 4.0 sub-section after the existing breaking change content
• web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx — same sub-section (snapshot copy)
• CHANGELOG.md — one-line [Unreleased] documentation entry

Screenshots needed

None — this is a prose + table + code-only doc section.

[wheels-bot]

Wheels Bot — Reviewer A

This is a pure documentation PR that adds a well-researched "CORS — two paths in 4.0" sub-section to both the v4-0-0 and v4-0-1-snapshot upgrade guides, clarifying that set(allowCorsRequests=true) still works in 4.0, documenting the lifecycle difference between the global setting and wheels.middleware.Cors, and explaining precedence when both are active. The prose accurately reflects the implementation (verified against vendor/wheels/events/EventMethods.cfc, vendor/wheels/events/init/security.cfm, vendor/wheels/Global.cfc, and vendor/wheels/middleware/Cors.cfc). However, the commit header exceeds the 100-character commitlint limit enforced in commitlint.config.js, which is a required gate. One minor doc precision issue is also noted.

Correctness

The implementation claims were verified against the codebase:

• Global setting fires in onRequestStart, calls abort on OPTIONS (EventMethods.cfc lines 239–262) — documented correctly.
• Middleware runs during dispatch (Dispatch.cfc lines 314–324, called from index.cfm after onRequestStart) — documented correctly.
• Middleware wins on non-OPTIONS requests because cfheader in Cors.cfc (lines 72–79) overwrites what $setCORSHeaders emitted earlier — documented correctly.
• Access-Control-Max-Age absent from global setting path — confirmed: neither $setCORSHeaders in Global.cfc nor security.cfm initializes a maxAge setting. Table row is accurate.
• Available since Wheels 2.x — confirmed by CHANGELOG line 810 (2.0.0-rc.1 entry).

Minor precision issue (web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx, line 78):

All six `accessControlAllow*` settings are initialized in the 4.0 security defaults

security.cfm initializes exactly 5 accessControlAllow*-prefixed settings (accessControlAllowOrigin, accessControlAllowMethods, accessControlAllowMethodsByRoute, accessControlAllowCredentials, accessControlAllowHeaders) plus allowCorsRequests — which does not share the accessControlAllow* prefix. A reader scanning the code will count 5, not 6, entries with that prefix. Suggested fix:

All six CORS settings (`allowCorsRequests` and the five `accessControlAllow*` settings) are initialized in the 4.0 security defaults and read on every request.

The same line appears identically in the v4-0-1-snapshot copy and needs the same correction.

Commits

commitlint violation — header exceeds 100-character limit:

docs(web/guides): document allowCorsRequests global setting still works in 4.0 and clarify precedence vs middleware

This header is 115 characters. commitlint.config.js line 27 sets 'header-max-length': [2, 'always', 100]. This is a hard-error rule (severity 2). Suggested shorter header (97 chars):

docs(web/guides): clarify allowCorsRequests still works in 4.0 and middleware precedence

Tests

No code changes — docs-only PR. No test additions are required or expected.

Security

No security concerns. The PR accurately documents (rather than changes) CORS behavior. The precedence section correctly warns against running both paths simultaneously without intent.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is substantively accurate. Both findings are real, the code-verification work is solid, and the precision issue in the docs is confirmed against security.cfm. One minor arithmetic error in A's own suggestion doesn't affect the advice. The only structural gap is a verdict/finding mismatch: A flagged a commitlint severity-2 (hard-error) violation but submitted as COMMENTED rather than REQUEST_CHANGES, which understates the impact. Aligning on changes needed.

Sycophancy

None detected. A's positive framing ("well-researched", "accurately reflects the implementation") is each time backed by a specific file + line citation. That is evidence, not filler.

False positives

• A's suggested header character count is wrong. A described the replacement header as "97 chars" but it is actually 88 chars. The shorter header is still valid and fits comfortably under 100, so the advice stands — A just overstated the length. No impact on the recommendation.

Otherwise none. A's precision finding about "All six accessControlAllow* settings" is correct: vendor/wheels/events/init/security.cfm lines 17–22 show exactly 5 settings with the accessControlAllow* prefix, plus allowCorsRequests (no shared prefix). Calling all six by the glob prefix is imprecise, and A's suggested reword fixes it accurately.

The commitlint violation is also real: the commit header is 115 characters against a header-max-length: [2, 'always', 100] rule in commitlint.config.js.

Missed issues

None detected. A covers correctness (verified against four source files), commits, tests, and security. The docs-only scope makes this a complete checklist. The v4-0-1-snapshot copy needing the same prose fix was noted.

Verdict alignment

A used COMMENTED for a commitlint severity-2 (hard-error) rule violation. REQUEST_CHANGES would better match the finding: a hard-gate CI failure requires a commit rewrite, not just a follow-up note. The finding is accurate; the verdict understates it.

Convergence

Aligned on changes needed. Two concrete fixes are required:

1. In both web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx and web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx: replace "All six accessControlAllow* settings" with "All six CORS settings (allowCorsRequests and the five accessControlAllow* settings)".

2. Shorten the commit header from 115 characters to within 100. A's suggested replacement (88 chars) is suitable: docs(web/guides): clarify allowCorsRequests still works in 4.0 and middleware precedence.

Note: fix (2) requires amending the commit and force-pushing the branch; address-review can handle the doc text in (1), but the commit message rewrite may need a separate step or human intervention.

[wheels-bot]

Wheels Bot — Address Review (round 1)

Applied consensus findings from Reviewer A and Reviewer B's convergence (round 1):

• Doc precision fix (both finding 1 in A and confirmed by B): Replaced "All six accessControlAllow* settings" with "All six CORS settings (allowCorsRequests and the five accessControlAllow* settings)" in:

  • web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx:78
  • web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx:78

  Verified against vendor/wheels/events/init/security.cfm lines 17–22: five accessControlAllow*-prefixed settings plus allowCorsRequests (six CORS-related settings total, only five share the prefix).

Skipped: commitlint header-length violation on commit 8999271. Reviewer A and B both flagged this as real (115 chars vs 100-char cap). Reviewer B explicitly noted "fix (2) requires amending the commit and force-pushing the branch; address-review can handle the doc text in (1), but the commit message rewrite may need a separate step or human intervention." The shared rails forbid git push --force, git reset --hard, or any subcommand that rewrites history (.claude/commands/_shared-rails.md §"Tool restrictions"). Leaving this for a human to resolve via interactive rebase + force-push, or via merging with a squash-on-merge that lets the maintainer rewrite the squashed header.

No test run required — docs/bot-* scope, only .mdx files touched.

The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on approve or the outer-loop cap (5 rounds) is reached.

[wheels-bot]

Wheels Bot — Reviewer A

The round-1 address commit (f7f0acaf9) correctly applies the prose precision fix flagged by both Reviewer A and Reviewer B to both the v4-0-0 and v4-0-1-snapshot upgrade guides. That finding is resolved. However, the commitlint violation on the original commit (8999271fa) — a 115-character header against a hard-error 100-character limit — remains unresolved. One of two requested changes is done; one is not. Verdict: changes needed.

Correctness

The fix at line 78 of both guide files is accurate and matches vendor/wheels/events/init/security.cfm lines 17–22:

All six CORS settings (`allowCorsRequests` and the five `accessControlAllow*` settings) are initialized in the 4.0 security defaults and read on every request.

That is the correct count: 5 settings share the accessControlAllow* prefix (accessControlAllowOrigin, accessControlAllowMethods, accessControlAllowMethodsByRoute, accessControlAllowCredentials, accessControlAllowHeaders) plus allowCorsRequests (no shared prefix). The wording is now precise in both copies. This finding is closed.

Commits

Outstanding: commitlint violation on the original commit.

Commit 8999271fa still has a 115-character header:

docs(web/guides): document allowCorsRequests global setting still works in 4.0 and clarify precedence vs middleware

commitlint.config.js line 27 enforces 'header-max-length': [2, 'always', 100] — severity 2 is a hard error that fails CI. The round-1 address commit did not amend or squash this. The new commit f7f0acaf9 (docs(web/guides): address Reviewer A/B consensus findings (round 1), 67 chars) is fine on its own.

Required action: squash or rebase-amend 8999271fa to a header within 100 characters. The header proposed by Reviewer B (88 chars) is suitable:

docs(web/guides): clarify allowCorsRequests still works in 4.0 and middleware precedence

Squashing both commits into one with the corrected header would also produce cleaner history for a docs-only change.

Tests

No code changes — docs-only PR. No test additions required or expected.

Security

No concerns. The PR documents existing behavior; no code changes.

[wheels-bot]

Wheels Bot — Reviewer B (round 2)

A's round-2 review is accurate. The prose fix is confirmed closed; the commitlint violation on the original commit remains the only outstanding item. The same verdict/state mismatch from round 1 recurs: a hard-error CI failure was submitted as COMMENTED rather than REQUEST_CHANGES. Findings align; convergence is on changes needed.

Sycophancy

None detected. A's positive closure on the prose finding is accompanied by an explicit inline code block showing the exact corrected text from both guide files, and is cross-referenced to the source at vendor/wheels/events/init/security.cfm lines 17-22. That is evidence, not filler.

False positives

None. All of A's claims check out:

• Commit 8999271fa header is 115 characters, confirmed (15 over the 100-char cap).
• New commit f7f0acaf9 header is 67 characters, confirmed, cleanly within limits.
• A's proposed replacement header is 88 characters, confirmed.
• commitlint.config.js line 27 rule header-max-length: [2, 'always', 100] is severity 2, a hard error.

Missed issues

None. This is a docs-only change. No cross-engine concerns, no test gaps, and no security issues. A correctly scoped the review to the one remaining blocking item.

One marginal observation A could have noted but is not a blocker: the PR title (docs(web/guides): document allowCorsRequests global setting still works in 4.0, 78 chars) is fine and does not need to match the proposed squash header. Not flagging its absence as a missed issue.

Verdict alignment

For the second consecutive round A submitted a COMMENTED verdict for a severity-2 (hard-error) commitlint violation. REQUEST_CHANGES is the appropriate verdict when a finding would produce a known CI failure. The finding itself is correct; the state choice understates the urgency.

Convergence

Aligned on changes needed. The single remaining action is for a human maintainer to squash or rebase-amend 8999271fa so the commit history contains no header exceeding 100 characters. A's suggested 88-character replacement header is suitable. The docs content is correct as of the current head.

[wheels-bot]

Wheels Bot — Address Review (round 2)

No commits applied. Reviewer A and Reviewer B converged on a single
remaining finding:

• Commit header length on 8999271fa (115 chars vs. 100-char cap
  in commitlint.config.js) — skipped. Rewriting an already-pushed
  non-HEAD commit's header requires git commit --amend /
  interactive rebase plus git push --force, both forbidden by
  .claude/commands/_shared-rails.md § "Tool restrictions" ("Never
  git push, ... git --force, or any subcommand that rewrites
  history"). Reviewer B explicitly noted in round 2 that this is
  "for a human maintainer to squash or rebase-amend." Round 1 made
  the same call.

Resolution paths for a human maintainer:

1. Squash-merge the PR — the maintainer-set squash subject (or
   the current 78-char PR title) becomes the only commit on
   develop, and the 115-char header disappears with 8999271fa.
2. Rebase-amend locally: git rebase -i develop, mark
   8999271fa as reword, replace the header with the 88-char
   variant Reviewer A suggested
   (docs(web/guides): clarify allowCorsRequests still works in 4.0 and middleware precedence),
   then git push --force-with-lease.

Doc content is correct as of f7f0acaf9 (round 1 prose fix
confirmed by Reviewer B). No further bot action is possible on this
SHA without violating the shared rails — handing back to humans for
the commit-history fix.

[wheels-bot]

Wheels Bot — Reviewer A

This docs-only PR adds a "CORS — two paths in 4.0" sub-section to both the v4-0-0 and v4-0-1-snapshot upgrade guides, clarifying that the global set(allowCorsRequests=true) path is still honored in 4.0, documenting the lifecycle difference between the two CORS paths, and explaining precedence when both run simultaneously. Both outstanding findings from prior review rounds are now resolved — the diff is clean and ready to merge.

Correctness

Both prior correctness findings are resolved:

1. Precision fix applied (both copies). Line 78 in v4-0-0/upgrading/3x-to-4x.mdx and its snapshot mirror now reads:

   All six CORS settings (allowCorsRequests and the five accessControlAllow* settings) are initialized in the 4.0 security defaults…

   This accurately counts the 5 accessControlAllow*-prefixed settings (accessControlAllowOrigin, accessControlAllowMethods, accessControlAllowMethodsByRoute, accessControlAllowCredentials, accessControlAllowHeaders) plus allowCorsRequests, matching vendor/wheels/events/init/security.cfm lines 17–22. Closed.

2. The implementation claims in the comparison table and precedence section (verified against EventMethods.cfc, security.cfm, Cors.cfc in prior rounds) remain accurate.

Commits

Both commits conform to commitlint.config.js and carry valid DCO sign-offs:

• f9ccbc3c0 — docs(web/guides): clarify allowCorsRequests still works in 4.0 and middleware precedence — 88 chars, Signed-off-by: claude[bot] present. The prior 115-char violation is resolved.
• 6409c0027 — docs(web/guides): address Reviewer A/B consensus findings (round 1) — 67 chars, Signed-off-by: claude[bot] present.

Tests

Docs-only PR — no test additions required or expected.

Security

No concerns. The PR documents existing framework behavior; no code is changed.

[wheels-bot]

Wheels Bot — Reviewer B (round 3)

A's round-3 review is accurate and complete. All prior findings are resolved. The branch now contains exactly two commitlint-compliant, DCO-signed commits, CI's "Validate Commit Messages" check passed on the current head, and the docs content is correct. The only observation worth noting is a recurring pattern: A submitted COMMENTED rather than APPROVED for a PR with no outstanding findings, which understates readiness. Converging on approve.

Sycophancy

None detected. A's positive closure on both prior findings is backed by explicit evidence:

• Prose fix: A quoted the exact corrected line from both files and cross-referenced it to vendor/wheels/events/init/security.cfm lines 17–22.
• Commit compliance: A cited the exact character counts (88 and 67) and confirmed Signed-off-by trailers are present for both commits.

False positives

None. All of A's claims are accurate:

• f9ccbc3c0 header is docs(web/guides): clarify allowCorsRequests still works in 4.0 and middleware precedence — 88 chars, within the 100-char cap. Confirmed.
• 6409c0027 header is docs(web/guides): address Reviewer A/B consensus findings (round 1) — 67 chars. Confirmed.
• The PR now contains exactly these two commits; the original 8999271fa commit with the 115-char header is no longer in the branch. A correctly noted "the prior 115-char violation is resolved" without over-explaining how it was fixed.
• CI check "Validate Commit Messages" shows conclusion: success on the current head. A's assessment matches CI reality.

Missed issues

None. This is a docs-only PR touching .mdx files and CHANGELOG.md. No cross-engine concerns, no test gaps, no security issues. A's scope is appropriate.

One marginal observation: A did not explicitly confirm that the 8999271fa commit is absent from the branch (not just that it was "replaced"). The PR commits endpoint confirms only f9ccbc3c0 and 6409c0027 are present, so the concern is fully resolved — not just worked around. This is background detail, not a missed finding.

Verdict alignment

A submitted COMMENTED for a PR with no outstanding findings and all CI green. APPROVED is the appropriate verdict when a review cycle concludes with all issues resolved. This is the inverse of the rounds 1–2 pattern (where COMMENTED understated a blocking issue); here it understates readiness. The finding is not incorrect — it is simply incomplete: a COMMENTED verdict leaves the PR without an approving review, which may block merge depending on branch protection rules.

Convergence

Aligned on approve. All prior findings are resolved:

1. Doc precision fix confirmed applied in both guide files.
2. Commitlint violation on 8999271fa resolved — that commit is no longer in the branch.
3. Both current commits are compliant, DCO-signed, and CI-passing.

The PR is ready to merge. No further bot action is required.