docs(cursor-rules): fix the two live AI-context contradictions in .cursor/rules/

[fabrizzio-dotCMS]

What

Fixes the two contradictions still live in .cursor/rules/, and adds a script that measures whether one of them actually stops recurring.

.cursor/rules/*.mdc is the second entry point for AI context — Cursor loads a rule automatically when the file you are editing matches its globs. java-context.mdc fires on every *.java and pom.xml; test-context.mdc on every *Test.java. The Rock's M1–M3 (#37126, #37127, #37128) audited docs/ and root CLAUDE.md and left this directory untouched, because it sits in Scout's slice. Result: two of the four failure modes #37124 exists to stop are still being served to anyone working from Cursor.

Java version

java-context.mdc stated Core: Java 11 syntax. CLI: Java 21 ok. Runtime: Java 21.

CLAUDE.md:68 no longer pins a version at all — it defers to .sdkmanrc for the runtime, dotcms.core.compiler.release in parent/pom.xml for core modules, and maven.compiler.release in tools/dotcms-cli/pom.xml for the CLI. #37126 fixed this in the docs; the Cursor rule kept serving Java 11 idioms. It now points at the properties instead of restating a number, with a line saying not to hardcode one here again — that is what caused the drift.

Integration-test registration

MainSuite/Junit5Suite appeared nowhere under .cursor/rules/, while test-context.mdc did hand out a command for running integration tests. So the rule gave the "how to run" without the "how to make CI run it".

An integration test not listed in a @SuiteClasses array compiles, passes review, and is silently never run in CI — green build, zero coverage. That has been a Critical Rule in CLAUDE.md since #37127, and it is the opening example in #37124's own problem statement.

Per review feedback from @nollymar and @jcastro-dotcms, the rule states the consequence and defers the mechanics to docs/testing/INTEGRATION_TESTS.md, which #37583 rewrote the same day: the suite to pick is whichever MainSuite* currently has the shortest CI runtime, and the suite set is explicitly not fixed. The rule tells the reader not to hardcode suite names — the same drift the Java fix above addresses.

Measuring it

scripts/validate-integration-test-registration.sh reads the suite list from .github/test-matrix.yml — what CI actually runs, so a future MainSuite3b is picked up the day it lands, and QuickSuite (in the tree, not in the matrix) correctly does not count. It extracts the classes in each suite's @SuiteClasses block, cross-checks against the concrete *Test.java classes in dotcms-integration, and reports two different things: the standing backlog, and — the part that matters for the gate — the tests added in a recent window.

$ scripts/validate-integration-test-registration.sh 60
CI suites (from .github/test-matrix.yml):
  - MainSuite1a … MainSuite3a, Junit5Suite1, OpenSearchUpgradeSuite

Registered classes:  609
Concrete *Test.java: 673
Never run in CI:     87

Leak rate: 0 of 28 new tests unregistered.

The headline number is 0, and that is worth stating plainly: over the last 60 days, every new integration test was registered. The failure mode this Rock cites is not currently leaking in the flow. What remains is a standing backlog of 87 classes that exist and never run — separate work, not a regression.

An earlier revision of this PR quoted 1 of 28. That was wrong: the script's suite list was a hardcoded glob that missed OpenSearchUpgradeSuite, so a test registered there read as unregistered. Two further bugs were fixed in the same pass — the bot review's point that class extraction matched every X.class token rather than the @SuiteClasses block, and, once anchored, that MainSuite3a spells the annotation @Suite.SuiteClasses and was silently dropped entirely. The script now aborts if any CI suite yields zero classes, so that class of error fails loudly instead of inflating the count.

Caveat, documented in the script: matching is by simple class name, not fully-qualified. Two same-named classes in different packages, one registered and one not, read as registered. Fine for trending; verify by hand before quoting the number anywhere.

What this means for the gate

#37581's monitoring gate was premised on watching a leak stop. With a measured baseline of 0 leaks in 60 days, the gate's job changes: it confirms the rate stays at 0 now that Cursor users get the rule too, rather than demonstrating a drop. Worth a decision on whether that still warrants the full 1–2 week window.

Testing

Documentation and tooling only — no production code. The script was run against main at dfbe40f. Its 87-class backlog figure was reproduced independently, and five entries spot-checked by hand against every *Suite*.java in the module. The two .mdc edits were checked against real source: .sdkmanrc, parent/pom.xml, tools/dotcms-cli/pom.xml, .github/test-matrix.yml, and the suite files under dotcms-integration/src/test/java/com/dotcms/.

Refs #37577, #37581

🤖 Generated with Claude Code

This PR fixes: #37577

[claude]

Claude finished @fabrizzio-dotCMS's task in 2m 54s —— View job

---

Review

Docs + tooling only, no production code. I verified the two .mdc edits against real source and traced the new script's logic. The reviewer feedback from @nollymar / @jcastro-dotcms is addressed by 07d4c0e8.

New Issues

• 🟡 Medium: scripts/validate-integration-test-registration.sh:60 — the class-extraction awk only recognizes @SuiteClasses / @Suite.SuiteClasses, but Junit5Suite1 (deliberately included via the matrix) registers its tests with JUnit 5's @SelectClasses (Junit5Suite1.java:34). The script produces correct numbers today only by coincidence: line 26 of that file mentions {@code @SuiteClasses} in a javadoc comment, which trips inblock=1, and since no }) appears before the real @SelectClasses({ … }) block, its 15 classes get captured anyway. If that javadoc is ever reworded/reordered, extraction returns 0 for Junit5Suite1 and the guard at line 66–68 hard-fails with the misleading message "unrecognized @SuiteClasses form?" (set -e → exit 1) — or, absent the guard, all ~15 JUnit 5 ITs (JobQueue*, BulkUpload*) would read as "never run in CI" and, being recent additions, as false leaks in the window (a false --strict exit 1 if wired to CI). The comment at line 56 ("both spellings occur … @SuiteClasses and @Suite.SuiteClasses") doesn't acknowledge @SelectClasses at all. Add @SelectClasses to the regex on line 60 so the coincidence becomes intent. Fix this →

Resolved

• ✅ .cursor/rules/test-context.mdc:22 — @jcastro-dotcms / @nollymar's feedback (point IT docs at docs/testing/INTEGRATION_TESTS.md, don't hardcode a suite list) is handled: the rule now links the doc's "Registering Tests in a MainSuite (CI gate)" section (heading confirmed present) and drops the hardcoded suite names.

Verified

• .cursor/rules/java-context.mdc:29-31 — properties resolve: .sdkmanrc (java=25.0.4+1-ms), parent/pom.xml (dotcms.core.compiler.release=25), tools/dotcms-cli/pom.xml (maven.compiler.release=11). No hardcoded version — matches CLAUDE.md.
• Script sources exist: .github/test-matrix.yml and its test_class: entries, plus the abstract-class / concrete-*Test.java split and the loud-fail guard are sound for the @SuiteClasses families. --strict and the class-name caveat are documented.

Nice touch reading the suite set from .github/test-matrix.yml rather than hardcoding it — that keeps the script honest about what CI actually runs. The one gap is that the matrix now includes a JUnit 5 suite the extractor doesn't formally understand. Non-blocking.

_{Note: I couldn't execute the script in this environment (permission), so the trace above is by reading, not by run.}
· issue-37577-cursor-rules-contradictions