nemoclaw-maintainer-cut-release-tag

name	nemoclaw-maintainer-cut-release-tag
description	Creates deterministic NemoClaw semver release tags on origin/main, handles release housekeeping, drafts release notes, and verifies the maintainer-published Announcement. Use when cutting a release, tagging a version, shipping a build, creating vX.Y.Z tags, publishing release announcements, or completing release communication.
user_invocable	true

Cut Release Tag

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, draft release notes, then verify the maintainer-published Announcement before final handoff.

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.
• Before asking for release confirmation, satisfy the canonical pre-tag E2E evidence policy for that exact commit.
• 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.
• 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 mark the announcement step complete until the maintainer provides a valid Discussion URL and the published Announcement is verified.
• Follow the shared Git and GitHub Access Hard Stop for SSH, authentication, remote access, authorization, or permission failures.

Workflow

Copy this checklist and update it as you proceed:

Release Progress:
- [ ] Step 1: Generate release plan
- [ ] Step 2: Show plan, E2E evidence, 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: Wait for maintainer-published Announcement
- [ ] Step 8: Verify Announcement and hand off sharing

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:

npm run release:plan -- --bump patch
npm run release:plan -- --bump minor
npm run release:plan -- --bump major

Patch is the default if the maintainer says "yes", "go", or similar without choosing.

The script writes a plan outside the checkout root, for example:

../nemoclaw-release-v0.0.58/plan.json

Step 2: Show Plan, E2E Evidence, 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,
• forbidden operations,
• exact confirmation phrase,
• open issue/PR housekeeping plan for the release label.

For the plan's full origin/main SHA, review .github/workflows/e2e.yaml at that commit and build the evidence ledger required by the canonical pre-tag E2E evidence policy. The workflow is the sole source of truth; do not substitute or maintain a separate release-gating test list.

Before showing the confirmation prompt, present:

• the exact candidate SHA;
• the number of tests with green evidence out of the number required by the workflow;
• each required test mapped to a successful run or job URL and attempt; and
• an itemized maintainer exception for every test without green evidence, including its current result or failure summary and the rationale for proceeding.

Do not ask for the exact phrase until every test has green evidence or an explicit itemized maintainer exception. If origin/main moves or the candidate SHA otherwise changes, regenerate the plan and rebuild the ledger for the new SHA.

Ask the maintainer to paste the exact phrase:

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

Run the cut script with the plan and the maintainer's exact phrase:

npm run release:cut -- --plan <plan.json> --confirm "CONFIRM RELEASE vX.Y.Z <full-origin-main-sha>"

The script verifies a clean worktree, unchanged origin/main, tag availability, target reachability, and remote peeled tag state. It writes:

<release-dir>/cut-result.json

If the script fails because of SSH, authentication, remote access, authorization, or permissions, follow Git and GitHub Access Hard Stop. 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

Run:

npm run release:wait-latest -- --plan <plan.json>

The script waits until vX.Y.Z^{} and latest^{} both peel to the planned commit and verifies lkg did not change from the plan. It writes:

<release-dir>/latest-result.json

If it fails, report the failed workflow/status. Do not manually move latest.

Step 5: Bump Remaining Open Issues/PRs

Move every remaining open issue or PR carrying the released version to the next patch label:

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.

Then verify the released version has no open stragglers:

gh issue list --repo NVIDIA/NemoClaw --state open --label <released-version> --limit 100
gh pr list --repo NVIDIA/NemoClaw --state open --label <released-version> --limit 100

Summarize:

• open issues/PRs bumped to <next-version>;
• any items that need manual maintainer attention.

Step 6: Generate Release-Note Data and Draft Markdown

Collect deterministic release-note input:

npm run release:notes-data -- --plan <plan.json>

This writes:

<release-dir>/notes-data.json

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.

Load and follow nemoclaw-maintainer-release-notes, then use its output as the draft. Save only Markdown, outside the checkout root:

<release-dir>/release-note-draft.md

Before continuing to Step 7, verify the draft has exactly three lead paragraphs, categorized shipped changes, one what-changed-and-why-it-matters bullet with a visible #NNNN link for every included change, and thanks for external contributors only.

Do not create or update a GitHub Discussion.

Step 7: Wait for Maintainer-Published Announcement

Return:

• release tag,
• confirmed release commit,
• plan path and plan hash,
• cut-result.json, latest-result.json, and notes-data.json paths,
• Markdown draft path,
• issue/PR housekeeping summary,
• suggested discussion title: NemoClaw <new-version> is out.

Ask the maintainer to publish the draft in the Announcements Discussion category and return the resulting Discussion URL. Do not create or update the Discussion. Keep Step 7 in progress until the maintainer provides the URL.

Step 8: Verify Announcement and Hand Off Sharing

Before making any network request, reject the maintainer-provided URL unless it exactly matches https://github.com/NVIDIA/NemoClaw/discussions/<positive-integer> with no query string or fragment. Only then open it using a read-only GitHub or web capability and verify:

• the title is NemoClaw <new-version> is out;
• the category is Announcements;
• the body preserves the draft's three lead paragraphs, category headings, every included PR link, comparison URL, and external contributor usernames; formatting-only edits are acceptable;
• the comparison link targets <previous-version>...<new-version> and visible PR links target github.com/NVIDIA/NemoClaw/pull/<number>.

If the Announcement is valid, return its URL with the release artifacts and mark the release workflow complete. Remind the maintainer to share that Discussion URL in the appropriate external channels. Do not create a duplicate Announcement.

Recovery

• Plan generation fails: fix the named precondition, then regenerate the plan.
• origin/main moved after plan generation: regenerate the plan and ask for the new exact confirmation phrase.
• Remote semver tag already exists: stop; do not retag unless the maintainer explicitly starts protected-tag remediation.
• latest workflow fails or times out: report the workflow/status; do not move latest manually.
• latest workflow rejects a rollback: keep latest unchanged, inspect the plan target commit, and regenerate the plan for the current origin/main tip if appropriate.
• lkg changed: stop and escalate to a release admin.
• Post-tag housekeeping fails: report the error and list items still carrying the released label. After the failure is fixed, rerun the same bump command; already-moved items no longer match the source label.
• Announcement is not published yet: keep Step 7 in progress and return the draft path and suggested title; the tag and housekeeping remain complete.
• Announcement title, category, body, or links are wrong: ask the maintainer to edit the existing Discussion, then verify the same URL again. Do not create a replacement. After three failed verification attempts for the same Discussion, stop and escalate to a release admin.
• Announcement cannot be inspected: report the read failure and ask the maintainer to confirm access or provide a public URL; do not mark Step 8 complete.