prometeu-studio/discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md

id	ticket	title	status	created	completed	tags
PLN-0077	pbs-lsp-editor-assistance-wave-1	VS Code Consumption and Wave 1 Editor Assistance Validation	open	2026-05-08		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.