Fail the build on dangling javadoc comments

AGENTS.md

@@ -82,6 +82,10 @@ pins a released version. Consequences for a change here:
   constructor through `SsfCollections.copyOf` and nulls normalised to empty. Arguments are checked
   with `SsfAssert`. Factories are static `from(...)` (lenient, returns `null` or an empty value for
   input that does not fit) and `of(...)`.
+- **A javadoc comment belongs to a declaration.** One that an edit left between a method and its
+  own javadoc, or above a blank line, fails the `jdk` job of the CI (javac's `dangling-doc-comments`
+  lint, JDK 23 or newer, profile `dangling-doc-comments`); Java 21 builds do not notice. When you
+  insert a method, anchor on the javadoc above the neighbour, not on its signature.
 - **Protocol facts carry their source.** Javadoc and comments cite the specification and section
   (`SSF 1.0 8.1.4.1`, `RFC 9967, section 2.4`) and name the real-world deviation they tolerate
   (`// CAEP defines seconds since epoch, some transmitters send milliseconds`). Keep that habit;

CONTRIBUTING.md

@@ -91,6 +91,11 @@ GitHub Actions, see [`.github/workflows`](.github/workflows):
      and on the newest JDK as a job that does not fail the build; it passes
      `-Dbytebuddy.experimental=true` in case Mockito's Byte Buddy does not know the class file
      version yet), and `database` (the stores of `easyssf-receiver-jdbc` on PostgreSQL and MySQL).
+     The `jdk` job is also where a javadoc comment attached to nothing fails the build: the profile
+     `dangling-doc-comments` of the root POM turns on javac's lint of that name with `-Werror`
+     wherever the build JDK is 23 or newer, which knows the lint; Java 21 does not. To run the check
+     locally, build with such a JDK, for example `JAVA_HOME=~/.sdkman/candidates/java/25.0.2-tem
+     ./mvnw -o -DskipTests test-compile`.
   4. `status` is green when every job that had to run succeeded; skipped jobs count as green. It is
      the one check to require in the branch protection of `main`, the others come and go with the
      change.

pom.xml

@@ -427,6 +427,29 @@
                 </plugins>
             </build>
         </profile>
+        <profile>
+            <!-- A javadoc comment that is attached to nothing, typically one that a later edit separated from
+                 its method, is an error. javac knows the lint from JDK 23 on, so the check runs where the build
+                 JDK is new enough: the "jdk" job of the CI, not the Java 21 jobs. See CONTRIBUTING.md. -->
+            <id>dangling-doc-comments</id>
+            <activation>
+                <jdk>[23,)</jdk>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-compiler-plugin</artifactId>
+                        <configuration>
+                            <compilerArgs>
+                                <arg>-Xlint:dangling-doc-comments</arg>
+                                <arg>-Werror</arg>
+                            </compilerArgs>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
         <profile>
             <!-- Builds the artifacts the way Maven Central requires them: sources and javadoc jars,
                  GPG signatures, and "deploy" publishes to the Central portal. See CONTRIBUTING.md. -->