test(it): Redesign Invoker coverage matrix

AGENTS.md

@@ -19,13 +19,15 @@
 
 ## Tests
 - Put isolated Mojo behavior, parameters, version gates, reflection failures, and utility behavior in `src/test/java` unit tests.
-- Add `src/it/<project>` Maven Invoker tests only for real consuming-build behavior: lifecycle wiring, classpaths, Groovy compilation, generated stubs, multi-module builds, or configuration interactions.
-- Do not add integration-test combinations mechanically; cover distinct user-visible workflows and regressions that unit tests cannot establish.
+- `src/it` intentionally contains one flat Maven Invoker project per distinct consuming-build workflow; it covers lifecycle wiring, classpaths, Groovy compilation, generated stubs, reactor builds, and packaging boundaries that unit tests cannot establish.
+- Add an Invoker project only for a new user-visible workflow or a regression whose consuming-build boundary is absent from `src/it/README.md`; otherwise extend the existing fixture that owns that boundary.
+- Keep parameter-only changes without consuming-build output, version gates, reflection failures, and interactive `console`/`shell` behavior in focused unit tests; do not add configuration cross-products mechanically.
 
 ## References
 | Need | File |
 |---|---|
 | Build, plugin metadata, and Invoker configuration | `pom.xml` |
 | CI compatibility matrix | `.github/workflows/ci.yaml` |
 | Common local, release, and maintenance commands | `DEVELOPER_NOTES.md` |
+| Invoker workflow coverage and add-test criteria | `src/it/README.md` |
 | Project and user documentation | `README.md` |

src/it/README.md

@@ -0,0 +1,28 @@
+# Integration Test Coverage
+
+Each directory is one user-visible Maven workflow. Keep fixtures flat so they can be selected with `-Dinvoker.test`, and add one only when it covers a distinct lifecycle, classpath, reactor, compatibility, or historical feature/regression boundary that unit tests cannot prove.
+
+| Fixture | Workflow | Coverage boundary | Primary assertion |
+|---|---|---|---|
+| `compile-default` | Compile Groovy sources | Default lifecycle | Compiled classes run in tests |
+| `compile-config-script` | Compile with a configuration script | Compiler configuration | Configured source and test compilation |
+| `compile-parameters` | Compile with Java parameter metadata | Generated bytecode metadata | Reflection assertion |
+| `compile-mixed-java-groovy` | Compile Java and Groovy together | Main source ordering | Cross-language runtime behavior |
+| `compile-reactor` | Compile a mixed reactor | Inter-module dependency ordering | Reactor consumer test |
+| `stubs-main-and-test` | Generate main and test stubs | Source-root registration | Maven source-root model |
+| `stubs-cleanup` | Remove test stubs | Source-root removal | Removed test source root |
+| `compile-classpath-isolation` | Reject a polluted classpath | Classloader isolation | Expected Maven failure |
+| `stubs-classpath-isolation` | Reject polluted stub generation classpaths | Stub classloader isolation | Expected Maven failure |
+| `execute-inline-and-file` | Execute inline and file scripts | Script and Maven-context injection | Script assertions and runtime output |
+| `execute-reactor-classpath` | Execute scripts in a reactor | Reactor classpath resolution | Cross-module script execution |
+| `groovydoc-main-and-jar` | Generate main GroovyDoc and JAR | Attached documentation artifact | Documentation test and package goal |
+| `groovydoc-test-and-test-jar` | Generate test GroovyDoc and JAR | Test documentation lifecycle | Generated test documentation |
+| `forked-jvm-compile-and-stubs` | Fork compilation and stubs | JDK toolchain selection | Toolchain build-log check |
+| `forked-jvm-groovydoc` | Fork GroovyDoc | JDK toolchain selection | Toolchain build-log check |
+| `classpath-project-only` | Resolve Groovy from the project | `PROJECT_ONLY` | Project dependency compilation |
+| `classpath-plugin-only` | Resolve Groovy from plugin dependencies | `PLUGIN_ONLY` | Plugin-only compilation and docs |
+| `classpath-project-and-plugin` | Resolve both classpaths | `PROJECT_AND_PLUGIN` | Combined dependency compilation and docs |
+| `shaded-groovy` | Use Groovy from an uber JAR | Shaded runtime discovery | Consumer runtime test |
+| `maven-plugin-consumer` | Build a Groovy Maven plugin | Plugin descriptor and consumer execution | Invoked custom Mojo |
+
+Do not add a fixture for a parameter-only change without consuming-build output, reflection failure, or interactive console/shell behavior; cover those with focused unit tests. New fixtures require a regression issue or a documented distinct user workflow.