dsh-jj-vcs

Readme

<p align="center">
  <img src="docs/assets/dsh-jj-vcs-hero.jpg" alt="DeepSeek Harness and Jujutsu connected by a change graph" width="100%">
</p>

<h1 align="center">dsh-jj-vcs</h1>

<p align="center"><strong>Jujutsu version control for DeepSeek Harness agent teams</strong></p>

<p align="center">
  <a href="README.zh.md">中文</a> ·
  <a href="https://github.com/bingfengaaaaa/dsh-jj-vcs/releases/latest"><img alt="GitHub release" src="https://img.shields.io/github/v/release/bingfengaaaaa/dsh-jj-vcs"></a>
  <a href="https://github.com/bingfengaaaaa/dsh-jj-vcs/actions/workflows/verify.yml"><img alt="Verification status" src="https://github.com/bingfengaaaaa/dsh-jj-vcs/actions/workflows/verify.yml/badge.svg"></a>
  <img alt="Jujutsu 0.44.0" src="https://img.shields.io/badge/Jujutsu-0.44.0-5c4ee5">
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</p>

`dsh-jj-vcs` gives DeepSeek Harness agents a simpler way to work with version history. Each agent receives its own Jujutsu workspace and change. The skill records repository operations before and after a task, checks ownership at handoff, and limits remote publication to the exact bookmark that was reviewed.

Git still stores the repository, and GitHub still hosts it. Agents use `jj` for history-changing commands instead of coordinating a staging index, branch checkout, and raw Git mutations.

> [!IMPORTANT]
> This is an independent community project, not an official DeepSeek release. Its maintained command rules are audited against exactly `jj 0.44.0`.

## Why Jujutsu fits agent teams

Jujutsu treats the working copy as a change, so an agent can edit files and inspect the result without a separate `git add` step. A change ID usually stays the same when a commit is rewritten, including normal rebases and description edits, while the commit ID continues to identify an exact snapshot.

That distinction is useful when several agents work at once. A coordinator assigns one durable change ID to each task, gives every worker a separate workspace, and checks that same identity when the work returns. Repository mutations also enter Jujutsu's operation log, which makes before-and-after receipts and recovery practical.

The plugin adds the DSH-specific rules around those JJ features:

| Need | What the skill does |
|---|---|
| Separate agent work | Creates one external JJ workspace and one change per agent |
| Clear ownership | Stores the task and agent in the change description and verifies both at handoff |
| Auditable mutations | Records operation IDs before and after task setup and completion |
| Controlled publication | Separates local editing, shared-history changes, and remote-visible actions |
| Concurrent safety | Rejects conflicts, divergent changes, shared change ownership, and unexpected workspaces |
| Windows correctness | Detects materialized Git symlinks and workspace aliases that can produce false file changes |

## Quick start

### Requirements

| Component | Maintained baseline |
|---|---|
| DeepSeek Harness | `0.1.1-rc.1` skill registry and Profile Bundle interfaces |
| Jujutsu | exact `jj 0.44.0` |
| Node.js | `>=22.19.0` |
| Git | repository backend and read-only interoperability |

### Install the reviewed release in DSH

```sh
dsh plugin --profile <profile> add github:bingfengaaaaa/dsh-jj-vcs#v0.1.1
dsh --profile <profile> --dump-config
```

The release tag keeps the command readable. For a fully immutable profile, replace `v0.1.1` with the exact commit ID shown on the GitHub release page after reviewing it.

For local plugin development, run the same commands from the parent directory with `./dsh-jj-vcs` as the package source.

The package contains plain JavaScript and has no `prepare`, `preinstall`, or `postinstall` script. Installation registers one immutable skill provider on DSH's existing `ctx.skills` service.

> [!NOTE]
> Installing the plugin does not install JJ, initialize a repository, change Git remotes, or touch credentials. Repository initialization and remote-visible operations remain separately authorized actions.

### Check JJ before using the skill

Run the installed version and help first. The local help text is authoritative for that installation.

```sh
jj --version
jj help
node <skill-dir>/scripts/verify-jj-compat.mjs --repo <repository>
```

If the JJ version differs from `0.44.0`, use the [upgrade verification procedure](skills/dsh-jj-vcs/references/version-and-upgrades.md) before changing repository history.

## A multi-agent task in practice

The coordinator chooses an explicit base revision and creates the worker's workspace outside the repository directory:

```sh
node <skill-dir>/scripts/jj-task.mjs start \
  --repo <coordinator-workspace> \
  --destination <external-worker-directory> \
  --workspace <task-agent-name> \
  --agent <agent-id> \
  --task <task-id> \
  --base <explicit-revset>
```

The command returns a JSON receipt containing the workspace root, task owner, change ID, commit ID, and operation IDs from before and after creation. The durable `changeId`, rather than the changing commit ID, identifies the assignment.

The worker edits files normally and reviews the change with `jj st` and `jj diff`. There is no staging step. Before accepting the handoff, the coordinator runs:

```sh
node <skill-dir>/scripts/jj-task.mjs finish \
  --workspace-root <external-worker-directory> \
  --workspace <task-agent-name> \
  --agent <agent-id> \
  --task <task-id> \
  --expected-change <change-id>
```

The finish receipt verifies the workspace, task, owner, change identity, operation IDs, conflicts, and divergence. The full procedure is documented in [multi-agent workspaces](skills/dsh-jj-vcs/references/multi-agent-workspaces.md).

## Permissions, conflicts, and recovery

The skill separates four permission levels: read-only inspection, task-local changes, shared local history, and remote-visible operations. A task authorization covers ordinary edits in the assigned workspace. Rewrites that affect shared history need task-specific approval. Fetch, push, GitHub changes, and protection-bypass flags need explicit remote authorization.

Agent-facing history changes use JJ. Git remains available as the backend, for read-only interoperability checks, and for repository-owned test scripts. See [permissions and remotes](skills/dsh-jj-vcs/references/permissions-and-remotes.md) before moving bookmarks or publishing, and [recovery and conflicts](skills/dsh-jj-vcs/references/recovery-and-conflicts.md) before undoing or restoring operations.

## Verify the package

Run the package, provider, compatibility, and workspace checks from a repository checkout:

```sh
npm run verify
npm test
npm pack --dry-run --json
node skills/dsh-jj-vcs/scripts/verify-jj-compat.mjs --skip-repo
node skills/dsh-jj-vcs/scripts/verify-jj-task.mjs
```

GitHub Actions runs the package and JJ suites on Linux and Windows. A separate scheduled probe checks candidate JJ releases without changing the audited baseline.

## One skill, two package entry points

DSH loads the Profile Bundle through `cordis.patch.yml` and `index.js`. Codex packaging reads `.codex-plugin/plugin.json`. Both entry points use the single maintained skill in [`skills/dsh-jj-vcs`](skills/dsh-jj-vcs), so behavior does not drift between copies.

The Codex manifest is included for packaging and local development. A remote Codex marketplace command will be documented after that installation method has been tested with this repository.

## Maintenance and provenance

[`compatibility.json`](skills/dsh-jj-vcs/compatibility.json) is the machine-readable JJ command baseline. Upgrading JJ requires review of the official release notes and installed help, an upgrade-mode probe, updates to affected references and tests, and a final exact-version pass. Release details are in [MAINTAINING.md](MAINTAINING.md); proposed changes follow [CONTRIBUTING.md](CONTRIBUTING.md).

The original design audit covered [`nshcr/jj-codex`](https://github.com/nshcr/jj-codex), [`techsaint/jj-vcs-skills`](https://github.com/techsaint/jj-vcs-skills), and [`clementpoiret/skills`](https://github.com/clementpoiret/skills). Their repositories informed the review, but no candidate file is vendored or copied into this project.

Artwork sources and license notices are recorded in [the asset attribution](docs/assets/ATTRIBUTION.md).