From cccdb15481b06b4cb4389e9fe45b96d2e7a88552 Mon Sep 17 00:00:00 2001
From: Ahmed Mohammed <7650147+amElnagdy@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:45:37 +0300
Subject: [PATCH] test: enforce skill version lockstep

---
 CONTRIBUTING.md              | 13 +++++++++++--
 test/relay/package-shape.mjs | 10 ++++++++++
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 50ef48c..dfdc3da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -76,16 +76,25 @@ module names — see `test/relay/index.mjs`) skips the rest of the matrix.
 A changed relay also wants a direct run — `--help` plus a read-only or no-write run against a
 throwaway repo. The full pre-publish list is in [AGENTS.md](AGENTS.md).
 
+Before changing completion detection or `touchedFiles`, read the relevant skill's result contract.
+Exercise clean, pre-dirty, same-dirty-path, dirty-submodule, and git-unavailable worktrees, and assert
+the exact `delegate-relay.result.v1` fields instead of generic success or failure.
+
 ## Shared relay helpers
 
-Shared relay helpers are byte-identical by CI contract. Edit one relay, run
-`node test/relay-parity.mjs`, then paste its helper into the copies the test names.
+Shared relay helpers are byte-identical by contract. Before making them identical, inspect every
+divergent sibling and carry the strongest behavior forward, including bounds and timeouts. Then run
+`node test/relay-parity.mjs` and `node test/relay-smoke.mjs`.
 
 ## Review
 
 One maintainer reviews these and reads the relay line by line. Expect questions about anything the
 verification line claims.
 
+Automated reviewers such as CodeRabbit, Codex, and Greptile are advisory. If one is unavailable,
+rate-limited, or silent, record that and continue; do not wait or retry. Required project gates plus
+maintainer review determine readiness.
+
 Where two pull requests cover the same implementer, this checklist decides — the one that satisfies
 more of it merges. Ties break on verification evidence, then on the earlier claim. The other pull
 request's distinct improvements get pulled in and credited by number in the commit that lands them.
diff --git a/test/relay/package-shape.mjs b/test/relay/package-shape.mjs
index 2f8ea56..fc88891 100644
--- a/test/relay/package-shape.mjs
+++ b/test/relay/package-shape.mjs
@@ -35,6 +35,16 @@ export function runPackageShape(h) {
     h.check(`${dir}: listed in skills.sh.json`, registered.has(dir));
     h.check(`${dir}: in the utility carve-out`, onDiskUtility.includes(dir));
   }
+  const metadataVersions = [...onDiskDelegate, ...onDiskUtility].map((dir) => {
+    const skillFile = join(skillsDir, dir, "SKILL.md");
+    return existsSync(skillFile)
+      ? readFileSync(skillFile, "utf8").match(/^metadata:\r?\n  version:\s*(\S+)\s*$/m)?.[1] ?? "(missing)"
+      : "(missing)";
+  });
+  h.check(
+    "all skill metadata.version values are present and in lockstep",
+    !metadataVersions.includes("(missing)") && new Set(metadataVersions).size === 1,
+  );
   h.check("smoke matrix has no entry without a directory", h.SKILLS.every((s) => onDiskDelegate.includes(`${s}-delegate`)));
   h.check(
     "skills.sh.json has no entry without a directory",