dsh-scout 0.9.0 → 0.9.2

package/docs/dsh-scout-product-contract.md

@@ -3,7 +3,26 @@
 状态：Draft 0.1
 目标：把公司与岗位尽调收敛为一个可复现、可追溯、能支持下一步行动的 DSH 场景插件。
 
-当前实现进度：首个公开切片已经覆盖 session 隔离的内存 case、封闭来源类型、主体核验、claim 证据历史、保守三态决策、结构化报告、卸载清理和临时 DSH profile 安装门禁；v0.2 已落地持久化五文件导出（`scout_export` / `scout_import`，含可回放事件流 `events.jsonl` 与导入后决策重算）；v0.3 已落地可配置存储（`scoutDir` / `autoPersist` 插件配置）与面试问题生成（`scout_questions`）；v0.4 已落地信息采集登记（`scout_ingest`：批量登记采集结果并按 URL 自动推断来源类型与证据等级）；v0.5 已落地公司/岗位对比（`scout_compare`：2–5 案例并排对比报告与合并面试问题）；v0.6 已落地采集→主张流转（`scout_ingest` 支持 claim 草稿，登记来源同时自动添加主张）；v0.7 已落地 Provider 深度集成（`scout_search`：接入 DSH Web Provider，搜索结果自动登记为来源）。
+当前实现进度：首个公开切片已经覆盖 session 隔离的内存 case、封闭来源类型、主体核验、claim 证据历史、保守三态决策、结构化报告、卸载清理和临时 DSH profile 安装门禁；v0.2 已落地持久化五文件导出（`scout_export` / `scout_import`，含可回放事件流 `events.jsonl` 与导入后决策重算）；v0.3 已落地可配置存储（`scoutDir` / `autoPersist` 插件配置）与面试问题生成（`scout_questions`）；v0.4 已落地信息采集登记（`scout_ingest`：批量登记采集结果并按 URL 自动推断来源类型与证据等级）；v0.5 已落地公司/岗位对比（`scout_compare`：2–5 案例并排对比报告与合并面试问题）；v0.6 已落地采集→主张流转（`scout_ingest` 支持 claim 草稿，登记来源同时自动添加主张）；v0.7 已落地 Provider 深度集成（`scout_search`：接入 DSH Web Provider，搜索结果自动登记为来源）；v0.8.x 完成 npm 首发与 DSH 0.2 rc 通道对齐（`exports` 映射、Schemastery `Config` 声明、profile smoke 门禁）；v0.9.0 适配 DSH 0.2 运行时，并建立四个精确版本的兼容矩阵与夜间兼容检查。
+
+**v0.9.1** 把插件从「能跑」推到「在真实 DSH 里表现正确、便宜、可解释」，主题是接缝而不是新功能：
+
+- **输出契约**：变更类工具不再回吐整份 case JSON，改为「结构化对象 `value` + 整串（含省略号）不超过 1 KB 的紧凑 render」；全量数据仍由 `scout_report` / `scout_export` 提供。
+- **落盘可信度**：`autoPersist` 失败可见化（返回值 `persist.persisted=false` + `persist.error`）；导出统一为「先记事件、后写文件」；导出目录写 `export.complete.json` 完成标记（**先置 `complete:false`、五文件写完再置 `complete:true`**）；`scout_import` 读标记的 `complete` 字段，缺失或不完整时报告 `complete: false`；写盘转发 `exec.signal`。
+- **服务绑定与路径**：`fs` / `web` 改为调用时解析（不再在 `apply()` 时快照）；导出返回解析后的绝对路径；缓存未命中时，**只有完整导出**（完成标记 `complete: true`）才从 `<scoutDir>/<caseId>/` 惰性回填并记 `case_rehydrated`（0.9.0 旧导出无完成标记，需显式 `scout_import`）。案例对齐只在 `decide` 路径生效（重算决策的工具调用与缓存未命中时的惰性回填经过它；回填由第一个访问该 case 的工具调用触发，所以冷启动后即使只调 `scout_report` 也可能带上一次对齐）；**直接读磁盘 `case.json`、从不经过插件的第三方工具看不到对齐**。
+- **可解释与双语**：新增 `language: 'zh-CN' | 'en'`（默认 `zh-CN`），未编辑的出厂默认文案会自动对齐到部署语言——精选面试问题按**下标逐条**判定（长度与出厂数组相同时逐条替换，用户改过的那条保持原样；长度不同则整组原样保留），`decisionObjective` / `role.fitQuestion` 逐字段判定；报告新增 `## Coverage` 调查覆盖度区块。
+- **显式入口**：新增 `/scout` 命令（`status` / `questions` / `report` / `export` 四个子动作）与插件注册的 `scout` Skill。
+- **分发契约**：`engines.dsh`、`dsh.manifestVersion: 1`、`locale/en.json` + `locale/zh.json`（必须写进 `exports`，否则被静默忽略）、包内 `icon`。
+
+0.9.1 明确不做的事见 [CHANGELOG](../CHANGELOG.md)：client 面板、自造 session event、`ctx.storageDomain` 持久化重写、评分与排名（0.9.2 沿用同一非目标）。
+
+**v0.9.2（当前版本）**是收口版本：把 0.9.1 验证报告点名的最大盲区（U11）补成真实宿主门禁，并清掉三轮独立验证留下的文档税。本版本**不新增工具、不新增命令、不新增 Skill 条目**：
+
+- **F2 · 真实宿主端到端门禁（关闭 U11）**：`scripts/profile-smoke.mjs` 扩展为六步真实宿主场景链——创建 → 导出 → 冷重启 → 惰性回填 → 跨语言导入 → 卸载，另加完成标记「缺失 / `complete:false`」两条负向对照；四版本矩阵在扩展后的门禁下 4/4 通过。**仍未覆盖**：真实 LLM / agent loop 与 approval 策略、相对路径、`autoPersist`、真实进程中断，以及其余 6 个工具（仅断言注册）。
+- **F1 · 面试问题按下标逐条对齐（关闭 D10）**：精选面试问题由「整组 all-or-nothing」改为按下标逐条——长度与出厂数组相同时逐条替换，用户改过的那条保持原样；长度不同则整组原样保留。默认行为对**未编辑**场景零变化。
+- **F5 · render 整串上限加固（关闭 O10）**：整串（含省略号）不超过 1024 B，裁切预算由省略号自身的 UTF-8 长度推导（不再依赖手写余量）。
+- **F4 · 依赖对齐**：`@deepseek-ai/schemastery` 由 `^3.18.2` 改为 `~3.18.4`，与宿主系列一致；`peerDependencies` 与 `engines.dsh` 范围不变。
+- **已知边界 G1（有意不修，推迟 0.10.0）**：冷启动惰性回填会把决策理由措辞由初始文案换成 `decisionReasons.identity`（并补 `decisionReasonCode`），`decision` 不变；详见 [0.9.2 门禁发现](dsh-scout-0.9.2-gate-findings.md)（仓库文档，不在 npm 包内）。
 
 ## 1. 产品承诺
 
@@ -41,15 +60,24 @@ scout-cases/<case-id>/
   claims.json
   events.jsonl
   report.md
+  export.complete.json   # 0.9.1 起：完成标记（先置 complete:false，五文件落盘后改写 complete:true）
 ```
 
+0.9.1 起，五个数据文件之外还有一个完成标记 `export.complete.json`，内容形如 `{ schemaVersion, caseId, complete, files, eventCount }`。写入顺序是：**先**把标记写成 `complete: false`，五个数据文件全部落盘后**再**改写为 `complete: true`。因此**陈旧标记不会为半份导出宣称完整**——在覆盖写场景下，上一次成功导出的标记会在新文件写入前先被降级为 `complete: false`。
+
+标记里的 `eventCount` **只有在 `complete: true` 时才与磁盘上 `events.jsonl` 的行数一致**：导出中断时，它记录的是那次失败尝试**期望**的事件数，可能与实际行数不同。读取方请以 `complete` 为准，不要只看 `eventCount`。
+
+标记里的 `files` 只列**五个数据文件**；`scout_export` 返回值里的 `files` 是这次调用写出的**六个名字**（五个数据文件 + 标记自身）。同名不同义，两者都正确。
+
+`scout_import` 读的是标记里的 **`complete` 字段**，而不是「标记文件是否存在」：标记缺失或 `complete: false` 时，只要**五个数据文件都已落盘**，导入仍会进行，但返回值报告 `complete: false`，让调用方自己决定是否信任这份快照。也就是说：中断的导出只要五个数据文件都在，仍可导入，但会被如实标为不完整；五个数据文件缺任何一个（例如在写 `claims.json` 时中断的全新导出）仍是硬失败。
+
 首版不要求精确的总分。报告必须包含：
 
 - 一句话判断和判断状态
 - 3 个支持判断的关键证据
 - 3 个阻断或待核验风险
 - 岗位可能的真实任务与权限假设
-- 5-10 个面试反问
+- 面试反问清单：**上限 12 条**；案例自带的精选问题**永远保留名额**，其余名额按「待办下一步 → 缺失必需维度 → 未调查维度」的优先级填充
 - 下一步最小核验动作
 
 ## 4. 证据模型
@@ -72,11 +100,28 @@ scout-cases/<case-id>/
 首版作为外部 bundle，优先使用现有工具、子 Agent、任务和文件系统能力：
 
 - 工具：启动 case、核验 claim、比较公司、生成面试问题、导出报告。
-- 事件观察：记录工具结果和来源归档，不重写 Agent Loop。
-- 配置：来源目录、报告目录、并发数、超时和输出语言必须是可配置字段。
+- 事件观察：记录工具结果和来源归档，不重写 Agent Loop。插件自己的 `events.jsonl` 事件只存在于导出文件里，**不写进 session log**（理由见 §5.1）。
+- 配置：来源目录、报告目录和输出语言必须是可配置字段。`scoutDir` / `autoPersist` 已在 v0.3 落地，`language`（`'zh-CN' | 'en'`，默认 `'zh-CN'`）在 0.9.1 落地——`case.json` 里的 `language` 是**本部署的渲染语言**，不是文件内容的语言：对齐只按这个标签判定，不校验标签与内容是否自洽，手工改写的外来文件不做校正。**并发数与超时 0.9.1 明确不做**：DSH 工具默认串行（未声明 `isConcurrencySafe` 即 exclusive），插件这一层没有可并发的调度面；超时按需在 0.10.0 引入。契约里的字段要么实现、要么写明为什么不做，不留未解释的占位。
 - 生命周期：所有 watcher、后台任务、连接和临时文件都必须在卸载时清理。
 
-首版不新增模型可见的持久化事件；如果未来需要让 case 状态进入模型上下文，必须为其设计可回放的 session event。
+### 5.1 撤回「自造 session event」计划（红线）
+
+0.9.0 的路线图曾写：「如果未来需要让 case 状态进入模型上下文，必须为其设计可回放的 session event」。**该计划在 DSH 0.2.0-rc.2 上撤回**——这不是取舍，而是硬约束：
+
+- 类型层确实开放：`SessionEventMap` 可以 declaration-merge，官方文档也写明「A plugin may declaration-merge extra `SessionEventMap` types」。但**落盘读路径不认**：`validateStoredEvents()` 对任何不在 `KNOWN_SESSION_EVENT_TYPES`（构建期生成的 59 个名字）内、且 `ignorable !== true` 的事件类型直接抛错（*refusing to interpret the log*，`@deepseek-ai/dsh-session-persistence/lib/index.js:184`）。
+- 而 `Session.append()` 构造的信封只有 `{ type, seq, time, data, …surfaceMetadata }`，**没有任何路径能写入 `ignorable`**（`@deepseek-ai/dsh-session/lib/index.js:1441-1459`；`surfaceMetadata` 只带 `sourceEventSeqs` / `surfaceOp`）。唯一例外是创建期的 seed 事件（`assertSessionEventEnvelope` 的白名单包含 `ignorable`，`dsh-session/lib/types/index.js:141,154`），活会话里追加没有出路。
+- 后果：插件自造的事件会让**插件自己写的会话在重启 / 恢复时无法重建**。一个主打「证据可追溯」的插件不能拿用户的会话日志去赌这个。
+
+### 5.2 替代路线：只用宿主已知词表内的接缝
+
+| 需求 | 0.2.0-rc.2 里可用的接缝 | 落地版本 |
+| --- | --- | --- |
+| 用户显式动作（`/scout status` / `questions` / `report` / `export`） | `ctx.commands.register(def)`；宿主在处理前后自动落 `command/run` + `command/done`，两个名字都在 `KNOWN_SESSION_EVENT_TYPES` 内 | 0.9.1 |
+| 结构化 UI 载荷 | `output.presentationMeta(args, value)` → 持久化在 `tool/result.meta`（无损 JSON，随会话日志走） | 0.10.0（0.9.1 不引入：没有 client 消费者时它没有可见收益） |
+| 跨会话 / 跨重启保存台账 | `ctx.storageDomain`（`defineDomain` + `ctx.storageDomain.open()`，读同步、写持久、`domain/changed` 有序） | 0.10.0（会改变 owner 语义，需与「case 是否跨会话共享」一起决策） |
+| 把「尽调方法」交给模型 | `ctx.skills.register({ name, description, content, … })`——无需落文件、无需 client bundle，卸载即消失 | 0.9.1 |
+
+> 一句话规则：**不要自造 session event。** 用户显式动作走 `command/run` + `command/done`，结构化 UI 载荷走 `output.presentationMeta` → `tool/result.meta`，持久状态走 `ctx.storageDomain`。
 
 ## 6. 明确非目标
 
@@ -86,6 +131,7 @@ scout-cases/<case-id>/
 - 不把个人简历、身份信息或求职意图默认发送给第三方服务。
 - 不提供法律、投资或医疗结论。
 - 不在首版实现完整 Web UI、实时数据库或公司评分排行榜。
+- client 面板与 `ctx.storageDomain` 持久化重写排在 **0.10.0**（见 §5.2）：后者要引入 domain schema、生命周期与迁移策略，并改变现在的 owner 语义（按 `SessionId` 分桶）。在它们落地之前，跨会话持久化仍由五文件导出 / 导入承担。
 
 ## 7. 首个验收案例
 

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Scout",
+    "description": "Evidence-driven company and job due diligence for DeepSeek Harness: every claim is sourced, verifiable, and traceable."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "司察 Scout",
+    "description": "证据驱动的公司与岗位尽调插件：每条主张都有出处、可核验、可追溯。"
+  }
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-scout",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Evidence-driven company and job intelligence plugin for DeepSeek Harness.",
+  "icon": "./assets/icon.svg",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -12,11 +13,15 @@
       "default": "./dist/index.js"
     },
     "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/en.json": "./locale/en.json",
+    "./locale/zh.json": "./locale/zh.json",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "cordis.patch.yml",
+    "locale",
+    "assets",
     "scripts/check-release.mjs",
     "scripts/profile-smoke.mjs",
     "README.md",
@@ -24,7 +29,11 @@
     "docs/dsh-scout-product-contract.md",
     "docs/fixtures/dsh-scout/snapmaker-hr-head.json",
     "tests/model.test.mjs",
-    "README.en.md"
+    "tests/package.test.mjs",
+    "tests/tools.test.mjs",
+    "tests/acceptance.test.mjs",
+    "README.en.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -35,7 +44,8 @@
     "prepare": "npm run build"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.19.0",
+    "dsh": ">=0.1.0-rc.6 <0.3.0-0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.2 <5",
@@ -44,9 +54,6 @@
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
       "optional": true
-    },
-    "@deepseek-ai/dsh-tools": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -55,9 +62,10 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "~3.18.4"
   },
   "dsh": {
+    "manifestVersion": 1,
     "bundle": {
       "patch": "./cordis.patch.yml"
     }

package/scripts/check-release.mjs

@@ -1,12 +1,185 @@
+#!/usr/bin/env node
+/**
+ * dsh-scout release gate.
+ *
+ * Runs the unit tests, the real-invocation profile smoke against every DSH
+ * version in the verified matrix, and the packaging dry run.
+ *
+ * DSH 0.9.1 addition — declared-range classification. `engines.dsh` in
+ * package.json is the declared compatibility window; `DSH compatibility is
+ * declarative until a reader enforces it` (dsh-package-manifest), so this gate
+ * is where the declaration is actually checked. Each matrix failure is now
+ * classified:
+ *   - a failure INSIDE `engines.dsh` is a REGRESSION (the plugin used to work
+ *     and the code or the host changed);
+ *   - a failure OUTSIDE `engines.dsh` is reported with the `OUT OF DECLARED
+ *     RANGE` prefix: it is expected drift when DSH publishes a new major line
+ *     (for example `0.3.0-alpha.1` against `<0.3.0-0`), not a code regression.
+ * Set `DSH_ALLOW_OUT_OF_RANGE=1` to keep an out-of-range channel job green while
+ * still printing the distinct prefix.
+ *
+ * Environment:
+ *   DSH_VERSIONS            override the verified version matrix
+ *                           (comma- or whitespace-separated, e.g.
+ *                           `DSH_VERSIONS=0.2.0-rc.2 node scripts/check-release.mjs`)
+ *   DSH_ALLOW_OUT_OF_RANGE  `1` downgrades out-of-range failures to warnings
+ *
+ * SemVer semantics (do NOT "fix" this matcher): this script has no runtime
+ * dependency, so it carries a small comparator-set matcher that mirrors
+ * node-semver's `{ includePrerelease: true }` mode — the exact mode DSH uses to
+ * evaluate plugin compatibility (`semver.satisfies(runtimeVersion, requirement,
+ * { includePrerelease: true })`, `@deepseek-ai/dsh-app-boot/lib/index.js:300`).
+ * In plain node-semver mode a prerelease version only satisfies a comparator set
+ * when some comparator shares its [major, minor, patch] tuple, which would
+ * reject the entire verified 0.2 prerelease line. Measured with semver 7.8.5
+ * against `engines.dsh = ">=0.1.0-rc.6 <0.3.0-0"`:
+ *
+ *   version        plain   includePrerelease
+ *   0.1.0-rc.6     true    true
+ *   0.1.2-rc.1     false   true
+ *   0.2.0-rc.2     false   true
+ *   0.2.1-alpha.2  false   true
+ *   0.2.9          true    true
+ *   0.3.0-alpha.1  false   false
+ *   0.3.0          false   false
+ *
+ * This matcher was differentially tested against semver 7.8.5 with
+ * `{ includePrerelease: true }` and agrees on every case above plus
+ * 0.1.0-rc.5 / 0.1.0 / 0.1.1 / 0.2.0-alpha.0 / 0.3.0-0 / 0.2.1 / 1.0.0 / 0.0.9.
+ * Unsupported range syntax (for example `1.x`, `*`, `latest`) is reported as
+ * UNKNOWN instead of being guessed.
+ * Note: `engines.dsh` itself is declarative in DSH 0.2.0-rc.2 (`dsh-package-manifest`:
+ * "DSH compatibility is declarative until a reader enforces it"); the range DSH
+ * actually enforces is the `peerDependencies` one at the call site above, so this
+ * gate is where the `engines.dsh` declaration is really checked.
+ */
 import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
 
-const command = name => process.platform === 'win32' ? `${name}.cmd` : name
-const verifiedDshVersions = [
+const DEFAULT_VERIFIED_DSH_VERSIONS = [
   '0.1.0-rc.6',
   '0.1.2-rc.1',
   '0.2.0-rc.2',
   '0.2.1-alpha.2',
 ]
+const ALLOW_OUT_OF_RANGE = process.env.DSH_ALLOW_OUT_OF_RANGE === '1'
+const command = name => process.platform === 'win32' ? `${name}.cmd` : name
+
+const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const declaredRange = typeof packageJson.engines?.dsh === 'string' ? packageJson.engines.dsh.trim() : ''
+
+function resolveVersions() {
+  const override = (process.env.DSH_VERSIONS ?? '').trim()
+  if (!override) return { versions: DEFAULT_VERIFIED_DSH_VERSIONS, source: 'default matrix' }
+  const versions = override.split(/[,\s]+/).filter(Boolean)
+  if (versions.length === 0) throw new Error(`DSH_VERSIONS is set but names no version: ${JSON.stringify(process.env.DSH_VERSIONS)}`)
+  return { versions, source: 'DSH_VERSIONS override' }
+}
+
+// --- minimal SemVer comparator support (see the module doc for the deviation) --
+
+const VERSION_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+function parseVersion(text) {
+  const match = VERSION_PATTERN.exec(String(text).trim())
+  if (match === null) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] === undefined ? [] : match[4].split('.'),
+  }
+}
+
+function compareIdentifiers(a, b) {
+  const numeric = /^\d+$/
+  const aNumeric = numeric.test(a)
+  const bNumeric = numeric.test(b)
+  if (aNumeric && bNumeric) return Number(a) === Number(b) ? 0 : Number(a) < Number(b) ? -1 : 1
+  if (aNumeric) return -1
+  if (bNumeric) return 1
+  return a === b ? 0 : a < b ? -1 : 1
+}
+
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0
+  if (a.length === 0) return 1
+  if (b.length === 0) return -1
+  const length = Math.max(a.length, b.length)
+  for (let index = 0; index < length; index += 1) {
+    if (a[index] === undefined) return -1
+    if (b[index] === undefined) return 1
+    const order = compareIdentifiers(a[index], b[index])
+    if (order !== 0) return order
+  }
+  return 0
+}
+
+function compareVersions(a, b) {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1
+  return comparePrerelease(a.prerelease, b.prerelease)
+}
+
+function parseRange(text) {
+  const orSets = String(text).trim().split('||').map(part => part.trim()).filter(Boolean)
+  if (orSets.length === 0) return { sets: null, unsupported: String(text) }
+  const sets = []
+  for (const part of orSets) {
+    const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(part)
+    const tokens = hyphen === null ? part.split(/\s+/).filter(Boolean) : [`>=${hyphen[1]}`, `<=${hyphen[2]}`]
+    const comparators = []
+    for (const token of tokens) {
+      const match = /^(>=|<=|>|<|=|\^|~)?(.*)$/.exec(token)
+      const operator = match[1] === undefined ? '=' : match[1]
+      const version = parseVersion(match[2])
+      if (version === null) return { sets: null, unsupported: token }
+      if (operator === '^' || operator === '~') {
+        comparators.push({ operator: '>=', version })
+        comparators.push({
+          operator: '<',
+          version: operator === '^'
+            ? { major: version.major + 1, minor: 0, patch: 0, prerelease: ['0'] }
+            : { major: version.major, minor: version.minor + 1, patch: 0, prerelease: ['0'] },
+        })
+      } else {
+        comparators.push({ operator, version })
+      }
+    }
+    sets.push(comparators)
+  }
+  return { sets, unsupported: null }
+}
+
+function satisfiesSet(version, comparators) {
+  return comparators.every(comparator => {
+    const order = compareVersions(version, comparator.version)
+    switch (comparator.operator) {
+      case '>=': return order >= 0
+      case '>': return order > 0
+      case '<=': return order <= 0
+      case '<': return order < 0
+      case '=': return order === 0
+      default: return false
+    }
+  })
+}
+
+/** Classify one DSH version against `engines.dsh`. */
+function classifyVersion(version) {
+  if (declaredRange === '') return { status: 'unknown', reason: 'package.json declares no engines.dsh' }
+  const parsedVersion = parseVersion(version)
+  if (parsedVersion === null) return { status: 'unknown', reason: `not a SemVer version: ${version}` }
+  const range = parseRange(declaredRange)
+  if (range.sets === null) return { status: 'unknown', reason: `unsupported engines.dsh syntax near "${range.unsupported}"` }
+  const satisfied = range.sets.some(set => satisfiesSet(parsedVersion, set))
+  return satisfied
+    ? { status: 'in-range', reason: `satisfies engines.dsh "${declaredRange}"` }
+    : { status: 'out-of-range', reason: `outside engines.dsh "${declaredRange}"` }
+}
+
+// --- gate ---------------------------------------------------------------------
 
 function run(program, args, env = process.env) {
   const result = spawnSync(command(program), args, { env, stdio: 'inherit' })
@@ -16,8 +189,50 @@ function run(program, args, env = process.env) {
   }
 }
 
+const { versions, source } = resolveVersions()
+console.log('dsh-scout release gate')
+console.log(`  declared engines.dsh: ${declaredRange === '' ? '(none declared — failures cannot be classified)' : declaredRange}`)
+console.log('  range semantics: node-semver includePrerelease:true (mirrors dsh-app-boot evaluatePluginCompatibility:300)')
+console.log(`  profile matrix: ${versions.join(', ')} (${source})`)
+console.log(`  out-of-range failures: ${ALLOW_OUT_OF_RANGE ? 'warn only (DSH_ALLOW_OUT_OF_RANGE=1)' : 'fatal, reported as OUT OF DECLARED RANGE'}`)
+
 run('npm', ['test'])
-for (const version of verifiedDshVersions) {
-  run('npm', ['run', 'test:profile'], { ...process.env, DSH_VERSION: version })
+
+const regressions = []
+const outOfRangeFailures = []
+const unknownRangeFailures = []
+for (const version of versions) {
+  const classification = classifyVersion(version)
+  try {
+    run('npm', ['run', 'test:profile'], { ...process.env, DSH_VERSION: version })
+    console.log(`[ok] dsh ${version} — profile smoke passed (${classification.reason})`)
+  } catch (error) {
+    if (classification.status === 'out-of-range') {
+      console.error(`[expected drift] OUT OF DECLARED RANGE dsh ${version} — profile smoke failed ${classification.reason}`)
+      outOfRangeFailures.push({ version, reason: classification.reason })
+    } else if (classification.status === 'unknown') {
+      console.error(`[regression] dsh ${version} — profile smoke failed and the version cannot be classified (${classification.reason})`)
+      unknownRangeFailures.push({ version, reason: classification.reason })
+    } else {
+      console.error(`[regression] dsh ${version} — profile smoke failed inside the declared range`)
+      regressions.push({ version, reason: classification.reason })
+    }
+  }
 }
+
 run('pnpm', ['pack', '--dry-run'])
+
+const fatal = regressions.length > 0 || unknownRangeFailures.length > 0 || (outOfRangeFailures.length > 0 && !ALLOW_OUT_OF_RANGE)
+if (regressions.length > 0 || outOfRangeFailures.length > 0 || unknownRangeFailures.length > 0) {
+  console.error('')
+  console.error(`dsh-scout release gate: ${fatal ? 'FAIL' : 'PASS (with expected out-of-range drift)'}`)
+  for (const failure of regressions) console.error(`  REGRESSION (declared range): dsh ${failure.version} — ${failure.reason}`)
+  for (const failure of unknownRangeFailures) console.error(`  RANGE UNKNOWN (cannot classify): dsh ${failure.version} — ${failure.reason}`)
+  for (const failure of outOfRangeFailures) {
+    const kind = ALLOW_OUT_OF_RANGE ? 'OUT OF DECLARED RANGE (warn only)' : 'OUT OF DECLARED RANGE'
+    console.error(`  ${kind}: dsh ${failure.version} — ${failure.reason}; widen engines.dsh only after verifying the new line`)
+  }
+  if (regressions.length > 0 || unknownRangeFailures.length > 0 || !ALLOW_OUT_OF_RANGE) process.exitCode = 1
+} else {
+  console.log(`dsh-scout release gate: PASS (${versions.length} DSH versions, ${declaredRange || 'no declared range'})`)
+}