pi-lens 4.2.0 → 4.3.0

package/docs/adr/0006-derived-state-benchmark-first.md

@@ -0,0 +1,31 @@
+# ADR 0006: benchmark before a derived-state cache
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+The staleness arc fixed caches whose invalidation keys could not express the
+truth. For signatures, line counts, hashes, and import graphs, a bounded
+request-local recompute can remove that invalidation surface. Tool-run caches
+are a separate class because the expensive operation is the tool run.
+
+## Decision
+
+Do not add a cross-request derived-state cache until a fresh-process benchmark
+shows that request-local recomputation is the cost. A justified cache carries
+the generation from which it was derived.
+
+## Consequences
+
+Cheap derived state has no stale cache to invalidate. Any future cache needs a
+benchmark with a control row, explicit freshness axes, and a measured reason
+that the request-local pass is insufficient.
+
+## Links
+
+- Catalog shape: `AGENTS.md` shape 51.
+- Issue: #1644 closure decision, 2026-09-22.
+- PR: #3253.
+

package/docs/adr/0007-end-to-end-witness-per-seam-slice.md

@@ -0,0 +1,38 @@
+# ADR 0007: end-to-end witness per seam slice
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+Seam umbrellas #1892, #1816, #1193, #1894, and #1844 need evidence that
+survives adapter wiring and records both what the model receives and what the
+degradation ledger recorded. The #3247 round-2 adapter tests establish the
+shape through the pi and MCP turn-end surfaces.
+
+## Decision
+
+Every slice under those seam umbrellas adds one witness test through the real
+host entry: pi `index.ts` `turn_end` to the runtime-context message, or the MCP
+turn-end entry in `clients/mcp/session.ts`. The test commits the rendered
+context message and degradation-ledger rows as a golden fixture under
+`tests/fixtures/witness/<slice>/` and diffs it on every run. The witness is
+owned by the #1605 lane umbrella. Process boundaries, including LSP servers
+and tool binaries, use the real-wire fake server rather than a module mock.
+
+## Consequences
+
+Witnesses are the verifiable, repeatable artifact for each seam slice and
+expose adapter drift at the host boundary. A witness is not the sole mechanism
+at a process boundary: a module mock cannot prove argv, wire framing, process
+lifecycle, or tool output, so those boundaries require the real-wire fake
+server. In-process stores, sinks, coordinators, and dispatchers remain real.
+
+## Links
+
+- Umbrella: #1605.
+- Seam slices: #1892, #1816, #1193, #1894, #1844.
+- Shape: `tests/index-3246-turn-end-delivery.test.ts` and
+  `tests/clients/mcp/session-inline-blocker-dispositions.test.ts`.
+- Adapter evidence: #3247 round 2.

package/docs/adr/0008-turn-end-lane-interface.md

@@ -0,0 +1,165 @@
+# ADR 0008: one `TurnEndLane` interface, and what stays in the composer
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+`clients/runtime-turn.ts` was 4,654 lines with fourteen delivery lanes written
+inline in `handleTurnEnd`. Each lane read its own store, applied its own
+freshness/disposition policy, and formatted its own section into
+`blockerParts`/`advisoryParts`, so the composer stated every lane's rules and no
+lane could be read, tested or changed on its own. #1892's third slice deepens
+the composer into a thin orchestrator over lane modules that share ONE
+interface, one lane per round, with no agent-facing change.
+
+The constraint that shapes the interface is #3264's fold: the turn-end scanner
+stores share ONE `gateFindingsByPathFreshness` call, so a path two stores cite
+is `stat`'d once, spends one stat budget, and writes one bounded decision
+record per delivery instead of up to six. A lane that gated itself would
+re-split that pass the moment a second lane existed.
+
+The second constraint is the delivery-surface registry
+(`clients/finding-delivery-gate.ts`): its `@delivery-surface:` seam scan reads
+exactly `clients/runtime-turn.ts` and `tools/lens-diagnostics.ts`. Code that
+renders an agent-facing section from a file that scan does not read would be an
+unregistered surface, invisible to the mechanism built to enumerate them.
+
+## Decision
+
+**The interface** (`clients/turn-end/lane.ts`) is three stages, and nothing else — no lane id, because nothing would read one:
+
+| Stage | Signature | Owns |
+|---|---|---|
+| collect | `collect(ctx) → Promise<S>` where `S` maps STORE name → `FindingFreshnessSource` | which caches to read, classification, the per-store `citedPath`/`scannedAt`/`onMissing` policy. Structured rows with source identity, never a rendered string. Calls no gate. |
+| gate | `gate(gates: TurnEndLaneGates<S>, ctx) → Kept` | the policy the shared pass cannot apply: dispositions through `filterFindingsByDisposition` (the seam in `clients/dispatch/finding-policy.ts`, ADR 0004), plus any per-store existence/lifecycle contract. `Kept` is lane-private. |
+| render | `render(kept, ctx) → TurnEndLaneParts` | the sections, the display cap, the tier each section belongs to, the per-store suppressed counts, and the location keys it delivered. Returns sections; never pushes. `TurnEndLaneParts` carries a field per tier the composer actually pushes and no others — an unread field is a side channel that drops a lane's output, so the advisory tier joins the type with the lane that renders one. |
+
+`TurnEndLaneContext` is the whole window a lane gets onto the turn: `cwd`, the
+hook's `signal`, `readScannerCache` (memoized per turn by the composer) and
+`peekActionableWarnings`.
+
+**Writers by axis** — what the composer keeps, and why it cannot be a lane's:
+
+| Axis | Owner | Why |
+|---|---|---|
+| Path-freshness pass (stat memo, stat budget, `finding_dead_path_drop` / `finding_stale_line_demote` rows) | composer | A cross-lane resource. Per-lane gating is #3264 undone: N stat passes, N budgets, N records for one filesystem fact. A lane only DECLARES sources. |
+| One read per scanner store per turn | composer (`readScannerCache` memo) | The trivy store is read by the secrets lane and by the CVE/license tiers. Two envelopes of one store in one delivery is the parallel-store shape, and the TTL boundary can fall between the reads. |
+| Disposition application | lane | Per-store anchor identity; only the lane knows which `ProjectDiagnostic` adapter anchors its rows. |
+| Tier order, `blockerParts`/`staleSecretParts`/`advisoryParts` accumulation, the `@delivery-surface:` tags | composer | The tags are what enumerates the surfaces; the scan reads the composer. |
+| Suppressed-by-disposition notice | composer, fed per lane | One bounded notice per turn (#1616), with per-lane attribution. |
+| Turn signature dedupe, `turn-end-findings` cache write, git-guard record, message cap, turn telemetry | composer | Delivery-event properties of the whole turn, not of one lane. |
+| Delivered location keys | lane produces, composer consumes | One secret is reported once across tiers (#131 Mode 3). |
+
+**Registry evidence.** A surface whose render moved into a lane keeps its
+registry `file` as `clients/runtime-turn.ts`, because that is where its tagged
+push seam and its gate call live. Its evidence literal is repinned from the
+partition it used to read (`gitleaksGate.live,`) to the gated store object the
+composer hands the lane (`gitleaksGate,`). That is a weaker pin — it no longer
+states which partition feeds which tier — and the loss is recorded rather than
+hidden: the live/stale split is a lane rule now, pinned behaviourally by
+`tests/clients/runtime-turn-finding-freshness.test.ts` and the witness goldens.
+What the pin still proves is what the registry exists for: the rows came out of
+a real gate call, not a hand-built object.
+
+**Lanes that do not fit, and are not being made to.** Test-runner findings
+(generation/retirement state, a verdict rather than diagnostics, its own
+provenance validation at read), the git-guard latch (a durable second
+writer/consumer with a commit-gate audience) and the agent nudge (session
+read/edit relevance, no findings and no freshness axis at all) stay outside
+this interface. So do the package-pinned trivy CVE/license tiers: they have no
+cited path, so their `collect` would declare no freshness source and their
+honesty mechanism is the age label, not the gate.
+
+**One lane is one delivery contract, not one store.** The secrets lane
+(`clients/turn-end/lanes/secrets.ts`) owns BOTH secret stores, because #131
+Mode 3 collapses gitleaks, trivy-secrets and ast-grep by LOCATION into one
+blocker section with combined provenance, and the demoted tier merges the same
+two stores. A "gitleaks-only" lane would leave every rendering rule in the
+composer and move only a cache read.
+
+## Amendment — 2026-09-23: the advisory tier joins `TurnEndLaneParts`
+
+`TurnEndLaneParts` gains ONE field, `advisoryParts?: readonly string[]`, with
+the govulncheck lane (`clients/turn-end/lanes/govulncheck.ts`). This is the
+amendment the Decision above anticipated ("the advisory tier joins the type
+with the lane that renders one"), not a widening of the rule.
+
+**Why it was withheld until now.** The rule is "a field per tier the composer
+PUSHES, and no others", because a field the composer does not read is a side
+channel that silently drops a lane's whole output (AGENTS.md shape 5). The
+secrets lane renders no advisory, so an `advisoryParts` shipped with the
+interface would have been exactly that: a slot a later lane could fill and lose.
+The field, the composer's push and the surface's registry id therefore move
+together, in one round, as one claim.
+
+**What the composer pushes it into.** `handleTurnEnd`'s `advisoryParts` array
+(`clients/runtime-turn.ts`), under the existing tag
+`// @delivery-surface: runtime-turn:govulncheck-advisory`, at the same position
+in the tier order the inline block occupied. The tag is what makes the tier a
+registered delivery surface rather than a string, and
+`tests/config/turn-end-lane-boundaries.test.ts` already listed `advisoryParts`
+in the tier-push rule it reds on — so a lane that pushes its own advisory was
+forbidden before the field existed, and still is.
+
+**What did NOT change.** Still three stages; still no lane id; still no fourth
+method. The `runtime-turn:govulncheck-advisory` registry entry keeps its `file`,
+its `gated` mode and its evidence literal `scannerGates.govulncheck` unchanged
+— the composer still binds that gate arm itself and hands it to the lane, so
+unlike the secrets repin nothing was weakened here.
+
+**The interface question this lane was asked and did not need to answer.** The
+brief asked how a lane declares "no freshness source" honestly, since a
+package-pinned row (trivy CVE/license) has no path to stat. The state table is:
+
+| Lane's store | has a cited path | honesty mechanism | fits the interface today |
+|---|---|---|---|
+| govulncheck | yes (first trace frame with a filename) | the shared gate, `onMissing: "demote"` | yes — this round |
+| gitleaks / trivy-secrets | yes (`finding.file`) | the shared gate, `onMissing: "drop"` | yes — #3269 |
+| trivy CVE / license | no — pinned by package, not by file | `formatCacheAgeLabel`, the registry's `labeled` mode | NO |
+| a finding whose `citedPath` returns `undefined` for SOME rows | mixed | the gate leaves the uncited row live and gates the rest | yes — already handled per row |
+
+The last row is the one that matters for "no freshness source": the gate already
+takes `citedPath` returning `undefined` as "leave live", per FINDING, so a lane
+with a partially-uncited store needs nothing new (the govulncheck witness pins
+it: `GO-2026-0103` has an empty trace and renders by module). A store where
+EVERY row is uncited is a different animal — it is not a gated lane at all, it
+is a `labeled` one, and giving it a `sources: {}` `collect` would let it pass
+the composer's gate with an empty declaration and look gated in the registry
+while nothing checked anything. That is the second exception the brief said not
+to bend the lane around, so it is not added: the labeled lanes need a `label`
+stage (an age string the composer renders into the header) before they can be
+extracted, and that is the design decision of the round that extracts one.
+
+## Consequences
+
+- The composer no longer states a govulncheck rule (2026-09-23): 4,438 →
+  4,403 lines, and the six rules the block held (the `demote`/first-frame
+  freshness declaration, the both-arm disposition anchor, the stale-line
+  withholding and marker, the module/package fallback, the fix hint and the
+  display cap) are stated once, in the lane.
+- The composer no longer states a secrets rule: 4,654 → 4,438 lines, and the
+  ten rules the block used to hold (cache key, classification budget and
+  fail-open, blocking filter, freshness declaration, two disposition anchors
+  over both arms, location dedupe, ast-grep enrichment, display cap, both
+  preambles, demoted-row identity) are stated once, in the lane.
+- Extracting a lane moves code out from under two mechanisms that read only
+  `clients/runtime-turn.ts`, so `tests/config/turn-end-lane-boundaries.test.ts`
+  walks `clients/turn-end/` and reds if a lane pushes into a tier or calls the
+  freshness gate itself. Both rules name the recurrence they prevent.
+- Registrations move with the code: the `bounded()` call-site registry entry,
+  the one-hop unbounded-await pin, and the delivery-surface marker exemption
+  all name the lane file now. A lane is a new file every directory-scanning
+  governance suite sees.
+- The next lanes are extracted one per round against this interface. A lane
+  that needs a stage this interface does not have is a finding to report, not a
+  fourth method to add quietly.
+
+## Links
+
+- Umbrella: #1892. Previous slices: #3264 (the shared freshness pass), #3269
+  (this interface and the secrets lane).
+- Witness convention: docs/adr/0007-end-to-end-witness-per-seam-slice.md.
+- Disposition seam: docs/adr/0004-disposition-policy-seam.md.
+- Registry and evidence rules: `clients/finding-delivery-gate.ts`.

package/docs/adr/0009-reported-path-attribution.md

@@ -0,0 +1,114 @@
+# ADR 0009: reported-path attribution is one seam, based on the runner cwd
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+Every runner that parses a tool's textual or JSON output has to answer one
+question per reported line: *is this diagnostic about the file the dispatcher
+ran me for?* Twelve sites answered it with their own predicate — a bare `===` or
+`!==` over two `path.resolve` results, a `path.resolve` with NO base argument, a
+`path.posix.basename` compare, and two `endsWith` compares. #209 and #3277 are
+the shipped defects of the first two shapes: a spelling that differs only in
+case is the SAME file on Windows and on a case-folding POSIX mount, so the
+compare dropped every finding for the edited file and the run reported clean.
+#3278 measured the population at ~11 and #1193 recorded the fold verdict.
+
+The state space, written before the first edit. Left = the path the tool
+printed. Right = `path.resolve(ctx.filePath)`, which is
+`normalizeMapKey`-canonical and absolute by the #2016 invariant.
+
+| axis | value | consequence |
+|---|---|---|
+| host folds case | win32 always; POSIX only on a case-folding mount (APFS, `nocase` vfat/ntfs3/cifs) | a `process.platform === "win32"` test is wrong in both directions on APFS. Only the filesystem knows, so the predicate must ask it. |
+| reported spelling | absolute (the tool echoes our argv), relative to the tool's own cwd, relative to a package/base directory it chose, or basename-only | only the tool's OWN cwd is a base the caller can supply; `process.cwd()` is the extension's and is a different directory whenever `resolveRunnerCwd` returns a nested language root. |
+| separators after `path.resolve` | host-native on both sides; a foreign separator survives only embedded in the reported string | separator folding can only MERGE, never split. |
+| symlinked project dir | `pathsEqual` does NOT resolve symlinks on POSIX (`clients/path-utils.ts:181`, deliberate) | a project entered through a directory symlink can still mis-match; that is a property of the shared seam, unchanged by this decision (#3276's recorded output). |
+| purpose | identity test of ONE file, per reported line — not a stored key, not set membership | asks for an equality predicate, not a key derivation. |
+
+Candidate seams: `normalizeEphemeralMapKey` is rejected by its own contract
+(`clients/path-utils.ts:488-490` — "never … compared against externally-supplied
+paths where symlink / real-casing resolution actually matters"; the left side is
+literally an external process's output, and it folds case on
+`process.platform === "win32"` only). `normalizeFilePath`/`normalizeMapKey` are
+the right rule in the wrong shape: the caller would still hold the comparison
+and re-derive both keys. A NEW `reportedPathMatchesTarget(reported, { cwd,
+target })` helper fails the deletion test — removing it would put back the same
+single expression at each call site rather than concentrating anything — and it
+would hide the comparison from the #1193 sweep's call-site walk while raising
+the helper count.
+
+## Decision
+
+The predicate is `pathsEqual(path.resolve(<the cwd the tool ran in>, reported),
+absTarget)`, written INLINE at each call site. It is not a new helper: it is the
+call shape `clients/dispatch/runners/terragrunt.ts:90`,
+`elixir-check.ts:63` (#3276) and `go-vet.ts:107` (#3277) already use, so this
+decision migrates the remaining members onto an existing seam and adds nothing.
+A parse function that does not receive the runner cwd takes it as a parameter;
+no parse function resolves a reported path against `process.cwd()`.
+
+Absence is enforced by `tests/config/reported-path-attribution-sweep.test.ts`, a
+shrink-only census of runner sites that still hold their own predicate.
+`tests/config/path-key-fold-sweep.test.ts` counts folds that EXIST and therefore
+structurally cannot see a member with no fold at all — measured on #3277, where
+mutating `go-vet.ts` to a hand-rolled case fold left that sweep green.
+
+A member's fold is admitted only with its premise established: what spelling
+does this tool really emit under OUR invocation? Where the tool echoes the
+absolute path we hand it as argv, the fold is behaviour-preserving and its tests
+say so, rather than feeding a spelling the tool never emits.
+
+## Consequences
+
+The path-case rule exists once, in `clients/path-utils.ts`; no runner holds a
+`process.platform` test or a `toLowerCase` for this question. `pathsEqual` costs
+a `realpathSync.native`/`existsSync` per reported line, which is bounded by the
+tool's own output size on a parse path that already allocates per line.
+
+Two directions are now pinned per member: the tool's real spelling attaches, and
+a different file's finding does not. On a case-folding host the case-variant
+spelling attaches too, and on a case-sensitive host it must not — asserted from
+the filesystem's own answer, never from `process.platform`.
+
+The predicate still cannot see through a directory symlink on POSIX, and a
+runner that needs that must say so at its own call site rather than re-deriving
+a local rule. It also cannot SPLIT a separator: `pathsEqual` folds `\` to `/` on
+every platform (`clients/path-utils.ts:231`), so a POSIX file literally named
+`a\b.gleam` stays merged with `a/b.gleam` after a member's own hand-rolled fold
+is deleted. Deleting the local fold removes a second, divergent copy of the rule;
+it does not change that answer.
+
+Two amendments from #3285 / #3286, the two remainders:
+
+1. The CAPTURE is part of this decision, not a detail before it. A tool renders
+   its location line however it likes, and `gleam` renders through
+   `codespan_reporting`, whose locus line wraps the path in a `┌─` gutter. A
+   suffix compare tolerates that decoration and an equality predicate cannot, so
+   a member whose reported path arrives decorated moves the decoration out of the
+   captured group in the same change — and its premise is a vector generated by
+   the upstream RENDERER (`tests/fixtures/gleam-codespan/`), not a transcription
+   of it. The same rule covers colour: a tool that may emit SGR codes goes
+   through `stripAnsi` before an anchored capture.
+2. The population is runners AND tool clients (`clients/*-client.ts`). The autofix
+   half of a tool lives in its client, `ruff-client.ts` held the same bare `!==`,
+   and a detector scoped to `clients/dispatch/runners/**` structurally could not
+   see it. Widening cost exactly one non-member registration
+   (`clients/test-runner-client.ts`, two self-derived directories).
+
+## Links
+
+- Umbrella: #1193 (P3 fold), #3278 (the population).
+- Precedents: #3276 (`elixir-check`), #3277 / PR #3281 (`go-vet`).
+- Shipped defects: #209, #3277.
+- Detector: `tests/config/reported-path-attribution-sweep.test.ts`.
+- Cells: `tests/clients/dispatch/runners/reported-path-attribution.test.ts`.
+- Witness (ADR 0007): `tests/fixtures/witness/runner-outcome-eslint-golangci/golangci-lint-relative-path.txt`.
+- Remainders, both now closed: `gleam-check.ts` (#3285 — its `endsWith` was
+  load-bearing for `codespan_reporting`'s gutter) and `clients/ruff-client.ts`
+  (#3286 — outside the runner population).
+- Upstream vectors: `tests/fixtures/gleam-codespan/` (gleam v1.18.1 +
+  codespan-reporting 0.13.1), `tests/fixtures/ruff-json/` (ruff 0.16.8).
+- Cells for the client half: `tests/clients/ruff-client-reported-path.test.ts`.

package/docs/adr/README.md

@@ -0,0 +1,26 @@
+# Architecture decision records
+
+Each record is `NNNN-title.md` and uses the same short shape: number/title,
+status, date, Context, Decision, Consequences, and Links. Records capture a
+settled design decision; observations without a decision remain in the defect
+catalog or issue history.
+
+The catalog is the index for defect shapes. A shape that records a decision
+links its ADR in `AGENTS.md`; ADR links point to the catalog shape, the issue
+that supplied the question, and the PR or brief that settled it. Use `refs`
+for work that remains open and `closes` only when its acceptance criteria are
+complete.
+
+## Seed catalog
+
+| ADR | Decision | Catalog shape | Status |
+|---|---|---:|---|
+| [0001](0001-stale-advisory-live-arm.md) | Stale advisory arm skips disposition policy; live arm applies it. | 10 | Accepted |
+| [0002](0002-workspace-hash-rendezvous.md) | `workspaceHash` is pure cross-process rendezvous derivation. | 1, 2 | Accepted |
+| [0003](0003-git-guard-latch-writer.md) | Git-guard latch is a separate writer on the durable record. | 24 | Accepted |
+| [0004](0004-disposition-policy-seam.md) | Dispositions fold onto `applyFindingPolicy`; no new store before measured #1892 work. | 10, 26 | Accepted |
+| [0005](0005-tool-availability-enforcement-seam.md) | Tool availability is one seam by enforcement, with migrate-on-touch. | 52 | Accepted |
+| [0006](0006-derived-state-benchmark-first.md) | No cross-request derived-state cache without a fresh-process benchmark. | 51 | Accepted |
+| [0007](0007-end-to-end-witness-per-seam-slice.md) | Every seam slice commits an end-to-end host witness and degradation ledger artifact. | #1605 umbrella; #1892, #1816, #1193, #1894, #1844 | Accepted |
+| [0009](0009-reported-path-attribution.md) | Reported-path attribution is `pathsEqual` against the runner cwd, inline at each call site. | 2, 34, 38; #1193, #3278 | Accepted |
+| [0008](0008-turn-end-lane-interface.md) | One `TurnEndLane` interface; `handleTurnEnd` stays a thin orchestrator over lane modules. | #1892 umbrella; #3264, #3269 | Accepted |

package/docs/agent-tools.md

@@ -46,7 +46,24 @@ same gate rather than bypassing it.
   `workspace`; explicit `paths` always win over `scope`). `severity` is a
   threshold, not an exact filter: `error` shows only errors; `warning` adds
   warnings; `information` adds information; `hint`/`all` (default) show every
-  tier. Legacy `mode`: `delta` (current turn), `all` (resurfaces stale
+  tier. `source=lsp` reads a file's on-disk content and will not sync it to a
+  language server past **2 MiB or 5000 lines** (`clients/runtime-config.ts`
+  `pipeline.lspMaxFileBytes`/`lspMaxFileLines`, checked in
+  `clients/lsp/content-limits.ts`) — not env-tunable today. A file over that
+  bound gets an explicit `file too large for LSP diagnostics (<N> bytes/lines
+  > <limit>)` result instead of stale or partial diagnostics. This is a
+  *different* 2 MiB from the auto-fix full-content attachment cap described in
+  [agent-guide.md](agent-guide.md), section 6 ("Auto-format / auto-fix
+  timing") — the two caps currently share one constant
+  (`RUNTIME_CONFIG.pipeline.lspMaxFileBytes`) but gate unrelated behaviors
+  (LSP sync vs. tool-result content attachment) and can diverge independently
+  in the future. Separately, every save-triggered edit now sends the server a
+  `textDocument/didSave` when it declared `textDocumentSync.save` — with the
+  file text when the server asked for it (`includeText`) and the file is
+  within the same bound, otherwise the save is still sent but without `text`
+  (never dropped outright); this is what makes save-triggered servers like
+  Expert (Elixir) re-diagnose an edit made through pi-lens (refs #3405,
+  #3408). Legacy `mode`: `delta` (current turn), `all` (resurfaces stale
   blockers dropped from turn context), `full` (project-wide scan).
 - **`lens_diagnostic_mark`** — Triage a diagnostic: `false-positive` /
   `suppress` (writes an inline `pi-lens-ignore` comment) / `defer`

package/docs/ast-grep_rules_catalog.md

@@ -2,7 +2,7 @@
 
 <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
 
-pi-lens bundles **481 enabled** ast-grep rules (297 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
+pi-lens bundles **482 enabled** ast-grep rules (298 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
 
 See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `rules/ast-grep-rules/rules/` (pi-lens), `rules/ast-grep-rules/coderabbit/rules/` (vendored).
 
@@ -260,7 +260,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `openssl-cbc-static-iv-php` | warning | no | CodeRabbit | Static IV used with AES in CBC mode. Static IVs enable chosen-plaintext attacks against encrypted data. |
 | `search-active-debug-php` | warning | no | CodeRabbit | Debug logging is explicitly enabled. This can potentially disclose sensitive information and should never be active on production systems. |
 
-### Python (98)
+### Python (99)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
@@ -271,7 +271,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `hashids-with-flask-secret-python` | warning | no | CodeRabbit | The Flask secret key is used as salt in HashIDs. The HashID mechanism is not secure. By observing sufficient HashIDs, the salt used to cons… |
 | `insecure-cipher-algorithm-rc4-python` | warning | no | CodeRabbit | Detected ARC4 cipher algorithm which is considered insecure. This algorithm is not cryptographically secure and can be reversed easily. Use… |
 | `jwt-python-hardcoded-secret-python` | warning | no | CodeRabbit | Hardcoded JWT secret or private key is used. This is a Insufficiently Protected Credentials weakness: https://cwe.mitre.org/data/definition… |
-| `no-assert-tuple` | error | no | pi-lens | Assert should not be called on a tuple literal |
+| `no-assert-tuple` | warning | no | pi-lens | Assert should not be called on a tuple literal |
 | `no-aws-access-key-literal` | error | no | pi-lens | AWS access keys should not be hardcoded — use IAM roles, environment variables, or AWS Secrets Manager |
 | `no-aws-apigateway-no-auth` | error | no | pi-lens | AWS API Gateway should require authentication |
 | `no-aws-s3-public-access` | error | no | pi-lens | S3 buckets should not grant access to all users or authenticated users |
@@ -361,6 +361,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `python-webrepl-empty-password-python` | warning | no | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
 | `python-webrepl-hardcoded-secret-python` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `reducible-list-comprehension` | warning | yes | pi-lens | A list comprehension is unnecessary here; use a generator expression |
+| `unchecked-numeric-parse-python` | warning | no | pi-lens | int()/float() without try/except — raises ValueError on non-numeric input |
 | `unchecked-throwing-call-python` | error | no | pi-lens | Call without try/except — throws on invalid input or missing file |
 
 ### Ruby (20)

package/docs/configuration.md

@@ -5,7 +5,7 @@ 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. |
+| `~/.pi-lens/config.json` | the machine | Your defaults across every project. The winning global location is selected by the [global-location table](#global-config-location); see [environment variables](environment-variables.md) for the knobs. |
 
 Both files have the same shape, with one exception noted below the example:
 everything LSP-related lives under an `lsp` namespace inside them.
@@ -86,6 +86,60 @@ Subsystem-specific env overrides follow the same shape: a
 `reviewGraph.maxFiles`. `docs/environment-variables.md` and `docs/settings.md`
 are the per-setting references.
 
+### Global config location
+
+The global file is selected by this order, highest precedence first. The
+canonical default is still `~/.pi-lens/config.json`; `PI_LENS_HOME` relocates
+machine-generated data and state, not this file. This is the complete truth
+table for the three existence axes.
+
+| `PI_LENS_CONFIG_PATH` | `~/.pi-lens/config.json` exists | `PI_CODING_AGENT_DIR` set and `extensions/pi-lens.json` exists | Winner |
+| --- | --- | --- | --- |
+| unset | no | no | `~/.pi-lens/config.json` (canonical default) |
+| unset | no | yes | `$PI_CODING_AGENT_DIR/extensions/pi-lens.json` |
+| unset | yes | no | `~/.pi-lens/config.json` (grandfathered existing file) |
+| unset | yes | yes | `~/.pi-lens/config.json` (the host file is shadowed; shadowed file reported once per session (#3299)) |
+| set | no | no | the explicit `PI_LENS_CONFIG_PATH` file |
+| set | no | yes | the explicit `PI_LENS_CONFIG_PATH` file |
+| set | yes | no | the explicit `PI_LENS_CONFIG_PATH` file |
+| set | yes | yes | the explicit `PI_LENS_CONFIG_PATH` file |
+
+If an existence probe for a recognized candidate errors (for example,
+`ENOTDIR`, `EACCES`, or `ELOOP`), that candidate's tier is retained rather
+than falling through to a lower location. The subsequent read reports the
+degraded config under `PILENS_CFG_0001`; a probe error is not treated as
+absence.
+
+pi-lens does not write this file. Create or edit it yourself, then start a new
+process. For an XDG-like setup, put generated data and state at a durable data
+root and choose one config surface:
+
+```sh
+export PI_LENS_HOME="$HOME/.local/share/pi-lens"
+
+# XDG-shaped host: use its config directory.
+export PI_CODING_AGENT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/pi"
+mkdir -p "$PI_CODING_AGENT_DIR/extensions"
+```
+
+For hosts without `PI_CODING_AGENT_DIR`, use an explicit config path instead:
+
+```sh
+export PI_LENS_CONFIG_PATH="${XDG_CONFIG_HOME:-$HOME/.config}/pi-lens/config.json"
+mkdir -p "$(dirname "$PI_LENS_CONFIG_PATH")"
+```
+
+When migrating an existing `~/.pi-lens/config.json`, create the new file first
+and delete the old file second. While both exist, the old file wins by design;
+deleting it first would leave the process without the intended settings. Copy
+the file (or hand-author it, since pi-lens has no writer), verify the new
+location, then run `rm "$HOME/.pi-lens/config.json"` to opt out of
+grandfathering. If the new host file is later deleted, the old file wins again
+while it exists; with neither file present, the canonical default path is used.
+
+See also the [environment-variable reference](environment-variables.md#config-location)
+and [settings overview](settings.md#the-three-ways-to-configure-pi-lens).
+
 ### One exception: `lsp.disabledServers` is a denial, not a value
 
 Ordinary settings are last-tier-wins. A **denial** is not, because the tier