docs(#3503): document RPM lockfile scope for UBI bump PRs

AGENTS.md

@@ -112,6 +112,53 @@ Read these before modifying the corresponding areas:
 - [internal/validate/vsa/DESIGN.md](internal/validate/vsa/DESIGN.md) — VSA: storage backends, DSSE signing rationale, expiration model
 - [acceptance/README.md](acceptance/README.md) — acceptance test framework, Testcontainers, WireMock, snapshot testing
 
+## UBI Base Image Updates
+
+The project pins the `ubi-minimal` base image digest in three Dockerfiles:
+
+- `Dockerfile` (production)
+- `Dockerfile.dist` (distribution)
+- `acceptance/kubernetes/kind/acceptance.Dockerfile` (acceptance tests)
+
+The script `hack/ubi-base-image-bump.sh` updates all three files to the same
+digest and then invokes `hack/update-rpm-lock.sh` to regenerate `rpms.lock.yaml`.
+Renovate raises the same bump automatically; the script exists for manual runs
+between Renovate PRs. All three Dockerfiles must pin the same digest, and the
+lockfile must be regenerated after any digest bump.
+
+### RPM lockfile scope
+
+`rpms.lock.yaml` is generated from `rpms.in.yaml` and only tracks the packages
+explicitly listed there — currently `ca-certificates`, `jq`, and `gzip`. RPMs
+that ship inside the base image itself (for example `curl-minimal`, `glib2`,
+`libcurl-minimal`, `libnghttp2`) are **not** tracked in the lockfile.
+
+Consequence: when a UBI base image digest bump ships updates only to
+base-image-bundled RPMs and the tracked packages' available versions do not
+change, `hack/update-rpm-lock.sh` runs successfully but produces no diff in
+`rpms.lock.yaml`. A commit that bumps the digest in the Dockerfiles without
+touching `rpms.lock.yaml` is the expected outcome in that case, not evidence
+that the lockfile was skipped.
+
+### Review guidance for UBI bump PRs
+
+On any PR that bumps the `ubi-minimal` digest:
+
+- Do **not** flag "`rpms.lock.yaml` was not regenerated" as a finding solely
+  because the lockfile is unchanged. Regeneration is a no-op when no tracked
+  package's version changed, and that is the common case. Confirm the lockfile
+  was regenerated only by asking the author (or checking CI logs) — the diff
+  alone cannot prove it either way.
+- If the concern is that a new base-image-bundled RPM should be tracked
+  explicitly, that is a separate change to `rpms.in.yaml`, not a bug in the
+  bump PR.
+
+On `release-v*` branches, bump PRs may intentionally update only the production
+Dockerfiles (`Dockerfile`, `Dockerfile.dist`) and skip the acceptance
+Dockerfile, since acceptance test infrastructure is typically not backported.
+The coordinated update set in `hack/ubi-base-image-bump.sh` applies to `main`;
+a narrower scope on release branches is expected, not stale.
+
 ## Claude Code Skills
 
 Skills live in `.claude/skills/<name>/SKILL.md`. They are **step-by-step executable workflows**