docs(coherence): workers are reachable; completion is not a fixed vocabulary

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
This commit is contained in:
Levi Neuwirth 2026-07-31 20:05:06 -04:00
parent 6ca757ae99
commit bc2bbe0d42
1 changed files with 15 additions and 8 deletions

View File

@ -98,7 +98,7 @@ remain open to them.
| 2 | Golden product journey | **Runs to step 10** | `pmacs .` opens the directory (1a); the interface introduces itself (1b-3); a missing language server says so (1b-2, #204); a build is bound and prefilled (1b-1, #203). Steps 1, 11 and 12 remain the thin end | | 2 | Golden product journey | **Runs to step 10** | `pmacs .` opens the directory (1a); the interface introduces itself (1b-3); a missing language server says so (1b-2, #204); a build is bound and prefilled (1b-1, #203). Steps 1, 11 and 12 remain the thin end |
| 3 | Zero-configuration state | **Partial** | Defaults genuinely strong; missing-tool failure is silent, not graceful | | 3 | Zero-configuration state | **Partial** | Defaults genuinely strong; missing-tool failure is silent, not graceful |
| 4 | Progressive disclosure | **Inverted** | The advanced level is real; the beginner level is the missing one | | 4 | Progressive disclosure | **Inverted** | The advanced level is real; the beginner level is the missing one |
| 5 | Unified discoverability | **Partial** | Discovery Stage 1: eleven `help.*` commands (describe key/mode/hook/buffer/command/setting, where-is, list commands/keybindings/settings, apropos) over the existing registries, indexed by `M-x help`. Commands, keys, modes, hooks and settings are now reachable; **packages and workers are not** (§13, §9), `Command` still has no title/category/flags, M-x rows are still bare names, and the Rust help layer is still orphaned | | 5 | Unified discoverability | **Partial** | Discovery Stage 1: eleven `help.*` commands (describe key/mode/hook/buffer/command/setting, where-is, list commands/keybindings/settings, apropos) over the existing registries, indexed by `M-x help`. Commands, keys, modes, hooks and settings are now reachable, and `*workers*` already was (`M-x editor.list-workers`); **packages have no comparable surface** (§13), and workers still lack owner/purpose/hierarchy and any indicator (§9). `Command` still has no title/category/flags, M-x rows are still bare names, and the Rust help layer is still orphaned |
| 6 | Interaction islands | **Weak, and growing** | Six hardcoded key-interception shadows; no transient-keymap mechanism exists | | 6 | Interaction islands | **Weak, and growing** | Six hardcoded key-interception shadows; no transient-keymap mechanism exists |
| 7 | First-class workspaces | **Missing (conventions only)** | Marker walk + four independent consumers; no workspace object | | 7 | First-class workspaces | **Missing (conventions only)** | Marker walk + four independent consumers; no workspace object |
| 8 | Execution locations | **Missing (architecture ready)** | SSH attach works; "location" is not a value anywhere | | 8 | Execution locations | **Missing (architecture ready)** | SSH attach works; "location" is not a value anywhere |
@ -524,8 +524,11 @@ orchestrate workers, replace interaction models):
- inspect ✓ (SourceLocation on everything; no jump-to-source command - inspect ✓ (SourceLocation on everything; no jump-to-source command
though) · redefine live ✓ (`unregister` + `define`) · packages ✓ though) · redefine live ✓ (`unregister` + `define`) · packages ✓
(authoring is real, §13) · new views ✓ (listview is Lua-usable) · (authoring is real, §13) · new views ✓ (listview is Lua-usable) ·
providers ✓ (statusline; completion/minibuffer sources are a fixed providers ✓ (statusline; and minibuffer completion is **not** a fixed
Rust vocabulary) · keymap layers ✗ (§6 — the mechanism does not Rust vocabulary — `parse_completion_source` accepts a Lua function as
`CompletionSource::Custom`, which is how Discovery Stage 1 gave
`help.describe-setting` completion with no Rust at all) · keymap
layers ✗ (§6 — the mechanism does not
exist) · workspace policy ✗ · orchestrate workers △ exist) · workspace policy ✗ · orchestrate workers △
(`pmacs.workers.register` funnels into builtin dispatchers, §9) · (`pmacs.workers.register` funnels into builtin dispatchers, §9) ·
replace interaction models ✗ (the shadows, §6). replace interaction models ✗ (the shadows, §6).
@ -572,7 +575,9 @@ Lua function through `CompletionSource::Custom`.
is still never evaluated; M-x rows are still bare name strings; the Rust is still never evaluated; M-x rows are still bare name strings; the Rust
help layer is still orphaned (Stage 1 funnels every command through one help layer is still orphaned (Stage 1 funnels every command through one
Lua seam so the eventual migration is enumerated per subject rather than Lua seam so the eventual migration is enumerated per subject rather than
per call site); packages and workers have no discovery surface; settings per call site); **packages** have no discovery surface, and workers,
though `M-x editor.list-workers` opens `*workers*`, still lack the
ownership model and the activity indicator §9 asks for; settings
value provenance is still absent; and there is still no help prefix key. value provenance is still absent; and there is still no help prefix key.
*The original audit grade, for reference:* **substrate without surface — *The original audit grade, for reference:* **substrate without surface —
@ -634,10 +639,12 @@ the sharpest instance of §1.1.**
with `editor.describe-command` / `editor.describe-setting` retained as with `editor.describe-command` / `editor.describe-setting` retained as
forwarders. `help.describe-setting` **now completes**, through a Lua forwarders. `help.describe-setting` **now completes**, through a Lua
function passed as `CompletionSource::Custom`. function passed as `CompletionSource::Custom`.
**What remains missing here:** a discovery surface for **packages and **What remains missing here:** a discovery surface for **packages**
workers** (§13, §9), and **no key reaches any of it** — the family is (§13) — `*workers*` already has one, reachable by
`M-x`-only by design until the help-prefix decision is taken (see the `M-x editor.list-workers`, though §9's ownership model and activity
prefix bullet below). indicator are still absent — and **no key reaches any of this**: the
family is `M-x`-only by design until the help-prefix decision is taken
(see the prefix bullet below).
*Completion is assistance, not validation:* `resolve_accepted_value` *Completion is assistance, not validation:* `resolve_accepted_value`
returns the literal typed text when no candidate is selected, so a returns the literal typed text when no candidate is selected, so a
typo still reaches the handler; refusing a non-candidate is unbuilt typo still reaches the handler; refusing a non-candidate is unbuilt