Document UBI base image bump workflow in AGENTS.md to prevent false-positive review findings

[fullsend-ai-retro]

What happened

On PR #3499, the Qodo review bot posted a Medium/Bug finding claiming rpms.lock.yaml was not regenerated after the base image digest changed in Dockerfile.dist. A human reviewer (robnester-rh) flagged this to the PR author, who had to explain that the lockfile WAS regenerated but produced no changes because the updated RPMs (curl-minimal, glib2, libcurl-minimal, libnghttp2) live inside the base image and are not tracked in rpms.in.yaml. The tracked packages (ca-certificates, jq, gzip) were unaffected. This false positive added ~1.5 hours of unnecessary reviewer back-and-forth.

The root cause is that AGENTS.md contains no documentation about the Docker/UBI infrastructure. The relationship between hack/ubi-base-image-bump.sh (bumps digests in 3 Dockerfiles, then runs lockfile regeneration), hack/update-rpm-lock.sh (regenerates rpms.lock.yaml from rpms.in.yaml), and the distinction between RPMs tracked in the lockfile vs. RPMs bundled inside the base image is entirely undocumented for agents and reviewers.

What could go better

Any reviewer — human or automated — encountering a UBI base image digest bump PR should understand that rpms.lock.yaml only tracks packages explicitly listed in rpms.in.yaml (ca-certificates, jq, gzip). When the base image digest changes but those packages' available versions don't change, the lockfile regeneration produces no diff, and that is expected behavior. Without this context documented in AGENTS.md, review tools will continue to flag missing lockfile changes on UBI bump PRs.

Confidence: High. The false positive directly traces to the documentation gap. The Qodo finding cited hack/update-rpm-lock.sh as evidence that the lockfile should change, but did not understand which packages the lockfile actually tracks. This same pattern will recur on future UBI bump PRs (which happen regularly via Renovate and manual runs of hack/ubi-base-image-bump.sh).

Note: This proposal targets AGENTS.md because that is the primary context file for agents reviewing this repo. The Qodo bot (which generated this specific false positive) is a third-party tool with no repo-level configuration file present. Adding this context to AGENTS.md will benefit the fullsend review agent and human reviewers directly; it may or may not help the Qodo bot depending on whether it reads AGENTS.md.

Proposed change

Add a new section to AGENTS.md documenting the Docker and UBI base image infrastructure. The section should cover:

1. UBI base image bump workflow — hack/ubi-base-image-bump.sh updates the ubi-minimal digest in three Dockerfiles (Dockerfile, Dockerfile.dist, acceptance/kubernetes/kind/acceptance.Dockerfile), then calls hack/update-rpm-lock.sh to regenerate the lockfile.
2. RPM lockfile scope — rpms.lock.yaml is generated from rpms.in.yaml and only tracks explicitly declared packages (ca-certificates, jq, gzip). When the base image digest changes but these packages' available versions remain the same, the lockfile regeneration produces no diff. This is expected behavior, not an error.
3. Cross-file consistency — All three Dockerfiles must pin the same ubi-minimal digest. The lockfile must be regenerated (even if unchanged) after any digest bump.
4. Reviewer guidance — On UBI bump PRs, the absence of changes to rpms.lock.yaml does not indicate the lockfile was not regenerated. Do not flag this as a bug.

Validation criteria

On the next 3 UBI base image bump PRs in conforma/cli where rpms.lock.yaml has no diff, no review agent or bot should flag 'RPM lockfile not regenerated' as a finding. If an automated reviewer does flag it, the AGENTS.md documentation should provide sufficient context for a human reviewer to dismiss it without needing to ask the PR author.

---

Generated by retro agent from #3499

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 6:44 PM UTC · Completed 6:47 PM UTC

Commit: 87c4a29 · View workflow run →

[fullsend-ai-triage]

Related work: PR #3504 (for issue #3502) adds a UBI Base Image Updates section to AGENTS.md covering the multi-branch Dockerfile strategy, but does not document the RPM lockfile scope. This issue's proposed content — explaining that rpms.lock.yaml only tracks rpms.in.yaml packages and that no-diff after a digest bump is expected — is complementary and should extend that section.

Maintainer context: A maintainer commented on #3502 that this type of agent-specific guidance may be too granular for AGENTS.md, suggesting the review agent should inherently evaluate changes in the context of the target branch. The same concern may apply here — consider whether the RPM lockfile scope explanation belongs in AGENTS.md or in a comment header in rpms.in.yaml / hack/update-rpm-lock.sh instead.

Proposed test case:

After merging, on the next 3 UBI bump PRs where rpms.lock.yaml has no diff:
- No automated reviewer should flag 'RPM lockfile not regenerated'
- If flagged, AGENTS.md context should let a human dismiss without
  contacting the PR author

---

Labels: This is a documentation issue targeting AGENTS.md (matches 'documentation' label) and directly improves agent reviewer behavior (matches 'agentic' label), consistent with labeling on the related issue #3502.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ⏭️ Skipped (open PR #3154 by @app/renovate already addresses issue #3503) · Started 6:48 PM UTC · Completed 6:48 PM UTC

Commit: 87c4a29 · View workflow run →

[fullsend-ai-coder]

An open PR already addresses this issue — skipping automated implementation.

• Update github actions (release-v0.7) (patch) #3154 by @app/renovate
• Update github actions (release-v0.7) (minor) #3156 by @app/renovate

To override, comment /fs-code --force on this issue.

_{Posted by fullsend pre-code check}