@bruc3van/dsh-doctor 0.5.3 → 0.5.5

package/README.en.md

@@ -29,14 +29,17 @@ Upgrade this plugin from DSH 0.1.1 to DSH 0.1.2.
 Analyze compatibility first, modify the code, then complete build and runtime verification.
 ```
 
+An upgrade request does not itself authorize dropping the old runtime. If the developer has not said, the skill explicitly asks whether the same upgraded plugin release must still support DSH 0.1.1 before any migration write, dependency installation, build, or runtime command. When compatibility must be preserved, the agent designs a dual-version approach first and verifies 0.1.1 and 0.1.2 separately; one successful 0.1.2 run is not dual-version evidence.
+
 The skill reminds the agent to work in this order:
 
 1. inspect the plugin root, Harness checkout, package manager, and available DSH Doctor;
 2. analyze source, type imports, dependencies, manifest, client graph, patches, and build output;
-3. preview and apply code changes that are known to be equivalent;
-4. use the new API owners to handle semantic changes that require understanding the plugin;
-5. rebuild the plugin and run static, build, and isolated runtime verification;
-6. report the changed files, remaining work, backups, and the verification level actually reached.
+3. confirm whether the upgraded release targets only 0.1.2 or must remain compatible with 0.1.1;
+4. preview and apply code changes that are known to be equivalent under the selected compatibility strategy;
+5. use the new API owners to handle semantic changes that require understanding the plugin;
+6. rebuild the plugin and run static, build, and isolated runtime verification, covering both versions in dual-version mode;
+7. report the compatibility intent, changed files, remaining work, backups, and the verification level actually reached.
 
 `npx skills add` installs agent instructions only. It does not install DSH Doctor globally. The skill checks the local CLI and npm registry first. If the local version is unsuitable, it uses a pinned `npx` version by default and does not change the global npm installation.
 
@@ -96,11 +99,11 @@ Source analysis uses the TypeScript AST and is cross-checked against the manifes
 ## Safety
 
 - `diagnose`, `migrate analyze`, and static verification are read-only and do not load or execute the inspected plugin;
-- `migrate apply` requires `--safe`; without `--yes`, it only previews changes;
+- `migrate apply` requires `--safe --plan-file`; preview only creates a new plan outside the plugin root, never overwrites an existing file, and persists the complete analysis plus every input-file hash; `--yes` applies only that same reviewed plan;
 - only `exact` migrations are auto-edited; semantic changes are not guessed;
 - SHA-256 is checked before writing, so a file changed after preview is rejected;
 - existing files receive timestamped backups and are replaced atomically through a temporary file;
-- build and runtime verification execute plugin scripts and therefore require explicit `--yes`;
+- build and runtime verification synchronize dependencies and execute plugin scripts, so they require explicit `--yes --install`; install lifecycle scripts are disabled and lockfile plus resolved-version evidence is recorded;
 - runtime verification uses a temporary `DSH_HOME`, not the normal `~/.dsh`;
 - JSON, baselines, and recovery snapshots redact plugin configuration and common secret/token/password/key fields;
 - global CLI installation, persistent quarantine, plugin removal, and publishing are never performed automatically by the skill.
@@ -112,7 +115,7 @@ Node.js `^22.19.0` or `>=24.0.0` is required.
 First confirm that the CLI contains the required migration:
 
 ```sh
-npx --yes --package=@bruc3van/dsh-doctor@0.5.3 \
+npx --yes --package=@bruc3van/dsh-doctor@0.5.5 \
   dsh-doctor migrations list
 ```
 
@@ -133,31 +136,33 @@ Analysis checks source, dependencies, manifest, client graph, patch targets, and
 ```sh
 # Preview
 dsh-doctor migrate apply /path/to/plugin --safe \
+  --plan-file /temporary/path/reviewed-migration-plan.json \
   --harness-root /path/to/deepseek-harness --json
 
 # Write after confirmation
 dsh-doctor migrate apply /path/to/plugin --safe --yes \
+  --plan-file /temporary/path/reviewed-migration-plan.json \
   --harness-root /path/to/deepseek-harness --json
 ```
 
-Apply can split mixed imports, move exact symbols, leave semantic symbols in place, and update development dependencies when the change is known. Every changed file receives a backup.
+The plan must stay outside the plugin root so it is not analyzed as plugin input. Apply checks the plan digest, every analyzed input, and each edit's before/after hashes; source, manifest, or other analyzed-input changes require a new reviewed plan. Deterministic dependency edits use catalog-owned Client/Host and peer/dev policies instead of inheriting the removed package's dependency section. Every changed file receives a backup.
 
 ### 3. Verify
 
 ```sh
 dsh-doctor migrate verify /path/to/plugin --level static \
   --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level build --yes \
+dsh-doctor migrate verify /path/to/plugin --level build --yes --install \
   --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
+dsh-doctor migrate verify /path/to/plugin --level runtime --yes --install \
   --harness-root /path/to/deepseek-harness --json
 ```
 
 | Level | What it checks |
 |---|---|
 | `static` | Rechecks source, manifest, client graph, patches, and artifacts |
-| `build` | Runs the plugin's existing build/test scripts and scans the output again |
-| `runtime` | Packs the real tarball and checks the target DSH version, installed package, bundle, and effective configuration in a temporary profile |
+| `build` | Synchronizes and verifies target dependencies and the lockfile, then runs build/test scripts and scans output again |
+| `runtime` | After dependency and build gates, packs the real tarball and checks target DSH, installed package, bundle, and effective configuration in a temporary profile |
 
 Verification states are:
 

package/README.md

@@ -29,14 +29,17 @@ npx skills add bruc3van/dsh-doctor
 先分析兼容问题，再修改代码，最后完成构建和运行时验证。
 ```
 
+升级请求本身不代表可以放弃旧版。若开发者没有说明，Skill 会在任何迁移写入、依赖安装、构建或运行时命令前，显式询问升级后的同一插件版本是否还要兼容 DSH 0.1.1。选择保留兼容时，Agent 会先设计双版本适配方式，并分别验证 0.1.1 和 0.1.2；不能用一次 0.1.2 验证代替双版本结论。
+
 Skill 会提醒 Agent 按下面的顺序工作：
 
 1. 检查插件目录、Harness checkout、包管理器和可用的 DSH Doctor；
 2. 分析源码、类型导入、依赖、manifest、client graph、patch 和构建产物；
-3. 预览并应用可以确定等价的代码修改；
-4. 根据新的 API 所有者处理需要理解业务的语义迁移；
-5. 重新构建插件，并依次做静态、构建和隔离运行时验证；
-6. 报告修改内容、剩余问题、备份和实际达到的验证等级。
+3. 确认升级后是仅支持 0.1.2，还是同一版本继续兼容 0.1.1；
+4. 预览并应用可以确定等价、且符合所选兼容策略的代码修改；
+5. 根据新的 API 所有者处理需要理解业务的语义迁移；
+6. 重新构建插件，并依次做静态、构建和隔离运行时验证；双版本模式分别验证两端；
+7. 报告兼容目标、修改内容、剩余问题、备份和实际达到的验证等级。
 
 `npx skills add` 只安装 Agent 指令，不会安装全局 DSH Doctor。Skill 会先检查本地 CLI 和 npm registry；本地版本不合适时，默认使用固定版本的 `npx`，不会自行修改全局 npm 安装。
 
@@ -96,11 +99,11 @@ Migration catalog 保存 source/target tag 和 Git commit，并记录 package、
 ## 安全性
 
 - `diagnose`、`migrate analyze` 和静态验证只读，不加载或执行待检查插件；
-- `migrate apply` 必须带 `--safe`，没有 `--yes` 时只展示将要修改的内容；
+- `migrate apply` 必须带 `--safe --plan-file`；预览只会新建插件目录外的 plan，不会覆盖已有文件，并把完整分析和所有输入文件哈希固化下来；`--yes` 只应用同一个已审阅 plan；
 - 只有 `exact` 迁移会自动改代码，语义变化不会自动猜测；
 - 写入前检查文件 SHA-256，预览后文件发生变化会拒绝写入；
 - 修改已有文件前创建时间戳备份，并使用临时文件原子替换；
-- build 和 runtime 会执行插件脚本，因此必须显式使用 `--yes`；
+- build 和 runtime 会同步依赖并执行插件脚本，因此必须显式使用 `--yes --install`；依赖安装禁用 lifecycle scripts，并记录 lockfile 和实际解析版本证据；
 - runtime 使用临时 `DSH_HOME`，不会安装到正常的 `~/.dsh`；
 - JSON、baseline 和恢复快照会脱敏插件配置和常见 secret/token/password/key 字段；
 - 全局 CLI 安装、持久隔离、删除插件和发布都不会由 Skill 自动执行。
@@ -112,7 +115,7 @@ Migration catalog 保存 source/target tag 和 Git commit，并记录 package、
 先确认 CLI 包含需要的迁移：
 
 ```sh
-npx --yes --package=@bruc3van/dsh-doctor@0.5.3 \
+npx --yes --package=@bruc3van/dsh-doctor@0.5.5 \
   dsh-doctor migrations list
 ```
 
@@ -133,31 +136,33 @@ dsh-doctor migrate analyze /path/to/plugin \
 ```sh
 # 预览
 dsh-doctor migrate apply /path/to/plugin --safe \
+  --plan-file /temporary/path/reviewed-migration-plan.json \
   --harness-root /path/to/deepseek-harness --json
 
 # 确认后写入
 dsh-doctor migrate apply /path/to/plugin --safe --yes \
+  --plan-file /temporary/path/reviewed-migration-plan.json \
   --harness-root /path/to/deepseek-harness --json
 ```
 
-Apply 可以拆分混合 import、移动精确 symbol、保留语义 symbol，并更新确定可以调整的开发依赖。每个被修改的文件都会保留备份。
+Plan 必须放在插件目录外，避免被当成插件输入。Apply 会核对 plan digest、完整分析输入和每个修改的 before/after hash；源码、manifest 或其他分析输入在预览后变化时必须重新生成并审阅 plan。确定性依赖改写使用 catalog 明确的 Client/Host 与 peer/dev 策略，不再沿用旧包所在的 dependency section。每个被修改的文件都会保留备份。
 
 ### 3. 验证
 
 ```sh
 dsh-doctor migrate verify /path/to/plugin --level static \
   --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level build --yes \
+dsh-doctor migrate verify /path/to/plugin --level build --yes --install \
   --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
+dsh-doctor migrate verify /path/to/plugin --level runtime --yes --install \
   --harness-root /path/to/deepseek-harness --json
 ```
 
 | 级别 | 验证内容 |
 |---|---|
 | `static` | 再次检查源码、manifest、client graph、patch 和产物 |
-| `build` | 运行插件已有的构建与测试脚本，并在构建后重新扫描产物 |
-| `runtime` | 打真实 tarball，在临时 profile 中验证目标 DSH 版本、安装包、bundle 和生效配置 |
+| `build` | 先同步并核验目标依赖和 lockfile，再运行已有构建/测试脚本并重新扫描产物 |
+| `runtime` | 完成依赖与构建门后，打真实 tarball，在临时 profile 中验证目标 DSH、安装包、bundle 和生效配置 |
 
 验证状态依次是：
 

package/migrations/dsh-v0.1.1-rc.2__dsh-v0.1.2-alpha.2/packages.json

@@ -42,6 +42,17 @@
     "@deepseek-ai/dsh-client-store": "0.1.2-alpha.2",
     "@deepseek-ai/dsh-session": "0.1.2-alpha.2"
   },
+  "dependencyPolicies": {
+    "@deepseek-ai/cordis": {
+      "client": ["peerDependencies", "devDependencies"]
+    },
+    "@deepseek-ai/dsh-client-store": {
+      "client": ["devDependencies"]
+    },
+    "@deepseek-ai/dsh-session": {
+      "client": ["devDependencies"]
+    }
+  },
   "semanticReplacements": {
     "@deepseek-ai/dsh-client-runtime": [
       "@deepseek-ai/dsh-api-session-controller",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Help agents diagnose and upgrade DeepSeek Harness plugins from DSH 0.1.1 to 0.1.2",
   "license": "MIT",
   "type": "module",

package/skills/dsh-plugin-upgrade/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dsh-plugin-upgrade
-description: Help diagnose and upgrade a DeepSeek Harness plugin from DSH 0.1.1 to 0.1.2 with dsh-doctor. Use when a plugin developer asks to assess compatibility, identify changed APIs, replace removed dsh-client-runtime or dsh-host-apiproxy usage, update DSH dependencies, modify plugin code, rebuild artifacts, or verify the plugin before releasing a new version. Apply only catalog-confirmed exact rewrites automatically, guide semantic code changes, and report what still needs developer verification. The current catalog uses dsh-v0.1.1-rc.2 and dsh-v0.1.2-alpha.2 as its reference points.
+description: Help diagnose and upgrade a DeepSeek Harness plugin from DSH 0.1.1 to 0.1.2 with dsh-doctor, while deciding explicitly whether the upgraded release must remain compatible with DSH 0.1.1. Use when a plugin developer asks to assess compatibility, identify changed APIs, replace removed dsh-client-runtime or dsh-host-apiproxy usage, update DSH dependencies, modify plugin code, rebuild artifacts, or verify the plugin before releasing a new version. Apply only catalog-confirmed exact rewrites automatically, guide semantic code changes, and report what still needs developer verification. The current catalog uses dsh-v0.1.1-rc.2 and dsh-v0.1.2-alpha.2 as its reference points.
 ---
 
 # Upgrade a DSH 0.1.1 plugin to 0.1.2
@@ -16,6 +16,7 @@ Determine:
 - the plugin repository root;
 - the DSH Harness checkout when available;
 - the plugin's actual DSH dependency and peer ranges, and the requested 0.1.2 target;
+- whether the upgraded plugin must keep supporting DSH 0.1.1, target only DSH 0.1.2, or still needs that decision from the developer;
 - whether the developer authorizes writes and project command execution;
 - whether the developer authorizes a global CLI install or update;
 - the plugin's package manager and build scripts.
@@ -25,12 +26,26 @@ Use these catalog reference points in the current CLI commands:
 - source: `dsh-v0.1.1-rc.2`
 - target: `dsh-v0.1.2-alpha.2`
 
-Read [cli-bootstrap.md](references/cli-bootstrap.md) before running any migration command, [migration-map.md](references/migration-map.md) before making semantic changes, and [verification.md](references/verification.md) before build or runtime verification.
+Read [cli-bootstrap.md](references/cli-bootstrap.md) before running any migration command, [compatibility-strategy.md](references/compatibility-strategy.md) before proposing or writing changes, [source-investigation.md](references/source-investigation.md) before investigating an unlisted version or semantic task, [migration-map.md](references/migration-map.md) before making semantic changes, and [verification.md](references/verification.md) before dependency, build, or runtime verification.
 
 Before touching the plugin, inspect the local CLI and perform the read-only registry update check described in `cli-bootstrap.md`. Select one exact DSH Doctor version, verify it exposes this migration catalog, and keep the same invocation for analyze, apply, and verify. Prefer an exact-version `npx` fallback over changing the developer's global installation. Never globally install or update the CLI without explicit authorization.
 
 The examples below use `dsh-doctor` for readability. When bootstrap selected an npx invocation, substitute the complete pinned prefix, `npx --yes --package=@bruc3van/dsh-doctor@<selected-version> dsh-doctor`, in every phase.
 
+## Compatibility decision gate
+
+An upgrade request does not say whether the developer accepts dropping DSH 0.1.1. Write authorization also does not answer that product decision. Do not infer the answer from the current peer range, the word "upgrade," or the fact that a 0.1.2-only rewrite is simpler.
+
+You may inspect files, bootstrap the CLI, and run read-only analysis to collect evidence. Before any `migrate apply` preview, source or manifest edit, dependency install, build, or runtime command:
+
+1. record an explicit choice already present in the developer's request; or
+2. ask: **"Should the same upgraded plugin release continue to support DSH 0.1.1, or may it target DSH 0.1.2 only?"**
+
+If the answer is unavailable or ambiguous, stop at `analyzed`, identify the compatibility decision as pending, and do not modify the plugin. Follow the selected path in [compatibility-strategy.md](references/compatibility-strategy.md):
+
+- **0.1.2-only:** the catalog's exact rewrites may be applied after their normal preview and write confirmation.
+- **dual-version:** treat every 0.1.2 rewrite as a candidate, not an automatically compatible change. Design and review an adapter or conditional entry/build approach before writing. If the same release cannot honestly support both versions, explain the conflict and ask whether separate releases are acceptable; that changes the compatibility intent and must not be presented as same-release dual compatibility.
+
 ## Phase 1: analyze
 
 Run from any directory:
@@ -44,6 +59,8 @@ dsh-doctor migrate analyze <plugin-root> \
 
 Append `--harness-root <deepseek-harness-root>` when the checkout is available. Prefer an exact Harness checkout so the CLI verifies both tag commits. Both tags must exist and resolve to the commits recorded by the catalog; fetch the repository tags first when a shallow checkout lacks them. Without `--harness-root`, analysis is catalog-only and must be reported as such.
 
+Follow `source-investigation.md` to record the actual PATH or explicit DSH command, installed package, profile, plugin manifest and resolved dependency versions. When the actual source or target differs from the catalog refs, inspect that additional ref interval separately with read-only Git commands. For each semantic finding, use its target module and the catalog reference paths to inspect the exact exported API and plugin callers; do not stop at naming a likely new owner.
+
 Group the result by:
 
 1. errors blocking compatibility;
@@ -56,19 +73,25 @@ Do not infer compatibility from a clean bundled artifact alone. The analyzer int
 
 ## Phase 2: apply exact changes
 
+Enter this phase only after the compatibility decision gate is resolved. The commands below are the 0.1.2-target migration path. For dual-version work, first apply the additional constraints in `compatibility-strategy.md`; do not assume a catalog-safe codemod is safe for 0.1.1.
+
 Preview first:
 
 ```sh
-dsh-doctor migrate apply <plugin-root> --safe --harness-root <deepseek-harness-root> --json
+dsh-doctor migrate apply <plugin-root> --safe \
+  --plan-file <reviewed-plan-outside-plugin-root.json> \
+  --harness-root <deepseek-harness-root> --json
 ```
 
-Review affected files and hashes. Apply only with explicit authorization:
+Store the plan outside the plugin root so it is not treated as plugin input. Review the plan id, complete analysis, affected files, and before/after hashes. Apply that exact plan only with explicit authorization:
 
 ```sh
-dsh-doctor migrate apply <plugin-root> --safe --yes --harness-root <deepseek-harness-root> --json
+dsh-doctor migrate apply <plugin-root> --safe --yes \
+  --plan-file <same-reviewed-plan.json> \
+  --harness-root <deepseek-harness-root> --json
 ```
 
-The CLI creates timestamped backups and refuses writes when a file changed after preview. It may split a mixed import: exact symbols move to their new owners while semantic symbols remain unresolved. It may pin non-removed DSH development dependencies and add dependencies required by exact symbol moves. It does not change the ranges of existing published peers automatically. Never mechanically replace the removed Client Runtime with one aggregate package; no such replacement exists.
+The CLI binds the apply to the persisted report and edit hashes, creates timestamped backups, and refuses writes when the plugin analysis changed after preview. It may split a mixed import: exact symbols move to their new owners while semantic symbols remain unresolved. Dependency additions follow catalog-owned Client/Host and peer/dev policies instead of copying the removed package's old dependency section. It may pin non-removed DSH development dependencies. It does not widen the ranges of existing published peers automatically. Never mechanically replace the removed Client Runtime with one aggregate package; no such replacement exists.
 
 After apply, inspect every `MIG_SEMANTIC_API_CHANGE`. Rewrite behavior using the new domain owner and its current snapshot/lifecycle contract. Keep these edits separate enough to review and test.
 
@@ -78,11 +101,11 @@ Run the gates in order:
 
 ```sh
 dsh-doctor migrate verify <plugin-root> --level static --harness-root <deepseek-harness-root> --json
-dsh-doctor migrate verify <plugin-root> --level build --yes --harness-root <deepseek-harness-root> --json
-dsh-doctor migrate verify <plugin-root> --level runtime --yes --harness-root <deepseek-harness-root> --json
+dsh-doctor migrate verify <plugin-root> --level build --yes --install --harness-root <deepseek-harness-root> --json
+dsh-doctor migrate verify <plugin-root> --level runtime --yes --install --harness-root <deepseek-harness-root> --json
 ```
 
-Build and runtime levels execute plugin scripts and therefore require `--yes`. Runtime verification packs the real plugin, creates a temporary `DSH_HOME`, installs into a new web profile, dumps effective config, and performs an activation smoke. It does not modify the developer's normal `~/.dsh`.
+Build and runtime levels require `--yes --install`: the CLI first runs the detected package manager with lifecycle scripts disabled, updates the lockfile when needed, and verifies the installed DSH/Cordis versions against runtime, development, peer, and optional dependency declarations before executing project scripts. A required peer must resolve and satisfy every declared range; a missing optional peer is recorded but does not fail the gate. Review lockfile changes as migration changes. Runtime verification then packs the real plugin, creates a temporary `DSH_HOME`, installs into a new web profile, dumps effective config, and performs an activation smoke. It does not modify the developer's normal `~/.dsh`.
 
 Resolve every semantic task and rebuild stale artifacts before expecting static verification to pass. An `apply` exit code of 1 after successful writes means migration blockers remain in the follow-up analysis; inspect `mode`, `writes`, and `report` instead of treating it as a write failure.
 
@@ -90,6 +113,8 @@ On failure, preserve and report the temporary directory. On success, the CLI rem
 
 Runtime activation is not business-behavior proof. Finish with targeted manual or automated checks for visible UI, service lifecycle, event subscriptions, cleanup, configuration, and plugin-specific workflows.
 
+For a dual-version result, verify the produced release against both the actual 0.1.1 and 0.1.2 environments. The catalog-driven `migrate verify` commands prove only the configured target side. Use the plugin's own build/test flow and an isolated 0.1.1 Harness profile for the legacy side, and name the evidence from each matrix row. A successful 0.1.2 runtime smoke must never be reported as dual-version compatibility.
+
 ## Prepare for release when requested
 
 Verification prepares the plugin for release but does not publish it. If the developer explicitly asks to release the upgraded plugin, first follow the repository's own release instructions and confirm that required semantic and behavior checks are complete. Then update the plugin version and changelog, inspect the packed artifact, and use the repository's existing commit, tag, publish, and registry-verification workflow. Do not commit, tag, or publish merely because the migration skill was installed or run.
@@ -107,3 +132,5 @@ State the highest achieved gate exactly:
 Do not call the plugin compatible while errors, semantic tasks, stale artifacts, or required behavior checks remain. Include backups and retained temporary directories in the handoff.
 Also report the selected DSH Doctor version and source (`local`, exact-version `npx`, or explicitly authorized global install), the registry version observed at bootstrap, and whether update status was current, outdated, missing, or unknown.
 Report the plugin's actual source/target version evidence separately from the catalog reference refs. State whether the plugin is ready for its normal release process; if a release was explicitly requested and completed, include the commit, tag, registry, and release verification evidence.
+Report the migration plan file and plan id, dependency-install command, lockfile change, and resolved target dependency versions. For semantic or unlisted-version work, include the DSH executable/package evidence, checkout refs and commits, inspected source paths, and remaining unknowns described in `source-investigation.md`.
+State the compatibility intent as one of `0.1.2-only`, `dual-version`, or `pending developer decision`. For `dual-version`, report build, artifact, runtime, and behavior evidence separately for 0.1.1 and 0.1.2; only call the release dual-compatible when every required row passes.

package/skills/dsh-plugin-upgrade/references/compatibility-strategy.md

@@ -0,0 +1,51 @@
+# Compatibility strategy
+
+## Decide before changing the plugin
+
+Moving a plugin to 0.1.2 and preserving 0.1.1 are different deliverables. The 0.1.2 catalog describes target migrations; it does not prove that the resulting source, dependency graph, artifact, or manifest still works on 0.1.1.
+
+Record one explicit intent:
+
+| Intent | Meaning | Write policy |
+| --- | --- | --- |
+| `0.1.2-only` | The next plugin release may drop 0.1.1 | Follow the catalog migration after preview and authorization |
+| `dual-version` | The same release must support both 0.1.1 and 0.1.2 | Design the compatibility mechanism and two-version verification matrix before editing |
+| `pending developer decision` | The developer has not chosen | Read-only analysis only; stop before apply, edits, installs, build, or runtime execution |
+
+Do not treat general write authorization as permission to drop an older runtime. If the request does not settle the choice, ask the developer directly.
+
+## Assess whether one release can support both
+
+For `dual-version`, inventory each migration finding and determine whether the old and new owners coexist:
+
+- static imports of packages that exist in only one DSH version;
+- changed Service names, snapshot shapes, lifecycle, or event behavior;
+- client graph `inject`, `external`, platform modules, and client exports;
+- peer, optional peer, development, and bundled dependency ranges;
+- patch targets and profile entries that differ between Harness versions;
+- generated output that may capture version-specific imports.
+
+Choose a repository-appropriate same-release mechanism based on evidence, such as a shared compatibility adapter with runtime feature detection or conditional version-specific entry points/builds inside the same package. Do not invent dynamic loading when the bundler or Harness activation model cannot support it. Do not publish a peer range that claims both versions until installation and runtime evidence supports that range.
+
+The safe codemod is intentionally target-oriented. In dual-version mode, preview its changes only after the decision is recorded and review each proposed import and dependency edit against 0.1.1 before applying it. Semantic migrations always require the same cross-version review.
+
+If the same release cannot load because required packages or static graph declarations are mutually exclusive, report the exact conflict. Ask the developer whether to change scope to separate plugin releases or accept a 0.1.2-only release. Neither alternative satisfies the original same-release `dual-version` intent.
+
+## Verify a two-version matrix
+
+Use exact Harness versions or checkouts and keep evidence separate:
+
+| Gate | DSH 0.1.1 | DSH 0.1.2 |
+| --- | --- | --- |
+| dependency installation and peer resolution | required | required |
+| typecheck/build/test and packed artifact inspection | required | required |
+| isolated profile install and activation smoke | required | required |
+| plugin-specific UI, Service lifecycle, commands, settings, and cleanup | required where applicable | required where applicable |
+
+The current migration catalog and `migrate verify` target 0.1.2. They do not independently certify the legacy row. Verify 0.1.1 with the plugin repository's supported scripts and an isolated profile using the actual 0.1.1 Harness CLI. Preserve failure workspaces and report the exact commands, versions, artifacts, logs, or screenshots for each row.
+
+Use precise conclusions:
+
+- `0.1.2 runtime-verified; 0.1.1 not tested` is not dual-compatible.
+- Passing builds on both versions is not runtime or behavior proof.
+- Claim `dual-version` compatibility only after all required matrix rows pass for the same release artifact or for the explicitly documented version-specific artifact strategy.

package/skills/dsh-plugin-upgrade/references/migration-map.md

@@ -25,6 +25,16 @@ Session snapshots no longer own Conversation views or all pending-interaction fa
 - React, Cordis, client-store, ui-slots, and ui-primitives baseline modules are implicit and should not be repeated in `dsh.client.external`.
 - A declared web client requires a published `exports["./client"]` artifact.
 
+## Dependency ownership
+
+An exact symbol move and its npm dependency placement are separate catalog decisions. The current target policy records Client relationships explicitly:
+
+- Cordis must be present in matching `peerDependencies` and `devDependencies` for a client plugin;
+- `dsh-client-store` and `dsh-session` Client/type relationships are development-only;
+- existing published peer ranges are not widened automatically merely because a development dependency is pinned to the target catalog version.
+
+Do not copy a replacement package into every dependency section that contained `dsh-client-runtime`. After apply, use the dependency verification gate to synchronize the lockfile and confirm the versions actually resolved in `node_modules`.
+
 ## Patch targets
 
 For `MIG_PATCH_TARGET_CHANGED`, first confirm the Harness checkout is exact and its tag scan succeeded. Then compare the old and target web profile bundle patches: remove an obsolete override only when the old row disappeared without a replacement, or update the id when upstream deliberately renamed/moved the row. Do not guess a replacement id from a similar name.

package/skills/dsh-plugin-upgrade/references/source-investigation.md

@@ -0,0 +1,97 @@
+# Investigate the actual DSH source and installed runtime
+
+Use this workflow whenever the plugin's declared or requested DSH version differs from a catalog reference, a semantic migration remains, or the developer asks what changed in DSH. The catalog is a starting point, not a substitute for checking the actual runtime and source.
+
+## 1. Record the runtime actually in use
+
+Keep these as separate facts:
+
+- the DSH executable selected by PATH or an explicit command;
+- the version printed by that executable;
+- the DSH package installation backing the executable;
+- the plugin's dependency, peer, optional-peer, and development ranges;
+- the DSH packages resolved in the plugin lockfile and `node_modules`;
+- the requested target version;
+- the source and target refs used by the migration catalog.
+
+On Windows, use read-only commands such as:
+
+```powershell
+Get-Command dsh -All
+dsh --version
+npm root --global
+Get-Content "$env:APPDATA\npm\node_modules\@deepseek-ai\dsh\package.json"
+```
+
+On macOS or Linux:
+
+```sh
+command -v -a dsh
+dsh --version
+npm root --global
+cat "$(npm root --global)/@deepseek-ai/dsh/package.json"
+```
+
+Also inspect `DSH_HOME`, the selected profile manifest and lockfile, the plugin's lockfile, and any project-local DSH package. Do not assume PATH, a running DSH process, the profile, and the plugin workspace all resolve the same version.
+
+## 2. Locate or obtain a Harness checkout
+
+Prefer, in order:
+
+1. an explicit checkout supplied by the developer;
+2. a nearby project checkout whose remote and refs can be verified;
+3. source provenance recorded by the installed package or repository metadata;
+4. an upstream checkout obtained only when network access and cloning/fetching are within the developer's authorization.
+
+Record `git remote -v`, worktree status, `git rev-parse <ref>`, and whether the checkout contains both relevant refs. Do not switch, reset, clean, or update a developer's checkout merely to inspect another ref. Use `git show`, `git diff`, `git grep`, and `git ls-tree` against refs without changing the worktree. A dirty checkout can still be used for ref-based inspection; report that the worktree itself was not treated as target evidence.
+
+## 3. Build the additional-version delta
+
+When the plugin's actual source or requested target is not exactly the catalog pair, compare the missing interval separately. At minimum inspect:
+
+```sh
+git diff --name-status <actual-source-ref>..<actual-target-ref> -- packages apps
+git diff <actual-source-ref>..<actual-target-ref> -- '**/package.json'
+git grep -n '<old-symbol-or-service>' <actual-source-ref> -- packages apps
+git grep -n '<old-symbol-or-service>' <actual-target-ref> -- packages apps
+git grep -n '<new-owner-or-symbol>' <actual-target-ref> -- packages apps
+git show <actual-target-ref>:<candidate-package>/package.json
+```
+
+Check package existence and exports, declaration files or TypeScript source, Service names and Cordis injection, snapshot shapes, event and cleanup lifecycles, client manifest rules, profile patches, build presets, and upstream architecture or migration notes. Do not infer an API from a similarly named package or symbol.
+
+Classify every additional difference as:
+
+- confirmed exact move;
+- semantic behavior change;
+- removed with no replacement;
+- configuration or packaging change;
+- unknown because source or evidence is unavailable.
+
+Only the catalog-confirmed pair is eligible for the built-in safe codemod. Treat additional exact-looking changes as proposed manual edits until independently reviewed and tested.
+
+## 4. Investigate each semantic task in the plugin
+
+Start from the finding's `file`, `symbol`, `targetModule`, `targetSymbol`, and `reason`. Then:
+
+1. trace every caller and lifecycle owner in the plugin;
+2. inspect the target package export and implementation at the exact target ref;
+3. compare source and target snapshot/event shapes;
+4. identify activation, subscription, cleanup, error, and recovery behavior;
+5. decide whether one source tree can support both requested DSH versions;
+6. propose the smallest behavior-preserving change and name the tests needed to prove it.
+
+If the catalog reference paths in `migration.references` exist in the Harness checkout, read them at the target ref. They are supporting evidence, not a replacement for inspecting the actual exported API and the plugin's callers.
+
+## 5. Report provenance and uncertainty
+
+For each conclusion, report:
+
+- actual installed/runtime version evidence;
+- plugin manifest and resolved dependency evidence;
+- checkout remote, refs, and commits;
+- catalog-covered delta versus additionally inspected delta;
+- exact source paths, symbols, or commands used;
+- remaining unknowns and the developer decision they block.
+
+Never call an unlisted version combination compatible merely because the catalog pair passed.

package/skills/dsh-plugin-upgrade/references/verification.md

@@ -6,7 +6,9 @@ Static analysis covers source/type imports, dependency ranges, client graph decl
 
 ## Build
 
-The CLI selects the package manager from lockfiles and runs declared scripts in this order: `typecheck`, `build`, `test`, `pack:check`, stopping at the first failure. Artifact verification requires a successful `build` or `pack:check`; `typecheck`/`test` alone do not pass this gate.
+Build and runtime verification require `--yes --install`. The CLI selects the package manager from lockfiles, synchronizes dependencies with dependency lifecycle scripts disabled, records the lockfile hash before and after, and verifies installed DSH/Cordis versions against `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies`. Required peers must resolve and satisfy every declared range. Missing optional dependencies or peers are recorded as `optional-missing`; when installed, they must satisfy their ranges. It then runs declared scripts in this order: `typecheck`, `build`, `test`, `pack:check`, stopping at the first failure. Artifact verification requires a successful `build` or `pack:check`; `typecheck`/`test` alone do not pass this gate.
+
+If dependency installation or resolution verification fails, stop before running project scripts. Review and retain package manifest and lockfile changes with the source migration.
 
 ## Runtime
 

package/src/cli.mjs

@@ -45,7 +45,9 @@ Options:
   --from <ref>            source DSH ref (default: dsh-v0.1.1-rc.2)
   --to <ref>              target DSH ref (default: dsh-v0.1.2-alpha.2)
   --safe                  restrict migrate apply to catalog-confirmed exact rewrites
+  --plan-file <path>      persist or consume the reviewed migrate apply plan
   --level <level>         static, build, or runtime verification
+  --install               synchronize dependencies before build/runtime verification
   --keep-temp             retain a successful runtime verification directory
   -h, --help             show help
   -v, --version          show version
@@ -85,7 +87,9 @@ const HELP_ZH = `用法：
   --from <ref>           源 DSH ref（默认：dsh-v0.1.1-rc.2）
   --to <ref>             目标 DSH ref（默认：dsh-v0.1.2-alpha.2）
   --safe                 migrate apply 仅执行 catalog 确认的精确改写
+  --plan-file <路径>     保存或读取已审阅的 migrate apply 计划
   --level <级别>        static、build 或 runtime
+  --install              在 build/runtime 验证前同步依赖
   --keep-temp            成功后仍保留运行时验证目录
   -h, --help             显示帮助
   -v, --version          显示版本
@@ -143,8 +147,11 @@ function parse(args) {
     else if (arg === '--to') options.to = valueAfter(args, index++, arg)
     else if (arg.startsWith('--to=')) options.to = optionValue(arg, '--to')
     else if (arg === '--safe') options.safe = true
+    else if (arg === '--plan-file') options.planFile = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--plan-file=')) options.planFile = optionValue(arg, '--plan-file')
     else if (arg === '--level') options.level = valueAfter(args, index++, arg)
     else if (arg.startsWith('--level=')) options.level = optionValue(arg, '--level')
+    else if (arg === '--install') options.install = true
     else if (arg === '--keep-temp') options.keepTemp = true
     else if (arg === '--help' || arg === '-h') options.help = true
     else if (arg === '--version' || arg === '-v') options.version = true
@@ -293,7 +300,7 @@ async function main() {
     if (!['analyze', 'apply', 'verify'].includes(options.migrateAction)) throw new Error('migrate needs analyze, apply, or verify')
     if (options.migrateAction === 'apply' && options.safe !== true) throw new Error('migrate apply requires --safe')
     if (options.migrateAction === 'apply' && options.pluginRoot === undefined) throw new Error('migrate apply requires an explicit plugin root')
-    const migrationOptions = { from: options.from, to: options.to, harnessRoot: options.harnessRoot, dshCommand: options.dshCommand, level: options.level, yes: options.yes, safe: options.safe, keepTemp: options.keepTemp }
+    const migrationOptions = { from: options.from, to: options.to, harnessRoot: options.harnessRoot, dshCommand: options.dshCommand, level: options.level, yes: options.yes, safe: options.safe, keepTemp: options.keepTemp, planFile: options.planFile, install: options.install }
     if (options.migrateAction === 'verify') {
       const { formatVerification, verifyMigration } = await import('./migrate-verify.mjs')
       const result = verifyMigration(options.pluginRoot, migrationOptions)

package/src/migrate-verify.mjs

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { basename, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import crossSpawn from 'cross-spawn'
+import semver from 'semver'
 import { analyzeMigration, publicMigrationReport } from './migrate.mjs'
 import { sha256 } from './safe-write.mjs'
 
@@ -38,9 +39,55 @@ function commandEvidence(result) {
 }
 
 function packageManager(root) {
-  if (existsSync(join(root, 'pnpm-lock.yaml'))) return { command: 'pnpm', run: script => ['run', script], pack: destination => ['pack', '--pack-destination', destination] }
-  if (existsSync(join(root, 'yarn.lock'))) return { command: 'yarn', run: script => [script], pack: destination => ['pack', '--out', join(destination, 'plugin.tgz')] }
-  return { command: 'npm', run: script => ['run', script], pack: destination => ['pack', '--json', '--pack-destination', destination] }
+  if (existsSync(join(root, 'pnpm-lock.yaml'))) return { command: 'pnpm', install: ['install', '--no-frozen-lockfile', '--ignore-scripts'], lockfile: 'pnpm-lock.yaml', run: script => ['run', script], pack: destination => ['pack', '--pack-destination', destination] }
+  if (existsSync(join(root, 'yarn.lock'))) return { command: 'yarn', install: ['install', '--ignore-scripts'], lockfile: 'yarn.lock', run: script => [script], pack: destination => ['pack', '--out', join(destination, 'plugin.tgz')] }
+  return { command: 'npm', install: ['install', '--ignore-scripts'], lockfile: 'package-lock.json', run: script => ['run', script], pack: destination => ['pack', '--json', '--pack-destination', destination] }
+}
+
+function lockfileHash(root, manager) {
+  const file = join(root, manager.lockfile)
+  return existsSync(file) ? sha256(readFileSync(file)) : undefined
+}
+
+function installedManifestFile(root, name) {
+  let current = resolve(root)
+  while (true) {
+    const file = join(current, 'node_modules', ...name.split('/'), 'package.json')
+    if (existsSync(file)) return file
+    const parent = dirname(current)
+    if (parent === current) return undefined
+    current = parent
+  }
+}
+
+export function installedDependencyEvidence(root, manifest) {
+  const requested = new Map()
+  for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    for (const [name, range] of Object.entries(manifest[field] ?? {})) {
+      if (name !== '@deepseek-ai/cordis' && !name.startsWith('@deepseek-ai/dsh-')) continue
+      const optional = field === 'optionalDependencies' || (field === 'peerDependencies' && manifest.peerDependenciesMeta?.[name]?.optional === true)
+      const declarations = requested.get(name) ?? []
+      declarations.push({ field, range, optional })
+      requested.set(name, declarations)
+    }
+  }
+  return [...requested].map(([name, declarations]) => {
+    const file = installedManifestFile(root, name)
+    if (file === undefined) {
+      const optional = declarations.every(item => item.optional)
+      return { name, declarations, installed: false, optional, passed: optional, ...(optional ? { status: 'optional-missing' } : { error: 'declared dependency is not installed' }) }
+    }
+    try {
+      const installed = JSON.parse(readFileSync(file, 'utf8'))
+      const checks = declarations.map(item => {
+        const validRange = typeof item.range === 'string' ? semver.validRange(item.range) : null
+        return { ...item, passed: validRange !== null && semver.satisfies(installed.version, validRange) }
+      })
+      return { name, declarations: checks, installed: true, manifestFile: file, installedVersion: installed.version, passed: installed.name === name && checks.every(item => item.passed) }
+    } catch (error) {
+      return { name, declarations, installed: true, manifestFile: file, passed: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  })
 }
 
 function discoverDsh(options) {
@@ -98,6 +145,7 @@ export function verifyMigration(pluginRoot = process.cwd(), options = {}) {
   const level = options.level ?? 'static'
   if (!['static', 'build', 'runtime'].includes(level)) throw new Error(`unsupported verification level ${level}`)
   if (level !== 'static' && options.yes !== true) throw new Error(`migrate verify --level ${level} executes project commands and requires --yes`)
+  if (level !== 'static' && options.install !== true) throw new Error(`migrate verify --level ${level} requires --install to synchronize and verify target dependencies`)
   const analysis = analyzeMigration(pluginRoot, options)
   const result = {
     schemaVersion: 1,
@@ -111,10 +159,29 @@ export function verifyMigration(pluginRoot = process.cwd(), options = {}) {
     manualBehaviorVerificationRequired: true,
   }
   if (level === 'static') return result
+  if (!result.passed) return result
 
   const root = analysis.plugin.root
   const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
   const manager = packageManager(root)
+  const lockfileBefore = lockfileHash(root, manager)
+  const installRun = commandResult(manager.command, manager.install, { cwd: root })
+  const dependencies = installedDependencyEvidence(root, manifest)
+  const dependenciesPassed = installRun.passed && dependencies.every(item => item.passed)
+  result.stages.push({
+    name: 'dependencies',
+    passed: dependenciesPassed,
+    packageManager: manager.command,
+    command: commandEvidence(installRun),
+    lockfile: {
+      file: manager.lockfile,
+      beforeHash: lockfileBefore,
+      afterHash: lockfileHash(root, manager),
+    },
+    resolved: dependencies,
+  })
+  result.passed = dependenciesPassed
+  if (!result.passed) return result
   const scripts = ['typecheck', 'build', 'test', 'pack:check'].filter(name => typeof manifest.scripts?.[name] === 'string')
   const commandRuns = []
   for (const script of scripts) {

package/src/migrate.mjs

@@ -1,14 +1,14 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
-import { basename, join, relative, resolve } from 'node:path'
+import { basename, isAbsolute, join, relative, resolve } from 'node:path'
 import semver from 'semver'
 import ts from 'typescript'
 import { parseDocument } from 'yaml'
-import { atomicWrite, sha256 } from './safe-write.mjs'
+import { atomicWrite, sha256, sha256File, writeNewFile } from './safe-write.mjs'
 import { loadMigration, verifyHarnessCheckout } from './migration-catalog.mjs'
 
 const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts'])
 const SOURCE_DIRS_TO_SKIP = new Set(['.git', 'node_modules', 'coverage'])
-const ARTIFACT_DIRS = ['lib', 'dist', 'build']
+const ARTIFACT_DIRS = ['lib', 'dist', 'build', 'out']
 const DEPENDENCY_FIELDS = ['dependencies', 'peerDependencies', 'devDependencies', 'optionalDependencies']
 const LOCKFILES = new Set(['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'])
 const NON_RUNTIME_TEXT_EXTENSIONS = new Set(['.md', '.mdx', '.txt', '.snap'])
@@ -132,13 +132,25 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
             remaining.push(spec)
             const semantic = rule?.confidence === 'semantic'
             findings.push({ code: semantic ? 'MIG_SEMANTIC_API_CHANGE' : 'MIG_REMOVED_PACKAGE_REFERENCE', severity: 'error', message: semantic ? `${spec.imported} requires a semantic migration: ${rule.reason}` : `${moduleName} was removed without a safe automatic replacement`, location: where, evidence: { module: moduleName, ...(spec.imported ? { symbol: spec.imported } : {}) }, autoFix: 'none' })
-            unresolved.push({ file: where.file, package: rootName, symbol: spec.imported, reason: rule?.reason ?? 'No exact replacement is known.' })
+            unresolved.push({
+              file: where.file,
+              package: rootName,
+              symbol: spec.imported,
+              ...(rule?.toModule ? { targetModule: rule.toModule } : {}),
+              ...(rule?.toSymbol ? { targetSymbol: rule.toSymbol } : {}),
+              reason: rule?.reason ?? 'No exact replacement is known.',
+            })
           }
         }
         const declarationText = ts.isImportDeclaration(node) ? text.slice(node.getStart(source), node.getEnd()) : ''
         const simpleNamedImport = exact.length > 0 && ts.isImportDeclaration(node) && node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings) && node.importClause.name === undefined && node.attributes === undefined && node.assertClause === undefined && !/\/(?:\/|\*)/.test(declarationText)
         if (simpleNamedImport) {
-          for (const item of exact) exactTargets.set(`${rootName}\0${item.toModule}`, { fromPackage: rootName, toPackage: packageRoot(item.toModule) })
+          for (const item of exact) exactTargets.set(`${rootName}\0${item.toModule}`, {
+            fromPackage: rootName,
+            toPackage: packageRoot(item.toModule),
+            relationship: 'client',
+            typeOnly: item.typeOnly,
+          })
           const groups = new Map()
           for (const item of exact) {
             const list = groups.get(item.toModule) ?? []
@@ -203,6 +215,12 @@ function manifestFindings(manifest, catalog) {
     }
   }
   const client = manifest.value.dsh?.client
+  if (client !== undefined && (client === null || Array.isArray(client) || typeof client !== 'object')) {
+    findings.push({ code: 'MIG_INVALID_MANIFEST', severity: 'error', message: 'dsh.client must be an object', location: { file: 'package.json' }, evidence: { field: 'dsh.client' }, autoFix: 'none' })
+    return findings
+  }
+  if (client !== undefined && typeof client.platform !== 'string') findings.push({ code: 'MIG_INVALID_MANIFEST', severity: 'error', message: 'dsh.client.platform must be a string', location: { file: 'package.json' }, evidence: { field: 'dsh.client.platform' }, autoFix: 'none' })
+  if (client?.immediately !== undefined && typeof client.immediately !== 'boolean') findings.push({ code: 'MIG_INVALID_MANIFEST', severity: 'error', message: 'dsh.client.immediately must be a boolean', location: { file: 'package.json' }, evidence: { field: 'dsh.client.immediately' }, autoFix: 'none' })
   for (const field of ['inject', 'external']) {
     const values = client?.[field]
     if (values !== undefined && !Array.isArray(values)) {
@@ -302,10 +320,6 @@ function planManifest(manifest, sourceResults, artifactResults, opaqueReferences
     for (const removedPackage of presentRemoved) {
       const stillUsed = sourceReferences.has(removedPackage) || clientGraph.includes(removedPackage) || opaqueReferences.has(removedPackage) || (sourceResults.length === 0 && artifactText.includes(removedPackage))
       if (!stillUsed) delete deps[removedPackage]
-      for (const move of exactTargets.filter(item => item.fromPackage === removedPackage)) {
-        const version = targetVersion(move.toPackage, catalog)
-        if (version !== undefined && deps[move.toPackage] === undefined) deps[move.toPackage] = version
-      }
     }
     if (field === 'devDependencies') {
       for (const [name, range] of Object.entries(deps)) {
@@ -314,6 +328,16 @@ function planManifest(manifest, sourceResults, artifactResults, opaqueReferences
       }
     }
   }
+  for (const move of new Map(exactTargets.map(item => [`${item.relationship}\0${item.toPackage}`, item])).values()) {
+    const fields = catalog.packages.dependencyPolicies?.[move.toPackage]?.[move.relationship]
+    const version = targetVersion(move.toPackage, catalog)
+    if (!Array.isArray(fields) || version === undefined) continue
+    for (const field of fields) {
+      if (!DEPENDENCY_FIELDS.includes(field)) throw new Error(`migration catalog has an invalid dependency field ${field}`)
+      const deps = next[field] ??= {}
+      if (deps[move.toPackage] === undefined) deps[move.toPackage] = version
+    }
+  }
   const changes = []
   for (const field of DEPENDENCY_FIELDS) {
     const before = manifest.value[field] ?? {}
@@ -336,6 +360,12 @@ function summarize(findings, safeEdits, unresolved) {
   }
 }
 
+function analysisInputs(root) {
+  return walkAll(root, SOURCE_DIRS_TO_SKIP)
+    .map(file => ({ file: relativePath(root, file), hash: sha256File(file) }))
+    .sort((left, right) => left.file.localeCompare(right.file))
+}
+
 export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   const root = resolve(pluginRoot)
   if (!statSync(root).isDirectory()) throw new Error(`plugin root is not a directory: ${root}`)
@@ -363,28 +393,84 @@ export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   return {
     schemaVersion: 1,
     command: 'migrate analyze',
-    migration: { id: catalog.manifest.id, from: catalog.manifest.from, to: catalog.manifest.to, harness },
+    migration: { id: catalog.manifest.id, from: catalog.manifest.from, to: catalog.manifest.to, references: catalog.manifest.references ?? {}, harness },
     plugin: { root, name: manifest.value.name ?? basename(root), version: manifest.value.version ?? 'unknown', manifestFile: manifest.file, packageManager: existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : 'npm' },
     summary: summarize(findings, safeEdits, unresolved),
     findings,
     safeEdits,
     semanticTasks: unresolved,
+    sourceInvestigation: {
+      required: harness.exact !== true || unresolved.length > 0,
+      targetRef: catalog.manifest.to.ref,
+      catalogReferences: catalog.manifest.references ?? {},
+      semanticTargets: [...new Set(unresolved.map(item => item.targetModule).filter(Boolean))],
+    },
     verification: { status: 'analyzed', level: 'static-analysis', passed: findings.every(item => item.severity !== 'error') },
+    _inputs: analysisInputs(root),
     _plan: changed.map(item => ({ file: item.file, snapshot: { file: item.file, exists: true, hash: sha256(item.text) }, nextText: item.nextText })),
   }
 }
 
 export function publicMigrationReport(report) {
-  const { _plan, ...value } = report
+  const { _inputs, _plan, ...value } = report
   const harness = { ...value.migration.harness }
   delete harness.fromEntryIds
   delete harness.toEntryIds
   return { ...value, migration: { ...value.migration, harness } }
 }
 
+export function createMigrationPlan(report) {
+  const publicReport = publicMigrationReport(report)
+  const payload = {
+    schemaVersion: 1,
+    command: 'migrate apply plan',
+    plugin: { root: report.plugin.root, manifestFile: report.plugin.manifestFile },
+    migration: {
+      id: report.migration.id,
+      from: report.migration.from.ref,
+      to: report.migration.to.ref,
+      harness: {
+        status: report.migration.harness.status,
+        fromCommit: report.migration.harness.fromCommit,
+        toCommit: report.migration.harness.toCommit,
+      },
+    },
+    reportHash: sha256(JSON.stringify(publicReport)),
+    inputs: report._inputs,
+    edits: report.safeEdits,
+  }
+  return { ...payload, planId: sha256(JSON.stringify(payload)) }
+}
+
+function readMigrationPlan(file) {
+  const value = JSON.parse(readFileSync(resolve(file), 'utf8'))
+  if (value?.schemaVersion !== 1 || value.command !== 'migrate apply plan' || typeof value.planId !== 'string') throw new Error('invalid migration plan file')
+  const { planId, ...payload } = value
+  if (sha256(JSON.stringify(payload)) !== planId) throw new Error('migration plan file digest does not match its contents')
+  return value
+}
+
+function assertMigrationPlan(report, plan) {
+  const current = createMigrationPlan(report)
+  if (plan.plugin.root !== current.plugin.root || plan.plugin.manifestFile !== current.plugin.manifestFile) throw new Error('migration plan targets a different plugin')
+  if (plan.migration.id !== current.migration.id || plan.migration.from !== current.migration.from || plan.migration.to !== current.migration.to) throw new Error('migration plan targets a different catalog')
+  if (plan.reportHash !== current.reportHash || JSON.stringify(plan.inputs) !== JSON.stringify(current.inputs) || JSON.stringify(plan.edits) !== JSON.stringify(current.edits)) throw new Error('plugin analysis changed after the preview; create and review a new migration plan')
+  return current
+}
+
 export function applyMigration(report, options = {}) {
   if (options.safe !== true) throw new Error('migrate apply requires --safe')
-  if (options.yes !== true) return { mode: 'preview', ...publicMigrationReport(report) }
+  if (options.planFile === undefined) throw new Error('migrate apply requires --plan-file so the confirmed preview can be verified')
+  const planFile = resolve(options.planFile)
+  const planRelative = relative(report.plugin.root, planFile)
+  if (planRelative === '' || (planRelative !== '..' && !planRelative.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && !isAbsolute(planRelative))) throw new Error('migration plan file must be outside the plugin root')
+  if (options.yes !== true) {
+    const plan = createMigrationPlan(report)
+    writeNewFile(planFile, `${JSON.stringify(plan, null, 2)}\n`)
+    return { mode: 'preview', plan: { file: planFile, id: plan.planId }, ...publicMigrationReport(report) }
+  }
+  const plan = readMigrationPlan(planFile)
+  const verifiedPlan = assertMigrationPlan(report, plan)
   // Exact edits remain safe when semantic work remains; unresolved references keep the removed dependency.
   for (const item of report._plan) {
     const currentExists = existsSync(item.snapshot.file)
@@ -393,7 +479,7 @@ export function applyMigration(report, options = {}) {
   }
   const writes = report._plan.map(item => ({ ...atomicWrite(item.snapshot, item.nextText), beforeHash: item.snapshot.hash, afterHash: sha256(item.nextText) }))
   const verification = analyzeMigration(report.plugin.root, { from: report.migration.from.ref, to: report.migration.to.ref, harnessRoot: report.migration.harness.root })
-  return { mode: 'applied', writes, report: publicMigrationReport(verification) }
+  return { mode: 'applied', plan: { file: planFile, id: verifiedPlan.planId }, writes, report: publicMigrationReport(verification) }
 }
 
 export function formatMigrationReport(report, language = 'en') {

package/src/safe-write.mjs

@@ -1,11 +1,38 @@
 import { createHash, randomBytes } from 'node:crypto'
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
 export function sha256(text) {
   return createHash('sha256').update(text).digest('hex')
 }
 
+export function sha256File(file) {
+  const hash = createHash('sha256')
+  const descriptor = openSync(file, 'r')
+  const buffer = Buffer.allocUnsafe(64 * 1024)
+  try {
+    let bytesRead
+    do {
+      bytesRead = readSync(descriptor, buffer, 0, buffer.length, null)
+      if (bytesRead > 0) hash.update(buffer.subarray(0, bytesRead))
+    } while (bytesRead > 0)
+  } finally {
+    closeSync(descriptor)
+  }
+  return hash.digest('hex')
+}
+
+export function writeNewFile(file, text) {
+  mkdirSync(dirname(file), { recursive: true })
+  try {
+    writeFileSync(file, text, { flag: 'wx', mode: 0o600 })
+  } catch (error) {
+    if (error?.code === 'EEXIST') throw new Error(`${file} already exists; choose a new migration plan path`)
+    throw error
+  }
+  return { file }
+}
+
 export function snapshotFile(file) {
   const exists = existsSync(file)
   const text = exists ? readFileSync(file, 'utf8') : ''

package/skills/dsh-plugin-upgrade/evals/evals.json

@@ -1,49 +0,0 @@
-{
-  "skill_name": "dsh-plugin-upgrade",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "检查这个只有后端 bundle 的 DSH 插件能否从 DSH 0.1.1 升级到 0.1.2。它的 peerDependencies 仍是 ^0.1.1，不要改文件。",
-      "expected_output": "Records the plugin's actual version ranges, uses the current exact-ref catalog as the analysis baseline, identifies target range mismatch, and does not claim runtime compatibility.",
-      "expectations": [
-        "Uses migrate analyze before proposing edits",
-        "Distinguishes the requested 0.1.1 to 0.1.2 upgrade from the catalog's exact reference refs",
-        "Reports the exact verification status as analyzed",
-        "Does not write files or execute build scripts"
-      ]
-    },
-    {
-      "id": 2,
-      "prompt": "把这个前端插件升级到 DSH 0.1.2。源码里有 import type { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'，可以安全改的帮我改，其他的列出来。",
-      "expected_output": "Safely moves ClientContext to Cordis while leaving ISessions as an explicit semantic migration task, with backup evidence.",
-      "expectations": [
-        "Detects type-only imports from source rather than relying on the bundle",
-        "Uses migrate apply --safe and requires explicit confirmation for writes",
-        "Does not mechanically rewrite the semantic ISessions contract"
-      ]
-    },
-    {
-      "id": 3,
-      "prompt": "完整升级这个混合前后端插件并验证，Harness 在 /workspace/deepseek-harness。构建失败也要把现场路径告诉我。",
-      "expected_output": "Performs analyze, safe apply, semantic work, build and isolated runtime gates; reports the highest proven status and retained failure workspace.",
-      "expectations": [
-        "Uses the exact Harness refs and verifies the catalog commits",
-        "Runs static, build, then runtime verification in order",
-        "Uses a temporary DSH_HOME and reports retained failure state",
-        "Keeps business behavior verification separate from activation smoke"
-      ]
-    },
-    {
-      "id": 4,
-      "prompt": "帮我升级这个插件，但机器上的 dsh-doctor 是旧版，而且我没有授权修改全局 npm 包。请先检查有没有新版本，再继续迁移。",
-      "expected_output": "Checks the registry read-only, selects one exact-version npx CLI with the required catalog, avoids global installation, and reports the selected version and update status.",
-      "expectations": [
-        "Checks the local CLI version and exact migration catalog before use",
-        "Uses npm view as a read-only registry update check",
-        "Pins one resolved npx package version for all migration phases",
-        "Does not install or update a global CLI without explicit authorization",
-        "Reports local, registry, selected CLI, catalog, and update-status evidence"
-      ]
-    }
-  ]
-}