neuwirth
/
pmacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: retire the bottom-panel lane — Arc 7 is done 

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) <noreply@anthropic.com>
This commit is contained in:
Levi Neuwirth 2026-08-04 19:08:39 +02:00
parent f186253e69
commit b2aa16d6ed
No known key found for this signature in database
2 changed files with 78 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
docs/active-work.md
View File

@ -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 <their base>..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 <path> -b <local> githubsucks/<branch>`
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

35
docs/agent-handoff.md
View File

@ -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<String>`; `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