🔨 chore: clear pedantic clippy lint backlog across codebase

Resolve accumulated clippy pedantic warnings spanning 53 files:

- Add #[must_use] to ~60 public functions returning values
  callers should not silently discard
- Add `# Errors` doc sections to all fallible public functions
  describing specific failure conditions
- Replace .expect() panics with proper error propagation via
  .context() and pattern matching in changelog parsing
- Use clone_into()/clone_from() over direct clone assignment
  to avoid intermediate allocations
- Simplify .map().unwrap_or() chains to .map_or()
- Generalize HashMap parameters with BuildHasher trait bounds
  for hasher flexibility in provider helpers
- Flatten Result<Option<T>> to Option<T> where errors were
  never meaningfully produced (resolve_remote_head_base)
- Use struct literal initialization with ..Default in tests
- Suppress pedantic doc lints in test utility modules where
  full documentation rigor is unnecessary

Author: hyperb1iss

src/agents/context.rs

@@ -60,6 +60,7 @@ pub enum TaskContext {
 impl TaskContext {
     /// Create context for the gen (commit message) command.
     /// Always uses staged changes only.
+    #[must_use]
     pub fn for_gen() -> Self {
         Self::Staged {
             include_unstaged: false,
@@ -68,6 +69,7 @@ impl TaskContext {
 
     /// Create context for amending the previous commit.
     /// The agent will see the combined diff from HEAD^1 to staged state.
+    #[must_use]
     pub fn for_amend(original_message: String) -> Self {
         Self::Amend { original_message }
     }
@@ -79,6 +81,10 @@ impl TaskContext {
     /// - `--to` on its own compares `<fallback-base>..to`
     /// - `--commit` is mutually exclusive with `--from/--to`
     /// - `--include-unstaged` is incompatible with range comparisons
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the provided flag combination is invalid.
     pub fn for_review(
         commit: Option<String>,
         from: Option<String>,
@@ -93,6 +99,10 @@ impl TaskContext {
     /// CLI and Studio should prefer a repo-aware base from `GitRepo::get_default_base_ref()`.
     /// This lets branch comparisons follow the repository's actual primary branch
     /// instead of relying on the legacy `"main"` fallback.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the provided flag combination is invalid.
     pub fn for_review_with_base(
         commit: Option<String>,
         from: Option<String>,
@@ -136,13 +146,15 @@ impl TaskContext {
     /// - `from` only: Compare `from..HEAD`
     /// - `to` only: Compare `<fallback-base>..to`
     /// - Neither: Compare `<fallback-base>..HEAD`
+    #[must_use]
     pub fn for_pr(from: Option<String>, to: Option<String>) -> Self {
         Self::for_pr_with_base(from, to, "main")
     }
 
     /// Create PR context with an explicit default comparison base.
     ///
     /// CLI and Studio should prefer a repo-aware base from `GitRepo::get_default_base_ref()`.
+    #[must_use]
     pub fn for_pr_with_base(from: Option<String>, to: Option<String>, default_base: &str) -> Self {
         match (from, to) {
             (Some(f), Some(t)) => Self::Range { from: f, to: t },
@@ -165,6 +177,7 @@ impl TaskContext {
     ///
     /// These always require a `from` reference; `to` defaults to HEAD.
     /// Automatically sets today's date if not provided.
+    #[must_use]
     pub fn for_changelog(
         from: String,
         to: Option<String>,
@@ -180,11 +193,13 @@ impl TaskContext {
     }
 
     /// Generate a human-readable prompt context string for the agent.
+    #[must_use]
     pub fn to_prompt_context(&self) -> String {
         serde_json::to_string_pretty(self).unwrap_or_else(|_| format!("{self:?}"))
     }
 
     /// Generate a hint for which `git_diff` call the agent should make.
+    #[must_use]
     pub fn diff_hint(&self) -> String {
         match self {
             Self::Staged { include_unstaged } => {
@@ -208,11 +223,13 @@ impl TaskContext {
     }
 
     /// Check if this context represents a range comparison (vs staged/single commit)
+    #[must_use]
     pub fn is_range(&self) -> bool {
         matches!(self, Self::Range { .. })
     }
 
     /// Check if this context involves unstaged changes
+    #[must_use]
     pub fn includes_unstaged(&self) -> bool {
         matches!(
             self,
@@ -223,11 +240,13 @@ impl TaskContext {
     }
 
     /// Check if this is an amend operation
+    #[must_use]
     pub fn is_amend(&self) -> bool {
         matches!(self, Self::Amend { .. })
     }
 
     /// Get the original commit message if this is an amend context
+    #[must_use]
     pub fn original_message(&self) -> Option<&str> {
         match self {
             Self::Amend { original_message } => Some(original_message),

src/agents/core.rs

@@ -16,6 +16,7 @@ pub struct AgentBackend {
 }
 
 impl AgentBackend {
+    #[must_use]
     pub fn new(provider_name: String, model: String, fast_model: String) -> Self {
         Self {
             provider_name,
@@ -25,6 +26,10 @@ impl AgentBackend {
     }
 
     /// Create backend from Git-Iris configuration
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the configured provider name is invalid or missing configuration.
     pub fn from_config(config: &Config) -> Result<Self> {
         let provider: crate::providers::Provider = config
             .default_provider
@@ -53,17 +58,20 @@ pub struct AgentContext {
 }
 
 impl AgentContext {
+    #[must_use]
     pub fn new(config: Config, git_repo: GitRepo) -> Self {
         Self {
             config,
             git_repo: Arc::new(git_repo),
         }
     }
 
+    #[must_use]
     pub fn repo(&self) -> &GitRepo {
         &self.git_repo
     }
 
+    #[must_use]
     pub fn config(&self) -> &Config {
         &self.config
     }
@@ -80,6 +88,7 @@ pub struct TaskResult {
 }
 
 impl TaskResult {
+    #[must_use]
     pub fn success(message: String) -> Self {
         Self {
             success: true,
@@ -90,6 +99,7 @@ impl TaskResult {
         }
     }
 
+    #[must_use]
     pub fn success_with_data(message: String, data: serde_json::Value) -> Self {
         Self {
             success: true,
@@ -100,6 +110,7 @@ impl TaskResult {
         }
     }
 
+    #[must_use]
     pub fn failure(message: String) -> Self {
         Self {
             success: false,
@@ -110,11 +121,13 @@ impl TaskResult {
         }
     }
 
+    #[must_use]
     pub fn with_confidence(mut self, confidence: f64) -> Self {
         self.confidence = confidence;
         self
     }
 
+    #[must_use]
     pub fn with_execution_time(mut self, duration: std::time::Duration) -> Self {
         self.execution_time = Some(duration);
         self

src/agents/debug.rs

@@ -62,6 +62,10 @@ fn debug_artifacts_dir() -> io::Result<PathBuf> {
 }
 
 /// Write debug artifact with restrictive permissions and return the file path.
+///
+/// # Errors
+///
+/// Returns an error when the artifact directory or file cannot be created.
 pub fn write_debug_artifact(filename: &str, contents: &str) -> io::Result<PathBuf> {
     let mut path = debug_artifacts_dir()?;
     path.push(filename);

src/agents/iris.rs

@@ -451,6 +451,10 @@ pub struct IrisAgent {
 
 impl IrisAgent {
     /// Create a new Iris agent with the given provider and model
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the provider or model configuration is invalid.
     pub fn new(provider: &str, model: &str) -> Result<Self> {
         Ok(Self {
             provider: provider.to_string(),
@@ -892,6 +896,10 @@ Guidelines:
     /// Execute a task with the given capability and user prompt
     ///
     /// This now automatically uses structured output based on the capability type
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when capability loading, agent construction, or generation fails.
     pub async fn execute_task(
         &mut self,
         capability: &str,
@@ -990,6 +998,10 @@ Guidelines:
     /// The callback receives `(chunk, aggregated_text)` for each delta.
     ///
     /// Returns the final structured response after streaming completes.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when capability loading, agent construction, or streaming fails.
     pub async fn execute_task_streaming<F>(
         &mut self,
         capability: &str,
@@ -1227,11 +1239,16 @@ Guidelines:
     }
 
     /// Get the current capability being executed
+    #[must_use]
     pub fn current_capability(&self) -> Option<&str> {
         self.current_capability.as_deref()
     }
 
     /// Simple single-turn execution for basic queries
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the provider request fails.
     pub async fn chat(&self, message: &str) -> Result<String> {
         let agent = self.build_agent()?;
         let response = agent.prompt(message).await?;
@@ -1244,6 +1261,7 @@ Guidelines:
     }
 
     /// Get provider configuration
+    #[must_use]
     pub fn provider_config(&self) -> &HashMap<String, String> {
         &self.provider_config
     }
@@ -1278,6 +1296,7 @@ pub struct IrisAgentBuilder {
 
 impl IrisAgentBuilder {
     /// Create a new builder
+    #[must_use]
     pub fn new() -> Self {
         Self {
             provider: "openai".to_string(),
@@ -1305,6 +1324,10 @@ impl IrisAgentBuilder {
     }
 
     /// Build the `IrisAgent`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the configured provider or model cannot build an agent.
     pub fn build(self) -> Result<IrisAgent> {
         let mut agent = IrisAgent::new(&self.provider, &self.model)?;
 

src/agents/output_validator.rs

@@ -41,6 +41,10 @@ impl<T> ValidationResult<T> {
 }
 
 /// Validate and parse JSON with schema validation and error recovery
+///
+/// # Errors
+///
+/// Returns an error when the JSON cannot be parsed even after recovery attempts.
 pub fn validate_and_parse<T>(json_str: &str) -> Result<ValidationResult<T>>
 where
     T: JsonSchema + DeserializeOwned,