feat/v2.2-adoption-feedback: polish the operator experience surfaced by the service pilot

[vedanthvdev]

Why

The v2.1 pilot against Modulr's security-service (CAR-5190) surfaced five non-breaking rough edges that an adopter hits in their first hour with the plugin. This PR sharpens each one while keeping every DSL knob, default, and resolved behaviour from v2.1 bit-for-bit identical — v2.1 users can bump to v2.2 without touching build.gradle.

What (the five fixes)

Bug A — --explain no longer forces a full compile

The unconditional testClasses dependency turned a 3-second diagnostic run into a multi-minute compile on the real repo. v2.2 wraps the dependency in a Callable that re-evaluates after CLI parsing: when --explain is set the Callable returns an empty list and testClasses is pruned from the task graph; when --explain is absent the dependency behaves exactly as before.

Bug B — situation-specific Hint: lines in the --explain trace

Pre-v2.2 every mapper-touching situation printed the same "outOfScopeTestDirs is configured" hint — misleading on runs where OOS wasn't the cause. v2.2 splits the hint into three targeted branches:

• DISCOVERY_EMPTY → "discovery mapped 0 test classes" + testSuffixes / testDirs / no-coverage-yet causes
• DISCOVERY_INCOMPLETE → names the parse-failure risk + points at onDiscoveryIncomplete = "full_suite"
• DISCOVERY_SUCCESS with OOS configured-but-unmatched keeps the v2.1 wording

Risk C — LOCAL + DISCOVERY_INCOMPLETE now emits a loud WARN

LOCAL keeps onDiscoveryIncomplete = SELECTED on purpose, but without a visible signal a parse failure silently understates what ran. v2.2 emits a lifecycle WARN with marker affectedTest: LOCAL mode accepted a partial selection — grep-friendly, visible at Gradle's default log level, gated so it never fires in CI/STRICT (which already escalate to FULL_SUITE on DISCOVERY_INCOMPLETE).

Feature D — -PaffectedTestsMode runtime override

Mirrors -PaffectedTestsBaseRef: set -PaffectedTestsMode=local|ci|strict|auto to flip the plugin's mode without editing build.gradle. Implemented as a convention() so DSL-declared mode = '...' keeps precedence — a repo pinning its CI mode cannot be silently overridden by a stray -P.

Polish E — :module:test dispatch breakdown in --explain

A SELECTED --explain run now prints the exact dispatch grouping a non-explain run would use:

Modules:         2 modules, 3 test classes to dispatch
  :application:test (2 test classes)
    com.example.FooTest
    com.example.BarTest
  :api:test (1 test class)
    com.example.BazTest

Non-SELECTED runs suppress the block entirely.

Verification

• ./gradlew test functionalTest green locally (73 unit tests + 54 Cucumber scenarios, +2 new unit tests and +10 new e2e scenarios from this PR).
• New e2e file 06-v2.2-adoption-feedback.feature pins each user-facing behaviour above, so a regression on any of the five surfaces as a named scenario failure rather than silent UX drift.
• Unit tests pin the Callable prune shape (Bug A), the mode-precedence contract (Feature D), the three hint variants (Bug B), and the Modules-block empty/multi-module/root-project/preview-truncation edges (Polish E).

Release plan

• CHANGELOG.md has a full v2.2.0 entry describing each fix and its scope.
• .release-version pins 2.2.0 so the next merge-to-master release workflow tags and publishes v2.2.0, then auto-deletes the pin in a [skip ci] follow-up (matches the v2.1.0 release flow).

Test plan

• ./gradlew test — green
• ./gradlew functionalTest — green (all 6 feature files, including new 06-v2.2-adoption-feedback.feature)
• CI pipeline green on this branch before merge