Require SkillSpector 2.12.0 or newer

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to SkillEvaluator are documented in this file.
 
 ## Unreleased
 
+### Changed
+
+- Require SkillSpector 2.12.0 or newer for Tier 1 security scanning. Older
+  scanner versions now leave the result `INCOMPLETE` with upgrade guidance.
+
 ## 0.3.0 - 2026-09-17
 
 ### Added

README.md

@@ -115,9 +115,9 @@ skillevaluator context-optimization-check ./my-skill
 skillevaluator similarity-check ./skills
 ```
 
-Install Semgrep, SkillSpector, and Gitleaks before a full run; missing Tier 1
-scanner evidence makes validation incomplete. Then verify the selected agent
-runtime and use `validate --full`:
+Install Semgrep, SkillSpector, and Gitleaks for full validation (SkillSpector
+`>=2.12.0`). Missing scanner evidence makes validation incomplete. Verify the
+agent runtime and use `validate --full`:
 
 ```bash
 skillevaluator doctor --agents codex --env-mode docker

docs/ci-integration.mdx

@@ -34,9 +34,9 @@ Each flag earns its place:
 
 ## GitHub Actions recipe
 
-A complete workflow: install with uv, add the external Semgrep, SkillSpector,
-and Gitleaks scanners for a complete security result, validate, upload the
-reports, and post the Markdown report on the pull request.
+A complete workflow: install with uv, add the external Semgrep, SkillSpector
+2.12.0 or newer, and Gitleaks scanners for a complete security result, validate,
+upload the reports, and post the Markdown report on the pull request.
 
 ```yaml title="ci.yml"
 name: Validate skills
@@ -256,8 +256,9 @@ jq -e '([.quality_summary[]?.overall_score] | min // 100) >= 80' "$report"
   <Accordion title="overall_status is 'incomplete'">
     A required scanner is missing or returned no evidence. Check the report for
     the named scanner: Semgrep, SkillSpector, and Gitleaks are all separate
-    executables, and the `security` extra alone does not install them. The
-    scanners fail closed: `validate` exits non-zero and the report stays
+    executables, and the `security` extra alone does not install them. SkillSpector
+    versions older than 2.12.0 must be upgraded. The scanners fail closed:
+    `validate` exits non-zero and the report stays
     non-green until every required scanner is installed and returns valid
     evidence. See the workflow above or
     [Installation: System tools](installation.mdx#system-tools).

docs/installation.mdx

@@ -135,6 +135,13 @@ uv tool install semgrep                                       # isolated Python
 uv tool install git+https://github.com/NVIDIA/SkillSpector.git
 ```
 
+SkillSpector **2.12.0 or newer** is required. Older versions leave validation
+`INCOMPLETE`. To upgrade an existing uv tool installation, run:
+
+```bash title="Upgrade SkillSpector"
+uv tool install --upgrade git+https://github.com/NVIDIA/SkillSpector.git
+```
+
 On other systems, install Gitleaks with `go install github.com/gitleaks/gitleaks/v8@latest` or a binary from the [Gitleaks releases](https://github.com/gitleaks/gitleaks/releases). Semgrep and SkillSpector must be on `PATH`, or configured with `SKILLEVALUATOR_SEMGREP_PATH` and `SKILLEVALUATOR_SKILLSPECTOR_PATH`. RHEL 8 and compatible enterprise Linux systems can supply compatible executables independently of the SkillEvaluator Python environment.
 
 Docker is required only for Tier 3 Docker-mode evaluation. Agent CLIs and their credentials are user-supplied — see [Agents & Sandboxes](agents-and-sandboxes.mdx).
@@ -158,7 +165,7 @@ skillevaluator health-check
 uv installs tools to `~/.local/bin`, which may not be on PATH yet. Run `uv tool update-shell` and open a new terminal.
 </Accordion>
 <Accordion title="Validation reports INCOMPLETE and exits non-zero">
-Install any missing required scanner named in the report. The `security` extra supplies Bandit and pip-audit; Semgrep, SkillSpector, and Gitleaks are separate executables. Missing required evidence leaves validation `INCOMPLETE` and non-zero.
+Install any missing required scanner named in the report. The `security` extra supplies Bandit and pip-audit; Semgrep, SkillSpector, and Gitleaks are separate executables. SkillSpector must be version 2.12.0 or newer; see [System tools](#system-tools) for the upgrade command. Missing required evidence or an older SkillSpector version leaves validation `INCOMPLETE` and non-zero.
 </Accordion>
 </AccordionGroup>
 

docs/quickstart.mdx

@@ -42,8 +42,9 @@ Get your first evaluation result in about two minutes, with no API key. This pag
 
   `validate` runs the full static and security check suite. The `[all]` install
   above includes the Python scanners, but complete evidence also requires the
-  separate Semgrep, SkillSpector, and Gitleaks executables. Install all three,
-  and pass `--no-dedup` to skip the Tier 2 pass that needs an embeddings key:
+  separate Semgrep, SkillSpector 2.12.0 or newer, and Gitleaks executables.
+  Install all three, and pass `--no-dedup` to skip the Tier 2 pass that needs
+  an embeddings key:
 
   ```bash title="Complete offline Tier 1"
   brew install semgrep gitleaks   # macOS

docs/tier1-validation.mdx

@@ -275,7 +275,7 @@ The default set is `schema`, `version`, `security`, `pii`, `license`, `code-inte
 
 ## Scanner setup
 
-Install `skillevaluator[security]` for the bundled Python scanners (Bandit and pip-audit). Install Semgrep and SkillSpector in separate tool environments, and install Gitleaks separately — it is a Go binary, not a pip package. See [Installation](installation.mdx) for commands and the extras table.
+Install `skillevaluator[security]` for the bundled Python scanners (Bandit and pip-audit). Install Semgrep and SkillSpector **2.12.0 or newer** in separate tool environments, and install Gitleaks separately — it is a Go binary, not a pip package. Older SkillSpector versions leave the run `INCOMPLETE`; see [Installation: System tools](installation.mdx#system-tools) for installation and upgrade commands.
 
 Semgrep uses a policy packaged with the installed distribution, with metrics and version checks disabled; Tier 1 never fetches a registry policy at runtime. The other public Tier 1 configuration also ships inside the package under `skillevaluator/config/`: `pii_patterns.yaml`, `unicode_smuggle_patterns.yaml`, `license_config.yaml`, and `profiles/external.yaml`.
 

src/skillevaluator/validators/security.py

@@ -54,6 +54,7 @@
 
 _AUTHOR_IDENTITY_RE = re.compile(r"^\S[^<>\n]* <(?P<email>[^<>@\s]+@[^<>\s]+)>$")
 _SKILLSPECTOR_POLICY_EXIT_CODES = frozenset({0, 1})
+_SKILLSPECTOR_MIN_VERSION = (2, 12, 0)
 _SKILLSPECTOR_STATUSLESS_COMPLETENESS_VERSIONS = {(2, 9, 5), (2, 9, 6)}
 _SKILLSPECTOR_FINDING_IDENTITY_VERSION = (2, 11, 1)
 _SKILLSPECTOR_COMPLETENESS_SCHEMA_VERSION = (2, 10, 0)
@@ -1723,6 +1724,15 @@ def _validate_skillspector_report(
             )
             return False
 
+        if skillspector_version is not None and skillspector_version < _SKILLSPECTOR_MIN_VERSION:
+            minimum_version = ".".join(str(part) for part in _SKILLSPECTOR_MIN_VERSION)
+            result.add_error(
+                f"SkillSpector {minimum_version} or newer is required; found {metadata['skillspector_version']}. "
+                "Upgrade with: uv tool install --upgrade git+https://github.com/NVIDIA/SkillSpector.git; "
+                "security scan did not complete"
+            )
+            return False
+
         return True
 
     @staticmethod