# Contributing to VibeGate

Thanks for helping improve VibeGate! This guide covers local setup, style rules, and how to add new checks while keeping the system deterministic.

## Development setup

1) Ensure Python 3.10+ is available.
2) Create a virtual environment and install dependencies:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

If you use uv, the equivalent is:

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

## Running tests and checks

```bash
pytest
ruff check .
ruff format --check .
pyright .
```

To apply formatting locally:

```bash
ruff format .
```

## Submitting pull requests

1) Fork the repository and create a feature branch from `main`.
2) Make focused changes with clear commit messages.
3) Run the test and lint commands above before opening a PR.
4) Open a pull request describing what changed, why it changed, and how to test it.

## Adding a new check

1) **Define the config** in `src/vibegate/config.py` (look for existing `*Check` dataclasses and the `VibeGateConfig` tree).
2) **Wire the schema** in `schema/vibegate.schema.json` so the check can be configured from `vibegate.yaml`.
3) **Implement the runner** in `src/vibegate/checks.py` by adding a `run_*` function that returns a `CheckOutcome` and uses `run_tool` for command execution.
4) **Register it in orchestration** in `src/vibegate/runner.py` so it is executed and its artifacts are captured.
5) **Update docs/tests** as needed in `README.md`, `docs/`, and `tests/` to reflect the new check.

## Determinism expectations

VibeGate is designed to be deterministic and reproducible.

- Avoid network access during checks unless the check is explicitly about network behavior.
- Sort or stabilize any list output before emitting findings.
- Record tool versions using existing helpers (e.g., `tool_version`).
- Keep check outputs reproducible: avoid timestamps in user-visible artifacts unless they are part of the canonical evidence format.
- Prefer fixed tool versions and pinned dependencies.

If you are unsure whether a change impacts determinism, call it out in your PR and add coverage in tests.
