dsh-standards 1.2.2 → 1.3.0

package/40-checker/src/index.mjs

@@ -1,11 +1,11 @@
 /** Programmatic API for dsh-plugin-verify. */
-export { main, parseArgs, usage, VERSION } from './cli.mjs'
+export { main, parseArgs, usage, VERSION, detectHostRuntime, resolveRuntimeAnchor, declarationsOf } from './cli.mjs'
 export { runManifestChecks, checkMarketEntry, DEFAULT_RUNTIME_VERSION, inferKind, resolveEntry } from './manifest.mjs'
 export { checkCapabilities, checkCredentials, checkLabels, checkImportTimeAdvisory, CAPABILITIES, LABELS } from './declarations.mjs'
 export { runRuntimeChecks } from './runtime.mjs'
-export { buildReport, formatText, formatSarif, writeReport } from './report.mjs'
+export { buildReport, formatText, formatSarif, writeReport, summarizeBlocking, DECLARATION_CHECKS } from './report.mjs'
 export { joinAdvice, DOCS_BASE } from './remediation.mjs'
 export { satisfies, validRange, parseVersion, compareVersions } from './semver.mjs'
 export { parseInstallSpec } from './install-spec.mjs'
-export { FLOW_IDS, FLOW_EVIDENCE_SCHEMA, evidenceHash, finalizeEvidence, journeyAggregate, isSandboxAttested, treeSha256, validateFlowEvidence } from './flow-evidence.mjs'
+export { FLOW_IDS, FLOW_EVIDENCE_SCHEMA, evidenceHash, finalizeEvidence, journeyAggregate, isSandboxAttested, treeSha256, validateFlowEvidence, recomputeSubject, bindEvidenceSubject, ciAttribution } from './flow-evidence.mjs'
 export { sanitizedEnv, scrubProcessEnv, isSecretEnvName, isAllowedEnvName, envPolicy } from './sandbox-env.mjs'

package/40-checker/src/report.mjs

@@ -31,6 +31,46 @@ function adjustEntryCheck(item, entryClaim) {
   return { ...item, result: 'WARN', reason: 'C-2.1 version declaration missing/invalid; entry treats it as WARN (C-2.2/C-2.3 remain blocking)' }
 }
 
+/** Declaration-class checks: a WARN here is hygiene, not a loadability defect. */
+export const DECLARATION_CHECKS = new Set(['DSC-11', 'DSC-12', 'DSC-13'])
+const DETAIL_RANK = { FAIL: 5, ERROR: 4, WARN: 3, PASS: 2, NA: 1 }
+
+function bucketRow(item, extra = {}) {
+  return {
+    id: item.id,
+    clause: item.clause ?? null,
+    result: item.result,
+    coverage: item.coverage ?? null,
+    reason: item.reason ?? '',
+    ...extra,
+  }
+}
+
+/**
+ * `entryBlocking` is only sound when every prerequisite was actually evaluated.
+ * C-1.x always produce details; C-3.1/3.2/3.5 only produce them when an install
+ * spec or market index was supplied. Missing details must therefore make
+ * `pass` false instead of silently claiming the gate held.
+ */
+export function summarizeBlocking(checks, blocking) {
+  const seen = new Map()
+  for (const item of checks) {
+    for (const detail of item.details ?? []) {
+      if (!blocking.includes(detail.item)) continue
+      const rank = DETAIL_RANK[detail.result] ?? 0
+      if (!seen.has(detail.item) || rank > (DETAIL_RANK[seen.get(detail.item)] ?? 0)) seen.set(detail.item, detail.result)
+    }
+  }
+  const checked = blocking.filter(id => seen.has(id))
+  // C-2.3 (workspace: range) has no detail when C-2.2 was evaluated against a
+  // normal range; evaluating C-2.2 rules the workspace form out, so count it.
+  if (seen.has('C-2.2') && blocking.includes('C-2.3') && !checked.includes('C-2.3')) checked.push('C-2.3')
+  checked.sort((a, b) => blocking.indexOf(a) - blocking.indexOf(b))
+  const failed = blocking.filter(id => seen.get(id) === 'FAIL')
+  const notChecked = blocking.filter(id => !checked.includes(id))
+  return { required: blocking.length, checked, notChecked, failed, pass: failed.length === 0 && notChecked.length === 0 }
+}
+
 function allowedNa(check, scope, profile, kind) {
   if (check.result !== 'NA') return false
   if (check.id === 'DSC-03' && scope !== 'mvp' && profile === 'package') return true
@@ -39,7 +79,7 @@ function allowedNa(check, scope, profile, kind) {
   return false
 }
 
-export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true }) {
+export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true, declarations = null }) {
   const mandatory = mandatoryFor(scope, profile, staticOnly, entryClaim)
   const adjustedChecks = scope === 'entry' ? checks.map(item => adjustEntryCheck(item, entryClaim)) : checks
   const runtimeIds = new Set(['DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09'])
@@ -59,6 +99,17 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   const warnings = selected.filter(item => item.result === 'WARN')
   const pass = selected.filter(item => item.result === 'PASS')
 
+  // Coverage counts every check the report carries (14 in a full run), not just
+  // the mandatory subset. A report that only counts its mandatory five hides
+  // the runtime checks it never ran; that is the bug this block fixes.
+  const evaluatedAll = effectiveChecks.filter(item => ['PASS', 'WARN', 'FAIL'].includes(item.result))
+  const naAll = effectiveChecks.filter(item => item.result === 'NA')
+  const errorAll = effectiveChecks.filter(item => item.result === 'ERROR')
+  const notRunAll = effectiveChecks.filter(item => item.result !== 'NA' && (item.coverage === 'not-run' || item.coverage === 'partial'))
+  const notRunAllIds = [...new Set([...notRunAll.map(item => item.id), ...errorAll.map(item => item.id), ...missing])]
+  const entryBlockingIds = scope === 'entry' ? (entryClaim === 'static' ? ENTRY_BLOCKING : ENTRY_RUNTIME_BLOCKING) : null
+  const entryBlocking = entryBlockingIds ? summarizeBlocking(effectiveChecks, entryBlockingIds) : null
+
   let status
   let exitCode
   if (failed.length > 0) { status = 'fail'; exitCode = 1 }
@@ -87,6 +138,31 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   if (warnings.length > 0) reasonParts.push(`WARN: ${warnings.map(item => item.id).join(', ')}`)
   if (advisoryWarnings.length > 0) reasonParts.push(`advisory: ${advisoryWarnings.map(item => item.id).join(', ')}`)
 
+  // Findings by reader-relevant bucket. A check appears in exactly one bucket:
+  // FAIL -> blocking, WARN -> hygiene, NA/ERROR/not-run -> notChecked.
+  const blockingBucket = effectiveChecks.filter(item => item.result === 'FAIL').map(item => bucketRow(item))
+  const hygieneBucket = effectiveChecks.filter(item => item.result === 'WARN').map(item => bucketRow(item, {
+    declaration: DECLARATION_CHECKS.has(item.id),
+    advisory: item.advisory === true,
+  }))
+  const notCheckedBucket = effectiveChecks
+    .filter(item => item.result === 'NA' || item.result === 'ERROR')
+    .map(item => bucketRow(item))
+  for (const id of missing) {
+    notCheckedBucket.push({ id, clause: null, result: 'NOT-RUN', coverage: 'not-run', reason: 'mandatory check missing' })
+  }
+  const buckets = { blocking: blockingBucket, hygiene: hygieneBucket, notChecked: notCheckedBucket }
+  const declaredFields = Array.isArray(declarations?.present) ? declarations.present.length : 0
+  const canMarkSuspect = anchor?.suspect === true
+
+  const metrics = {
+    checked: evaluatedAll.length,
+    total: effectiveChecks.length,
+    declaredFields,
+  }
+  const prereq = entryBlocking ? ` (prereq ${entryBlocking.checked.length}/${entryBlocking.required})` : ''
+  const headline = `${scope}/${profile} · runtime ${anchor?.dsh ?? 'unknown'}${anchor?.runtimeSource ? ` ${anchor.runtimeSource}` : ''}${canMarkSuspect ? ' SUSPECT' : ''} · blocking ${buckets.blocking.length}${prereq} · hygiene ${buckets.hygiene.length} · not checked ${buckets.notChecked.length}/${effectiveChecks.length}`
+
   const report = {
     schema: 'dsh-conformance/1',
     standard: { id: 'DS-C', version: '1.0.0' },
@@ -95,21 +171,22 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
     g4,
     checks: effectiveChecks,
     coverage: {
+      total: effectiveChecks.length,
       mandatory: mandatory.length,
-      pass: pass.length,
-      warn: warnings.length,
+      checked: evaluatedAll.length,
+      pass: evaluatedAll.filter(item => item.result === 'PASS').length,
+      warn: evaluatedAll.filter(item => item.result === 'WARN').length,
       advisory: advisoryWarnings.length,
-      fail: failed.length,
-      na: selected.filter(item => item.result === 'NA').length,
-      notRun: notRunIds.length,
-      error: errored.length,
-      entryBlocking: scope === 'entry' ? (() => {
-        const blocking = entryClaim === 'static' ? ENTRY_BLOCKING : ENTRY_RUNTIME_BLOCKING
-        const failedItems = effectiveChecks.flatMap(item => (item.details ?? []).filter(detail => detail.result === 'FAIL' && blocking.includes(detail.item)).map(detail => detail.item))
-        return { required: blocking.length, failed: failedItems, pass: failedItems.length === 0 }
-      })() : null,
+      fail: evaluatedAll.filter(item => item.result === 'FAIL').length,
+      na: naAll.length,
+      notRun: notRunAllIds.length,
+      error: errorAll.length,
+      entryBlocking,
     },
+    buckets,
+    metrics,
     conclusion: {
+      headline,
       level,
       status,
       exitCode,
@@ -132,25 +209,49 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
 
 const ICON = { PASS: 'PASS', WARN: 'WARN', FAIL: 'FAIL', NA: 'NA  ', ERROR: 'ERR ' }
 
+function renderBucket(lines, title, rows, byId) {
+  lines.push(`${title} (${rows.length}):`)
+  if (rows.length === 0) {
+    lines.push('  none')
+    return
+  }
+  for (const row of rows) {
+    const tags = [row.declaration ? 'declaration' : null, row.advisory ? 'advisory' : null].filter(Boolean)
+    const reason = String(row.reason ?? '').replace(/\s+/g, ' ').slice(0, 150)
+    lines.push(`  ${(ICON[row.result] ?? row.result).padEnd(4)} ${String(row.id).padEnd(7)} ${String(row.clause ?? '-').padEnd(6)} ${String(row.coverage ?? '-').padEnd(8)} ${reason}${tags.length > 0 ? ` [${tags.join(',')}]` : ''}`)
+    const item = byId.get(row.id)
+    if (!item || (row.result !== 'FAIL' && row.result !== 'WARN')) continue
+    for (const detail of item.details ?? []) {
+      if (detail.result === 'PASS') continue
+      lines.push(`          - ${detail.item}: ${detail.result} ${String(detail.reason ?? '').replace(/\s+/g, ' ').slice(0, 140)}`)
+    }
+  }
+}
+
 export function formatText(report) {
   const lines = []
-  const { subject, anchor, conclusion, coverage } = report
+  const { subject, anchor = {}, conclusion, coverage } = report
+  const byId = new Map((report.checks ?? []).map(item => [item.id, item]))
   lines.push(`DS-C check — ${subject.name ?? '<unknown>'}@${subject.version ?? '?'} (${subject.kind}${subject.kindInferred ? ', inferred' : ''})`)
-  lines.push(`anchor: repo=${anchor.repo} commit=${anchor.commit.slice(0, 12)} dsh=${anchor.dsh} cordis=${anchor.cordis}`)
+  lines.push(`anchor: repo=${anchor.repo ?? '?'} commit=${String(anchor.commit ?? '').slice(0, 12)} dsh=${anchor.dsh ?? '?'} cordis=${anchor.cordis ?? '?'}${anchor.runtimeSource ? ` source=${anchor.runtimeSource}` : ''}${anchor.suspect ? ' suspect=true' : ''}`)
   lines.push(`scope=${conclusion.scope} profile=${conclusion.profile} status=${conclusion.status} exit=${conclusion.exitCode}${conclusion.subset ? ` subset=${conclusion.subset}` : ''}${conclusion.staticOnly ? ' static-only' : ''}`)
   if (conclusion.level) lines.push(`level: ${conclusion.level}`)
+  if (conclusion.headline) lines.push(`headline: ${conclusion.headline}`)
   lines.push('')
-  lines.push('id      result  clause  layer   reason')
-  for (const item of report.checks) {
-    const reason = (item.reason || '').replace(/\s+/g, ' ').slice(0, 120)
-    lines.push(`${item.id.padEnd(7)} ${ICON[item.result] ?? item.result}  ${item.clause.padEnd(6)} ${item.layer.padEnd(6)} ${reason}`)
-    for (const detail of item.details ?? []) {
-      if (detail.result === 'PASS') continue
-      lines.push(`        - ${detail.item}: ${detail.result} ${String(detail.reason).slice(0, 140)}`)
-    }
-  }
+  renderBucket(lines, 'Blocking (FAIL)', report.buckets?.blocking ?? [], byId)
   lines.push('')
-  lines.push(`coverage: mandatory=${coverage.mandatory} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun}`)
+  renderBucket(lines, 'Hygiene (WARN)', report.buckets?.hygiene ?? [], byId)
+  lines.push('')
+  renderBucket(lines, 'Not checked (NA / not-run / ERROR)', report.buckets?.notChecked ?? [], byId)
+  lines.push('')
+  const passed = (report.checks ?? []).filter(item => item.result === 'PASS')
+  lines.push(`passed (${passed.length}): ${passed.map(item => item.id).join(', ') || 'none'}`)
+  lines.push(`coverage: total=${coverage.total ?? report.checks.length} checked=${coverage.checked ?? coverage.pass + coverage.warn + coverage.fail} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun} error=${coverage.error} advisory=${coverage.advisory}`)
+  if (coverage.entryBlocking) {
+    const blocking = coverage.entryBlocking
+    lines.push(`entryBlocking: checked=${blocking.checked?.length ?? '?'}/${blocking.required} failed=[${(blocking.failed ?? []).join(', ')}] notChecked=[${(blocking.notChecked ?? []).join(', ')}] pass=${blocking.pass}`)
+  }
+  lines.push(`metrics: checked=${report.metrics?.checked ?? '?'}/${report.metrics?.total ?? '?'} declaredFields=${report.metrics?.declaredFields ?? 0}/5`)
   if (conclusion.reason) lines.push(`reason: ${conclusion.reason}`)
   if (conclusion.status === 'incomplete') lines.push('NOT A DS-C PASS: at least one mandatory check did not run (see notRun).')
   if (Array.isArray(report.advice) && report.advice.length > 0) {

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 1.3.0 — 2026-11-06
+
+### Added
+
+- `check [dir]` 子命令：默认 cwd、Markdown 报告（一句结论、≤3 条优先修复、分桶全表、advice、免责声明），`--json` 与 `--html`（单文件、内联 CSS、零依赖）。
+- `spec/schemas/advice.schema.json`（`dsh-advice/1`），advice 逐条过 schema。
+- 证据主体绑定：`--flow-evidence --dir` 校验 name/version/treeSha256/tarball 哈希，不一致即 `invalid`。
+- CI 归属：collector 写 `producer.runUrl/repository/commit`，audit 标 `attestation: self-declared|ci`（不升级 claimLevel）。
+- sidecar 生成（`publish/sidecar.json`，`dsh-market-sidecar/1`）、每日过期/撤回 workflow、离线包（~580 KB）。
+- `SUPPORTED.md`（host × node × checker 矩阵 + 证据锚）与 `CHANGELOG-RULES.md`（规则级变更与影响面）。
+
+### Fixed
+
+- coverage 按全部 14 项统计，`na/notRun/error` 不再为 0；未查 C-3.1/3.2/3.5 时 `entryBlocking.pass=false`，并输出 `checked/notChecked`。
+- 默认 runtime 锚改为宿主实际版本（`anchor.runtimeSource=host`），与 `--runtime-version` 不一致时 `anchor.suspect=true`；不再固定 `0.2.2-alpha.2`。
+- 报告分三桶：`blocking`/`hygiene`（DSC-11/12/13 声明类）/`notChecked`，text 分组渲染，JSON 加 `buckets/metrics/headline`。
+
+### Verified
+
+- `npm test` 193/193（含 root `test/`）。
+
 ## 1.2.2 — 2026-11-06
 
 - FLOW 沙箱：`flow collect --sandbox` 在 `unshare -Urn` + `prlimit` 下运行，记录 `sandbox{}`；env 白名单硬断言 token 不在子进程；进程组超时击杀；`producer.kind=sandbox` 仅当隔离项全部生效，否则 `sandbox-degraded` 且 audit 永不 runtime。测试 152 → 159。

package/README.en.md

@@ -1,8 +1,8 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-dark.svg">
-  <img src="docs/assets/dsh-standards-flow-light.svg" width="100%" alt="dsh-standards pipeline: plugin dir → dsh-standards (DSC-01…13 static) → L1–L3 runtime → report (text/json/sarif, exit 0|1|2|3) → dsh-levels (ENTRY / FLOW / BOOST)">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-hero-en-dark.webp">
+  <img src="docs/assets/dsh-standards-hero-en-light.webp" width="100%" alt="dsh-standards: DSC-01…13 static checks + L1–L3 runtime, reproducible reports">
 </picture>
 
 # dsh-standards
@@ -76,6 +76,11 @@ The full 51-document index lives in the Chinese [README.md](README.md).
 
 </details>
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-v4-dark.svg">
+  <img src="docs/assets/dsh-standards-flow-v4-light.svg" width="100%" alt="dsh-standards pipeline: plugin dir → DSC-01…13 → L1–L3 runtime → report → dsh-levels">
+</picture>
+
 ## Three-step setup
 
 **1. Install** (either way; Node `>=24.9.0`):

package/README.es.md

@@ -1,8 +1,8 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-dark.svg">
-  <img src="docs/assets/dsh-standards-flow-light.svg" width="100%" alt="Flujo de dsh-standards: directorio del plugin → dsh-standards (DSC-01…13 estáticas) → runtime L1–L3 → informe (text/json/sarif, exit 0|1|2|3) → dsh-levels (ENTRY / FLOW / BOOST)">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-hero-en-dark.webp">
+  <img src="docs/assets/dsh-standards-hero-en-light.webp" width="100%" alt="dsh-standards: DSC-01…13 static checks + L1–L3 runtime, reproducible reports">
 </picture>
 
 # dsh-standards
@@ -76,6 +76,11 @@ El índice completo de 51 documentos está en el [README.md](README.md) en chino
 
 </details>
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-v4-dark.svg">
+  <img src="docs/assets/dsh-standards-flow-v4-light.svg" width="100%" alt="dsh-standards pipeline: plugin dir → DSC-01…13 → L1–L3 runtime → report → dsh-levels">
+</picture>
+
 ## Instalación en tres pasos
 
 **1. Instalar** (dos opciones; Node `>=24.9.0`):

package/README.hi.md

@@ -1,8 +1,8 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-dark.svg">
-  <img src="docs/assets/dsh-standards-flow-light.svg" width="100%" alt="dsh-standards प्रवाह: प्लगइन डायरेक्टरी → dsh-standards (DSC-01…13 स्थिर) → L1–L3 रनटाइम → रिपोर्ट (text/json/sarif, exit 0|1|2|3) → dsh-levels (ENTRY / FLOW / BOOST)">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-hero-en-dark.webp">
+  <img src="docs/assets/dsh-standards-hero-en-light.webp" width="100%" alt="dsh-standards: DSC-01…13 static checks + L1–L3 runtime, reproducible reports">
 </picture>
 
 # dsh-standards
@@ -76,6 +76,11 @@ npm पर पुराना आरक्षण `dsh-standards@0.0.3` केव
 
 </details>
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-v4-dark.svg">
+  <img src="docs/assets/dsh-standards-flow-v4-light.svg" width="100%" alt="dsh-standards pipeline: plugin dir → DSC-01…13 → L1–L3 runtime → report → dsh-levels">
+</picture>
+
 ## तीन चरणों में शुरुआत
 
 **1. इंस्टॉल** (दो में से कोई भी; Node `>=24.9.0`):

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-dark.svg">
-  <img src="docs/assets/dsh-standards-flow-light.svg" width="100%" alt="dsh-standards 流程：插件目录 → dsh-standards（DSC-01…13 静态）→ L1–L3 运行时 → 报告（text/json/sarif、exit 0|1|2|3）→ dsh-levels（ENTRY / FLOW / BOOST）">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-hero-zh-dark.webp">
+  <img src="docs/assets/dsh-standards-hero-zh-light.webp" width="100%" alt="dsh-standards：DSC-01…13 静态检查 + L1–L3 运行时，报告可复现">
 </picture>
 
 # dsh-standards
@@ -94,6 +94,11 @@ npm 上的旧占位 `dsh-standards@0.0.3` 只是名字预留，这条 1.x 线取
 
 </details>
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-v4-dark.svg">
+  <img src="docs/assets/dsh-standards-flow-v4-light.svg" width="100%" alt="dsh-standards 流程：插件目录 → DSC-01…13 静态 → L1–L3 运行时 → 报告 → dsh-levels">
+</picture>
+
 ## 三步上手
 
 **1. 安装**（二选一，Node 需 `>=24.9.0`）：

package/README.pt.md

@@ -1,8 +1,8 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-dark.svg">
-  <img src="docs/assets/dsh-standards-flow-light.svg" width="100%" alt="Fluxo do dsh-standards: diretório do plugin → dsh-standards (DSC-01…13 estáticas) → runtime L1–L3 → relatório (text/json/sarif, exit 0|1|2|3) → dsh-levels (ENTRY / FLOW / BOOST)">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-hero-en-dark.webp">
+  <img src="docs/assets/dsh-standards-hero-en-light.webp" width="100%" alt="dsh-standards: DSC-01…13 static checks + L1–L3 runtime, reproducible reports">
 </picture>
 
 # dsh-standards
@@ -76,6 +76,11 @@ O índice completo de 51 documentos está no [README.md](README.md) em chinês.
 
 </details>
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-standards-flow-v4-dark.svg">
+  <img src="docs/assets/dsh-standards-flow-v4-light.svg" width="100%" alt="dsh-standards pipeline: plugin dir → DSC-01…13 → L1–L3 runtime → report → dsh-levels">
+</picture>
+
 ## Instalação em três passos
 
 **1. Instalar** (duas opções; Node `>=24.9.0`):

package/bin/dsh-standards.mjs

@@ -2,6 +2,9 @@
 // Public umbrella entry point for the DSH standards checker.
 // The implementation lives in 40-checker/; this shim keeps the package-level
 // command stable while the checker remains independently runnable from source.
+//
+//   dsh-standards check [dir]   author-facing Markdown / --json / --html report
+//   dsh-standards <dir>         raw checker report (backwards compatible)
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
@@ -15,5 +18,13 @@ if (argv.includes('--version') || argv.includes('-v')) {
   process.exit(0)
 }
 
-process.env.DSH_CHECKER_BRAND = `dsh-standards ${pkg.version} (checker 0.1.0)`
-await import('../40-checker/bin/dsh-plugin-verify.mjs')
+if (argv[0] === 'check') {
+  const { runCheck } = await import('../40-checker/src/author-cli.mjs')
+  const code = await runCheck(argv.slice(1))
+  process.exitCode = code
+  // The checker may have imported a plugin; do not let stray handles hang us.
+  setTimeout(() => process.exit(code), 250)
+} else {
+  process.env.DSH_CHECKER_BRAND = `dsh-standards ${pkg.version} (checker 0.1.0)`
+  await import('../40-checker/bin/dsh-plugin-verify.mjs')
+}

package/docs/assets/dsh-standards-flow-v3-dark.svg

@@ -0,0 +1,87 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1100" height="660" viewBox="0 0 1100 660" role="img" aria-label="dsh-standards pipeline">
+<defs>
+  <linearGradient id="lineGrad" x1="0" y1="0" x2="1" y2="0">
+    <stop offset="0" stop-color="#8496f5" stop-opacity=".15"/>
+    <stop offset=".5" stop-color="#8496f5" stop-opacity=".9"/>
+    <stop offset="1" stop-color="#8496f5" stop-opacity=".15"/>
+  </linearGradient>
+  <filter id="soft" x="-40%" y="-40%" width="180%" height="200%">
+    <feDropShadow dx="0" dy="9" stdDeviation="12" flood-color="#1b1735" flood-opacity="0.55"/>
+  </filter>
+  <pattern id="dots" width="28" height="28" patternUnits="userSpaceOnUse">
+    <circle cx="1.3" cy="1.3" r="1.3" fill="#182031"/>
+  </pattern>
+</defs>
+<rect width="1100" height="660" fill="#0d1117"/>
+<rect width="1100" height="660" fill="url(#dots)" opacity=".5"/>
+<text x="50" y="62" fill="#f0f3f9" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="32" font-weight="700">dsh-standards</text>
+<text x="50" y="90" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="16">static checks, runtime measurement, one reproducible report</text>
+<rect x="50" y="108" width="1000" height="1.6" rx="1" fill="#2a3142"/>
+<g filter="url(#soft)">
+  <rect x="50" y="190" width="176" height="118" rx="17" fill="#161b26" stroke="#2a3142" stroke-width="1.3"/>
+</g>
+<circle cx="74" cy="214" r="12" fill="#242d42"/>
+<text x="74" y="219" text-anchor="middle" fill="#8496f5" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">01</text>
+<text x="138.0" y="256" text-anchor="middle" fill="#f0f3f9" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">plugin dir</text>
+<text x="138.0" y="282" text-anchor="middle" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">the repository</text>
+<path d="M231 249.0 C241.0 249.0, 241.0 249.0, 251 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M241 244.0 l8 5 -8 5" fill="none" stroke="#8496f5" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="256" y="190" width="176" height="118" rx="17" fill="#161b26" stroke="#8496f5" stroke-width="2.6"/>
+</g>
+<circle cx="280" cy="214" r="12" fill="#242d42"/>
+<text x="280" y="219" text-anchor="middle" fill="#8496f5" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">02</text>
+<text x="344.0" y="256" text-anchor="middle" fill="#f0f3f9" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">DSC-01…13</text>
+<text x="344.0" y="282" text-anchor="middle" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">static checks</text>
+<path d="M437 249.0 C447.0 249.0, 447.0 249.0, 457 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M447 244.0 l8 5 -8 5" fill="none" stroke="#8496f5" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="462" y="190" width="176" height="118" rx="17" fill="#161b26" stroke="#2a3142" stroke-width="1.3"/>
+</g>
+<circle cx="486" cy="214" r="12" fill="#242d42"/>
+<text x="486" y="219" text-anchor="middle" fill="#8496f5" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">03</text>
+<text x="550.0" y="256" text-anchor="middle" fill="#f0f3f9" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">L1–L3</text>
+<text x="550.0" y="282" text-anchor="middle" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">runtime measurement</text>
+<path d="M643 249.0 C653.0 249.0, 653.0 249.0, 663 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M653 244.0 l8 5 -8 5" fill="none" stroke="#8496f5" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="668" y="190" width="176" height="118" rx="17" fill="#161b26" stroke="#2a3142" stroke-width="1.3"/>
+</g>
+<circle cx="692" cy="214" r="12" fill="#242d42"/>
+<text x="692" y="219" text-anchor="middle" fill="#8496f5" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">04</text>
+<text x="756.0" y="256" text-anchor="middle" fill="#f0f3f9" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">report</text>
+<text x="756.0" y="282" text-anchor="middle" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">text / json / sarif</text>
+<path d="M849 249.0 C859.0 249.0, 859.0 249.0, 869 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M859 244.0 l8 5 -8 5" fill="none" stroke="#8496f5" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="874" y="190" width="176" height="118" rx="17" fill="#161b26" stroke="#3fb950" stroke-width="2.6"/>
+</g>
+<circle cx="898" cy="214" r="12" fill="#242d42"/>
+<text x="898" y="219" text-anchor="middle" fill="#8496f5" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">05</text>
+<text x="962.0" y="256" text-anchor="middle" fill="#f0f3f9" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">dsh-levels</text>
+<text x="962.0" y="282" text-anchor="middle" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">ENTRY/FLOW/BOOST</text>
+<g filter="url(#soft)">
+  <rect x="462" y="378" width="118" height="58" rx="14" fill="#161b26" stroke="#3fb950" stroke-width="1.2"/>
+</g>
+<text x="486" y="404" fill="#3fb950" font-family="ui-monospace, monospace" font-size="16" font-weight="700">0</text>
+<text x="486" y="423" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit pass</text>
+<g filter="url(#soft)">
+  <rect x="592" y="378" width="118" height="58" rx="14" fill="#161b26" stroke="#d29922" stroke-width="1.2"/>
+</g>
+<text x="616" y="404" fill="#d29922" font-family="ui-monospace, monospace" font-size="16" font-weight="700">1</text>
+<text x="616" y="423" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit fail</text>
+<g filter="url(#soft)">
+  <rect x="722" y="378" width="118" height="58" rx="14" fill="#161b26" stroke="#d29922" stroke-width="1.2"/>
+</g>
+<text x="746" y="404" fill="#d29922" font-family="ui-monospace, monospace" font-size="16" font-weight="700">2</text>
+<text x="746" y="423" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit config</text>
+<g filter="url(#soft)">
+  <rect x="852" y="378" width="118" height="58" rx="14" fill="#161b26" stroke="#d29922" stroke-width="1.2"/>
+</g>
+<text x="876" y="404" fill="#d29922" font-family="ui-monospace, monospace" font-size="16" font-weight="700">3</text>
+<text x="876" y="423" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit runtime</text>
+<rect x="50" y="476" width="1000" height="58" rx="15" fill="#161b26" stroke="#2a3142"/>
+<text x="74" y="502" fill="#8496f5" font-family="ui-monospace, monospace" font-size="13" font-weight="700">static ≠ runtime</text>
+<text x="74" y="522" fill="#a8b1c4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13">a static pass never substitutes for a runtime run; not-run is reported, never upgraded to PASS</text>
+<text x="50" y="596" fill="#a8b1c4" font-family="ui-monospace, monospace" font-size="13">Apache-2.0 + CC-BY-4.0 · PerryLink DSH plugin family</text>
+</svg>

package/docs/assets/dsh-standards-flow-v3-light.svg

@@ -0,0 +1,87 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1100" height="660" viewBox="0 0 1100 660" role="img" aria-label="dsh-standards pipeline">
+<defs>
+  <linearGradient id="lineGrad" x1="0" y1="0" x2="1" y2="0">
+    <stop offset="0" stop-color="#4B67B4" stop-opacity=".15"/>
+    <stop offset=".5" stop-color="#4B67B4" stop-opacity=".9"/>
+    <stop offset="1" stop-color="#4B67B4" stop-opacity=".15"/>
+  </linearGradient>
+  <filter id="soft" x="-40%" y="-40%" width="180%" height="200%">
+    <feDropShadow dx="0" dy="9" stdDeviation="12" flood-color="#1b1735" flood-opacity="0.10"/>
+  </filter>
+  <pattern id="dots" width="28" height="28" patternUnits="userSpaceOnUse">
+    <circle cx="1.3" cy="1.3" r="1.3" fill="#f2f0f8"/>
+  </pattern>
+</defs>
+<rect width="1100" height="660" fill="#ffffff"/>
+<rect width="1100" height="660" fill="url(#dots)" opacity=".5"/>
+<text x="50" y="62" fill="#141419" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="32" font-weight="700">dsh-standards</text>
+<text x="50" y="90" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="16">static checks, runtime measurement, one reproducible report</text>
+<rect x="50" y="108" width="1000" height="1.6" rx="1" fill="#e6e3f0"/>
+<g filter="url(#soft)">
+  <rect x="50" y="190" width="176" height="118" rx="17" fill="#fcfcfe" stroke="#e6e3f0" stroke-width="1.3"/>
+</g>
+<circle cx="74" cy="214" r="12" fill="#ece7f9"/>
+<text x="74" y="219" text-anchor="middle" fill="#4B67B4" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">01</text>
+<text x="138.0" y="256" text-anchor="middle" fill="#141419" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">plugin dir</text>
+<text x="138.0" y="282" text-anchor="middle" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">the repository</text>
+<path d="M231 249.0 C241.0 249.0, 241.0 249.0, 251 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M241 244.0 l8 5 -8 5" fill="none" stroke="#4B67B4" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="256" y="190" width="176" height="118" rx="17" fill="#fcfcfe" stroke="#4B67B4" stroke-width="2.6"/>
+</g>
+<circle cx="280" cy="214" r="12" fill="#ece7f9"/>
+<text x="280" y="219" text-anchor="middle" fill="#4B67B4" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">02</text>
+<text x="344.0" y="256" text-anchor="middle" fill="#141419" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">DSC-01…13</text>
+<text x="344.0" y="282" text-anchor="middle" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">static checks</text>
+<path d="M437 249.0 C447.0 249.0, 447.0 249.0, 457 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M447 244.0 l8 5 -8 5" fill="none" stroke="#4B67B4" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="462" y="190" width="176" height="118" rx="17" fill="#fcfcfe" stroke="#e6e3f0" stroke-width="1.3"/>
+</g>
+<circle cx="486" cy="214" r="12" fill="#ece7f9"/>
+<text x="486" y="219" text-anchor="middle" fill="#4B67B4" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">03</text>
+<text x="550.0" y="256" text-anchor="middle" fill="#141419" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">L1–L3</text>
+<text x="550.0" y="282" text-anchor="middle" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">runtime measurement</text>
+<path d="M643 249.0 C653.0 249.0, 653.0 249.0, 663 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M653 244.0 l8 5 -8 5" fill="none" stroke="#4B67B4" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="668" y="190" width="176" height="118" rx="17" fill="#fcfcfe" stroke="#e6e3f0" stroke-width="1.3"/>
+</g>
+<circle cx="692" cy="214" r="12" fill="#ece7f9"/>
+<text x="692" y="219" text-anchor="middle" fill="#4B67B4" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">04</text>
+<text x="756.0" y="256" text-anchor="middle" fill="#141419" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">report</text>
+<text x="756.0" y="282" text-anchor="middle" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">text / json / sarif</text>
+<path d="M849 249.0 C859.0 249.0, 859.0 249.0, 869 249.0" stroke="url(#lineGrad)" stroke-width="2.2" fill="none"/>
+<path d="M859 244.0 l8 5 -8 5" fill="none" stroke="#4B67B4" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+<g filter="url(#soft)">
+  <rect x="874" y="190" width="176" height="118" rx="17" fill="#fcfcfe" stroke="#16a34a" stroke-width="2.6"/>
+</g>
+<circle cx="898" cy="214" r="12" fill="#ece7f9"/>
+<text x="898" y="219" text-anchor="middle" fill="#4B67B4" font-family="ui-monospace, monospace" font-size="11.5" font-weight="700">05</text>
+<text x="962.0" y="256" text-anchor="middle" fill="#141419" font-family="ui-monospace, monospace" font-size="15.5" font-weight="700">dsh-levels</text>
+<text x="962.0" y="282" text-anchor="middle" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">ENTRY/FLOW/BOOST</text>
+<g filter="url(#soft)">
+  <rect x="462" y="378" width="118" height="58" rx="14" fill="#fcfcfe" stroke="#16a34a" stroke-width="1.2"/>
+</g>
+<text x="486" y="404" fill="#16a34a" font-family="ui-monospace, monospace" font-size="16" font-weight="700">0</text>
+<text x="486" y="423" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit pass</text>
+<g filter="url(#soft)">
+  <rect x="592" y="378" width="118" height="58" rx="14" fill="#fcfcfe" stroke="#bc4c00" stroke-width="1.2"/>
+</g>
+<text x="616" y="404" fill="#bc4c00" font-family="ui-monospace, monospace" font-size="16" font-weight="700">1</text>
+<text x="616" y="423" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit fail</text>
+<g filter="url(#soft)">
+  <rect x="722" y="378" width="118" height="58" rx="14" fill="#fcfcfe" stroke="#bc4c00" stroke-width="1.2"/>
+</g>
+<text x="746" y="404" fill="#bc4c00" font-family="ui-monospace, monospace" font-size="16" font-weight="700">2</text>
+<text x="746" y="423" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit config</text>
+<g filter="url(#soft)">
+  <rect x="852" y="378" width="118" height="58" rx="14" fill="#fcfcfe" stroke="#bc4c00" stroke-width="1.2"/>
+</g>
+<text x="876" y="404" fill="#bc4c00" font-family="ui-monospace, monospace" font-size="16" font-weight="700">3</text>
+<text x="876" y="423" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12.5">exit runtime</text>
+<rect x="50" y="476" width="1000" height="58" rx="15" fill="#fcfcfe" stroke="#e6e3f0"/>
+<text x="74" y="502" fill="#4B67B4" font-family="ui-monospace, monospace" font-size="13" font-weight="700">static ≠ runtime</text>
+<text x="74" y="522" fill="#4d5261" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13">a static pass never substitutes for a runtime run; not-run is reported, never upgraded to PASS</text>
+<text x="50" y="596" fill="#4d5261" font-family="ui-monospace, monospace" font-size="13">Apache-2.0 + CC-BY-4.0 · PerryLink DSH plugin family</text>
+</svg>