semantic-js-mcp 0.9.0 → 0.10.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "author": {
     "name": "Jonathan Muñoz Lucas"

package/.prettierrc.json

@@ -1,5 +1,6 @@
 {
   "bracketSpacing": false,
+  "endOfLine": "lf",
   "printWidth": 140,
   "proseWrap": "preserve",
   "semi": true,

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-07-17
+
+### Added
+
+- Publish release tags to npm through a protected GitHub Actions environment using short-lived OIDC credentials and automatic provenance.
+
+### Fixed
+
+- Document and validate marketplace refresh before reinstalling an existing Codex plugin.
+- Install and verify ripgrep in the trusted-publishing runner before executing the release gate.
+
+## [0.10.0] - 2026-07-17
+
+### Added
+
+- Add a deterministic semantic-evidence usability status to named counts and audits, with explicit follow-up reasons for incomplete collection or ambiguous definition selection.
+- Add a repeated post-disposal memory benchmark that separates MCP heap, MCP resident memory, and child-provider resident memory under an explicitly scoped measurement method.
+- Add cross-platform CI coverage for supported Node.js LTS lines.
+- Add focused negative-verification and public-documentation gates.
+- Add concise starter prompts and evidence examples for common agent workflows.
+
+### Fixed
+
+- Recover with fresh language-server and Vue tsserver clients after an initialized provider exits, while settling pending requests and diagnostics without leaving timeout handles active.
+- Resolve cross-project import aliases consistently when a language server first returns the local import binding.
+- Canonicalize Windows source positions when verifying and grouping cross-project references.
+- Make release verification portable across Windows paths, executable shims, temporary-file locking, and checkout line endings.
+- Keep declaration filtering and language-server client eviction stable across platform-specific provider output and slow initialization.
+
 ## [0.9.0] - 2026-07-16
 
 ### Changed

package/CONTRIBUTING.md

@@ -19,13 +19,14 @@ npm run doctor
 npm run smoke:ci
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
 npm run smoke:release
 npm run smoke:evaluation
 npm run smoke:matrix
 npm run smoke:distribution
 ```
 
-Run `npm run benchmark` for changes that affect repository scanning, reference verification, caching, lifecycle, or memory.
+Run `npm run benchmark` for changes that affect repository scanning, reference verification, caching, lifecycle, or memory. Provider disposal changes should also run `npm run benchmark:lifecycle-memory`; it uses explicit garbage collection and POSIX process metrics, remains separate from the deterministic release gate, and reports its measurement scope.
 
 ## Source Of Truth
 
@@ -56,13 +57,16 @@ npm run check:runtime
 npm run smoke:ci
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
 npm run smoke:release
 npm run smoke:evaluation
 npm run smoke:matrix
 npm run smoke:distribution
 ```
 
-Also run `npm run benchmark` when collection cost or memory could change. Run `npm run doctor` when changing runtime resolution, provider startup, the CLI, or diagnostic trust. New behavior should use generic fixtures and cover complete, partial, limited, failed, stale, or untrusted outcomes as applicable.
+Also run `npm run benchmark` when collection cost or memory could change, and `npm run benchmark:lifecycle-memory` when provider disposal behavior changes. Run `npm run doctor` when changing runtime resolution, provider startup, the CLI, or diagnostic trust. New behavior should use generic fixtures and cover complete, partial, limited, failed, stale, or untrusted outcomes as applicable.
+
+`npm run check:documentation` validates the durable public documentation contract. `npm run smoke:negative` exercises missing runtime providers, invalid workspaces and limits, stale or expired reference sets, repository mutation, unresolved candidates, and diagnostic trust. The complete `npm run release:verify` gate includes both checks.
 
 `npm run release:verify` executes the complete local release gate and reports every check in one machine-readable result. It does not publish, tag, or modify an installed plugin.
 

package/README.md

@@ -16,7 +16,7 @@ For each file, it identifies the owning workspace and uses the corresponding Typ
 
 ## Project Status
 
-Version `0.9.0` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
+Version `0.10.1` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
 
 ## Installation
 
@@ -31,6 +31,18 @@ codex plugin add semantic-js-mcp@elnonathan
 
 Codex CLI 0.144.4 or newer is required for npm-backed marketplace installation. Start a new Codex session after installation. The plugin bundles both the MCP server configuration and the semantic-navigation skill.
 
+### Updating the Codex plugin
+
+Codex installs from a local snapshot of each configured marketplace. Refresh that snapshot before reinstalling so `plugin add` resolves the version currently declared by the marketplace:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+`plugin add` reinstalls the plugin; a separate removal is not required. Start a new Codex session after the command reports the expected version.
+
 ### MCP executable
 
 Install the package globally when using an MCP host that accepts a command-based stdio configuration:
@@ -42,9 +54,11 @@ semantic-js-mcp doctor
 
 Configure the host to run `semantic-js-mcp serve`.
 
+For practical investigation prompts and compact evidence examples, see [Getting started](docs/getting-started.md).
+
 ## Runtime
 
-- Node.js 22 or newer is supported.
+- Node.js 22 or newer is required.
 - Node.js 24 LTS is recommended for new installations. See the [Node.js release schedule](https://nodejs.org/en/about/previous-releases).
 - `rg` (ripgrep) must be available on `PATH` for repository-wide discovery.
 - The nearest workspace TypeScript SDK is used when available; the bundled TypeScript SDK is the fallback.
@@ -66,9 +80,10 @@ npm run doctor
 npm run smoke:ci
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
 ```
 
-Run `npm run benchmark` after changes to scanning, references, caching, lifecycle, or memory. Normal analysis is local and read-only; it does not require network access after dependencies are installed.
+Run `npm run benchmark` after changes to scanning, references, caching, lifecycle, or memory. Provider disposal changes can also be characterized with `npm run benchmark:lifecycle-memory`; its output declares the garbage-collection and platform measurement method. Normal analysis is local and read-only; it does not require network access after dependencies are installed.
 
 For an MCP host that accepts a direct stdio configuration, point it at the checked-out server using an absolute path:
 
@@ -152,6 +167,8 @@ Reference pages group the locations returned in that page under `referenceGroups
 
 Named counts and audits report `definitionSelectionStatus` as `no-definition-selected`, `one-definition-selected`, or `multiple-definitions-selected`. This status describes exact declarations remaining after `fileHint` filtering, before any `maxDefinitions` analysis limit. When selection is empty or ambiguous, `continueWith` recommends structural or position-based tools. It recommends `lsp_reference_page` only when the response contains a reusable reference set.
 
+They also report `semanticEvidence.status` as `usable-as-requested` or `follow-up-required`. Follow-up reasons combine incomplete collection and ambiguous definition selection without treating a compact, paged, or subset presentation as incomplete evidence. This status evaluates only the requested semantic result; it does not declare the code correct.
+
 When `fileHint` selects no declaration, a named audit can verify whether source bindings resolve to the hinted file while keeping declaration identity and uncertainty explicit.
 
 ### Limits
@@ -207,6 +224,7 @@ npm run doctor
 npm run smoke
 npm run smoke:ci
 npm run smoke:vue
+npm run smoke:lifecycle
 npm run smoke:distribution
 ```
 
@@ -216,6 +234,10 @@ npm run smoke:distribution
 
 The smoke tests create temporary generic TypeScript and Vue projects. They do not depend on a specific application repository.
 
+## Reporting Problems
+
+Run `semantic-js-mcp doctor` and include its structured output, the package version, Node.js version, operating system, affected source type, and the smallest reproducible workspace or public repository. Remove proprietary source, credentials, local absolute paths, and customer data before opening an issue. See [Contributing](CONTRIBUTING.md) for validation details and the [Security policy](SECURITY.md) for private vulnerability reports.
+
 ## Current Limitations
 
 - The server provides static semantic evidence, not runtime call tracing or behavioral proof.

package/ROADMAP.md

@@ -28,7 +28,7 @@ Semantic JS MCP is under active development. This roadmap outlines areas of inve
 
 ## Distribution
 
-- Expand reproducible package and plugin release checks across supported Node.js LTS releases and hosted CI.
+- Maintain reproducible package and plugin release checks across supported Node.js LTS releases and operating systems.
 - Document setup for additional MCP hosts using the same public server contract.
 - Add immutable release-source, upgrade, rollback, and installed-plugin verification.
 

package/docs/distribution.md

@@ -11,6 +11,16 @@ codex plugin add semantic-js-mcp@elnonathan
 
 The marketplace entry pins a concrete npm package version. Codex CLI 0.144.4 is the minimum verified client for npm-backed marketplace installation. A release updates the package version, plugin manifest, and marketplace entry together.
 
+For an existing marketplace installation, refresh its local snapshot before reinstalling the plugin:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+`plugin add` reinstalls the plugin selected by the refreshed marketplace. Start a new Codex session after the listed version matches the release being installed.
+
 ## Executable
 
 ```bash
@@ -45,9 +55,14 @@ Run the complete local validation sequence before reviewing a distribution chang
 ```bash
 npm run check
 npm run check:runtime
+npm run check:documentation
 npm run smoke:ci
+npm run smoke:publish
+npm run smoke:negative
+npm run smoke:doctor
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
 npm run smoke:distribution
 ```
 
@@ -63,3 +78,15 @@ npm run verify:published -- <version>
 The local release gate runs every configured source, runtime, semantic, evaluation, distribution, and benchmark check and reports all failures instead of stopping at the first one. It performs no publication or installed-plugin mutation.
 
 Postpublication verification requires an explicit version and the matching `v<version>` repository tag. It queries that immutable registry version, installs it with a fresh temporary npm cache and consumer project, verifies the installed executable and manifest, then runs the installed doctor to cover MCP startup, tool discovery, TypeScript evidence, and Vue navigation. It also installs the plugin from the tag-pinned marketplace inside a temporary `CODEX_HOME` and verifies the enabled plugin version. Temporary state is removed afterward. An unavailable registry, marketplace, or network is reported as `blocked`.
+
+## npm Trusted Publishing
+
+The `publish.yml` workflow publishes tags matching `v*` from a GitHub-hosted Node.js 24 runner. It requires the protected `npm-publish` environment, verifies that the tag exactly matches the package version, runs the complete release gate, and publishes through npm Trusted Publishing with OIDC. No long-lived npm token is used. npm generates provenance automatically for the public package.
+
+Configure the npm trusted publisher for GitHub user `elnonathan`, repository `semantic-js-mcp`, workflow filename `publish.yml`, and environment `npm-publish`. Allow `npm publish` only. In package publishing access, require two-factor authentication and disallow tokens.
+
+Create and push the matching `v<version>` tag only after the release commit is on `main` and its CI matrix passes. Approve the protected environment deployment, verify the published package, and then create the matching GitHub release.
+
+## Continuous Integration
+
+GitHub Actions runs the complete release gate on Node.js 22 and 24 across Ubuntu, macOS, and Windows. A second Linux matrix runs the same gate on Node.js 22 across Ubuntu, Fedora, Arch Linux, and openSUSE. The gate verifies ripgrep before running static checks, runtime resolution, documentation, CI policy, negative fixtures, doctor, TypeScript and Vue semantics, provider lifecycle, package installation, and the short benchmark.

package/docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting Started
+
+Semantic JS MCP adds static semantic evidence to an agent's existing code investigation. These prompts are starting points; the agent should still inspect source, search text, and run focused checks when behavior matters.
+
+## Trace A Symbol
+
+> Trace the named symbol `parseRequest` across this repository. Measure its scope first, verify the exact declaration and references, then inspect its direct callers and callees. Report unresolved or incomplete evidence explicitly.
+
+## Review A Security-Sensitive Change
+
+> Review the authentication changes in this diff. Use semantic evidence to verify every material symbol and cross-workspace reference, corroborate reachability with text search and direct source inspection, and distinguish introduced defects from pre-existing behavior.
+
+## Check Current Diagnostics
+
+> Check current diagnostics for `src/handler.ts`. Treat the file as clean only if the language server confirms the current document snapshot; otherwise report the result as untrusted and explain the required follow-up.
+
+## Reading Compact Results
+
+The examples below show the decision-bearing fields. Actual responses also identify the producer, normalized request, presentation mode, and exact continuation tools.
+
+### Complete Evidence
+
+```yaml
+result:
+  definitionSelectionStatus: one-definition-selected
+  semanticEvidence:
+    status: usable-as-requested
+    followUpReasons: []
+collection:
+  status: complete
+```
+
+This supports the requested static symbol claim. It does not prove runtime behavior or approve a change.
+
+### Partial Evidence
+
+```yaml
+result:
+  semanticEvidence:
+    status: follow-up-required
+    followUpReasons:
+      - collection-is-partial
+collection:
+  status: partial
+continueWith:
+  - lsp_unresolved_reference_page
+```
+
+Inspect the unresolved candidates and relevant source before making a coverage claim.
+
+### Untrusted Diagnostics
+
+```yaml
+result:
+  evidence:
+    status: untrusted
+    reason: language-server-did-not-report-current-document
+  diagnosticsForCurrentDocument: null
+collection:
+  status: partial
+```
+
+An empty unconfirmed report is not a clean diagnostic result.
+
+### Startup Failure
+
+```yaml
+status: blocked
+reason: runtime-component-missing
+```
+
+Run `semantic-js-mcp doctor` and report its structured runtime component evidence. A missing provider or unavailable command is an environment blocker, not a code pass or diagnostic result.

package/docs/result-schema-migration.md

@@ -4,6 +4,17 @@ Semantic JS MCP increments `producer.resultSchemaVersion` when a tool-result
 shape changes incompatibly. Consumers should validate this value before parsing
 tool-specific evidence.
 
+## Schema 7
+
+Schema 7 adds `result.semanticEvidence` to named counts and audits. Its
+`status` is `usable-as-requested` only when collection is complete and exactly
+one definition is selected. Otherwise `follow-up-required` includes every
+applicable collection or definition-selection reason under `followUpReasons`.
+
+Presentation mode, page size, and subset presentation never affect this
+status. It summarizes whether the requested semantic result needs another
+semantic step; it does not establish code correctness or runtime behavior.
+
 ## Schema 6
 
 Schema 6 replaces representational duplication with a compact response while

package/lib/doctor.mjs

@@ -1,5 +1,5 @@
 import path from "node:path";
-import {mkdtemp, mkdir, realpath, rm, writeFile} from "node:fs/promises";
+import {mkdtemp, mkdir, realpath, writeFile} from "node:fs/promises";
 import {tmpdir} from "node:os";
 import {Client} from "@modelcontextprotocol/sdk/client/index.js";
 import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -24,6 +24,7 @@ import {
   TOOL_ORDER,
 } from "../protocol.mjs";
 import {PACKAGE_ROOT, inspectExternalCommand, inspectNodeRuntime, inspectRuntimeComponents} from "./runtime.mjs";
+import {removeTemporaryDirectory} from "./temporary-directory.mjs";
 
 const STATUS_EXIT_CODE = Object.freeze({
   [CI_STATUS.PASS]: CI_EXIT_CODE.PASS,
@@ -312,7 +313,7 @@ export async function runDoctor({packageRoot = PACKAGE_ROOT} = {}) {
     }
   } finally {
     await client.close().catch(() => undefined);
-    await rm(fixture.workspace, {recursive: true, force: true});
+    await removeTemporaryDirectory(fixture.workspace);
   }
 
   return doctorResult(packageRoot, checks, runtime);

package/lib/file-identity.mjs

@@ -0,0 +1,18 @@
+import path from "node:path";
+import {OPERATING_SYSTEM} from "../protocol.mjs";
+
+export function fileIdentity(file, operatingSystem = process.platform) {
+  const pathImplementation = operatingSystem === OPERATING_SYSTEM.WINDOWS ? path.win32 : path;
+  const resolved = pathImplementation.resolve(file);
+  return operatingSystem === OPERATING_SYSTEM.WINDOWS ? resolved.toLowerCase() : resolved;
+}
+
+export function locationKeyAt(file, line, column, operatingSystem = process.platform) {
+  return `${fileIdentity(file, operatingSystem)}:${line}:${column}`;
+}
+
+export function locationKeyForOperatingSystem(operatingSystem) {
+  return (location) => locationKeyAt(location.file, location.range.start.line, location.range.start.column, operatingSystem);
+}
+
+export const locationKey = locationKeyForOperatingSystem(process.platform);

package/lib/pending-requests.mjs

@@ -0,0 +1,38 @@
+export class PendingRequestRegistry {
+  constructor({timeoutMilliseconds, timeoutMessage}) {
+    this.timeoutMilliseconds = timeoutMilliseconds;
+    this.timeoutMessage = timeoutMessage;
+    this.entries = new Map();
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+
+  create(key, operation) {
+    if (this.entries.has(key)) throw new Error(`Pending request already exists: ${key}`);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.entries.delete(key);
+        reject(new Error(this.timeoutMessage(operation)));
+      }, this.timeoutMilliseconds);
+      this.entries.set(key, {resolve, reject, timer});
+    });
+  }
+
+  take(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return undefined;
+    clearTimeout(entry.timer);
+    this.entries.delete(key);
+    return entry;
+  }
+
+  rejectAll(error) {
+    for (const entry of this.entries.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    this.entries.clear();
+  }
+}

package/lib/runtime.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import {fileURLToPath} from "node:url";
 import {CONFIGURATION_FILE, NODE_EVENT, PROCESS_EXIT_CODE, REQUIRED_RUNTIME_COMPONENT, RUNTIME_REQUIREMENT} from "../protocol.mjs";
 
+const STREAM_EVENT = Object.freeze({DATA: "data"});
+
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 export function inspectNodeRuntime() {
@@ -50,10 +52,10 @@ export function inspectExternalCommand(command, args) {
     const child = spawn(command, args, {stdio: ["ignore", "pipe", "pipe"]});
     let stdout = "";
     let stderr = "";
-    child.stdout.on("data", (chunk) => {
+    child.stdout.on(STREAM_EVENT.DATA, (chunk) => {
       stdout += chunk;
     });
-    child.stderr.on("data", (chunk) => {
+    child.stderr.on(STREAM_EVENT.DATA, (chunk) => {
       stderr += chunk;
     });
     child.on(NODE_EVENT.ERROR, (error) => resolve({command, available: false, error: error.message}));

package/lib/semantic-evidence.mjs

@@ -0,0 +1,44 @@
+import {
+  COLLECTION_STATUS,
+  DEFINITION_SELECTION_STATUS,
+  SEMANTIC_EVIDENCE_FOLLOW_UP_REASON,
+  SEMANTIC_EVIDENCE_STATUS,
+  TOOL,
+} from "../protocol.mjs";
+
+const NAMED_SYMBOL_TOOLS = new Set([TOOL.COUNT_NAMED_SYMBOL, TOOL.AUDIT_NAMED_SYMBOL]);
+const DEFINITION_SELECTION_STATUSES = new Set(Object.values(DEFINITION_SELECTION_STATUS));
+
+export function isNamedSymbolTool(tool) {
+  return NAMED_SYMBOL_TOOLS.has(tool);
+}
+
+export function namedSemanticEvidence(selectionStatus, collectionStatus) {
+  const followUpReasons = [];
+  if (collectionStatus === COLLECTION_STATUS.LIMITED) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.COLLECTION_LIMITED);
+  }
+  if (collectionStatus === COLLECTION_STATUS.PARTIAL) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.COLLECTION_PARTIAL);
+  }
+  if (selectionStatus === DEFINITION_SELECTION_STATUS.NONE) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.NO_DEFINITION_SELECTED);
+  }
+  if (selectionStatus === DEFINITION_SELECTION_STATUS.MULTIPLE) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.MULTIPLE_DEFINITIONS_SELECTED);
+  }
+  return {
+    status: followUpReasons.length === 0 ? SEMANTIC_EVIDENCE_STATUS.USABLE : SEMANTIC_EVIDENCE_STATUS.FOLLOW_UP_REQUIRED,
+    followUpReasons,
+  };
+}
+
+export function namedSemanticEvidenceMatches(result, collectionStatus) {
+  const actual = result?.semanticEvidence;
+  if (!actual || !Array.isArray(actual.followUpReasons)) return false;
+  if (!DEFINITION_SELECTION_STATUSES.has(result.definitionSelectionStatus)) return false;
+  const expected = namedSemanticEvidence(result.definitionSelectionStatus, collectionStatus);
+  if (actual.status !== expected.status) return false;
+  if (actual.followUpReasons.length !== expected.followUpReasons.length) return false;
+  return actual.followUpReasons.every((reason, index) => reason === expected.followUpReasons[index]);
+}

package/lib/stable-collection.mjs

@@ -0,0 +1,10 @@
+export async function collectStableSnapshot({attempts, collect, inventory, sameInventory, fingerprint}) {
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const inventoryBefore = await inventory();
+    const value = await collect();
+    const [fingerprints, inventoryAfter] = await Promise.all([fingerprint(value), inventory()]);
+    if (!sameInventory(inventoryBefore, inventoryAfter)) continue;
+    return {value, fingerprints, inventory: inventoryAfter, attempt};
+  }
+  return undefined;
+}

package/lib/temporary-directory.mjs

@@ -0,0 +1,15 @@
+import {rm} from "node:fs/promises";
+
+const CLEANUP = Object.freeze({
+  MAXIMUM_RETRIES: 10,
+  RETRY_DELAY_MILLISECONDS: 100,
+});
+
+export async function removeTemporaryDirectory(directory) {
+  await rm(directory, {
+    recursive: true,
+    force: true,
+    maxRetries: CLEANUP.MAXIMUM_RETRIES,
+    retryDelay: CLEANUP.RETRY_DELAY_MILLISECONDS,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "keywords": [
     "mcp",
@@ -44,13 +44,18 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node --check scripts/release-contract.mjs && node --check scripts/release-verify.mjs && node --check scripts/release-smoke.mjs && node --check scripts/postpublication-smoke.mjs && node --check scripts/codex-plugin-verification.mjs && node --check scripts/agent-evaluation-contract.mjs && node --check scripts/agent-evaluation.mjs && node --check scripts/agent-evaluation-smoke.mjs && node --check scripts/repository-matrix-contract.mjs && node --check scripts/repository-matrix.mjs && node --check scripts/repository-matrix-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs",
+    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check lib/semantic-evidence.mjs && node --check lib/pending-requests.mjs && node --check lib/stable-collection.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/documentation-contract.mjs && node --check scripts/documentation-gate.mjs && node --check scripts/documentation-gate-smoke.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/publish-workflow-smoke.mjs && node --check scripts/negative-verification-smoke.mjs && node --check scripts/doctor-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/lifecycle-smoke.mjs && node --check scripts/lifecycle-memory-contract.mjs && node --check scripts/lifecycle-memory-observer.mjs && node --check scripts/lifecycle-memory-benchmark.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node --check scripts/release-contract.mjs && node --check scripts/release-verify.mjs && node --check scripts/release-smoke.mjs && node --check scripts/postpublication-smoke.mjs && node --check scripts/codex-plugin-verification.mjs && node --check scripts/agent-evaluation-contract.mjs && node --check scripts/agent-evaluation.mjs && node --check scripts/agent-evaluation-smoke.mjs && node --check scripts/repository-matrix-contract.mjs && node --check scripts/repository-matrix.mjs && node --check scripts/repository-matrix-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs && node scripts/documentation-gate-smoke.mjs",
     "check:runtime": "node scripts/check-runtime.mjs",
+    "check:documentation": "node scripts/documentation-gate.mjs",
     "doctor": "node cli.mjs doctor",
     "ci:evaluate": "node scripts/semantic-js-mcp-ci.mjs",
     "smoke": "node scripts/smoke.mjs",
     "smoke:ci": "node scripts/ci-smoke.mjs",
+    "smoke:publish": "node scripts/publish-workflow-smoke.mjs",
+    "smoke:negative": "node scripts/negative-verification-smoke.mjs",
+    "smoke:doctor": "node scripts/doctor-smoke.mjs",
     "smoke:vue": "node scripts/vue-smoke.mjs",
+    "smoke:lifecycle": "node scripts/lifecycle-smoke.mjs",
     "smoke:distribution": "node scripts/distribution-smoke.mjs",
     "smoke:release": "node scripts/release-smoke.mjs",
     "smoke:evaluation": "node scripts/agent-evaluation-smoke.mjs",
@@ -60,8 +65,9 @@
     "release:verify": "node scripts/release-verify.mjs",
     "verify:published": "node scripts/postpublication-smoke.mjs",
     "benchmark": "node scripts/benchmark.mjs",
-    "format": "prettier --write \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\"",
-    "format:check": "prettier --check \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\""
+    "benchmark:lifecycle-memory": "node scripts/lifecycle-memory-benchmark.mjs",
+    "format": "prettier --write \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\"",
+    "format:check": "prettier --check \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",

package/protocol.mjs

@@ -207,9 +207,9 @@ export const TOOL_DESCRIPTION = Object.freeze({
   [TOOL.DIAGNOSTICS]:
     "Returns diagnostics for one file and marks evidence untrusted when the current document snapshot cannot be confirmed.",
   [TOOL.COUNT_TEXT_MATCHES]: `Counts exact identifier text matches without semantic verification. Use ${TOOL.COUNT_NAMED_SYMBOL} or ${TOOL.AUDIT_NAMED_SYMBOL} to verify identity.`,
-  [TOOL.COUNT_NAMED_SYMBOL]: `Returns exact-definition and verified-reference counts for a symbol name. Use ${TOOL.AUDIT_NAMED_SYMBOL} for identity, signature, or file-hint binding verification and ${TOOL.REFERENCE_PAGE} with a returned referenceSetId for locations.`,
+  [TOOL.COUNT_NAMED_SYMBOL]: `Returns exact-definition and verified-reference counts plus explicit semantic follow-up status for a symbol name. Use ${TOOL.AUDIT_NAMED_SYMBOL} for identity, signature, or file-hint binding verification and ${TOOL.REFERENCE_PAGE} with a returned referenceSetId for locations.`,
   [TOOL.COUNT_REFERENCES]: `Returns verified-reference counts for the symbol at one source position. Use ${TOOL.AUDIT_SYMBOL} for identity and signature or ${TOOL.REFERENCE_PAGE} with the returned referenceSetId for locations.`,
-  [TOOL.AUDIT_NAMED_SYMBOL]: `Returns a compact exact-name audit and verifies source bindings to fileHint when no declaration is selected. Use ${TOOL.REFERENCE_PAGE} with a returned referenceSetId for locations.`,
+  [TOOL.AUDIT_NAMED_SYMBOL]: `Returns a compact exact-name audit with explicit semantic follow-up status and verifies source bindings to fileHint when no declaration is selected. Use ${TOOL.REFERENCE_PAGE} with a returned referenceSetId for locations.`,
   [TOOL.AUDIT_SYMBOL]: `Returns a compact definition, signature, coverage, and freshness summary for one source position. Use ${TOOL.REFERENCE_PAGE} with the returned referenceSetId for locations.`,
   [TOOL.REFERENCES]: `Returns the first page of verified source locations and detailed collection evidence. Use ${TOOL.REFERENCE_PAGE} for later pages.`,
   [TOOL.REFERENCE_PAGE]: `Returns a page from a freshness-checked reference set created by a count, audit, or ${TOOL.REFERENCES} call.`,
@@ -219,10 +219,19 @@ export const TOOL_DESCRIPTION = Object.freeze({
 
 export const LSP_METHOD = Object.freeze({
   DOCUMENT_DIAGNOSTIC: "textDocument/diagnostic",
+  EXECUTE_COMMAND: "workspace/executeCommand",
   PUBLISH_DIAGNOSTICS: "textDocument/publishDiagnostics",
   WORKSPACE_DIAGNOSTIC_REFRESH: "workspace/diagnostic/refresh",
 });
 
+export const LSP_COMMAND = Object.freeze({
+  GO_TO_SOURCE_DEFINITION: "_typescript.goToSourceDefinition",
+});
+
+export const TYPESCRIPT_SERVER_COMMAND = Object.freeze({
+  DEFINITION_AND_BOUND_SPAN: "definitionAndBoundSpan",
+});
+
 export const LIMIT_MODE = Object.freeze({
   UNLIMITED: "unlimited",
   MAXIMUM: "maximum",
@@ -244,6 +253,18 @@ export const DEFINITION_SELECTION_STATUS = Object.freeze({
   MULTIPLE: "multiple-definitions-selected",
 });
 
+export const SEMANTIC_EVIDENCE_STATUS = Object.freeze({
+  USABLE: "usable-as-requested",
+  FOLLOW_UP_REQUIRED: "follow-up-required",
+});
+
+export const SEMANTIC_EVIDENCE_FOLLOW_UP_REASON = Object.freeze({
+  COLLECTION_LIMITED: "collection-is-limited",
+  COLLECTION_PARTIAL: "collection-is-partial",
+  NO_DEFINITION_SELECTED: DEFINITION_SELECTION_STATUS.NONE,
+  MULTIPLE_DEFINITIONS_SELECTED: DEFINITION_SELECTION_STATUS.MULTIPLE,
+});
+
 export const SIGNATURE_SOURCE = Object.freeze({
   QUERY_POSITION_HOVER: "query-position-hover",
   RESOLVED_DEFINITION_HOVER: "resolved-definition-hover",
@@ -369,6 +390,7 @@ export const CI_REASON = Object.freeze({
   VERIFIED_DIAGNOSTIC_ERRORS: "verified-current-document-has-error-diagnostics",
   INCOMPLETE_EVIDENCE: "collection-is-limited-or-partial",
   UNTRUSTED_DIAGNOSTICS: "diagnostics-for-current-document-are-untrusted",
+  SEMANTIC_FOLLOW_UP_REQUIRED: "semantic-evidence-requires-follow-up",
   TOOL_EXECUTION_FAILED: "tool-execution-failed",
   INVALID_INPUT: "input-is-not-a-semantic-js-mcp-result",
 });
@@ -383,10 +405,10 @@ export const INTERNAL_RESOLUTION_SOURCE = Object.freeze({
 
 export const RESULT_SCHEMA = Object.freeze({
   NAME: PRODUCT.NAME,
-  VERSION: 6,
+  VERSION: 7,
 });
 
-export const SERVER_VERSION = "0.9.0";
+export const SERVER_VERSION = "0.10.1";
 
 export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
   TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",
@@ -411,6 +433,12 @@ export const NODE_EVENT = Object.freeze({
   CLOSE: "close",
 });
 
+export const OPERATING_SYSTEM = Object.freeze({
+  LINUX: "linux",
+  MACOS: "darwin",
+  WINDOWS: "win32",
+});
+
 export const DEFAULT = Object.freeze({
   REQUEST_TIMEOUT_MS: 30_000,
   DIAGNOSTIC_WAIT_MS: 2_000,