dsh-composition-doctor: Read-Only Composition Diagnostics and Upgrade Preflight for DeepSeek Harness

What Does It Do?

Composition Doctor is a read-only DSH plugin for DeepSeek Harness that explains observable Cordis and plugin composition risks with concrete evidence. It solves the problem of not knowing what a profile change or upgrade will break, surfacing duplicate Cordis rows, hook-order risks, UI slot and route ownership conflicts, bundle overrides, peer and platform mismatches, and profile drift before you act. It reads only an explicitly selected profile and never edits a real profile or silently changes permissions.

Core Features

• Composition scan: detects duplicate Cordis rows, hook-order risks, UI slot and route ownership conflicts, bundle overrides, peer and platform mismatches, and profile drift.
• Snapshots and diffs: produces redacted, comparable profile snapshots with lockfile hashes, and summarizes added, removed, and upgraded plugins, rows, hooks, UI claims, peers, and platforms.
• Upgrade preflight: rehearses a target DSH upgrade in an isolated temporary profile, recording a validated exact version reference without installing or running lifecycle scripts.
• Evidence modes: reports declare whether findings come from allow-listed manifest and patch metadata, a public dump-config composition result, or a successful isolated runtime observation.
• Read-only settings page: the Web Settings page reads the latest local report, shows a conflict graph, and exports JSON or Markdown, with no repair, install, or uninstall action.
• Exit-code control: scan exit codes can be tied to diagnostic severity, defaulting to never failing on warnings or errors so it fits into automation.

How to Use This Plugin?

After enabling it in DSH, run a scan against a chosen profile; the report is written only to the directory you request. To make the same report visible to the read-only Settings page, opt in explicitly and emit both JSON and Markdown so the Web route has its report file. Before an upgrade, take a snapshot of the current state, then use a diff to compare before and after, or run a preflight to rehearse the target version in an isolated temporary profile. Never use a profile directory, an environment file location, or any directory holding keys or tokens as a report directory. If no compatible public DSH CLI is available, the scan falls back to static mode and records a warning.

How to Troubleshoot This Plugin?

A static fallback warning in the report means no compatible public DSH CLI was available, so findings cover only manifest and patch metadata and are not proof of the final runtime composition. If a report shows an older evidence label, it was written under an earlier schema; new reports never emit that label. Malformed arguments return exit code 2 while operational failures return 1, which helps separate a mistyped command from an environment problem.