Review finding (P2): docs/active-work.md and docs/agent-handoff.md both
still said "PR not yet open". This file's own rule is that an open PR
gets a lane recording its state — "When a PR is opened, give it a lane",
written after #171 drifted 153 commits while invisible here. Both now
carry PR #209, its six commits, and the first CI run.
That run is worth recording rather than merely citing, because it
discharges the one risk the framing could not close locally. ALL 14
CHECKS GREEN, including both new jobs (Test (crdt) 12m20s, M10 Perf
Gates (crdt) 5m40s) and the macOS/luajit leg that is the documented
flake surface. This was the first time in the project's history that
any of these tests executed in CI.
ACCEPTANCE 8 HOLDS AGAINST THE REAL RUN. Test (crdt) reported 3,717
passed / 0 failed / 30 ignored: the 3,746 all-targets census (with
basedpyright NOT skipped, as it is locally) plus one doc test, less the
30 ignored. The job demonstrably compiled and ran the crdt corpus rather
than reporting green over nothing — which was the whole point of writing
that criterion while the local sweep was already green.
A trap for the next reader is recorded with it: DO NOT SUBTRACT THE TWO
JOBS' TOTALS. Test (ubuntu/luajit) reports 3,485 and Test (crdt) 3,747,
a difference of 262 rather than 279, because the jobs run different
SETS — the non-crdt job adds pmacs-protocol's 17 tests. The dark count
is the all-targets comparison, 3,746 - 3,467. The wrong number looks
entirely plausible.
Chasing that discrepancy found a real gap, and one this lane's own tool
could never have surfaced: PMACS-PROTOCOL HAS ITS OWN `crdt` FEATURE.
It gates no tests, so a per-test census reports 17 either way and scores
the crate as unaffected — but it changes `cfg!(feature = "crdt")`
EXPRESSIONS inside InstanceCapabilities::default and
FrontendCapabilities::default, so those same 17 tests exercise different
runtime values under it. CI had only ever run the non-crdt ones. Closed
with an explicit `-p pmacs-protocol --all-targets --features crdt` step,
verified 17/17.
The blind spot is structural, not an omission, so it is documented at
the tool rather than fixed in it: scripts/feature-census censuses the
workspace DEFAULT MEMBER, because that is what a bare
`cargo test --all-targets` builds. Sibling crates are invisible to it no
matter what configs are passed. The durable lesson: A FEATURE CAN MATTER
TO A CRATE A PER-TEST CENSUS SCORES AS UNAFFECTED. Check siblings by
hand.
Verified: ci.yml parses at 10 jobs, script syntax clean, fmt,
diff-check, and the new protocol step green locally.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Framing revision 3, plus the ledger and handoff updates the lane owes.
docs/active-work.md's "NEEDS A LANE" block is replaced rather than
annotated: the lane now has a branch, a framing, an implementation and
verification, so the old text's premise ("no branch, no framing yet")
was the part that needed removing. Its stale figures go with it — the
273-dark reading at 74301d1 and the seven-item clippy list, both
superseded and both explicitly labelled do-not-quote in the new block.
The corrections this lane produced, all now recorded where the next
reader will hit them:
* m10_10_perf is a CI-DEFAULT REGRESSION TRIPWIRE, not a bench. Its
bounds are deliberately generous "to catch catastrophic regressions,
not to verify a tight perf claim", so #[ignore]ing it to give it a
perf job would have reduced coverage inside a coverage lane. The
framing had this backwards through revision 1 and says so.
* gpu-render runs `cargo test -p pmacs-gpu` — a DIFFERENT PACKAGE from
the root-package GPU suites. The long-recorded fix-shape of "move
the GPU-requiring crdt suites onto gpu-render, it already has
lavapipe" does not work as written.
* PMACS_REQUIRE_GPU is not uniform: absent from
gpu_invocation_acceptance and gpu_initial_target_acceptance
entirely, so it cannot serve as blanket proof the GPU suites ran.
* The dark-test classification found THREE dispositions, not two:
benches awaiting a job, deliberately-manual operator tests, and
known-defect markers. Collapsing the second into the first gives a
CI job to tests whose #[ignore] reason says not to.
* §1.1's own target-column claim was wrong, and scripts/feature-census
caught it. Eleven targets run with zero tests under CI's flags;
eight of those gain tests under crdt and three are helper binaries
with no tests in either. The framing had merged two true statements.
Acceptance 9 is revised rather than quietly met at a lower bar. The
planned deliberately-broken-test bite is replaced by the --covers
coverage assertion plus the CI count reconciliation, and the doc states
what that trades: stronger on the claim specific to this lane (the old
job STRUCTURALLY cannot see these tests), and no longer proving that a
failing crdt test turns the job red — which is generic cargo and Actions
behavior, not anything this lane changes.
The handoff gains a census hazard beside the existing sweep note,
because every trap in it was hit while writing the script and one of
them survived two framing revisions: libtest prints `name: test` with no
space before the colon, a zero-test target prints only its Running line,
and both configurations need an --ignored pass or pre-existing ignores
get attributed to the feature.
The ledger also records what is NOT established, which is the lane's
whole remaining risk: the sweep is green SERIALIZED ON A DEVELOPER
MACHINE, and the failures this lane expects are hosted-runner timing and
concurrency. That green removes the "tests are wrong" explanation and
leaves the expected one untested. It must not be quoted as evidence the
CI leg will be green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs/active-work.md says the dark-test figure "moves with every merge
and must be re-measured, not quoted." That instruction has never had a
tool, so every re-measurement was a hand-rolled `--list` pipeline
written from scratch.
Hand-rolling it is not safe. Writing this lane's census by hand, the
first attempt filtered libtest's list with `/ : test$/` — but the output
is `name: test` with NO space before the colon, so it matched nothing,
reported zero targets, and looked like a clean run. A census that
silently reports nothing is the same failure class as the dark tests
themselves: no signal, presented as a result.
scripts/feature-census diffs `cargo test --list` between two feature
configurations and reports what the second has that the first cannot
see. Its header records each parsing trap, because every one of them was
hit while writing it:
* `name: test` has no space before the colon.
* `--list` also emits `: benchmark` lines.
* cargo's `Running` lines have two shapes — `unittests src/lib.rs` and
`tests/foo.rs` — so a fixed field index handles one and mangles the
other.
* a target with zero tests prints its `Running` line and nothing else,
so counting only test lines DROPS it from the diff — losing exactly
the finding worth surfacing.
* `--list` includes #[ignore]d tests, which are dark in the same sense
but are NOT recovered by adding a feature to an ordinary test job.
That last one needed a second correction after the script was running.
Counting only B's ignored set attributed pre-existing ignores to the
feature: `rope::tests::perf_smoke_*` are ignored under both configs and
are not "dark and ignored." Both sides now get an ignored pass and the
figure is the difference, which is what turns a flat "279 dark" into
"268 recovered by a plain leg, 11 needing --ignored."
The script also corrected a claim in this lane's own framing doc. The
framing said eight test binaries contain zero tests under CI's flags,
derived from a target-count difference (93 vs 101). The truth is that
ELEVEN targets run with zero tests under those flags; eight of them gain
tests under crdt and three are helper binaries with no tests in either
configuration. Two different true statements, and the framing had
merged them.
Fail-closed on a build failure (exit 3) rather than reporting a census.
A configuration that does not compile yields no test list, which is
indistinguishable by counting from "this configuration has no tests" and
would render as a spectacular and entirely false "every test is dark."
That is not a small error; it is a number that would get quoted.
All five documented exit codes are exercised rather than asserted: 0 on
a clean census and a holding --covers claim, 1 when the claim fails
(both for a test present under both configs and for a misspelled name),
2 on usage, 3 on a configuration that fails to build.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Nothing in this workflow ever enabled the `crdt` feature, so every
`#[cfg(feature = "crdt")]` test was NOT COMPILED — not skipped, not
filtered, not reported. Measured at 4223dd3: 3,467 tests under the
`test` job's flags versus 3,746 with `crdt`. 279 tests had never
executed in CI, and 186 of them are in the library, whose
`cargo test --lib --features crdt` invocation CLAUDE.md lists as a
REQUIRED pre-PR gate. CI had never run a required gate.
Eight test binaries also contained zero tests under the old flags. They
built, ran, and reported `ok` with nothing in them.
This job recovers 275 of the 279. The other four are excluded on
purpose, each for a stated reason rather than left as residue: three are
m10_11_acceptance's PTY-doubled tests, marked "operator-invoked before
tagging, not CI-default", and one is the #157 CRDT undo repro, an
#[ignore]d marker for a known open defect whose arming belongs to that
defect's lane. Seven of the 275 arrive via m10-perf-gates in the
previous commit; this job carries the remaining 268.
ONE JOB, NOT TWO. The shape recorded in docs/active-work.md put the
GPU-requiring suites onto `gpu-render` "which already has lavapipe and
PMACS_REQUIRE_GPU". That job runs `cargo test -p pmacs-gpu` — a
DIFFERENT PACKAGE from the four root-package suites that would move
there, so co-locating them would mean adding a whole new invocation
rather than extending an existing one. Splitting also requires
enumerating which suites are GPU-requiring, and a suite added later
would silently land in the job that needs no GPU and skip there forever.
Running the whole corpus in one place with a working adapter cannot
develop that hole.
PMACS_REQUIRE_GPU is set because these suites do not fail without an
adapter — a37 and its siblings eprintln a skip and return `ok`, measured
at 9/9 in 0.17s versus ~4s for a real run. The build is --workspace
rather than root-only because those suites locate the `pmacs-gpu` binary
beside `pmacs`, and its absence is the documented cause of twelve
gpu_invocation_acceptance failures on a crdt sweep.
The external-tool install block from the `test` job is deliberately not
duplicated. It gates m4_acceptance, m6_5_repl_acceptance and
m6_8_multi_repl_acceptance, and none of those has a single dark test —
measured, not assumed. Installing clangd/zsh/fish/lua/rust-analyzer/
gopls/npm servers again would cost minutes to change nothing. The only
tool-gated code in the dark set is src/process.rs, whose two variables
need no install and are set.
Clippy for the crdt targets runs HERE rather than in the `clippy` job.
Clearing those lints once is not enough: the `clippy` job matrixes over
Lua flavor and never enables `crdt`, so without this step the targets
drift straight back out of compliance and the next job to compile them
is red on arrival — the exact state this lane found. One job now owns
"crdt compiles, lints, and passes."
Verified locally at the exact commands this job runs: clippy green,
doc tests green, and the full serialized sweep with PMACS_REQUIRE_GPU=1
at 3,715 passed / 0 failed / 30 ignored in 366s — identical to the
pre-change sweep, so the lint commit changed no behavior. The 35-minute
ceiling is justified in the job comment against that measurement plus
lavapipe and cold-cache headroom.
This job has NOT yet been proven non-vacuous. That is the next commit:
break a crdt-gated test, confirm this job goes red, revert. A leg added
to a corpus that is already green locally cannot otherwise be
distinguished from a leg that compiles nothing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`m10_2_perf` and `m10_11_perf` were dark for TWO independent reasons,
and only one of them is this lane's headline subject:
1. They are `crdt`-gated, and nothing in the workflow enabled the
feature, so they were never compiled.
2. Even setting `crdt` aside, no job named them. Grepping ci.yml for
`--test` yielded exactly four suites: acceptance, m4_acceptance,
m5_perf_acceptance, m6_perf_acceptance. Their `#[ignore]` is
deliberate; their absence from every workflow was not.
Fixing both here is a deliberate scope call, taken with the second cause
named rather than absorbed: leaving it would ship a lane headlined "the
dark tests now run" with 7 still dark, and the remedy is one job block,
not a second investigation.
The two suites are NOT the same kind of thing, and the job says so
because a future reader will otherwise assume "perf gates" means
"budgets":
* m10_11_perf asserts one budget — cross-frontend propagation p99
under 50ms. Measured 1.47ms locally, a ~34x margin, so a red here
is a regression rather than runner noise.
* m10_2_perf asserts NOTHING. Six benches that print throughput
numbers, the baselines M10.2's 391x unicode finding and v0.2+
optimization work compare against.
Including a suite that cannot fail a budget needs its own
justification, so the workflow states it: `run_workload` drives 30
seconds of randomized mixed edits against both the v0.1 and CRDT buffer
paths, and nothing else in the corpus exercises a sustained randomized
CRDT workload. Its value here is soak and panic detection, not gating.
The comment explicitly warns against "fixing" it later by adding
throughput assertions, which is how perf jobs become flaky on shared
runners.
Per framing Q#CC3 and §1.3a, `tests/m10_10_perf.rs` is deliberately NOT
touched: it is a CI-default regression tripwire with generous bounds,
not a bench, and adding `#[ignore]` to give it a job would have shipped
a coverage reduction inside a coverage lane. It is recovered by the
plain crdt leg in the next commit instead.
Observed execution, local release build 2026-08-01: m10_2_perf 79s
(6 passed), m10_11_perf 5s (1 passed). The 25-minute ceiling matches
m5-perf-gates and is set by the cold-cache release build, not the ~85s
of tests — the reasoning the file already applies to its other perf
jobs.
Verified: ci.yml parses, 9 jobs, every one carrying timeout-minutes.
Both suites pass locally under the exact commands the job runs.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`cargo clippy --workspace --all-targets --features crdt -- -D warnings`
has never passed on main. The standing gate list runs clippy without
`crdt`, so these lints have never been enforced, and any CI job that
compiles the crdt targets would be red on arrival. This is framing §7
step 1: nothing else in the lane is testable until it lands.
Eight findings across four files, none behavioral:
src/daemon.rs useless_conversion (u64)
src/daemon.rs missing doc backticks
src/daemon.rs too_many_lines (112/100)
tests/auto_indent_crdt_acceptance.rs missing doc backticks
tests/bottom_panel_stage2b_gpu_acceptance too_many_lines (104/100)
tests/vterm_stage3_acceptance.rs too_many_lines (122/100)
tests/vterm_stage3_acceptance.rs too_many_lines (132/100)
tests/vterm_stage3_acceptance.rs redundant `continue`
--keep-going is what made this an inventory rather than a lower bound.
docs/active-work.md recorded seven findings at 74301d1 and correctly
warned they were "a lower bound, not an inventory" because clippy
abandons remaining targets once one fails. With --keep-going the set is
complete, and it differs from the ledger's in both directions: the
`unneeded mut` at src/daemon.rs:4965 is gone (fixed incidentally by
later work), a finding in bottom_panel_stage2b_gpu_acceptance.rs is new,
and every src/daemon.rs line number had moved. A stale lint inventory is
worse than none — it invites fixing lines that no longer exist.
The four too_many_lines findings are silenced with a reason rather than
refactored. Refactoring a test body to satisfy a lint that has never run
would be a behavioral change riding a CI-configuration lane, and the
codebase already has ~20 `#[allow(clippy::too_many_lines)]` sites, the
best of them carrying `reason =`. Each reason states why the scenario is
one test: the GPU acceptances exist specifically to prove a real
daemon, a real PTY and real wgpu fit together, which splitting would
hide.
The redundant `continue` needed care. Replacing it with `Err(_) => {}`
traded the lint for `single_match` — the match then destructured one
pattern. Rewritten as an edition-2024 let-chain, which drops both
without changing semantics: an unreadable message still falls through
to the next loop iteration.
Verified: clippy green with and without `crdt` (the second confirming
no regression to the enforced gate), fmt, diff-check, --lib --features
crdt 2081 passed, and the three touched suites green — vterm_stage3 at
9/9 in 4.34s rather than 0.17s, so a37 really ran rather than reporting
ok on a missing binary.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`.github/workflows/ci.yml` never enables the `crdt` feature anywhere, so
every `#[cfg(feature = "crdt")]` test is not compiled in CI — not
skipped, not filtered, not reported. 279 tests have never executed in
CI, and 186 of them are in the library, whose `cargo test --lib
--features crdt` invocation CLAUDE.md lists as a required pre-PR gate.
CI has never once run a required gate.
Named in docs/active-work.md as "NEEDS A LANE" since it was found while
gating #166, with no branch and no owner until now.
Revision 2, approved. What the scout established beyond the ledger:
- The census moved and was re-measured at 4223dd3: 279 dark, not the
ledger's 273. Plus a fact the old census did not carry — eight test
binaries contain zero tests under CI flags, so they build, run, and
report ok with nothing in them.
- "279 dark" overstates the fix. Eleven are #[ignore]d, so a plain crdt
leg recovers 268. All 279 are now assigned a disposition: 268 by the
leg, 7 by a new m10-perf-gates job, 3 deliberately manual, 1 an
ignored known-defect marker. The lane recovers 275 of 279 and the
other four are excluded for stated reasons rather than left as
residue.
- The classification docs/active-work.md called "the lane's first task"
is finished, and it found three dispositions rather than two:
benches awaiting a job, deliberately-manual operator tests, and
known-defect markers.
- The ledger's clippy inventory was stale in both directions. It warned
its own list was "a lower bound, not an inventory" because clippy
aborts on first failure; --keep-going is what converts it. The
complete set is eight findings across four files, none behavioral.
- A hole in the proposed fix shape: the gpu-render job runs
`cargo test -p pmacs-gpu`, a different package from the four root-package
suites the fix wants to move there. And PMACS_REQUIRE_GPU is absent
from two of those four, so it cannot serve as blanket proof they ran.
- The full serialized crdt sweep is green: 3,715 passed, 0 failed, 30
ignored, reconciling exactly to the 3,746 census. That green result
shaped the acceptance criteria more than a red one would have — a
green pre-measurement is the condition under which a vacuous CI job
ships unnoticed, so the criteria gained a count reconciliation and a
deliberately-broken-test bite.
Revision 1 -> 2 also corrects revision 1's classification of
m10_10_perf, which was wrong in a way that would have made the lane
worse: the suite is a deliberate CI-default regression tripwire with
generous bounds, not a bench, so adding #[ignore] would have shipped a
coverage reduction inside a coverage lane.
Framing only. No workflow change, no source change, no branch plan
executed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Nine PRs landed since the handoff's anchor (#199-#207) and it named
only four of them, so a fresh machine would not have learned that
ambient-root isolation exists, that the journey arc's 1b split
completed, or that the reap-ledger diagnostic landed. The ledger's
canonical base and recovery floor were five merges stale, and three
lanes described merged work as in flight.
Taken now because ZERO PRs are open. The ledger's own rule is never to
open a standalone refresh PR — because with several PRs open a lane
written on `main` re-conflicts at every merge — and this is the one
window where that cost is nil.
The handoff gains §1a, "Outstanding work — the whole board", which is
the point of the pass rather than a by-product: every arc against §20's
priority order with its next step, every open lane, every deferred item
attributed to the framing that parked it, and the standing hazards
someone running gates on a new machine needs — the three known flakes
by name, the basedpyright skip, the crdt sweep's build prerequisite,
and why a green a37 means nothing alone.
Two arcs completed, so per rule 4 their lanes are removed and their
facts are in the handoff: Journey Stage 1 and test ambient-root
isolation. Discovery and reap-ledger merged a stage each, so their
lanes are rewritten to the remaining plan rather than deleted — the
discovery lane now enumerates Stage 2 in dependency order and carries
the two Stage-1 facts a Stage-2 author would otherwise rediscover.
Base and floor advance together to `cfc1710`, per the file's own rule
that a floor accepting an older commit than the declared base passes on
a tree the document does not describe.
The recovery path was EXERCISED rather than asserted: from an empty
directory, clone, alias, fetch, floor check, and a lane worktree all
ran clean. The two-argument `git worktree add` still fails for a
remote-only branch, which is why every lane spells out the `-b` form.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
CI caught this on all four test legs. The forwarder body called
`pmacs.command.invoke_interactive`, which raises when the alias is
reached through `pmacs.command.invoke` — and
`tests/config_registry_acceptance.rs` does exactly that, three times.
The acceptance pin passed throughout because it drives the M-x path,
which is the path the framing spent three review rounds getting right.
Being right about one entry point is not the same as covering the
command, and a rename touches every caller of the old name regardless
of how it is reached.
Plain `invoke` is also the correct semantics rather than merely the
working one: the interactive-command boundary is rotated once, by
whatever entry point the user actually used, for the name they actually
typed. Rotating again on the inner call would record a second boundary
for a command the user never invoked.
Adds `d8c`, which invokes both forwarders programmatically. Bitten by
restoring `invoke_interactive`: the new pin fails alongside the three
config-registry tests that found it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
The isolation lane (#206) landed with an adoption ratchet, and it
caught this branch's brand-new suite on the first run after the merge:
these suites construct an editor through the ambient entry points,
so they read the developer's real init.lua and write into their real
data root: ["discovery_acceptance.rs (1 site(s))"]
That is the ratchet working as designed against code written by someone
who was not looking at the isolation lane while writing it — which is
the case it exists for.
`discovery_acceptance` is therefore MIGRATED, not allowlisted: it
includes `common/iso.rs` and constructs through
`EditorState::new_with_roots(&iso::roots())`. Allowlisting would have
put a fresh ambient site into the census the same day the census was
built.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Review round 2 on #207, two findings, both accepted.
Three places said workers have no discovery surface. They do:
`editor.list-workers` opens `*workers*` via M-x, which §2's own step-11
row has recorded all along — so the document contradicted itself. Two
of the three were mine, including the bullet I wrote last round while
correcting a different stale claim in the same section; grepping for
the phrase found only the two pre-existing sites because my own copy
was split across a line break.
Corrected to say what is actually missing, which is not the same thing
for the two subjects: PACKAGES have no comparable surface at all, while
workers have one and lack §9's ownership model and activity indicator.
Collapsing those into "no discovery surface" would send a reader at the
wrong work.
Separately, §4's extension-surface list called completion/minibuffer
sources "a fixed Rust vocabulary". `parse_completion_source` accepts a
Lua function as `CompletionSource::Custom` — the mechanism this very PR
uses to give `help.describe-setting` completion with no Rust. The claim
now names it, since a reader who believed the old text would conclude a
custom source needs binding work it does not.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
§7 said the classification comes first and alone, "its answer belongs in
review before any mechanical edit rides on it." The classification came
back at 342 sites across 66 of 97 files, and the whole-corpus migration
rode this PR anyway. That was a decision, not an oversight, and revision
5 records it as one so a later reader does not have to reconstruct it
from the diff.
The reasoning, in short: splitting would either leave 65 suites still
writing the developer's real data root while the seam sat unused, or ship
acceptance 12's ratchet with a ~65-file allowlist — and a ratchet
exempting most of the corpus records rather than ratchets. §7's ORDERING
is honoured (the census is the first commit); its implied SCOPING is not.
Revision 5 also records what review round 1 established about the shape
acceptance 12 needs: "a narrow, named allowlist" is not sufficient by
itself, because narrowness constrains which files are exempt and says
nothing about how far each exemption stretches. Exemptions carry counts.
`docs/active-work.md` picks up the same two facts and the PR number.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Review round 1: `isolated_construction_is_init_complete` asserted its
paired half — that the *ambient* constructor is unchanged — with an
ambient `EditorState::new()` in an ordinary parent test. That reads the
developer's real `init.lua` and materializes packages into their real
data root: the exposure this suite exists to remove, committed by the
suite itself.
The claim is worth keeping, so it moves rather than dies. It now lives in
the re-exec'd positive control, which runs only as a child under a
hostile-by-construction environment. That is the one place an ambient
constructor is safe, and so it is where every ambient claim this suite
makes belongs.
**The ratchet did not catch this, and that is the more important half.**
`ambient_isolation_acceptance.rs` was on the allowlist for its positive
control, and a bare file-level exemption licenses the named file to grow
new ambient sites forever — which is exactly what happened. So every
exemption now carries its **exact permitted site count**, and a file with
more sites than it was reviewed with fails even while allowlisted. A
count that drops fails too, so the allowlist stays a census rather than
drifting into a ceiling nobody rechecks.
The count immediately earned itself: it rejected the number written from
memory for `journey_acceptance` (47) and reported the real one (26 — 19
`new()` + 7 `open(`, after the scanner drops two assertion-message
mentions and the assembled `concat!` needle).
Verified in both directions: restoring the removed ambient site fails the
ratchet with `2 site(s), allowlist says 1`; and with the ambient half
gone, both init-complete pins still fail under the `if roots.is_ambient()`
mutation, so neither has become a test that passes for the wrong reason.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Review round 1 on #207, one finding, accepted. I moved §5's scorecard
row and ground-truth grade but left the itemized "what is missing" list
below them describing the pre-stage world, so the section contradicted
itself.
Two claims were false at this PR's head:
- §4's disclosure table said keybinding search was absent ("no
list-keybindings/where-is commands"). It now reads ✓ with the three
commands named, and keeps the real remaining gap: no key reaches
them.
- §5's "missing as commands entirely" bullet listed all nine new
commands and recorded `describe-setting` as free-text with no
completion source. Both shipped. The bullet now states what exists,
and names what genuinely remains: no discovery surface for packages
or workers, no key on any of it, and completion that assists rather
than validates.
The superseded text is pruned rather than kept as a provenance note,
per §25 — "prune superseded facts rather than appending; this is a
briefing, not a log."
While in the section I also corrected the `C-h` bullet, whose citation
I was touching anyway. It reported the keymap's own "the key was free"
comment without the reason that comment omits: non-kitty terminals
cannot disambiguate Ctrl+Backspace from Ctrl+H, so rebinding breaks
Ctrl+Backspace everywhere legacy. Reading it as an oversight is what
would send someone at the wrong fix, and it is precisely why Stage 1
shipped the family unbound.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Per §25 the audited claim this stage falsifies is updated on the
landing PR. §5's scorecard row and ground truth both said the
registration metadata was best-in-class with almost no way for a user
to reach it; eleven `help.*` commands now reach it.
The row names what is still missing rather than implying the concern is
closed: packages and workers have no discovery surface, `Command` still
has no title/category/aliases/flags, M-x rows are still bare name
strings, the predicate is still never evaluated, settings value
provenance is still absent, and there is still no help prefix key. The
original audit grade is kept inline for reference.
`docs/keybindings.md` gains the family table and records that the
commands are reachable by name and bound to nothing — the help-prefix
decision belongs to a later stage, for the reason #205 recorded.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Implements `docs/discovery-stage1-command-family-framing.md` (approved
at revision 6). `COHERENCE.md` §5 graded discoverability "substrate
without surface": the registries already carried descriptions, source
locations and reverse key lookup, and almost none of it was reachable.
Eleven commands under one `help.*` prefix, so typing `help` at M-x
surfaces the whole family. Nine are new; `editor.describe-command` and
`editor.describe-setting` are renamed in, with the old names retained
as forwarders so nothing documented breaks.
No Rust. Every command renders data `pmacs.describe.*`,
`pmacs.keymap.list()`, `pmacs.command.list()` and `pmacs.config.list()`
already return, and `describe-setting`'s completion source is a Lua
function via `CompletionSource::Custom`, which needed no binding work
either — correcting a comment in `default.lua` that claimed `source`
was a fixed Rust-side vocabulary.
`apropos` matches by substring, not fuzzy: `fuzzy_score` is
subsequence-based and descriptions are long sentences, so fuzzy would
match nearly every command.
Two disciplines the file keeps. Every command renders through the
public `pmacs.editor._show_help`, which buys one owner for the shared
`*help*` policy — reuse-by-name, wholesale replacement, `q`, and the
foreign-buffer hazard. It does NOT buy a one-site migration to
`src/help.rs`, which has no renderer for settings, lists or apropos; so
rendering is a named per-subject function, and the future Rust work is
enumerated per subject rather than discovered per call site.
The seam-counting pin earned its place immediately: the two renamed
commands were still calling the file-local `show_help_text`, so the
funnel was fiction for exactly the two commands that predate it. They
now call the public seam, with a comment saying why the local is not
used from the same file.
Moves `help` out of `welcome.lua` into the new `runtime/help.lua`,
which owns the family and loads after it so the index can read
`pmacs.welcome.entries`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
`docs/active-work.md`: the lane moves from FRAMING OPEN to
IMPLEMENTATION OPEN, with the implementation branch and worktree and a
recovery command that names them. The framing-only worktree is spent —
its doc is on `main` (#201).
`docs/agent-handoff.md` §3: a local full-suite run needs all FIVE
storage variables controlled, not four. `PMACS_STATE_HOME` outranks
`XDG_STATE_HOME`, so naming only the XDG four leaves a
higher-precedence state override live; and a run isolating only
`XDG_CONFIG_HOME` stops the `init.lua` reads while still writing through
the real data root — every local gate run in this repo before today had
that hole. `HOME` is deliberately excluded: it is the fallback the XDG
roots already cover once set, and it separately drives `~`-expansion,
which `find_file_acceptance` pins on purpose.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
The mechanical half, riding on the census in the previous commit.
* 342 in-process construction sites in 65 files now take
`new_with_roots` / `open_with_roots` with `iso::roots()`. The isolated
base is a pure function of `CARGO_TARGET_TMPDIR` — no counter, no
`OnceLock` — so two copies of the module in one binary agree instead of
racing, and the tree lives somewhere `cargo clean` owns rather than
leaking into `/tmp` once per run. It is shared deliberately:
materialization is content-gated and idempotent, so a per-test
directory would repeat it ~330 times per run for a byte-identical
result.
* `journey_acceptance` keeps the ambient `EditorState::open`, because
proving the production entry point has a caller is the whole of what
that ratchet is for. Rev 2's "isolated by the environment its binary is
launched with" was not a mechanism — cargo launches each test binary
with the caller's environment, and a binary cannot re-point its own
roots before its tests run. Each test is now a thin parent that
re-execs this binary for its own name with controlled roots, and the
child runs the body against production's call. Two pins guard it: the
child asserts all four roots resolve inside the controlled base, and
the suite asserts against its own source that it has not quietly taken
the seam. The parent also asserts the child ran `1 passed` — a stale
`--exact` filter would otherwise hollow the whole thing out silently.
* The shared spawners take all five storage variables.
`spawn_daemon_process_with_env` set `HOME` and `XDG_CONFIG_HOME` only;
`HOME` is a FALLBACK, so it isolates a root only while the matching
`XDG_*` is unset — the harness's apparent adequacy was a property of
one developer's environment. The PTY spawner backfills whichever of the
five its caller did not pin. The 10 direct `Command::new` daemon and
attach spawns get the same treatment.
Three suites had `mod common;` behind `#[cfg(feature = "crdt")]`;
`common::iso` is needed in every build, so those are ungated. Files that
already pull in `common` reach `iso` through a `use` rather than a second
`#[path]` declaration — loading one file as two modules is
`clippy::duplicate_mod`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
The census first, because it decides how large the mechanical edit is
(framing §7). Every occurrence was listed with its enclosing context and
read; a grep for the bare name over-counts, which is how revision 1
reported 18 by grepping `Editor::new` — a pattern that does not match the
real constructor.
in-process 342 calls in 66 of 97 files
(330 of 334 `EditorState::new()` occurrences; 4 are prose)
(12 of 14 `EditorState::open(` occurrences; 2 are strings)
spawned 14 real `pmacs` spawns in 8 files
(of 36 `CARGO_BIN_EXE_pmacs` hits, 18 are the fake-LSP and
fake-MCP siblings and 4 are path derivations for
`pmacs-gpu`, not spawns)
mixed 5 files are both, so sites — not files — are the unit
The full census, with per-site attribution, is the module doc of
`tests/ambient_isolation_acceptance.rs`.
Four things it pins:
* Isolated construction still finishes initialization, asserted twice —
the flag, and the behaviour it gates (`pmacs.attach` must refuse).
Falsified by wrapping the config block in `if roots.is_ambient()`;
`m8_2_acceptance` does NOT catch that, because reopening an already-open
init phase is a no-op.
* The writes land in the redirected data root — content produced, not an
invariant preserved. A "the real root did not change" check would pass
vacuously wherever it already holds identical bytes, since
`write_if_changed` is content-gated.
* Bet 3, in two children with opposite jobs. The positive control proves
the hostile environment IS hostile (an ambient editor loads its
`init.lua` and writes its data root); without it the isolation half
asserts nothing. The isolated child then stays green under the same
environment and leaves its hostile root byte-identical.
* A durable adoption ratchet, not a one-time census: a source scan that
fails when a new ambient constructor appears outside a named allowlist,
plus a check that no allowlist entry has gone dead. Its scanner strips
comments, strings and raw strings, and that stripping has its own pin —
the corpus contains all three shapes, and a grep-shaped answer already
cost this lane a review round.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
`EditorState::new` resolves two storage roots from the process
environment before it returns: the data root, which the bundled-package
materialization then WRITES into unconditionally (outside every `cfg`
guard), and the config root, from which `init.lua` is read.
The `#[cfg(not(test))]` guard on the second was written to stop the
crate's own unit tests picking up a developer's real `init.lua`. It does
exactly that and nothing more: `cfg(test)` is set only while compiling
the lib's own tests, so an integration test in `tests/` — compiled
without it — reads the real config and writes the real data root. On a
machine with a real `~/.config/pmacs/init.lua`, that is 11 deterministic
failures in `compile_mode_acceptance`, attributed to whatever branch is
checked out.
Tests cannot fix that themselves: `std::env::set_var` is `unsafe` and
this crate is `#![forbid(unsafe_code)]` — the same constraint that
produced `Installer::with_install_root_override`. So isolation arrives as
a parameter.
`BootstrapRoots` names the four storage roots (config, data, state,
cache). `ambient()` leaves every one `None` and every resolution goes to
the environment exactly as today, so production is unchanged.
`new_with_roots` and `open_with_roots` take it — both, because `open`
calls `Self::new()` internally and a constructor-only parameter would
leave every open-path test ambient. `install_state_dirs` consults it
too: it runs after construction, so resolving from the environment there
would reopen the hole the constructor closed.
The redirected branch changes WHICH directory is read, never WHETHER the
block runs. Config loading shares one conditional with
`set_init_complete()`, and `tests/m8_2_acceptance.rs:75` documents its
dependence on integration-test construction finishing init-complete.
`child_env()` translates the same value into the environment a spawned
`pmacs` needs. Five variables, not four: `PMACS_STATE_HOME` outranks
`XDG_STATE_HOME`, so a child given only the XDG four still resolves an
inherited state override — invisible on a machine that exports none.
The `src/editor.rs` comment claimed a protection it does not provide and
said nothing about the write above it; both are corrected in place. The
guard is deliberately NOT widened to cover integration tests.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Correct the M-x prompt census: six of the eleven canonical commands
need a second prompt, including describe-command. Make the apropos
substring negative discriminate against fuzzy matching with a concrete
non-contiguous fixture and a no-substring precondition. Update the help
index mutation to the twelfth canonical command, and carry all three
corrections into the active-work ledger.
No review findings at 1cc9d96; these are the two product choices the
framing deliberately left open.
Q#D2 resolves to `help.*` canonical with two forwarders. The family is
eleven commands under one prefix, so typing `help` at M-x surfaces all
of it — which is the discoverability win this arc exists for.
`editor.describe-command` and `editor.describe-setting` stay registered
as forwarders, so nothing in muscle memory or in
`docs/keybindings.md` breaks. Two forwarders are duplication of exactly
the kind §5 complains about; they are accepted as the bounded price of
not breaking documented names, and they carry a deprecation path. What
is not accepted is the split family revision 3 shipped.
Q#D3 resolves to substring. `fuzzy_score` is subsequence-based and
descriptions are long sentences, so a short query's letters almost
always appear in order — fuzzy would match nearly every command and
destroy the precision that makes apropos worth having. Acceptance 4 now
pins the decision rather than the intent: a subsequence that is not a
substring must find nothing.
Counts and pins follow the decision: the family is eleven throughout,
the `_show_help` counting stub expects eleven (the two renamed commands
are in it precisely because they were the pre-existing direct callers),
and the preservation pin now drives the forwarders through the real M-x
path — dropping them after the rename is the failure a user with muscle
memory would hit first.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two factual corrections, both accepted and both verified in the code.
The custom completion source does not control display order. Revision 3
justified sorting the pool by claiming `Custom` candidates appear in
return order; `recompute_candidates` hands the pool straight to
`filter_and_sort`, which ranks by fuzzy score descending and breaks
ties lexically, so the source's order never reaches the user.
The sort is kept, for a reason that is actually true: `filter_and_sort`
applies `.take(CANDIDATE_LIMIT)` to the FILTERED iterator before
sorting, so when more settings match than the limit, pool order decides
which survive truncation. Registration order would make that vary with
an unrelated config edit; sorting makes it reproducible.
Read-only would not mitigate the foreign-`*help*` collision either.
Revision 3 implied it would. A buffer the user created and named
`*help*` carries no intercept of ours, so an intercept on the buffers
we create protects nothing — the renderer still matches on the name and
clears theirs. The missing guarantee is ownership identity: a private
table of buffers this module created, so found-by-name is not adoption.
`listview` carries it as `panels` and dired as its handle table; this
mechanism carries neither. Naming the wrong missing guarantee would
send a later fix at the wrong layer, which is why the correction is
worth its own paragraph rather than a word swap.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two blocking, two major. All four accepted.
The ledger lane still said revision 1 and still carried the two claims
revision 2 refuted. The cause is worth recording: revision 2's ledger
edit was an assert-then-write block whose later assertion failed, so
nothing before it was written either — while the commit message
reported the whole change as done. This is the second time in this
project that shape has silently dropped edits. The lane is rewritten
from scratch and the result verified by re-reading the file rather than
inferred from an exit code.
`names_from` does not exist. Revision 2's completion source called a
helper nobody has written, over `pmacs.config.list()`'s descriptor
tables where `CompletionSource::Custom` consumes a sequence of strings.
Opening the prompt would have raised on an undefined global. The mapper
is now specified, and sorted — `Custom` presents candidates in the
order returned, and registration order is neither stable nor useful.
`*help*` has no read-only intercept. Revision 2 claimed one while
`show_help_text` writes with plain delete/insert, and #205 had already
recorded that this mechanism has not adopted the generated-buffer write
invariant. §3.4 now names the policies that really are shared —
reuse-by-name, wholesale replacement, the `q` binding, and the
foreign-buffer hazard — and notes that the last is precisely what a
read-only intercept would have mitigated and does not.
The naming was underspecified. With no `help.describe-command` in the
table, calling the existing `editor.describe-*` commands
"aliases-by-retention" was wrong on both halves: nothing forwards to
them and there was nothing for them to alias. They are now explicit
exceptions, the resulting split surface is named as a wart, and Q#D2 is
sharpened to the two ways out — forward the two under `help.*`, or keep
the family `editor.*` throughout.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two blocking, two major. All four accepted and verified in the code
before the doc changed.
Completion does not close the free-text hole, and revision 1 said it
did. `resolve_accepted_value` returns the literal typed text whenever
no candidate is selected, so a non-matching typo still reaches
`on_accept` and the existing error path; separately, a fuzzy near-miss
can silently describe a DIFFERENT setting, which is a new failure mode
revision 1 did not name. Completion is reframed as assistance, the
acceptance pins both outcomes, and closed-set acceptance semantics are
named as Rust work rather than smuggled in as a side effect of adding
a source.
`invoke_interactive` is not the M-x path — the exact error #205
corrected one PR earlier. It rotates the interactive-command boundary
and calls the body; it opens no palette. The acceptance now states the
real path once and drives it: dispatch M-x, type the name, assert the
selected candidate BEFORE RET (accept does `session.take()`), accept,
and — for the five commands that take an argument — drive the second
prompt too. A pin that stops after the first RET has tested the
palette, not the command.
The `_show_help` seam is an output sink, not a migration seam.
`src/help.rs` has semantic renderers for command/key/buffer/mode/hook/
view and none for settings, lists or apropos, and the seam takes
already-flattened text, so a later migration still has to change each
command's subject-specific logic. The claim is narrowed to what is true
— one owner for Lua `*help*` writes — and paired with a per-subject
renderer function so the future Rust work is enumerated rather than
discovered.
Ground truth corrected: the missing-command list was eight and omitted
`list-settings` while §3.1 said nine; the site count said ten where
nine additions make eleven; `pmacs.keymap.lookup` does not return
`description` (it passes `cmd = None`); and the predicate sites cited
were `MenuItem` fields, not `Command.predicate`. The predicate
conclusion survives on the correct evidence — `src/help.rs:76` and one
assertion past `#[cfg(test)]`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
`COHERENCE.md` §20 Priority 4, which §5 grades "substrate without
surface — the sharpest instance of §1.1" and calls the best
payoff-per-effort in the document. Nine describe/list commands over
introspection that already exists, picking up the family root `M-x
help` that #205 landed and documented for exactly this.
The stage adds no Rust. `pmacs.describe.*`, `pmacs.keymap.list()`,
`pmacs.command.list()` and `pmacs.config.list()` already return
everything the commands render, and `parse_completion_source` accepts a
Lua function as a `CompletionSource::Custom` — so `describe-setting`'s
free-text prompt, which today turns a typo into a status-line error
while `describe-command` has had completion all along, closes with no
new Rust either.
The consequential decision is a single rendering seam. `src/help.rs`'s
cross-referenced renderer is orphaned and the reachable Lua
`show_help_text` renders less, so nine new commands calling it directly
would turn a two-site migration into a ten-site one. Everything routes
through `pmacs.editor._show_help`, and an acceptance pin replaces that
seam with a counting stub — funnelling asserted, not merely intended.
Records that `Command.predicate` is stored and exposed but evaluated
nowhere, and deliberately does not start evaluating it: that makes
commands stop being invocable, which needs its own decision about what
"unavailable" means at each call site. A preservation pin registers a
raising predicate and asserts the command still runs, so a later stage
has to change that pin knowingly.
Adds no keybindings at all — the help-prefix question is taken once,
for the whole family, by the stage that can weigh it against the
constraint #205 recorded.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two audited rows were false at this PR's head and one of them is this
PR's own doing, so per §25 the correction rides the landing PR rather
than a follow-up.
Row 19 said the journey suite covers "steps 2, 3, 5". This PR adds step
4; #203 and #204 added 9 and 6 before it. It now carries 45 pins over
six steps, and the row names the five §19 scenarios that genuinely
remain unwritten instead of an out-of-date count.
Row 2 said the journey "runs to step 5 ... thin from step 6 on". That
was already stale when #203 and #204 landed and should have ridden
them. With 1b complete the journey runs to step 10, and the thin end is
now steps 1, 11 and 12 — install, background-work visibility, and
session restore.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Review round 2 on #205, one finding, accepted. #204 is this PR's base,
so three places still describing it as open were simply false.
- `COHERENCE.md` §2's step-6 row: "(PR open) ends the silence" ->
"(#204) ended the silence", and the "flips only on merge" clause is
replaced by the reason the row is still Partial at all — a server
that starts and then crashes is unsurfaced, which that landing did
not touch.
- `docs/agent-handoff.md`: the 1b-2 bullet says LANDED (#204), with the
same substituted reason.
- `docs/active-work.md`: 1b-2's per-stage block is removed rather than
relabelled, per rule 4 — it has merged and its durable facts are in
the handoff, which is the precondition for removal.
That last one exposed a structural problem the merge had created: 1b-2's
old lane body had come in *underneath* the unified journey header, so
the file carried two journey sections and the first one's text
described the second's predecessor. There is now one arc lane with
1b-3 nested under it as the only open stage.
Also corrects the reap-ledger lane header, which still read
"IMPLEMENTED, PR OPEN" after #202 merged. Same class of staleness,
noticed while editing the same file.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Review round 1 on #205, two findings, both accepted.
The greeting was written straight into the registry without calling
`notify_buffer_edit`. The window's `TextView` had been indexed while
`*scratch*` was empty, and newlines are zero-width to a painter working
from a stale line index — so the first TUI frame collapsed the whole
three-line greeting onto row 0. Every buffer-text assertion passed
because the buffer content was correct; only the rendering was wrong.
The edit is now captured, the registry borrow released, and the core
notified.
The pin that would have caught it paints a real frame and asserts the
second line occupies its own row AND that row 0 does not contain it —
both directions, because a one-direction check passes when everything
collapses upward. Bitten by dropping the notify call: row 1 comes back
empty with row 0 holding the lot, and it is the only pin that fails.
Second: the project docs still described the arc as it was two PRs ago.
`COHERENCE.md` §20 called 1b-2 in flight and the welcome buffer
unstarted; its arc list said 1b-3 remained; and the ledger's journey
lane header still read "1b-2 PR OPEN" while the 1b-3 block carried a
mangled "Framing only; no code" line left by an earlier edit. All now
describe the PR-head state per §25.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
The journey suite conflicted additively — step 4 from this lane, step 6
from #204 — and both are kept: 44 pins now cover steps 2, 3, 4, 5, 6
and 9.
Per §25 the audited claims this stage falsifies are updated on the
landing PR rather than deferred: the scorecard's row 18 and §18's
ground truth both read "Missing" / "missing entirely", and a welcome
buffer plus a reachable cheat sheet makes both false. They move to
Partial. §2's step-4 row stays Partial, because `C-h` still deletes a
word and there is no tutorial.
§18's ground truth now records WHY `C-h` stays as it is, so the
help-prefix question reaches the discovery arc as a stated trade rather
than an oversight: non-kitty terminals cannot disambiguate
Ctrl+Backspace from Ctrl+H, so rebinding it would break Ctrl+Backspace
on every legacy terminal.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Implements `docs/journey-stage1b3-welcome-framing.md` (approved at
revision 4, after three review rounds). The last of the 1b split.
`COHERENCE.md` §18 graded onboarding "missing entirely": no welcome, no
cheat sheet reachable from inside the editor, and `M-x` — the only door
in — discoverable only by already knowing about it. A fresh `pmacs` now
greets an untouched `*scratch*` with three lines naming `M-x` and four
real bindings, and `M-x help` renders a cheat sheet.
The startup seam is the substance. No constructor is the right hook:
`EditorState::open` calls `new` before resolving its target, the daemon
constructs one too, `init.lua` runs inside `new`, and desktop restore
happens later still. So `run()`'s terminal-free prefix is extracted into
`prepare_startup`, which `run` delegates to, and the greeting happens
there — after config, after attach dispatch resolves to local, and
after desktop restore. Extracting it is also what makes the wiring
testable: with the greeting called by hand from tests instead, deleting
the production call would leave every assertion green while shipping no
welcome.
Lua owns what is said, Rust owns when and where. `pmacs.welcome.entries`
is a structured list that both renders the text and drives the binding
checks — scraping the rendered prose would be ambiguous, since `C-c c`
is two chords and nothing in the text marks the boundary.
The greeting is deliberately NOT written through
`set_generated_contents`: that would lift read-only, discard history and
mark the buffer generated, all wrong for the buffer journey step 5
requires the user to type into immediately. It is left unmodified so it
does not look like unsaved work.
`M-x help` renders through `editor.describe-command`'s existing `*help*`
mechanism via a new `pmacs.editor._show_help` seam, rather than growing
a second help surface.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two findings, both accepted.
The pinned API was crate-private while the pin was external.
`tests/journey_acceptance.rs` is a separate integration crate and
cannot call a `pub(crate)` function or match a `pub(crate)` enum, so
revision 3's acceptance 1 could not have compiled. `prepare_startup`
and `Startup` are now `pub`, which is consistent rather than expedient:
`run`, `EditorState::new`, `EditorState::open`, `install_state_dirs`
and `restore_desktop_if_armed` are already public, so the startup
sequence is public surface and this was the piece missing from it. The
alternative — keep it private and move the pin into `src/editor.rs`'s
unit tests — was rejected because §19 wants the journey row in the
journey suite.
The isolation that pin needs is now stated rather than left implicit.
`prepare_startup` deliberately calls `install_state_dirs`, which
resolves `PMACS_STATE_HOME` and XDG roots that tests cannot override
(`set_var` is unsafe and forbidden), so the pin inherits the standing
five-variable ambient-root requirement, asserts buffer content only,
and must assert that desktop restore was unarmed — a developer whose
real `init.lua` calls `desktop_mode(true)` would otherwise get a
restored scratch buffer and a silently different result.
The M-x acceptance still left its key assertion as an "or", and half of
it was impossible: `Minibuffer::accept` does `session.take()` and
resolves against the selected candidate, so after RET neither the
session nor the typed contents survive to be asserted. The framing now
specifies one observable, available before RET:
`pmacs.minibuffer.selected()` must equal exactly "help", then accept.
If the completion source selected something else the pin fails there,
naming what was actually selected, instead of passing on a help buffer
some other command produced.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two acceptance holes and one doc correction, all accepted.
The real startup wiring was still unpinned, and revision 2 knew it: it
named the gap and then accepted it as residual, which is worse than
missing it. Deleting the sole `run()` call to `finalize_local_launch`
would have left every proposed pin green while shipping no welcome —
pin 1 called the seam by hand and pin 10 only proved constructors were
blank. That is the shape of a guard with no production caller passing
every direct-call test.
The fix is extraction, not disclaimer. Everything in `run()` from
`install_panic_hook` through the end of the attach-dispatch match is
terminal-free; `Frontend::new()` is where takeover begins. That prefix
becomes `prepare_startup`, which `run()` delegates to and which the
welcome pin now drives. Deleting the finalize call inside it turns the
pin red. What stays outside a test is `Frontend::new()` and the event
loop, which is where terminal takeover genuinely lives.
Acceptance 4 was not the M-x path. `pmacs.command.invoke` is the
programmatic API; M-x is `editor.execute-command`, which opens a
minibuffer with the `commands` completion source and calls
`invoke_interactive` only on accept. The pin now dispatches the chord,
enters the name, and accepts — and names the hazard that makes that
non-trivial: a selected candidate shadows typed text, so the pin has to
assert which command ran rather than trusting that some help buffer
appeared. dired refused a completion source on its own prompt for
exactly this reason.
Also corrects the #204 references: revision 2's history said it had
landed while the framing footer and ledger still called it open.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Four findings, all accepted and verified in the tree first. The three
open questions are answered and folded into the design: three lines,
name `C-c c` and `C-c t` verified from structured entries, and the
command is `help`.
The startup seam was wrong, and every acceptance criterion rested on
it. `EditorState::new()` is not the no-argument entry point:
`EditorState::open` calls it before resolving the target, the daemon
constructs one too, user config runs inside it, and desktop restore
happens much later inside `run()`'s `RunLocal` arm. Greeting from
`new()` would greet a daemon, greet before a file argument replaced the
buffer, and precede anything config or a restored session put in
`*scratch*`. The stage now adds a launch-finalization seam called right
after `restore_desktop_if_armed`, using the `had_file` signal already
threaded to that point. Its untestable part — that `run()` calls it —
is stated rather than papered over, and bracketed by pins proving the
seam works and that no constructor greets on its own.
The step-2 pin amendment is withdrawn. Revision 1 analysed a
status-line welcome and then chose `*scratch*` but kept the amendment,
which was an internal contradiction. The status stays empty so the pin
stays true, and "no error text" has no defined predicate over an
unstructured status string — replacing an exact check with a fuzzy one
would weaken the ratchet to buy nothing.
The claim that this stage carried no §25 obligation was false. The
scorecard's row 18 and §18's ground truth both read Missing, and a
landed welcome plus reachable cheat sheet falsifies both: they move to
Partial on merge while §2's step-4 row stays Partial. A stage can be
too small to flip its journey step and still falsify a "missing
entirely" grade.
Acceptance 2 could not have been implemented as written. Scraping key
sequences out of prose is ambiguous — `M-x help` mixes a chord with a
command name, and `C-c c` is two chords whose boundary the text does
not mark. One structured entry list now both renders the text and
drives the `pmacs.keymap.lookup` checks, and `M-x help` is exercised
through the real palette path.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
The last of the 1b split. Journey step 4 and `COHERENCE.md` §18: a
fresh `pmacs` greets the user with an empty buffer, an empty status
line, and no indication that `M-x` exists — the sole discovery
affordance in the product is knowing to press it.
Three findings shape the design:
- The existing step-2 ratchet pin collides with any welcome. It asserts
`status.is_empty()` while its own message says "reports no error" —
the same predicate only while nothing writes a non-error status at
startup. The framing corrects the assertion to its message's claim
and names that as the one existing assertion the stage changes,
rather than burying it in a diff.
- `C-h` is not free. It is bound to word-delete because non-kitty
terminals cannot disambiguate Ctrl+Backspace from Ctrl+H — both
produce byte 0x08 — so rebinding it to a help prefix would break
Ctrl+Backspace on every legacy terminal. §2's step-4 row calls it an
oversight; it is a deliberate trade with a stated rationale. The
help-prefix decision is deferred to the discovery arc with the
constraint recorded so it is inherited rather than rediscovered.
- A `*help*` buffer mechanism already exists over `src/help.rs`, so the
welcome can point at something real. Its two gaps are recorded rather
than inherited silently: it writes with delete/insert instead of
`set_generated_contents`, and it is found by name.
The welcome deliberately does NOT use `set_generated_contents`: that
lifts read-only, discards history and marks the buffer generated, all
wrong for the buffer step 5 requires the user to type into immediately.
Step 4 stays Partial — the row names a welcome, a cheat sheet and
`C-h`, and this closes the first plus a minimal second — so this is the
first 1b stage with no landed-evidence obligation on merge.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Stage 1b-1 landed as #203, so the four places it deliberately left
saying "in flight" are flipped here rather than in a standalone docs
PR: this branch already touches all three files, and a separate PR
would re-conflict on every merge.
- `COHERENCE.md` §2's step-9 row: Partial -> **Works**.
- §2's keybinding-inversion paragraph: all three examples answered. The
quote itself is deliberately unchanged — it names a bias, and three
fixes do not retire a bias.
- §20 Priority 1 and the arc list: 1b-1 landed, 1b-2 in flight, 1b-3
remaining.
- `docs/agent-handoff.md` §1: IMPLEMENTED -> LANDED.
Conflicts were additive on both sides and are resolved keeping both:
the journey suite carries step 9 and step 6 (34 pins), and §24 keeps
both drift entries — the `ProjectKind::Cargo` naming error and §1.2's
wrong frequency note.
The two journey lanes are unified into one arc lane rather than one
being deleted. Rule 4 removes a lane when its ARC is done, and the
journey arc is not: 1b-2 is in flight and 1b-3 is unframed. Stage 1a
and 1b-1 are summarized there with their facts in the handoff, which is
rule 4's precondition satisfied rather than deferred.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Implements `docs/journey-stage1b2-lsp-guidance-framing.md` (approved at
revision 4, after three review rounds). Lua, tests and docs; no Rust
change and no protocol change.
`COHERENCE.md` §1.2's canonical silence: a preconfigured server that is
not installed failed with no status message, no record and no modeline
marker, while tree-sitter highlighting kept working and masked it. Now
the status line names the command, the language and the errno; the
modeline reads `LSP:!` instead of nothing; and `M-x lsp.status` renders
a durable `*lsp*` panel.
Half of this was already built. `status_buffer_text()` and
`last_error()` have existed since M4.8, exposed to Lua and tested, with
no production caller and no buffer to render into — several doc
comments already referred to "the `*lsp*` buffer" as though it existed.
The reporting shape was likewise already adopted twice inside
`lsp.lua`; the canonical case was silent because nobody had converted
it.
Three tables with three lifetimes, because one cannot do the job:
`reported` is never cleared and includes the command, so repointing at
another missing executable reports again; `failures` is cleared by a
successful spawn so the panel goes quiet on recovery; and a
buffer-keyed projection feeds the modeline, because that provider runs
for every window on every paint and deriving an affinity key inside it
would invoke root resolvers during painting.
The memo is on the report, not the failure: the spawn is still
attempted on every file open, so installing the binary mid-session
recovers with nothing to invalidate.
Adds `tests/lsp_spawn_guidance_acceptance.rs` (16 pins) and a step-6
row to the journey ratchet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
One blocking lifecycle gap, accepted. The registry's dispatch order was
read before specifying the fix rather than assumed.
`failed_attachments` is keyed by `tostring(buf)` and revision 3 never
said who deletes an entry, so killing a failed buffer leaked its
projection for the session — and that also made revision 3's sweep
bound ("at most the number of open buffers") false, since the table
could exceed the number of buffers that exist.
Nothing existing would have cleaned it incidentally. The LSP resource
reconciliation finds its work through `attachments_under`, which
iterates `attachments`, and a failed buffer has no attachment by
construction — that is the whole reason the projection exists. The gap
needed its own registration.
Revision 4 specifies:
- `pmacs.buffer.on_removed` registered once per projection, never per
failed attempt, since `attach_buffer` is reachable more than once for
the same buffer and per-attempt registration would stack callbacks —
the same unbounded-registrar shape with the leak moved rather than
fixed.
- The handle released on the success sweep, where the buffer is still
alive, but not from inside the removal callback: dispatch does
`callbacks.take(id)` and then iterates a local vector, so the entry is
already gone.
- Rename and delete CLEAR the projection rather than re-keying it.
The projection asserts "this buffer's server failed for affinity K",
and after a rename that is no longer known to hold — the new path may
be in a different project or none. Re-keying would assert a failure at
a location where none was observed, which is the error shape this arc
has been correcting throughout.
- The sweep bound now follows from the cleanup instead of sitting beside
it as an independent claim.
Adds acceptance 14-16 for kill, rename and delete, each asserting the
chosen behaviour rather than merely the absence of the forbidden one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two blocking, two cleanups. All four accepted, and both blockers
verified by running Lua rather than by reading it.
Recovery was inconsistent across buffers sharing an affinity. Revision
2 cleared `failures[K]` on a successful spawn but cleared only the
succeeding buffer's projection, so: buffer A fails, buffer B succeeds
for the same key, `M-x lsp.status` reports nothing wrong, and A's
modeline still reads `LSP:!`. Revision 2's claim that the two tables
are "written and cleared at the same moment" was false for exactly the
cross-buffer case, which is the normal case for a project with more
than one file. Each projection now carries its affinity key and a
success sweeps every projection holding it. The new pin asserts on A,
not B — a version checking B passes on the broken implementation.
The markerless key had no Lua representation. `key_uri` is deliberately
nil and `t[nil] = v` raises "table index is nil" — confirmed under both
LuaJIT and Lua 5.4 — so the central markerless criterion was literally
unimplementable as written, and leaving it to implementation would have
produced two ad-hoc encodings for the two tables. The framing now
prescribes one key function used by both, with a `u`/`n` discriminator
that cannot collide with any URI and a NUL separator (Lua strings are
8-bit clean, checked).
Acceptance 10 could not have observed what it claimed: making the
command resolvable changes no state by itself, since `failures` is
cleared by a successful spawn. The pin now reattaches before pressing
`g`, and says why that step is load-bearing.
Also corrects the ledger heading, which still said revision 1.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Review round 1 on #203, two blocking findings, both accepted.
The compile-directory assertions used the suite's lexical `canon()`,
but `pmacs.project.detect` canonicalizes before walking
(`canonicalize_or_passthrough`, `src/project.rs:509-511`), so the
compile cwd is filesystem-canonical. On macOS `/var` is a symlink to
`/private/var` and the two spellings disagree — both macOS legs failed
while Ubuntu, where `/tmp` is not a symlink, stayed green.
Fixed with a `detected_root()` expectation, and pinned by a fixture
that launches through an explicit **symlink** so lexical and canonical
paths disagree on every platform. That matters more than the fix: the
original bite ran only on Linux, where nothing could make the two
differ, so no amount of local mutation testing would have caught this.
The new pin is the only one that goes red when the lexical expectation
is restored.
Second: `COHERENCE.md` §2's step-9 row was flipped to **Works** and the
handoff said Stage 1b-1 was **LANDED**, while this PR is open. §25 is
explicit that grades change only with landed evidence, never
aspirationally. Both now describe the real state — the row stays
Partial and names #203 as the open PR that closes it, §20 and the arc
list say "in flight", and the handoff says IMPLEMENTED with the PR
number.
The flip is not dropped, it is owned: the active-work lane records the
four places to change on merge, because an unowned doc flip is exactly
how this ledger's drift starts.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Two blocking, three major, one minor. All six accepted and verified in
the code before the doc changed.
The affinity key was misstated. `ensure_server` sets `key_uri` only
when the root came from config or a marker walk, so a markerless file
keys on nil and loose files across unrelated directories deliberately
share one server per language. Revision 1's "(root, language)" would
have split what the runtime shares and re-reported one failure once per
directory. The memo now uses the real key and the stage changes no
reuse behaviour.
Dedupe and current-failure state were conflated into one record, and
revision 1 said nothing about recovery. One record cannot do both jobs:
keep it and `*lsp*` shows a failure the user has already fixed; clear
it and the message returns on the next file open. They are now two
records with different lifetimes, the reported identity includes the
command so repointing config at a different missing executable reports
again, and recovery is pinned in both surfaces.
The modeline provider is a pure per-buffer projection by design — it
runs for every window on every paint. Revision 1's "read the failure
table" would have made it derive an affinity key, invoking user root
resolvers and project detection inside painting. The failure is now
projected per buffer at attach time and the segment stays one map
lookup, with a preservation pin that counts resolver invocations.
"Adopt listview's idiom" is replaced by requiring `pmacs.listview.open`
and naming what it guarantees, including `on_refresh` — without which
`listview.refresh` early-returns and `g` is a bound key that silently
does nothing.
The acceptance had no journey ratchet row despite the stage making step
6 real; `tests/journey_acceptance.rs` states that steps 6-12 join as
later stages make them real, and 1b-1 added step 9 the same way. The
end-to-end row is now acceptance 1 and the M4 pins stay beneath it.
Also refreshes the ledger's canonical-base anchor and recovery floor
from `7586905` to `fbcf235`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
`COHERENCE.md` §1.2's canonical silence, and journey step 6: a
preconfigured-but-missing language server fails with no status message,
no record, and no modeline marker, while tree-sitter highlighting keeps
working and masks it.
Three findings shape the design, all verified in the tree:
- The reporting pattern is already adopted twice inside `lsp.lua`
itself — root-resolver failures and subscriber failures both report
through `pmacs.editor.set_status` with the `pmacs.error` arm riding
along. The canonical spawn failure at `:658-674` was simply never
converted, so this stage finishes an adoption rather than starting
one.
- Half the stage is already built and unwired.
`LspManager::status_buffer_text()` renders "the `*lsp*` status
buffer", `last_error(sid)` exists, and both are exposed to Lua and
tested — with no production caller, no `*lsp*` buffer and no command.
Several doc comments already refer to that buffer as though it
exists.
- COHERENCE's frequency note is wrong, and the correction decides the
hardest question. It records the failure as firing once per project
root; `LspManager::spawn` returns early *before* both
`status_tracker.ensure` and `clients.insert`, so a failed spawn
leaves no record, the affinity loop cannot see it, and the real rate
is once per file open. Hence the rule the stage adopts: memoize the
report, not the failure — the spawn is still retried, so installing
the binary mid-session recovers with nothing to invalidate.
Records one limitation rather than hiding it: `status_buffer_text`
renders from `self.clients`, which a failed spawn never enters, so the
durable surface cannot yet show the failure natively. The record stays
in Lua for this stage.
Also logs four stale `COHERENCE.md` §1.2 citations for correction when
the stage lands.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv428Fth9LRtffwJSsqH7T
Levi Neuwirth