From b2aa16d6ed9ce7b9e9dd9f4b81b0455ca9c2b7c3 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Tue, 4 Aug 2026 19:08:39 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20retire=20the=20bottom-panel=20lane=20?= =?UTF-8?q?=E2=80=94=20Arc=207=20is=20done?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rule 4 removes a lane when its ARC is done AND its durable facts are in docs/agent-handoff.md. Both hold: #213 merged, and §1 carries the five facts Stage 3 produced. The lane goes; the distribution and CI-CRDT lanes stay, rewritten, because each keeps named follow-ons. The canonical base and the RECOVERY FLOOR both advance to f186253. The floor moving with the base is this file's own rule, and the reason is worth restating: a check that accepts an older commit than the declared base passes on a tree the rest of the file does not describe. The three places that named cfc1710 — the base line, the prose, and the `git log` verification step — now name f186253 together, because a floor that advances in one place and not the others is worse than one that does not advance at all. TWO CI WEAKNESSES STAGE 3 EXPOSED, recorded in the crdt lane that owns that job rather than lost with the lane being retired: * CI does not pass --no-fail-fast, so a multi-suite break reports as a single-suite one. #213's first crdt failure showed ONE suite where a local --no-fail-fast sweep of the same tree showed THIRTEEN. The Stage 3 census hit the identical trap and recorded it; CI has it too. * The crdt job pairs the heaviest build — lavapipe, full workspace with crdt, the largest test count — with real-PTY smokes on 5-second deadlines. #213 saw two different such suites fail on two runs of the same commit; one was a real regression, the other was load. That ambiguity is the actual problem: a job where noise and signal look alike trains people to rerun rather than read. Neither is a defect and neither is fixed here. They are decisions about what the crdt job should cost, and they belong to whoever picks that lane up. Two ops lessons move to the handoff §5, both learned the expensive way on #213: * A LOCAL SWEEP IS BLIND TO WHICHEVER FEATURE CONFIGURATION IT DOES NOT BUILD. Stage 3's census and every verification sweep ran `--features luajit` without `crdt`, so compile_mode_crdt_acceptance reached CI broken. Sweep both configurations before calling a corpus green. * "MY CHANGE MADE THIS FRAGILE" IS A DIFFERENT FINDING FROM "THIS WAS ALWAYS FLAKY", and only one of them is yours to fix. Two CI runs on one commit failed different PTY/GPU suites — the load-sensitivity signature, on suites the flake list already names. The tell that it was neither: the failures kept landing on GPU TERMINAL tests, and terminal placement was what the PR changed. Ask which tests and why those, before reaching for a rerun. Docs only. Co-Authored-By: Claude Opus 5 (1M context) --- docs/active-work.md | 145 +++++++++++++++--------------------------- docs/agent-handoff.md | 35 ++++++++-- 2 files changed, 78 insertions(+), 102 deletions(-) diff --git a/docs/active-work.md b/docs/active-work.md index f11e10e..733ca6d 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -11,8 +11,15 @@ exercised from this checkout and the `githubsucks` alias was absent and had to be added, exactly as that section anticipates. **One lane opened: 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. Everything -else in this file is unchanged. +`ci-crdt-coverage` and its block replaces the old one 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 — +which completes Arc 7**. Its lane is **removed** per rule 4: the arc is +done *and* its durable facts are in `docs/agent-handoff.md` §1. The +distribution and CI-CRDT lanes are rewritten rather than removed, +because each keeps named follow-ons. **This snapshot is an absorption pass, taken with ZERO open PRs** — the one window in which a ledger refresh has nothing to re-conflict @@ -82,21 +89,23 @@ lesson, §1 for the two framings). are identical on every machine. Remote names are otherwise machine-local: `origin` may name this canonical URL, a release mirror, or something else, and therefore has no authority by name alone. -- Canonical base at this snapshot: - `githubsucks/main` @ `cfc1710` (discovery Stage 1 #207, atop the - ambient-root isolation implementation #206, Journey Stage 1b-3 #205, - 1b-2 #204 and 1b-1 #203, the reap-ledger diagnostic #202, the - isolation framing #201, the process-signal diagnostic #200, the ledger - absorption #199, and the previously recorded landed work). - **Protocol schema support is - `v6..=v21`; the production server-first `Hello` still advertises - v20** — two different facts, and #184 landed only the first. The - previous snapshot named `fbcf235`, and **the - recovery floor advances with it**: the check below now requires - `cfc1710` or newer, so a tree at `fbcf235` no longer passes. That is - deliberate — the floor moves with the base, because a check that - accepts an older commit than the declared base passes on a tree the - rest of this file does not describe. +- Canonical base at this snapshot: **`githubsucks/main` @ `f186253`** + — bottom-panel Stage 3 **#213**, which completes Arc 7, atop the + post-release accuracy pass **#212**, Distribution Stage 1 **#211** + (released as **v1.1.0**, the first release with prebuilt binaries), + and the CI CRDT coverage lane **#209**. Beneath those, `cfc1710`: + discovery Stage 1 #207, the ambient-root isolation implementation + #206, Journey Stage 1b-3 #205, 1b-2 #204 and 1b-1 #203, the + reap-ledger diagnostic #202, the isolation framing #201, the + process-signal diagnostic #200 and the ledger absorption #199. + **Protocol schema support is `v6..=v21`; the production server-first + `Hello` still advertises v20** — two different facts, and #184 landed + only the first. + **The recovery floor advances with the base**, so the check below + now requires `f186253` or newer; a tree at `cfc1710` no longer + passes. That is deliberate — a check accepting an older commit than + the declared base passes on a tree the rest of this file does not + describe. **Lanes below that name an older base have not been re-based; derive their integration surface from `git diff ..main`.** - On the transfer source, `origin/main` named a release mirror at @@ -132,7 +141,7 @@ git worktree list git status --short --branch ``` -The `git log` command must expose `cfc1710` — the base named above — or a +The `git log` command must expose `f186253` — the base named above — or a newer intentional main. Keep this threshold and the canonical-base line in step: a recovery check that accepts an older commit than the base it declares canonical will pass on a tree the rest of this file does not @@ -142,7 +151,7 @@ If it does not, stop and repair the remote/fetch configuration. **This path was exercised, not asserted, at this snapshot** — ahead of a machine move. From an empty directory: `git clone` the canonical URL, add the `githubsucks` alias, `git fetch githubsucks --prune`, confirm -`cfc1710` is an ancestor of `githubsucks/main`, and recover a lane with +`f186253` is an ancestor of `githubsucks/main`, and recover a lane with the three-argument `git worktree add -b githubsucks/` form. All four steps ran clean. **The two-argument form still does not work** for a remote-only branch (`fatal: invalid reference`), which is @@ -166,6 +175,28 @@ Durable facts — the corrections, the traps, the census tool — are in recovered**, the other four excluded with stated reasons. - Branch `ci-crdt-coverage` retained; it carries nothing unmerged. +### Two CI weaknesses Stage 3 exposed — decisions, not defects + +Both surfaced while gating #213 and belong to this lane because it owns +the crdt job. + +- **CI does not pass `--no-fail-fast`, so a multi-suite break reports as + a single-suite one.** `cargo test` halts after a failing binary, so + #213's first crdt failure showed **one** suite when a local + `--no-fail-fast` sweep of the same tree showed **thirteen**. The + Stage 3 census hit the identical trap and recorded it; CI has it too. + The cost of the flag is running the remaining suites on a red build, + which is usually what you want when diagnosing. +- **The crdt job pairs the heaviest build with real-PTY deadlines.** It + installs lavapipe, builds the full workspace with `crdt`, runs the + largest test count, and includes real-PTY smokes with **5-second** + waits. #213 saw two different such suites fail on two runs of the + same commit. One of those was a real regression the flip caused; the + other was load. **That ambiguity is the problem** — a job where noise + and signal look alike trains people to rerun rather than read. + Candidate: longer deadlines for real-PTY assertions in this job + specifically, or serialize the PTY suites. + ### Still owned by this lane, not yet done - **The macOS `crdt` leg.** Deliberately ubuntu-only at first, "decide @@ -311,82 +342,6 @@ them) and why `dired`/`listview` were the correct first two families. Whichever starts second integrates first. -## Bottom-panel lane (Arc 7) — STAGE 3 COMPLETE; ARC DONE, pending PR - -**Arc 7 is finished.** Stage 1 (#155), the Stage 2 framing (#175), -Stages 2A (#177), 2B-1 (#184), 2B-2 (#187) and 2B-3 (#198) are on -`main`; **Stage 3 — the adopter default flip — is implemented on -`bottom-panel-stage3`** and is the arc's last step. Framing -`docs/bottom-panel-stage3-framing.md` revision 3, approved with -amendments after three review rounds. - -**This lane is removed once Stage 3 merges and its facts are in -`docs/agent-handoff.md` §1** (rule 4). It is retained now only because -the PR has not landed. - -- **Branch `bottom-panel-stage3`** off `githubsucks/main` @ `21de0b2`, - pushed, upstream tracking set. Six commits: `fa12095` framing, - `0224c68` census, `41d37fc` shared resolver, `8d14e6a` lane/portability, - `c0eb16b` the flip + test revisions, `5f01ede` the fallback pin. -- **Verification:** full serialized sweep **3449 passed / 0 failed** - against a 3447 baseline (+2 new pins); fmt, diff-check, clippy with and - without `crdt`, `--lib` 1896, `--lib --features crdt` 2081, - pmacs-protocol 19, m4 149, required GPU 221, and - `bottom_panel_stage1_acceptance` 47/47 under both Lua flavors. - -### What Stage 3 changed - -Omitting `display` resolves to the **panel** for listview, compile and -terminal. **Dired keeps `"current"`** — `pmacs.path.directory_handler` -calls it with no `display`, so a flipped default would open `pmacs .` in -a bottom panel. Per-adopter `select`: listview `true`, compile `false`, -terminal `true`. - -Four hand-written copies of the `display` validator collapsed into one -shared `resolve_adopter_display(operation, raw, default)`; the default is -a **parameter**, which is what makes dired's exemption visible at its -call site rather than hidden in a divergent copy. - -### Three defects the flip exposed, each fixed rather than tested around - -- **The outline panel's `on_visit` used the RAW switch** - (`pmacs.window.switch_buffer`), which replaces the buffer in the ACTIVE - window. Harmless while the outline opened into a document window; - once the panel became the default, RET **clobbered the panel with the - source**. The references panel was migrated to `display_file` when the - arc landed — the outline was missed because nothing exercised it from a - panel until the flip. Q#BP11c names this exact corruption. -- **`compile._last` stored only `{cmdline, cwd}`**, so `g` reached - `start_run` with no `display` and took the new default: an explicit - `display = "current"` silently reverted on the next recompile. **An - opt-out that reverts is not an opt-out.** -- **`opts.display` on a nil `opts`** — a regression introduced by the - fix above and caught by `journey_acceptance`, which is what that - ratchet is for. - -### Two contracts now pinned, not merely observed - -- **Compile's chords are PANEL-LOCAL.** All are bound - `scope = "buffer"`, so with `select = false` none dispatch from the - document — `C-c C-k` included. `M-x compile.kill` still reaches the - running slot anywhere via its `or compile_slot()` fallback. A global - chord is a command-surface decision and belongs in its own framing. -- **The two `q` mechanisms are complementary, not competing.** - Presentation history chains in the side slot (`C → B → A → delete`, - Q#BP2c); `p.prev` prevents raw-switch and capability-fallback listview - loops. `s1_12` pins the second with explicit `display = "current"`; - the new `s3_1` pins the first. - -### The census lesson worth carrying past this arc - -**It counted failures, not causes.** Thirteen listview failures had ONE -root cause — a panel is derived-hidden while frame geometry is unknown, -and that suite never declared any because it never needed to. The same -applied to `m4_acceptance` and `vterm_stage2_acceptance`. And -**`--no-fail-fast` is mandatory**: the first sweep reported 2 failures in -1 suite because `cargo test` halts after a failing binary; the real -figure was 37 across 5. - ## Reap-ledger silent failures — MERGED (#202); kept for its parked follow-ons - **Branch `reap-ledger-silent-failures`**, worktree diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index 6b633aa..ca33f92 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -1,9 +1,12 @@ # Agent handoff — cross-machine continuity -**Last updated: 2026-08-01, as Distribution Stage 1 #211 — released as -v1.1.0, the first pmacs release with prebuilt binaries, which makes -journey step 1 reachable without cloning the repository. Beneath it the -docs absorption #210 and the CI CRDT coverage lane #209 — the +**Last updated: 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 — +released as v1.1.0, the first pmacs release with prebuilt binaries, +which makes journey step 1 reachable without cloning the repository — +and the CI CRDT coverage lane #209, the first time CI has ever compiled and run the `crdt` half of the test corpus, closing a gap that left 279 tests (including a REQUIRED `CLAUDE.md` gate) unexecuted for the project's whole life. Development @@ -68,7 +71,9 @@ commands, read `docs/active-work.md` immediately after this file. ## 1. Where the project stands (2026-08-01) -- **`main` @ `000b6cd`, released as v1.1.0.** Distribution Stage 1 #211 +- **`main` @ `f186253`.** Bottom-panel Stage 3 **#213** completes Arc 7, + atop the post-release accuracy pass #212 and `000b6cd` / **v1.1.0**. + Beneath that, Distribution Stage 1 #211 lands atop the docs absorption #210, the CI CRDT coverage lane #209, the absorption #208 and `cfc1710`. Beneath that, nine PRs landed in this order: the ledger absorption #199, the process-signal diagnostic @@ -77,7 +82,8 @@ commands, read `docs/active-work.md` immediately after this file. #204 and **1b-3** #205, the ambient-root isolation **implementation** #206, and discovery Stage 1 #207. Each has its own bullet below; this line is the head-of-`main` anchor and nothing else. -- **Bottom panel Arc 7 COMPLETE — Stage 3, the adopter default flip.** +- **Bottom panel Arc 7 COMPLETE — Stage 3 (#213), the adopter default + flip.** Omitting `display` now means the panel for listview, compile and terminal; **dired keeps `"current"`** because `pmacs.path.directory_handler` calls it with no `display` and a flipped @@ -216,7 +222,7 @@ anchor, so every item is startable. | 2 | Workspace + location | Missing; model gap | The long-lead arc. Start before a fifth subsystem grows its own root convention — four have already diverged (§7) | | 3 | Extension ownership | Missing; prerequisite-shaped | **`pmacs.hook.remove` does not exist.** That one bug-sized gap blocks §13's disable/uninstall, §10's trust classes, and package-scoped cancellation | | 4 | **Discovery** | **Stage 1 MERGED (#207)** | Stage 2 candidates, in rough dependency order: richer M-x rows (**protocol change** — `MinibufferPrompt.candidates` is `Vec`; `CompletionPopupRow` already proves the pattern), `Command` gaining title/category/aliases/flags/arg-schema (~147 definition sites), predicate evaluation, help-layer unification, and the help-prefix decision | -| 5 | Workbench convergence | Partial; **Arc 7 COMPLETE** (Stage 3 implemented) | The bottom panel is finished on both frontends and the adopter default is flipped. **The tree primitive is now the arc's successor** — `COHERENCE.md` §14 grades Tree ✗, and DAP's variables view is its next would-be inventor. Build it *before* dired's `i` and the worker tree invent two | +| 5 | Workbench convergence | Partial; **Arc 7 COMPLETE** (Stage 3 merged, #213) | The bottom panel is finished on both frontends and the adopter default is flipped. **The tree primitive is now the arc's successor** — `COHERENCE.md` §14 grades Tree ✗, and DAP's variables view is its next would-be inventor. Build it *before* dired's `i` and the worker tree invent two | | 6 | Config productization | Foundation only | Value provenance, then layering, then adoption migration (**table-valued settings are the hard prerequisite** — `ConfigValue` is four scalars) | | 7 | Package lifecycle | Not started | Correctly sequenced after P3 | | 8 | **Distribution** | **Stage 1 SHIPPED (v1.1.0, #211)** | Binaries on tag, checksums, machine-checked glibc floor. **Journey step 1 now works and the "invisible until this exists" blocker is lifted.** Next is a *decision* about channels / update / signing, not a queued plan | @@ -297,6 +303,21 @@ someone forgot. `gpu_invocation_acceptance` tests fail on a missing `pmacs-gpu` binary. `cargo build --workspace --no-default-features --features luajit,crdt` is the invocation that produces both binaries. +- **A local sweep is blind to whichever feature configuration it does + not build.** Stage 3's census and every verification sweep ran + `--features luajit` WITHOUT `crdt`, so no crdt-gated suite was + exercised and `compile_mode_crdt_acceptance` reached CI broken. Sweep + BOTH configurations before claiming a corpus is green — the crdt job + exists precisely because that blindness is easy. +- **"My change made this fragile" is a different finding from "this was + always flaky", and only one of them is yours to fix.** Stage 3 saw two + CI runs on one commit fail DIFFERENT PTY/GPU suites — the + load-sensitivity signature, on suites the flake list already names. + The tell that it was neither: the failures kept landing on GPU + *terminal* tests, and terminal placement was what the PR changed. + Those fixtures opened with no `display`, so the flip shrank the very + window whose rendered frames they assert against. **Ask which tests + and why those, before reaching for a rerun.** - **Never hand-roll the dark-test census — use `scripts/feature-census`.** libtest prints `name: test` with **no space before the colon**, so a filter written `/ : test$/` matches