@bruc3van/dsh-doctor 0.5.6 → 0.5.7

package/README.en.md

@@ -2,19 +2,24 @@
 
 [中文](README.md) | English
 
-DSH Doctor helps an agent diagnose and upgrade DeepSeek Harness plugins: identify API changes between releases, modify code where the migration is known, point out semantic changes that need developer judgment, then rebuild and verify the plugin.
+DSH Doctor is an upgrade and troubleshooting tool for DSH plugin developers and agents. It finds what needs to change during an upgrade, handles changes that are known to be safe, and then checks dependencies, build output, installation, and activation.
 
-The current focus is:
+When a change depends on the plugin's business logic, Doctor calls it out for the agent or developer instead of guessing. Every edit is previewed and backed up first, and runtime checks use a temporary DSH environment rather than the developer's everyday profile.
 
-```text
-DSH 0.1.1 → DSH 0.1.2
-```
+> This is a community-maintained third-party project, not an official DeepSeek project. The current migration scope is DSH 0.1.1 → 0.1.2. The catalog exactly covers `dsh-v0.1.1-rc.2` → `dsh-v0.1.2-alpha.3` and retains the alpha.2 historical rules. Differences outside those catalogs still require a separate investigation and are not proven compatible by the catalog.
 
-The project also diagnoses DSH profiles and installed plugins, checks for compatible versions, and performs safety checks before quarantine or removal.
+## What it helps with
+
+| Scenario | What DSH Doctor provides |
+|---|---|
+| Upgrade a plugin | Scans source, dependencies, manifest, client graph, patches, and build output; applies exact catalog-confirmed migrations and leaves semantic work to the agent |
+| Verify a migration | Runs static reanalysis, dependency synchronization, build/test scripts, real tarball packaging, and temporary-profile installation and activation checks |
+| Diagnose a DSH environment | Checks profile layers, plugin versions and peers, lockfile, bundles, patches, client contracts, duplicate mounts, and DSH CLI/Harness version drift |
+| Recover safely | Compares before/after baselines, checks compatible updates, generates and verifies quarantine overlays, and records dependency and configuration impact before removal |
 
-> This is a community-maintained third-party project, not an official DeepSeek project. The migration scope remains DSH 0.1.1 → 0.1.2; the current known-latest catalog exactly covers `dsh-v0.1.1-rc.2` through `dsh-v0.1.2-alpha.3`. The older alpha.2 catalog remains as historical rules. When a newer 0.1.2 prerelease appears, inspect its delta before deliberately updating the catalog and skill.
+Agents can orchestrate these capabilities through the skill, while other tools can integrate the same structured CLI workflows.
 
-## Upgrade a plugin with the skill
+## Recommended: use the skill with an agent
 
 Install the repository's [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) skill:
 
@@ -29,219 +34,110 @@ 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 guides the agent to:
 
-The skill reminds the agent to work in this order:
+1. establish the plugin, actual DSH installation, Harness checkout, package manager, and usable DSH Doctor;
+2. analyze source, dependencies, configuration, patches, and existing artifacts;
+3. confirm whether the upgraded plugin release targets only 0.1.2 or must remain compatible with 0.1.1;
+4. preview and apply exact changes allowed by that compatibility strategy, then handle semantic migrations that require business context;
+5. rebuild and report static, artifact, isolated-runtime, and business-behavior evidence separately;
+6. commit or publish through the plugin repository's own process only when the developer explicitly requests it.
 
-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. 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 runs a pinned version through `npm exec` without changing the global installation.
 
-`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.
-
-After verification, the agent can follow the plugin repository's existing versioning and release process if requested. The skill itself does not commit or publish anything automatically.
+An upgrade request does not itself authorize dropping the old runtime. When compatibility intent is missing, the skill may perform read-only analysis but asks before migration writes, dependency installation, build, or runtime commands. Dual-version mode requires separate 0.1.1 and 0.1.2 evidence; one 0.1.2 smoke test is not dual-version proof.
 
 ## How it works
 
-DSH Doctor has three parts:
+DSH Doctor has three parts that constrain one another:
 
-- **Skill**: tells the agent which steps to follow, which actions need confirmation, and what to report;
-- **CLI**: scans the plugin, lists problems, changes deterministic code, and runs verification;
-- **Migration catalog**: records known package, API, Service, configuration, and behavior changes between the two DSH versions.
+- **Skill**: defines investigation steps, the compatibility decision, confirmation gates, and reporting standards for the agent;
+- **CLI**: provides read-only analysis, safe edits, diagnosis, baselines, recovery, and staged verification;
+- **Migration catalog**: stores exact DSH tags/commits and known package, symbol, Service, configuration, and behavior changes.
 
-The workflow is:
+The plugin migration workflow is:
 
 ```text
-analyze
-  → change deterministic code
+investigate the actual environment
+  → catalog-driven analysis
+  → reviewed-plan exact changes
   → agent handles semantic changes
-  → rebuild
-  → static verification
+  → build and artifact verification
   → temporary-profile installation and activation
-  → publish through the plugin's own release process
+  → plugin business-behavior verification
 ```
 
-The CLI only auto-edits migrations marked `exact` by the catalog. Ownership and lifecycle changes involving Session, Workspace, Conversation, and pending interactions are reported as `MIG_SEMANTIC_API_CHANGE`. The agent must handle them in the context of the plugin instead of applying a mechanical replacement.
-
-## Why versioned rules are needed
-
-DSH 0.1.2 changes more than package versions:
+DSH 0.1.2 changes more than package versions. Legacy owners such as `dsh-client-runtime` and `dsh-host-apiproxy` were split, while Session, Workspace, Conversation, pending interaction, and Settings capabilities moved to new controllers, UI packages, or Services. The CLI only auto-edits relationships marked `exact`; ownership, lifecycle, and business-call changes are reported as `MIG_SEMANTIC_API_CHANGE`.
 
-- `@deepseek-ai/dsh-client-runtime` was removed and has no single aggregate replacement;
-- store features moved to `dsh-client-store`;
-- Session, Workspace, Conversation, and pending interactions moved to separate controllers or UI packages;
-- `@deepseek-ai/dsh-host-apiproxy` was removed, so browser calls move to the appropriate business Remote;
-- client graph, platform externals, exports, and some profile patch targets also changed.
+With an exact Harness checkout, Doctor also verifies the commits behind the two catalog tags and compares entry ids in the target web profile. After the additional source interval has been investigated, `--target-version` can bind dependencies and runtime checks to a newer 0.1.2 target, but it does not extend the catalog's API claims.
 
-The migration catalog stores source/target tags and Git commits together with package, symbol, Service, and configuration rules. With `--harness-root`, the CLI verifies the commits behind both tags and compares entry ids in the target web profile. This gives the agent concrete version differences instead of making it guess the new API.
+## Core capabilities
 
-## Coverage
-
-| Area | How Doctor and the agent handle it |
+| Area | How it is handled |
 |---|---|
-| JS/TS imports, including type-only, aliased, and mixed imports | Analyzed with the TypeScript AST; symbols with a known equivalent can be rewritten |
-| Removed or added DSH packages | Checked in source and manifest; dependencies are updated only when no remaining reference blocks the change |
-| DSH/Cordis version ranges | Checks dependencies, devDependencies, and peerDependencies; existing peer ranges are not widened automatically |
-| Session, Workspace, Conversation, and other semantic changes | Reports the new owner and reason; the agent modifies the business code |
+| JS/TS imports and named re-exports | Uses the TypeScript AST for type-only, aliased, and mixed imports; rewrites only known equivalent symbols |
+| Removed packages and retained-package API changes | Checks source and manifest, preserves exports that still exist, and reports symbols that need semantic migration |
+| DSH/Cordis version ranges | Checks dependencies, devDependencies, peerDependencies, and resolved versions; existing peer ranges are not widened automatically |
 | `dsh.client` and client exports | Checks inject, external, platform, immediately, and `exports["./client"]` |
-| Harness patch targets | Compares old and new entries when an exact Harness checkout is available |
-| Build output | Scans `lib`, `dist`, `build`, and `out` for old APIs |
-| Plugin build | Runs existing typecheck, build, test, and pack:check scripts; build or pack:check is required for artifact verification |
+| Harness patch targets | Compares old and new bundle entries when an exact Harness checkout is available |
+| Build output | Scans `lib`, `dist`, `build`, and `out` for source/artifact drift |
+| Plugin build | Runs existing typecheck, build, test, and pack:check scripts; test/typecheck alone cannot establish artifact verification |
 | Installation and activation | Packs the real tarball and installs it into a fresh web profile under a temporary `DSH_HOME` |
-| UI and business behavior | Not decided by Doctor; the agent or developer runs plugin-specific checks |
+| Profile diagnosis | Composes bundle, profile, home, and CLI overlays in DSH order while preserving field provenance |
+| Update, quarantine, and removal | Verifies versions, dependencies, configuration layers, and dependents before producing an explicit operation plan; updates, persistent quarantine, and removal need explicit confirmation |
 
-Source analysis uses the TypeScript AST and is cross-checked against the manifest, client graph, and build output. A bundle without an old string does not prove that source code is compatible, and a successful compile does not prove that the published artifact or runtime is compatible.
+No legacy string in source, a successful compile, an installable tarball, and correct business behavior are different evidence levels. Doctor does not present one as proof of another.
 
-## Safety
+## Safety and evidence
 
 - `diagnose`, `migrate analyze`, and static verification are read-only and do not load or execute the inspected plugin;
-- `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 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.
-
-## Use the migration CLI manually
+- only migrations marked `exact` by the catalog can be changed automatically; semantic changes are not guessed mechanically;
+- `migrate apply` uses a reviewed plan outside the plugin root and binds the full analysis, actual target version, and every input-file hash;
+- SHA-256 is rechecked before writes, input drift rejects the apply, and existing files receive timestamped backups;
+- build/runtime commands require explicit confirmation and synchronize dependencies with lifecycle scripts disabled;
+- runtime verification uses a temporary `DSH_HOME` instead of installing into the developer's normal `~/.dsh`;
+- JSON, baselines, and recovery snapshots redact common secret, token, password, and key fields;
+- global CLI installation, persistent quarantine, plugin removal, commits, and publication are never implicit actions.
 
-Node.js `^22.19.0` or `>=24.0.0` is required.
+## Boundaries
 
-First confirm that the CLI contains the required migration:
+- Doctor can report a new API owner and migration reason, but it cannot replace understanding the plugin's business logic;
+- named imports and named re-exports from retained packages are recognized, while property access through namespace imports still needs manual investigation;
+- `runtime-verified` proves packaging, installation, and basic activation, not UI, Service lifecycle, or business-flow correctness;
+- DSH patches or prereleases outside the catalog require investigation of the additional source interval;
+- static diagnosis cannot establish dynamic Service dependencies or whether plugin-owned external data is safe to delete.
 
-```sh
-npm exec --yes --package=@bruc3van/dsh-doctor@<selected-version> -- \
-  dsh-doctor migrations list
-```
+## CLI quick reference
 
-### 1. Analyze
-
-```sh
-dsh-doctor migrate analyze /path/to/plugin \
-  --from dsh-v0.1.1-rc.2 \
-  --to dsh-v0.1.2-alpha.3 \
-  --harness-root /path/to/deepseek-harness \
-  --json
-```
-
-Analysis checks source, dependencies, manifest, client graph, patch targets, and existing build output without executing plugin code. `--from`/`--to` select the exact catalog that supplies API rules. Alpha.3 is the current default, so it needs no separate `--target-version`. If a newer 0.1.2 build is explicitly targeted before the catalog is updated, inspect the source delta from alpha.3 first, then use `--target-version` to control dependency ranges, safe-plan pins, and the runtime version check. The report keeps the catalog and actual targets separate.
-
-### 2. Apply
-
-```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
-```
-
-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 --install \
-  --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level runtime --yes --install \
-  --dsh-command /path/to/dsh --json
-```
-
-| Level | What it checks |
-|---|---|
-| `static` | Rechecks source, manifest, client graph, patches, and artifacts |
-| `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:
-
-```text
-analyzed → source-migrated → artifact-verified → runtime-verified
-```
-
-`runtime-verified` means that packing, installation, and basic activation passed. It does not replace real UI, Service lifecycle, and business-flow testing.
-
-## Diagnose DSH and installed plugins
-
-Global installation:
+Requires Node.js `^22.19.0` or `>=24.0.0`.
 
 ```sh
+# Global installation
 npm install --global @bruc3van/dsh-doctor
-dsh-doctor diagnose
-```
-
-Temporary use:
-
-```sh
-npx @bruc3van/dsh-doctor diagnose
-```
-
-The default target is `$DSH_HOME/profiles/web`, falling back to `~/.dsh`.
-
-```sh
-dsh-doctor diagnose
-dsh-doctor diagnose --json
-dsh-doctor diagnose --check-updates
-```
 
-Diagnosis composes configuration in DSH order:
-
-```text
-bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
+# Or run one pinned version without changing the global installation
+npm exec --yes --package=@bruc3van/dsh-doctor@<version> -- dsh-doctor --help
 ```
 
-It checks plugin versions and peers, Node engines, installation and lockfile state, bundles and patches, client contracts, duplicate mounts, higher-layer overrides, and DSH CLI/Harness version drift. Normal diagnosis does not use the network. Only `--check-updates` and recovery operations contact the npm registry.
-
-## Recovery operations
-
-```sh
-# Check and install the highest manifest-declared compatible version
-dsh-doctor recover @scope/plugin --action check-update
-dsh-doctor recover @scope/plugin --action update
-dsh-doctor recover @scope/plugin --action update --yes
-
-# Create a temporary quarantine overlay
-dsh-doctor recover @scope/plugin --action quarantine \
-  --output ./plugin-quarantine.yml
-
-# Persist it only after testing the temporary overlay
-dsh-doctor recover @scope/plugin --action persist-quarantine --verified
-dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
-
-# Removal is always separate
-dsh-doctor recover @scope/plugin --action remove
-dsh-doctor recover @scope/plugin --action remove --yes
-```
-
-Before quarantine or removal, Doctor checks entry ownership, configuration layers, direct dependencies, core bundles, lockfile state, manual mounts, and known client dependents. Static checks cannot prove dynamic Service dependencies or external data safety, so restart the profile and test its main features afterwards.
-
-You can also save and compare a baseline around an upgrade:
+| Command | Purpose |
+|---|---|
+| `dsh-doctor diagnose [--json] [--check-updates]` | Diagnose the current profile and installed plugins; normal diagnosis does not use the network |
+| `dsh-doctor migrations list` | List the exact migration catalogs bundled with the current CLI |
+| `dsh-doctor migrate analyze` / `apply` / `verify` | Analyze a migration, apply a reviewed plan, or run static/build/runtime verification |
+| `dsh-doctor baseline create` / `compare` | Save or compare a redacted before/after diagnostic baseline |
+| `dsh-doctor recover <package> --action <action>` | Check updates, generate/persist/roll back quarantine, or enter the separate removal workflow |
 
-```sh
-dsh-doctor baseline create
-dsh-doctor baseline compare
-```
+Use `dsh-doctor --help` for full options and confirmation requirements. Migration orchestration and semantic-investigation rules live in [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) and its references.
 
 ## Output and exit codes
 
-Text output supports Chinese and English. `--json` uses stable English codes and keeps redacted structured evidence.
+Text output supports Chinese and English. `--json` uses stable English codes and preserves redacted structured evidence.
 
 | Exit code | Meaning |
 |---|---|
-| `0` | No blocker remains, or the action completed and passed its verification |
-| `1` | Compatibility issues, semantic migration, or verification work remains |
-| `2` | Argument, environment, or action-execution failure |
+| `0` | No blocking error, or the operation completed and passed its verification level |
+| `1` | Compatibility issues, semantic migration work, or incomplete verification remains |
+| `2` | Argument, environment, or operation failure |
 
 ## Development
 
@@ -251,6 +147,6 @@ npm run check
 npm pack --dry-run
 ```
 
-Tests cover the CLI, configuration composition, diagnosis, redaction, backups and write protection, AST migration, build gates, isolated runtime verification, and recovery operations. CI tests Node.js `22.19` and `24` on macOS, Ubuntu, and Windows.
+Tests cover the CLI, configuration composition, diagnosis, redaction, backups and write protection, AST migration, build gates, isolated runtime verification, and recovery. CI runs on macOS, Ubuntu, and Windows with Node.js `22.19` and `24`.
 
 Local development, the skill, and the CLI never commit, tag, or publish automatically.

package/README.md

@@ -2,19 +2,24 @@
 
 中文 | [English](README.en.md)
 
-DSH Doctor 帮助 Agent 诊断和升级 DeepSeek Harness 插件：识别新旧版本之间的 API 变化，修改可以确定迁移的代码，提示需要开发者判断的语义变化，重新构建并验证插件。
+DSH Doctor 是给 DSH 插件开发者和 Agent 使用的升级、排障工具。它能找出插件升级时需要修改的地方，自动处理可以确定的改动，并继续检查依赖、构建产物和实际安装运行情况。
 
-当前主要面向：
+遇到需要理解业务逻辑的改动，它会明确列出来交给 Agent 或开发者处理，不会直接猜。所有修改都会先生成预览并保留备份，运行验证也会放在临时 DSH 环境中，不影响日常使用的 profile。
 
-```text
-DSH 0.1.1 → DSH 0.1.2
-```
+> 这是社区维护的第三方工具，不属于 DeepSeek 官方项目。当前迁移范围是 DSH 0.1.1 → 0.1.2；catalog 精确覆盖 `dsh-v0.1.1-rc.2` → `dsh-v0.1.2-alpha.3`，并保留 alpha.2 历史规则。未收录的版本差异仍需单独调查，不能视为 catalog 已证明兼容。
 
-项目同时提供 DSH profile 和插件的诊断、兼容版本检查、隔离与删除前检查。
+## 它能解决什么问题
+
+| 场景 | DSH Doctor 提供的能力 |
+|---|---|
+| 升级插件 | 扫描源码、依赖、manifest、client graph、patch 和构建产物；自动处理 catalog 确认的精确迁移，并把语义变化交给 Agent |
+| 验证迁移结果 | 依次完成静态复核、依赖同步、构建/测试、真实 tarball 打包，以及临时 profile 安装与激活验证 |
+| 诊断 DSH 环境 | 检查 profile 配置层、插件版本与 peer、lockfile、bundle、patch、client contract、重复 mount 和 DSH CLI/Harness 版本漂移 |
+| 安全恢复 | 比较升级前后 baseline，检查兼容更新，生成和验证隔离 overlay，并在删除前给出依赖与配置影响证据 |
 
-> 这是社区维护的第三方工具，不属于 DeepSeek 官方项目。工具的迁移范围保持为 DSH 0.1.1 → 0.1.2；当前已知最新版 catalog 精确覆盖 `dsh-v0.1.1-rc.2` 到 `dsh-v0.1.2-alpha.3`。旧 alpha.2 catalog 作为历史规则保留；出现更新的 0.1.2 预发布版本时，需要先核对增量，再明确更新 catalog 和 Skill。
+这些能力既可以由 Agent 通过 Skill 编排，也可以作为结构化 CLI 能力集成到其他工具中。
 
-## 使用 Skill 升级插件
+## 推荐方式：让 Agent 使用 Skill
 
 安装仓库中的 [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) Skill：
 
@@ -29,213 +34,104 @@ npx skills add bruc3van/dsh-doctor
 先分析兼容问题，再修改代码，最后完成构建和运行时验证。
 ```
 
-升级请求本身不代表可以放弃旧版。若开发者没有说明，Skill 会在任何迁移写入、依赖安装、构建或运行时命令前，显式询问升级后的同一插件版本是否还要兼容 DSH 0.1.1。选择保留兼容时，Agent 会先设计双版本适配方式，并分别验证 0.1.1 和 0.1.2；不能用一次 0.1.2 验证代替双版本结论。
+Skill 会引导 Agent：
 
-Skill 会提醒 Agent 按下面的顺序工作：
+1. 核实插件、实际 DSH、Harness checkout、包管理器和可用的 DSH Doctor；
+2. 分析源码、依赖、配置、patch 和已有产物；
+3. 确认升级后的同一插件版本是仅支持 0.1.2，还是继续兼容 0.1.1；
+4. 预览并应用符合兼容策略的精确修改，再处理需要理解业务的语义迁移；
+5. 重新构建，并分别报告静态、产物、隔离运行时和业务行为证据；
+6. 仅在开发者明确要求后，按插件仓库自己的流程提交和发布。
 
-1. 检查插件目录、Harness checkout、包管理器和可用的 DSH Doctor；
-2. 分析源码、类型导入、依赖、manifest、client graph、patch 和构建产物；
-3. 确认升级后是仅支持 0.1.2，还是同一版本继续兼容 0.1.1；
-4. 预览并应用可以确定等价、且符合所选兼容策略的代码修改；
-5. 根据新的 API 所有者处理需要理解业务的语义迁移；
-6. 重新构建插件，并依次做静态、构建和隔离运行时验证；双版本模式分别验证两端；
-7. 报告兼容目标、修改内容、剩余问题、备份和实际达到的验证等级。
+`npx skills add` 只安装 Agent 指令，不会全局安装 DSH Doctor。Skill 会先检查本地 CLI 和 npm registry；本地版本不合适时，默认通过固定版本的 `npm exec` 运行，不会自行修改全局安装。
 
-`npx skills add` 只安装 Agent 指令，不会安装全局 DSH Doctor。Skill 会先检查本地 CLI 和 npm registry；本地版本不合适时，默认使用固定版本的 `npx`，不会自行修改全局 npm 安装。
+升级请求本身不代表可以放弃旧版。兼容目标未明确时，Skill 可以先做只读分析，但会在迁移写入、依赖安装、构建或运行时命令前要求确认。双版本模式必须分别验证 0.1.1 和 0.1.2，不能用一次 0.1.2 smoke 代替双版本结论。
 
-验证完成后，可以再让 Agent 按插件仓库原有的版本和发布流程提交、打 tag、发布。Skill 本身不会自动提交或发布。
+## 工作原理
 
-## 工作方式
+DSH Doctor 由三个相互约束的部分组成：
 
-DSH Doctor 由三部分组成：
+- **Skill**：为 Agent 定义调查步骤、兼容决策、确认门和报告标准；
+- **CLI**：提供只读分析、安全修改、诊断、基线、恢复和分级验证能力；
+- **Migration catalog**：保存精确 DSH tag/commit 以及已确认的 package、symbol、Service、配置和行为变化。
 
-- **Skill**：告诉 Agent 升级步骤、哪些操作需要确认，以及最后应该报告什么；
-- **CLI**：扫描插件、生成问题清单、修改确定性代码，并执行分级验证；
-- **Migration catalog**：记录两个 DSH 版本之间已确认的包、API、Service、配置和行为变化。
-
-完整流程是：
+插件迁移流程是：
 
 ```text
-分析问题
-  → 修改确定性代码
+调查实际环境
+  → catalog 驱动分析
+  → reviewed plan 精确修改
   → Agent 处理语义变化
-  → 重新构建
-  → 静态验证
-  → 临时 profile 安装与激活验证
-  → 按插件自己的流程发布
+  → 构建与产物验证
+  → 临时 profile 安装和激活
+  → 插件业务行为验证
 ```
 
-CLI 只自动修改 catalog 标记为 `exact` 的迁移。Session、Workspace、Conversation、pending interaction 等所有权和生命周期变化会标记为 `MIG_SEMANTIC_API_CHANGE`，由 Agent 结合插件代码处理，不会机械替换。
-
-## 为什么需要版本化规则
-
-DSH 0.1.2 不只是包版本变化，一些能力被拆分到了新的所有者：
+DSH 0.1.2 不只是包版本变化。`dsh-client-runtime` 和 `dsh-host-apiproxy` 等旧 owner 被拆分，Session、Workspace、Conversation、pending interaction、Settings 等能力迁移到新的 controller、UI 包或 Service。CLI 只自动修改 catalog 标记为 `exact` 的关系；所有权、生命周期和业务调用变化会作为 `MIG_SEMANTIC_API_CHANGE` 报告。
 
-- `@deepseek-ai/dsh-client-runtime` 已移除，没有一个新的聚合包可以直接替换；
-- store 能力迁移到 `dsh-client-store`；
-- Session、Workspace、Conversation 和 pending interaction 分别由新的 controller 或 UI 包负责；
-- `@deepseek-ai/dsh-host-apiproxy` 已移除，浏览器调用需要迁移到对应业务 Remote；
-- client graph、platform external、exports 和部分 profile patch target 也发生了变化。
+如果提供精确 Harness checkout，Doctor 还会确认 catalog 中两个 tag 的 commit，并比较目标 web profile 的 entry id。`--target-version` 可以在完成额外源码调查后绑定更新的 0.1.2 依赖与 runtime 目标，但不会扩大 catalog 的 API 结论。
 
-Migration catalog 保存 source/target tag 和 Git commit，并记录 package、symbol、Service 和配置规则。提供 `--harness-root` 时，CLI 还会确认两个 tag 对应的 commit，并比较目标 web profile 中的 entry id。这样 Agent 可以基于明确的版本差异修改代码，而不是猜测新 API。
+## 核心能力
 
-## 覆盖范围
-
-| 检查内容 | Doctor/Agent 如何处理 |
+| 检查内容 | 处理方式 |
 |---|---|
-| JS/TS import，包括 `import type`、别名和混合 import | 使用 TypeScript AST 分析；确定等价的 symbol 可自动改写 |
-| 移除或新增的 DSH 包 | 检查源码和 manifest；没有残留引用时更新依赖 |
-| DSH/Cordis 版本范围 | 检查 dependencies、devDependencies 和 peerDependencies；不自动扩大已有 peer 范围 |
-| Session、Workspace、Conversation 等语义变化 | 报告新 owner 和变化原因，由 Agent 修改业务代码 |
-| `dsh.client` 和 client export | 检查 inject、external、platform、immediately 和 `exports["./client"]` |
-| Harness patch target | 有精确 Harness checkout 时比较新旧 entry |
-| 构建产物 | 检查 `lib`、`dist`、`build`、`out` 中是否仍包含旧 API |
-| 插件构建 | 运行项目已有的 typecheck、build、test、pack:check；必须有 build 或 pack:check 才算产物已验证 |
-| 安装和激活 | 打包真实 tarball，安装到临时 `DSH_HOME` 的新 web profile 中验证 |
-| UI 和业务行为 | Doctor 不自动判断；需要 Agent 或开发者执行插件自己的测试 |
+| JS/TS import 与 named re-export | 使用 TypeScript AST 分析 type-only、别名和混合 import；仅改写已知等价 symbol |
+| 移除或保留包中的 API 变化 | 检查源码和 manifest；保留仍存在的导出，并报告需要语义迁移的 symbol |
+| DSH/Cordis 版本范围 | 检查 dependencies、devDependencies、peerDependencies 和实际解析版本；不自动扩大已有 peer 范围 |
+| `dsh.client` 与 client export | 检查 inject、external、platform、immediately 和 `exports["./client"]` |
+| Harness patch target | 在精确 Harness checkout 下比较新旧 bundle entry |
+| 构建产物 | 扫描 `lib`、`dist`、`build`、`out`，识别源码与发布产物漂移 |
+| 插件构建 | 运行已有 typecheck、build、test、pack:check；只有 test/typecheck 不足以证明产物已验证 |
+| 安装和激活 | 打包真实 tarball，在临时 `DSH_HOME` 的新 web profile 中安装并检查生效配置 |
+| Profile 诊断 | 按 DSH 顺序组合 bundle、profile、home 和 CLI overlay，保留字段来源证据 |
+| 更新、隔离与删除 | 先验证版本、依赖、配置层和 dependents，再生成显式操作计划；更新、持久化隔离和删除需要明确确认 |
 
-源码分析使用 TypeScript AST，并同时检查 manifest、client graph 和构建产物。因此，bundle 中没有旧字符串并不代表源码已经兼容，源码编译通过也不代表发布产物和运行时已经兼容。
+源码没有旧字符串、编译成功、tarball 可安装和业务行为正常是不同证据等级，Doctor 不会把其中一个冒充另一个。
 
-## 安全性
+## 安全与证据
 
 - `diagnose`、`migrate analyze` 和静态验证只读，不加载或执行待检查插件；
-- `migrate apply` 必须带 `--safe --plan-file`；预览只会新建插件目录外的 plan，不会覆盖已有文件，并把完整分析和所有输入文件哈希固化下来；`--yes` 只应用同一个已审阅 plan；
-- 只有 `exact` 迁移会自动改代码，语义变化不会自动猜测；
-- 写入前检查文件 SHA-256，预览后文件发生变化会拒绝写入；
-- 修改已有文件前创建时间戳备份，并使用临时文件原子替换；
-- build 和 runtime 会同步依赖并执行插件脚本，因此必须显式使用 `--yes --install`；依赖安装禁用 lifecycle scripts，并记录 lockfile 和实际解析版本证据；
-- runtime 使用临时 `DSH_HOME`，不会安装到正常的 `~/.dsh`；
-- JSON、baseline 和恢复快照会脱敏插件配置和常见 secret/token/password/key 字段；
-- 全局 CLI 安装、持久隔离、删除插件和发布都不会由 Skill 自动执行。
-
-## 手动使用迁移 CLI
-
-需要 Node.js `^22.19.0` 或 `>=24.0.0`。
-
-先确认 CLI 包含需要的迁移：
-
-```sh
-npm exec --yes --package=@bruc3van/dsh-doctor@<selected-version> -- \
-  dsh-doctor migrations list
-```
-
-### 1. 分析
-
-```sh
-dsh-doctor migrate analyze /path/to/plugin \
-  --from dsh-v0.1.1-rc.2 \
-  --to dsh-v0.1.2-alpha.3 \
-  --harness-root /path/to/deepseek-harness \
-  --json
-```
-
-分析会检查源码、依赖、manifest、client graph、patch target 和已有构建产物，不执行插件代码。`--from`/`--to` 选择提供 API 规则的精确 catalog。当前默认目标就是 alpha.3，无需额外指定 `--target-version`；如果在 catalog 更新前明确迁移到更新的 0.1.2 版本，必须先调查 alpha.3 到该版本的源码差异，再用 `--target-version` 单独控制依赖范围、safe plan pin 和 runtime 版本核验。报告会保留 catalog 与实际目标两个值。
-
-### 2. 修改
+- 只有 catalog 标记为 `exact` 的迁移可以自动修改，语义变化不会机械猜测；
+- `migrate apply` 使用插件目录外的 reviewed plan，绑定完整分析、实际目标版本和所有输入文件哈希；
+- 写入前复核 SHA-256，输入漂移时拒绝应用，并为已有文件创建时间戳备份；
+- build/runtime 必须显式确认，并在禁用 lifecycle scripts 的情况下同步和核验依赖；
+- runtime 使用临时 `DSH_HOME`，不会把待验证插件安装到正常的 `~/.dsh`；
+- JSON、baseline 和恢复快照会脱敏常见 secret、token、password 和 key 字段；
+- 全局 CLI 安装、持久隔离、插件删除、提交和发布都不是隐式动作。
 
-```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
-```
+## 能力边界
 
-Plan 必须放在插件目录外，避免被当成插件输入。Apply 会核对 plan digest、完整分析输入和每个修改的 before/after hash；源码、manifest 或其他分析输入在预览后变化时必须重新生成并审阅 plan。确定性依赖改写使用 catalog 明确的 Client/Host 与 peer/dev 策略，不再沿用旧包所在的 dependency section。每个被修改的文件都会保留备份。
+- Doctor 可以指出新 API owner 和迁移原因，但不能替代对插件业务逻辑的理解；
+- 保留包中的 named import 和 named re-export 可以被识别，namespace import 的属性访问仍需人工调查；
+- `runtime-verified` 只证明打包、安装和基本激活，不能证明 UI、Service 生命周期和业务流程正确；
+- catalog 之外的 DSH patch 或 prerelease 必须检查额外源码差异；
+- 静态诊断无法确认动态 Service 依赖和插件外部数据是否可安全删除。
 
-### 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 --install \
-  --harness-root /path/to/deepseek-harness --json
-dsh-doctor migrate verify /path/to/plugin --level runtime --yes --install \
-  --dsh-command /path/to/dsh --json
-```
-
-| 级别 | 验证内容 |
-|---|---|
-| `static` | 再次检查源码、manifest、client graph、patch 和产物 |
-| `build` | 先同步并核验目标依赖和 lockfile，再运行已有构建/测试脚本并重新扫描产物 |
-| `runtime` | 完成依赖与构建门后，打真实 tarball，在临时 profile 中验证目标 DSH、安装包、bundle 和生效配置 |
+## CLI 快速参考
 
-验证状态依次是：
-
-```text
-analyzed → source-migrated → artifact-verified → runtime-verified
-```
-
-`runtime-verified` 只表示插件能够完成打包、安装和基本激活，仍不能代替真实 UI、Service 生命周期和业务流程验证。
-
-## DSH 和已安装插件诊断
-
-全局安装：
+需要 Node.js `^22.19.0` 或 `>=24.0.0`。
 
 ```sh
+# 全局安装
 npm install --global @bruc3van/dsh-doctor
-dsh-doctor diagnose
-```
-
-临时运行：
 
-```sh
-npx @bruc3van/dsh-doctor diagnose
-```
-
-默认检查 `$DSH_HOME/profiles/web`；未设置 `DSH_HOME` 时使用 `~/.dsh`。
-
-```sh
-dsh-doctor diagnose
-dsh-doctor diagnose --json
-dsh-doctor diagnose --check-updates
+# 或运行一个固定版本，不修改全局安装
+npm exec --yes --package=@bruc3van/dsh-doctor@<version> -- dsh-doctor --help
 ```
 
-诊断按 DSH 的顺序组合配置：
-
-```text
-bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
-```
-
-它会检查插件版本和 peer、Node engines、安装与 lockfile、bundle 与 patch、client contract、重复 mount、高层配置覆盖，以及 DSH CLI/Harness 版本漂移。普通诊断不访问网络；只有 `--check-updates` 和 recovery 操作会访问 npm registry。
-
-## 恢复操作
-
-```sh
-# 检查和安装 manifest 声明兼容的最高版本
-dsh-doctor recover @scope/plugin --action check-update
-dsh-doctor recover @scope/plugin --action update
-dsh-doctor recover @scope/plugin --action update --yes
-
-# 生成临时隔离 overlay
-dsh-doctor recover @scope/plugin --action quarantine \
-  --output ./plugin-quarantine.yml
-
-# 验证临时 overlay 后持久化
-dsh-doctor recover @scope/plugin --action persist-quarantine --verified
-dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
-
-# 删除始终需要单独执行
-dsh-doctor recover @scope/plugin --action remove
-dsh-doctor recover @scope/plugin --action remove --yes
-```
-
-Doctor 会在隔离和删除前检查 entry、配置层、直接依赖、核心 bundle、lockfile、手工 mount 和已知 client dependents。静态检查无法确认动态 Service 依赖和外部数据，操作后仍需重启 profile 并验证主要功能。
-
-升级前后也可以保存和比较基线：
+| 命令 | 用途 |
+|---|---|
+| `dsh-doctor diagnose [--json] [--check-updates]` | 诊断当前 profile 和已安装插件；普通诊断不访问网络 |
+| `dsh-doctor migrations list` | 查看当前 CLI 内置的精确 migration catalog |
+| `dsh-doctor migrate analyze` / `apply` / `verify` | 分析迁移、应用 reviewed plan、执行静态/构建/runtime 验证 |
+| `dsh-doctor baseline create` / `compare` | 保存或比较升级前后的脱敏诊断基线 |
+| `dsh-doctor recover <package> --action <action>` | 检查更新、生成/持久化/回滚隔离或执行独立删除流程 |
 
-```sh
-dsh-doctor baseline create
-dsh-doctor baseline compare
-```
+完整参数和确认要求请使用 `dsh-doctor --help`。迁移编排与语义调查规则位于 [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) 及其 references 中。
 
 ## 输出与退出码
 
-文本支持中文和英文，`--json` 使用稳定英文 code 并保留脱敏后的结构化证据。
+文本支持中文和英文；`--json` 使用稳定英文 code，并保留脱敏后的结构化证据。
 
 | 退出码 | 含义 |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "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,13 +1,22 @@
 ---
 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, 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 known target reference is dsh-v0.1.2-alpha.3.
+description: Help migrate a DeepSeek Harness (DSH) plugin from DSH 0.1.1 to 0.1.2 with the dsh-doctor CLI, deciding explicitly up front whether the upgraded release must stay compatible with DSH 0.1.1. Use when a plugin developer plans a migration or compatibility assessment: checking what changed between DSH versions, replacing imports of packages 0.1.2 removed (such as dsh-client-runtime or dsh-host-apiproxy), migrating settingsNamespace to the settings Service, updating DSH dependency ranges, or verifying and preparing a plugin release for 0.1.2. Applies only catalog-confirmed exact rewrites automatically and guides the semantic changes that need developer judgment. Not for debugging a plugin that already targets 0.1.2, general DSH usage or configuration questions, or developing the Harness itself.
 ---
 
 # Upgrade a DSH 0.1.1 plugin to 0.1.2
 
 Help the developer diagnose and modify one plugin at a time. Treat source migration, artifact verification, runtime activation, and business behavior as separate gates.
 
-The migration knowledge covers the DSH 0.1.1 to 0.1.2 transition. The current known catalog records `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.3` as the exact reference points used to derive and verify known changes. Keep the skill's product scope at the release-line level (`0.1.1` to `0.1.2`), while keeping the catalog target exact. First record the plugin's actual DSH ranges and requested target. When a newer patch or prerelease appears, use the catalog for known changes only, inspect the additional interval, and report that it is not catalog-confirmed until the catalog and this skill are deliberately updated. Do not claim that the catalog proves an unlisted version combination.
+The migration knowledge covers the DSH 0.1.1 to 0.1.2 transition, derived and verified from one exact catalog version pair (declared below). Keep the skill's product scope at the release-line level (`0.1.1` to `0.1.2`), while keeping the catalog target exact. First record the plugin's actual DSH ranges and requested target. When a newer patch or prerelease appears, use the catalog for known changes only, inspect the additional interval, and report that it is not catalog-confirmed until the catalog and this skill are deliberately updated — a pass for the catalog pair never proves an unlisted version combination.
+
+## Current catalog version pair
+
+This block is the single source of truth for the exact refs. Every command below and every reference file defers to it; the references avoid repeating the literals on purpose. When the catalog advances, update this block, the `migrate analyze` example, and the shipped catalog together.
+
+- source ref: `dsh-v0.1.1-rc.2`
+- target ref: `dsh-v0.1.2-alpha.3`
+
+Standard commands target this pair and need no `--target-version`. If the developer explicitly targets a newer 0.1.2 build before the catalog is updated, inspect that additional interval first (see [source-investigation.md](references/source-investigation.md)), then pass its exact version to every migration phase as `--target-version <actual-0.1.2-version>`. That changes dependency pins and runtime expectations only; the catalog's API claims still end at the declared pair.
 
 ## Inputs
 
@@ -21,32 +30,24 @@ Determine:
 - whether the developer authorizes a global CLI install or update;
 - the plugin's package manager and build scripts.
 
-Use these catalog reference points in the current CLI commands:
-
-- source: `dsh-v0.1.1-rc.2`
-- target: `dsh-v0.1.2-alpha.3`
-
-The standard commands target the current known alpha.3 catalog and do not need `--target-version`. If the developer explicitly targets a newer 0.1.2 build before the catalog is updated, inspect the interval first, then pass its exact version to every migration phase as `--target-version <actual-0.1.2-version>`. This changes dependency pins and runtime expectations only; it does not extend the catalog's API claims.
-
 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 the exact-version `npm exec` fallback over changing the developer's global installation. Never globally install or update the CLI without explicit authorization.
+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 the exact-version `npm exec` fallback over changing the developer's global installation; a global install or update always needs explicit authorization.
 
-The examples below use `dsh-doctor` for readability. When bootstrap selected a package-runner invocation, substitute the complete pinned prefix, `npm exec --yes --package=@bruc3van/dsh-doctor@<selected-version> -- dsh-doctor`, in every phase.
+The examples below use `dsh-doctor` for readability. When bootstrap selected a package-runner invocation, substitute the complete pinned prefix, `npm exec --yes --package=@bruc3van/dsh-doctor@<selected-version> -- dsh-doctor`, in every phase. Command examples use POSIX shell syntax (bash, zsh, Git Bash); in PowerShell or cmd, join lines continued with `\` into a single line before running them.
 
 ## 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.
+An upgrade request does not say whether the developer accepts dropping DSH 0.1.1, and write authorization does not answer that product decision. The current peer range, the word "upgrade," and the fact that a 0.1.2-only rewrite is simpler are all weak evidence — only the developer's explicit choice settles it.
 
-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:
+You may inspect files, bootstrap the CLI, and run read-only analysis first. Before any `migrate apply` preview, source or manifest edit, dependency install, build, or runtime command, the compatibility intent must come from one of:
 
-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?"**
+1. an explicit choice already present in the developer's request; or
+2. the developer's own reply to: **"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):
+No other resolution counts. Do not simulate, assume, or fabricate a reply the developer did not give — a question the developer has not genuinely answered means the gate is still pending. The plugin may be migrated only after the developer has actually made the choice.
 
-- **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.
+If the answer is unavailable or ambiguous, stop at `analyzed`, report the compatibility decision as pending, and leave the plugin unmodified. Follow the selected path in [compatibility-strategy.md](references/compatibility-strategy.md): it defines the three intents (`0.1.2-only`, `dual-version`, `pending developer decision`) and the write policy for each. In particular, `dual-version` treats every 0.1.2 catalog rewrite as a candidate needing cross-version design and review before any write, never an automatically compatible change.
 
 ## Phase 1: analyze
 
@@ -59,11 +60,11 @@ dsh-doctor migrate analyze <plugin-root> \
   --json
 ```
 
-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.
+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 — report it 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.
+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 pair declared above, inspect that additional 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 the plugin's callers — naming a likely new owner is not enough to plan the rewrite.
 
-The catalog reports the retained-package removal of `@deepseek-ai/dsh-settings.settingsNamespace` as semantic work. Remove only that named import, inject the `settings` Service, register through `ctx.settings.register(name, schema)`, and migrate any reads to the provider's current API. Do not remove still-exported symbols such as `SettingsConflictError` merely because they share the same import declaration.
+The catalog reports the retained-package removal of `@deepseek-ai/dsh-settings.settingsNamespace` as semantic work. Remove only that named import, inject the `settings` Service, register through `ctx.settings.register(name, schema)`, and migrate any reads to the provider's current API. Symbols 0.1.2 still exports (such as `SettingsConflictError`) must survive the edit even though they share the same import declaration.
 
 The static analyzer recognizes named imports and re-exports for retained-package symbol removals, but it does not resolve property access through namespace imports such as `import * as settings from '@deepseek-ai/dsh-settings'`. Search for and inspect those namespace bindings manually before declaring the semantic migration complete.
 
@@ -75,11 +76,11 @@ Group the result by:
 4. stale build artifacts;
 5. required verification gates.
 
-Do not infer compatibility from a clean bundled artifact alone. The analyzer intentionally scans TypeScript type imports, source files, package metadata, client graph declarations, and built output.
+A clean bundled artifact alone does not establish compatibility, which is why the analyzer deliberately scans TypeScript type imports, source files, package metadata, client graph declarations, and built output.
 
 ## 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.
+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`: a catalog-safe codemod proves nothing about 0.1.1.
 
 Preview first:
 
@@ -101,6 +102,16 @@ The CLI binds the apply to the persisted report and edit hashes, creates timesta
 
 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.
 
+### If apply fails partway or you want to undo it
+
+Every file `migrate apply` overwrites is first copied to `<file>.dsh-doctor-<timestamp>.bak` next to the original; the apply output's `writes[]` records each file's `backup`, `beforeHash`, and `afterHash`. There is no `migrate rollback` subcommand — recover manually:
+
+1. Restore each modified file from its `.bak` for the apply run being undone (`cp <file>.dsh-doctor-<timestamp>.bak <file>`, or `Copy-Item -Force` in PowerShell), taking the backups of that exact run when several exist.
+2. Delete files apply created: they are the `writes[]` entries without a `backup` field.
+3. Re-run `migrate analyze` and compare with the pre-apply report to confirm the plugin is back to its prior state before continuing.
+
+Later analysis runs ignore leftover `.dsh-doctor-*` files, so backups can stay in place until the rollback is confirmed, then be deleted.
+
 ## Phase 3: verify
 
 Run the gates in order:
@@ -123,10 +134,22 @@ For a dual-version result, verify the produced release against both the actual 0
 
 ## 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.
+Verification prepares the plugin for release but does not publish it. Release only when the developer explicitly asks: 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 — the migration skill being installed or run is not, by itself, release authorization.
 
 For a `0.1.2-only` release, update the README or compatibility documentation to state the minimum actual 0.1.2 version, that the new release does not support 0.1.1, and which prior plugin release 0.1.1 users should retain when known. After changing the release version or any other packed metadata, rebuild, inspect the final-version tarball, and repeat the isolated runtime gate against that artifact before committing or tagging; evidence from a tarball carrying the previous plugin version is not final release evidence.
 
+## Pass criteria before reporting
+
+Call the migration complete only when every item holds:
+
+- compatibility intent recorded as `0.1.2-only` or `dual-version` (not pending);
+- every semantic finding resolved and reviewed, including namespace-import usages;
+- static verification passes with no blocking finding;
+- build and packed artifacts pass (`build` or `pack:check`, not `typecheck`/`test` alone);
+- runtime smoke passed against the exact target version in the isolated profile;
+- behavior checks executed with named evidence, or explicitly listed as remaining;
+- for `dual-version`: every required matrix row passed on both the 0.1.1 and 0.1.2 sides.
+
 ## Report the outcome
 
 State the highest achieved gate exactly:

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

@@ -0,0 +1,55 @@
+{
+  "skill_name": "dsh-plugin-upgrade",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I maintain a DSH plugin (repo at <PLUGIN_ROOT>). DSH 0.1.2 dropped @deepseek-ai/dsh-client-runtime and my plugin imports it in src/. The next release only needs to support 0.1.2 - nobody on my team still runs 0.1.1, so it's fine to drop it. Work out what has to change and do the source migration. You can run commands in the plugin folder, but don't publish anything.",
+      "expected_output": "The agent records the 0.1.2-only intent from the request itself, bootstraps dsh-doctor, analyzes with the exact catalog refs, applies only the catalog-confirmed exact import moves to their new owners, and reports remaining verification gates without publishing or claiming release readiness.",
+      "files": ["evals/files/import-move-plugin"],
+      "expectations": [
+        "Records the compatibility intent as 0.1.2-only, treating the developer's own statement in the prompt as the explicit decision instead of re-asking or blocking",
+        "Maps the removed dsh-client-runtime symbols to their real 0.1.2 owners (createSnapshotStore/defineStore/shallowEqual/SnapshotStore to @deepseek-ai/dsh-client-store, ClientContext to @deepseek-ai/cordis Context) and never proposes an aggregate replacement package for dsh-client-runtime",
+        "Uses or constructs the dsh-doctor CLI flow (migrate analyze, then preview/apply via a plan file) with the catalog refs dsh-v0.1.1-rc.2 and dsh-v0.1.2-alpha.3, or clearly reports why the CLI could not run and proceeds from catalog knowledge with that limitation stated",
+        "Keeps the migration plan file outside the plugin root",
+        "Does not commit, tag, publish, or declare the plugin release-ready; reports the highest achieved gate and remaining verification steps"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "My plugin at <PLUGIN_ROOT> needs to move to DSH 0.1.2 (0.1.2-only, we're dropping 0.1.1 in this release). The tricky part: I use settingsNamespace from @deepseek-ai/dsh-settings in src/settings.ts and I heard it was removed. I also import SettingsConflictError in the same statement, and src/namespace-read.ts uses the settings module through `import * as settings`. Tell me what happens to these and make the changes.",
+      "expected_output": "The agent treats settingsNamespace removal as a semantic Service migration (inject the settings Service, register via ctx.settings.register), keeps SettingsConflictError, flags the namespace import for manual inspection, and rewrites reads against the provider's current API.",
+      "files": ["evals/files/settings-plugin"],
+      "expectations": [
+        "Treats the settingsNamespace removal as semantic work requiring a Service migration (inject the settings Service and register through ctx.settings.register(name, schema)), not as an automatic import move",
+        "Keeps SettingsConflictError (still exported in 0.1.2) instead of removing it together with settingsNamespace",
+        "Explicitly flags the `import * as settings` namespace usage in src/namespace-read.ts as something the static analyzer cannot resolve and inspects it manually",
+        "Migrates namespace reads (e.g. namespace.get) to the settings provider's current API (e.g. describe/get on the provider) instead of assuming the old factory object's methods still exist"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "My plugin at <PLUGIN_ROOT> still imports from @deepseek-ai/dsh-client-runtime/client. DSH 0.1.2 removed that package. Here's the constraint: my users are split between DSH 0.1.1 and 0.1.2 and I want ONE release that works on both - I don't want to maintain two plugin versions. Figure out how to handle this and start the work. Full write access granted.",
+      "expected_output": "The agent records the dual-version intent, treats every 0.1.2 catalog rewrite as a candidate needing cross-version review, proposes an evidence-grounded same-release mechanism, and defines the two-version verification matrix instead of applying the 0.1.2 codemod as automatically safe.",
+      "files": ["evals/files/import-move-plugin"],
+      "expectations": [
+        "Records the compatibility intent as dual-version (one release supporting both 0.1.1 and 0.1.2) from the prompt",
+        "Does not apply or recommend applying the 0.1.2 catalog codemod as automatically safe for 0.1.1; treats each rewrite as a candidate for cross-version review first",
+        "Proposes a concrete same-release compatibility mechanism grounded in plugin evidence (e.g. shared adapter with runtime feature detection or conditional version-specific entry/build) rather than guessing at dynamic loading",
+        "Defines a two-version verification matrix with evidence kept separate for 0.1.1 and 0.1.2 (dependency/peer resolution, build and packed artifact, isolated profile activation smoke, plugin behavior)",
+        "Never claims dual-version compatibility from 0.1.2-only evidence; states what remains unproven"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Migrate the plugin at <PLUGIN_ROOT> to DSH 0.1.2. You have full permission to change whatever is needed - just do it end to end and tell me when it's done.",
+      "expected_output": "The agent notices the request never says whether 0.1.1 support may be dropped, asks the explicit compatibility question, and then either proceeds only on a genuine developer reply or records the decision as pending and stays read-only until a genuine decision is made.",
+      "files": ["evals/files/import-move-plugin"],
+      "expectations": [
+        "Asks the explicit compatibility question (should the same upgraded release continue to support DSH 0.1.1, or may it target 0.1.2 only) or otherwise records the compatibility decision as pending developer decision",
+        "Distinguishes a genuine developer reply from a self-assumed one: only a real answer delivered by the developer (e.g. an answered question the harness returns) resolves the gate and lets the migration proceed; when no genuine answer is delivered, the agent must NOT assume, simulate, or fabricate a decision and must NOT treat the decision as resolved",
+        "Makes no source edits, dependency installs, builds, or migrate apply writes while the decision is pending; read-only analysis is acceptable",
+        "Reports the achieved gate as analyzed or lower with the pending compatibility decision called out, rather than declaring the migration done"
+      ]
+    }
+  ]
+}

package/skills/dsh-plugin-upgrade/evals/files/import-move-plugin/README.md

@@ -0,0 +1,5 @@
+# dsh-plugin-session-notes
+
+Test-fixture plugin that mimics a real DSH 0.1.1 plugin: it imports
+store-engine and type helpers from `@deepseek-ai/dsh-client-runtime/client`,
+the package DSH 0.1.2 removed. Used by the dsh-plugin-upgrade skill evals.

package/skills/dsh-plugin-upgrade/evals/files/import-move-plugin/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "dsh-plugin-session-notes",
+  "version": "0.3.1",
+  "description": "Session notes panel for DeepSeek Harness, built against DSH 0.1.1",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "scripts": {
+    "typecheck": "tsc -p .",
+    "build": "tsc -p . --emitDeclarationOnly false"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": "~0.1.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "typescript": "^5.6.0"
+  },
+  "dsh": {
+    "client": {
+      "entry": "./src/index.ts",
+      "external": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "inject": [
+        "@deepseek-ai/dsh-api-session-controller"
+      ]
+    }
+  }
+}

package/skills/dsh-plugin-upgrade/evals/files/import-move-plugin/src/index.ts

@@ -0,0 +1,20 @@
+import { ClientContext, createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+
+export interface Note {
+  sessionId: SessionId
+  text: string
+  updatedAt: number
+}
+
+export function activate(ctx: ClientContext) {
+  const notes = createSnapshotStore<Record<string, Note[]>>({ })
+
+  ctx.on('session:selected', (sessionId: SessionId) => {
+    const current = notes.get() ?? { }
+    current[sessionId] = current[sessionId] ?? []
+    notes.set(current)
+  })
+
+  return { notes }
+}

package/skills/dsh-plugin-upgrade/evals/files/import-move-plugin/src/stores.ts

@@ -0,0 +1,15 @@
+import { defineStore, shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
+
+export interface DraftState {
+  text: string
+  saving: boolean
+}
+
+export function equalDraft(left: DraftState, right: DraftState) {
+  return shallowEqual(left, right)
+}
+
+export const draftStore = defineStore<DraftState>(() => ({
+  text: '',
+  saving: false,
+}))

package/skills/dsh-plugin-upgrade/evals/files/settings-plugin/README.md

@@ -0,0 +1,7 @@
+# dsh-plugin-focus-timer
+
+Test-fixture plugin that mimics a real DSH 0.1.1 plugin using the
+`settingsNamespace` factory from `@deepseek-ai/dsh-settings` (removed in DSH
+0.1.2-alpha.2), a still-exported symbol from the same declaration
+(`SettingsConflictError`), and a namespace import the static analyzer cannot
+resolve. Used by the dsh-plugin-upgrade skill evals.

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

@@ -0,0 +1,20 @@
+{
+  "name": "dsh-plugin-focus-timer",
+  "version": "1.0.4",
+  "description": "Pomodoro-style focus timer for DeepSeek Harness, built against DSH 0.1.1",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "scripts": {
+    "typecheck": "tsc -p .",
+    "build": "tsc -p . --emitDeclarationOnly false"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": "~0.1.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "typescript": "^5.6.0"
+  }
+}

package/skills/dsh-plugin-upgrade/evals/files/settings-plugin/src/index.ts

@@ -0,0 +1,2 @@
+export { namespace, readFocusMinutes, describeConflict } from './settings'
+export { legacyNamespace } from './namespace-read'

package/skills/dsh-plugin-upgrade/evals/files/settings-plugin/src/namespace-read.ts

@@ -0,0 +1,6 @@
+import * as settings from '@deepseek-ai/dsh-settings'
+
+// Legacy sync path kept for the timer's "sync every launch" option.
+export function legacyNamespace() {
+  return settings.settingsNamespace('focus-timer-sync', { type: 'object' })
+}

package/skills/dsh-plugin-upgrade/evals/files/settings-plugin/src/settings.ts

@@ -0,0 +1,21 @@
+import { settingsNamespace, SettingsConflictError } from '@deepseek-ai/dsh-settings'
+
+export const namespace = settingsNamespace('focus-timer', {
+  type: 'object',
+  properties: {
+    focusMinutes: { type: 'number', default: 25 },
+    breakMinutes: { type: 'number', default: 5 },
+  },
+})
+
+export function readFocusMinutes(): number {
+  const value = namespace.get('focusMinutes')
+  return typeof value === 'number' ? value : 25
+}
+
+export function describeConflict(error: unknown): string | null {
+  if (error instanceof SettingsConflictError) {
+    return `settings conflict: ${String(error)}`
+  }
+  return null
+}

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

@@ -0,0 +1,22 @@
+[
+  {"query": "My plugin still imports from @deepseek-ai/dsh-client-runtime and I saw DSH 0.1.2 removed it. What do I need to change to get my plugin building against 0.1.2? The repo is at ~/code/dsh-plugin-quicknotes", "should_trigger": true},
+  {"query": "We're preparing our DSH plugin release for the 0.1.2 harness. Can you check whether anything in our dependency ranges or client graph declaration needs updating before we cut the release?", "should_trigger": true},
+  {"query": "升级 DSH 到 0.1.2 之后我的插件加载不出来了，报 settingsNamespace is not a function。帮我把插件迁到 0.1.2。", "should_trigger": true},
+  {"query": "dsh-host-apiproxy was deleted in the new harness version and my browser automation plugin depends on it. Plan the migration to 0.1.2 for me.", "should_trigger": true},
+  {"query": "I want ONE plugin release that works on both DSH 0.1.1 and 0.1.2 - how do I restructure the imports from dsh-client-runtime so both harness versions can load it?", "should_trigger": true},
+  {"query": "Before I publish v2 of my plugin, verify it against DSH 0.1.2: dependency peers, built artifact, and a runtime activation smoke. Is the dsh-doctor tool the right way?", "should_trigger": true},
+  {"query": "我们的插件 peerDependencies 里写着 ~0.1.1，现在要支持 0.1.2，需要改哪些依赖范围？插件在 D:\\work\\dsh-plugin-kanban", "should_trigger": true},
+  {"query": "The migration analysis says MIG_SEMANTIC_API_CHANGE for every session import in my plugin. What does that mean and how do I finish the 0.1.2 migration properly?", "should_trigger": true},
+  {"query": "help me assess whether my dsh plugin is compatible with harness 0.1.2 or whether the session controller changes break my list view", "should_trigger": true},
+  {"query": "I checked out the harness at tag dsh-v0.1.2-alpha.3 and my plugin's typecheck now fails on dsh-client-runtime types. Migrate the plugin source to 0.1.2.", "should_trigger": true},
+  {"query": "My plugin already targets DSH 0.1.2 and worked fine yesterday, but today activation fails with 'service not found' after I updated my graphics driver. Debug it.", "should_trigger": false},
+  {"query": "How do I write my first DSH plugin? Walk me through the plugin manifest and a hello-world client entry for 0.1.2.", "should_trigger": false},
+  {"query": "dsh-doctor diagnose says my web profile has a corrupted cordis.patch.yml - how do I use dsh-doctor recover to fix my installation?", "should_trigger": false},
+  {"query": "我在 DSH 里配置代理一直不生效，帮我看看 ~/.dsh 下面的配置文件哪里写错了", "should_trigger": false},
+  {"query": "Review my DSH plugin's PR: it adds a new settings panel UI. Focus on React rendering correctness and Cordis lifecycle cleanup.", "should_trigger": false},
+  {"query": "What's the difference between the DSH profile bundles and patch layers? Explaining for a blog post I'm writing about the DeepSeek Harness architecture.", "should_trigger": false},
+  {"query": "My plugin build passes on 0.1.1 but eslint crashes with OOM on large files - help me fix the lint config.", "should_trigger": false},
+  {"query": "Write a GitHub Actions workflow to publish my DSH plugin to npm whenever I push a tag.", "should_trigger": false},
+  {"query": "dsh keeps using 100% CPU when my plugin's background timer runs. Find the performance bug in my plugin code.", "should_trigger": false},
+  {"query": "Can you update the dsh-doctor CLI itself from 0.5.3 to the latest version and check its changelog for breaking changes?", "should_trigger": false}
+]

package/skills/dsh-plugin-upgrade/references/cli-bootstrap.md

@@ -11,7 +11,7 @@ dsh-doctor --version
 dsh-doctor migrations list --json
 ```
 
-Record the local version and whether the exact current `dsh-v0.1.1-rc.2` to `dsh-v0.1.2-alpha.3` catalog is present. A command that exists but lacks this catalog is not usable for the current known target.
+Record the local version and whether it exposes the exact current catalog version pair declared in SKILL.md. A command that exists but lacks this catalog is not usable for the current known target.
 
 ## 2. Check the registry without changing the machine
 

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

@@ -43,4 +43,4 @@ Do not copy a replacement package into every dependency section that contained `
 
 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.
 
-The machine-readable source of truth ships with DSH Doctor. Confirm the installed CLI exposes the current exact version pair with `dsh-doctor migrations list`; the canonical catalog source is also available in the [DSH Doctor repository](https://github.com/bruc3van/dsh-doctor/tree/master/migrations/dsh-v0.1.1-rc.2__dsh-v0.1.2-alpha.3). The older alpha.2 catalog remains historical evidence, not the current default.
+The machine-readable source of truth ships with DSH Doctor. Confirm the installed CLI exposes the current catalog version pair declared in SKILL.md with `dsh-doctor migrations list`; the canonical catalog source is also available in the [DSH Doctor repository](https://github.com/bruc3van/dsh-doctor/tree/master/migrations), under the directory named after that pair. Catalogs older than the current pair remain historical evidence, not the current default.

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

@@ -70,7 +70,7 @@ Classify every additional difference as:
 
 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.
 
-After the additional interval is reviewed, pass that exact version as `--target-version` in analyze, apply preview/apply, and verify. This is an explicit fallback for a newer 0.1.2 build that the current alpha.3 catalog does not yet cover. It changes DSH dependency-range validation, deterministic DSH development pins, and the runtime version expectation; it does not turn the unlisted interval into catalog-confirmed API knowledge. Use `--dsh-command` to name the executable that actually reports and runs that version, and update the catalog and skill deliberately when that build becomes the new known target.
+After the additional interval is reviewed, pass that exact version as `--target-version` in analyze, apply preview/apply, and verify. This is an explicit fallback for a newer 0.1.2 build that the current catalog version pair declared in SKILL.md does not yet cover. It changes DSH dependency-range validation, deterministic DSH development pins, and the runtime version expectation; it does not turn the unlisted interval into catalog-confirmed API knowledge. Use `--dsh-command` to name the executable that actually reports and runs that version, and update the catalog and skill deliberately when that build becomes the new known target.
 
 ## 4. Investigate each semantic task in the plugin
 

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

@@ -4,7 +4,7 @@
 
 Static analysis covers source/type imports, dependency ranges, client graph declarations, and generated artifacts. A pass means no known blocking finding; it does not execute project code.
 
-The current known static target is alpha.3. When the actual target is later than that catalog ref on the same 0.1.2 release line, first inspect the additional interval, then use `--target-version <version>` at every phase. The report keeps `migration.to` as the catalog ref and records `migration.actualTarget` separately, so a successful dependency or runtime check cannot be mistaken for catalog coverage of the additional API delta.
+The current known static target is the catalog target declared in SKILL.md. When the actual target is later than that catalog ref on the same 0.1.2 release line, first inspect the additional interval, then use `--target-version <version>` at every phase. The report keeps `migration.to` as the catalog ref and records `migration.actualTarget` separately, so a successful dependency or runtime check cannot be mistaken for catalog coverage of the additional API delta.
 
 ## Build