@@ -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
 
@@ -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);
 
@@ -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
 
@@ -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());