docs: expand-then-contract for cross-repo changes

[LukasWodka]

Step 4 of the cross-repo plan on backend#1371.

Why. The train promotes each repo independently — fail-fast: false, no ordering — so a hop routinely merges some repos and holds others (the 2026-07-29 prod hop merged 8 of 10). Nothing today prevents averaging-service promoting a change that needs a backend change backend has not shipped, and backend can be held by something unrelated to that work.

What the measurement said. Only 1 of 17 epics on the board spans repos, and that one (#1262) is a process epic. Cross-repo work does happen — RFC-0003 touched five repos — but it is tracked as separate issues rather than sub-issues of one epic, so the ticket graph does not encode the dependency and cannot be gated on. That rules out epic-sibling gating for now.

So the durable fix is compatibility, not orchestration: expand → adopt → contract removes the dependency on promotion timing instead of managing it. Every step is independently promotable and safe in any order.

• README.md: a Cross-repo changes section with the pattern, the reasoning, and what to do when a change is genuinely breaking (tick Breaking change, put the rollout order in Deployment notes, tell whoever fires the train).
• .github/pull_request_template.md: one checklist line pointing at it.

Scope notes. This deliberately does not document repos.yml atomic groups — those do not exist yet (step 2, queued behind release-train#11 since both edit promote.yml). And the org template only applies to repos without their own; all ten train repos have their own, and they have drifted (722/891/901/905/1150 bytes), so a sweep is needed to make the checklist line actually reach them — ticketed separately.

---

Note

Low Risk
Documentation and PR checklist only; no runtime, security, or deployment behavior changes.

Overview
Documents how to ship work that spans multiple repos when the release train promotes each repository independently (no ordering between repos).

The README gains a Cross-repo changes section: why you cannot assume the fleet moves together, the expand → adopt → contract compatibility pattern, and what to do for genuinely breaking changes (tick Breaking change, document rollout order in Deployment notes with tracebloc/<repo>#N refs, coordinate manual train sequencing).

The org PR template adds a checklist item requiring either expand-then-contract or an explicit breaking-change rollout when a PR depends on another repo.

^{Reviewed by Cursor Bugbot for commit 734a053. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

👋 Heads-up — Code review queue is at 34 / 30

Above the WIP limit. The team convention is to review existing PRs before opening new work.

Open PRs currently in Code review (oldest first):

• backend#1146 — docs(rfc): platform cost & autoscaling architecture · author: @saadqbal · reviewer: @LukasWodka, @saqlainsyed007, @aptracebloc
• backend#1201 — docs(rfc): Data spaces & federated dataset composition (draft) · author: @LukasWodka · reviewer: @saadqbal
• backend#1217 — docs(rfc): Dataset integrity & score reproducibility (draft) · author: @LukasWodka · reviewer: @saadqbal
• backend#1261 — RFC-BACKEND-0008: board & process reset (decision RFC — for markup) · author: @LukasWodka · reviewer: @saadqbal
• backend#1284 — docs(deploy): backend deploy runbook skeleton (#1263) · author: @LukasWodka · no reviewer assigned
• backend#1332 — feat(check-model): allow KNN/GaussianProcess on a single-edge owned dataset (#923 follow-up) · author: @divyasinghds · no reviewer assigned
• backend#1353 — chore(ci): baseline historical gitleaks findings + wire caller · author: @LukasWodka · no reviewer assigned
• backend#1361 — feat(tasks): bound ExperimentQueue growth for PAUSED experiments (backend#1351) · author: @saqlainsyed007 · no reviewer assigned
• claude-skills#14 — feat(skill): add tracebloc-frontend-app skill · author: @waqaskhanroghani · reviewer: @saadqbal
• claude-skills#15 — feat(skill): add tracebloc-design-system skill · author: @waqaskhanroghani · reviewer: @saadqbal

Pull from review before opening new work. (This is a nudge from the kanban WIP check, not a block.)

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 734a053. Configure here.}