---
id: PLN-0077
ticket: pbs-lsp-editor-assistance-wave-1
title: VS Code Consumption and Wave 1 Editor Assistance Validation
status: open
created: 2026-05-08
completed:
tags: [vscode, extension, editor, completion, hover, signature-help, validation]
---

## Objective

Keep the VS Code extension thin while validating that the new LSP-delivered `completion`, `hover`, and `signature help` features actually produce a minimally usable PBS editing experience end to end.

## Background

`DEC-0035` explicitly requires the extension to remain a client/adaptor rather than a second semantic engine. Because VS Code already knows how to consume LSP completion, hover, and signature-help responses, the extension work should be small and mostly about ensuring transport, configuration, and real validation are correct.

## Scope

### Included

- Confirm the extension does not need or gain local semantic tables for stdlib, members, or signatures.
- Adjust only the minimal extension/bootstrap behavior needed for the new LSP features to flow correctly.
- Add verification coverage and manual validation guidance for the full wave.

### Excluded

- Compiler-side editorial resolution logic.
- LSP-side protocol feature implementation.
- Formatter/indentation, code actions, or non-wave-1 IDE features.

## Non-Goals

- Turning the extension into a feature-rich semantic client.
- Adding hardcoded completion/signature content for PBS inside TypeScript runtime code.

## Execution Steps

### Step 1 - Verify thin-client integration boundaries

**What:** Confirm the extension remains a pure LSP consumer for the new features.
**How:** Review and adjust the extension only where necessary so completion, hover, and signature help are obtained from the LSP session without client-side semantic fallback tables.
**File(s):** `tools/vscode-extension/src/**`, `tools/vscode-extension/package.json`.

### Step 2 - Add any minimal structural configuration required by VS Code

**What:** Keep static contribution surfaces minimal and structural.
**How:** If VS Code requires additional structural contribution metadata for the new features, add only that metadata. Do not add curated PBS semantic or signature data into the extension package.
**File(s):** `tools/vscode-extension/package.json`.

### Step 3 - Add validation coverage for end-to-end editor assistance

**What:** Lock the no-local-semantics rule and the end-to-end feature expectations.
**How:** Add tests or deterministic verification steps that ensure:

1. the extension connects and receives the feature set from the server;
2. no local completion/signature tables were introduced;
3. the user-facing wave can be exercised end to end.

**File(s):** `tools/vscode-extension/**`, existing validation harnesses if present, and related docs/test notes.

### Step 4 - Define manual smoke scenarios for wave 1 usability

**What:** Make the wave verifiable as a product experience rather than only a protocol exercise.
**How:** Document and run manual checks for:

1. keyword and local-name completion;
2. imported stdlib/member completion after `.`;
3. hover on locals, imported services, builtin types, and methods;
4. signature help during function/method/constructor calls.

**File(s):** extension verification notes or adjacent implementation docs/tests as appropriate.

## Test Requirements

### Unit Tests

- Any extension-side helpers introduced for structural integration only.

### Integration Tests

- End-to-end or near-end-to-end validation that VS Code consumes the server feature set without local semantic duplication.

### Manual Verification

- Open representative PBS files in VS Code and verify `completion`, `hover`, and `signature help` behavior matches the expected wave-1 scope.

## Acceptance Criteria

- [ ] The extension remains thin and contains no new hardcoded PBS semantic tables for members or signatures.
- [ ] VS Code can consume the new LSP completion, hover, and signature-help responses without extension-side semantic authorship.
- [ ] Wave-1 smoke scenarios are documented and manually verifiable.

## Dependencies

- `DEC-0035` accepted and normatively locked.
- `PLN-0076` for the actual LSP feature delivery.

## Risks

- It is easy to accidentally patch around server gaps with client-local logic; this plan must resist that.
- Validation can become too protocol-centric and miss real usability failures if manual smoke scenarios are weak.