xl-cli-tools

2026-03-17-xldiff.md (58492B)

---

 # xldiff Implementation Plan
 
 > **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** Port go-xldiff to Rust as the `xldiff` binary in this repo, with type-aware comparison and tolerance support.
 
 **Architecture:** New `src/diff.rs` module for core diff logic (data structures, positional/key-based algorithms, tolerance). New `src/bin/xldiff.rs` binary for CLI parsing, file:sheet argument handling, and four output formatters (text, markdown, json, csv). Reuses existing `reader`, `metadata`, `filter` (for `resolve_column`), and `formatter` modules.
 
 **Tech Stack:** Rust, polars (DataFrames), calamine (reading), clap (CLI), serde_json (JSON output), std::io::IsTerminal (TTY detection)
 
 **Spec:** `docs/superpowers/specs/2026-03-17-xldiff-design.md`
 
 ---
 
 ### Task 1: Cargo.toml & lib.rs setup
 
 **Files:**
 - Modify: `Cargo.toml`
 - Modify: `src/lib.rs`
 
 - [ ] **Step 1: Add xldiff binary entry and dependencies to Cargo.toml**
 
 Add after the xlfilter `[[bin]]` block:
 
 ```toml
 [[bin]]
 name = "xldiff"
 path = "src/bin/xldiff.rs"
 ```
 
 Add to `[dependencies]`:
 
 ```toml
 serde_json = { version = "1", features = ["preserve_order"] }
 ```
 
 - [ ] **Step 2: Add diff module to lib.rs**
 
 ```rust
 pub mod cell;
 pub mod diff;
 pub mod filter;
 pub mod formatter;
 pub mod metadata;
 pub mod reader;
 pub mod writer;
 ```
 
 - [ ] **Step 3: Create empty diff.rs so the project compiles**
 
 Create `src/diff.rs`:
 
 ```rust
 // Diff engine for comparing two Excel sheets.
 ```
 
 - [ ] **Step 4: Verify project compiles**
 
 Run: `cargo check`
 Expected: success (no errors)
 
 - [ ] **Step 5: Commit**
 
 ```bash
 git add Cargo.toml src/lib.rs src/diff.rs
 git commit -m "chore: add xldiff binary entry, serde deps, empty diff module"
 ```
 
 ---
 
 ### Task 2: Make formatter helpers public
 
 **Files:**
 - Modify: `src/formatter.rs`
 
 The markdown output formatter in xldiff needs `render_table`, `compute_col_widths`, `render_table_header`, `render_table_rows`, and `format_any_value` from `formatter.rs`. These are currently private.
 
 - [ ] **Step 1: Make the five helper functions public**
 
 In `src/formatter.rs`, change:
 
 - `fn compute_col_widths(` → `pub fn compute_col_widths(`
 - `fn render_table_header(` → `pub fn render_table_header(`
 - `fn render_table_rows(` → `pub fn render_table_rows(`
 - `fn render_table(` → `pub fn render_table(`
 - `fn format_any_value(` → `pub fn format_any_value(`
 
 - [ ] **Step 2: Verify project compiles**
 
 Run: `cargo check`
 Expected: success
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/formatter.rs
 git commit -m "refactor: make formatter table helpers public for xldiff reuse"
 ```
 
 ---
 
 ### Task 3: Make `col_letter_to_index` and `resolve_column` available from filter module
 
 **Files:**
 - Modify: `src/filter.rs`
 
 `col_letter_to_index` is currently private in `filter.rs`. The xldiff binary needs `resolve_column` (already public) and `resolve_columns` (already public), which internally use `col_letter_to_index`. Since `resolve_column` is already public, no changes are needed here — xldiff will call `xlcat::filter::resolve_column()` directly.
 
 **This task is a no-op** — confirming that the existing public API is sufficient. Skip to Task 4.
 
 ---
 
 ### Task 4: diff.rs — data structures
 
 **Files:**
 - Modify: `src/diff.rs`
 
 - [ ] **Step 1: Write the data structures**
 
 ```rust
 use polars::prelude::*;
 
 /// Source file and sheet metadata for display.
 #[derive(Debug, Clone)]
 pub struct SheetSource {
     pub file_name: String,
     pub sheet_name: String,
 }
 
 /// A single row from an added or removed set.
 #[derive(Debug, Clone)]
 pub struct DiffRow {
     pub values: Vec<String>,
 }
 
 /// A change in a single cell.
 #[derive(Debug, Clone)]
 pub struct CellChange {
     pub column: String,
     pub old_value: String,
     pub new_value: String,
 }
 
 /// A row present in both files with cell-level differences.
 #[derive(Debug, Clone)]
 pub struct ModifiedRow {
     pub key: Vec<String>,
     pub changes: Vec<CellChange>,
 }
 
 /// Result of comparing two sheets.
 #[derive(Debug, Clone)]
 pub struct DiffResult {
     pub headers: Vec<String>,
     pub key_columns: Vec<String>,
     pub added: Vec<DiffRow>,
     pub removed: Vec<DiffRow>,
     pub modified: Vec<ModifiedRow>,
     pub source_a: SheetSource,
     pub source_b: SheetSource,
 }
 
 impl DiffResult {
     pub fn has_differences(&self) -> bool {
         !self.added.is_empty() || !self.removed.is_empty() || !self.modified.is_empty()
     }
 }
 
 /// Options controlling how the diff is performed.
 #[derive(Debug, Clone, Default)]
 pub struct DiffOptions {
     pub key_columns: Vec<String>,
     pub tolerance: Option<f64>,
 }
 ```
 
 - [ ] **Step 2: Verify project compiles**
 
 Run: `cargo check`
 Expected: success
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/diff.rs
 git commit -m "feat(xldiff): add diff data structures — DiffResult, DiffRow, ModifiedRow, CellChange"
 ```
 
 ---
 
 ### Task 5: diff.rs — positional mode
 
 **Files:**
 - Modify: `src/diff.rs`
 - Create: `tests/test_xldiff.rs` (unit tests only at first)
 
 - [ ] **Step 1: Write the failing test for positional diff**
 
 Add at the bottom of `src/diff.rs`:
 
 ```rust
 #[cfg(test)]
 mod tests {
     use super::*;
 
     fn make_source(name: &str) -> SheetSource {
         SheetSource {
             file_name: format!("{name}.xlsx"),
             sheet_name: "Sheet1".to_string(),
         }
     }
 
     #[test]
     fn test_positional_no_diff() {
         let s1 = Series::new("name".into(), &["Alice", "Bob"]);
         let s2 = Series::new("score".into(), &[90i64, 80]);
         let df_a = DataFrame::new(vec![s1.clone().into_column(), s2.clone().into_column()]).unwrap();
         let df_b = DataFrame::new(vec![s1.into_column(), s2.into_column()]).unwrap();
 
         let opts = DiffOptions::default();
         let result = diff_positional(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert!(!result.has_differences());
         assert!(result.added.is_empty());
         assert!(result.removed.is_empty());
     }
 
     #[test]
     fn test_positional_added_removed() {
         let df_a = DataFrame::new(vec![
             Series::new("name".into(), &["Alice", "Bob"]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("name".into(), &["Alice", "Charlie"]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions::default();
         let result = diff_positional(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert_eq!(result.removed.len(), 1);
         assert_eq!(result.removed[0].values, vec!["Bob"]);
         assert_eq!(result.added.len(), 1);
         assert_eq!(result.added[0].values, vec!["Charlie"]);
         assert!(result.modified.is_empty());
     }
 
     #[test]
     fn test_positional_duplicate_rows() {
         let df_a = DataFrame::new(vec![
             Series::new("x".into(), &["A", "A", "A"]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("x".into(), &["A", "A"]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions::default();
         let result = diff_positional(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert_eq!(result.removed.len(), 1);
         assert!(result.added.is_empty());
     }
 }
 ```
 
 - [ ] **Step 2: Run tests to verify they fail**
 
 Run: `cargo test --lib diff::tests`
 Expected: FAIL — `diff_positional` not found
 
 - [ ] **Step 3: Implement positional diff**
 
 Add to `src/diff.rs` before the tests module:
 
 ```rust
 use crate::formatter;
 use std::collections::HashMap;
 
 /// Format a cell value for hashing/display, using a null sentinel to distinguish null from empty.
 fn cell_to_string(col: &Column, idx: usize) -> String {
     match col.get(idx) {
         Ok(AnyValue::Null) | Err(_) => String::new(),
         Ok(v) => formatter::format_any_value(&v),
     }
 }
 
 fn cell_to_key_part(col: &Column, idx: usize) -> String {
     match col.get(idx) {
         Ok(AnyValue::Null) | Err(_) => "\x01NULL\x01".to_string(),
         Ok(v) => formatter::format_any_value(&v),
     }
 }
 
 /// Convert a DataFrame row to a string key by joining cell values with null bytes.
 fn row_to_key(df: &DataFrame, row_idx: usize) -> String {
     let cols = df.get_columns();
     let parts: Vec<String> = cols
         .iter()
         .map(|c| cell_to_key_part(c, row_idx))
         .collect();
     parts.join("\0")
 }
 
 /// Convert a DataFrame row to a Vec<String> of display values.
 fn row_to_strings(df: &DataFrame, row_idx: usize) -> Vec<String> {
     df.get_columns()
         .iter()
         .map(|c| cell_to_string(c, row_idx))
         .collect()
 }
 
 /// Positional diff: treats entire row as identity using multiset comparison.
 pub fn diff_positional(
     df_a: &DataFrame,
     df_b: &DataFrame,
     _opts: &DiffOptions,
     source_a: SheetSource,
     source_b: SheetSource,
 ) -> anyhow::Result<DiffResult> {
     let headers_a: Vec<String> = df_a.get_column_names().iter().map(|s| s.to_string()).collect();
     let headers_b: Vec<String> = df_b.get_column_names().iter().map(|s| s.to_string()).collect();
 
     // Warn about mismatched column counts in positional mode
     if headers_a.len() != headers_b.len() {
         eprintln!(
             "warning: column count differs ({} vs {}), padding shorter side with empty values",
             headers_a.len(), headers_b.len()
         );
     }
 
     // Use headers from the file with more columns
     let headers = if headers_b.len() > headers_a.len() { headers_b } else { headers_a };
 
     // Build frequency maps
     let mut counts_a: HashMap<String, Vec<usize>> = HashMap::new();
     for i in 0..df_a.height() {
         counts_a.entry(row_to_key(df_a, i)).or_default().push(i);
     }
     let mut counts_b: HashMap<String, Vec<usize>> = HashMap::new();
     for i in 0..df_b.height() {
         counts_b.entry(row_to_key(df_b, i)).or_default().push(i);
     }
 
     let mut removed = Vec::new();
     let mut consumed_b: HashMap<String, usize> = HashMap::new();
 
     // Walk A: try to match with B
     for i in 0..df_a.height() {
         let key = row_to_key(df_a, i);
         let b_count = counts_b.get(&key).map(|v| v.len()).unwrap_or(0);
         let already_consumed = consumed_b.get(&key).copied().unwrap_or(0);
         if already_consumed < b_count {
             *consumed_b.entry(key).or_insert(0) += 1;
         } else {
             let mut vals = row_to_strings(df_a, i);
             vals.resize(headers.len(), String::new()); // pad if needed
             removed.push(DiffRow { values: vals });
         }
     }
 
     // Walk B: anything not consumed is added
     let mut consumed_a: HashMap<String, usize> = HashMap::new();
     let mut added = Vec::new();
     for i in 0..df_b.height() {
         let key = row_to_key(df_b, i);
         let a_count = counts_a.get(&key).map(|v| v.len()).unwrap_or(0);
         let already_consumed = consumed_a.get(&key).copied().unwrap_or(0);
         if already_consumed < a_count {
             *consumed_a.entry(key).or_insert(0) += 1;
         } else {
             let mut vals = row_to_strings(df_b, i);
             vals.resize(headers.len(), String::new()); // pad if needed
             added.push(DiffRow { values: vals });
         }
     }
 
     Ok(DiffResult {
         headers,
         key_columns: vec![],
         added,
         removed,
         modified: vec![],
         source_a,
         source_b,
     })
 }
 ```
 
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cargo test --lib diff::tests`
 Expected: all 3 tests PASS
 
 - [ ] **Step 5: Commit**
 
 ```bash
 git add src/diff.rs
 git commit -m "feat(xldiff): implement positional diff with multiset comparison"
 ```
 
 ---
 
 ### Task 6: diff.rs — key-based mode
 
 **Files:**
 - Modify: `src/diff.rs`
 
 - [ ] **Step 1: Write failing tests for key-based diff**
 
 Add to the `tests` module in `src/diff.rs`:
 
 ```rust
     #[test]
     fn test_keyed_no_diff() {
         let df_a = DataFrame::new(vec![
             Series::new("id".into(), &["1", "2"]).into_column(),
             Series::new("val".into(), &[10i64, 20]).into_column(),
         ]).unwrap();
         let df_b = df_a.clone();
 
         let opts = DiffOptions { key_columns: vec!["id".to_string()], ..Default::default() };
         let result = diff_keyed(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert!(!result.has_differences());
     }
 
     #[test]
     fn test_keyed_added_removed() {
         let df_a = DataFrame::new(vec![
             Series::new("id".into(), &["1", "2"]).into_column(),
             Series::new("val".into(), &[10i64, 20]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("id".into(), &["2", "3"]).into_column(),
             Series::new("val".into(), &[20i64, 30]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions { key_columns: vec!["id".to_string()], ..Default::default() };
         let result = diff_keyed(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert_eq!(result.removed.len(), 1);
         assert_eq!(result.added.len(), 1);
         assert_eq!(result.removed[0].values, vec!["1", "10"]);
         assert_eq!(result.added[0].values, vec!["3", "30"]);
     }
 
     #[test]
     fn test_keyed_modified() {
         let df_a = DataFrame::new(vec![
             Series::new("id".into(), &["1", "2"]).into_column(),
             Series::new("score".into(), &[90i64, 80]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("id".into(), &["1", "2"]).into_column(),
             Series::new("score".into(), &[95i64, 80]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions { key_columns: vec!["id".to_string()], ..Default::default() };
         let result = diff_keyed(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert!(result.added.is_empty());
         assert!(result.removed.is_empty());
         assert_eq!(result.modified.len(), 1);
         assert_eq!(result.modified[0].key, vec!["1"]);
         assert_eq!(result.modified[0].changes.len(), 1);
         assert_eq!(result.modified[0].changes[0].column, "score");
         assert_eq!(result.modified[0].changes[0].old_value, "90");
         assert_eq!(result.modified[0].changes[0].new_value, "95");
     }
 
     #[test]
     fn test_keyed_composite_key() {
         let df_a = DataFrame::new(vec![
             Series::new("date".into(), &["2024-01", "2024-01"]).into_column(),
             Series::new("ticker".into(), &["AAPL", "GOOG"]).into_column(),
             Series::new("price".into(), &[150i64, 100]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("date".into(), &["2024-01", "2024-01"]).into_column(),
             Series::new("ticker".into(), &["AAPL", "GOOG"]).into_column(),
             Series::new("price".into(), &[155i64, 100]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions {
             key_columns: vec!["date".to_string(), "ticker".to_string()],
             ..Default::default()
         };
         let result = diff_keyed(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert_eq!(result.modified.len(), 1);
         assert_eq!(result.modified[0].key, vec!["2024-01", "AAPL"]);
     }
 ```
 
 - [ ] **Step 2: Run tests to verify they fail**
 
 Run: `cargo test --lib diff::tests`
 Expected: FAIL — `diff_keyed` not found
 
 - [ ] **Step 3: Implement key-based diff**
 
 Add to `src/diff.rs`:
 
 ```rust
 /// Row data stored during key-based comparison.
 struct KeyedRow {
     values: Vec<String>,
     key_values: Vec<String>,
 }
 
 /// Key-based diff: match rows by key columns, compare remaining cells.
 pub fn diff_keyed(
     df_a: &DataFrame,
     df_b: &DataFrame,
     opts: &DiffOptions,
     source_a: SheetSource,
     source_b: SheetSource,
 ) -> anyhow::Result<DiffResult> {
     let headers_a: Vec<String> = df_a.get_column_names().iter().map(|s| s.to_string()).collect();
     let headers_b: Vec<String> = df_b.get_column_names().iter().map(|s| s.to_string()).collect();
 
     // Resolve key column indices for both frames
     let key_indices_a: Vec<usize> = opts.key_columns.iter()
         .map(|k| headers_a.iter().position(|h| h == k)
             .ok_or_else(|| anyhow::anyhow!("key column '{}' not found in first file", k)))
         .collect::<anyhow::Result<Vec<_>>>()?;
 
     let key_indices_b: Vec<usize> = opts.key_columns.iter()
         .map(|k| headers_b.iter().position(|h| h == k)
             .ok_or_else(|| anyhow::anyhow!("key column '{}' not found in second file", k)))
         .collect::<anyhow::Result<Vec<_>>>()?;
 
     // Find common non-key columns for comparison
     let non_key_a: Vec<String> = headers_a.iter()
         .filter(|h| !opts.key_columns.contains(h))
         .cloned().collect();
     let non_key_b: Vec<String> = headers_b.iter()
         .filter(|h| !opts.key_columns.contains(h))
         .cloned().collect();
     let common_non_key: Vec<String> = non_key_a.iter()
         .filter(|h| non_key_b.contains(h))
         .cloned().collect();
 
     // Warn about columns only in one file
     for col in &non_key_a {
         if !non_key_b.contains(col) {
             eprintln!("warning: column '{}' only in first file, skipping", col);
         }
     }
     for col in &non_key_b {
         if !non_key_a.contains(col) {
             eprintln!("warning: column '{}' only in second file, skipping", col);
         }
     }
 
     // Headers = key columns + union of non-key columns (common first, then only-in-A, only-in-B)
     let mut headers = opts.key_columns.clone();
     headers.extend(non_key_a.iter().chain(
         non_key_b.iter().filter(|h| !non_key_a.contains(h))
     ).cloned());
 
     // Build row maps
     let map_a = build_key_map(df_a, &key_indices_a);
     let map_b = build_key_map(df_b, &key_indices_b);
 
     // Detect duplicate keys
     check_duplicate_keys(df_a, &key_indices_a, &source_a);
     check_duplicate_keys(df_b, &key_indices_b, &source_b);
 
     let mut added = Vec::new();
     let mut removed = Vec::new();
     let mut modified = Vec::new();
 
     // Removed: keys in A but not B
     for (key_str, row_a) in &map_a {
         if !map_b.contains_key(key_str) {
             removed.push(DiffRow { values: row_a.values.clone() });
         }
     }
 
     // Added: keys in B but not A; Modified: keys in both
     for (key_str, row_b) in &map_b {
         match map_a.get(key_str) {
             None => {
                 added.push(DiffRow { values: row_b.values.clone() });
             }
             Some(row_a) => {
                 let changes = compare_rows(
                     df_a, df_b,
                     &headers_a, &headers_b,
                     row_a, row_b,
                     &common_non_key,
                     opts,
                 );
                 if !changes.is_empty() {
                     modified.push(ModifiedRow {
                         key: row_a.key_values.clone(),
                         changes,
                     });
                 }
             }
         }
     }
 
     Ok(DiffResult {
         headers,
         key_columns: opts.key_columns.clone(),
         added,
         removed,
         modified,
         source_a,
         source_b,
     })
 }
 
 fn build_key_map(df: &DataFrame, key_indices: &[usize]) -> HashMap<String, KeyedRow> {
     let cols = df.get_columns();
     let mut map = HashMap::new();
     for i in 0..df.height() {
         let key_values: Vec<String> = key_indices.iter()
             .map(|&idx| formatter::format_any_value(&cols[idx].get(i).unwrap_or(AnyValue::Null)))
             .collect();
         let key_str = key_values.join("\0");
         let values: Vec<String> = cols.iter()
             .map(|c| formatter::format_any_value(&c.get(i).unwrap_or(AnyValue::Null)))
             .collect();
         map.insert(key_str, KeyedRow { values, key_values });
     }
     map
 }
 
 fn check_duplicate_keys(df: &DataFrame, key_indices: &[usize], source: &SheetSource) {
     let cols = df.get_columns();
     let mut seen: HashMap<String, usize> = HashMap::new();
     for i in 0..df.height() {
         let key: Vec<String> = key_indices.iter()
             .map(|&idx| formatter::format_any_value(&cols[idx].get(i).unwrap_or(AnyValue::Null)))
             .collect();
         let key_str = key.join(", ");
         let count = seen.entry(key_str.clone()).or_insert(0);
         *count += 1;
         if *count == 2 {
             eprintln!("warning: duplicate key \"{}\" in {}", key_str, source.file_name);
         }
     }
 }
 
 /// Compare non-key columns of two matched rows.
 fn compare_rows(
     df_a: &DataFrame,
     df_b: &DataFrame,
     headers_a: &[String],
     headers_b: &[String],
     row_a: &KeyedRow,
     row_b: &KeyedRow,
     common_columns: &[String],
     opts: &DiffOptions,
 ) -> Vec<CellChange> {
     let mut changes = Vec::new();
     for col_name in common_columns {
         let idx_a = headers_a.iter().position(|h| h == col_name).unwrap();
         let idx_b = headers_b.iter().position(|h| h == col_name).unwrap();
         let val_a = &row_a.values[idx_a];
         let val_b = &row_b.values[idx_b];
 
         let is_equal = if let Some(tol) = opts.tolerance {
             values_equal_with_tolerance(val_a, val_b, tol, df_a, df_b, col_name)
         } else {
             val_a == val_b
         };
 
         if !is_equal {
             changes.push(CellChange {
                 column: col_name.clone(),
                 old_value: val_a.clone(),
                 new_value: val_b.clone(),
             });
         }
     }
     changes
 }
 
 fn is_float_dtype(dt: &DataType) -> bool {
     matches!(dt, DataType::Float32 | DataType::Float64)
 }
 
 fn is_int_dtype(dt: &DataType) -> bool {
     matches!(dt, DataType::Int8 | DataType::Int16 | DataType::Int32 | DataType::Int64
         | DataType::UInt8 | DataType::UInt16 | DataType::UInt32 | DataType::UInt64)
 }
 
 /// Check if two values are equal, applying tolerance for float columns.
 /// Tolerance applies to Float64 columns and Int64-vs-Float64 cross-type,
 /// but NOT to pure integer columns (spec requirement).
 fn values_equal_with_tolerance(
     val_a: &str,
     val_b: &str,
     tolerance: f64,
     df_a: &DataFrame,
     df_b: &DataFrame,
     col_name: &str,
 ) -> bool {
     if let (Ok(a), Ok(b)) = (val_a.parse::<f64>(), val_b.parse::<f64>()) {
         // Handle NaN
         if a.is_nan() && b.is_nan() {
             return true;
         }
         if a.is_nan() || b.is_nan() {
             return false;
         }
         let type_a = df_a.column(col_name).ok().map(|c| c.dtype().clone());
         let type_b = df_b.column(col_name).ok().map(|c| c.dtype().clone());
 
         let a_is_float = type_a.as_ref().map_or(false, is_float_dtype);
         let b_is_float = type_b.as_ref().map_or(false, is_float_dtype);
         let a_is_int = type_a.as_ref().map_or(false, is_int_dtype);
         let b_is_int = type_b.as_ref().map_or(false, is_int_dtype);
 
         // Pure integer columns: exact comparison, no tolerance
         if a_is_int && b_is_int {
             return val_a == val_b;
         }
         // At least one float, or cross-type int/float: apply tolerance
         if a_is_float || b_is_float {
             return (a - b).abs() <= tolerance;
         }
     }
     // Fallback: exact string comparison
     val_a == val_b
 }
 ```
 
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cargo test --lib diff::tests`
 Expected: all 7 tests PASS
 
 - [ ] **Step 5: Commit**
 
 ```bash
 git add src/diff.rs
 git commit -m "feat(xldiff): implement key-based diff with composite keys and duplicate detection"
 ```
 
 ---
 
 ### Task 7: diff.rs — tolerance tests
 
 **Files:**
 - Modify: `src/diff.rs`
 
 - [ ] **Step 1: Write tolerance tests**
 
 Add to the `tests` module:
 
 ```rust
     #[test]
     fn test_keyed_tolerance_within() {
         let df_a = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("price".into(), &[100.001f64]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("price".into(), &[100.002f64]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions {
             key_columns: vec!["id".to_string()],
             tolerance: Some(0.01),
         };
         let result = diff_keyed(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert!(!result.has_differences(), "values within tolerance should be equal");
     }
 
     #[test]
     fn test_keyed_tolerance_exceeded() {
         let df_a = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("price".into(), &[100.0f64]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("price".into(), &[100.05f64]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions {
             key_columns: vec!["id".to_string()],
             tolerance: Some(0.01),
         };
         let result = diff_keyed(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert_eq!(result.modified.len(), 1);
     }
 
     #[test]
     fn test_keyed_nan_handling() {
         let df_a = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("val".into(), &[f64::NAN]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("val".into(), &[f64::NAN]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions {
             key_columns: vec!["id".to_string()],
             tolerance: Some(0.01),
         };
         let result = diff_keyed(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert!(!result.has_differences(), "NaN == NaN should be equal");
     }
 ```
 
 - [ ] **Step 2: Run tests**
 
 Run: `cargo test --lib diff::tests`
 Expected: all 10 tests PASS
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/diff.rs
 git commit -m "test(xldiff): add tolerance and NaN handling tests"
 ```
 
 ---
 
 ### Task 8: diff.rs — public entry point `diff_sheets`
 
 **Files:**
 - Modify: `src/diff.rs`
 
 - [ ] **Step 1: Write test for the unified entry point**
 
 Add to tests:
 
 ```rust
     #[test]
     fn test_diff_sheets_positional() {
         let df_a = DataFrame::new(vec![
             Series::new("x".into(), &["a", "b"]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("x".into(), &["a", "c"]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions::default(); // no key → positional
         let result = diff_sheets(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert_eq!(result.removed.len(), 1);
         assert_eq!(result.added.len(), 1);
     }
 
     #[test]
     fn test_diff_sheets_keyed() {
         let df_a = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("v".into(), &[10i64]).into_column(),
         ]).unwrap();
         let df_b = DataFrame::new(vec![
             Series::new("id".into(), &["1"]).into_column(),
             Series::new("v".into(), &[20i64]).into_column(),
         ]).unwrap();
 
         let opts = DiffOptions { key_columns: vec!["id".to_string()], ..Default::default() };
         let result = diff_sheets(&df_a, &df_b, &opts, make_source("a"), make_source("b")).unwrap();
         assert_eq!(result.modified.len(), 1);
     }
 ```
 
 - [ ] **Step 2: Run tests to verify they fail**
 
 Run: `cargo test --lib diff::tests::test_diff_sheets`
 Expected: FAIL
 
 - [ ] **Step 3: Implement `diff_sheets`**
 
 Add to `src/diff.rs`:
 
 ```rust
 /// Compare two DataFrames. Dispatches to positional or key-based mode.
 pub fn diff_sheets(
     df_a: &DataFrame,
     df_b: &DataFrame,
     opts: &DiffOptions,
     source_a: SheetSource,
     source_b: SheetSource,
 ) -> anyhow::Result<DiffResult> {
     if opts.key_columns.is_empty() {
         diff_positional(df_a, df_b, opts, source_a, source_b)
     } else {
         diff_keyed(df_a, df_b, opts, source_a, source_b)
     }
 }
 ```
 
 - [ ] **Step 4: Run tests**
 
 Run: `cargo test --lib diff::tests`
 Expected: all 12 tests PASS
 
 - [ ] **Step 5: Commit**
 
 ```bash
 git add src/diff.rs
 git commit -m "feat(xldiff): add diff_sheets entry point dispatching positional/keyed modes"
 ```
 
 ---
 
 ### Task 9: xldiff.rs — CLI skeleton + file:sheet parsing
 
 **Files:**
 - Create: `src/bin/xldiff.rs`
 
 - [ ] **Step 1: Write the CLI binary with clap args and file:sheet parsing**
 
 Create `src/bin/xldiff.rs`:
 
 ```rust
 use std::io::IsTerminal;
 use std::path::PathBuf;
 use std::process;
 
 use anyhow::Result;
 use clap::Parser;
 
 use xlcat::diff::{self, DiffOptions, DiffResult, SheetSource};
 use xlcat::filter;
 use xlcat::metadata;
 use xlcat::reader;
 
 #[derive(Parser)]
 #[command(
     name = "xldiff",
     about = "Compare two Excel sheets and report differences",
     version
 )]
 struct Args {
     /// First file, optionally with :sheet suffix (e.g., old.xlsx:Sales)
     file_a: String,
 
     /// Second file, optionally with :sheet suffix
     file_b: String,
 
     /// Comma-separated key columns for row matching (name or column letter).
     /// Omit for positional (whole-row) comparison.
     #[arg(long)]
     key: Option<String>,
 
     /// Comma-separated columns to compare (name or column letter).
     /// Default: all columns. Key columns are always included.
     #[arg(long)]
     cols: Option<String>,
 
     /// Rows to skip before header. Single value for both files, or N,M for independent skips.
     #[arg(long, default_value = "0")]
     skip: String,
 
     /// Treat first row as data; generate synthetic column_0, column_1, … headers.
     /// NOTE: declared for CLI compatibility but not yet implemented — follow-up task.
     #[arg(long)]
     no_header: bool,
 
     /// Numeric tolerance for float comparisons (e.g., 0.01)
     #[arg(long)]
     tolerance: Option<f64>,
 
     /// Output format: text (default), markdown, json, csv
     #[arg(long, default_value = "text")]
     format: String,
 
     /// Force-disable ANSI colors
     #[arg(long)]
     no_color: bool,
 }
 
 /// Parse a file argument like "path.xlsx:Sheet1" into (path, Option<sheet>).
 /// Uses rfind(':') to handle Windows drive letters (C:\...).
 fn parse_file_arg(arg: &str) -> (PathBuf, Option<String>) {
     if let Some(colon_pos) = arg.rfind(':') {
         // Don't split if the colon is part of a Windows drive letter (e.g., C:\)
         // A drive letter colon is at position 1 and followed by \ or /
         if colon_pos == 1 && arg.len() > 2 && (arg.as_bytes()[2] == b'\\' || arg.as_bytes()[2] == b'/') {
             return (PathBuf::from(arg), None);
         }
         // Don't split if nothing after the colon
         if colon_pos == arg.len() - 1 {
             return (PathBuf::from(&arg[..colon_pos]), None);
         }
         let path = PathBuf::from(&arg[..colon_pos]);
         let sheet = arg[colon_pos + 1..].to_string();
         (path, Some(sheet))
     } else {
         (PathBuf::from(arg), None)
     }
 }
 
 /// Parse the --skip flag: "3" or "3,5"
 fn parse_skip(s: &str) -> Result<(usize, usize)> {
     if let Some((a, b)) = s.split_once(',') {
         let skip_a = a.trim().parse::<usize>().map_err(|_| anyhow::anyhow!("invalid skip value: {}", a))?;
         let skip_b = b.trim().parse::<usize>().map_err(|_| anyhow::anyhow!("invalid skip value: {}", b))?;
         Ok((skip_a, skip_b))
     } else {
         let skip = s.trim().parse::<usize>().map_err(|_| anyhow::anyhow!("invalid skip value: {}", s))?;
         Ok((skip, skip))
     }
 }
 
 /// Resolve sheet name from user input or default to first sheet.
 fn resolve_sheet(info: &metadata::FileInfo, sheet_arg: Option<&str>) -> Result<String> {
     match sheet_arg {
         None => info.sheets.first()
             .map(|s| s.name.clone())
             .ok_or_else(|| anyhow::anyhow!("workbook has no sheets")),
         Some(s) => {
             // Try exact name match
             if let Some(sheet) = info.sheets.iter().find(|si| si.name == s) {
                 return Ok(sheet.name.clone());
             }
             // Try as 0-based index
             if let Ok(idx) = s.parse::<usize>() {
                 if let Some(sheet) = info.sheets.get(idx) {
                     return Ok(sheet.name.clone());
                 }
             }
             let names: Vec<_> = info.sheets.iter().map(|s| s.name.as_str()).collect();
             anyhow::bail!("sheet '{}' not found. Available: {}", s, names.join(", "))
         }
     }
 }
 
 fn run(args: Args) -> Result<()> {
     let (path_a, sheet_sel_a) = parse_file_arg(&args.file_a);
     let (path_b, sheet_sel_b) = parse_file_arg(&args.file_b);
 
     // Validate files exist
     if !path_a.exists() {
         anyhow::bail!("file not found: {}", path_a.display());
     }
     if !path_b.exists() {
         anyhow::bail!("file not found: {}", path_b.display());
     }
 
     // Validate format
     let format = match args.format.as_str() {
         "text" | "markdown" | "json" | "csv" => args.format.as_str(),
         other => anyhow::bail!("unknown format '{}'. Use: text, markdown, json, csv", other),
     };
 
     // Parse skip
     let (skip_a, skip_b) = parse_skip(&args.skip)?;
 
     // Resolve sheets
     let info_a = metadata::read_file_info(&path_a)?;
     let info_b = metadata::read_file_info(&path_b)?;
     let sheet_a = resolve_sheet(&info_a, sheet_sel_a.as_deref())?;
     let sheet_b = resolve_sheet(&info_b, sheet_sel_b.as_deref())?;
 
     // Read DataFrames
     let df_a = if skip_a > 0 {
         reader::read_sheet_with_skip(&path_a, &sheet_a, skip_a)?
     } else {
         reader::read_sheet(&path_a, &sheet_a)?
     };
     let df_b = if skip_b > 0 {
         reader::read_sheet_with_skip(&path_b, &sheet_b, skip_b)?
     } else {
         reader::read_sheet(&path_b, &sheet_b)?
     };
 
     // Resolve key columns (validate they exist in both files)
     let key_columns: Vec<String> = if let Some(ref key_str) = args.key {
         let specs: Vec<String> = key_str.split(',').map(|s| s.trim().to_string()).collect();
         let cols_a: Vec<String> = df_a.get_column_names().iter().map(|s| s.to_string()).collect();
         let cols_b: Vec<String> = df_b.get_column_names().iter().map(|s| s.to_string()).collect();
         let resolved = filter::resolve_columns(&specs, &cols_a)
             .map_err(|e| anyhow::anyhow!("first file: {}", e))?;
         // Validate key columns also exist in second file
         for k in &resolved {
             if !cols_b.iter().any(|c| c == k) {
                 anyhow::bail!("key column '{}' not found in second file", k);
             }
         }
         resolved
     } else {
         vec![]
     };
 
     // Column filtering
     let (df_a, df_b) = if let Some(ref cols_str) = args.cols {
         let specs: Vec<String> = cols_str.split(',').map(|s| s.trim().to_string()).collect();
         let cols_a: Vec<String> = df_a.get_column_names().iter().map(|s| s.to_string()).collect();
         let mut selected = filter::resolve_columns(&specs, &cols_a)
             .map_err(|e| anyhow::anyhow!(e))?;
         // Ensure key columns are included
         for k in &key_columns {
             if !selected.contains(k) {
                 selected.insert(0, k.clone());
             }
         }
         let sel_refs: Vec<&str> = selected.iter().map(|s| s.as_str()).collect();
         let df_a = df_a.select(&sel_refs)?;
         let df_b = df_b.select(&sel_refs)?;
         (df_a, df_b)
     } else {
         (df_a, df_b)
     };
 
     let source_a = SheetSource {
         file_name: path_a.file_name().unwrap_or_default().to_string_lossy().to_string(),
         sheet_name: sheet_a,
     };
     let source_b = SheetSource {
         file_name: path_b.file_name().unwrap_or_default().to_string_lossy().to_string(),
         sheet_name: sheet_b,
     };
 
     let opts = DiffOptions {
         key_columns,
         tolerance: args.tolerance,
     };
 
     let result = diff::diff_sheets(&df_a, &df_b, &opts, source_a, source_b)?;
 
     // Determine color
     let use_color = !args.no_color && std::io::stdout().is_terminal();
 
     // Format and print
     let output = match format {
         "text" => format_text(&result, use_color),
         "markdown" => format_markdown(&result),
         "json" => format_json(&result),
         "csv" => format_csv(&result),
         _ => unreachable!(),
     };
     print!("{output}");
 
     // Exit code
     if result.has_differences() {
         process::exit(1);
     }
     Ok(())
 }
 
 fn main() {
     let args = Args::parse();
     if let Err(err) = run(args) {
         eprintln!("xldiff: {err}");
         process::exit(2);
     }
 }
 
 // Output formatters — implemented in subsequent tasks
 fn format_text(_result: &DiffResult, _color: bool) -> String { todo!() }
 fn format_markdown(_result: &DiffResult) -> String { todo!() }
 fn format_json(_result: &DiffResult) -> String { todo!() }
 fn format_csv(_result: &DiffResult) -> String { todo!() }
 ```
 
 - [ ] **Step 2: Verify it compiles**
 
 Run: `cargo check --bin xldiff`
 Expected: success (todo!() stubs compile but will panic at runtime)
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/bin/xldiff.rs
 git commit -m "feat(xldiff): add CLI skeleton with file:sheet parsing, skip, key/cols resolution"
 ```
 
 ---
 
 ### Task 10: xldiff.rs — text output formatter
 
 **Files:**
 - Modify: `src/bin/xldiff.rs`
 
 - [ ] **Step 1: Implement `format_text`**
 
 Replace the `format_text` stub:
 
 ```rust
 fn format_text(result: &DiffResult, color: bool) -> String {
     if !result.has_differences() {
         return "No differences found.\n".to_string();
     }
 
     let mut out = String::new();
 
     // Header
     let (red, green, yellow, reset) = if color {
         ("\x1b[31m", "\x1b[32m", "\x1b[33m", "\x1b[0m")
     } else {
         ("", "", "", "")
     };
 
     out.push_str(&format!(
         "--- {} ({})\n+++ {} ({})\n\n",
         result.source_a.sheet_name, result.source_a.file_name,
         result.source_b.sheet_name, result.source_b.file_name,
     ));
 
     // Summary
     out.push_str(&format!(
         "Added: {} | Removed: {} | Modified: {}\n\n",
         result.added.len(),
         result.removed.len(),
         result.modified.len(),
     ));
 
     // Removed rows
     for row in &result.removed {
         out.push_str(red);
         out.push_str("- ");
         out.push_str(&format_row_inline(&result.headers, &row.values));
         out.push_str(reset);
         out.push('\n');
     }
 
     // Added rows
     for row in &result.added {
         out.push_str(green);
         out.push_str("+ ");
         out.push_str(&format_row_inline(&result.headers, &row.values));
         out.push_str(reset);
         out.push('\n');
     }
 
     if (!result.removed.is_empty() || !result.added.is_empty()) && !result.modified.is_empty() {
         out.push('\n');
     }
 
     // Modified rows
     for m in &result.modified {
         out.push_str(yellow);
         out.push_str("~ ");
         // Show key
         let key_display: Vec<String> = result.key_columns.iter()
             .zip(m.key.iter())
             .map(|(col, val)| format!("{}: \"{}\"", col, val))
             .collect();
         out.push_str(&key_display.join("  "));
         out.push_str(reset);
         out.push('\n');
         for change in &m.changes {
             out.push_str(yellow);
             out.push_str(&format!("    {}: \"{}\" → \"{}\"", change.column, change.old_value, change.new_value));
             out.push_str(reset);
             out.push('\n');
         }
     }
 
     out
 }
 
 /// Format a row as inline key-value pairs: Name: "Alice"  Score: "90"
 fn format_row_inline(headers: &[String], values: &[String]) -> String {
     headers.iter()
         .zip(values.iter())
         .map(|(h, v)| format!("{}: \"{}\"", h, v))
         .collect::<Vec<_>>()
         .join("  ")
 }
 ```
 
 - [ ] **Step 2: Verify it compiles**
 
 Run: `cargo check --bin xldiff`
 Expected: success
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/bin/xldiff.rs
 git commit -m "feat(xldiff): implement colored text output formatter"
 ```
 
 ---
 
 ### Task 11: xldiff.rs — markdown output formatter
 
 **Files:**
 - Modify: `src/bin/xldiff.rs`
 
 - [ ] **Step 1: Implement `format_markdown`**
 
 Replace the `format_markdown` stub:
 
 ```rust
 fn format_markdown(result: &DiffResult) -> String {
     use xlcat::formatter;
 
     if !result.has_differences() {
         return "No differences found.\n".to_string();
     }
 
     let mut out = String::new();
 
     // Added
     if !result.added.is_empty() {
         out.push_str(&format!("## Added ({})\n", result.added.len()));
         let rows: Vec<Vec<String>> = result.added.iter().map(|r| r.values.clone()).collect();
         out.push_str(&formatter::render_table(&result.headers, &rows));
         out.push('\n');
     }
 
     // Removed
     if !result.removed.is_empty() {
         out.push_str(&format!("## Removed ({})\n", result.removed.len()));
         let rows: Vec<Vec<String>> = result.removed.iter().map(|r| r.values.clone()).collect();
         out.push_str(&formatter::render_table(&result.headers, &rows));
         out.push('\n');
     }
 
     // Modified
     if !result.modified.is_empty() {
         out.push_str(&format!("## Modified ({})\n", result.modified.len()));
         let key_label = if result.key_columns.len() == 1 {
             format!("Key ({})", result.key_columns[0])
         } else {
             format!("Key ({})", result.key_columns.join(", "))
         };
         let mod_headers = vec![key_label, "Column".to_string(), "Old".to_string(), "New".to_string()];
         let mut mod_rows = Vec::new();
         for m in &result.modified {
             let key_str = m.key.join(", ");
             for (i, change) in m.changes.iter().enumerate() {
                 let key_cell = if i == 0 { key_str.clone() } else { String::new() };
                 mod_rows.push(vec![
                     key_cell,
                     change.column.clone(),
                     change.old_value.clone(),
                     change.new_value.clone(),
                 ]);
             }
         }
         out.push_str(&formatter::render_table(&mod_headers, &mod_rows));
         out.push('\n');
     }
 
     out
 }
 ```
 
 - [ ] **Step 2: Verify it compiles**
 
 Run: `cargo check --bin xldiff`
 Expected: success
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/bin/xldiff.rs
 git commit -m "feat(xldiff): implement markdown output formatter"
 ```
 
 ---
 
 ### Task 12: xldiff.rs — JSON output formatter
 
 **Files:**
 - Modify: `src/bin/xldiff.rs`
 
 - [ ] **Step 1: Implement `format_json`**
 
 Replace the `format_json` stub:
 
 ```rust
 fn format_json(result: &DiffResult) -> String {
     use serde_json::{json, Map, Value};
 
     let row_to_obj = |row: &diff::DiffRow| -> Value {
         let mut map = Map::new();
         for (h, v) in result.headers.iter().zip(row.values.iter()) {
             map.insert(h.clone(), Value::String(v.clone()));
         }
         Value::Object(map)
     };
 
     let added: Vec<Value> = result.added.iter().map(row_to_obj).collect();
     let removed: Vec<Value> = result.removed.iter().map(row_to_obj).collect();
 
     let modified: Vec<Value> = result.modified.iter().map(|m| {
         let mut key_map = Map::new();
         for (col, val) in result.key_columns.iter().zip(m.key.iter()) {
             key_map.insert(col.clone(), Value::String(val.clone()));
         }
         let changes: Vec<Value> = m.changes.iter().map(|c| {
             json!({
                 "column": c.column,
                 "old": c.old_value,
                 "new": c.new_value,
             })
         }).collect();
         json!({
             "key": Value::Object(key_map),
             "changes": changes,
         })
     }).collect();
 
     let obj = json!({
         "added": added,
         "removed": removed,
         "modified": modified,
     });
 
     serde_json::to_string_pretty(&obj).unwrap() + "\n"
 }
 ```
 
 - [ ] **Step 2: Verify it compiles**
 
 Run: `cargo check --bin xldiff`
 Expected: success
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/bin/xldiff.rs
 git commit -m "feat(xldiff): implement JSON output formatter"
 ```
 
 ---
 
 ### Task 13: xldiff.rs — CSV output formatter
 
 **Files:**
 - Modify: `src/bin/xldiff.rs`
 
 - [ ] **Step 1: Implement `format_csv`**
 
 Replace the `format_csv` stub:
 
 ```rust
 fn format_csv(result: &DiffResult) -> String {
     let mut out = String::new();
 
     // Header: _status, col1, col2, ..., _old_col1, _old_col2, ...
     let mut header_parts = vec!["_status".to_string()];
     header_parts.extend(result.headers.clone());
     for h in &result.headers {
         header_parts.push(format!("_old_{}", h));
     }
     out.push_str(&csv_row(&header_parts));
 
     // Added rows
     for row in &result.added {
         let mut parts = vec!["added".to_string()];
         parts.extend(row.values.clone());
         // Empty _old_ columns
         for _ in &result.headers {
             parts.push(String::new());
         }
         out.push_str(&csv_row(&parts));
     }
 
     // Removed rows
     for row in &result.removed {
         let mut parts = vec!["removed".to_string()];
         parts.extend(row.values.clone());
         // Empty _old_ columns
         for _ in &result.headers {
             parts.push(String::new());
         }
         out.push_str(&csv_row(&parts));
     }
 
     // Modified rows
     for m in &result.modified {
         let mut main_vals = vec![String::new(); result.headers.len()];
         let mut old_vals = vec![String::new(); result.headers.len()];
 
         // Fill key columns in main values
         for (key_col, key_val) in result.key_columns.iter().zip(m.key.iter()) {
             if let Some(idx) = result.headers.iter().position(|h| h == key_col) {
                 main_vals[idx] = key_val.clone();
             }
         }
 
         // Fill changed columns
         for change in &m.changes {
             if let Some(idx) = result.headers.iter().position(|h| h == &change.column) {
                 main_vals[idx] = change.new_value.clone();
                 old_vals[idx] = change.old_value.clone();
             }
         }
 
         let mut parts = vec!["modified".to_string()];
         parts.extend(main_vals);
         parts.extend(old_vals);
         out.push_str(&csv_row(&parts));
     }
 
     out
 }
 
 /// Format a single CSV row with RFC 4180 quoting.
 fn csv_row(values: &[String]) -> String {
     let escaped: Vec<String> = values.iter().map(|v| {
         if v.contains(',') || v.contains('"') || v.contains('\n') {
             format!("\"{}\"", v.replace('"', "\"\""))
         } else {
             v.clone()
         }
     }).collect();
     escaped.join(",") + "\n"
 }
 ```
 
 - [ ] **Step 2: Verify it compiles**
 
 Run: `cargo check --bin xldiff`
 Expected: success
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add src/bin/xldiff.rs
 git commit -m "feat(xldiff): implement CSV output formatter"
 ```
 
 ---
 
 ### Task 14: Test fixtures
 
 **Files:**
 - Modify: `tests/common/mod.rs`
 
 - [ ] **Step 1: Add diff test fixtures**
 
 Append to `tests/common/mod.rs`:
 
 ```rust
 /// Create a pair of files for positional diff testing.
 /// File A: Alice/90, Bob/80, Charlie/70
 /// File B: Alice/90, Charlie/70, Dana/85 (Bob removed, Dana added)
 pub fn create_diff_pair(path_a: &Path, path_b: &Path) {
     let mut wb = Workbook::new();
     let ws = wb.add_worksheet().set_name("Data").unwrap();
     ws.write_string(0, 0, "Name").unwrap();
     ws.write_string(0, 1, "Score").unwrap();
     ws.write_string(1, 0, "Alice").unwrap();
     ws.write_number(1, 1, 90.0).unwrap();
     ws.write_string(2, 0, "Bob").unwrap();
     ws.write_number(2, 1, 80.0).unwrap();
     ws.write_string(3, 0, "Charlie").unwrap();
     ws.write_number(3, 1, 70.0).unwrap();
     wb.save(path_a).unwrap();
 
     let mut wb = Workbook::new();
     let ws = wb.add_worksheet().set_name("Data").unwrap();
     ws.write_string(0, 0, "Name").unwrap();
     ws.write_string(0, 1, "Score").unwrap();
     ws.write_string(1, 0, "Alice").unwrap();
     ws.write_number(1, 1, 90.0).unwrap();
     ws.write_string(2, 0, "Charlie").unwrap();
     ws.write_number(2, 1, 70.0).unwrap();
     ws.write_string(3, 0, "Dana").unwrap();
     ws.write_number(3, 1, 85.0).unwrap();
     wb.save(path_b).unwrap();
 }
 
 /// Create a pair for key-based diff testing.
 /// File A: ID=1/Score=90, ID=2/Score=80, ID=3/Score=70
 /// File B: ID=1/Score=95, ID=2/Score=80, ID=4/Score=85
 /// Expected: ID=1 modified (90→95), ID=3 removed, ID=4 added
 pub fn create_diff_pair_with_keys(path_a: &Path, path_b: &Path) {
     let mut wb = Workbook::new();
     let ws = wb.add_worksheet().set_name("Data").unwrap();
     ws.write_string(0, 0, "ID").unwrap();
     ws.write_string(0, 1, "Name").unwrap();
     ws.write_string(0, 2, "Score").unwrap();
     ws.write_string(1, 0, "1").unwrap();
     ws.write_string(1, 1, "Alice").unwrap();
     ws.write_number(1, 2, 90.0).unwrap();
     ws.write_string(2, 0, "2").unwrap();
     ws.write_string(2, 1, "Bob").unwrap();
     ws.write_number(2, 2, 80.0).unwrap();
     ws.write_string(3, 0, "3").unwrap();
     ws.write_string(3, 1, "Charlie").unwrap();
     ws.write_number(3, 2, 70.0).unwrap();
     wb.save(path_a).unwrap();
 
     let mut wb = Workbook::new();
     let ws = wb.add_worksheet().set_name("Data").unwrap();
     ws.write_string(0, 0, "ID").unwrap();
     ws.write_string(0, 1, "Name").unwrap();
     ws.write_string(0, 2, "Score").unwrap();
     ws.write_string(1, 0, "1").unwrap();
     ws.write_string(1, 1, "Alice").unwrap();
     ws.write_number(1, 2, 95.0).unwrap();
     ws.write_string(2, 0, "2").unwrap();
     ws.write_string(2, 1, "Bob").unwrap();
     ws.write_number(2, 2, 80.0).unwrap();
     ws.write_string(3, 0, "4").unwrap();
     ws.write_string(3, 1, "Dana").unwrap();
     ws.write_number(3, 2, 85.0).unwrap();
     wb.save(path_b).unwrap();
 }
 
 /// Create a pair for tolerance testing.
 /// File A: ID=1/Price=100.001, ID=2/Price=200.5
 /// File B: ID=1/Price=100.002, ID=2/Price=200.6
 /// With tolerance 0.01: only ID=2 should be modified (diff=0.1 > 0.01)
 pub fn create_diff_pair_with_floats(path_a: &Path, path_b: &Path) {
     let mut wb = Workbook::new();
     let ws = wb.add_worksheet().set_name("Data").unwrap();
     ws.write_string(0, 0, "ID").unwrap();
     ws.write_string(0, 1, "Price").unwrap();
     ws.write_string(1, 0, "1").unwrap();
     ws.write_number(1, 1, 100.001).unwrap();
     ws.write_string(2, 0, "2").unwrap();
     ws.write_number(2, 1, 200.5).unwrap();
     wb.save(path_a).unwrap();
 
     let mut wb = Workbook::new();
     let ws = wb.add_worksheet().set_name("Data").unwrap();
     ws.write_string(0, 0, "ID").unwrap();
     ws.write_string(0, 1, "Price").unwrap();
     ws.write_string(1, 0, "1").unwrap();
     ws.write_number(1, 1, 100.002).unwrap();
     ws.write_string(2, 0, "2").unwrap();
     ws.write_number(2, 1, 200.6).unwrap();
     wb.save(path_b).unwrap();
 }
 ```
 
 - [ ] **Step 2: Verify compilation**
 
 Run: `cargo test --no-run`
 Expected: compiles successfully
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add tests/common/mod.rs
 git commit -m "test(xldiff): add diff test fixtures — positional, keyed, and float tolerance pairs"
 ```
 
 ---
 
 ### Task 15: Integration tests
 
 **Files:**
 - Create: `tests/test_xldiff.rs`
 
 - [ ] **Step 1: Write integration tests**
 
 Create `tests/test_xldiff.rs`:
 
 ```rust
 mod common;
 
 use assert_cmd::Command;
 use predicates::prelude::*;
 use tempfile::TempDir;
 
 #[test]
 fn test_no_diff() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     // Use same data for both
     common::create_simple(&path_a);
     common::create_simple(&path_b);
 
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--no-color")
         .assert()
         .success() // exit 0
         .stdout(predicate::str::contains("No differences found."));
 }
 
 #[test]
 fn test_positional_diff() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     common::create_diff_pair(&path_a, &path_b);
 
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--no-color")
         .assert()
         .code(1) // differences found
         .stdout(predicate::str::contains("Removed: 1"))
         .stdout(predicate::str::contains("Added: 1"))
         .stdout(predicate::str::contains("Bob"));
 }
 
 #[test]
 fn test_keyed_diff() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     common::create_diff_pair_with_keys(&path_a, &path_b);
 
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--key").arg("ID")
         .arg("--no-color")
         .assert()
         .code(1)
         .stdout(predicate::str::contains("Modified: 1"))
         .stdout(predicate::str::contains("Removed: 1"))
         .stdout(predicate::str::contains("Added: 1"));
 }
 
 #[test]
 fn test_tolerance() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     common::create_diff_pair_with_floats(&path_a, &path_b);
 
     // With tolerance=0.01, ID=1 diff (0.001) within tolerance, ID=2 diff (0.1) exceeds
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--key").arg("ID")
         .arg("--tolerance").arg("0.01")
         .arg("--no-color")
         .assert()
         .code(1)
         .stdout(predicate::str::contains("Modified: 1"));
 }
 
 #[test]
 fn test_json_format() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     common::create_diff_pair_with_keys(&path_a, &path_b);
 
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--key").arg("ID")
         .arg("--format").arg("json")
         .assert()
         .code(1)
         .stdout(predicate::str::contains("\"added\""))
         .stdout(predicate::str::contains("\"removed\""))
         .stdout(predicate::str::contains("\"modified\""));
 }
 
 #[test]
 fn test_markdown_format() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     common::create_diff_pair_with_keys(&path_a, &path_b);
 
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--key").arg("ID")
         .arg("--format").arg("markdown")
         .assert()
         .code(1)
         .stdout(predicate::str::contains("## Added"))
         .stdout(predicate::str::contains("## Removed"))
         .stdout(predicate::str::contains("## Modified"));
 }
 
 #[test]
 fn test_csv_format() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     common::create_diff_pair_with_keys(&path_a, &path_b);
 
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--key").arg("ID")
         .arg("--format").arg("csv")
         .assert()
         .code(1)
         .stdout(predicate::str::contains("_status"))
         .stdout(predicate::str::contains("added"))
         .stdout(predicate::str::contains("removed"))
         .stdout(predicate::str::contains("modified"));
 }
 
 #[test]
 fn test_file_not_found() {
     Command::cargo_bin("xldiff").unwrap()
         .arg("nonexistent.xlsx")
         .arg("also_nonexistent.xlsx")
         .assert()
         .code(2)
         .stderr(predicate::str::contains("file not found"));
 }
 
 #[test]
 fn test_sheet_selector() {
     let dir = TempDir::new().unwrap();
     let path = dir.path().join("multi.xlsx");
     common::create_multi_sheet(&path);
     let path_str = path.to_str().unwrap();
 
     // Compare Revenue vs Expenses sheets within same file
     Command::cargo_bin("xldiff").unwrap()
         .arg(format!("{}:Revenue", path_str))
         .arg(format!("{}:Expenses", path_str))
         .arg("--no-color")
         .assert()
         .code(1); // different data → exit 1
 }
 
 #[test]
 fn test_cols_filter() {
     let dir = TempDir::new().unwrap();
     let path_a = dir.path().join("a.xlsx");
     let path_b = dir.path().join("b.xlsx");
     common::create_diff_pair_with_keys(&path_a, &path_b);
 
     // Only compare Name column (ignore Score), so ID=1 shows no modification
     Command::cargo_bin("xldiff").unwrap()
         .arg(path_a.to_str().unwrap())
         .arg(path_b.to_str().unwrap())
         .arg("--key").arg("ID")
         .arg("--cols").arg("ID,Name")
         .arg("--no-color")
         .assert()
         .code(1)
         // ID=1 has same Name in both, so no modification for that row
         .stdout(predicate::str::contains("Modified: 0").or(predicate::str::contains("Modified").not()));
 }
 ```
 
 - [ ] **Step 2: Run integration tests**
 
 Run: `cargo test --test test_xldiff`
 Expected: all tests PASS
 
 - [ ] **Step 3: Commit**
 
 ```bash
 git add tests/test_xldiff.rs
 git commit -m "test(xldiff): add integration tests — all modes, formats, tolerance, errors"
 ```
 
 ---
 
 ### Task 16: Update CLAUDE.md and README
 
 **Files:**
 - Modify: `CLAUDE.md`
 
 - [ ] **Step 1: Update CLAUDE.md**
 
 Update the "Current tools" section to include xldiff, remove it from "Related tools" and "Planned":
 
 In CLAUDE.md, update:
 - Add `- **xldiff** — compare two sheets, report added/removed/modified rows` to "Current tools"
 - Remove or update the "Related tools" xldiff entry
 - Remove xlfilter from "Planned" if still there (it's already built)
 - Update the Architecture line to mention the diff module
 
 - [ ] **Step 2: Commit**
 
 ```bash
 git add CLAUDE.md
 git commit -m "docs: update CLAUDE.md — add xldiff to current tools, remove from planned"
 ```
 
 ---
 
 ### Task 17: Final verification
 
 - [ ] **Step 1: Run all tests**
 
 Run: `cargo test`
 Expected: all tests pass (existing + new)
 
 - [ ] **Step 2: Run clippy**
 
 Run: `cargo clippy --all-targets`
 Expected: no warnings
 
 - [ ] **Step 3: Build release binary**
 
 Run: `cargo build --release --bin xldiff`
 Expected: binary created at `target/release/xldiff`
 
 - [ ] **Step 4: Manual smoke test**
 
 Run: `cargo run --bin xldiff -- demo/budget.xlsx demo/sales.xlsx --no-color`
 Expected: shows differences between the two demo files
 
 - [ ] **Step 5: Commit any fixes**
 
 If clippy or tests revealed issues, fix and commit.