Skip to content
Merged
Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
c1a242e
feat(skills): add dependency upgrade audit workflow
ericksoa Jul 13, 2026
9a0809a
fix(skills): preserve explicit prerelease targets
ericksoa Jul 13, 2026
e749998
docs(skills): document release ledger collector
ericksoa Jul 13, 2026
26088b1
docs(skill): require observed matrix execution
ericksoa Jul 13, 2026
fbfc79d
docs(skill): harden dependency migration audits
ericksoa Jul 13, 2026
b261938
docs(skill): bind runtime and verifier identities
ericksoa Jul 13, 2026
7774863
test(skill): pin dependency audit trust boundaries
ericksoa Jul 13, 2026
6415c0b
docs(skill): recurse through producer builders
ericksoa Jul 13, 2026
2d9f514
docs(skill): verify automatic migration postconditions
ericksoa Jul 13, 2026
32083fd
fix(skill): preserve exact SemVer identities
ericksoa Jul 13, 2026
38232ca
fix(skill): order rebuild tags by ancestry
ericksoa Jul 13, 2026
aeb0610
fix(skill): bind dependency release evidence
ericksoa Jul 13, 2026
fe080ca
fix(skill): bind dependency evidence to upstream refs
ericksoa Jul 13, 2026
e0dbc87
fix(skill): harden dependency release evidence
ericksoa Jul 13, 2026
211b146
chore(skill): merge current NemoClaw main
ericksoa Jul 13, 2026
154edca
docs(skill): harden dependency migration rollback audits
ericksoa Jul 13, 2026
0e156b5
test(skill): keep dependency tests branch-free
ericksoa Jul 13, 2026
a1d83fe
fix(skill): restrict release ledger API host
ericksoa Jul 13, 2026
9b15830
fix(skills): keep audit contract phrase contiguous
ericksoa Jul 13, 2026
087de9b
fix(skill): harden release ledger execution
ericksoa Jul 13, 2026
e525d5e
Merge remote-tracking branch 'origin/main' into feat/dependency-upgra…
ericksoa Jul 13, 2026
918251a
test(skill): avoid scanner-ambiguous races
ericksoa Jul 13, 2026
632c950
Merge remote-tracking branch 'origin/main' into feat/dependency-upgra…
ericksoa Jul 13, 2026
4d77f10
fix(skills): bound tag collection and ledger publish
ericksoa Jul 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
307 changes: 307 additions & 0 deletions .agents/skills/nemoclaw-contributor-update-dependencies/SKILL.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

interface:
display_name: "Upgrade Dependencies"
short_description: "Audit dependency migrations across releases"
default_prompt: "Use $nemoclaw-contributor-update-dependencies to audit and implement this dependency upgrade end to end."
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Contract audit

Use this reference to find migration risk that version searches and existing tests miss.

## Risk surfaces

| Surface | Inspect upstream | Trace downstream | Silent failure examples |
|---|---|---|---|
| CLI | commands, flags, argument order, output formats, errors, exit codes | command builders, parsers, shell scripts, docs, fixtures | success parsed as failure; ignored new default |
| Configuration | schemas, keys, defaults, precedence, paths, migrations | generated config, environment assembly, recovery, doctor checks | valid config selects different driver or endpoint |
| API and protocol | protobuf, JSON, REST, headers, enums, pagination | clients, status probes, mocks, recorded fixtures | unknown field discarded; state misclassified |
| Security and identity | auth, credentials, secret rewriting, certificates, policy | provider mutation, redaction, child env, network policy | credential bypass, stale identity reuse, false green status |
| Lifecycle | create, start, restart, update, rebuild, destroy, cleanup | onboarding, rollback, retries, locks, crash recovery | orphan resources, double mutation, incomplete teardown |
| Persisted state and caches | materialization inputs, cache keys, snapshots, schema versions, invalidation | prepared roots, generated config, UID/GID, driver, platform, policy, recovery | same-version config change reuses stale identity or rootfs |
| Network | DNS, TLS, CONNECT, proxying, SSRF, timeouts | policy generation, probes, tunnels, error classification | fail-open route, re-resolution, misleading transport error |
| Runtime topology | processes, sidecars, drivers, images, sockets, ports | build, publish, download, store, extract, install, execute, cleanup | narrow extraction is mistaken for a narrow distributed image |
| Component selection and identity | binary/image precedence, fallbacks, version output, content digests | sibling discovery, driver config, registry state, gateway reuse, live PID 1 | matching CLI version hides different supervisor bytes or a mutable image tag |
| Packaging | asset names, archive layout, hashes, libc, architectures | installers, Brev, workflows, sibling-binary discovery | correct version with missing binary or unsupported host |
| Dependency graph | resolved versions, sources, checksums, features, build scripts, native or unsafe code | lockfiles, notices, SBOM, advisories, allowlists, direct callers | transitive security implementation is absent from notices or review |
| Build and image content | base digests, package repositories, package pins, build stages, provenance, full image contents | accepted images, extraction paths, security scans, runtime selectors | mutable base or unpinned package changes behind a trusted product version |
| Platform support | declared minimums, kernel features, capabilities, runtime versions | supported-host matrix, preflight, fallbacks, affected hardware | upstream CI passes on a newer runtime than the supported user host |
| Observability | status fields, logs, warnings, health semantics | doctor, status UI, automated recovery, troubleshooting | unhealthy runtime reported ready |
| Evidence pipeline | producer run state, workflow path/event/attempt, credentials, checkout order, tool resolution | base-owned verification workflows, artifact staging, provenance records | PR code poisons verification tools or an artifact from a failed run is accepted |
| Compatibility | deprecations, removals, fallback rules, feature gates | version selection, old fixtures, upgrade/recovery paths | workaround masks new contract or blocks recovery |

Inspect adjacent source when a changed file delegates to an apparently unchanged contract. A new
caller, default, or topology can change the effective behavior of byte-identical code.

## Downstream tracing method

For each upstream change:

1. Extract stable identifiers from source and tests: symbols, strings, keys, commands, paths,
image names, labels, status values, and errors.
2. Search the entire downstream repository, including hidden workflows and generated-input
sources. Exclude only vendored/build output deliberately.
3. Follow each result to its callers and state transitions. Do not stop at the first wrapper.
4. Search for semantic aliases when literals differ, such as a downstream helper that emits an
upstream config key indirectly.
5. Inspect negative space: downstream paths that rely on upstream defaults and therefore contain
no explicit key.
6. Compare downstream tests with upstream tests. Identify which new upstream behavior has no
downstream assertion.
7. For persisted or cached results, derive the complete behavior-changing input set from the
materialization code and compare it with the cache key and cache-hit validation.
8. For images and archives, trace each content set through build, publication, download, storage,
verification, extraction, installation, and execution. Do not collapse these into one surface.
9. For multi-component runtimes, derive selection precedence and compare the selected artifact's
content identity with persisted state and the live executable. Vary bytes while holding the
reported version constant.
10. For proof workflows, identify the first checked-out-code execution, every credential lifetime,
how tools are resolved, and whether producer workflow/event/attempt/conclusion are machine-bound.

## Concern schema

Use one record per independently reviewable risk:

```text
ID: DEP-<number>
Range: <old-tag>..<new-tag>
Surface: <risk surface>
Severity: <critical|high|medium|low>
Confidence: <high|medium|low>
Upstream old contract: <source/test citation>
Upstream new contract: <source/test citation>
Downstream consumer: <path/symbol/call chain, or exclusion evidence>
Failure mode: <specific observable or silent failure>
Disposition: <migrate|pin|guard|test|runtime-proof|document|no-impact>
Implementation: <diff or planned change>
Verification: <test/source comparison/runtime artifact>
Remaining gate: <none or explicit external dependency>
```

## Disposition standards

- `migrate`: change downstream behavior or data to the new contract and test the transition.
- `pin`: bind an immutable artifact or selector; also resolve the semantic concern separately.
- `guard`: reject or diagnose an invalid state before it crosses the dependency boundary.
- `test`: add deterministic coverage for a contract already implemented correctly.
- `runtime-proof`: exercise process, network, credential, hardware, or lifecycle behavior that
static tests cannot establish.
- `document`: update current operational truth; never use docs to compensate for broken behavior.
- `no-impact`: cite the upstream boundary and downstream call path or exclusion that proves the
change cannot affect supported behavior.

A concern can need several dispositions. List the primary disposition and every supporting gate.

## Evidence quality

Strong evidence directly exercises or defines the contract:

- exact-tag source and upstream tests;
- downstream tests that fail on the old assumption;
- immutable runtime artifacts with exact process/image identities;
- exact resolved dependency graph entries tied to notices, SBOM, advisory, and provenance review;
- cache invalidation proofs that vary one material input while holding the dependency version fixed;
- wire-level behavior for network and credential boundaries;
- affected-platform proof for platform-specific migrations.
- a base-trusted verifier that runs before proposed code, binds a successful producer run, and
revokes credentials before proposed code executes.

Weak evidence cannot close a material concern by itself:

- an aggregate test suite passed;
- no literal version string was found;
- release notes did not mention a breaking change;
- the CLI printed the expected version;
- one component printed the expected version while a sibling binary or image was selected;
- artifact metadata matched a source SHA but the producer run ultimately failed;
- a moving development tag worked once;
- source compiled without errors.

Use aggregate CI only after every material concern has direct evidence.
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Release ledger

Use this reference to turn a version gap into adjacent, auditable migration ranges.

## Required identities

Record for the current dependency and every candidate endpoint:

- semantic version and exact commit SHA;
- lightweight or annotated tag type;
- whether the commit is verified under the upstream project's policy;
- tag ancestry from the currently supported release;
- GitHub or registry release status: published, draft, prerelease, failed, or absent;
- producer repository, workflow path, event, run, attempt, status, conclusion, and source SHA when
artifacts exist;
- release date and the next endpoint.

Treat a tag, release, package publication, and container publication as separate facts. A tag with
a failed release workflow is a source boundary but not a shippable artifact boundary.
Artifacts uploaded before a later job failure remain non-shippable even when their individual
metadata and source SHA look correct.

## Adjacent-range procedure

For every `release N -> release N+1` range:

1. Read the official release notes and repository changelog entry.
2. Read every commit subject and inspect the complete changed-path list.
3. Open source and tests for every plausible downstream contract change.
4. Identify changes omitted from or generalized by the notes.
5. Record packaging, CI, and release failures even when product source is sound.
6. Add concern-ledger rows before moving to the next range.

Do not batch “small” releases together. A one-line commit can change a default, image tag,
minimum platform, or failure mode that controls the entire downstream runtime.

## Source priority

Use evidence in this order when sources disagree:

1. Exact tagged source and tests that execute the contract.
2. Published schemas, generated API definitions, and release workflow inputs.
3. Official release notes and changelog.
4. Commit or PR descriptions.
5. Downstream assumptions and historical documentation.

Lower-priority evidence can identify a concern but cannot overrule higher-priority behavior.

## Missing or failed releases

When a tag lacks a successful release:

- retain it in the semantic source ledger;
- record why publication failed and which artifacts were skipped;
- do not use its absent artifacts as a compatibility result;
- inspect whether the next release incorporates the same source plus additional changes;
- require the final consumed release to pass its own provenance and compatibility gates.

When the target is an unreleased commit, label the last range `latest-tag -> candidate-commit` and
repeat that range against the final tag before shipping.

## Minimum per-range output

```text
Range: <old-tag>..<new-tag>
Identity: <old-sha> -> <new-sha>
Release state: <published|failed|absent|candidate>
Commits and changed paths: <ledger reference>
Notes claims: <claims or none>
Source/test findings: <behavioral findings>
Downstream touchpoints: <paths/symbols or pending trace>
Concerns opened: <IDs>
Concerns resolved: <IDs and evidence>
Carry-forward questions: <questions for later ranges>
```

Carry questions forward explicitly. A later release may supersede a migration, but the ledger must
show the old and new contracts and why only the final one needs downstream implementation.
Loading
Loading