Revision 4 of `docs/macos-ci-signal-integrity-framing.md` records
implementation findings, not a new design round: §4's acceptance is
unchanged and was approved at revision 3. Two of the four findings
correct this document.
- **§1.3 named the right window and the wrong assertion.**
`leader=exited(signal SIGUSR1)` is rendered only on a FAILED `kill`,
and the USR1 cannot be the call that failed — it is the call that did
the killing. The failing call is the SIGTERM that follows, so
`.expect("TERM delivers")` is what blew up, not the `Running` state
check; `ProcessState` never carries that value and nothing ticks
between the two calls. The row's fragment and mechanism were both
right. Why a group-directed TERM found no group is NOT established
here, and the fix does not depend on it.
- **§1.5 scoped the fix one function too narrowly.**
`wait_for_published_file` gates the real-TUI smoke on the identical
predicate. §1.5's note about the bottom-panel helper is about a
different file and correctly refuses creep there; it does not reach
this one.
- The fixture also had an unnamed second dependency: these signals are
group-directed, so a forked `sleep` is an untrapped group member, and
survival depended on bash and dash suppressing the fork for the last
command of a `-c` script.
- R2's witness could not reproduce the row on Linux, so it widens the
pre-trap window deliberately and proves survival by exit disposition
rather than by an absence observed within a window.
`docs/ci-red-signatures.md` gains the sentence R3 needs most: **R2's
retirement does not touch it and must not be read as touching it.** The
hardening changed a fixture and no product code; the same
group-directed `kill` runs. Because the fixture changes the shape of the
signalled group, a change in how often R3 appears would be evidence
about FREQUENCY, not about cause — and its retirement is still a
diagnosis by the process-signal / reap-ledger lanes.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three corrections.
"NO OCCURRENCE WAS EVER OBSERVED" OVERSTATED WHAT THE AUDIT CAN SAY.
Someone may well have seen one of these fail and simply not recorded it;
what is established is the absence of a RECORD. The framing now says
"linked or captured" and states the distinction explicitly, because an
audit that claims to know what nobody saw is making the same kind of
unfounded assertion this lane exists to remove — one level up.
A missing closing quotation mark in acceptance 3.
THE LANE CHECKPOINTED THE REVIEWED HEAD, WHICH GOES STALE ON THE NEXT
PUSH — the exact mechanism by which #171 became invisible while it
drifted 153 commits. Recording one head is a snapshot; what a resume
ledger needs is the sequence. It is now a table of head -> CI run ->
result, newest last, with the rule stated: the branch tip is
authoritative over any row, verified by `git rev-parse`, because the
table is written by hand and the tip is not.
Verified: fmt, diff-check.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Five corrections, one blocking.
BLOCKING — the contract, not the implementation, was what needed
changing. Revision 2's acceptance 3 offered a binary: carry an incumbent
in with a signature and evidence, or remove it as never substantiated.
Stage 1 shipped a THIRD state because both incumbents are neither. The
framing is now revision 3 and names all three states, because a
governing criterion that says "two" while the branch does five is the
framing describing something that does not exist.
"MECHANISM NAMED" OVERSTATED THE EVIDENCE, and the phrase is retired.
The a33 audit proves an assertion string exists; the m6_8 audit proves a
test is timing-based. NEITHER ESTABLISHES A FAILURE MECHANISM — no
occurrence was ever observed, so nothing is known about how, or whether,
either fails. They are now AUDIT NOTES A1/A2 rather than registry rows,
with `R`-numbers reserved for signatures carrying linked evidence. The
distinction is not row-versus-weaker-row: a row says "this was seen,
here is the evidence", a note says "someone recorded a belief and no
occurrence backs it". Both remain unmatchable, so a red in either test
is a new incident.
R2's SIGNATURE WAS WEAKENED AND IS RESTORED. Splitting
`leader=exited(signal SIGUSR1)` into `leader=exited(` plus `SIGUSR1`
would match a child that exited by some OTHER disposition while SIGUSR1
appeared elsewhere in the output — precisely the name-style
over-matching this registry exists to refuse, reintroduced one level
down as fragment-style over-matching. It is one exact fragment again,
and the row says why.
THE HANDOFF STILL ISSUED LIVE IMPERATIVES. Its historical block opened
with "rerun isolated before treating a sweep failure as a regression"
and closed with "rerun the test alone before investigating", so the
supersession note I added sat between two instructions it contradicted.
Both are rewritten as record: the block now reports what that lane
OBSERVED, and the retired instruction is marked retired with its reason
— an isolated green reproduces nothing about a load-sensitive failure.
#215 HAD NO LANE, in the file that requires one for every open PR and
records why: #171 drifted 153 commits while invisible there. That is the
same defect, caught in review rather than 153 commits later. The lane
now carries branch, base, PR, reviewed head, what Stage 1 ships, the
verification, what Stage 2 owes, and the recovery worktree command. Both
snapshot headers are bumped.
Also narrowed a claim the PR body overstated: the registry is NOT
macOS-only. All four EVIDENCED rows are macOS, which is a property of
these occurrences; A1's job is `GPU Render (headless)`, which runs on
Ubuntu, and A2's job was never recorded. A future row from any job
belongs in the same table.
Verified: fmt, diff-check, clippy, --lib 1896, --lib --features crdt
2081.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Define signatures as normalized selector/job/output matches, preserve
historical evidence while centralizing live triage policy, and replace
green-run retirement with causal disposition.
Also fix the rerun-rule contradiction and move the questions out of the
inline-math namespace.
Four red CI incidents across #213 and #214 were each judged "not caused
by this PR", and #214's case is airtight: it is docs-only and its tree is
byte-identical to a green main. THAT PROVES THE PRs DID NOT CAUSE THEM.
It does not prove they are harmless environmental noise, and three of the
four have a specific, findable mechanism. This lane separates those two
claims, which the current process conflates.
FOUR INCIDENTS, THREE TESTS, FOUR SIGNATURES. The registry counts
signatures, not test names, because the process test alone produced two
with different mechanisms and different causal status — collapsing them
under one name is how a possible product defect acquires a flake's
immunity.
1. supersede_cancels_in_flight_job_within_50ms —
"supersede did not cancel within 50ms". MEASUREMENT DESIGN. Its
premise is a 15ms sleep asserted-by-comment to mean "the worker
picked the job up"; on a loaded runner it may not have, in which
case the test measures the QUEUED path while claiming the running
one. And the 50ms clock starts before the second dispatch and is
consumed by the test's own tick+sleep pump, so the measured
interval is dominated by when THE TEST got scheduled. Widening the
number would make it pass and measure nothing more.
2. a_successful_signal_disposition — "leader=exited(signal SIGUSR1)".
TEST RACE. Readiness is ProcessEventKind::Started, emitted at
SPAWN, not when /bin/sh has installed `trap '' USR1`. USR1's
default disposition is terminate, so a signal in that window kills
the child. The fixture's own comment states the requirement it does
not enforce.
3. a_successful_signal_disposition — "EPERM,
measured_group=unobservable(ESRCH), leader=live". NOT a test race:
the group-target behaviour #176 and #200 circled and the
reap-ledger lane parked disposition changes pending. Recorded
UNRESOLVED, POSSIBLE PRODUCT DEFECT, with a diagnosis — never a
green rerun — as its retirement condition.
4. terminal_escape_gates — "left: [], right: [49]". TEST RACE.
`wait_for_file` returns as soon as `fs::read` succeeds, which
succeeds on a ZERO-BYTE file; the probe's `open()` creates the file
before `write()` fills it. The predicate is "readable", the
assertion is "contains 1" — the same shape as signature 2, fixable
at the helper so every caller inherits it.
THE EXISTING PROSE IS DUPLICATED AND KEYED BY NAME. Flake claims live in
at least six places, disagree in detail, carry no signatures or evidence
links, and the handoff's list names three tests — two of which are not
among these four incidents, while three of the four are absent from it.
A list that is both stale and incomplete is worse than none: it confers
"known flaky" on whatever happens to be named and withholds it from
everything else. Acceptance 3 therefore AUDITS the existing three: each
is carried in with a signature and evidence, or removed with a note. No
entry survives on reputation.
The rerun rule is REPLACED rather than softened: one rerun reproducing
the SAME signature is evidence of intermittence only; a DIFFERENT
signature, or the same one twice consecutively, requires investigation
or a merge-base control before the red is attributed to the environment.
Quarantine, if hardening fails, is a separate STILL-BLOCKING CI step —
never #[ignore], continue-on-error, or silent retry-to-green. A
quarantine that stops failing the build is a deletion with extra steps.
Framing only. Sequencing is registry first, hardening second, per
review.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Levi Neuwirth