docs: make the gate ./gradlew build, not clean build

[juherr]

Follow-up to #3302 and #3309.

What this started as, and what it became

The first version of this PR added a paragraph telling agents to judge by hand whether a diff could affect the build, so they could skip the six-minute clean build on documentation changes. A review pass took it apart.

The paragraph was working around a cost I had created myself. CI runs build, not clean build. Without clean, Gradle's up-to-date check already answers the question the paragraph asked a human to answer — and answers it from the real task inputs, which cannot drift. Measured here:

build with real work to do	6m 44s
build after a documentation-only change	1–3s

So the gate becomes ./gradlew build, and the paragraph is deleted rather than fixed. clean stays documented for ruling out stale output.

The list it carried was wrong in both directions

• .github/workflows/ cannot fail a Gradle build. It was listed as something that "does break the build", one sentence after the build was defined as clean build. An agent editing a workflow, running the gate and seeing green would have verified nothing — the exact failure the paragraph existed to prevent.
• LICENSE.txt does. It reads as documentation and is copied into META-INF of every jar by testng.java-library.gradle.kts.
• Comments were listed as safe. They are not: autostyleCheck runs google-java-format, which reflows javadoc, and .java files ship in the published sources jar. Both were reproduced as failing builds during review.

Also corrected

"CI runs it on every push and pull request" was false. The branches: ['*'] filter in test.yml does not match /, and every branch here has one — so pushing docs/foo triggers no Test run until a pull request exists. Verified against the run history: every push-triggered run is on master. Pull requests also get an OpenRewrite check and wrapper validation on top of the matrix, so a green local build is not a green CI.

CLAUDE.md is aligned with the new gate.

Verification

Applied the new rule to itself: documentation-only diff, so ./gradlew build — 1s, exit 0, and verifyPublishedPomDependencies still green. Staleness checked before committing.

Summary by CodeRabbit

• Documentation
  • Updated build verification guidance to recommend running ./gradlew build as the CI gate.
  • Clarified when clean is appropriate and why local results may not match CI outcomes.
  • Added CI pull request check context and explained how workflow triggers behave for push branches.
  • Refreshed long-running build and log-monitoring examples to match the build workflow and improve pipeline failure visibility.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5c30a7b4-7445-4085-ab81-188188a21c72

📥 Commits

Reviewing files that changed from the base of the PR and between f4cdaa5 and a8335e4.

📒 Files selected for processing (2)

• AGENTS.md
• CLAUDE.md

🚧 Files skipped from review as they are similar to previous changes (1)

• CLAUDE.md

---

📝 Walkthrough

Walkthrough

Build guidance now uses ./gradlew build instead of ./gradlew clean build. The documentation clarifies Gradle rerun behavior, CI-only validation, workflow branch filtering, timeouts, and pipefail handling for filtered build output.

Changes

Gradle verification guidance

Layer / File(s)	Summary
Clarify verification gate AGENTS.md	Defines ./gradlew build as the CI gate, explains when to use clean, and documents OpenRewrite, wrapper validation, and push-branch filtering.
Update Gradle command examples CLAUDE.md	Replaces clean builds in long-running commands and filtered output pipelines while retaining pipefail and updating failure extraction commands.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• testng-team/testng#3302: Updates overlapping AGENTS.md and CLAUDE.md Gradle build-command guidance.
• testng-team/testng#3309: Refines related AGENTS.md verification guidance.

Suggested reviewers: krmahadevan

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main documentation change from ./gradlew clean build to ./gradlew build.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 16-21: The verification wording in AGENTS.md incorrectly presents
clean build as the exact CI command. Update the documentation to distinguish the
CI workflow’s build task from the recommended local ./gradlew clean build
command, while retaining the existing duration and zero-failure expectations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 60554c89-ec03-4f76-91ed-f1fc45ac258d

📥 Commits

Reviewing files that changed from the base of the PR and between 474bcce and 7a4aa7e.

📒 Files selected for processing (1)

• AGENTS.md