chore(lint): enable clippy::allow_attributes_without_reason

Cargo.toml

@@ -47,3 +47,11 @@ multiple_crate_versions = "allow"
 dbg_macro = "deny"
 # Forbid leftover `todo!` placeholders from reaching production
 todo = "deny"
+# Require every `#[allow(...)]` / `#![allow(...)]` attribute to carry a
+# `reason = "..."` string explaining WHY the lint is suppressed. Without a
+# reason, a suppression is opaque: a future reader can't tell whether the
+# `allow` is a deliberate policy decision, a temporary workaround, or an
+# accidental copy-paste. Documenting the reason turns each suppression into
+# self-explanatory code and makes it easy to re-evaluate or remove them as
+# the codebase evolves.
+allow_attributes_without_reason = "deny"

src/commands/open/mod.rs

@@ -14,7 +14,10 @@ use worktree_io::{
     workspace::Workspace,
 };
 
-#[allow(clippy::fn_params_excessive_bools)]
+#[allow(
+    clippy::fn_params_excessive_bools,
+    reason = "each bool maps directly to a distinct CLI flag (`--no-editor`, `--no-hooks`, `--headless`, `--force`); wrapping them in a flags struct would add indirection without clarity gains at the single call site"
+)]
 pub fn cmd_open(
     issue_ref: Option<&str>,
     force_editor: bool,

src/main.rs

@@ -1,5 +1,8 @@
 //! Worktree CLI binary — open GitHub issues as git worktree workspaces.
-#![allow(missing_docs)] // binary crate; public API lives in the library
+#![allow(
+    missing_docs,
+    reason = "binary crate — public API and its documentation live in the library crate, not the binary entry-point"
+)]
 use anyhow::Result;
 use clap::Parser;
 mod cli;

src/opener/entries.rs

@@ -42,7 +42,10 @@ const BASE: &[(&[&str], &str, &str, &str)] = &[
 
 /// All supported editor/terminal entries for the current platform.
 #[must_use]
-#[allow(unused_mut)]
+#[allow(
+    unused_mut,
+    reason = "`v` is mutated by `cfg`-gated blocks that push platform-specific entries on macOS and Linux; the binding must be `mut` for those platforms even though it appears unused on others"
+)]
 pub fn all_entries() -> Vec<EditorEntry> {
     let mut v: Vec<EditorEntry> = BASE
         .iter()

src/opener/terminal.rs

@@ -30,7 +30,7 @@ pub(super) fn try_terminal_with_init(
     }
     let path_escaped = path_str.replace('\'', "'\\''");
     // Single quotes around {path_escaped} are shell quoting, not Rust string delimiters.
-    #[allow(clippy::literal_string_with_formatting_args)]
+    #[allow(clippy::literal_string_with_formatting_args, reason = "`${SHELL:-sh}` and `${SHELL}` are POSIX shell variable expansions embedded in the script string, not Rust format arguments; the braces are intentional shell syntax")]
     let bootstrap = format!(
         "#!/bin/sh\ncd '{path_escaped}'\ntrap 'exec \"${{SHELL:-sh}}\"' INT\n{init_script}\nexec \"${{SHELL:-sh}}\"\n"
     );

src/scheme/macos/mod.rs

@@ -57,7 +57,10 @@ pub fn uninstall() -> Result<()> {
 ///
 /// Always succeeds on macOS; the `Result` return type matches the platform
 /// abstraction in `scheme/mod.rs`.
-#[allow(clippy::unnecessary_wraps)]
+#[allow(
+    clippy::unnecessary_wraps,
+    reason = "macOS detection always succeeds synchronously, but the `Result` return type is required to match the cross-platform `scheme::status()` abstraction used on all platforms"
+)]
 pub fn status() -> Result<SchemeStatus> {
     let app = app_dir();
     if app.join("Contents").join("Info.plist").exists() {

tests/cli.rs

@@ -1,4 +1,7 @@
-#![allow(missing_docs)]
+#![allow(
+    missing_docs,
+    reason = "integration test crate — doc comments are not required for test helpers and fixtures"
+)]
 use std::path::{Path, PathBuf};
 use std::process::Command;
 

tests/git.rs

@@ -1,4 +1,7 @@
-#![allow(missing_docs)]
+#![allow(
+    missing_docs,
+    reason = "integration test crate — doc comments are not required for test helpers and fixtures"
+)]
 use std::path::{Path, PathBuf};
 use std::process::Command;
 use worktree_io::git::{

tests/snapshot_tests.rs

@@ -4,7 +4,10 @@
 //! the expected content and land at the expected paths.  Running them inside a
 //! clean Docker container (see `docker/Dockerfile.test`) eliminates host-state
 //! pollution and keeps the snapshots deterministic.
-#![allow(missing_docs)]
+#![allow(
+    missing_docs,
+    reason = "integration test crate — doc comments are not required for test helpers and fixtures"
+)]
 
 use worktree_io::repo_hooks_scaffold::SCAFFOLD;
 use worktree_io::{config::Config, ttl::WorkspaceRegistry};