dsh-plugin-upgrade 0.1.3 → 2.0.1

package/lib/scan.mjs

@@ -1,26 +1,49 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
 /**
- * scan-0.1.5.mjs — zero-dependency detector for the DSH `0.1.3-alpha.1 → 0.1.5-alpha.1`
- * plugin-adaptation seams.
+ * scan-0.1.5.mjs — zero-dependency detector for the DSH `0.1.3-alpha.1 →
+ * 0.1.5-rc.1` plugin-adaptation seams.
  *
- * Why this exists: typecheck passing is NOT evidence of adaptation. Two classes of
- * failure survive a green local gate — (a) seams the published type line hides
- * because the repo compiles against stale types, and (b) seams whose tests are
- * mocked against the old shape. This scanner reports `file:line` facts for ten
- * seams measured against 40 real plugin repos during the 2026-09-09 wave, and
- * treats the "tsconfig silently resolves to the wrong types" case (M1) as a
- * first-class defect, not a warning.
+ * Why this exists: this span's breakage is mostly *silent*. Two examples that
+ * motivate the whole catalog:
+ *   - the bare `conversation` client slot was deleted with no alias, and
+ *     `ctx.slots.inject()` only runs its callback when the declaration exists —
+ *     so a client half that still targets it stops mounting without an error,
+ *     a log line or a failed build (`C1`);
+ *   - `assistant/message` gained a required `stream` field, so a log written
+ *     without it imports fine and then refuses to resume (`S3`).
+ * A green local gate is therefore NOT evidence of adaptation: the published
+ * type line hides both deletions entirely.
+ *
+ * This scanner is the MERGED catalog for the whole `0.1.3-alpha.1 → 0.1.5-rc.1`
+ * corridor. It supersedes two version-locked predecessors that each covered one
+ * hop of the same span:
+ *   - leg A `0.1.3-alpha.1 → 0.1.5-alpha.1` — seams `S1`–`S10`, `M1`
+ *     (formerly `dsh-plugin-upgrade`)
+ *   - leg B `0.1.5-alpha.1 → 0.1.5-rc.1` — seams `C1`–`C5`, `H1`–`H4`, `P1`
+ *     (formerly `dsh-plugin-upgrade-rc1`)
+ * `M1` and the former leg-B `C3` were the same defect (a local gate compiling a
+ * stale type line), so they are one seam here; the card records the old spelling.
+ * The hop `0.1.5-rc.1 → 0.1.5-rc.2` added no plugin-facing seam, so the span
+ * ends at rc.1 by construction.
+ *
+ * The catalog below is the single source of truth shared by the version card,
+ * the packaged skill and this CLI. `test/card.test.mjs` fails when the card and
+ * this catalog disagree about the seam ids.
  *
  * Usage:
- *   node scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams S3,S8,M1] [--quiet]
+ *   node scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams S3,C1] [--quiet]
  *
  * Exit codes: 0 = no error-severity hit, 1 = at least one error-severity hit,
  *             2 = usage/scan failure.
  *
- * Provenance: evidence for every seam lives in the 2026-09-09 batch report
- * (40 plugin repos) and the per-repo cards produced by that wave. The scanner
- * ships in this package so a plugin author can re-measure their own repo; it
- * imports nothing outside Node's standard library.
+ * Provenance: every upstream fact behind a seam was re-read from the harness
+ * checkout and recorded with `path:line` in `docs/EVIDENCE.md` and in the
+ * version card
+ * (`skills/plugin-upgrade/references/v0.1.3-alpha.1-to-v0.1.5-rc.1.md`).
+ * This scanner ships so a plugin author can re-measure their own repository; it
+ * imports nothing outside Node's standard library and never writes inside the
+ * scanned tree.
  */
 
 import fs from 'node:fs'
@@ -29,10 +52,34 @@ import path from 'node:path'
 const SKIP_DIRS = new Set(['node_modules', 'lib', 'dist', '.git', '.tmp', 'coverage', '_scratch', '_archive', 'downloads', 'upstream', 'dev'])
 const SCAN_EXT = /\.(ts|tsx|mts|cts|mjs|cjs|js|jsx|json|yml|yaml)$/
 
-/** @typedef {{ id: string, title: string, severity: 'error'|'warn'|'info', action: string, test: RegExp }} Seam */
+/**
+ * @typedef {object} Seam
+ * @property {string} id
+ * @property {string} title
+ * @property {'error'|'warn'|'info'} severity
+ * @property {string} action
+ * @property {RegExp|null} test  null = structured or card-only, deliberately not detected line-wise
+ * @property {(line: string) => boolean} [lineFilter]
+ * @property {(lines: string[], i: number) => boolean} [windowFilter]
+ * @property {(text: string, file: string) => boolean} [fileCheck]
+ * @property {(text: string, file: string) => boolean} [fileCheck2]
+ * @property {(text: string) => boolean} [downgradeIf]
+ */
+
+/**
+ * @typedef {object} Hit
+ * @property {string} seam
+ * @property {string} severity
+ * @property {string} file
+ * @property {number} line
+ * @property {string} snippet
+ * @property {string} detail
+ */
 
 /** @type {Seam[]} */
 export const SEAMS = [
+  // ---------------------------------------------------------------- leg A
+  // 0.1.3-alpha.1 → 0.1.5-alpha.1
   {
     id: 'S3',
     title: 'assistant/message 缺 stream（V3 必填）',
@@ -73,10 +120,10 @@ export const SEAMS = [
   },
   {
     id: 'M1',
-    title: 'tsconfig 的 checkout 路径解析失败 → typecheck 静默回退',
+    title: '本地门禁编译的是过期类型线 → typecheck 静默回退（假绿）',
     severity: 'error',
-    action: 'tsconfig `paths` 指向不存在的目录时 TypeScript 会静默回退到 node_modules 的已发布类型，本地门禁变成假绿。路径应为 `../../../../deepseek-harness/packages/...`（相对仓库根）。',
-    test: /__tsconfig_paths_probe__/,
+    action: '两种独立成因，任何一种都让本地门禁变成假绿：(a) dev/test 依赖钉在 `0.1.5-alpha.*`，本地类型看不到 rc.1 的删除；(b) tsconfig `paths` 指向不存在的 checkout 目录时 TypeScript 静默回退到 node_modules 的已发布类型。把 dev/test 依赖钉到当前 rc 线，并保证每条 checkout 别名都能解析。**本接缝在 leg B 卡片上曾记作 `C3`，是同一条缺陷。**',
+    test: null,
   },
   {
     id: 'S4',
@@ -135,8 +182,99 @@ export const SEAMS = [
     action: '宿主事件词表 fail-closed 且 `Session.append` 无 `ignorable` 写入通道；无条件 append 会让会话不可读，请保留"探测后降级"的写法。',
     test: /SessionEventMap|\.append\(/,
   },
+
+  // ---------------------------------------------------------------- leg B
+  // 0.1.5-alpha.1 → 0.1.5-rc.1
+  {
+    id: 'C1',
+    title: '裸 slot `conversation` 已删除（无别名）→ UI 静默不挂载',
+    severity: 'error',
+    action: '把 `ctx.slots.inject(\'conversation\', …)` / `slots.register({ name: \'conversation\' })` 改写成 `main.conversation`（会话内容位）或 `main`（全局中央面板，需 `key`）。rc.1 没有别名，也没有 deprecation 说明：回调永不执行，插件 UI 消失且没有任何报错。',
+    test: /['"]conversation['"]/,
+    // Same-line and multi-line call forms both count; the key must sit in a
+    // slot-facing context, never in prose or an unrelated settings string.
+    windowFilter: (lines, i) => {
+      const win = lines.slice(Math.max(0, i - 2), i + 2).join('\n')
+      return /\.inject\s*\(/.test(win) || /register\s*\(\s*\{/.test(win) || /name\s*:\s*['"]conversation['"]/.test(win)
+    },
+  },
+  {
+    id: 'C2',
+    title: 'npm 包改名：`dsh-client-ui-sidebar-textpreview` → `…-sidebar-documentpreview`',
+    severity: 'error',
+    action: '把 peer / optional peer / import / lockfile 里的 `@deepseek-ai/dsh-client-ui-sidebar-textpreview` 改为 `@deepseek-ai/dsh-client-ui-sidebar-documentpreview`。旧名在 rc.1 的 `packages/client/` 下已不存在，也没有 shim 包；做文档预览的插件改注册到 `sidebar.right.tab.document`。',
+    test: /sidebar-textpreview/,
+  },
+  {
+    id: 'P1',
+    title: 'peer 区间缺了第二段 → `0.1.5-rc.1` 被 semver 拒绝',
+    severity: 'error',
+    action: '`>=0.1.2-rc.1 <0.2.0` 单段在 semver 下**不满足** `0.1.5-rc.1`（实测 semver 7.8.5 → false）：npm 的 prerelease-tuple 规则只在同一 `[major,minor,patch]` 元组上存在带 prerelease 的 comparator 时才放行。必须保留 `|| >=0.1.5-alpha.1 <0.2.0` 这一段，rc.1 适配**不改** peer 区间。',
+    test: null,
+  },
+  {
+    id: 'C4',
+    title: 'rc.1 新增全局面板模型，且每个 slot 多一个 `usePanelInfo` 标准 prop',
+    severity: 'warn',
+    action: '纯增量：rc.1 给几乎每个 slot 的 standardProps 追加了 `usePanelInfo: UsePanelInfo`（47 个文件提及），并新增 `main`（keyed/root）、`sidebar.panellist`（list/root）、`ctx.layout.selectPanel(MainPanelId | null)`、`ctx.layout.beginNavigation()`。用官方 `ComposedProps` 的仓零改动；手写 props 接口的组件需要复核。',
+    test: /usePanelInfo|selectPanel\(|sidebar\.panellist|MainPanelId|beginNavigation\(/,
+  },
+  {
+    id: 'C5',
+    title: '右侧文档预览迁到 keyed slot `sidebar.right.tab.document`',
+    severity: 'warn',
+    action: 'TextPreview 的行为迁到 `sidebar.right.tab.document`（keyed/session，ownerProps = `DocumentContent`）。`sidebar.right.pane.tab` / `.title` 仍然存在，但 `declaredBy` 从 `rightbar` 变成 `rightbar.session`：inject `rightbar` 取得 pane 的插件要复核注入目标。',
+    test: /sidebar\.right\.pane\.tab|TextPreview|DocumentContent/,
+  },
+  {
+    id: 'H1',
+    title: 'fail-closed 会话事件词表新增两个类型',
+    severity: 'warn',
+    action: '`KNOWN_SESSION_EVENT_TYPES` 新增 `deliverables/presented` 与 `subagent/catalog`。枚举过该词表、或自建事件白名单 / 计数快照的读取方要重新快照；否则新事件从「未知跳过」变成进入 surface，计数与渲染都会变。',
+    test: /KNOWN_SESSION_EVENT_TYPES|deliverables\/presented|subagent\/catalog/,
+  },
+  {
+    id: 'H2',
+    title: '新工具 `present` 占用了 tool view 的 key `\'present\'`',
+    severity: 'warn',
+    action: 'rc.1 的新工具 `present` 自带 PresentRow，注册在 `tool.call.toolview` 的 key `\'present\'`（`packages/client/ui-deliverables/src/client/index.ts:62`），并且 `present` 因此进入 `conversation.chat.node` 的 already-taken keyDomain（`grep` 与 `read` 之间）。alpha.1 时该 key 是空闲的：已占用它的插件会被官方行顶掉，请换 key。',
+    test: /['"]present['"]/,
+    lineFilter: line => /toolview|tool\.call|chat\.node|key\s*:\s*['"]present['"]/.test(line),
+  },
+  {
+    id: 'H4',
+    title: 'DeepSeek 适配器的默认咨询模型目录改以 `deepseek-flash` 打头',
+    severity: 'info',
+    action: 'rc.1 起 `llm-deepseek` 的默认 `models` 目录第一项是 `deepseek-flash`（name `DeepSeek-V41-Flash`，commit `bc5fd3b8dc`），README 的 `models` 默认行同步改为「V41 Flash + V4 Flash + V4 Pro + V4 Flash Vision Exp」。硬编码模型 id、或假定目录首项即默认模型的插件复核。',
+    test: /['"]deepseek-(?:chat|reasoner|v[0-9][a-z0-9.-]*|flash[a-z0-9.-]*)['"]/,
+  },
+  {
+    id: 'H3',
+    title: 'rc.1 新增可选能力（纯增量，卡片列出，不做自动检测）',
+    severity: 'info',
+    action: '`ctx.sessionFeedback`（`command-feedback`）；`ctx.layout.selectPanel()` / `beginNavigation()`；`ctx.workspaces.openSession()` / `openWorkspace()` / `forkSession()`；新品牌类型 `MainPanelId`。全部是增量：不接入不会有任何破坏，接入是可选收益。本接缝刻意没有自动检测。',
+    test: null,
+  },
 ]
 
+/** Seam ids in card order; the version card must name exactly this set. */
+export const SEAM_IDS = SEAMS.map(s => s.id)
+
+/** Seams implemented structurally (not by regex), like `M1` and `P1`. */
+const STRUCTURED = new Set(['M1', 'P1'])
+
+/**
+ * Seams that are documented on the card and id-parity checked, but deliberately
+ * have no automatic detection (pure additive capabilities).
+ */
+export const CARD_ONLY = SEAMS.filter(s => s.test === null && !STRUCTURED.has(s.id)).map(s => s.id)
+
+/**
+ * Yield every scannable file under `dir`, depth-limited and read-only.
+ * @param {string} dir
+ * @param {number} [depth]
+ * @returns {Generator<string, void, void>}
+ */
 function* walk(dir, depth = 0) {
   if (depth > 8) return
   let ents
@@ -151,16 +289,67 @@ function* walk(dir, depth = 0) {
   }
 }
 
-/** Strip comment-only lines so prose never satisfies a code-level check. */
+/**
+ * 1-based line number of the first line containing `needle`, or 1.
+ * @param {string} text
+ * @param {string} needle
+ * @returns {number}
+ */
+function lineOf(text, needle) {
+  const lines = text.split(/\r?\n/)
+  const i = lines.findIndex(l => l.includes(needle))
+  return i < 0 ? 1 : i + 1
+}
+
+/**
+ * Strip comment-only lines so prose never satisfies a code-level check.
+ * @param {string} text
+ * @returns {string}
+ */
 function stripComments(text) {
   return text.split(/\r?\n/).filter(l => !/^\s*(?:\/\/|\/\*|\*|#)/.test(l)).join('\n')
 }
 
-/** M1: resolve every `paths` entry; a missing target means silent fallback. */
-function checkTsconfigPaths(repoDir, imports) {
+/**
+ * Read and parse the repository's top-level package.json, or null.
+ * @param {string} repoDir
+ * @returns {{ file: string, text: string, json: Record<string, unknown> } | null}
+ */
+function readManifest(repoDir) {
+  const file = path.join(repoDir, 'package.json')
+  try { return { file, text: fs.readFileSync(file, 'utf8'), json: JSON.parse(fs.readFileSync(file, 'utf8')) } } catch { return null }
+}
+
+/**
+ * M1 — the local-gate false green. Two independent causes, both reported under
+ * this one seam (leg B's card spelled the pair `C3`):
+ *   (a) a `@deepseek-ai/*` dev/test dependency pinned on the `0.1.5-alpha.*`
+ *       line, so local typecheck cannot see the deletions later in the span;
+ *   (b) a `tsconfig` `paths` alias pointing at a checkout directory that does
+ *       not exist, where TypeScript silently falls back to node_modules.
+ * @param {string} repoDir
+ * @param {Set<string>} imports bare `@deepseek-ai/*` specifiers the repo imports
+ */
+function checkStaleTypeLine(repoDir, imports) {
   const hits = []
-  const files = fs.readdirSync(repoDir).filter(f => /^tsconfig.*\.json$/.test(f))
-  for (const f of files) {
+  const manifest = readManifest(repoDir)
+  if (manifest) {
+    const dev = manifest.json.devDependencies && typeof manifest.json.devDependencies === 'object' ? manifest.json.devDependencies : {}
+    for (const [dep, spec] of Object.entries(dev)) {
+      if (!dep.startsWith('@deepseek-ai/')) continue
+      if (typeof spec !== 'string') continue
+      // Exact-ish pins on the alpha line only: a deliberate range that still
+      // covers the span (`>=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0`) is fine.
+      if (!/^[\^~]?0\.1\.5-alpha\.[12]$/.test(spec.trim())) continue
+      hits.push({
+        seam: 'M1', severity: 'error', file: manifest.file, line: lineOf(manifest.text, `"${dep}"`),
+        snippet: `"${dep}": "${spec}"`,
+        detail: `dev/test types are pinned at the 0.1.5-alpha line (${spec}) → local typecheck cannot see the rc.1 slot catalog (green gate is fake)`,
+      })
+    }
+  }
+  const names = (() => { try { return fs.readdirSync(repoDir).filter(f => /^tsconfig.*\.json$/.test(f)) } catch { return [] } })()
+  for (const f of names) {
     const full = path.join(repoDir, f)
     let json
     try { json = JSON.parse(fs.readFileSync(full, 'utf8')) } catch { continue }
@@ -183,7 +372,7 @@ function checkTsconfigPaths(repoDir, imports) {
         const resolved = path.resolve(base, probe)
         if (!fs.existsSync(resolved)) {
           hits.push({
-            seam: 'M1', severity: 'error', file: path.join(repoDir, f), line: 1,
+            seam: 'M1', severity: 'error', file: full, line: 1,
             snippet: `"${alias}": ["${t}"]`,
             detail: `resolves to ${resolved} which does not exist → TypeScript silently falls back to node_modules (green gate is fake)`,
           })
@@ -194,11 +383,37 @@ function checkTsconfigPaths(repoDir, imports) {
   return hits
 }
 
+/**
+ * P1 — the peer band must keep its second segment. `>=0.1.2-rc.1 <0.2.0` alone
+ * rejects `0.1.5-rc.1` under npm semver's prerelease-tuple rule.
+ * @param {string} repoDir
+ */
+function checkPeerBand(repoDir) {
+  /** @type {Hit[]} */
+  const hits = []
+  const manifest = readManifest(repoDir)
+  if (!manifest) return hits
+  const peers = manifest.json.peerDependencies && typeof manifest.json.peerDependencies === 'object' ? manifest.json.peerDependencies : {}
+  for (const [dep, spec] of Object.entries(peers)) {
+    if (!dep.startsWith('@deepseek-ai/dsh-')) continue
+    if (typeof spec !== 'string') continue
+    const text = spec.trim()
+    if (!/0\.1\.2-rc\.1/.test(text)) continue
+    if (/0\.1\.5-alpha\.1/.test(text) || /0\.1\.5-rc\.1/.test(text)) continue
+    hits.push({
+      seam: 'P1', severity: 'error', file: manifest.file, line: lineOf(manifest.text, `"${dep}"`),
+      snippet: `"${dep}": "${text}"`,
+      detail: 'peer band lost its `>=0.1.5-alpha.1 <0.2.0` segment → 0.1.5-rc.1 is rejected by semver\'s prerelease-tuple rule (measured false on semver 7.8.5)',
+    })
+  }
+  return hits
+}
+
 /**
  * Scan one repo.
  * @param {string} repoDir
  * @param {{ seams?: string[] }} [options]
- * @returns {{ repo: string, scannedAt: string, files: number, hits: any[], bySeam: Record<string, number> }}
+ * @returns {{ repo: string, scannedAt: string, files: number, hits: Hit[], bySeam: Record<string, number> }}
  */
 export function scanRepo(repoDir, options = {}) {
   const wanted = options.seams && options.seams.length ? new Set(options.seams) : null
@@ -213,7 +428,8 @@ export function scanRepo(repoDir, options = {}) {
     const lines = text.split(/\r?\n/)
     for (const seam of SEAMS) {
       if (wanted && !wanted.has(seam.id)) continue
-      if (seam.id === 'M1') continue // handled separately (structured, not regex)
+      if (seam.test === null) continue // structured or card-only seam
+      if (STRUCTURED.has(seam.id)) continue // handled separately (structured, not regex)
       if (seam.fileCheck && !seam.fileCheck(text, file)) continue
       if (seam.fileCheck2 && !seam.fileCheck2(text, file)) continue
       for (let i = 0; i < lines.length; i++) {
@@ -238,19 +454,28 @@ export function scanRepo(repoDir, options = {}) {
       }
     }
   }
-  if (!wanted || wanted.has('M1')) hits.push(...checkTsconfigPaths(repoDir, imports))
+  if (!wanted || wanted.has('M1')) hits.push(...checkStaleTypeLine(repoDir, imports))
+  if (!wanted || wanted.has('P1')) hits.push(...checkPeerBand(repoDir))
+  /** @type {Record<string, number>} */
   const bySeam = {}
   for (const h of hits) bySeam[h.seam] = (bySeam[h.seam] || 0) + 1
   return { repo: repoDir, scannedAt: new Date().toISOString(), files, hits, bySeam }
 }
 
-/** Human-readable rendering. */
+/**
+ * Human-readable rendering. Error group first, advisory seams after.
+ * @param {{ repo: string, files: number, hits: Hit[] }} report
+ * @returns {string}
+ */
 export function render(report) {
   const L = []
   L.push(`# scan-0.1.5 · ${report.repo}`)
   L.push(`files scanned: ${report.files} · hits: ${report.hits.length}`)
-  if (!report.hits.length) { L.push('no seam hits — still verify with real-host smoke (this scanner is necessary, not sufficient)'); return L.join('\n') }
-  const order = ['S3', 'S8', 'S9', 'M1', 'S4', 'S5', 'S6', 'S7', 'S2', 'S1', 'S10']
+  const order = ['S3', 'S8', 'S9', 'M1', 'S4', 'S5', 'S6', 'C1', 'C2', 'P1', 'S7', 'S2', 'S1', 'S10', 'C4', 'C5', 'H1', 'H2', 'H4']
+  if (!report.hits.length) {
+    L.push('no seam hits — still verify with a real-host smoke AND a real browser assertion for the client half')
+    L.push('(this scanner is necessary, not sufficient: the breakage this corridor covers is silent)')
+  }
   for (const id of order) {
     const group = report.hits.filter(h => h.seam === id)
     if (!group.length) continue
@@ -261,10 +486,18 @@ export function render(report) {
     for (const h of group.slice(0, 12)) L.push(`   ${path.relative(process.cwd(), h.file)}:${h.line}  ${h.snippet}`)
     if (group.length > 12) L.push(`   ... ${group.length - 12} more`)
   }
+  L.push('')
+  L.push('H3 [info] card-only: the rc.1 additive capabilities are listed on the version card and are never auto-detected.')
   return L.join('\n')
 }
 
+/**
+ * CLI entry point.
+ * @param {string[]} argv
+ * @returns {number} the process exit code.
+ */
 export function main(argv) {
+  /** @type {{ repo: string, json: string | null, seams: string[] | null, quiet: boolean }} */
   const args = { repo: process.cwd(), json: null, seams: null, quiet: false }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
@@ -272,7 +505,7 @@ export function main(argv) {
     else if (a === '--json') args.json = argv[++i]
     else if (a === '--seams') args.seams = String(argv[++i]).split(',').map(s => s.trim()).filter(Boolean)
     else if (a === '--quiet') args.quiet = true
-    else if (a === '--help' || a === '-h') { console.log('usage: node scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams S3,S8,M1] [--quiet]'); return 0 }
+    else if (a === '--help' || a === '-h') { console.log('usage: node scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams S3,C1] [--quiet]'); return 0 }
     else { console.error(`unknown argument: ${a}`); return 2 }
   }
   const repoDir = path.resolve(args.repo)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-upgrade",
-  "version": "0.1.3",
-  "description": "Plugin-author upgrade skill for DeepSeek Harness: a version-locked 0.1.3-alpha.1 -> 0.1.5-alpha.1 version card plus a zero-dependency seam scanner (V3 session format, assistant/message.stream, SessionHandleReadResult, ctx.agent, Inbox, SubprocessHandle.pid, SystemPrompt persona, PTC rename, EpochHeader.system, and the tsconfig stale-path false green), packaged as a bundle skill and an npx CLI.",
+  "version": "2.0.1",
+  "description": "Plugin-author upgrade skill for DeepSeek Harness: one package, one corridor index - the scanner detects the caller peer band and routes to the matching closed corridor card (0.1.3-alpha.1 -> 0.1.5-rc.1 as legs A+B, and 0.1.5-rc.2 -> 0.1.6-alpha.2 as leg C), with a zero-dependency seam scanner shipped as a bundle skill and an npx CLI.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/PerryLink/dsh-plugin-upgrade.git"
@@ -35,16 +35,17 @@
     "lib",
     "scripts",
     "skills",
+    "docs",
     "cordis.patch.yml",
     "CHANGELOG.md",
     "SECURITY.md",
     "AGENTS.md",
     "THIRD_PARTY_NOTICES.md",
     "README.md",
-    "README.zh.md",
-    "README.es.md",
-    "README.pt.md",
-    "README.hi.md",
+    "README-zh.md",
+    "README-es.md",
+    "README-pt.md",
+    "README-hi.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -53,6 +54,45 @@
       "patch": "./cordis.patch.yml"
     }
   },
+  "dshWorkshop": {
+    "schema": "omdsh-workshop-package/v1",
+    "type": "plugin",
+    "integration": {
+      "protocol": "harness-profile",
+      "artifact": "cordis.patch.yml"
+    },
+    "install": {
+      "mode": "transactional",
+      "adapter": "profile-bundle",
+      "failurePolicy": "generation-rollback",
+      "touchesCurrentBeforeActivation": false
+    },
+    "lifecycle": {
+      "activation": "restart-profile",
+      "dispose": "supported"
+    },
+    "permissions": [
+      "filesystem:read"
+    ],
+    "compatibility": {
+      "dshVersions": [
+        "0.1.2-rc.1",
+        "0.1.5-rc.2"
+      ]
+    },
+    "capability": {
+      "id": "plugin-upgrade",
+      "kind": "service",
+      "invocation": "ctx.skills.get('plugin-upgrade') resolves a complete SkillDefinition",
+      "expected": "the session skill catalog lists plugin-upgrade and the loaded body carries the merged 0.1.3-alpha.1 -> 0.1.5-rc.1 corridor card with a directory resourceBase"
+    },
+    "evidence": {
+      "install": null,
+      "failureIsolation": null,
+      "hotReload": null,
+      "remove": null
+    }
+  },
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -63,7 +103,8 @@
     "migration",
     "skill",
     "version-card",
-    "scanner"
+    "scanner",
+    "client-slots"
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -71,16 +112,20 @@
   "packageManager": "pnpm@11.7.0",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-skill": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0",
+    "@deepseek-ai/dsh-skill": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-skill": "0.1.5-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/dsh-skill": "0.1.5-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
   },
   "scripts": {
     "test": "node --test \"test/*.test.mjs\"",
+    "check": "tsc -p tsconfig.check.json",
+    "typecheck:ci": "tsc -p tsconfig.check.ci.json",
     "scan": "node scripts/scan-0.1.5.mjs",
     "check:readmes": "node scripts/check-readme-sync.mjs",
     "verify:self-contained": "node scripts/verify-self-contained.mjs",

package/scripts/changelog-section.mjs

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Print the CHANGELOG.md section for one version, for GitHub Release notes.
 // Usage: node scripts/changelog-section.mjs <x.y.z>
 import { readFileSync } from 'node:fs'

package/scripts/check-readme-sync.mjs

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Five-language README sync gate: every README must carry the same number of
 // `## ` sections as the English source and state the install command.
 // Usage: node scripts/check-readme-sync.mjs
@@ -6,14 +7,16 @@ import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
-const FILES = ['README.md', 'README.zh.md', 'README.es.md', 'README.pt.md', 'README.hi.md']
+const FILES = ['README.md', 'README-zh.md', 'README-es.md', 'README-pt.md', 'README-hi.md']
 const INSTALL_COMMAND = 'dsh plugin --profile web add dsh-plugin-upgrade'
 const failures = []
+/** @param {string} file @returns {string} */
 const read = (file) => {
   const p = join(root, file)
   if (!existsSync(p)) { failures.push(`${file} is missing`); return '' }
   return readFileSync(p, 'utf8')
 }
+/** @param {string} text @returns {number} */
 const sectionCount = text => (text.match(/^## /gmu) ?? []).length
 
 const contents = FILES.map(read)

package/scripts/scan-0.1.5.mjs

@@ -1,15 +1,29 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
 /**
- * CLI wrapper for the packaged seam scanner.
+ * CLI wrapper for the corridor-index router (one package, several closed corridors).
  *
  * Usage:
- *   node scripts/scan-0.1.5.mjs [--repo <path>] [--json <out.json>] [--seams M1,S3] [--quiet]
+ *   node scripts/scan-0.1.5.mjs [--repo <path>] [--span legC|legAB|<span>] [--json <out.json>] [--seams E1,E3] [--quiet]
  *   npx --package dsh-plugin-upgrade dsh-plugin-upgrade-scan --repo <path>
  *
+ * The wrapper only routes: it reads the target repository's declared dsh band (or
+ * an explicit --span) and hands the SAME argv to that corridor's own catalog
+ * module, so every corridor keeps its own evidence-bound seam array and its own
+ * main(). An unknown band routes to the older corridor (legAB), which is what a
+ * repository predating 0.1.6 needs. Nothing here reaches the network.
+ *
  * Exit codes: 0 = no error-severity hit, 1 = at least one error-severity hit,
- *             2 = usage or scan failure. The implementation lives in ../lib/scan.mjs
- * so the plugin, the CLI and the tests share one seam catalog.
+ *             2 = usage or scan failure.
  */
-import { main } from '../lib/scan.mjs'
+import { resolveCorridor, spanFromArgv, repoFromArgv, loadCatalog } from '../lib/route.mjs'
+
+const argv = process.argv.slice(2)
+const corridor = resolveCorridor({ repoDir: repoFromArgv(argv), span: spanFromArgv(argv) })
+const catalog = await loadCatalog(corridor)
+
+if (!argv.includes('--quiet')) {
+  process.stderr.write(`corridor: ${corridor.id} (${corridor.span}) -> ${corridor.catalog}\n`)
+}
 
-process.exit(main(process.argv.slice(2)))
+process.exit(catalog.main(argv))

package/scripts/sweep-all.mjs

@@ -1,4 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
 // Sweep every plugin repo under a workspace root and write the evidence table.
+// Maintainer tool: it ships in the tarball because `scripts/` does, but neither
+// the plugin entry nor the skill body calls it.
 // Usage: node sweep-all.mjs [<workspaceRoot>] [<out.md>]
 import fs from 'node:fs'
 import path from 'node:path'
@@ -6,7 +9,8 @@ import { scanRepo } from '../lib/scan.mjs'
 
 const ROOT = path.resolve(process.argv[2] || '.')
 const OUT = path.resolve(process.argv[3] || path.join(ROOT, 'scan-0.1.5-sweep.md'))
-const SKIP = new Set(['adp-list', 'audit-dsh-infinite-gen-2', 'pan17-dsh-wechat', 'dsh-autotier', 'dsh-personal-directive'])
+// Third-party repositories that happen to live in the same workspace.
+const SKIP = new Set(['adp-list', 'audit-dsh-infinite-gen-2', 'pan17-dsh-wechat', 'dsh-personal-directive'])
 const dirs = fs.readdirSync(ROOT, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name)
   .filter(n => !n.startsWith('_') && !n.startsWith('.') && !SKIP.has(n))
   .filter(n => fs.existsSync(path.join(ROOT, n, 'package.json'))).sort()
@@ -23,7 +27,7 @@ L.push('# scan-0.1.5 · workspace sweep evidence')
 L.push('')
 L.push(`Generated ${new Date().toISOString()} · scanner \`scripts/scan-0.1.5.mjs\` · workspace \`${ROOT}\``)
 L.push('')
-L.push('All repos below were adapted to `0.1.5-alpha.1` by the 2026-09-09 wave. Error-severity hits are expected to be **zero**; warn-severity hits are heuristic leads for manual review (S1/S2/S10).')
+L.push('Error-severity hits mean the repo would silently break (or already fails to resolve) somewhere on the merged `0.1.3-alpha.1 → 0.1.5-rc.1` corridor. Warn/info hits are heuristic leads for manual review.')
 L.push('')
 L.push('| repo | files | errors | warns | error seams |')
 L.push('|---|---|---|---|---|')