pi-lens 4.2.0 → 4.3.0

package/docs/engineering-principles.md

@@ -0,0 +1,202 @@
+# Engineering principles
+
+Source of truth: https://github.com/apmantza/engineering-principles (private), file PRINCIPLES.md. Verbatim copy; the repo wins on drift. Project-level AGENTS.md / CLAUDE.md add the project catalog and win on conflict.
+
+Project-neutral rules distilled from the pi-lens contracts, playbooks and merge
+train (2026-08 to 2026-09). Each rule is imperative and carries the reason it
+exists. Projects keep their own catalog of defect shapes, registries, and
+commands; this file is what stays the same across them.
+
+Read order for any agent starting work: this file, then the project's own
+AGENTS.md or CLAUDE.md, then the role contract for the task (fixer, reviewer,
+investigator). Project instructions win on conflict.
+
+## 1. Building
+
+**Premise first.** Reproduce a reported defect through the production call
+path before writing a fix. Drive the real dispatcher, loader, or builder; never
+a hand-shaped input that exists only to hit the bug. If it does not reproduce,
+the deliverable is the recorded refutation (which invariant covers it, with the
+probe) and, where cheap, an assertion that pins it, not machinery for a
+collision that cannot occur.
+
+**Climb the minimalism ladder before writing code.** Be lazy about the
+solution, never about reading. Trace the real flow, then ask in order: does this
+need to exist at all; does the codebase already do it (reuse the seam); does the
+platform or stdlib do it; does an installed dependency do it; is it one line.
+Only then write the minimum that works. Validation, error handling, security and
+bounded observability are never skipped in the name of minimalism.
+
+**Net-count rule for shared helpers.** A change that introduces a shared helper
+while same-shape siblings exist deletes at least one sibling in the same change.
+The helper count never goes up. Deferring the fold is allowed only when the
+brief names every sibling, states why folding them together is unsafe, and
+links the follow-up. This binds whoever writes the brief as much as whoever
+implements it.
+
+**A fix's pattern matters more than its instance.** When a root cause is
+understood, name the defect shape and sweep the whole tree for other members
+before closing. Fix the contained siblings in the same change; file the rest
+with the member list; record what was grepped and what was found clean. Seeing
+without recording is indistinguishable from not looking. Every sweep ends with
+a consolidation verdict: fold onto one seam (name it) or stay distributed (say
+why). The deciding test is deletion: would removing the shared module
+concentrate complexity back into callers (fold) or merely relocate the same
+lines (stay)?
+
+**Design shared state once, at design time.** Before adding a second writer to
+any shared record (a cache entry, a latch, a ledger, a mirror, a counter) decide
+whether every actor needs one canonical object or each can own its record and
+merge at read. Refresh mirrors inside the guard that published the durable
+state. A resource bounded along one axis and unbounded along another is a leak.
+
+**Every new failure path gets bounded observability.** One record per distinct
+event per session, never one per occurrence in a loop; repeated degradations go
+through a once-only or counted record. A discriminator nothing can observe is a
+vacuous guard and does not ship.
+
+**Blast radius as a call-tree diff.** For any change to a shared seam, list the
+changed symbol, its callers above, its callees below, with plus and minus on the
+lines that moved. Prose keeps missing callers; a tree the reviewer can grep does
+not. Name every strict consumer of a durable record whose shape changes, and
+prove old records still parse.
+
+**Deletion sweeps dependents first.** Before removing a guard, a defensive
+branch, or a field, grep every caller and every test double. Correct-looking
+deletion asks have redded CI because dozens of doubles depended on the removed
+line.
+
+**Identity and lifecycle rules are stated before the first edit.** When a change
+touches session, ownership, or resume semantics, write the invariants and the
+writers-by-axis table (which actor, which identity, which timing) first, and
+choose the simplest identity rule that satisfies every cell. Adding a second
+identity clause "to be safe" produced two consecutive regressions on one seam.
+
+## 2. Testing
+
+**Red first, and keep the transcript.** Every regression test is shown failing
+on the pre-fix code with the failure that matches the defect, and the output is
+pasted into the change description. A test that passes pre-fix is a finding.
+
+**Tests ship with the code, in the same commit.** A change and the tests that
+prove it land together; a test-only follow-up round means the first commit
+shipped unproven. The failure list is written before the first edit, and the
+mutation table is that list with transcripts, never a list invented after the
+code.
+
+**Keep fixture corpora from every supported version.** Every durable record,
+config file, cache entry or wire message the project still reads has a fixture
+from each version that produced it, and the parser is run over all of them. An
+old-record parse proof is a fixture in the corpus, not a sentence in a PR body.
+
+**Mutation output is quoted, not ticked.** For every new guard, branch, filter,
+cap or fallback: neuter it in the built output, run the suite that should catch
+it, and paste the red. A checked box with no transcript is treated as false. A
+mutation that fails to compile proves nothing about the test; redo it as a
+compile-valid change. A guard that cannot be made to red does not need to exist.
+
+**Tautological tests are harmful.** A test observes behaviour through the real
+seam and asserts an independent effect. It never restates the implementation,
+never asserts a value its own setup supplied, and never swaps a real in-process
+store, sink, coordinator or registry for a fake. Mocks belong only at true
+process or host boundaries.
+
+**Every guard test names the recurrence it prevents** in its own comment: the
+shipped defect or the concrete drift it would catch. A guard with no named
+recurrence is speculative and does not ship.
+
+**Detectors match code, not prose.** Any test-side scan that regexes source
+must run over comment-and-string-blanked text, with a per-needle policy for the
+rare needle whose evidence is a string literal. A comment quoting the needle
+must never satisfy a requirement or an exemption. The self-excuse direction
+(prose makes a guard pass) is the dangerous one; the false-positive direction
+reds loudly and is lower priority.
+
+**Ratchets and baselines are admissions, not loosening.** A new real spawn,
+timer, or wall-clock assertion is admitted with a header stating why the real
+thing is required, a registry entry, a baseline row and lane membership. A
+mocked seam is not a real spawn and gets an exemption with its reason, never an
+admission.
+
+**Run targeted files while iterating; the full suite runs once.** Build before
+testing when tests execute compiled output, and rebuild between mutations. A red
+is environmental only when the same test is red on the base branch in the same
+environment; say so with the evidence.
+
+**Probe hygiene.** Every probe, test run and child process pins its home,
+data and log directories under the working tree. Nothing an agent runs writes
+to the maintainer's real home.
+
+## 3. Reviewing and delegating
+
+**Every change is reviewed adversarially, including small and self-authored
+ones.** Depth follows what the diff touches, never the priority label: runtime,
+tooling, CI and manifests get full adversarial review; test-only diffs that are
+not ratchets get one scoped pass; docs and renames get an orchestrator read plus
+CI on the exact head.
+
+**A finding is real when a probe proves it; a fix is real when the same probe
+passes.** Reviewers attack with throwaway probes and quote the output. They
+reproduce the red run themselves (keep the tests, revert the source), mutate
+every new guard, check merge state first (a conflicted change silently skips
+its gates), and read CI on the exact head. Reviewer prescriptions are
+hypotheses: the verify round attacks them as a rival's.
+
+**The same reviewer verifies each fix round.** Continuity is the reviewer's
+judgment and probe set; the checkout under it is rebuilt fresh at the new head
+every round. When a review or verify names a new defect on the same seam, the
+next fix opens with the state-space table written before any edit, on the
+strongest available model. Never send a third patch-only round on one seam.
+
+**Round routing.** A round that only applies a prescribed remedy with quoted
+reds merges on green. A round that adds mechanism, touches lifecycle or session
+semantics, or rewrites a guard gets a fresh verify. Classify by the worst
+finding, not the count. Intent-free findings (a body sentence, a comment, a
+literal, a changelog line) are applied by the orchestrator as trailing commits
+and never re-verified; anything that changes what code means goes through a
+round, however small it looks.
+
+**Merge gate.** Merge only when the verdict is merge-ready, every gating check
+genuinely executed and passed on the exact head, and every failing check was
+read and judged. Absent is not green. Read exit codes directly, never after a
+pipe. After a merge, check the other open changes for conflicts and prune only
+the merged lane's worktrees.
+
+**Delegation contract.** Every delegation names the role, the absolute worktree,
+branch, base, acceptance criteria, non-goals, sibling files to avoid, and Git
+authority. A role never grants Git authority by itself. A worker without it
+leaves changes uncommitted and hands off through a PR body and a commit message
+at the worktree root; the orchestrator commits. Implementation and review are
+never mixed in one delegation. Scope changes are mirrored on the tracking issue
+before they are sent, so the worker can verify them.
+
+**No manufactured work.** An idle worker is cheaper than fake work. Delegate
+when a real producer, consumer, probe or diagnosis is unresolved, never to keep
+a pool busy. The same applies to status artifacts: they exist for coordination
+someone consumes.
+
+## 4. Honesty and records
+
+**Closes versus refs follows delivery, not optimism.** Close only when every
+acceptance criterion is met; otherwise reference the issue and post the named
+remainder before anything merges. After merging a referencing change, verify the
+issue carries that comment or close it crediting the change.
+
+**Report what ran, what was skipped, and what CI must still confirm.** A
+skipped suite, an environment-blocked file, a mutation that could not be
+executed: each is named, never implied green.
+
+**Contracts move in the same session.** When a review or an incident reveals a
+defect class rather than an instance, the rule enters the project's catalog with
+the reference and a one-line screen before the next dispatch. Two rounds on the
+same shape in one session is the trigger.
+
+**Detection retrospective on every merged bug fix.** Record which verification
+layer caught it and which layer should have caught it earlier and at what cost.
+If that layer does not exist, file it with the bug as its named recurrence.
+
+**Keep a lane ledger.** One row per lane with a fixed state vocabulary (not
+started, fixing rN, waiting on CI, waiting on review, waiting on verify,
+blocked, ready to merge, merged, needs user decision, held). It is what survives
+a context reset, and it lets a different orchestrator build the status table
+without reading transcripts.

package/docs/environment-variables.md

@@ -30,13 +30,36 @@ config JSON) and how they interact, see [Settings](settings.md).
 
 ### `PI_LENS_CONFIG_PATH`
 
-Override the path of the global config file. **Default:** `~/.pi-lens/config.json`
-(`%USERPROFILE%\.pi-lens\config.json` on Windows). When set, the value is
-resolved to an absolute path and used verbatim.
+Override the path of the global config file. **Default:** the resolution order
+below. When set, the value is resolved to an absolute path and used verbatim;
+it wins over every other location. See the [winning-location table](configuration.md#global-config-location).
 
 **When to set it:** keeping the config under version control or a dotfiles
 manager at a non-default location, or pointing CI at a fixture config.
 
+### `PI_CODING_AGENT_DIR`
+
+Host-relative global config location, honored by pi-lens when pi sets it.
+**Resolved path:** `$PI_CODING_AGENT_DIR/extensions/pi-lens.json`. The tier is
+opt-in by creation: the file is read when it EXISTS and the legacy default
+does not. Absent, nothing changes.
+
+The full resolution order for the global config file, highest first:
+
+1. `PI_LENS_CONFIG_PATH` — an explicit file override, used verbatim.
+2. `~/.pi-lens/config.json` — **only when it already exists**; current users
+   never move.
+3. `$PI_CODING_AGENT_DIR/extensions/pi-lens.json` — **only when it exists**
+   and step 2 missed.
+4. `~/.pi-lens/config.json` — the canonical default (unchanged).
+
+pi-lens does not write the global config; there is no settings writer in this
+repository. Create or edit the selected file by hand. `effective_config` shows
+which file supplies the global tier. If an existence probe errors (a file where
+a directory belongs, permission errors, or a symlink loop), the errored tier is
+retained and the read failure is reported under `PILENS_CFG_0001`; it is not
+treated as absent. See the [XDG-like recipe](configuration.md#global-config-location).
+
 ## Data directory
 
 ### `PILENS_DATA_DIR`
@@ -260,12 +283,46 @@ Days to keep rotated logs before cleanup. **Default:** `7`.
 
 Maximum log size (MB) before rotation. **Default:** `10`.
 
+## Diagnostic-only knobs
+
+These use the `PILENS_` (no underscore after `PI`) prefix, so they are
+invisible to a `grep PI_LENS_` sweep — use the wider `grep -E 'PI_?LENS_'`
+below to find them and anything like them. Not part of the supported surface;
+each exists for a narrow diagnostic or escape-hatch purpose, not everyday
+tuning.
+
+### `PILENS_PROBE`
+
+Set to `1` to force an ad-hoc probe (a bare `node -e` or throwaway script
+against built `clients/*.js`, run outside a test harness and without
+`PI_LENS_HOME` set) to redirect its home/log directory away from the real
+`~/.pi-lens`, the same way running from an agent worktree or `os.tmpdir()`
+already does automatically (`clients/probe-home-state.ts`). Prefer setting
+`PI_LENS_HOME` explicitly; this is the forced opt-in for a probe run from an
+ordinary project checkout, where the automatic detection would not fire.
+
+### `PILENS_UNSAFE_FORCE_GRAMMAR_LOAD`
+
+Diagnostic escape hatch for the grammar-health probe only (`clients/grammar-source.ts`).
+Set to `1` to force-load a tree-sitter grammar this runtime has blocklisted,
+to test whether a newer build/runtime lifts the block. Disables the crash
+protection the blocklist provides and can abort the process. Never set in
+normal operation.
+
+### `PILENS_PUB_DEBUG`
+
+Set to `1` to trace each LSP server's `publishDiagnostics` behavior (version +
+diagnostic count) to diagnose the clean-file affirmative-signal question:
+which servers publish an empty-with-version set on a clean scan vs. go silent
+(`clients/lsp/client.ts`). Off by default.
+
 ## Advanced tuning knobs
 
 pi-lens also has many advanced/internal tuning variables — LSP timeouts and
 memory budgets, debounce intervals (`PI_LENS_LSP_*`, and others). These are for
 edge-case tuning, are not part of the supported surface above, and are documented
-in the source; enumerate them with `grep PI_LENS_ clients/`.
+in the source; enumerate them with `grep -E 'PI_?LENS_' clients/` (the wider
+pattern catches the `PILENS_` diagnostic-only knobs above too).
 
 ## Related
 

package/docs/features.md

@@ -316,7 +316,7 @@ Covers JavaScript/TypeScript, Python, Go, Rust, Ruby, Shell, and CMake. A TypeSc
 
 Structural rules organized by language in `rules/tree-sitter-queries/<language>/`. Rules marked **🔴** block the agent inline at write time (only for lines in the current edit); others are advisory.
 
-**Suppressing a finding:** add `// pi-lens-ignore: rule-id` on the flagged line or the line above (JS/TS), or `# pi-lens-ignore: rule-id` for Python/Ruby/Shell. This suppresses that specific rule at that location only.
+**Suppressing a finding:** add `// pi-lens-ignore: rule-id` on the flagged line or the line above (JS/TS), or `# pi-lens-ignore: rule-id` for Python/Ruby/Shell. Rule ids are comma-separated. A supported separator (` -- `, ` — `, or `: `) starts one trailing reason suffix for the whole payload; all remaining text, including commas, stays in the reason and is not parsed as another rule id. This suppresses each listed rule at that location only.
 
 **Bring your own rules:** drop YAML query files into `rules/tree-sitter-queries/<language>/` in your project — pi-lens merges them with the built-ins on session start. The schema, predicates (`eq`, `match`, `any-of`), and `inline_tier` (`blocking` | `warning` | `review`) are documented in [`custom-rules.md`](custom-rules.md). A `rules/tree-sitter-queries/rule-schema.json` JSON Schema is bundled for editor autocomplete via `.vscode/settings.json`.
 
@@ -401,7 +401,7 @@ pi-lens ships an MCP (Model Context Protocol) server so Claude Code — or any M
 | **Per-turn** | `pilens_turn_end` | Drives the **real** `handleTurnEnd` (knip incremental, dep-circular, cascade, tests, actionable+code-quality warnings) — not a re-implementation. Caller-supplied edited files are auto-registered into turn-state via `addModifiedRange`. |
 | **Per-session** | `pilens_session_start` | Drives the **real** `handleSessionStart` — full jscpd/knip/madge/govulncheck/gitleaks/trivy scans + complexity baselines + LSP warm. The error-debt baseline is not currently populated by the production session-start path. |
 | **Project / observability** | `pilens_project_scan`, `pilens_project_report`, `pilens_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search`, `pilens_effective_config` | Cheap project-wide scans, cached diagnostic state, latency telemetry, ranked identifier search (BM25 over the persisted word index — see [docs/word-index.md](word-index.md)). Cross-file blast radius now lives in `pilens_module_report`'s `blastRadius` option. `pilens_health` (and its pi-side `/lens-health` counterpart) also reports a bounded, process-local **degradation ledger** — trust refusals, mode suppressions, LSP breaker trips, formatter skips/failures, TypeScript/word-index/review-graph/project-snapshot idle evictions, WASM aborts, and diagnostics-timeout tallies — so silently degraded behavior stays visible instead of vanishing into a log. `pilens_effective_config` answers **“why is X running / why is X not running”** from one query — the resolved configuration with the provenance of every setting, and for a file you name, its language plus every LSP server with the reason it was selected or denied and the runners that would dispatch. It reports sources, never values. |
-| **Lifecycle / loop** | `pilens_rebuild` | Runs `npm run build:dist` so `pilens_analyze mode=fresh` reflects the latest commit. Makes the review loop self-contained: commit → `pilens_rebuild` → `pilens_analyze mode=fresh` → `pilens_latency`. |
+| **Lifecycle / loop** | `pilens_rebuild`, `pilens_session_end` | `pilens_rebuild` runs `npm run build:dist` so `pilens_analyze mode=fresh` reflects the latest commit. Makes the review loop self-contained: commit → `pilens_rebuild` → `pilens_analyze mode=fresh` → `pilens_latency`. `pilens_session_end` ends the MCP connection's telemetry session and writes its bounded situational-tool telemetry line; terminal for the connection. |
 
 **Honest limits** (live-tested, documented in `mcp.md`):
 

package/docs/globalconfig.md

@@ -1,6 +1,11 @@
 # Configuration
 
-pi-lens reads optional user preferences from `~/.pi-lens/config.json` (`%USERPROFILE%\\.pi-lens\\config.json` on Windows). An unrecognized top-level key is logged once (to surface a typo like `lps` for `lsp`) and then ignored; `$schema` is always allowed for editor JSON-schema association. Missing or invalid config falls back to defaults.
+pi-lens reads optional user preferences from the global file selected by the
+[winning-location table](configuration.md#global-config-location) (`~/.pi-lens/config.json`
+by default; `%USERPROFILE%\\.pi-lens\\config.json` on Windows). An unrecognized
+top-level key is logged once (to surface a typo like `lps` for `lsp`) and then
+ignored; `$schema` is always allowed for editor JSON-schema association. Missing
+or invalid config falls back to defaults.
 
 ## Every toggle, both ways
 

package/docs/language-coverage.md

@@ -50,6 +50,8 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | CMake                 | ✓ (cmake-language-server) | lsp                                                                                      | cmake-format            |
 | CUE                   | ✓ (syntax via cue lsp, evaluation via cue vet) | lsp, cue-vet                                                              | cue fmt                 |
 
+### CUE tree-sitter grammar
+
 `cue lsp` reports load and parse errors as you type but leaves conflicting
 values and failed constraints to `cue vet` — the `cue-vet` auxiliary runner
 (#1522) covers that gap, so together they give full coverage: syntax/parse
@@ -79,6 +81,21 @@ Both are upstream grammar limitations (tracked among
 [eonpatapon/tree-sitter-cue](https://github.com/eonpatapon/tree-sitter-cue)'s
 open issues), not something a query change here can fix.
 
+## Non-core grammars
+
+The `tree-sitter` runner and `symbol_search`/`module_report` structural
+extraction ship a fixed set of core grammars; grammars for the other
+languages in the table above (CUE included) are fetched lazily on first use
+into web-tree-sitter's resolved package directory, verified against
+`scripts/grammars.lock.json`. This resolution works on a runtime that cannot
+resolve a bare package specifier — pi shipped as a `bun build --compile`
+binary — via one shared subpath-based ladder
+(`scripts/lib/web-tree-sitter-dir.mjs`, #3409); before that fix, non-core
+languages could never be analysed on those hosts. A grammar that never loads
+(fetch failure, unwritable target, an unsupported runtime) is recorded as a
+`grammar_unavailable` **skip**, never a clean pass
+(`clients/dispatch/runners/tree-sitter.ts`).
+
 ## Considered and skipped (2026-08-20 survey, closed out by #1757)
 
 Recorded so these are not re-litigated. The 2026-08-20 survey's first pass

package/docs/lsp-capability-matrix.md

@@ -9,7 +9,8 @@ confirmed against Neovim's LSP client, which sidesteps this entirely by being as
 
 Generate/refresh this matrix with `node scripts/characterize-lsp.mjs [--install]`
 (the `mode` column) and `node scripts/probe-clean-signal.mjs [--install]` (the
-`clean-behavior` column — 4-way: 2 / 2* / 3 / unknown). Both **merge** in place: a server the
+`clean-behavior` column — 4-way: 2 / 2* / 3 / unknown — and the `first-publish`
+column, #3310). Both **merge** in place: a server the
 running host couldn't spawn keeps its prior row, so an ubuntu-poor run can't
 regress a richer one (#390). The nightly **tool-smoke** workflow runs both (plus
 `server-capabilities.mjs`) and opens/updates a single auto-PR
@@ -27,6 +28,49 @@ anything). The native TS7 launch variant (`typescript7`/`typescript7-clean`,
 #524/#526) is deliberately excluded from comparison against classic's marker —
 they share a server id but not a verified clean-signal behavior.
 
+What IS gated is the pair of COMMITTED sources:
+`tests/config/lsp-clean-behavior-census.test.ts` (#3347) compares the
+`clean-behavior` column below against the `silentOnClean` markers in both
+directions — every measured push row against its marker, and every marker
+against a push row measured `silent` — so a nightly refresh cannot merge a
+re-measured server until its marker moves with it, and a marker cannot outlive
+the measurement that justified it. Push rows the probe has not classified are
+admitted by name in that file, and an admission reds once its row becomes
+measured.
+
+## First publish: is the first push an answer? (#3310)
+
+A second, ORTHOGONAL axis to the tiers below, measured from the same probe run
+and written as the `first-publish` column:
+
+| value | meaning | wait policy |
+|---|---|---|
+| `direct` | the first publish for a dirty file carries the findings | the first publish resolves the wait, as it always did |
+| `empty-first` | the server answers `didOpen` with an EMPTY set while a one-time index builds, then publishes again once indexing ends | the client HOLDS that first empty publish (`emptyFirstPublish: "indexing"` in `clients/lsp/wait-policy/strategies.ts`); the server's own next publish releases it, and the hold is one-shot per client session |
+| `empty-only` | every publish on the dirty fixture was empty | not classifiable on this axis — an undiagnosed dirty fixture looks exactly like an unfinished index, so nothing is inferred in either direction |
+| `n/a (pull)` / `TBD` | pull-mode, or not measured on a host that could reach the server | no behavior change |
+
+Why this axis had to exist at all: the wait needs a positive signal, and an
+empty publish is a positive signal for a Tier 2/2\* server (a genuinely clean
+file) and a MEANINGLESS one for a server that has not finished indexing. The two
+are identical on the wire, so the difference is a measurement, not an inference.
+intelephense is the measured member (2026-09-23, v1.18.5): `[]` at +295ms,
+`indexingStarted` at +301ms — i.e. AFTER the empty publish, so no
+work-in-progress signal is available at the moment the decision must be made —
+`indexingEnded` at +689ms and the real 2-diagnostic set at +696ms. On a
+genuinely clean file the same session publishes `[]` twice (at +304ms and again
+at +663ms, right after indexing), which is what lets the held publish be
+released by the server itself rather than by a timer; a WARM touch publishes the
+real set first, so the hold costs nothing once the session is warm. pi-lens does
+not advertise `window.workDoneProgress` (#974: advertising it crash-loops
+opengrep's `--experimental` LSP mode), so `$/progress` is not an available
+discriminator either.
+
+`tests/config/lsp-first-publish-census.test.ts` compares this column against the
+`emptyFirstPublish` markers and reds in BOTH directions, which is the expiry
+check: when the nightly re-measures a server into a different class, the docs
+refresh cannot merge until the marker is updated with it.
+
 ## The strategies
 
 | Tier | Signal | Affirmative clean? | Example |
@@ -48,7 +92,7 @@ the next touch probes again. Only silence through the full push budget latches
 that server id as navigation-only for the service session. A publish upgrades it
 to the ordinary push-wait policy.
 
-## Matrix (dev box + CI nightly; mode last refreshed 2026-06-17 from run 27713958681, clean-behavior probed on the dev box 2026-07-08 — #460)
+## Matrix (dev box + CI nightly; mode last refreshed 2026-06-17 from run 27713958681, clean-behavior probed in run 35914033696 — #460)
 
 `mode` from cached capabilities; `clean-behavior` from the phase-aware publish-trace
 probe. The probe attributes publishes to two phases — the **dirty touch** (proves the
@@ -63,37 +107,49 @@ nightly steps, **dev** = the dev box (a row measured on both reads `dev+ci`).
 Merges never blank a prior good value, so a CI non-result leaves the dev
 classification standing.
 
-| lang | server | mode | clean-behavior | tier | src |
-|---|---|---|---|---|---|
-| json | vscode-json-language-server | pull | — | 1 | dev+ci |
-| css | vscode-css-language-server | pull | — | 1 | dev+ci |
-| html | vscode-html-language-server | pull | — | 1 | dev+ci |
-| rust | rust-analyzer | pull | — | 1 | dev |
-| svelte | svelte-language-server | pull | — | 1 | dev+ci |
-| deno | deno (alt of typescript) | pull | — | 1 | dev+ci |
-| ruby | ruby-lsp | pull | — | 1 | ci |
-| csharp | csharp-ls | pull | — | 1 | ci |
-| typescript | typescript-language-server | push-only | silent | 3 | dev+ci |
-| python | pyright | push-only | publishes-versioned | 2 | dev+ci |
-| jedi | jedi-language-server (alt of python) | push-only | publishes-versioned | 2 | ci |
-| yaml | yaml-language-server | push-only | publishes-unversioned | 2* | dev+ci |
-| shell | bash-language-server | push-only | publishes-versioned | 2 | dev+ci |
-| dockerfile | docker-langserver | push-only | publishes-unversioned | 2* | dev+ci |
-| toml | taplo | push-only | publishes-unversioned | 2* | dev+ci |
-| terraform | terraform-ls | push-only | TBD | 2/3? | dev+ci |
-| prisma | @prisma/language-server | push-only | publishes-unversioned | 2* | dev+ci |
-| php | intelephense | push-only | TBD | 2/3? | dev+ci |
-| zig | zls | push-only | publishes-unversioned | 2* | dev+ci |
-| vue | @vue/language-server | push-only | TBD | 2/3? | dev+ci |
-| dart | dart language-server | push-only | publishes-unversioned | 2* | ci |
-| gleam | gleam lsp | push-only | publishes-unversioned | 2* | ci |
-| clojure | clojure-lsp | push-only | publishes-unversioned | 2* | ci |
-| opengrep | opengrep (aux) | push-only | publishes-unversioned | 2* | dev+ci |
-| ast-grep | ast-grep (aux) | push-only | publishes-versioned | 2 | dev+ci |
+`vue`'s `clean-behavior` was hand-reset to `unknown` (#3390): its
+`publishes-unversioned` cell came from 58/45 publishes that the shared
+`extension.log` window had attributed to vue but that belonged to `tinymist`.
+With the sink scoped per server, nightly 36046209160 measured vue 0/0, and an
+`unknown` result is never written by the merge above — so the refuted value had
+to be cleared by hand. It stays `unknown` until a run observes
+`@vue/language-server` publish; `tests/config/lsp-clean-behavior-census.test.ts`
+carries the named admission until then.
+
+| lang | server | mode | clean-behavior | first-publish | tier | src |
+|---|---|---|---|---|---|---|
+| json | vscode-json-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| css | vscode-css-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| html | vscode-html-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| rust | rust-analyzer | pull | — | n/a (pull) | 1 | dev |
+| svelte | svelte-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| deno | deno (alt of typescript) | pull | — | n/a (pull) | 1 | dev+ci |
+| ruby | ruby-lsp | pull | — | n/a (pull) | 1 | ci |
+| csharp | csharp-ls | pull | — | n/a (pull) | 1 | ci |
+| typescript | typescript-language-server | push-only | silent | direct | 3 | dev+ci |
+| markdown | marksman | push-only | silent | direct | 3 | ci |
+| lua | lua-language-server | push-only | silent | direct | 3 | dev+ci |
+| python | pyright | push-only | publishes-versioned | direct | 2 | dev+ci |
+| jedi | jedi-language-server (alt of python) | push-only | publishes-versioned | direct | 2 | ci |
+| yaml | yaml-language-server | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| shell | bash-language-server | push-only | publishes-versioned | direct | 2 | dev+ci |
+| dockerfile | docker-langserver | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| toml | taplo | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| terraform | terraform-ls | push-only | TBD | TBD | 2/3? | dev+ci |
+| prisma | @prisma/language-server | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| php | intelephense | push-only | publishes-unversioned | empty-first | 2* | dev+ci |
+| zig | zls | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| vue | @vue/language-server | push-only | unknown | direct | 2/3? | dev+ci |
+| dart | dart language-server | push-only | publishes-unversioned | direct | 2* | ci |
+| gleam | gleam lsp | push-only | publishes-unversioned | direct | 2* | ci |
+| clojure | clojure-lsp | push-only | publishes-unversioned | direct | 2* | ci |
+| opengrep | opengrep (aux) | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| ast-grep | ast-grep (aux) | push-only | publishes-versioned | direct | 2 | dev+ci |
+| cue | CUE Language Server (cue lsp serve) | push-only | publishes-versioned | direct | 2 | dev+ci |
 
 **Unknown — fixture exists, mode not yet captured.** The toolchain-gated family
 (no auto-install today; tracked in #241) — `go` (gopls), `java` (jdtls),
-`kotlin`, `swift` (sourcekit-lsp), `lua`, `cpp` (clangd), `haskell`, `elixir`,
+`kotlin`, `swift` (sourcekit-lsp), `cpp` (clangd), `haskell`, `elixir`,
 `ocaml`, `nix` (nixd), `fsharp`. Their servers don't install in the nightly, so
 characterize reports `unknown` (a non-failure ⚠). Once #241 lands they'll fill in
 the same way clojure-lsp/gleam now do (both auto-install via the github strategy
@@ -103,7 +159,8 @@ and were characterized `push-only` in the run above).
 - **Mode ≠ tier, and the split needs BOTH axes.** Push-only further splits along
   latency (does anything publish on a clean transition? — silence is the only
   budget-wait case, because pi-lens's publish handler emits and early-returns the
-  wait on EVERY publish, versioned or not) and currency-proof (is the publish
+  wait on every publish, versioned or not, with the single #3310 exception of a
+  held empty FIRST publish from an `empty-first` server) and currency-proof (is the publish
   versioned, i.e. provably about the live edit?). The 4-way
   `probe-clean-signal.mjs` measurement drives this: ast-grep → 2, yaml/opengrep →
   2\*, typescript (clean file) → 3.
@@ -121,6 +178,16 @@ and were characterized `push-only` in the run above).
   fixtures for exactly this reason. Corollary: a 2\* measured only on a dirty
   fixture may overstate a server whose publishes stop when its set goes empty —
   langs without a clean fixture carry that caveat.
+- **The probe's publish capture was dead, and the column looked alive anyway
+  (#3310).** `probe-clean-signal.mjs` intercepted `console.error` for the
+  `[lsp-pub]` trace, but #1333 moved that trace's sink to `extension.log` — so
+  every phase counted zero publishes, every server classified `unknown`, and the
+  #390 merge guard then preserved the July 2026 values verbatim. A dead
+  instrument and a healthy one are indistinguishable when non-results are
+  discarded by design. The probe now reads the sink the client actually writes;
+  `first-publish` measurements on the dev box, 2026-09-23: php `empty-first`,
+  typescript / opengrep / ast-grep / marksman `direct` (so the class does not
+  extend to them on the measurement, whatever their comments suggest).
 - **#458's learned-deadline target set = the tier-3 rows only.** 2\* rows resolve
   the wait at runtime and must NOT be given learned deadlines.
 - **Tier 3 is budget-bound by necessity**, not laziness: a silent server's silence is

package/docs/pi-lens-fixer.md

@@ -9,8 +9,48 @@
 - Preserve contributor authorship and leave Git authority to the orchestrator
   unless the delegation grants it explicitly.
 
+## Standing procedure
+
+### Standard mechanics
+
+- Commit the code as soon as the targeted suite is green, then add evidence in
+  a later commit. A worker can be settled mid-evidence-pass; on PR #3268 the
+  orchestrator had to commit the tree.
+- A whole-module `vi.mock` of a production module must spread `importOriginal`.
+  Run `tests/config/vi-mock-export-sweep.test.ts`.
+- Exact-pin sweeps and merge state: `tests/config/glossary-synonym-sweep.test.ts`
+  (#3279) pins the live retired-synonym identifier population per (term, file)
+  exactly, in both directions. If a change adds or removes one of the pinned
+  identifier uses, run the sweep on the head and on the merge of
+  `origin/master` + head before pushing, then re-pin in the same PR using the
+  sweep's own `UNPINNED`/`STALE` output. On 2026-09-23, two green PRs merged
+  red (#3279's pins predated #3283, leaving master red until #3288), and #3284
+  was red on its own `path` count changes (cue-vet 5→6, dart-analyze 6→4)
+  until an orchestrator trailing commit re-pinned.
+
+### Failure list before code
+
+Before the first edit of any fix, write the list of ways the change could fail
+(the directions the mutation table will later prove) in the PR body. The
+mutation table is that list with transcripts, never a list invented after the
+code. This week's evidence: #3252 r1 shipped an exit table whose inverse
+direction (nonzero WITH findings) was never listed and was caught by the
+reviewer.
+
+Seams are named in the brief before the round; no test is written at an
+unconfirmed seam — a fixer that needs a new seam stops and reports it as a
+finding, not as a test.
+
+A fix round does not deepen: no refactor, no helper extraction, no rename
+beyond the fix's own lines; deepening is its own slice under the owning
+umbrella. #3254 and #3256 stayed inside their briefs; #3178's four rounds show
+the cost of not doing so.
+
 ## Evidence
 
+- Witness rule (ADR 0007): #1605 owns the witness lanes, and their fixtures
+  live under `tests/fixtures/witness/<slice>/`.
+
 - Add a regression test through the production path.
 - Capture the pre-fix assertion failure.
 - Prove the fixed test passes.
@@ -47,9 +87,23 @@
 
 - Without Git authority, leave changes uncommitted.
 - Write root-level `PR_BODY.md` and `COMMIT_MSG.txt`; keep both untracked.
-- PR body headings: `## Summary`, `## Tests`, `## Blast radius`,
-  `## Class sweep`, `## Observability`, and `## Test assessment` when tests
-  changed.
+- The PR body is the whole `.github/PULL_REQUEST_TEMPLATE.md`, every
+  heading present in order: `## Why` (one sentence), `## Notes for the
+  reviewer`, `## Change outline`, `## Summary`, `## Type of change`,
+  `## Area`, `## Checklist`, `## Tests`, `## Blast radius`,
+  `## Observability` (a record literal from the runtime diff, or exactly
+  `No new failure path; no record added.`), `## Class sweep`, and
+  `## Test assessment`. A brief that names only some headings does not
+  shorten this list.
+- Run `node scripts/check-pr-body.mjs --lint-local PR_BODY.md` and
+  `node scripts/check-changelog-fragments.mjs` before the hand-back; both
+  must pass, and the hand-back quotes them. A changelog fragment is
+  `---` / `section: <Added|Changed|Deprecated|Removed|Fixed|Security>` /
+  `---` / blank / one `- ` bullet. (Four of six Luna PRs on 2026-09-23
+  redded the PR-body and changelog gates on the first head; the fixes were
+  all mechanical.)
+- The hand-back carries the commit SHA; a dirty tree is an incomplete
+  round.
 - Include every red, mutation result, skipped check, and environment block.
 - Answer each finding id with `fixed`, `not fixed`, or `withdrawn (reason)`.
 - Report verdict, changed files, totals, and unverifiable checks.

package/docs/pi-lens-investigator.md

@@ -26,6 +26,15 @@
 
 ## Evidence rules
 
+- **Already-shipped check before naming a slice:** for every umbrella member the
+  brief cites as remaining work, grep the current tree and the closing PRs and
+  state shipped, partially shipped, or not shipped with `file:line`; a first
+  slice may name only work whose absence was verified on the current head.
+  The 2026-09-22 primitives brief named three scanner filter blocks as the
+  #1461 first slice even though #1622/#1625/#1628 had already removed them;
+  the fixer found the premise error in PR #3264 and the #1892 comment on
+  2026-09-23.
+
 - A reported defect is not confirmed until the production-path probe is red on
   the current tree for the reported reason.
 - A probe must distinguish competing hypotheses, use independent observations,