---
name: rust-quality-gate
description: "PM-invocable protocol for running and interpreting Rust quality gates in the trusty-tools monorepo: fmt, clippy, and test in strict sequence before any merge"
user-invocable: false
disable-model-invocation: true
version: 1.0.0
category: toolchain
author: Claude MPM Team
license: MIT
progressive_disclosure:
entry_point:
summary: "Three-gate quality sequence (fmt → clippy → test) that must pass before any PR merge in a Rust workspace"
when_to_use: "Before any PR merge, after implementation work, or when user says 'check quality', 'run tests', 'verify', or 'is this ready to merge'"
quick_start: "1. cargo fmt --check 2. cargo clippy --workspace --all-targets -- -D warnings 3. cargo test -p <crate> — stop on first failure"
token_estimate:
entry: 130
full: 1600
context_limit: 750
tags:
- rust
- quality
- testing
- clippy
- fmt
- cargo
- ci
- monorepo
- qa
requires_tools: []
---
# Rust Quality Gate Protocol
## When to Invoke
Invoke this protocol when:
- Any implementation task completes and code changes are ready to commit
- User asks "check quality", "run tests", "run clippy", "is this ready", or "verify"
- Before creating a pull request or merging to main
- After modifying a shared library crate (`trusty-common`, `trusty-mcp-core`, `trusty-embedder`, `trusty-symgraph`)
- After the rust-qa agent delivers a work product
## The Three-Gate Sequence
Run gates in this exact order. **Stop on first failure — do not proceed to the next gate.**
### Gate 1: Format Check (fastest — always run first)
```bash
cargo fmt --check
```
**Pass**: No output, exit code 0.
**Fail**: Lists files with formatting differences. Fix with:
```bash
cargo fmt
```
Then re-run `cargo fmt --check` to confirm clean.
**Why first**: Format failures are trivially fixable. Running it first avoids wasting clippy and test time on unformatted code.
### Gate 2: Clippy Lint Gate
```bash
cargo clippy --workspace --all-targets -- -D warnings
```
**Pass**: No warnings emitted, exit code 0.
**Fail**: One or more `error[clippy::]` lines. Fix each warning the compiler reports. Common patterns:
```bash
# Check a single crate faster during iteration
cargo clippy -p trusty-search -- -D warnings
# Check with a specific feature enabled
cargo clippy -p trusty-common --features axum-server -- -D warnings
```
**open-mpm exception**: `open-mpm` has 142 pre-existing clippy errors at HEAD (tracked separately). These errors **do not block other work**. When running workspace-wide clippy and `open-mpm` fails, confirm whether the failures are confined to `open-mpm` only:
```bash
# Run clippy on everything except open-mpm to confirm other crates are clean
cargo clippy --workspace --all-targets -- -D warnings 2>&1 | grep -v "open-mpm"
```
If all errors are in `open-mpm`, treat the gate as passing for the purpose of non-open-mpm work.
### Gate 3: Test Gate
**Single-crate (fast — use during iteration):**
```bash
cargo test -p <crate>
```
**Workspace-wide (required before commit):**
```bash
cargo test --workspace
```
**With ignored integration tests (full validation):**
```bash
cargo test -p <crate> -- --include-ignored
# or workspace-wide:
cargo test --workspace -- --include-ignored
```
## Crate Name vs Directory Name
Cargo `-p` flags use the **`name` field in `Cargo.toml`**, not the directory name. Exceptions:
| Directory | Cargo flag |
|---|---|
| `crates/trusty-git-analytics/` | `-p tga` |
| `crates/open-mpm/` | `-p open-mpm` |
All other crates: directory name = crate name (e.g. `crates/trusty-search/` → `-p trusty-search`).
## Reading Test Output
Cargo test output ends with a summary line:
```
test result: ok. 42 passed; 0 failed; 3 ignored; 0 measured; 0 filtered out
```
| Field | Meaning |
|---|---|
| `passed` | Tests that ran and succeeded |
| `failed` | Tests that ran and failed — **must be zero** |
| `ignored` | Tests tagged `#[ignore]` — skipped by default (ONNX/integration) |
| `measured` | Benchmark results (bench mode only) |
**`#[ignore]` tests**: These are slow ONNX-backed or environment-dependent integration tests. They are intentionally skipped in the default gate. Run them with `--include-ignored` for full local validation before releases.
**Evidence format required**: Report the literal summary line, not "tests pass". Example of acceptable evidence:
```
test result: ok. 87 passed; 0 failed; 5 ignored; 0 measured; 0 filtered out; finished in 3.42s
```
## Pre-existing vs New Failure Triage
If a gate fails, determine whether the failure existed before the current patch:
```bash
# Stash current changes
git stash
# Run the failing gate at clean HEAD
cargo test -p <crate>
# If it also fails at HEAD: pre-existing failure — do not block the patch
# If it passes at HEAD: the patch introduced the regression — must fix
# Restore patch
git stash pop
```
Report: "Failure is pre-existing at HEAD — not introduced by this change" or "Failure is new — introduced by this patch."
## Single-Crate vs Workspace Scope
| Scope | Command | When |
|---|---|---|
| Single crate | `cargo test -p <crate>` | Fast iteration during implementation |
| Single crate (check only) | `cargo check -p <crate>` | Fastest — confirms compilation, no test run |
| Single crate + features | `cargo test -p trusty-common --features axum-server` | When feature flag needed |
| Workspace | `cargo test --workspace` | Required before committing any change |
| Workspace + ignored | `cargo test --workspace -- --include-ignored` | Before tagging a release |
## After Modifying a Shared Library Crate
When `trusty-common`, `trusty-mcp-core`, `trusty-embedder`, or `trusty-symgraph` changes:
1. Run `cargo check` (workspace-wide) first — catches compilation errors in all dependents immediately.
2. Run `cargo test -p <lib>` for the modified library.
3. Run `cargo test -p <consumer>` for each crate that imports the modified library.
4. Only commit after all dependent tests pass.
## Gate Summary
```
cargo fmt --check → Gate 1 (format) — fix: cargo fmt
cargo clippy --workspace → Gate 2 (lint) — fix: address each warning
cargo test -p <crate> → Gate 3 (tests) — fix: repair failing tests
```
All three must be green before a PR is mergeable. Evidence must include the literal output from each gate.
## Anti-Patterns
- Running tests before format and clippy — wastes time if format fails.
- Reporting "tests pass" without showing the result summary line.
- Treating `ignored` count as failures — they are intentionally skipped.
- Blocking work on `open-mpm` clippy errors that are pre-existing at HEAD.
- Using `cargo build` as a substitute for `cargo test` — build success does not validate behavior.
- Running `cargo test` workspace-wide without confirming crate name aliases (e.g., use `-p tga` not `-p trusty-git-analytics`).