From 30e22090ae457ff6892ed8c3251cb36d4ab9b6ee Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Tue, 11 Aug 2026 21:10:32 +0200 Subject: [PATCH] docs: Stage 0 --- six review findings, including the ledger it exists to fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1, and the worst of them: the AUTHORITY BLOCK was stale in four ways while this lane's whole purpose was retiring stale ledger state. The canonical base said `122b8e8` (actual: `e67ad07`), protocol said `v6..=v22` (actual: v23, #228), the recovery threshold accepted `9a26ac8` --- far older than the base above it, so the check it defines would pass on a tree missing everything since --- and this lane's own entry named base `0e4c58d` and declared itself PARKED beneath a heading saying ready-for-PR. A ledger that contradicts itself defeats its own cross-machine purpose. All four corrected; the park bullet is replaced by what actually happened. "Exactly two journey deficits" was stronger than the evidence permits, and the table said so three paragraphs below itself: GPU 3(c) and 9 are INFERRED, so a third failure cannot be ruled out. Now "known failures at two steps; exact set pending verification". GPU 6(c) is inferred too and is noted as unable to change step 6, which 6(e) already floors. The product subgrade had criteria but no GRADING RULE --- three closure conditions distinguish closed from not-closed, which does not derive `Weak` rather than `Partial` or `Missing`. A rule is now stated, and the distinction it turns on is worth having: `Partial` would mean the GPU is merely unfinished; `Weak` means it is BEHIND a frontend shipping in the same binary. Criterion 3 is marked NOT ASSESSED --- §3.2's register is seeded empty --- rather than being quietly counted as a pass. The framing REQUIRED a handoff §6 cross-reference and there was none; only the Lean 4 numbering note existed. Added, carrying the facts a cross-machine reader needs first: the product subgrade, the P2 start gate, and that "Arc 8" means Lean 4. Three more scorecard-versus-ground-truth drifts, the same class this lane exists to close: row 14 said listview has 4 call sites "all LSP panels" (it has 5 in `lsp.lua` and 4 in `git.lua` since #227, so it is no longer LSP-only); row 15 said "no git integration at all" while §15 records status and diff; and §9's plane table said no builtin opens `*lsp*`, though `M-x lsp.status` does (`lsp.lua:3533`) --- it has no BINDING, which is the distinction this document now draws everywhere else. Finally, §20 physically placed the arc after Priority 5 while its prose said after Priority 1. In a *Recommended Priority Order* position is the schedule, so the block moves to sit directly after P1, and now states its interleaving with P2-P5 explicitly rather than leaving it to position alone. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai --- COHERENCE.md | 115 ++++++++++++++++++++++++++++-------------- docs/active-work.md | 35 +++++++------ docs/agent-handoff.md | 14 +++++ 3 files changed, 108 insertions(+), 56 deletions(-) diff --git a/COHERENCE.md b/COHERENCE.md index d7db767..6b1f344 100644 --- a/COHERENCE.md +++ b/COHERENCE.md @@ -107,8 +107,8 @@ remain open to them. | 11 | Config layering + provenance | **Partial (foundation only)** | Typed registry is right; 5 settings live in it; no value provenance | | 12 | Profiles | **Missing** | One hardcoded default keymap; not a named concept | | 13 | Package lifecycle UX | **Resolution without lifecycle** | Mature resolver/lockfile; init-only install; no uninstall/disable/search | -| 14 | Workbench primitives | **Partial (best trajectory)** | Listview is a real primitive but only **4** call sites, all LSP panels (`*lsp*` added post-audit by #204); buffer-list and search re-implement it; **the bottom panel is COMPLETE — both frontends, and Stage 3 flipped the adopter default so omission means the panel**. **Tree is implemented (◐) with the LSP outline as its one adopter; the remaining consumers, including dired's `i`, have not adopted** | -| 15 | Contextual affordances | **Weak** | Right-click menu only; code actions apply first-blindly; no git integration at all | +| 14 | Workbench primitives | **Partial (best trajectory)** | Listview is a real primitive with call sites in **two** modules — `lsp.lua` (5) and **`git.lua` (4, `*git-status*`, #227)** — so it is **no longer LSP-only**; buffer-list and search re-implement it; **the bottom panel is COMPLETE — both frontends, and Stage 3 flipped the adopter default so omission means the panel**. **Tree is implemented (◐) with the LSP outline as its one adopter; the remaining consumers, including dired's `i`, have not adopted** | +| 15 | Contextual affordances | **Weak** | Right-click menu only; code actions apply first-blindly; **Git integration reaches status and diff (#227, Stage 1) and no further** — §15's ground truth is authoritative, and this row previously said "no git integration at all" | | 16 | Semantic frontend | **Architectural: Strong · Product: Weak** | v6..=v23 schema support; production attach remains v20 during the dark panel slice; degradation practiced. **The two subgrades and the product criteria live in §16** — the row points there rather than carrying a grade of its own, so the GUI-as-a-product half cannot hide inside an architectural `Strong` | | 17 | Distribution | **Partial** | **v1.1.0 ships prebuilt Linux/macOS binaries on tag** (#211) with checksums and a stated glibc floor. No channels, in-place update, rollback, signing, or package-manager distribution | | 18 | Onboarding | **Partial** | Journey Stage 1b-3: an unconfigured launch greets in `*scratch*` naming `M-x` and four real bindings, and `M-x help` renders a cheat sheet. Still no tutorial and `C-h` still deletes a word — deliberately, see §18 | @@ -474,9 +474,15 @@ specifically **a binding that opens it**. | 11 | Understand background work | **Missing** | **Missing** | **Missing** | 11(c) — **no binding opens `editor.list-workers`**, so a keybinding listing cannot lead anyone to it: the subclaim is **absent**, not degraded, and it floors the cell. *The view is not binding-free — `C-c C-k` runs `workers.cancel-at-point` buffer-locally inside it (`docs/keybindings.md:282`) — but a binding that only works once you are already there cannot satisfy a discoverability subclaim.* 11(b) fails too — #232 gives **purpose**, never an accountable **owner**, and the planes stay disjoint (jobs in `*workers*`, processes in `pmacs.process.list`, servers in `*lsp*`, terminals **nowhere**). 11(a) passes on the activity indicator | | 12 | Close + restore | **Partial** | **Missing** | **Missing** | 12(c) — local restores nothing beyond per-file state (desktop-save is opt-in); on **both daemon-backed frontends it is a structural no-op** (Q#DS9), so they fail it **by construction** | -**Closure condition 2 currently FAILS, at exactly two steps.** GPU is -below local TUI at **step 5** (Partial vs Works) and **step 12** -(Missing vs Partial). Every other cell is equal. That is the whole of +**Closure condition 2 currently FAILS, with KNOWN failures at two +steps and the exact set pending verification.** GPU is below local TUI +at **step 5** (Partial vs Works) and **step 12** (Missing vs Partial), +and every *graded* cell elsewhere is equal — but GPU 3(c) and 9 rest on +inference (below), so a third failure cannot be ruled out until they are +verified. "Exactly two" would be a stronger claim than this table's own +evidence supports, and an earlier draft made it. GPU 6(c) is inferred +too, but cannot change step 6, which is already floored at `Missing` by +6(e) on all three frontends. That is the whole of the GPU's journey deficit as this table measures it — a narrower result than "the GUI feels behind", and a falsifiable one. It survived a review round that corrected six of the twelve rows, which is some evidence it @@ -1204,7 +1210,7 @@ editor.list-workers`, auto-refreshing, `C-c C-k` cancel-at-point). |---|---|---| | Async jobs | `*workers*` | processes, servers, terminals | | OS processes | `pmacs.process.list` (no buffer view exists) | **filters to `LineOriented` only — terminal PTYs are invisible**; `spawn_terminal` bypasses the public path entirely | -| LSP servers | `*lsp*` status text | **no builtin command opens it**; LSP sets `RestartPolicy::Never` on the supervisor and runs its own restart logic | +| LSP servers | `*lsp*` status text | opened by **`M-x lsp.status`** (`builtin/runtime/lsp.lua:3533`), but by no binding; LSP sets `RestartPolicy::Never` on the supervisor and runs its own restart logic | | Terminals | private id set drained after the supervisor tick | user-visible in none of the above | A terminal PTY appears in **no** user-visible activity view. An LSP @@ -1727,14 +1733,36 @@ not choose sat inside the healthiest concern in this document. **Product subgrade criteria** (each falsifiable, none aspirational): 1. **GPU ≥ local TUI at every journey step** under §2b. **Currently - FAILS at two steps** — 5 (no IME) and 12 (restore is a structural - no-op). + FAILS at two known steps** — 5 (no IME) and 12 (restore is a + structural no-op) — with the exact set pending verification of §2b's + inferred cells. 2. **The daily-driver blocker list is empty.** **Currently nine open** (`docs/gui-arc-framing.md` §3.1): Escape quits, IME absent, `translate_key` holes, sub-line/horizontal scroll, no DPI, folding dead on the GPU, no session restore, no reconnect, the one-window ceiling. 3. **Every surviving divergence is declared**, not accidental. + **Not yet assessed** — §3.2's register is seeded empty, so this + criterion has no finding either way and cannot lift or lower the + grade. + +**How the grade is derived, so it is a grading rule and not an +adjective.** The three criteria above are *closure* conditions; on their +own they distinguish only "closed" from "not closed", which is not a +grade. The product subgrade reads: + +| grade | condition | +|---|---| +| **Strong** | all three criteria pass | +| **Partial** | criterion 1 passes — the GPU is nowhere *behind* the TUI — while blockers remain open | +| **Weak** | criterion 1 fails at one or more steps **and** the blocker list is non-empty | +| **Missing** | no usable graphical frontend | + +**Current: Weak** — criterion 1 fails at two known steps, and nine +blockers are open including the one-window ceiling. The distinction that +matters is between `Weak` and `Partial`: the GPU is not merely +*unfinished*, it is **behind a frontend that ships in the same binary**, +and that is what the ceiling and the two failing steps say. **What moves it.** The GUI arc, and nothing else — it exists to satisfy exactly these three. The product subgrade is what the arc closes @@ -1953,6 +1981,47 @@ documented no-op under a daemon. Journey Stage 1 closing is what moves this priority's own work to done — what is left is other priorities' work showing up in the journey. +### The GUI arc — placement (Q#GA5) + +**Half A slots after Priority 1**, whose own work is complete (§20 P1), +which is why this block sits here rather than lower down — in a +*Recommended Priority Order*, position IS the schedule, and an earlier +draft placed it after Priority 5 while the prose said P1. + +**How it interleaves with P2–P5.** Half A is independent of them and +runs alongside: it adds no workspace object, no extension-ownership +model, no discovery surface. The interaction is at **P2 only**, through +the gate below. P3, P4 and P5 neither block it nor are blocked by it, +and P5's workbench-primitive adoption is *helped* by it — Stage 9's +sidebar is a tree-primitive consumer. + +It is the product half of §16, and it is what the §16 product subgrade +is graded against. + +**Reaching Stage 4b is a P2 START GATE.** Stages 4b (session save and +restore) and 9 (project/files sidebar) are **workspace-owned**: a +session and a sidebar root are both P2's objects, and inventing local +conventions for them is precisely the "fifth independent root +convention" §7 warns against. So when the arc reaches Stage 4b, **P2 +starts**, and **no later GUI stage begins** until P2 has an approved +framing and an opened lane. Non-gated GUI work may interleave freely +after that while the object lands. + +**The gate is on STARTING P2, not on finishing it** — so the arc is +never blocked on work nobody has begun, and it cannot outrun the model +it depends on. Without the gate, every non-gated stage could finish +first and leave P2 as a terminal closure blocker. + +**Arc naming (Q#GA4).** This arc is **"the GUI arc"**, deliberately a +name and not a number. The roadmap's **"Arc 8 — GPU structural parity" +label is RETIRED** here; its scope is this arc's Half B. **"Arc 8" now +unambiguously means the Lean 4 arc** (`docs/agent-handoff.md` §1a, +stages 1–4b landed), which is the numbering that stays. Landed framing +documents that say "Arc 8 adjacent" of viewport facts or splits +(`editing-conveniences-framing.md`, `bottom-panel-framing.md`) keep +their historical text — they are dated records, and this is the +authoritative disambiguation for anything written from here on. + ### Priority 2: Make workspace and location explicit Otherwise project, LSP, remote, task, and persistence accumulate @@ -1999,36 +2068,6 @@ constraint source, and DAP's variables view is why the primitive was worth building first. Also remaining: table / inspector / diff, and help unification. -### The GUI arc — placement (Q#GA5) - -**Half A slots after Priority 1**, whose own work is complete (§20 P1). -It is the product half of §16, and it is what the §16 product subgrade -is graded against. - -**Reaching Stage 4b is a P2 START GATE.** Stages 4b (session save and -restore) and 9 (project/files sidebar) are **workspace-owned**: a -session and a sidebar root are both P2's objects, and inventing local -conventions for them is precisely the "fifth independent root -convention" §7 warns against. So when the arc reaches Stage 4b, **P2 -starts**, and **no later GUI stage begins** until P2 has an approved -framing and an opened lane. Non-gated GUI work may interleave freely -after that while the object lands. - -**The gate is on STARTING P2, not on finishing it** — so the arc is -never blocked on work nobody has begun, and it cannot outrun the model -it depends on. Without the gate, every non-gated stage could finish -first and leave P2 as a terminal closure blocker. - -**Arc naming (Q#GA4).** This arc is **"the GUI arc"**, deliberately a -name and not a number. The roadmap's **"Arc 8 — GPU structural parity" -label is RETIRED** here; its scope is this arc's Half B. **"Arc 8" now -unambiguously means the Lean 4 arc** (`docs/agent-handoff.md` §1a, -stages 1–4b landed), which is the numbering that stays. Landed framing -documents that say "Arc 8 adjacent" of viewport facts or splits -(`editing-conveniences-framing.md`, `bottom-panel-framing.md`) keep -their historical text — they are dated records, and this is the -authoritative disambiguation for anything written from here on. - ### Priority 6: Productize configuration **State: foundation only (§11). Model-lite:** value provenance in the diff --git a/docs/active-work.md b/docs/active-work.md index 220b72d..b04f365 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -136,7 +136,8 @@ 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` @ `122b8e8`** — +- Canonical base at this snapshot: **`githubsucks/main` @ `e67ad07`** — + the file-watcher arc absorption, atop `122b8e8` the file-watcher D3 **#235** (closes issue #233), atop `b867f64` git integration Stage 1 **#227**, atop `ae84d58` the LSP file-watcher fix **#234**, atop `0e4c58d` destination capture **#231**, `3cc1b85` @@ -160,9 +161,10 @@ lesson, §1 for the two framings). #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..=v22`; the production server-first + **Protocol schema support is `v6..=v23`; the production server-first `Hello` still advertises v20** — two different facts, and #184 landed - only the first. The upper bound moved to **v22 at #221**, which added + only the first. The upper bound moved to **v23 at #228** + (`MinibufferPromptRows`), after **v22 at #221**, which added `InstanceMessage::LineWrapFacts`; `ADVERTISED_PROTOCOL_VERSION` did not move and must not be edited to chase it. Verified against `pmacs-protocol/src/message.rs`, not carried forward: this line said @@ -211,7 +213,7 @@ git worktree list git status --short --branch ``` -The `git log` command must expose `9a26ac8` — the base named above — or a +The `git log` command must expose `e67ad07` — 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 @@ -262,26 +264,23 @@ absorption" was too generous. Five stale lanes remain below, and two `COHERENCE.md` corrections had not been made at all. What is done here is listed at the commit that does it, not promised here. -- **Branch `gui-arc-stage0`**, base `githubsucks/main` @ `0e4c58d` (the - #231 merge). **`githubsucks/gui-arc-stage0` is the authoritative - tip** — the ref, not a SHA. Recover with +- **Branch `gui-arc-stage0`**, base `githubsucks/main` @ `e67ad07` (the + file-watcher arc absorption) after the 2026-08-11 rebase; it was + branched at `0e4c58d`. **`githubsucks/gui-arc-stage0` is the + authoritative tip** — the ref, not a SHA. Recover with `git fetch githubsucks && git checkout gui-arc-stage0`. - **Framing `docs/gui-arc-framing.md`, revision 3, APPROVED 2026-08-10** after two review rounds (two blocking findings each round, closed). It is **also the framing for Stage 0 itself**, which is docs-only; Stages 1–10 each require their own framing before their branch. -- **PARKED, deliberately.** Nothing further happens on this branch - until **#227 (git Stage 1) is finished and merged**. #227's ref is 72 - `main` commits behind and touches `COHERENCE.md`, - `docs/active-work.md` and `builtin/runtime/listview.lua` — the three - files Stage 0's absorption rewrites. Sequencing it first avoids - compounding exactly the conflicts Stage 0 exists to retire. The - branch exists now, ahead of that work, **only so the approved framing - is portable**: uncommitted work does not travel between machines, and - the framing spent its whole review as an untracked file in one - worktree. -- **Scope when it resumes (docs only, no `src/`):** the absorption pass +- **The park is over and the work is DONE.** The branch was parked at + its first commit until #227 merged, because #227 was 72 `main` commits + behind and touched the three files Stage 0's absorption rewrites. + #227 merged (`b867f64`), #233's arc closed (#234, #235), this branch + rebased onto `e67ad07`, and the absorption ran. **15 commits above the + base; ready for its PR.** +- **What landed (docs only, no `src/`):** the absorption pass enumerated in the framing's §5 — five stale lanes, the authority/recovery anchor, `COHERENCE.md`'s `v6..=v21` → `v6..=v23`, the U4 correction and the U9 rewrite in `docs/ci-red-signatures.md`, diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index df056b7..8e381cf 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -3195,6 +3195,20 @@ servers. ## 6. Named deferrals (the standing backlog, consolidated) +**The GUI arc — OPEN, framing approved 2026-08-10, Stage 0 in PR.** +`docs/gui-arc-framing.md` is the arc-level frame and is also Stage 0's +own framing; Stages 1–10 each need their own before their branch. It +opened from a daily-driver report: the TUI is daily-drivable, the GUI is +not. **`COHERENCE.md` §16 now carries a PRODUCT subgrade (Weak) beside +its architectural one (Strong)**, and the arc is what closes it. §20 +places Half A after Priority 1, and **reaching Stage 4b is a P2 START +GATE** — no later GUI stage begins until P2 has an approved framing and +an opened lane. The name is deliberate: **"Arc 8" means the Lean 4 arc +and nothing else** (Q#GA4). Several standing-backlog items below are +sequenced by this arc rather than deferred — §2.5 of the framing maps +every one to a stage or leaves it here explicitly. + + **Fixture project-detection census — NOT STARTED, follow-on from R8.** `tests/m4_acceptance.rs` alone constructs state through `EditorState::new_with_roots` **113 times**, and an unknown number of