CI: a docs-only PR can never merge — required contexts never report under ci.yml's paths-ignore, and the merge queue that made that safe is off

[macanderson]

Problem

A pull request that touches only prose is permanently BLOCKED. Not slow — unmergeable.

Branch protection requires three contexts:

$ gh api repos/macanderson/stella/branches/main/protection/required_status_checks --jq .contexts
["fmt + clippy + test", "cargo deny + cargo audit", "harbor_adapter + analyzer pytest"]

The first two come from ci.yml, which carries paths-ignore for website/**, docs/**, *.md and .github/ISSUE_TEMPLATE/**. A workflow skipped by a path filter reports nothing at all — unlike a job skipped by an if: condition, which reports skipped and satisfies branch protection. GitHub therefore waits forever for a check that will never arrive.

Live example: #1863, a two-line fix to AGENTS.md and CONTRIBUTING.md that unbreaks main's gate-parity failure. Every check it reports is green; mergeStateStatus is BLOCKED; the two ci.yml contexts are absent from its check list entirely. The fix for a red main cannot land because it is prose.

Why the design is not wrong, only unfinished

ci.yml's own comment states the assumption:

Note merge_group does NOT honor paths-ignore, so a docs-only PR that skips the Rust gate on pull_request still runs the full gate once queued; that is deliberate — the required check must report on the merged result.

That is correct and it requires the merge queue to be enabled. It is not (#1645 option 1, which needs admin). So the filter that was safe under a queue is, without one, a trap.

This also explains prose PRs that did merge: enforce_admins is off, so an admin can bypass. Everyone else waits.

Fix directions

1. Enable the merge queue (Red PRs keep landing on main: enforce_admins is off and the pre-push gate is routinely --no-verify'd #1645). Restores the documented design exactly, fixes this and the BEHIND-deadlock class together. Needs admin.
2. Move the filtering from the workflow into the jobs. Drop paths-ignore from the triggers; add a cheap changes job (dorny/paths-filter or a git diff step) and gate the expensive jobs with if: needs.changes.outputs.rust == 'true'. A skipped job does satisfy a required check, so the contexts always report and a prose PR still costs seconds. No admin needed.
3. A same-name stub workflow on the inverse path filter. Standard practice, but a PR touching both prose and code then produces two check runs with the same name, which is confusing enough to be its own hazard. Least preferred.

Recommend (2) if the queue is not going to be enabled soon — it is self-contained, needs no repository settings, and keeps the cost saving that motivated the filter.

Verify

Open a PR touching only *.md. Today it sits BLOCKED with all reported checks green and the two ci.yml contexts missing. After the fix it either reports them as skipped (option 2) or runs them in the queue (option 1), and merges.

Constraints

• Whatever lands must keep docs-guards.yml and wire-schema.yml doing their jobs — they exist precisely because ci.yml ignores those paths (gate: empty-scope (website-only) pushes still pay wire-schema's cargo build — and the docs/wire-only edit hole behind it #1439).
• Option (2) must not accidentally make every prose PR pay the hour-long Rust gate; the whole point of the filter is that it does not.
• The three context NAMES are branch-protection settings, so any change must preserve them exactly.

Refs #1645, #1439, #1863, #1883

[macanderson]

Concrete new instance of this hole, from today's unbreak of main:

The #1860 squash (4437e98) silently reverted the production half of #1836 — every parallel_safe_names forwarding override across four crates (stella-cli, stella-tools, stella-mcp, stella-serve). Both PRs added a trait-default method at the same seam (after drain_sub_agent_spend_usd in each tool-stack decorator); each conflict was resolved keeping only #1860's drain_wait_request. Because the method has a default impl, no compiler error resulted — six tests failed across four crates, three of them one crate past where make test bails. Sibling task calls serialized again in every real session: the third resurrection of #1776's defect.

#1860 was green on its PR checks, which means the tree it actually landed was never the tree CI tested — exactly the stale-green merge this issue exists to close. #1894 fixed main's other three red gates but could not have caught this one.

Fixed on main by 31aa45c (restores all eleven forwarding impls verbatim from #1836, plus the TaskTap tests module and the production-stack witness the_production_tool_stack_forwards_parallel_safe_names). Verified: the six failing tests plus the wait-request/spend twins all pass; clippy -D warnings clean on the four crates.