# Contributing to Soluna Harness

Thanks for helping make agent-driven software engineering more reliable and auditable.

## Before you start

- Search existing issues and discussions before opening a new one.
- Use GitHub's private vulnerability reporting for security issues.
- Keep changes focused. Large architecture changes should begin with an issue or discussion.
- Do not include credentials, private repository content, or real run artifacts in issues or fixtures.

## Development setup

Requirements:

- Node.js 20 or newer
- npm
- Git

```bash
git clone https://github.com/Leopold-Fitz-AI/soluna-harness.git
cd soluna-harness
npm ci
npm run check
npm run lint
npm test
```

The normal validation sequence is:

```bash
npm run check
npm run lint
npm test
npm pack --dry-run
```

Tests must not modify real Codex or DeepSeek Harness profiles. Use temporary `CODEX_HOME`, `DSH_HOME`, `XDG_STATE_HOME`, and fixture repositories.

## Project map

- `src/orchestrator.ts` — orchestration state machine and role lifecycle
- `src/scheduler.ts` — packet DAG validation and scheduling
- `src/context.ts` — context compilation and secret redaction
- `src/workspace.ts` — Git workspace evidence
- `src/verification.ts` — structured verification execution
- `src/storage.ts` — persistent state and locking
- `src/server.ts` — MCP tool surface
- `dsh/plugin.js` — DeepSeek Harness Cordis integration
- `tests/` — unit, integration, and installed-runtime coverage
- `docs/` — architecture and acceptance evidence

## Pull requests

A good pull request:

1. explains the user-visible problem and chosen design;
2. includes focused tests for behavioral changes;
3. preserves strict schemas and fail-closed behavior;
4. documents new commands, policy, tools, or safety boundaries;
5. reports the exact validation commands run;
6. avoids unrelated formatting or dependency churn.

For orchestration changes, include state-transition and persistence implications. For installer changes, cover idempotence, ownership, rollback, and user-modified state. For process execution, use argv arrays and explicit cancellation—never interpolate model output into a shell command.

## Commit style

Use concise, imperative commit subjects, for example:

```text
Add DSH profile ownership tracking
Reject overlapping packet ownership
Document cooperative execution boundary
```

## License

By contributing, you agree that your contributions will be licensed under the project's MIT License.