@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-lens/docs/configuration.md

@@ -0,0 +1,222 @@
+# Configuring pi-lens
+
+There are **two** pi-lens config files:
+
+| File | Scope | Notes |
+| --- | --- | --- |
+| `.pi-lens.json` | the project | Committed or not, your call. Nearest one wins **per field** — a package can override one setting without restating the repo root's. |
+| `~/.pi-lens/config.json` | the machine | Your defaults across every project. `PI_LENS_CONFIG_PATH` relocates it. |
+
+Both files have the same shape, with one exception noted below the example:
+everything LSP-related lives under an `lsp` namespace inside them.
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/apmantza/pi-lens/master/docs/schema/pi-lens-config-v1.json",
+  "ignore": ["dist/**"],
+  "maxProjectFiles": 8000,
+  "rules": { "high-complexity": { "threshold": 25 } },
+  "lsp": {
+    "disabledServers": ["typos"],
+    "warmFiles": ["src/main.rs"],
+    "servers": {
+      "my-server": {
+        "name": "My Custom LSP",
+        "extensions": [".myext"],
+        "command": "my-lsp-server",
+        "args": ["--stdio"]
+      }
+    },
+    "serverOverrides": {
+      "rust": {
+        "initializationOptions": { "check": { "command": "clippy" } }
+      }
+    }
+  }
+}
+```
+
+**Some settings are global-only.** A handful of switches — `lsp.enabled`
+(`--no-lsp`), `tests.enabled`, `delta.enabled` and the other session-wide
+toggles — are decided once for the machine, not per project, so writing one in a
+`.pi-lens.json` does nothing. It is not ignored quietly: the project loader says
+so, naming the key. `docs/settings.md` lists which flags are which.
+
+## Which file wins
+
+One order, lowest precedence first. A later tier replaces an earlier tier's
+value **for that field only** — objects are merged field-wise, never replaced
+whole, so setting one key never silently drops the rest of a section.
+
+1. **global** — `~/.pi-lens/config.json`.
+2. **project root** — the outermost `.pi-lens.json` at or above your working
+   directory.
+3. **nested-project** — every `.pi-lens.json` between that root and your working
+   directory, outermost first. The nearest file wins, per field.
+
+Those three are the tiers the config **files** resolve through, and they are the
+only ones this resolution populates. Four more tiers are reserved in the
+precedence table — `builtin` below them, and `env`, `cli`, `host` above — and
+nothing writes into them yet; #2427 (env/CLI) and #2416 (host and project trust)
+are what fill them in.
+
+Until they do, environment variables and CLI flags are read by their own
+accessors rather than through this resolution, and their effective precedence
+for a pi-lens toggle is:
+
+1. a `PI_LENS_*` environment variable set to `1` — checked first, and it wins
+   outright;
+2. the matching `--lens-*` / `--no-*` CLI flag;
+3. the nearest project `.pi-lens.json`, then the outer ones (project-scoped
+   settings only);
+4. `~/.pi-lens/config.json`;
+5. the built-in default.
+
+Subsystem-specific env overrides follow the same shape: a
+`PI_LENS_REVIEW_GRAPH_MAX_FILES` beats a `.pi-lens.json`'s
+`reviewGraph.maxFiles`. `docs/environment-variables.md` and `docs/settings.md`
+are the per-setting references.
+
+### One exception: `lsp.disabledServers` is a denial, not a value
+
+Ordinary settings are last-tier-wins. A **denial** is not, because the tier
+that made it is usually the one you control and the tier that would override it
+is usually one that arrived with somebody else's checkout.
+
+`lsp.disabledServers` resolves as the **union of every tier's entries**. A
+project `.pi-lens.json` can add to it and can never subtract from it, so a
+repository cannot re-enable a server you turned off in
+`~/.pi-lens/config.json`. There is no vocabulary for un-denying an entry: if
+you change your mind, edit the file that denied. The provenance reports, per
+denied server, the tier that contributed it.
+
+```console
+$ # which servers run for this file, and why
+$ pilens_effective_config file=src/main.rs
+  ✗ typos — disabled-by-config (global ~/.pi-lens/config.json → /lsp/disabledServers/0)
+```
+
+The union spans **both spellings**: a document's deprecated root keys
+(`servers`, `serverOverrides`, `disabledServers`, `warmFiles`) are read
+into the `lsp` namespace before any tier is merged, so one setting is resolved
+once no matter which spelling each file uses. Migrating does not change the
+answer, staying un-migrated is not a way around the denial, and a half-migrated
+pair of files merges rather than one clobbering the other.
+
+Two rules make the rest of the table unambiguous:
+
+- **The search stops at `$HOME`.** pi-lens never reads a config file in your
+  home directory or above it. A stray `pi-lens.json` in `$HOME` (or at `C:\`)
+  is not adopted by every project on the machine. The machine-global file is
+  read by its own path, so it is unaffected.
+- **The canonical spelling wins.** Where a legacy file or a legacy key means the
+  same thing as the canonical one, the canonical one is used — otherwise the
+  migration below could never be completed.
+
+## Legacy locations (still read; being removed)
+
+These are read for their deprecation window and then **removed**. Each one you
+still have produces one warning per setting, naming exactly where to move it —
+carrying the stable code `PILENS_CFG_0003` (a deprecated file) or
+`PILENS_CFG_0002` (a deprecated key), so you can match or suppress on the code
+rather than on the prose.
+
+| Legacy | Move it to | Code |
+| --- | --- | --- |
+| `.pi-lens/lsp.json` | `.pi-lens.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `pi-lsp.json` | `.pi-lens.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `pi-lens.json` (undotted) | `.pi-lens.json` | `PILENS_CFG_0003` |
+| `~/.pi-lens/lsp.json` | `~/.pi-lens/config.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `servers` at the file root | `lsp.servers` | `PILENS_CFG_0002` |
+| `serverOverrides` at the file root | `lsp.serverOverrides` | `PILENS_CFG_0002` |
+| `disabledServers` at the file root | `lsp.disabledServers` | `PILENS_CFG_0002` |
+| `warmFiles` at the file root | `lsp.warmFiles` | `PILENS_CFG_0002` |
+
+**Deprecated since 4.1.4. Read for the last time before 5.0.0.** The window is
+declared as data in `clients/config-diagnostic-codes.ts`
+(`DEPRECATED_CONFIG_SURFACES`) and enforced by test, so the schedule above and
+the code cannot drift apart. `docs/public-api-stability.md` describes the policy
+these dates instantiate.
+
+A `.pi-lens.json` that mixes both spellings is fine while you migrate: the
+canonical key wins, and the keys you have not moved yet keep working.
+
+Only keys pi-lens actually recognizes get "move it to …" advice. A key in a
+legacy file that is not a pi-lens setting at all — a typo, or a leftover from
+another tool — cannot be migrated anywhere, so it gets the ordinary
+unrecognized-key notice (`PILENS_CFG_0001`) and is counted in ONE whole-file
+`PILENS_CFG_0003` notice for the file rather than being told to move.
+
+## When a config is ignored
+
+A file that cannot be read or parsed is **ignored, never partially applied** —
+pi-lens runs on defaults for it and says so once, with the code
+`PILENS_CFG_0001`. A field whose value does not match its declared type is
+dropped on its own (`PILENS_CFG_0005`), and an unrecognized field is dropped
+with a message naming the key (`PILENS_CFG_0004`). If resolving a file fails
+internally the whole file is ignored and said so under its own code
+(`PILENS_CFG_0008`), so "one field went missing" and "none of this file is in
+effect" are never the same code. Nothing about your config is ever ignored
+silently.
+
+The number of notices one file can produce is bounded PER NOTICE LIST, because
+the number of keys in a file is not. There are two lists, split by who composes
+them rather than by what they say — both are about values that were rejected:
+
+- what **resolving** the file produced — the per-field rejections
+  (`PILENS_CFG_0004`, `PILENS_CFG_0005`, `PILENS_CFG_0006`) together with the
+  deprecation notices (`PILENS_CFG_0002`, `PILENS_CFG_0003`), which share this
+  list;
+- what the **loader** reading the file produced on its own — unknown top-level
+  keys and settings it refused (`PILENS_CFG_0001`).
+
+Each list is bounded at 20 records: up to 19 notices plus, when the bound bit,
+a single `PILENS_CFG_0007` summary giving the count that was suppressed, so a
+truncated list always says that it is truncated. That summary is about the
+LIST, not about the file: a config whose every setting was applied can still
+overflow the bound, so it is worded and recorded as a summary rather than as an
+ignored config.
+
+One notice is never suppressed by that bound: `PILENS_CFG_0008`, which says the
+whole file is out of effect. It is not one more rejected key competing for a
+slot — it is what tells you the rejections above it are no longer the whole
+story — so it is kept however full the list already was.
+
+## Asking what is actually in effect
+
+You never have to reconstruct the table above by hand. `pilens_effective_config`
+(MCP) and `effective_config` (pi) return the resolved configuration with the
+provenance of **every** leaf — the tier, the file, the key, and the trust
+decision that applied — plus, for a file you name, its language, every LSP
+server with the reason it was selected or denied, and the runners that would
+dispatch. That is the answer to "why is this running" and to "why is this *not*
+running", without reading a log.
+
+Naming a `file` resolves the configuration **at that file's own directory**,
+which is where the runtime decides from — so a nested `repo/sub/.pi-lens.json`
+layer contributes to the answer, appears in the reported document list, and is
+named as the file behind any decision it made. The walk runs upward and is
+**confined to `cwd`**: a `file` that resolves outside `cwd` — including a
+sibling package in the same monorepo — is rejected rather than answered from
+its own unrelated tree, because the per-file answer is only ever correct when
+it is a superset of the workspace's own; the rejection names the `cwd` it was
+measured against and the remedy is to re-query with `cwd` set to that file's
+own workspace. A confined `file` always passes back through the workspace's
+own documents on its way up, so they are always included too.
+
+It reports **sources, never values**. Environment values never appear, a custom
+server's command line is cut to the binary itself, and every path is rewritten
+`~`-relative. There is no un-redacted mode: the un-redacted data is the config
+file you already have.
+
+`pilens_health` embeds the same provenance as **counts per tier** — how many
+settings each source decided, and which `PILENS_CFG_*` notices the resolution
+produced — so a session's config posture is visible without the detail.
+
+## See also
+
+- `docs/globalconfig.md` — every key of `~/.pi-lens/config.json`, in detail.
+- `docs/settings.md` — the CLI flags and what they map to.
+- `docs/environment-variables.md` — the `PI_LENS_*` tier.
+- `docs/public-api-stability.md` — what `x-stability`, the `PILENS_CFG_*` codes,
+  and the deprecation windows commit pi-lens to.

package/node_modules/pi-lens/docs/dependencies.md

@@ -40,9 +40,9 @@ Auto-install behavior depends on gate type:
 | `intelephense`                      | PHP LSP                          | Yes            | Flow-gated                         |
 | `bash-language-server`              | Bash LSP                         | Yes            | Language-default                   |
 | `yaml-language-server`              | YAML LSP                         | Yes            | Language-default                   |
-| `vscode-langservers-extracted`      | JSON/ESLint/CSS/HTML LSP         | Yes            | Language-default                   |
-| `vscode-css-languageserver`         | CSS LSP                          | Yes            | Language-default                   |
-| `vscode-html-languageserver-bin`    | HTML LSP                         | Yes            | Language-default                   |
+| `vscode-json-language-server`       | JSON LSP (`vscode-langservers-extracted`) | Yes  | Language-default                   |
+| `vscode-css-languageserver`         | CSS LSP (`vscode-langservers-extracted`)  | Yes  | Language-default                   |
+| `vscode-html-languageserver-bin`    | HTML LSP (`vscode-langservers-extracted`) | Yes  | Language-default                   |
 | `svelte-language-server`            | Svelte LSP                       | Yes            | Flow-gated                         |
 | `@vue/language-server`              | Vue LSP                          | Yes            | Flow-gated                         |
 | `opengrep`                          | Experimental security dispatch   | Auto-install   | Local config / explicit opt-in     |

package/node_modules/pi-lens/docs/features.md

@@ -53,6 +53,43 @@ so the final state is formatter-stable. A `write` immediately followed by an
 deferred too. See `clients/pipeline.ts`, `clients/runtime-tool-result.ts`, and
 `clients/runtime-agent-end.ts`.
 
+A tool pi-lens does not name is classified by the SHAPE of its arguments
+(`clients/mutating-tool.ts`). A host or extension edit tool called `replace` or
+`insert` therefore gets a turn-state entry, a change-log receipt attributed to
+the tool itself, and the deferred autofix and format pass — the same chain
+`edit` gets. Its lines are resolved when the anchor is unambiguous (roughly
+two-thirds of anchors in practice — `clients/hashline-anchor.ts`); otherwise
+the mutation is recorded whole-file with lines unknown, and the
+read-before-edit guard takes its no-line-info arm rather than guessing.
+Deferred is the default for any edit-shaped tool pi-lens cannot place, because
+formatting between the calls of a multi-step rewrite fights the tool that is
+still writing. A tool whose SHAPE is unrecognized too is caught by observation:
+pi-lens takes a bounded snapshot of the path that call names — and only that
+path, so a change to a neighbouring file is never blamed on it — replays
+whatever actually changed through the same chain, then remembers that tool as
+mutating for the session, and on disk under the project's data directory once a
+second observation confirms it, so later sessions classify it by name with no
+snapshot at all. A tool that names no file is caught at `agent_settled` by an
+incremental content check over the files pi-lens has already read, written,
+diagnosed or opened on a language server: a rotating window of the set each
+turn, reading only the files whose size or timestamp actually moved, so the
+check stays affordable as the set grows. A file it has never seen has no
+baseline and is therefore not covered, and a file it cannot verify is named
+rather than reformatted on a timestamp alone
+(`clients/observed-mutation.ts`).
+
+**Bundled fallback lint configs stay conservative.** When a project ships no
+tool config, the package-owned fallback configs set the rules (`config/biome/core.jsonc`,
+`config/ruff/core.toml`, `config/markdownlint/core.json`). The biome fallback
+disables `useImportType`: its safe fix rewrites a value import used only in
+type positions into `import type`, which erases the runtime binding that
+experimental decorator metadata (`emitDecoratorMetadata`) still needs and
+breaks decorator-based dependency injection (refs #2385). Every other
+recommended rule stays on, and an explicit project `biome.json(c)` remains
+authoritative: if you enable `useImportType` there, pi-lens does not override
+it. The ruff fallback selects no flake8-type-checking (TC) rules and applies
+only safe fixes, so it never hoists imports into `TYPE_CHECKING` blocks.
+
 Deferred formatting (the `agent_end` default) runs with **bounded
 concurrency**: at most three formatter subprocesses in flight at once, with
 results applied in admission order and cooperative yields between files, so a
@@ -140,12 +177,14 @@ pi-lens MCP server expose the same shape to Claude Code / any MCP client.
 
 ### Actionable Warnings
 
-At `turn_end`, pi-lens writes `.pi-lens/cache/actionable-warnings.json` summarizing fixable warnings introduced by the current turn. This powers the optional conservative autofix at `agent_end`.
+At `turn_end`, pi-lens writes `<project-data-dir>/cache/actionable-warnings.json` summarizing fixable warnings introduced by the current turn. This powers the optional conservative autofix at `agent_end`.
+
+`<project-data-dir>` is whatever `getProjectDataDir(cwd)` resolves to: `<project>/.pi-lens` only when that legacy directory already exists, otherwise `~/.pi-lens/projects/<project-slug>` (or a `PILENS_DATA_DIR` location). The turn-end advisory points at `lens_diagnostics mode=delta` first and names the resolved file second, so you never have to work the layout out by hand (#2521).
 
 **Report contents:**
 
 - Warnings are delta-only by default: only diagnostics in lines touched during the current turn are included. Pass `--lens-actionable-warning-all` to report all warnings regardless of location
-- Each warning carries a stable `aw:<hash>` ID derived from file, rule, and message, so suppression state persists across turns in `.pi-lens/cache/actionable-warning-state.json`
+- Each warning carries a stable `aw:<hash>` ID derived from file, rule, and message, so suppression state persists across turns in `<project-data-dir>/cache/actionable-warning-state.json`
 - Sources: pipeline `fixable` diagnostics (always included) and LSP code-action warnings when `--lens-actionable-warning-actions` is set
 - When warnings are present, a concise advisory is injected into the agent context (no blocker language)
 
@@ -354,14 +393,14 @@ pi-lens ships an MCP (Model Context Protocol) server so Claude Code — or any M
 
 **Why a second host:** the pi extension's tools are registered via the host SDK and run on pi's event loop. Claude Code lives in a different process with no SDK access. The MCP server sits in that gap, speaking JSON-RPC over stdio (or a warm Unix socket / Windows named pipe side-channel for the Claude Code PostToolUse hook). It's the easiest way to live-test, debug, and dogfood pi-lens — including running a **review loop** where Claude commits to pi-lens and re-measures.
 
-**16 tools, grouped by lifecycle layer** (the same three layers the pi agent hooks use):
+**18 tools, grouped by lifecycle layer** (the same three layers the pi agent hooks use):
 
 | Layer | MCP tools | What they expose |
 |---|---|---|
-| **Per-edit** | `pilens_analyze`, `pilens_lsp_diagnostics`, `pilens_lsp_navigation`, `pilens_ast_grep_search`, `pilens_ast_grep_replace`, `pilens_module_report`, `pilens_read_symbol` | The fast pipeline (format → autofix → LSP diagnostics → parallel runners) plus the structured read-substitute pair. `analyze` accepts `mode: warm \| fresh` — `warm` reuses the server's in-process LSP, `fresh` forks a worker that loads freshly-built code from disk so the result reflects the latest commit. |
+| **Per-edit** | `pilens_analyze`, `pilens_lsp_diagnostics`, `pilens_lsp_navigation`, `pilens_ast_grep_search`, `pilens_ast_grep_replace`, `pilens_module_report`, `pilens_read_symbol`, `pilens_read_enclosing` | The fast pipeline (format → autofix → LSP diagnostics → parallel runners) plus the structured read-substitute pair. `analyze` accepts `mode: warm \| fresh` — `warm` reuses the server's in-process LSP, `fresh` forks a worker that loads freshly-built code from disk so the result reflects the latest commit. |
 | **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_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search` | 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. |
+| **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`. |
 
 **Honest limits** (live-tested, documented in `mcp.md`):

package/node_modules/pi-lens/docs/globalconfig.md

@@ -27,6 +27,20 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
 | `--lens-compact-tool-line` | `ui.compactToolLine` | `false` |
 | `--no-lazy-tools` | `tools.lazy` | `true` |
 | `--lens-turn-end-madge` | `turnEnd.madge.enabled` | `false` |
+| `--no-knip` | `knip.enabled` | `true` |
+| `--no-jscpd` | `jscpd.enabled` | `true` |
+| `--no-madge` | `madge.enabled` | `true` |
+| `--no-gitleaks` | `gitleaks.enabled` | `true` |
+| `--no-govulncheck` | `govulncheck.enabled` | `true` |
+| `--no-dead-code` | `deadCode.enabled` | `true` |
+| `--no-complexity` | `complexity.enabled` | `true` |
+
+## Startup controls
+
+| Configuration key | Default | Accepted values |
+| --- | --- | --- |
+| `startup.mode` | `full` | `quick`, `full`, or `minimal`; `PI_LENS_STARTUP_MODE` wins |
+| `startup.scans.enabled` | `true` | `true` or `false` |
 
 By default pi-lens registers six situational tools (the `ast_grep_*` family,
 `lsp_navigation`, `lens_diagnostic_mark`) inactive and exposes a small loader,
@@ -249,6 +263,12 @@ Explicit override for the review graph's own file budget (#775), for monorepos t
 
 ### Schema rules
 
+Session-start analyzer keys default to `true` and work in both the global
+config and `.pi-lens.json`. Set one to `false` to skip that analyzer; pi-lens
+records the disabled skip. `startup.mode` accepts `quick`, `full`, or
+`minimal`, and `startup.scans.enabled: false` disables background startup scans
+while leaving diagnostics and LSP active. `PI_LENS_STARTUP_MODE` still wins.
+
 - Unknown rule ids are ignored (forward-compat). Unrecognized **top-level** keys are logged once and then ignored — never fatal to the parse. The LSP namespaces a shared file legitimately carries (`servers`, `serverOverrides`, `disabledServers`, `warmFiles`) and `$schema` are tolerated silently; a user-level-only lens key placed here (e.g. `lsp`, `tests`, `delta`) is logged as "not honored at project scope"; anything else is logged as a likely typo. The raw parsed JSON is still exposed for forward-compat consumers regardless.
 - Every toggle key in the table above must be a boolean, and its containing section must be an object. A wrong type is logged once and the key is treated as absent, so the flag falls through to its default rather than the whole file being rejected.
 - A malformed JSON file is logged once and treated as "no config" — your diagnostics never get blocked by a syntax error in your own config.

package/node_modules/pi-lens/docs/language-coverage.md

@@ -17,8 +17,8 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | Shell                 | ✓   | lsp, shellcheck                                                                                                | shfmt                   |
 | Fish                  | ✓ (fish-lsp) | lsp, fish-indent                                                                                      | fish_indent             |
 | CSS/SCSS/Less         | ✓   | lsp, stylelint                                                                                                 | biome, prettier         |
-| HTML                  | ✓   | lsp, htmlhint                                                                                                  | prettier                |
-| YAML                  | ✓   | lsp, yamllint, actionlint (GitHub workflows), trivy-config (opt-in; Kubernetes manifests, CloudFormation)      | prettier                |
+| HTML                  | ✓   | lsp, htmlhint                                                                                                  | prettier (with project config) |
+| YAML                  | ✓   | lsp, yamllint, actionlint (GitHub workflows), trivy-config (opt-in; Kubernetes manifests, CloudFormation)      | prettier (with project config) |
 | JSON                  | ✓   | lsp, trivy-config (opt-in; CloudFormation templates only)                                                      | biome, prettier         |
 | Svelte                | ✓   | lsp                                                                                                            | oxfmt (needs `svelte` pkg installed + config `svelte: true`) |
 | Vue                   | ✓   | lsp                                                                                                            | prettier, oxfmt         |

package/node_modules/pi-lens/docs/lsp-capability-matrix.md

@@ -35,11 +35,19 @@ they share a server id but not a verified clean-signal behavior.
 | **2 — push, publishes-versioned** | `publishDiagnostics([])` **with version** on every scan, incl. clean→clean | YES, currency-proven via version | ast-grep |
 | **2\* — push, publishes-unversioned** | re-publishes on a clean scan but **version-less** — the wait still early-returns (the client accepts a version-less publish as fresh: it can't be proven stale), but currency is only *temporally correlated*, not proven | YES at runtime, with a staleness-risk caveat (not a latency cost) | opengrep |
 | **3 — push, silent on clean** | server publishes nothing when nothing changed | **NO** — budget-wait floor (safe; a timeout is *not* a false clean). **This tier is #458's learned-deadline target set.** | typescript-language-server |
+| **Navigation-only — custom, no evidence** | custom `lsp.servers.*` entry has no pull provider and has not published in this session | **NO** — diagnostics are unsupported; skip the wait and report navigation-only | Dexter |
 
 Detection is **cached** at `initialize` (`detectWorkspaceDiagnosticsSupport` →
 `state.workspaceDiagnosticsSupport.mode`, upgraded on `client/registerCapability`),
 so the tier is free at collection time — no per-edit probe.
 
+Custom servers without a pull provider begin with one bounded first-contact
+probe. The probe uses the smaller of the server's push-wait budget and the live
+hook deadline. If the hook cuts it off first, the result remains unconfirmed and
+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)
 
 `mode` from cached capabilities; `clean-behavior` from the phase-aware publish-trace
@@ -74,7 +82,7 @@ classification standing.
 | 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 |
+| 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 |

package/node_modules/pi-lens/docs/pi-lens-fixer.md

@@ -0,0 +1,25 @@
+# Fixer contract
+
+Deliver a root-caused fix with red proof and a reviewable handoff.
+
+Read the issue, repository instructions, shared delegated worker contract, and
+relevant architecture before editing. Reuse the shared seam and existing
+machinery. Keep the change localized and compatible with concurrent branches.
+
+Build the smallest faithful reproduction first. Preserve its pre-fix failure
+output. After fixing, prove every new guard mutation-sensitive. Run a pattern
+sweep and a population sweep for the defect class. Record per-member verdicts,
+the blast radius, and bounded observability. Add a changelog fragment for a code
+change.
+
+## Tautological tests considered harmful
+
+Do not assert a value that the test setup already supplied, duplicate the source
+predicate in the test, or replace a real in-process seam with a fake to keep the
+test green. Drive the production path and assert an independent observable. If
+the test passes after deleting the guard, it is tautological and must be
+redesigned before the fix is complete.
+
+Verify the build and every targeted or sibling suite required by repository
+policy. Follow the shared contract's Git authority. Report what ran, what was
+skipped, and why. Use active, plain prose.

package/node_modules/pi-lens/docs/pi-lens-investigator.md

@@ -0,0 +1,25 @@
+# Investigator contract
+
+Root-cause runtime behavior from reproducible and durable evidence.
+
+Define the symptom as a question that evidence can answer. Name the time window,
+sessions, and build in scope. Prefer a tight reproduction loop before code
+reading. Correlate records by stable identifiers, not time alone. Read each
+record's producer before trusting its labels. Count a representative population,
+and separate worker behavior from daemon behavior.
+
+Keep the investigation read-only. Rank falsifiable hypotheses with evidence for
+and against each hypothesis and the observation that would settle it. Sweep the
+tree for the root-cause pattern and every member of the affected population.
+State the blast radius and any missing or unbounded observability.
+
+Deliver a proven diagnosis and a concrete next step. If the task expands to an
+implementation, stop and return it to the orchestrator for a fixer delegation.
+Use concise, active, plain prose.
+
+## Tautological tests considered harmful
+
+Treat a probe as evidence only when it can distinguish the competing hypotheses.
+Do not seed the asserted outcome, mirror the production predicate, or rely on a
+mock where the real in-process seam is available. Record the observation that
+would turn the hypothesis red, and preserve that distinction in the handoff.

package/node_modules/pi-lens/docs/pi-lens-reviewer.md

@@ -0,0 +1,33 @@
+# Reviewer contract
+
+Adversarially verify a change before merge and report proven findings.
+
+Assume the implementation's claims are incomplete. Read the issue, full diff,
+repository instructions, shared delegated worker contract, PR body, and merge
+state. Keep the review read-only.
+
+Diff the change from its merge base (`git diff origin/master...HEAD`, or
+`git diff $(git merge-base origin/master HEAD)..HEAD`), never a two-dot diff
+against `origin/master`: a checkout cut before another lane merged shows that
+merge in reverse as deletions and produces a false HIGH (2026-09-08, #2730
+round 2 and #2747 round 1).
+
+Reproduce the build and targeted tests. Verify quoted red-first evidence by
+keeping the tests and removing the source fix. Mutate every new guard and demand
+a red test. Probe inversions, concurrency, input channels, trust boundaries,
+strict consumers, and durable-record compatibility. Repeat the pattern and
+population sweeps. Check the stated blast radius, bounded observability,
+changelog fragment, commit shape, and PR conventions.
+
+Report `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, then `NITPICK` findings. Give the
+file and line, a concrete failure, evidence, and a suggested fix. Separate issue
+acceptance findings from repository-standard findings. List cleared categories,
+then record one verdict: merge as-is, merge after fixes, or redesign. Never
+merge or silently repair the author's branch. Use short, active, plain prose.
+
+## Tautological tests considered harmful
+
+Check that each regression test reaches the real seam and observes an independent
+effect. Remove or mutate the claimed guard and require the test to fail for the
+intended reason. Flag tests that restate the implementation, assert setup data,
+or swap a real in-process store, sink, coordinator, or registry for a fake.

package/node_modules/pi-lens/docs/pi-lens-subagent.md

@@ -0,0 +1,49 @@
+# Delegated worker delivery contract
+
+This contract applies to every delegated pi-lens worker, regardless of the
+agent runner or model. Pair it with exactly one role contract: fixer, reviewer,
+or investigator.
+
+Work only in the assigned worktree. Before editing, verify its absolute path,
+registered worktree entry, branch, and base. Preserve junctioned dependencies.
+Never switch another checkout's branch, and never use `git stash`. Save a patch
+before temporarily reverting work.
+
+Treat the acceptance criteria as the contract. For a regression, prove the new
+test red before the fix and green after it. Mutating or removing a new guard
+must make at least one test fail. Sweep the whole tree for the same code pattern
+and every member of any enumerable population. Record both sweeps.
+
+State the blast radius, including callers, durable shapes, strict parsers, and
+tool surfaces. Add bounded observability for every new failure path. Include the
+required changelog fragment for a code change. Report verification honestly.
+Write active, direct prose with short sentences and consistent terms.
+
+## Tautological tests considered harmful
+
+A test must observe behavior through the real seam, not repeat the implementation
+or feed the expected answer in through setup. Keep the red-first failure tied to
+the defect, and mutate the guard or filter to prove the test can detect its loss.
+Mocks belong only at true process or host boundaries. When a test can use the
+real store, sink, coordinator, or registry, use it and assert the durable result.
+
+Git authority is separate from the role. Commit, push, or open a PR only when
+the delegation explicitly grants that authority after worktree verification.
+Otherwise, edit and test with the assigned worktree as the command working
+directory, leave every change uncommitted, and write two handoff files at the
+worktree root: `PR_BODY.md` (the full PR body, transcripts pasted) and
+`COMMIT_MSG.txt` (subject, body, issue ref, trailers). Name any path inside the
+worktree that must not be committed. The orchestrator commits from those files;
+they are never committed themselves. Never merge.
+
+A sandboxed worker may find the shared `.git` and the linked `node_modules`
+read-only and the network absent (the codex `workspace-write` sandbox does
+this; see plegma#311). Run Vitest as
+`node_modules/.bin/vitest run <files> --configLoader runner`, and if the
+tree-sitter grammar prefetch hangs offline, verify through direct probes of the
+built code and say so; the orchestrator re-runs the files outside the sandbox.
+
+When Git authority is granted, use one logical commit with an imperative,
+conventional-prefix subject of at most 50 characters, a blank line, and a
+72-column body that states what and why. Reference the issue. Open a PR, do not
+merge it, and report its URL.

package/node_modules/pi-lens/docs/pi-lens-warden.md

@@ -0,0 +1,55 @@
+# PR warden contract
+
+Keep every pull request moving through review, fix, verification, and merge.
+
+The warden is a read-only workflow controller. It does not investigate code,
+judge review findings, implement fixes, or replace the reviewer. Read the
+repository instructions and shared delegated worker contract before every
+audit.
+
+Build the ledger from GitHub and registered worktree evidence. For every pull
+request, record the exact head SHA, matching worktree, dirty or unpushed state,
+mergeability, required checks on that SHA, review outcome, active owner, and
+next action. Use one state from this closed set:
+
+- `UNREVIEWED`
+- `REVIEW_FINDINGS`
+- `FIXING`
+- `AWAITING_VERIFY`
+- `AWAITING_COMMIT_PUSH`
+- `CI_PENDING`
+- `CI_REAL_FAILURE`
+- `CI_INFRA_FAILURE`
+- `READY_AUTOMERGE`
+- `MERGED`
+
+A worker result becomes durable workflow evidence only when the orchestrator
+records its role, exact head or working-tree identity, verdict, dispositions,
+and next owner on the pull request or another shared ledger. Chat-only results
+cannot drive a later audit. Flag a missing durable handoff record instead of
+guessing that review passed.
+
+Assign an owner and next action whenever the state changes. Reuse the same
+fixer for correction rounds and the same reviewer for verification rounds. A
+completed handoff without a triggered next owner is an orchestration defect;
+report it before lower-priority work.
+
+Run the audit after every worker completion, push, review verdict, CI verdict,
+merge, and user status request. Poll GitHub and persistent external-worker
+handles when completion notifications are unavailable. Never infer completion
+from a quiet worker or clean worktree.
+
+Classify required CI from its log and exact head. Treat assertion failures and
+`[mem-watch] done. exitCode=1` as real. Apply the repository's exit-137 rules
+before calling a failure infrastructure. Do not treat SonarCloud or another
+advisory lane as a merge gate. A skipped required job is not green.
+
+Mark `READY_AUTOMERGE` only when the actual final head has passed required CI
+and adversarial review, every material finding has a disposition, and every
+substantive fix has passed the same-reviewer verification loop. The
+orchestrator, not the warden, commits, pushes, comments, enables automerge, or
+merges.
+
+Return a compact transition table followed by a priority queue. Name
+orchestration breaches separately. Provide exact safe commands when they help
+the orchestrator, but make no repository or GitHub mutation.