fix(java): the agent-context staleness nudge compared two version lines, so it fired forever (#347)

meta agent-docs COPIES the agent-instruction files into a consuming repo; it does not
link. The copy freezes at whatever version wrote it and a dependency bump never touches
it, so an agent reads old instructions and authors vocabulary the current loader rejects.
The staleness advisory exists to break that silence.

On the JVM it could never fire correctly. generatedBy is always an NPM version, because
meta agent-docs is the canonical scaffolder for every port and the others redirect to it.
installedVersion() reads the MAVEN artifact version, which carries a historical major of 7
by design. The comparison is exact equality -- deliberately, so prerelease drift still
nudges -- so "7.24.1".equals("0.24.1") was false and always would be. The nudge fired on
every mvn metaobjects:generate forever, including when the context was perfectly in sync.
Not silent: permanently loud, which carries the same signal and is tuned out faster.

C# and Python were never affected; both read a version on the 0.x line. Java and Kotlin
are the broken pair, and only because the Maven major is deliberately different. This is
the two-version-lines contract biting somewhere nobody looked.

The fix is in the COORDINATE, not the comparison. stalenessAcrossVersionLines reduces both
sides to the release they name and keeps the equality EXACT, so every property the original
contract defends survives -- an RC-scaffolded context against a final release still nudges,
and the message still names both real versions. staleness() is untouched; its javadoc
forbids relaxing it into a semver compare and is right.

Correct while the four registries share a minor.patch. That is the documented lockstep rule
and is already relied on by scripts/prerelease.mjs:210 and scripts/release-verify.mjs:27,
which both build the Maven version as `7.` + npm's remainder -- so this reuses a convention
rather than inventing one, and is a third site for it rather than a first. It is a
convention and not a gate; if lockstep ever breaks this reports in-sync across a real gap.
That trade is accepted and stated in the javadoc, because it is strictly better than a
check that can never match.

Why it survived: every existing test used a generatedBy of "7.2.1" -- a shape production
CANNOT produce, since only the Node CLI writes that field. The fixtures asserted a world
where both operands sat on the Maven line, so the pure function looked correct while the
deployed comparison was never exercised once. Six cases now use the real shape, including
the in-sync case that is the whole point.

Option A of four, chosen after a two-arm adjudication that converged independently on it.
Rejected: comparing metamodelVersion instead -- it is identical across ports by
construction, but 91 commits touched agent-context/skills/ in 90 days against 5 distinct
values of that constant in the project's whole history, so its blind spot is dominant
rather than marginal. Rejected: stamping every port's line into the manifest -- the Node
scaffolder cannot know a consumer's Maven version. Rejected: a content digest -- the
manifest does carry per-file hashes, but they exist to detect hand-edits, and the JVM
ships no skill content at all, so the port with the bug cannot compute the current side.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NynrRND6ZUwGvq3ZUTCfxG

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,44 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — the JVM agent-context staleness nudge compared two different version lines, so it fired forever ([#347](https://github.com/metaobjectsdev/metaobjects/issues/347))
+
+`meta agent-docs` **copies** the agent-instruction files into a consuming repo; it does not
+link. So the copy freezes at whatever version wrote it and a dependency bump never touches it —
+an agent then reads old instructions and authors vocabulary the current loader rejects. A
+staleness advisory exists in all four ports to break that silence, and on `gen`/`verify` it
+compares the version that scaffolded the context against the installed one.
+
+**On the JVM those are two different version lines and can never be equal.** `generatedBy` is
+always an **npm** version, because `meta agent-docs` is the canonical scaffolder for every port
+and the others redirect to it. `AgentContextScaffold.installedVersion()` reads the **Maven**
+artifact version, which carries a historical major of `7` by design. The comparison is exact
+equality — deliberately, so prerelease drift still nudges — so `"7.24.1".equals("0.24.1")` was
+false and always would be. The nudge fired on **every `mvn metaobjects:generate`, in
+perpetuity, including when the context was perfectly in sync.** Not silent: permanently loud,
+which carries the same amount of signal and gets tuned out faster.
+
+C# and Python were never affected — both read a version on the `0.x` line. **Java and Kotlin
+are the broken pair**, and only because the Maven major is deliberately different.
+
+**The fix is in the coordinate, not the comparison.** `stalenessAcrossVersionLines` reduces both
+sides to the release they name (`7.24.1` and `0.24.1` both → `24.1`) and keeps the equality
+EXACT, so every property the original contract defends survives — an RC-scaffolded context
+against a final release still nudges. The message still names both real versions. The plain
+`staleness` is untouched; its javadoc forbids relaxing it into a semver compare and is right.
+
+Correct while the four registries share a `minor.patch` — the documented lockstep rule, already
+relied on by `scripts/prerelease.mjs` and `scripts/release-verify.mjs`, which both build the
+Maven version as `7.` + npm's remainder. It is a convention rather than a gate, and that is the
+accepted trade: reporting in-sync across a hypothetical future gap is strictly better than a
+check that can never match.
+
+**Why it survived:** the existing tests used a `generatedBy` of `"7.2.1"` — a **shape production
+cannot produce**, since only the Node CLI writes that field. The fixture asserted a world where
+both operands were on the Maven line, so the pure function looked correct and the deployed
+comparison was never exercised. Six regression cases now use the real shape.
+
+
 ### Added — a retired capability gets its status back: `@status: retired` (FR-039)
 
 `@status` gains a fourth member, **`retired`**, and `@supersededBy` is registered again — this

server/java/maven-plugin/src/main/java/com/metaobjects/mojo/AbstractMetaDataMojo.java

@@ -221,7 +221,10 @@ protected void warnIfAgentContextStale() {
             AgentContextScaffold.Manifest manifest = new AgentContextScaffold.Manifest(
                     version, generatedBy, new ArrayList<>(), new ArrayList<>(),
                     new LinkedHashMap<>());
-            String nudge = AgentContextScaffold.staleness(
+            // ACROSS VERSION LINES on purpose: the manifest is stamped by the Node CLI with an
+            // npm version (0.24.1) while installedVersion() is the Maven one (7.24.1), so plain
+            // equality never matched and this nudged on every build forever. See the javadoc.
+            String nudge = AgentContextScaffold.stalenessAcrossVersionLines(
                     manifest, AgentContextScaffold.installedVersion());
             if (nudge != null) {
                 getLog().warn(nudge);

server/java/metadata/src/main/java/com/metaobjects/agentcontext/AgentContextScaffold.java

@@ -77,6 +77,65 @@ public static String staleness(Manifest manifest, String currentVersion) {
                 + "the .claude/skills docs.";
     }
 
+    /**
+     * The comparable coordinate of a version — everything after the leading major.
+     *
+     * <p>{@code "7.24.1"} and {@code "0.24.1"} both yield {@code "24.1"}. Returns the input
+     * unchanged when there is no {@code '.'}, so a malformed or sentinel value never becomes
+     * something that accidentally matches.
+     */
+    static String releaseCoordinate(String version) {
+        if (version == null) {
+            return null;
+        }
+        int dot = version.indexOf('.');
+        return dot < 0 ? version : version.substring(dot + 1);
+    }
+
+    /**
+     * {@link #staleness} for a consumer whose installed version sits on a DIFFERENT VERSION
+     * LINE from the one that stamped the manifest.
+     *
+     * <p>This exists because of a fact peculiar to the JVM. The manifest is always stamped by
+     * the Node CLI — {@code meta agent-docs} is the canonical scaffolder for every port and the
+     * others redirect to it — so {@code generatedBy} is always an npm version ({@code 0.24.1}).
+     * The JVM's {@link #installedVersion()} reads the Maven artifact version ({@code 7.24.1}),
+     * which carries a historical major of {@code 7} by design. Exact equality between those two
+     * is false and always will be, so the plain {@link #staleness} nudged on EVERY build, in
+     * perpetuity, including when the context was perfectly in sync. An advisory that cries wolf
+     * in the inner loop gets tuned out, and then it is not there for the upgrade it exists for.
+     *
+     * <p>The fix is in the COORDINATE, not in the comparison: both sides are reduced to the
+     * release they name and the equality stays EXACT, so every property {@link #staleness}'s
+     * contract defends — prerelease and build-metadata drift still nudging — is preserved. Do
+     * not instead relax {@link #staleness} into a semver compare; its javadoc forbids that, and
+     * it is right.
+     *
+     * <p>Correct while the four registries share a {@code minor.patch}, which is the documented
+     * lockstep rule and is already relied on by the release tooling
+     * ({@code scripts/prerelease.mjs} and {@code scripts/release-verify.mjs} both construct the
+     * Maven version as {@code 7.} + npm's remainder). It is a CONVENTION rather than a gate: if
+     * lockstep ever breaks, this reports in-sync across a real gap. That is the accepted trade,
+     * and it is strictly better than a check that can never match.
+     *
+     * @param manifest       the parsed prior manifest, or {@code null} if none on disk.
+     * @param currentVersion the installed version, on this port's own line.
+     * @return the nudge message naming BOTH real versions, or {@code null} when in sync.
+     */
+    public static String stalenessAcrossVersionLines(Manifest manifest, String currentVersion) {
+        if (manifest == null) {
+            return null;
+        }
+        String stamped = releaseCoordinate(manifest.generatedBy());
+        // A null/absent generatedBy is legacy and must still nudge — delegate, which says so.
+        if (stamped != null && stamped.equals(releaseCoordinate(currentVersion))) {
+            return null;
+        }
+        // Message construction lives in ONE place; this only decides whether to ask for it.
+        // The delegate cannot return null here: the coordinates differ, so the versions do.
+        return staleness(manifest, currentVersion);
+    }
+
     /**
      * The installed MetaObjects version, resolved the idiomatic Maven way: read
      * {@code /META-INF/maven/com.metaobjects/metaobjects-metadata/pom.properties} from the

server/java/metadata/src/test/java/com/metaobjects/agentcontext/AgentContextStalenessTest.java

@@ -6,6 +6,7 @@
 import java.util.Map;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
 
@@ -28,6 +29,58 @@
  */
 public class AgentContextStalenessTest {
 
+    // ---- across version lines (the JVM's actual situation) ---------------------
+    //
+    // Every fixture ABOVE uses a `7.x` generatedBy, and that shape CANNOT OCCUR: the manifest
+    // is written only by the Node CLI, which stamps an npm version. Those cases pin the pure
+    // function's contract and are correct as such — but they are also why nobody noticed that
+    // the JVM was comparing `7.24.1` against `0.24.1` on every build and nudging forever.
+    // These cases use the shape production actually produces.
+
+    @Test
+    public void sameRelease_acrossLines_isNotStale() {
+        assertNull("npm-stamped 0.24.1 vs Maven 7.24.1 is the SAME release — must not nudge",
+                AgentContextScaffold.stalenessAcrossVersionLines(manifest("0.24.1"), "7.24.1"));
+    }
+
+    @Test
+    public void differentRelease_acrossLines_nudgesNamingBothRealVersions() {
+        String msg = AgentContextScaffold.stalenessAcrossVersionLines(manifest("0.23.1"), "7.24.1");
+        assertNotNull("a real release gap must still nudge", msg);
+        // The message names the REAL versions, not the stripped coordinates — a reader has to
+        // recognise what is installed and what is on disk.
+        assertTrue("should name the stamped version", msg.contains("0.23.1"));
+        assertTrue("should name the installed version", msg.contains("7.24.1"));
+    }
+
+    @Test
+    public void prereleaseDrift_acrossLines_stillNudges() {
+        // The pure contract's exact-equality property survives the coordinate reduction:
+        // 24.1-rc.1 != 24.1, so an RC-scaffolded context against a final release still nudges.
+        assertNotNull(AgentContextScaffold.stalenessAcrossVersionLines(
+                manifest("0.24.1-rc.1"), "7.24.1"));
+    }
+
+    @Test
+    public void absentGeneratedBy_acrossLines_stillNudges() {
+        assertNotNull("a legacy manifest with no stamp must not read as in-sync",
+                AgentContextScaffold.stalenessAcrossVersionLines(manifest(null), "7.24.1"));
+    }
+
+    @Test
+    public void nullManifest_acrossLines_isNotStale() {
+        assertNull(AgentContextScaffold.stalenessAcrossVersionLines(null, "7.24.1"));
+    }
+
+    @Test
+    public void releaseCoordinate_stripsOnlyTheLeadingMajor() {
+        assertEquals("24.1", AgentContextScaffold.releaseCoordinate("7.24.1"));
+        assertEquals("24.1", AgentContextScaffold.releaseCoordinate("0.24.1"));
+        assertEquals("24.1-rc.1", AgentContextScaffold.releaseCoordinate("0.24.1-rc.1"));
+        // No dot: returned unchanged, so a sentinel cannot accidentally match a real version.
+        assertEquals("unknown", AgentContextScaffold.releaseCoordinate("unknown"));
+    }
+
     private static AgentContextScaffold.Manifest manifest(String generatedBy) {
         return new AgentContextScaffold.Manifest(
                 1, generatedBy, List.of("java"), List.of("react"), Map.of());