docs(#4263): add upstream-tracking convention to AGENTS.md

[fullsend-ai-coder]

Add an "Upstream-Tracking Packages" section to the ai-integrations workspace AGENTS.md documenting that some packages replicate upstream backstage/backstage schemas as stopgaps while upstream PRs are pending. When a package explicitly tracks an upstream PR, upstream naming and API conventions (interface names, apiVersion typing, type guard patterns, moduleId format) take precedence over workspace-local conventions.

This prevents review agents from flagging intentional upstream alignment as convention violations, reducing false positive findings on upstream-tracking PRs.

Assisted-by: Claude Opus 4.6 Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

---

Closes #4263

Post-script verification

• Branch is not main/master (agent/4263-upstream-convention-docs)
• Secret scan passed (gitleaks — 8bf7bc3e58cbba6cff97d922dda1c96b0acc33ff..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.07%. Comparing base (8bf7bc3) to head (8a9786c).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4264   +/-   ##
=======================================
  Coverage   59.07%   59.07%           
=======================================
  Files        2454     2454           
  Lines       97995    97995           
  Branches    27328    27329    +1     
=======================================
  Hits        57892    57892           
- Misses      38555    38562    +7     
+ Partials     1548     1541    -7     

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.55% <ø> (ø)		Carriedforward from 8bf7bc3
ai-integrations	68.29% <ø> (ø)
app-defaults	69.79% <ø> (ø)		Carriedforward from 8bf7bc3
augment	46.67% <ø> (ø)		Carriedforward from 8bf7bc3
boost	77.63% <ø> (ø)		Carriedforward from 8bf7bc3
bulk-import	72.79% <ø> (ø)		Carriedforward from 8bf7bc3
cost-management	13.55% <ø> (ø)		Carriedforward from 8bf7bc3
dcm	67.21% <ø> (ø)		Carriedforward from 8bf7bc3
e2e-adoption-insights	60.00% <ø> (ø)		Carriedforward from 8bf7bc3
e2e-intelligent-assistant	46.74% <ø> (ø)		Carriedforward from 8bf7bc3
extensions	56.59% <ø> (ø)		Carriedforward from 8bf7bc3
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from 8bf7bc3
global-header	66.50% <ø> (ø)		Carriedforward from 8bf7bc3
homepage	47.59% <ø> (ø)		Carriedforward from 8bf7bc3
install-dynamic-plugins	59.95% <ø> (ø)		Carriedforward from 8bf7bc3
intelligent-assistant	75.42% <ø> (ø)		Carriedforward from 8bf7bc3
konflux	91.98% <ø> (ø)		Carriedforward from 8bf7bc3
lightspeed	69.02% <ø> (ø)		Carriedforward from 8bf7bc3
mcp-integrations	83.40% <ø> (ø)		Carriedforward from 8bf7bc3
orchestrator	71.31% <ø> (ø)		Carriedforward from 8bf7bc3
quickstart	63.74% <ø> (ø)		Carriedforward from 8bf7bc3
sandbox	79.56% <ø> (ø)		Carriedforward from 8bf7bc3
scorecard	86.23% <ø> (ø)		Carriedforward from 8bf7bc3
theme	88.14% <ø> (ø)		Carriedforward from 8bf7bc3
translations	5.12% <ø> (ø)		Carriedforward from 8bf7bc3
x2a	79.20% <ø> (ø)		Carriedforward from 8bf7bc3

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8bf7bc3...8a9786c. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 11:52 PM UTC · Completed 12:06 AM UTC

Commit: 8a9786c · View workflow run →

[fullsend-ai-retro]

Retro: PR #4264 — docs(#4263): add upstream-tracking convention to AGENTS.md

What happened

This PR was the product of a clean retro→triage→code pipeline. The retro agent on PR #4211 identified that ~10 naming-convention review findings were false positives because the new packages intentionally replicate upstream backstage/backstage#34476 patterns. It filed issue #4263 proposing AGENTS.md documentation to prevent future false positives. The triage agent classified the issue as medium severity, added placement guidance and related-issue context, and labeled it ready-to-code. The code agent produced a clean 28-line documentation addition on the first try, and gabemontero approved and merged within 23 minutes of PR creation.

Pipeline quality

• Rework rate: Zero — single commit, no review findings, no fix cycles.
• Token cost: Efficient — triage added useful context in ~5 minutes, code agent made a single well-targeted change in ~7 minutes.
• Time to resolution: ~35 minutes from issue creation to merge.
• Code quality: The documentation is well-structured, covers the four specific convention categories that generated false positives on PR feat(#4209): add ai-model-server API spec type extension #4211, and is general enough to cover future upstream-tracking packages.

Review was skipped

The review agent did not run on this PR. Workflow logs for run 31546682157 show the review dispatch was skipped with a collaborator permission error for the bot author. This is covered by existing issue rhdh-plugins#4166 (restore review dispatch for bot-authored PRs). For a 28-line documentation-only change that directly implements a well-specified retro issue, the impact of the review skip was minimal.

Existing issues covering identified patterns

• Review skip on bot-authored PRs: rhdh-plugins#4166 — this retro confirms the issue is still active; the review dispatch was skipped on this bot-authored PR due to the collaborator permission lookup failure.
• Review optimization for docs-only PRs: agents#373 and fullsend#1900 cover skipping irrelevant review dimensions for docs/prompt-only changes.

Harness dispatch LoadWithBase error

Workflow logs show the fullsend dispatch command logging errors when loading harness configs with base: fields, causing code and fix agents to be reported as "skipped" in the harness dispatch step. Agents still executed through other workflow paths, so no functional impact occurred. This is distinct from fullsend#2819 (which addresses internal path drift within LoadWithBase, not the dispatch step failing to call LoadWithBase at all). See proposal below.

Proposals filed

• Harness dispatch should use LoadWithBase for configs with base composition (in fullsend-ai/fullsend)