diff --git a/docs/active-work.md b/docs/active-work.md index 24e157b..969532e 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -13,6 +13,10 @@ CI CRDT coverage**, which had been sitting under "NEEDS A LANE" with no branch and no owner since #166. It is implemented on `ci-crdt-coverage` and its block replaces the old one below. +**Updated 2026-08-05.** One lane opened: **macOS CI signal integrity** +(#215, in review), which this file required a lane for and did not have +until review caught it — the #171 defect recurring. Its block is below. + **Updated 2026-08-04.** Four PRs landed since: the CI CRDT coverage lane #209, Distribution Stage 1 #211 (released as **v1.1.0**), the post-release accuracy pass #212, and **bottom-panel Stage 3 #213 — @@ -157,6 +161,62 @@ form. All four steps ran clean. **The two-argument form still does not work** for a remote-only branch (`fatal: invalid reference`), which is why every lane below spells out the `-b` form. +## macOS CI signal integrity — STAGE 1 IN REVIEW, PR #215 + +**This file requires a lane for every open PR** (see the #171/#174 note +above: an open PR is exactly the volatile work this file records, and +#171 drifted 153 commits while invisible here). #215 had none until this +entry — the same defect, caught in review. + +- **Branch `macos-ci-signal-integrity`**, base `githubsucks/main` @ + `bfb97c6`. Framing `docs/macos-ci-signal-integrity-framing.md` + **revision 3**. +- **PR: ** — Stage 1, + docs only. Reviewed at head `d33bf4d` with all 14 checks green + ([run 30950108477](https://github.com/levineuwirth/pmacs/actions/runs/30950108477)); + one review round since. +- **What Stage 1 ships:** `docs/ci-red-signatures.md`, the single + authority for judging a red CI run. Rows key on **signature** — + selector + job/flavor + every required fragment, normalized — so **a + test-name match confers nothing**. The rerun rule is replaced: a green + rerun establishes **intermittence only**; the same signature again is + a second occurrence and stays blocking; a different signature is a new + incident. Retirement is **causal**, never a count of green runs. +- **Four incidents, three tests, four signatures.** The process test + produced two — one a test race (R2), one an **unresolved possible + product defect** (R3) that no rerun can clear. Counting by test name + would have hidden the second behind the first. +- **The audit found a third state the framing did not allow**, which is + why the framing is at revision 3: two incumbents have a historical + claim but **no linked occurrence ever**. They are **audit notes A1/A2**, + not rows — unmatchable by construction, so a red in either is a new + incident. The registry is therefore *stricter* than the list it + replaces: nothing is pre-excused. +- **Verification:** fmt, diff-check, clippy with and without `crdt`, + `--lib` 1896, `--lib --features crdt` 2081, pmacs-protocol 19, m4 149, + required GPU 221. All three named tests pass locally on Linux — + consistent with R1–R4 being macOS occurrences, and **not evidence + about any of them**. + +### Stage 2 — hardening, NOT started + +Waits on #215's merge. Owns R2's trap-readiness fix and R4's +`wait_for_file` predicate, each with a **repetition set** rather than a +single green run, plus a discriminating witness that fails without the +fix. **R1 is referred to the async-runtime lane** (Q#MCI3) rather than +patched: widening its budget would make it pass and measure nothing +more. **R3 stays unresolved** and belongs to the process-signal / +reap-ledger lanes. + +Recovery from a clean checkout: + +```sh +git fetch githubsucks +git worktree add ../pmacs-ci-signals \ + -b macos-ci-signal-integrity \ + githubsucks/macos-ci-signal-integrity +``` + ## CI CRDT coverage — MERGED (#209); kept for its three follow-ons **Rewritten, not removed.** Rule 4 removes a lane when its ARC is done; diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index 7c0d432..b165193 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -1,6 +1,10 @@ # Agent handoff — cross-machine continuity -**Last updated: 2026-08-04, as bottom-panel Stage 3 #213 — the adopter +**Last updated: 2026-08-05.** The live CI-triage rule in §5 now points +at `docs/ci-red-signatures.md` (PR #215, in review), which keys on +signature rather than test name; the hazards list this file used to +carry is retired, and its two unevidenced entries are audit notes there. +Previously **2026-08-04, as bottom-panel Stage 3 #213 — the adopter default flip, which COMPLETES ARC 7: omitting `display` now means the panel, and the workbench's panel half is done on both frontends. Beneath it the post-release accuracy pass #212 and Distribution Stage 1 #211 — @@ -2003,12 +2007,14 @@ before trusting them: separate proposals, each owed its own evidence. - **GPU on the laptop**: AMD Radeon 780M (RADV) — native Vulkan, `PMACS_REQUIRE_GPU=1` works without lavapipe. -- **Flaky-under-load tests — rerun isolated before treating a sweep - failure as a regression.** *(Historical, from this lane. For LIVE - triage of a red run use `docs/ci-red-signatures.md`, whose rerun rule - supersedes "rerun isolated" — a green rerun proves intermittence only. - `m6_8_supervisor_reaps_all_children_across_cycles` is R6 there, with - no signature ever captured.)* The m8 daemon tests and the m6 +- **Flaky-under-load tests — what this lane OBSERVED.** *(Historical + record. This bullet no longer states a triage rule: for judging a red + run, `docs/ci-red-signatures.md` is the authority, and its rule + supersedes "rerun isolated" — a green rerun establishes intermittence + only, never environmental cause. + `m6_8_supervisor_reaps_all_children_across_cycles` is **A2** there — + an audit note, not a matchable row, because no signature was ever + captured.)* The m8 daemon tests and the m6 process/PTY tests (`m6_1_pty_mode_lifecycle_started_then_exited`, `m6_8_supervisor_reaps_all_children_across_cycles`) are timing-based; `editor::composition_overhead_under_ten_percent` is a render-ratio @@ -2017,9 +2023,11 @@ before trusting them: `real_tui_terminal_smoke_restores_host_after_output_input_resize_scroll_copy_and_bell`; the complete failed-job rerun passed. The required-GPU gate also failed once in `headless_diag_face_recolors_band_counter_despite_unchanged_text`, then - passed both an isolated single-thread rerun and the full 139-test rerun. A - lone timing failure → rerun the test alone (`-- --test-threads=1`) before - investigating. Run the workspace + passed both an isolated single-thread rerun and the full 139-test rerun. + *(That "rerun the test alone before investigating" instruction is + retired — an isolated green reproduces nothing about a load-sensitive + failure and establishes intermittence at most. See the registry's + rerun rule.)* Run the workspace sweep as ONE `cargo test` invocation piped to a full log — a double invocation + `grep -c "test result: ok"` can mask real failures with a misleading `0`. diff --git a/docs/ci-red-signatures.md b/docs/ci-red-signatures.md index 45adff8..3c702f9 100644 --- a/docs/ci-red-signatures.md +++ b/docs/ci-red-signatures.md @@ -69,7 +69,11 @@ by removing or explaining its mechanism: | **test race** | hardening that removes the named mechanism, plus a discriminating witness for the stronger predicate | | **measurement design** | the owning lane replaces or justifies the measurement and pins the resulting claim | | **unresolved** | diagnosis and an explicit disposition | -| **mechanism named, no occurrence** | a linked occurrence promotes it to one of the above; sustained absence is not retirement, because nothing was ever measured | + +**Audit notes (`A`-numbers) have no retirement condition**, because they +have nothing to retire — see that section. A linked occurrence promotes +one into an `R` row; absence retires nothing, because nothing was ever +measured. Main-branch greens are **occurrence evidence** and accumulate toward a rate. They retire nothing by themselves. Retired rows stay in this file @@ -104,7 +108,7 @@ and measure nothing more.** |---|---| | **selector** | `--lib process::tests::a_successful_signal_disposition_depends_on_whether_it_is_fatal` | | **job / flavor** | macOS / lua54 | -| **required fragments** | `leader=exited(` + `SIGUSR1` | +| **required fragments** | `leader=exited(signal SIGUSR1)` — **one exact fragment, not two loose ones**. Split into `leader=exited(` and `SIGUSR1` it would match a child that exited by some *other* disposition while `SIGUSR1` appeared elsewhere in the output | | **causal status** | **test race** | | **evidence** | [#213 run 30927084982 attempt 1](https://github.com/levineuwirth/pmacs/actions/runs/30927084982/attempts/1) | | **retirement** | the fixture proves the trap is installed, with a witness that fails without it | @@ -153,40 +157,54 @@ on a **zero-byte file**. The probe writes readiness with --- -## Audited incumbents — mechanism named, no occurrence recorded +## Audit notes — historical claims with no linked occurrence -These were carried in the handoff's hazards list **without evidence**. -The audit found the tests real and the mechanisms plausible, so they are -neither confirmed nor deleted: they are recorded honestly as unmeasured. +**These are NOT registry rows.** They carry `A`-numbers, not `R`-numbers, +because nothing here can be matched against a red run and nothing here +confers any status. -**Nothing here confers "known flaky".** A red matching one of these is a -first recorded occurrence and should be investigated, not reruns-to-green. +They were named in the handoff's hazards list without evidence. The audit +found the tests real and the claims recorded in good faith — but **an +assertion string existing is not a mechanism, and "timing-based" is not +an observation.** No occurrence of either was ever linked, so nothing is +known about how either fails, or whether either has failed. -### R5 — GPU terminal cell background did not paint +Deleting them would discard a real recorded belief. Listing them beside +the evidenced rows would grant the reputation this file exists to deny. +So they are stated as what they are: **claims awaiting a first +occurrence.** A red in either test is a first recorded occurrence, to be +investigated and then promoted to an `R` row — not matched against +anything here. + +### A1 — GPU terminal cell background did not paint | field | value | |---|---| | **selector** | `-p pmacs-gpu a33_headless_terminal_frame_paints_cells_without_document_layers` | | **job / flavor** | GPU Render (headless), under parallel load | | **required fragments** | `the terminal cell background did not paint` + `blue pixels` | -| **causal status** | **mechanism named, no occurrence recorded** | -| **evidence** | **none linked.** The assertion string is real (`pmacs-gpu/src/main.rs:17973`); no run was ever cited | -| **retirement** | a linked occurrence promotes this row; absence retires nothing, because nothing was measured | +| **status** | **historical claim, no linked occurrence** | +| **what IS established** | the test exists and the assertion string is real (`pmacs-gpu/src/main.rs:17973`). That is all | +| **what is NOT** | any mechanism, and any occurrence. No run was ever cited | +| **promotion** | a linked occurrence makes this an `R` row with a signature. Absence retires nothing, because nothing was measured | -### R6 — supervisor reap across cycles +### A2 — supervisor reap across cycles | field | value | |---|---| | **selector** | `--test m6_8_multi_repl_acceptance m6_8_supervisor_reaps_all_children_across_cycles` | | **job / flavor** | not recorded | | **required fragments** | **not recorded** — no signature was ever captured | -| **causal status** | **mechanism named, no occurrence recorded** ("timing-based", 10 cycles) | -| **evidence** | **none linked** | -| **retirement** | a linked occurrence with a signature promotes this row | +| **status** | **historical claim, no linked occurrence** | +| **what IS established** | the test exists and runs 10 cycles; the handoff called it "timing-based" | +| **what is NOT** | any mechanism, any signature, any occurrence | +| **promotion** | a linked occurrence *with a captured signature* makes this an `R` row | -**R6 cannot currently be matched.** Without required fragments there is -no rule to apply, so a red in this test is a new incident by default. -That is the correct outcome for an entry that never carried evidence. +**A2 cannot be matched, and neither can A1** — that is what makes them +notes rather than rows. A red in either test is a new incident by +default. That is the correct outcome for an entry that never carried +evidence, and it means this file is **stricter** than the list it +replaces: nothing is pre-excused. --- @@ -201,6 +219,12 @@ That is the correct outcome for an entry that never carried evidence. Four incidents, three tests, **four signatures**. Count signatures: the process test contributed two, and only one of them is a test bug. +**All four *evidenced* rows (R1–R4) are macOS.** That is a property of +these occurrences, not of the file: **A1's job is `GPU Render +(headless)`, which runs on Ubuntu**, and **A2's job was never +recorded**. Nothing here is macOS-only by construction, and a future +row from any job belongs in the same table. + The #214 occurrence is the strongest available evidence that these are not caused by the PRs they appeared on — that PR is **docs-only and its tree is byte-identical to a green `main`**. It is not evidence that any diff --git a/docs/macos-ci-signal-integrity-framing.md b/docs/macos-ci-signal-integrity-framing.md index c3ba89d..b7d1a40 100644 --- a/docs/macos-ci-signal-integrity-framing.md +++ b/docs/macos-ci-signal-integrity-framing.md @@ -1,7 +1,27 @@ # Framing — macOS CI signal integrity: a signature registry, then hardening -**Revision 2.** Status: framing only. No branch work beyond this -document. Scouted against `githubsucks/main` @ `bfb97c6`. Revision 2 +**Revision 3.** Status: **Stage 1 implemented** on +`macos-ci-signal-integrity`, PR #215. Scouted against +`githubsucks/main` @ `bfb97c6`. + +**Revision 2 → 3** exists because the implementation discovered a state +the contract did not allow, and the contract — not the implementation — +was what needed changing. Acceptance 3 offered a binary: carry an +incumbent in with a signature and evidence, or remove it as never +substantiated. **Both incumbents are neither**, and shipping a third +state while the governing criterion still said "two" would have made the +framing describe something the branch does not do. + +Revision 3 also **retires the phrase "mechanism named"**, which +overstated what the audit found. The a33 audit proves an assertion +string and a historical claim exist; 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 either fails. They become +**audit notes A1/A2**, not registry rows, and `R`-numbers are reserved +for signatures with linked evidence. + +Revision 2 separates a machine-matchable signature from verbatim, variable CI output; preserves historical incident evidence while centralizing live triage policy; gives retirement a causal rule rather than an arbitrary @@ -257,10 +277,21 @@ everything else. may gain a registry status link, but its evidence and reasoning are not replaced. Forward-looking risk statements are audited as risks, not silently promoted to known flakes. -3. **The three tests named in the current handoff list are audited**: - each is either carried into the registry with a signature and - evidence, or removed with a note saying it was never substantiated. - No entry survives on reputation. +3. **The three tests named in the current handoff list are audited**, + into one of **three** states — the third was found by doing the audit + and is why this is revision 3: + - **carried as a registry row** (`R`-numbered) when a signature and a + linked occurrence both exist; + - **removed** when nothing substantiates it at all; + - **recorded as an audit note** (`A`-numbered) when a *historical + claim* exists but **no occurrence was ever linked**. An audit note + is not a registry row, cannot be matched against a red run, and + confers nothing. + + **No entry survives on reputation, and an audit note is not a weaker + row — it is a different kind of statement.** A row says "this was + seen, here is the evidence"; a note says "someone recorded a belief + and no occurrence backs it. 4. **The rerun rule is replaced**, not softened: - a **green rerun after a red** establishes intermittence only; it does not establish environmental cause, harmlessness, or retirement; @@ -304,9 +335,13 @@ everything else. recorded in the CI CRDT lane. Related in spirit, separate in scope. - **A general flake-rate dashboard.** The registry accumulates occurrences; turning that into a rate with alerting is its own thing. -- **Linux and GPU flakes.** `a33_headless_terminal_frame_paints_...` and - `m6_8_supervisor_reaps_...` are in the current handoff list and get - audited under acceptance 3, but this lane's incidents are macOS. +- **Linux and GPU flakes.** `a33_headless_terminal_frame_paints_...` + and `m6_8_supervisor_reaps_...` were audited under acceptance 3 and + became **audit notes A1/A2** — claims with no linked occurrence. + **A1's job runs on Ubuntu**, so the registry is not macOS-only even + now; A2's job was never recorded. This lane's four *evidenced* + incidents are macOS, which is a fact about them and not about the + file. ---