feat(python): agent-context staleness nudge in gen/verify

Port the TS agent-context staleness advisory to the Python port. When an
adopter upgrades MetaObjects but does not re-scaffold the copied-in
.claude/skills agent context, `metaobjects gen`/`verify` now print ONE
stderr line nudging a re-scaffold.

Three parts (mirrors server/typescript/packages/sdk/src/agent-context/scaffold.ts):

1. Stamp `generatedBy` (SAME key as TS — polyglot cross-read) into the
   .metaobjects/.agent-context.json manifest when `agent-docs` scaffolds it.
   Version resolved via importlib.metadata.version("metaobjects"), falling
   back to "0.0.0" on PackageNotFoundError (mirrors the TS fallback).

2. Pure decision `agent_context_staleness(manifest, current_version)`: no
   manifest -> None; generatedBy == current -> None (exact equality on
   purpose — any drift nudges, never a semver compare); differs/absent -> a
   one-line message naming both versions + the Python refresh command
   ('metaobjects agent-docs'). Unit-testable, no FS.

3. gen + verify read <cwd>/.metaobjects/.agent-context.json near their start
   and print the message to stderr if stale. Advisory only: never raises,
   never changes the exit code, never writes; missing/corrupt manifest is
   silently ignored.

The manifest is not in the byte-gated assembled file set, so adding
generatedBy leaves agent-context conformance goldens unchanged.

Tests: pure decision (none/equal/differ/absent), the stamp, and gen+verify
stderr wiring (stale -> nudge + exit 0; absent/corrupt -> silent).

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

Author: dmealing

server/python/src/metaobjects/agent_context/__init__.py

@@ -22,7 +22,9 @@
     AGENT_CONTEXT_MANIFEST_PATH,
     Manifest,
     ScaffoldDecision,
+    agent_context_staleness,
     hash_contents,
+    installed_metaobjects_version,
     plan_scaffold,
 )
 from .types import (
@@ -43,8 +45,10 @@
     "SKILL_NAMES",
     "ScaffoldDecision",
     "Stack",
+    "agent_context_staleness",
     "assemble",
     "hash_contents",
+    "installed_metaobjects_version",
     "make_stack",
     "plan_scaffold",
     "resolve_agent_context_root",

server/python/src/metaobjects/agent_context/scaffold.py

@@ -14,6 +14,7 @@
 import hashlib
 from collections.abc import Callable
 from dataclasses import dataclass, field
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
 
 from .assemble import AssembledFile
 from .types import Stack
@@ -22,6 +23,20 @@
 AGENT_CONTEXT_MANIFEST_PATH = ".metaobjects/.agent-context.json"
 
 
+def installed_metaobjects_version() -> str:
+    """The installed ``metaobjects`` distribution version, or ``"0.0.0"`` if absent.
+
+    Resolved idiomatically via :func:`importlib.metadata.version`; a
+    ``PackageNotFoundError`` (e.g. running straight from a source checkout that
+    was never installed) falls back to ``"0.0.0"`` — mirroring the TS reference's
+    fallback so the stamp/nudge never crashes.
+    """
+    try:
+        return _pkg_version("metaobjects")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
 @dataclass
 class Manifest:
     """Tracks what the assembler last wrote, so re-runs can detect hand-edits."""
@@ -31,14 +46,21 @@ class Manifest:
     clients: list[str]
     #: consumer-relative path → sha256 of the contents as last scaffolded.
     files: dict[str, str]
+    #: The MetaObjects version that last scaffolded this context. Drives the
+    #: staleness nudge (an upgrade can leave the copied-in skills/docs stale).
+    #: Optional for back-compat with manifests written before version tracking.
+    #: Serialized as ``generatedBy`` — the SAME key as the TS reference, so a
+    #: polyglot repo can cross-read the manifest regardless of which port wrote it.
+    generated_by: str | None = None
 
     def to_json(self) -> dict[str, object]:
-        return {
-            "version": self.version,
-            "servers": list(self.servers),
-            "clients": list(self.clients),
-            "files": dict(self.files),
-        }
+        out: dict[str, object] = {"version": self.version}
+        if self.generated_by is not None:
+            out["generatedBy"] = self.generated_by
+        out["servers"] = list(self.servers)
+        out["clients"] = list(self.clients)
+        out["files"] = dict(self.files)
+        return out
 
     @staticmethod
     def from_json(data: dict[str, object]) -> "Manifest":
@@ -50,11 +72,13 @@ def from_json(data: dict[str, object]) -> "Manifest":
         )
         servers = data.get("servers", [])
         clients = data.get("clients", [])
+        generated_by = data.get("generatedBy")
         return Manifest(
             version=int(data.get("version", 1)),  # type: ignore[arg-type]
             servers=[str(x) for x in servers] if isinstance(servers, list) else [],
             clients=[str(x) for x in clients] if isinstance(clients, list) else [],
             files=files,
+            generated_by=str(generated_by) if generated_by is not None else None,
         )
 
 
@@ -95,8 +119,13 @@ def plan_scaffold(
     assembled: list[AssembledFile],
     prior: Manifest | None,
     read_current: Callable[[str], str | None],
+    generated_by: str | None = None,
 ) -> ScaffoldDecision:
-    """Decide what to write for a (re-)scaffold (pure; FS via ``read_current``)."""
+    """Decide what to write for a (re-)scaffold (pure; FS via ``read_current``).
+
+    ``generated_by`` is the MetaObjects version doing the scaffold — stamped into
+    the persisted manifest so a later ``gen``/``verify`` can detect staleness.
+    """
     writes: list[_Write] = []
     conflicts: list[_Conflict] = []
     files: dict[str, str] = {}
@@ -130,6 +159,33 @@ def plan_scaffold(
             servers=list(stack.servers),
             clients=list(stack.clients),
             files=files,
+            generated_by=generated_by,
         ),
         removed=removed,
     )
+
+
+def agent_context_staleness(
+    manifest: dict[str, object] | None, current_version: str
+) -> str | None:
+    """One-line nudge if the scaffolded agent context predates the install.
+
+    Returns ``None`` when there is nothing to say — no agent context here, or it
+    is in sync — and a one-line advisory message otherwise. Pure + advisory:
+    never raises, never blocks, never writes.
+
+    The comparison is **exact equality** on purpose: ANY drift nudges (a
+    re-scaffold is cheap + idempotent). Do NOT "fix" this into a semver compare —
+    a prerelease/build-metadata difference is still a reason to refresh.
+    """
+    if manifest is None:
+        return None  # no agent context here → nothing to nudge
+    generated_by = manifest.get("generatedBy")
+    if generated_by == current_version:
+        return None  # in sync
+    frm = generated_by if generated_by else "an older MetaObjects"
+    return (
+        f"MetaObjects agent context was generated by {frm}; "
+        f"you're on {current_version}. Re-run 'metaobjects agent-docs' to "
+        f"refresh the .claude/skills docs."
+    )

server/python/src/metaobjects/cli.py

@@ -44,7 +44,9 @@
 from metaobjects.agent_context import (
     AGENT_CONTEXT_MANIFEST_PATH,
     Manifest,
+    agent_context_staleness,
     assemble,
+    installed_metaobjects_version,
     make_stack,
     plan_scaffold,
     resolve_agent_context_root,
@@ -161,11 +163,35 @@ def _cmd_list(_args: argparse.Namespace) -> int:
     return 0
 
 
+def _warn_if_agent_context_stale() -> None:
+    """Print ONE advisory line to stderr if the scaffolded agent context is stale.
+
+    Reads ``<cwd>/.metaobjects/.agent-context.json`` (if present), compares its
+    stamped ``generatedBy`` to the installed version, and nudges a re-scaffold on
+    any drift. Advisory only: never raises, never changes the exit code, never
+    writes — a missing or corrupt manifest is silently ignored.
+    """
+    try:
+        manifest_path = Path.cwd() / AGENT_CONTEXT_MANIFEST_PATH
+        if not manifest_path.is_file():
+            return
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if not isinstance(manifest, dict):
+            return
+        msg = agent_context_staleness(manifest, installed_metaobjects_version())
+        if msg is not None:
+            print(msg, file=sys.stderr)
+    except Exception:  # noqa: BLE001 — advisory; any failure is silently ignored
+        return
+
+
 def _cmd_gen(args: argparse.Namespace) -> int:
     # `--list` is a pure discoverability path: print the registry and exit, no codegen.
     if getattr(args, "list", False):
         return _cmd_list(args)
 
+    _warn_if_agent_context_stale()
+
     if args.metadata_dir is None or args.out is None:
         print(
             "error: gen requires <metadata_dir> and --out (or use --list).",
@@ -395,6 +421,8 @@ def _cmd_verify(args: argparse.Namespace) -> int:
     max (non-zero if ANY mode drifts). Bare ``verify`` (no subverb) keeps the
     historical default = ``--codegen`` + a one-line note advertising the subverbs.
     """
+    _warn_if_agent_context_stale()
+
     run_db = args.db is not None
     run_templates = bool(args.templates)
     run_codegen = bool(args.codegen)
@@ -505,7 +533,13 @@ def _read_current(rel: str) -> str | None:
         p = out_dir / rel
         return p.read_bytes().decode("utf-8") if p.is_file() else None
 
-    decision = plan_scaffold(stack, assembled, prior, _read_current)
+    decision = plan_scaffold(
+        stack,
+        assembled,
+        prior,
+        _read_current,
+        generated_by=installed_metaobjects_version(),
+    )
 
     for w in decision.writes:
         dest = out_dir / w.path

server/python/tests/codegen/test_cli_staleness_nudge.py

@@ -0,0 +1,93 @@
+"""``gen``/``verify`` print the agent-context staleness nudge to stderr.
+
+Advisory only: a stale ``.metaobjects/.agent-context.json`` in the cwd causes ONE
+stderr line but never changes the exit code, never writes, and a missing/corrupt
+manifest is silently ignored.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from metaobjects.cli import main
+
+FIXTURE = (
+    Path(__file__).parents[4]
+    / "fixtures"
+    / "persistence-conformance"
+    / "canonical"
+    / "meta.fitness.json"
+)
+
+
+def _meta_dir(tmp_path: Path) -> str:
+    d = tmp_path / "meta"
+    d.mkdir()
+    (d / "meta.fitness.json").write_text(FIXTURE.read_text())
+    return str(d)
+
+
+def _write_manifest(cwd: Path, generated_by: str | None) -> None:
+    m: dict[str, object] = {"version": 1, "servers": ["python"], "clients": [], "files": {}}
+    if generated_by is not None:
+        m["generatedBy"] = generated_by
+    p = cwd / ".metaobjects" / ".agent-context.json"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(m, indent=2) + "\n")
+
+
+def test_gen_nudges_on_stale_manifest(tmp_path, capsys, monkeypatch) -> None:
+    meta_dir = _meta_dir(tmp_path)
+    out = tmp_path / "out"
+    monkeypatch.chdir(tmp_path)
+    _write_manifest(tmp_path, "0.0.1-old")
+
+    rc = main(["gen", meta_dir, "--out", str(out)])
+    assert rc == 0  # advisory: never changes the exit code
+    err = capsys.readouterr().err
+    assert "0.0.1-old" in err
+    assert "metaobjects agent-docs" in err
+
+
+def test_verify_nudges_on_stale_manifest(tmp_path, capsys, monkeypatch) -> None:
+    meta_dir = _meta_dir(tmp_path)
+    out = tmp_path / "out"
+    monkeypatch.chdir(tmp_path)
+    # Generate AND verify under the same cwd so verify --codegen is in-sync (no
+    # DRIFT) — isolating the nudge from the codegen exit code.
+    main(["gen", meta_dir, "--out", str(out)])
+    capsys.readouterr()  # drain
+
+    _write_manifest(tmp_path, "0.0.1-old")
+
+    rc = main(["verify", meta_dir, "--codegen", "--out", str(out)])
+    assert rc == 0
+    err = capsys.readouterr().err
+    assert "0.0.1-old" in err
+    assert "metaobjects agent-docs" in err
+
+
+def test_gen_silent_when_no_manifest(tmp_path, capsys, monkeypatch) -> None:
+    meta_dir = _meta_dir(tmp_path)
+    out = tmp_path / "out"
+    monkeypatch.chdir(tmp_path)  # no manifest in cwd
+
+    rc = main(["gen", meta_dir, "--out", str(out)])
+    assert rc == 0
+    err = capsys.readouterr().err
+    assert "metaobjects agent-docs" not in err
+
+
+def test_gen_silent_on_corrupt_manifest(tmp_path, capsys, monkeypatch) -> None:
+    meta_dir = _meta_dir(tmp_path)
+    out = tmp_path / "out"
+    monkeypatch.chdir(tmp_path)
+    p = tmp_path / ".metaobjects" / ".agent-context.json"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text("{ this is not valid json ")  # corrupt → silently ignored
+
+    rc = main(["gen", meta_dir, "--out", str(out)])
+    assert rc == 0
+    err = capsys.readouterr().err
+    assert "metaobjects agent-docs" not in err

server/python/tests/unit/test_agent_context_staleness.py

@@ -0,0 +1,77 @@
+"""Unit tests for the agent-context staleness nudge (cross-port feature).
+
+Port of the TS reference (``server/typescript/packages/sdk/src/agent-context/
+scaffold.ts`` — ``agentContextStaleness`` + ``generatedBy`` manifest stamping).
+
+When an adopter upgrades MetaObjects but does not re-scaffold the copied-in
+``.claude/skills`` agent context, ``gen``/``verify`` should print ONE advisory
+line nudging a re-scaffold. The decision is a pure function (exact-equality on
+the stamped version — ANY drift nudges, never a semver compare), and the manifest
+written by ``agent-docs`` carries the installed version under ``generatedBy``
+(SAME key as TS — a polyglot repo may cross-read the manifest).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from metaobjects.agent_context.scaffold import (
+    agent_context_staleness,
+    installed_metaobjects_version,
+)
+from metaobjects.cli import main
+
+
+# ---- the pure decision -----------------------------------------------------
+
+
+def test_no_manifest_returns_none() -> None:
+    # No agent context scaffolded here → nothing to nudge.
+    assert agent_context_staleness(None, "0.7.0") is None
+
+
+def test_matching_version_returns_none() -> None:
+    # In sync → silent.
+    manifest = {"version": 1, "generatedBy": "0.7.0", "servers": [], "clients": [], "files": {}}
+    assert agent_context_staleness(manifest, "0.7.0") is None
+
+
+def test_differing_version_nudges_naming_both_versions_and_command() -> None:
+    manifest = {"version": 1, "generatedBy": "0.6.1", "servers": [], "clients": [], "files": {}}
+    msg = agent_context_staleness(manifest, "0.7.0")
+    assert msg is not None
+    assert "0.6.1" in msg  # the from-version
+    assert "0.7.0" in msg  # the current version
+    assert "agent-docs" in msg  # names the Python refresh command
+    assert "metaobjects agent-docs" in msg
+
+
+def test_absent_generated_by_nudges_with_older_phrase() -> None:
+    # A manifest written before version tracking existed → still nudge.
+    manifest = {"version": 1, "servers": [], "clients": [], "files": {}}
+    msg = agent_context_staleness(manifest, "0.7.0")
+    assert msg is not None
+    assert "an older MetaObjects" in msg
+    assert "0.7.0" in msg
+    assert "metaobjects agent-docs" in msg
+
+
+def test_installed_version_is_a_string() -> None:
+    # Resolved via importlib.metadata; falls back to "0.0.0" off the package.
+    v = installed_metaobjects_version()
+    assert isinstance(v, str)
+    assert v  # non-empty
+
+
+# ---- the stamp -------------------------------------------------------------
+
+
+def test_agent_docs_stamps_generated_by(tmp_path: Path) -> None:
+    rc = main(["agent-docs", "--server", "python", "--out", str(tmp_path)])
+    assert rc == 0
+    manifest = json.loads(
+        (tmp_path / ".metaobjects" / ".agent-context.json").read_text()
+    )
+    assert "generatedBy" in manifest
+    assert manifest["generatedBy"] == installed_metaobjects_version()