From e316ba3a271837c214284884f7271d44425f716b Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Wed, 22 Jul 2026 19:54:14 -0400 Subject: [PATCH] docs: record Vterm Stage 3 landing Advance canonical state to protocol v19, close the Vterm lane and roadmap arc, preserve the cross-PR integration lesson, mark PR #91 landed, and point machine-local housekeeping at the durable policy. --- docs/active-work.md | 118 +--------------------------------------- docs/agent-handoff.md | 65 ++++++++++++++-------- docs/roadmap-2026-07.md | 24 ++++---- 3 files changed, 55 insertions(+), 152 deletions(-) diff --git a/docs/active-work.md b/docs/active-work.md index 154da9d..ef0ac15 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -14,8 +14,8 @@ backlog. 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` @ `2625ec7` (tab-width parity #137 merged atop - locals-query #134 and modeline detection #132; protocol v18 on `main`). + `githubsucks/main` @ `cac4961` (Vterm Stage 3 #135 merged after tab-width + parity #137; protocol v19). - On the transfer source, `origin/main` named a release mirror at `d3fa632` and lagged badly. On the current destination, `origin` names the canonical URL. This difference is why all recovery begins by @@ -49,121 +49,9 @@ git worktree list git status --short --branch ``` -The first command must expose `2625ec7` or a newer intentional main. +The first command must expose `cac4961` or a newer intentional main. If it does not, stop and repair the remote/fetch configuration. -## Vterm Stage 3 implementation lane - -- Portable branch: `githubsucks/vterm-gpu` -- Framing carried as the first commit; implementation follows it. -- Base: cut from canonical `main` @ `1dd47fc`, NOT stacked on - `vterm-stage3-framing`, per the framing's §8. Canonical `main` @ - `2625ec7` (tab-width parity #137, locals-query #134, modeline handoff - #133/#136) is MERGED IN — see the integration entry below. -- PR: #135, , open against - canonical `main`. Never merge without explicit authorization. -- State: criteria 28-37 implemented. Protocol v19 (`SUPPORTED=[6..=19]`): - `InstanceMessage::TerminalFrame` (discriminant 26, daemon-gated), - `FrontendEvent::TerminalResize` (11) and `TerminalPointer` (12) - (frontend-gated). `pmacs-protocol/src/terminal.rs` owns the shared - bounds and `TerminalFrame::validate`; `pmacs-gpu/src/terminal.rs` is the - pure cell-space paint planner; `pmacs-gpu --headless-probe` drives the - real attach client without winit for criterion 37. -- Verification (clean tree, this machine): - - `cargo fmt --check`; - - `cargo clippy --workspace --all-targets -- -D warnings`; - - `cargo test --lib`: 1,757 passed (3 ignored); - - `cargo test --lib --features crdt`: 1,933 passed (3 ignored); - - vterm Stage 1 acceptance: 9 default / 10 CRDT; - - vterm Stage 2 acceptance: 4 default / 4 CRDT; - - vterm Stage 3 acceptance: 4 default / 5 CRDT (the CRDT-only case is - the real-daemon + real-PTY + headless-GPU path); - - statusline acceptance: 7 default / 8 CRDT; - - `cargo test --test m4_acceptance -- --skip basedpyright`: 120 passed - (3 ignored, 1 filtered); - - `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`: 127 passed; - - `cargo test --workspace -- --skip basedpyright`: 2,919 passed across - 83 suites (19 ignored), one invocation; - - `git diff --check`. -- Review round 1 addressed (framing §0.10): hover no longer claims durable - terminal control (real defect, bite-verified); terminal motion dedupes by - cell; declarations record only once sent; unchanged frames skip - revalidation; the terminal-mode presence-sweep skip is removed. The - review's predicted presence FREEZE did not reproduce — the buffer-follow - clears the declaration before `render_frame`, so a truthful sweep always - precedes terminal mode; that test is a labelled regression guard, not - fix evidence. -- Review round 2 addressed (framing §0.11): a daemon disconnect now leaves - terminal mode so the notice is visible (real defect, hand-verified - because fix and test share a file); the per-tick full-grid clone is - gone; inbound terminal events require a negotiated v19 session; a - grid-missing press no longer arms a drag; roadmap/handoff Arc 5 lines - corrected. Named deferral: terminal wheel gestures discard scroll - magnitude. -- Post-round-2 gates (pre-integration): 1,758 default + 1,934 CRDT library - tests; required GPU 129; workspace sweep 2,923 across 83 suites; Stage 3 - acceptance 5 default / 7 CRDT; M4 120; fmt, clippy, diff check clean. -- **Post-integration gates (canonical `main` @ `2625ec7` merged in):** - `cargo fmt --check`; strict workspace Clippy; `pmacs-protocol` 17; - `cargo test --lib` 1,768; `--features crdt` 1,944 (3 ignored each); - vterm Stage 1 9/10, Stage 2 4/4, Stage 3 5/7, statusline 7/8, tab-width - 2/2 (default/CRDT); M4 121 passed (3 ignored, 1 filtered); required GPU - 139; workspace sweep 2,946 passed across 84 suites (19 ignored), one - invocation; `git diff --check` clean. -- Closed caveat: the once-seen required-GPU failure did not reproduce in - eight author runs plus five reviewer runs. Treated as environmental. -- Canonical-main integration after #137 landed: the agreed order was - #137 first (it was approved and FROZEN at `5b23e11`, so it could not - absorb a rebase without breaking its freeze), then this lane second. - Integrated by MERGING canonical main into the branch, matching repo - precedent (`Merge canonical main into vterm-tui`, `… into modeline - detection`) rather than a rebase, which would have force-pushed away - the review anchors on #135. Main had also moved past this lane's base - by #133/#134/#136, so the integration surface was wider than the - #135/#137 overlap: `src/semantic_render.rs` was a fourth overlapping - code file and auto-merged, as did `pmacs-protocol/src/lib.rs`. The one - code conflict was the `pmacs_protocol` import list in - `pmacs-gpu/src/main.rs` (`TAB_STOP_COLUMNS` against the terminal - types) — resolved as a union. -- Next: further user review rounds on the PR. - -Recovery worktree: - -```sh -git worktree add --track \ - -b vterm-gpu \ - ../pmacs-vterm-gpu \ - githubsucks/vterm-gpu -``` - - -## Cross-PR coordination: #135 and #137 (resolved) - -**Resolved 2026-07-22: #137 merged first, #135 integrated second.** Kept -as the worked example, because the deciding argument is reusable. - -#137 was APPROVED and FROZEN at `5b23e11`. "Frozen" and "rebase onto the -resulting main" are mutually exclusive, so the frozen PR had to land -first — the alternative would have broken its freeze and voided its -approval. Three arguments pointed the same way: the approved PR should -not wait on an unapproved one; the PR carrying the protocol byte pins -should be the one that integrates, because its own suite is what detects -a disturbed discriminant; and the larger, more invasive change should -pay the integration cost, since its author has the context to verify the -merged result. - -The named overlap (`pmacs-gpu/src/main.rs`, `pmacs-protocol/src/lib.rs`, -`Cargo.lock`, both ledger docs) was accurate but incomplete — main had -also moved by #133/#134/#136, making `src/semantic_render.rs` a fourth -overlapping code file. **Lesson: derive the integration surface from -`git diff ..main`, not from the other PR's file list.** - -The feared semantic collision did not occur. Terminal cell geometry -still uses the monospace advance and is not routed through -`TAB_STOP_COLUMNS`: terminal columns come from the child, and tab -expansion is a DOCUMENT projection concern. That is verified rather than -assumed — see the integration gates on the lane above. - ## Parked lane: kill-ring browser + persistence - Portable branch: `githubsucks/kill-ring-browser` diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index bf384ce..56a32b3 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -1,12 +1,10 @@ # Agent handoff — cross-machine continuity -**Last updated: 2026-07-22, after tab-width rendering parity (#137) and -locals-query processing (#134) landed on `main`, and canonical `main` was -merged into the Vterm Stage 3 lane. Vterm Stage 3 (protocol v19, GPU -terminal) is implemented on `vterm-gpu` and in review as PR #135; see -`docs/active-work.md`. Vterm Stage 2 (#130), modeline detection (#132), -mode system wiring (#129), config registry (#127), Vterm Stage 1 (#126), -and completed Themes Arc 4 (#120/#124/#125) are on `main`.** +**Last updated: 2026-07-22, after Vterm Stage 3 (#135, protocol v19 and +native GPU terminal) landed on `main`, following tab-width rendering parity +(#137), locals-query processing (#134), modeline detection (#132), mode system +wiring (#129), config registry (#127), Vterm Stages 1–2 (#126/#130), and +completed Themes Arc 4 (#120/#124/#125).** This file is the bridge between development machines. If you are an agent reading this on a fresh clone: this document plus the `docs/*-framing.md` @@ -20,10 +18,9 @@ commands, read `docs/active-work.md` immediately after this file. ## 1. Where the project stands (2026-07-22) -- `main` @ `2625ec7` (tab-width parity #137 atop locals-query #134), - protocol **v18** on `main`, **v19** on `vterm-gpu` - (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 = - `FontFacts`, v18 = `StatuslineSegments`). +- `main` @ `cac4961` (Vterm Stage 3 #135 atop tab-width parity #137), + protocol **v19** (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 = + `FontFacts`, v18 = `StatuslineSegments`, v19 = terminal frames/events). - **Config registry LANDED — #127** (`docs/config-registry-framing.md` rev 3; merge `2e37c04`; two review rounds). `pmacs.config` is the typed, introspectable options registry the backlog ranked first, and @@ -268,11 +265,11 @@ commands, read `docs/active-work.md` immediately after this file. is a clean behavioral bite. The parser dispatch has its independent clean behavioral bite; the original `main`/crate-root bite remains explicitly weaker compile-time API evidence. - - **Stage 3 GPU/protocol is IMPLEMENTED on `vterm-gpu`** (framing - `docs/vterm-framing.md` Revision 9, criteria 28-37; awaiting review). + - **Stage 3 GPU/protocol LANDED ON `main` — #135** (merge `cac4961`; + `docs/vterm-framing.md` Revision 9, criteria 28–37). Protocol **v19**: `InstanceMessage::TerminalFrame` (discriminant 26, daemon-gated) plus `FrontendEvent::TerminalResize` (11) and - `TerminalPointer` (12), both frontend-gated - the first bump gating in + `TerminalPointer` (12), both frontend-gated — the first bump gating in BOTH directions. `SUPPORTED=[6..=19]`. - `pmacs-protocol/src/terminal.rs` now owns the shared terminal bounds, `TerminalProcessState`, `TerminalSelectionSpan`, and the single @@ -300,6 +297,16 @@ commands, read `docs/active-work.md` immediately after this file. origin. `pmacs-gpu --headless-probe` drives the real attach client without winit (`attach::connect_with_sink`), which is how criterion 37 gets one real daemon + real PTY + real wgpu path. + - #135 integrated canonical `main` after #137 landed. The one code conflict + joined `TAB_STOP_COLUMNS` with the terminal imports in + `pmacs-gpu/src/main.rs`; terminal geometry remains fixed-cell and never + consumes the document tab-stop projection. + - Final post-integration gates: strict Clippy; 1,768 default + 1,944 CRDT + library tests; Vterm Stages 1/2/3 at 9/10, 4/4, and 5/7 default/CRDT; + statusline 7/8; tab-width 2/2; M4 121; required GPU 139; workspace 2,946 + passed across 84 suites; formatting and diff check clean. The first + macOS/LuaJIT CI run timed out waiting for `VTERM_ALT_READY` in the Stage 2 + real-TUI smoke; the complete failed-job rerun passed all 12 checks. - **Stage 2 TUI LANDED ON `main` — #130** (merge `86fc1bc`; `docs/vterm-framing.md` Revision 7, criteria 15–27). `TerminalViewKey` keys per-frontend/window projection state over one shared process/screen; logical @@ -324,8 +331,8 @@ commands, read `docs/active-work.md` immediately after this file. and pure `ui.modeline.terminal` process/scroll segment. - `tests/vterm_stage2_acceptance.rs` maps Lua transactionality, shared-view isolation, clipboard/modeline behavior, and a hermetic real `/bin/sh` TUI - PTY smoke. Stage 2 changes no wire schema or GPU renderer; protocol remains - v18 until Stage 3. + PTY smoke. Stage 2 changed no wire schema or GPU renderer; protocol + remained v18 until Stage 3. - PR #130 review round 1 (`8702791`) aligned dispatch with the approved escape-prefix contract, closed the non-terminal Lua error path, made controller replacement atomic, retained zero-area view anchors, removed @@ -388,9 +395,8 @@ commands, read `docs/active-work.md` immediately after this file. fix (#101). - **Arc 4 (themes + extensibility) COMPLETE** — named UI faces (#120), live GPU font preferences (#124), statusline providers (#125). - - **Arc 5 terminal stage ACTIVE** — compile mode (#113), Vterm terminal - core (#126), and Vterm TUI (#130) landed; protocol/GPU Stage 3 is - implemented and in review as PR #135. + - **Arc 5 terminal stage COMPLETE** — compile mode (#113), Vterm terminal + core (#126), TUI frontend (#130), and protocol/GPU Stage 3 (#135) landed. - **Config registry COMPLETE (#127)** — not a numbered arc; it was the cross-cutting substrate ranked first on `docs/side-quest-backlog.md`'s north star, and it unblocks the @@ -459,11 +465,16 @@ before trusting them: `m6_8_supervisor_reaps_all_children_across_cycles`) are timing-based; `editor::composition_overhead_under_ten_percent` is a render-ratio microbenchmark that fails ~1/3 even isolated single-threaded (already - `cfg!(macos)`-disabled). A lone failure of one of these → rerun that - test alone (`-- --test-threads=1`) before investigating. Also: 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`. + `cfg!(macos)`-disabled). Vterm Stage 3's merge CI saw one macOS timeout in + `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 + 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`. - **GPU tests** need a Vulkan device. `PMACS_REQUIRE_GPU=1` makes absence a hard failure instead of a silent skip. Headless option: lavapipe (see `docs/repository-audit-2026-07-03.md` for the CI @@ -543,6 +554,12 @@ cannot detect a discriminant shift. - **Stacked PRs**: retarget the child to main BEFORE merging the parent — GitHub auto-closes a PR whose base branch is deleted and cannot reopen it (#104 → re-opened as #105). +- **Frozen reviewed PRs do not absorb moving overlapping work.** For #135 and + #137, the approved/frozen #137 landed first; the larger #135 lane then + merged canonical `main`, retained its review anchors, and reran every gate. + Derive that integration surface from `git diff ..main`, not the other + PR's file list — concurrent landed work added an overlap the original + two-PR comparison missed. - **Scripted edits (sed/python) in files with repeated similar blocks** (`src/lsp.rs` JSON builders): anchor on a unique line or you will silently edit the wrong block. This produced a vacuously-passing test diff --git a/docs/roadmap-2026-07.md b/docs/roadmap-2026-07.md index 5e37411..19cae73 100644 --- a/docs/roadmap-2026-07.md +++ b/docs/roadmap-2026-07.md @@ -80,7 +80,7 @@ preference at protocol v17; and composable per-window `pmacs.statusline` providers transported to semantic/GPU frontends by protocol-v18 `StatuslineSegments`. -### Arc 5 — Terminal, staged — VTERM STAGE 3 IN REVIEW +### Arc 5 — Terminal, staged — COMPLETE - **Compile mode landed in #113**: line-oriented PTY/ANSI output, error-regex navigation, and `M-x compile`. @@ -92,13 +92,12 @@ protocol-v18 `StatuslineSegments`. - **Vterm Stage 2 TUI landed in #130**: terminal-window composition, input/resize, per-context scroll/selection/copy, authenticated frontend ownership, BEL/clipboard drainage, and the strict Lua surface. -- **Vterm Stage 3 protocol/GPU is implemented and in review (PR #135)**: - additive protocol v19 complete frames/events, an aggregate glyph-byte bound - under the unchanged transport cap, dual viewport bootstrap, authenticated - semantic routing, and native fixed-cell GPU terminal rendering. The 16 MiB - transport cap is preserved: the measured legal-worst frame encodes to - 13,437,863 bytes under an 8 MiB aggregate glyph bound, never chunked. - Landing it closes Arc 5's terminal stage. +- **Vterm Stage 3 protocol/GPU landed in #135**: additive protocol-v19 + complete frames/events, an aggregate glyph-byte bound under the unchanged + transport cap, dual viewport bootstrap, authenticated semantic routing, and + native fixed-cell GPU terminal rendering. The 16 MiB transport cap is + preserved: the measured legal-worst frame encodes to 13,437,863 bytes under + an 8 MiB aggregate glyph bound, never chunked. ### Arc 6 — Folding (keystone gutter rider) @@ -122,11 +121,10 @@ after daemon restart, cursor blink, font/theme config (overlaps Arc 4). ## Housekeeping (do opportunistically) -- Merge PR #91 (gutter click classification + fit guard). -- Delete or mark-superseded stale docs: `pmacs-gpu-editing-perf-handoff.md` - (freeze fixed by PR #60 arc), `session-5-stale-styling-handover.md` - (fixed, task #25 closed), `python_experiment.md`, `#run.sh#`, - `semantic-frontend-protocol.md.local-bak`. +- ~~Merge PR #91 (gutter click classification + fit guard).~~ Landed on + 2026-07-07. +- Machine-local handoff/experiment files are intentionally untracked; see + `docs/agent-handoff.md` §7. They are not repository housekeeping targets. - `V0.2-PREREQUISITES.md` cited twice by CHANGELOG but missing on disk — reconstruct or unlink. - README still leads with "What v0.1 ships with" — refresh.