Javadoc silencers passed on a workflow's mvn command line evade both strictness guards

[EtaCassiopeia]

Problem

rift-java now has two javadoc-strictness guards, and neither can see a silencer added to a workflow's own Maven command line:

• The poison canary (Add permanent regression test for javadoc strictness enforcement #200, PR test(ci): add a javadoc strictness canary so a re-added failOnError cannot pass silently (#200) #202) proves behaviour, but only for rift-java-core and only for the command IT runs itself.
• The effective-pom sweep (Javadoc canary doesn't cover per-module failOnError overrides #203, PR test(ci): sweep every module's effective javadoc config for silencers (#203) #204) proves configuration across all 11 modules, but reads the POM model only.

maven-javadoc-plugin binds failOnError and skip to the user properties maven.javadoc.failOnError and maven.javadoc.skip. Those can be supplied with -D on the command line, where they never appear in help:effective-pom output. So adding -Dmaven.javadoc.failOnError=false to the real deploy command in .github/workflows/publish.yml (the deploy step) would silence javadoc errors for the actual Central release while both guards keep reporting "javadoc strictness confirmed".

This is the same self-concealing shape as #197 → #200 → #203, relocated one more layer out: from the root pom, to a module pom, to the CI invocation.

Evidence

• scripts/check-javadoc-strictness.py header states this limitation explicitly ("It cannot see a `-Dmaven.javadoc.failOnError=false` added to a workflow's own mvn command line").
• CONTRIBUTING.md repeats it in the "Build & verify" section.
• The deploy command in publish.yml and the sweep's own help:effective-pom invocation in ci.yml are independent hardcoded strings — nothing keeps them consistent.
• Raised by a silent-failure-hunter review agent during review of PR test(ci): sweep every module's effective javadoc config for silencers (#203) #204; deliberately scoped out of that PR, whose charter was the per-module POM gap.

Proposed Fix Options

This needs a design decision, hence triage not auto-implement.

Option A – assert the workflow commands themselves: a CI step that scans .github/workflows/*.yml for -Dmaven.javadoc. / -Ddoclint= / -Dmaven.javadoc.skip on any mvnw line and fails. Cheap, but it is a literal-string grep at a new layer (the same objection that got the grep option rejected in #200).

Option B – have the release lane assert the resolved value at run time: e.g. a tiny help:evaluate -Dexpression=maven.javadoc.failOnError check inside the same invocation, so whatever the command line actually set is what gets asserted. Closer to the effective-config philosophy already adopted in #203.

Option C – accept and document: the deploy command is a small, rarely-edited, code-reviewed surface.

Note: Option B is the only one that inspects the value Maven actually resolves for the invocation under test, which is the property #203 was chosen to have.

Provenance

Discovered during review of PR #204 (issue #203), merged as 75dbfd3. Pre-existing boundary of both guards, not introduced by that PR.

[EtaCassiopeia]

Triage — design decided: Option D (new), pin the values in the POM — supersedes A/B/C

A <configuration> value in the POM takes precedence over a Maven user property, so explicitly pinning the javadoc parameters does not merely detect a command-line silencer — it stops one from having any effect at all. That turns #205 from a detection problem into a non-problem.

Empirically verified (2026-08-05)

Broken {@link does.not.Exist} injected into Rift.java, then ./mvnw -Prelease -DskipTests -Dgpg.skip=true -pl rift-java-core -am package:

invocation	today (no pin)	with the pin
plain	FAILS (correct)	FAILS (correct)
-Dmaven.javadoc.failOnError=false	exit 0 — silenced	FAILS (defeated)
-Dmaven.javadoc.skip=true	exit 0 — silenced	FAILS (defeated)
-Ddoclint=none	silenced	FAILS (defeated)
-Dmaven.javadoc.skippedModules=rift-java-core	—	FAILS (defeated)

The first row is the #205 hole, reproduced. Every row is defeated by the pin.

What ships

Root pom.xml pluginManagement gains:

<configuration>
  <failOnError>true</failOnError>
  <skip>false</skip>
  <doclint>all</doclint>
</configuration>

and scripts/check-javadoc-strictness.py (#203) is extended to require that pin on every module. Without that second half the fix is self-concealing in the now-familiar way: deleting the <configuration> block restores the old permissive-by-default state, the sweep still sees no permissive value, and CI stays green. The sweep already accepts true/false/all as strict, so it keeps passing — it just also fails if the pin goes missing.

Why not the options in the body

• A (grep the workflows) — detection, not prevention, and defeated by any indirection (env var, composite action, shell variable).
• B (assert the resolved value) — as written it does not work: a separate help:evaluate invocation does not inherit the deploy step's -D flags, so it would prove nothing unless publish.yml were restructured to share one command-line string. Most complex, least benefit.
• C (document and close) — leaves the hole open on the one path that actually publishes to Central.

Acceptance criteria

• Clean tree + pin: the release build still succeeds (the pin must not turn existing warnings into errors).
• Broken {@link} + -Dmaven.javadoc.failOnError=false: build fails (today it succeeds).
• Removing the <configuration> pin makes the Javadoc canary doesn't cover per-module failOnError overrides #203 sweep fail, naming the modules that lost it.
• The existing poison canary and effective-pom sweep both still pass.