dsh-vet 0.2.6 → 0.4.0

package/README.md

@@ -6,10 +6,12 @@ Security vetting for DeepSeek Harness (DSH) plugins: permission & supply-chain
 audits before install, graded via the open [`dsh-vet/v1`](docs/dsh-vet-v1.md)
 report standard.
 
-> **Status: v0.1 shipped.** [`dsh-vet@0.1.0` is live on npm](https://www.npmjs.com/package/dsh-vet) —
-> reference scanner, 15 calibrated rules, public rule rationales, and an
-> 11-package ecosystem sweep record. v0.2 (author-side CI + badges) is next
-> on the [roadmap](ROADMAP.md).
+> **Status: v0.3 underway.** v0.2 shipped the author side — reference
+> scanner ([npm](https://www.npmjs.com/package/dsh-vet), 16 calibrated rules
+> with public rationales), CI Action, and auditable grade badges live in two
+> repos. v0.3 is the ecosystem round: report validation for consumers, the
+> verified-emitter program, and marketplace adoption before the contract's
+> formal freeze ([roadmap](ROADMAP.md)).
 
 ## Install
 
@@ -31,12 +33,33 @@ npx dsh-vet <specifier>          # npm package, git URL, or local path
 npx dsh-vet --json <specifier>   # dsh-vet/v1 report on stdout
 npx dsh-vet --strict <specifier> # exit 1 on findings >= high (confidence >= medium)
 npx dsh-vet --rules dep.install-scripts <specifier>
+npx dsh-vet validate <report.json> # check a report against the contract
+npx dsh-vet diff base.report.json head.report.json --json
 ```
 
 Any completed report exits `0` — grades describe findings, they do not gate.
 Scanner failures exit non-zero. The scanner runs locally, reads the npm
 registry for dependency metadata only, and never transmits audited code.
 
+Every report records what the scan actually covered (`x-dsh-vet` scan
+context: rule profile, coverage, content digests, stable finding
+identities); human output and badges show coverage alongside the grade,
+and a missing context reads as `unknown`, never complete.
+
+### Comparing two reports (release review)
+
+`dsh-vet diff` compares two reports produced by the same scanner version
+and rule profile over complete scans, and reports what changed:
+[`dsh-vet/diff/v1`](docs/report-diff-v1.md) — added/removed/changed
+findings by stable identity, behavior-observation deltas, both sides of
+every transition. Exit `0` for a comparable result regardless of risk
+changes, `1` when the pair cannot be trusted to describe the same
+subject under the same checks (with explicit reasons), `2` on usage or
+invalid reports. Two local-directory scans additionally need
+`--subject <label>`. An incomparable pair is a prompt to rescan both
+artifacts with the same configuration — never a claim that nothing
+changed.
+
 Shipped rules (each with a public rationale under
 [`docs/rules/`](docs/rules)):
 
@@ -61,13 +84,19 @@ from your repo, so its value is auditable through git history and no badge
 service is involved:
 
 ```yaml
-- uses: rogerdigital/dsh-vet/action@v0.2.0
+- uses: rogerdigital/dsh-vet/action@v0.4.0
   with:
     specifier: '.'
     commit-report: true
 ```
 
 Every run uploads the full report as an artifact; PRs get a single
+comment, edited in place. Set `baseline-report` to a report scanned from
+the merge base and PRs additionally show what changed since it — see
+[comparing releases](action/README.md#comparing-releases) for the
+trusted-baseline recipe, and the
+[pilot record](docs/release-risk-pilot.md) for how the comparison
+behaved on real release pairs.
 edited-in-place findings comment. Badge snippet and all inputs:
 [`action/README.md`](action/README.md). The `dsh-vet badge <report.json>`
 command renders the shields endpoint JSON if you wire CI yourself.
@@ -104,8 +133,12 @@ The differentiating piece is not another scanner — it is
 deterministic JSON report contract (findings with severity **and confidence**,
 derived A–F grades) that any scanner may emit and any marketplace, CI job, or
 UI may consume, in the spirit of the community's `dsh-doctor/v1` contract.
-The TypeScript reference types ship from this package; third-party emitters
-are welcome and listed here once verified.
+The TypeScript reference types and the reference markdown renderer ship from
+this package; `dsh-vet validate` checks any report against the contract —
+including the derived grade, so a report from an emitter you don't know can't
+forge one. Third-party emitters are welcome and
+[listed once verified](docs/emitters.md); marketplaces can start from
+[docs/adopt-marketplace.md](docs/adopt-marketplace.md).
 
 ## How it differs
 
@@ -127,12 +160,13 @@ rules get re-examined and the rule set gets corrected in public.
 
 ## Roadmap
 
-- **v0.1** — contract frozen; reference CLI (`dsh vet <pkg>`) with the four
-  check families above
+- **v0.1** — contract shipped (stable, additive-only since 0.1.0) + reference
+  CLI (`dsh-vet <pkg>`) with the four check families above
 - **v0.2** — GitHub Action + badge so plugin authors self-audit and publish
   their grade
-- **v0.3** — marketplace integrations render `dsh-vet/v1` reports; contract
-  adopted by at least one third-party emitter
+- **v0.3** — ecosystem round: `dsh-vet validate` + the verified-emitter
+  program, marketplace integrations rendering `dsh-vet/v1` reports, and the
+  contract's formal freeze after the feedback round
 
 The detailed, trackable plan — task breakdowns, recorded decisions,
 definitions of done, risks, and kill criteria — lives in

package/docs/adopt-marketplace.md

@@ -0,0 +1,83 @@
+# Rendering `dsh-vet/v1` reports in your marketplace
+
+A one-pager for marketplace and catalog maintainers. Short version: your
+users currently judge DSH plugins by vibes at install time; a committed
+`dsh-vet/v1` report gives you a grade, a findings table, and filters from
+one JSON file — with zero servers to run and no endorsement implied.
+
+## Why render reports
+
+- **Demand already exists.** The community's most-upvoted feature request
+  ([deepseek-harness#1115](https://github.com/deepseek-ai/deepseek-harness/discussions/1115))
+  asks for marketplace standards and review mechanisms. The official
+  marketplace will take time.
+- **Authors publish reports already.** The
+  [GitHub Action](https://github.com/rogerdigital/dsh-vet/tree/main/action)
+  audits a plugin on every push and publishes the report + badge to a
+  `dsh-vet/report` branch, so for adopting repos the data is a raw-file URL
+  away — nothing for you to run.
+- **Zero lock-in.** The contract is additive-only, consumers must ignore
+  unknown fields, and the grade ships inside the report — you render it, you
+  never recompute it. Dropping the integration later loses a column, not
+  your site.
+- **Display is not endorsement.** Reports are signals, not verdicts; the
+  spec says so, and the badge says so. You surface what the audit found.
+
+## Three integration paths
+
+**1. The badge (minutes).** Render a shields.io badge from a report:
+
+```sh
+npx dsh-vet badge <report.json>   # → shields endpoint JSON
+```
+
+**2. The findings table (an hour).** Import the reference renderer — the
+same one the GitHub Action uses for PR comments:
+
+```ts
+import { renderMarkdown, validateReport } from 'dsh-vet'
+
+const report = await fetch(reportUrl).then((r) => r.json())
+const { ok } = validateReport(report)      // never trust an unverified emitter
+if (ok) page.add(renderMarkdown(report, { runUrl: reportUrl }))
+```
+
+**3. Ingestion-time validation (for pipelines).** Reject malformed or
+forged reports before they reach your UI — the validator recomputes the
+grade from the findings, so an emitter cannot assert a grade its evidence
+does not support:
+
+```sh
+npx dsh-vet validate report.json && echo structurally-conformant
+```
+
+`validate` proves structural conformance only. It does not prove
+completeness (that the emitter ran every check and omitted nothing),
+artifact identity (that the report describes the plugin version you are
+serving), or provenance (who produced the report). For those guarantees,
+fetch reports through channels you control — the Action's report branch in
+the author's own repo, or a scan you run yourself — and treat reports from
+unverified emitters as unreviewed claims.
+
+## Consumer rules (from the spec)
+
+- **Ignore unknown fields** — emitters may add `x-`-prefixed extras; tolerate
+  them.
+- **Read `summary.grade`; never recompute it.** Grades are derived at emit
+  time by contract.
+- **Never present grade `X`** as a plugin's grade — it marks an incomplete
+  scan.
+- **List findings, don't re-score them.** Severity and confidence are part
+  of the data; a low-confidence finding never lowers a grade, by contract.
+
+## Where reports come from
+
+Plugin authors commit them via the [Action](https://github.com/rogerdigital/dsh-vet/tree/main/action)
+(`dsh-vet/report` branch in their repo), or you can run the scanner yourself
+on any npm-installable plugin: `npx dsh-vet --json <specifier>`. Emitters
+you didn't write must pass `dsh-vet validate` first; verified emitters are
+listed in [emitters.md](emitters.md).
+
+The contract itself: [dsh-vet-v1.md](dsh-vet-v1.md) — stable, additive-only
+since 0.1.0, freezing after this adoption round. Feedback on it is exactly
+what the freeze round is for: [discussions](https://github.com/rogerdigital/dsh-vet/discussions).

package/docs/dsh-vet-v1.md

@@ -1,7 +1,11 @@
 # The `dsh-vet/v1` report contract
 
-Status: **draft** — open for community input before v0.1 freezes it.
+Status: **stable — additive-only since v0.1.0.** Every report the 0.1.0
+reference scanner emitted still validates today. The formal freeze is
+announced with v0.3, after the marketplace-feedback round; until then,
+changes are limited to new optional fields and new rule ids.
 Reference TypeScript types: `src/contract.ts` (shipped from this package).
+Conformance checking: `dsh-vet validate <report.json>`.
 
 `dsh-vet/v1` defines a machine-readable audit report for a DeepSeek Harness
 (DSH) plugin. It is implementation-agnostic: any scanner may emit it, and any
@@ -97,13 +101,43 @@ initially broke vendor-prefixed check ids — do not repeat that.
 
 | Grade | Condition (over findings with confidence ≥ `medium`) |
 |---|---|
-| `A` | none, or only `info`/`low`-severity findings |
+| `A` | no graded findings — the report is empty, or every finding is `info`-severity or `low`-confidence |
 | `B` | worst graded finding is `low` |
 | `C` | worst graded finding is `medium` |
 | `D` | worst graded finding is `high` |
 | `F` | at least one `critical` |
 | `X` | scan incomplete or errored — never presented as the plugin's grade |
 
+## What validation proves — and what it does not
+
+`dsh-vet validate` checks **structural conformance** with this contract:
+field types and enums, rule-id shape, evidence presence, the deterministic
+sort, and — the load-bearing check — that `summary` is exactly what the
+`findings` derive. A conformant report cannot assert a grade its evidence
+does not support.
+
+It does not, and cannot, verify:
+
+- **Emitter honesty** — whether the emitter omitted findings or fabricated
+  evidence. Structural consistency is not evidence that the audit was
+  thorough.
+- **Completeness** — v1 records nothing about which files or rules a scan
+  covered. A subset scan's report is structurally indistinguishable from a
+  full one.
+- **Artifact identity** — nothing ties a report to the artifact you are
+  holding. `target.resolved.integrity` is recorded by the emitter, not
+  checked against your copy.
+- **Provenance** — who actually produced the report, and whether it changed
+  in transit.
+
+Those guarantees come from delivery channels, not from the report's shape:
+see [emitters.md](emitters.md) for how emitters are verified and
+[adopt-marketplace.md](adopt-marketplace.md) for consumer guidance. The
+optional scan-context extension ([scan-context-v1.md](scan-context-v1.md))
+records coverage and content identity; the reference scanner begins
+emitting it in a later release, and until a report carries it, absent
+coverage data means **unknown**, never complete.
+
 ## CLI recommendations (non-normative)
 
 Emitters that ship a CLI should exit `0` whenever a report was produced —
@@ -152,8 +186,9 @@ confidence ≥ `medium` exist, for CI gating.
 
 ## Versioning
 
-`/v1` freezes at the v0.1 release of this package. Backward-compatible
-additions (new optional fields, new rule ids) stay in `/v1`; semantic changes
-get `/v2` with a migration note. Discussion happens in
+`/v1` has been additive-only since the v0.1 release of this package — new
+optional fields and new rule ids stay in `/v1`; semantic changes get `/v2`
+with a migration note. The formal freeze follows the v0.3 marketplace-feedback
+round: afterwards even additive changes land only after public discussion in
 [GitHub Discussions](https://github.com/rogerdigital/dsh-vet/discussions)
 and the [dsh-plugin topic](https://github.com/topics/dsh-plugin).

package/docs/emitters.md

@@ -0,0 +1,57 @@
+# Verified emitters of `dsh-vet/v1`
+
+An **emitter** is any tool that produces `dsh-vet/v1` reports — a scanner
+like this one, a CI integration, a marketplace's own analysis pipeline. The
+contract is only useful if consumers can trust reports from emitters they
+did not write, so this page defines what *verified* means and lists the
+emitters that made it.
+
+## The checklist
+
+An emitter is listed as verified when it meets every item below. The list is
+deliberately short: the contract carries the structure, this carries the
+honesty.
+
+1. **Structure.** Reports are built through `createReport()` from this
+   package, or — for non-TypeScript emitters — every published report passes
+   `dsh-vet validate` (`npx dsh-vet validate <report.json>`). Either path
+   guarantees the derived summary, the deterministic sort, and well-formed
+   rule ids; an emitter that hand-assembles reports and skips validation is
+   not verified. Validation proves structure, not honesty — it cannot
+   detect omitted findings, which is why the remaining items on this list
+   exist.
+2. **Determinism.** Two runs over the same artifact with the same emitter
+   version produce identical reports, `scanner.ranAt` aside.
+3. **Conservative severity.** Findings follow the severity ladder in the
+   [spec](dsh-vet-v1.md#severity-definitions); anything that depends on
+   runtime values is emitted at `low` confidence (or reduced severity), never
+   the reverse. The cost of a false positive is paid by a plugin author.
+4. **Evidence.** Every finding carries at least one evidence item (`file`,
+   and `line` when the emitter has it); snippets are minimal and never
+   include secrets.
+5. **Vendor-prefixed, documented rules.** Third-party rule ids start with
+   the vendor's own segment (`acme.eval-detect`) and each rule has a public
+   rationale page — a rule nobody can dispute in public is a rule nobody
+   should trust.
+6. **A public dispute channel.** A place authors can contest findings, with
+   a visible record of corrections.
+7. **Honest `scanner` fields.** `name` and `version` identify the emitting
+   tool as it actually ran.
+
+## Verification process
+
+1. The emitter's maintainer opens an issue here linking to the emitter and
+   2–3 sample reports against real plugins.
+2. We run `dsh-vet validate` on the samples and read the vendor rule docs,
+   checking severity calibration against the spec ladder (item 3).
+3. Both sides record the verified version range; listings link to the
+   emitter's repo and rule docs. Breaking the checklist later removes the
+   listing, with the reason stated in the issue.
+
+## Registry
+
+| Emitter | Verified versions | Rules | Notes |
+|---|---|---|---|
+| [`dsh-vet`](https://github.com/rogerdigital/dsh-vet) | 0.1.0 – | [`docs/rules/`](rules/) | the reference emitter; self-audited in [`examples/`](../examples/) |
+
+Third-party emitters: none yet — the slot is open.

package/docs/outreach/README.md

@@ -0,0 +1,15 @@
+# Outreach drafts
+
+Ready-to-send drafts. Each file names its destination. The v0.3
+announcement round went live on 2026-09-02 (thread links in ROADMAP.md);
+the release-risk round below is pending. Send from the maintainer's
+account, then record the thread link so feedback has a traceable home.
+
+| File | Destination | Depends on |
+|---|---|---|
+| [deepseek-harness-1115-reply.md](deepseek-harness-1115-reply.md) | reply in [deepseek-harness#1115](https://github.com/deepseek-ai/deepseek-harness/discussions/1115) | npm 0.3.0 published — **sent 2026-09-02** |
+| [show-your-plugins-post.md](show-your-plugins-post.md) | community "Show Your Plugins" thread | 0.3.0 published — **sent 2026-09-02** |
+| [awesome-list-pr.md](awesome-list-pr.md) | PR against a dsh/agent awesome-list | — **merged 2026-09-03** |
+| [dsh-plugin-audit-collab.md](dsh-plugin-audit-collab.md) | issue/DM to dsh-plugin-audit maintainers | — **sent 2026-09-02** |
+| [release-risk-1115-followup.md](release-risk-1115-followup.md) | follow-up in [deepseek-harness#1115](https://github.com/deepseek-ai/deepseek-harness/discussions/1115) | next npm release ships `dsh-vet diff` |
+| [release-risk-pilot-ask.md](release-risk-pilot-ask.md) | issue/DM per target plugin author (template with pre-run results) | — |

package/docs/outreach/awesome-list-pr.md

@@ -0,0 +1,39 @@
+<!-- Destination: PR against a dsh / agent-skills / security-tools awesome list.
+     Swap in the list's entry format (table vs bullet) and category. -->
+
+PR title: `Add dsh-vet — pre-install security audits for DSH plugins`
+
+## What
+
+[dsh-vet](https://github.com/rogerdigital/dsh-vet) — static security vetting
+for DeepSeek Harness plugins, built around an open report contract:
+
+```markdown
+- [dsh-vet](https://github.com/rogerdigital/dsh-vet) — pre-install permission & supply-chain audits
+  for DSH plugins; emits the open `dsh-vet/v1` report (severity + confidence, derived grades),
+  ships a CI Action + auditable badge, and validates/renders reports from any conforming emitter.
+```
+
+or, for table-format lists:
+
+```markdown
+| [dsh-vet](https://github.com/rogerdigital/dsh-vet) | CLI · library · CI Action | Pre-install static audits for DSH plugins; emits and verifies the open `dsh-vet/v1` report |
+```
+
+## Why it fits
+
+- Solves a live pain: the community's top feature request is marketplace
+  review standards (deepseek-harness#1115); incidents like the Full Access
+  home-directory wipe (#461) show the stakes.
+- Not another closed tool: the differentiating artifact is the
+  implementation-agnostic report contract — any scanner may emit it, any
+  marketplace/UI may consume it, `dsh-vet validate` verifies conformance.
+- Maintained in the open: public per-rule rationales, public
+  false-positive dispute process, calibration record against 11 real
+  plugins, self-audited with its own scanner, MIT.
+
+## Checks
+
+- [ ] MIT licensed, docs and tests present, CI green
+- [x] Installable via npm (`dsh-vet`), runs via `npx`, zero runtime deps
+      beyond the parser

package/docs/outreach/deepseek-harness-1115-reply.md

@@ -0,0 +1,38 @@
+<!-- Destination: reply in deepseek-ai/deepseek-harness discussion #1115
+     (marketplace standards / review mechanisms). Send after 0.3.0 is on npm. -->
+
+Sharing what we built against exactly this problem, in case it's useful
+before an official marketplace lands.
+
+The core idea: "should I install this plugin?" needs a **shared,
+machine-readable answer**, not per-tool vibes. So the contract came first —
+[`dsh-vet/v1`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/dsh-vet-v1.md),
+an implementation-agnostic audit report (findings with severity *and*
+confidence, derived A–F grades), following the pattern `dsh-doctor/v1`
+proved: freeze a small boring contract, compete on implementations.
+
+On top of it:
+
+- **A reference scanner** ([dsh-vet on npm](https://www.npmjs.com/package/dsh-vet)) —
+  static, deterministic, never installs or transmits the audited plugin.
+  16 rules across capability seams, supply chain, obfuscation, and data
+  egress; every rule has a public rationale page and a public dispute
+  template. Calibrated against 11 real ecosystem plugins
+  ([sweep record](https://github.com/rogerdigital/dsh-vet/blob/main/docs/calibration-v0.1.md)).
+- **Author-side CI** — a GitHub Action that audits on every push and
+  publishes the report + grade badge from the plugin's own repo (zero
+  server; the badge value is auditable through git history). Live in two
+  repos already, including the scanner's own self-audit.
+- **A consumer story** — `dsh-vet validate` checks any report against the
+  contract (grade is recomputed from findings, so an emitter can't forge
+  one), and `renderMarkdown` gives marketplaces/UIs the same rendering the
+  Action uses: [adopting it](https://github.com/rogerdigital/dsh-vet/blob/main/docs/adopt-marketplace.md).
+
+The contract has been additive-only since 0.1.0 — every report the first
+release emitted still validates today. **We're actively seeking feedback
+from marketplace and tool maintainers before formally freezing `/v1`.** If
+you're building a catalog or review layer, this round is exactly for you:
+what would you need the report to carry?
+
+Happy to go deeper on any piece — severity calibration, false-positive
+handling, or the freeze criteria.

package/docs/outreach/dsh-plugin-audit-collab.md

@@ -0,0 +1,37 @@
+<!-- Destination: issue on dsh-plugin-audit's repo (or DM to its maintainers).
+     Tone: peer-to-peer, one concrete ask (a conversation), no commitment demanded. -->
+
+Hi — maintainer of [dsh-vet](https://github.com/rogerdigital/dsh-vet) here.
+Your runtime-sentinel work is in our README's comparison table as the
+complementary half of this problem, and I'd like to make that explicit
+instead of just documented on our side.
+
+The shape of it:
+
+- **dsh-vet** answers *"what does this plugin do?"* **before install** —
+  static analysis, emitted as the open
+  [`dsh-vet/v1`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/dsh-vet-v1.md)
+  report (findings with severity + confidence, derived grades, evidence per
+  finding).
+- **dsh-plugin-audit** answers *"what is it doing right now?"* at runtime —
+  permission profiling and sentinels.
+
+Static-before-install and runtime-during-use cover different failure modes
+(obfuscated payloads vs. behavior that only emerges live), which is why we
+list you as complementary rather than competing — and why we'd rather
+coordinate than FUD.
+
+Two things that might be cheap and useful, if you're interested:
+
+1. **Shared vocabulary.** Our report contract deliberately leaves rule ids
+   open-ended (`acme.eval-detect` style vendor prefixes). If your runtime
+   findings ever want a common shape — severity/confidence semantics,
+   evidence, dispute channels — the contract is additive-only and open for
+   feedback before its formal freeze. You'd be the most natural co-author
+   of whatever `/v1` learns from runtime auditing.
+2. **Cross-linking.** We already point to you as the runtime half; a link
+   back from your side (if you find the pre-install half useful) would let
+   users find the full stack.
+
+No ask beyond a conversation — if either half sounds useful, I'm happy to
+open a discussion with concrete details.

package/docs/outreach/release-risk-1115-followup.md

@@ -0,0 +1,37 @@
+<!-- Destination: follow-up comment in deepseek-ai/deepseek-harness discussion #1115
+     (marketplace standards / review mechanisms), under our 2026-09-02 reply.
+     Depends on: an npm release that ships `dsh-vet diff` (next version) —
+     send from the maintainer's account, then record the thread link in ROADMAP. -->
+
+Following up with the piece the contract was missing: **what changed since
+the last release**.
+
+"Should I install this plugin?" got a machine-readable answer with
+`dsh-vet/v1`. "Should I *upgrade*?" now has one too:
+
+- Every report records **what the scan actually covered** — rule profile,
+  coverage, content digests, stable finding identities — as an optional
+  `x-dsh-vet` extension ([spec](https://github.com/rogerdigital/dsh-vet/blob/main/docs/scan-context-v1.md)).
+  A grade no longer silently means "whatever subset happened to run":
+  partial coverage says so, in the CLI, the PR comment, and the badge.
+- `dsh-vet diff` compares two reports from the same scanner and profile
+  and reports added / removed / changed risk by **stable identity** —
+  line moves and reformatting are not risk additions, a second endpoint
+  is ([diff spec](https://github.com/rogerdigital/dsh-vet/blob/main/docs/report-diff-v1.md)).
+  Two reports that can't be honestly compared say so with explicit
+  reasons instead of a fake "no changes".
+- The GitHub Action takes an optional `baseline-report` scanned from the
+  merge base, so PRs show exactly what risk-relevant behavior the PR
+  introduces — with a recipe that keeps the baseline out of the PR's
+  control ([action docs](https://github.com/rogerdigital/dsh-vet/blob/main/action/README.md#comparing-releases)).
+
+We piloted it on real releases —
+[left-pad and chalk, every reported addition reconciled against the
+code](https://github.com/rogerdigital/dsh-vet/blob/main/docs/release-risk-pilot.md).
+The chalk case is the interesting one: 5.x vendored its dependencies and
+the diff flagged exactly the two vendored files unreachable through the
+`#`-imports map — nothing else moved.
+
+If you maintain a plugin and want the same read on your last two
+releases, reply here or open an issue — we'll run the comparison and
+post the result for you to check against what you actually changed.

package/docs/outreach/release-risk-pilot-ask.md

@@ -0,0 +1,71 @@
+<!-- Destination: issue (or DM) to the author of each target plugin, one
+     thread per plugin. The template below is filled with real pre-run
+     results — send as-is; the recipient installs nothing and answers from
+     their own knowledge of the release. Send from the maintainer's account,
+     then record each thread link in docs/release-risk-pilot.md. -->
+
+# Release-risk pilot ask (template)
+
+Subject: `Did your last release change what your plugin can do? (2-minute check)`
+
+Hi — I maintain [`dsh-vet`](https://github.com/rogerdigital/dsh-vet), the
+static audit tool for DSH plugins. It just learned to **compare two
+releases of the same plugin and report exactly what risk-relevant
+behavior changed** — new endpoints, new capabilities, new install
+scripts, changed confidence — while ignoring line moves and reformatting.
+
+I ran it on your last two releases so you don't have to install anything.
+The results are below; three questions at the end.
+
+---
+
+## Filled example — dsh-doctor 0.4.2 → 0.4.3
+
+Both scans: same scanner, full rule profile, complete coverage. Grades
+stayed **D → D**. What moved:
+
+- **New network client call** in `lib/client.js` — the destination is
+  computed at runtime, so the scanner can't see where it sends
+  (`perm.network-client`, subject `runtime-target`).
+- **Subprocess spawns went from 1 to 2** in `lib/index.js`
+  (`child_process.spawn`).
+
+Nothing else changed (13 identities unchanged).
+
+## Filled example — dsh-searxng 0.2.1 → 0.3.0
+
+Grades stayed **A → A**. One transition: **write/delete calls with
+runtime-computed targets went from 1 to 17** in `lib/cli.mjs`
+(`perm.undeclared-fs-write`, dynamic variant). These are low-severity /
+low-confidence — they never affect the grade — but the count jump is the
+kind of thing worth a look during a minor bump.
+
+## Filled example — dsh-wechat 0.9.5 → 0.9.6
+
+**Zero risk-relevant changes.** All 7 audited behaviors identical, grade
+C → C. If that matches your intent for the release, the diff just saved
+you the re-review.
+
+---
+
+## The three questions
+
+1. Does the reported delta match what you intended to change in that
+   release? Anything you'd flag that the scanner missed or got wrong?
+2. Any entries that felt like noise (didn't help you understand the
+   release)?
+3. If this ran automatically on your PRs against the base revision —
+   [one Action input](https://github.com/rogerdigital/dsh-vet/blob/main/action/README.md#comparing-releases) —
+   would you read it before merging?
+
+Answers in any form are useful; I'll record anonymized takeaways in the
+[pilot record](https://github.com/rogerdigital/dsh-vet/blob/main/docs/release-risk-pilot.md).
+This is the last feedback loop before deciding whether to build CI
+gating on top (opt-in "fail on new risk"), so negative answers are as
+valuable as positive ones.
+
+<!-- Per-send checklist:
+     - re-run the pair with the latest main build the day of sending
+     - paste the actual result block for THIS author's package
+     - keep grades/identities verbatim from the diff, don't paraphrase
+     - one package per thread; don't batch multiple authors -->

package/docs/outreach/show-your-plugins-post.md

@@ -0,0 +1,41 @@
+<!-- Destination: a community "Show Your Plugins" / project showcase thread.
+     Adjust the opening line to the thread's framing. Send after 0.3.0 is on npm. -->
+
+**dsh-vet** — know what a plugin does *before* you install it.
+
+DSH's everything-is-a-plugin model is its superpower and its attack surface:
+an installed plugin can touch your filesystem, spawn processes, and open
+network connections. After the incident where a Full Access session wiped a
+user's home directory, "should I install this?" deserved better than vibes.
+
+dsh-vet audits any npm-installable DSH plugin — statically, locally, without
+installing or executing it — and emits an open, deterministic
+[`dsh-vet/v1`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/dsh-vet-v1.md)
+report: findings with severity **and** confidence, and a derived A–F grade
+where a low-confidence finding never counts against you.
+
+```sh
+npx dsh-vet <plugin>        # human summary
+npx dsh-vet --json <plugin> # full dsh-vet/v1 report
+```
+
+What makes it defensible rather than noisy:
+
+- **Every rule has a public rationale** and a public false-positive dispute
+  template; disputed rules get corrected in the open (it has happened, and
+  the changelog shows it).
+- **Calibrated on real plugins** — an 11-package sweep record is published,
+  including grades and the two tunings the sweep forced.
+- **It audits itself** — the repo's own grade badge is generated from the
+  exact tarball that ships to npm, and every signal the scanner finds in
+  itself is in the published report.
+
+For plugin authors: a [GitHub Action](https://github.com/rogerdigital/dsh-vet/tree/main/action)
+audits on every push and publishes your grade badge from your own repo —
+no badge service, the value is auditable through your git history. For
+catalog/UI builders: [`dsh-vet validate`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/adopt-marketplace.md)
+ingests and verifies reports from any conforming emitter.
+
+The contract is additive-only since 0.1.0 and open for feedback before the
+formal freeze. Repo: [rogerdigital/dsh-vet](https://github.com/rogerdigital/dsh-vet) —
+criticism on severity calibration is genuinely welcome.