Add AGENTS.md guidance for cross-file impact when Konflux PRs substitute Tekton tasks

[fullsend-ai-retro]

What happened

PR #3513 was an automated Konflux/MintMaker PR updating 15 Tekton task bundle references. Most were routine digest or version bumps, but one change substituted the clair-scan task entirely with roxctl-scan — changing both the task name and bundle reference. The review agent on its second run (Aug 29, cost $3.52, claude-opus-4-6/high effort) correctly identified stale references to clair-scan in benchmark/offliner/scans.go:90 and hack/view-clair-reports.sh:39, neither of which were in the PR diff. The human confirmed the findings and filed follow-up PR #3530 for the benchmark offliner. The hack/view-clair-reports.sh stale reference remains unaddressed since the script is rarely used and the roxctl output format differs.

What could go better

The review agent caught the cross-file impact correctly on this PR, so this proposal is preventive rather than corrective. AGENTS.md currently has no guidance distinguishing routine Tekton bundle digest/version bumps from task substitutions (name changes). Task substitutions carry qualitatively different risk because they can silently break Go code, shell scripts, and tooling that filter by task name — producing empty results rather than errors. Without explicit guidance, detection depends on the agent's general reasoning rather than repo-specific knowledge of where task names are referenced (e.g., benchmark/offliner/, hack/, cmd/). Confidence: moderate — the agent already caught this correctly, but codifying the expectation makes the behavior more reliable across model versions and helps human reviewers recognize the risk pattern when triaging automated Konflux PRs.

Proposed change

Add a subsection to AGENTS.md (in the review guidance or CI/pipeline area) documenting the distinction between Tekton task bundle update types for Konflux/MintMaker PRs:

1. Digest-only bumps and patch version bumps are low-risk — the task name and interface are unchanged, so cross-file analysis is unnecessary.
2. Task name changes or task substitutions (e.g., clair-scan → roxctl-scan) are higher-risk — the reviewer should grep the codebase for references to the old task name in Go source (benchmark/, cmd/), shell scripts (hack/), and documentation. These references often use string literals for task-name filtering in SLSA provenance attestations and will silently return empty results after the rename.
3. When stale references are found, distinguish production code paths (higher priority) from developer utility scripts in hack/ (lower priority, per the conventions in issue Add AGENTS.md guidance for hack/ directory script conventions and review expectations #3508).

Validation criteria

On the next automated Konflux/MintMaker PR that contains a Tekton task name change (not just a digest or version bump), the review agent should flag cross-file stale references and cite the AGENTS.md guidance. Measure over the next 3 such PRs — each should include explicit cross-file analysis in the review findings when a task substitution is detected.

---

Generated by retro agent from #3513

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 6:32 PM UTC · Completed 6:37 PM UTC

Commit: ca5794c · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.91

[fullsend-ai-triage]

Related issues: This is part of a series of AGENTS.md documentation improvements — #3508 (hack/ directory conventions, referenced in point 3 of the proposal), #3502/#3503 (UBI bump workflow), #3451 (skill format), #3458 (Renovate exclusions). The hack/ directory conventions from #3508 are complementary but not blocking — the new guidance can reference the priority distinction conceptually and be refined once #3508 lands.

Proposed test case:

# Conceptual validation (manual, over next 3 Konflux task-substitution PRs):
# 1. Identify a Konflux/MintMaker PR where a task name changes (not just digest)
# 2. Verify the review agent's findings include cross-file stale reference analysis
# 3. Confirm the review cites AGENTS.md guidance for the task substitution pattern
# 4. Check that production code references are flagged at higher priority than hack/ scripts

---

Labels: AGENTS.md documentation enhancement for agentic review guidance, consistent with labeling on similar issues #3508, #3510, #3502, #3503, #3451.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 6:38 PM UTC · Completed 6:44 PM UTC

Commit: ca5794c · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.56