dsh-jj-vcs
Jujutsu version control for DeepSeek Harness agent teams
中文 ·
`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 add github:bingfengaaaaa/dsh-jj-vcs#v0.1.1
dsh --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 /scripts/verify-jj-compat.mjs --repo
```
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 /scripts/jj-task.mjs start \
--repo \
--destination \
--workspace \
--agent \
--task \
--base
```
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 /scripts/jj-task.mjs finish \
--workspace-root \
--workspace \
--agent \
--task \
--expected-change
```
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).