Complete Agent LSP Navigation: semantic navigation/discovery, one-hop calls, maintainable reviewed registry updates, and representative Go/TypeScript/C++ use.
Build on MVP; 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.
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
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.
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.
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.
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.
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.
---
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.