docs(#3559): add Backstage version consistency review guidance

[fullsend-ai-coder]

Add a Backstage Version Consistency subsection to the Working with Workspaces section of AGENTS.md. This gives the review agent explicit instructions to cross-check four version-carrying fields within a workspace when any of them change: backstage.json version, source.json repo-backstage-version, metadata supportedVersions, and the bs_ prefix in metadata OCI tags. Previously the review agent flagged mismatches inconsistently (2 of 3 runs on PR #3259) because no guidance existed.

Also adds spec.backstage.supportedVersions to the Package YAML key fields list, which previously omitted it.

---

Closes #3559

Post-script verification

• Branch is not main/master (agent/3559-version-consistency-guidance)
• Secret scan passed (gitleaks — ec81e029b8435977654579f1084ef0e569eae762..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[openshift-ci]

Hi @fullsend-ai-coder[bot]. Thanks for your PR.

I'm waiting for a redhat-developer member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:48 PM UTC · Completed 6:53 PM UTC

Commit: 6c73bd8 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $0.66

[fullsend-ai-review]

Review — PR #3560

Verdict: approve ✅

Summary

Clean, well-scoped documentation change that adds explicit Backstage version consistency review guidance to AGENTS.md. The change directly addresses the gap documented in #3559, where the review agent inconsistently detected version mismatches across workspace files (2 of 3 runs on PR #3259).

Analysis

Correctness: The four version-carrying fields listed (backstage.json version, source.json repo-backstage-version, metadata supportedVersions, and bs_ prefix in OCI tags) are accurate and complete. Verified against the actual pingidentity workspace, which confirms the exact mismatch pattern described: backstage.json and source.json show 1.54.5 while both metadata files reference 1.54.4 in supportedVersions and OCI tags.

Intent & coherence: Matches the authorized work in #3559. Appropriately scoped to documentation only — no code changes needed. The placement under "Working with Workspaces" (between "Overlay vs Patch" and "Major Version Bumps in Patches") follows the existing document structure for review guidance sections.

Style/conventions: Follows existing AGENTS.md formatting patterns: ### subsection header, numbered list for the fields, bold directives, and a concrete example. The directive tone ("Do not approve a PR with mismatched Backstage versions") is consistent with similar guidance in the "Major Version Bumps in Patches" section.

Documentation currency: Correctly adds spec.backstage.supportedVersions (Backstage compatibility version) to the Package YAML key fields list, which previously omitted it — a gap acknowledged in #3559.

Security: No security impact — documentation-only change with no injection patterns in PR body or content.

Cross-repo contracts: No external impact — changes are confined to internal review guidance.

No findings

No blocking or notable issues identified.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

[durandom]

/fs-diagnose

[fullsend-ai-review]

🤖 Finished Ci Diagnose · ✅ Success · Started 9:37 AM UTC · Completed 9:41 AM UTC

Commit: 6c73bd8 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $0.67

[fullsend-ai-review]

✅ CI Diagnosis — 0 of 0 curated checks failing · 6c73bd8

Verdict: All curated checks are passing (or were not triggered for this docs-only change).

This PR modifies only AGENTS.md. None of the curated CI checks (Prow e2e lanes, E2E Code Quality, appConfigExamples coverage, Python unit tests, smoke, publish, smoketest) were triggered — there are no failures to diagnose.

---

_{Automated CI diagnosis · updates as checks complete · not a substitute for review. For bot-authored PRs, pr_regression failures are handed to the fix agent automatically (up to 2 attempts). pre_existing failures are linked to an open PR when one already exists. A maintainer can take over any time with /fs-fix <instruction>, or stop auto-fix with /fs-fix-stop — see the fix agent docs.}