# Contributing

Thank you for helping improve Swarm House. This repository is a self-contained
design proposal for an on-prem data platform for autonomous drone swarms — all
contributions must follow the rules in [`AGENTS.md`](AGENTS.md).

## TDD first (required)

Every change to executable code ships with tests **before** or **alongside** the
implementation — never as an afterthought.

1. **Red:** write or extend a failing test that captures the behaviour you need.
2. **Green:** implement the smallest change that makes it pass.
3. **Refactor:** clean up without weakening the test.

The CI pipeline enforces this:

| Gate | When it runs |
| --- | --- |
| `python scripts/check_docs.py` | Every push/PR (`docs-verify` job) — links, glossary anchors, readability rules ([ci-rules](docs/improvement/ci-rules.md)) |
| `pytest tests/` | Every push/PR (`verify` job) |
| `RUN pytest tests/` in the simulator Docker build | Every `docker build` — a red test blocks the image |
| Smoke flight + DuckDB assertion | Every push/PR |
| Trivy scan | After verify passes |

Test locations:

- `simulator/tests/` — Python unit tests (SQL gate, broadcast codec, writer layout, flight kinematics)
- Prototype: `npm run build` / `tsc --noEmit` before UI changes

## Local development

### Fast inner loop (Compose)

```bash
cd simulator
pip install -r requirements.txt
pytest tests/ -q                          # run tests first
DRONE_COUNT=5 docker compose up --build   # writes to ../var/t1
```

### Full ground miniature (k3d + Terraform + Flux)

```bash
ansible-playbook infra/ansible/sim-cluster.yml
cd infra/terraform/sim-env && terraform init && terraform apply
cd ../ground && terraform init && terraform apply
cd ../../prototype && npm install && npm run dev   # press "go live"
```

Shared data directories (gitignored, created automatically):

| Path | Tier | Contents |
| --- | --- | --- |
| `var/t1/` | T1 live lake | In-flight Parquet from Compose or k3d fleet |
| `var/t3/` | T3 warehouse | Offloaded historical partitions |

Override with `SWARM_T1_DIR` / `SWARM_WAREHOUSE_DATA` / `SWARM_SIM_DATA` env vars.

### Prototype only

```bash
cd prototype && npm install && npm run dev
```

## Commit messages

Conventional Commits only:

```
feat: add warehouse offload cron schedule variable
fix: reject COPY statements in the SQL gate
docs: clarify WireGuard vs SSH layering
test: cover broadcast frame roundtrip
```

Never include AI tool references, `Co-authored-by` trailers for assistants, or
identifying names of people, companies, or locations.

## Pull request checklist

- [ ] Tests added or updated; `pytest tests/ -q` passes locally
- [ ] `docker build` in `simulator/` succeeds (test stage included)
- [ ] Documentation updated if behaviour or boundaries changed
- [ ] **ADR added** if the change alters an architectural boundary, contract, or trade-off (see [`docs/adr/`](docs/adr/))
- [ ] English only; no identifying references
- [ ] Conventional commit message

## Decisions

Architectural decisions are recorded chronologically as ADRs in
[`docs/adr/`](docs/adr/). Read [`docs/adr/README.md`](docs/adr/README.md) before
changing a boundary or contract; add a new ADR (from
[`docs/adr/TEMPLATE.md`](docs/adr/TEMPLATE.md)) rather than editing an Accepted
one when you reverse course.

## Questions

Open design questions live in [`docs/09-open-questions.md`](docs/09-open-questions.md).
Architecture boundaries are documented in [`docs/06-environments.md`](docs/06-environments.md#iac-boundaries).