rust-port-validation-gauntlet

rust-port-validation-gauntlet — drive a crate to all-green through every quality gate

Take a Rust port/crate and run it through the full gate battery as a loop that iterates until everything is green, recording every dead end so it is never retried.

⚠️ Critical Constraints

One gate, one fix, one re-run — never batch. Run a gate, fix exactly what it reports, re-run that same gate before advancing. Why: batched edits make it impossible to attribute a regression; a "fix" for clippy can silently break a test, and you lose the causal chain.
Every failed attempt goes in the ledger before the next attempt. No fix is tried twice. Why: the loop's whole value is monotonic progress; without negative evidence an autonomous agent re-discovers the same dead end on every pass and never converges.
Never weaken a gate to make it pass. Do not add #[allow(...)], --no-default-features, #[ignore], or lower the lint level to get green. Why: that converts a real defect into hidden debt and defeats the gauntlet. WRONG: #[allow(clippy::all)] over the module. CORRECT: fix the lint, or record in the ledger why the lint is provably inapplicable with a scoped, justified allow.
Gate order is fixed and fail-fast. fmt → build → clippy → test → miri → fuzz → bench. Why: cheap, deterministic gates first; a fmt or build failure invalidates every downstream result, so running them first saves the whole battery.

Why This Exists

A port (C/C++/Python → Rust, or a crate-split) is exactly where latent undefined behavior, lint debt, and missing test coverage hide. Running gates ad-hoc and by hand means an agent forgets what it already tried, oscillates between two broken states, and declares victory after the cheap gates pass. This skill makes the gauntlet autonomous and monotonic: a fixed gate order, a verification checkpoint between every gate, and a persisted negative-evidence ledger so the loop converges instead of looping forever.

Quick Start

# from the crate root (the dir with Cargo.toml)
fmt:   cargo fmt --all -- --check
build: cargo build --all-targets --all-features
clippy:cargo clippy --all-targets --all-features -- -D warnings
test:  cargo test --all-features
miri:  cargo +nightly miri test            # UB detector (needs rustup component add miri)
fuzz:  cargo +nightly fuzz run <target> -- -max_total_time=60
bench: cargo bench

Initialize the ledger once, then enter the loop:

bash {baseDir}/scripts/init-ledger.sh GAUNTLET-LEDGER.md

The Gauntlet Loop

Snapshot. Record the crate name, toolchain (rustc -Vv), and enabled features into the ledger header. This pins what "green" means.
Pick the next red gate in fixed order: fmt → build → clippy → test → miri → fuzz → bench. Run only that gate.
If green: mark the gate PASS in the matrix, advance to the next gate.
If red: read the failure. Before editing, check the ledger — if this exact approach is already a logged dead end, pick a different one. Apply ONE targeted fix.
Verification checkpoint: re-run the same gate. Also re-run fmt + build + clippy + test (the fast quartet) to catch a fix that regressed an earlier gate.
Log the outcome. If the fix worked, note it. If it failed, append a negative-evidence row (gate, approach, why it failed) so it is never retried.
Repeat until all gates in the matrix are PASS, or until a gate is logged as blocked with evidence (e.g. miri unsupported for an FFI call) and explicitly waived.

Per-gate failure patterns, miri/fuzz setup, and the ledger schema: see references/gates.md.

Output Specification

File: GAUNTLET-LEDGER.md at the crate root.
- A gate matrix table: | Gate | Status | Last run | Notes |.
- A negative-evidence log table: | Gate | Approach tried | Why it failed | Date |.
Stdout: one PASS/FAIL line per gate per pass.
Done = every row in the gate matrix is PASS or an evidence-backed WAIVED.

Quality Rubric

Every gate in the matrix is PASS or WAIVED-with-evidence; no gate left UNKNOWN.
No gate was made to pass by weakening it (no blanket allow, no --no-default-features shortcut, no #[ignore]) — verifiable by diffing the crate against the start snapshot.
The negative-evidence log has no duplicate (gate, approach) rows — the loop never retried a dead end.

Examples

Clippy red on a ported module: cargo clippy ... -D warnings flags needless_lifetimes. Fix the signature, re-run clippy + the fast quartet, mark PASS.
Miri finds UB in unsafe FFI shim: miri reports a use-after-free through a raw pointer. Fix the lifetime; if miri cannot model the foreign call at all, log it WAIVED with the exact unsupported-operation message as evidence.

Troubleshooting

Symptom	Likely cause	Move
Loop oscillates between two failures	A fix for gate X regresses gate Y	Re-run the fast quartet after every fix (step 5); log both as a paired dead end
`cargo miri` not found	miri component/toolchain missing	`rustup +nightly component add miri`; see references/gates.md
Fuzz never finds a crash but never returns	No time bound	Always pass `-- -max_total_time=N`; treat clean run as PASS
Same fix attempted twice	Ledger not consulted before editing	Enforce step 4: read the negative-evidence log first

About this skill