From 7227da98caaae0f5d19fa47c1399ca7fa4323ef0 Mon Sep 17 00:00:00 2001
From: Mohsen Zainalpour <zainalpour@gmail.com>
Date: Wed, 5 Aug 2026 18:29:40 -0400
Subject: [PATCH] fix(build): pin javadoc strictness so a -D flag cannot
 silence it (#205)

maven-javadoc-plugin binds failOnError/skip/doclint to Maven USER PROPERTIES, and a property only supplies the value when the POM does not. Left unset, `-Dmaven.javadoc.failOnError=false` on any mvn command line (including publish.yml's real deploy) silences javadoc without touching a file in the repo, invisible to both existing guards. A POM <configuration> value takes precedence over the property, so pinning makes the override impossible rather than merely detectable. The #203 sweep is extended to REQUIRE the pin, because deleting it restores the overridable state without introducing any permissive value.
---
 CONTRIBUTING.md                     |  42 +++-
 pom.xml                             |  11 +
 scripts/check-javadoc-strictness.py | 309 +++++++++++++++++++++++++---
 3 files changed, 320 insertions(+), 42 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 99c8dc1..96ccdc6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -30,8 +30,8 @@ installing). It runs automatically in the release lane (`-Prelease`, i.e. CI's r
 deploy); to run it locally, add `-Dinvoker.skip=false`.
 
 Javadoc errors fail the build. A broken `{@link}`, an unresolvable reference, or a malformed tag
-is an error under the JDK's default doclint, and the javadoc jars published to Maven Central are
-built with the plugin's default `failOnError=true`. Javadoc only runs in the release lane, so a
+is an error under doclint, and the javadoc jars published to Maven Central are built with
+`failOnError` on — both pinned explicitly in the root pom (see *The pin*, below). Javadoc only runs in the release lane, so a
 plain `./mvnw verify` will not catch it, but CI's release-smoke will — check it locally with:
 
 ```sh
@@ -61,7 +61,7 @@ override elsewhere would leave it green. The sweep runs `help:effective-pom` ove
 reactor and rejects any module whose *effective* javadoc config silences errors — `failOnError`,
 `skip`, `skippedModules`, a `doclint` value other than `all`, an `-Xdoclint` option that disables a
 group, or the equivalent `maven.javadoc.*` / `doclint` **properties**, which need no `<configuration>`
-at all. Run it locally with:
+at all. It also **requires** the pin described below to be present on every module. Run it locally with:
 
 ```sh
 # -DdualEmbedded matches CI, so the sweep covers rift-java-embedded too
@@ -73,11 +73,37 @@ python3 scripts/check-javadoc-strictness.py --self-test   # asserts the detector
 The module set depends on your JDK (`rift-java-embedded-jdk21` only joins on JDK 21), so a local run
 sweeps fewer modules than CI — pass `--require` only if you know which set to expect.
 
-Two things it deliberately does *not* do: it reads configuration, not behaviour (that is the
-canary's job), and it cannot see a `-Dmaven.javadoc.failOnError=false` added to a workflow's own
-`mvn` command line. Its `--require` list in `ci.yml` names the modules the reactor must contain, so
-a module dropping out of the reactor fails the sweep instead of silently shrinking it — add new
-published modules there.
+It reads configuration, not behaviour — proving the behaviour is the canary's job. Its `--require`
+list in `ci.yml` names the modules the reactor must contain, so a module dropping out of the reactor
+fails the sweep instead of silently shrinking it; add new published modules there.
+
+**The pin** closes the command-line gap, and is the reason the root `pluginManagement` sets these
+three explicitly rather than relying on their (already strict) defaults:
+
+```xml
+<configuration>
+  <failOnError>true</failOnError>
+  <skip>false</skip>
+  <doclint>all</doclint>
+</configuration>
+```
+
+Each of these parameters binds to a Maven **user property**, and a property only supplies the value
+when the POM does not. Left unset, `-Dmaven.javadoc.failOnError=false` on any `mvn` command line —
+including `publish.yml`'s real deploy — silences javadoc errors for that invocation without touching
+a file in the repo, where neither guard above could see it. A `<configuration>` value takes
+precedence over the property, so pinning makes that override *impossible* rather than merely
+detectable. Verified: with the pin, a broken `{@link}` still fails the build under
+`-Dmaven.javadoc.failOnError=false`, `-Dmaven.javadoc.skip=true` and `-Ddoclint=none`.
+
+Deleting the pin would restore the silently-overridable state without introducing any *permissive*
+value, so the sweep requires it and names any module that lost it. Do not remove it.
+
+The sweep requires the pin on the entry Maven actually **executes**, and on any `<execution>` that
+carries its own `<configuration>`. Both are load-bearing: a module can override its inherited
+configuration (`combine.self="override"`) at either level, which drops the pin at run time while the
+inherited copy still looks pinned. If you add a javadoc `<configuration>` to a module or an
+execution, repeat the three pinned values in it.
 
 ## Module layout
 
diff --git a/pom.xml b/pom.xml
index 3dbb7c0..9162780 100644
--- a/pom.xml
+++ b/pom.xml
@@ -137,6 +137,17 @@
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-javadoc-plugin</artifactId>
           <version>${maven-javadoc-plugin.version}</version>
+          <!-- Pinned, not merely left to the strict defaults: these three parameters bind to the
+               user properties maven.javadoc.failOnError / maven.javadoc.skip / doclint, so without
+               an explicit value here a `-Dmaven.javadoc.failOnError=false` on any mvn command line
+               silences javadoc errors for that invocation (#205). A <configuration> value takes
+               precedence over the property, which makes that override impossible rather than merely
+               detectable. scripts/check-javadoc-strictness.py requires this block to stay. -->
+          <configuration>
+            <failOnError>true</failOnError>
+            <skip>false</skip>
+            <doclint>all</doclint>
+          </configuration>
         </plugin>
         <!-- Not bound to any phase: CI's javadoc-strictness sweep invokes help:effective-pom by
              goal prefix (#203). Prefix-invoked goals otherwise resolve whatever is newest on Central
diff --git a/scripts/check-javadoc-strictness.py b/scripts/check-javadoc-strictness.py
index b7ddf22..d2ea56a 100755
--- a/scripts/check-javadoc-strictness.py
+++ b/scripts/check-javadoc-strictness.py
@@ -16,8 +16,9 @@
 # execute, with inheritance, profiles and per-module overrides already merged, so the check cannot be
 # defeated by whitespace, a property indirection, or the setting living in a different file.
 #
-# Every rejection below was verified behaviourally: each one makes a build with a deliberately broken
-# {@link} in rift-java-jackson exit 0 instead of failing.
+# Every rejection below was verified behaviourally — each makes a build with a deliberately broken
+# {@link} in rift-java-jackson exit 0 instead of failing — except `skippedModules`, which the
+# non-aggregate `jar` goal never reads (see REQUIRED_PIN) and is rejected pre-emptively.
 #
 # `doclint` and `-Xdoclint` are matched as an ALLOWLIST, not a denylist. Their value space is open
 # (`none`, `syntax`, `all,-missing,-reference`, …) and only some values disable the `reference` group
@@ -25,9 +26,13 @@
 # repo's intended state is "not configured at all", so anything other than `all` is rejected and
 # widening the allowlist is a conscious edit.
 #
-# Scope, stated honestly: this asserts CONFIGURATION reachable from the POM. It cannot see a
-# `-Dmaven.javadoc.failOnError=false` added to a workflow's own mvn command line. The rift-java-core
-# poison canary asserts BEHAVIOUR. Each covers the other's blind spot — keep both.
+# Scope, stated honestly: this asserts CONFIGURATION; the rift-java-core poison canary asserts
+# BEHAVIOUR. Each covers the other's blind spot — keep both.
+#
+# The command-line vector (`-Dmaven.javadoc.failOnError=false` on a workflow's own mvn invocation,
+# invisible to any POM-reading check) is not defended here by detection but closed by construction:
+# the root pluginManagement pins the parameters explicitly, and a POM <configuration> value beats a
+# user property, so the flag has no effect (#205). REQUIRED_PIN below is what keeps that pin in place.
 
 import argparse
 import contextlib
@@ -36,6 +41,7 @@
 import sys
 import tempfile
 import xml.etree.ElementTree as ET
+from typing import NamedTuple
 
 NS = "{http://maven.apache.org/POM/4.0.0}"
 JAVADOC_PLUGIN = "maven-javadoc-plugin"
@@ -61,6 +67,18 @@
     "additionalOptions",
 )
 
+# Every module must set these EXPLICITLY, not merely leave them at their strict defaults (#205).
+# These parameters bind to user properties, and a property only supplies the value when the POM does
+# not — so an unconfigured plugin is silently overridable by `-Dmaven.javadoc.failOnError=false` on
+# any mvn command line, including publish.yml's real deploy. Pinning them in the POM makes that
+# override impossible; requiring the pin here is what stops someone quietly deleting it again.
+#
+# maven.javadoc.skippedModules is deliberately NOT pinned even though it is rejected below: in
+# 3.11.2 it is only consulted by the aggregate goals, and the release profile binds the
+# non-aggregate `jar` goal, so it is inert here. Rejecting it is cheap insurance for the day someone
+# switches to aggregate-jar; pinning a parameter the build never reads would just be noise.
+REQUIRED_PIN = {"failOnError": "true", "skip": "false", "doclint": "all"}
+
 
 def _doclint_is_strict(value):
     """Only an unset or fully-enabled doclint keeps `error: reference not found` fatal."""
@@ -104,40 +122,116 @@ def permissive_settings(config):
     return reasons
 
 
+EXECUTING = "build/plugins"
+MANAGED = "pluginManagement"
+
+
 def javadoc_plugins(project):
-    """Javadoc plugin elements that actually govern the build.
+    """[(where, plugin)] for javadoc entries that govern the build.
 
     Scoped to <build><plugins> and <build><pluginManagement><plugins>. <reporting> is site-only and
     any <profiles> the effective pom retains are, by definition, not the active model — including
     either would raise false alarms, and a guard that cries wolf is a guard that gets deleted.
+
+    The two containers are tagged rather than merged because they are not interchangeable: only the
+    EXECUTING entry decides what Maven runs. A module can carry `<configuration combine.self=
+    "override">` in its own <build><plugins> entry, which drops the inherited pin from the executing
+    config while the pluginManagement copy still shows it — verified against this repo.
     """
     found = []
     build = project.find(NS + "build")
     if build is None:
         return found
-    containers = [build.find(NS + "plugins")]
+    plugins = build.find(NS + "plugins")
+    if plugins is not None:
+        for plugin in plugins.findall(NS + "plugin"):
+            if plugin.findtext(NS + "artifactId") == JAVADOC_PLUGIN:
+                found.append((EXECUTING, plugin))
     management = build.find(NS + "pluginManagement")
     if management is not None:
-        containers.append(management.find(NS + "plugins"))
-    for container in containers:
-        if container is None:
-            continue
-        for plugin in container.findall(NS + "plugin"):
-            if plugin.findtext(NS + "artifactId") == JAVADOC_PLUGIN:
-                found.append(plugin)
+        managed = management.find(NS + "plugins")
+        if managed is not None:
+            for plugin in managed.findall(NS + "plugin"):
+                if plugin.findtext(NS + "artifactId") == JAVADOC_PLUGIN:
+                    found.append((MANAGED, plugin))
     return found
 
 
+def pin_gaps(config):
+    """Which REQUIRED_PIN entries this <configuration> fails to set to the required value."""
+    gaps = []
+    for name, expected in REQUIRED_PIN.items():
+        element = config.find(NS + name)
+        actual = (element.text or "").strip().lower() if element is not None else None
+        if actual != expected:
+            gaps.append(f"<{name}> is {actual if actual is not None else 'unset'}, must be {expected}")
+    return gaps
+
+
+def _binds_javadoc_jar(plugin):
+    """True if some execution of this entry will actually run the `jar` goal.
+
+    `<phase>none</phase>` on an inherited execution id is Maven's documented idiom for unbinding it.
+    The plugin-level <configuration> — pin included — stays visible in the effective pom, so the
+    module reads as compliant while javadoc never runs for it and no javadoc jar is produced. A
+    pinned value that is never consulted proves nothing, which is the failure this file exists to
+    stop. An absent <phase> is normal: the goal's own default binding applies.
+    """
+    for execution in plugin.iter(NS + "execution"):
+        goals = [goal.text.strip() for goal in execution.iter(NS + "goal") if goal.text]
+        if "jar" not in goals:
+            continue
+        if (execution.findtext(NS + "phase") or "").strip().lower() != "none":
+            return True
+    return False
+
+
+def _is_pinned(plugin):
+    """True only if this entry pins the parameters for the plugin AND for every execution of it.
+
+    An execution's own <configuration> overrides the plugin-level one at run time, so
+    `<execution><configuration combine.self="override">` drops the inherited pin for that execution
+    while leaving the plugin-level pin visible in the effective pom. Verified: that shape ships
+    broken javadoc under -Dmaven.javadoc.failOnError=false while every other check stays green.
+    An execution with no <configuration> of its own simply inherits the plugin-level pin.
+    """
+    config = plugin.find(NS + "configuration")
+    if config is None or pin_gaps(config):
+        return False
+    for execution in plugin.iter(NS + "execution"):
+        exec_config = execution.find(NS + "configuration")
+        if exec_config is not None and pin_gaps(exec_config):
+            return False
+    return True
+
+
+class ProjectCheck(NamedTuple):
+    """Per-module result. Named because the checks keep growing and positional unpacking rots."""
+
+    artifact_id: str
+    executing_entries: int
+    findings: list
+    pinned: bool
+    bound: bool
+
+
 def check_project(project):
-    """(artifactId, javadoc_plugin_count, [(artifactId, where, reason)])."""
+    """Inspect one effective <project>; see ProjectCheck."""
     artifact_id = project.findtext(NS + "artifactId") or "<unknown>"
     findings = []
     plugins = javadoc_plugins(project)
+    executing = [plugin for where, plugin in plugins if where == EXECUTING]
 
-    for plugin in plugins:
+    # EVERY executing entry must carry the pin, and there must be at least one. "Any entry passes"
+    # would let an inert pluginManagement copy vouch for an executing entry that overrode it away.
+    pinned = bool(executing) and all(_is_pinned(plugin) for plugin in executing)
+
+    for where, plugin in plugins:
         config = plugin.find(NS + "configuration")
         if config is not None:
-            findings += [(artifact_id, "plugin configuration", r) for r in permissive_settings(config)]
+            findings += [
+                (artifact_id, f"{where} configuration", r) for r in permissive_settings(config)
+            ]
 
         # An execution-level <configuration> overrides the plugin-level one, so it silences errors
         # just as effectively and must be inspected too.
@@ -157,7 +251,10 @@ def check_project(project):
             if value is not None and not is_strict(value.strip()):
                 findings.append((artifact_id, "properties", f"<{name}>{value.strip()}</{name}>"))
 
-    return artifact_id, len(plugins), findings
+    # Count the EXECUTING entries: a module with only a pluginManagement copy never runs javadoc,
+    # which the "absent from <build>" guard should report rather than the vaguer "not pinned".
+    bound = bool(executing) and any(_binds_javadoc_jar(plugin) for plugin in executing)
+    return ProjectCheck(artifact_id, len(executing), findings, pinned, bound)
 
 
 def run_check(path, required):
@@ -177,14 +274,23 @@ def run_check(path, required):
 
     findings = []
     without_plugin = []
+    unpinned = []
+    unbound = []
     inspected = []
     for project in projects:
-        artifact_id, plugin_count, project_findings = check_project(project)
-        inspected.append(artifact_id)
-        findings += project_findings
-        if plugin_count == 0:
-            without_plugin.append(artifact_id)
-        print(f"  checked {artifact_id} ({plugin_count} javadoc-plugin entries)")
+        result = check_project(project)
+        inspected.append(result.artifact_id)
+        findings += result.findings
+        if result.executing_entries == 0:
+            without_plugin.append(result.artifact_id)
+        elif not result.pinned:
+            unpinned.append(result.artifact_id)
+        elif not result.bound:
+            unbound.append(result.artifact_id)
+        print(
+            f"  checked {result.artifact_id} ({result.executing_entries} javadoc-plugin entries,"
+            f" pinned={result.pinned}, jar-bound={result.bound})"
+        )
 
     print(f"inspected {len(projects)} modules: {', '.join(inspected)}")
 
@@ -208,12 +314,37 @@ def run_check(path, required):
         )
         return 1
 
+    # Report the precise silencer before the vaguer "not pinned". Changing the pin to a permissive
+    # value (say <doclint>none</doclint>) trips BOTH, and the specific diagnostic is the useful one.
     if findings:
         print("::error::javadoc strictness is silenced in the effective pom (#203):")
         for artifact_id, where, reason in findings:
             print(f"::error::  {artifact_id}: {where} sets {reason}")
         return 1
 
+    # Leaving the parameters at their strict DEFAULTS is not enough: a default is what a user
+    # property overrides, so an unpinned module can be silenced by a `-D` on any mvn command line
+    # without touching a single file in the repo (#205).
+    if unpinned:
+        expected = ", ".join(f"<{k}>{v}</{k}>" for k, v in REQUIRED_PIN.items())
+        print(
+            "::error::maven-javadoc-plugin is not pinned in: "
+            + ", ".join(unpinned)
+            + f" — the root pluginManagement <configuration> must set {expected}, otherwise"
+            " -Dmaven.javadoc.failOnError=false on any command line silences javadoc (#205)"
+        )
+        return 1
+
+    # A pin nothing consults proves nothing: an execution unbound with <phase>none</phase> keeps the
+    # config visible while javadoc never runs, so the module publishes no javadoc jar at all.
+    if unbound:
+        print(
+            "::error::the javadoc `jar` goal is not bound to a lifecycle phase in: "
+            + ", ".join(unbound)
+            + " — javadoc never runs for them, so the pin above is never consulted"
+        )
+        return 1
+
     print("javadoc strictness confirmed: no module weakens maven-javadoc-plugin")
     return 0
 
@@ -221,9 +352,13 @@ def run_check(path, required):
 # A guard that cannot fail is not a guard. If a future edit broke permissive_settings so it always
 # returned [], every real sweep would still print "confirmed" — #200's shape relocated into this
 # script. These fixtures make that regression loud, and cost no Maven invocation.
-_STRICT_FIXTURE = """<projects><project xmlns="http://maven.apache.org/POM/4.0.0">
+_PIN = "<configuration><failOnError>true</failOnError><skip>false</skip><doclint>all</doclint></configuration>"
+
+_STRICT_FIXTURE = f"""<projects><project xmlns="http://maven.apache.org/POM/4.0.0">
   <artifactId>fixture-strict</artifactId>
-  <build><plugins><plugin><artifactId>maven-javadoc-plugin</artifactId></plugin></plugins></build>
+  <build><plugins><plugin><artifactId>maven-javadoc-plugin</artifactId>
+    {_PIN}
+  </plugin></plugins></build>
 </project></projects>"""
 
 _PERMISSIVE_FIXTURES = {
@@ -262,14 +397,40 @@ def run_check(path, required):
 }
 
 
-def _fixture(plugin_body="", properties=""):
+# A pin that sets only some of the three is not a pin: the unset ones stay property-overridable.
+_PARTIAL_PIN_FIXTURES = {
+    "pin missing <skip> and <doclint>": "<configuration><failOnError>true</failOnError></configuration>",
+    "pin missing <doclint>": (
+        "<configuration><failOnError>true</failOnError><skip>false</skip></configuration>"
+    ),
+    "pin with wrong <doclint> value": (
+        "<configuration><failOnError>true</failOnError><skip>false</skip>"
+        "<doclint>all,-missing</doclint></configuration>"
+    ),
+}
+
+
+def _fixture(plugin_body="", properties="", managed_body=None):
+    """A one-module effective pom.
+
+    `managed_body` adds a coexisting <pluginManagement> entry — the shape EVERY real module has,
+    since the pin lives in the root pluginManagement and is inherited. Fixtures without it cannot
+    exercise the interaction that actually decides `pinned`.
+    """
     props = f"<properties>{properties}</properties>" if properties else ""
+    managed = ""
+    if managed_body is not None:
+        managed = (
+            "<pluginManagement><plugins><plugin>"
+            "<artifactId>maven-javadoc-plugin</artifactId>"
+            f"{managed_body}</plugin></plugins></pluginManagement>"
+        )
     return (
         '<projects><project xmlns="http://maven.apache.org/POM/4.0.0">'
         "<artifactId>fixture</artifactId>"
         f"{props}"
         "<build><plugins><plugin><artifactId>maven-javadoc-plugin</artifactId>"
-        f"{plugin_body}</plugin></plugins></build>"
+        f"{plugin_body}</plugin></plugins>{managed}</build>"
         "</project></projects>"
     )
 
@@ -279,18 +440,92 @@ def self_test():
     failures = 0
 
     strict = ET.fromstring(_STRICT_FIXTURE)
-    _, _, strict_findings = check_project(next(strict.iter(NS + "project")))
+    strict_result = check_project(next(strict.iter(NS + "project")))
+    strict_findings, strict_pinned = strict_result.findings, strict_result.pinned
     if strict_findings:
         print(f"::error::self-test: the strict fixture was flagged: {strict_findings}")
         failures += 1
+    elif not strict_pinned:
+        print("::error::self-test: the strict fixture was not recognised as pinned")
+        failures += 1
+    else:
+        print("  ok  strict fixture -> no findings, pinned")
+
+    # An unconfigured plugin is the pre-#205 state: strict by default, but silently overridable by
+    # -D. It must read as NOT pinned, or removing the pin would sail through.
+    bare_pinned = check_project(next(ET.fromstring(_fixture()).iter(NS + "project"))).pinned
+    if bare_pinned:
+        print("::error::self-test: an unconfigured plugin was reported as pinned")
+        failures += 1
     else:
-        print("  ok  strict fixture -> no findings")
+        print("  ok  unconfigured plugin -> not pinned")
+
+    # The regression that motivated scoping the pin to the EXECUTING entry: a module overrides its
+    # own <configuration combine.self="override">, dropping the inherited pin, while the inert
+    # pluginManagement copy still carries it. Verified against this repo — the sweep used to pass.
+    _EXEC_OVERRIDE = (
+        "<executions><execution><id>attach-javadocs</id>"
+        "<configuration><quiet>true</quiet></configuration></execution></executions>"
+    )
+    # The real shape: id attach-javadocs, goal jar, no explicit <phase> (default binding applies).
+    _EXEC_BOUND = (
+        "<executions><execution><id>attach-javadocs</id>"
+        "<goals><goal>jar</goal></goals></execution></executions>"
+    )
+    _EXEC_PHASE_NONE = (
+        "<executions><execution><id>attach-javadocs</id><phase>none</phase>"
+        "<goals><goal>jar</goal></goals></execution></executions>"
+    )
+    two_container = [
+        ("executing entry overrides the pin away", "<configuration><quiet>true</quiet></configuration>", _PIN, False),
+        ("executing entry keeps the pin", _PIN, _PIN, True),
+        ("only pluginManagement is pinned", "", _PIN, False),
+        # An execution config overrides the plugin-level one at run time, so a pinned plugin with an
+        # unpinned execution is NOT pinned — verified exploitable before this case existed.
+        ("execution overrides the pin away", _PIN + _EXEC_OVERRIDE, _PIN, False),
+        ("execution with no config of its own", _PIN + _EXEC_BOUND, _PIN, True),
+    ]
+
+    # <phase>none</phase> unbinds the execution: the pin stays visible but javadoc never runs, so a
+    # pinned-looking module publishes no javadoc at all.
+    bound_cases = [
+        ("jar goal bound to its default phase", _PIN + _EXEC_BOUND, True),
+        ("jar goal unbound with <phase>none</phase>", _PIN + _EXEC_PHASE_NONE, False),
+    ]
+    for name, body, expected in bound_cases:
+        actual = check_project(
+            next(ET.fromstring(_fixture(plugin_body=body, managed_body=_PIN)).iter(NS + "project"))
+        ).bound
+        if actual != expected:
+            print(f"::error::self-test: '{name}' reported bound={actual}, expected {expected}")
+            failures += 1
+        else:
+            print(f"  ok  {name} -> bound={actual}")
+    for name, body, managed, expected in two_container:
+        actual = check_project(
+            next(ET.fromstring(_fixture(plugin_body=body, managed_body=managed)).iter(NS + "project"))
+        ).pinned
+        if actual != expected:
+            print(f"::error::self-test: '{name}' reported pinned={actual}, expected {expected}")
+            failures += 1
+        else:
+            print(f"  ok  {name} -> pinned={actual}")
+
+    for name, partial in _PARTIAL_PIN_FIXTURES.items():
+        part_pinned = check_project(
+            next(ET.fromstring(_fixture(plugin_body=partial)).iter(NS + "project"))
+        ).pinned
+        if part_pinned:
+            print(f"::error::self-test: '{name}' was reported as pinned")
+            failures += 1
+        else:
+            print(f"  ok  {name} -> not pinned")
 
     cases = [(n, _fixture(plugin_body=b)) for n, b in _PERMISSIVE_FIXTURES.items()]
     cases += [(n, _fixture(properties=p)) for n, p in _PERMISSIVE_PROPERTY_FIXTURES.items()]
     for name, xml in cases:
         project = next(ET.fromstring(xml).iter(NS + "project"))
-        _, _, found = check_project(project)
+        found = check_project(project).findings
         if not found:
             print(f"::error::self-test: '{name}' was NOT detected — the checker is disarmed")
             failures += 1
@@ -303,15 +538,21 @@ def self_test():
     with tempfile.TemporaryDirectory() as tmp:
         strict_path = os.path.join(tmp, "strict.xml")
         permissive_path = os.path.join(tmp, "permissive.xml")
+        unpinned_path = os.path.join(tmp, "unpinned.xml")
         with open(strict_path, "w", encoding="utf-8") as handle:
-            handle.write(_fixture())
+            handle.write(_fixture(plugin_body=_PIN + _EXEC_BOUND))
         with open(permissive_path, "w", encoding="utf-8") as handle:
             handle.write(_fixture(plugin_body="<configuration><failOnError>false</failOnError></configuration>"))
+        # No permissive VALUE anywhere — just the pin deleted. This is the #205 regression, and the
+        # whole reason the pin must be required rather than merely tolerated.
+        with open(unpinned_path, "w", encoding="utf-8") as handle:
+            handle.write(_fixture())
 
         roundtrips = [
-            ("run_check: clean pom, --require satisfied", strict_path, ["fixture"], 0),
-            ("run_check: clean pom, --require missing a module", strict_path, ["absent-module"], 1),
+            ("run_check: pinned pom, --require satisfied", strict_path, ["fixture"], 0),
+            ("run_check: pinned pom, --require missing a module", strict_path, ["absent-module"], 1),
             ("run_check: permissive pom", permissive_path, [], 1),
+            ("run_check: pin deleted (#205 regression)", unpinned_path, [], 1),
             ("run_check: unreadable path", os.path.join(tmp, "nope.xml"), [], 1),
         ]
         for name, path, required, expected in roundtrips: