cov-loupe 3.0.0 → 4.0.0.pre

data/docs/dev/arch-decisions/application-architecture.md

@@ -0,0 +1,259 @@
+# Application Architecture
+
+[Back to main README](../../index.md)
+
+This document describes the core architectural decisions that shape how cov-loupe operates: its dual-mode design and context-aware error handling strategy.
+
+## Table of Contents
+
+- [Dual-Mode Operation (CLI and MCP Server)](#dual-mode-operation-cli-and-mcp-server)
+- [Context-Aware Error Handling](#context-aware-error-handling)
+
+---
+
+## Dual-Mode Operation (CLI and MCP Server)
+
+### Status
+
+Accepted
+
+### Context
+
+cov-loupe needed to serve two distinct use cases:
+
+1. **Human users** wanting a command-line tool to inspect coverage reports in their terminal
+2. **AI agents and MCP clients** needing programmatic access to coverage data via the Model Context Protocol (MCP) over JSON-RPC
+
+We considered three approaches:
+
+1. **Separate binaries/gems**: Create `simplecov-cli` and `cov-loupe` as separate projects
+2. **Single binary with explicit mode flags**: Require users to pass `--mode mcp` to run as MCP server
+3. **Automatic mode detection**: Single binary that automatically detects the operating mode based on input (TTY status, stdin)
+
+#### Key Constraints
+
+- MCP servers communicate via JSON-RPC over stdin/stdout, so any human-readable output would corrupt the protocol
+- CLI users expect immediate, readable output without ceremony
+- The gem should be simple to install and use for both audiences
+- Mode selection must be reliable and unambiguous
+
+### Decision (v4.0.0+)
+
+We implemented **explicit mode selection** via the `-m/--mode` flag. The default mode is `cli`, and MCP users must pass `-m mcp` or `--mode mcp` to run the server.
+
+#### Mode Selection Logic
+
+The mode is determined by parsing the `-m/--mode` flag from argv (including environment variables via `COV_LOUPE_OPTS`):
+
+- **Default**: CLI mode (when `-m/--mode` is not specified)
+- **MCP mode**: Must explicitly pass `-m mcp` or `--mode mcp`
+
+The implementation parses the configuration from the command-line arguments and routes to either `CoverageCLI` or `MCPServer` based on the mode setting.
+
+#### Why This Works
+
+- **MCP clients** are configured once with `-m mcp` or `--mode mcp` in their server config → always routes to MCP server
+- **CLI users** don't need to specify anything → defaults to CLI mode
+- **No ambiguity**: Mode is explicit and deterministic based on the `-m/--mode` flag
+
+#### Historical Note
+
+Prior to v4.0.0, cov-loupe used automatic mode detection based on TTY status and presence of subcommands. This was removed because:
+- Automatic detection caused issues with piped input (`cov-loupe --format json > output.json` would hang in MCP mode)
+- CI environments and non-TTY contexts were unpredictable
+- CLI-only flags without subcommands (`--format`, `--sort-order`) couldn't be reliably detected
+- Explicit mode selection is more predictable and follows standard practice for language servers
+
+### Consequences
+
+#### Positive
+
+1. **User convenience**: Single gem to install (`gem install cov-loupe`), single executable (`cov-loupe`)
+2. **Predictable behavior**: Mode is explicit and deterministic - no surprises based on environment
+3. **Simpler implementation**: No complex mode detection logic to maintain
+4. **Clear separation**: CLI and MCP server implementations remain completely separate after routing
+5. **Follows conventions**: Matches standard practice for language servers (e.g., `typescript-language-server --stdio`)
+
+#### Negative
+
+1. **Breaking change**: Users upgrading from v3.x must update MCP server configuration to include `-m mcp` or `--mode mcp`
+2. **Slight verbosity**: MCP users must include `-m mcp` or `--mode mcp` in their server config (but this is one-time setup)
+3. **Shared dependencies**: Some components (error handling, coverage model) must work correctly in both modes
+
+#### Trade-offs
+
+- **Versus automatic detection**: More explicit, but eliminates ambiguity and edge cases
+- **Versus separate gems**: Single installation is simpler, but requires mode flag for MCP
+
+#### Future Constraints
+
+- Shared components (like `CoverageModel`) must never output to stdout/stderr in ways that differ by mode
+- Default mode must remain `cli` for backward compatibility with existing CLI users
+
+### References
+
+- Implementation: `lib/cov_loupe.rb` (`CovLoupe.run`)
+- Configuration: `lib/cov_loupe/app_config.rb`
+- CLI implementation: `lib/cov_loupe/cli.rb`
+- MCP server implementation: `lib/cov_loupe/mcp_server.rb`
+- Related section: [Context-Aware Error Handling](#context-aware-error-handling)
+
+---
+
+## Context-Aware Error Handling
+
+### Status
+
+Accepted
+
+### Context
+
+cov-loupe operates in three distinct contexts, each with different error handling requirements:
+
+1. **CLI mode**: Human users expect friendly error messages, exit codes, and optional debug traces
+2. **MCP server mode**: AI agents/clients need structured error responses that don't crash the server
+3. **Library mode**: Embedding applications need exceptions they can catch and handle programmatically
+
+Initially, we considered uniform error handling across all modes, but this created poor user experiences:
+
+- CLI users saw raw exceptions with stack traces (scary and unhelpful)
+- MCP servers crashed on errors instead of returning error responses
+- Library users got friendly messages logged to stderr (unwanted side effects in their applications)
+
+#### Key Requirements
+
+- **CLI**: User-friendly messages, meaningful exit codes, optional stack traces for debugging
+- **MCP Server**: Logged errors (to file, not stdout), structured JSON-RPC error responses, no server crashes
+- **Library**: Raise custom exceptions with no logging, allowing consumers to handle errors as needed
+- **Consistency**: Same underlying error types, but different presentation strategies
+
+### Decision
+
+We implemented a **context-aware error handling strategy** using three components:
+
+#### 1. Custom Exception Hierarchy
+
+All errors inherit from `CovLoupe::Error` (lib/cov_loupe/errors.rb) with a `user_friendly_message` method:
+
+```ruby
+class Error < StandardError
+  def user_friendly_message
+    message  # Can be overridden in subclasses
+  end
+end
+
+class FileNotFoundError < FileError; end
+class CoverageDataError < Error; end
+class ResultsetNotFoundError < CoverageDataError; end
+# ... etc
+```
+
+This provides a unified interface for presenting errors to users while preserving exception types for programmatic handling.
+
+#### 2. ErrorHandler Class
+
+The `ErrorHandler` class (see `lib/cov_loupe/error_handler.rb`) provides configurable error handling behavior:
+
+```ruby
+class ErrorHandler
+  attr_accessor :error_mode, :logger
+
+  VALID_ERROR_MODES = [:off, :log, :debug].freeze
+
+  def initialize(error_mode: :log, logger: nil)
+    @error_mode = error_mode
+    @logger = logger
+  end
+
+  def handle_error(error, context: nil, reraise: true)
+    log_error(error, context)
+    if reraise
+      raise error.is_a?(CovLoupe::Error) ? error : convert_standard_error(error)
+    end
+  end
+end
+```
+
+The `convert_standard_error` method transforms Ruby's standard errors into user-friendly custom exceptions:
+
+- `Errno::ENOENT` → `FileNotFoundError`
+- `JSON::ParserError` → `CoverageDataError`
+- `Errno::EACCES` → `FilePermissionError`
+
+#### 3. ErrorHandlerFactory
+
+The `ErrorHandlerFactory` (defined in `lib/cov_loupe/error_handler_factory.rb`) creates mode-specific handlers:
+
+```ruby
+module ErrorHandlerFactory
+  def self.for_cli(error_mode: :log)
+    ErrorHandler.new(error_mode: error_mode)
+  end
+
+  def self.for_library(error_mode: :off)
+    ErrorHandler.new(error_mode: :off)  # No logging
+  end
+
+  def self.for_mcp_server(error_mode: :log)
+    ErrorHandler.new(error_mode: :log)   # Logs to file
+  end
+end
+```
+
+#### Error Flow by Mode
+
+**CLI Mode** (lib/cov_loupe/cli.rb):
+1. Catches all exceptions in the main run loop
+2. Uses `for_cli` handler to log errors if debug mode is enabled
+3. Displays `user_friendly_message` to the user
+4. Exits with appropriate code (1 for errors, 2 for usage errors)
+
+**MCP Server Mode** (`lib/cov_loupe/base_tool.rb`):
+1. Each tool wraps execution in a rescue block
+2. Uses `for_mcp_server` handler to log errors to `~/cov_loupe.log`
+3. Returns structured JSON-RPC error response
+4. Server continues running (no crashes)
+
+**Library Mode** (`lib/cov_loupe.rb`):
+1. Uses `for_library` handler with `error_mode: :off` (no logging)
+2. Raises custom exceptions directly
+3. Consumers catch and handle `CovLoupe::Error` subclasses
+
+### Consequences
+
+#### Positive
+
+1. **Excellent UX**: Each context gets appropriate error handling behavior
+2. **Robustness**: MCP server never crashes on tool errors
+3. **Debuggability**: CLI users can enable stack traces with error modes, MCP errors are logged
+4. **Clean library API**: No unwanted side effects (logging, stderr output) when used as a library
+5. **Type safety**: Custom exceptions allow programmatic error handling by type
+
+#### Negative
+
+1. **Complexity**: Three error handling paths to maintain and test
+2. **Coordination required**: All error types must implement `user_friendly_message` consistently
+3. **Error conversion overhead**: Standard errors must be converted to custom exceptions
+
+#### Trade-offs
+
+- **Versus uniform error handling**: More code complexity, but dramatically better UX in each context
+- **Versus separate error classes per mode**: Single error hierarchy is simpler, factory pattern adds mode-specific behavior
+
+#### Implementation Notes
+
+The `ErrorHandler.convert_standard_error` method uses pattern matching on exception types and error messages to provide helpful, context-aware error messages. This includes:
+
+- Extracting filenames from system error messages
+- Detecting SimpleCov-specific error patterns
+- Providing actionable suggestions ("please run your tests first")
+
+### References
+
+- Custom exceptions: `lib/cov_loupe/errors.rb`
+- ErrorHandler implementation: `lib/cov_loupe/error_handler.rb`
+- ErrorHandlerFactory: `lib/cov_loupe/error_handler_factory.rb`
+- CLI error handling: `lib/cov_loupe/cli.rb` (rescue block in `CoverageCLI#run`)
+- MCP tool error handling: `lib/cov_loupe/base_tool.rb` (`BaseTool#call`)
+- Library mode: `lib/cov_loupe.rb` (error handling within `CovLoupe.run`)
+- Related section: [Dual-Mode Operation](#dual-mode-operation-cli-and-mcp-server)

data/docs/dev/arch-decisions/coverage-data-quality.md

@@ -0,0 +1,193 @@
+# Coverage Data Quality
+
+[Back to main README](../../index.md)
+
+This document describes how cov-loupe ensures the accuracy and reliability of coverage data through staleness detection.
+
+## Coverage Staleness Detection
+
+### Status
+
+Accepted
+
+### Context
+
+Coverage data can become outdated when source files are modified after tests run. This creates misleading results:
+
+- Coverage percentages appear lower/higher than reality
+- Line numbers in coverage reports don't match the current source
+- AI agents and users may make decisions based on stale data
+
+We needed a staleness detection system that could:
+
+1. Detect when source files have been modified since coverage was collected
+2. Detect when source files have different line counts than coverage data
+3. Handle edge cases (deleted files)
+4. Support both file-level and project-level checks
+5. Allow users to control whether staleness is reported or causes errors
+
+#### Alternative Approaches Considered
+
+1. **No staleness checking**: Simple, but leads to confusing/incorrect reports
+2. **Single timestamp check**: Fast, but misses line count mismatches (files edited and reverted)
+3. **Content hashing**: Accurate, but expensive for large projects
+4. **Multi-type detection with modes**: More complex, but provides accurate detection with user control
+
+### Decision
+
+We implemented a **staleness detection system** with configurable error modes that can identify four distinct staleness conditions.
+
+#### Four Staleness Types
+
+The `StalenessChecker` class (defined in `lib/cov_loupe/staleness/staleness_checker.rb`) detects four distinct types of staleness:
+
+1. **Type "error" (Error)**: The staleness check itself failed
+   - Returned by `CoverageModel#staleness_for` when an exception is raised during staleness checking
+   - Example: File permission errors, resolver failures, or other unexpected issues
+   - The error is logged but execution continues with an "error" status instead of crashing
+
+2. **Type "missing" (Missing)**: The source file exists in coverage but is now deleted/missing
+   - Returned by `file_staleness_status` when `File.file?(file_abs)` returns false
+   - Example: File was deleted after tests ran
+
+3. **Type "newer" (Timestamp)**: The source file's mtime is newer than coverage timestamp
+   - Detected by comparing `File.mtime(file_abs)` with coverage timestamp
+   - Example: File was edited after tests ran
+
+4. **Type "length_mismatch" (Length)**: The source file line count doesn't match the coverage lines array length
+   - Detected by comparing `File.foreach(path).count` with `coverage_lines.length`
+   - Example: Lines were added/removed without changing mtime (rare but possible with version control)
+
+5. **Type "ok" (Not stale)**: The file is not stale
+   - Returned when none of the above staleness conditions apply
+   - Indicates the coverage data is current and accurate
+
+#### Implementation Details
+
+The core algorithm lives in `CovLoupe::StalenessChecker#compute_file_staleness_details`:
+
+```ruby
+def compute_file_staleness_details(file_abs, coverage_lines)
+  coverage_ts = coverage_timestamp
+  exists = File.file?(file_abs)
+  file_mtime = exists ? File.mtime(file_abs) : nil
+
+  cov_len = coverage_lines.respond_to?(:length) ? coverage_lines.length : 0
+  src_len = exists ? safe_count_lines(file_abs) : 0
+
+  # If coverage timestamp is 0 (missing/invalid), we cannot determine if file is newer
+  newer = if coverage_ts.to_i > 0
+            !!(file_mtime && file_mtime.to_i > coverage_ts.to_i)
+          else
+            false
+          end
+
+  len_mismatch = (cov_len.positive? && src_len != cov_len)
+  newer &&= !len_mismatch  # Prioritize length mismatch over timestamp
+
+  {
+    exists: exists,
+    file_mtime: file_mtime,
+    coverage_timestamp: coverage_ts,
+    cov_len: cov_len,
+    src_len: src_len,
+    newer: newer,
+    len_mismatch: len_mismatch
+  }
+end
+```
+
+#### Staleness Modes
+
+The checker supports two modes, configured when instantiating `StalenessChecker`:
+
+- **`:off`** (default): Staleness is detected but only reported in responses, never raises errors
+- **"error"**: Staleness raises `CoverageDataStaleError` or `CoverageDataProjectStaleError`
+
+This allows:
+- Interactive tools to show warnings without crashing
+- CI systems to fail builds on stale coverage
+- AI agents to decide how to handle staleness based on their goals
+
+#### File-Level vs Project-Level Checks
+
+**File-level** (`check_file!` and `file_staleness_status`):
+- Checks a single file's staleness
+- Returns one of the staleness status strings ("ok", "missing", "newer", "length_mismatch", "error")
+- Used by single-file tools (summary, detailed, uncovered)
+
+**Project-level** (`check_project!`):
+- Checks all covered files plus optionally tracked files
+- Detects:
+  - Files newer than coverage timestamp
+  - Files deleted since coverage was collected
+  - Tracked files missing from coverage (newly added files)
+- Raises `CoverageDataProjectStaleError` with lists of problematic files
+- Used by `list_tool` and `coverage_table_tool`
+
+**Totals behavior**:
+- `project_totals` excludes any stale files ("missing", "newer", "length_mismatch", "error") from aggregate counts.
+- Totals include explicit `with_coverage`/`without_coverage` breakdowns so callers can reconcile what was omitted.
+- The `without_coverage` payload includes counts for three categories:
+  - `missing_from_coverage`: Tracked files that have no coverage data in the resultset
+  - `unreadable`: Files that exist but could not be read (e.g., due to permission errors, I/O issues, or staleness check failures)
+  - `skipped`: Files that were skipped during list processing due to coverage data errors (e.g., malformed entries)
+- The `unreadable` count is populated from `list_result['unreadable_files']`, which is collected during staleness checking when files exist but cannot be accessed or validated.
+
+#### Tracked Globs Feature
+
+The project-level check supports `tracked_globs` parameter to detect newly added files:
+
+```ruby
+# Detects if lib/**/*.rb files exist that have no coverage data
+checker.check_project!(coverage_map)  # with tracked_globs: ['lib/**/*.rb']
+```
+
+This helps teams ensure new files are included in test runs.
+
+#### Resultset Path Consistency (SimpleCov)
+
+SimpleCov can emit mixed path forms for the same file when resultsets are merged across suites or
+environments (for example, absolute vs relative paths, or different roots). This is a SimpleCov
+data consistency risk, not a cov-loupe behavior. Downstream tools that normalize paths may treat
+one entry as overriding another when multiple keys map to the same absolute path.
+
+**Guidance:** Keep `SimpleCov.root` consistent across all suites and avoid manual path rewriting
+before merging resultsets.
+
+### Consequences
+
+#### Positive
+
+1. **Accurate detection**: Three types catch different staleness scenarios comprehensively
+2. **User control**: Modes allow errors or warnings based on use case
+3. **Detailed information**: Staleness errors include specific file lists and timestamps
+4. **Project awareness**: Can detect newly added files that lack coverage
+5. **Conservative totals**: Aggregate totals only include fresh coverage data
+
+#### Negative
+
+1. **Complexity**: Three staleness types are harder to understand than a single timestamp check
+2. **Performance**: Line counting and mtime checks for every file add overhead
+3. **Ambiguity**: When multiple staleness types apply, prioritization logic (length > timestamp) may surprise users
+
+#### Trade-offs
+
+- **Versus timestamp-only**: More accurate but slower and more complex
+- **Versus content hashing**: Fast enough for most projects, but can't detect "edit then revert" scenarios
+- **Versus no checking**: Essential for reliable coverage reporting, worth the complexity
+
+#### Edge Cases Handled
+
+1. **Deleted files**: Appear as "missing" type staleness
+2. **Empty files**: `cov_len.positive?` guard prevents false positives
+3. **No coverage timestamp**: Defaults to 0, effectively disabling timestamp checks
+
+### References
+
+- Implementation: `lib/cov_loupe/staleness_checker.rb` (`StalenessChecker` class)
+- File-level checking: `StalenessChecker#check_file!` and `#file_staleness_status`
+- Project-level checking: `StalenessChecker#check_project!`
+- Staleness detail computation: `StalenessChecker#compute_file_staleness_details`
+- Error types: `lib/cov_loupe/errors.rb` (`CoverageDataStaleError`, `CoverageDataProjectStaleError`)
+- Usage in tools: `lib/cov_loupe/tools/list_tool.rb`, `lib/cov_loupe/model.rb`

data/docs/dev/arch-decisions/output-character-mode.md

@@ -0,0 +1,217 @@
+# Output Character Mode
+
+[Back to main README](../../index.md)
+
+This document describes the architectural decision for implementing a global output character mode that controls ASCII vs Unicode output across CLI and MCP interfaces.
+
+## Status
+
+Accepted
+
+## Context
+
+cov-loupe outputs data in multiple formats across two interfaces:
+
+1. **CLI mode**: Human users read terminal output including tables, error messages, and formatted coverage reports
+2. **MCP server mode**: AI agents receive JSON responses containing coverage data and metadata
+
+### The Problem
+
+Modern projects often contain file paths with Unicode characters (e.g., accented characters, non-Latin scripts). The original implementation used Unicode characters throughout:
+
+- Table borders using box-drawing characters (│ ─ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼)
+- Source code markers (✓ for covered, · for uncovered)
+- Error messages with file paths preserved as-is
+
+This caused issues in environments that don't support Unicode:
+
+- Windows terminals with legacy encoding
+- CI/CD systems with ASCII-only terminals
+- Piped output to files or tools expecting ASCII
+- Legacy systems without UTF-8 support
+
+Users experienced garbled output, corrupted tables, and unreadable error messages.
+
+### Requirements
+
+- **ASCII mode**: Must produce ASCII-only output (0-127 characters) when requested
+- **Fancy mode**: Should use Unicode characters for enhanced readability when supported
+- **Auto-detection**: Default mode should intelligently choose based on environment
+- **MCP integration**: MCP tools must support the same output modes as CLI
+- **Comprehensive coverage**: All output channels must respect the mode setting
+- **Backward compatibility**: Existing behavior (Unicode) should remain the default when supported
+
+### Considered Approaches
+
+1. **Separate ASCII formatters**: Create duplicate formatter implementations for ASCII output
+   - Too much code duplication
+   - Maintenance burden (two implementations of each formatter)
+
+2. **Post-process all output**: Apply ASCII conversion after formatting
+   - Inefficient (convert entire formatted output)
+   - Could corrupt already-encoded data (JSON structure)
+
+3. **Centralized conversion with charsets**: Define separate charsets and convert at formatting time
+   - Clean separation of concerns
+   - Efficient (convert only what's displayed)
+   - Consistent across all formatters
+
+## Decision
+
+We implemented **global output character mode** with centralized conversion using charset definitions.
+
+### Mode Options
+
+Three modes are available:
+- `default`: Auto-detects terminal UTF-8 support at runtime → fancy if supported, otherwise ASCII
+- `fancy`: Forces Unicode output with box-drawing characters and fancy markers
+- `ascii`: Forces ASCII-only output with transliteration fallback to `?` for unknown characters
+
+### Configuration
+
+- **CLI**: `-O/--output-chars MODE` flag (case-insensitive, short forms `d|f|a`)
+- **MCP**: Optional `output_chars` parameter in tool requests (overrides server default)
+- **No environment variable**: Intentionally omitted to keep configuration simple and explicit
+
+### Core Implementation
+
+The `OutputChars` module (`lib/cov_loupe/output_chars.rb`) provides:
+
+```ruby
+module OutputChars
+  # Mode resolution
+  def self.resolve_mode(mode)
+    return :fancy if mode == :fancy
+    return :ascii if mode == :ascii
+    # default: detect terminal UTF-8 support
+    stdout_utf8? ? :fancy : :ascii
+  end
+
+  # Character conversion using transliteration map
+  def self.convert(text, mode)
+    return text unless mode == :ascii
+    text.chars.map { |c| TRANSLITERATIONS[c] || c.ascii_only? ? c : '?' }.join
+  end
+
+  # Charset selection
+  def self.charset_for(mode)
+    mode == :fancy ? FANCY_CHARSET : ASCII_CHARSET
+  end
+end
+```
+
+### Transliteration Strategy
+
+Instead of a generic library (like `ActiveSupport::Multibyte`), we use an internal `TRANSLITERATIONS` hash mapping common characters to ASCII equivalents:
+
+- Accented Latin characters (á → a, é → e, ñ → n, etc.)
+- Symbols and punctuation (→ ->, — --, © (C), etc.)
+- Box-drawing characters (│ → |, ─ → -, ┌ → +, etc.)
+
+Characters without defined mappings fall back to `?` to maintain ASCII-only output.
+
+### Formatter Integration
+
+All formatters respect the `output_chars` parameter:
+
+1. **JSON**: Uses `JSON.generate(..., ascii_only: true)` in ASCII mode
+2. **YAML**: Post-processes through `OutputChars.convert`
+3. **AmazingPrint**: Post-processes through `OutputChars.convert`
+4. **Tables**: Uses appropriate charset (`OutputChars.charset_for`) and converts cell contents
+5. **Source**: Uses ASCII-safe markers (`+`/`-` instead of `✓`/`·`) and converts source code
+
+### Error Message Integration
+
+- CLI error handlers convert messages via `OutputChars.convert`
+- Staleness error messages convert file paths via `convert_path` lambda
+- Option parser errors converted before display
+- Backtrace lines converted in debug mode
+
+### Scope of Conversion
+
+**Converted in ASCII mode:**
+- All CLI error messages and option parser errors
+- Staleness error messages and file paths
+- Command literal strings (via `convert_text` helper in BaseCommand)
+- MCP tool JSON responses (via `respond_json` with `ascii_only: true`)
+- All formatted output (tables, source, JSON, YAML)
+
+**Not converted in ASCII mode:**
+- **Log files**: Preserved in original encoding for debugging fidelity. Log files are system/debugging artifacts, not user-facing output. Converting would lose exact file paths and error details needed for troubleshooting, create inconsistency between logged paths and actual filesystem paths, and provides no user value since logs are developer artifacts.
+- **Gem post-install message**: Intentionally left unchanged per requirements
+
+## Consequences
+
+### Positive
+
+1. **Broad compatibility**: Works in any terminal environment, including legacy systems
+2. **Better UX**: Fancy mode provides enhanced readability when Unicode is supported
+3. **Auto-detection**: Default mode adapts to environment without user configuration
+4. **Comprehensive coverage**: All output channels respect the mode setting
+5. **MCP parity**: CLI and MCP interfaces have identical behavior
+6. **No dependencies**: Internal transliteration map avoids external dependencies
+7. **Consistent behavior**: Single source of truth for character conversion
+
+### Negative
+
+1. **Complexity**: Additional configuration option and conversion logic to maintain
+2. **Transliteration coverage**: Not all Unicode characters have mappings (falls back to `?`)
+3. **Performance**: Conversion overhead for every output operation (minimal in practice)
+4. **Test burden**: Comprehensive tests needed across all formatters and modes
+
+### Trade-offs
+
+- **Internal vs external transliteration**: Internal map is less comprehensive but avoids dependencies and keeps behavior predictable
+- **Charset vs post-processing**: Charsets are cleaner but require formatter awareness; post-processing is simpler but can corrupt structured data
+- **Auto-detection vs explicit default**: Auto-detection is more convenient but less predictable; explicit default is clearer but requires configuration
+
+### Future Constraints
+
+- Any new formatters must respect `output_chars` parameter
+- New output channels (e.g., HTML) need ASCII mode support
+- Transliteration map must be maintained as new characters are encountered
+- Log files must never be converted (documented design decision)
+
+## Implementation Notes
+
+### Mode Precedence
+
+1. Explicit mode parameter (CLI flag or MCP tool parameter)
+2. Server default (for MCP)
+3. Built-in default (auto-detect UTF-8 support)
+
+### Performance Considerations
+
+- Conversion only applies in ASCII mode (fancy mode is a no-op)
+- Transliteration map lookup is O(1) per character
+- JSON `ascii_only: true` is optimized by the json gem
+- Overall performance impact is negligible (< 1ms for typical outputs)
+
+### Testing Strategy
+
+Comprehensive test coverage ensures correctness:
+
+- Mode resolution and normalization tests
+- Formatter tests for both ASCII and fancy modes
+- CLI option parsing tests for `--output-chars` flag
+- MCP tool output mode tests
+- Staleness error message tests with Unicode file paths
+- Integration tests across all subcommands with Unicode file names
+
+## References
+
+- Core implementation: `lib/cov_loupe/output_chars.rb`
+- Configuration: `lib/cov_loupe/config/app_config.rb`, `lib/cov_loupe/config/option_normalizers.rb`
+- Formatters:
+  - `lib/cov_loupe/formatters/formatters.rb` (JSON, YAML, AmazingPrint)
+  - `lib/cov_loupe/formatters/table_formatter.rb` (tables)
+  - `lib/cov_loupe/formatters/source_formatter.rb` (source code)
+- Error handling: `lib/cov_loupe/cli.rb`, `lib/cov_loupe/errors/error_handler.rb`
+- MCP integration: `lib/cov_loupe/base_tool.rb`, `lib/cov_loupe/tools/*.rb`
+- CLI option parsing: `lib/cov_loupe/config/option_parser_builder.rb`
+- Tests:
+  - `spec/cov_loupe/output_chars_spec.rb`
+  - `spec/cov_loupe/formatters/*_spec.rb`
+  - `spec/cov_loupe/cli/cli_output_chars_spec.rb`
+  - `spec/cov_loupe/tools/*_spec.rb`
+- Review document: `docs/dev/output-chars-review.md`