What happened
On PR #3171, the review agent (run 31097665796, run 31098654050) approved commits 1–3 which introduced CTA text referencing midstream-only scripts (sync-midstream.sh, generatePipelineRunsForPlugins.sh, build/ci/update-index.sh) without gating them behind _in_midstream_repo(). These scripts do not exist in the upstream GitHub repo — they only exist in the GitLab midstream repo (rhdh-plugin-catalog). The PR author caught this gap and pushed a 4th commit (3bc7b9e) to add an early return in print_fallback_rebuild_cta() that gates all midstream rebuild guidance behind _in_midstream_repo().
What could go better
The review agent had no context about the upstream/midstream distinction. AGENTS.md and CLAUDE.md contain zero mentions of 'midstream', 'downstream', 'GitLab', or the two-repo architecture. The codebase itself is deeply aware of this distinction — generatePluginBuildInfo.py has _in_midstream_repo(), current_midstream_branch(), DEFAULT_MIDSTREAM_BRANCH, and tests explicitly verify both upstream and midstream paths. But without AGENTS.md documentation, the review agent treated the midstream script references as valid without questioning whether they needed runtime gating.
Confidence: High. The review agent's approval text on commit c002b0c correctly described the _in_midstream_repo() function but did not flag that the CTA code paths using midstream-only scripts were not gated behind it. This is a clear context gap, not a reasoning failure.
Proposed change
Add a new section to AGENTS.md (under or near 'Repository Purpose' or 'Key Workflows') documenting the upstream/midstream architecture:
- What the two repos are: This GitHub repo (
rhdh-plugin-export-overlays) is the upstream. A separate GitLab repo (rhdh-plugin-catalog) is the midstream, used for Konflux/Quay builds.
- What exists only in midstream:
build/ci/sync-midstream.sh, generatePipelineRunsForPlugins.sh, build/ci/update-index.sh, and related Konflux pipeline infrastructure.
- Review guidance: When reviewing
scripts/ changes that generate user-facing text or CLI commands referencing midstream-only paths, verify those references are gated behind _in_midstream_repo() (which detects midstream by checking for build/ci/sync-midstream.sh). Code that runs in the upstream context must not reference non-existent midstream scripts.
- Key functions:
_in_midstream_repo(), current_midstream_branch(), rhdh_git_branch_for_midstream() — these are the runtime detection mechanisms.
This complements existing issue #2893 (general scripts/ review guidance) by adding the domain-specific two-repo context that the review agent currently lacks.
Validation criteria
On the next PR that modifies scripts/generatePluginBuildInfo.py or related scripts with midstream-aware code paths, the review agent should: (1) explicitly acknowledge the upstream/midstream distinction in its review, and (2) verify that any new midstream-only references are gated behind _in_midstream_repo() or equivalent. Track across the next 3 such PRs.
Generated by retro agent from #3171
What happened
On PR #3171, the review agent (run 31097665796, run 31098654050) approved commits 1–3 which introduced CTA text referencing midstream-only scripts (
sync-midstream.sh,generatePipelineRunsForPlugins.sh,build/ci/update-index.sh) without gating them behind_in_midstream_repo(). These scripts do not exist in the upstream GitHub repo — they only exist in the GitLab midstream repo (rhdh-plugin-catalog). The PR author caught this gap and pushed a 4th commit (3bc7b9e) to add an early return inprint_fallback_rebuild_cta()that gates all midstream rebuild guidance behind_in_midstream_repo().What could go better
The review agent had no context about the upstream/midstream distinction. AGENTS.md and CLAUDE.md contain zero mentions of 'midstream', 'downstream', 'GitLab', or the two-repo architecture. The codebase itself is deeply aware of this distinction —
generatePluginBuildInfo.pyhas_in_midstream_repo(),current_midstream_branch(),DEFAULT_MIDSTREAM_BRANCH, and tests explicitly verify both upstream and midstream paths. But without AGENTS.md documentation, the review agent treated the midstream script references as valid without questioning whether they needed runtime gating.Confidence: High. The review agent's approval text on commit
c002b0ccorrectly described the_in_midstream_repo()function but did not flag that the CTA code paths using midstream-only scripts were not gated behind it. This is a clear context gap, not a reasoning failure.Proposed change
Add a new section to
AGENTS.md(under or near 'Repository Purpose' or 'Key Workflows') documenting the upstream/midstream architecture:rhdh-plugin-export-overlays) is the upstream. A separate GitLab repo (rhdh-plugin-catalog) is the midstream, used for Konflux/Quay builds.build/ci/sync-midstream.sh,generatePipelineRunsForPlugins.sh,build/ci/update-index.sh, and related Konflux pipeline infrastructure.scripts/changes that generate user-facing text or CLI commands referencing midstream-only paths, verify those references are gated behind_in_midstream_repo()(which detects midstream by checking forbuild/ci/sync-midstream.sh). Code that runs in the upstream context must not reference non-existent midstream scripts._in_midstream_repo(),current_midstream_branch(),rhdh_git_branch_for_midstream()— these are the runtime detection mechanisms.This complements existing issue #2893 (general scripts/ review guidance) by adding the domain-specific two-repo context that the review agent currently lacks.
Validation criteria
On the next PR that modifies
scripts/generatePluginBuildInfo.pyor related scripts with midstream-aware code paths, the review agent should: (1) explicitly acknowledge the upstream/midstream distinction in its review, and (2) verify that any new midstream-only references are gated behind_in_midstream_repo()or equivalent. Track across the next 3 such PRs.Generated by retro agent from #3171