@bruc3van/dsh-doctor 0.5.3 → 0.5.4

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.
 
@@ -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.4 \
   dsh-doctor migrations list
 ```
 

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 安装。
 
@@ -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.4 \
   dsh-doctor migrations list
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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, [migration-map.md](references/migration-map.md) before making semantic changes, and [verification.md](references/verification.md) before 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:
@@ -56,6 +71,8 @@ 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
@@ -90,6 +107,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 +126,4 @@ 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.
+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/evals/evals.json

@@ -15,9 +15,11 @@
     {
       "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.",
+      "expected_output": "Recognizes that write authorization does not decide whether 0.1.1 may be dropped, asks the compatibility question, and waits before applying changes; after a 0.1.2-only answer, safely moves ClientContext while leaving ISessions as a semantic task.",
       "expectations": [
         "Detects type-only imports from source rather than relying on the bundle",
+        "Explicitly asks whether the same release must preserve DSH 0.1.1 compatibility",
+        "Does not preview, apply, edit, install, build, or run the plugin until that decision is answered",
         "Uses migrate apply --safe and requires explicit confirmation for writes",
         "Does not mechanically rewrite the semantic ISessions contract"
       ]
@@ -25,9 +27,10 @@
     {
       "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.",
+      "expected_output": "Analyzes first, asks whether the same release must retain 0.1.1, and waits before safe apply or executable gates; after the decision, performs the selected migration and verification matrix and reports retained failure state.",
       "expectations": [
         "Uses the exact Harness refs and verifies the catalog commits",
+        "Treats legacy compatibility as an explicit product decision rather than inferring it from an upgrade request",
         "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"
@@ -36,13 +39,37 @@
     {
       "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.",
+      "expected_output": "Checks the registry read-only, selects one exact-version npx CLI with the required catalog, avoids global installation, asks for the unresolved compatibility intent, and reports the selected version and update status without starting writes or executable verification.",
       "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"
+        "Reports local, registry, selected CLI, catalog, and update-status evidence",
+        "Stops at analyzed until the developer chooses 0.1.2-only or dual-version support"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "升级这个插件到 DSH 0.1.2，但同一个 npm 版本还必须继续支持 0.1.1。可以修改代码并执行测试；如果单一产物做不到，先告诉我冲突和可选方案，不要自行放弃旧版。",
+      "expected_output": "Records an explicit dual-version requirement, assesses whether imports, manifests, graph declarations, and artifacts can coexist, selects or proposes an adapter/conditional-build/separate-release strategy, and verifies both version rows before claiming compatibility.",
+      "expectations": [
+        "Records the compatibility intent as dual-version without asking a redundant question",
+        "Treats 0.1.2 safe codemods as candidates that still require 0.1.1 review",
+        "Does not widen peer ranges or claim one-artifact support without installation and runtime evidence",
+        "Separately verifies build, artifact, runtime, and behavior evidence for DSH 0.1.1 and 0.1.2",
+        "Reports an exact incompatibility and asks before switching to separate releases or dropping 0.1.1"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "这是一次 breaking release，只需要支持 DSH 0.1.2，不再兼容 0.1.1。先分析再按安全流程修改和验证。",
+      "expected_output": "Records the explicit 0.1.2-only intent without asking a redundant compatibility question, then follows analyze, safe preview/apply, semantic migration, and target verification gates.",
+      "expectations": [
+        "Records the compatibility intent as 0.1.2-only",
+        "Does not ask again whether 0.1.1 compatibility must be retained",
+        "Still separates write authorization from compatibility intent and follows preview and confirmation safeguards",
+        "Reports only the 0.1.2 verification evidence actually achieved"
       ]
     }
   ]

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.