# Contributing

## Start Here

Pick your role and follow the shortest path:

| Role | First read | Second read |
|---|---|---|
| Engineer / contributor | `docs/contributor-map.md` | `CLAUDE.md` |
| Operator / DevOps | `docs/operations-runbook.md` | `docs/architecture.md` |
| Agent builder / integrator | `AGENTS.md` | `docs/agents/quickstart.md` |

Additional reference:

- Full guide: `docs/full-guide.md`
- Security expectations: `SECURITY.md`
- API stability constraints: `docs/api-stability-policy.md`

## Branches and PRs

- Open feature branches from `main`.
- Keep PRs scoped to one change theme (for example: PR6 RAG traceability).
- Link related issue/task context in the PR description.

## Commit Style

Use Conventional Commits with a scope:

```
feat(scope): short imperative description
fix(scope): ...
refactor(scope): ...
test(scope): ...
docs(scope): ...
chore(scope): ...
```

Scope examples: `agent-contract`, `trust-report`, `revocation`, `mcp`, `conformance`, `api`, `hitl`, `export`.

Use `!` for breaking changes:

```
feat(api)!: rename /status/{job_id}/critic field
```

## Local Checks Before Push

Set up the environment once:

```bash
make bootstrap-dev && source .venv/bin/activate
```

Then run the required check suite:

```bash
make qa-fast    # ruff + black check + pytest core + mypy
make qa-hitl    # HITL integration tests (included in qa-fast)
```

Or use pre-commit to run all linters at once:

```bash
pre-commit run --all-files
```

To run tests directly (mirrors what `make qa-fast` does):

```bash
.venv/bin/python -m pytest grantflow/tests/ -x -q
```

## Changelog Rule

- For user-visible behavior changes, update `CHANGELOG.md` under `Unreleased`.
- On release, move `Unreleased` entries into the new version section.

## API Stability

- Review `docs/api-stability-policy.md` before changing endpoint paths, payload fields, or status semantics.
- Breaking API changes require:
  - SemVer major version bump
  - changelog entry with migration note
  - explicit reviewer sign-off in PR
