dsh-standards 1.0.3 → 1.2.0

package/40-checker/src/flow-evidence.mjs

@@ -0,0 +1,431 @@
+/**
+ * FLOW evidence chain: `dsh-flow-evidence/2` construction and validation.
+ *
+ * One module owns the shape so the collector and the audit cannot drift:
+ *   - `treeSha256` binds the package directory (read-only copy stays identical);
+ *   - `finalizeEvidence`/`evidenceHash` bind the whole document (chain);
+ *   - `validateFlowEvidence` is the structural gate `level-audit` uses. v1
+ *     (`dsh-flow-journey/1`, `dsh-flow-runtime/1`) and the bare
+ *     `{ "J1": { "status": "pass" } }` shape are recognised only so the audit
+ *     can label them `deprecated`; they never count as a pass.
+ *
+ * Pass rule (per journey, enforced from `checks[]`, never from the declared
+ * status alone): at least one check, every check has exitCode 0, at least one
+ * observed (non-static) check, and every observed check's assertions hold.
+ * A journey declared `warn`/`blocked`/`na`/`static`/`not-run` never counts.
+ */
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const FLOW_IDS = ['J1', 'J2', 'J3', 'J4', 'J5', 'J6', 'J7', 'J8']
+export const FLOW_EVIDENCE_SCHEMA = 'dsh-flow-evidence/2'
+export const FLOW_V1_SCHEMAS = new Set(['dsh-flow-journey/1', 'dsh-flow-runtime/1'])
+export const JOURNEY_STATUSES = new Set(['pass', 'fail', 'warn', 'blocked', 'static', 'na', 'not-run'])
+export const CHECK_KINDS = new Set(['observed', 'static', 'manual'])
+
+const HASH_RE = /^sha256:[0-9a-f]{64}$/
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+const COMMIT_RE = /^[0-9a-f]{40}$/
+const INTEGRITY_RE = /^(?:sha512|sha256)-[A-Za-z0-9+/=]+$/
+
+/** Journey -> normative anchor in 32-DSH-FLOW顺畅规范.md (R1..R8). */
+export const FLOW_CLAUSE_ANCHORS = {
+  J1: '32#R1 安装/移除',
+  J2: '32#R2 启用/停用',
+  J3: '32#R3 配置',
+  J4: '32#R4 首次成功',
+  J5: '32#R5 权限',
+  J6: '32#R6 升级/回滚/卸载',
+  J7: '32#R7 可观测',
+  J8: '32#R8 client/server',
+}
+
+export function clauseAnchor(checkId) {
+  const id = String(checkId ?? '')
+  return FLOW_CLAUSE_ANCHORS[id.slice(0, 2)] ?? null
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function sha256Hex(data) {
+  return crypto.createHash('sha256').update(data).digest('hex')
+}
+
+export function sha256Value(data) {
+  return `sha256:${sha256Hex(data)}`
+}
+
+export function sha256File(file) {
+  return sha256Value(fs.readFileSync(file))
+}
+
+/** JSON with recursively sorted object keys; array order is preserved. */
+export function canonicalJson(value) {
+  const sort = (node) => {
+    if (Array.isArray(node)) return node.map(sort)
+    if (isPlainObject(node)) {
+      const out = {}
+      for (const key of Object.keys(node).sort()) out[key] = sort(node[key])
+      return out
+    }
+    return node
+  }
+  return JSON.stringify(sort(value))
+}
+
+/** Chain hash: every field except `chain` and `signature`. */
+export function evidenceHash(document) {
+  const copy = { ...document }
+  delete copy.chain
+  delete copy.signature
+  return sha256Value(canonicalJson(copy))
+}
+
+export function finalizeEvidence(document) {
+  const output = { ...document }
+  output.chain = { evidenceHash: evidenceHash(output) }
+  return output
+}
+
+export function evidenceHashMatches(document) {
+  const declared = document?.chain?.evidenceHash
+  if (typeof declared !== 'string') return false
+  return declared === evidenceHash(document)
+}
+
+const DEFAULT_TREE_EXCLUDE = ['.git', 'node_modules']
+const TREE_EXCLUDE_ALWAYS = new Set(['.git', 'node_modules'])
+
+/**
+ * Deterministic directory hash: relative path + byte length + file hash for
+ * every regular file, sorted, with `.git`/`node_modules` and `exclude` skipped.
+ * Symlinks are hashed by target string so re-linking cannot pass unnoticed.
+ * Returns `{ hash, files, bytes })` where `hash` is `sha256:<64 hex>`.
+ */
+export function treeSha256(dir, { exclude = [] } = {}) {
+  const root = path.resolve(dir)
+  const skip = new Set([...DEFAULT_TREE_EXCLUDE, ...exclude.map(item => String(item).split(path.sep).join('/'))])
+  const rows = []
+  let bytes = 0
+  const walk = (current, relative) => {
+    const entries = fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    for (const entry of entries) {
+      const rel = relative ? `${relative}/${entry.name}` : entry.name
+      const segments = rel.split('/')
+      if (segments.some(segment => TREE_EXCLUDE_ALWAYS.has(segment))) continue
+      if ([...skip].some(pattern => rel === pattern || rel.startsWith(`${pattern}/`))) continue
+      const absolute = path.join(current, entry.name)
+      if (entry.isDirectory()) {
+        walk(absolute, rel)
+      } else if (entry.isSymbolicLink()) {
+        const target = fs.readlinkSync(absolute)
+        rows.push(`${rel}\0link\0${sha256Hex(target)}`)
+      } else if (entry.isFile()) {
+        const size = fs.statSync(absolute).size
+        bytes += size
+        rows.push(`${rel}\0${size}\0${sha256Hex(fs.readFileSync(absolute))}`)
+      }
+    }
+  }
+  walk(root, '')
+  rows.sort()
+  return { hash: sha256Value(rows.join('\n')), files: rows.length, bytes }
+}
+
+export function isIsoTimestamp(value) {
+  return typeof value === 'string' && ISO_RE.test(value) && Number.isFinite(Date.parse(value))
+}
+
+/**
+ * Aggregate one journey from its checks.
+ * `pass` requires observed evidence; `static` means preflight only; `warn`
+ * means the commands succeeded but an assertion contradicts the claim.
+ */
+export function journeyAggregate(checks) {
+  if (!Array.isArray(checks) || checks.length === 0) return 'not-run'
+  if (checks.some(check => check?.exitCode !== 0)) return 'fail'
+  const observed = checks.filter(check => (check?.kind ?? 'observed') !== 'static')
+  if (observed.length === 0) return 'static'
+  const held = observed.every(check => Array.isArray(check.assertions)
+    && check.assertions.length > 0
+    && check.assertions.every(assertion => assertion?.observed === true))
+  return held ? 'pass' : 'warn'
+}
+
+/** True only when a declared journey status agrees with its checks. */
+export function journeyCountsAsPass(journey) {
+  const derived = journeyAggregate(journey?.checks)
+  const declared = journey?.status ?? null
+  if (derived !== 'pass') return false
+  return declared === null || declared === 'pass'
+}
+
+function emptyVerdict(kind, schema, errors) {
+  return {
+    kind,
+    schema: schema ?? null,
+    valid: false,
+    errors,
+    journeys: {},
+    computedHash: null,
+    declaredHash: null,
+    subject: null,
+    host: null,
+    generatedAt: null,
+    conclusion: null,
+  }
+}
+
+/**
+ * Classify + structurally validate a flow evidence document.
+ * `kind`: `v2` | `v1-deprecated` | `legacy` | `invalid`.
+ */
+export function validateFlowEvidence(document) {
+  if (!isPlainObject(document)) return emptyVerdict('invalid', null, ['root must be a JSON object'])
+  const schema = typeof document.schema === 'string' ? document.schema : null
+  if (schema === FLOW_EVIDENCE_SCHEMA) return validateV2(document)
+  const legacyRows = FLOW_IDS.some(id => isPlainObject(document[id]))
+  if (schema && (FLOW_V1_SCHEMAS.has(schema) || !legacyRows)) {
+    return emptyVerdict('v1-deprecated', schema, [
+      `schema ${schema} is deprecated; only ${FLOW_EVIDENCE_SCHEMA} is accepted`,
+    ])
+  }
+  if (legacyRows || isPlainObject(document.journeys)) {
+    return emptyVerdict('legacy', schema, [
+      'bare {Jx:{status}} rows are deprecated and never count as a pass',
+    ])
+  }
+  return emptyVerdict('invalid', schema, [`unrecognised flow evidence document; expected schema ${FLOW_EVIDENCE_SCHEMA}`])
+}
+
+function validateV2(document) {
+  const errors = []
+  const requireObject = (value, label) => {
+    if (!isPlainObject(value)) {
+      errors.push(`${label} must be an object`)
+      return false
+    }
+    return true
+  }
+  const requireString = (value, label, { allowNull = false, minLength = 1, pattern = null } = {}) => {
+    if (value === null && allowNull) return
+    if (typeof value !== 'string' || value.length < minLength) {
+      errors.push(`${label} must be a non-empty string${allowNull ? ' or null' : ''}`)
+      return
+    }
+    if (pattern && !pattern.test(value)) errors.push(`${label} has an invalid format`)
+  }
+  const requireIso = (value, label) => {
+    if (!isIsoTimestamp(value)) errors.push(`${label} must be an ISO-8601 timestamp`)
+  }
+  const requireHash = (value, label, { allowNull = false } = {}) => {
+    if (value === null && allowNull) return
+    if (typeof value !== 'string' || !HASH_RE.test(value)) errors.push(`${label} must be sha256:<64 lowercase hex>${allowNull ? ' or null' : ''}`)
+  }
+  const requireLog = (value, label) => {
+    if (!requireObject(value, label)) return
+    requireString(value.path, `${label}.path`)
+    requireHash(value.sha256, `${label}.sha256`)
+    for (const key of Object.keys(value)) if (!['path', 'sha256'].includes(key)) errors.push(`${label}.${key} is not allowed`)
+  }
+
+  for (const key of ['schema', 'generatedAt', 'producer', 'subject', 'host', 'journeys', 'claims', 'chain']) {
+    if (!(key in document)) errors.push(`${key} is required`)
+  }
+  if (!errors.includes('schema is required')) {
+    if (document.schema !== FLOW_EVIDENCE_SCHEMA) errors.push(`schema must be ${FLOW_EVIDENCE_SCHEMA}`)
+  }
+  if ('generatedAt' in document) requireIso(document.generatedAt, 'generatedAt')
+  if ('evidenceId' in document) requireString(document.evidenceId, 'evidenceId')
+
+  if (requireObject(document.producer, 'producer')) {
+    requireIso(document.producer.at ?? null, 'producer.at')
+    const command = document.producer.command
+    if (!Array.isArray(command) || command.length === 0 || command.some(item => typeof item !== 'string')) {
+      errors.push('producer.command must be a non-empty array of strings')
+    }
+    if ('kind' in document.producer && document.producer.kind !== null && !['local', 'ci', 'sandbox'].includes(document.producer.kind)) {
+      errors.push('producer.kind must be local, ci, or sandbox')
+    }
+    for (const key of ['runner', 'actor', 'runUrl']) {
+      if (key in document.producer && document.producer[key] !== null) requireString(document.producer[key], `producer.${key}`)
+    }
+  }
+
+  if (requireObject(document.subject, 'subject')) {
+    const subject = document.subject
+    requireString(subject.name, 'subject.name')
+    requireString(subject.version, 'subject.version')
+    requireFieldOrNull(errors, subject, 'integrity', value => requireString(value, 'subject.integrity', { allowNull: true, pattern: INTEGRITY_RE }))
+    requireField(errors, subject, 'tarballSha256', () => requireHash(subject.tarballSha256, 'subject.tarballSha256'))
+    requireFieldOrNull(errors, subject, 'commit', value => requireString(value, 'subject.commit', { allowNull: true, pattern: COMMIT_RE }))
+    requireField(errors, subject, 'treeSha256', () => requireHash(subject.treeSha256, 'subject.treeSha256'))
+    if ('treeSha256After' in subject) requireHash(subject.treeSha256After, 'subject.treeSha256After', { allowNull: true })
+    if ('treeStable' in subject && typeof subject.treeStable !== 'boolean') errors.push('subject.treeStable must be a boolean')
+    if ('treeExclude' in subject) {
+      if (!Array.isArray(subject.treeExclude) || subject.treeExclude.some(item => typeof item !== 'string')) {
+        errors.push('subject.treeExclude must be an array of strings')
+      }
+    }
+    if ('source' in subject) requireString(subject.source, 'subject.source')
+  }
+
+  if (requireObject(document.host, 'host')) {
+    requireString(document.host.dsh, 'host.dsh', { allowNull: true })
+    requireString(document.host.node, 'host.node')
+    requireString(document.host.platform, 'host.platform')
+    for (const key of ['dshCommit', 'cordis']) {
+      if (key in document.host && document.host[key] !== null) requireString(document.host[key], `host.${key}`)
+    }
+  }
+
+  if (requireObject(document.journeys, 'journeys')) {
+    for (const key of Object.keys(document.journeys)) {
+      if (!FLOW_IDS.includes(key)) errors.push(`journeys.${key} is not a known journey (J1-J8)`)
+    }
+    for (const id of FLOW_IDS) {
+      const journey = document.journeys[id]
+      if (!isPlainObject(journey)) {
+        errors.push(`journeys.${id} must be an object`)
+        continue
+      }
+      for (const key of Object.keys(journey)) {
+        if (!['status', 'reason', 'kind', 'checks', 'limitations'].includes(key)) errors.push(`journeys.${id}.${key} is not allowed`)
+      }
+      if ('status' in journey && journey.status !== null && !JOURNEY_STATUSES.has(journey.status)) {
+        errors.push(`journeys.${id}.status must be one of ${[...JOURNEY_STATUSES].join(', ')}`)
+      }
+      if ('reason' in journey && journey.reason !== null) requireString(journey.reason, `journeys.${id}.reason`)
+      if ('limitations' in journey) {
+        if (!Array.isArray(journey.limitations) || journey.limitations.some(item => typeof item !== 'string')) {
+          errors.push(`journeys.${id}.limitations must be an array of strings`)
+        }
+      }
+      if (!Array.isArray(journey.checks)) {
+        errors.push(`journeys.${id}.checks must be an array`)
+        continue
+      }
+      journey.checks.forEach((check, index) => validateCheck(check, `journeys.${id}.checks[${index}]`))
+    }
+  }
+
+  if (requireObject(document.claims, 'claims')) {
+    const claims = document.claims
+    if (!['self-attested', 'ci-attested', 'sandbox-attested'].includes(claims.claimLevel)) {
+      errors.push('claims.claimLevel must be self-attested, ci-attested, or sandbox-attested')
+    }
+    if ('notClaimed' in claims && (!Array.isArray(claims.notClaimed) || claims.notClaimed.some(item => typeof item !== 'string'))) {
+      errors.push('claims.notClaimed must be an array of strings')
+    }
+    if ('method' in claims) requireString(claims.method, 'claims.method')
+  }
+
+  if (requireObject(document.chain, 'chain')) {
+    requireHash(document.chain.evidenceHash, 'chain.evidenceHash')
+    for (const key of Object.keys(document.chain)) if (key !== 'evidenceHash') errors.push(`chain.${key} is not allowed`)
+  }
+  if ('signature' in document && document.signature !== null && !isPlainObject(document.signature)) {
+    errors.push('signature must be null or an object')
+  }
+  if ('conclusion' in document && document.conclusion !== null && !['flow-pass', 'flow-warn', 'flow-blocked', 'flow-fail'].includes(document.conclusion)) {
+    errors.push('conclusion must be flow-pass, flow-warn, flow-blocked, or flow-fail')
+  }
+
+  // Aggregation consistency: declared pass/fail must agree with the checks.
+  const journeys = {}
+  for (const id of FLOW_IDS) {
+    const journey = isPlainObject(document.journeys?.[id]) ? document.journeys[id] : null
+    const checks = Array.isArray(journey?.checks) ? journey.checks : []
+    const derived = journeyAggregate(checks)
+    const declared = journey?.status ?? null
+    const passes = journeyCountsAsPass(journey)
+    journeys[id] = { declared, derived, checks: checks.length, passes }
+    if (declared === 'pass' && derived !== 'pass') errors.push(`journeys.${id} declares pass but its checks aggregate to ${derived}`)
+    if (declared === 'fail' && derived === 'pass') errors.push(`journeys.${id} declares fail but its checks aggregate to pass`)
+  }
+
+  // Chain integrity: recompute over every field except chain/signature.
+  const computedHash = evidenceHash(document)
+  const declaredHash = typeof document.chain?.evidenceHash === 'string' ? document.chain.evidenceHash : null
+  if (declaredHash !== computedHash) {
+    errors.push(`chain.evidenceHash does not match the document (declared ${declaredHash ?? 'missing'}, computed ${computedHash})`)
+  }
+
+  return {
+    kind: 'v2',
+    schema: FLOW_EVIDENCE_SCHEMA,
+    valid: errors.length === 0,
+    errors,
+    journeys,
+    computedHash,
+    declaredHash,
+    subject: isPlainObject(document.subject) ? document.subject : null,
+    host: isPlainObject(document.host) ? document.host : null,
+    generatedAt: document.generatedAt ?? null,
+    conclusion: document.conclusion ?? null,
+  }
+
+  function validateCheck(check, label) {
+    if (!isPlainObject(check)) {
+      errors.push(`${label} must be an object`)
+      return
+    }
+    for (const key of Object.keys(check)) {
+      if (!['id', 'kind', 'command', 'exitCode', 'startedAt', 'endedAt', 'stdout', 'stderr', 'assertions', 'durationMs'].includes(key)) {
+        errors.push(`${label}.${key} is not allowed`)
+      }
+    }
+    requireString(check.id, `${label}.id`, { pattern: /^J[1-8](?:\.[A-Za-z0-9._-]+)?$/ })
+    if ('kind' in check && !CHECK_KINDS.has(check.kind)) errors.push(`${label}.kind must be observed, static, or manual`)
+    if (!Array.isArray(check.command) || check.command.length === 0 || check.command.some(item => typeof item !== 'string')) {
+      errors.push(`${label}.command must be a non-empty array of strings`)
+    }
+    if (!Number.isInteger(check.exitCode) || check.exitCode < 0 || check.exitCode > 255) {
+      errors.push(`${label}.exitCode must be an integer in 0..255`)
+    }
+    requireIso(check.startedAt, `${label}.startedAt`)
+    requireIso(check.endedAt, `${label}.endedAt`)
+    if (isIsoTimestamp(check.startedAt) && isIsoTimestamp(check.endedAt) && Date.parse(check.endedAt) < Date.parse(check.startedAt)) {
+      errors.push(`${label}.endedAt is before startedAt`)
+    }
+    requireField(errors, check, 'stdout', () => requireLog(check.stdout, `${label}.stdout`))
+    if ('stderr' in check) requireLog(check.stderr, `${label}.stderr`)
+    if (!Array.isArray(check.assertions) || check.assertions.length === 0) {
+      errors.push(`${label}.assertions must be a non-empty array`)
+    } else {
+      check.assertions.forEach((assertion, index) => {
+        const alabel = `${label}.assertions[${index}]`
+        if (!isPlainObject(assertion)) {
+          errors.push(`${alabel} must be an object`)
+          return
+        }
+        for (const key of Object.keys(assertion)) if (!['claim', 'observed', 'detail'].includes(key)) errors.push(`${alabel}.${key} is not allowed`)
+        requireString(assertion.claim, `${alabel}.claim`)
+        if (typeof assertion.observed !== 'boolean') errors.push(`${alabel}.observed must be a boolean`)
+        if ('detail' in assertion && assertion.detail !== null) requireString(assertion.detail, `${alabel}.detail`)
+      })
+    }
+    if ('durationMs' in check && (typeof check.durationMs !== 'number' || check.durationMs < 0)) {
+      errors.push(`${label}.durationMs must be a non-negative number`)
+    }
+  }
+}
+
+function requireField(errors, object, key, validate) {
+  if (!(key in object)) {
+    errors.push(`${key} is required`)
+    return
+  }
+  validate()
+}
+
+function requireFieldOrNull(errors, object, key, validate) {
+  if (!(key in object)) {
+    errors.push(`${key} is required`)
+    return
+  }
+  validate(object[key])
+}

package/40-checker/src/index.mjs

@@ -4,5 +4,8 @@ export { runManifestChecks, checkMarketEntry, DEFAULT_RUNTIME_VERSION, inferKind
 export { checkCapabilities, checkCredentials, checkLabels, checkImportTimeAdvisory, CAPABILITIES, LABELS } from './declarations.mjs'
 export { runRuntimeChecks } from './runtime.mjs'
 export { buildReport, formatText, formatSarif, writeReport } 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, treeSha256, validateFlowEvidence } from './flow-evidence.mjs'
+export { sanitizedEnv, scrubProcessEnv, isSecretEnvName, isAllowedEnvName, envPolicy } from './sandbox-env.mjs'

package/40-checker/src/manifest.mjs

@@ -204,6 +204,11 @@ export function runManifestChecks(dir, options = {}) {
     manifestDetails.push(detail('C-1.2', 'PASS', `entry resolves via ${entry.source}: ${entry.relative}`, [entry.relative]))
   } else if (entry.buildHint) {
     manifestDetails.push(detail('C-1.2', 'WARN', `entry not present in checkout; source/build hint exists (${entry.sourceEntry ?? 'build script'})`, ['package.json#scripts']))
+  } else if (kind === 'bundle' && patch.present) {
+    // 2026-11-04: a bundle that ships only a cordis.patch.yml has no runtime entry
+    // by design (dsh.bundle.patch is the carrier). Report NA, not WARN, so the
+    // mandatory coverage is not charged for something the package never claimed.
+    manifestDetails.push(detail('C-1.2', 'NA', 'patch-only bundle; no runtime entry by design', patch.files.map(f => f.relative)))
   } else if (kind === 'bundle' || kind === 'client') {
     manifestDetails.push(detail('C-1.2', 'WARN', `no runtime entry; ${kind} packages may be patch/client only`, ['package.json#exports']))
   } else if (Array.isArray(manifest.workspaces) || (manifest.workspaces && typeof manifest.workspaces === 'object')) {

package/40-checker/src/remediation.mjs

@@ -0,0 +1,132 @@
+/**
+ * Join a dsh-conformance/1 report with the remediation rule table.
+ *
+ * This module is deliberately pure: it never reads files, never writes, and
+ * never changes the report it receives. `buildReport()` calls it at the end so
+ * every report carries additive `advice[]` entries; the checker's verdict is
+ * untouched.
+ */
+
+import packageJson from '../../package.json' with { type: 'json' }
+
+/** Release-pinned guide base. `docs` in the rule table is a relative path. */
+export const DOCS_BASE = 'https://github.com/PerryLink/dsh-plugin-guide/blob/v0.4.4/'
+
+const LIVE = new Set(['FAIL', 'WARN'])
+const SEVERITY_RANK = { FAIL: 2, WARN: 1 }
+
+function tableOf(rules) {
+  if (!rules || typeof rules !== 'object') return {}
+  // Accept either the whole spec/1 object or a bare key→rule map.
+  if (rules.rules && typeof rules.rules === 'object') return rules.rules
+  if (rules.items && typeof rules.items === 'object') return rules.items
+  return rules
+}
+
+function versionOf(rules) {
+  if (rules && typeof rules.version === 'string') return rules.version
+  return typeof packageJson.version === 'string' ? packageJson.version : null
+}
+
+function docsUrlOf(rule, docsBase) {
+  if (!rule || typeof rule.docs !== 'string' || rule.docs.trim() === '') return null
+  const base = String(docsBase ?? DOCS_BASE)
+  const prefix = base.endsWith('/') ? base : `${base}/`
+  return `${prefix}${rule.docs.replace(/^\/+/, '')}`
+}
+
+function uniqueEvidence(...lists) {
+  const seen = new Set()
+  const out = []
+  for (const list of lists) {
+    for (const value of Array.isArray(list) ? list : []) {
+      if (typeof value !== 'string' || value === '' || seen.has(value)) continue
+      seen.add(value)
+      out.push(value)
+    }
+  }
+  return out.slice(0, 10)
+}
+
+/**
+ * Build additive advice from a report.
+ *
+ * One entry is produced per (check.id, detail.item) pair with FAIL/WARN — or,
+ * for a FAIL/WARN check with no live details, one entry keyed by check.clause.
+ * Duplicate details are merged: severity takes the worst value, evidence is
+ * unioned, and the specific reasons are joined for diagnostics.
+ *
+ * @param {object} report dsh-conformance/1 report
+ * @param {object} rules flat key→rule map (also accepts a { rules } or { items } wrapper)
+ * @param {string} [docsBase] absolute release-pinned guide base
+ * @returns {object[]} advice entries
+ */
+export function joinAdvice(report, rules, docsBase = DOCS_BASE) {
+  const table = tableOf(rules)
+  const version = versionOf(rules)
+  const merged = new Map()
+
+  const add = (check, key, severity, reason, evidence) => {
+    if (typeof key !== 'string' || key === '' || !LIVE.has(severity)) return false
+    const id = `${check.id}|${key}`
+    const current = merged.get(id)
+    if (!current) {
+      merged.set(id, {
+        check,
+        key,
+        severity,
+        reasons: typeof reason === 'string' && reason !== '' ? [reason] : [],
+        evidence: uniqueEvidence(evidence),
+        occurrences: 1,
+      })
+      return true
+    }
+    current.occurrences += 1
+    if (typeof reason === 'string' && reason !== '' && !current.reasons.includes(reason)) current.reasons.push(reason)
+    if (SEVERITY_RANK[severity] > SEVERITY_RANK[current.severity]) current.severity = severity
+    current.evidence = uniqueEvidence(current.evidence, evidence)
+    return true
+  }
+
+  for (const check of Array.isArray(report?.checks) ? report.checks : []) {
+    const liveDetails = (Array.isArray(check.details) ? check.details : [])
+      .filter(detail => detail && LIVE.has(detail.result))
+    let added = 0
+    for (const detail of liveDetails) if (add(check, detail.item, detail.result, detail.reason, detail.evidence)) added += 1
+    // A runtime FAIL (DSC-04 / DSC-14) has no details; its clause is the only
+    // joinable key. Only use the fallback when no joinable detail was produced,
+    // so a specific detail always wins over the check-level summary.
+    if (added === 0 && LIVE.has(check.result)) {
+      add(check, check.clause, check.result, check.reason, check.evidence)
+    }
+  }
+
+  const advice = []
+  for (const entry of merged.values()) {
+    const rule = table[entry.key] ?? null
+    const item = {
+      key: entry.key,
+      severity: entry.severity,
+      title: rule?.title ?? entry.key,
+      why: rule?.why ?? null,
+      fix: rule?.fix ?? null,
+      docsUrl: docsUrlOf(rule, docsBase),
+      source: entry.check.id,
+      version,
+      evidence: entry.evidence,
+      reason: entry.reasons.slice(0, 3).join(' | '),
+      occurrences: entry.occurrences,
+      advisory: entry.check.advisory === true,
+    }
+    if (!rule) item.ruleMissing = true
+    advice.push(item)
+  }
+
+  // FAIL before WARN, then key/source for deterministic output.
+  advice.sort((a, b) => (
+    (SEVERITY_RANK[b.severity] ?? 0) - (SEVERITY_RANK[a.severity] ?? 0)
+    || a.key.localeCompare(b.key)
+    || a.source.localeCompare(b.source)
+  ))
+  return advice
+}

package/40-checker/src/report.mjs

@@ -1,4 +1,6 @@
 import path from 'node:path'
+import remediationSpec from '../../spec/remediation.json' with { type: 'json' }
+import { DOCS_BASE, joinAdvice } from './remediation.mjs'
 
 export const PACKAGE_MANDATORY = [
   'DSC-01', 'DSC-02', 'DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09', 'DSC-11', 'DSC-12', 'DSC-13',
@@ -37,7 +39,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' }) {
+export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true }) {
   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'])
@@ -85,7 +87,7 @@ 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(', ')}`)
 
-  return {
+  const report = {
     schema: 'dsh-conformance/1',
     standard: { id: 'DS-C', version: '1.0.0' },
     subject,
@@ -120,6 +122,12 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
       reason: reasonParts.join('; '),
     },
   }
+  // Additive only: `advice` is a sibling of `checks`, never part of a check,
+  // and the verdict is computed above without reading it.
+  if (advice !== false) {
+    report.advice = joinAdvice(report, remediationSpec, DOCS_BASE)
+  }
+  return report
 }
 
 const ICON = { PASS: 'PASS', WARN: 'WARN', FAIL: 'FAIL', NA: 'NA  ', ERROR: 'ERR ' }
@@ -145,6 +153,15 @@ export function formatText(report) {
   lines.push(`coverage: mandatory=${coverage.mandatory} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun}`)
   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) {
+    lines.push('')
+    lines.push('advice (non-blocking):')
+    for (const item of report.advice) {
+      const missing = item.ruleMissing ? ' [ruleMissing]' : ''
+      lines.push(`  ${String(item.severity).padEnd(4)} ${String(item.key).padEnd(7)} ${item.source}${missing}: ${String(item.fix ?? item.title ?? '').replace(/\s+/g, ' ').slice(0, 160)}`)
+      if (item.docsUrl) lines.push(`          ${item.docsUrl}`)
+    }
+  }
   lines.push('')
   return `${lines.join('\n')}\n`
 }