Skip to content

Commit 02c935e

Browse files
authored
Merge branch 'main' into feat/4630-platform-support-matrix
2 parents bf0c4f6 + 06cff76 commit 02c935e

751 files changed

Lines changed: 67516 additions & 10724 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
2+
<!-- SPDX-License-Identifier: Apache-2.0 -->
3+
4+
# Git and GitHub Access Hard Stop
5+
6+
Use this guardrail from any workflow that runs `git`, `ssh`, or `gh` commands.
7+
8+
If a Git/GitHub command fails because of authentication, authorization, missing credentials, SSO, token scope, SSH key setup, remote access, or push permissions, stop and ask the user to resolve access.
9+
10+
Do **not** work around access failures by:
11+
12+
- switching remote protocols or remotes;
13+
- editing credentials, tokens, or SSH config;
14+
- generating new tokens or SSH keys;
15+
- rewriting remotes to bypass permissions;
16+
- force-pushing or bypassing branch protections/required checks.
17+
18+
Report the exact command, the relevant error output, and the next action needed from the user, then wait.
19+
20+
This hard stop is for access/authentication/authorization problems only. Normal Git workflow problems such as merge conflicts, stale branches, dirty worktrees, or mechanical rebase conflicts should be handled by the relevant workflow. Stop for user guidance only when conflict resolution would change behavior, alter contributor intent, or require a design decision.
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
2+
<!-- SPDX-License-Identifier: Apache-2.0 -->
3+
4+
# PR CI and Automated Review Follow-Up
5+
6+
Use this workflow after creating a PR and after every push to an open PR.
7+
8+
## Watch checks
9+
10+
```bash
11+
PR_NUMBER=${PR_NUMBER:-$(gh pr view --json number -q .number)}
12+
gh pr checks "$PR_NUMBER" --watch
13+
```
14+
15+
Then inspect the settled check state:
16+
17+
```bash
18+
gh pr view "$PR_NUMBER" --json url,statusCheckRollup,comments,reviews,reviewDecision
19+
```
20+
21+
## Inspect automated feedback
22+
23+
Check sticky PR comments and inline review comments from CodeRabbit and the PR Review Advisor:
24+
25+
```bash
26+
gh api "repos/NVIDIA/NemoClaw/issues/${PR_NUMBER}/comments" --paginate \
27+
--jq '.[] | select((.body // "") | test("CodeRabbit|coderabbit|PR Review Advisor|nemoclaw-pr-review-advisor"; "i")) | {author: .user.login, updated_at, body}'
28+
29+
gh api "repos/NVIDIA/NemoClaw/pulls/${PR_NUMBER}/comments" --paginate \
30+
--jq '.[] | select((.body // "") | test("CodeRabbit|coderabbit|PR Review Advisor|nemoclaw-pr-review-advisor"; "i")) | {author: .user.login, path, line, updated_at, body}'
31+
```
32+
33+
## Triage
34+
35+
- **CI failure:** inspect the failing job logs, fix the root cause, rerun relevant local checks, commit, push, and monitor again.
36+
- **CodeRabbit or PR Review Advisor correctness/security/test-coverage finding:** address it when valid, rerun relevant checks, commit, push, and monitor again.
37+
- **Style nits or false positives:** avoid unnecessary churn. Note the rationale in your final report or comment on the PR when reviewer-visible context is useful.
38+
- **Ambiguous, risky, broad, or design-changing feedback:** stop and consult the user before changing code.
39+
40+
Repeat until required CI is green and there are no unresolved actionable CodeRabbit or PR Review Advisor findings, or until the user tells you to stop.
41+
42+
If any follow-up push or `gh`/GitHub query hits SSH, authentication, remote access, authorization, or permission problems, follow [Git and GitHub Access Hard Stop](git-github-hard-stop.md). Do not stop for ordinary merge conflicts or dirty-worktree state; resolve mechanical conflicts in the relevant workflow and ask the user only when resolution would change behavior or contributor intent.

‎.agents/skills/nemoclaw-contributor-create-pr/SKILL.md‎

Lines changed: 93 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: nemoclaw-contributor-create-pr
3-
description: Create GitHub pull requests that follow the NemoClaw PR template. Use when the user wants to create a new PR, submit code for review, open a pull request, or push changes for review. Trigger keywords - create PR, pull request, new PR, submit for review, open PR, push for review.
3+
description: Create GitHub pull requests that follow the NemoClaw PR template, then monitor CI and automated review feedback. Use when the user wants to create a new PR, submit code for review, open a pull request, or push changes for review. Trigger keywords - create PR, pull request, new PR, submit for review, open PR, push for review.
44
---
55

66
# Create GitHub Pull Request
@@ -12,6 +12,11 @@ Create pull requests on the NemoClaw GitHub repository using the `gh` CLI. This
1212
- The `gh` CLI must be authenticated (`gh auth status`).
1313
- You must be in the NemoClaw git repository.
1414
- You must have commits on a branch that is pushed to the remote.
15+
- The PR description must include a valid DCO `Signed-off-by:` declaration, and every commit that will appear in the PR must appear as `Verified` in GitHub.
16+
17+
## Hard Stop: Git, SSH, and Authentication Problems
18+
19+
Follow the shared [Git and GitHub Access Hard Stop](../_shared/git-github-hard-stop.md) guardrail for SSH, authentication, remote access, authorization, or permission failures. Resolve ordinary Git workflow problems such as merge conflicts or dirty worktrees in the current workflow.
1520

1621
## Step 1: Verify Branch State
1722

@@ -35,27 +40,47 @@ Before creating a PR, verify the branch.
3540
git status
3641
```
3742

38-
## Step 2: Run Pre-PR Checks
43+
## Step 2: Choose Efficient Pre-PR Checks
44+
45+
Do not rerun the whole local gate just to create a PR when Git hooks already supplied that evidence.
46+
Use the checks that match the diff and the verification you already have.
3947

40-
Choose checks based on the files changed.
48+
### Hook Evidence
4149

42-
For code changes, run both checks and confirm they pass before proceeding:
50+
If the commits were created normally and the branch was pushed normally, count the installed hooks as verification:
51+
52+
- `pre-commit` runs file fixers, formatters, linters, docs-to-skills dry-run validation, and changed-surface Vitest hooks.
53+
- `commit-msg` runs commitlint.
54+
- `pre-push` runs TypeScript build and type-check gates.
55+
56+
If hooks were skipped with `--no-verify`, were not installed, failed, or you cannot tell whether they ran, run a manual diff-scoped fallback before creating the PR:
4357

4458
```bash
45-
npx prek run --all-files
46-
npm test
59+
npx prek run --from-ref main --to-ref HEAD
4760
```
4861

49-
For doc-only changes, do not run the full test suite unless the docs change requires it.
50-
Run the docs and hook checks instead:
62+
Use `npx prek run --all-files` only when you need a whole-repository baseline, such as changing hook configuration, formatter configuration, generated-check scripts, or other repo-wide validation behavior.
63+
64+
### Targeted Tests
65+
66+
Run the smallest meaningful tests for changed behavior:
67+
68+
- CLI or root `src/`, `bin/`, `scripts/`, or `test/` changes: `npx vitest run --project cli` or the directly affected test file.
69+
- Plugin changes under `nemoclaw/src/`: `npx vitest run --project plugin` or the directly affected plugin test file.
70+
- E2E support changes under `test/e2e-scenario/support-tests/`: `npx vitest run --project e2e-vitest-support`.
71+
- Installer behavior changes: run the relevant installer integration project only when the local environment supports it.
72+
73+
Reserve full `npm test` for broad runtime changes, test harness changes, or cases where targeted coverage is hard to justify.
74+
Do not run the full test suite for doc-only changes unless the docs change code samples or generated behavior in a way that needs runtime validation.
75+
76+
For doc-only changes, run the docs build before opening the PR:
5177

5278
```bash
53-
npx prek run --all-files
5479
npm run docs
5580
```
5681

5782
If a required check fails, fix the issue before creating the PR.
58-
When preparing the PR body for a doc-only change, leave the `npm test` verification box unchecked unless you actually ran it.
83+
When preparing the PR body, check only the verification boxes backed by hooks, manual commands, or CI evidence you actually have.
5984

6085
## Step 3: Push the Branch
6186

@@ -65,7 +90,36 @@ Ensure the branch is pushed to the remote.
6590
git push -u origin HEAD
6691
```
6792

68-
## Step 4: Determine PR Metadata
93+
If the push fails because of SSH, authentication, remote access, authorization, or permission problems, follow [Git and GitHub Access Hard Stop](../_shared/git-github-hard-stop.md). Resolve ordinary non-access Git failures, such as merge conflicts or dirty worktrees, in the current workflow.
94+
95+
## Step 4: Prepare DCO Declaration and Verify GitHub Commits
96+
97+
Before creating the PR, prepare the DCO declaration for the PR body and verify every commit in `main..HEAD`.
98+
This is a hard contributor self-serve gate.
99+
Do not run `gh pr create` until the PR body will include the DCO declaration and every commit passes GitHub verification.
100+
101+
1. **DCO declaration.** The PR body must include a `Signed-off-by:` declaration for the contributor.
102+
Use the contributor's configured Git identity unless the contributor provides a different valid identity.
103+
104+
```bash
105+
git config user.name
106+
git config user.email
107+
```
108+
109+
2. **GitHub verification.** Each pushed commit must appear as verified in GitHub.
110+
Check the commit SHAs from `main..HEAD` with the GitHub API before opening the PR.
111+
112+
```bash
113+
for sha in $(git rev-list main..HEAD); do
114+
gh api "/repos/NVIDIA/NemoClaw/commits/$sha" --jq '.sha + " verified=" + (.commit.verification.verified | tostring) + " reason=" + .commit.verification.reason'
115+
done
116+
```
117+
118+
If the PR body would miss the DCO declaration or any commit is missing GitHub verification, stop.
119+
Tell the contributor to fix the issue before opening a PR.
120+
If force-push is not allowed and the published branch already contains an unverified commit, require a fresh branch and fresh PR with a clean compliant history.
121+
122+
## Step 5: Determine PR Metadata
69123

70124
### Title
71125

@@ -100,14 +154,15 @@ Check the branch name and commit messages for issue references. If an issue exis
100154

101155
### DCO Sign-Off
102156

103-
The PR body must include a DCO sign-off line. Determine the user's name and email from git config:
157+
The PR body must include a DCO sign-off line.
158+
Determine the user's name and email from git config:
104159

105160
```bash
106161
git config user.name
107162
git config user.email
108163
```
109164

110-
## Step 5: Compose the PR Body
165+
## Step 6: Compose the PR Body
111166

112167
Use the exact template structure below. Fill in each section based on the diff (`git diff main...HEAD`). Check the applicable boxes and leave others unchecked. Do not add, remove, or reorganize sections.
113168

@@ -129,8 +184,10 @@ Use the exact template structure below. Fill in each section based on the diff (
129184

130185
## Verification
131186
<!-- Check each item you ran and confirmed. Leave unchecked items you skipped. Doc-only changes do not require npm test unless you ran it. -->
132-
- [ ] `npx prek run --all-files` passes
133-
- [ ] `npm test` passes
187+
- [ ] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub
188+
- [ ] Git hooks passed during commit and push, or `npx prek run --from-ref main --to-ref HEAD` passes
189+
- [ ] Targeted tests pass for changed behavior
190+
- [ ] Full `npm test` passes (broad runtime changes only)
134191
- [ ] Tests added or updated for new or changed behavior
135192
- [ ] No secrets, API keys, or credentials committed
136193
- [ ] Docs updated for user-facing behavior changes
@@ -139,7 +196,7 @@ Use the exact template structure below. Fill in each section based on the diff (
139196
- [ ] New doc pages include SPDX header and frontmatter (new pages only)
140197

141198
---
142-
<!-- DCO sign-off required by CI. Run: git config user.name && git config user.email -->
199+
<!-- DCO sign-off is required in this PR description, and every commit must appear as Verified in GitHub. Run: git config user.name && git config user.email -->
143200
Signed-off-by: {name} <{email}>
144201
```
145202

@@ -151,19 +208,20 @@ Follow these rules when filling in the template:
151208
- **Related Issue:** Include `Fixes #NNN` or `Closes #NNN` if an issue exists. Remove the section entirely if there is no related issue.
152209
- **Changes:** Bullet list of key changes. Be specific — reference file names, commands, or behaviors that changed.
153210
- **Type of Change:** Check exactly one box. Use `[x]` for checked, `[ ]` for unchecked.
154-
- **Verification:** Check only the boxes for steps you actually ran and confirmed passing. Do not check boxes for steps you skipped or did not verify. For doc-only changes, `npm test` is not required; leave it unchecked unless you ran it.
211+
- **Verification:** Check only the boxes for steps you actually ran and confirmed passing, or for Git hooks that passed during normal commit and push. Do not check boxes for steps you skipped or did not verify. The DCO declaration and GitHub verification checkbox is mandatory before PR creation because Step 4 must pass first. For doc-only changes, `npm test` is not required; leave it unchecked unless you ran it.
155212
- **DCO Sign-Off:** Replace `{name}` and `{email}` with values from `git config user.name` and `git config user.email`.
156213

157-
## Step 6: Create the PR
214+
## Step 7: Create the PR
158215

159216
Use `gh pr create` with the `--assignee @me` flag and a HEREDOC for the body to preserve formatting.
217+
Only run this step after Step 4 confirms that the PR body includes the DCO declaration and every commit is GitHub-verified.
160218

161219
```bash
162220
gh pr create \
163221
--title "<type>(<scope>): <description>" \
164222
--assignee "@me" \
165223
--body "$(cat <<'EOF'
166-
<full PR body from Step 5>
224+
<full PR body from Step 6>
167225
EOF
168226
)"
169227
```
@@ -185,20 +243,31 @@ For work-in-progress that is not ready for review:
185243
gh pr create --draft --title "..." --assignee "@me" --body "..."
186244
```
187245

188-
## Step 7: Report the Result
246+
## Step 8: Monitor CI and Review Feedback
247+
248+
After creating the PR, do not stop at the URL. Follow the shared [PR CI and Automated Review Follow-Up](../_shared/pr-follow-up.md) workflow: watch required CI, inspect CodeRabbit and PR Review Advisor feedback, address valid findings, and consult the user when feedback is ambiguous or design-changing.
249+
250+
## Step 9: Report the Result
189251

190-
After the PR is created, display the PR URL as a clickable markdown link:
252+
After the PR is created and the initial CI/reviewer follow-up is handled, display the PR URL as a clickable markdown link and summarize the status:
191253

192254
```text
193255
Created PR [#NNN](https://github.com/NVIDIA/NemoClaw/pull/NNN)
256+
CI: passing/pending/failing
257+
Automated review: no actionable findings / addressed findings / waiting on user
194258
```
195259

196260
## Common Mistakes to Avoid
197261

198-
- **Do not invent your own PR body format.** Use the template from Step 5 exactly.
262+
- **Do not invent your own PR body format.** Use the template from Step 6 exactly.
199263
- **Do not omit sections.** Even if a section is not applicable, keep it with the "Skip if..." comment.
200264
- **Do not check boxes for steps you did not run.** If you did not run `npm run docs`, leave that box unchecked.
201-
- **Do not run the full test suite for doc-only changes by default.** Run docs and hook checks instead, and leave `npm test` unchecked unless you actually ran it.
202-
- **Do not forget the DCO sign-off.** CI will reject the PR without it.
265+
- **Do not rerun hook-covered checks by default.** Normal commit and push hooks are valid verification. Use `npx prek run --from-ref main --to-ref HEAD` as the fallback when hooks were skipped, missing, or uncertain.
266+
- **Do not run the full test suite for doc-only changes by default.** Run the docs build instead, and leave `npm test` unchecked unless you actually ran it.
267+
- **Do not forget the DCO sign-off declaration in the PR body.** CI will reject the PR without it.
268+
- **Do not create PRs with unverified commits.** GitHub must report every PR commit as `Verified` before the PR is opened.
269+
- **Do not rely on maintainers to repair contributor signature history.** If force-push is not allowed and the branch contains an unverified commit, use a fresh branch and fresh PR.
203270
- **Do not forget `--assignee @me`.** Every PR must be assigned to its creator.
204271
- **Do not create PRs from main.** Always use a feature branch.
272+
- **Do not troubleshoot Git/GitHub access in-agent.** If SSH, `gh`, authentication, remote access, authorization, or push permissions fail, stop and ask the user to fix access. Do resolve ordinary merge conflicts and dirty-worktree state when the workflow calls for it.
273+
- **Do not abandon the PR immediately after creation.** Watch CI and automated feedback from CodeRabbit and the PR Review Advisor, address valid findings, and consult the user when feedback is ambiguous.

0 commit comments

Comments
 (0)