Add AGENTS.md guidance for reviewing dependency fork/scope substitutions in patches

Start with AGENTS.md in redhat-developer/rhdh-plugin-export-overlays and read the existing "Major Version Bumps in Patches" section. Add an adjacent section covering dependency fork/scope substitutions and the six proposed review criteria, including provenance, fork changes, upstream alternatives, maintenance risk, and verification. Done means the guidance is present and the next applicable patch review can reference it.

What happened

PR #2531 (cherry-pick of #2527) changed a patch file to replace the official es5-ext@0.10.64 npm package with a fork from a different npm scope (npm:@unes/es5-ext@0.10.64-1). The change was approved by two human reviewers with no inline comments and no agent review (the review agent was not dispatched due to the fork-PR routing exclusion). While the change addresses a legitimate security concern (removing post-install scripts per RHIDP-14008), it introduces a dependency on a third-party fork package — a supply-chain risk category that the existing AGENTS.md patch review guidance does not address.

What could go better

The AGENTS.md has a detailed "Major Version Bumps in Patches" section with explicit review criteria (detect the bump, check changelogs, assess API usage, flag for verification). However, there is no analogous guidance for dependency fork/scope substitutions — where a patch replaces a package with a fork from a different npm scope or GitHub org (e.g., es5-ext → @unes/es5-ext). This is a distinct risk category: the package name changes, the publisher changes, and the trust chain is different. A version bump within the same package is governed by semver conventions; a fork substitution has no such contract. Reviewers (human or agent) should be prompted to assess: (1) who maintains the fork and why it exists, (2) what changes the fork introduces beyond the claimed fix, (3) whether the fork is actively maintained and receives security updates, and (4) whether an upstream fix is available that would eliminate the need for the fork. Confidence: high that this is a genuine gap — I searched all three target repos and found no existing issue or guidance covering forked package substitution. The existing dependency patch issues (#2911, #2926, #2925, #2924, #2921) focus on CVE minimality, version enumeration, and lockfile validation — none address package identity changes.

Proposed change

Add a new section to the AGENTS.md file in redhat-developer/rhdh-plugin-export-overlays, adjacent to the existing "Major Version Bumps in Patches" section, titled something like "Dependency Fork/Scope Substitutions in Patches". The section should explain why substituting a package with a fork from a different npm scope is a supply-chain risk and provide review criteria analogous to the major-version-bump checklist:

1. Detect the substitution. When a patch replaces a package resolution with npm:<scope>/<name>@<version> pointing to a different package, flag it as a fork substitution.
2. Assess the fork's provenance. Check who publishes the fork, why it exists, and whether it is actively maintained. Look for a linked upstream issue or PR that explains the divergence.
3. Verify the fork's changes. Compare the fork to the original package at the same version. Confirm the changes are limited to the stated purpose (e.g., removing post-install scripts) and do not introduce additional modifications.
4. Check for upstream alternatives. Determine whether the upstream package has addressed the concern in a newer version, which would eliminate the need for the fork.
5. Assess ongoing maintenance risk. A fork may not receive timely security patches from the original package's maintainers. Flag if the fork's maintenance cadence is unclear.
6. Recommend CI verification. As with major version bumps, recommend /smoketest and /test (if E2E tests exist) as minimum verification steps.

Validation criteria

The next review (human or agent) of a PR that introduces a dependency fork substitution in a patch file should reference the new AGENTS.md guidance and explicitly assess at least the fork's provenance and the availability of upstream alternatives. Measurable by checking the next 3 PRs that modify patches/*.patch files to substitute a dependency with a fork — reviewers should demonstrate awareness of the guidance.

Generated by retro agent from https://github.com/redhat-developer/rhdh-plugin-export-overlays/pull/2531