From 968e01ae6a5c21d4b94ec39e17816af050603463 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Mon, 20 Jul 2026 10:51:34 -0400 Subject: [PATCH] docs: add cross-machine active-work handoff Add synchronized agent bootstraps and a volatile active-work ledger so another machine can distinguish durable project state from open branches, local checkpoints, machine-only providers, and incomplete verification. Record githubsucks/main as the canonical development line, refresh the #124/protocol-v17 handoff, correct the current keybinding reference for compile mode, and mark the July roadmap as a historical snapshot. --- AGENTS.md | 33 ++++ CLAUDE.md | 31 +-- docs/active-work.md | 169 +++++++++++++++++ docs/agent-handoff.md | 69 +++++-- docs/keybindings.md | 379 +++++++++++++++++++++++++++++++++++++ docs/roadmap-2026-07.md | 4 + docs/side-quest-backlog.md | 16 +- 7 files changed, 665 insertions(+), 36 deletions(-) create mode 100644 AGENTS.md create mode 100644 docs/active-work.md create mode 100644 docs/keybindings.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1252d2e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,33 @@ +# pmacs agent instructions + +**Start here: read `docs/agent-handoff.md`, then +`docs/active-work.md`, before taking on any work.** The handoff carries +durable project state, working method, substrate invariants, and the +standing backlog. The active-work ledger carries volatile branches, +checkpoints, verification, and exact cross-machine recovery commands. +Keep both updated according to their own update protocols. + +Always true, independent of the handoff: + +- Rust core + Lua runtime (`builtin/runtime/*.lua`), TUI + GPU + (`pmacs-gpu`) frontends over a versioned semantic protocol + (`pmacs-protocol`). `#![forbid(unsafe_code)]`. +- Workflow: framing doc in `docs/` -> user approval -> branch -> implement + -> full gate suite -> PR -> user review rounds -> user says when to + merge. Never merge unprompted. One feature, one branch, one PR. +- Gates before any PR: `cargo fmt --check`; `cargo clippy --workspace + --all-targets -- -D warnings` (as its own step); `cargo test --lib`; + `cargo test --lib --features crdt`; the touched acceptance suites; + `cargo test --test m4_acceptance -- --skip basedpyright`; + `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`; `git diff --check`. +- The checkout may be shared with the user: check `git status` for + foreign uncommitted work before stash, checkout, or branch operations, + and never delete untracked files you did not create. +- `githubsucks/main` is the canonical development line. `origin/main` + is a release mirror and may lag substantially; never base new work on + it without comparing both refs. +- Work is portable only after it is committed and pushed. Uncommitted + worktree changes, untracked files, and `/tmp` dependencies do not + travel to another machine. +- Write commit messages with `git commit -F `. Never use + `git add .`. diff --git a/CLAUDE.md b/CLAUDE.md index 1ede25a..1252d2e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,18 +1,19 @@ -# pmacs — agent instructions +# pmacs agent instructions -**Start here: read `docs/agent-handoff.md` before taking on any work.** -It carries current project state, the working method, substrate -invariants, and the standing backlog — it is the continuity bridge -between development machines. Keep it updated as part of your work -(update protocol is in the file itself). +**Start here: read `docs/agent-handoff.md`, then +`docs/active-work.md`, before taking on any work.** The handoff carries +durable project state, working method, substrate invariants, and the +standing backlog. The active-work ledger carries volatile branches, +checkpoints, verification, and exact cross-machine recovery commands. +Keep both updated according to their own update protocols. Always true, independent of the handoff: - Rust core + Lua runtime (`builtin/runtime/*.lua`), TUI + GPU (`pmacs-gpu`) frontends over a versioned semantic protocol (`pmacs-protocol`). `#![forbid(unsafe_code)]`. -- Workflow: framing doc in `docs/` → user approval → branch → implement - → full gate suite → PR → user's review rounds → user says when to +- Workflow: framing doc in `docs/` -> user approval -> branch -> implement + -> full gate suite -> PR -> user review rounds -> user says when to merge. Never merge unprompted. One feature, one branch, one PR. - Gates before any PR: `cargo fmt --check`; `cargo clippy --workspace --all-targets -- -D warnings` (as its own step); `cargo test --lib`; @@ -20,7 +21,13 @@ Always true, independent of the handoff: `cargo test --test m4_acceptance -- --skip basedpyright`; `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`; `git diff --check`. - The checkout may be shared with the user: check `git status` for - foreign uncommitted work before stash/checkout/branch operations, and - never delete untracked files you didn't create. -- Commit messages via `git commit -F `, ending with the Claude - co-author line; PR bodies end with the Claude Code attribution. + foreign uncommitted work before stash, checkout, or branch operations, + and never delete untracked files you did not create. +- `githubsucks/main` is the canonical development line. `origin/main` + is a release mirror and may lag substantially; never base new work on + it without comparing both refs. +- Work is portable only after it is committed and pushed. Uncommitted + worktree changes, untracked files, and `/tmp` dependencies do not + travel to another machine. +- Write commit messages with `git commit -F `. Never use + `git add .`. diff --git a/docs/active-work.md b/docs/active-work.md new file mode 100644 index 0000000..67826a3 --- /dev/null +++ b/docs/active-work.md @@ -0,0 +1,169 @@ +# Active work — cross-machine resume ledger + +**Snapshot: 2026-07-20.** This file records volatile work that has not +landed on `main`. Read it after `docs/agent-handoff.md`. Remove completed +entries when their PR merges; do not let this become a second permanent +backlog. + +## Repository authority + +- Canonical development remote: `githubsucks` + (`https://github.com/levineuwirth/pmacs.git`). +- Canonical base at this snapshot: + `githubsucks/main` @ `f8096ff` (#124 merged, protocol v17). +- `origin/main` @ `d3fa632` is the release mirror and was 400 commits + behind `githubsucks/main` at the snapshot. Do not base new work on it. +- The shared desktop checkout contained unrelated uncommitted work. The + branches below were prepared in isolated worktrees; never clean or + overwrite the shared checkout to recover them. + +Start on another machine with: + +```sh +git fetch githubsucks --prune +git log -1 --oneline githubsucks/main +git worktree list +git status --short --branch +``` + +The first command must expose `f8096ff` or a newer intentional main. +If it does not, stop and repair the remote/fetch configuration. + +## Active lane: PR #123 — JSON + YAML + +- PR: +- Public PR branch: `githubsucks/json-yaml-grammar` +- Public PR head before the transfer checkpoint: `4be2a65` +- Original merge base: `56eb67e`; current main is nine commits ahead. +- Portable checkpoint branch: + `githubsucks/json-yaml-handoff-2026-07-20` +- The checkpoint is a continuation branch for recovery, not a second + feature and not a merge target. Finish there, then push its completed + head to `githubsucks/json-yaml-grammar`. + +The checkpoint carries the unpushed review-fix set that previously lived +only in `../pmacs-jsonyaml`: + +- push configured settings via + `workspace/didChangeConfiguration` immediately after `initialized`; +- fake-LSP configuration sink and a deterministic delivery test; +- explicit `json.validate.enable = true`; +- JSON provider pin + `@t1ckbase/vscode-langservers-extracted@2.0.2`; +- corrected YAML configuration sections: + `yaml`, `http`, `[yaml]`, `editor`, `files`; +- corrected telemetry, schema-network, and schema-association claims; +- PATH-gated real JSON provider integration test. + +Verification already completed before transfer: + +- JSON provider standalone protocol smoke passed. +- JSON provider through pmacs passed + `m4_real_json_provider_receives_config_and_reports_diagnostics`. +- `m4_json_yaml_lsp_configs_pin_command_and_sections` passed. +- `m4_5_initial_config_pushed_via_did_change_configuration` passed. +- `cargo fmt --check` and `git diff --check` passed. +- `yaml-language-server@1.24.0` standalone protocol smoke passed: + initialization reported version 1.24.0; the initial + `workspace/configuration` request was exactly + `yaml`, `http`, `[yaml]`, `editor`, `files`; opening the document + caused a second scoped `[yaml]` request; invalid YAML produced a real + parser diagnostic; shutdown exited 0 with empty stderr. + +Still required on the destination machine: + +1. Add the PATH-gated real-YAML pmacs acceptance test, mirroring the + JSON test. Disable SchemaStore and Kubernetes CRD catalog access in + the test for deterministic, network-free operation. +2. Run it against the exact Red Hat provider and require: + auto-attach, initialized state, a non-empty diagnostic, and no crash. +3. Update `docs/json-yaml-framing.md` if the live pmacs path reveals any + difference from the standalone evidence. +4. Rebase the checkpoint onto current `githubsucks/main`. +5. Run the full repository gate suite from `AGENTS.md`. +6. Push the completed head to `githubsucks/json-yaml-grammar`; confirm + new PR checks belong to that head. Never merge without the user's + instruction. + +Provider setup is intentionally machine-local: + +```sh +npm install --prefix /tmp/pmacs-jsonls \ + @t1ckbase/vscode-langservers-extracted@2.0.2 +npm install --prefix /tmp/pmacs-yamlls \ + yaml-language-server@1.24.0 +``` + +The Node language servers had to run outside the prior machine's +restrictive execution sandbox. The `/tmp` prefixes and smoke harnesses +do not travel. + +Recovery worktree: + +```sh +git worktree add --track \ + -b json-yaml-handoff-2026-07-20 \ + ../pmacs-jsonyaml-home \ + githubsucks/json-yaml-handoff-2026-07-20 +``` + +## Active lane: Arc 4 stage 3 — statusline segments + +- Portable branch: `githubsucks/statusline-segments` +- State: framing only, revision 1, based on `f8096ff` / protocol v17. +- Status: awaiting user review. No implementation and no PR. +- Scope: composable per-window Lua modeline providers, dynamic + modeline-face inventory, and protocol v18 + `StatuslineSegments`; the built-in LSP segment is the first consumer. +- Do not implement until the user approves the framing. When approved, + continue on this branch so the framing remains the first commit. + +Recovery worktree: + +```sh +git worktree add --track \ + -b statusline-segments \ + ../pmacs-statusline \ + githubsucks/statusline-segments +``` + +## Parked lane: kill-ring browser + persistence + +- Portable branch: `githubsucks/kill-ring-browser` +- State: framing only, revision 2; no implementation and no PR. +- Status: explicitly parked by the user on 2026-07-20. +- Its original scout was based on `0efb5cd`. The preserved framing marks + this ground truth stale and requires a complete re-scout against the + then-current `githubsucks/main` before implementation. +- Compile-mode has merged since the original scout, so old + “compile-mode in flight” keybinding/touch-set assumptions are not + authoritative. + +Recovery worktree, only when the user un-parks it: + +```sh +git worktree add --track \ + -b kill-ring-browser \ + ../pmacs-kill-ring-browser \ + githubsucks/kill-ring-browser +``` + +## Documentation lane + +- Portable branch: `githubsucks/handoff-2026-07-20` +- Carries synchronized `AGENTS.md` / `CLAUDE.md`, this ledger, the + durable handoff refresh, and the keybinding reference correction. +- It changes no runtime code. +- Review and merge this documentation branch separately; it must not be + folded into PR #123 or either feature framing branch. + +## Update protocol + +Whenever a listed lane changes materially: + +1. update its public branch and head/state here; +2. record new verification and remove superseded caveats; +3. keep durable architecture in `docs/agent-handoff.md`, not here; +4. remove the lane after merge or abandonment; +5. verify every recovery command from a clean worktree before calling + the transfer complete. diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index d9986c7..36c7412 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -1,7 +1,8 @@ # Agent handoff — cross-machine continuity -**Last updated: 2026-07-15, after multi-language injections (#122) -merged; also carries the #120 themes-stage-1 snapshot.** This file is the +**Last updated: 2026-07-20, after the cross-machine continuity audit; +main still reflects GPU font preferences (#124), themes stage 1 (#120), +and injections (#122).** 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` files ARE your memory. Read this fully before taking on work, seed @@ -9,11 +10,14 @@ your persistent memory from it, and **update this file (and commit it) whenever project state changes materially** — the next machine reads it the way you just did. -## 1. Where the project stands (2026-07-15) +For volatile branches, checkpoints, verification, and recovery +commands, read `docs/active-work.md` immediately after this file. -- `main` @ `5e73966` (multi-language injections #122 merged; #120 - themes stage 1 below it), protocol **v16** (`SUPPORTED=[6..16]`; - v15→16 shipped the `ThemeFacts` channel — injections added no wire). +## 1. Where the project stands (2026-07-20) + +- `main` @ `f8096ff` (GPU font preferences #124 merged), protocol + **v17** (`SUPPORTED=[6..17]`; v15→16 shipped `ThemeFacts`, v16→17 + shipped `FontFacts`). - **Syntax-highlight / language-detection side-quest (#114–#118) LANDED** — a one-shot arc built in sibling worktrees off main while the user's themes lane (`theme-faces`) ran concurrently in the shared @@ -114,12 +118,38 @@ reads it the way you just did. survive both sides) and the **store-sourced diag-count freeze** (per-URI severity totals in `DiagnosticStore`, O(1), survive `mark_stale`). -- **NEXT: themes stage 2 — `pmacs.gpu.set_font` at protocol v17** - (shipped versions are never reused; the `pmacs-gpu-design.md:299` - no-wire-change claim is superseded and must be corrected in the - stage-2 framing). Glyphon font reload was flagged HARD. Stage 3 - after: Lua statusline-segment API (segments carry face names). - Workflow as always: framing → user approval → branch → gates → PR. +- **Themes (Arc 4) stage 2 LANDED — #124 merged after the complete + behavioral review** (`docs/gpu-set-font-framing.md` rev 5): + `pmacs.gpu.set_font { family?, size? }` is a live global preference; + authoritative bufferless `FontFacts` is gated at protocol v17. + GPU family resolution is frontend-local and fail-closed to a + sanitized monospace default across normal/bold/italic queries; + metrics for all seven glyphon buffers derive atomically from one + logical-pixel size. The visual-run caret substrate normalizes + source bytes through adornments and shaped clusters (including + combining sequences/ligatures), preserves deliberately scrolled-away + viewports, and reflows on font, gutter, minimap, text, CRDT, resize, + and snapshot geometry changes. Test fixtures enter fontdb before + `FontSystem` construction; alternate advances are measured across + complete shaped runs, not sampled glyphs. +- **NEXT: themes stage 3 — Lua statusline-segment API.** + Revision 1 is preserved on branch `statusline-segments` and awaits + review. It scopes additive per-window modeline providers, face-name + segments, dynamic `ThemeFacts` inventory, and a new v18 + `StatuslineSegments` channel; the existing LSP status tracker is the + first built-in provider. Approval → implementation → gates → PR. + Completing stage 3 completes Arc 4. +- **OPEN: JSON + YAML PR #123.** The public PR branch still points to + the original two-commit implementation (`4be2a65`). Review fixes and + live-provider evidence are preserved on checkpoint branch + `json-yaml-handoff-2026-07-20`; the real YAML-through-pmacs smoke, + rebase, and full gates remain. Do not mistake the PR's old green CI + for validation of the checkpoint. Exact recovery is in + `docs/active-work.md`. +- **PARKED: kill-ring browser + persistence.** Revision 2 framing is + preserved on branch `kill-ring-browser`, but its `0efb5cd` scout is + stale and must be repeated before implementation. No PR or + implementation is active. - Roadmap: `docs/roadmap-2026-07.md` (ranked arcs). Position: - **Arc 1 (LSP utility surface) COMPLETE** — completion popup (#92/#93), panels/references/outline/hover (#94–#96), plus @@ -238,8 +268,9 @@ buffer owns a path's recovery slot; only recover/discard release unclaimed crash data; adopt clears the old owner's skip cache. **Protocol** — encoding-breaking bumps are deliberate and versioned -(`SUPPORTED=[6..15]`). v15 = `CompletionPopup` + `StatusFacts.message`. -New wire surface ⇒ bump + both-frontends support + acceptance. +(`SUPPORTED=[6..17]`). v15 = `CompletionPopup` + +`StatusFacts.message`; v16 = `ThemeFacts`; v17 = `FontFacts`. New wire +surface ⇒ bump + both-frontends support + acceptance. **Fake LSP** (`src/bin/pmacs_fake_lsp.rs`) modes: `fullonly`, `rangeonly`, `rangeonly16` (UTF-16 + fail-closed bounds validation), @@ -323,7 +354,9 @@ runtime/Lua-registered languages (v1 resolves only against `BUILTIN_LANGUAGES`), and the next injection *consumers* gated on new grammars — HTML/CSS/GraphQL/SQL (`