📝 Correct the pi-lsp false-positive finding

The TS1295/TS1287 errors were not an LSP misconfiguration: the server
was still running from an earlier local test that had emptied
package.json, and kept the corrupted project state alive. Driven with
pi-lsp's exact handshake, tsc --lsp --stdio reads tsconfig.json
correctly. Record the real caveat instead: no file watchers, so
tsconfig.json/package.json edits can leave diagnostics stale until the
server restarts.

AGENTS.md

@@ -9,7 +9,7 @@ first-action facts. Do not restate evolving prose here — it will drift.
 
 - Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
 - **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed.
-- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet).
+- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
 - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
 - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
 - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch.

backlog.tasks

@@ -22,11 +22,11 @@ Setup:
     ☐ Fix the declaration emit (`.d.ts` post-step) or stop using relative `.ts` in the declaration surface
     ☐ Reconcile the README/CONTRIBUTING claim that `rewriteRelativeImportExtensions` yields "conventional ESM imports"
     ☐ Add a consumer-resolution test to the suite (durable guard; `attw` currently misses it)
-☐ Document pi-lsp false-positive diagnostics
+✔ Document pi-lsp false-positive diagnostics @done
-    - `lsp_diagnostics` reports TS1295/TS1287 "CommonJS file under `verbatimModuleSyntax`" errors that `check:tsc` never produces — the server is not picking up the repo's `tsconfig.json`
+    - `lsp_diagnostics` reported TS1295/TS1287 "CommonJS file under `verbatimModuleSyntax`" errors that `check:tsc` never produced
-    - AGENTS.md only warns that empty LSP output is inconclusive, not that it can emit false errors
+    - root cause: an earlier local test emptied package.json; the still-running TS7 server (5 min idle timeout) kept the corrupted project state alive and reported it against the real files
-    ☐ Add a line to AGENTS.md: ignore LSP errors that `check:tsc` does not reproduce
+    ✔ No LSP misconfiguration to fix: driven with pi-lsp's exact handshake, tsc --lsp --stdio reads tsconfig.json correctly; hover resolves real inferred types and lsp_diagnostics is clean on a fresh server @done
-    ☐ Or fix the LSP server configuration so it picks up `tsconfig.json`
+    ✔ Added the one real caveat to AGENTS.md: the server does not register file watchers, so tsconfig.json/package.json edits can leave diagnostics stale until it restarts @done
 ✔ Run packaging checks in CI `build` @done
     - `publish:publint` / `publish:attw` only run in the tag-triggered `publish` job, so a PR that breaks packaging stays green until release
     ✔ At minimum add `publish:publint` to the `build` job (offline, fast); `attw` needs a pack @done