Guard release docs tag commands

Author: AbrahamGreenman

scripts/package-runtime-coverage.test.ts

@@ -1148,6 +1148,64 @@ test("validatePackageRuntimeCoverage rejects lightweight release tag workflow co
   );
 });
 
+test("validatePackageRuntimeCoverage rejects unsafe release tag doc commands", async (t) => {
+  const tempDir = await mkdtemp(path.join(tmpdir(), "ray-package-runtime-release-doc-tags-"));
+  t.after(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  const rootPackageJson = path.join(tempDir, "package.json");
+  await writeFile(
+    rootPackageJson,
+    JSON.stringify(
+      {
+        name: "ray-test",
+        packageManager: "bun@1.3.9",
+        engines: {
+          bun: ">=1.3.0",
+        },
+        scripts: {},
+      },
+      null,
+      2,
+    ),
+  );
+  await writeFile(
+    path.join(tempDir, "README.md"),
+    [
+      "# Ray test",
+      "",
+      "```bash",
+      'TAG_CORE="core-v1.2.3"',
+      'TAG_SDK="sdk-v1.2.3"',
+      'git tag "$TAG_CORE"',
+      'git push origin "$TAG_CORE" "$TAG_SDK"',
+      "```",
+      "",
+    ].join("\n"),
+  );
+
+  const summary = await validatePackageRuntimeCoverage({
+    cwd: tempDir,
+    packageJsonPaths: [rootPackageJson],
+  });
+  const diagnostics = summary.results.flatMap((result) => result.diagnostics);
+
+  assert.equal(summary.ok, false);
+  assert.ok(
+    diagnostics.some(
+      (diagnostic) =>
+        diagnostic.code === "runtime_doc_release_lightweight_tag_command" && diagnostic.line === 6,
+    ),
+  );
+  assert.ok(
+    diagnostics.some(
+      (diagnostic) =>
+        diagnostic.code === "runtime_doc_release_tag_push_not_atomic" && diagnostic.line === 7,
+    ),
+  );
+});
+
 test("validatePackageRuntimeCoverage requires bounded quality release gate workflow commands", async (t) => {
   const tempDir = await mkdtemp(path.join(tmpdir(), "ray-package-runtime-quality-timeouts-"));
   t.after(async () => {

scripts/package-runtime-coverage.ts

@@ -70,6 +70,10 @@ const workflowReleaseMainAncestryPattern =
 const workflowIdTokenWritePattern = /^\s*id-token:\s*write\s*$/m;
 const workflowNpmTokenPattern = /NODE_AUTH_TOKEN:\s*\$\{\{\s*secrets\.NPM_TOKEN\s*\}\}/;
 const workflowLightweightReleaseTagCommentPattern = /^\s*#\s*git\s+tag\s+"\$TAG"(?:\s|$)/;
+const releaseTagVariablePattern = /\$(?:\{TAG(?:_(?:CORE|SDK))?\}|TAG(?:_(?:CORE|SDK))?)/;
+const releaseDocGitTagCommandPattern = /^git\s+tag\s+/;
+const releaseDocAnnotatedGitTagCommandPattern = /^git\s+tag\s+(?:-a|--annotate)\b/;
+const releaseDocNonAtomicTagPushPattern = /^git\s+push\s+origin\b/;
 const repoOwnedVpsWorkflowDocPattern =
   /\b(?:GitHub VPS workflow|workflow bootstrap|workflow appends|RAY_ENV_FILE_CONTENTS|repository variables|The deploy workflow)\b/;
 
@@ -2601,6 +2605,32 @@ async function validateRuntimeDoc(
       });
     }
 
+    if (
+      releaseTagVariablePattern.test(line) &&
+      releaseDocGitTagCommandPattern.test(line) &&
+      !releaseDocAnnotatedGitTagCommandPattern.test(line)
+    ) {
+      diagnostics.push({
+        level: "error",
+        code: "runtime_doc_release_lightweight_tag_command",
+        docPath,
+        line: index + 1,
+        message:
+          "Runtime release docs must use annotated git tags in executable examples so operators do not cut lightweight package release tags.",
+      });
+    }
+
+    if (releaseTagVariablePattern.test(line) && releaseDocNonAtomicTagPushPattern.test(line)) {
+      diagnostics.push({
+        level: "error",
+        code: "runtime_doc_release_tag_push_not_atomic",
+        docPath,
+        line: index + 1,
+        message:
+          "Runtime release docs must push package release tags with git push --atomic so linked package tags are not partially published.",
+      });
+    }
+
     if (options.enforceVpsTimeouts && isPipedShellCurl(line) && !hasPipedShellTimeout(line)) {
       diagnostics.push({
         level: "error",