docs(ci): explain the nested testsuite workflow refs

[castrojo]

What problem are you solving?

Stable-promotion triage can read test_ref: v1 as proof that every testsuite fix is current. It is not. A reusable workflow carries two independent refs:

• uses selects the workflow definition — including workflow-level fixes such as VM disk sizing
• test_ref selects the test tree that workflow checks out

They move separately, so a managed test_ref beside a pinned uses leaves half the stack stale while the caller looks managed.

Changes

• adds the triage row: tests update but E2E setup stays stale → compare the reusable workflow uses ref with its test checkout ref
• adds a section explaining the two refs and the promotion trap, directing triage to the nested workflow shown in the run log rather than the ref written in the caller

One file, 13 added lines.

Relationship to #1014

This supersedes #1014, which carried the same insight but could no longer be merged: its branch had accumulated 16 conflicts against main — Containerfile, five workflows, build_files/, unit tests, renovate.json — for a change that touches one documentation file. Resolving those to land a docs addition would have produced a diff nobody could review against the change it claims to make, so it is re-cut from current main instead. Authorship is preserved in the commit trailer.

The content was also re-checked against main: failure-modes.md has grown a lot since #1014 was opened, but nothing in it covers the nested-ref distinction, so the contribution is still needed.

Testing

• python3 .github/scripts/validate-docs.py → documentation ok: 13 skills, 41 Markdown files

Refs #929

[hanthor]

Small, accurate docs addition: uses (workflow definition) and test_ref (test tree) on a reusable testsuite workflow do move independently, so a managed test_ref next to a pinned uses is a real trap — workflow-level fixes (VM sizing, runner setup) don't arrive just because the test tree ref is current. Good judgement re-cutting this from current main instead of resolving 16 unrelated conflicts on the superseded #1014, with authorship preserved in the trailer. One file, 13 lines, no workflow behavior changed. CI is green.

---

Generated by Claude Code