Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs(dsh): record host migration review and release evidence boundaries

tt-a1ifae6186f20bf
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 717c449c..f43db7f5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -135,8 +135,10 @@ Use this single checklist in the release PR or its linked release record. Link e
For every Archify release, record the DSH decision in the release PR or its linked follow-up. The Skill source is pinned: releasing Archify or updating `main` does not update the DSH package or existing installations. Use the [DSH release maintenance procedure](integrations/deepseek-harness/README.md#release-maintenance) for commands and host requirements.
- [ ] Assess whether the release needs a DSH update. Record the selected Archify source/version and plugin version, or an explicit deferral with its reason and follow-up. The plugin has its own version sequence; it need not match Archify's version.
+- [ ] For a host-version change or compatibility report, complete the [host migration review](integrations/deepseek-harness/README.md#host-migration-review): pin official source tags/commits and registry identities, inventory the adapter's actual API/configuration touchpoints, and check the target host's compatibility checker (including prerelease semantics). Record applicable changes and gaps in any community reference; a heuristic scan or an accepted peer range is not support evidence. Do not widen peers or add exemptions merely to make installation pass.
- [ ] If syncing, update `integrations/deepseek-harness/release.json` to a full immutable `sourceCommit` and matching `skillVersion`; retain or deliberately update the exact tested DSH host version. Check both `archify/package.json` and `archify/skill-release.json` at that source. Identify any fixes included after the Archify version tag.
- [ ] Commit the adapter inputs before packing. Inspect the actual `.tgz`, including `release.json`, the bundled Skill version/content, license notices, and dependency exclusions; run the package contracts and real distribution acceptance (isolated install, discovery/load, installed Skill smoke, and uninstall). Before plugin publication, complete the DSH workflow's three-platform adapter release gate on the candidate commit and retain its receipts.
+- [ ] Record a support-evidence matrix with the plugin version/tarball digest, bundled Skill source/version, exact host and command source, OS/Node, profile, update mechanism, host running/exited state, date, and evidence link. Separate clean install, load, CLI smoke, same-profile upgrade, and uninstall outcomes. Reuse unchanged evidence under its original identity; CLI acceptance does not validate Electron Desktop or an in-process third-party updater. Keep untested platforms and externally reported failures explicit before changing the support statement.
- [ ] Record publication separately from PR completion: verify the tested npm tarball/version and `archify-dsh-v<plugin-version>` tag, then align the integration README, public README install commands, and `community/packages/archify-dsh.json` with what users can actually obtain. Keep published and pending versions distinct while unpublished; never describe a prepared bundle as publicly available.
- [ ] Treat plugin publication and updates to users' live installations as separate authorized actions. Do not replace an existing version/tag or silently publish as part of the Archify release.
diff --git a/integrations/deepseek-harness/README.md b/integrations/deepseek-harness/README.md
index 9ed7ae79..c1af78f8 100644
--- a/integrations/deepseek-harness/README.md
+++ b/integrations/deepseek-harness/README.md
@@ -30,6 +30,8 @@ The 1.0.0 release gate covers both a clean installation and upgrading the previo
Run the same exact-version install command above in each profile that uses Archify. Updating DSH itself or the Archify repository does not update an already installed plugin.
+For newer-host investigations, see the [host migration review and evidence matrix](#host-migration-review). The CLI checks recorded there do not extend the published support contract to Desktop or other DSH versions.
+
Do **not** use `dsh plugin add tt-a1i/archify`: the repository root is not a DSH package and has no bundle metadata (see [#341](https://github.com/tt-a1i/archify/issues/341)). For an npm download problem, a locally downloaded, integrity-verified `.tgz` can be passed to `dsh plugin --profile web add /absolute/path/to/package.tgz`.
## Host activation configuration
@@ -50,6 +52,76 @@ node integrations/deepseek-harness/scripts/pack.mjs --out /tmp/archify-dsh.tgz -
Distribution acceptance requires Node 22 for the canonical ZIP regression check and pnpm 10. It installs the real pinned DSH runtime and tarball in temporary profiles, checks discovery and loading, runs `doctor` and `demo` through the installed CLI, and checks uninstall. It also installs an integrity-pinned published 0.1.0 tarball, upgrades that same profile to the candidate, checks both Skill identities and loading, exercises the upgraded CLI, and verifies removal preserves the base profile. The full source-version package smoke runs on a temporary copy of the installed Skill because it rewrites bundled examples; the copy preserves pnpm store hard links in the actual installation. Release CI runs this on Linux, macOS, and Windows. Publish only the tested tarball as a new version; tag the corresponding adapter commit as `archify-dsh-v<version>`. After each publication is publicly verified, update the public install examples and community metadata to the verified version. Rebuilding a released adapter uses its tag and recorded Skill commit, not a moving branch.
+## Host migration review
+
+<details>
+<summary>Review procedure, 0.2 host findings, and support-evidence matrix</summary>
+
+Use this review within the [central DSH release checklist](../../CONTRIBUTING.md#release-checklist-dsh-synchronization), without creating another release pipeline. Keep three identities separate: **adapter 1.0.0**, **bundled Archify 3.0.1 / source `7158026e852f3aa6578c741e673b46d7878c92c1`**, and the **exact DSH host**. `release.json.dshVersion` pins this repository's acceptance runtime; it is not a host-enforced minimum version or a promise about later hosts.
+
+For each new target:
+
+1. Record the actual npm package or Desktop binary source, exact version and immutable source commit, Node/OS, profile and command owner. Read the repository rules and existing acceptance results before changing anything. Use only authorized disposable profiles; leave live installations and unrelated configuration alone.
+2. Compare the adapter's consumed surface against both exact official host revisions: bundle metadata, patch parsing/activation and `baseUrl`, filesystem provider configuration and Skill loading, and manifest/dependency compatibility checks. Separate Host, Web Client and standalone Skill CLI APIs. A migration card applies only if this adapter uses that surface; record missing version edges rather than treating a zero-hit scan as a complete audit.
+3. Baseline the existing package contracts. For an approved implementation change, rerun affected checks and real isolated installation, discovery/load, installed CLI smoke, same-profile upgrade and uninstall. Keep dependency cohorts coherent. Do not run a community verifier or its install lifecycle scripts implicitly, widen peer ranges, grant version exemptions, or disable security scanning to obtain a pass.
+4. Attach the tested artifact digest, source/host coordinates, date and results to the release record. Explicitly distinguish reused results from new-head checks and missing native-platform coverage. Change the support statement only after the proposed scope has its own acceptance evidence; publication remains a separate action.
+
+### Review recorded on 2026-10-05
+
+The comparison uses official DeepSeek Harness tags resolved to these commits, not a moving `latest`:
+
+| Host | Official source commit |
+| --- | --- |
+| `0.1.2-rc.1` | [`a66e4702047846cdaa10c66c9d3df3951f5ea70d`](https://github.com/deepseek-ai/deepseek-harness/tree/a66e4702047846cdaa10c66c9d3df3951f5ea70d) |
+| `0.2.0-rc.2` | [`639ed015397290b3745d163aafe02ffee4aa3f84`](https://github.com/deepseek-ai/deepseek-harness/tree/639ed015397290b3745d163aafe02ffee4aa3f84) |
+| `0.2.1-alpha.1` | [`5badb15009ae1756c3afe0ae0cef1faafc290ccc`](https://github.com/deepseek-ai/deepseek-harness/tree/5badb15009ae1756c3afe0ae0cef1faafc290ccc) |
+
+| Actual touchpoint | Finding across those sources | Consequence for this adapter |
+| --- | --- | --- |
+| `package.json` → `dsh.bundle.patch` | The host still accepts a single patch-file string; newer hosts also support a list. See [profile bundle loading](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/boot/app-boot/src/profile.ts). | The existing one-file declaration needs no conversion. |
+| `cordis.patch.yml` → `!!js` / profile `baseUrl` | The [include YAML schema](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/vendor/include/src/index.ts) preserves expression nodes; [loader interpolation](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/vendor/loader/src/config/utils.ts) still evaluates against the context. | Keep package resolution via `createRequire(baseUrl).resolve(...)`. The expression remains host-process code. `lib/index.js` is not the bundle's activation hook. Config dump alone is insufficient; the existing probes actually load the Skill. |
+| `@deepseek-ai/dsh-skill-filesystem` | `inject: ['skills']`, provider registration, `providerName`, `includeDefaultRoots` and `bundledSkillDir` remain available. Newer [provider code](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/skill/skill-filesystem/src/index.ts) resolves the loaded Skill file's real path; the provider source is unchanged between the two reviewed 0.2 tags. | One `archify-plugin` provider with packaged resources still loads in the recorded CLI tests. Watcher disposal and Windows hot replacement require separate native evidence. |
+| Manifest / DSH peer enforcement | The two 0.2 tags have the same [compatibility checker](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/boot/app-boot/src/plugin-compatibility.ts). It checks declared `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*` peers with `includePrerelease: true`; the published adapter has no dependency or peer fields. | There is no DSH peer mismatch to reject here. A successful check does not certify support; no manifest change is justified by this review. |
+
+The actual official npm `@deepseek-ai/dsh-app-boot` checker was also exercised with synthetic peer declarations (no exemptions). These are boundary examples, **not recommended ranges**:
+
+| DSH peer declaration | `0.2.0-rc.2` | `0.2.1-alpha.1` |
+| --- | --- | --- |
+| None, as published | No incompatible peer reported | No incompatible peer reported |
+| `0.1.2-rc.1` or `^0.1.2-rc.1` | Rejected | Rejected |
+| `^0.2.0` | Rejected | Accepted |
+| `^0.2.0-rc.1` | Accepted | Accepted |
+| `>=0.1.0 <0.2.0` | Accepted | Rejected |
+
+In particular, prerelease inclusion does not lower `^0.2.0`'s stable lower bound, while the literal upper bound `<0.2.0` admits `0.2.0-rc.2`. Do not infer a safe support range from its spelling or from one passing install. This review leaves the published manifest and the `0.1.2-rc.1` support contract unchanged.
+
+The adapter has no Web Client, custom Remote service, session-fork hook, toolview renderer, schedule bundle or host native-command integration. Changes to those APIs in the reviewed community cards do not call for adapter changes. The bundled Skill's Node CLI and platform opener are a separate execution surface; they still need native-platform smoke when that surface or its claimed coverage changes.
+
+### Evidence matrix and outstanding work
+
+All rows below concern the **published 1.0.0 tarball**, SHA256 `d009c4709000915e254d709b8f023b20d2cced142cd086e56f03d96baf370b50`, from adapter tag commit `594f6087358610bd16e64e5602976020871b6bff`, containing the Archify snapshot above. These are historical acceptance results, not a new release of this documentation revision.
+
+| Exact host / carrier | Environment and procedure | Evidence / status |
+| --- | --- | --- |
+| Official npm CLI `0.1.2-rc.1` | Linux/macOS/Windows, Node 22, isolated profiles; clean install, load, installed CLI smoke, 0.1.0 → 1.0.0 upgrade, uninstall/base-profile preservation. No running Desktop updater. | Published support baseline: [three-platform tag gate](https://github.com/tt-a1i/archify/actions/runs/37219862967), [release record dated 2026-10-04](https://github.com/tt-a1i/archify/releases/tag/archify-dsh-v1.0.0). |
+| Official npm CLI `0.2.0-rc.2` | macOS, Node 26.8.1, pnpm 11.5.2, isolated `web` profile; clean install, unique discovery/full load, `doctor`/`demo`, uninstall, same-profile 0.1.0 → 1.0.0 upgrade and repeat checks. CLI probes stop before package mutation. | Passed in the 2026-10-05 investigation; [maintainer evidence](https://github.com/tt-a1i/archify/issues/716#issuecomment-5991963398). Reused, not an expansion of support. |
+| Official npm CLI `0.2.1-alpha.1` | Same isolated macOS procedure and Node/pnpm versions as the preceding row. | Passed in the same [2026-10-05 investigation](https://github.com/tt-a1i/archify/issues/716#issuecomment-5991963398); reused, not an expansion of support. |
+| Other OS/Node combinations on these 0.2 hosts; packaged Electron Desktop | Not covered by the two macOS CLI experiments. Reporter: Windows 11 build 26200, Desktop `0.2.0-rc.2`, separate CLI `0.2.1-alpha.1`, updater `1.6.4`; new adapter not yet installed when reported. | Pending native acceptance and exact Desktop binary/command provenance in [#716](https://github.com/tt-a1i/archify/issues/716). No Windows/Desktop success claim. |
+
+The 0.2 experiment installed official npm host dependencies with lifecycle scripts disabled; it tested Skill behavior, not all host native features. It did not rerun the full release gate or source-version package smoke. Its success cannot stand in for Electron packaging, Node 24, or a live third-party updater.
+
+For Desktop evidence, distinguish the standalone npm CLI from the command installed through Desktop's menu. The [official Desktop ownership documentation](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/apps/desktop/README.md#installation-ownership) reserves `desktop` for Electron: only the Desktop-installed command can manage its initialized profile while the application is fully quit. Do not use the standalone CLI or overwrite existing configuration to bypass this boundary. Confirm the binary and command source before any disposable-profile test.
+
+Two external tracks remain open: Windows watcher/rename behavior in [updater #37](https://github.com/Airmetro/dsh-update-checker/issues/37), and the third-party gate's exact rule/file/line evidence in [#716](https://github.com/tt-a1i/archify/issues/716). Watchers are a candidate cause, not a reproduced Windows root cause. Do not equate fault-injected rollback tests with observed data loss, or static package review with clearance of all scanner findings. Native acceptance must separately cover clean install/load, exited-host upgrade/uninstall, and any claimed running-host update path without disabling scanning.
+
+### Community reference boundary
+
+The independent community [dsh-plugin-upgrade-skill reference](https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill/tree/ef075767b476e8000c716a18f848028eebcd5aef) informed the touchpoint inventory; it is not an official DeepSeek compatibility guarantee and was not installed or executed. At that snapshot, its [version index](https://github.com/oh-my-dsh/dsh-plugin-upgrade-skill/blob/ef075767b476e8000c716a18f848028eebcd5aef/skills/plugin-upgrade/references/README.md) has no carded edge for `0.1.7-rc.1 → 0.1.7-rc.2`, `0.2.0-rc.1 → 0.2.0-rc.2`, or `0.2.0-rc.2 → 0.2.1-alpha.1`. The rc.2 field notes are not complete version cards. This targeted official-source review covers Archify's consumed surface across those gaps, not every upstream API.
+
+Its planner is heuristic; its runtime verifier executes installation lifecycle scripts and is POSIX-only. Its release guide still contains a `0.1.1-rc.2` baseline and a broad `<0.2.0` example. Do not copy those examples as this adapter's dependency or support policy. Keep source review, host-checker acceptance, real runtime evidence and publication authorization distinct.
+
+</details>
+
## Invoke
Ask DSH to load Archify by name: