dsh-plugin-upgrade 0.1.0

package/AGENTS.md

@@ -0,0 +1,102 @@
+# AGENTS.md
+
+Standalone DeepSeek Harness plugin repository (`dsh-plugin-upgrade`). Development follows
+the dsh-plugin-guide skill and the official plugin contract; this file records repo-local
+decisions. Read `README.md` (external contract) and the packaged version card
+(`skills/plugin-upgrade-015/references/v0.1.3-alpha.1-to-v0.1.5-alpha.1.md`) before
+changing behavior.
+
+## Layout (JS form, pure host, no browser half)
+
+```
+index.mjs             single host face: Config schema + skill bundle reader + apply()
+types.d.ts            Config, SeamHit, ScanReport and the public function surface
+lib/scan.mjs          zero-dependency seam catalog + scanner + CLI main()
+scripts/scan-0.1.5.mjs   thin bin wrapper (npx dsh-plugin-upgrade-scan)
+skills/plugin-upgrade-015/scripts/scan-0.1.5.mjs  the same wrapper inside the skill directory,
+                      so the skill body's `./scripts/...` resolves against its resourceBase
+scripts/sweep-all.mjs    maintainer tool: sweep a workspace of plugin repos into a table
+scripts/changelog-section.mjs  print one CHANGELOG section for GitHub Release notes
+scripts/verify-self-contained.mjs  every import resolves inside the package
+scripts/verify-artifacts.mjs       pack + inspect the published tarball
+scripts/check-readme-sync.mjs      five-language README consistency
+skills/plugin-upgrade-015/SKILL.md  the bundled skill body (frontmatter name is the skill id)
+skills/plugin-upgrade-015/references/…  the version card
+test/scan.test.mjs    synthetic bad/good fixtures + a live negative on an adapted repo
+test/plugin.test.mjs  real Cordis Context + real SkillRegistry: register, dispose, negative
+fixtures/             scanner fixtures (bad-repo, good-repo)
+cordis.patch.yml      bundle declaration (insert dsh-plugin-upgrade); every Config key inline
+pnpm-workspace.yaml   nearest-workspace root (isolates this repo from a surrounding harness checkout)
+package.json          npm metadata; files whitelist = published content
+.github/workflows/    CI (3 OS × 2 Node), monthly compat probe, v* npm release
+README.md             English primary (GitHub default page; source of truth)
+README.{zh,es,pt,hi}.md  translations, top switcher, updated in the same commit
+CHANGELOG.md          Keep a Changelog, [Unreleased] at the top
+SECURITY.md           private vulnerability reporting + scope
+THIRD_PARTY_NOTICES.md  install-time dependencies (none bundled)
+LICENSE               Apache-2.0
+```
+
+## Hard rules applied here
+
+- **The corridor is locked.** This package upgrades plugins across `0.1.3-alpha.1 →
+  0.1.5-alpha.1` and nothing else. Do not widen the peer band or the card to "all versions":
+  a drifting card is worse than no card. A new corridor is a new package.
+- **M1 is an error, never a warning.** If a `tsconfig` `paths` alias does not resolve, every
+  other local signal is fake. The scanner must keep failing the run for it.
+- **The scanner is read-only and dependency-free.** No network, no child process, no write
+  inside `--repo`; `lib/scan.mjs` imports only `node:fs` and `node:path`. Keep it that way.
+- **Advisory seams stay advisory.** `S7`/`S1`/`S2`/`S10` have legitimate matches; they are
+  leads for manual review. Only promote one to `error` with evidence and a fixture that
+  proves the false positive is gone.
+- **A clean scan is necessary, not sufficient.** Never describe a scan as proof of
+  adaptation; the card's exit criterion is a real-host smoke on a temp `DSH_HOME`.
+- **Mount loud.** A missing `SKILL.md`, an empty body, or a frontmatter without `name` must
+  abort the mount. Never register a placeholder skill.
+- **The skill id is the frontmatter name.** `skillName` selects the directory; the registered
+  name comes from the file. Keep the two in sync (`plugin-upgrade-015`).
+- **Registration is an effect.** `ctx.skills.register()` runs inside `ctx.effect()` so the
+  disposer removes the contribution on unload; the test asserts that.
+- **No build step.** Pure ESM: `index.mjs` + `lib/` are the shipped artifacts. There is no
+  `build`/`prepare` script — keep it that way.
+- **Optional seams fail closed.** `skills` is a hard `inject`; if the service is absent the
+  plugin waits rather than registering into a void.
+
+## Checks
+
+```sh
+pnpm install
+pnpm test                          # node --test (9 tests: scanner + real-registry mount)
+pnpm run verify:self-contained     # dependency specs resolve from the registry
+pnpm run verify:artifacts          # shipped files present + entry importable from the tarball
+pnpm run check:readmes             # five-language README consistency
+pnpm pack                          # the published tarball
+```
+
+`pnpm-workspace.yaml` keeps `minimumReleaseAge: 0`: pnpm 11 enables a 1440-minute age gate by
+default and its frozen-install lockfile verification ignores `minimumReleaseAgeExclude`, so
+the freshly published `@deepseek-ai` pins would otherwise keep a fresh install red for 24h
+after every harness release.
+
+## Release
+
+Version is currently `0.1.0`. For a new version: bump `package.json#version`, stamp the
+CHANGELOG `[Unreleased]` section into `## [<x.y.z>] - <UTC date>`, re-run the full gate,
+commit `chore(release): <x.y.z>`, and `git tag -a v<x.y.z>`. `git push origin main
+--follow-tags` triggers `.github/workflows/release.yml`, which re-runs the gate, publishes to
+npm with provenance (skipped without the `NPM_TOKEN` secret), and creates the GitHub Release
+from the stamped CHANGELOG section. Never push a tag for a version already on the registry.
+
+The scanner catalog is evidence-bound: a version bump that changes a seam must update the
+card, the fixtures and `CHANGELOG.md` in the same commit.
+
+## Docs
+
+- Five-language READMEs (`README.md` is the source; `README.zh.md`, `README.es.md`,
+  `README.pt.md`, `README.hi.md` follow). Every behavior change updates all five in the same
+  commit; `check:readmes` enforces the shared surface in CI.
+- GitHub topics `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`,
+  `plugin-upgrade`, `migration`, `skill`, `version-card`, `scanner` (mirror `package.json`
+  keywords; the ecosystem's visibility channel is the `dsh-plugin` topic).
+- License is Apache-2.0 (`LICENSE` + the package.json `license` field).
+  `THIRD_PARTY_NOTICES.md` documents install-time dependencies; nothing is bundled.

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- **Bundled agent skill `plugin-upgrade-015`** — the version-locked `0.1.3-alpha.1 → 0.1.5-alpha.1` upgrade corridor: a 6-step fix-and-verify loop plus the version card with host path, commit, minimal fix and regression for every seam.
+- **Zero-dependency seam scanner** (`dsh-plugin-upgrade-scan`, also `dsh-plugin-upgrade/scan`) — reports `file:line` facts for ten seams measured against 40 real plugin repositories during the 2026-09-09 adaptation wave; exit `1` on any error-severity hit.
+- **Ten-seam catalog** — `S1` V3 session format / generation-scoped log name, `S2` `EpochHeader.system` removal, `S3` `assistant/message.stream` required, `S4` `tool/code-dispatch` → `tool/ptc-dispatch`, `S5` `ctx.agent` removal, `S6` `Inbox` typed interface, `S7` `SubprocessHandle.pid` removal, `S8` `SessionHandleReadResult`, `S9` `SystemPrompt.persona` → `personaPrefix`/`personaSuffix`, `M1` stale `tsconfig` `paths` producing a silently fake-green typecheck.
+- **M1 as a first-class defect** — the scanner resolves every checkout-style `tsconfig` alias and fails the scan when a target directory does not exist, instead of letting the repo compile against published types.
+- **Plugin surface** — `enabled`, `skillName`, `skillsRoot`, `userInvocable` config keys; the skill registers through the injected `skills` service and unregisters with its effect disposer. A missing bundle, an empty body or a nameless frontmatter fails the mount loud.
+- **Gates** — `node --test` against a real Cordis `Context` and the real `SkillRegistry`, five-language README consistency, self-contained import resolution, and a packed-tarball artifact check that imports the entry under plain Node.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 dsh-memento contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.es.md

@@ -0,0 +1,172 @@
+<div align="center">
+
+# ⬆️ dsh-plugin-upgrade
+- **Canal de la tienda 1024**: ejecuta `npm i -g dsh1024` una vez y luego `dsh1024 plugin --profile web add dsh-plugin-upgrade` (cuenta para el ranking de instalaciones de [deepseek1024.com](https://deepseek1024.com)).
+[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-upgrade)
+
+**Habilidad de actualización de plugins con versión fijada para DeepSeek Harness — `0.1.3-alpha.1` → `0.1.5-alpha.1`.**
+
+*Una tarjeta de versión más un escáner de costuras sin dependencias, para que «typecheck está en verde» nunca se confunda con «el plugin sigue funcionando».*
+
+> **Repositorio oficial.** Este es el único repositorio oficial de dsh-plugin-upgrade, mantenido por PerryLink. Los repositorios con el mismo nombre en otras cuentas no están afiliados.
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![dsh-doctor](https://raw.githubusercontent.com/PerryLink/dsh-plugin-doctor/main/badges/PerryLink__dsh-plugin-upgrade.svg)](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-plugin-upgrade/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-plugin-upgrade/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-plugin-upgrade?label=version)](https://github.com/PerryLink/dsh-plugin-upgrade/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-upgrade)](https://www.npmjs.com/package/dsh-plugin-upgrade)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-upgrade)](https://www.npmjs.com/package/dsh-plugin-upgrade)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## Compatibilidad
+
+| Superficie | Estado |
+|---|---|
+| Harness | DeepSeek Harness `0.1.5-alpha.1` (checkout `19d2e38480`, tag `dsh-v0.1.5-alpha.1` = `5dda764ed3`). Banda de peers `@deepseek-ai/dsh-skill >=0.1.2-rc.1 <0.2.0 \|\| >=0.1.5-alpha.1 <0.2.0`, `@deepseek-ai/cordis ^4.0.2`, `@deepseek-ai/schemastery ^3.18.2`. |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| Plataformas | Donde corra Node; el escáner solo lee el sistema de archivos y es neutral respecto a la plataforma |
+| Modelo | Modelos solo de texto totalmente soportados; la habilidad es un cuerpo Markdown, sin requisitos de herramientas ni visión |
+| Alcance | **Un solo corredor**: `0.1.3-alpha.1` → `0.1.5-alpha.1`. No es un marco de migración general. |
+
+## Lo que obtienes
+
+Dos mitades y un único catálogo de costuras:
+
+- **Una habilidad de agente incluida (`plugin-upgrade-015`)**: una tarjeta de versión y un bucle de corregir-y-verificar. El modelo solo la carga cuando la tarea realmente la necesita; el paquete no aporta ningún párrafo al prompt del sistema ni registra herramientas.
+- **Una CLI sin dependencias (`dsh-plugin-upgrade-scan`)**: informa hechos `archivo:línea` para diez costuras medidas sobre 40 repositorios de plugins reales durante la ola de adaptación del 2026-09-09. Sale con `1` ante cualquier hallazgo de severidad error, así que entra directo en CI.
+
+El objetivo es el modo de fallo que la tarjeta existe para eliminar: **una puerta local en verde no es prueba de adaptación.** Dos clases de rotura sobreviven a `typecheck` + `test`:
+
+1. la línea de tipos publicada oculta la costura y el repositorio compila contra tipos obsoletos (costura `M1`);
+2. las pruebas están simuladas contra la forma antigua, así que pasan mientras el host rechaza la nueva.
+
+Cuatro de las diez costuras — `S3`, `S8`, `S9`, `M1` — seguían sin cobertura por ningún PR comunitario de actualización cuando se escribió este paquete; las otras seis están contrastadas con la evidencia de la ola.
+
+## Inicio rápido
+
+```sh
+# 1. instala el bundle en tu perfil
+dsh plugin --profile web add dsh-plugin-upgrade
+
+# 2. verifica que la fila se montó
+dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-upgrade'
+
+# 3. escanea el plugin que estás actualizando
+npx dsh-plugin-upgrade-scan --repo ../my-plugin
+```
+
+Después pide al agente que use la habilidad `plugin-upgrade-015`, o guía el bucle tú mismo con la tarjeta en
+`skills/plugin-upgrade-015/references/v0.1.3-alpha.1-to-v0.1.5-alpha.1.md`.
+
+## Instalación y desinstalación
+
+```sh
+dsh plugin --profile web add dsh-plugin-upgrade            # desde npm
+dsh plugin --profile web add "github:PerryLink/dsh-plugin-upgrade#main"   # desde el código
+dsh plugin --profile web remove dsh-plugin-upgrade         # desinstalar (reversible)
+```
+
+Instalar el bundle solo registra una habilidad; quitar la fila la elimina. La CLI es un destino `npx` normal y no necesita ningún perfil.
+
+## Configuración
+
+Cada clave es opcional y vive en el patch del perfil:
+
+| Clave | Predeterminado | Significado |
+|---|---|---|
+| `enabled` | `true` | Registra la habilidad incluida. `false` mantiene la dependencia montada pero silenciosa. |
+| `skillName` | `plugin-upgrade-015` | Directorio bajo `skillsRoot` que se registra, y nombre mostrado en el catálogo. |
+| `skillsRoot` | el `./skills` del propio paquete | Dónde vive `<skillName>/SKILL.md`. Apúntalo a tu propia tarjeta para reutilizar la infraestructura. |
+| `userInvocable` | `true` | Si una persona puede invocar la habilidad por nombre además del modelo. |
+
+```yaml
+- insert:
+    - id: dsh-plugin-upgrade
+      name: dsh-plugin-upgrade
+      config:
+        skillName: plugin-upgrade-015
+```
+
+El montaje falla en voz alta: un `SKILL.md` ausente, un cuerpo vacío o un frontmatter sin `name` abortan el montaje en lugar de registrar una habilidad vacía.
+
+## Superficies
+
+**Habilidad** — `plugin-upgrade-015` (invocable por el modelo y por la persona por defecto). Cuerpo: el bucle de 6 pasos. Referencias: la tarjeta de versión. Scripts: el detector, incluido dentro del directorio de la habilidad para que las rutas relativas resuelvan.
+
+**CLI** — `dsh-plugin-upgrade-scan`:
+
+```sh
+dsh-plugin-upgrade-scan [--repo <path>] [--json <out.json>] [--seams S3,S8,M1] [--quiet]
+```
+
+| Bandera | Significado |
+|---|---|
+| `--repo <path>` | Repositorio a escanear (predeterminado: cwd). |
+| `--json <out.json>` | Escribe además el informe legible por máquina (`repo`, `scannedAt`, `files`, `hits[]`, `bySeam`). |
+| `--seams S3,S8,M1` | Restringe a costuras concretas. |
+| `--quiet` | Silencia la salida humana (combínala con `--json`). |
+
+Códigos de salida: `0` sin hallazgos de severidad error · `1` al menos uno · `2` uso o fallo de escaneo. Un escaneo limpio es necesario pero no suficiente: el criterio de salida de la tarjeta es una prueba real en un `DSH_HOME` temporal.
+
+## Las diez costuras
+
+| Id | Severidad | Qué cambió en la línea `0.1.5-alpha.1` |
+|---|---|---|
+| `S1` | warn | El formato de sesión es V3; el archivo de log lleva generación (`session.v3.jsonl.zstd`). Las rutas fijas a `session.jsonl.zstd` dejan de funcionar en silencio. |
+| `S2` | warn | `EpochHeader.system` desapareció; el prompt del sistema es `system/message` en el nodo 0 de la superficie. Los lectores necesitan un respaldo estructural. |
+| `S3` | error | `assistant/message` requiere `stream`; sin él la sesión se importa pero no se puede reanudar (`Session.fromRestore` rechaza campos de settlement inválidos). |
+| `S4` | error | `tool/code-dispatch` pasó a llamarse `tool/ptc-dispatch`. |
+| `S5` | error | `ctx.agent` se eliminó; los llamadores reciben el `Agent` explícitamente. |
+| `S6` | error | `Inbox` pasó a ser una interfaz de tipo: ya no se puede construir; usa `agent.inbox` y la forma oficial del fixture. |
+| `S7` | warn | `SubprocessHandle.pid` se eliminó (solo `SubprocessTerminalHandle` conserva `pid`). |
+| `S8` | error | `SessionHandle.read()` ahora devuelve `SessionHandleReadResult`: desenvuelve `.events`. |
+| `S9` | error | La configuración `persona` de `SystemPrompt` pasó a `personaPrefix` / `personaSuffix`. |
+| `M1` | error | Un alias `paths` de `tsconfig` que apunta a un directorio inexistente hace que TypeScript vuelva en silencio a los tipos publicados: la puerta local se vuelve **falsamente verde**. |
+
+`S7`, `S1`, `S2` y `S10` son deliberadamente informativos: tienen coincidencias legítimas (el `pid` de Node, lectores de generaciones antiguas, la propia puerta de eventos adaptativa de un plugin), así que el escáner los reporta como pistas para revisión manual y no como fallos.
+
+## Lo que esto no cubre
+
+- **Otros corredores.** `0.1.1` → `0.1.2` y líneas futuras quedan fuera; la tarjeta está fijada a propósito, porque una tarjeta que se desvía es peor que ninguna.
+- **La ruta de actualización de DSH para usuarios.** Este paquete actualiza el **código fuente del plugin**, no la instalación del harness de un usuario.
+- **Comportamiento de cliente/navegador.** El escáner es estático; una mitad cliente aún necesita una aserción real en el navegador.
+- **Prueba.** Un escaneo limpio es una hipótesis. El criterio de salida es una prueba real en el host (`DSH_HOME` temporal, CLI objetivo, `plugin add <tarball>`, `--dump-config`, más una ida y vuelta de resume para quien escribe logs de sesión).
+
+## Límites de seguridad
+
+- **Escaneo de solo lectura.** La CLI nunca escribe dentro del repositorio escaneado; `--json` escribe solo en la ruta que le indiques.
+- **Sin red ni shell.** El escáner no importa nada fuera de la biblioteca estándar de Node y nunca lanza procesos.
+- **Sin secretos.** Nada en el paquete lee credenciales, tokens de entorno ni datos de sesión.
+- **Receta de prueba en sandbox.** La comprobación real de la tarjeta usa un `DSH_HOME` creado con `mkdtemp`; nunca toca tu `~/.dsh` real.
+
+## Desarrollo
+
+```sh
+pnpm install
+pnpm test                          # node --test (Cordis real + SkillRegistry real)
+pnpm run verify:self-contained     # cada import resuelve dentro del paquete
+pnpm run verify:artifacts          # el tarball incluye la habilidad, la CLI y el patch
+pnpm run check:readmes             # consistencia de los README en cinco idiomas
+pnpm pack
+```
+
+El escáner trae sus propios `fixtures/bad-repo` y `fixtures/good-repo` sintéticos, más un negativo en vivo sobre un repositorio ya adaptado por la ola, de modo que una regresión en el catálogo falla la suite en lugar de llegar a un usuario.
+
+## Temas
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `plugin-upgrade`, `migration`, `skill`, `version-card`, `scanner` (reflejan las keywords de `package.json`; `dsh-plugin` es el canal de visibilidad del ecosistema).
+
+## Familia de plugins DSH de PerryLink
+
+Parte de la familia de plugins DSH de PerryLink: 40 repositorios que cubren sesiones, memoria, permisos, entrega, observabilidad y herramientas para desarrolladores. Explora el catálogo en [perrylink-dsh-catalog.perrylink.workers.dev](https://perrylink-dsh-catalog.perrylink.workers.dev) o el [tema `dsh-plugin`](https://github.com/topics/dsh-plugin).
+
+## Licencia
+
+Apache-2.0 — consulta [LICENSE](LICENSE). Las dependencias de instalación y sus licencias figuran en [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md); no se empaqueta nada de terceros.