Add requirements

.github/workflows/build.yml

@@ -33,6 +33,15 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
+      - name: Set up Java for OpenFastTrace
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Trace MVP requirements
+        run: npm run requirements:trace
+
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:

README.md

@@ -2,6 +2,20 @@
 
 This is the README for your extension "openfasttrace". After writing up a brief description, we recommend including the following sections.
 
+[![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)
+
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=bugs)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=coverage)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=itsallcode_openfasttrace-vscode-extension&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=itsallcode_openfasttrace-vscode-extension)
+
 ## Features
 
 Describe specific features of your extension including screenshots of your extension in action. Image paths are relative to this README file.

doc/changesets/01-mvp-specification.md

@@ -0,0 +1,52 @@
+# 01 MVP Specification Baseline
+
+## Goal
+
+Establish the complete product backlog derived from the IntelliJ plugin and a
+traced, LSP-first MVP boundary for the VS Code extension.
+
+## Scope
+
+In scope:
+
+* Record every discovered IntelliJ user-facing capability as a feature,
+  requirement, and scenario.
+* Define the reusable LSP server and VS Code adapter boundary.
+* Mark the MVP feature chain with `Tags: mvp`.
+
+Out of scope:
+
+* Production implementation.
+* Non-VS-Code client implementations.
+
+## Design References
+
+* [System Requirements](../system_requirements.md)
+* [Design](../design.md)
+* [LSP-first Architecture](../design/architecture.md)
+* [Quality Requirements](../design/quality_requirements.md)
+
+## Task List
+
+### Requirements And Design
+
+- [x] Document the complete discovered feature inventory as traced features,
+  requirements, and scenarios.
+- [x] Define the LSP-first design and VS Code-specific adapter responsibilities.
+- [x] Mark the MVP vertical slice with `Tags: mvp`.
+- [ ] Stop and ask user for a review of the system requirements.
+- [ ] Stop and ask user for a review of the design.
+
+### Implementation
+
+- [ ] Create the Java LSP server and OpenFastTrace integration.
+- [ ] Add the VS Code language client, snippets, highlighting, and trace command.
+- [ ] Implement standard navigation and completion capabilities.
+
+### Verification
+
+- [x] Add CI validation for the completed MVP feature-to-scenario chain.
+- [ ] Add unit, LSP protocol, and VS Code integration tests required by the
+  quality requirements.
+- [ ] Extend the CI trace to MVP design, implementation, and tests after their
+  coverage tags exist.

doc/changesets/README.md

@@ -0,0 +1,5 @@
+# Changesets
+
+Changesets describe a bounded implementation plan before production changes.
+They are named `<number>-<short-kebab-title>.md` and link to the affected
+requirements, design, and quality requirements.

doc/design.md

@@ -0,0 +1,24 @@
+# Design
+
+## Solution Strategy
+
+The product separates OFT semantics from IDE presentation:
+
+* A standalone Java LSP server reuses the OpenFastTrace Java library for
+  parsing, workspace indexing, link resolution, completion, and tracing.
+* The VS Code extension is a thin TypeScript client and presentation adapter.
+* Standard LSP requests provide portable editor behavior. Custom commands carry
+  trace execution and structured trace results, whose visual presentation is
+  inherently IDE-specific.
+
+This boundary permits future LSP clients for other IDEs without duplicating OFT
+semantics.
+
+## Building Blocks
+
+See [LSP-first architecture](design/architecture.md) for the traced runtime
+design items and protocol boundary.
+
+## Quality
+
+See [Quality Requirements](design/quality_requirements.md).

doc/design/architecture.md

@@ -0,0 +1,113 @@
+# LSP-First Architecture
+
+## Runtime Boundary
+
+### OFT Language Server
+`dsn~oft-language-server~1`
+
+The standalone Java LSP server owns parsing of OFT declarations and coverage
+tags, a workspace index, link resolution, ranked completion, and invocation of
+the OpenFastTrace trace engine. It publishes the standard LSP capabilities
+`workspace/symbol`, `definition`, `implementation`, `references`,
+`completion`, and semantic tokens. It receives configuration and file changes
+from each connected client.
+
+Tags: mvp
+
+Covers:
+- `scn~discover-and-follow-a-trace-link~1`
+- `scn~author-an-oft-link~1`
+- `scn~trace-the-mvp-scope~1`
+
+Needs: impl
+
+### VS Code Language Client
+`dsn~vscode-language-client~1`
+
+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.
+
+Tags: mvp
+
+Covers:
+- `scn~discover-and-follow-a-trace-link~1`
+- `scn~author-an-oft-link~1`
+- `scn~trace-the-mvp-scope~1`
+
+Needs: impl
+
+### Editor Presentation
+`dsn~editor-presentation~1`
+
+The VS Code adapter contributes snippets for OFT templates, a Markdown
+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`
+
+Needs: impl
+
+### Trace Command and Plain-Text Report
+`dsn~trace-command-and-plain-text-report~1`
+
+The `OpenFastTrace: Trace Workspace` command sends a custom LSP execute-command
+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`
+
+Needs: impl
+
+### Trace Profiles
+`dsn~trace-profiles~1`
+
+The extension stores named, JSON-compatible profiles in VS Code workspace
+settings. Profiles contain scope, additional paths, artifact-type filters, tag
+filters, and output mode. Commands and a Quick Pick select profiles; optional
+VS Code Tasks are an adapter, not the persistence model.
+
+Covers:
+- `scn~configure-a-repeatable-filtered-trace~1`
+
+Needs: impl
+
+### Structured Trace Results
+`dsn~structured-trace-results~1`
+
+The server exposes a normalized trace-result tree through a custom LSP command.
+The VS Code adapter maps it to `TestController` items grouped by file, item,
+and trace link; each node retains its source `Location` and defect detail.
+
+Covers:
+- `scn~inspect-structured-results~1`
+
+Needs: impl
+
+### User Guide Command
+`dsn~user-guide-command~1`
+
+The VS Code adapter registers a command that opens the canonical upstream user
+guide using the host browser service. The guide itself is not bundled or
+duplicated.
+
+Covers:
+- `scn~read-the-oft-guide~1`
+
+Needs: impl
+
+## Cross-IDE Contract
+
+Portable behavior uses standard LSP methods. Trace execution and result-tree
+transfer use namespaced custom commands with JSON-serializable parameters and
+results. Snippets, grammars, output channels, Test Explorer, Tasks, and browser
+opening remain client adapters because they are not LSP UI concepts.

doc/design/quality_requirements.md

@@ -0,0 +1,18 @@
+# Quality Requirements
+
+* Requirements, scenarios, design items, implementation tags, and tests must
+  remain traceable with OpenFastTrace.
+* Every MVP implementation item and its tests must carry `mvp` so an
+  OpenFastTrace trace configured with the `mvp` tag filter verifies only the
+  MVP chain.
+* CI must trace the complete currently implemented MVP chain. Until production
+  coverage exists, it traces `feat`, `req`, and `scn`; the implementation
+  changeset must extend the gate through design, implementation, and tests.
+* The Java language server must have unit tests for parsing, indexing, link
+  resolution, completion ranking, and trace request mapping.
+* The VS Code adapter must have integration tests for client startup,
+  navigation, completion, snippets, and trace-report presentation.
+* LSP protocol tests must verify capability negotiation and custom-command
+  payload compatibility independently of VS Code.
+* The extension must keep workspace indexing cancellable and update it from
+  document and workspace file changes.

doc/developer_guide.md

@@ -5,3 +5,15 @@
 ```sh
 npx npm-check-updates@latest --upgrade && npm install
 ```
+
+## Trace Requirements
+
+Run the current MVP requirements trace locally with Java 17 and Maven:
+
+```sh
+npm run requirements:trace
+```
+
+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.