@vltpkg/query 1.0.0-rc.8 → 1.0.1

package/dist/{esm/types.d.ts → types.d.ts}

@@ -18,11 +18,18 @@ export type GraphSelectionState = {
     nodes: Set<NodeLike>;
     edges: Set<EdgeLike>;
 };
+/**
+ * Callback that returns changed file paths for a given
+ * commitish reference. Used by the :diff() pseudo selector.
+ * The returned paths should be relative to the project root.
+ */
+export type DiffFilesProvider = (commitish: string) => Set<string>;
 export type ParserState = {
     cancellable: () => Promise<void>;
     collect: GraphSelectionState;
     comment: string;
     current: PostcssNode;
+    diffFiles?: DiffFilesProvider;
     hostContexts?: HostContextsMap;
     importers: Set<NodeLike>;
     initial: GraphSelectionState;
@@ -68,7 +75,7 @@ export type Insights = {
     eval?: boolean;
     fs?: boolean;
     license?: LicenseInsights;
-    malware?: MalwareInsights;
+    malware?: boolean;
     minified?: boolean;
     native?: boolean;
     network?: boolean;
@@ -88,6 +95,7 @@ export type Insights = {
     unmaintained?: boolean;
     unpopular?: boolean;
     unstable?: boolean;
+    vuln?: VulnInsights;
 };
 export type LicenseInsights = {
     unlicensed: boolean;
@@ -105,8 +113,8 @@ export type LeveledInsights = {
     high: boolean;
     critical: boolean;
 };
-export type MalwareInsights = LeveledInsights;
 export type SeverityInsights = LeveledInsights;
+export type VulnInsights = LeveledInsights;
 export type SquatInsights = {
     medium: boolean;
     critical: boolean;
@@ -115,4 +123,3 @@ export type ParserFn = (opt: ParserState) => Promise<ParserState>;
 export type ParsedSelectorToken = PostcssNode & {
     token: string;
 };
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,79 +1,78 @@
 {
   "name": "@vltpkg/query",
   "description": "Query syntax parser that retrieves items from a graph",
-  "version": "1.0.0-rc.8",
+  "version": "1.0.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
     "directory": "src/query"
   },
-  "author": "vlt technology inc. <support@vlt.sh> (http://vlt.sh)",
-  "tshy": {
-    "selfLink": false,
-    "liveDev": true,
-    "dialects": [
-      "esm"
-    ],
-    "exports": {
-      "./package.json": "./package.json",
-      ".": "./src/index.ts"
-    }
+  "author": {
+    "name": "vlt technology inc.",
+    "email": "support@vlt.sh",
+    "url": "http://vlt.sh"
   },
   "dependencies": {
-    "minimatch": "^10.0.3",
-    "p-retry": "^7.0.0",
-    "postcss-selector-parser": "^7.1.0",
-    "@vltpkg/dep-id": "1.0.0-rc.8",
-    "@vltpkg/dss-parser": "1.0.0-rc.8",
-    "@vltpkg/error-cause": "1.0.0-rc.8",
-    "@vltpkg/graph": "1.0.0-rc.8",
-    "@vltpkg/types": "1.0.0-rc.8",
-    "@vltpkg/security-archive": "1.0.0-rc.8",
-    "@vltpkg/semver": "1.0.0-rc.8"
+    "@vltpkg/dep-id": "1.0.1",
+    "@vltpkg/dss-parser": "1.0.1",
+    "@vltpkg/error-cause": "1.0.1",
+    "@vltpkg/security-archive": "1.0.1",
+    "@vltpkg/semver": "1.0.1",
+    "@vltpkg/types": "1.0.1",
+    "minimatch": "^10.1.1",
+    "p-retry": "^7.1.1",
+    "postcss-selector-parser": "^7.1.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.34.0",
-    "@types/node": "^22.17.2",
-    "eslint": "^9.34.0",
-    "prettier": "^3.6.2",
-    "tap": "^21.1.0",
-    "tshy": "^3.0.2",
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^22.19.2",
+    "@vltpkg/spec": "1.0.1",
+    "eslint": "^9.39.1",
+    "prettier": "^3.7.4",
+    "tap": "^21.5.0",
     "typedoc": "~0.27.9",
     "typescript": "5.7.3",
-    "typescript-eslint": "^8.40.0",
-    "@vltpkg/spec": "1.0.0-rc.8"
+    "typescript-eslint": "^8.49.0"
   },
   "license": "BSD-2-Clause-Patent",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.22.0"
+  },
+  "scripts": {
+    "format": "prettier --write . --log-level warn --ignore-path ../../.prettierignore --cache",
+    "format:check": "prettier --check . --ignore-path ../../.prettierignore --cache",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "prepack": "tsc -p tsconfig.publish.json && ../../scripts/update-dist-exports.ts",
+    "snap": "tap",
+    "test": "tap",
+    "posttest": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
   },
   "tap": {
     "extends": "../../tap-config.yaml"
   },
   "prettier": "../../.prettierrc.js",
-  "module": "./dist/esm/index.js",
+  "module": "./dist/index.js",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "import": {
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
+        "default": "./dist/index.js"
       }
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/dss-query/evals"
   ],
-  "scripts": {
-    "format": "prettier --write . --log-level warn --ignore-path ../../.prettierignore --cache",
-    "format:check": "prettier --check . --ignore-path ../../.prettierignore --cache",
-    "lint": "eslint . --fix",
-    "lint:check": "eslint .",
-    "snap": "tap",
-    "test": "tap",
-    "posttest": "tsc --noEmit",
-    "tshy": "tshy",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  "bugs": [
+    {
+      "type": "link",
+      "url": "https://github.com/vltpkg/vltpkg/issues"
+    }
+  ],
+  "homepage": "https://github.com/vltpkg/vltpkg/tree/main/src/query#readme"
+}

package/skills/dss-query/REFERENCE.md

@@ -0,0 +1,123 @@
+# DSS Reference
+
+Compiled from https://docs.vlt.io/cli/selectors/ (source:
+`www/docs/src/content/docs/cli/selectors/`). When in doubt, check
+those docs — they are canonical.
+
+## Attribute selectors
+
+Match against `package.json` fields.
+
+| Selector         | Meaning                                          |
+| ---------------- | ------------------------------------------------ |
+| `[attr]`         | has the property                                 |
+| `[attr=value]`   | equals                                           |
+| `[attr^=value]`  | starts with                                      |
+| `[attr$=value]`  | ends with                                        |
+| `[attr*=value]`  | contains                                         |
+| `[attr~=value]`  | whitespace-separated list contains               |
+| `[attr\|=value]` | equals value or starts with `value-`             |
+| `[attr=value i]` | case-insensitive (`s` = case-sensitive, default) |
+
+Nested fields (e.g. `engines.node`) need `:attr()`:
+`:attr(engines, [node])`,
+`:attr(peerDependenciesMeta, foo, [optional=true])`.
+
+`#foo` is shorthand for `[name=foo]`.
+
+## Combinators
+
+| Combinator | Meaning                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `A > B`    | B is a **direct** dependency of A (chain for depth: `:root > * > *`) |
+| `A B`      | B is a direct **or transitive** dependency of A                      |
+| `A ~ B`    | B shares a parent with A (sibling)                                   |
+
+## Pseudo-states (no arguments)
+
+Graph structure:
+
+| Selector     | Matches                                 |
+| ------------ | --------------------------------------- |
+| `:root`      | top-level package.json node             |
+| `:project`   | root + all workspaces ("your code")     |
+| `:workspace` | workspaces from vlt.json                |
+| `:scope`     | current selector scope (with `--scope`) |
+
+Dependency type:
+
+| Selector                                 | Matches                                                |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `:prod` / `:dev` / `:optional` / `:peer` | by dependency type                                     |
+| `:missing`                               | declared but not installed (**edges only, not nodes**) |
+| `:overridden`                            | has an override applied                                |
+
+Package properties:
+
+| Selector      | Matches                                      |
+| ------------- | -------------------------------------------- |
+| `:private`    | `"private": true`                            |
+| `:empty`      | no dependencies                              |
+| `:link`       | linked packages                              |
+| `:prerelease` | version has prerelease part (`1.0.0-beta.1`) |
+| `:built`      | built during reify                           |
+| `:scanned`    | has Socket security metadata                 |
+
+## Pseudo-classes (take arguments)
+
+| Selector            | Meaning                                 | Example                                        |
+| ------------------- | --------------------------------------- | ---------------------------------------------- |
+| `:attr(...)`        | nested package.json property            | `:attr(engines, [node])`                       |
+| `:dist(tag)`        | registry dist-tag                       | `:dist(latest)`                                |
+| `:has(sel)`         | has matching descendant                 | `:has(.peer[name=react])`                      |
+| `:host(name)`       | switch graph context to another project | `:host(local) :malware`                        |
+| `:is(a, b)`         | any of (forgiving list)                 | `:is([name=a], [name=b])`                      |
+| `:not(sel)`         | negation                                | `:not([license=MIT])`                          |
+| `:outdated(kind?)`  | newer version exists                    | `:outdated(major)`                             |
+| `:published(range)` | by publish date                         | `:published(">2024")`                          |
+| `:semver(range)`    | semver comparison on installed version  | `:semver(^1.0.0)`                              |
+| `:spec(spec)`       | by declared specifier (edge)            | `:spec(^1.0.0)`                                |
+| `:path(glob)`       | workspace/file packages by path         | `:path("packages/**")`                         |
+| `:type(kind)`       | package type                            | `:type(git)`, `:type(registry)`, `:type(file)` |
+| `:diff(ref)`        | files changed vs git ref                | `:diff(main)`                                  |
+| `:hostname(host)`   | upstream hostname                       | `:hostname(github.com)`                        |
+| `:registry(name)`   | configured registry name                | `:registry(npm)`                               |
+
+## Security insights (Socket-powered, network call)
+
+Severity args accept names or numbers (`critical`/`0`, `high`/`1`,
+`medium`/`2`, `low`/`3`) and comparators: `:severity(">=medium")`.
+
+Threats: `:malware` (binary, no params), `:squat(sev?)`,
+`:suspicious`, `:confused`.
+
+Vulnerabilities: `:vuln(sev?)` (alias `:vulnerable`),
+`:cve(CVE-2023-1234)`, `:cve(*)`, `:cwe(CWE-79)`, `:severity(level)`.
+`:vuln` without params matches severity ≥ medium; `:vuln(critical)`
+exact-matches; `:vuln(">=high")` uses comparators. Also matches alerts
+carrying a `cveId` prop.
+
+Licensing: `:license(type)` — types: `unlicensed`, `misc`,
+`restricted`, `ambiguous`, `copyleft`, `unknown`, `none`, `exception`.
+
+Code behavior: `:eval`, `:network`, `:fs`, `:env`, `:shell`,
+`:scripts` (install scripts), `:debug`, `:dynamic`.
+
+Obfuscation: `:obfuscated`, `:minified`, `:entropic`, `:native`,
+`:shrinkwrap`.
+
+Health: `:deprecated`, `:unmaintained` (5+ years stale), `:unpopular`,
+`:trivial` (<10 LOC), `:abandoned`, `:unknown`, `:unstable`.
+
+Other: `:tracker` (telemetry), `:undesirable`, `:score(rate, kind?)` —
+kinds: `overall` (default), `license`, `maintenance`, `quality`,
+`supplyChain`, `vulnerability`; e.g. `:score("<=0.5", "maintenance")`.
+
+## Audit query starters
+
+```bash
+vlt query ':malware, :vuln(critical), :cve(*), :obfuscated'   # critical issues
+vlt query ':abandoned, :unmaintained, :unknown'        # supply chain risk
+vlt query ':license(copyleft), :license(unlicensed)'   # license compliance
+vlt query ':eval, :shell, :network, :fs'               # behavior audit
+```

package/skills/dss-query/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: dss-query
+description:
+  Explain and compose vlt Dependency Selector Syntax (DSS) queries —
+  CSS-selector-like strings for filtering packages in a dependency
+  graph, including Socket-powered security auditing. Use when the user
+  asks about DSS, `vlt query`, dependency selectors, wants to
+  find/filter packages (e.g. "find outdated deps", "select all
+  workspaces"), or wants to security-audit dependencies ("which
+  packages have CVEs", "check for malware/typosquats", "what can run
+  shell commands or hit the network").
+allowed-tools: [Read, Grep]
+context: fork
+---
+
+# DSS Query Helper
+
+Run DSS queries via `vlt query '<selector>'`.
+
+## Response style
+
+**Be concise, but teach one thing.** Give the query first, then a
+one-line explanation. No long preambles, no exhaustive alternatives —
+but don't dead-end either: close with a short **Examples** tail of 1–2
+adjacent queries (one step broader, narrower, or a sibling concept).
+Users learn DSS through adjacent examples, and each answer is a chance
+to build that intuition cheaply. Keep the tail bare — a query plus a
+few-word label, no surrounding prose; the whole answer should still
+read in seconds.
+
+Two more rules:
+
+- **Gloss jargon in place.** Readers may not know DSS terms — on first
+  use, give a 2–4 word parenthetical instead of assuming: "`:root`
+  anchors the match (starts it) at your project root", "`>` (direct
+  deps only)". Never a terminology lecture, just the aside.
+- **End with a docs deep link** so the answer has a "learn more" exit.
+  Use the verified map in [Full reference](#full-reference) below —
+  link the section relevant to the query, not the docs homepage.
+
+Example answer shape:
+
+> ```
+> vlt query ':root > :outdated(major)'
+> ```
+>
+> Direct dependencies with a newer major version available.
+>
+> Examples:
+>
+> - `vlt query ':root > :outdated'` — any newer version, not just
+>   major
+> - `vlt query ':outdated(major)'` — whole graph, not just direct
+>
+> Add `--view=json` for machine-readable output. More:
+> <https://docs.vlt.io/cli/selectors/>
+
+## Workflow
+
+1. **Clarify intent first** if the goal is ambiguous — ask 1–2 short
+   questions, never a survey. Pin down:
+   - **What to match**: which packages? Whole graph or just direct
+     deps? Everywhere, or only under a specific workspace/package?
+   - **Expected outcome**: what does the result set look like if the
+     query works — a handful of known offenders, every workspace, one
+     package? What will they do with it (audit, remove, report)? Skip
+     this when the request is already specific — don't interrogate
+     someone who said "direct deps of root with an MIT license".
+2. **Compose the query** with the steps below. Then:
+   - Show the query.
+   - Explain each piece in one short sentence.
+   - State what the results should look like, so the user can tell
+     whether it worked.
+   - Close with the **Examples** tail (1–2 adjacent queries).
+3. **"What does this query do?"**: decompose left to right, one line
+   per segment. Offer 1–2 example queries the user could try next.
+4. **Correcting a mistaken query?** Add one line on _why_ it was
+   wrong, not just the fix — e.g. combinators point from dependent to
+   dependency (parent `>` child), so `#x > *` selects x's
+   dependencies, not its dependents. The rule transfers; the fix alone
+   doesn't.
+5. **Uncertain match?** Offer to run it: `vlt query '<selector>'`
+   (always single-quote the selector in the shell). Output format:
+   `--view=human|json|mermaid|svg|png|count` — defaults to human (json
+   when piped).
+6. **Iterate**: compare results against the expected outcome from step
+   1 — too broad/narrow means refine one piece at a time (add a
+   combinator, a pseudo-state, or `:not()`).
+
+## Composing a query from a goal
+
+Build left to right, in this order — each step is optional:
+
+1. **Anchor** — where in the graph? `:root` (top level), `:workspace`,
+   `:project`, `#pkg-name`, or nothing (whole graph).
+2. **Traverse** — what relationship? `>` direct deps, ` ` (space)
+   anything beneath, `~` siblings. Skip to filter the anchor itself.
+3. **Filter** — chain conditions with no space = AND: attribute
+   (`[license=MIT]`), state (`:dev`), functional (`:outdated(major)`),
+   negation (`:not(...)`).
+4. **Union** — need OR? Join complete selectors with commas.
+5. **Invert direction** — "what depends on X?" flips traversal: use
+   `:has(> #x)` (dependents of x), not `#x > *` (dependencies of x).
+
+Worked example — "prod deps of my workspaces with a copyleft license":
+`:workspace` (anchor) + `>` (direct) + `:prod:license(copyleft)`
+(filters) → `vlt query ':workspace > :prod:license(copyleft)'`
+
+## Core syntax (mental model: CSS, but nodes are packages)
+
+| Piece                               | Meaning                                     | Example                  |
+| ----------------------------------- | ------------------------------------------- | ------------------------ |
+| `[name=foo]` / `#foo`               | match by package.json field / name shortcut | `[version^=2]`, `#react` |
+| `>`                                 | direct dependency                           | `:root > *`              |
+| ` ` (space)                         | any transitive dependency                   | `:root [name=js-tokens]` |
+| `~`                                 | sibling (shares a parent)                   | `[name=react] ~ *`       |
+| `:root` `:project` `:workspace`     | graph anchors                               | `:workspace > :dev`      |
+| `:prod` `:dev` `:optional` `:peer`  | dependency type                             | `:dev:outdated`          |
+| `:has()` `:not()` `:is()`           | structural filters                          | `:has(> :cve(*))`        |
+| `:outdated()` `:semver()` `:type()` | functional filters                          | `:outdated(major)`       |
+| `:malware` `:cve()` `:license()`    | security (Socket data, network call)        | `:license(copyleft)`     |
+| `,`                                 | OR — union of selectors                     | `:dev, :optional`        |
+
+Chaining without spaces is AND: `:workspace:private` = workspace AND
+private.
+
+## Common recipes
+
+```bash
+vlt query ':root > *'                    # direct dependencies
+vlt query ':workspace'                   # select all workspaces
+vlt query ':root > :outdated'            # outdated direct deps
+vlt query '[name=react] *'               # everything react pulls in
+vlt query ':has(> #react)'               # packages that directly depend on react
+vlt query ':dev:eval'                    # dev deps using eval()
+vlt query ':malware, :cve(*)'            # malware or any CVE
+```
+
+## Security auditing (Socket-powered)
+
+DSS's sharpest feature: nodes are enriched with Socket insight data,
+so the dependency graph doubles as a security scanner. Selectors group
+into four families — compose them with anchors and combinators like
+any other filter:
+
+| Family          | Selectors                                                                        | Ask                                    |
+| --------------- | -------------------------------------------------------------------------------- | -------------------------------------- |
+| Threats         | `:malware` `:squat` `:obfuscated` `:suspicious`                                  | is anything actively hostile?          |
+| Vulnerabilities | `:vuln(critical)` `:cve(CVE-…)` `:cve(*)` `:cwe(CWE-79)` `:severity(">=medium")` | known CVEs / vulns, filter by severity |
+| Capabilities    | `:eval` `:network` `:fs` `:shell` `:env`                                         | what _can_ this code do?               |
+| Hygiene         | `:abandoned` `:unmaintained` `:deprecated` `:score("<=0.5", "maintenance")`      | will this rot on us?                   |
+
+Audit recipes:
+
+```bash
+vlt query ':malware, :vuln(critical), :squat, :obfuscated'   # supply-chain sweep
+vlt query ':workspace > :prod:severity(">=high")'     # release blockers
+vlt query ':dev:shell, :dev:network'                  # dev deps that spawn/phone home
+```
+
+All of these fetch Socket data over the network — expect latency on
+first run.
+
+## Gotchas
+
+- `:workspace` matches workspaces declared in `vlt.json` — yarn/pnpm/
+  bun-style workspace configs aren't read unless mirrored there.
+- `:license(x)` takes a category (`copyleft`, `unlicensed`, `none`,
+  …), never a license ID — for a specific license use the attribute
+  form `[license=MIT]`.
+- `:missing` matches edges (declarations), not nodes — no package
+  output.
+- Quote values with special chars: `[name^="@vltpkg"]`.
+
+## Full reference
+
+Selector-by-selector detail (all pseudo-classes, security insights,
+operators): see [REFERENCE.md](REFERENCE.md).
+
+Canonical docs — deep-link the section that matches the query
+(verified anchors; don't invent others):
+
+| Query topic                               | Link                                                         |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| syntax, composition, anything structural  | <https://docs.vlt.io/cli/selectors/>                         |
+| malware / typosquats / obfuscation        | <https://docs.vlt.io/cli/security#malware-detection>         |
+| CVEs / CWEs / severity                    | <https://docs.vlt.io/cli/security#vulnerability-detection>   |
+| capabilities (`:eval` `:network` `:fs` …) | <https://docs.vlt.io/cli/security#behavioral-security-risks> |
+| license compliance                        | <https://docs.vlt.io/cli/security#license-compliance>        |
+| security scores                           | <https://docs.vlt.io/cli/security#security-scoring>          |

package/skills/dss-query/evals/README.md

@@ -0,0 +1,79 @@
+# dss-query skill evals
+
+How we evaluate the [dss-query](../SKILL.md) agent skill:
+
+Claude's skill-creator plugin "Evaluate a skill" decomposes into three
+different measurements with different levels of rigor
+
+| Layer                  | Question                                                | Method                                                                                      | LLM involved?         | CI-gateable?                                |
+| ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------- |
+| 1. Content correctness | Are the skill's documented selectors valid and current? | Extract selectors from SKILL.md/REFERENCE.md, parse + execute against the real query engine | No                    | Yes — deterministic                         |
+| 2. Content efficacy    | Does the skill make model output measurably better?     | With-skill vs baseline differential, graded deterministically                               | As subject, not judge | Not as a hard gate (single-sample variance) |
+| 3. Trigger efficacy    | Does the skill activate when it should?                 | Repeated trigger-rate sampling on the production model                                      | Yes, unavoidably      | No — probabilistic, monitor only            |
+
+Two principles behind this split, learned the hard way:
+
+- **Never use an LLM as the judge of a skill written for that LLM** —
+  grade with deterministic checks (parse, execute, regex). The LLM may
+  be the _subject_ of an eval, never its grader.
+- **A skill's value is its lift over baseline.** A strong model may
+  already know the domain (correctness lift ≈ 0) while the skill still
+  earns its keep on response style, concision, and latency. Only a
+  with/without differential reveals which.
+
+## Layer 2: the efficacy differential (primary loop)
+
+Lives in [`../../dss-query-workspace/`](../../dss-query-workspace/)
+(gitignored). Test prompts + deterministic assertions are defined in
+[evals.json](evals.json). Each iteration:
+
+1. For every eval, spawn two subagents in the same turn: one told to
+   read and follow the live SKILL.md (**force-loaded** — this removes
+   the trigger confound, see below), one baseline (no skill, or a
+   snapshot of the pre-edit skill when iterating).
+2. Grade every answer with [grade.mjs](grade.mjs) (run from
+   `src/query`:
+   `node skills/dss-query/evals/grade.mjs <iteration-dir>`) — no LLM:
+   - extract selectors from the answer (`vlt query '…'` and bare
+     code-block selectors);
+   - every selector must **parse** via `@vltpkg/dss-parser`;
+   - structural selectors must **execute** via `Query.search()`
+     against the in-memory fixture graph
+     (`src/query/test/fixtures/graph.ts`). Selectors using `:outdated`
+     (registry fetch) or security pseudo-selectors (need the Socket
+     archive) are parse-checked only, so grading stays offline.
+     Comma-separated selectors are split at the top level first —
+     multi-selector lists enable the engine's loose mode, which
+     silently swallows invalid segments;
+   - per-eval regex assertions (expected shape, style contract,
+     required caveats).
+3. Aggregate with skill-creator's `aggregate_benchmark` and review
+   outputs in its eval viewer; human feedback drives the next skill
+   edit, then re-run with the pre-edit snapshot as baseline.
+
+Read the benchmark honestly: pass-rate delta is the skill's
+correctness lift; time/token deltas are its efficiency cost/benefit;
+assertions that pass in **both** configs are non-discriminating — they
+can't detect skill regressions on that model (but may on weaker ones).
+
+## Layer 1: doc-selector validation
+
+Machinery exists in [grade.mjs](grade.mjs) (parse + offline execute);
+a standalone sweep that extracts every selector from
+SKILL.md/REFERENCE.md and validates it the same way is the natural CI
+gate — it catches the regression that actually bites: the query engine
+changes and the skill's documented examples silently go stale.
+
+## Adding cases
+
+Add to [evals.json](evals.json). Prefer deterministic assertions
+(selector parses, executes, matches shape) over prose matching; make
+prompts realistic (casual phrasing, a wrong attempt to correct,
+project context) rather than textbook questions; and verify any
+factual claim an assertion encodes against the engine source first —
+e.g. `:license()` takes only category kinds, so an eval expecting
+`:license(mit)` would grade correct answers as failures.
+
+This directory is excluded from the published `@vltpkg/query` package
+(see the `files` field in `package.json`) — it's repo tooling, not
+part of the skill consumers receive.