# Contributing to dsh-tool-chaos

Thank you for helping make DSH resilience testing reproducible and safe.

## Before opening code

- Search existing issues and discussions.
- For a new fault action, public schema change, report-schema change, or DSH pipeline assumption, open a design issue first.
- Small fixes, tests, documentation, compatibility updates, and new narrow examples may go directly to a pull request.

No contributor license agreement is required. By contributing, you agree that your contribution is licensed under this repository's MIT License.

## Development setup

Requirements: Node.js 22.19+ or 24+, npm, and Git. A real DSH installation is required only for the consumer smoke gate.

```bash
npm install
npm run typecheck
npm test
npm run verify
npm pack --dry-run
```

Run the full local gate:

```bash
npm run check
```

## Design rules

1. **Deterministic first.** Do not use runtime randomness in the rule engine. Preserve the documented seed material and dry-run parity.
2. **Fail closed.** Invalid configuration must reject activation rather than silently broaden a target.
3. **Narrow blast radius.** Default off, default dry-run, one injection per rule, explicit opt-in for exact `*`.
4. **DSH-native.** Use documented Cordis/tool pipeline seams; do not patch the Agent loop.
5. **Cooperative cancellation.** Await delegated work to quiescence and restore replaced signals in `finally`.
6. **Evidence, not claims.** Behavior changes require a deterministic scenario, test, and expected decision/report fields.
7. **No secrets.** Tests, fixtures, logs, screenshots, and issue reports must contain synthetic data only.

## Change layout

- `src/options.ts`: public config and direct-call validation.
- `src/core.ts`: deterministic, runtime-independent engine.
- `src/runtime.ts`: thin DSH pipeline adapter.
- `src/reporter.ts`: stable JSONL evidence stream.
- `bin/`: machine-facing CLI and autonomous orchestration.
- `plugins/`: Codex plugin and Agent Skill.
- `tests/`: Node built-in tests.

Keep changes in the narrowest layer. Do not put DSH runtime dependencies into `src/engine.ts` or pure engine tests.

## Tests expected by change type

| Change | Required evidence |
|---|---|
| matcher/scheduler/sampling | deterministic unit test and dry-run parity |
| DSH adapter | fake-context adapter test and real consumer smoke when API-facing |
| cancellation | abort-before, abort-during, quiescence, signal restoration |
| CLI/report | fake executable integration test and JSON schema assertions |
| Skill/prompt | repository verification plus one fixture requirement |
| documentation only | link/path validation and command review |

## Pull requests

Keep the PR focused. Include:

- problem and user impact;
- exact DSH contract relied upon;
- safety/blast-radius analysis;
- reproducible scenario;
- tests run and results;
- compatibility implications;
- screenshots only when UI-visible.

Generated text is welcome only when the author has reviewed it, run the commands, and can defend the design. Do not submit unverified bulk-generated files.