#165's own commits could not update the handoff snapshot to name the
merge that contains them, so the protocol obligation lands here.
- `docs/agent-handoff.md`: absorb the dired lane into §1, replacing the
placeholder that promised exactly this. The bullet carries Stage 1's
durable substrate facts — why the tolerant `read_dir` had to be Rust,
why exposing the core normalizer beat mirroring it in Lua, the
fixed-width `_layout` contract Stage 3 reads offsets from, the
ambient-action buffer guard, treating a failure as the answer instead
of probing, the per-entry error cap, the first mode-scoped keymap and
the pre-existing test it broke, and the dedication a descent does not
carry. Refresh the head-of-`main` anchor and the last-updated line.
- `docs/agent-handoff.md` §5: two ops lessons that cost real time. A fix
must be committed before it is bitten, because `scripts/bite` restores
by `git checkout --` and reverts to HEAD; a CONFLICTING PR runs no CI
at all, because `pull_request` workflows build a merge ref GitHub does
not create while the branch conflicts, and nothing reports the absence.
- `docs/active-work.md`: remove the merged lane per update-protocol rule
4 and summarize it under "Closed since the last snapshot", keeping the
two forward items Stage 2 needs (the rename rebind is first-match-only
over a raw path, and Q#DR5's seam is the main-thread drain). Refresh
the canonical base. Flag the two lane headers that still call a merged
PR "IN REVIEW" — #161 and #166 — rather than editing lanes another
thread owns.
- `COHERENCE.md`: #165 is no longer a PR. Per §25 the audited claims this
work changed were updated when it landed; this corrects their tense in
seven places and the two prose lines that still asserted dired was in
flight.
- `docs/dired-framing.md`: status line to MERGED, and state plainly that
Stages 2 and 3 each still need their own framing.
Docs only; no code, no gate-relevant change.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126d2sikA6jZpFin3rtLCSK
Main moved again while this lane was gating: the GPU terminal-input fix
merged as #166. One conflict, in COHERENCE.md's journey table, resolved
as the union -- this lane owns step 7's file half, #166 owns step 8's
GPU-terminal addendum.
Multi-root LSP affinity merged as #161 (`main` @ `46a1b8f`) while this
lane was in review, which made the PR conflict -- and a conflicting PR
has no merge ref, so GitHub silently stopped running CI on it after the
first push. Integrating rather than rebasing, per the #135/#137
precedent: the review anchors stay addressable and every gate is rerun
against the merged tree.
One conflict, in COHERENCE.md's in-flight list, resolved as the union of
both truths -- and #161 is now merged, which its own text still called a
PR.
The overlap to watch is `src/lua_bindings/mod.rs`: #161 widened the
`lsp.list()` row builder while this lane added `pmacs.path` and the
read_dir listing conversion. The merge was textually clean, which the
folding arc's lesson says is not the same as compiling, so the full gate
suite reruns from here.
COHERENCE.md section 25 and the handoff/ledger update protocols make
these ride the PR.
COHERENCE.md:
- Section 6 named one optimistic key classifier and attributed it to the
GPU. There are two, one per replica frontend:
crate::optimistic::classify_key belongs to the pmacs --attach TUI
replica, and pmacs-gpu has its own unrelated optimistic_insert_text /
optimistic_crdt_insert. The section's "kept honest by
dispatch_idle_for" claim is confirmed for both, which this
investigation verified rather than assumed.
- Section 16 graded per-frontend degradation strong on the evidence of
per-frontend fold projection. That grade stands, but the practice is
enforced by convention rather than structure, and this defect is the
counter-example; the note says so and points at what is now structural.
- Section 2 step 8 records that the terminal was broken outright on the
GPU frontend, not merely undiscoverable.
docs/agent-handoff.md section 5 gains four lessons: adjacency does not
make two operations alternatives (and two individually sound idempotence
guards can be jointly useless); bite against every pre-image the fix
could have taken, since the obvious guard here fixes the storm and
introduces a controller leak; a quiet child is an instrument, because a
frame storm hides inside a chatty fixture and a geometric readout is
satisfied by an oscillating geometry; and TerminalMode::Raw makes
sh-based input fixtures useless because there is no ICRNL.
docs/active-work.md gains the lane entry with the branch, the bite
matrix, the named out-of-scope items, and the gate results.
docs/dired-framing.md rev 6: §0 gains the Stage 1 implementation notes
(S1-1..S1-9) -- the normalizer is exposed rather than mirrored (so B2 is
false by one small binding, in the direction Q#DR2 preferred); R2-3's
dedication claim is falsified by the display policy; acceptance 3c
cannot pin the descent routing and now says so; dired is the first
builtin to bind a mode-scoped key, which one pre-existing lib test
assumed impossible; `C-x d` takes no completion source on purpose;
ownership is the handle table alone; the mark column ships blank; a
symlinked directory needs a probe; and interactive origin does not
survive an await.
COHERENCE.md, per its §25 (an audited claim this PR changes updates
here, riding the PR): §1.1's interactive-file-opening fact, §2's journey
step 7, §4's beginner-level `files`, §14's tree bullet (Stage 1 landed a
flat listing and did NOT invent a tree convention), and §15's Priority 1
list. Step 3 stays **Missing at the CLI** with the mechanism spelled
out: `pmacs .` still exits 1, and this arc deliberately does not claim
the CLI path -- it supplies the buffer a directory should resolve to.
docs/active-work.md: the dired lane rewritten for Stage 1, including why
the branch is a fresh cut rather than a rebase of `dired`, the durable
substrate facts, the bite results (one VACUOUS, recorded rather than
relabelled), and the verification. Its canonical-base line was four
merges stale and now names 8c86d34.
docs/agent-handoff.md: one forward pointer only. The handoff describes
merged state, so it absorbs the substance when this merges.
Rides this PR per COHERENCE.md §25 ("when a PR changes any audited claim
here, updating this file rides that PR").
§0 and §7: multi-root LSP affinity moves from in-flight-branch to PR
#161, and §7 gains the rule the slice actually establishes — a
*fallback* root is deliberately NOT an identity, so markerless files
keep sharing one server per language. That is the part a reader would
otherwise assume went the other way.
§1.2 gains the finding this PR turned up, which sharpens the audit
rather than restating it. The section recorded that background failures
produce "no `*errors*` entry"; the sharper fact is that **the channel
does not exist**. Fifteen call sites — `async.lua` (5), `syntax.lua`
(4), and one each in `lsp.lua`, `mcp.lua`, `fs.lua`, `editops.lua`,
`autosave.lua`, `commands/default.lua` — report through `pmacs.error`,
each guarded `if pmacs.error then ...`. It is defined nowhere in
production; the only assignment in the tree is a test stub
(`src/editor.rs:9881`), and `type(pmacs.error)` is nil in a fresh
`EditorState` (probed, not inferred). `pmacs.errors` plural in
compile.lua is an unrelated namespace. All fifteen are dead, and the
guard is what kept it unnoticed — it makes the silence read as
deliberate.
Hence the corollary now recorded beside the rule: report through a
channel with a **test that observes it**, or the guard is
indistinguishable from the silence it was meant to fix.
Also a frequency note: per-root affinity makes the
preconfigured-but-missing-server failure fire once per project root
rather than once per language per session. Unchanged in kind, strictly
more frequent. Surfacing it stays Priority 1 work needing its own
framing — it is user-visible product behavior (what message, where,
with what guidance), not a substrate fix to smuggle into an affinity PR.
Line-number citations in the touched sections re-verified per §25;
symbols are authoritative where they drifted.
COHERENCE.md states the product-coherence thesis (pmacs should be
immediately excellent, progressively understandable, completely
inspectable, and ultimately replaceable) and, per-section, the audited
ground truth of how the codebase measures against it: a scorecard
across 19 concerns, the golden-journey verdict table (breaks at "open a
real project" -- `pmacs .` exits 1), the six hardcoded key-interception
shadows with no transient-keymap mechanism to migrate them to, the
discoverability substrate-without-surface gap, the package/worker
identity gap, and three cross-cutting patterns (substrate without
surface, the silence asymmetry, per-arc coherence debt) that explain
most of the individual findings.
CLAUDE.md and AGENTS.md now list it as required reading alongside
agent-handoff.md and active-work.md, and ask new framing docs to state
their coherence impact. No runtime code changes.
Levi Neuwirth