docs: retire the routing and fallback contract for the fleet-first posture (Phase 9b)

[kyle-sexton]

No related issue: melodic-software/github-iac#378 tracks the ci-perf program (Phase 9b). Draft until Phase 7 steps 5 and 7 land.

Summary

This repository's README documented a routing contract that no longer exists. Its "Routing and fallback contract" section described three selector policies (hosted-only, prefer-self-hosted, self-hosted-only), the liveness rule that chose between them, and a recovery procedure that flips the affected repository's effective policy to hosted-only through the audited github-iac routing-control workflow and then re-runs all jobs to force a fresh selector verdict.

ci-perf Phase 7 deleted every part of that. The select-runner reusable workflow is gone (ci-workflows#569, merged as 541ee4e90d12d77a90a3ddd72a3af9bc78634ea7, released as v0.23.0), its grammar is out of the runner-policy component (melodic-software/standards#556, merged as 771a796628f325c3c418c7b397d09fb7211e2972), and the routing-control workflow that wrote CI_RUNNER_POLICY is deleted (github-iac#453, merged as 4c5937e6b6067552d11b87abef04620191dda503).

Nothing about this controller changed. It still supplies runners inside its governed name and label namespaces, and a busy runner still queues rather than diverting work. What changed sits entirely upstream of it: an eligible private job names melodic-ubuntu-24.04-x64 as a literal in its own runs-on, and nothing decides placement at run time. The decision record is github-iac ADR 0014, which supersedes ADR 0004.

Fix

README.md:

• Intro paragraph. "The centrally governed routing policy decides whether local capacity is preferred, required, or bypassed" and "serve the organization's governed self-hosted-only routing default" both describe a policy that is gone.
• Runtime architecture mermaid. The Reusable workflow selector node with its "managed route" and "hosted route" edges becomes a workflow job naming one label or the other.
• "Routing and fallback contract" becomes "Routing contract", rewritten. The three policies, the liveness rule, the fail-open/fail-closed selector behaviour and the two-minute ubuntu-slim selector control job are recorded as retired with their citing SHAs. Two consequences a reader actually needs are stated plainly: a rerun no longer recomputes anything about placement, so Re-run all jobs and a failed-job rerun are equivalent as far as routing is concerned; and there is no consumer-side recovery from an unavailable fleet at all, so affected jobs queue until a host returns. The unrelated stale-re-run hazard is pointed at github-iac POSTURE.md rather than restated.
• Rollback order. Its first step was "set routing hosted-only". There is no routing variable, so the rollback now says what a fleet it cannot restore actually means: the affected jobs queue until it is back. It also states what the escape would really cost, because the escape is not one edit: widening the reason set is a governed standards change and each affected repository still needs its own per-job exceptions entry plus a runs-on change before anything routes differently. A reader planning a rollback window needs that stated, not silently dropped.

There is no consumer-side recovery from a fleet outage, and the doc now says so. An earlier draft offered a runner-policy.json exception as the substitute for the deleted hosted-only flip. That path does not exist: reason must be a member of the closed hostedExceptionReasons set (dependabot, docker-socket, job-container, privileged-control-plane, publication, service-container, windows), enforced at runner-policy.mjs:348, and none of them expresses "the fleet is down". Both the routing section and the rollback order now say the affected jobs queue until a host returns, and that widening that set is a governed standards change, which on its own routes nothing.

Two further precision points carried over from the sibling PRs' review, so this document does not repeat their errors:

• CI_RUNNER_POLICY is described as present and unread, not as deleted. The organization variable is live at self-hosted-only; only its removal from the github-iac Pulumi program is decided, pending that repository's Phase 7 step 5 apply. Nothing reads it, because the selector that consumed it is deleted.
• hosted-exception-required is named as a finding, not a config key. A reader following the other phrasing would write a config the schema rejects (the repository-policy schema is additionalProperties: false and permits no such top-level key). The real shape is an entry under exceptions, keyed <workflow path>#<jobId>, carrying a reason from the closed enum plus a justification.
• The ADR 0014 reference names github-iac#466 rather than a main URL, which would 404 until that PR merges. "Supersedes ADR 0004" likewise becomes true only when #466 lands; both PRs are gated on the same Phase 7 steps.

docs/roadmap.md:

• The isolated-Linux-VM backend section required a future backend to preserve "the audited hosted-only cutoff with a full workflow rerun that recomputes selector eligibility". There is no eligibility to recompute and no cutoff to preserve.
• The cost-reporting section required separating "selector spend from workload spend". The selector's ubuntu-slim control job is retired, so there is no selector spend.

Verification

• npx markdownlint-cli2 README.md docs/roadmap.md: 0 issues.
• No em-dashes in added lines (git diff -U0 | grep "^+" | grep -c "—" prints 0).
• Every SHA cited is a full 40 characters and was resolved against the local clones before being written.
• In the two changed files, every surviving selector / CI_RUNNER_POLICY hit is deliberate retirement prose, not an instruction. This is scoped to the changed files on purpose: docs/queue-monitor.md lines 104 to 108 still instruct an operator to flip CI_RUNNER_POLICY to hosted-only and expect the selector to re-run, and .github/scripts/queue-monitor.cjs:23 ships the same text in incident output. Both are deleted by ci-runner#357 and are deliberately left to it rather than conflicted with here. Merge-order note: if this PR lands first, the README contradicts that shipped incident text until ci: retire the queued-job and actions-budget monitors (Phase 7 step 6) #357 follows.
• Claims about what was deleted were checked against origin/main of the ci-workflows clone: select-runner.yml, selector-conformance.yml and queue-monitor-liveness.yml are absent from .github/workflows/.

Expected interaction with ci-runner#357. That draft also edits README.md, but only to remove two entries from the "Further documentation" list (lines 435 onward) as it deletes the two monitors. My edits are in the intro, the mermaid block, the routing section and the rollback paragraph, so the two diffs touch disjoint hunks and merge cleanly in either order. #357 is gated on a seven-day green pool-alert.yml window; this PR is gated on Phase 7 steps 5 and 7. Whichever lands second may need a trivial rebase.

Related

• melodic-software/github-iac#378, the ci-perf program; github-iac#466, the Phase 9b PR carrying ADR 0014 and the completed POSTURE.md.
• ci-workflows#569, merged as 541ee4e90d12d77a90a3ddd72a3af9bc78634ea7: deletes select-runner.yml.
• feat(runner-policy)!: retire the selector grammar (Phase 7 step 2) standards#556, merged as 771a796628f325c3c418c7b397d09fb7211e2972: retires the selector grammar.
• github-iac#453, merged as 4c5937e6b6067552d11b87abef04620191dda503: deletes the routing-control workflow this README's recovery procedure pointed at.
• ci-runner#357, the queue-monitor and budget-monitor retirement, gated on the pool-alert window.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-08T08:55:59.974253Z	268972c	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 268972c99f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".