# Community and platform research

This note records the design constraints checked before implementing the
plugin (verified 2026-09-01). Links are kept in the document so the project
can be re-audited when DeepSeek Harness changes during its developer-preview
phase.

## Official Harness contract

The implementation was checked against the `dsh-v0.1.2-alpha.4` developer
preview (commit `4e84901e6471b79ec0338099867ebb4606d12bb5`) and Node
`22.19+`/`24+`; the earlier alpha.3 commit
`dd6322d604e00eec1ba5e0c8541159906a21094a` remains supported. Treat these as
verification baselines, not a promise of long-term API stability.

- [Your first plugin](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/index.md)
  defines the ESM/TypeScript plugin shape: a named `name`, optional `inject`,
  and `apply(ctx, config)`. Contributions registered through Cordis are
  disposed with the plugin fiber.
- [Plugin configuration](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/config.md)
  requires an exported Schemastery `Config` schema when a plugin accepts
  configuration.
- [Package and install a plugin](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)
  defines the installable bundle manifest: `type: module`, `main`, and
  `dsh.bundle.patch`. The patch inserts a row that references the installed
  package by name.
- [Tool authoring reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cookbook/adding-a-tool.md)
  specifies model-facing tool schemas, canonical JSON outputs, bounded
  renderers, cancellation via `exec.signal`, and the `agent.inject` contract.
- The public [agent runtime types](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/agent/src/runtime-types.ts)
  expose `agent/status` (`idle`/`running`) and `agent.runMaintenance()`. The
  plugin uses the idle event only as a debounce trigger; it never blocks a
  model turn with a cleanup operation.

## Community examples reviewed

| Project | Useful pattern | Boundary kept in this MVP |
| --- | --- | --- |
| [dsh-tidy-organizer](https://github.com/LzqSuShi/dsh-tidy-organizer) | Scan → plan → apply → undo, JSONL audit records, collision-safe moves, plain-JS-friendly bundle packaging | Its broad desktop/download classification is outside this plugin's deliberately narrow managed roots |
| [workspace-metabolism](https://github.com/metabolism-tools/workspace-metabolism) | Policy-driven audit/recycle/rollback vocabulary and state outside the workspace | No accidental or unbounded purge; autonomy is an explicit opt-in, with no global daemon or opaque policy inference |
| [dsh-plugin-development](https://github.com/w2112515/dsh-plugin-development) | Minimal plain ESM `index.js`, `dsh.bundle`, isolated-profile verification | This plugin additionally exports a Schemastery config and model tools |

The community projects are references, not dependencies. Their names and
APIs may change; the implementation in this repository is self-contained.

## Decisions derived from the review

1. Ship plain JavaScript in the first release. A Git install fetches sources,
   and avoiding a `prepare` build keeps installation transparent.
2. Keep the bundle patch to one stable row id (`workspace-hygiene`) so a user
   can replace the whole config in a profile overlay.
3. Keep manual mutation two-phase: a read-only plan, a short-lived token, then
   explicit confirmation and revalidation. Autonomous mode still creates the
   same hash-bound plan and revalidates it, but uses the explicit autonomy
   setting as the confirmation boundary.
4. Treat `workspace-artifacts/` as a metadata catalog, not a file repository.
   Its four groups store only each source file's relative path, directory,
   name, purpose, and handling recommendation; source files remain in place by
   default. Recoverable copies, run state, and audit records for archive/delete
   actions stay in the dedicated quarantine and state directories. A
   `to-delete` entry is removed only after an operator confirms deletion (or an
   explicitly enabled autonomous policy authorizes it) and the source passes
   path/protection/fingerprint checks.
5. Expose an explicit `autonomousMode` so researchers can opt into applying
   eligible decisions during idle maintenance. Physical source moves/renames
   additionally require `valuePolicy.organization.moveFiles: true`; permanent
   deletion requires the delete permission. The mode is off by default and
   cannot bypass hard protections, managed roots, budgets, or fingerprints.
6. Return compact structured JSON to the model. Full inventories remain in the
   catalog or behind a bounded `limit`, reducing context pressure.

## Boundary of this revision

Creating a catalog does not imply a global rewrite of the project tree. Manual
mode maintains the index and lets an operator approve each action; autonomous
mode is the explicit choice that lets idle maintenance apply eligible
recommendations. Physical source moves/renames additionally require
`valuePolicy.organization.moveFiles: true`, while permanent deletion remains
delete-policy gated. Experiments should report the information-density benefit
of indexing separately from the benefit (and risk) of physical organization.

## Security note

Harness plugins are trusted same-process code. Installing this package grants
it the host process's filesystem permissions. Review source, pin Git commits,
and use an isolated profile for experiments. Tool approval prompts do not
provide a sandbox for plugin implementation code.