Add AGENTS.md guidance that metadata version/OCI tag mismatches block /publish

Read the Working with Workspaces section of AGENTS.md and the metadata examples under workspaces//metadata/.yaml. Review PR #2896 and the linked /publish validation run to understand the documented mismatch cases. Done means AGENTS.md clearly identifies version, OCI tag, and Backstage compatibility mismatches as blocking and requires checking every package in plugins-list.yaml.

What happened

On PR #2896, the initial commit updated source.json and the main theme metadata but did not update the qe-theme metadata file. The review agent (run 30066160356) correctly identified this: it noted that qe-theme metadata still referenced version 0.11.0 while the upstream source had bumped to 0.12.0. However, it classified this as a low-severity finding. When the author ran /publish, the publish workflow failed with 3 metadata validation errors — the version mismatch and OCI tag mismatches were hard errors. This required a second commit and another publish cycle, adding ~20 minutes of delay and wasted CI resources.

What could go better

The review agent had the right finding but the wrong severity. The AGENTS.md does not currently document that /publish includes a metadata validation step that enforces strict consistency between the built plugin versions and the metadata YAML fields (spec.version, spec.dynamicArtifact OCI tag). Because the review agent didn't know this validation was a hard gate, it reasonably classified the inconsistency as informational rather than blocking. Adding this context to AGENTS.md would let the review agent correctly flag metadata mismatches as blocking findings that will fail the publish pipeline. Confidence is high: this is a factual gap in the documented review criteria, and the /publish metadata validation is a deterministic check.

Proposed change

Add to the 'Working with Workspaces' section of AGENTS.md, after the existing metadata YAML documentation, a subsection titled 'Metadata Validation in /publish'. The guidance should state:

1. The /publish workflow includes a metadata validation step that compares each built plugin's actual version and Backstage compatibility version against the corresponding spec.version, spec.dynamicArtifact OCI tag, and spec.backstage.supportedVersions fields in workspaces/*/metadata/*.yaml.
2. Any mismatch between these fields and the actual build output causes /publish to fail. This is a hard gate, not a warning.
3. When reviewing workspace update PRs, the review agent should verify that ALL metadata YAML files in the workspace are updated consistently with the new source.json ref. If any metadata file still references old versions or OCI tags, this should be flagged as a blocking finding because it will cause /publish to fail.
4. In particular, check that every package listed in plugins-list.yaml has its corresponding metadata YAML updated when the workspace's source.json changes.

Validation criteria

On the next workspace update PR where a metadata YAML file is not updated consistently with source.json, the review agent should flag it as a blocking finding (not low-severity). Verify on at least 3 workspace update PRs that the review agent explicitly checks all metadata YAML files for version/OCI tag consistency.

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