@openworkproof/dsh-plugin

Readme

# OpenWorkProof for DeepSeek Harness

Add prior authorization, execution evidence, independent rechecking, and human
acceptance to DeepSeek Harness code changes.

[中文](README_zh.md) · [Core protocol](https://github.com/dengyier/OpenWorkProof)

## Current status

This is a community plugin discovered through the official DeepSeek Harness
`dsh-plugin` GitHub topic. It is maintained independently and is not an official
DeepSeek product or endorsement.

```text
plugin: 0.1.0
DeepSeek Harness: exactly 0.1.1-rc.2
OpenWorkProof Core: 1.4.0 public release
customer_adoption: not_evidenced
deepseek_endorsement: not_evidenced
```

The tested protocol dependency is OpenWorkProof Core `1.4.0`. The release
evidence proves the packaged integration behavior described below; it does not
prove production use, customer adoption, or DeepSeek endorsement.

A local preflight installs the exact plugin tarball and OpenWorkProof wheel into
fresh environments. It drives real Harness tool calls, an external Verifier,
host restart, composed offline delivery verification, and tamper rejection.
The generated manifest binds both artifacts and repository revisions. This is
not external reproduction, production use, customer adoption, or DeepSeek
endorsement.

## Why this exists

When an agent says that a change is complete, a customer still needs to know:

- who authorized it;
- what repository, paths, tools, quota, and test profile were in scope;
- whether the patch and tests belong to the same execution;
- what an independent verifier actually checked;
- who accepted or rejected the final delivery.

OpenWorkProof does not make an agent smarter. It makes declared agent work
independently reviewable.

## Two modes

### Not configured, then Audit

The installed bundle is disabled by default and reports no evidence; treat that
state as `NOT_CONFIGURED`. After an operator explicitly enables the plugin and
provides a private case directory, Audit is the default operating mode. Audit
observes the Harness tool pipeline and asks the Python bridge to sign an
`ObservationRecord`. It does not block existing native tools and never turns an
action without prior authorization into an `ActionReceipt`.

### Enforce

Enforce must be enabled explicitly. It denies the known native mutation
surfaces `write`, `edit`, `bash`, `pwsh`, `str_replace_editor`,
`cordis_define`, `cordis_run`, `cordis_stop`, and `cordis_undefine`, then
exposes only two consequential tools:

- `owp_apply_patch`: applies one pre-authorized, bounded patch;
- `owp_run_tests`: runs the frozen test profile through an external Verifier
  boundary.

Async authorization is followed by a monotonic final guard. Missing, replayed,
or mismatched decision state fails closed.

## Install

### npm package

The public package is available on
[npm](https://www.npmjs.com/package/@openworkproof/dsh-plugin/v/0.1.0). Install
the exact release:

```bash
dsh plugin --profile owp-preview add @openworkproof/dsh-plugin@0.1.0
dsh --profile owp-preview --dump-config
```

### GitHub source

The tagged source can also be installed directly:

```bash
dsh plugin --profile owp-preview add \
  github:dengyier/openworkproof-dsh-plugin#v0.1.0
```

This path builds TypeScript through the package `prepare` script. With pnpm 10
or later, the profile may require an explicit `allowBuilds` entry for
`@openworkproof/dsh-plugin`. Prefer the prebuilt npm package when that policy
cannot be changed.

### Local release tarball

To reproduce or inspect the package before installation:

```bash
pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm build
pnpm pack --pack-destination dist

dsh plugin --profile owp-preview add \
  /absolute/path/openworkproof-dsh-plugin-0.1.0.tgz
dsh --profile owp-preview --dump-config
```

The installed bundle is disabled (`NOT_CONFIGURED`). For an already prepared
private case directory, explicitly apply the packaged Enforce profile:

```bash
export OWP_CASE_DIRECTORY=/absolute/path/to/private-case
dsh --profile owp-preview \
  --patch "$DSH_HOME/profiles/owp-preview/node_modules/@openworkproof/dsh-plugin/profiles/owp-verified.patch.yml"
```

The case must contain no Manager, Verifier, or Acceptor private key. General
case initialization, the independent Verifier service, and external Acceptor
workflow remain integration responsibilities in this V0.1 candidate.

## Five-minute release preflight

```bash
OWP_CORE_ROOT=/absolute/path/to/OpenWorkProof-at-v1.4.0 \
  node scripts/live-preflight.mjs \
  dist/openworkproof-dsh-plugin-0.1.0.tgz \
  /absolute/path/openworkproof-1.4.0-py3-none-any.whl \
  dist/preflight-manifest.json
```

The preflight installs both packed artifacts into temporary clean environments,
checks the effective profile, exercises real Harness actions and an external
Verifier across process restarts, verifies the composed delivery in a second
process, rejects a tampered package, and writes a revision-bound manifest.
`OWP_CORE_ROOT` must name the exact Core source checkout that supplies the live
fixture and its isolated `.venv`; the script does not guess a local worktree.
The temporary profile is removed on exit. No package is published and no remote
service is contacted.

## User commands

With an open case, the plugin registers:

```text
/owp-status
/owp-evidence
/owp-verify
/owp-export
```

`/owp-verify` accepts no free-form claim. It submits the exact correlated
`owp_apply_patch` receipt to the core bridge for independent repository,
artifact, frozen-test, and causal-ledger readback. `UNKNOWN` and `REFUTED`
results remain non-success and never become `VERIFIED` merely because a result
file exists.

`/owp-export` prepares the full customer-private evidence package needed for
offline replay. Verify that package in a separate process with:

```bash
owp dsh-delivery-verify /absolute/path/to/export
```

Verification and acceptance are deliberately separate:

```text
VERIFIED != ACCEPTED != PAID/SETTLED/LEGAL AUDIT/ADOPTION
```

The agent has no acceptance-signing surface. Manager and Acceptor private keys
remain outside Harness.

## Data and process behavior

The plugin starts `owp dsh-bridge --stdio`, exchanges closed JSONL messages,
observes declared tool metadata and durable event identifiers, and may write
signed observations into the case evidence root. One-use decision tokens live
only in memory.

It does not collect hidden reasoning, arbitrary environment variables, or
files outside the frozen case. It does not hold funds, execute payments, or
accept work for a human. DeepSeek Harness and other installed plugins may have
their own network and telemetry behavior.

## Uninstall and evidence retention

```bash
dsh plugin --profile owp-preview remove @openworkproof/dsh-plugin
```

Uninstalling the profile dependency does not delete ledgers, evidence roots,
session events, exports, or public keys. Archive and verify any required
delivery evidence before deleting it.

## Compatibility and limitations

- this is a community plugin, not an official DeepSeek distribution;
- exact tested host: DeepSeek Harness `0.1.1-rc.2`;
- V0.1 supports one repository and serial `owp_apply_patch` / `owp_run_tests`;
- Audit cannot prove side effects outside the observed tool pipeline;
- different keys do not by themselves prove organizational independence;
- Codex, ChatGPT, and Claude Code are future adapters, not current support;
- the local fixture is not a zero-configuration production initializer.

See [SECURITY.md](SECURITY.md) and the core
[integration guide](https://github.com/dengyier/OpenWorkProof/blob/main/docs/integrations/deepseek-harness.md).

## License

Apache-2.0. See [LICENSE](LICENSE).