# Contributing

Thanks for taking a look. This is a small package with a deliberately narrow integration
surface, so changes should stay close to the official Agent Teams behavior.

## Development setup

* Node.js 22+
* DeepSeek Harness Desktop `0.2.1-rc.2` for the installed-runtime contract tests
* No package dependencies; `npm test` uses Node's built-in test runner

```bash
npm test
npm run build
npm run verify
```

Installed-runtime tests look for the Electron `app.asar` at the default macOS path. Set
`DSH_ASAR` to another path, or let those tests skip when no installation is available.

## Runtime graph

`lib/` is the source of truth. The Host loads `runtime/<hash>/`, which is generated:

```bash
npm run build
```

The build hashes every file in `lib/` into a new immutable graph, rewrites the package
exports, and rewrites `cordis.patch.yml`. Commit the generated graph together with both
updated files. Do not edit `runtime/<hash>/` by hand, and do not point the patch or exports
at `lib/` directly.

## What to keep out of commits

* session logs, raw `request/header` dumps, and probe output;
* profile snapshots, `pnpm-lock.yaml` backups, and `cordis.patch.yml` copies from a personal
  profile;
* absolute home paths, usernames, email addresses, hostnames, tokens, and API keys;
* `.diagnostics/`, `docs/evidence/`, `docs/rollback/`, and the author's internal notes.

The repository `.gitignore` excludes the known local directories, but please check
`git diff --cached` before committing.

## Design expectations

* Reuse official handlers and transitions; do not copy the board or continuation lifecycle.
* Keep authority checks based on actual `parentSession` lineage.
* Fail closed when a private seam changes; report the reason instead of degrading silently.
* Do not add a second tool with the same name or a hidden model fallback.
* Add a test for every new contract, authority boundary, or version-sensitive seam.
* Keep the three components independently switchable and pointing at the same graph.

## Commit and PR notes

Describe the DSH version you tested against, the tests you ran, and any live verification.
If a path is covered only by contract tests, say so explicitly.