From 78ce27d0d9253aacc5a87829fee092046a979f52 Mon Sep 17 00:00:00 2001
From: Chisanan232 <bulls23mj1991@gmail.com>
Date: Thu, 16 Jul 2026 11:21:57 +0800
Subject: [PATCH 1/6] =?UTF-8?q?=E2=9C=A8=20(scripts):=20Own=20bullet-form?=
 =?UTF-8?q?=20Agent=20Assembly=20SDK=20prereq=20lines?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The generator owned only the table form of the Prerequisites SDK
requirement; go/README.md states it as a Markdown bullet, which drifted
to rc.3 while the table rows advanced to rc.5. Add a list-marker-anchored
bullet matcher and wire it into process_prereq_rows so the version can no
longer disagree across forms.

Closes AAASM-4717

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HMnPRm9T3fdrS4uNYXkzg6
---
 go/README.md                         |  2 +-
 scripts/generate_example_metadata.py | 37 ++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/go/README.md b/go/README.md
index 89a586d..20dd522 100644
--- a/go/README.md
+++ b/go/README.md
@@ -30,7 +30,7 @@ All examples use the [`github.com/ai-agent-assembly/go-sdk`](https://pkg.go.dev/
 ## Prerequisites
 
 - Go >= 1.26
-- Agent Assembly Go SDK v0.0.1-rc.3
+- Agent Assembly Go SDK v0.0.1-rc.5
 
 A live gateway is **not required** to run any of these examples — each uses an
 offline mock `GovernanceClient` by default so you can explore governance behavior
diff --git a/scripts/generate_example_metadata.py b/scripts/generate_example_metadata.py
index 9a55ecf..8598e89 100755
--- a/scripts/generate_example_metadata.py
+++ b/scripts/generate_example_metadata.py
@@ -420,6 +420,41 @@ def _sub(match: re.Match[str]) -> str:
     return _write_if_changed(path, new_text)
 
 
+# Some landing-page READMEs state the same requirement as a Markdown *bullet*
+# instead of a table row — ``go/README.md`` carries ``- Agent Assembly Go SDK
+# <version>`` under ``## Prerequisites`` (AAASM-4717). The bullet is anchored to
+# a list marker (``-``/``*``), so it can never collide with the table row (which
+# starts with ``|``) nor with the generated sdk-install block. Only the first
+# version token in the value is rewritten, so a trailing note is preserved
+# verbatim, exactly like the table-row pass.
+def _prereq_bullet_re(label: str) -> re.Pattern[str]:
+    return re.compile(
+        r"^(?P<pre>[ \t]*[-*][ \t]+Agent Assembly "
+        + re.escape(label)
+        + r" SDK[ \t]+)(?P<val>.*)$",
+        re.MULTILINE,
+    )
+
+
+def rewrite_prereq_bullet(path: Path, label: str, version: str) -> bool:
+    """Align a bullet-form ``- Agent Assembly <label> SDK <version>`` line.
+
+    The list-item sibling of ``rewrite_prereq_row``. A no-op for READMEs that
+    state the requirement as a table row or omit it entirely; when the bullet is
+    present only its first version token is aligned with the SoT.
+    """
+
+    text = path.read_text(encoding="utf-8")
+    bullet_re = _prereq_bullet_re(label)
+
+    def _sub(match: re.Match[str]) -> str:
+        new_val = _VERSION_TOKEN_RE.sub(version, match.group("val"), count=1)
+        return f"{match.group('pre')}{new_val}"
+
+    new_text = bullet_re.sub(_sub, text)
+    return _write_if_changed(path, new_text)
+
+
 # ---------------------------------------------------------------------------
 # Directory walkers
 # ---------------------------------------------------------------------------
@@ -605,6 +640,8 @@ def process_prereq_rows(repo_root: Path, versions: SdkVersions) -> list[Path]:
         for label, version in labels:
             if rewrite_prereq_row(readme, label, version):
                 touched = True
+            if rewrite_prereq_bullet(readme, label, version):
+                touched = True
         if touched:
             changed.append(readme)
     return changed

From 24835234aa04e79d274433be817993d219ee8621 Mon Sep 17 00:00:00 2001
From: Chisanan232 <bulls23mj1991@gmail.com>
Date: Thu, 16 Jul 2026 11:23:18 +0800
Subject: [PATCH 2/6] =?UTF-8?q?=E2=9C=A8=20(scripts):=20Own=20the=20agent-?=
 =?UTF-8?q?assembly=3D=3D=20pin=20in=20scenario=20Dockerfiles?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The live-core-enforcement python-agent Dockerfile pins the SDK via
pip install agent-assembly==<ver>, previously hand-maintained (AAASM-4702
had to hand-bump it). Add a bounded, non-recursive Dockerfile walker and a
lookbehind-anchored rewriter so the pin tracks the SoT and is covered by
the audit. No content diff today (already rc5); this is ownership only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HMnPRm9T3fdrS4uNYXkzg6
---
 scripts/generate_example_metadata.py | 72 ++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/scripts/generate_example_metadata.py b/scripts/generate_example_metadata.py
index 8598e89..240d299 100755
--- a/scripts/generate_example_metadata.py
+++ b/scripts/generate_example_metadata.py
@@ -251,6 +251,34 @@ def _sub(match: re.Match[str]) -> str:
     return _write_if_changed(path, new_text)
 
 
+# ---------------------------------------------------------------------------
+# Dockerfile pin rewrites
+# ---------------------------------------------------------------------------
+#
+# A handful of scenario Dockerfiles ``pip install`` the published Python SDK by
+# an exact ``agent-assembly==<version>`` pin (the live-core-enforcement
+# python-agent image). Left to hand-maintenance these drift on every SDK bump —
+# AAASM-4702 had to hand-correct one. The generator now owns that pin too so
+# future bumps (and the --check audit) cover it. The negative lookbehind anchors
+# the match to the standalone ``agent-assembly`` project name so it can never
+# fire on ``@agent-assembly/sdk`` or ``github.com/ai-agent-assembly/...``.
+_DOCKERFILE = "Dockerfile"
+
+_DOCKERFILE_PIN_RE = re.compile(
+    r'(?<![\w/@.-])(?P<pre>agent-assembly==)(?P<ver>[^"\s]+)'
+)
+
+
+def rewrite_dockerfile(path: Path, sdk: PythonSdk) -> bool:
+    text = path.read_text(encoding="utf-8")
+
+    def _sub(match: re.Match[str]) -> str:
+        return f"{match.group('pre')}{sdk.version}"
+
+    new_text = _DOCKERFILE_PIN_RE.sub(_sub, text)
+    return _write_if_changed(path, new_text)
+
+
 # ---------------------------------------------------------------------------
 # README bounded-block rewrites
 # ---------------------------------------------------------------------------
@@ -464,6 +492,24 @@ def _sub(match: re.Match[str]) -> str:
 _README = "README.md"
 
 
+def _globbed(repo_root: Path, patterns: tuple[str, ...]) -> list[Path]:
+    """Return the de-duplicated files matched by a set of bounded globs.
+
+    The patterns are explicit (no ``**`` recursion) so vendored trees
+    (``node_modules``, ``.venv``, ``dist``, build contexts) can never leak into
+    the generator's or the audit's scope.
+    """
+
+    seen: set[Path] = set()
+    out: list[Path] = []
+    for pattern in patterns:
+        for path in sorted(repo_root.glob(pattern)):
+            if path.is_file() and path not in seen:
+                seen.add(path)
+                out.append(path)
+    return out
+
+
 def _python_subprojects(repo_root: Path) -> list[Path]:
     """Return every directory that holds a python `pyproject.toml` in scope."""
 
@@ -534,6 +580,18 @@ def _go_subprojects(repo_root: Path) -> list[Path]:
     return out
 
 
+# Bounded, non-recursive walk over the scenario Dockerfiles: a scenario may keep
+# its Dockerfile at ``scenarios/<scenario>/Dockerfile`` or one level deeper at
+# ``scenarios/<scenario>/<component>/Dockerfile`` (e.g. the python-agent image).
+_DOCKERFILE_GLOBS = ("scenarios/*/Dockerfile", "scenarios/*/*/Dockerfile")
+
+
+def _dockerfiles(repo_root: Path) -> list[Path]:
+    """Return every in-scope scenario Dockerfile."""
+
+    return _globbed(repo_root, _DOCKERFILE_GLOBS)
+
+
 def process_python(repo_root: Path, versions: SdkVersions) -> list[Path]:
     """Rewrite all in-scope python manifests and READMEs.
 
@@ -592,6 +650,19 @@ def process_go(repo_root: Path, versions: SdkVersions) -> list[Path]:
     return changed
 
 
+def process_dockerfiles(repo_root: Path, versions: SdkVersions) -> list[Path]:
+    """Align the ``agent-assembly==`` pin in every in-scope Dockerfile.
+
+    Returns the list of files that were rewritten.
+    """
+
+    changed: list[Path] = []
+    for dockerfile in _dockerfiles(repo_root):
+        if rewrite_dockerfile(dockerfile, versions.python):
+            changed.append(dockerfile)
+    return changed
+
+
 # Bounded set of README locations that may carry a prose ``## Prerequisites``
 # table: the per-example READMEs, the language landing pages, and the scenario
 # READMEs (both scenario-level and per-agent). Kept as explicit globs rather
@@ -672,6 +743,7 @@ def main(argv: list[str] | None = None) -> int:
     changed.extend(process_python(args.repo_root, versions))
     changed.extend(process_node(args.repo_root, versions))
     changed.extend(process_go(args.repo_root, versions))
+    changed.extend(process_dockerfiles(args.repo_root, versions))
     changed.extend(process_prereq_rows(args.repo_root, versions))
 
     if changed:

From c510d4a1bbdf8beba670b6ff880577a7cc6ff5b0 Mon Sep 17 00:00:00 2001
From: Chisanan232 <bulls23mj1991@gmail.com>
Date: Thu, 16 Jul 2026 11:25:03 +0800
Subject: [PATCH 3/6] =?UTF-8?q?=E2=9C=A8=20(scripts):=20Add=20--check=20or?=
 =?UTF-8?q?phan-version-literal=20audit?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Make the generator the complete source of truth by adding the matching
reader: --check scans the bounded human-authored surfaces (manifest pins
under python/ node/ go/ scenarios/ and SDK-version prose in READMEs +
docs/*.md, never lockfiles or vendored trees) and exits non-zero naming
each drifted file:line. A newly added stale surface now fails CI. Lines
carrying the inline 'sdk-version-exempt' marker are skipped for legitimate
historical/provenance text.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HMnPRm9T3fdrS4uNYXkzg6
---
 scripts/generate_example_metadata.py | 166 +++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)

diff --git a/scripts/generate_example_metadata.py b/scripts/generate_example_metadata.py
index 240d299..db6b8e4 100755
--- a/scripts/generate_example_metadata.py
+++ b/scripts/generate_example_metadata.py
@@ -22,6 +22,15 @@
 
 Historical release notes and example-provenance content (e.g. "written
 against 0.0.1-rc.3") are out of scope and must not be touched.
+
+Audit mode (``--check``): instead of rewriting, scan the same bounded set of
+human-authored surfaces (manifest pins under ``python/ node/ go/ scenarios/``
+and SDK-version prose in READMEs / ``docs/*.md`` — never lockfiles or vendored
+trees) and exit non-zero, naming each ``file:line``, if any SDK-version literal
+has drifted from the SoT. This is the anti-recurrence invariant: a newly added
+stale surface fails CI. Legitimate historical/provenance text is exempted per
+line by the inline marker ``sdk-version-exempt``; such a line is never rewritten
+and never audited.
 """
 
 from __future__ import annotations
@@ -718,6 +727,139 @@ def process_prereq_rows(repo_root: Path, versions: SdkVersions) -> list[Path]:
     return changed
 
 
+# ---------------------------------------------------------------------------
+# Orphan-version-literal audit (--check)
+# ---------------------------------------------------------------------------
+#
+# The rewriters above make the generator the single *writer* of every SDK-version
+# literal it knows about; this audit is the matching *reader* that fails CI when
+# a new human-authored surface introduces a literal the generator does not yet
+# own, or when someone hand-edits an owned literal out of sync. It scans a
+# bounded set of human-authored surfaces — never lockfiles (``go.sum``,
+# ``pnpm-lock.yaml``), vendored trees, or build output — and reports each
+# ``file:line`` whose SDK-version literal differs from the SoT.
+#
+# Exemption: any line containing the inline marker ``sdk-version-exempt`` is
+# skipped, for legitimate historical / provenance text (e.g. a release note or
+# a "written against 0.0.1-rc.3" verification report).
+
+EXEMPT_MARKER = "sdk-version-exempt"
+
+# Which SDK a prose line refers to, so its version token can be compared against
+# the right SoT entry.
+_PROSE_LABEL_RE = re.compile(r"Agent Assembly (Python|Node\.js|Go) SDK")
+
+# Precise main-SDK pin matchers for the manifest audit. Each captures the pinned
+# version in group ``ver``. The identifiers are anchored so a subpackage
+# (``@agent-assembly/runtime-*``) or a non-``go-sdk`` org path
+# (``github.com/ai-agent-assembly/...``) can never false-match: the python id is
+# ``agent-assembly`` immediately followed by a PEP 440 operator; the node id is
+# exactly ``@agent-assembly/sdk``; the go id is exactly
+# ``github.com/ai-agent-assembly/go-sdk`` followed by whitespace.
+_PY_PIN_AUDIT_RE = re.compile(
+    r"(?<![\w/@.-])agent-assembly(?:==|>=|~=|<=|!=|<|>)(?P<ver>[^\"'\s,]+)"
+)
+_NODE_PIN_AUDIT_RE = re.compile(r'"@agent-assembly/sdk"\s*:\s*"(?P<ver>[^"]+)"')
+_GO_PIN_AUDIT_RE = re.compile(
+    r"github\.com/ai-agent-assembly/go-sdk(?=\s)\s+(?P<ver>\S+)"
+)
+
+# Bounded globs for the pin audit — every manifest that carries a main-SDK pin
+# under python/, node/, go/, and scenarios/. Lockfiles and go.sum are excluded
+# by construction (never globbed).
+_PY_PIN_GLOBS = (
+    "python/*/pyproject.toml",
+    "scenarios/*/pyproject.toml",
+    "scenarios/*/*/pyproject.toml",
+)
+_NODE_PIN_GLOBS = (
+    "node/*/package.json",
+    "scenarios/*/package.json",
+    "scenarios/*/*/package.json",
+)
+_GO_PIN_GLOBS = (
+    "go/*/go.mod",
+    "scenarios/*/go.mod",
+    "scenarios/*/*/go.mod",
+)
+
+
+def _audit_lines(path: Path):
+    """Yield ``(lineno, line)`` pairs for a text file, 1-based."""
+
+    for lineno, line in enumerate(
+        path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        yield lineno, line
+
+
+def _audit_pins(repo_root: Path, versions: SdkVersions) -> list[str]:
+    """Report every manifest/Dockerfile pin whose version drifts from the SoT."""
+
+    checks = (
+        (_PY_PIN_GLOBS, _PY_PIN_AUDIT_RE, versions.python.version),
+        (_NODE_PIN_GLOBS, _NODE_PIN_AUDIT_RE, versions.node.version),
+        (_GO_PIN_GLOBS, _GO_PIN_AUDIT_RE, versions.go.version),
+        (_DOCKERFILE_GLOBS, _DOCKERFILE_PIN_RE, versions.python.version),
+    )
+    problems: list[str] = []
+    for globs, pin_re, expected in checks:
+        for path in _globbed(repo_root, globs):
+            for lineno, line in _audit_lines(path):
+                if EXEMPT_MARKER in line:
+                    continue
+                match = pin_re.search(line)
+                if match and match.group("ver") != expected:
+                    rel = path.relative_to(repo_root)
+                    problems.append(
+                        f"{rel}:{lineno}: pins {match.group('ver')!r}, "
+                        f"expected {expected!r}"
+                    )
+    return problems
+
+
+def _audit_prose(repo_root: Path, versions: SdkVersions) -> list[str]:
+    """Report every README/doc prose line whose SDK version drifts from the SoT.
+
+    Only lines that both name a language SDK (``Agent Assembly <Lang> SDK``) and
+    carry a version token are checked; the token is compared like the rewriter's
+    first-token substitution, so a generator-produced tree always audits clean.
+    """
+
+    expected_by_label = {
+        "Python": versions.python.version,
+        "Node.js": versions.node.version,
+        "Go": versions.go.version,
+    }
+    problems: list[str] = []
+    for path in _globbed(repo_root, _README_GLOBS + ("docs/*.md",)):
+        for lineno, line in _audit_lines(path):
+            if EXEMPT_MARKER in line:
+                continue
+            label_match = _PROSE_LABEL_RE.search(line)
+            if not label_match:
+                continue
+            token_match = _VERSION_TOKEN_RE.search(line)
+            if token_match is None:
+                continue
+            expected = expected_by_label[label_match.group(1)]
+            if token_match.group(0) != expected:
+                rel = path.relative_to(repo_root)
+                problems.append(
+                    f"{rel}:{lineno}: states {token_match.group(0)!r}, "
+                    f"expected {expected!r}"
+                )
+    return problems
+
+
+def audit(repo_root: Path, versions: SdkVersions) -> list[str]:
+    """Return every drifted SDK-version literal as a sorted ``file:line`` list."""
+
+    return sorted(
+        _audit_pins(repo_root, versions) + _audit_prose(repo_root, versions)
+    )
+
+
 # ---------------------------------------------------------------------------
 # CLI
 # ---------------------------------------------------------------------------
@@ -736,9 +878,33 @@ def main(argv: list[str] | None = None) -> int:
         default=_repo_root_from_script(),
         help="Path to the repository root (defaults to the script's parent).",
     )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help=(
+            "Audit mode: do not rewrite. Scan the bounded human-authored "
+            "surfaces and exit non-zero, naming each file:line, if any "
+            "SDK-version literal has drifted from the SoT."
+        ),
+    )
     args = parser.parse_args(argv)
 
     versions = load_sdk_versions(args.repo_root)
+
+    if args.check:
+        problems = audit(args.repo_root, versions)
+        if problems:
+            print("SDK-version literals out of sync with the SoT:")
+            for problem in problems:
+                print(f"  {problem}")
+            print(
+                "\nAlign metadata/sdk-versions.yaml + re-run the generator, or "
+                f"mark legitimate historical text with '{EXEMPT_MARKER}'."
+            )
+            return 1
+        print("--check: every audited surface matches the SoT.")
+        return 0
+
     changed: list[Path] = []
     changed.extend(process_python(args.repo_root, versions))
     changed.extend(process_node(args.repo_root, versions))

From f4cf8544ff48ca0bb109423950ee5049f79fd65a Mon Sep 17 00:00:00 2001
From: Chisanan232 <bulls23mj1991@gmail.com>
Date: Thu, 16 Jul 2026 11:26:51 +0800
Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=94=A7=20(ci):=20Widen=20drift=20path?=
 =?UTF-8?q?s=20and=20run=20the=20audit=20+=20generator=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Trigger the metadata drift lane on scenario go.mod and Dockerfile changes
(newly owned) and on the generator test file, then run the --check audit
and the generator unit tests. permissions stay contents: read; other lanes
untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HMnPRm9T3fdrS4uNYXkzg6
---
 .github/workflows/example-metadata-check.yml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.github/workflows/example-metadata-check.yml b/.github/workflows/example-metadata-check.yml
index af34535..80b0510 100644
--- a/.github/workflows/example-metadata-check.yml
+++ b/.github/workflows/example-metadata-check.yml
@@ -19,7 +19,10 @@ on:
       - "snippets/**"
       - "scenarios/**/pyproject.toml"
       - "scenarios/**/package.json"
+      - "scenarios/**/go.mod"
+      - "scenarios/**/Dockerfile"
       - "scenarios/**/README.md"
+      - "scripts/test_generate_example_metadata.py"
       - ".github/workflows/example-metadata-check.yml"
   push:
     branches:
@@ -60,3 +63,9 @@ jobs:
             echo "::error::  python scripts/extract_snippets.py"
             exit 1
           fi
+
+      - name: Audit for orphan SDK-version literals
+        run: python scripts/generate_example_metadata.py --check
+
+      - name: Run generator unit tests
+        run: python -m unittest scripts.test_generate_example_metadata

From 1d6ff3509bcff48bebab6d5e403bc72a9544cf2a Mon Sep 17 00:00:00 2001
From: Chisanan232 <bulls23mj1991@gmail.com>
Date: Thu, 16 Jul 2026 11:28:34 +0800
Subject: [PATCH 5/6] =?UTF-8?q?=E2=9C=85=20(scripts):=20Test=20bullet/Dock?=
 =?UTF-8?q?erfile=20rewrite=20and=20the=20--check=20audit?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cover, against synthetic tmp trees: bullet rewrite (incl. trailing-note
preservation, no-collision with the table row and generated block),
Dockerfile pin rewrite and its identifier precision + two-level walk bound,
and the audit (in-sync pass, stale manifest/Dockerfile/prose detection,
exemption marker, and subpackage/org-path non-false-match). Adds
scripts/__init__.py so the suite is importable via unittest.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HMnPRm9T3fdrS4uNYXkzg6
---
 scripts/__init__.py                       |   7 +
 scripts/test_generate_example_metadata.py | 223 ++++++++++++++++++++++
 2 files changed, 230 insertions(+)
 create mode 100644 scripts/__init__.py
 create mode 100644 scripts/test_generate_example_metadata.py

diff --git a/scripts/__init__.py b/scripts/__init__.py
new file mode 100644
index 0000000..5d1e02e
--- /dev/null
+++ b/scripts/__init__.py
@@ -0,0 +1,7 @@
+"""Repo tooling package.
+
+Exists so the metadata generator's unit tests are importable as
+``scripts.test_generate_example_metadata`` (``python -m unittest``). The
+generator and snippet extractors are also runnable directly by path, which does
+not depend on this marker.
+"""
diff --git a/scripts/test_generate_example_metadata.py b/scripts/test_generate_example_metadata.py
new file mode 100644
index 0000000..793b7e2
--- /dev/null
+++ b/scripts/test_generate_example_metadata.py
@@ -0,0 +1,223 @@
+"""Unit tests for the SDK-version metadata generator and its --check audit.
+
+These exercise the capabilities added for AAASM-4719/AAASM-4717 in isolation,
+against synthetic trees built in a tmp dir — they never depend on the live repo
+layout, so they stay valid as examples are added or renamed. Run with:
+
+    python -m unittest scripts.test_generate_example_metadata
+"""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from scripts import generate_example_metadata as gen
+
+# A self-contained SoT mirroring metadata/sdk-versions.yaml, so load_sdk_versions
+# resolves the same version literals the real generator aligns to.
+_SOT_YAML = """\
+python:
+  package: "agent-assembly"
+  version: "0.0.1rc5"
+  install_pip: "pip install agent-assembly=={{version}}"
+  install_uv: "uv add agent-assembly=={{version}}"
+
+node:
+  package: "@agent-assembly/sdk"
+  version: "0.0.1-rc.5"
+  install_pnpm: "pnpm add @agent-assembly/sdk@{{version}}"
+  install_npm: "npm install @agent-assembly/sdk@{{version}}"
+  install_yarn: "yarn add @agent-assembly/sdk@{{version}}"
+
+go:
+  module: "github.com/ai-agent-assembly/go-sdk"
+  version: "v0.0.1-rc.5"
+  install: "go get github.com/ai-agent-assembly/go-sdk@{{version}}"
+"""
+
+
+def _write(root: Path, rel: str, content: str) -> Path:
+    path = root / rel
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+class _RepoTestCase(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+        _write(self.root, "metadata/sdk-versions.yaml", _SOT_YAML)
+        self.versions = gen.load_sdk_versions(self.root)
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+
+class BulletRewriteTests(_RepoTestCase):
+    def test_rewrites_stale_bullet_to_sot(self) -> None:
+        path = _write(
+            self.root,
+            "go/README.md",
+            "## Prerequisites\n\n- Go >= 1.26\n- Agent Assembly Go SDK v0.0.1-rc.3\n",
+        )
+        changed = gen.rewrite_prereq_bullet(path, "Go", self.versions.go.version)
+        self.assertTrue(changed)
+        self.assertIn("- Agent Assembly Go SDK v0.0.1-rc.5", path.read_text())
+
+    def test_preserves_trailing_note(self) -> None:
+        path = _write(
+            self.root,
+            "go/README.md",
+            "- Agent Assembly Go SDK v0.0.1-rc.3 (server component only)\n",
+        )
+        gen.rewrite_prereq_bullet(path, "Go", self.versions.go.version)
+        self.assertEqual(
+            path.read_text(),
+            "- Agent Assembly Go SDK v0.0.1-rc.5 (server component only)\n",
+        )
+
+    def test_does_not_touch_table_row(self) -> None:
+        table = "| Agent Assembly Go SDK | v0.0.1-rc.3 |\n"
+        path = _write(self.root, "go/README.md", table)
+        changed = gen.rewrite_prereq_bullet(path, "Go", self.versions.go.version)
+        self.assertFalse(changed)
+        self.assertEqual(path.read_text(), table)
+
+    def test_does_not_touch_generated_block(self) -> None:
+        block = (
+            f"{gen.SDK_BLOCK_BEGIN}\n"
+            "| Agent Assembly Go SDK (`github.com/ai-agent-assembly/go-sdk`) "
+            "| v0.0.1-rc.3 |\n"
+            f"{gen.SDK_BLOCK_END}\n"
+        )
+        path = _write(self.root, "go/README.md", block)
+        changed = gen.rewrite_prereq_bullet(path, "Go", self.versions.go.version)
+        self.assertFalse(changed)
+        self.assertEqual(path.read_text(), block)
+
+
+class DockerfileRewriteTests(_RepoTestCase):
+    def test_rewrites_stale_pin(self) -> None:
+        path = _write(
+            self.root,
+            "scenarios/live/python-agent/Dockerfile",
+            'RUN pip install --no-cache-dir maturin "agent-assembly==0.0.1rc3"\n',
+        )
+        changed = gen.rewrite_dockerfile(path, self.versions.python)
+        self.assertTrue(changed)
+        self.assertIn('"agent-assembly==0.0.1rc5"', path.read_text())
+
+    def test_ignores_node_and_go_identifiers(self) -> None:
+        content = (
+            '"@agent-assembly/sdk": "0.0.1-rc.5"\n'
+            "github.com/ai-agent-assembly/go-sdk v0.0.1-rc.5\n"
+        )
+        path = _write(self.root, "scenarios/live/x/Dockerfile", content)
+        changed = gen.rewrite_dockerfile(path, self.versions.python)
+        self.assertFalse(changed)
+        self.assertEqual(path.read_text(), content)
+
+    def test_walker_is_bounded_to_two_levels(self) -> None:
+        _write(self.root, "scenarios/a/Dockerfile", "x")
+        _write(self.root, "scenarios/a/b/Dockerfile", "x")
+        _write(self.root, "scenarios/a/b/c/Dockerfile", "x")  # too deep, ignored
+        found = {p.relative_to(self.root).as_posix() for p in gen._dockerfiles(self.root)}
+        self.assertEqual(found, {"scenarios/a/Dockerfile", "scenarios/a/b/Dockerfile"})
+
+
+def _in_sync_tree(root: Path) -> None:
+    """Populate a tmp repo whose every audited surface matches the SoT."""
+
+    _write(
+        root,
+        "python/ex/pyproject.toml",
+        'dependencies = [\n    "agent-assembly==0.0.1rc5",\n]\n',
+    )
+    _write(
+        root,
+        "node/ex/package.json",
+        '{\n  "dependencies": {\n    "@agent-assembly/sdk": "0.0.1-rc.5"\n  }\n}\n',
+    )
+    _write(
+        root,
+        "go/ex/go.mod",
+        "require github.com/ai-agent-assembly/go-sdk v0.0.1-rc.5\n",
+    )
+    _write(
+        root,
+        "scenarios/live/python-agent/Dockerfile",
+        'RUN pip install "agent-assembly==0.0.1rc5"\n',
+    )
+    _write(
+        root,
+        "go/README.md",
+        "- Agent Assembly Go SDK v0.0.1-rc.5\n",
+    )
+
+
+class AuditTests(_RepoTestCase):
+    def test_passes_on_in_sync_tree(self) -> None:
+        _in_sync_tree(self.root)
+        self.assertEqual(gen.audit(self.root, self.versions), [])
+
+    def test_detects_stale_manifest_pin(self) -> None:
+        _in_sync_tree(self.root)
+        _write(
+            self.root,
+            "go/ex/go.mod",
+            "require github.com/ai-agent-assembly/go-sdk v0.0.1-rc.3\n",
+        )
+        problems = gen.audit(self.root, self.versions)
+        self.assertEqual(len(problems), 1)
+        self.assertIn("go/ex/go.mod:1", problems[0])
+        self.assertIn("v0.0.1-rc.3", problems[0])
+
+    def test_detects_stale_dockerfile_pin(self) -> None:
+        _in_sync_tree(self.root)
+        _write(
+            self.root,
+            "scenarios/live/python-agent/Dockerfile",
+            'RUN pip install "agent-assembly==0.0.1rc4"\n',
+        )
+        problems = gen.audit(self.root, self.versions)
+        self.assertTrue(
+            any("scenarios/live/python-agent/Dockerfile:1" in p for p in problems)
+        )
+
+    def test_detects_stale_prose(self) -> None:
+        _in_sync_tree(self.root)
+        _write(self.root, "go/README.md", "- Agent Assembly Go SDK v0.0.1-rc.3\n")
+        problems = gen.audit(self.root, self.versions)
+        self.assertEqual(len(problems), 1)
+        self.assertIn("go/README.md:1", problems[0])
+
+    def test_exemption_marker_is_honored(self) -> None:
+        _in_sync_tree(self.root)
+        _write(
+            self.root,
+            "go/ex/go.mod",
+            "require github.com/ai-agent-assembly/go-sdk v0.0.1-rc.3 "
+            "// sdk-version-exempt\n",
+        )
+        self.assertEqual(gen.audit(self.root, self.versions), [])
+
+    def test_ignores_runtime_subpackage_and_org_path(self) -> None:
+        # A node runtime subpackage and the go org path are not the main SDK id;
+        # a stale-looking version on those lines must not trip the audit.
+        _in_sync_tree(self.root)
+        _write(
+            self.root,
+            "node/ex/package.json",
+            '{\n  "dependencies": {\n'
+            '    "@agent-assembly/sdk": "0.0.1-rc.5",\n'
+            '    "@agent-assembly/runtime-linux-x64": "0.0.1-rc.3"\n'
+            "  }\n}\n",
+        )
+        self.assertEqual(gen.audit(self.root, self.versions), [])
+
+
+if __name__ == "__main__":
+    unittest.main()

From cdbf0fe0482f99b52378382de6873607f14b7481 Mon Sep 17 00:00:00 2001
From: Bryant Liu <bulls23mj1991@gmail.com>
Date: Thu, 16 Jul 2026 11:39:51 +0800
Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=97=91=EF=B8=8F=20(scripts):=20Remove?=
 =?UTF-8?q?=20unused=20=5FDOCKERFILE=20constant?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/generate_example_metadata.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/scripts/generate_example_metadata.py b/scripts/generate_example_metadata.py
index db6b8e4..d3835a3 100755
--- a/scripts/generate_example_metadata.py
+++ b/scripts/generate_example_metadata.py
@@ -271,8 +271,6 @@ def _sub(match: re.Match[str]) -> str:
 # future bumps (and the --check audit) cover it. The negative lookbehind anchors
 # the match to the standalone ``agent-assembly`` project name so it can never
 # fire on ``@agent-assembly/sdk`` or ``github.com/ai-agent-assembly/...``.
-_DOCKERFILE = "Dockerfile"
-
 _DOCKERFILE_PIN_RE = re.compile(
     r'(?<![\w/@.-])(?P<pre>agent-assembly==)(?P<ver>[^"\s]+)'
 )