feat(skills): add dependency upgrade audit workflow

[ericksoa]

Summary

Adds a contributor skill that treats dependency upgrades as release-by-release semantic migrations instead of version-only changes. It requires upstream source/test evidence, downstream contract tracing, concern-specific proofs, and a separate immutable-artifact audit before a bump can be called ready.

Changes

• Add nemoclaw-contributor-update-dependencies with a mandatory adjacent-release ledger, source-first contract audit, workaround/removal review, concern ledger, platform/runtime proof requirements, conditional-skip audit, and final-tag revalidation.
• Hard-limit the workflow's mutations to NVIDIA/NemoClaw; dependency repositories, workflows, issues, and pull requests remain read-only.
• Add a deterministic, fail-closed Git ledger collector that resolves exact commits, validates ancestry, preserves annotated/lightweight tag identities and prerelease ordering, records every adjacent range, and refuses to overwrite output.
• Add integration coverage for policy requirements and collector behavior, and register the skill in the contributor catalog.

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 changes an internal contributor skill and its catalog entry; no NemoClaw user-facing product behavior or docs changed.
• 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
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project integration test/skills-frontmatter.test.ts test/dependency-upgrade-skill.test.ts (32 passed); skill validator passed
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable; this adds one standalone contributor skill/collector and focused integration tests without changing runtime or the shared test harness.
• 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)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Aaron Erickson aerickson@nvidia.com

Summary by CodeRabbit

• New Features
  • Added a new contributor skill for end-to-end dependency upgrades with strict evidence and safety boundaries.
  • Introduced deterministic “release ledger” tooling to capture upgrade ranges, commits, and rename/copy evidence.
  • Added an OpenAI agent skill configuration for the dependency-upgrade interface.
  • Updated the skills catalog and guidance counts to include the new capability.
• Documentation
  • Added reference materials covering contract auditing, migration-risk concerns, evidence quality, and release provenance checks.
• Tests
  • Added automated coverage for determinism, prerelease rules, rename evidence, fail-closed behavior, output overwrite protection, and security hardening.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: b27683bb-f11c-45ec-8571-ecb81d86213b

📥 Commits

Reviewing files that changed from the base of the PR and between 632c950 and 4d77f10.

📒 Files selected for processing (4)

• .agents/skills/nemoclaw-contributor-update-dependencies/SKILL.md
• .agents/skills/nemoclaw-contributor-update-dependencies/scripts/collect-release-ledger.py
• test/dependency-upgrade-skill-security.test.ts
• test/dependency-upgrade-skill.test.ts

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

• test/dependency-upgrade-skill-security.test.ts
• test/dependency-upgrade-skill.test.ts
• .agents/skills/nemoclaw-contributor-update-dependencies/SKILL.md
• .agents/skills/nemoclaw-contributor-update-dependencies/scripts/collect-release-ledger.py

---

📝 Walkthrough

Walkthrough

Adds a contributor skill for dependency upgrades, supporting audit and release-ledger references, a hardened Git/GitHub ledger collector, skills-catalog registration, agent configuration, and Vitest coverage for policy, integrity, security, and collector behavior.

Changes

Dependency upgrade contributor skill

Layer / File(s)	Summary
Skill workflow and audit guidance .agents/skills/nemoclaw-contributor-update-dependencies/SKILL.md, .agents/skills/nemoclaw-contributor-update-dependencies/references/*, .agents/skills/nemoclaw-contributor-update-dependencies/agents/openai.yaml, .agents/skills/nemoclaw-skills-guide/SKILL.md	Defines dependency migration boundaries, release-range auditing, downstream contract tracing, concern-ledger records, verification requirements, artifact identity checks, handoff evidence, agent configuration, and catalog registration.
Hardened release-ledger collector .agents/skills/nemoclaw-contributor-update-dependencies/scripts/collect-release-ledger.py	Adds SemVer build metadata, trusted bounded command execution, repository integrity checks, deterministic Git evidence collection, adjacent range construction, and protected JSON output.
GitHub release evidence binding .agents/skills/nemoclaw-contributor-update-dependencies/scripts/collect-release-ledger.py	Validates GitHub identities, release publication states, peeled remote tags, target refs, and remote/local evidence consistency.
Collector behavior validation test/dependency-upgrade-skill.test.ts	Tests policy text, release identities, GitHub evidence, prerelease and build-metadata handling, failure modes, CLI validation, and deterministic output.
Collector security validation test/dependency-upgrade-skill-security.test.ts	Tests repository isolation, unsafe Git configuration rejection, subprocess ceilings, object closure, inert evidence handling, environment controls, inventory limits, and output permissions.

Estimated code review effort: 5 (Critical) | ~100 minutes

Suggested labels: feature

Suggested reviewers: cv, miyoungc

Sequence Diagram(s)

sequenceDiagram
  participant Contributor
  participant CollectorCLI
  participant ReleaseLedgerCollector
  participant GitRepository
  participant GitHubAPI
  Contributor->>CollectorCLI: provide repository and release refs
  CollectorCLI->>ReleaseLedgerCollector: run collection command
  ReleaseLedgerCollector->>GitRepository: validate history and collect local evidence
  GitRepository-->>ReleaseLedgerCollector: return tags, ancestry, commits, and paths
  ReleaseLedgerCollector->>GitHubAPI: validate remote identities and publications
  GitHubAPI-->>ReleaseLedgerCollector: return release and tag evidence
  ReleaseLedgerCollector-->>Contributor: emit deterministic JSON release ledger

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.46% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding a dependency-upgrade audit workflow under skills.
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 feat/dependency-upgrade-skill

---

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

[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. The PR is limited to contributor skill documentation, a local dependency-audit helper, and its deterministic unit/security tests. It does not modify NemoClaw production runtime, deployment, installer/onboarding, sandbox lifecycle, credential/security enforcement, network policy, inference routing, or real assistant flows.

Optional E2E

• None.

New E2E recommendations

• None.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the feat/dependency-upgr... branch remains at 79%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 79a42b9	feat/dependency-upgr... 4d77f10	+/-
src/lib/name-validation.ts	100%	94%	-6%
src/lib/securit...ntial-filter.ts	99%	96%	-3%
src/lib/runner.ts	75%	72%	-3%
src/lib/agent/defs.ts	80%	79%	-1%
src/lib/state/m...-acquisition.ts	81%	80%	-1%
src/lib/state/gateway.ts	91%	93%	+2%
src/lib/security/redact.ts	95%	99%	+4%
src/lib/actions...ge-preflight.ts	74%	89%	+15%

---

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

[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.
Findings: 0 required · 0 warnings · 0 optional suggestions
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.

[coderabbitai]

Actionable comments posted: 1

🤖 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-contributor-update-dependencies/scripts/collect-release-ledger.py:
- Around line 226-252: Preserve metadata for an explicitly targeted prerelease
in the candidate-building flow: when a tag resolves to target_sha and matches
args.to_ref, do not exclude it via the include_prereleases filter. Ensure
endpoint_for_tag supplies the target endpoint’s real version and tagKind, while
retaining the existing prerelease filtering for other tags and the bare fallback
for untagged targets.

🪄 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: e6df73da-10ad-4814-be8e-4ed747973b72

📥 Commits

Reviewing files that changed from the base of the PR and between deed1aa and c1a242e.

📒 Files selected for processing (7)

• .agents/skills/nemoclaw-contributor-update-dependencies/SKILL.md
• .agents/skills/nemoclaw-contributor-update-dependencies/agents/openai.yaml
• .agents/skills/nemoclaw-contributor-update-dependencies/references/contract-audit.md
• .agents/skills/nemoclaw-contributor-update-dependencies/references/release-ledger.md
• .agents/skills/nemoclaw-contributor-update-dependencies/scripts/collect-release-ledger.py
• .agents/skills/nemoclaw-skills-guide/SKILL.md
• test/dependency-upgrade-skill.test.ts

[cjagwani]

Reviewed exact head 9b15830. I cannot approve this authenticated collector yet:

1. High — establish an agent/executable trust boundary. SKILL.md:113-130 ingests upstream-controlled release notes, commits, diffs, source, and tests, while SKILL.md:446-449 says to execute the checkout-local collector. Explicitly treat all upstream content as untrusted evidence, never instructions; verify this collector and every transitive execution surface against refreshed trusted origin/main before execution; resolve reviewed Python/Git/GH executables before consuming that content; and pass gh a minimal allowlisted environment. Add PATH-shim and prompt-injection regressions.

2. Medium — bound output volume, not only elapsed time. collect-release-ledger.py:191-200, 452-477, 576-622, 640-687, 909-913, and 1039-1043 can buffer complete Git histories/object/path inventories and paginated GitHub responses. Stream these sources, enforce explicit byte/record ceilings, terminate on excess, and fail closed with oversized-output tests.

3. Low/Medium — create the private ledger as mode 0600 at creation time. collect-release-ledger.py:1583-1586 uses Path.open('x'), which produces 0644 under a normal umask. Add an umask-independent permission test.

4. Review gate — CodeRabbit is paused and only reviewed c1a242e, 18 first-parent commits behind this head. Require a fresh current-head CodeRabbit review before approval.

The nine-category security pass found no hardcoded secret, shell injection, SSRF, auth bypass, unsafe deserialization, or unauthorized GitHub mutation; the items above are the remaining approval blockers.

[cjagwani]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (2)

test/dependency-upgrade-skill.test.ts (1)

332-413: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Test public contracts instead of exact prose and private parser internals.

Keep only explicitly contractual wording checks. Replace the remaining phrase assertions with structural/validator tests, and test malformed identifiers through the collector CLI with a fake git that proves no Git invocation occurred.

As per path instructions, prefer observable outcomes through the public boundary over source-text or private-shape assertions.

Also applies to: 1319-1338

🤖 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/dependency-upgrade-skill.test.ts` around lines 332 - 413, Refactor the
dependency-upgrade skill tests to assert only explicit public contracts,
replacing non-contractual exact-prose and private-parser-shape checks with
structural or validator behavior tests. Exercise malformed identifiers through
the collector CLI, using a fake git executable to verify validation rejects them
without invoking Git. Apply the same approach to the related assertions around
the additional referenced test range, preserving observable public-boundary
outcomes.

Source: Path instructions

test/dependency-upgrade-skill-security.test.ts (1)

354-382: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Exercise malformed GitHub payloads through the CLI boundary.

The runpy probe calls private validators directly, so it still passes if collect() stops routing GitHub payloads through them. Return the malformed URLs from a fake gh, invoke runCollector(), and assert the CLI fails closed.

As per path instructions, prefer observable outcomes through the public boundary over private-shape 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/dependency-upgrade-skill-security.test.ts` around lines 354 - 382,
Replace the direct runpy calls to private validators in the test “rejects
noncanonical URLs and release URLs bound to another tag” with a fake gh
executable that returns the malformed URL and mismatched release payload. Invoke
runCollector() through the CLI boundary and assert it fails closed with a
nonzero status, preserving coverage for both malformed URL cases and the
release/tag mismatch.

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.

Inline comments:
In
@.agents/skills/nemoclaw-contributor-update-dependencies/scripts/collect-release-ledger.py:
- Around line 1368-1375: Update the remote-tag loop around
require_local_commit_object and the ancestry checks to evaluate whether
commit_sha is within the start_sha..target_sha range before requiring its local
object. Skip absent local commits that are outside the range, while retaining
exact local tag matching via require_exact_local_tag for in-range commits whose
objects are available.
- Around line 1876-1901: Update the file-output branch in main to create a
mode-0600 temporary file in the destination directory, write the payload, and
fsync it before publication. Atomically publish the completed temporary file to
the requested output path using no-replace semantics, and ensure cleanup removes
the temporary file on write, fsync, or publish failure without leaving partial
output at the final path.
- Around line 1285-1328: Apply the existing record and endpoint ceilings before
any per-tag expansion: batch local ref metadata, count SemVer tags during
collection, and reject excess tags before invoking per-tag subprocesses,
github_tag_identity_from_root, or ancestry checks. Update
github_semver_tag_inventory to enforce the SemVer-tag ceiling while processing
paginated refs, before remote tag peeling begins, and preserve duplicate/non-tag
validation.

---

Nitpick comments:
In `@test/dependency-upgrade-skill-security.test.ts`:
- Around line 354-382: Replace the direct runpy calls to private validators in
the test “rejects noncanonical URLs and release URLs bound to another tag” with
a fake gh executable that returns the malformed URL and mismatched release
payload. Invoke runCollector() through the CLI boundary and assert it fails
closed with a nonzero status, preserving coverage for both malformed URL cases
and the release/tag mismatch.

In `@test/dependency-upgrade-skill.test.ts`:
- Around line 332-413: Refactor the dependency-upgrade skill tests to assert
only explicit public contracts, replacing non-contractual exact-prose and
private-parser-shape checks with structural or validator behavior tests.
Exercise malformed identifiers through the collector CLI, using a fake git
executable to verify validation rejects them without invoking Git. Apply the
same approach to the related assertions around the additional referenced test
range, preserving observable public-boundary outcomes.

🪄 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: 9d541be5-c9fc-4039-905c-d75f4db40511

📥 Commits

Reviewing files that changed from the base of the PR and between 26088b1 and 632c950.

📒 Files selected for processing (7)

• .agents/skills/nemoclaw-contributor-update-dependencies/SKILL.md
• .agents/skills/nemoclaw-contributor-update-dependencies/references/contract-audit.md
• .agents/skills/nemoclaw-contributor-update-dependencies/references/release-ledger.md
• .agents/skills/nemoclaw-contributor-update-dependencies/scripts/collect-release-ledger.py
• .agents/skills/nemoclaw-skills-guide/SKILL.md
• test/dependency-upgrade-skill-security.test.ts
• test/dependency-upgrade-skill.test.ts

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

• .agents/skills/nemoclaw-contributor-update-dependencies/references/contract-audit.md
• .agents/skills/nemoclaw-contributor-update-dependencies/SKILL.md

[cjagwani]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cjagwani]

Approving exact head 4d77f100f5fe2afd221a1d15098dfbba444caa72.

All required checks are green; every commit is GitHub-verified; both PR Advisor models report no findings; the exact-head CodeRabbit incremental review has no actionable comments; and all 12 review threads are resolved. Independent re-audit confirms the tag ceiling, absent-object handling, and atomic no-replace publication blockers are fixed. Focused validation passed 51/51 tests plus adversarial mode, symlink, no-replace, and link-failure probes.

The parent-directory fsync observation is non-blocking hardening and does not recreate partial-final publication. This is ready for human merge follow-up.