# Contributing

## Current stage

The local Release Candidate portion of Stage 7 is complete, but the overall
Stage 7 exit gate is not closed until its authorized public Tag/Release checks
are completed. Contributions must target the current unique stage in
`docs/dsh-control-plane-roadmap.md` and include its acceptance criteria.
Public publication and an awesome listing remain separate actions requiring
explicit authorization.

## Before changing files

Read:

- `AGENTS.md`;
- `docs/dsh-control-plane-roadmap.md`;
- the DSH Cordis and Plugin contract for the target version;
- the detailed document for the active stage.

Protect unrelated worktree changes. Do not use destructive reset or checkout
commands as a cleanup shortcut.

## Public-data rule

Use synthetic IDs, placeholder paths, and redacted fixtures. Put machine-local
values only in ignored `agentworkos.local.toml`. Never use a real Session,
private knowledge export, or raw local log as a test fixture.

## Implementation rules

- Keep runtime lifecycle operations behind allowlisted adapters.
- Keep Host/Client messages JSON-safe and minimal.
- Give optional features independent failure boundaries and disposers.
- Add cleanup, disable, unload, and recovery tests with every integration.
- Do not claim support for a DSH version without an isolated verification.

## Pull requests

Pull requests should state:

- the active roadmap stage;
- the user-visible result;
- the files and ownership plane changed;
- checks and isolated runtime tests run;
- privacy scan and Review Pack status;
- known limitations and recovery instructions.

Do not publish or submit to `awesome-dsh-plugin` from a development change.
Those actions require the separate release stage and explicit authorization.