itsallcode · kaklakariada · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@
 # Stores VSCode versions used for testing VSCode extensions
 /extension/.vscode-test/
 /extension/out/
+/extension/server/
 
 /.serena/
 

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -6,10 +6,10 @@
 		"source.fixAll": "explicit"
 	},
 	"files.exclude": {
-		"extension/out": false // set this to true to hide the "out" folder with the compiled JS files
+		"extension/out": true
 	},
 	"search.exclude": {
-		"extension/out": true // set this to false to include "out" folder in search results
+		"extension/out": true
 	},
 	// Turn off tsc task auto detection since we have the necessary tasks as npm scripts
 	"js/ts.tsc.autoDetect": "off"

diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # openfasttrace-vscode-extension
 
-This is the README for your extension "openfasttrace". After writing up a brief description, we recommend including the following sections.
+OpenFastTrace provides a VS Code client for the OpenFastTrace language server.
+This initial slice launches the bundled server and supports the standard
+`workspace/symbol` request.
 
 [![Build](https://github.com/itsallcode/openfasttrace-vscode-extension/actions/workflows/build.yml/badge.svg)](https://github.com/itsallcode/openfasttrace-vscode-extension/actions/workflows/build.yml)
 [![Quality gate status](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
@@ -18,28 +20,27 @@ This is the README for your extension "openfasttrace". After writing up a brief
 
 ## Features
 
-Describe specific features of your extension including screenshots of your extension in action. Image paths are relative to this README file.
-
-For example if there is an image subfolder under your extension project workspace:
-
-\!\[feature X\]\(images/feature-x.png\)
-
-> Tip: Many popular extensions utilize animations. This is an excellent way to show off your extension! We recommend short, focused animations that are easy to follow.
+The extension starts the staged Java language-server distribution and uses LSP
+for portable editor behavior. The first supported request is
+`workspace/symbol`; it currently returns no symbols until workspace indexing is
+implemented.
 
 ## Requirements
 
-If you have any requirements or dependencies, add a section describing those and how to install and configure them.
+The extension requires Java 21 or later. It uses `openfasttrace.java.home` when
+configured, then `JAVA_HOME`, then the `java` executable on `PATH`. The server
+distribution is packaged with the extension, so no global server installation
+is needed.
 
 ## Extension Settings
 
 Include if your extension adds any VS Code settings through the `contributes.configuration` extension point.
 
 For example:
 
-This extension contributes the following settings:
-
-* `myExtension.enable`: Enable/disable this extension.
-* `myExtension.thing`: Set to `blah` to do something.
+This extension contributes `openfasttrace.java.home`, an absolute path to a
+Java 21 or later runtime. Configure it when VS Code cannot find a suitable
+runtime through `JAVA_HOME` or `PATH`.
 
 ## Known Issues
 

diff --git a/build.gradle b/build.gradle
@@ -23,7 +23,6 @@ sonar {
 requirementTracing {
   inputDirectories = files('doc')
   reportVerbosity = 'FAILURE_DETAILS'
-  filteredArtifactTypes = ['feat', 'req', 'scn']
   filteredTags = ['mvp']
   filterAcceptsItemsWithoutTag = false
 }

diff --git a/doc/changesets/02-integrate-lsp.md b/doc/changesets/02-integrate-lsp.md
@@ -0,0 +1,95 @@
+# 02 Integrate the Language Server
+
+## Goal
+
+Connect the VS Code extension to the standalone Java language server and prove
+that the packaged server can complete a standard LSP request from the VS Code
+client.
+
+## Scope
+
+In scope:
+
+* Launch the Java 21 or later LSP server over stdio from the server application
+  distribution.
+* Start and stop the VS Code language client with the extension lifecycle.
+* Stage the server distribution as an extension asset for development and
+  packaging.
+* Advertise and handle the initial `workspace/symbol` capability so the
+  integration test exercises a real request/response round trip.
+* Add the required extension integration test, dependency updates, trace
+  coverage, and developer documentation.
+
+Out of scope:
+
+* Full OFT parsing, indexing, navigation, completion, semantic tokens, and
+  trace execution.
+* Trace profiles, structured trace views, snippets, and editor highlighting.
+* Packaging or publishing workflow beyond making the server distribution
+  available in the extension asset layout.
+
+## Design References
+
+* [System Requirements](../system_requirements.md)
+* [Design](../design.md)
+* [LSP-first Architecture](../design/architecture.md)
+* [Quality Requirements](../design/quality_requirements.md)
+
+## Strategy
+
+Use `vscode-languageclient/node` with a stdio `ServerOptions` executable. The
+client resolves Java in the documented order (`openfasttrace.java.home`,
+`JAVA_HOME`, `PATH`), validates Java 21 or later before launch, and reports an actionable
+startup error. The client launches the staged Gradle `installDist` executable;
+the server keeps stdout exclusively for LSP traffic. The first portable server
+feature is `workspace/symbol`, initially returning an empty result while the
+workspace index is implemented in a later changeset.
+
+## Task List
+
+### Requirements And Design
+
+- [x] Confirm the existing MVP requirements and LSP-first architecture remain
+      accurate for this incremental integration.
+- [x] Add or update traced `impl` and `itest` items for client startup,
+      capability negotiation, and the workspace-symbol round trip, all tagged
+      `mvp`.
+- [x] Extend the requirements-tracing verification configuration to include the
+      new design, implementation, and integration-test chain.
+
+### Implementation
+
+- [x] Add the locked `vscode-languageclient` runtime dependency.
+- [x] Implement extension client lifecycle, document selector, Java resolution,
+      server executable selection, startup error handling, and disposal.
+- [x] Add Gradle tasks/dependencies to build `:server:installDist` and stage its
+      output under the extension’s ignored server asset directory.
+- [x] Advertise `workspaceSymbolProvider` in the Java server and implement the
+      workspace-symbol request with an empty, non-null result.
+- [x] Remove the placeholder hello-world activation path and register only the
+      LSP-backed extension behavior for this slice.
+
+### Verification
+
+- [x] Add a VS Code integration test that activates the extension, waits for the
+      client to become ready, sends `workspace/symbol`, and asserts a successful
+      empty response from the live Java server.
+- [x] Keep the existing Java capability test and add protocol-level coverage for
+      workspace-symbol capability negotiation and response compatibility.
+- [x] Run server tests, extension compile/lint/unit/integration tests, the full
+      Gradle build, and the MVP requirements trace.
+- [x] Keep the OpenFastTrace trace clean and ensure all new MVP implementation
+      and test items are covered.
+
+### Update User Documentation
+
+- [x] Update `README.md` and `doc/developer_guide.md` with LSP startup,
+      Java 21 or later, and server-distribution build/test requirements.
+
+## Version and Changelog Update
+
+- [ ] Check the current version against the latest GitHub release.
+- [ ] Increment the semantic version for this feature integration.
+- [ ] Add the release changelog entry, including the bundled OpenFastTrace
+      version from resolved Gradle dependency metadata.
+- [ ] Update the release date and issue list when a tracker number is assigned.
diff --git a/doc/design.md b/doc/design.md
@@ -27,7 +27,7 @@ material advantage for this standalone, standard-protocol server.
 
 The server is a Gradle project using the Groovy DSL and the `application`
 plugin. Gradle produces the runnable distribution that the VS Code extension
-launches. The server targets Java 21. The VS Code extension is also a Gradle
+launches. The server targets Java 21 as its minimum runtime version. The VS Code extension is also a Gradle
 subproject: its lifecycle tasks install locked Node.js dependencies, compile,
 lint, and test the TypeScript adapter. When available, extension integration
 tests run under Xvfb; otherwise they run directly. Consequently, `./gradlew
@@ -36,7 +36,7 @@ runs the requirements trace as an independent verification task and does not
 define the language-server build.
 
 VS Code extensions execute in a Node.js extension host and do not receive a
-Java runtime from VS Code. The extension therefore obtains a Java 21 runtime
+Java runtime from VS Code. The extension therefore obtains a Java 21 or later runtime
 from the configured `openfasttrace.java.home`, then `JAVA_HOME`, then `PATH`.
 It validates the selected runtime before launching the server and reports an
 actionable configuration error when no compatible runtime is available.

diff --git a/doc/design/architecture.md b/doc/design/architecture.md
@@ -3,7 +3,7 @@
 ## Runtime Boundary
 
 ### OFT Language Server
-`dsn~oft-language-server~1`
+`dsn~oft-language-server~2`
 
 The standalone Java LSP server owns parsing of OFT declarations and coverage
 tags, a workspace index, link resolution, ranked completion, and invocation of
@@ -17,19 +17,17 @@ protocol messages; diagnostics and operational logs are written elsewhere.
 Tags: mvp
 
 Covers:
-- `scn~discover-and-follow-a-trace-link~1`
-- `scn~author-an-oft-link~1`
-- `scn~trace-the-mvp-scope~1`
+- `scn~start-and-negotiate-language-server~1`
 
 Needs: impl
 
 ### VS Code Language Client
-`dsn~vscode-language-client~1`
+`dsn~vscode-language-client~2`
 
 The TypeScript extension launches the language server, maps the workspace and
 supported document selectors, forwards configuration and file events, and
 registers VS Code commands. It contains no competing OFT parser or index. As
-VS Code does not provide Java to extensions, the client resolves Java 21 from
+VS Code does not provide Java to extensions, the client resolves Java 21 or later from
 `openfasttrace.java.home`, then `JAVA_HOME`, then `PATH`, validates it before
 startup, and reports a configuration error if none is suitable. It launches
 the server using the Gradle `application` distribution rather than assuming a
@@ -38,12 +36,51 @@ globally installed server executable.
 Tags: mvp
 
 Covers:
-- `scn~discover-and-follow-a-trace-link~1`
-- `scn~author-an-oft-link~1`
-- `scn~trace-the-mvp-scope~1`
+- `scn~start-and-negotiate-language-server~1`
 
 Needs: impl
 
+### LSP Client Startup
+`impl~lsp-client-startup~1`
+
+The extension validates a configured Java 21 or later runtime before launching
+the staged server distribution. It prefers `openfasttrace.java.home`, then
+`JAVA_HOME`, then `PATH`; it sets `JAVA_HOME` for a selected explicit runtime
+and stops the language client when VS Code deactivates the extension.
+
+Tags: mvp
+
+Covers:
+- `dsn~vscode-language-client~2`
+
+Needs: itest
+
+### Workspace Symbol Protocol Slice
+`impl~workspace-symbol-protocol-slice~1`
+
+The server advertises the standard `workspace/symbol` capability and returns
+an empty, non-null result until workspace indexing is introduced.
+
+Tags: mvp
+
+Covers:
+- `dsn~oft-language-server~2`
+
+Needs: itest
+
+### Workspace Symbol End-To-End Test
+`itest~workspace-symbol-end-to-end~1`
+
+The VS Code integration test activates the extension, waits for the language
+client, sends `workspace/symbol`, and verifies that the staged server returns
+an empty result.
+
+Tags: mvp
+
+Covers:
+- `impl~lsp-client-startup~1`
+- `impl~workspace-symbol-protocol-slice~1`
+
 ### Editor Presentation
 `dsn~editor-presentation~1`
 
@@ -52,8 +89,6 @@ TextMate injection grammar for immediate declaration coloring, and maps LSP
 semantic tokens to OFT coverage-tag styling. It preserves the host language of
 every document.
 
-Tags: mvp
-
 Covers:
 - `scn~recognize-and-highlight-oft-content~1`
 - `scn~author-an-oft-link~1`
@@ -68,8 +103,6 @@ request with workspace-relative inputs and filters. The server returns a typed
 trace report containing status, messages, and source locations. The adapter
 renders it in an Output channel and opens locations from report entries.
 
-Tags: mvp
-
 Covers:
 - `scn~trace-the-mvp-scope~1`
 
@@ -122,7 +155,7 @@ opening remain client adapters because they are not LSP UI concepts.
 ## Build And Distribution
 
 The language server is a standalone Gradle project using the Groovy DSL and
-the `application` plugin, targeting Java 21. Its distribution contains the
+the `application` plugin, targeting Java 21 as its minimum runtime. Its distribution contains the
 server launcher and all runtime dependencies. The extension packages and
 launches the matching distribution for the user's platform. The OpenFastTrace
 Gradle task remains separate from the server build.
diff --git a/doc/developer_guide.md b/doc/developer_guide.md
@@ -4,7 +4,7 @@
 
 Prerequisites:
 
-* Java 21
+* Java 21 or later
 * Node.js 24 and its bundled `npm`
 * On Linux, `xvfb-run` is optional and enables headless VS Code integration
   tests
@@ -26,6 +26,12 @@ these focused tasks when needed:
 ./gradlew :extension:integrationTestExtension
 ```
 
+The extension test tasks first run `:server:installDist` and stage its
+distribution under `extension/server`. The staged executable is the only
+server executable used by the extension. At runtime, it accepts Java 21 or a
+newer release, resolving it from `openfasttrace.java.home`, `JAVA_HOME`, then
+`PATH`.
+
 When `xvfb-run` is available, `integrationTestExtension` launches the VS Code
 test runtime through `xvfb-run -a`; otherwise it invokes the npm
 integration-test script directly.
@@ -38,9 +44,8 @@ Run the current MVP requirements trace locally with Java 17 or later:
 ./gradlew traceRequirements
 ```
 
-The CI workflow runs this command. It intentionally validates the completed
-feature-to-scenario chain. Add design, implementation, and test artifact types
-when their coverage tags are implemented.
+The CI workflow runs this command. It validates the MVP requirements, design,
+implementation, and integration-test chain.
 
 ## Server