fix(GATE-ANCHOR-PER-JOB): each diff gate anchors on its own last STEP verdict, so a red main can return to green (#1773)

[localai-bot]

A diff-scoped gate on the push lane used to ask the runs endpoint for
status=success. That is the RUN's own conclusion, the one thing
scripts/main-baseline.py has said since #274 must never be read, and it is
wrong in both directions: it reads success over a red continue-on-error job,
and cancelled over a job that ran to completion. Because a successful run was
exactly what a red gate blocked, the anchor froze while the range widened on
every push, re-flagging the commits blocking it. Measured at 21abaf169: 484
commits, anchored eleven days back.

Worse, a shared base resolved in a SEPARATE job is a race. The consumers carry
if: always(), so they outlive that job's cancellation. On run 32625264281 the
resolver was cancelled, the shared string rendered empty, and
documentation-checkpoint fell back to PUSH_BASE and passed over one push,
the same gate that fails over 484 commits whenever the resolver survives. The
verdict on main was decided by which job won a cancellation race.

Each diff-scoped job now resolves its OWN anchor, in its own first step.

The unit is the STEP, not the job

The first round of this pull request anchored on the job, and the fresh review
failed it on that. It re-created #863's hole one level down. GitHub concludes a
job failure the moment any step fails and marks every remaining step
skipped, so "the job concluded" reads failure over a gate that refused the
range and over a gate that never executed, and cannot tell the two apart. Both
agent-record and commit-protocol-tag place their diff-scoped gate after
other steps.

Measured on commit-protocol-tag, where the strict trailer walk runs nowhere
else on the push lane:

run	head	job	strict-trailer step
32599040638	038ff61e5	success	success
32601353990	1a1d17e53	failure	skipped
32608320394	6354755ba	failure	skipped
32613454280	b508cbce6	failure	skipped
32616777372	66d1b0a90	failure	skipped
32623377380	a4f2a9585	failure	skipped
32625264281	1fdd3e26d	success	success

A job-level anchor walks 038ff61e5..a4f2a9585, six commits, straight past.
agent-record is twelve commits on the same shape, rescued only because
documentation-checkpoint runs the same checker, which is luck rather than
construction.

Three things enforce the step as the unit. --gate-step is required and the
flag-less form exits 2, so the hole cannot be re-created by omitting a flag.
steps_concluded reads steps[].conclusion and treats an absent step as no
verdict. Every gate step carries
if: !cancelled() && steps.checkout.outcome == 'success' && steps.anchor.outcome == 'success' && env.GATE_ANCHOR_DEGRADED != 'true',
so an earlier failure cannot silence it and the three cases where a conclusion
would be a lie produce a skip instead. documentation-checkpoint ran two
diff-scoped checkers in ONE step under set -eu, where the first one's failure
aborted before the second ran while the step still concluded, and that step is
now split in two.

The floor, and a degraded query

The floor read one run short, so the oldest candidate's own head fell outside
the range the floor exists to guarantee. It now reads window + 1 runs, which
costs nothing. Past the window commits still roll off permanently, and that is
stated with its bound and asserted by a test rather than denied: it happens only
after a gate has returned no verdict on 20 consecutive pushes, and only after
the pull request lane already gated those commits at merge.

The floor could also land on the run being pushed. With one push run in the
window runs[-1] IS runs[0], so the anchor resolved to the head being pushed
and base..head was EMPTY: a gate reporting success over no commits at all, and
CONCLUDING on it, which advanced its own anchor. Latent on this repository, whose
window is always full, and reachable on a fork's first push. There is nothing to
floor on with a single run, so the answer is the clean absence. Below
window + 1 runs the off-by-one is not repairable at all -- the oldest available
run is itself a candidate, and a workflow_run object carries head_sha and no
parent -- so that residual is asserted by a test rather than implied away.

A degraded query was swallowed by || true, leaving an empty anchor that the
gate silently replaced with PUSH_BASE. Under a step-level anchor that is not
merely dishonest but a hole, because the narrowed pass advances the anchor past
everything the narrowing dropped. --gate-anchor now exits 3 on
REMOTE_UNVERIFIED and 1 on a clean absence, the split AGENTS.md already
documents for scripts/agent-pr-body.py, and a degraded read SKIPS the gate.

push_runs broke that split from underneath. It returned an empty window --
rc 1, and therefore a NARROWED range -- for any payload that was not a dict
carrying workflow_runs, where jobs_for has always answered
REMOTE_UNVERIFIED for the same case. Driving the real main through a fake
gh_api, a list payload, a null payload and GitHub's {"message": "Not Found"}
error object all exited 1 where they had to exit 3. All four shapes exit 3 now,
and a genuinely empty window still exits 1, because collapsing the two in either
direction is its own defect.

The five commits, and the landing rule

The external-fork hypothesis is refuted. check-role-discipline.py reads no
ref: for a single-parent commit arrives_via_row_pr is commit-message text and
nothing else, and the one NON-fork commit of the five fails identically. What
the five share is a subject with no (#N).

The mechanism is labelled INFERRED, because the forge records no merge-input
payload and the review was right to say so. Four of the five pull requests carry
a "Maintainer change on top" section, not three as first written, and all five
were merged by the same account that appends (#N) correctly on every other
squash. check-role-discipline.py is not touched and no exception is recorded.
AGENTS.md gains a landing rule instead, which names the flag and the endpoint
field, binds whoever performs the MERGE rather than the author, and says plainly
that no gate can catch it. The third review found AGENTS.md still asserting the
inferred mechanism as fact and naming a specific account as the cause, after
this spec and the index row had both retracted it. It is the one file every
agent loads automatically, so it carried the strongest version of a claim the
rest of this pull request hedges, and it would have been quoted forward as
measured. The RULE is unchanged and still one flag; the causal and the account
attribution now match the evidence, and the reader is pointed at the spec for
the two facts that weaken the hypothesis.

.agents/issue-index.md's row is corrected to match, because that row is ADDED
by this pull request and stated both retracted claims as fact: the inferred
commit_title mechanism, and the job-level anchor the review refuted. The spec's
first reason for leaving it was wrong -- the row has not landed, and
scripts/check-issue-index-append-only.py diffs the merge base against the head,
so amending a row this branch also added stays a pure addition. With
squash_merge_commit_message = PR_BODY exactly one version of that row will ever
exist on main, so before the merge is the last moment it can be right.

The guards are RESOLVED now, not grepped

The second review passed the design and failed the guards around it. The test
holding the five gate-step if: conditions asserted four SUBSTRINGS. Appending
|| true to all five leaves every one of them byte-for-byte intact, turns the
whole conjunction into the constant true, and restores the degraded-read
narrowing in full -- 99 tests, OK, All gates green., no skip. It now resolves
the guard to a boolean over all sixteen states it has to decide, reusing the
expression evaluator this suite already carried for concurrency keys; the same
mutation reports 75 failures across all five steps.

The one-gate-per-step test had the same shape. It read the first python3 <arg>,
so a git fetch planted before check-now-current.py was invisible, and
if not checkers: continue exempted the one gate step whose whole body is an
inline shell gate. Both mutations reported 99 tests, OK. Under set -eu that
command aborts the step, the step concludes failure, and steps_concluded
reads the conclusion as a verdict about a gate that never ran. The property is
held by resolving the body now: the range prelude may bind variables and call
set, [, echo and :, the first command that is not one of those IS the
gate, and it must consume the range. Both mutations red, and the inline-shell
step is in the population.

The prelude refusal covered the wrong statements

The third review confirmed the TREE as correct, and failed the pull request
because a test and a record assert a completeness they do not hold. That is the
same class as the two findings above, one layer further in.

The repair described in the previous section stated one residual and had three
escapes past it. The parser returned on any name=... head BEFORE the
$(/backtick refusal ran, so a binding carrying a substitution was never
examined; and [ was allowlisted on the reasoning that its if/|| consumes
the failure, while the parser splits on || and discards it, so nothing checked
that a given [ HAS one. Four injections immediately before
check-now-current.py, each executed under bash with python3 shimmed:

injected before the gate	step body under set -eu	gate ran	suite
base="$(git rev-parse --verify "${base}^{commit}")"	rc 128 when the anchor is absent, rc 0 when it resolves	0x	Ran 109, OK
_p="$(git fetch -q origin nope)"	rc 128	0x	Ran 109, OK
_p=`git fetch -q origin nope`	rc 128	0x	Ran 109, OK
[ -f .git/NO_SUCH ]	rc 1	0x	Ran 109, OK

The first is the one to worry about, and its two rcs are the point. Normalising
the anchor to a full commit id right before the gate is the natural next edit in
that step; it is harmless while the anchor resolves and aborts at 128 once it
does not, which is the shallow fetch, the rewritten branch, and the floor SHA
aged out of the window. The step then concludes failure over a gate that never
executed, which is the defect this test exists to close.

commands_in becomes statements_in. It returns bindings as statements instead
of dropping them, and it keeps the operator that follows each piece, because
whether a failure aborts the step depends on what comes after it. The refusal
covers every statement before the gate, and a [ is admitted only where an
if/while header or an ||/&& reads its status. It discriminates rather
than banning: [ -f .git/NO_SUCH ] || echo missing, an if header form and a
plain binding all stay green, and the shell agrees with the test on each. The
nine shapes the previous round caught still red. Two residuals are now stated on
the test instead of overstated.

Three more repairs ride with it. baseline_runs, the advisory lane's reader,
had never been executed by any test and reported an unreadable forge to a human
as a clean absence -- a list, a null and {"message": "Not Found"} each printed
"No completed baseline run found on main." with an instruction to trigger the
first run. The rc was never wrong, so nothing read it as a pass; what was wrong
is that unknown was reported as absence, and jobs_for beside it already
refused those shapes. test_the_checker_resolves_no_ref_to_decide_arrival
forbade origin/, ls-remote and for-each-ref in the RAW source, so a future
comment explaining that this checker resolves no ref would red it with a message
about a lookup that is not there; it now reads the source with comments and
docstrings blanked and string literals kept, which is where a real lookup lives.
And the spec's own count of the gate-step guards said four in one line and five
in another; measured from ci.yml it is five.

Evidence

test_no_commit_is_ever_skipped is re-expressed at the granularity that can
actually fail. The union of the ranges was never the property: a job-level
anchor keeps that union whole while the gate is skipped on every push. Against
the unmodified implementation it reports commits with no verdict from any run that ran the gate: ['p2', 'p3']. tests/scripts/test_main_baseline.py reports
Ran 111 tests, OK, up from 82, then 99, then 109.
tests/scripts/test_check_role_discipline.py is Ran 22 tests, OK.
scripts/agent-preflight.sh reports All gates green., rc 0.

Sixteen mutations across the first two review rounds and twenty-six probes in
the third, each printed with
git diff --stat, parsed -- PyYAML for ci.yml, ast.parse for the scripts --
to prove it was not a syntax error wearing a pass, and restored against a
recorded sha256 with an empty git status --porcelain, an empty git diff, and
__pycache__ cleared under PYTHONDONTWRITEBYTECODE=1 on both sides. That last
step is not ceremony: a same-length mutation and a same-second restore both
satisfy Python's (mtime, size) cache validation, and one restored file in the
previous round kept running the mutant's bytecode from a provably clean tree.

Live anchors on origin/main at c98ffd4d0: commit-protocol-tag resolves a
verdict anchor at 21abaf169, while agent-record and
documentation-checkpoint fall back to the window floor 08c81a892. ci.yml
parses under PyYAML with an explicit duplicate-key scan reporting 0, and a
job-by-job comparison against origin/main reports 17 jobs on both sides, none
added, none dropped, no job-level if: and no needs: changed.

git diff --numstat origin/main -- .agents/issue-index.md is 2 0, and
scripts/check-issue-index-append-only.py returns OK.

One gap is filed rather than repaired here. scripts/check-symbol-anchors.py
resolves a path::Symbol citation, so a document that cites a symbol as a bare
backticked name with no path is outside its population -- which is why this pull
request's own rename in 26def4c8f left .agents/specs/ci-concurrency.md
naming a test that does not exist, with every gate green. The stale citation is
repaired here. Teaching the checker to resolve a bare identifier changes checker
semantics and needs its own row, spec and red-before evidence, and it carries a
real design question about which backticked tokens are citations at all. Tracked
as #1787, owned by this row's spec under ## Owed.

Refs #1764 (the live reds; its documentation-checkpoint item is what this
addresses, and its two other items stay open), #274, #822, #863, #873, #1262
(the landed exception whose argument this row invalidates, rewritten in place),
#1787.

Closes #1773

FOLLOWING_AGENTS_PROTOCOL

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: AGENT:claude-opus-5 [claude-code]