feat(cli): nudge to refresh agent-context when it predates the installed CLI

Closes the version-drift gap in the scaffolded-skills model (ADR-0024 review
follow-up): the .claude/skills agent-context ships with the package, so an
upgrade can leave the copied-in copy stale with nothing telling the adopter.

- sdk: the agent-context manifest now records `generatedBy` (the MetaObjects
  version that scaffolded it; optional-on-read for back-compat, required-on-write).
  New pure `agentContextStaleness({manifest, currentVersion})` → a one-line nudge
  when the manifest predates (or lacks) the installed version, else null.
- cli: `meta init` stamps `generatedBy`; `meta gen` + `meta verify` print the
  advisory nudge near the top (after --list/arg-parse exits). Never throws, never
  blocks — a missing/corrupt manifest is silent. Extracted `cliVersion()` to a
  shared lib (was inline in index.ts).

TS pilot. The manifest schema (`version: 1` + optional `generatedBy`) is the
cross-port contract: Java/Python/C# agent-docs scaffolds stamp it + mirror the
pure staleness check in their gen/verify next. sdk+cli 420/0, typecheck clean,
end-to-end smoked (stale→nudge, in-sync→silent).

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

Author: dmealing

server/typescript/packages/cli/src/commands/gen.ts

@@ -5,6 +5,7 @@ import { resolveGenConfig } from "../lib/config.js";
 import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
 import { formatGenResult, type GenFileEntry, type GenFileStatus } from "../lib/output.js";
 import { log } from "../lib/log.js";
+import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { loadMemory, DEFAULT_METADATA_DIR } from "@metaobjectsdev/sdk";
 import { runGen, listGenerators, deriveTraceFields } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
@@ -32,6 +33,9 @@ export async function genCommand(args: string[], cwd: string): Promise<number> {
     return listGeneratorsCommand();
   }
 
+  // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
+  warnIfAgentContextStale(cwd);
+
   const projectRoot = cwd;
   const cliConfig = resolveGenConfig(flags);
 

server/typescript/packages/cli/src/commands/init.ts

@@ -10,6 +10,7 @@ import {
 import { resolveStack } from "../lib/detect-stack.js";
 import { parseInitArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
+import { cliVersion } from "../lib/version.js";
 import { findWranglerConfig, parseWranglerConfig } from "@metaobjectsdev/migrate-ts";
 
 const META_COMMON_JSON = JSON.stringify(
@@ -107,6 +108,7 @@ async function writeAgentContext(opts: InitOptions, result: InitResult): Promise
       const abs = join(opts.cwd, rel);
       return existsSyncWrap(abs) ? readFileSyncWrap(abs, "utf8") : undefined;
     },
+    generatedBy: cliVersion(),
   });
 
   for (const w of decision.writes) {

server/typescript/packages/cli/src/commands/verify.ts

@@ -10,6 +10,7 @@
 import { join } from "node:path";
 import { parseVerifyArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
+import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
@@ -48,6 +49,9 @@ export async function verifyCommand(args: string[], cwd: string): Promise<number
     return 2;
   }
 
+  // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
+  warnIfAgentContextStale(cwd);
+
   // ADR-0021 D2 — explicit verify subverbs. Each flag selects one drift mode;
   // any combination runs each and the overall exit code is the MAX (non-zero on
   // any drift). A bare `verify` (no explicit subverb) keeps its documented

server/typescript/packages/cli/src/index.ts

@@ -1,33 +1,10 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import { log } from "./lib/log.js";
+import { cliVersion } from "./lib/version.js";
 export { defineConfig } from "@metaobjectsdev/codegen-ts";
 export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
-// Derive the version from the CLI's own package.json so it never goes stale.
-// The compiled entry is dist/src/index.js while package.json sits at the package
-// root, so walk up from the module location until @metaobjectsdev/cli's manifest.
-function readCliVersion(): string {
-  let dir = dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 6; i++) {
-    const candidate = join(dir, "package.json");
-    if (existsSync(candidate)) {
-      try {
-        const pkg = JSON.parse(readFileSync(candidate, "utf8")) as { name?: string; version?: string };
-        if (pkg.name === "@metaobjectsdev/cli" && pkg.version) return pkg.version;
-      } catch {
-        // not our manifest / unreadable — keep walking up
-      }
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return "0.0.0";
-}
-
-const VERSION = readCliVersion();
+const VERSION = cliVersion();
 
 const HELP_TEXT = `meta — MetaObjects CLI (v${VERSION})
 

server/typescript/packages/cli/src/lib/agent-context-staleness.ts

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, type Manifest } from "@metaobjectsdev/sdk";
+import { cliVersion } from "./version.js";
+import { log } from "./log.js";
+
+/**
+ * Advisory: if a scaffolded MetaObjects agent context predates this CLI version,
+ * print a one-line nudge to re-scaffold. Never throws, never blocks — an absent or
+ * corrupt manifest is silently ignored (this is a reminder, not a gate).
+ */
+export function warnIfAgentContextStale(cwd: string): void {
+  const p = join(cwd, AGENT_CONTEXT_MANIFEST_PATH);
+  let manifest: Manifest | undefined;
+  if (existsSync(p)) {
+    try {
+      manifest = JSON.parse(readFileSync(p, "utf8")) as Manifest;
+    } catch {
+      return; // unreadable/corrupt — say nothing
+    }
+  }
+  const msg = agentContextStaleness({ manifest, currentVersion: cliVersion() });
+  if (msg !== null) log.warn(msg);
+}

server/typescript/packages/cli/src/lib/version.ts

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The installed `@metaobjectsdev/cli` version, read from its own package.json so it
+ * never goes stale. Walks up from this module to the cli package root; returns
+ * "0.0.0" if not found.
+ */
+export function cliVersion(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync(candidate, "utf8")) as { name?: string; version?: string };
+        if (pkg.name === "@metaobjectsdev/cli" && pkg.version) return pkg.version;
+      } catch {
+        // not our manifest / unreadable — keep walking up
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "0.0.0";
+}

server/typescript/packages/sdk/src/agent-context/scaffold.ts

@@ -6,6 +6,13 @@ export const AGENT_CONTEXT_MANIFEST_PATH = ".metaobjects/.agent-context.json";
 
 export interface Manifest {
   version: 1;
+  /**
+   * 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). Optional for
+   * back-compat with manifests written before version tracking existed.
+   */
+  generatedBy?: string;
   servers: string[];
   clients: string[];
   /** consumer-relative path → sha256 of the contents as last scaffolded. */
@@ -38,8 +45,10 @@ export function planScaffold(opts: {
   assembled: AssembledFile[];
   prior: Manifest | undefined;
   readCurrent: (path: string) => string | undefined;
+  /** The MetaObjects version doing the scaffold — stamped into the manifest. */
+  generatedBy: string;
 }): ScaffoldDecision {
-  const { stack, assembled, prior, readCurrent } = opts;
+  const { stack, assembled, prior, readCurrent, generatedBy } = opts;
   const writes: ScaffoldDecision["writes"] = [];
   const conflicts: ScaffoldDecision["conflicts"] = [];
   const files: Record<string, string> = {};
@@ -65,7 +74,30 @@ export function planScaffold(opts: {
   return {
     writes,
     conflicts,
-    manifest: { version: 1, servers: stack.servers, clients: stack.clients, files },
+    manifest: { version: 1, generatedBy, servers: stack.servers, clients: stack.clients, files },
     removed,
   };
 }
+
+/**
+ * A one-line nudge if the scaffolded agent context predates the installed MetaObjects
+ * (so `gen`/`verify` can remind the user to refresh the skills after an upgrade), or
+ * `null` when there is nothing to say — no agent context scaffolded, or it is in sync.
+ * Advisory only: never throws, never blocks, never writes.
+ */
+export function agentContextStaleness(opts: {
+  manifest: Manifest | undefined;
+  currentVersion: string;
+}): string | null {
+  const { manifest, currentVersion } = opts;
+  if (manifest === undefined) 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
+  const from = manifest.generatedBy ?? "an older MetaObjects";
+  return (
+    `MetaObjects agent context was generated by ${from}; you're on ${currentVersion}. ` +
+    `Re-run 'meta init --docs-only --refresh-docs' to refresh the .claude/skills docs.`
+  );
+}

server/typescript/packages/sdk/test/agent-context/scaffold.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { hashContents, planScaffold, AGENT_CONTEXT_MANIFEST_PATH, type Manifest } from "../../src/agent-context/scaffold.js";
+import { hashContents, planScaffold, agentContextStaleness, AGENT_CONTEXT_MANIFEST_PATH, type Manifest } from "../../src/agent-context/scaffold.js";
 import { makeStack } from "../../src/agent-context/resolve.js";
 import type { AssembledFile } from "../../src/agent-context/types.js";
 
@@ -15,7 +15,7 @@ describe("planScaffold", () => {
   });
 
   test("all-new project: every file is a write; manifest records hashes; no conflicts", () => {
-    const d = planScaffold({ stack, assembled: files, prior: undefined, readCurrent: () => undefined });
+    const d = planScaffold({ stack, assembled: files, prior: undefined, readCurrent: () => undefined, generatedBy: "0.9.0" });
     expect(d.writes.map((w) => w.path).sort()).toEqual(files.map((f) => f.path).sort());
     expect(d.conflicts).toEqual([]);
     expect(d.manifest.files[".metaobjects/AGENTS.md"]).toBe(hashContents("always-on v2"));
@@ -28,6 +28,7 @@ describe("planScaffold", () => {
     const d = planScaffold({
       stack, assembled: [files[0]!], prior,
       readCurrent: (p) => (p === ".metaobjects/AGENTS.md" ? "always-on v1" : undefined),
+      generatedBy: "0.9.0",
     });
     expect(d.writes.map((w) => w.path)).toEqual([".metaobjects/AGENTS.md"]);
     expect(d.conflicts).toEqual([]);
@@ -38,19 +39,49 @@ describe("planScaffold", () => {
     const d = planScaffold({
       stack, assembled: [files[0]!], prior,
       readCurrent: () => "I HAND EDITED THIS",
+      generatedBy: "0.9.0",
     });
     expect(d.writes).toEqual([]);
     expect(d.conflicts).toEqual([{ path: ".metaobjects/AGENTS.md", newPath: ".metaobjects/AGENTS.md.new", contents: "always-on v2" }]);
   });
 
   test("file present but no prior manifest record → treat as hand-edited (.new), never clobber", () => {
-    const d = planScaffold({ stack, assembled: [files[0]!], prior: undefined, readCurrent: () => "pre-existing unknown" });
+    const d = planScaffold({ stack, assembled: [files[0]!], prior: undefined, readCurrent: () => "pre-existing unknown", generatedBy: "0.9.0" });
     expect(d.conflicts.map((c) => c.path)).toEqual([".metaobjects/AGENTS.md"]);
   });
 
   test("a file in the prior manifest no longer assembled (stack shrank) is reported as removed", () => {
     const prior: Manifest = { version: 1, servers: ["typescript", "java"], clients: ["react"], files: { ".claude/skills/metaobjects-codegen/references/java.md": "abc" } };
-    const d = planScaffold({ stack, assembled: files, prior, readCurrent: () => undefined });
+    const d = planScaffold({ stack, assembled: files, prior, readCurrent: () => undefined, generatedBy: "0.9.0" });
     expect(d.removed).toEqual([".claude/skills/metaobjects-codegen/references/java.md"]);
   });
 });
+
+describe("planScaffold generatedBy stamp", () => {
+  test("manifest records the MetaObjects version that scaffolded it", () => {
+    const d = planScaffold({ stack, assembled: files, prior: undefined, readCurrent: () => undefined, generatedBy: "0.9.0" });
+    expect(d.manifest.generatedBy).toBe("0.9.0");
+  });
+});
+
+describe("agentContextStaleness", () => {
+  const m = (generatedBy?: string): Manifest => ({ version: 1, generatedBy, servers: ["typescript"], clients: ["react"], files: {} });
+
+  test("no agent-context manifest → silent (null)", () => {
+    expect(agentContextStaleness({ manifest: undefined, currentVersion: "0.9.0" })).toBeNull();
+  });
+  test("generatedBy equals installed version → in sync (null)", () => {
+    expect(agentContextStaleness({ manifest: m("0.9.0"), currentVersion: "0.9.0" })).toBeNull();
+  });
+  test("generatedBy differs from installed → warning naming both versions", () => {
+    const w = agentContextStaleness({ manifest: m("0.8.0"), currentVersion: "0.9.0" });
+    expect(w).toContain("0.8.0");
+    expect(w).toContain("0.9.0");
+    expect(w).toContain("refresh-docs");
+  });
+  test("legacy manifest without generatedBy → warning (treated as older)", () => {
+    const w = agentContextStaleness({ manifest: m(undefined), currentVersion: "0.9.0" });
+    expect(w).toContain("0.9.0");
+    expect(w).toContain("refresh-docs");
+  });
+});