Nemoclaw Pr Contribution

NemoClaw PR Contribution Recipe

Also apply the shared OSS contribution quality protocol in ../../references/contribution-quality.md. Project-specific instructions below override the shared protocol when they conflict.

For every sweep and replenishment slot, create or refresh the shared durable decision and verification receipt. A queue slot counts only once its independently validated PR is open.

When the user asks to contribute a PR to NemoClaw, pick the next issue, or "follow the recipe", do the following in order. Before making any code changes: set upstream if needed, switch to main, pull from upstream, create the new branch; then implement the fix.

Repo: NVIDIA/NemoClaw - open source stack for running OpenClaw always-on assistants safely with OpenShell. Apache-2.0. Contributions require signed-off commits (git commit -s) and verified (SSH-signed) commits (-S).

Git commands: The agent must run all git commands directly via the integrated terminal. CRITICAL: Before executing or suggesting any sync, checkout, or commit, the agent must run git status and git branch silently to verify the current state. If the local state already matches the target (e.g., already on the correct branch, already up to date with upstream/main), skip the command and proceed immediately to the next step. Never use platform-specific sync widgets if terminal access is available. Always use --no-verify and explicit -m messages on commits to prevent tool-attribution trailers. Apply permission behavior through the selected runtime adapter.

Shared execution guardrails

Apply these rules throughout the recipe:

• Think before coding. Do not silently assume issue scope, reviewer intent, or the right fix direction. If issue comments, PR comments, linked work, or overlapping open PRs point in different directions, stop and resolve that ambiguity before editing code.
• Simplicity first. Ship the smallest change that fixes the reported problem. Do not add new knobs, abstractions, cleanup refactors, or speculative edge-case handling unless the issue or reviewer explicitly calls for them.
• Surgical changes. Touch only the files and lines that trace directly to the issue, failing check, or requested review follow-up. Clean up only fallout caused by your change; do not restyle or "improve" unrelated nearby code.
• Docs-only discipline. If the issue or reviewer frames the work as documentation, onboarding copy, or docs UX, keep the PR docs-only unless a maintainer explicitly asks for runtime behavior. Do not add source, manifest, config, onboarding prompt, or test changes to "prove" a docs clarification. If code behavior looks wrong, call it out as a separate follow-up instead of expanding the PR.
• Test scope discipline. Tests are required for behavior changes, but they are not a license to expand the PR. Do not add tests to docs-only or copy/UX-only changes unless the repo has an explicit docs-test lane or a maintainer asks. Avoid brittle tests that grep markdown wording just to justify a docs change. If extra tests cause CI failures outside the issue scope, narrow or remove those tests instead of debugging accidental scope creep.
• CI failure discipline. Treat failing CI as a real failure to investigate and fix, but first check whether the failing files or behavior belong to the PR's intended scope. If CI fails because the PR drifted into source/tests/runtime changes that the issue did not need, narrow the PR back to scope instead of debugging the extra work.
• Goal-driven execution. Work in a tight verify loop: identify the concrete failure, implement the smallest fix, run the narrowest relevant validation first, then widen if needed. For open PR work, follow: inspect comments/checks/conflicts -> fix -> rebase -> rerun focused validation -> push -> re-read checks/reviews. Leave a short PR comment only after you know whether fresh CodeRabbit/CI work is terminal or still pending.

Workflow order (do in this sequence): 0. Recent merged PR scan - Before picking a new issue, scan the latest 10 merged NemoClaw PRs from other contributors and extract current repo practices (§2.0).

1. Sync / rebase - Keep local code latest: fetch upstream, checkout main, pull. Do this before creating your branch or making any code changes.
2. Create branch - From the updated main, create the feature branch (e.g. fix/NNNNN-short-description). No code changes before the branch exists.
3. Implement - Make only the changes needed for the issue (§4).
4. Build locally - If the project has a build step (e.g. npm run build), run it so the change compiles.
5. Add unit tests - When the change introduces or modifies logic that should be covered, add or extend tests. When existing tests cover the behavior you changed, update their expectations so they match the new behavior.
6. Run unit tests - Run the test suite (e.g. npm test). Fix any failures before committing.
7. Commit and push - Run git commit and git push directly with the correct flags (§5, §6).

1. Set upstream (one-time per clone)

If the user cloned from their fork, add NVIDIA as upstream:

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
git remote add upstream https://github.com/NVIDIA/NemoClaw.git
# or: git remote add upstream git@github.com:NVIDIA/NemoClaw.git
git fetch upstream

1.1 Set up SSH commit signing (one-time per machine)

NVIDIA/NemoClaw requires verified commit signatures (branch protection rule). Use SSH signing with the existing GitHub SSH key:

# Use SSH for commit signing
git config --global gpg.format ssh
git config --global user.signingkey /Users/dejain/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

# Set up local signature verification
echo "deepujain@gmail.com $(cat ~/.ssh/id_ed25519.pub)" > ~/.ssh/allowed_signers
git config --global gpg.ssh.allowedSignersFile /Users/dejain/.ssh/allowed_signers

The same SSH key must also be registered as a Signing Key on GitHub (not just Authentication): https://github.com/settings/ssh/new with Key type = Signing Key.

Once commit.gpgsign is true, all commits (including git rebase --continue) are automatically signed. The -S flag in commit commands below is explicit but redundant when the global setting is on.

2. Pick an issue

• First run the recent merged contributor scan (§2.0). Do not start a new issue from stale mental models; NemoClaw changes quickly, especially around onboarding, installer, policy, E2E, and migrated TypeScript paths.
• Prefer well-scoped issues from NVIDIA/NemoClaw issues.
• Prefer gh for issue and PR discovery. Run gh auth status first. If auth is healthy, use:
  • gh issue list --repo NVIDIA/NemoClaw --state open --limit 100
  • gh issue view <number> --repo NVIDIA/NemoClaw
  • gh pr list --repo NVIDIA/NemoClaw --author deepujain --state open
• Fallback when gh is unavailable or unauthenticated: use web fetch on the GitHub issues and PR list pages, then fetch individual issue pages for details.
• Read the full issue before choosing it. Check the issue body, comments, linked PRs, referenced commits, and any maintainer guidance.
• Treat scope labels as hard gates. Do not branch, edit, or open a PR for an issue labeled needs: triage, needs: design, or needs: unblock until a maintainer removes the gate or explicitly approves the proposed scope and direction. A clear reproduction or seemingly obvious patch does not override the label.
• Do not pick an issue that already has an active PR unless the user explicitly asks you to work on that existing PR. If the issue timeline or linked development shows an open PR for the same fix direction, skip the issue.
• Search beyond the issue number. Before starting, search PRs by issue number, issue title keywords, error text, and touched subsystem/file names. A PR may already exist without mentioning the issue number directly.
• Repeat the collision search immediately before the first push or PR creation. Long builds, full test matrices, and review preparation can give another contributor time to publish the same fix after the initial screen. Fetch upstream, search open PRs again by issue number, title/error text, and affected files, and stop without pushing when new work now owns the issue. Prefer the existing PR when it has equal or stronger coverage.
• Audit merged and closed replacement work, not only open PRs. An issue can remain open after the exact fix merged when the earlier PR used Refs #NNNN instead of Fixes #NNNN. Search merged and closed PRs, referenced commits, and current main; compare the reported behavior and acceptance criteria against the shipped implementation before treating the open issue as available. If current main already contains the fix, skip the issue and record the stale linkage instead of opening a duplicate PR.
• A PR-limit closure does not release claimed work. If a contributor's exact implementation was closed automatically only because they exceeded the repository's open-PR limit, treat the issue as still claimed while their source branch, signed commit, and demonstrated intent remain available. Do not recreate their completed patch under another account merely because the bot closed the PR; wait for the author to reopen after reducing their queue or for a maintainer to explicitly invite replacement work.
• Treat maintainer design feedback as binding. If issue or PR discussion says an approach is wrong for NemoClaw, do not re-open that approach in a fresh PR.
• Check existing open PRs to avoid collisions. Avoid issues that touch the same files or areas as the user's existing open PRs.
• Check all open PRs that touch the same hot files, not just the issue number or the user's PR list. For NemoClaw, files like bin/nemoclaw.js, bin/lib/onboard.js, workflow files, and core tests often have multiple concurrent PRs. Before picking an issue or declaring a PR "clear", search open PRs by file path / subsystem and note overlapping work.
• Fetch issue details if needed to confirm scope.

2.1 Deep batch mode

When the user says "deep batch", "pick 10 good solid issues", or asks for a batch of substantial NemoClaw PRs:

• Default to 10 issues unless the user gives a different count.
• Prefer meaningful product/runtime work over tiny cleanup: CLI behavior, onboarding flows, installer/preflight failures, inference/provider behavior, policy/security posture, workflow correctness, E2E/runtime reliability, performance, or testable bug fixes.
• Avoid typo-only, copy-only, docs-only, label cleanup, trivial dependency bumps, and small test-only issues unless the user explicitly asks for small tickets or the issue is a blocker for a larger flow.
• Do the full issue-overlap screen for every candidate before coding: issue comments, linked PRs, referenced commits, assignees, maintainer comments, open PRs by issue number, open PRs by title keywords, and open PRs touching the same hot files.
• Rank candidates by merge probability and impact. Prefer issues with clear repro/expected behavior, maintainable scope, and a validation path you can actually run locally.
• Run the full PR recipe for each selected issue independently: sync from upstream, branch from current main, implement surgically, validate with focused and broad checks, create a signed commit, push, open the PR, then inspect CI/reviews and act on early feedback.
• If the batch cannot finish in one session, do not switch to vague status. Report an exact table with each candidate as PR opened, in progress, skipped with reason, or not started yet, plus the next concrete action.

2.0 Recent merged contributor scan

Before picking or implementing a new issue, scan the latest merged PRs from other contributors so the fix follows the current repo shape, tools, and validation standard. This is a quick calibration step, not an excuse to copy unrelated code.

Use gh when authenticated:

gh pr list --repo NVIDIA/NemoClaw --state merged --limit 30 \
  --json number,title,author,mergedAt,headRefName,url \
  --jq '[.[] | select(.author.login != "deepujain")][0:10]'

For each of the 10 PRs, inspect files, PR body, review feedback, and comments:

gh pr view <number> --repo NVIDIA/NemoClaw \
  --json number,title,author,mergedAt,body,files,reviews,comments

If the PR touches the same subsystem as the issue candidate, also inspect the diff:

gh pr diff <number> --repo NVIDIA/NemoClaw --patch

Extract these learnings before selecting the final issue:

• Current file locations. Watch for recent migrations such as inference helpers under src/lib/inference/**, onboard support under src/lib/onboard/**, and session state under src/lib/state/**. Do not edit old migrated paths unless the current tree still uses them.
• Validation commands by area. Borrow the latest relevant validation from merged PRs, not just the generic test suite.
• Design patterns. Prefer shared helpers and constants that recent PRs introduced, especially for installer messages, PATH refresh, policy mirroring, gateway/dashboard state, provider credential envs, and E2E job registration.
• Reviewer expectations. Treat recent CodeRabbit and human review fixes as living style guidance: no duplicate helper logic, no hardcoded stale paths, ambient PATH should be preserved in tests, security-sensitive policy/build-context changes need explicit assertions, and workflow changes need static tests.
• Scope discipline. If a recent merged PR already solved the issue candidate or moved the subsystem in a conflicting direction, skip that issue or work on the existing PR instead.
• Testing strategy by subsystem. Record the exact test pattern used by recent merged PRs in the same area: shell syntax/lint for E2E scripts, argv-contract tests for external CLI calls, focused vitest plus typecheck for TS helpers, docs-to-skills plus docs build for docs, and selective E2E when onboard/sandbox/runtime behavior changed.
• PR description shape. Notice how merged PRs explain before/after behavior, issue linkage, changed areas, verification, and known gaps. Mirror that structure in the new PR body.
• Review-response pattern. When merged PRs addressed CodeRabbit or human comments, they usually pushed a targeted fix, mapped the finding to the commit or test that covers it, and kept any follow-up comment short. Use that pattern.
• Quality-gate template shape. Recent project-member merges use the full NemoClaw template, not a short custom body: Type of Change, Quality Gates, DGX Station Hardware Evidence, Verification, sensitive-path review state, skipped/missing CI justification, Verified signatures, and Signed-off-by.
• PR Review Advisor pattern. Treat github-actions PR Review Advisor comments as review input alongside CodeRabbit and humans. Valid findings get a focused fix plus commit/test evidence; false positives or intentional scope boundaries get a concise evidence-backed explanation.

Recent merged PR scan output should influence the work plan and PR body. Mention only the relevant borrowed pattern or validation in the PR, not the whole scan.

3. Sync and create branch (before any code changes)

Do this before making any fixes. Switch to main, update from upstream, then create the feature branch.

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
git fetch upstream
git checkout main
git pull upstream main
git checkout -b fix/NNNNN-short-description

If there are uncommitted changes: git stash push -m "description" then run the commands above, then git stash pop after creating the new branch.

4. Implement (only after the new branch exists)

• Make only the changes needed for the issue.
• NemoClaw uses TypeScript/JavaScript, Python (blueprint), and Shell. Follow existing style and the project's .editorconfig if present.
• Tests: Run the project test suite (§4.1) after making changes. When your change affects behavior that is already covered by tests (e.g. a mapping or CLI output), update the test expectations so they match the new behavior. Add or extend tests when the change introduces or modifies logic that should be covered (e.g. new helper, changed config). Do not leave tests failing or outdated; fix or add tests as part of the same PR.
• Optionally run the installer or smoke steps in a supported environment (e.g. ./install.sh); project is alpha and may have rough edges.
• Do not rely on code reading or AI intuition alone. If the issue is runtime-, environment-, install-, networking-, container-, onboarding-, or integration-sensitive, gather real execution evidence in a matching local or scripted environment before opening or updating a PR.

4.1 Build and test locally (before push or PR)

Run these from the repo root before committing or opening a PR so the change compiles and tests pass.

Build (if you touched TypeScript in nemoclaw/):

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
cd nemoclaw && npm install --ignore-scripts && npm run build && cd ..

Test (always run before push/PR):

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
npm test

This runs node --test test/*.test.js. Fix any build or test failures before committing (§5).

Do not run npm run build:cli and tests that import dist/** in parallel. Many NemoClaw tests import compiled files from dist, so the build must finish before the focused Vitest command starts; otherwise the test can fail on a missing compiled module even when the code is fine.

After TS migration or source-shape refactors, stale untracked generated files in dist can shadow the freshly generated directory declarations. Example: dist/lib/deploy.d.ts can take precedence over dist/lib/deploy/index.d.ts and produce impossible typecheck errors in unrelated tests. If typecheck complains about a type that the rebuilt source/declaration clearly contains, check for untracked stale sibling files with git ls-files and git status --short before editing source. Remove only untracked stale generated artifacts, rebuild with npm run build:cli, then rerun npm run typecheck:cli.

If the full suite reproduces pre-existing unrelated failures in the current environment, do not pretend the suite is green. Record the exact failing files/tests, run the narrowest relevant local validation for the changed area (for example npx vitest run test/cli.test.js), and call out both the scoped passing check and the unrelated failures in the PR body.

For environment-sensitive fixes, the narrowest relevant validation is often not enough by itself. Add at least one realistic check that exercises the reported workflow, such as:

• installer/docs change: run the documented command or smoke script
• onboarding/session bug: run the relevant onboard or resume flow
• container/runtime bug: run the affected shell script or e2e/smoke scenario
• network/policy bug: run the policy or gateway test that reproduces the behavior
• external CLI integration bug: verify the real subcommand contract before trusting a mock. Check the actual tool help/schema (<tool> --help, subcommand help, clap/argparse definitions) or compare against a known-good in-repo call site. If the test double only records argv and exits 0, treat that as arg-construction coverage, not proof that the real CLI accepts the invocation.

If you cannot produce real-environment evidence, say so plainly and do not present the PR as validated.

Use the recent merged PR scan (§2.0) to choose extra validation for the touched area:

• TypeScript CLI / onboard / inference: npm run build:cli, npm run typecheck:cli, focused npx vitest run ..., and npm run source-shape:check when paths/import layout changed.
• Inference model-menu refreshes: preserve explicit default-route invariants such as DEFAULT_CLOUD_MODEL, even when the featured menu order changes. Tests should assert the intended default/fallback model, not blindly follow the first refreshed menu entry.
• Compiled package-contract tests: if a test constructs paths into dist/lib/** or imports compiled output, place it under test/package-contract/** and run npm run build:cli before that focused Vitest command. Top-level test/** and src/** tests should use source boundaries unless the current repo has an explicit exception.
• Package-contract refactor evidence stays behavioral. NemoClaw's zero source-shape budget rejects tests that instrument generated CommonJS modules or assert that old source text is absent. Prove shared-boundary refactors through observable behavior at every built public entrypoint, pair that with focused parser/contract cases for malformed inputs, and rely on the production diff plus source-shape guardrail to show the duplicate implementation was removed.
• Changed test conditional guard: current CI rejects PRs that increase if ( counts in changed test files. Keep new or modified tests linear: split cases, use data tables, helpers without new branch statements, or it.skipIf / it.runIf for environment gates. When this guard fails, run npm run test-conditionals:scan -- --top 25, remove the added conditionals from touched tests, and rerun focused tests plus npm run lint.
• Generated-script test isolation: when a unit test executes a generated shell script, redirect every absolute runtime path into the test fixture, not only the primary output path. Audit secondary config, state, cache, lock, and permission-normalization paths so the test cannot read or mutate /sandbox, a developer machine, or shared CI state. Keep separate assertions for the production literals so isolation does not weaken the path contract.
• Core src/lib/onboard.ts changes: avoid growing the entrypoint; extract new logic into src/lib/onboard/** helpers, add focused unit tests for the helper, and run onboarding/provider state-handoff tests. If the change crosses provider selection, resume, or inference setup, run or explicitly justify skipping the relevant onboard E2E subset.
• External CLI integration (openshell, docker, kubectl, npm, ollama): assert exact argv shape in tests and verify the real CLI contract against help/parser definitions or an existing known-good call site. A mock that only records $@ is not proof the real CLI accepts trailing commands or flags.
• Runtime monkey patches / upstream-shape patches: make the patch fail closed for truly unknown shapes, but also detect when upstream already contains the desired behavior and return an idempotent "already applied" result. Do not rely only on a NemoClaw marker comment or exact full-block match; add a regression test for the upstream-fixed shape.
• Background watchers / subprocess loops: cover timeout, retry, and transient-failure behavior. Do not mark a request permanently handled after a timeout unless the runtime contract proves that is safe.
• Subprocess termination requires observed exit. A successful SIGTERM/SIGKILL request, child error event, or elapsed timeout does not prove the child was reaped; only observed exit does. Do not discard the only ChildProcess handle until exit is confirmed. If bounded cleanup expires or process control errors, return a distinct recoverable state that retains the handle and original failure, and test both no-event and error-event paths.
• Never retry a failed close by descriptor number. POSIX close can consume the original descriptor before reporting failure, allowing that integer to be reused concurrently. Record the first non-EBADF error, continue closing each other originally owned descriptor once, and do not probe or retry the failed integer. Fault-injection tests should perform the real close before throwing so they model this ambiguity without leaking a test descriptor.
• Runtime health probes: validate response shape and protocol semantics, not only HTTP status. Add regression tests for invalid bodies and valid edge cases.
• Formatting-sensitive changes: npm run format:check -- <files> or the repo's current formatter check from recent merged PRs.
• Installer scripts: bash -n scripts/install.sh, focused installer/preflight tests, and copy-paste validation for any documented shell one-liner.
• E2E shell scripts: bash -n test/e2e/<script>.sh, shellcheck test/e2e/<script>.sh when available, git diff --check, test/validate-e2e-coverage.test.ts, and a selective E2E job when the PR changes nightly coverage or real sandbox flows.
• Docs / generated skills: run the docs generator used by the repo, commonly python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user, then npm run docs or make docs when docs build behavior changed. If hooks expect generated dist, run npm run build:cli too.
• GitHub Actions / automation: add or update static workflow tests; verify triggers, permissions, no unsafe interpolation, no unnecessary checkout, shell syntax, and required token permissions such as id-token: write for provenance.
• Policy / blueprint / shields: update validation tests and assert important fields explicitly, not just object presence. For shields or security posture, assert exact owner, mode, lock/chattr state, legacy layout handling, and run the relevant selective E2E when possible.

5. Commit (sign-off required) - the agent runs commit directly

• Sign-off: NemoClaw requires DCO sign-off. Every commit must use -s or --signoff.
• Author and Signed-off-by: GitHub username is deepujain. Use real name and email so both Author and Signed-off-by show Deepak Jain <deepujain@gmail.com> (not "dejain" or the GitHub username). Always use -c user.name="Deepak Jain" -c user.email="deepujain@gmail.com" and --author="Deepak Jain <deepujain@gmail.com>".
• Treat repository Git identity as test-contaminated state. Tests and fixtures can write Test User <test@example.com> into the shared worktree config. After the final test run and immediately before every commit or amend, inspect git config --show-origin --get user.name and user.email, restore them if needed, and still pass the explicit -c user.* plus --author arguments below. Never rely on a previously correct config.
• Message: Clear summary; reference the issue (e.g. Fixes #NNNNN). Use single quotes in shell to avoid zsh history expansion.
• --no-verify is mandatory. This prevents local hooks from adding tool-attribution trailers and skips unavailable pre-commit hooks.
• Commit only the fix files. Do not add or commit any PR_NNNNN_body.md (that file is for copy-paste only).
• Verify after commit: Run git log -1 --format='%B' and remove any tool-attribution trailer before delivery.
• Stop on GitHub no_user. Immediately after each push, query every PR commit through GitHub's commit API. Local %G? = G is insufficient: if GitHub reports verification.verified: false or reason: no_user, do not post a completion/review comment or wait for CI. Correct the author and committer identity, re-sign the affected commit stack, push with lease, and recheck GitHub verification first.

Commit command (agent runs this directly):

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
git add <list of changed files>
git -c user.name="Deepak Jain" -c user.email="deepujain@gmail.com" commit -s -S --no-verify --author="Deepak Jain <deepujain@gmail.com>" -m 'fix(scope): short summary

Fixes #NNNNN'

Amend command (if author, Signed-off-by, or Made-with needs fixing):

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
git -c user.name="Deepak Jain" -c user.email="deepujain@gmail.com" commit --amend --no-verify -S -s --author="Deepak Jain <deepujain@gmail.com>" -m 'fix(scope): short summary

Fixes #NNNNN'

6. Push and open PR - the agent runs push directly

• Push command (agent runs this):

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
git push --no-verify --set-upstream origin <branch>

Use the actual branch name (e.g. fix/66-nim-image-nemotron-3-nano). After a rebase, follow the remote-head preservation procedure in §8.4. Push only with --force-with-lease. If the lease fails, fetch and inspect the remote-only commits before doing anything else. Never use plain --force, and never erase reviewer, maintainer, or automation changes. If the remote already contains an equivalent or stronger fix, adopt that remote head, validate it, and avoid pushing duplicate local commits.

• Open the PR: Prefer gh when authenticated. Run gh auth status first.
• PR create command (preferred):

cd /Users/dejain/nvidia/oss/worktrees/nvidia/nemoclaw
gh pr create --repo NVIDIA/NemoClaw --base main --head deepujain:<branch> --title 'fix: short summary (Fixes #NNNNN)' --body-file PR_NNNNN_body.md

Replace <branch> and #NNNNN with the actual branch and issue number. The agent should run this directly when gh auth status is healthy.

• Fallback if gh auth is broken or unavailable: provide the deep link and PR body path so the user can open it manually.
• Deep link: Always provide a clickable URL that opens the "New PR" page with branches pre-selected: https://github.com/NVIDIA/NemoClaw/compare/main...<github-username>:NemoClaw:<branch>?expand=1 Replace <github-username> with deepujain and <branch> with the actual branch name.
• Post-create CI follow-up: After gh pr create, checks and CodeRabbit often start asynchronously. Immediately run gh pr checks <pr> --repo NVIDIA/NemoClaw and gh pr view <pr> --repo NVIDIA/NemoClaw --json reviews,comments,mergeStateStatus,statusCheckRollup. If checks are pending or queued, wait/poll when practical until they become terminal. If a native scheduler/automation tool is available, create a delayed follow-up for the PR (for example 20-30 minutes later, plus a later retry if still pending) to re-check CI, CodeRabbit, human comments, stale/conflict state, and copy-pr-bot runner gates, then take needed action without waiting for the user. If no scheduler is available, say "CI still rerunning" in the handoff and include the exact PR/checks to revisit.
• Keep publication automation harness-agnostic. Define success through portable Git and GitHub outcomes, not a particular agent runner, checkout layout, or client. Reconcile the canonical main, the exact remote branch, PR state, commit verification, and required checks before reporting delivery. Bind draft-to-ready or equivalent publication transitions to the same verified commit; use bounded recovery, and leave the PR draft for a human when the atomic transition cannot be proved.

7. PR description and handoff

• Create a local file (e.g. PR_NNNNN_body.md) for the PR description; do not commit it. Use it for copy-paste into the GitHub PR description.
• PR title: Include the issue number so the PR links to the issue and is easy to find. Use: fix: short summary (Fixes #66) or fix: short summary (#66). Example: fix: use nvcr.io/nim/nvidia/nemotron-3-nano for NIM local pull (Fixes #66).
• PR body format: Use the current NemoClaw PR template, not a short custom body. Include Summary, Related Issue when applicable, Changes, Type of Change, Quality Gates, Documentation Writer Review, DGX Station Hardware Evidence, Verification, and Signed-off-by: Deepak Jain <deepujain@gmail.com>. Include "Fixes #66" (or Closes #66) in the body only when the PR fully resolves the issue so GitHub auto-closes it on merge; otherwise use Refs #66.
• Documentation Writer Review is revision-bound evidence. After every commit, merge-from-main update, conflict resolution, or maintainer push, rerun or refresh the documentation review and update its head/blob receipt metadata to the latest PR commit. Do this even when the final change is test-only: the receipt attests to the complete final change set, not only the latest file. In the PR body and review comments, say latest PR commit <sha> or cite the SHA directly; do not use current-head or exact-head as revision terminology.
• Assign lifecycle ownership to exact actors. When documenting a multi-process or multi-component boundary, name which actor creates, opens, maps, validates, reads, closes, removes, revokes, terminates, and reaps each resource. Do not collapse parent and child responsibilities into a collective launcher/service claim, and do not describe a control as secure or reliable without naming the implemented mechanism and its recovery path.
• Re-read CodeRabbit's live release block. CodeRabbit can regenerate and overwrite its auto-generated PR-body release notes after a later push or review cycle. After CodeRabbit completes, fetch the live PR body again and verify that the marked release-note block still states concrete controls and failure outcomes accurately; do not trust an earlier local body copy or assume a prior manual correction survived.
• Issue linkage discipline: Use Fixes #NNNN only when the PR fully resolves the issue. Use Refs #NNNN when the PR handles one symptom, a defensive hardening, or a follow-up while the issue should remain open; explain the remaining scope in the PR body.
• Evidence it works is mandatory. Every PR must show concrete validation, not just "looks correct". For normal code changes, include the exact local test/build commands and outcomes. For environment-sensitive fixes, include the real workflow or smoke/e2e evidence that matches the bug report.
• Fill every Quality Gate honestly. Mark whether tests were added, existing tests cover the change, or tests are not applicable with a concrete justification. For sensitive paths, either cite the reviewer/approval link or explicitly say review is pending. For skipped, non-success, or missing CI, name the check and justification or leave it pending rather than implying it passed.
• DGX Station evidence is a real section. For Station/platform changes, include tested commit, profile/scenario, result, and supporting evidence links. For non-Station changes, explicitly mark the fields not applicable instead of deleting the section.
• Use npm run check:diff when hooks are skipped or unavailable. Recent merged PRs cite this as the broad gate substitute for normal pre-commit, commit-msg, and pre-push hooks. Pair it with targeted tests for the changed behavior.
• Before/after evidence is preferred. For runtime bugs, health probes, installer failures, and workflow behavior changes, include a short pre-fix failure and post-fix success signal when feasible. If live repro is unavailable, say what environment was missing and which focused tests exercise the failing contract.
• Writing pass: Before handing off PR_NNNNN_body.md or any PR comment/review reply, run the final prose through the local humanizer-zh skill at /Users/dejain/nvidia/oss/.agents/skills/humanizer-zh/SKILL.md. Keep issue numbers, commands, evidence, and exact claims unchanged.
• Do not open PRs based on AI alone. If you only have code inspection and no meaningful validation, stop and gather evidence before opening the PR.
• After implementing and testing, the agent runs commit and push directly, then creates the PR with gh when auth is available. If PR creation fails because of auth or repo permissions, say that explicitly and provide the deep link plus the local PR body path.

8. Fixing an open PR (conflicts, review feedback, or updates)

When the user shares a PR URL, it means there is something to act on: reviewer comments, CI/CD failures, merge conflicts, or a requested rebase. Always read the PR page first. NemoClaw uses CodeRabbit for automated reviews, so there will almost always be nitpick comments to address. The PR page also shows a conflict banner ("This branch has conflicts that must be resolved") when rebase is needed - always check for it and rebase if present.

If the user shares a PR URL, use that PR. Do not open a second PR for the same issue. Check out the PR branch, make the fix there, commit, and push back to that existing PR unless the user explicitly asks for a replacement branch.

If the user shares a NemoClaw author PR-list URL or says "open NemoClaw PRs/MRs", treat that as a request to sweep every currently open PR for that author in NVIDIA/NemoClaw: list PRs, inspect CodeRabbit, bot, human review comments, CI checks, out-of-date/conflict state, and stale/cancelled statuses for each PR; fix actionable issues on existing branches; push follow-up commits directly; leave short PR status comments; then re-check and report a table with one row per PR. Do not stop at a status-only table. The table is the handoff after action, not a substitute for action. If a pushed fix leaves checks pending, especially CodeRabbit PENDING after a new head commit, do not call the PR clear. Poll when practical, schedule a delayed CI/review follow-up when tooling supports it, or mark the PR as rerunning: CodeRabbit pending with the exact check still open.

At the start of every repeated sweep, reconcile the previous/recent authored PR set with the current open set. A PR that disappeared from the open list must never disappear from the report silently:

• Query its exact state, mergedAt, closedAt, final comments, reviews, and timeline. Do not infer that it merged merely because it is no longer open.
• If it merged, record the merge and capture a new testing, design, review, or workflow pattern only when the evidence is genuinely reusable.
• If it closed without merge, determine why: duplicate/already fixed, superseded by a replacement PR, invalid or expanded scope, policy/signature failure, unresolved CI/review issue, or abandonment. Inspect the linked issue, overlapping PRs, and replacement commit before drawing the conclusion.
• State whether the contribution survived elsewhere. When a maintainer replacement preserves the contributor's authored commit, distinguish that from a direct merge while crediting the resulting merged fix accurately.
• Turn an evidence-backed closure lesson into the smallest durable update at the correct place in this skill, validate it, commit it, and push the skill repository. Do not overfit the skill to one unexplained closure; if there is no reusable lesson, report no skill change needed and the reason.
• Include a short departed-PR reconciliation table before the open-PR sweep table whenever any PR merged or closed since the previous sweep.

Sweep maintenance and replenishment

Treat sweep as both PR maintenance and controlled replenishment, whether it is triggered by the user or by a scheduled task.

• An explicit user pause overrides replenishment. When the user says no new PRs, pause issue selection, branch creation, pushes for unpublished work, and PR creation until the user explicitly resumes them. Continue reconciling departed PRs and maintaining every existing open PR through conflicts, CI, reviews, and base updates. Do not interpret a later sweep or scheduled heartbeat by itself as permission to resume new-PR creation.
• After open-PR maintenance and departed-PR reconciliation, always run the replenishment gateway unless an explicit user pause is active. This applies to manual and scheduled sweeps even when no PR merged since the previous sweep.
• An empty authored-PR queue is not a no-op condition. It is a healthy queue that must proceed to candidate discovery a

…(truncated)