lazycodex-ai 5.0.0-beta.85 → 5.0.0-beta.87

package/packages/shared-skills/skills/programming/references/rust/unsafe-discipline.md

@@ -146,7 +146,7 @@ impl Arena {
         // bump. `aligned` is aligned to `layout.align()` by `align_up`. No
         // other writer can have observed this offset because the CAS above
         // returned `Ok`.
-        let ptr = unsafe { self.map.as_mut_ptr().add(aligned) as *mut T };
+        let ptr = unsafe { self.map.as_mut_ptr().add(aligned) }.cast::<T>();
         // SAFETY: `ptr` is non-null (mmap base + offset), aligned (above),
         // exclusively owned (CAS), and we are about to initialize it.
         unsafe { ptr::write(ptr, value) };
@@ -187,7 +187,35 @@ What miri catches that the borrow checker cannot:
 - Stacked borrows / Tree borrows aliasing violations
 - Data races (single-threaded model, but catches concurrent access through `UnsafeCell` misuse)
 - Atomic ordering bugs in some patterns
-- Memory leaks (with `-Zmiri-track-pointer-tag`)
+- Memory leaks (reported by default at exit; `-Zmiri-ignore-leaks` turns it off)
+
+## FFI Declarations (Rust 2024)
+
+The 2024 edition makes the unsafety of FFI items visible at the declaration:
+
+```rust
+use core::ffi::{c_char, c_int};
+
+// SAFETY: these signatures match <string.h>/<stdlib.h> for every target we build.
+unsafe extern "C" {
+    /// No preconditions: callable from safe code.
+    pub safe fn abs(x: c_int) -> c_int;
+    /// Caller must pass a valid NUL-terminated string.
+    pub unsafe fn strlen(s: *const c_char) -> usize;
+}
+
+// Exported symbol: the attribute itself is unsafe because a name clash is UB.
+#[unsafe(no_mangle)]
+pub extern "C" fn mylib_version() -> u32 { 3 }
+```
+
+- A bare `extern "C" { ... }` block is a hard error in the 2024 edition; write `unsafe extern` and mark each item `safe fn` (no caller obligations) or `unsafe fn`. Marking an item `safe` is a promise you make for every caller; when in doubt, it is `unsafe`.
+- `#[no_mangle]`, `#[export_name]`, and `#[link_section]` are written `#[unsafe(...)]`.
+- A panic that unwinds out of an `extern "C"` function aborts the process (1.81+). Catch it with `std::panic::catch_unwind` at the boundary and return an error code; use `extern "C-unwind"` only when the foreign side is built to unwind.
+
+## Uninitialized Memory
+
+`MaybeUninit<T>` is the only way to hold memory that is not yet a valid `T`. `mem::uninitialized()` is always wrong, and `mem::zeroed()` is UB for any type whose all-zero bit pattern is invalid (references, `NonZero*`, `bool`-bearing enums, most `repr(Rust)` structs). An uninitialized array is `[const { MaybeUninit::<T>::uninit() }; N]`; write every element through `MaybeUninit::write`, then convert once, with a SAFETY comment stating that all `N` elements were written.
 
 ## When Miri Cannot Run
 
@@ -218,8 +246,8 @@ mod tests {
     fn concurrent_push_pop() {
         loom::model(|| {
             let queue = std::sync::Arc::new(MyQueue::new());
-            let q1 = queue.clone();
-            let q2 = queue.clone();
+            let q1 = std::sync::Arc::clone(&queue);
+            let q2 = std::sync::Arc::clone(&queue);
             let h1 = loom::thread::spawn(move || q1.push(1));
             let h2 = loom::thread::spawn(move || q2.pop());
             h1.join().unwrap();
@@ -229,7 +257,7 @@ mod tests {
 }
 ```
 
-Run: `RUSTFLAGS="--cfg loom" cargo test --release`. Loom exhaustively explores thread interleavings for the test scope. Combined with miri on the single-thread paths, you have machine-checked soundness over the full state space.
+Run: `RUSTFLAGS="--cfg loom" cargo test --release`. Loom systematically explores the interleavings its bounded model allows for the test scope; combined with miri on the single-thread paths, that is strong machine-checked evidence, not a proof over every execution.
 
 ## The Forbidden List
 
@@ -241,7 +269,7 @@ Reject in code review, automatic CI fail:
 - `std::mem::transmute` for anything but lifetime extension on the same layout (and that should usually be `core::mem::transmute_copy` or `bytemuck::cast` if the relayout is well-defined).
 - `std::ptr::read_unaligned` / `write_unaligned` without a comment explaining why aligned access is impossible.
 - `from_raw_parts` / `from_raw_parts_mut` without proving the source pointer's provenance covers the entire slice.
-- `Arc::get_mut_unchecked`, `Box::leak` to bypass ownership, `MaybeUninit::assume_init` on partially-initialized data.
+- `Arc::get_mut_unchecked`, `Box::leak` to bypass ownership, `MaybeUninit::assume_init` on partially-initialized data, `mem::uninitialized`, `mem::zeroed` for a type whose all-zero pattern is not valid.
 - `unsafe impl Send`, `unsafe impl Sync` on types containing raw pointers, without a comment naming exactly which interior-mutability rule is upheld.
 - Any `unsafe` block whose justification depends on "in practice this never happens".
 

package/packages/shared-skills/skills/programming/references/rust/zero-cost-safety.md

@@ -100,18 +100,20 @@ const fn fibonacci(n: usize) -> usize {
 const FIB_20: usize = fibonacci(20); // computed at compile time: 6765
 
 // Use in array sizes
+#[expect(clippy::indexing_slicing, reason = "const evaluation: an out-of-bounds index is a compile error")]
 const LOOKUP: [u8; 256] = {
     let mut table = [0u8; 256];
-    let mut i = 0;
-    while i < 256 {
-        table[i] = (i as u8).wrapping_mul(7);
+    let mut i: u8 = 0;
+    loop {
+        table[i as usize] = i.wrapping_mul(7); // u8 -> usize widens: lossless
+        if i == u8::MAX { break; }
         i += 1;
     }
     table
 };
 ```
 
-**Stable since Rust 1.82:** `const fn` supports `match`, loops, `if`, references, mutable locals — nearly full Rust. Use `const { }` blocks (Rust 1.79+) for inline compile-time assertions.
+`const fn` bodies may use `if`, `match`, `loop`/`while`, and mutable locals; trait methods (`From`, `TryFrom`, `Iterator`) are not callable in `const` on stable. That makes a **lossless widening `as` inside `const`** the one accepted numeric cast: iterate in the narrow type and widen to index, as above, so no value can truncate. Use `const { }` blocks (Rust 1.79+) for inline compile-time assertions.
 
 ```rust
 fn process<const N: usize>(data: &[u8; N]) {
@@ -123,6 +125,7 @@ fn process<const N: usize>(data: &[u8; N]) {
 ### const generics — Type-Level Values
 
 ```rust
+#[derive(Debug)]
 struct Buffer<const N: usize> {
     data: [u8; N],
     len: usize,
@@ -134,13 +137,17 @@ impl<const N: usize> Buffer<N> {
     }
 
     fn push(&mut self, byte: u8) -> Result<(), BufferFullError> {
-        if self.len >= N { return Err(BufferFullError); }
-        self.data[self.len] = byte;
-        self.len += 1;
+        let slot = self.data.get_mut(self.len).ok_or(BufferFullError)?;
+        *slot = byte;
+        self.len = self.len.saturating_add(1); // < N after the get_mut above
         Ok(())
     }
 }
 
+impl<const N: usize> Default for Buffer<N> {
+    fn default() -> Self { Self::new() }
+}
+
 // Compiler enforces: Buffer<16> and Buffer<32> are distinct types.
 let small: Buffer<16> = Buffer::new();
 let large: Buffer<1024> = Buffer::new();
@@ -148,26 +155,7 @@ let large: Buffer<1024> = Buffer::new();
 
 ### proc macros — Code Generation (Zig comptime type creation)
 
-When `const fn` is not enough (generating struct fields, impl blocks, or derive logic), proc macros fill the gap.
-
-```rust
-// In a proc-macro crate:
-use proc_macro::TokenStream;
-use quote::quote;
-use syn::{parse_macro_input, DeriveInput};
-
-#[proc_macro_derive(Builder)]
-pub fn derive_builder(input: TokenStream) -> TokenStream {
-    let input = parse_macro_input!(input as DeriveInput);
-    let name = &input.ident;
-    // ... generate builder struct and impl
-    TokenStream::from(quote! {
-        impl #name {
-            pub fn builder() -> #name##Builder { /* ... */ }
-        }
-    })
-}
-```
+When `const fn` is not enough (generating struct fields, impl blocks, or derive logic), proc macros fill the gap. Crate layout, `syn`/`quote`, identifier construction, and spanned errors → [macros.md](macros.md).
 
 **Decision tree:**
 
@@ -195,15 +183,14 @@ fn process(input: &str) -> String {
 
 // GOOD: caller provides output buffer, zero allocation
 fn process(input: &[u8], output: &mut [u8]) -> usize {
-    let len = input.len().min(output.len());
-    for i in 0..len {
-        output[i] = input[i].to_ascii_uppercase();
+    for (dst, src) in output.iter_mut().zip(input) {
+        *dst = src.to_ascii_uppercase();
     }
-    len // returns bytes written
+    input.len().min(output.len()) // bytes written; zip stopped at the shorter slice
 }
 
 // GOOD: return borrowed data when possible
-fn find_token<'a>(input: &'a str) -> Option<&'a str> {
+fn find_token(input: &str) -> Option<&str> {
     input.split_whitespace().next() // no allocation — borrows from input
 }
 ```
@@ -231,9 +218,28 @@ tags.push(1); // on stack if <= 8 elements
 
 // ArrayVec: purely stack, fixed capacity, no heap ever
 let mut buf: ArrayVec<u8, 64> = ArrayVec::new();
-buf.try_push(42).map_err(|_| "full")?; // returns error instead of panic
+buf.try_push(42).map_err(|_| BufferFullError)?; // typed error instead of panic
+```
+
+### Move Out of `&mut` Without Cloning
+
+```rust
+// Take the value, leave Default behind: no clone, no Option dance.
+let pending = std::mem::take(&mut self.pending);      // Vec/String/HashMap
+let old = std::mem::replace(&mut self.state, State::Idle);
+let conn = self.conn.take();                          // Option<T> field
 ```
 
+A `.clone()` whose only purpose is to satisfy the borrow checker behind `&mut self` is almost always one of these three.
+
+### Reuse and Pre-Size
+
+- Reserve from a known size: `Vec::with_capacity(n)` / `String::with_capacity(n)`, or `reserve(n)` before a batch `extend`.
+- In a loop, hoist a scratch buffer and `clear()` it each iteration instead of allocating a fresh one; `clear` keeps the capacity. Drop or `shrink_to` it when one outlier would pin a huge allocation.
+- Format into an existing buffer with `write!(buf, ...)` (`use std::fmt::Write as _`) instead of building intermediate `format!` strings, and pass `&str` literals where no formatting happens.
+
+Apply these on paths a profile or benchmark shows to be hot; elsewhere the clearer allocation wins.
+
 ### Cow — Defer Allocation Until Mutation
 
 ```rust
@@ -264,15 +270,7 @@ Even in `std` code, the *mindset* applies: prefer `&[T]` over `Vec<T>` in functi
 
 ### Clippy Lints for Hidden Allocations
 
-```toml
-# Cargo.toml — catch accidental allocations
-[lints.clippy]
-# These warn on patterns that allocate when a borrow would suffice:
-unnecessary_to_owned = "warn"       # .to_string() / .to_vec() when borrow works
-redundant_clone = "warn"            # .clone() that's immediately consumed
-large_stack_arrays = "warn"         # accidental large stack usage
-vec_init_then_push = "warn"         # Vec::new() + push instead of vec![]
-```
+The groups in [cargo-strict.md](cargo-strict.md) already enable the allocation lints: `unnecessary_to_owned` and `vec_init_then_push` (in `all`, denied), `redundant_clone` (nursery), `large_stack_arrays` (pedantic). Do not re-list them in `[lints.clippy]`: a per-lint `"warn"` entry overrides the group and silently downgrades a deny.
 
 ---
 
@@ -408,22 +406,24 @@ Zig's `errdefer` runs cleanup only on error paths. Rust's `Drop` always runs, bu
 ### scopeguard — The errdefer Equivalent
 
 ```rust
-use scopeguard::{defer, guard};
+use scopeguard::{guard, ScopeGuard};
 use std::fs;
 
 fn create_and_process(path: &str) -> std::io::Result<()> {
     let file = fs::File::create(path)?;
     // If anything below fails, clean up the file.
     // This is exactly Zig's errdefer.
-    let _cleanup = guard((), |_| {
-        let _ = fs::remove_file(path);
+    let cleanup = guard((), |()| {
+        if let Err(error) = fs::remove_file(path) {
+            tracing::warn!(%error, path, "cleanup after failed write");
+        }
     });
 
     write_data(&file)?;
     validate_data(path)?;
 
     // Success: defuse the guard so it does NOT run cleanup.
-    std::mem::forget(_cleanup);
+    ScopeGuard::into_inner(cleanup);
     Ok(())
 }
 ```
@@ -437,7 +437,7 @@ fn with_temp_dir() -> anyhow::Result<()> {
     let dir = tempfile::tempdir()?;
     defer! {
         // Runs when scope exits, success or failure.
-        println!("Cleaning up {}", dir.path().display());
+        tracing::debug!(path = %dir.path().display(), "leaving temp dir scope");
         // dir's Drop also cleans up, but this shows the pattern.
     }
 
@@ -449,6 +449,7 @@ fn with_temp_dir() -> anyhow::Result<()> {
 ### Drop as RAII Cleanup
 
 ```rust
+#[derive(Debug)]
 struct TempFile { path: std::path::PathBuf }
 
 impl TempFile {
@@ -461,7 +462,10 @@ impl TempFile {
 
 impl Drop for TempFile {
     fn drop(&mut self) {
-        let _ = std::fs::remove_file(&self.path);
+        // Drop cannot return an error; report it instead of discarding it.
+        if let Err(error) = std::fs::remove_file(&self.path) {
+            tracing::warn!(%error, path = %self.path.display(), "temp file not removed");
+        }
     }
 }
 
@@ -469,19 +473,25 @@ impl Drop for TempFile {
 let tmp = TempFile::new("/tmp/scratch.dat")?;
 ```
 
+### Drop Order Is Part of the Contract
+
+Locals drop in reverse declaration order; struct fields drop in declaration order (first field first). When one resource must outlive another (a transaction before its connection, a worker handle before the channel it drains), encode it: declare the dependent field first, or call `drop(x)` at the exact point the dependency ends. Never rely on an order the code does not state.
+
 ### The errdefer Pattern — Defuse on Success
 
 The key insight from Zig's `errdefer`: you want cleanup on error but NOT on success. In Rust:
 
 ```rust
-use scopeguard::ScopeGuard;
+use scopeguard::{guard, ScopeGuard};
 
 fn deploy(artifact: &Path) -> Result<(), DeployError> {
     let backup = backup_current()?;
 
     // errdefer: restore backup if anything fails
-    let rollback = guard(backup.clone(), |b| {
-        let _ = restore_from_backup(&b);
+    let rollback = guard(backup, |b| {
+        if let Err(error) = restore_from_backup(&b) {
+            tracing::error!(%error, "rollback failed; manual restore needed");
+        }
     });
 
     upload(artifact)?;
@@ -522,6 +532,6 @@ All achievable within Rust's single toolchain. You get Zig's explicitness **plus
 - **Zero-alloc APIs** hurt readability when the function naturally produces owned data. Don't force `&mut [u8]` output buffers on a function that logically returns `String`.
 - **`#[repr(packed)]`** only for wire formats and FFI. Never for regular domain types.
 - **Scope guards** unnecessary when `Drop` on the value itself handles cleanup (e.g., `tempfile::NamedTempFile` already does this).
-- **`const fn`** everything? No — only when the value is genuinely needed at compile time or the function is trivially const-eligible. Don't contort logic just to be const.
+- **`const fn`** everything? No — only when a `const` context needs the function or it is trivially const-eligible. Don't contort logic just to be const.
 
 The goal is **visible costs and explicit control**, not asceticism. Use `String` and `Vec` freely when they're the right tool. Reach for these patterns when allocation behavior matters for correctness or performance.

package/packages/shared-skills/skills/programming/references/rust-ub/miri-sanitizers-loom.md

@@ -66,7 +66,7 @@ cargo +nightly miri test
 MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test
 ```
 
-**Protocol:** Run Stacked Borrows first. If it fails, fix it. Then run Tree Borrows to confirm. Code that passes Stacked Borrows is sound under both models.
+**Protocol:** Run Stacked Borrows first. If it fails, fix it. Then run Tree Borrows as a separate pass. The models are not nested: Stacked Borrows is stricter about most reborrow patterns, but Tree Borrows rejects some code Stacked Borrows accepts. Ship only when both are clean.
 
 #### Strict Provenance
 

package/packages/shared-skills/skills/programming/references/rust-ub/ub-taxonomy.md

@@ -140,7 +140,7 @@ MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
 - Passing a Rust `enum` to C without `#[repr(C)]` or `#[repr(i32)]`.
 - Null pointer passed where C expects non-null (and Rust wraps it in `&T`).
 - C code writing to Rust-owned memory through a pointer Rust considers immutable.
-- Forgetting to mark FFI functions as `unsafe extern "C"`.
+- Declaring a foreign function `safe fn` inside `unsafe extern` when it has caller preconditions (null, length, lifetime), so safe code can violate them.
 - longjmp/setjmp across Rust frames (unwinding UB).
 
 **Miri detection:** LIMITED — Miri cannot execute foreign code. It detects UB in the Rust-side handling of FFI return values.
@@ -236,12 +236,15 @@ MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
 **Root cause:** A Rust panic unwinding through a frame that uses the C calling convention.
 
 **Canonical triggers:**
-- `panic!()` inside a `#[no_mangle] extern "C" fn` callback passed to C code.
+- `panic!()` inside a `#[unsafe(no_mangle)] extern "C" fn` callback passed to C code.
 - `unwrap()` inside FFI callbacks.
+- Foreign code unwinding (C++ exceptions, `longjmp`) through a Rust frame declared `extern "C"`.
+
+Since Rust 1.81 a Rust panic that reaches an `extern "C"` boundary aborts the process instead of unwinding into foreign frames: no longer UB, but still a crash.
 
 **Miri detection:** PARTIAL — Miri does not model foreign unwinding, but it can detect the immediate UB if the panic reaches the FFI boundary.
 
-**Fix pattern:** Use `std::panic::catch_unwind` at every FFI entry point. Mark FFI callbacks as `extern "C-unwind"` when panic propagation is intentional (nightly). Prefer returning `Result`-like error codes from FFI callbacks.
+**Fix pattern:** Use `std::panic::catch_unwind` at every FFI entry point and return an error code. Declare the ABI `extern "C-unwind"` (stable since 1.71) only when both sides are built to let unwinding cross.
 
 ---
 

package/packages/shared-skills/skills/programming/scripts/rust/check-no-excuse-rules.sh

@@ -1,8 +1,22 @@
 #!/usr/bin/env bash
 # No-excuse rule checker for Rust files.
-# Mirrors the philosophy of python-programmer / typescript-programmer scripts:
-# only rules that can be enforced via pure text matching live here.
+# Only rules that can be enforced via pure text matching live here.
 # Everything semantic is on clippy + miri + nextest.
+#
+# Rules:
+#   unwrap / expect         outside tests, unless the previous line carries
+#                           #[expect(clippy::unwrap_used|expect_used, reason = "...")]
+#   placeholder-macro       todo!/unimplemented!/unreachable! in committed code
+#   box-dyn-error           Box<dyn Error> in non-test code
+#   lib-panic               panic!() in library code
+#   discarded-result        `let _ = call(...)`, unless the previous line carries
+#                           #[expect(clippy::let_underscore_must_use, reason = "...")]
+#   blocking-in-async       std::thread::sleep / std::fs / reqwest::blocking /
+#                           .blocking_*() inside an async fn or async block
+#   unsafe-no-safety        unsafe { without // SAFETY: in the preceding 5 lines
+#   allow-attribute         #[allow(...)] - silence lints with #[expect(lint, reason)]
+#   expect-without-reason   #[expect(...)] with no `reason = "..."`
+#   narrowing-as-cast       possible narrowing numeric `as` cast
 
 set -euo pipefail
 
@@ -13,23 +27,22 @@ fi
 
 violations=0
 report() {
-    local file="$1"
-    local line="$2"
-    local rule="$3"
-    local detail="$4"
-    echo "::error file=${file},line=${line}::[${rule}] ${detail}" >&2
+    echo "::error file=$1,line=$2::[$3] $4" >&2
     violations=$((violations + 1))
 }
 
 is_test_path() {
-    local path="$1"
-    case "$path" in
+    case "$1" in
         */tests/*|*/benches/*|*/examples/*|*/build.rs|*_test.rs|tests/*|benches/*|examples/*) return 0 ;;
     esac
-    # In-file #[cfg(test)] modules are handled per-line below.
     return 1
 }
 
+count_char() {
+    local only="${1//[^$2]/}"
+    echo "${#only}"
+}
+
 for file in "$@"; do
     [ -f "$file" ] || continue
     case "$file" in
@@ -37,108 +50,106 @@ for file in "$@"; do
         *) continue ;;
     esac
 
-    if is_test_path "$file"; then
-        # Test files are exempt from unwrap/expect/todo rules.
-        # Still enforce unsafe-comment, allow-comment, panic-in-lib rules below
-        # by setting a marker - keeping the loop unified.
-        in_test_file=1
-    else
-        in_test_file=0
-    fi
-
-    # Track #[cfg(test)] regions for per-line exemptions.
-    in_cfg_test=0
-    cfg_test_brace_depth=0
-    line_no=0
-
-    while IFS= read -r raw_line || [ -n "$raw_line" ]; do
-        line_no=$((line_no + 1))
-        line="$raw_line"
-
-        # Crude #[cfg(test)] region tracker: when we see #[cfg(test)] on a
-        # line followed by a mod with `{`, count braces until depth returns
-        # to zero. This is approximate but matches typical formatting.
+    in_test_file=0
+    is_test_path "$file" && in_test_file=1
+
+    lines=()
+    while IFS= read -r raw || [ -n "$raw" ]; do lines+=("$raw"); done < "$file"
+    total=${#lines[@]}
+
+    # Brace-tracked regions: a region starts at its marker line and ends when the
+    # braces opened after the marker are closed again.
+    in_cfg_test=0; cfg_depth=0; cfg_opened=0
+    in_async=0; async_depth=0; async_opened=0
+
+    for ((i = 0; i < total; i++)); do
+        line_no=$((i + 1))
+        line="${lines[$i]}"
+        prev=""
+        [ "$i" -gt 0 ] && prev="${lines[$((i - 1))]}"
+        code_only="${line%%//*}"
+        opens=$(count_char "$code_only" "{")
+        closes=$(count_char "$code_only" "}")
+
         if [[ "$line" =~ \#\[cfg\(test\)\] ]]; then
-            in_cfg_test=1
-            cfg_test_brace_depth=0
+            in_cfg_test=1; cfg_depth=0; cfg_opened=0
         fi
         if [ "$in_cfg_test" -eq 1 ]; then
-            opens=$(printf '%s' "$line" | tr -cd '{' | wc -c)
-            closes=$(printf '%s' "$line" | tr -cd '}' | wc -c)
-            cfg_test_brace_depth=$((cfg_test_brace_depth + opens - closes))
-            if [ "$cfg_test_brace_depth" -le 0 ] && [[ ! "$line" =~ \#\[cfg\(test\)\] ]]; then
-                in_cfg_test=0
-            fi
+            cfg_depth=$((cfg_depth + opens - closes))
+            [ "$opens" -gt 0 ] && cfg_opened=1
+            if [ "$cfg_opened" -eq 1 ] && [ "$cfg_depth" -le 0 ]; then in_cfg_test=0; fi
+        fi
+
+        if [ "$in_async" -eq 0 ] && [[ "$code_only" =~ (^|[^[:alnum:]_])async([[:space:]]+(move[[:space:]]*)?\{|[[:space:]]+(unsafe[[:space:]]+)?fn[[:space:]]) ]]; then
+            in_async=1; async_depth=0; async_opened=0
+        fi
+        async_line=$in_async
+        if [ "$in_async" -eq 1 ]; then
+            async_depth=$((async_depth + opens - closes))
+            [ "$opens" -gt 0 ] && async_opened=1
+            if [ "$async_opened" -eq 1 ] && [ "$async_depth" -le 0 ]; then in_async=0; fi
         fi
 
         exempt=0
         [ "$in_test_file" -eq 1 ] && exempt=1
         [ "$in_cfg_test" -eq 1 ] && exempt=1
 
-        # Strip line comments before pattern checks - so doc comments and
-        # explanatory prose do not trip the regexes.
-        code_only="${line%%//*}"
-
         if [ "$exempt" -eq 0 ]; then
-            # .unwrap()
-            if [[ "$code_only" =~ \.unwrap\(\) ]]; then
-                # Allow if previous line had // SAFE-UNWRAP: comment
-                prev_line=$(sed -n "$((line_no - 1))p" "$file" 2>/dev/null || true)
-                if [[ ! "$prev_line" =~ //[[:space:]]*SAFE-UNWRAP: ]]; then
-                    report "$file" "$line_no" "unwrap" ".unwrap() outside tests - use ? / ok_or / pattern match or annotate previous line with // SAFE-UNWRAP: <reason>"
-                fi
+            if [[ "$code_only" =~ \.unwrap\(\) ]] && [[ ! "$prev" =~ \#\[expect\(clippy::unwrap_used,.*reason ]]; then
+                report "$file" "$line_no" "unwrap" ".unwrap() outside tests - use ? / ok_or / let-else, or for a proven invariant use .expect() behind #[expect(clippy::expect_used, reason = \"...\")]"
             fi
 
-            # .expect("...")
-            if [[ "$code_only" =~ \.expect\( ]]; then
-                prev_line=$(sed -n "$((line_no - 1))p" "$file" 2>/dev/null || true)
-                if [[ ! "$prev_line" =~ //[[:space:]]*SAFE-EXPECT: ]]; then
-                    report "$file" "$line_no" "expect" ".expect() outside tests - use ? or annotate previous line with // SAFE-EXPECT: <reason>"
-                fi
+            if [[ "$code_only" =~ \.expect\( ]] && [[ ! "$prev" =~ \#\[expect\(clippy::expect_used,.*reason ]]; then
+                report "$file" "$line_no" "expect" ".expect() outside tests - use ?, or for a proven invariant annotate the previous line with #[expect(clippy::expect_used, reason = \"...\")]"
             fi
 
-            # todo!() / unimplemented!() / unreachable!()
             if [[ "$code_only" =~ (todo!|unimplemented!|unreachable!|unreachable_unchecked!) ]]; then
                 report "$file" "$line_no" "placeholder-macro" "todo!/unimplemented!/unreachable! in committed code"
             fi
 
-            # Box<dyn Error
             if [[ "$code_only" =~ Box\<dyn[[:space:]]+Error ]]; then
                 report "$file" "$line_no" "box-dyn-error" "Box<dyn Error> in non-test code - use anyhow::Error (apps) or thiserror enum (libs)"
             fi
 
-            # panic!( in lib
             if [[ "$file" == */src/lib.rs || "$file" == */src/*/mod.rs || ( "$file" == */src/*.rs && "$file" != */src/main.rs && "$file" != */src/bin/* ) ]]; then
                 if [[ "$code_only" =~ panic!\( ]]; then
                     report "$file" "$line_no" "lib-panic" "panic!() in library code - return Result"
                 fi
             fi
+
+            if [[ "$code_only" =~ let[[:space:]]+_[[:space:]]*=[[:space:]]*[^\;]*\( ]] && [[ ! "$prev" =~ \#\[expect\(clippy::let_underscore_must_use,.*reason ]]; then
+                report "$file" "$line_no" "discarded-result" "let _ = call() drops its result - propagate or handle the error; log it on a best-effort path"
+            fi
+
+            if [ "$async_line" -eq 1 ] && [[ "$code_only" =~ (thread::sleep\(|std::fs::|reqwest::blocking::|\.blocking_(recv|send|lock|read|write)\() ]]; then
+                report "$file" "$line_no" "blocking-in-async" "blocking call inside async code - use tokio::time::sleep / tokio::fs / the async client, or move it into spawn_blocking"
+            fi
         fi
 
-        # unsafe { without preceding // SAFETY: in the last 5 lines (always enforced)
         if [[ "$code_only" =~ unsafe[[:space:]]*\{ ]]; then
-            start=$((line_no > 5 ? line_no - 5 : 1))
-            window=$(sed -n "${start},${line_no}p" "$file" 2>/dev/null || true)
+            start=$((i > 5 ? i - 5 : 0))
+            window=$(printf '%s\n' "${lines[@]:$start:$((i - start + 1))}")
             if [[ ! "$window" =~ //[[:space:]]*SAFETY: ]]; then
                 report "$file" "$line_no" "unsafe-no-safety-comment" "unsafe block without // SAFETY: comment in preceding 5 lines"
             fi
         fi
 
-        # #[allow(clippy::...)] without preceding // CLIPPY-ALLOW: justification
-        if [[ "$code_only" =~ \#\[allow\(clippy:: ]]; then
-            prev_line=$(sed -n "$((line_no - 1))p" "$file" 2>/dev/null || true)
-            if [[ ! "$prev_line" =~ //[[:space:]]*CLIPPY-ALLOW: ]]; then
-                report "$file" "$line_no" "unjustified-clippy-allow" "#[allow(clippy::...)] without // CLIPPY-ALLOW: <reason> on previous line"
+        if [[ "$code_only" =~ \#!?\[allow\( ]]; then
+            report "$file" "$line_no" "allow-attribute" "#[allow(...)] - use #[expect(lint, reason = \"...\")] so the exception fails once the lint stops firing"
+        fi
+
+        if [[ "$code_only" =~ \#!?\[expect\( ]]; then
+            attr=$(printf '%s\n' "${lines[@]:$i:4}")
+            if [[ ! "$attr" =~ reason[[:space:]]*= ]]; then
+                report "$file" "$line_no" "expect-without-reason" "#[expect(...)] needs reason = \"...\" naming why the lint does not apply"
             fi
         fi
 
-        # Narrowing numeric `as` casts - heuristic flag for human review.
-        # Catches the common shapes; precise type analysis belongs to clippy::cast_possible_truncation.
-        if [[ "$code_only" =~ as[[:space:]]+(u8|u16|u32|i8|i16|i32) ]] && \
-           [[ "$code_only" =~ (u16|u32|u64|u128|usize|i16|i32|i64|i128|isize)[[:space:]]+as[[:space:]]+(u8|u16|u32|i8|i16|i32) ]]; then
+        # Heuristic flag for human review; exact analysis belongs to clippy::cast_possible_truncation.
+        if [[ "$code_only" =~ (u16|u32|u64|u128|usize|i16|i32|i64|i128|isize)[[:space:]]+as[[:space:]]+(u8|u16|u32|i8|i16|i32)([^[:alnum:]_]|$) ]]; then
             report "$file" "$line_no" "narrowing-as-cast" "possible narrowing 'as' cast - use TryFrom / try_into() for fallible conversion"
         fi
-    done < "$file"
+    done
 done
 
 if [ "$violations" -gt 0 ]; then
@@ -146,9 +157,9 @@ if [ "$violations" -gt 0 ]; then
     echo "rust-programmer: ${violations} violation(s). Fix before declaring work done." >&2
     echo "" >&2
     echo "Then run the full toolchain gate:" >&2
-    echo "  cargo +stable fmt --all -- --check" >&2
-    echo "  cargo +stable clippy --all-targets --all-features -- -D warnings" >&2
-    echo "  cargo nextest run --all-targets --all-features" >&2
+    echo "  cargo fmt --all -- --check" >&2
+    echo "  cargo clippy --all-targets --all-features -- -D warnings" >&2
+    echo "  cargo nextest run --all-targets --all-features && cargo test --doc" >&2
     echo "  cargo +nightly miri nextest run --all-features    # if unsafe touched" >&2
     echo "  cargo machete" >&2
     echo "  cargo deny check" >&2