feat(csharp): port agent-context staleness nudge to the .NET CLI

dmealing · claude · dmealing · commit dc24abc58d4d · 2026-06-06T12:26:09.000-04:00
When an adopter upgrades MetaObjects but doesn't re-scaffold the copied-in
.claude/skills agent context, `dotnet meta gen`/`verify` now print ONE
advisory line nudging a re-scaffold. Mirrors the TS reference.

- Stamp `generatedBy` (the installed assembly's InformationalVersion, with a
  "0.0.0" fallback) into the .metaobjects/.agent-context.json manifest when
  agent-docs writes it. Same JSON key as the other ports so a polyglot repo
  can cross-read the stamp; UnsafeRelaxedJsonEscaping encoder unchanged.
- Pure, unit-testable AgentContextScaffold.AgentContextStaleness(manifest,
  current): null manifest -&gt; null; exact-equal version -&gt; null (any drift
  nudges, no semver parsing); otherwise a one-line message naming both
  versions + 'dotnet meta agent-docs'.
- Wire the check into gen + verify (AgentContextStalenessCheck.WarnIfStale):
  read the cwd manifest if present and write the message to stderr. Advisory
  only — never throws, never changes the exit code; missing/corrupt manifest
  is silently ignored.

The manifest is not part of the byte-gated assembled file set, so the
agent-context conformance gate is unaffected (4/4 still green).

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/server/csharp/MetaObjects.Cli.Tests/AgentContextStalenessTests.cs b/server/csharp/MetaObjects.Cli.Tests/AgentContextStalenessTests.cs
@@ -0,0 +1,112 @@
+// AgentContextStalenessTests — the staleness-nudge feature (port of the TS
+// agent-context-staleness wiring).
+//
+// Three things are exercised:
+//   1. The stamp — `dotnet meta agent-docs` writes a `generatedBy` into the manifest.
+//   2. The pure decision — AgentContextScaffold.AgentContextStaleness(manifest, current):
+//        null manifest                 -> null (no agent context here)
+//        manifest.GeneratedBy == cur   -> null (in sync; exact equality on purpose)
+//        differs / null GeneratedBy    -> a one-line nudge naming both versions + agent-docs
+//   3. The version source — the installed-assembly version is read, never hardcoded.
+
+using System.Text.Json;
+using MetaObjects.AgentContext;
+using MetaObjects.Cli;
+using Xunit;
+
+namespace MetaObjects.Cli.Tests;
+
+public sealed class AgentContextStalenessTests
+{
+    // ---- 1. the stamp -------------------------------------------------------
+
+    [Fact]
+    public void AgentDocs_stamps_generatedBy_into_the_manifest()
+    {
+        var tmp = Path.Combine(Path.GetTempPath(), "meta-stale-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(tmp);
+        try
+        {
+            // A *.csproj triggers the csharp-server stack auto-detection.
+            File.WriteAllText(Path.Combine(tmp, "App.csproj"), "<Project />");
+
+            var exit = AgentDocsCommand.Run(new[] { "--out", tmp });
+            Assert.Equal(0, exit);
+
+            var manifestPath = Path.Combine(tmp, AgentContextScaffold.ManifestPath);
+            Assert.True(File.Exists(manifestPath), "manifest was not written");
+
+            using var doc = JsonDocument.Parse(File.ReadAllText(manifestPath));
+            Assert.True(doc.RootElement.TryGetProperty("generatedBy", out var gb),
+                "manifest is missing the generatedBy property");
+            var stamped = gb.GetString();
+            Assert.False(string.IsNullOrEmpty(stamped));
+            // It must be the live installed version, not a literal.
+            Assert.Equal(AgentContextStalenessCheck.CurrentVersion(), stamped);
+        }
+        finally
+        {
+            try { Directory.Delete(tmp, recursive: true); } catch { }
+        }
+    }
+
+    // ---- 2. the pure decision ----------------------------------------------
+
+    [Fact]
+    public void Null_manifest_is_not_stale()
+    {
+        Assert.Null(AgentContextScaffold.AgentContextStaleness(null, "1.2.3"));
+    }
+
+    [Fact]
+    public void Matching_generatedBy_is_not_stale()
+    {
+        var m = ManifestWith("1.2.3");
+        Assert.Null(AgentContextScaffold.AgentContextStaleness(m, "1.2.3"));
+    }
+
+    [Fact]
+    public void Differing_generatedBy_nudges_naming_both_versions()
+    {
+        var m = ManifestWith("1.0.0");
+        var msg = AgentContextScaffold.AgentContextStaleness(m, "2.0.0");
+        Assert.NotNull(msg);
+        Assert.Contains("1.0.0", msg);
+        Assert.Contains("2.0.0", msg);
+        Assert.Contains("dotnet meta agent-docs", msg);
+    }
+
+    [Fact]
+    public void Null_generatedBy_nudges_with_older_phrasing()
+    {
+        var m = ManifestWith(null);
+        var msg = AgentContextScaffold.AgentContextStaleness(m, "2.0.0");
+        Assert.NotNull(msg);
+        Assert.Contains("an older MetaObjects", msg);
+        Assert.Contains("2.0.0", msg);
+        Assert.Contains("dotnet meta agent-docs", msg);
+    }
+
+    // Even a prerelease/build-metadata difference nudges (exact equality, not semver).
+    [Fact]
+    public void Any_drift_nudges_no_semver_parsing()
+    {
+        var m = ManifestWith("1.2.3");
+        Assert.NotNull(AgentContextScaffold.AgentContextStaleness(m, "1.2.3-rc.1"));
+    }
+
+    // ---- 3. version source --------------------------------------------------
+
+    [Fact]
+    public void CurrentVersion_reads_a_nonempty_value_from_the_assembly()
+    {
+        var v = AgentContextStalenessCheck.CurrentVersion();
+        Assert.False(string.IsNullOrEmpty(v));
+    }
+
+    // ---- helper -------------------------------------------------------------
+
+    private static AgentContextScaffold.Manifest ManifestWith(string? generatedBy) =>
+        new(1, generatedBy, Array.Empty<string>(), Array.Empty<string>(),
+            new Dictionary<string, string>());
+}
diff --git a/server/csharp/MetaObjects.Cli/AgentContextStalenessCheck.cs b/server/csharp/MetaObjects.Cli/AgentContextStalenessCheck.cs
@@ -0,0 +1,76 @@
+// AgentContextStalenessCheck — the side-effecting half of the agent-context staleness
+// nudge (the pure decision lives in MetaObjects.AgentContext.AgentContextScaffold).
+//
+// Port of the TS cli lib (version.ts + agent-context-staleness.ts): read the installed
+// MetaObjects version from the assembly, read the consumer's sidecar manifest if present,
+// and print ONE advisory line to stderr when the scaffolded agent context predates this
+// build. Advisory only — never throws, never blocks, never writes, never changes the exit
+// code. A missing/corrupt manifest is silently ignored (this is a reminder, not a gate).
+
+using System.Reflection;
+using System.Text.Json;
+using MetaObjects.AgentContext;
+
+namespace MetaObjects.Cli;
+
+/// <summary>Reads the manifest + installed version and emits the staleness nudge (advisory).</summary>
+public static class AgentContextStalenessCheck
+{
+    /// <summary>
+    /// The installed MetaObjects version, read from the assembly (the
+    /// <c>AssemblyInformationalVersion</c>, falling back to the assembly version), with a
+    /// safe <c>"0.0.0"</c> fallback when neither is present. Never a hardcoded literal.
+    /// </summary>
+    public static string CurrentVersion()
+    {
+        var asm = typeof(AgentContextScaffold).Assembly;
+        var info = asm.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion;
+        if (!string.IsNullOrEmpty(info)) return info;
+        var ver = asm.GetName().Version?.ToString();
+        return string.IsNullOrEmpty(ver) ? "0.0.0" : ver;
+    }
+
+    /// <summary>
+    /// If a scaffolded MetaObjects agent context under <paramref name="cwd"/> predates this
+    /// build, write a one-line nudge to stderr. Never throws — an absent or corrupt manifest
+    /// is silently ignored. Advisory: the caller's exit code is unaffected.
+    /// </summary>
+    public static void WarnIfStale(string cwd)
+    {
+        try
+        {
+            var path = Path.Combine(cwd, AgentContextScaffold.ManifestPath);
+            if (!File.Exists(path)) return; // no agent context here → nothing to nudge
+
+            AgentContextScaffold.Manifest? manifest;
+            try
+            {
+                manifest = ReadManifest(path);
+            }
+            catch
+            {
+                return; // unreadable / corrupt — say nothing
+            }
+
+            var msg = AgentContextScaffold.AgentContextStaleness(manifest, CurrentVersion());
+            if (msg is not null) Console.Error.WriteLine(msg);
+        }
+        catch
+        {
+            // Belt-and-suspenders: an advisory must never break the command it rides on.
+        }
+    }
+
+    private static AgentContextScaffold.Manifest? ReadManifest(string path)
+    {
+        using var doc = JsonDocument.Parse(File.ReadAllText(path));
+        var root = doc.RootElement;
+        // Only generatedBy is load-bearing for the decision; the rest is read for fidelity.
+        var version = root.TryGetProperty("version", out var v) && v.ValueKind == JsonValueKind.Number
+            ? v.GetInt32() : 1;
+        var generatedBy = root.TryGetProperty("generatedBy", out var g) ? g.GetString() : null;
+        return new AgentContextScaffold.Manifest(
+            version, generatedBy, Array.Empty<string>(), Array.Empty<string>(),
+            new Dictionary<string, string>());
+    }
+}
diff --git a/server/csharp/MetaObjects.Cli/AgentDocsCommand.cs b/server/csharp/MetaObjects.Cli/AgentDocsCommand.cs
@@ -85,7 +85,7 @@ public static int Run(string[] rest)
         var prior = ReadPriorManifest(manifestPath);
 
         var decision = AgentContextScaffold.Plan(stack, assembled, prior,
-            rel => ReadCurrent(target, rel));
+            rel => ReadCurrent(target, rel), AgentContextStalenessCheck.CurrentVersion());
 
         foreach (var w in decision.Writes)
         {
@@ -121,11 +121,12 @@ public static int Run(string[] rest)
             using var doc = JsonDocument.Parse(File.ReadAllText(manifestPath));
             var root = doc.RootElement;
             var version = root.TryGetProperty("version", out var v) ? v.GetInt32() : 1;
+            var generatedBy = root.TryGetProperty("generatedBy", out var g) ? g.GetString() : null;
             var files = new Dictionary<string, string>();
             if (root.TryGetProperty("files", out var f) && f.ValueKind == JsonValueKind.Object)
                 foreach (var prop in f.EnumerateObject())
                     files[prop.Name] = prop.Value.GetString() ?? "";
-            return new AgentContextScaffold.Manifest(version, JsonStrings(root, "servers"),
+            return new AgentContextScaffold.Manifest(version, generatedBy, JsonStrings(root, "servers"),
                 JsonStrings(root, "clients"), files);
         }
         catch (JsonException)
@@ -162,6 +163,10 @@ private static void WriteManifest(string manifestPath, AgentContextScaffold.Mani
         var doc = new
         {
             version = manifest.Version,
+            // Same JSON key as the TS/Java/Python references ("generatedBy") so a polyglot
+            // repo can cross-read the stamp. The installed MetaObjects version, read from
+            // the assembly — nudges a re-scaffold once the package moves ahead.
+            generatedBy = manifest.GeneratedBy,
             servers = manifest.Servers,
             clients = manifest.Clients,
             files = manifest.Files,
diff --git a/server/csharp/MetaObjects.Cli/MetaObjects.Cli.csproj b/server/csharp/MetaObjects.Cli/MetaObjects.Cli.csproj
@@ -20,6 +20,11 @@
     <ProjectReference Include="../MetaObjects.Codegen/MetaObjects.Codegen.csproj" />
   </ItemGroup>
 
+  <!-- The test project drives the internal command entry points (e.g. AgentDocsCommand). -->
+  <ItemGroup>
+    <InternalsVisibleTo Include="MetaObjects.Cli.Tests" />
+  </ItemGroup>
+
   <!-- Bundle the repo-root agent-context/ content tree so `dotnet meta agent-docs`
        resolves it both in dev (run-from-output) and when installed as a .NET tool.
        Copied under <output>/agent-context/, where ContentRoot.Resolve looks first. -->
diff --git a/server/csharp/MetaObjects.Cli/Program.cs b/server/csharp/MetaObjects.Cli/Program.cs
@@ -74,6 +74,10 @@ static int RunGen(string[] rest)
         return 2;
     }
 
+    // Advisory: nudge a re-scaffold if the copied-in agent context predates this build.
+    // Never throws, never changes the exit code (a missing/corrupt manifest is ignored).
+    AgentContextStalenessCheck.WarnIfStale(Directory.GetCurrentDirectory());
+
     var generatorNames = generatorsCsv
         ?.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
 
@@ -156,6 +160,10 @@ static int RunVerify(string[] rest)
         return 2;
     }
 
+    // Advisory: nudge a re-scaffold if the copied-in agent context predates this build.
+    // Never throws, never changes the exit code (a missing/corrupt manifest is ignored).
+    AgentContextStalenessCheck.WarnIfStale(Directory.GetCurrentDirectory());
+
     var generators = generatorsCsv
         ?.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
 
diff --git a/server/csharp/MetaObjects/AgentContext/AgentContextScaffold.cs b/server/csharp/MetaObjects/AgentContext/AgentContextScaffold.cs
@@ -27,8 +27,15 @@ public sealed record Write(string Path, string Contents);
     public sealed record Conflict(string Path, string NewPath, string Contents);
 
     /// <summary>Tracks what the assembler last wrote, so re-runs can detect hand-edits.</summary>
+    /// <param name="GeneratedBy">
+    /// The MetaObjects version that last scaffolded this agent context. Used to nudge a
+    /// re-scaffold when the installed version moves ahead (the skills/docs ship with the
+    /// package, so an upgrade can leave the copied-in context stale). Nullable for
+    /// back-compat with manifests written before version tracking existed.
+    /// </param>
     public sealed record Manifest(
         int Version,
+        string? GeneratedBy,
         IReadOnlyList<string> Servers,
         IReadOnlyList<string> Clients,
         IReadOnlyDictionary<string, string> Files);
@@ -51,11 +58,13 @@ public static string HashContents(string s)
     /// Decide what to write for a (re-)scaffold. Pure: filesystem access is via the
     /// <paramref name="readCurrent"/> function (returns on-disk contents, or <c>null</c> if absent).
     /// </summary>
+    /// <param name="generatedBy">The MetaObjects version doing the scaffold — stamped into the manifest.</param>
     public static ScaffoldDecision Plan(
         Stack stack,
         IReadOnlyList<AssembledFile> assembled,
         Manifest? prior,
-        Func<string, string?> readCurrent)
+        Func<string, string?> readCurrent,
+        string generatedBy)
     {
         var writes = new List<Write>();
         var conflicts = new List<Conflict>();
@@ -91,9 +100,29 @@ public static ScaffoldDecision Plan(
 
         var manifest = new Manifest(
             1,
+            generatedBy,
             stack.Servers.ToList(),
             stack.Clients.ToList(),
             files);
         return new ScaffoldDecision(writes, conflicts, manifest, removed);
     }
+
+    /// <summary>
+    /// A one-line nudge if the scaffolded agent context predates the installed MetaObjects
+    /// (so <c>gen</c>/<c>verify</c> can remind the user to refresh the skills after an
+    /// upgrade), or <c>null</c> when there is nothing to say — no agent context scaffolded,
+    /// or it is in sync. Advisory only: never throws, never blocks, never writes. Pure.
+    /// </summary>
+    public static string? AgentContextStaleness(Manifest? manifest, string currentVersion)
+    {
+        if (manifest is null) return null; // no agent context here → nothing to nudge
+        // Exact-equality on purpose: ANY drift nudges (a re-scaffold is cheap + idempotent).
+        // Don't "fix" this into a semver compare — a prerelease/build-metadata difference is
+        // still a reason to refresh, and the nudge is advisory, never a gate.
+        if (manifest.GeneratedBy == currentVersion) return null; // in sync
+        var from = manifest.GeneratedBy ?? "an older MetaObjects";
+        return
+            $"MetaObjects agent context was generated by {from}; you're on {currentVersion}. " +
+            "Re-run 'dotnet meta agent-docs' to refresh the .claude/skills docs.";
+    }
 }
