Standardize LSP traceability report contract

docs/lsp-traceability-report-contract.md

@@ -0,0 +1,79 @@
+# LSP Traceability Report Contract
+
+OpenQC consumes backend reports that prove scientific docstrings link to LLM
+Wiki nodes and that wiki source claims link to raw evidence assets. Backend
+repositories own language-specific scanning; OpenQC owns the shared report
+contract and family gate.
+
+Schema file: `docs/schemas/lsp-traceability-report.schema.json`
+
+## Required Report
+
+Backends should write one JSON report at one of the paths consumed by
+`scripts/check-lsp-family.mjs`, preferably:
+
+```text
+reports/docstring-wiki-raw-traceability.json
+```
+
+The report must use:
+
+```json
+{
+  "schemaVersion": "openqc.lsp.traceability.v1",
+  "serverId": "cp2k-lsp-enhanced",
+  "repository": "newtontech/cp2k-lsp-enhanced",
+  "languageId": "cp2k",
+  "generatedAt": "2026-06-15T00:00:00.000Z",
+  "summary": {
+    "docstringsTotal": 2,
+    "docstringsLinked": 2,
+    "brokenWikiLinks": 0,
+    "wikiSourcesWithoutRaw": 0,
+    "rawManifestFailures": 0
+  },
+  "docstrings": [],
+  "wikiSources": [],
+  "ruleIds": [],
+  "sourceUrls": [],
+  "rawManifest": {
+    "path": "raw/assets/manifest.json",
+    "ok": true
+  }
+}
+```
+
+## Rule IDs
+
+Rule IDs must use:
+
+```text
+<BACKEND>-<FILE_ROLE>-<CATEGORY>-NNN
+```
+
+Examples:
+
+- `CP2K-INPUT-SYNTAX-001`
+- `DPGEN-MACHINE-SCHEMA-001`
+
+`BACKEND`, `FILE_ROLE`, and `CATEGORY` are uppercase alphanumeric tokens. Use
+underscores inside a token when needed.
+
+## Path Rules
+
+Reports must not require hidden local absolute paths. Use repository-relative
+paths for code, wiki, and raw evidence:
+
+- `src/...` for code docstrings and rule sources
+- `wiki/...` or `docs/...` for LLM Wiki nodes
+- `raw/...` or `raw/assets/...` for raw assets and manifests
+
+Remote source claims must also include a raw evidence path, not only a URL.
+
+## OpenQC Gate
+
+`npm run lsp:check-family -- --strict` validates the report shape when a
+backend report is present. Missing reports remain warnings during rollout;
+invalid schema, server ID mismatch, unlinked docstrings, broken wiki links,
+missing raw evidence links, and raw manifest failures are reported as
+traceability gaps with explicit remediation actions.

docs/schemas/lsp-traceability-report.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/newtontech/OpenQC-VSCode/docs/schemas/lsp-traceability-report.schema.json",
+  "title": "OpenQC LSP Traceability Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "serverId",
+    "repository",
+    "languageId",
+    "generatedAt",
+    "summary",
+    "docstrings",
+    "wikiSources",
+    "ruleIds",
+    "sourceUrls",
+    "rawManifest"
+  ],
+  "$defs": {
+    "repoRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?![A-Za-z]:[\\\\/])(?!file:)(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+"
+    }
+  },
+  "properties": {
+    "schemaVersion": {
+      "const": "openqc.lsp.traceability.v1"
+    },
+    "serverId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "repository": {
+      "type": "string",
+      "minLength": 1
+    },
+    "languageId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "docstringsTotal",
+        "docstringsLinked",
+        "brokenWikiLinks",
+        "wikiSourcesWithoutRaw",
+        "rawManifestFailures"
+      ],
+      "properties": {
+        "docstringsTotal": { "type": "integer", "minimum": 0 },
+        "docstringsLinked": { "type": "integer", "minimum": 0 },
+        "brokenWikiLinks": { "type": "integer", "minimum": 0 },
+        "wikiSourcesWithoutRaw": { "type": "integer", "minimum": 0 },
+        "rawManifestFailures": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "docstrings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "symbol", "wikiPath"],
+        "properties": {
+          "path": { "$ref": "#/$defs/repoRelativePath" },
+          "symbol": { "type": "string", "minLength": 1 },
+          "wikiPath": { "$ref": "#/$defs/repoRelativePath" }
+        }
+      }
+    },
+    "wikiSources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["wikiPath", "sourceUrl", "rawPath"],
+        "properties": {
+          "wikiPath": { "$ref": "#/$defs/repoRelativePath" },
+          "sourceUrl": { "type": "string", "minLength": 1 },
+          "rawPath": { "$ref": "#/$defs/repoRelativePath" }
+        }
+      }
+    },
+    "ruleIds": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "sourcePath"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^[A-Z0-9]+-[A-Z0-9_]+-[A-Z0-9_]+-[0-9]{3}$"
+          },
+          "sourcePath": { "$ref": "#/$defs/repoRelativePath" }
+        }
+      }
+    },
+    "sourceUrls": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["url", "rawPath"],
+        "properties": {
+          "url": { "type": "string", "minLength": 1 },
+          "rawPath": { "$ref": "#/$defs/repoRelativePath" },
+          "kind": { "type": "string" }
+        }
+      }
+    },
+    "rawManifest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "ok"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repoRelativePath" },
+        "ok": { "type": "boolean" }
+      }
+    }
+  }
+}