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

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

@@ -1,6 +1,6 @@
 ---
 name: nemoclaw-maintainer-cut-release-tag
-description: Creates deterministic NemoClaw semver release tags on origin/main, handles release housekeeping, and drafts release notes. Use when cutting a release, tagging a version, shipping a build, creating vX.Y.Z tags, or preparing release announcements.
+description: Creates deterministic NemoClaw semver release tags on origin/main after release readiness is frozen, handles release housekeeping, and drafts announcement notes. Use when cutting a release, tagging a version, shipping a build, creating vX.Y.Z tags, or preparing release announcements.
 user_invocable: true
 ---
 
@@ -11,16 +11,19 @@ user_invocable: true
 
 Use the release scripts for normal release operations. Do not run raw `git tag`, `git push`, `gh api`, or version-bump commands by hand for the normal release flow.
 
-The release is one annotated semver tag on an already-merged `origin/main` commit. The GitHub workflow moves `latest`; release admins promote `lkg` manually after validation. After the tag and `latest` are verified, automatically move remaining open issues/PRs from the released version label to the next patch label, then draft release notes for the maintainer to post.
+The release is one annotated semver tag on an already-merged `origin/main` commit. The GitHub workflow moves `latest`; release admins promote `lkg` manually after validation. This skill consumes completed release readiness, generates the final plan as the commit-freeze boundary, pushes the semver tag, verifies `latest`, moves remaining open issues/PRs from the released version label to the next patch label, and drafts announcement notes for the maintainer to post.
 
 ## Hard Rules
 
 - Tag only the commit captured in a generated release plan.
-- Ask the maintainer to paste the exact confirmation phrase from the plan before cutting the tag.
+- Do not generate the release plan until release readiness is complete: docs merged or waived, docs scan delta reviewed, pre-tag checks complete or waived, and no further intended merge remains.
+- Any merge after plan generation invalidates the plan. Regenerate the plan after re-checking readiness against the new candidate SHA.
+- Ask the maintainer to paste the exact confirmation phrase from the final 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.
 - Never move, delete, or force-push an existing remote semver tag unless the maintainer explicitly starts protected-tag remediation.
-- Draft release notes locally. Do not create the GitHub Discussion; the maintainer does that.
+- Do not launch or merge the release-prep docs PR from this skill. Return to `nemoclaw-maintainer-evening` if mutable readiness work remains.
+- Draft announcement notes locally. Do not create the GitHub Discussion; the maintainer does that.
 - Follow the shared [Git and GitHub Access Hard Stop](../_shared/git-github-hard-stop.md) for SSH, authentication, remote access, authorization, or permission failures.
 
 ## Workflow
@@ -29,16 +32,30 @@ Copy this checklist and update it as you proceed:
 
 ```text
 Release Progress:
-- [ ] Step 1: Generate release plan
-- [ ] Step 2: Show plan and exact confirmation phrase
-- [ ] Step 3: Cut the semver tag from the confirmed plan
-- [ ] Step 4: Wait for workflow-managed latest
-- [ ] Step 5: Bump remaining open issues/PRs
-- [ ] Step 6: Generate release-note data and draft Markdown
-- [ ] Step 7: Hand off announcement steps
+- [ ] Step 1: Confirm release readiness and freeze inputs
+- [ ] Step 2: Generate final release plan
+- [ ] Step 3: Show final plan and ask for exact confirmation
+- [ ] Step 4: Cut the semver tag from the confirmed plan
+- [ ] Step 5: Wait for workflow-managed latest
+- [ ] Step 6: Bump remaining open issues/PRs
+- [ ] Step 7: Generate announcement data and draft Markdown
+- [ ] Step 8: Hand off announcement steps
 ```
 
-### Step 1: Generate Release Plan
+### Step 1: Confirm Release Readiness and Freeze Inputs
+
+Before running `release:plan`, confirm the maintainer can report:
+
+- cutoff inventory and post-tag straggler plan;
+- release-prep docs status, either merged with PR and merge SHA or waived with reason;
+- docs scan SHA, current candidate SHA, and the `docs_scan_sha..candidate_sha` delta review;
+- required pre-tag checks, with waiver reasons for any skipped check;
+- confirmation that no further intended merge remains.
+
+If release-prep docs are `pending`, stop before generating the release plan.
+If any mutable release prerequisite is still in progress, return to `nemoclaw-maintainer-evening`.
+
+### Step 2: Generate Final Release Plan
 
 Run exactly one of:
 
@@ -50,20 +67,25 @@ npm run release:plan -- --bump major
 
 Patch is the default if the maintainer says "yes", "go", or similar without choosing.
 
+This is the commit-freeze boundary.
+Do not merge additional PRs after this point.
+If `origin/main` changes after plan generation, discard the stale plan, re-check release readiness, and generate a fresh plan.
+
 The script writes a plan outside the checkout root, for example:
 
 ```text
 ../nemoclaw-release-v0.0.58/plan.json
 ```
 
-### Step 2: Show Plan and Ask for Exact Confirmation
+### Step 3: Show Final Plan and Ask for Exact Confirmation
 
 Read the generated `plan.json` and show the maintainer:
 
 - previous tag,
 - next tag,
 - target `origin/main` commit and headline,
 - plan hash,
+- release readiness summary,
 - forbidden operations,
 - exact confirmation phrase,
 - open issue/PR housekeeping plan for the release label.
@@ -76,7 +98,7 @@ CONFIRM RELEASE vX.Y.Z <full-origin-main-sha>
 
 Do not proceed on a generic "yes" at this step.
 
-### Step 3: Cut the Semver Tag
+### Step 4: Cut the Semver Tag
 
 Run the cut script with the plan and the maintainer's exact phrase:
 
@@ -92,7 +114,7 @@ The script verifies a clean worktree, unchanged `origin/main`, tag availability,
 
 If the script fails because of SSH, authentication, remote access, authorization, or permissions, follow [Git and GitHub Access Hard Stop](../_shared/git-github-hard-stop.md). For other precondition failures, report the failed precondition and use the recovery guidance below. Do not improvise git commands.
 
-### Step 4: Wait for Workflow-Managed `latest`
+### Step 5: Wait for Workflow-Managed `latest`
 
 Run:
 
@@ -108,15 +130,15 @@ The script waits until `vX.Y.Z^{}` and `latest^{}` both peel to the planned comm
 
 If it fails, report the failed workflow/status. Do not manually move `latest`.
 
-### Step 5: Bump Remaining Open Issues/PRs
+### Step 6: Bump Remaining Open Issues/PRs
 
 Move every remaining open issue or PR carrying the released version to the next patch label:
 
 ```bash
 node --experimental-strip-types --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/bump-stragglers.ts <released-version> <next-version>
 ```
 
-This is automatic post-tag housekeeping covered by the release plan and exact confirmation in Step 2. The script creates the next patch label when needed, removes the released-version label, and adds the next-version label to every open straggler. Do not run it before Step 4 verifies both the semver tag and workflow-managed `latest`.
+This is automatic post-tag housekeeping covered by the release plan and exact confirmation in Step 4. The script creates the next patch label when needed, removes the released-version label, and adds the next-version label to every open straggler. Do not run it before Step 5 verifies both the semver tag and workflow-managed `latest`.
 
 Then verify the released version has no open stragglers:
 
@@ -130,9 +152,9 @@ Summarize:
 - open issues/PRs bumped to `<next-version>`;
 - any items that need manual maintainer attention.
 
-### Step 6: Generate Release-Note Data and Draft Markdown
+### Step 7: Generate Announcement Data and Draft Markdown
 
-Collect deterministic release-note input:
+Collect deterministic announcement input:
 
 ```bash
 npm run release:notes-data -- --plan <plan.json>
@@ -146,20 +168,21 @@ This writes:
 
 If `notes-data.json` has `status: "partial"` or non-empty `pullRequestWarnings`, report the warnings and ask the maintainer whether to fetch/fill the missing PR metadata before drafting.
 
-Draft release notes from `notes-data.json` using the style from `nemoclaw-maintainer-release-notes`. Save only Markdown, outside the checkout root:
+Draft announcement notes from `notes-data.json` using the style from `nemoclaw-maintainer-release-notes`. Save only Markdown, outside the checkout root:
 
 ```text
-<release-dir>/release-note-draft.md
+<release-dir>/announcement-notes-draft.md
 ```
 
 Do not create or update a GitHub Discussion.
 
-### Step 7: Hand Off Announcement
+### Step 8: Hand Off Announcement
 
 Return:
 
 - release tag,
 - confirmed release commit,
+- release readiness summary, including docs status and docs scan delta review,
 - plan path and plan hash,
 - `cut-result.json`, `latest-result.json`, and `notes-data.json` paths,
 - Markdown draft path,

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

@@ -1,12 +1,12 @@
 ---
 name: nemoclaw-maintainer-evening
-description: Runs the end-of-day maintainer handoff for NemoClaw. Checks version target progress, records stragglers for an automatic post-tag bump, generates a QA handoff summary, and cuts the release tag. Use at the end of the workday. Trigger keywords - evening, end of day, EOD, wrap up, ship it, cut tag, handoff, done for the day.
+description: Runs the end-of-day maintainer handoff for NemoClaw. Checks version target progress, records stragglers for an automatic post-tag bump, completes pre-plan release readiness, and cuts the release tag. Use at the end of the workday. Trigger keywords - evening, end of day, EOD, wrap up, ship it, cut tag, handoff, done for the day.
 user_invocable: true
 ---
 
 # NemoClaw Maintainer Evening
 
-Wrap up the day: check progress, identify stragglers, summarize for QA, cut the tag, automatically bump stragglers to the next patch, and prepare release notes for posting.
+Wrap up the day: check progress, identify stragglers, summarize for QA, complete pre-plan release readiness, cut the tag, automatically bump stragglers to the next patch, and prepare announcement notes for posting.
 
 See [PR-REVIEW-PRIORITIES.md](../nemoclaw-maintainer-day/PR-REVIEW-PRIORITIES.md) for the daily cadence.
 
@@ -30,7 +30,7 @@ gh issue list --repo NVIDIA/NemoClaw --state open --label <version> --limit 100
 
 List open labeled PRs and issues as the post-tag housekeeping plan. Tell the maintainer that, after the tag and workflow-managed `latest` are verified, `cut-release-tag` will automatically move all of them to the next patch label.
 
-If an item should leave the daily release flow instead of moving forward, remove it from the released-version label before asking for the release confirmation phrase.
+If an item should leave the daily release flow instead of moving forward, remove it from the released-version label before declaring release readiness.
 
 ## Step 3: Generate Handoff Summary
 
@@ -40,31 +40,54 @@ 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.
 
-## Step 4: Cut the Tag and Publish Release Notes
+## Step 4: Complete Pre-Plan Release Readiness
 
-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.
+Load `nemoclaw-contributor-update-docs` for the release version before generating the final release plan.
+This can run while final E2E validation finishes.
+The release docs PR should use the release label being prepared, such as `v0.0.73`, and should land before `release:plan` captures the frozen candidate SHA unless the maintainer explicitly records a docs waiver.
 
-## Step 5: Confirm and Share
+Report one of these docs statuses before continuing:
 
-After the tag is cut and release notes are drafted or posted by the maintainer, present the final summary:
+- `merged`: release-prep docs landed for `<version>`.
+- `pending`: release-prep docs PR is open and must finish before the final release plan.
+- `waived`: maintainer explicitly accepted tagging without pre-tag docs and gave the reason.
+
+Stop on `pending`.
+When docs are `merged` or `waived`, record the docs scan SHA, the current candidate SHA, and whether the `docs_scan_sha..candidate_sha` delta has additional docs impact.
+Also confirm that all required pre-tag checks are complete or explicitly waived, and that no further intended merge remains.
+
+## Step 5: Freeze the Plan, Cut the Tag, and Publish Announcement Notes
+
+Load `cut-release-tag` only after release readiness is complete.
+The version is already known.
+Default to patch bump, but still show the commit, changelog, release-readiness status, post-tag bump plan, and announcement 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 announcement for the maintainer to post.
+
+## Step 6: Confirm and Share
+
+After the tag is cut and announcement notes are drafted or posted by the maintainer, present the final summary:
 
 - **Tag**: `v0.0.8` at commit `abc1234`
-- **Release notes draft**: `../nemoclaw-release-v0.0.8/release-note-draft.md`
+- **Release docs**: merged or waived with reason
+- **Readiness freeze**: docs scan SHA, candidate SHA, and delta review status
+- **Announcement draft**: `../nemoclaw-release-v0.0.8/announcement-notes-draft.md`
 - **Shipped**: 4 items (#1234, #1235, #1236, #1237)
 - **Bumped to v0.0.9**: 1 item (#1238 — still needs CI fix)
 - **QA focus areas**: installer changes, new onboard preset
 
 This summary can be shared in the team's handoff channel.
 
-## Step 6: Update State
+## Step 7: Update State
 
 ```bash
 node --experimental-strip-types --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/state.ts history "tag-cut" "<version>" "shipped N items, bumped M"
 ```
 
 ## Notes
 
-- Never cut a tag or hand off release notes without user confirmation.
+- Never cut a tag or hand off announcement notes without user confirmation.
+- Never generate the final release plan until release-prep docs are merged or explicitly waived and no further intended merge remains.
+- If any merge lands after plan generation, return to Step 4, re-check readiness, and generate a fresh plan.
 - If nothing was labeled or nothing shipped, ask whether to skip the tag today.
 - A PR version label activates release work; it is not a readiness claim.
 - If an open item misses the tag, post-tag housekeeping moves its target to the next patch version.

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

@@ -17,6 +17,22 @@ 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 Lifecycle
+
+NemoClaw uses this release sequence:
+
+```text
+prepare -> declare ready -> freeze/plan -> tag candidate -> validate -> promote lkg
+```
+
+The semver tag publishes the release candidate, including public docs and release artifacts.
+Release-prep docs therefore gate the semver tag.
+Exact-tag E2E and QA validation gate `lkg` promotion unless maintainers explicitly choose a different release model.
+
+The release plan is the commit-freeze boundary.
+All mutable release readiness work must finish before `release:plan` captures the final `origin/main` SHA.
+Any merge after plan generation invalidates the plan and requires maintainers to re-check readiness against the new candidate SHA before generating a fresh plan.
+
 ## Cutoff
 
 The daily cutoff is the maintainer-defined point where the release tag is prepared.
@@ -26,9 +42,23 @@ At cutoff:
 1. List merged PRs carrying the target version label.
 2. Confirm each is intended for the release.
 3. List open PRs and issues still carrying the target label as post-tag stragglers.
-4. Generate QA handoff from merged PRs.
-5. Cut the release tag only with explicit maintainer confirmation.
-6. After the tag and workflow-managed `latest` are verified, automatically move every open straggler to the next patch label.
+4. Merge release-prep docs, or record a maintainer waiver with the reason.
+5. Record the SHA through which docs were scanned and review any `docs_scan_sha..candidate_sha` delta for additional docs impact.
+6. Finish or explicitly waive every pre-tag check required for the release.
+7. Confirm that no further intended merge remains.
+8. Generate the final release plan for the current `origin/main` SHA.
+9. Cut the release tag only with explicit maintainer confirmation from the final plan.
+10. After the tag and workflow-managed `latest` are verified, automatically move every open straggler to the next patch label.
+
+Release readiness is complete only when the maintainer can report:
+
+- the cutoff inventory and post-tag straggler plan;
+- release-prep docs status, either merged with PR and merge SHA or waived with reason;
+- docs scan SHA and candidate SHA delta review;
+- pre-tag check status, including waivers and reasons;
+- confirmation that no further intended merge remains before plan generation.
+
+If release-prep docs are still pending, stop before generating the release plan.
 
 ## Carry Forward
 

.agents/skills/nemoclaw-maintainer-release-notes/SKILL.md

@@ -148,7 +148,7 @@ Keep the prose warm and polished, but concrete. Tie the narrative to actual PRs
 Create a Markdown draft outside the checkout root so the repo stays clean, for example:
 
 ```bash
-../nemoclaw-<current-version>-release-note-draft.md
+../nemoclaw-<current-version>-announcement-notes-draft.md
 ```
 
 The Markdown body is the source the maintainer can paste into GitHub Discussions.