feat(maven-plugin): nudge to refresh agent-context when it predates the installed version

Port the agent-context staleness nudge (TS reference) to the JVM port — covers
Java AND Kotlin, since Kotlin codegen runs through the same Maven goals.

- Stamp the installed MetaObjects version into the agent-context manifest as
  "generatedBy" (same key as TS for cross-read in a polyglot repo). The version
  is resolved the idiomatic Maven way: read pom.properties for
  com.metaobjects:metaobjects-metadata off the classpath, "0.0.0" fallback.
- Add a pure, unit-testable AgentContextScaffold.staleness(manifest, current):
  no manifest -> null; generatedBy exactly equals current -> null (exact equality
  on purpose, never a semver compare); differs/absent -> a one-line advisory naming
  both versions and the Java refresh goal 'mvn metaobjects:agent-docs'.
- Wire an advisory check into gen + verify (AbstractMetaDataMojo.execute and the
  verify override) reading .metaobjects/.agent-context.json under the project
  basedir. Advisory only: never throws, never fails the build, never writes; a
  missing/corrupt manifest is silently ignored.

The manifest is not part of the byte-gated assembled file set, so adding
"generatedBy" leaves AgentContextConformanceTest unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

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

@@ -1,6 +1,9 @@
 package com.metaobjects.mojo;
 
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
 import com.metaobjects.MetaDataException;
+import com.metaobjects.agentcontext.AgentContextScaffold;
 import com.metaobjects.generator.Generator;
 import com.metaobjects.loader.LoaderConfigurable;
 import com.metaobjects.loader.LoaderOptions;
@@ -17,8 +20,12 @@
 import java.lang.reflect.InvocationTargetException;
 import java.net.URL;
 import java.net.URLClassLoader;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 
@@ -73,6 +80,8 @@ public void execute() throws MojoExecutionException, MojoFailureException
         if ( getLoader() == null ) {
             throw new MojoExecutionException( "No <loader> element was defined");
         }
+        warnIfAgentContextStale();
+
         ClassLoader projectClassLoader = createProjectClassLoader();
 
         MetaDataLoader loader = createLoader(projectClassLoader);
@@ -154,6 +163,43 @@ public Map<String, String> mergeAndOverwriteArgs(GeneratorParam g) {
         return allargs;
     }
 
+    /**
+     * Advisory nudge: if the consumer's copied-in agent context
+     * ({@code .metaobjects/.agent-context.json} under the project basedir) was scaffolded
+     * by a different MetaObjects version than the one running, print ONE warning line
+     * suggesting {@code mvn metaobjects:agent-docs}.
+     *
+     * <p>Strictly advisory — never throws, never fails the build, never writes. A missing
+     * or corrupt manifest is silently ignored (no agent context here → nothing to say).
+     */
+    protected void warnIfAgentContextStale() {
+        try {
+            File basedir = project != null ? project.getBasedir() : null;
+            Path cwd = basedir != null ? basedir.toPath()
+                    : Path.of(System.getProperty("user.dir"));
+            Path manifestPath = cwd.resolve(AgentContextScaffold.MANIFEST_PATH);
+            if (!Files.isRegularFile(manifestPath)) {
+                return; // no agent context scaffolded here → nothing to nudge
+            }
+            JsonObject obj = JsonParser.parseString(
+                    new String(Files.readAllBytes(manifestPath), StandardCharsets.UTF_8))
+                    .getAsJsonObject();
+            int version = obj.has("version") ? obj.get("version").getAsInt() : 1;
+            String generatedBy = obj.has("generatedBy") && obj.get("generatedBy").isJsonPrimitive()
+                    ? obj.get("generatedBy").getAsString() : null;
+            AgentContextScaffold.Manifest manifest = new AgentContextScaffold.Manifest(
+                    version, generatedBy, new ArrayList<>(), new ArrayList<>(),
+                    new LinkedHashMap<>());
+            String nudge = AgentContextScaffold.staleness(
+                    manifest, AgentContextScaffold.installedVersion());
+            if (nudge != null) {
+                getLog().warn(nudge);
+            }
+        } catch (Exception ignored) {
+            // Advisory only — any failure to read/parse the manifest is silently ignored.
+        }
+    }
+
     protected abstract void executeGenerators(MetaDataLoader loader, List<Generator> generatorImpls);
 
     protected MetaDataLoader createLoader(ClassLoader projectClassLoader) {

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

@@ -98,8 +98,9 @@ public void execute() throws MojoExecutionException {
         Path manifestPath = outDir.resolve(AgentContextScaffold.MANIFEST_PATH);
         AgentContextScaffold.Manifest prior = readPriorManifest(manifestPath);
 
-        AgentContextScaffold.ScaffoldDecision decision =
-                AgentContextScaffold.plan(stack, assembled, prior, rel -> readCurrent(outDir, rel));
+        AgentContextScaffold.ScaffoldDecision decision = AgentContextScaffold.plan(
+                stack, assembled, prior, rel -> readCurrent(outDir, rel),
+                AgentContextScaffold.installedVersion());
 
         try {
             for (AgentContextScaffold.Write w : decision.writes()) {
@@ -156,7 +157,9 @@ private static AgentContextScaffold.Manifest parseManifest(JsonObject obj) {
         List<String> srv = jsonStrings(obj, "servers");
         List<String> cli = jsonStrings(obj, "clients");
         int version = obj.has("version") ? obj.get("version").getAsInt() : 1;
-        return new AgentContextScaffold.Manifest(version, srv, cli, files);
+        String generatedBy = obj.has("generatedBy") && obj.get("generatedBy").isJsonPrimitive()
+                ? obj.get("generatedBy").getAsString() : null;
+        return new AgentContextScaffold.Manifest(version, generatedBy, srv, cli, files);
     }
 
     private static List<String> jsonStrings(JsonObject obj, String key) {
@@ -186,9 +189,12 @@ private static void writeFile(Path dest, String contents) throws IOException {
 
     private void writeManifest(Path manifestPath, AgentContextScaffold.Manifest manifest)
             throws IOException {
-        // Build an ordered JSON object: version, servers, clients, files.
+        // Build an ordered JSON object: version, generatedBy, servers, clients, files.
         Map<String, Object> doc = new LinkedHashMap<>();
         doc.put("version", manifest.version());
+        if (manifest.generatedBy() != null) {
+            doc.put("generatedBy", manifest.generatedBy());
+        }
         doc.put("servers", manifest.servers());
         doc.put("clients", manifest.clients());
         doc.put("files", manifest.files());

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

@@ -107,6 +107,7 @@ public void execute() throws MojoExecutionException, MojoFailureException {
         if (getLoader() == null) {
             throw new MojoExecutionException("No <loader> element was defined");
         }
+        warnIfAgentContextStale();
 
         String m = mode == null ? MODE_CODEGEN : mode.trim();
         if (MODE_TEMPLATES.equalsIgnoreCase(m)) {

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

@@ -1,12 +1,14 @@
 package com.metaobjects.agentcontext;
 
+import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Properties;
 import java.util.function.Function;
 
 /**
@@ -26,6 +28,19 @@ public final class AgentContextScaffold {
     /** Consumer-relative path of the sidecar manifest that tracks scaffolded files. */
     public static final String MANIFEST_PATH = ".metaobjects/.agent-context.json";
 
+    /**
+     * Safe fallback when the installed version can't be resolved from the classpath
+     * (mirrors the TS reference's {@code "0.0.0"} fallback). Compares unequal to any
+     * real stamped version, so a real {@code generatedBy} always wins the equality
+     * check — the nudge stays advisory, never spuriously asserting "in sync".
+     */
+    public static final String UNKNOWN_VERSION = "0.0.0";
+
+    /** Maven group of the artifact carrying this class — used to find {@code pom.properties}. */
+    private static final String MAVEN_GROUP_ID = "com.metaobjects";
+    /** Maven artifact carrying this class — used to find {@code pom.properties}. */
+    private static final String MAVEN_ARTIFACT_ID = "metaobjects-metadata";
+
     private AgentContextScaffold() {
     }
 
@@ -37,9 +52,19 @@ public record Write(String path, String contents) {
     public record Conflict(String path, String newPath, String contents) {
     }
 
-    /** Tracks what the assembler last wrote, so re-runs can detect hand-edits. */
-    public record Manifest(int version, List<String> servers, List<String> clients,
-                           Map<String, String> files) {
+    /**
+     * Tracks what the assembler last wrote, so re-runs can detect hand-edits.
+     *
+     * <p>{@code generatedBy} is the MetaObjects version that last scaffolded this agent
+     * context. It is stamped so {@code gen}/{@code verify} can nudge a re-scaffold when
+     * the installed version moves ahead (the skills/docs ship with the artifact, so an
+     * upgrade can leave the copied-in context stale). It may be {@code null} for
+     * back-compat with manifests written before version tracking existed (and for
+     * cross-read manifests written by another port). Serialized as {@code "generatedBy"}
+     * — the SAME key as the TS reference — so a polyglot repo can cross-read it.
+     */
+    public record Manifest(int version, String generatedBy, List<String> servers,
+                           List<String> clients, Map<String, String> files) {
     }
 
     /** The outcome of planning a (re-)scaffold. */
@@ -73,11 +98,14 @@ public static String hashContents(String s) {
      * @param prior       the prior manifest, or {@code null} for a fresh scaffold.
      * @param readCurrent reads the on-disk contents of a consumer-relative path, or
      *                    {@code null} if absent.
+     * @param generatedBy the installed MetaObjects version doing the scaffold — stamped
+     *                    into the manifest so later runs can nudge a stale re-scaffold.
      * @return the scaffold decision (writes, conflicts, manifest, removed).
      */
     public static ScaffoldDecision plan(Stack stack, List<AssembledFile> assembled,
                                         Manifest prior,
-                                        Function<String, String> readCurrent) {
+                                        Function<String, String> readCurrent,
+                                        String generatedBy) {
         List<Write> writes = new ArrayList<>();
         List<Conflict> conflicts = new ArrayList<>();
         Map<String, String> files = new LinkedHashMap<>();
@@ -112,9 +140,64 @@ public static ScaffoldDecision plan(Stack stack, List<AssembledFile> assembled,
 
         Manifest manifest = new Manifest(
                 1,
+                generatedBy,
                 List.copyOf(stack.servers()),
                 List.copyOf(stack.clients()),
                 files);
         return new ScaffoldDecision(writes, conflicts, manifest, removed);
     }
+
+    /**
+     * A one-line nudge if the scaffolded agent context predates the installed MetaObjects
+     * (so {@code gen}/{@code verify} can remind the user to refresh the skills after an
+     * upgrade), or {@code null} when there is nothing to say — no agent context
+     * scaffolded, or it is in sync.
+     *
+     * <p>Pure + advisory: never throws, never blocks, never writes. Direct port of the TS
+     * {@code agentContextStaleness}. The equality check is EXACT on purpose — any drift
+     * (including a prerelease/build-metadata difference) nudges, because a re-scaffold is
+     * cheap + idempotent. Don't "fix" this into a semver compare.
+     *
+     * @param manifest       the parsed prior manifest, or {@code null} if none on disk.
+     * @param currentVersion the installed MetaObjects version (see {@link #installedVersion()}).
+     * @return the nudge message, or {@code null} when nothing needs saying.
+     */
+    public static String staleness(Manifest manifest, String currentVersion) {
+        if (manifest == null) {
+            return null; // no agent context here → nothing to nudge
+        }
+        if (currentVersion.equals(manifest.generatedBy())) {
+            return null; // in sync
+        }
+        String from = manifest.generatedBy() != null ? manifest.generatedBy() : "an older MetaObjects";
+        return "MetaObjects agent context was generated by " + from + "; you're on "
+                + currentVersion + ". Re-run 'mvn metaobjects:agent-docs' to refresh "
+                + "the .claude/skills docs.";
+    }
+
+    /**
+     * The installed MetaObjects version, resolved the idiomatic Maven way: read
+     * {@code /META-INF/maven/com.metaobjects/metaobjects-metadata/pom.properties} from the
+     * classpath (Maven stamps this into the built jar). Falls back to
+     * {@link #UNKNOWN_VERSION} when it can't be resolved (e.g. running from an exploded
+     * classes dir in a test/IDE) — mirroring the TS reference's {@code "0.0.0"} fallback.
+     * Never throws.
+     *
+     * @return the installed version, or {@link #UNKNOWN_VERSION}.
+     */
+    public static String installedVersion() {
+        String resource = "/META-INF/maven/" + MAVEN_GROUP_ID + "/" + MAVEN_ARTIFACT_ID
+                + "/pom.properties";
+        try (InputStream in = AgentContextScaffold.class.getResourceAsStream(resource)) {
+            if (in == null) {
+                return UNKNOWN_VERSION;
+            }
+            Properties props = new Properties();
+            props.load(in);
+            String v = props.getProperty("version");
+            return (v == null || v.isBlank()) ? UNKNOWN_VERSION : v.trim();
+        } catch (Exception e) {
+            return UNKNOWN_VERSION;
+        }
+    }
 }

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

@@ -27,7 +27,7 @@ private static List<AssembledFile> assembled() {
     @Test
     public void absentFilesAreWrittenFresh() {
         AgentContextScaffold.ScaffoldDecision d =
-                AgentContextScaffold.plan(STACK, assembled(), null, rel -> null);
+                AgentContextScaffold.plan(STACK, assembled(), null, rel -> null, "9.9.9");
         assertEquals(2, d.writes().size());
         assertTrue(d.conflicts().isEmpty());
         assertTrue(d.removed().isEmpty());
@@ -36,28 +36,35 @@ public void absentFilesAreWrittenFresh() {
                 d.manifest().files().get(".metaobjects/AGENTS.md"));
     }
 
+    @Test
+    public void manifestRecordsGeneratedBy() {
+        AgentContextScaffold.ScaffoldDecision d =
+                AgentContextScaffold.plan(STACK, assembled(), null, rel -> null, "9.9.9");
+        assertEquals("9.9.9", d.manifest().generatedBy());
+    }
+
     @Test
     public void unmodifiedSinceManifestIsRefreshed() {
         AgentContextScaffold.Manifest prior = new AgentContextScaffold.Manifest(
-                1, List.of("java"), List.of("react"),
+                1, "1.0.0", List.of("java"), List.of("react"),
                 Map.of(".metaobjects/AGENTS.md", AgentContextScaffold.hashContents("alpha")));
         // On disk still holds the prior-recorded contents → safe to overwrite.
         AgentContextScaffold.ScaffoldDecision d = AgentContextScaffold.plan(
                 STACK, assembled(), prior,
-                rel -> rel.equals(".metaobjects/AGENTS.md") ? "alpha" : null);
+                rel -> rel.equals(".metaobjects/AGENTS.md") ? "alpha" : null, "9.9.9");
         assertEquals(2, d.writes().size());
         assertTrue(d.conflicts().isEmpty());
     }
 
     @Test
     public void handEditedFileBecomesConflict() {
         AgentContextScaffold.Manifest prior = new AgentContextScaffold.Manifest(
-                1, List.of("java"), List.of("react"),
+                1, "1.0.0", List.of("java"), List.of("react"),
                 Map.of(".metaobjects/AGENTS.md", AgentContextScaffold.hashContents("alpha")));
         // On disk differs from the recorded hash → preserve it, emit a .new.
         AgentContextScaffold.ScaffoldDecision d = AgentContextScaffold.plan(
                 STACK, assembled(), prior,
-                rel -> rel.equals(".metaobjects/AGENTS.md") ? "USER EDIT" : null);
+                rel -> rel.equals(".metaobjects/AGENTS.md") ? "USER EDIT" : null, "9.9.9");
         assertEquals(1, d.writes().size());
         assertEquals(1, d.conflicts().size());
         assertEquals(".metaobjects/AGENTS.md.new", d.conflicts().get(0).newPath());
@@ -66,10 +73,10 @@ STACK, assembled(), prior,
     @Test
     public void priorPathNoLongerAssembledIsReportedRemoved() {
         AgentContextScaffold.Manifest prior = new AgentContextScaffold.Manifest(
-                1, List.of("java"), List.of("react"),
+                1, "1.0.0", List.of("java"), List.of("react"),
                 Map.of(".claude/skills/gone/SKILL.md", "deadbeef"));
         AgentContextScaffold.ScaffoldDecision d =
-                AgentContextScaffold.plan(STACK, assembled(), prior, rel -> null);
+                AgentContextScaffold.plan(STACK, assembled(), prior, rel -> null, "9.9.9");
         assertEquals(List.of(".claude/skills/gone/SKILL.md"), d.removed());
     }
 }

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

@@ -0,0 +1,64 @@
+package com.metaobjects.agentcontext;
+
+import org.junit.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * Unit coverage for the pure agent-context staleness decision — mirrors the TS
+ * reference {@code agentContextStaleness}
+ * ({@code server/typescript/packages/sdk/src/agent-context/scaffold.ts}):
+ *
+ * <ul>
+ *   <li>no manifest → {@code null} (nothing scaffolded here, nothing to nudge);</li>
+ *   <li>{@code generatedBy} EQUALS current → {@code null} (in sync; exact-equality
+ *       on purpose, NOT a semver compare — any drift nudges);</li>
+ *   <li>{@code generatedBy} DIFFERS → a one-line nudge naming both versions and the
+ *       Java refresh goal {@code mvn metaobjects:agent-docs};</li>
+ *   <li>{@code generatedBy} ABSENT (legacy manifest) → a nudge with "an older
+ *       MetaObjects" as the from-version.</li>
+ * </ul>
+ *
+ * <p>Advisory only — the production method never throws and never blocks.
+ */
+public class AgentContextStalenessTest {
+
+    private static AgentContextScaffold.Manifest manifest(String generatedBy) {
+        return new AgentContextScaffold.Manifest(
+                1, generatedBy, List.of("java"), List.of("react"), Map.of());
+    }
+
+    @Test
+    public void noManifestIsNull() {
+        assertNull(AgentContextScaffold.staleness(null, "7.2.1"));
+    }
+
+    @Test
+    public void inSyncIsNull() {
+        assertNull(AgentContextScaffold.staleness(manifest("7.2.1"), "7.2.1"));
+    }
+
+    @Test
+    public void differingVersionNudgesNamingBoth() {
+        String msg = AgentContextScaffold.staleness(manifest("7.1.0"), "7.2.1");
+        assertEquals(
+                "MetaObjects agent context was generated by 7.1.0; you're on 7.2.1. "
+                        + "Re-run 'mvn metaobjects:agent-docs' to refresh the .claude/skills docs.",
+                msg);
+    }
+
+    @Test
+    public void absentGeneratedByNudgesAsOlder() {
+        String msg = AgentContextScaffold.staleness(manifest(null), "7.2.1");
+        assertTrue("should name the current version", msg.contains("7.2.1"));
+        assertTrue("should describe an older MetaObjects",
+                msg.contains("an older MetaObjects"));
+        assertTrue("should name the agent-docs refresh goal",
+                msg.contains("mvn metaobjects:agent-docs"));
+    }
+}