feat/v2-explain: Add --explain task flag and ActionSource decision-trace

[vedanthvdev]

Summary

Adds an --explain flag to the affectedTest Gradle task that prints the full decision trace and exits without running tests. Closes the second of the deferred Phase 1 follow-ups from the v2 design doc.

Operators landing on a surprising outcome (full suite when they expected a selection, a skip when they expected a run) had no in-band way to ask why — the engine's reasoning lived in debug logs that CI runners do not capture by default. This PR makes that reasoning a first-class output.

What's in the box

• ActionSource enum in affected-tests-core — names which tier of the priority ladder picked each situation's action (EXPLICIT, LEGACY_BOOLEAN, MODE_DEFAULT, HARDCODED_DEFAULT). Resolved alongside Action in AffectedTestsConfig so the two stay in lockstep.
• Buckets record on AffectedTestsEngine.AffectedTestsResult — every result now carries the per-bucket file breakdown (ignored / out-of-scope / production / test / unmapped) the mapper produced, so the trace matches what the engine actually saw.
• --explain task option on AffectedTestTask — when set, the task renders the trace via lifecycle log lines and returns before dispatching tests. Marked @Internal so flipping the flag never invalidates a cached execution.
• renderExplainTrace as a pure function over config + result, so unit tests exercise the format without spinning up a live Gradle runtime.
• README gains a third Quick Start step with a sample trace.

Sample trace

```
=== Affected Tests — decision trace (--explain) ===
Base ref: origin/master
Mode: unset (effective: n/a (pre-v2 defaults))
Changed files: 3
Buckets:
ignored 1
out-of-scope 0
production .java 1
test .java 0
unmapped 1
ignored sample: README.md
production sample: src/main/java/com/example/Foo.java
unmapped sample: build.gradle
Situation: UNMAPPED_FILE
Action: FULL_SUITE (source: pre-v2 hardcoded default)
Outcome: FULL_SUITE — runAllOnNonJavaChange=true / onUnmappedFile=FULL_SUITE — non-Java or unmapped file in diff
Action matrix (situation → action [source]):
EMPTY_DIFF SKIPPED [pre-v2 hardcoded default]
ALL_FILES_IGNORED SKIPPED [pre-v2 hardcoded default]
ALL_FILES_OUT_OF_SCOPE SKIPPED [pre-v2 hardcoded default]
UNMAPPED_FILE FULL_SUITE [pre-v2 hardcoded default]
DISCOVERY_EMPTY SKIPPED [pre-v2 hardcoded default]
DISCOVERY_SUCCESS SELECTED [explicit onXxx setting]
=== end --explain ===
```

Tests

• `AffectedTestsConfigTest#actionSourceReflectsResolutionTierOrdering` — pins the explicit > legacy > mode > hardcoded ordering for `actionSourceFor()`.
• `AffectedTestTaskExplainFormatTest` (new) — eight cases covering header/footer, bucket breakdown + truncation, every action source tier, the full action matrix in stable order, and the three outcome shapes (FULL_SUITE / SKIPPED / SELECTED).
• Existing `AffectedTestTaskLogFormatTest` updated for the new `Buckets` field on `AffectedTestsResult`.

`./gradlew check` passes (25 unit tests + functional tests).

Test plan

• `./gradlew check` green locally
• Pilot in modulr-security-service to verify trace renders cleanly in real CI logs
• Wire the `--explain` flag into team docs once merged