@bruc3van/dsh-doctor 0.5.5 → 0.5.6

package/README.en.md

@@ -12,7 +12,7 @@ DSH 0.1.1 → DSH 0.1.2
 
 The project also diagnoses DSH profiles and installed plugins, checks for compatible versions, and performs safety checks before quarantine or removal.
 
-> This is a community-maintained third-party project, not an official DeepSeek project. The current catalog uses `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.2` as the reference points for the 0.1.1-to-0.1.2 changes. An agent should still check actual differences when a plugin uses another patch or prerelease.
+> 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.
 
 ## Upgrade a plugin with the skill
 
@@ -115,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.5 \
+npm exec --yes --package=@bruc3van/dsh-doctor@<selected-version> -- \
   dsh-doctor migrations list
 ```
 
@@ -124,12 +124,12 @@ npx --yes --package=@bruc3van/dsh-doctor@0.5.5 \
 ```sh
 dsh-doctor migrate analyze /path/to/plugin \
   --from dsh-v0.1.1-rc.2 \
-  --to dsh-v0.1.2-alpha.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.
+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
 
@@ -155,7 +155,7 @@ dsh-doctor migrate verify /path/to/plugin --level static \
 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 \
-  --harness-root /path/to/deepseek-harness --json
+  --dsh-command /path/to/dsh --json
 ```
 
 | Level | What it checks |

package/README.md

@@ -12,7 +12,7 @@ DSH 0.1.1 → DSH 0.1.2
 
 项目同时提供 DSH profile 和插件的诊断、兼容版本检查、隔离与删除前检查。
 
-> 这是社区维护的第三方工具，不属于 DeepSeek 官方项目。当前 catalog 以 `dsh-v0.1.1-rc.2` 和 `dsh-v0.1.2-alpha.2` 为基准记录 0.1.1 到 0.1.2 的变化；插件使用其他 patch 或预发布版本时，Agent 仍需核对实际差异。
+> 这是社区维护的第三方工具，不属于 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。
 
 ## 使用 Skill 升级插件
 
@@ -115,7 +115,7 @@ Migration catalog 保存 source/target tag 和 Git commit，并记录 package、
 先确认 CLI 包含需要的迁移：
 
 ```sh
-npx --yes --package=@bruc3van/dsh-doctor@0.5.5 \
+npm exec --yes --package=@bruc3van/dsh-doctor@<selected-version> -- \
   dsh-doctor migrations list
 ```
 
@@ -124,12 +124,12 @@ npx --yes --package=@bruc3van/dsh-doctor@0.5.5 \
 ```sh
 dsh-doctor migrate analyze /path/to/plugin \
   --from dsh-v0.1.1-rc.2 \
-  --to dsh-v0.1.2-alpha.2 \
+  --to dsh-v0.1.2-alpha.3 \
   --harness-root /path/to/deepseek-harness \
   --json
 ```
 
-分析会检查源码、依赖、manifest、client graph、patch target 和已有构建产物，不执行插件代码。
+分析会检查源码、依赖、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. 修改
 
@@ -155,7 +155,7 @@ dsh-doctor migrate verify /path/to/plugin --level static \
 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 \
-  --harness-root /path/to/deepseek-harness --json
+  --dsh-command /path/to/dsh --json
 ```
 
 | 级别 | 验证内容 |

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

@@ -38,9 +38,7 @@
     "@deepseek-ai/dsh-win32-process"
   ],
   "targetVersions": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-client-store": "0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.2-alpha.2"
+    "@deepseek-ai/cordis": "4.0.2"
   },
   "dependencyPolicies": {
     "@deepseek-ai/cordis": {

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

@@ -1,5 +1,13 @@
 {
   "modules": {
+    "@deepseek-ai/dsh-settings": {
+      "settingsNamespace": {
+        "toModule": "@deepseek-ai/dsh-settings",
+        "toSymbol": "SettingsProvider.register",
+        "confidence": "semantic",
+        "reason": "The settingsNamespace factory was removed. Inject the settings Service and register the namespace through ctx.settings.register(name, schema)."
+      }
+    },
     "@deepseek-ai/dsh-client-runtime/client": {
       "ClientContext": {
         "toModule": "@deepseek-ai/cordis",

package/migrations/dsh-v0.1.1-rc.2__dsh-v0.1.2-alpha.3/behavior.md

@@ -0,0 +1,14 @@
+# DSH 0.1.1-rc.2 to 0.1.2-alpha.3 behavior migration
+
+The old Client Runtime was split by ownership. There is no aggregate replacement package.
+
+- Session control, list state, commands, projections, queue and event windows belong to `api-session-controller/client`.
+- Workspace state and commands belong to `api-workspace-controller/client`; navigation policy belongs to `ui-workspace`.
+- Conversation assembly belongs to `ui-conversation`; Chat and Trajectory own their respective projections.
+- Approval and Question own their pending objects; `ui-session` only aggregates domain publications.
+- The store engine belongs to `client-store`; React hook synthesis belongs to the renderer.
+- The Host API Proxy was removed. Unary browser operations live on their natural Remote service owners.
+- The demo-only `dsh-agent-spine-demo` package and the SQLite session persistence package were removed by alpha.3; neither has a catalog-confirmed drop-in replacement.
+- Alpha.3 adds the `dsh-session-turn-outline` package and extends session submission/load-through APIs. These additions do not justify mechanical rewrites of existing plugin behavior.
+
+An import move is safe only when the catalog marks it `exact`. A `semantic` mapping identifies the new owner but still requires the plugin developer to rewrite behavior and verify the real lifecycle.

package/migrations/dsh-v0.1.1-rc.2__dsh-v0.1.2-alpha.3/config-rules.json

@@ -0,0 +1,36 @@
+{
+  "platformModules": [
+    "react",
+    "react/jsx-runtime",
+    "react-dom",
+    "react-dom/client",
+    "@deepseek-ai/cordis",
+    "@deepseek-ai/dsh-client-store",
+    "@deepseek-ai/dsh-client-ui-slots",
+    "@deepseek-ai/dsh-client-ui-primitives"
+  ],
+  "profilePatchPaths": {
+    "web": [
+      "packages/bundle/base/cordis.patch.yml",
+      "packages/bundle/web-app/cordis.patch.yml"
+    ]
+  },
+  "rules": [
+    {
+      "id": "client-inject-is-informational",
+      "note": "dsh.client.inject lists package dependency edges; Cordis service inject controls activation."
+    },
+    {
+      "id": "baseline-external-is-implicit",
+      "note": "Platform modules are implicit and must not be repeated in dsh.client.external."
+    },
+    {
+      "id": "feature-values-use-services-or-slots",
+      "note": "Feature plugins must not use dsh.client.external as a feature-to-feature value dependency mechanism."
+    },
+    {
+      "id": "client-export-required",
+      "note": "A web dsh.client declaration requires a published exports[\"./client\"] artifact."
+    }
+  ]
+}

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

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "id": "dsh-v0.1.1-rc.2__dsh-v0.1.2-alpha.3",
+  "from": {
+    "ref": "dsh-v0.1.1-rc.2",
+    "commit": "b150a551b8d465e31e418e1b2eaf5e79bbb7d28e"
+  },
+  "to": {
+    "ref": "dsh-v0.1.2-alpha.3",
+    "commit": "dd6322d604e00eec1ba5e0c8541159906a21094a",
+    "version": "0.1.2-alpha.3"
+  },
+  "description": "DeepSeek Harness 0.1.1-rc.2 to 0.1.2-alpha.3 plugin migration",
+  "references": {
+    "ownership": ".agents/notes/implemented/architecture/2026-08-20-client-session-conversation-ownership.md",
+    "remoteMigration": ".agents/notes/implemented/architecture/2026-08-10-unary-apiproxy-remote-migration.md",
+    "clientRules": "packages/client/AGENTS.md"
+  }
+}

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

@@ -0,0 +1,74 @@
+{
+  "removed": [
+    "@deepseek-ai/dsh-acp-demo",
+    "@deepseek-ai/dsh-acp-snapshot",
+    "@deepseek-ai/dsh-agent-spine-demo",
+    "@deepseek-ai/dsh-client-runtime",
+    "@deepseek-ai/dsh-host-apiproxy",
+    "@deepseek-ai/dsh-sdk-jsonrpc-demo",
+    "@deepseek-ai/dsh-session-persistence-sqlite"
+  ],
+  "added": [
+    "@deepseek-ai/dsh-acp-app",
+    "@deepseek-ai/dsh-api-session-controller",
+    "@deepseek-ai/dsh-api-settings-controller",
+    "@deepseek-ai/dsh-api-workspace-controller",
+    "@deepseek-ai/dsh-client-store",
+    "@deepseek-ai/dsh-client-ui-approval",
+    "@deepseek-ai/dsh-client-ui-chat",
+    "@deepseek-ai/dsh-client-ui-schedule",
+    "@deepseek-ai/dsh-client-ui-session",
+    "@deepseek-ai/dsh-deepseek-llm-api-extensions",
+    "@deepseek-ai/dsh-deque",
+    "@deepseek-ai/dsh-experimental-agent-team-profile",
+    "@deepseek-ai/dsh-experimental-agent-team-web-profile",
+    "@deepseek-ai/dsh-experimental-client-ui-agent-team",
+    "@deepseek-ai/dsh-experimental-inspector",
+    "@deepseek-ai/dsh-experimental-webworker-packer",
+    "@deepseek-ai/dsh-experimental-webworker-runtime",
+    "@deepseek-ai/dsh-plugin-package-inventory-deepseek",
+    "@deepseek-ai/dsh-sdk-app",
+    "@deepseek-ai/dsh-sdk-minimal",
+    "@deepseek-ai/dsh-session-log-deepseek",
+    "@deepseek-ai/dsh-session-snapshot",
+    "@deepseek-ai/dsh-session-turn-outline",
+    "@deepseek-ai/dsh-util-crypto",
+    "@deepseek-ai/dsh-util-time",
+    "@deepseek-ai/dsh-util-values",
+    "@deepseek-ai/dsh-util-workspace-path",
+    "@deepseek-ai/dsh-webhook",
+    "@deepseek-ai/dsh-webhook-github",
+    "@deepseek-ai/dsh-win32-process"
+  ],
+  "targetVersions": {
+    "@deepseek-ai/cordis": "4.0.2"
+  },
+  "dependencyPolicies": {
+    "@deepseek-ai/cordis": {
+      "client": ["peerDependencies", "devDependencies"]
+    },
+    "@deepseek-ai/dsh-client-store": {
+      "client": ["devDependencies"]
+    },
+    "@deepseek-ai/dsh-session": {
+      "client": ["devDependencies"]
+    }
+  },
+  "semanticReplacements": {
+    "@deepseek-ai/dsh-client-runtime": [
+      "@deepseek-ai/dsh-api-session-controller",
+      "@deepseek-ai/dsh-api-workspace-controller",
+      "@deepseek-ai/dsh-client-store",
+      "@deepseek-ai/dsh-client-ui-session",
+      "@deepseek-ai/dsh-client-ui-conversation",
+      "@deepseek-ai/dsh-client-ui-chat",
+      "@deepseek-ai/dsh-client-ui-trajectory",
+      "@deepseek-ai/dsh-client-ui-approval",
+      "@deepseek-ai/dsh-client-ui-user-questions"
+    ],
+    "@deepseek-ai/dsh-host-apiproxy": [
+      "@deepseek-ai/dsh-api-gateway",
+      "@deepseek-ai/dsh-api-remotes"
+    ]
+  }
+}

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

@@ -0,0 +1,28 @@
+{
+  "services": {
+    "sessions": {
+      "owner": "@deepseek-ai/dsh-api-session-controller/client",
+      "confidence": "semantic",
+      "note": "The service name survives, but Session snapshots no longer contain Conversation views or pending interactions."
+    },
+    "workspaces": {
+      "owner": "@deepseek-ai/dsh-api-workspace-controller/client",
+      "confidence": "semantic",
+      "note": "The service name survives, while cross-domain navigation belongs to ui-workspace."
+    },
+    "conversation": {
+      "owner": "@deepseek-ai/dsh-client-ui-conversation/client",
+      "confidence": "semantic",
+      "note": "Conversation assembly and input are independent of Session lifecycle snapshots."
+    },
+    "slots": {
+      "owner": "@deepseek-ai/dsh-client-ui-renderer/client",
+      "confidence": "semantic",
+      "note": "Slot declarations stay in ui-slots; runtime registration and binding belong to ui-renderer."
+    }
+  },
+  "removedHostFacade": {
+    "package": "@deepseek-ai/dsh-host-apiproxy",
+    "replacementPolicy": "Use the natural business Remote owner through generated api-remotes contributions; there is no replacement facade."
+  }
+}

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

@@ -0,0 +1,134 @@
+{
+  "modules": {
+    "@deepseek-ai/dsh-settings": {
+      "settingsNamespace": {
+        "toModule": "@deepseek-ai/dsh-settings",
+        "toSymbol": "SettingsProvider.register",
+        "confidence": "semantic",
+        "reason": "The settingsNamespace factory was removed. Inject the settings Service and register the namespace through ctx.settings.register(name, schema)."
+      }
+    },
+    "@deepseek-ai/dsh-client-runtime/client": {
+      "ClientContext": {
+        "toModule": "@deepseek-ai/cordis",
+        "toSymbol": "Context",
+        "confidence": "exact",
+        "reason": "ClientContext was a type alias of Cordis Context."
+      },
+      "createSnapshotStore": {
+        "toModule": "@deepseek-ai/dsh-client-store",
+        "toSymbol": "createSnapshotStore",
+        "confidence": "exact",
+        "reason": "The React-free store engine moved to client-store."
+      },
+      "defineStore": {
+        "toModule": "@deepseek-ai/dsh-client-store",
+        "toSymbol": "defineStore",
+        "confidence": "exact",
+        "reason": "The declarative store factory moved to client-store."
+      },
+      "ObservableSnapshot": {
+        "toModule": "@deepseek-ai/dsh-client-store",
+        "toSymbol": "ObservableSnapshot",
+        "confidence": "exact",
+        "reason": "The observable store contract moved to client-store."
+      },
+      "SnapshotStore": {
+        "toModule": "@deepseek-ai/dsh-client-store",
+        "toSymbol": "SnapshotStore",
+        "confidence": "exact",
+        "reason": "The writable store contract moved to client-store."
+      },
+      "shallowEqual": {
+        "toModule": "@deepseek-ai/dsh-client-store",
+        "toSymbol": "shallowEqual",
+        "confidence": "exact",
+        "reason": "The store equality helper moved to client-store."
+      },
+      "SessionId": {
+        "toModule": "@deepseek-ai/dsh-session/types",
+        "toSymbol": "SessionId",
+        "confidence": "exact",
+        "reason": "Session identity is owned by the Session domain."
+      },
+      "ISessions": {
+        "toModule": "@deepseek-ai/dsh-api-session-controller/client",
+        "toSymbol": "ISessions",
+        "confidence": "semantic",
+        "reason": "Session ownership moved to the Session Controller and its snapshots changed."
+      },
+      "Session": {
+        "toModule": "@deepseek-ai/dsh-api-session-controller/client",
+        "toSymbol": "Session",
+        "confidence": "semantic",
+        "reason": "The Client Session object and lifecycle moved to the Session Controller."
+      },
+      "SessionBinding": {
+        "toModule": "@deepseek-ai/dsh-api-session-controller/client",
+        "toSymbol": "SessionBinding",
+        "confidence": "semantic",
+        "reason": "Session bindings are now Controller-owned lifetimes."
+      },
+      "SessionListState": {
+        "toModule": "@deepseek-ai/dsh-api-session-controller/client",
+        "toSymbol": "SessionListState",
+        "confidence": "semantic",
+        "reason": "The list state moved and no longer owns Conversation or pending-interaction facts."
+      },
+      "SessionSummary": {
+        "toModule": "@deepseek-ai/dsh-api-session-controller/client",
+        "toSymbol": "SessionSummary",
+        "confidence": "semantic",
+        "reason": "The Session summary is now a Controller-owned control snapshot."
+      },
+      "UseProjection": {
+        "toModule": "@deepseek-ai/dsh-api-session-controller/client",
+        "toSymbol": "UseProjection",
+        "confidence": "semantic",
+        "reason": "Projection sources are now exposed by Session Controller bindings and adapted by ui-session."
+      },
+      "IWorkspaces": {
+        "toModule": "@deepseek-ai/dsh-api-workspace-controller/client",
+        "toSymbol": "IWorkspaces",
+        "confidence": "semantic",
+        "reason": "Workspace ownership moved to the Workspace Controller and navigation policy moved to ui-workspace."
+      },
+      "WorkspaceId": {
+        "toModule": "@deepseek-ai/dsh-api-workspace-controller/client",
+        "toSymbol": "WorkspaceId",
+        "confidence": "semantic",
+        "reason": "Workspace identity is re-exported by the Workspace Controller."
+      },
+      "WorkspaceView": {
+        "toModule": "@deepseek-ai/dsh-api-workspace-controller/client",
+        "toSymbol": "WorkspaceView",
+        "confidence": "semantic",
+        "reason": "Workspace snapshots are Controller-owned and their shape changed."
+      },
+      "ConversationNode": {
+        "toModule": "@deepseek-ai/dsh-client-ui-conversation/client",
+        "toSymbol": "ConversationNode",
+        "confidence": "semantic",
+        "reason": "Conversation assembly moved out of Session snapshots into ui-conversation."
+      },
+      "ConversationSnapshot": {
+        "toModule": "@deepseek-ai/dsh-client-ui-conversation/client",
+        "toSymbol": "ConversationSnapshot",
+        "confidence": "semantic",
+        "reason": "Conversation is now an independent target-neutral source."
+      },
+      "PendingInteraction": {
+        "toModule": "@deepseek-ai/dsh-client-ui-session/client",
+        "toSymbol": "SessionPendingInteraction",
+        "confidence": "semantic",
+        "reason": "Approval and Question now publish domain-owned pending interactions through ui-session."
+      },
+      "PendingWait": {
+        "toModule": "@deepseek-ai/dsh-client-ui-session/client",
+        "toSymbol": "SessionPendingInteraction",
+        "confidence": "semantic",
+        "reason": "The Runtime PendingWait aggregate was removed; pending domains own their payloads."
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "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,13 @@
 ---
 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 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 known target reference is dsh-v0.1.2-alpha.3.
 ---
 
 # 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 current migration knowledge covers the DSH 0.1.1 to 0.1.2 transition. Its CLI catalog records `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.2` as the exact reference points used to derive and verify known changes. Use those refs in dsh-doctor commands, but first record the plugin's actual DSH ranges and requested target. When another patch or prerelease is involved, use the catalog for known changes only and report that the additional version difference still needs review. 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. 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.
 
 ## Inputs
 
@@ -24,13 +24,15 @@ Determine:
 Use these catalog reference points in the current CLI commands:
 
 - source: `dsh-v0.1.1-rc.2`
-- target: `dsh-v0.1.2-alpha.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 an exact-version `npx` 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. 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.
+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.
 
 ## Compatibility decision gate
 
@@ -53,7 +55,7 @@ Run from any directory:
 ```sh
 dsh-doctor migrate analyze <plugin-root> \
   --from dsh-v0.1.1-rc.2 \
-  --to dsh-v0.1.2-alpha.2 \
+  --to dsh-v0.1.2-alpha.3 \
   --json
 ```
 
@@ -61,6 +63,10 @@ Append `--harness-root <deepseek-harness-root>` when the checkout is available.
 
 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.
 
+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 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.
+
 Group the result by:
 
 1. errors blocking compatibility;
@@ -102,7 +108,7 @@ Run the gates in order:
 ```sh
 dsh-doctor migrate verify <plugin-root> --level static --harness-root <deepseek-harness-root> --json
 dsh-doctor migrate verify <plugin-root> --level build --yes --install --harness-root <deepseek-harness-root> --json
-dsh-doctor migrate verify <plugin-root> --level runtime --yes --install --harness-root <deepseek-harness-root> --json
+dsh-doctor migrate verify <plugin-root> --level runtime --yes --install --dsh-command <actual-dsh-command> --json
 ```
 
 Build and runtime levels require `--yes --install`: the CLI first runs the detected package manager with lifecycle scripts disabled, updates the lockfile when needed, and verifies the installed DSH/Cordis versions against runtime, development, peer, and optional dependency declarations before executing project scripts. A required peer must resolve and satisfy every declared range; a missing optional peer is recorded but does not fail the gate. Review lockfile changes as migration changes. Runtime verification then packs the real plugin, creates a temporary `DSH_HOME`, installs into a new web profile, dumps effective config, and performs an activation smoke. It does not modify the developer's normal `~/.dsh`.
@@ -119,6 +125,8 @@ For a dual-version result, verify the produced release against both the actual 0
 
 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.
 
+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.
+
 ## Report the outcome
 
 State the highest achieved gate exactly:

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 `dsh-v0.1.1-rc.2` to `dsh-v0.1.2-alpha.2` catalog is present. A command that exists but lacks this catalog is not usable for this skill.
+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.
 
 ## 2. Check the registry without changing the machine
 
@@ -26,12 +26,14 @@ This is a read-only update check. If it fails because the registry is unavailabl
 ## 3. Select and pin one invocation
 
 - When the local version equals the registry version and exposes the catalog, use `dsh-doctor` directly.
-- When the local CLI is missing, differs from the registry version, or lacks the catalog, prefer the registry version through exact-version npx. First verify that version exposes the required catalog:
+- When the local CLI is missing, differs from the registry version, or lacks the catalog, prefer the registry version through an exact-version package runner. First verify that version exposes the required catalog:
 
 ```sh
-npx --yes --package=@bruc3van/dsh-doctor@<registry-version> dsh-doctor migrations list --json
+npm exec --yes --package=@bruc3van/dsh-doctor@<registry-version> -- dsh-doctor migrations list --json
 ```
 
+This `npm exec ... -- dsh-doctor` form is the preferred cross-platform invocation. On Windows, `npx --package=... dsh-doctor` can fail to resolve the temporary binary when launched from an unrelated project root. A direct `npx --yes @bruc3van/dsh-doctor@<version> ...` smoke from a fresh temporary directory is also acceptable, but keep one verified invocation for the whole migration.
+
 - When the registry is unavailable, use the local CLI only if its catalog check passed.
 - When neither candidate exposes the catalog, stop and report the missing prerequisite instead of guessing a compatible CLI.
 - Respect an explicit developer request to use a particular local or development CLI, but still record its version and verify the catalog.
@@ -54,6 +56,6 @@ Include these fields in the handoff:
 
 - local CLI version or `missing`;
 - registry version or `unknown`;
-- selected exact version and invocation source (`local`, `npx`, or authorized `global-install`);
+- selected exact version and invocation source (`local`, `npm-exec`, or authorized `global-install`);
 - required catalog present or absent;
 - update status: `current`, `outdated`, `missing`, or `unknown`.

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

@@ -19,6 +19,10 @@ Session snapshots no longer own Conversation views or all pending-interaction fa
 
 `@deepseek-ai/dsh-host-apiproxy` was removed. Browser operations use their natural generated Remote owners through API Remotes/API Gateway contributions. There is no facade-compatible package substitution.
 
+## Settings registration
+
+`@deepseek-ai/dsh-settings` remains, but its `settingsNamespace` factory export was removed in 0.1.2-alpha.2. This is a semantic Service migration, not an import move: inject the `settings` Service and register the plugin namespace through `ctx.settings.register(name, schema)`. Keep `SettingsConflictError` or other exports that still exist, and verify every namespace read path against the provider API (for example `describe`) instead of assuming the former factory object's methods still exist.
+
 ## Client graph
 
 - `dsh.client.inject` declares package dependency edges; Cordis service injection still controls activation.
@@ -39,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 this 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.2).
+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.

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

@@ -70,6 +70,8 @@ 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.
+
 ## 4. Investigate each semantic task in the plugin
 
 Start from the finding's `file`, `symbol`, `targetModule`, `targetSymbol`, and `reason`. Then:

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

@@ -4,12 +4,16 @@
 
 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.
+
 ## Build
 
 Build and runtime verification require `--yes --install`. The CLI selects the package manager from lockfiles, synchronizes dependencies with dependency lifecycle scripts disabled, records the lockfile hash before and after, and verifies installed DSH/Cordis versions against `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies`. Required peers must resolve and satisfy every declared range. Missing optional dependencies or peers are recorded as `optional-missing`; when installed, they must satisfy their ranges. It then runs declared scripts in this order: `typecheck`, `build`, `test`, `pack:check`, stopping at the first failure. Artifact verification requires a successful `build` or `pack:check`; `typecheck`/`test` alone do not pass this gate.
 
 If dependency installation or resolution verification fails, stop before running project scripts. Review and retain package manifest and lockfile changes with the source migration.
 
+If pnpm's `minimumReleaseAge` blocks a newly published target prerelease, do not disable or weaken the repository-wide supply-chain policy. Confirm the selected target and registry provenance, then add only the exact `package@version` rows required under `minimumReleaseAgeExclude`, including transitive DSH packages reported by pnpm. Review this workspace-policy change alongside the lockfile and report it explicitly.
+
 ## Runtime
 
 Runtime verification:
@@ -24,6 +28,8 @@ The gate also checks the DSH CLI's exact target version, the created profile man
 
 Use a built target Harness CLI through `--harness-root`, or pass `--dsh-command` explicitly. The temporary home is deleted only after a successful run unless `--keep-temp` is set.
 
+The runtime executable must report the exact actual target selected by `--target-version` (or the catalog target when the option is omitted). A later prerelease is not accepted implicitly because that would disconnect the runtime evidence from the reviewed dependency and source target.
+
 ## Behavior
 
 Choose focused checks from the plugin contract: render the real UI, invoke each command, exercise settings, verify service availability, repeat activation/deactivation, check listener cleanup, and cover failure recovery. Record exact commands, screenshots, logs, or tests. This gate is deliberately not inferred by dsh-doctor.

package/src/cli.mjs

@@ -43,7 +43,8 @@ Options:
   --fix, --repair        legacy confirmed repairs (never removes a plugin)
   --yes                  confirm an explicit write or command
   --from <ref>            source DSH ref (default: dsh-v0.1.1-rc.2)
-  --to <ref>              target DSH ref (default: dsh-v0.1.2-alpha.2)
+  --to <ref>              target DSH ref (default: dsh-v0.1.2-alpha.3)
+  --target-version <ver>  actual DSH 0.1.2 version for dependency/runtime checks
   --safe                  restrict migrate apply to catalog-confirmed exact rewrites
   --plan-file <path>      persist or consume the reviewed migrate apply plan
   --level <level>         static, build, or runtime verification
@@ -85,7 +86,8 @@ const HELP_ZH = `用法：
   --fix, --repair        旧式确认修复（绝不移除插件）
   --yes                  确认一个明确的写入或命令动作
   --from <ref>           源 DSH ref（默认：dsh-v0.1.1-rc.2）
-  --to <ref>             目标 DSH ref（默认：dsh-v0.1.2-alpha.2）
+  --to <ref>             目标 DSH ref（默认：dsh-v0.1.2-alpha.3）
+  --target-version <版本> 依赖与 runtime 验证使用的实际 DSH 0.1.2 版本
   --safe                 migrate apply 仅执行 catalog 确认的精确改写
   --plan-file <路径>     保存或读取已审阅的 migrate apply 计划
   --level <级别>        static、build 或 runtime
@@ -146,6 +148,8 @@ function parse(args) {
     else if (arg.startsWith('--from=')) options.from = optionValue(arg, '--from')
     else if (arg === '--to') options.to = valueAfter(args, index++, arg)
     else if (arg.startsWith('--to=')) options.to = optionValue(arg, '--to')
+    else if (arg === '--target-version') options.targetVersion = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--target-version=')) options.targetVersion = optionValue(arg, '--target-version')
     else if (arg === '--safe') options.safe = true
     else if (arg === '--plan-file') options.planFile = valueAfter(args, index++, arg)
     else if (arg.startsWith('--plan-file=')) options.planFile = optionValue(arg, '--plan-file')
@@ -300,7 +304,7 @@ async function main() {
     if (!['analyze', 'apply', 'verify'].includes(options.migrateAction)) throw new Error('migrate needs analyze, apply, or verify')
     if (options.migrateAction === 'apply' && options.safe !== true) throw new Error('migrate apply requires --safe')
     if (options.migrateAction === 'apply' && options.pluginRoot === undefined) throw new Error('migrate apply requires an explicit plugin root')
-    const migrationOptions = { from: options.from, to: options.to, harnessRoot: options.harnessRoot, dshCommand: options.dshCommand, level: options.level, yes: options.yes, safe: options.safe, keepTemp: options.keepTemp, planFile: options.planFile, install: options.install }
+    const migrationOptions = { from: options.from, to: options.to, targetVersion: options.targetVersion, harnessRoot: options.harnessRoot, dshCommand: options.dshCommand, level: options.level, yes: options.yes, safe: options.safe, keepTemp: options.keepTemp, planFile: options.planFile, install: options.install }
     if (options.migrateAction === 'verify') {
       const { formatVerification, verifyMigration } = await import('./migrate-verify.mjs')
       const result = verifyMigration(options.pluginRoot, migrationOptions)

package/src/migrate-verify.mjs

@@ -214,7 +214,8 @@ export function verifyMigration(pluginRoot = process.cwd(), options = {}) {
   const [versionCommand, versionArgs] = dshInvocation(dsh, ['--version'])
   const versionRun = commandResult(versionCommand, versionArgs, { cwd: root, env })
   const actualDshVersion = versionRun.stdout.trim()
-  const versionPassed = versionRun.passed && actualDshVersion === analysis.migration.to.version
+  const expectedDshVersion = analysis.migration.actualTarget.version
+  const versionPassed = versionRun.passed && actualDshVersion === expectedDshVersion
   const pack = commandResult(manager.command, manager.pack(packDir), { cwd: root })
   const tarball = tarballFromPack(pack, packDir)
   const runtimeCommands = []
@@ -236,7 +237,7 @@ export function verifyMigration(pluginRoot = process.cwd(), options = {}) {
   result.stages.push({
     name: 'runtime',
     passed: runtimePassed,
-    dshVersion: { expected: analysis.migration.to.version, actual: actualDshVersion, passed: versionPassed, command: commandEvidence(versionRun) },
+    dshVersion: { expected: expectedDshVersion, catalog: analysis.migration.to.version, actual: actualDshVersion, passed: versionPassed, command: commandEvidence(versionRun) },
     pack: commandEvidence(pack),
     tarball,
     commands: runtimeCommands.map(commandEvidence),

package/src/migrate.mjs

@@ -80,12 +80,17 @@ function moduleLiteral(node) {
 
 function namedImports(node) {
   const bindings = node.importClause?.namedBindings
-  if (!bindings || !ts.isNamedImports(bindings)) return []
-  return bindings.elements.map(item => ({
+  if (bindings && ts.isNamedImports(bindings)) return bindings.elements.map(item => ({
     imported: item.propertyName?.text ?? item.name.text,
     local: item.name.text,
     typeOnly: node.importClause.isTypeOnly || item.isTypeOnly,
   }))
+  if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) return node.exportClause.elements.map(item => ({
+    imported: item.propertyName?.text ?? item.name.text,
+    local: item.name.text,
+    typeOnly: node.isTypeOnly || item.isTypeOnly,
+  }))
+  return []
 }
 
 function quoteModule(text) {
@@ -117,10 +122,11 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
       handledLiterals.add(literal)
       const moduleName = literal.text
       const rootName = packageRoot(moduleName)
-      if (removed.has(rootName)) {
+      const moduleRemoved = removed.has(rootName)
+      const symbolRules = catalog.symbols.modules[moduleName]
+      if (moduleRemoved || symbolRules !== undefined) {
         const where = location(source, literal, pluginRoot)
-        const symbolRules = catalog.symbols.modules[moduleName]
-        const specs = ts.isImportDeclaration(node) ? namedImports(node) : []
+        const specs = namedImports(node)
         const exact = []
         const remaining = []
         for (const spec of specs) {
@@ -128,7 +134,7 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
           if (rule?.confidence === 'exact') {
             exact.push({ ...spec, imported: rule.toSymbol, toModule: rule.toModule, fromSymbol: spec.imported, reason: rule.reason })
             findings.push({ code: 'MIG_MOVED_SYMBOL', severity: 'error', message: `${spec.imported} moved to ${rule.toModule}`, location: where, evidence: { module: moduleName, symbol: spec.imported, targetModule: rule.toModule, replacement: rule.toSymbol }, autoFix: 'safe' })
-          } else {
+          } else if (rule?.confidence === 'semantic' || moduleRemoved) {
             remaining.push(spec)
             const semantic = rule?.confidence === 'semantic'
             findings.push({ code: semantic ? 'MIG_SEMANTIC_API_CHANGE' : 'MIG_REMOVED_PACKAGE_REFERENCE', severity: 'error', message: semantic ? `${spec.imported} requires a semantic migration: ${rule.reason}` : `${moduleName} was removed without a safe automatic replacement`, location: where, evidence: { module: moduleName, ...(spec.imported ? { symbol: spec.imported } : {}) }, autoFix: 'none' })
@@ -140,7 +146,7 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
               ...(rule?.toSymbol ? { targetSymbol: rule.toSymbol } : {}),
               reason: rule?.reason ?? 'No exact replacement is known.',
             })
-          }
+          } else remaining.push(spec)
         }
         const declarationText = ts.isImportDeclaration(node) ? text.slice(node.getStart(source), node.getEnd()) : ''
         const simpleNamedImport = exact.length > 0 && ts.isImportDeclaration(node) && node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings) && node.importClause.name === undefined && node.attributes === undefined && node.assertClause === undefined && !/\/(?:\/|\*)/.test(declarationText)
@@ -160,7 +166,7 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
           const generated = [...groups].map(([target, items]) => importText(target, items, node.importClause.isTypeOnly))
           if (remaining.length > 0) generated.unshift(importText(moduleName, remaining, node.importClause.isTypeOnly))
           replacements.push({ start: node.getStart(source), end: node.getEnd(), next: generated.join('\n'), exact })
-        } else if (specs.length === 0 || exact.length > 0) {
+        } else if (moduleRemoved && (specs.length === 0 || exact.length > 0)) {
           for (const finding of findings) if (finding.code === 'MIG_MOVED_SYMBOL' && finding.location.line === where.line && exact.some(item => item.fromSymbol === finding.evidence.symbol)) finding.autoFix = 'none'
           findings.push({ code: 'MIG_REMOVED_PACKAGE_REFERENCE', severity: 'error', message: `${moduleName} was removed and this reference cannot be rewritten safely`, location: where, evidence: { module: moduleName, kind: ts.SyntaxKind[node.kind] }, autoFix: 'none' })
           unresolved.push({ file: where.file, package: rootName, module: moduleName, reason: 'Default, namespace, side-effect, export, require, dynamic import, or module augmentation reference.' })
@@ -189,12 +195,28 @@ function readManifest(pluginRoot) {
   return { file, value, text }
 }
 
-function targetVersion(name, catalog) {
+function actualTargetVersion(catalog, requested) {
+  if (requested === undefined) return catalog.manifest.to.version
+  const version = semver.valid(requested)
+  if (version === null) throw new Error(`--target-version must be an exact semantic version, received ${requested}`)
+  const catalogVersion = semver.parse(catalog.manifest.to.version)
+  const target = semver.parse(version)
+  if (catalogVersion === null || target === null || target.major !== catalogVersion.major || target.minor !== catalogVersion.minor || target.patch !== catalogVersion.patch) {
+    throw new Error(`--target-version ${requested} is outside the catalog's ${catalogVersion?.major}.${catalogVersion?.minor}.${catalogVersion?.patch} release line`)
+  }
+  if (semver.lt(target, catalogVersion)) {
+    throw new Error(`--target-version ${requested} predates the catalog target ${catalog.manifest.to.version}`)
+  }
+  return version
+}
+
+function targetVersion(name, catalog, actualTarget) {
+  if (name.startsWith('@deepseek-ai/dsh-')) return actualTarget
   if (catalog.packages.targetVersions?.[name] !== undefined) return catalog.packages.targetVersions[name]
-  return name.startsWith('@deepseek-ai/dsh-') ? catalog.manifest.to.version : undefined
+  return undefined
 }
 
-function manifestFindings(manifest, catalog) {
+function manifestFindings(manifest, catalog, actualTarget) {
   const findings = []
   for (const field of DEPENDENCY_FIELDS) {
     const dependencyMap = manifest.value[field]
@@ -207,7 +229,7 @@ function manifestFindings(manifest, catalog) {
         findings.push({ code: 'MIG_REMOVED_PACKAGE_REFERENCE', severity: 'error', message: `${field}.${name} targets a removed package`, location: { file: 'package.json' }, evidence: { field, package: name, range }, autoFix: 'conditional' })
         continue
       }
-      const target = targetVersion(name, catalog)
+      const target = targetVersion(name, catalog, actualTarget)
       if (target === undefined) continue
       const validRange = typeof range === 'string' ? semver.validRange(range) : null
       if (validRange === null) findings.push({ code: 'MIG_INVALID_DEPENDENCY_RANGE', severity: 'error', message: `${field}.${name} has a non-registry range that cannot prove target compatibility`, location: { file: 'package.json' }, evidence: { field, package: name, range, target }, autoFix: field === 'devDependencies' ? 'safe' : 'none' })
@@ -307,7 +329,7 @@ function patchTargetFindings(pluginRoot, manifest, harness) {
   return findings
 }
 
-function planManifest(manifest, sourceResults, artifactResults, opaqueReferences, catalog) {
+function planManifest(manifest, sourceResults, artifactResults, opaqueReferences, catalog, actualTarget) {
   const next = structuredClone(manifest.value)
   const exactTargets = sourceResults.flatMap(result => result.exactTargets)
   const sourceReferences = new Set(sourceResults.flatMap(result => result.remainingPackages))
@@ -323,14 +345,14 @@ function planManifest(manifest, sourceResults, artifactResults, opaqueReferences
     }
     if (field === 'devDependencies') {
       for (const [name, range] of Object.entries(deps)) {
-        const target = targetVersion(name, catalog)
+        const target = targetVersion(name, catalog, actualTarget)
         if (target !== undefined && !catalog.packages.removed.includes(name) && (semver.validRange(range) === null || !semver.satisfies(target, range))) deps[name] = target
       }
     }
   }
   for (const move of new Map(exactTargets.map(item => [`${item.relationship}\0${item.toPackage}`, item])).values()) {
     const fields = catalog.packages.dependencyPolicies?.[move.toPackage]?.[move.relationship]
-    const version = targetVersion(move.toPackage, catalog)
+    const version = targetVersion(move.toPackage, catalog, actualTarget)
     if (!Array.isArray(fields) || version === undefined) continue
     for (const field of fields) {
       if (!DEPENDENCY_FIELDS.includes(field)) throw new Error(`migration catalog has an invalid dependency field ${field}`)
@@ -369,7 +391,8 @@ function analysisInputs(root) {
 export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   const root = resolve(pluginRoot)
   if (!statSync(root).isDirectory()) throw new Error(`plugin root is not a directory: ${root}`)
-  const catalog = loadMigration(options.from ?? 'dsh-v0.1.1-rc.2', options.to ?? 'dsh-v0.1.2-alpha.2')
+  const catalog = loadMigration(options.from ?? 'dsh-v0.1.1-rc.2', options.to ?? 'dsh-v0.1.2-alpha.3')
+  const actualTarget = actualTargetVersion(catalog, options.targetVersion)
   const harness = verifyHarnessCheckout(catalog, options.harnessRoot)
   const manifest = readManifest(root)
   const sourceFiles = walk(root, SOURCE_DIRS_TO_SKIP).filter(file => !isTopLevelArtifact(root, file))
@@ -378,10 +401,10 @@ export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   const opaqueReferences = opaqueReferenceFindings(root, sourceFiles, manifest, catalog)
   const sourceRemoved = sources.some(item => item.findings.some(finding => ['MIG_REMOVED_PACKAGE_REFERENCE', 'MIG_SEMANTIC_API_CHANGE', 'MIG_MOVED_SYMBOL'].includes(finding.code)))
   const artifactRemoved = artifacts.some(item => item.findings.some(finding => ['MIG_REMOVED_PACKAGE_REFERENCE', 'MIG_SEMANTIC_API_CHANGE', 'MIG_MOVED_SYMBOL'].includes(finding.code)))
-  const findings = [...manifestFindings(manifest, catalog), ...patchTargetFindings(root, manifest, harness), ...sources.flatMap(item => item.findings), ...opaqueReferences.findings, ...artifacts.flatMap(item => item.findings)]
+  const findings = [...manifestFindings(manifest, catalog, actualTarget), ...patchTargetFindings(root, manifest, harness), ...sources.flatMap(item => item.findings), ...opaqueReferences.findings, ...artifacts.flatMap(item => item.findings)]
   if (!sourceRemoved && artifactRemoved) findings.push({ code: 'MIG_SOURCE_ARTIFACT_DRIFT', severity: 'error', message: 'built artifacts still reference removed APIs although source files do not', location: { file: '.' }, evidence: { artifactDirectories: ARTIFACT_DIRS }, autoFix: 'none' })
   findings.push({ code: 'MIG_RUNTIME_VERIFICATION_REQUIRED', severity: 'info', message: 'static analysis cannot prove activation and lifecycle behavior; run migrate verify --level runtime', location: { file: '.' }, evidence: {}, autoFix: 'none' })
-  const manifestPlan = planManifest(manifest, sources, artifacts, opaqueReferences.packages, catalog)
+  const manifestPlan = planManifest(manifest, sources, artifacts, opaqueReferences.packages, catalog, actualTarget)
   const changed = [...sources.filter(item => item.changed), ...(manifestPlan.changed ? [manifestPlan] : [])]
   const safeEdits = changed.map(item => ({
     file: relativePath(root, item.file),
@@ -393,14 +416,21 @@ export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   return {
     schemaVersion: 1,
     command: 'migrate analyze',
-    migration: { id: catalog.manifest.id, from: catalog.manifest.from, to: catalog.manifest.to, references: catalog.manifest.references ?? {}, harness },
+    migration: {
+      id: catalog.manifest.id,
+      from: catalog.manifest.from,
+      to: catalog.manifest.to,
+      actualTarget: { version: actualTarget, catalogVersion: catalog.manifest.to.version, catalogExact: actualTarget === catalog.manifest.to.version },
+      references: catalog.manifest.references ?? {},
+      harness,
+    },
     plugin: { root, name: manifest.value.name ?? basename(root), version: manifest.value.version ?? 'unknown', manifestFile: manifest.file, packageManager: existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : 'npm' },
     summary: summarize(findings, safeEdits, unresolved),
     findings,
     safeEdits,
     semanticTasks: unresolved,
     sourceInvestigation: {
-      required: harness.exact !== true || unresolved.length > 0,
+      required: harness.exact !== true || unresolved.length > 0 || actualTarget !== catalog.manifest.to.version,
       targetRef: catalog.manifest.to.ref,
       catalogReferences: catalog.manifest.references ?? {},
       semanticTargets: [...new Set(unresolved.map(item => item.targetModule).filter(Boolean))],
@@ -429,6 +459,7 @@ export function createMigrationPlan(report) {
       id: report.migration.id,
       from: report.migration.from.ref,
       to: report.migration.to.ref,
+      targetVersion: report.migration.actualTarget.version,
       harness: {
         status: report.migration.harness.status,
         fromCommit: report.migration.harness.fromCommit,
@@ -453,7 +484,7 @@ function readMigrationPlan(file) {
 function assertMigrationPlan(report, plan) {
   const current = createMigrationPlan(report)
   if (plan.plugin.root !== current.plugin.root || plan.plugin.manifestFile !== current.plugin.manifestFile) throw new Error('migration plan targets a different plugin')
-  if (plan.migration.id !== current.migration.id || plan.migration.from !== current.migration.from || plan.migration.to !== current.migration.to) throw new Error('migration plan targets a different catalog')
+  if (plan.migration.id !== current.migration.id || plan.migration.from !== current.migration.from || plan.migration.to !== current.migration.to || plan.migration.targetVersion !== current.migration.targetVersion) throw new Error('migration plan targets a different catalog or actual target version')
   if (plan.reportHash !== current.reportHash || JSON.stringify(plan.inputs) !== JSON.stringify(current.inputs) || JSON.stringify(plan.edits) !== JSON.stringify(current.edits)) throw new Error('plugin analysis changed after the preview; create and review a new migration plan')
   return current
 }
@@ -478,7 +509,7 @@ export function applyMigration(report, options = {}) {
     if (currentExists !== item.snapshot.exists || sha256(current) !== item.snapshot.hash) throw new Error(`${item.snapshot.file} changed after the preview; diagnose again before applying`)
   }
   const writes = report._plan.map(item => ({ ...atomicWrite(item.snapshot, item.nextText), beforeHash: item.snapshot.hash, afterHash: sha256(item.nextText) }))
-  const verification = analyzeMigration(report.plugin.root, { from: report.migration.from.ref, to: report.migration.to.ref, harnessRoot: report.migration.harness.root })
+  const verification = analyzeMigration(report.plugin.root, { from: report.migration.from.ref, to: report.migration.to.ref, targetVersion: report.migration.actualTarget.version, harnessRoot: report.migration.harness.root })
   return { mode: 'applied', plan: { file: planFile, id: verifiedPlan.planId }, writes, report: publicMigrationReport(verification) }
 }