## AI Agent Quality Gates

These rules are **mandatory** for any AI agent changing this repo.

### Required checks (definition of done)

- **Tests pass**: Run `cargo test`.
  - If anything fails, either fix and re-run, or list failing tests and why they weren’t fixed.

- **Clippy clean**: Run `cargo clippy --all-features -- -D warnings`.
  - Code must build with **zero Clippy warnings**.
  - If some pre‑existing/externally caused warnings remain, minimize new ones and document what’s left and why.

- **Formatting**: Run `cargo fmt` on edited code; don’t fight `rustfmt`.

- **Type check**: `cargo check` (or equivalent CI check) must succeed.

- **Docs build**: `cargo doc --no-deps` must succeed for modified crates.

### When touching dependencies or critical code

- **Dependencies**: If you change `Cargo.toml` / `Cargo.lock`, prefer to run:
  - `cargo audit` (vulns) and, if configured, `cargo deny` (policy).
  - If they report issues you can’t fix, document which remain and why.
- **No unused deps**: Don’t leave unused crates in `Cargo.toml`. If `cargo udeps` is used, don’t add new unused deps (or explain clearly why they remain).
- **Unsafe / perf‑sensitive code**:
  - Where already used in this repo, prefer `cargo miri test` for `unsafe` and `cargo bench` (or project benchmarks) for perf‑critical changes. Avoid regressions.

These extra tools are not required for every tiny change, but **never break existing CI/tooling** and prefer to run them when working in their area.

GitHub Actions CI enforces these gates by running `cargo fmt --all -- --check`, `cargo clippy --all-features -- -D warnings`, and `cargo test` on every push and pull request targeting `main`.

### What every agent must report

In the final message for any task, explicitly state:

- Whether tests were run and passed.
- Whether Clippy was run and produced zero warnings.
- Whether any additional Rust checks above were run, and if not, why they weren’t needed.

### Commit message rules (strict)

All commits to this repo **must** use this format:

- **Subject line**:
  - Format: `type(scope): short summary`
  - `type` (one of): `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `chore`, `build`, `ci`.
  - `scope` is optional but recommended; use a short, lowercase identifier (e.g. `inputs`, `html`, `types`, `cli`).
  - Summary in **imperative mood**, max ~72 characters, no trailing period.

- **Body (optional but recommended)**:
  - Wrap at ~72 columns.
  - Explain **what** and especially **why**, not just restating the diff.
  - Use paragraphs or bullet points; leave one blank line after the subject.

- **Footer (optional)**:
  - Use for issue references and breaking changes.
  - Examples:
    - `Refs #123` / `Fixes #123`
    - `BREAKING CHANGE: description of the breaking behavior`

- **General rules**:
  - English only; no emoji in the subject.
  - One logical change per commit where practical.
  - Do **not** bypass hooks; if a hook fails, fix the issue and re-commit instead of forcing.

