docs: consolidate Wheels 5 roadmap into a single decided document

[bpamiri]

What

Replaces the draft docs/releases/wheels-5-roadmap-recommendations.md (2,689 lines) with a single canonical docs/releases/wheels-5-roadmap.md (268 lines). There is now one document describing what Wheels 5 is for.

This rewrite is the output of a critical review of the original draft — challenging not just the recommendations but the underlying assumptions and reasoning. Both the codebase claims and the external/market claims in the draft were independently verified.

Why the draft needed rework

The draft was accurate at the leaf level but wrong at the root:

• Wrong organizing frame. It assumed the contest is "Wheels vs ColdBox for CFML share." The CFML market is contracting and maintenance-weighted; the real risk is attrition (developers leaving CFML entirely), not ColdBox. Reframed the objective around retention + onboarding friction, with one forward bet.
• A load-bearing factual error. The draft claimed "no public RustCFML URL is assumed" and then made RustCFML a strategic pillar. It is in fact public (pixl8/RustCFML, Alex Skinner) but ~26★, AI-authored, and has no ORM — it cannot run Wheels' model layer. Demoted to monitor-only.
• "Consolidation" that proposed expansion. It framed several already-shipped v4 systems (DI, jobs, middleware, query builder, packages — all verified present) as net-new and layered more subsystems on top. This is now an explicit coherence release.
• Scope unrealistic for a small team and indecision shipped as design (three coexisting controller idioms, five strict modes, five CI tiers).

What the new roadmap commits to

• 5.0 core (small, decided): controller-level strong params (CFML-native helper functions, not a Rails-style object — avoids struct member-function collisions), an additive response object, a formalized RequestContext with one controller idiom (no action-arg injection, no three styles), decisive legacy removal (plugins → adapter package, RocketUnit), a single CI matrix manifest, and one forward bet: AI-legibility (machine-readable routes, lifecycle trace, stable MCP contract, canonical generators).
• Deferred to 5.1+: application modules, scheduler/async, config schema, DI discovery, OpenAPI.
• Dropped: strategic conformance program, RFC-gate process, RustCFML pillar.
• Dependency posture corrected: own the vendored LuCLI fork (it's an alpha, single-maintainer upstream) with a continuity plan; BoxLang first-class but re-evaluated quarterly.
• Testing right-sized to two tiers + a release gate (with public distribution canaries) instead of five tiers.
• §11 Open decisions flags the items that still need maintainer ratification (engine minimums, BoxLang level, Oracle blocking, whether this is a 5.0 vs 4.x minors), each with a recommended default.

Notes

• Docs-only change; no framework/CLI/app code touched, so no test suites apply. No changelog fragment (not a user-facing framework fix/feat).
• The previous draft is preserved in git history at 53e6778.

🤖 Generated with Claude Code

---

Generated by Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR. This PR replaces the 2,688-line wheels-5-roadmap-recommendations.md draft with a single 268-line wheels-5-roadmap.md canonical roadmap. It is a docs-only change — no framework/CLI/app code is touched, so no test suites or changelog fragment apply, and the PR body says as much correctly. I independently checked every "verified" codebase claim and every file/anchor link in the new document; all of them hold. Verdict: comment — the diff is essentially clean, with one trivial command-name nit that does not block.

Conventions

• docs/releases/wheels-5-roadmap.md:199 — the generated-app smoke flow is written as `new` → `generate scaffold` → `dbmigrate latest` → `test` → `start`. The canonical CLI verb is wheels migrate latest, not dbmigrate latest — cli/lucli/Module.cfc:606 defines function migrate() and there is no top-level dbmigrate command (the only dbmigrate hits in cli/lucli/ are template-snippet strings). CLAUDE.md's onboarding-harness note also describes the flow as wheels new → wheels start → wheels migrate latest. Suggest changing dbmigrate latest → migrate latest so the doc matches the surface it elsewhere documents carefully. Non-blocking.

Docs

Verification of the document's load-bearing factual claims (all confirmed against the tree at this head):

• §3 baseline table paths all resolve: vendor/wheels/Injector.cfc, Job.cfc, JobWorker.cfc, middleware/ (contains Pipeline, Cors, RateLimiter, SecurityHeaders, RequestId), model/query/QueryBuilder.cfc, PackageLoader.cfc + ModuleGraph.cfc, model/properties.cfc, cli/lucli/Module.cfc, .github/workflows/compat-matrix.yml + pr.yml. Relative ../../ depth from docs/releases/ is correct.
• §5.1 "Gap (verified)": accessibleProperties() (properties.cfc:10) and protectedProperties() (properties.cfc:32) exist; expectParams / requireParam / permit do not yet exist anywhere in vendor/wheels — the gap is real.
• §5.3 "there is no RequestContext.cfc": confirmed — no such file under vendor/wheels.
• §5.4 "Plugins.cfc, 1,131 lines": exact (wc -l = 1131). vendor/wheels/Test.cfc (RocketUnit) present as claimed.
• §3/§6 CLI claims: routes() (Module.cfc:1267) and doctor() (Module.cfc:2181) both exist.
• Intra-doc anchors #9-deferred-to-51, #10-what-wheels-5-will-not-do, #11-open-decisions match GitHub's slugification of the corresponding ## headers.

Commits

• 1b27b0531 docs: consolidate Wheels 5 roadmap into a single decided document — type docs is in the allowlist, subject is lower-case and well under 100 chars, body is wrapped, and the commit carries a DCO Signed-off-by trailer. Conforms to commitlint.config.js.

Nice cleanup — collapsing the dual-document state into one decided roadmap, with the prior draft preserved at 53e6778 in history, is the right call. The single nit above is optional.