fix(release): synchronize and validate the published agent card version (#520)

Keep Cargo, SKILL and the public agent card version consistent, validate replacements before writes, and verify staged release metadata. Refs #514.

Author: dirvine

.github/release-metadata-policy.json

@@ -15,7 +15,8 @@
       "level": "blocking",
       "inputs": [
         "SKILL.md",
-        "Cargo.toml"
+        "Cargo.toml",
+        ".well-known/agent.json"
       ],
       "modes": {
         "pull_request": "changed_only",

.github/scripts/test_release_metadata.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Offline regressions for the static release card/version contract."""
+
+import importlib.util
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+import unittest
+
+ROOT = Path(__file__).resolve().parents[2]
+VALIDATOR = Path('.github/scripts/validate_release_metadata.py')
+CARD = Path('.well-known/agent.json')
+
+
+class ReleaseCardTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        for name in [VALIDATOR, CARD, Path('Cargo.toml'), Path('SKILL.md'),
+                     Path('scripts/bump-version.sh')]:
+            target = self.root / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(ROOT / name, target)
+        self.policy = json.loads((ROOT / '.github/release-metadata-policy.json').read_text())
+        self.policy['rules'] = {'version_sync': self.policy['rules']['version_sync']}
+        (self.root / '.github/release-metadata-policy.json').write_text(json.dumps(self.policy))
+        spec = importlib.util.spec_from_file_location('validator_fixture', self.root / VALIDATOR)
+        self.validator = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(self.validator)
+        self.version = self.validator.extract_cargo_version('Cargo.toml')
+
+    def validate(self, tag=None, card=None):
+        command = ['python3', str(self.root / VALIDATOR), '--mode', 'release_tag',
+                   '--tag', 'v' + (tag or self.version)]
+        if card:
+            command += ['--agent-card', str(card)]
+        return subprocess.run(command, cwd=self.root, capture_output=True, text=True)
+
+    def test_current_source_and_staged_asset_match_tag(self):
+        staged = self.root / 'release-files/agent.json'
+        staged.parent.mkdir()
+        shutil.copyfile(self.root / CARD, staged)
+        result = self.validate(card=staged)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def test_stale_source_and_staged_asset_are_blocking(self):
+        for staged in [False, True]:
+            with self.subTest(staged=staged):
+                (self.root / CARD).write_text((ROOT / CARD).read_text())
+                target = self.root / ('staged-agent.json' if staged else CARD)
+                card = json.loads((ROOT / CARD).read_text())
+                card['version'] = '0.10.0'
+                target.write_text(json.dumps(card))
+                result = self.validate(card=target if staged else None)
+                self.assertEqual(result.returncode, 1)
+                self.assertIn('Agent card version', result.stdout)
+
+    def test_card_only_pr_change_runs_blocking_rule(self):
+        rule = self.policy['rules']['version_sync']
+        self.assertTrue(self.validator.should_run_rule(
+            rule, 'pull_request', [str(CARD)], self.policy))
+        self.assertEqual(rule['level'], 'blocking')
+
+    def test_bump_preserves_every_other_card_byte_and_checks_new_tag(self):
+        before = (self.root / CARD).read_text()
+        result = subprocess.run(['bash', 'scripts/bump-version.sh', '9.8.7'],
+                                cwd=self.root, capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual((self.root / CARD).read_text(), before.replace(
+            '"version": "' + self.version + '"', '"version": "9.8.7"', 1))
+        self.assertEqual(self.validate(tag='9.8.7').returncode, 0)
+        self.assertEqual(self.validate(tag='9.8.6').returncode, 1)
+
+    def test_bump_accepts_reformatted_json_and_preserves_other_bytes(self):
+        card = json.loads((ROOT / CARD).read_text())
+        # Put another version before the top-level field to catch accidental
+        # first-match replacement in nested objects.
+        card = {'metadata': {'version': 'keep-me'}, **card}
+        for indent, newline in [(None, '\n'), (4, '\n'), ('\t', '\n'), (2, '\r\n')]:
+            with self.subTest(indent=indent, newline=newline):
+                before = json.dumps(card, indent=indent).replace('\n', newline)
+                (self.root / CARD).write_bytes(before.encode('utf-8'))
+                result = subprocess.run(['bash', 'scripts/bump-version.sh', '9.8.7'],
+                                        cwd=self.root, capture_output=True, text=True)
+                self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+                self.assertEqual((self.root / CARD).read_bytes().decode('utf-8'), before.replace(
+                    '"version": "' + self.version + '"', '"version": "9.8.7"', 1))
+                self.assertEqual(self.validate(tag='9.8.7').returncode, 0)
+
+    def test_invalid_card_leaves_every_version_file_unchanged(self):
+        valid = json.loads((ROOT / CARD).read_text())
+        missing_version = dict(valid)
+        del missing_version['version']
+        for card_text in ['{broken json', json.dumps(missing_version),
+                          json.dumps({**valid, 'version': 17}),
+                          '{"version": "0.1.0", "version": "0.2.0"}']:
+            with self.subTest(card_text=card_text):
+                for name in ['Cargo.toml', 'SKILL.md']:
+                    shutil.copyfile(ROOT / name, self.root / name)
+                (self.root / CARD).write_text(card_text)
+                paths = [Path('Cargo.toml'), Path('SKILL.md'), CARD]
+                before = {path: (self.root / path).read_bytes() for path in paths}
+                result = subprocess.run(['bash', 'scripts/bump-version.sh', '9.8.7'],
+                                        cwd=self.root, capture_output=True, text=True)
+                self.assertNotEqual(result.returncode, 0)
+                self.assertEqual({path: (self.root / path).read_bytes() for path in paths},
+                                 before, 'validation failure must not partially bump versions')
+
+    def test_unmatched_version_file_leaves_inputs_unchanged(self):
+        for broken in ['Cargo.toml', 'SKILL.md']:
+            with self.subTest(broken=broken):
+                for name in ['Cargo.toml', 'SKILL.md']:
+                    shutil.copyfile(ROOT / name, self.root / name)
+                (self.root / broken).write_text('no version field here\n')
+                paths = [Path('Cargo.toml'), Path('SKILL.md'), CARD]
+                before = {path: (self.root / path).read_bytes() for path in paths}
+                result = subprocess.run(['bash', 'scripts/bump-version.sh', '9.8.7'],
+                                        cwd=self.root, capture_output=True, text=True)
+                self.assertNotEqual(result.returncode, 0)
+                self.assertEqual({path: (self.root / path).read_bytes() for path in paths},
+                                 before)
+
+
+if __name__ == '__main__':
+    unittest.main()

.github/scripts/validate_release_metadata.py

@@ -74,6 +74,10 @@ def parse_args():
         default=str(DEFAULT_POLICY_PATH),
         help="Path to the JSON policy file",
     )
+    parser.add_argument(
+        "--agent-card",
+        help="Validate a staged release card instead of the source card",
+    )
     return parser.parse_args()
 
 
@@ -344,13 +348,23 @@ def extract_release_windows_bins(path_str):
     return bins
 
 
-def validate_version_sync(rule, state, tag_version=None):
-    skill_path, cargo_path = rule["inputs"]
+def validate_version_sync(rule, state, tag_version=None, agent_card=None):
+    skill_path, cargo_path, card_path = rule["inputs"]
+    card_path = agent_card or card_path
+    card_version = json.loads(read_text(card_path)).get("version")
     skill_version = extract_skill_version(skill_path)
     cargo_version = extract_cargo_version(cargo_path)
 
     fix_hint = "run `just bump-version <X.Y.Z>` to sync every version-bearing file"
 
+    if card_version != cargo_version:
+        state.add(
+            rule["level"],
+            f"Agent card version {card_version!r} does not match Cargo.toml version "
+            f"{cargo_version} — {fix_hint}",
+            card_path,
+        )
+
     if skill_version != cargo_version:
         state.add(
             rule["level"],
@@ -457,7 +471,9 @@ def main():
         print(f"Running {rule_name} ({rule['kind']})")
 
         if rule["kind"] == "version_sync":
-            validate_version_sync(rule, state, tag_version=tag_version)
+            validate_version_sync(
+                rule, state, tag_version=tag_version, agent_card=args.agent_card
+            )
         elif rule["kind"] == "openclaw_bins":
             validate_openclaw_bins(rule, state)
         elif rule["kind"] == "current_release_docs":

.github/workflows/build.yml

@@ -19,6 +19,9 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Test release metadata validation
+        run: python3 .github/scripts/test_release_metadata.py
+
       - name: Validate release metadata (pull request)
         if: github.event_name == 'pull_request'
         run: |

.github/workflows/release.yml

@@ -28,6 +28,9 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Test release metadata validation
+        run: python3 .github/scripts/test_release_metadata.py
+
       - name: Validate release metadata (tag)
         if: startsWith(github.ref, 'refs/tags/v')
         run: |
@@ -493,7 +496,9 @@ jobs:
           cp SKILL.md release-files/
           cp SKILL.md.sig release-files/
           cp SAORSA_PUBLIC_KEY.asc release-files/
-          cp .well-known/agent.json release-files/ 2>/dev/null || true
+          cp .well-known/agent.json release-files/
+          python3 .github/scripts/validate_release_metadata.py \
+            --mode push_main --agent-card release-files/agent.json
           ls -la release-files/
 
       - name: Create GitHub Release

.well-known/agent.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://a2a.foundation/schemas/agent-card.json",
   "name": "x0x",
-  "version": "0.10.0",
+  "version": "0.41.3",
   "description": "Secure computer-to-computer networking for AI agents — gossip broadcast, direct messaging, CRDTs, group encryption. No servers, no intermediaries, no controllers. Post-quantum encrypted, NAT-traversing.",
   "homepage": "https://saorsalabs.com",
   "repository": "https://github.com/saorsa-labs/x0x",

scripts/bump-version.sh

@@ -3,10 +3,10 @@
 # Bump the project version in EVERY file the release `version_sync` gate
 # checks, in one shot, so a release can never fail because one copy was
 # forgotten (the recurring SKILL.md drift that broke the 0.22.1 and 0.23.0
-# tags). The version lives in two hand-maintained places — Cargo.toml's
-# [package] version and SKILL.md's frontmatter — and they MUST agree with the
-# release tag. Always bump via this script (or `just bump-version`) instead of
-# hand-editing either file.
+# tags). The version lives in three hand-maintained places — Cargo.toml's
+# [package] version, SKILL.md's frontmatter, and the static agent card — all
+# MUST agree with the release tag. Always bump via this script (or `just bump-version`) instead of
+# hand-editing these files.
 #
 # Usage: scripts/bump-version.sh <X.Y.Z>
 #
@@ -24,17 +24,75 @@ fi
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
 
-# Cargo.toml: the [package] version is the first line-anchored `version = "..."`.
-perl -i -pe 'if (!$done && /^version = "/) { s/^version = ".*"/version = "'"$VERSION"'"/; $done = 1 }' Cargo.toml
+# Precompute and validate every replacement before writing any version file.
+# This prevents invalid input from leaving a partial bump; it is not a
+# multi-file transaction against write failures or process interruption.
+python3 - "$VERSION" <<'PYTHON'
+import json
+import re
+import sys
+from pathlib import Path
 
-# SKILL.md frontmatter: the first `version: ...` line.
-perl -i -pe 'if (!$done && /^version:\s/) { s/^version:.*/version: '"$VERSION"'/; $done = 1 }' SKILL.md
+version = sys.argv[1]
+path = Path(".well-known/agent.json")
+text = path.read_bytes().decode("utf-8")
+card = json.loads(text)
+if not isinstance(card, dict) or not isinstance(card.get("version"), str):
+    raise SystemExit("Agent card must have a top-level string version")
+
+# Walk only the top-level object with the JSON decoder, so whitespace and
+# nested version fields do not matter. Replace the value's exact source span
+# to preserve every unrelated byte, including the card's existing formatting.
+decoder = json.JSONDecoder()
+
+def skip_space(pos):
+    while pos < len(text) and text[pos] in " \t\r\n":
+        pos += 1
+    return pos
+
+pos = skip_space(0) + 1  # validated top-level opening brace
+spans = []
+while text[skip_space(pos)] != "}":
+    key, pos = decoder.raw_decode(text, skip_space(pos))
+    start = skip_space(skip_space(pos) + 1)  # validated colon
+    _, end = decoder.raw_decode(text, start)
+    if key == "version":
+        spans.append((start, end))
+    pos = skip_space(end)
+    if text[pos] == "}":
+        break
+    pos += 1  # validated comma
+if len(spans) != 1:
+    raise SystemExit("Agent card must have exactly one top-level version")
+start, end = spans[0]
+updated = text[:start] + json.dumps(version) + text[end:]
+card["version"] = version
+if json.loads(updated) != card:
+    raise SystemExit("Cannot safely update agent card top-level version")
+
+replacements = {path: updated}
+for filename, pattern, replacement in [
+    ("Cargo.toml", r'(?m)^version = "[^"\n]*"', f'version = "{version}"'),
+    ("SKILL.md", r'(?m)^version:\s[^\n]*', f'version: {version}'),
+]:
+    path = Path(filename)
+    updated, count = re.subn(
+        pattern, lambda _: replacement, path.read_bytes().decode("utf-8"), count=1
+    )
+    if count != 1:
+        raise SystemExit(f"Cannot safely update version in {filename}")
+    replacements[path] = updated
+
+for path, updated in replacements.items():
+    path.write_bytes(updated.encode("utf-8"))
+PYTHON
 
 echo "Bumped to $VERSION:"
 grep -m1 '^version = ' Cargo.toml | sed 's/^/  Cargo.toml  /'
 grep -m1 '^version:'   SKILL.md   | sed 's/^/  SKILL.md    /'
+python3 -c 'import json; print("  agent.json  version:", json.load(open(".well-known/agent.json"))["version"])'
 
-# Prove the two are now in sync (and consistent with a vX.Y.Z tag) using the
+# Prove all three are now in sync (and consistent with a vX.Y.Z tag) using the
 # same validator the release workflow runs — fail loudly if anything drifted.
 if [[ -f .github/scripts/validate_release_metadata.py ]]; then
     echo