# Contributing to Brain-5D

Thank you for your interest in Brain-5D.

Brain-5D is an experimental engineering and research platform. Contributions
should preserve the project's deterministic persistence contracts, typed
boundaries, safety limits and test coverage.

## Code of Conduct

By participating, you agree to follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## Reporting issues

Use the GitHub issue tracker:

https://github.com/Thomas-Heisig/Brain-5D/issues

For bugs, include:

- Brain-5D version or commit;
- operating system;
- Python version;
- exact command;
- minimal reproduction steps;
- relevant logs or traceback;
- whether the problem is deterministic.

Do not publish security-sensitive exploit details in a normal issue. See
[SECURITY.md](SECURITY.md).

## Feature requests

Use the feature-request template and explain:

- the engineering or research problem;
- the expected benefit;
- which existing architecture boundary it affects;
- how success can be measured;
- how it fits the roadmap.

## Pull requests

1. Fork the repository and branch from `main`.
2. Keep the change focused.
3. Preserve backwards-compatible APIs where practical.
4. Add or update tests.
5. Update documentation for public behavior.
6. Run the quality gates before submitting.
7. Complete the pull-request template.

## Type-safety rules

New code should follow the alpha.5 type-safety policy:

- parameterize collections;
- avoid `Any` as a shortcut;
- validate JSON/YAML before narrowing;
- do not add dynamic attributes to neuron objects;
- keep dashboard boundaries typed;
- avoid private network/engine access from HTTP handlers;
- use explicit subprocess argument lists;
- do not suppress broad Pyright/Pylance classes.

## Quality gates

From the repository root in the project virtual environment:

```powershell
.\.venv\Scripts\python.exe -m pytest -v -m "not slow"
.\.venv\Scripts\python.exe -m mypy src
.\.venv\Scripts\python.exe -m black --check src tests scripts
.\.venv\Scripts\python.exe -m ruff check src/ tests/ scripts/
.\.venv\Scripts\python.exe -m pyright
.\.venv\Scripts\python.exe -m pylint --fail-under=9.0 src
git diff --check
```

The CI pipeline runs the same gates on every push/PR:

| Job | Tools | Scope |
|-----|-------|-------|
| `lint-format` | Black, Ruff, Pylint, whitespace | `src/`, `tests/`, `scripts/` |
| `type-check` | Mypy + Pyright (2 scopes) | `src/` |
| `tests` | Pytest (3.11/3.12/3.13 matrix) | `tests/` |
| `build` | `python -m build` + verify | wheel |
| `smoke` | Import/config smoke tests | `src/` + `configs/` |

Alpha.5 introduced a strict Pyright-clean integration scope. Repository-wide
strict Pyright still contains historical findings, therefore pull requests must
at minimum keep all changed/new files free of new strict Pyright/Pylance errors.

When applicable:

```powershell
.\.venv\Scripts\python.exe scripts\verify_v050a5.py
.\.venv\Scripts\python.exe -m pytest -v -m slow
```

## Commit messages

Conventional Commit-style messages are recommended, for example:

- `feat: add structural journal`
- `fix: preserve deterministic restore ordering`
- `docs: update operator guide`
- `test: add structural recovery coverage`
- `chore: update tooling`

## Licensing

Unless explicitly stated otherwise, contributions are submitted under the
project's MIT license.