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

[miyoungc]

Summary

This PR makes release-prep docs a small explicit prerequisite before cutting a NemoClaw tag.
Maintainers should run /nemoclaw-contributor-update-docs for vX.Y.Z before release:plan, and regenerate the plan if origin/main changes afterward.

Related Issue

None.

Changes

• Add the explicit /nemoclaw-contributor-update-docs for vX.Y.Z pre-tag invocation to the docs-update skill.
• Add a short pre-tag docs note to nemoclaw-maintainer-evening before it loads cut-release-tag.
• Add the same docs-before-plan precondition to nemoclaw-maintainer-cut-release-tag and the release-train policy reference.
• Add a narrow maintainer-skill policy regression test for the docs-before-plan ordering.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: this updates contributor and maintainer workflow guidance, not user-facing product documentation.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes — latest cleanup commits were pushed with --no-verify per maintainer request; relying on remote CI.
• Targeted tests pass for changed behavior — npm test -- test/maintainer-skills-policy.test.ts
• Full npm test passes (broad runtime changes only)
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — ran npm run docs; it completed successfully, but Fern reported 1 hidden warning, so this is left unchecked.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

• New Features

  • Added a required pre-tag documentation step before generating final release plans.
  • Clarified when release-prep documentation should be run for a versioned release.

• Bug Fixes

  • Prevented release plans from being created too early.
  • Ensured release plans are regenerated if release-related changes land afterward.

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. No E2E is recommended. The changes are limited to maintainer/contributor skill documentation, release-train reference text, and a policy unit test that checks those instructions. They do not affect installer/onboarding, sandbox lifecycle, credentials, security boundaries, network policy, inference routing, deployment, or real assistant user flows.

Optional E2E

• None.

New E2E recommendations

• None.

[github-actions]

E2E Target Recommendation

Required E2E targets: None
Optional E2E targets: None

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

• None. Changes are limited to agent skill documentation/policy text and a non-E2E unit test outside test/e2e/, with no impact on E2E target registry, workflow dispatch machinery, fixtures, live tests, runtime support, or target behavior.

Optional E2E targets

• None.

Relevant changed files

• None.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 337f7c30-42e4-4dca-a79e-108baf86526b

📥 Commits

Reviewing files that changed from the base of the PR and between 778aa60 and 5137b34.

📒 Files selected for processing (5)

• .agents/skills/nemoclaw-contributor-update-docs/SKILL.md
• .agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md
• .agents/skills/nemoclaw-maintainer-evening/SKILL.md
• .agents/skills/nemoclaw-maintainer-policies/references/release-train.md
• test/maintainer-skills-policy.test.ts

✅ Files skipped from review due to trivial changes (3)

• .agents/skills/nemoclaw-contributor-update-docs/SKILL.md
• .agents/skills/nemoclaw-maintainer-evening/SKILL.md
• .agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md

---

📝 Walkthrough

Walkthrough

Maintainer release skill documentation and policy references are updated to require release-prep documentation (via a docs-update command) be merged or explicitly waived before generating the release plan, with regeneration required if merges land afterward. A corresponding policy test is added and an existing test's expected step number is updated.

Changes

Release-Prep Docs Gating

Layer / File(s)	Summary
Contributor docs invocation semantics .agents/skills/nemoclaw-contributor-update-docs/SKILL.md	Clarifies that invoking the docs-update skill for a version is treated as pre-tag release-prep documentation unless that version's tag already exists.
Cut-release-tag hard rules and step gating .agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md	Adds Hard Rules blocking release-plan generation until release-prep docs are merged/waived and requiring regeneration if origin/main changes afterward; Step 1 now checks docs readiness before proceeding.
Evening skill pre-tag docs checklist .agents/skills/nemoclaw-maintainer-evening/SKILL.md	Adds a "Pre-Tag Docs" section requiring the docs-update command before loading cut-release-tag and gating plan capture on merge/waiver.
Release-train policy update .agents/skills/nemoclaw-maintainer-policies/references/release-train.md	Adds a Release-Prep Docs section gating release:plan on docs merge/waiver and requiring plan regeneration on later merges.
Policy test updates test/maintainer-skills-policy.test.ts	Updates an existing assertion's step number and adds a new test validating docs-before-plan ordering and gating text across skill/policy documents.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: chore

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: release tags are gated on pre-tag docs in the skills workflow.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/pretag-release-docs-gate

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Review Advisor (Nemotron Ultra) — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md:
- Line 141: The housekeeping note references the wrong validation step; update
the Step 2 cross-reference in the release-tag instructions so it points to Step
4 instead. Adjust the wording in SKILL.md around the post-tag housekeeping
guidance to keep the sequence consistent with the release flow, without changing
the behavior of the script or the Step 5 guard around the semver tag and
workflow-managed latest.

In @.agents/skills/nemoclaw-maintainer-evening/SKILL.md:
- Line 65: The example path in the maintainer guide still uses the old
release-note naming, which conflicts with the new announcement-notes flow.
Update the “Announcement draft” reference in SKILL.md so it points to the
announcement-notes artifact instead of release-note-draft.md, keeping the
wording consistent with the renamed handoff terminology.
- Line 64: The final handoff summary currently includes “pending” in the Release
docs status line, but that status should only appear before tag confirmation.
Update the final handoff summary wording in SKILL.md to remove “pending” and
keep only merged or waived-with-reason so the post-cut summary reflects resolved
docs gating.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 74cc6819-2a8f-4a94-beb1-27b168cc3b84

📥 Commits

Reviewing files that changed from the base of the PR and between 3a51447 and ddbdd3e.

📒 Files selected for processing (2)

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

[cv]

@miyoungc I think this PR is directionally right: release-prep docs are a real pre-tag condition. Looking at the broader release lifecycle, though, I suggest reshaping the flow around a clear freeze boundary:

prepare → declare ready → freeze/plan → tag candidate → validate → promote lkg

The important sequencing issue is that the current flow generates plan.json first, then starts or merges the docs PR. A docs merge necessarily moves origin/main, and release-cut-tag.sh correctly rejects the old plan because its target SHA is no longer the tip. In other words, the proposed happy path makes the immutable plan stale by design.

I think all mutable readiness work should finish before the final release plan is generated:

• declare cutoff and confirm the complete commit/PR inventory;
• identify open labeled items as post-tag stragglers;
• merge release-prep docs, or record a maintainer waiver and reason;
• record the SHA through which docs were scanned, then review any docs_scan_sha..candidate_sha delta for additional doc impact;
• finish or explicitly waive the checks that we define as pre-tag checks;
• confirm that no further intended merge remains.

Only after those conditions hold should release:plan capture the exact origin/main SHA and produce the confirmation phrase. Plan generation then becomes the commit-freeze boundary, and the actual tag operation stays deliberately boring: revalidate the ref state, receive exact confirmation, push one annotated semver tag, and verify where it peels.

There is also a release-state distinction worth spelling out. NemoClaw currently behaves approximately like:

semver tag → latest/public docs and images → exact-tag validation → lkg

If we keep that model, docs must gate the tag because the tag publishes them, while final exact-tag E2E/QA naturally gates lkg. If instead a semver tag is supposed to mean “fully validated release,” then E2E must also become a pre-tag condition and the surrounding workflows need to change. Either model can work, but the skill should name which one we mean.

Suggested ownership:

1. Put the readiness contract in the canonical nemoclaw-maintainer-policies/references/release-train.md.
2. Let nemoclaw-maintainer-evening orchestrate docs, cutoff, evidence, and waivers before invoking the tag skill.
3. Keep nemoclaw-maintainer-cut-release-tag focused on the frozen plan and mechanical tag transaction; it should consume readiness, not launch a potentially long-running docs PR.
4. If the docs gate is intended to be enforceable rather than advisory prose, capture the docs PR/merge SHA or waiver in a small hash-bound readiness record associated with the plan. Otherwise, describe it accurately as a maintainer policy prerequisite rather than saying the script prevents bypass.
5. Add a policy regression test for the ordering and for pending being a blocking pre-plan state.

Two related findings may be better handled in follow-ups rather than expanding this PR:

• Several tag monotonicity checks currently run only in release-latest-tag.sh, after the immutable semver tag has already been pushed. The safe subset should be preflighted before the push.
• The installed version-tag-sync pre-push hook currently requires a v0.0.x tag to match package.json (currently 0.1.0), while the tag-only release plan forbids version-bump commits. That makes the normal patch-tag path and the normal hook path contradictory. Local pre-push typechecking and ambient signing configuration also leak workstation state into tag creation.

One immediate test detail: test/maintainer-skills-policy.test.ts currently asserts the old “Do not run it before Step 4” wording, while this PR renumbers that guard to Step 5. So the “tests not applicable” statement should be revisited even though the changed files are Markdown.

The short version: complete or waive mutable release prerequisites first, generate the final plan last, then make tag creation deterministic and resumable.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the docs/pretag-release-... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	docs/pretag-release-... 5137b34	+/-
nemoclaw/src/se...cret-scanner.ts	—	100%	—
nemoclaw/src/commands/slash.ts	—	100%	—
nemoclaw/src/bl...eprint/state.ts	—	98%	—
nemoclaw/src/onboard/config.ts	—	98%	—
nemoclaw/src/bl...int/snapshot.ts	—	97%	—
nemoclaw/src/blueprint/ssrf.ts	—	97%	—
nemoclaw/src/bl...print/runner.ts	—	95%	—
nemoclaw/src/co...ration-state.ts	—	94%	—
nemoclaw/src/bl...ate-networks.ts	—	94%	—
nemoclaw/src/index.ts	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the docs/pretag-release-... branch is 69%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	docs/pretag-release-... 5137b34	+/-
src/lib/actions...dbox/rebuild.ts	—	82%	—
src/lib/actions...all/run-plan.ts	—	80%	—
src/lib/state/o...oard-session.ts	—	79%	—
src/lib/shields/index.ts	—	75%	—
src/lib/state/sandbox.ts	—	73%	—
src/lib/onboard...er-gpu-patch.ts	—	69%	—
src/lib/onboard/preflight.ts	—	69%	—
src/lib/actions...licy-channel.ts	—	59%	—
src/lib/policy/index.ts	—	56%	—
src/lib/onboard.ts	—	20%	—

---

_{Updated July 02, 2026 20:17 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[coderabbitai]

🧹 Nitpick comments (1)

test/maintainer-skills-policy.test.ts (1)

89-114: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Test asserts documentation substrings rather than observable maintainer-workflow behavior.

This test (and the file's established pattern) validates markdown prose via toContain/indexOf, which is source-text/implementation-lock-in rather than behavioral verification of the skill's actual runtime effect. Since these are doc-only skill files without executable logic, this may be an accepted convention in this repo, but per path instructions tests should "Prefer observable outcomes through the public boundary over source-text ... assertions." Given the doc-only nature of the underlying skills, this is likely unavoidable here, but worth confirming that no executable readiness-checking logic exists that could be tested more robustly instead.

As per path instructions, **/*.test.{ts,js,mts,mjs,cts,cjs}: "Prefer observable outcomes through the public boundary over source-text, private-shape, or mock-call assertions."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/maintainer-skills-policy.test.ts` around lines 89 - 114, The
maintainer-skills-policy test is asserting markdown substrings and text ordering
in skill docs instead of observable workflow behavior. Update the test around
maintainer release-plan readiness to exercise the public boundary or a runtime
outcome if any executable readiness-checking path exists, using the referenced
`read(...)`/`expect(...)` checks only where no behavioral API is available. If
there is no executable logic behind `nemoclaw-maintainer-evening`,
`cut-release-tag`, or `release-train.md`, keep the doc assertions but narrow
them to the minimum needed and avoid implying behavioral verification.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/maintainer-skills-policy.test.ts`:
- Around line 89-114: The maintainer-skills-policy test is asserting markdown
substrings and text ordering in skill docs instead of observable workflow
behavior. Update the test around maintainer release-plan readiness to exercise
the public boundary or a runtime outcome if any executable readiness-checking
path exists, using the referenced `read(...)`/`expect(...)` checks only where no
behavioral API is available. If there is no executable logic behind
`nemoclaw-maintainer-evening`, `cut-release-tag`, or `release-train.md`, keep
the doc assertions but narrow them to the minimum needed and avoid implying
behavioral verification.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 625d692f-3671-4a0e-93e5-5ffe72e968eb

📥 Commits

Reviewing files that changed from the base of the PR and between 5e042fe and 778aa60.

📒 Files selected for processing (5)

• .agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md
• .agents/skills/nemoclaw-maintainer-evening/SKILL.md
• .agents/skills/nemoclaw-maintainer-policies/references/release-train.md
• .agents/skills/nemoclaw-maintainer-release-notes/SKILL.md
• test/maintainer-skills-policy.test.ts

✅ Files skipped from review due to trivial changes (2)

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

🚧 Files skipped from review as they are similar to previous changes (2)

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

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[miyoungc]

@cv incorporated your feedback and trimmed down. Would you review again?