dsh-plugin-guide 0.5.0 → 0.5.2

package/SKILL.md

@@ -58,5 +58,7 @@ audit, or market gate. It does not score or rank plugins. When in doubt, link to
 the source document and state what was not run.
 
 For plugin security — capabilities, credentials, egress, install scripts, and
-supply chain — read `docs/security.md`. Its checks are static and advisory,
-and runtime security needs a sandbox, not a checker.
+supply chain — read `docs/security.md`. The security scope is static and shipped
+in `dsh-standards` 1.6.0+; `DSC-15`/`DSC-16`/`DSC-17` can block only under
+`--scope security`, `DSC-21` is WARN-only, and runtime security needs a sandbox,
+not a checker.

package/docs/boost.md

@@ -95,12 +95,13 @@ pitfalls”), record it as a WARN or a note. Do not invent a number.
 
 BOOST measures Cordis practice, not security. A reversible effect or a seam is
 good engineering, and it reduces blast radius, but it is not a sandbox: the
-plugin still shares the host process, the user, and the network. The proposed
-`DSC-15`–`DSC-22` checks are static and advisory outside `--scope security`
-(which `dsh-standards` 1.4.x does not ship yet); they never change a BOOST
-result and none of them proves a plugin safe. Runtime questions — actual egress,
-file reads, prompt corruption — require a sandbox with a network policy and
-capture, not an evidence card. Keep the security claim `not-run` instead of
+plugin still shares the host process, the user, and the network. The static
+`DSC-15`–`DSC-22` checks run in a separate `--scope security` (1.6.0+); outside
+it they are capped to WARN in the separate `security` block. `DSC-15`/`16`/`17`
+can block only under that scope, and `DSC-21` is WARN-only. They never change a
+BOOST result and none of them proves a plugin safe. Runtime questions — actual
+egress, file reads, prompt corruption — require a sandbox with a network policy
+and capture, not an evidence card. Keep the security claim `not-run` instead of
 borrowing BOOST evidence for it. See [security.md](security.md#scope).
 
 ## Run the audit

package/docs/entry.md

@@ -311,27 +311,31 @@ export function apply(ctx) {
 ## Security checks (DSC-15 to DSC-22)
 
 ENTRY is a compatibility gate; it does not answer "is this safe to install". The
-2026-11 audit proposes eight security checks as a separate scope:
+static security scope ships in `dsh-standards` 1.6.0+ and evaluates eight
+checks; with `--scope security` the report's `checks[]` carries all 22
+(`DSC-01`–`DSC-14` plus `DSC-15`–`DSC-22`).
 
 | Check | What it looks for | Verdict in `--scope security` |
 |---|---|---|
-| `DSC-15` | `preinstall`/`install`/`postinstall`/`prepare` that download, decode, or execute | blocking |
-| `DSC-16` | `eval`, `new Function`, `vm`, `module._compile`, `process.binding` | blocking |
+| `DSC-15` | `preinstall`/`install`/`postinstall`/`prepare` that download, decode, or execute (command string and referenced in-package script body, ≤512 KB) | blocking |
+| `DSC-16` | `eval`, `new Function`, `vm`, `module._compile`, `process.binding`; bare `child_process` is WARN in 1.6.1 | blocking |
 | `DSC-17` | reads of `~/.ssh`, `~/.aws`, `.npmrc`, `.netrc`, or credential backing files | blocking |
 | `DSC-18` | non-https, userinfo, bare-IP, webhook/paste/tunnel egress targets | WARN (clue) |
 | `DSC-19` | minified blobs, large base64 blocks, wasm/native without source | advisory |
-| `DSC-20` | tool/web text flowing into the system prompt without a boundary | advisory (runtime, v2) |
-| `DSC-21` | typosquat names, fake scopes, unpinned or script-bearing dependencies | blocking in listing |
+| `DSC-20` | tool/web text flowing into the system prompt without a boundary | advisory (static v1 + runtime hook v2) |
+| `DSC-21` | typosquat names, fake scopes, unpinned or script-bearing dependencies | mandatory but **WARN-only, never blocking** (listing included) |
 | `DSC-22` | `dist.integrity`, signatures, provenance attestations | advisory |
 
-These checks are **not released** in `dsh-standards` 1.4.x, and `--scope
-security` is a proposed flag; if your checker exits `3` for an unknown scope,
-that is expected. Outside that scope they do not run, and a security `FAIL` is
-capped at WARN, so it cannot change an ENTRY verdict. Four are mechanical and
-four only return clues — none of them proves a plugin is safe.
+`--scope security` is released in 1.6.0+; 1.5.x and earlier exit `3` for the
+unknown scope. Outside that scope the eight are not in `checks[]`; a security
+`FAIL` is capped to WARN in the separate `security` block, never enters
+`buckets.blocking`, and cannot change an ENTRY verdict. Only `15`/`16`/`17` can
+block (and only under `--scope security`); `21` never blocks; `18`/`19`/`20`/`22`
+are advice. `DSC-16` subprocess FAIL is scoped to 1.6.2; 1.6.1 keeps a bare
+`child_process` import at WARN.
 
 ```sh
-# proposed; not available in 1.4.x
+# 1.6.0+; exits 3 only on 1.5.x and earlier
 npx dsh-standards ./my-plugin --scope security --format json
 ```
 
@@ -343,6 +347,6 @@ and neither is a `DSC-11` PASS.
 ## What ENTRY does not do
 
 It is not a security audit, sandbox, full contract audit, market gate, score, or
-ranking. Those are separate concerns; do not borrow their authority. The
-proposed `DSC-15`–`DSC-22` are a static security scope, covered in
+ranking. Those are separate concerns; do not borrow their authority. The static
+`DSC-15`–`DSC-22` checks are a separate security scope, covered in
 [security.md](security.md), not part of the ENTRY verdict.

package/docs/flow.md

@@ -205,10 +205,13 @@ example `J2.toggle → 32-DSH-FLOW #R2`).
 ## Security boundary
 
 J5 checks that permissions are declared consistently; it is static preflight,
-not a security test. The proposed `DSC-15`–`DSC-22` live behind a separate
-`--scope security` that `dsh-standards` 1.4.x does not ship yet, and they never
-turn a FLOW journey into a security pass. Outside that scope a security finding
-is advisory: it is capped at WARN and cannot change the FLOW verdict.
+not a security test. The static `DSC-15`–`DSC-22` checks live behind a separate
+`--scope security`, shipped in `dsh-standards` 1.6.0+ (1.5.x and earlier exit
+`3`), and they never turn a FLOW journey into a security pass. Outside that
+scope a security finding is advisory: it is capped to WARN in the separate
+`security` block, never enters `buckets.blocking`, and cannot change the FLOW
+verdict. Under `--scope security` only `DSC-15`/`DSC-16`/`DSC-17` can block;
+`DSC-21` is WARN-only.
 
 Static checks also cannot observe what a plugin does at runtime — which URLs it
 reaches, which files it reads, or whether a prompt was corrupted. Those answers

package/docs/levels.md

@@ -76,10 +76,12 @@ The card fields are in
 
 ## Security is not a fourth layer
 
-Security checks are a **scope**, not a level, and they are proposed, not
-released: `DSC-15`–`DSC-22` sit behind a `--scope security` that
-`dsh-standards` 1.4.x does not have yet. They never change an ENTRY, FLOW, or
-BOOST verdict, and outside that scope a security `FAIL` is capped at WARN.
+Security checks are a **scope**, not a level, and they ship in `dsh-standards`
+1.6.0+ (1.5.x and earlier exit `3` for the unknown scope): `DSC-15`–`DSC-22`
+sit behind `--scope security`. They never change an ENTRY, FLOW, or BOOST
+verdict. Outside that scope a security `FAIL` is capped to WARN in the separate
+`security` block and does not enter `buckets.blocking`; under it only
+`DSC-15`/`16`/`17` can block, and `DSC-21` is WARN-only.
 
 - Static checks only match known source shapes; they cannot see runtime egress,
   file reads, or prompt corruption. Runtime security needs a sandbox with a

package/docs/rules.md

@@ -22,8 +22,10 @@ incomplete/not-run, `3` usage error. `WARN` is not a clean pass and
 The JSON report also carries a sibling `advice[]` array: one entry per live
 detail, with `title`, `why`, `fix`, `docsUrl`, `severity`, and `evidence`. It is
 additive and never changes the verdict (turn it off with `--no-advice`). The
-`docsUrl` follows the checker's `DOCS_BASE` (currently `v0.4.4`); if it points
-at an older page, this table is the current mapping.
+`docsUrl` follows the checker's `DOCS_BASE`: 1.6.1 pins `v0.4.6`, and the 1.6.2
+release moves it to guide `v0.5.0`. The `docs/security.md` anchors used by the
+`C-15`–`C-22` advice exist in 0.5.0; if a link points at an older page, this
+table is the current mapping.
 
 <a id="scope-matrix"></a>
 ## Which checks run in which scope
@@ -35,7 +37,7 @@ at an older page, this table is the current mapping.
 | `--scope entry --entry-claim static` | 01, 02, 11, 12, 13 (+ 03 for listing) | 04–09 are attempted and printed (usually `ERROR`/`NA`), 14 is `NA`; a `DSC-11`/`DSC-12`/`DSC-13` FAIL is downgraded to `WARN` |
 | `--scope entry --entry-claim runtime` | + 14 | 14 carries the runtime verdict, not 04–09 |
 | `--scope mvp` | 01, 02, 04–09 | the MVP subset, labelled `MVP-13` |
-| `--scope security` (proposed, not in 1.4.x) | + 15, 16, 17, 21; 18/19/20/22 advisory; 21 listing only | security scope only; DS-C 01–14 are unchanged and the report gains an additive `security` block |
+| `--scope security` (1.6.0+) | + 15, 16, 17, 21; 18/19/20/22 advisory | `checks[]` becomes 22 (14 + 8); DS-C 01–14 are unchanged and the report gains an additive `security` block. `15`/`16`/`17` blocking, `21` mandatory but WARN-only |
 
 <a id="table"></a>
 ## The check table
@@ -56,24 +58,26 @@ at an older page, this table is the current mapping.
 | **DSC-12** | C-12 credentials + seams | Blocking (ds-c); `WARN` in ENTRY. | Read credentials through `ctx.credentials`, declare `credentials:list` for `listRecords()` and `credentials:provider` for a provider, and never read the backing file. | [entry.md § credentials and seams](entry.md#credentials-and-seams) |
 | **DSC-13** | C-13 labels + mirror | Blocking (ds-c); `WARN` in ENTRY, advisory as a WARN. | Use only the five labels, add the label each capability requires, point `dsh.upstream` at an https URL that is not this package **and** add `mirror`, and drop endorsement words. | [entry.md § labels and mirror](entry.md#labels-and-mirror) |
 | **DSC-14** | C-14 entry run | Blocking only for a runtime claim (`--scope entry`). | Supply the real host: `--host` for a bundle (G0–G3) or `--runtime` for a plugin (L1); a client or preset cannot claim runtime. | [entry.md § runtime surface](entry.md#runtime-surface) |
-| **DSC-15** | C-15 lifecycle scripts (proposed) | **Blocking only under `--scope security`**; not run in the default scopes. | Ship no `preinstall`/`install`/`postinstall`/`prepare`; if one is unavoidable, no download-to-shell, `base64 -d`, or `node -e`. | [security.md § author 4](security.md#author-files) |
-| **DSC-16** | C-16 dynamic execution (proposed) | **Blocking only under `--scope security`**. | Remove `eval`, `new Function`, `vm.runIn*`, `module._compile`, and `process.binding`; dynamic `import()` takes a static path only. | [security.md § author 4](security.md#author-files) |
-| **DSC-17** | C-17 sensitive files (proposed) | **Blocking only under `--scope security`**. | Read credentials through `ctx.credentials`; never read `~/.ssh`, `~/.aws`, `.npmrc`, `.netrc`, or a credential backing file. | [security.md § author 2](security.md#author-credentials) |
-| **DSC-18** | C-18 egress endpoints (proposed) | **WARN** under `--scope security` (clue, not blocking). | Use a constant `https` allowlist, `redirect: 'manual'`, no credentials across origins, and disclose third-party endpoints. | [security.md § author 3](security.md#author-egress) |
-| **DSC-19** | C-19 obfuscation/binary (proposed) | **Advisory** under `--scope security`. | No minified blobs or binary-only code; ship wasm/native with source, build method, and `sha256`. | [security.md § author 4](security.md#author-files) |
-| **DSC-20** | C-20 prompt injection (proposed) | **Advisory** (FLOW runtime, v2), never blocking. | Treat tool/web/file/session text as untrusted, validate `output.schema`, and wrap external text before it reaches a prompt. | [security.md § author 5](security.md#author-prompt) |
-| **DSC-21** | C-21 supply chain (proposed) | **Blocking under `--scope security` in the listing profile**; non-blocking outside a listing. | Commit the lockfile, pin dependencies, reject typosquat/lookalike scopes, and treat an unpinned or script-bearing dependency as `not-run`. | [security.md § author 6](security.md#author-publish) |
-| **DSC-22** | C-22 provenance/integrity (proposed) | **Advisory**, never blocking. | Publish with provenance/attestations; `dist.integrity` only binds the tarball to the registry, not the code to a source. | [security.md § author 6](security.md#author-publish) |
+| **DSC-15** | C-15 lifecycle scripts | **Blocking only under `--scope security`** (1.6.0+); not run in the default scopes. It reads the referenced in-package script body (≤512 KB) as well as the command string. | Ship no `preinstall`/`install`/`postinstall`/`prepare`; if one is unavoidable, no download-to-shell, `base64 -d`, or `node -e`. | [security.md § author 4](security.md#author-files) |
+| **DSC-16** | C-16 dynamic execution | **Blocking only under `--scope security`**. `eval`/`Function`/`vm`/`_compile`/`process.binding` FAIL; a bare `child_process` import is WARN in 1.6.1, and the dangerous-subprocess FAIL is 1.6.2. | Remove `eval`, `new Function`, `vm.runIn*`, `module._compile`, and `process.binding`; dynamic `import()` takes a static path only. | [security.md § author 4](security.md#author-files) |
+| **DSC-17** | C-17 sensitive files | **Blocking only under `--scope security`**. | Read credentials through `ctx.credentials`; never read `~/.ssh`, `~/.aws`, `.npmrc`, `.netrc`, or a credential backing file. | [security.md § author 2](security.md#author-credentials) |
+| **DSC-18** | C-18 egress endpoints | **WARN** under `--scope security` (clue, not blocking). | Use a constant `https` allowlist, `redirect: 'manual'`, no credentials across origins, and disclose third-party endpoints. | [security.md § author 3](security.md#author-egress) |
+| **DSC-19** | C-19 obfuscation/binary | **Advisory** under `--scope security`. | No minified blobs or binary-only code; ship wasm/native with source, build method, and `sha256`. | [security.md § author 4](security.md#author-files) |
+| **DSC-20** | C-20 prompt injection | **Advisory**: static v1 (external text into `systemPrompt`, instruction-like literals) plus a runtime hook in v2; never blocking. | Treat tool/web/file/session text as untrusted, validate `output.schema`, and wrap external text before it reaches a prompt. | [security.md § author 5](security.md#author-prompt) |
+| **DSC-21** | C-21 supply chain | **Mandatory under `--scope security`, but WARN-only and never blocking** (listing included). | Commit the lockfile, pin dependencies, reject typosquat/lookalike scopes, and treat an unpinned or script-bearing dependency as `not-run`. | [security.md § author 6](security.md#author-publish) |
+| **DSC-22** | C-22 provenance/integrity | **Advisory**, never blocking. | Publish with provenance/attestations; `dist.integrity` only binds the tarball to the registry, not the code to a source. | [security.md § author 6](security.md#author-publish) |
 
 `DSC-14` has no `C-14` in the clause text; it is the ENTRY run-set gate
 (`ENT-14` in 31-DSH-ENTRY). Treat it as "did the thing actually start".
 
-`DSC-15`–`DSC-22` are **proposed** by the 2026-11 audit and are not in
-`dsh-standards` 1.4.x. Only `--scope security` makes `15`/`16`/`17` (and `21`
-in a listing) blocking; in every other scope they are absent or capped at WARN,
-and none of them changes the existing DS-C verdict. They are static evidence:
-four can fail mechanically, four only return clues, and no PASS proves a plugin
-safe. The author/user/market checklists are in [security.md](security.md).
+`DSC-15`–`DSC-22` shipped in `dsh-standards` 1.6.0; 1.5.x and earlier treat
+`--scope security` as an unknown scope and exit `3`. Only `--scope security`
+makes `15`/`16`/`17` blocking; `21` is mandatory but WARN-only and never blocks
+(listing included). In every other scope the eight stay out of `checks[]`; their
+FAILs are capped to WARN in the separate `security` block and never change the
+DS-C verdict. They are static evidence: three can fail mechanically, one only
+warns, four only return clues, and no PASS proves a plugin safe. The
+author/user/market checklists are in [security.md](security.md).
 
 <a id="warn"></a>
 ## Two things that look like passes but are not

package/docs/security.md

@@ -8,17 +8,26 @@
 > files, spawn processes, reach the network, and read the credential store
 > whether or not it declares that it does.
 
-`DSC-15`–`DSC-22` are **proposed** security checks from the 2026-11 audit. They
-are not in `dsh-standards` 1.4.x, and `--scope security` is a proposed scope, not
-a released flag. When they ship, four are mechanical (`15`, `16`, `17`, `21`)
-and four only produce clues (`18`, `19`, `20`, `22`); all eight reduce risk, and
-**none of them proves a plugin is safe**. Until then, this page is a checklist,
-not a gate.
-
-The same boundary applies to the existing scopes: outside `--scope security`,
-a security `FAIL` can land in `buckets.blocking` while `status` and the exit
-code stay `0`, because only the mandatory set decides the verdict. Read the
-scope, not the bucket.
+`DSC-15`–`DSC-22` are the **static security checks** shipped in
+`dsh-standards` **1.6.0**; `--scope security` is a released flag
+from 1.6.0 on (1.5.x and earlier treat `security` as an unknown scope and exit
+`3`; 1.6.1 supports it).
+With `--scope security`, `checks[]` carries all **22** checks (`DSC-01`–`DSC-14`
+plus `DSC-15`–`DSC-22`); the default `ds-c` run still carries 14 and reports the
+eight in the additive `security` block. Three can block (`15`, `16`, `17`), one
+is mandatory but **WARN-only and never blocks** (`21`, listing included), and
+four only produce clues (`18`, `19`, `20`, `22`); all eight reduce risk, and
+**none of them proves a plugin is safe**.
+
+The `security` block is a **separate view**, a scope, not a fourth layer. In the default
+scope a security `FAIL` is capped to `WARN` inside `security.checks[]`; it is
+listed only in `security.warn[]` (`security.blocking[]` stays empty), does not
+enter `buckets.blocking` or `conclusion.headline`, and changes neither `status`
+nor the exit code. Only `--scope security` puts `15`/`16`/`17` into `checks[]`,
+where a `FAIL` enters `buckets.blocking`, the headline, `status=fail` and exit
+`1`. `DSC-21` never FAILs, so it never blocks in either profile. Read the scope,
+and read the block's `checks[]`, not just its four arrays — see
+[Reading the `security` block](#security-block).
 
 ## The trust boundary in one table
 
@@ -99,9 +108,10 @@ forward a token "just in case".
 ### 3. Egress endpoints (DSC-18)
 
 Use a constant allowlist of exact hostnames and `https` only. Never fetch a URL
-that came from a model, a tool result, or a user message; redirects are checked
-hop by hop, and a credential is never sent across an origin. Disclose third-party
-endpoints, what is retained, and whether session text is forwarded.
+that came from a model, a tool result, or a user message; use
+`redirect: 'manual'` and refuse a redirect unless every `Location` hop passes the
+same allowlist (bounded), and never send a credential across an origin. Disclose
+third-party endpoints, what is retained, and whether session text is forwarded.
 
 ```ts
 const ALLOW = new Set(['api.example.com'])
@@ -174,9 +184,10 @@ not shell it, and do not let it choose an arbitrary URL.
 ```ts
 import { randomUUID } from 'node:crypto'
 
-const id = randomUUID()
-const wrap = (s: string) =>
-  `<untrusted-${id}>\n${JSON.stringify(s).replaceAll('<', '\\u003c')}\n</untrusted-${id}>`
+const wrap = (s: string) => {
+  const id = randomUUID() // per call, so reused wrappers get a fresh boundary
+  return `<untrusted-${id}>\n${JSON.stringify(s).replaceAll('<', '\\u003c')}\n</untrusted-${id}>`
+}
 ```
 
 Rendering is part of the same boundary: use `textContent`/React escaping, never
@@ -238,10 +249,13 @@ Include the version, DSH version, impact, and a minimal repro. First response wi
 ## User guide
 
 The checks tell you what a package declares; they do not tell you what it does.
-Assume a loaded plugin can do anything the user can. The proposed checks that
-touch this path are `DSC-15` (lifecycle scripts), `DSC-21` (source pinning,
-typosquat), and `DSC-22` (integrity/provenance) before install; `DSC-17`/`DSC-18`
-only ever produce static clues about files and egress.
+Assume a loaded plugin can do anything the user can. The static checks that
+touch this path are `DSC-15` (lifecycle scripts), `DSC-17` (credential files),
+`DSC-21` (typosquat/lookalike names, WARN-only) and `DSC-22`
+(integrity/provenance) before install; `DSC-18` only ever produces a static clue
+about egress. Under `--scope security`, `DSC-15`/`DSC-16`/`DSC-17` can block;
+outside it every security finding is capped to WARN in the separate `security`
+block.
 
 **Before installing.** Read the manifest: `dsh.capabilities`, `dsh.labels`,
 `scripts`, `files`, `engines.dsh`, and the source pin. Then look at the source
@@ -255,16 +269,20 @@ clearance.
 
 ```sh
 npm view pkg@1.2.3 version dsh scripts dist.integrity dist.signatures dist.attestations repository.url time.modified --json
+
+# the released static security scope (1.6.0+; does not run the plugin)
+npx dsh-standards check ./pkg --scope security --json
 ```
 
 **During install.** Start from a throwaway profile (`dsh plugin --profile lab
 ...` initializes it), add `--ignore-scripts`, and understand that it stops
 install scripts only, not the code the host loads. The GUI build approval runs
-a script with your permissions: read the script before approving. The CLI
-inherits your whole environment, so launch it from a clean shell with no
-tokens. A new session defaults to `workspace-write` + `ask`; do not switch to
-`danger-full-access` with `never`. `DSH_PERMISSION_MODE=read-only` constrains
-tool subprocesses, not plugins.
+a script with your permissions, but the approval list shows only the package
+name, not the script body: inspect the referenced script first (`npm pack`, then
+read `scripts/*`). The CLI inherits your whole environment, so launch it from a
+clean shell with no tokens. A new session defaults to `workspace-write` + `ask`;
+do not switch to `danger-full-access` with `never`.
+`DSH_PERMISSION_MODE=read-only` constrains tool subprocesses, not plugins.
 
 ```sh
 dsh plugin --profile lab add pkg@1.2.3 --ignore-scripts
@@ -303,12 +321,21 @@ read from the manifest. Missing data is never a pass. State that static checks
 cover known patterns and are not a security audit. The checker can import the
 plugin, so do not run it against an untrusted package on a host you care about.
 
-**Disputes and delisting.** Hard-reject only four cases: not a plugin /
-unparseable, source not pinnable, impersonation or infringement, and a malicious
-security hold (manual review with an appeal). List everything else with the
-finding attached. The author can withdraw at any time; a 90-day expiry removes
-only the label; a 14-day appeal window; keep history for at least two years and
-write the reason to `market-actions.jsonl`.
+**Disputes and delisting.** Hard-reject only four cases, each with its reason
+code: `not-a-plugin`, `source-not-pinnable`, `impersonation-or-infringement`,
+and `security-hold` (manual review with an appeal). List everything else with
+the finding attached. Market actions are not label fields: every listing and
+rejection is one row of `market-actions.jsonl`
+(`ts/subject/action/reasonCode/evidenceUrls/actor/signature/appealUrl`); a
+rejection carries one of the four reason codes above, and the authoritative
+fields, acting roles, and appeal link are in
+`00-live/market-contract/DECISION-TABLE.md` §2 and
+`00-live/market-contract/CONTRACT.md` §7. The author can withdraw at any time
+(`lifecycle` becomes `withdrawn` at `withdrawnAt`); a 90-day expiry counts from
+the record's `checkedAt` (rev1 records: from `generatedAt` to `expiresAt`) and
+removes only the label; a project-initiated withdrawal must carry a reason and
+evidence and opens a 14-day appeal window counted from `withdrawnAt` (shown as
+`under-review` while open). Keep record history for at least two years.
 
 **Wording ban.** Never write "secure", "certified", "official", "audited", or
 "100% risk-free", and never imply certification with a shield or a checkmark.
@@ -316,7 +343,7 @@ Use the fixed disclaimer: "unofficial · not certified · not security-audited
 not endorsed · no warranty".
 
 <a id="template"></a>
-## Template: minimal secure defaults
+## Template: minimal low-risk defaults
 
 The smallest honest starting point is: no lifecycle scripts, empty
 capabilities, a permissions disclosure marked draft, and a `SECURITY.md` in the
@@ -361,13 +388,37 @@ stale empty array hides the very `C-11.2` failure the check is for.
 
 | Scope | What runs | Verdict |
 |---|---|---|
-| `--scope ds-c` (default) / `entry` / `flow` / `boost` | DSC-01–14 mandatory; DSC-15–22 non-mandatory if implemented | a security `FAIL` is recorded in `blocking` but cannot change `status`/exit |
-| `--scope security` (proposed, not released) | + DSC-15–22 | `15`/`16`/`17` blocking; `21` blocking in the listing profile; `18` WARN; `19`/`20`/`22` advisory |
+| `--scope ds-c` (default) / `entry` / `flow` / `boost` | `DSC-01`–`DSC-14`: only the scope's mandatory subset counts (`DSC-10` is advisory; `03`/`14` can be NA/not-run). `DSC-15`–`DSC-22` run in the separate `security` block (`scope=advisory`) | a security `FAIL` is capped to `WARN` in that block; it is not in `checks[]`/`buckets.blocking` and cannot change `status`/exit |
+| `--scope security` (1.6.0+) | all 22 checks in `checks[]`: DSC-01–14 plus DSC-15–22 | `15`/`16`/`17` blocking (FAIL → exit 1); `21` mandatory **WARN-only**, never blocking (listing too); `18` WARN; `19`/`20`/`22` advisory |
 | runtime observation | sandbox with a network policy + capture | the only evidence that code actually egressed, read a file, or rewrote a prompt |
 
-When the scope ships, the JSON report gets an additive top-level `security`
-block; the DS-C verdicts stay unchanged. A PASS in that block means "no known
-shape matched in this static pass", not "safe".
+`DSC-16` blocks on `eval`/`new Function`/`vm`/`module._compile`/`process.binding`.
+A bare `child_process` import is WARN in 1.6.1; the FAIL for a statically
+dangerous subprocess command is scoped to 1.6.2.
+
+The JSON report carries an additive top-level `security` block; the DS-C verdicts
+stay unchanged. A PASS in that block means "no blocking FAIL, no WARN, and the
+mandatory `15`/`16`/`17`/`21` all produced a result", not "safe".
+
+<a id="security-block"></a>
+### Reading the `security` block
+
+- `conclusion.headline`'s `blocking N` and `buckets.blocking[]` are
+  **report-level**: they only count `checks[]` FAILs. `security.blocking[]` is
+  the block's own list and can only ever hold `DSC-15`/`DSC-16`/`DSC-17`.
+- **Default scope:** the eight run in `security.checks[]` with
+  `security.scope="advisory"`. A `FAIL` is capped to `WARN` (listed in
+  `security.warn[]`), `security.blocking=[]`, no security row appears in
+  `buckets.blocking`, the headline is unchanged, and `status`/exit stay the same.
+- **`--scope security`:** the eight join `checks[]`. A `15`/`16`/`17` FAIL →
+  `security.blocking=[...]` plus `buckets.blocking=[...]`, headline `blocking N`,
+  `status=fail`, exit `1`. `DSC-21` findings are WARN-only and never block;
+  `18`/`19`/`20`/`22` are advisory. A mandatory check with no result makes
+  `security.status=incomplete`.
+- **Partial:** 1.6.1 has no `security.partial[]`. A partly-run check is
+  `security.checks[].coverage === "partial"` (and top-level `coverage.partial` /
+  `buckets.partial`); `security.notRun[]` only carries `NA`/`ERROR`/full
+  `not-run`. Do not read the four arrays as complete coverage.
 
 <a id="limits"></a>
 ## What no static check can tell you

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "A practical guide to DSH plugin quality: ENTRY checks, FLOW checks, and BOOST guidance. Community guide; not official, not a certification, not a ranking.",
   "type": "module",
   "main": "index.js",