docs(skills): gate release tags on pre-tag docs

.agents/skills/nemoclaw-contributor-update-docs/SKILL.md

@@ -18,6 +18,7 @@ Scan recent git history for commits that affect user-facing behavior and draft d
 - Before a release, to catch any doc gaps.
 - During daily release prep, before opening the release-note docs PR.
 - Before cutting a release tag, so release-note docs land on the same release train.
+- When maintainers run `/nemoclaw-contributor-update-docs for vX.Y.Z`, treat it as pre-tag release-prep docs for `vX.Y.Z` unless the tag already exists.
 - After a release only when maintainers missed the pre-tag docs step and need a catch-up PR.
 - When a contributor asks "what docs need updating?"
 

.agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md

@@ -16,6 +16,8 @@ The release is one annotated semver tag on an already-merged `origin/main` commi
 ## Hard Rules
 
 - Tag only the commit captured in a generated release plan.
+- Do not generate the release plan until release-prep docs are merged or explicitly waived.
+- If `origin/main` changes after plan generation, regenerate the plan before cutting the tag.
 - Ask the maintainer to paste the exact confirmation phrase from the plan before cutting the tag.
 - Push only the semver tag (`vX.Y.Z`) from the agent-controlled step.
 - Never push `latest` or `lkg` from this skill.
@@ -40,6 +42,9 @@ Release Progress:
 
 ### Step 1: Generate Release Plan
 
+Before this step, confirm release-prep docs are merged or explicitly waived.
+Return to `nemoclaw-maintainer-evening` if docs are still pending.
+
 Run exactly one of:
 
 ```bash

.agents/skills/nemoclaw-maintainer-evening/SKILL.md

@@ -40,6 +40,12 @@ node --experimental-strip-types --no-warnings .agents/skills/nemoclaw-maintainer
 
 This lists commits since the last tag, identifies risky areas touched, and suggests QA test focus areas. Format the output as a concise summary the user can paste into the tag annotation or a handoff channel.
 
+## Pre-Tag Docs
+
+Run `/nemoclaw-contributor-update-docs for <version>` before loading `cut-release-tag`.
+The release-prep docs PR must be merged, or explicitly waived with a reason, before `release:plan` captures the release commit.
+If a docs PR or any other intended PR merges after `release:plan`, regenerate the plan before cutting the tag.
+
 ## Step 4: Cut the Tag and Publish Release Notes
 
 Load `cut-release-tag`. The version is already known — default to patch bump, but still show the commit, changelog, post-tag bump plan, and release notes draft for confirmation. NemoClaw releases are tag-based: tag `main`, let the workflow move `latest`, automatically bump remaining open issues/PRs to the next patch label, and prepare the release notes announcement for the maintainer to post.

.agents/skills/nemoclaw-maintainer-policies/references/release-train.md

@@ -17,6 +17,12 @@ Daily release labels coordinate release work. They do not classify issues and th
 - A PR or issue leaves the daily release cycle only when its version label is removed without a replacement.
 - Version labels are pruned after seven days only after durable release history is preserved and no open PR still carries or depends on the old label.
 
+## Release-Prep Docs
+
+Run `/nemoclaw-contributor-update-docs for vX.Y.Z` before generating the final release plan for `vX.Y.Z`.
+Release-prep docs must be merged or explicitly waived before `release:plan` captures the release commit.
+If any merge lands after `release:plan`, generate a fresh plan before cutting the tag.
+
 ## Cutoff
 
 The daily cutoff is the maintainer-defined point where the release tag is prepared.

test/maintainer-skills-policy.test.ts

@@ -86,6 +86,23 @@ describe("maintainer skills follow canonical workflow policy", () => {
     ).toBe(true);
   });
 
+  it("runs release-prep docs before generating the final release plan", () => {
+    const updateDocs = read(".agents/skills/nemoclaw-contributor-update-docs/SKILL.md");
+    const evening = read(".agents/skills/nemoclaw-maintainer-evening/SKILL.md");
+    const release = read(".agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md");
+    const policy = read(".agents/skills/nemoclaw-maintainer-policies/references/release-train.md");
+
+    expect(updateDocs).toContain("/nemoclaw-contributor-update-docs for vX.Y.Z");
+    expect(evening.indexOf("/nemoclaw-contributor-update-docs for <version>")).toBeLessThan(
+      evening.indexOf("Load `cut-release-tag`"),
+    );
+    expect(release).toContain(
+      "Do not generate the release plan until release-prep docs are merged or explicitly waived.",
+    );
+    expect(policy).toContain("Run `/nemoclaw-contributor-update-docs for vX.Y.Z`");
+    expect(policy).toContain("If any merge lands after `release:plan`, generate a fresh plan");
+  });
+
   it("keeps cross-issue sweeping separate from comparator scoring", () => {
     const sweep = read(".agents/skills/nemoclaw-maintainer-cross-issue-sweep/SKILL.md");
     const comparator = read(".agents/skills/nemoclaw-maintainer-pr-comparator/SKILL.md");