wheels upgrade: underscore-flag pre-check scope-asymmetry with advisory #2

[bpamiri]

Spun off from PR #2807 (Reviewer A round-3 non-blocking nit).

Problem

In `cli/lucli/Module.cfc::runUpgradeCheck()`, the advisory-1 suppression guard reads only `config/settings.cfm`:

```cfm
var settingsFile = variables.projectRoot & "/config/settings.cfm";
if (fileExists(settingsFile)) {
underscoreFlagAlreadySet = reFindNoCase(
"useUnderscoreReferenceColumns\s*=\s*true",
stripCfmlComments(fileRead(settingsFile))
) > 0;
}
```

But advisory #2 scans all of `config/` for the same pattern:

```cfm
arrayAppend(checks, {
description: "useUnderscoreReferenceColumns=true is set — confirm legacy migrations don't conflict",
severity: "advisory",
pattern: "useUnderscoreReferenceColumns\s*=\s*true",
scanDir: "config",
extensions: "cfm,cfc",
...
});
```

Impact

If a user sets the flag in an environment-specific override file (e.g., `config/production/settings.cfm`, `config/development/settings.cfm`), the pre-check on the root `settings.cfm` will return false, advisory #1 will fire ("opt into the flag!"), AND advisory #2 will also fire ("the flag is set!"). Same contradiction the round-1 fix was trying to prevent.

Low impact because:

1. Per-environment flag overrides for this setting are unusual
2. Both advisories are `severity: "advisory"` — they never gate CI

Suggested fix

Expand the pre-check to scan all of `config/` recursively (matching advisory #2's scope), not just the root `settings.cfm`. Existing helper pattern at `Module.cfc:3995` (the grep loop) shows how to do recursive scanning.

Alternatively: simplify by letting the bucketing handle the contradiction — e.g., if advisory #2 fires, suppress advisory #1 even if its guard didn't catch the flag.

Good first issue for someone wanting to touch the CLI without a deep dive.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see .ai/wheels/ for canonical patterns; the affected code is in cli/lucli/Module.cfc::runUpgradeCheck() (lines ~3913–3947).

Fix sketch

Single-file change in cli/lucli/Module.cfc. The pre-check at lines 3915–3927 only reads config/settings.cfm, but advisory #2 (lines 3945–3947) scans all of config/ recursively. Expand the pre-check to walk config/ (matching advisory #2's scanDir/extensions/comment-stripping behavior) so underscoreFlagAlreadySet is true whenever the flag is set in any environment-specific override. Existing recursive-grep pattern near Module.cfc:3995 is the prior art. Alternative the reporter mentions (suppress advisory #1 when advisory #2 fires, downstream of bucketing) is also acceptable — both eliminate the same contradiction.

Confidence: high

Issue body identifies the exact contradiction with quoted code, the fix is mechanical and confined to one CLI helper, no cross-engine concerns, no auto-downgrade rule applies (CLI scan code, not security/middleware/migrator/DI).

<!-- wheels-bot:triage:2808 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:high -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2809

Spec: cli/lucli/tests/specs/commands/UpgradeAdvisorySpec.cfc — failing → passing (source-level: text-match assertions against Module.cfc; the existing "uses stripCfmlComments on the settings-file pre-check" assertion was replaced with two new assertions covering recursive config/ scanning + per-file comment-stripping)

Implementation: cli/lucli/Module.cfc — runUpgradeCheck() pre-check now walks config/ recursively (matching advisory #2's scanDir: "config" / extensions: "cfm,cfc" scope) instead of reading only config/settings.cfm, so environment override files like config/production/settings.cfm satisfy the guard. Comment-stripping still runs per file so commented-out flag lines cannot satisfy the guard (Anti-Pattern #14).

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.