@vltpkg/query 1.0.0-rc.32 → 1.0.0-rc.34

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.

package/skills/dss-query/evals/evals.json

@@ -0,0 +1,89 @@
+{
+  "skill_name": "dss-query",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "How do I find outdated direct dependencies of my project root with vlt?",
+      "expected_output": "A vlt query using ':root > :outdated' (optionally with a specifier like major), with a one-line explanation. Concise — query first, no long preamble.",
+      "files": [],
+      "assertions": [
+        "proposes-root-outdated-selector: at least one extracted selector matches /:root\\s*>\\s*:outdated/",
+        "all-selectors-parse: every `vlt query '<sel>'` selector in the answer parses via @vltpkg/dss-parser",
+        "selector-executes-on-fixture-graph: the primary (structural) selector runs through Query.search() against the in-memory fixture graph without throwing",
+        "query-first-style: a fenced code block containing the vlt query appears before any multi-sentence explanation"
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "Write a DSS query for prod dependencies of my workspaces that have a MIT license.",
+      "expected_output": "A vlt query like ':workspace > :prod[license=MIT]' — workspace anchor, direct-dep combinator, prod filter chained with the [license=MIT] attribute. Must NOT suggest ':license(mit)': the :license() pseudo only accepts category kinds (copyleft, unlicensed, none, ...), so specific license IDs require the attribute form.",
+      "files": [],
+      "assertions": [
+        "uses-license-attribute-form: a selector matches /\\[license\\^?=\\s*['\"]?MIT/i (attribute form for a specific license ID)",
+        "avoids-invalid-license-pseudo: the answer does NOT propose :license(mit) — :license() only accepts category kinds, so this would throw 'Expected a valid license kind'",
+        "workspace-prod-anchored: a selector matches /:workspace\\s*>\\s*:prod/",
+        "all-selectors-parse: every extracted selector parses via @vltpkg/dss-parser"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "What vlt query shows me which packages directly depend on react? I keep writing '#react > *' and getting the wrong thing.",
+      "expected_output": "Inverted-direction query using ':has(> #react)' (dependents), correcting the user's '#react > *' (which selects react's dependencies, not its dependents).",
+      "files": [],
+      "assertions": [
+        "uses-has-inversion: a selector matches /:has\\(\\s*>\\s*(#react|\\[name=react\\])\\s*\\)/",
+        "corrects-direction-mistake: states that '#react > *' selects react's DEPENDENCIES (children), i.e. wrong direction for finding dependents (grader quotes evidence)",
+        "does-not-present-wrong-selector-as-answer: '#react > *' is not offered as the solution",
+        "all-selectors-parse: every extracted selector parses via @vltpkg/dss-parser"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "What does the vlt query ':workspace > :prod:cve(*)' do?",
+      "expected_output": "Left-to-right decomposition: workspaces anchor, direct dependencies, production type, has any CVE. Should mention security selectors hit the network (Socket data).",
+      "files": [],
+      "assertions": [
+        "covers-workspace-anchor: explanation mentions workspaces as the starting set (/workspace/i)",
+        "covers-direct-prod-segment: explanation mentions direct AND production dependencies (/direct/i and /prod/i)",
+        "covers-cve-segment: explanation says it matches packages with any known CVE (/cve/i)",
+        "mentions-security-data-source: notes that :cve() uses Socket security data / a network call (/socket|network/i)"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "We just got a supply-chain security alert at work. What vlt queries should I run to audit our dependency graph for malware, typosquats, and obfuscated code?",
+      "expected_output": "A supply-chain sweep using threat selectors — e.g. ':malware(critical), :squat, :obfuscated' (union or separate queries). Notes Socket data / network latency. Offers scoping or follow-up queries.",
+      "files": [],
+      "assertions": [
+        "uses-threat-selectors: selectors include :malware AND at least one of :squat / :obfuscated / :suspicious",
+        "all-selectors-parse: every extracted selector parses via @vltpkg/dss-parser",
+        "mentions-security-data-source: notes Socket data / network fetch (/socket|network/i)",
+        "offers-related-queries: at least 2 distinct selectors offered"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Which of my dev dependencies can run shell commands or hit the network? We're locking down CI.",
+      "expected_output": "Capability query composing :dev with :shell and :network — e.g. ':dev:shell, :dev:network' (chained AND, comma OR). Explains capabilities = what the code can do (Socket static analysis).",
+      "files": [],
+      "assertions": [
+        "uses-capability-selectors: a selector chains :dev with :shell or :network (e.g. :dev:shell)",
+        "covers-both-capabilities: both shell and network are queried (union or two queries)",
+        "all-selectors-parse: every extracted selector parses via @vltpkg/dss-parser",
+        "explains-capability-meaning: explains these match what code CAN do / Socket analysis (/socket|static|capab|can /i)"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Before our release I want to check whether any prod deps of our workspaces have high or critical severity vulnerabilities. What's the vlt query?",
+      "expected_output": "Severity-filtered composition anchored at workspaces — e.g. ':workspace > :prod:severity(\">=high\")' (or union of severity(high), severity(critical)). Explains the comparator and mentions Socket/network.",
+      "files": [],
+      "assertions": [
+        "uses-severity-filter: a selector uses :severity(...) or :sev(...)",
+        "anchors-workspace-prod: a selector matches /:workspace\\s*>\\s*:prod/",
+        "all-selectors-parse: every extracted selector parses via @vltpkg/dss-parser",
+        "mentions-security-data-source: notes Socket data / network fetch (/socket|network/i)"
+      ]
+    }
+  ]
+}