claw: push_gate.t27 -- skip a fix push that only restarts required checks #10606

What

Every push to a PR head restarts all of its checks at the back of the Actions queue, the four required ones included. The queue sat at 800 to 900 runs all of 2026-10-18.

At about 18:46 UTC an Auto-fix event reported claw-sarif red on #10585. Three facts about that red:

• It was the App-token error that claw-sarif: ask for no token without a changed .t27, degrade to a step-summary note when the App cannot mint one (Closes #10501) #10568 had already fixed on master.
• claw-sarif is not a required check.
• claw: claw-t27f/suggest/refresh pass with a note when the App token cannot be minted; claw-refresh can read the queue (#10576) #10585 does not touch the claw-sarif job.

The lane merged master and pushed anyway. That push fixed nothing that would land: the squash merge takes master's job regardless. Its only effect was to restart the PR's four pending required checks. #10563 and #10577 show the same red claw-sarif, and the same push would cost them the same.

Proposal

specs/claw/push_gate.t27 decides each lane push before it happens.

• A new PR, or pushing a held branch: hold it while more than QUEUE_LIMIT runs are queued, or when the queue could not be read. The limit is refresh.t27's constant, imported rather than copied.
• A fix push:
  • push when a required check is red;
  • push when the PR's own diff causes the red;
  • skip when master already fixed the red job;
  • skip, and fix it on master, when the red belongs to master.
• A fix push is never held for the queue.
• An unknown push kind holds.

Each verdict comes with a one-line reason: V TAB push|hold|skip TAB why.

Not in scope

• Reading the flags from GitHub. The caller supplies them; a workflow or tri wiring is a later step.
• Undoing the claw: claw-t27f/suggest/refresh pass with a note when the App token cannot be minted; claw-refresh can read the queue (#10576) #10585 push. Its required checks are queued again either way.

Checklist

• Spec with tests, including the claw: claw-t27f/suggest/refresh pass with a note when the App token cannot be minted; claw-refresh can read the queue (#10576) #10585 case
• t27c test-report 14/14 with 0 vacuous, t27b 14/14 (arm64 under qemu), six mutations each fail, gen-c and gcc clean, seal saved
• Ships in the same PR as queue_cost.t27 (claw: queue_cost.t27 -- job-time share and queued-run classes, so the queue measurement is reproducible (#10590) #10600): one run set instead of two. Commit e3fd46f on branch claw-queue-cost. Held: push_gate itself says hold at 834 queued.
  • 2026-10-18 19:25 UTC: master 8626ac0 merged into the branch locally (clean, not pushed). On that tree t27c reports 0 fail and 0 vacuous, and t27b passes 62 of 62 across the five specs the branch adds or seals. seal --verify matches all five. Still held at 573 queued.
• The Auto-fix path reads the three flags and takes this module's verdict before any push (lane procedure, tick 9)
• req_red is computed, not set by eye: specs/claw/required_red.t27 (commit 35e0e61 on the held branch) reads the newest run per required check (validate, check-linked-issue, parse-ratchet, own-language) and says true, false or unknown. A red claw-sarif (the claw: claw-t27f/suggest/refresh pass with a note when the App token cannot be minted; claw-refresh can read the queue (#10576) #10585 push) reads false. t27c 9/9 with 0 vacuous, t27b 9/9, five mutations caught, gen-c and gcc clean, seal saved.

Refs #10600, #10585, #10590

🤖 Generated with Claude Code

User Scenarios

• Given a fix push for a PR where a required check is red and the PR's own diff causes the red, When the push gate evaluates, Then it verdicts push with a reason citing the PR's own changes.
• Given a fix push for a PR where a non-required check (claw-sarif) is red, master already fixed that job, and the PR does not touch that job, When the push gate evaluates, Then it verdicts skip with a reason citing master's fix.
• Given a new PR or held-branch push when the Actions queue shows 834 runs queued (above QUEUE_LIMIT), When the push gate evaluates, Then it verdicts hold with a reason citing the queue depth.

Requirements

• FR-001: The spec MUST import QUEUE_LIMIT from refresh.t27 rather than copying the constant.
• FR-002: For a new PR or held branch, the spec MUST verdict hold when queued runs exceed QUEUE_LIMIT or the queue could not be read.
• FR-003: For a fix push, the spec MUST verdict push when a required check is red and the PR's own diff causes the red.
• FR-004: For a fix push, the spec MUST verdict skip when master already fixed the red job.
• FR-005: For a fix push, the spec MUST verdict skip when the red belongs to master (and the fix should be applied on master).
• FR-006: A fix push MUST never be held for queue depth.
• FR-007: An unknown push kind MUST verdict hold.
• FR-008: Every verdict MUST emit a one-line reason in the format V TAB push|hold|skip TAB why.

Success Criteria

• t27c test specs/claw/push_gate.t27 exits 0 with 14 tests passing, 0 vacuous.
• t27b test specs/claw/push_gate.t27 exits 0 with 14 tests passing (arm64 under qemu).
• Six mutation runs each fail (mutation testing passes).
• gen-c specs/claw/push_gate.t27 and gcc build exit 0.
• Seal saved for the spec.

Boundary

• specs/claw/push_gate.t27