Add a script to refresh a vendored dependency

.github/workflows/ci.yaml

@@ -831,6 +831,8 @@ jobs:
   validate-workspace-dependencies:
     name: Validate workspace dependencies
     runs-on: ubuntu-22.04
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -843,11 +845,21 @@ jobs:
       - name: Install dependency policy test requirements
         run: python3 -m pip install pytest==9.0.3
       - name: Test dependency policy validator
-        run: python3 -m pytest bin/tests/test_validate_workspace_dependencies.py -v
+        run: python3 -m pytest bin/tests -v
       - name: Validate dependency policy
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: python3 bin/validate_workspace_dependencies.py --verify-upstream
+      # Drift is a report, not a gate. A failed lookup exits 1 and shows "?"
+      # in its row; pipefail lets that reach continue-on-error, which marks
+      # the step with a warning instead of failing the PR.
+      - name: Report vendored dependency drift
+        continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -o pipefail
+          python3 bin/vendored_dependency.py status --markdown | tee -a "$GITHUB_STEP_SUMMARY"
 
   validate_objectives:
     runs-on: ubuntu-22.04

README.md

@@ -45,6 +45,6 @@ The hardware-only `kinova_gen3_site_config` and `picknik_ur_site_config` configu
 
 ## Updating vendored dependencies
 
-Each `UPSTREAM.yaml` file under `src/external_dependencies` records the exact upstream commit and retained paths. Refresh a dependency from that commit, preserve its license files, reapply the documented pruning, and validate every config that consumes the package.
+Each `UPSTREAM.yaml` file under `src/external_dependencies` records the exact upstream commit and retained paths. Run `bin/vendored_dependency.py status` to see how many commits each pinned upstream branch has moved past its recorded commit; CI publishes the same table in the job summary of the `Validate workspace dependencies` job. Run `bin/vendored_dependency.py update <source>` (optionally `--to <commit>`) to refresh one source: it re-vendors the retained paths at the new commit, carries over every local difference from the pinned commit (edits and pruned files alike) as a three-way merge, updates `commit:` in `UPSTREAM.yaml`, and then checks that `modified_paths` still matches. Conflicts are left as ordinary conflict markers to resolve by hand. A run that stops early has already rewritten the source and its pin; the message names the `git restore` command that discards it. Refresh one source per PR, and build and run the configs that consume it before committing.
 
 The optional ML model submodules can be advanced independently when their demonstration Objectives need a newer model package.