--- id: PX-PLAN-LSPCP6R4 type: plan title: Complete LSP Navigation spec: PX-SPEC-LSP4N8Q2 status: approved depends_on: - PX-PLAN-LSPMV8Q2 --- ## Outcome Complete [Agent LSP Navigation](../../specs/PX-SPEC-LSP4N8Q2-agent-lsp-navigation/index.md): semantic navigation/discovery, one-hop calls, maintainable reviewed registry updates, and representative Go/TypeScript/C++ use. Build on [MVP](../PX-PLAN-LSPMV8Q2-lsp-navigation-mvp/index.md); preserve its usable queries, lifecycle bounds, and uncertainty contract. ## Behavior dependencies MVP queries underpin richer navigation and registry maintenance; integrated cross-server use exercises both. ```mermaid flowchart TB M["MVP semantic queries"] --> N["Types and implementations"] N --> S["Discover symbols"] S --> C["Inspect one-hop calls"] M --> R["Refresh reviewed defaults"] C --> V["Use Go, TypeScript, and C++"] R --> V ``` ## Ordered behaviors 1. **Follow types and implementations.** Extend `extensions/lsp/src/tool.ts`, `client.ts`, and `result.ts` with type definition and implementations; retain one tool and shared bounds. Check current server capabilities and applicable registrations, not a maintained per-language support matrix. Normalize supported location forms and preserve meaningful server failures; do not substitute syntactic approximations. 2. **Discover declarations without an initial source position.** Add document/workspace symbols through the same tool/client/result modules; `registry.ts` resolves workspace-specific discovery context. Support hierarchical/flat document results and capability-appropriate workspace symbol resolution. Keep qualified names, locations, and result caps compact; disclose server completeness as unknown even when no client truncation occurred. Verify the experimentally observed case where server limits omit known symbols without a truncation marker. 3. **Inspect incoming and outgoing calls.** Add two-step call hierarchy handling within `tool.ts`/`client.ts`; preserve prepared server metadata and its session/source context. Ambiguous preparation returns actionable candidates; an explicit selection continues the query, while invalidated selections are rejected or re-resolved visibly. `source.ts`/`result.ts` attribute incoming call-site ranges to returned callers and outgoing ranges to the queried caller, including cross-file edges. Bound work to one hop; distinguish preparation/no-result/empty-relationship evidence without inventing readiness or runtime completeness. 4. **Refresh supported defaults without runtime catalog coupling.** Add extension-owned development helper `scripts/registry.ts`, explicit source/local-override policy under `registry/`, and `registry-refresh` Mise task. Fetch pinned Helix revisions as primary data; permit explicitly selected lsp-bridge supplements only where needed by supported profiles. Reuse existing repository parsing tools where suitable; upstream catalogs are data, never executable editor configuration. Normalize only launch, language/file/root, required initialization/settings, and provenance fields; reject unresolved machine paths/placeholders and preserve license notices. Compare imported changes with prior source values and local overrides; surface conflicting field changes rather than silently choosing a winner. Produce reviewable diffs; replace `registry/servers.json` only after successful validation, leaving previous usable data intact on fetch/parse/conflict/interruption failures. Runtime `registry.ts` consumes only packaged reviewed data, never importer code, upstream URLs, or checkout-relative dependencies. 5. **Use complete navigation across representative servers.** Add reviewed TypeScript language-server and clangd profiles alongside gopls; preserve explicit missing-executable behavior and no runtime installation. Extend source/session tests for distinct roots, profile/config changes, URI/platform paths, non-ASCII positions, source-context races, and late responses. `README.md`, tool descriptions, and results explain supported operations, actionable ambiguity, unknown completeness/freshness, and native-server side-effect boundaries without adding a sandbox policy. Rebuild and verify relocated package plus live Pi sessions; registry refresh or protocol dependency updates must not silently alter public tool semantics. ## Verification - Extend required Pi contract tests and owned protocol peers across every added operation, unsupported capabilities, registration changes, ambiguity/selection invalidation, budgets, and server-requested mutation denial. - Importer fixtures cover pinned sources, local overrides, simultaneous upstream/local edits, unavailable catalogs, malformed data, licensing/provenance, interrupted publication, and deterministic regeneration. - `registry-refresh` remains out of normal runtime/startup and fast test loops; importer tests use local fixtures, not live upstream availability. - Extend `//extensions/lsp:live` for built native Pi tool with real gopls, TypeScript language server, and clangd; report actual capabilities and unavailable operations, never approximate fallbacks. - Real-server checks cover known declarations/usages, both call directions with separate caller/callee files, UTF-8/UTF-16 conversion, edits, and clean process exits. - Deterministic peers cover naturally hard-to-trigger ambiguity, unsupported operations, timeouts, stale selections, and cancellation races; do not claim these replace real-server behavior. - Re-run extension `lint`, `test`, `check`, `verify-package`, live acceptance, and root `//:check` at integration; validate added Mise configuration and remeasure context impact. ## Exit criteria - [ ] Every in-scope operation is reachable through one Pi tool, capability-dependent, bounded, and faithful to the spec's uncertainty semantics. - [ ] Cross-file call-site ownership and actionable ambiguous-target selection are verified without recursive graph construction. - [ ] Explicit registry refresh preserves reviewed local decisions and provenance, reports conflicts, and cannot publish partial/unusable defaults. - [ ] Packaged registry works without upstream catalog access or repository files; installed-server prerequisites remain external and explicit. - [ ] Representative native Pi/server queries, adversarial lifecycle cases, relocation, and existing MVP regressions pass with recorded evidence. - [ ] Every spec acceptance criterion has concrete verification or remains explicitly blocked; unverified behavior is not marked complete. ## Scope guard No diagnostics UI, completion integration, rename, formatting, code actions, automatic repairs, server installation, Helix runtime, generic editor-config interpreter, or automatic protocol/catalog migration.