minting 1.3.0 → 1.5.0

data/doc/agents/recommendations.md

@@ -0,0 +1,335 @@
+# `minting` — Recommendations Roadmap
+
+Living document of improvement recommendations for the `minting` gem,
+produced from a full read of `AGENTS.md`, `README.md`, `CHANGELOG.md`,
+and the entire `lib/` + `test/` tree (v1.3.0 baseline).
+
+**Conventions**
+
+- P0 / P1 / P2 / P3 = priority. P0 = small, high-value, ship now.
+- ✅ = done (committed on `master` or an in-flight branch).
+- 🟡 = partially done.
+- Each item is sized to be a single PR unless marked *[epic]*.
+- File references are relative to repo root.
+
+---
+
+## TL;DR
+
+The gem is in **excellent shape**: ~1,400 LoC, 100% line coverage,
+RuboCop + Reek clean, performance bench suite, immutable `Rational`
+internals, 117 built-in currencies. The recommendations below are
+**polish, hardening, and roadmap** — not "fix the broken thing".
+
+Two of the highest-leverage moves are already in flight:
+
+- ✅ **README-as-spec** — `test_readme_usage` now asserts the
+  README's `to_s` / `to_json` / `to_hash` / `split` / `allocate`
+  examples instead of just exercising them silently.
+- ✅ **`Money.from_fractional`** — symmetric inverse of `#fractional`
+  with full test + README + CHANGELOG coverage.
+
+The remaining work is mostly documentation discipline, API ergonomics,
+and the two roadmap items already advertised in the README (I18n +
+exchange rates).
+
+---
+
+## 🔴 P0 — Quick wins, ship now
+
+### P0-1 ✅ Tighten README-as-spec
+
+**Status:** Merged in commit `20359dc`.
+
+- Turned 14 commented `#=>` examples in `test/minting_test.rb` into
+  real `assert_equal` calls.
+- Fixed typo: `conversiob` → `conversion`.
+- Corrected the README's `to_json` example to match the actual output
+  (the real string has spaces around the `:`).
+- Softened the "2× faster" headline to point at the Performance
+  section where the measured ratios live.
+- Added a one-line `rubocop:disable` on `test_readme_usage` (the spec
+  has to stay monolithic to serve as a spec).
+
+**Why it mattered:** the test was passing while the README silently
+drifted. Now any example change in the README either stays correct or
+fails CI.
+
+### P0-2 🟡 Auto-require `bigdecimal` and clean up `to_d`
+
+**Status:** Partial — the dependency was added in commit `33b2c01`
+(`s.add_dependency 'bigdecimal', '>= 4.0'` in `minting.gemspec`).
+The runtime guard in `lib/minting/money/conversion.rb` (lines 10–14)
+is now redundant:
+
+```ruby
+def to_d
+  raise NoMethodError, 'decimal gem required' unless defined?(BigDecimal)
+  amount.to_d 0
+end
+```
+
+**Follow-up:** delete the `raise NoMethodError` line. It's dead code
+once `bigdecimal` is a hard dependency. One-line PR.
+
+### P0-3 ✅ Fix CHANGELOG typos
+
+**Status:** Done in commit `20359dc` — "is no private" →
+"is now private" in the v1.3.0 entry. Watch for new typos as
+items are added under `[Unreleased]`.
+
+### P0-4 Add a CI gate on the marketing claims
+
+The README's "**2× faster**" / "**10×+ for formatting**" headline and
+the table at the bottom (lines 213–247) are generated from a single
+Qwen run on 2026-05-30 and aren't reproducible from CI.
+
+**Concrete action:** in CI, run
+
+```sh
+BENCH=true rake bench:regression
+```
+
+and fail the build if any benchmark regresses by more than (e.g.)
+20% vs the stored baseline in `pkg/bench_baseline.json`. The baseline
+file is optional but easy to maintain.
+
+This makes the table *defensible* rather than aspirational.
+
+---
+
+## 🟠 P1 — Correctness, clarity, small ergonomics
+
+### P1-1 🟡 `Money.from_fractional(integer, currency)`
+
+**Status:** Merged on branch `feature/money-from-fractional` (commit
+`150a2d0`).
+
+- Inverse of `#fractional`. Uses `Rational(n, fractional_multiplier)`
+  so subunit-0 currencies work without a special case.
+- Integer-only contract — rejects `Float` / `String` / `Rational` with
+  `ArgumentError` to preserve the exactness guarantee.
+- Accepts `String`, `Symbol`, or `Currency` for the currency arg,
+  matching `Mint.money` / `Money.create`.
+- 4 new tests + 3 new README-spec asserts; 100% coverage maintained.
+
+**To do** Add benchmark tests
+
+### P1-2 Add `Money#clamp(min, max)`, `Money#min(other)`, `Money#max(other)`
+
+`Comparable` is already mixed in (`lib/minting/money/comparable.rb`),
+so `min` and `max` work *implicitly* through the `<=>` machinery —
+but only when both operands are the same currency. A first-class
+`#clamp` would be a one-liner and very useful in domain code
+(pricing floors/ceilings, exchange-rate bands, etc.).
+
+```ruby
+# Sketch
+def clamp(min, max)
+  raise ArgumentError, 'min/max must share currency' unless
+    same_currency?(min) && same_currency?(max)
+  return min if self < min
+  return max if self > max
+  self
+end
+```
+
+Add tests for: in-range, below-min, above-max, equal-to-bound,
+non-matching-currency error.
+
+### P1-3 Improve `to_s` format-hash handling
+
+`lib/minting/money/formatting.rb` accepts `format:` as either a
+`String` or a `Hash` with `:positive` / `:negative` / `:zero` keys.
+The current code:
+
+- Falls through to `'%<symbol>s%<amount>f'` if `:positive` is missing
+  and the input is non-zero non-negative (line 58).
+- Has no test coverage for the hash form at all.
+
+**Action:** add explicit tests for:
+
+- `{ positive: '...', negative: '...', zero: '...' }`
+- `{ positive: '...' }` alone (default for neg/zero)
+- Mixing hash and `decimal:` / `thousand:` kwargs
+
+### P1-4 Document and harden registry thread-safety
+
+`lib/minting/mint/registry.rb` memoizes `@currencies`,
+`@currency_symbols`, and `@zero` with `||=`. In a multi-threaded
+server (Rails, Sidekiq, Puma) the first call to `Mint.money` from
+two threads can:
+
+- Both call `YAML.load_file` and `register` the same currencies.
+- Both call `@currency_symbols ||= ...` and produce a non-frozen copy
+  that diverges.
+
+**Action:** either
+
+1. Wrap the lazy initializers in `Mutex#synchronize` (3 places), or
+2. Switch to `Concurrent::Map` (no new dep), or
+3. Eager-load in a Railtie/loaded hook and treat the registry as
+   read-only after boot.
+
+Option 3 is the most pragmatic. Document the contract.
+
+### P1-5 Make `Mint.currencies` immutable
+
+`currencies` returns the live `@currencies` hash. A caller can
+`currencies.delete('USD')` and break invariants. Either:
+
+- Return a frozen copy (`@currencies.dup.freeze`), or
+- Document loudly that the returned hash must be treated read-only.
+
+### P1-6 Improve `coercion.rb` — add `**` and a clean `==`
+
+`lib/minting/money/coercion.rb` defines `CoercedNumber` (used by
+`Money#coerce`) with `+`, `-`, `*`, `/`, `<=>`, but no `**` or `==`.
+
+```ruby
+2 ** 0.dollars   #=> 1  (works)
+2 ** 5.dollars   #=> NoMethodError  (silent failure)
+```
+
+`==` falls through to `Comparable`, which raises `ArgumentError`, but
+a custom `==` on `CoercedNumber` would give a more specific error
+message.
+
+**Action:** add `**` and `==` to `CoercedNumber`. Tests in
+`test/money/money_coercion_test.rb` (or wherever they live).
+
+### P1-7 Add `inspect` round-trip test
+
+`Money#inspect` is implemented in `lib/minting/money/money.rb:79`
+as `"[#{currency_code} %0.#{currency.subunit}f]"` — e.g.
+`[USD 9.99]`. The existing parser (`lib/minting/money/parse.rb`)
+can almost read this back, but a clean round-trip would be a nice
+property test:
+
+```ruby
+m = Mint.money(9.99, 'USD')
+assert_equal m, Mint::Money.parse(m.inspect.delete_prefix('[').delete_suffix(']'))
+```
+
+Make it a one-liner or a property-based test with 10–20 random
+amounts. Cheap, catches regressions in either direction.
+
+---
+
+## 🟡 P2 — Roadmap items already advertised in README
+
+### P2-1 I18n / locale-aware formatting *[epic]*
+
+Foundation is already there: `to_s(decimal: ',', thousand: '.')`
+works. What's missing is locale-keyed defaults:
+
+```ruby
+Mint.money(9.99, 'USD').to_s(locale: :'pt-BR') #=> "US$ 9,99"
+Mint.money(9.99, 'USD').to_s(locale: :'fr')    #=> "9,99 $US"
+```
+
+**Action plan (multi-PR):**
+
+1. Add `Mint::Locale` value object + a small `locales.yaml` (or
+   build off `currencies.yaml` since most formatting info is per-
+   currency already).
+2. Add `I18n` integration behind a `require 'minting/i18n'` opt-in.
+3. Default to "no locale" so existing code is unaffected.
+
+### P2-2 Exchange rates *[epic]*
+
+Mentioned in the README Roadmap. The hard part isn't the math, it's
+the rate source. Suggested shape:
+
+```ruby
+Mint.bank = Mint::Bank::MemoryStore.new(
+  'USD' => { 'EUR' => 0.92, 'JPY' => 149.50 }
+)
+Mint.money(10, 'USD').exchange('EUR') #=> [EUR 9.20]
+```
+
+Multi-PR epic:
+
+1. `Mint::Bank` interface with `#exchange(money, target)`.
+2. `Mint::Bank::MemoryStore` (in-memory, good for tests).
+3. `Mint::Bank::ECB` or `Mint::Bank::OpenExchangeRates` (network).
+4. Update `minting-rails` to expose bank config in the Railtie.
+
+### P2-3 Reek / RuboCop tightening
+
+`.rubocop_todo.yml` still has 9 pre-existing offenses, all in
+`test/performance/*` and `test/mint_benchmark.rb`. They're
+"`Metrics::BlockLength`" / "`Metrics::MethodLength`" — fixable by
+extracting helper methods or by scoping the cop to non-bench code.
+
+---
+
+## 🟢 P3 — Polish
+
+### P3-1 ✅ Move AI-generated docs to `doc/agents/`
+
+Done in commit `ff08578`. Consider also moving `pkg/` artifacts to
+a release script that builds on tag rather than committing pre-built
+gems.
+
+### P3-2 `Gemfile.lock` policy
+
+`Gemfile.lock` is currently committed. The project is a *gem*, not
+an app, so the conventional choice is to *not* commit it (let
+consumers' Bundler resolve). Or, if you prefer reproducibility for
+CI, commit it and document the choice in `CONTRIBUTING.md`.
+
+### P3-3 Add `SECURITY.md` and `CODE_OF_CONDUCT.md`
+
+Standard hygiene for a public Ruby gem. One PR each, copy-paste
+from the GitHub templates.
+
+### P3-4 Document `Money#each_currency` / `Mint.currencies.each_value`
+
+The README's "Features" list doesn't mention that you can iterate
+registered currencies. Trivial doc addition; potential ergonomic
+win for tooling authors.
+
+### P3-5 Decide on `pkg/` retention
+
+`pkg/minting-*.gem` is in `.gitignore`, but old builds may still
+sit there. Run `rake clobber_pkg` (if it exists) or just `rm -rf
+pkg/*` once. Then add a `git clean -nd pkg` check to `Rakefile` if
+you want belt-and-braces.
+
+---
+
+## Suggested next PR (after `from_fractional` merges)
+
+**Title:** *Delete dead `to_d` guard, document `bigdecimal` as a hard dependency*
+
+**Scope:**
+
+- `lib/minting/money/conversion.rb`: remove
+  `raise NoMethodError, 'decimal gem required' unless defined?(BigDecimal)`.
+- `CHANGELOG.md`: add a one-liner under `[Unreleased]` → `### Other`.
+- `test/money/money_conversion_test.rb`: add a sanity test that
+  `to_d` returns a `BigDecimal` (already covered indirectly, but
+  make it explicit).
+
+One-line source change, one-line test, one-line changelog. ~10 min.
+
+---
+
+## Metrics to watch going forward
+
+| Metric | Current | Target |
+|---|---|---|
+| Line coverage | 100% (284/284) | ≥ 100% — don't regress |
+| Test count | 80 runs, 342 assertions | Grow with each new method |
+| `to_s` Hash format coverage | 0 tests | ≥ 6 (P1-3) |
+| Bench variance vs baseline | unmeasured | ≤ 20% (P0-4) |
+| Public API methods with YARD | ~all | 100% (already achieved) |
+| Open `rubocop_todo` offenses | 9 in `test/performance/*` | 0 (P2-3) |
+| `Gemfile.lock` policy | committed | documented (P3-2) |
+| `to_d` runtime guard | present but dead | removed (suggested next PR) |
+
+---
+
+*Last updated alongside PR #2 (`Money.from_fractional`). Refresh
+after each release.*

data/doc/agents/rubocop-issues.md

@@ -0,0 +1,332 @@
+# Rubocop Issues Assessment: Minting Gem
+
+**Date:** 2026-06-03  
+**Total Issues Found:** 93 (88 conventions, 5 warnings)  
+**Files Analyzed:** 37  
+**Files with Issues:** 23
+
+---
+
+## Executive Summary
+
+The minting gem's rubocop analysis reveals **93 total violations**, primarily concentrated in test code rather than production code. The violations fall into two broad categories:
+
+1. **Production Code Issues (9 violations):** Focused on architectural patterns, complexity, and parameter design
+2. **Test Code Issues (84 violations):** Mostly style/complexity issues in test assertions
+
+The good news: **Most issues are low-risk conventions** affecting code style and test organization, not correctness or performance. The critical items requiring attention are marked with ⚠️.
+
+---
+
+## Issues by Category
+
+### 🚨 Critical Issues (Must Address)
+
+#### 1. **Lint/ItWithoutArgumentsInBlock** (Warning)
+- **Severity:** Warning (Ruby 3.4 compatibility)
+- **Location:** `lib/minting/money/allocation.rb:56`
+- **Issue:** `it` calls without arguments will have different semantics in Ruby 3.4
+- **Action:** Use `it()` or `self.it` explicitly
+- **Status:** Actionable, simple fix
+
+#### 2. **Lint/EmptyWhen** (Warnings) - 4 occurrences
+- **Severity:** Warning
+- **Locations:** `lib/minting/money/money.rb` (lines 136, 137, 147, 148)
+- **Issue:** Empty `when` branches in case statement (likely fall-through logic)
+- **Action:** Either add `# rubocop:disable` comment if intentional, or refactor the case logic
+- **Status:** Needs clarification on intent
+
+---
+
+### ⚠️ High Priority - Production Code (Should Address Soon)
+
+#### 1. **ThreadSafety/ClassInstanceVariable** - 4 occurrences
+- **Severity:** Convention
+- **Location:** `lib/minting/mint/registry.rb` (lines 21, 64, 72, 80)
+- **Issue:** Class instance variables used in registry pattern for caching
+- **Current Design:** Registry caches currencies and symbol mappings using `@@` class variables
+- **Trade-offs:**
+  - ✅ Simple, works well for single-threaded scenarios
+  - ❌ Not thread-safe; could cause race conditions if accessed concurrently
+  - ❌ Rubocop flags this as an anti-pattern for multi-threaded apps
+- **Recommendation:** Current design is acceptable for a gem that caches static data (currencies don't change at runtime). Consider adding thread-safety if multi-threaded use becomes a requirement.
+- **Effort:** Medium (if refactored, would use class-level synchronization or lazy initialization)
+
+#### 2. **Metrics/ParameterLists** - 1 occurrence
+- **Severity:** Convention
+- **Location:** `lib/minting/mint/currency.rb:23`
+- **Issue:** Currency constructor has 6 parameters (limit: 5)
+- **Current Signature:** `initialize(code:, subunit:, symbol: nil, priority: 0, minimum_amount: nil, ...)`
+- **Recommendation:** Consider if all parameters are essential. Could use keyword arguments or a builder pattern.
+- **Effort:** Low-to-Medium (API surface change)
+
+#### 3. **Metrics/AbcSize (Low Severity)** - 3 occurrences in production code
+- **Severity:** Convention
+- **Locations:**
+  - `lib/minting/money/allocation.rb:15` - `allocate` method (18.68/17)
+  - `lib/minting/money/formatting.rb:81` - `format_amount` method (22.65/17)
+  - `lib/minting/money/money.rb:122` - `clamp` method (20.05/17)
+- **Issue:** These methods slightly exceed the complexity threshold, but are core business logic
+- **Recommendation:** These are acceptable as-is; splitting would reduce clarity. Monitor if they grow further.
+- **Effort:** Low priority; monitor only
+
+#### 4. **Metrics/CyclomaticComplexity & Metrics/PerceivedComplexity** - 3 occurrences
+- **Severity:** Convention
+- **Locations:**
+  - `lib/minting/money/money.rb:122` - `clamp` method
+  - `lib/minting/money/parse.rb:43` - `normalize_separators` method
+  - `test/performance/benchmark_helper.rb:71` - test utility
+- **Issue:** Multiple conditional branches increase cyclomatic complexity
+- **Recommendation:** These methods handle multi-condition business logic; acceptable for now. Refactor only if maintainability becomes an issue.
+- **Effort:** Low priority
+
+---
+
+### 📊 Medium Priority - Test Code Issues
+
+#### 1. **Minitest/MultipleAssertions** - 34 occurrences (37% of total issues)
+- **Severity:** Convention
+- **Affected Files:** Most test files
+- **Issue:** Test methods exceed 3 assertions (max threshold)
+- **Examples:**
+  - `test/mint_test.rb:21` - 10 assertions
+  - `test/money/money_allocation_test.rb:26` - 12 assertions
+  - `test/money/money_arithmetics_test.rb:6` - 7 assertions
+- **Rationale in Minting:** This is a measurement gem where comprehensive verification is necessary. Each operation's correctness depends on multiple properties:
+  - Amount correctness
+  - Currency preservation
+  - Rounding behavior
+  - Edge cases (zero, negative, large values)
+- **Recommendation:** Consider documenting this intentional choice in `.rubocop.yml` or refactoring into helper assertions that reduce per-test assertion count while maintaining test coverage.
+- **Effort:** Medium-to-High (would require restructuring test organization)
+
+#### 2. **Metrics/AbcSize (Test Context)** - 22 occurrences
+- **Severity:** Convention
+- **Affected Files:** Primarily benchmark and test files
+- **Issue:** Complex test methods with many branches
+- **Recommendation:** These are acceptable in test code; they reflect the complexity of the scenarios being tested. Low priority.
+- **Effort:** Low priority
+
+#### 3. **Metrics/ClassLength** - 4 occurrences
+- **Severity:** Convention
+- **Locations:**
+  - `test/money/money_format_test.rb:3` - 232 lines
+  - `test/performance/algorithm_benchmark.rb:5` - 172 lines
+  - `test/performance/competitive_performance_benchmark.rb:5` - 182 lines
+  - `test/performance/regression_benchmark.rb:5` - 151 lines
+- **Issue:** Test classes exceed 100-line limit
+- **Recommendation:** These are large test suites for good reason (comprehensive coverage). Could be split into smaller classes, but test organization should prioritize clarity over line counts.
+- **Effort:** Medium (if refactored)
+
+#### 4. **Metrics/BlockLength** - 3 occurrences
+- **Severity:** Convention
+- **Affected Files:** Performance benchmark files
+- **Issue:** Block length exceeds 25 lines
+- **Recommendation:** Low priority for benchmarks; these require comprehensive setup and measurement
+- **Effort:** Low priority
+
+#### 5. **Metrics/ModuleLength** - 1 occurrence
+- **Severity:** Convention
+- **Location:** `test/performance/benchmark_helper.rb:11` (105 lines)
+- **Issue:** Module slightly exceeds 100-line limit
+- **Recommendation:** This is a utility module for benchmarks; acceptable as-is
+- **Effort:** Low priority
+
+#### 6. **Performance/CollectionLiteralInLoop** - 1 occurrence
+- **Severity:** Convention
+- **Location:** `test/performance/algorithm_benchmark.rb:19`
+- **Issue:** Array literal created in loop
+- **Recommendation:** Extract to constant or variable outside loop for performance
+- **Effort:** Low
+
+---
+
+## Issue Distribution Analysis
+
+### By Component
+```
+Production Code Issues:
+├── lib/minting/mint/currency.rb: 1
+├── lib/minting/mint/registry.rb: 4 (thread safety)
+├── lib/minting/money/allocation.rb: 2
+├── lib/minting/money/formatting.rb: 1
+├── lib/minting/money/money.rb: 7 (complexity)
+└── lib/minting/money/parse.rb: 2
+
+Test/Benchmark Issues:
+├── Unit tests (test/): 43
+└── Benchmarks (test/performance/): 42
+```
+
+### By Severity
+- **Warnings:** 5 (Ruby 3.4 compatibility + empty when branches)
+- **Conventions:** 88 (style, complexity, structure)
+
+### By Cop Type
+```
+Minitest/MultipleAssertions    34 (37%)   - Test assertion counts
+Metrics/AbcSize                33 (35%)   - Complexity of methods
+ThreadSafety/ClassInstanceVar   4 (4%)   - Registry caching pattern
+Lint/EmptyWhen                  4 (4%)   - Incomplete case logic
+Metrics/ClassLength             4 (4%)   - Large test classes
+Metrics/CyclomaticComplexity    3 (3%)   - Branch complexity
+Metrics/PerceivedComplexity     3 (3%)   - Subjective complexity
+Metrics/BlockLength             3 (3%)   - Large blocks
+Others                          5 (5%)   - Various minor issues
+```
+
+---
+
+## Rubocop Configuration
+
+**Current thresholds** (in `.rubocop.yml`):
+- Line length: 120 characters
+- Method length: 30 lines
+- Default complexity thresholds apply
+
+**Active plugins:**
+- rubocop-minitest (for test-specific rules)
+- rubocop-packaging (gem packaging rules)
+- rubocop-performance (performance optimizations)
+- rubocop-rake (Rakefile rules)
+- rubocop-thread_safety (concurrency patterns)
+
+---
+
+## Recommendations by Priority
+
+### Priority 1: Fix Immediately
+- [ ] Fix `Lint/ItWithoutArgumentsInBlock` in `lib/minting/money/allocation.rb:56`
+  - **Effort:** < 5 minutes
+  - **Impact:** Ensures Ruby 3.4+ compatibility
+  
+- [ ] Clarify or fix `Lint/EmptyWhen` in `lib/minting/money/money.rb` (4 lines)
+  - **Effort:** < 10 minutes
+  - **Impact:** Clarifies intent of case statement logic
+
+### Priority 2: Plan Refactoring
+- [ ] Evaluate thread-safety requirements for `Registry` class
+  - **Effort:** Medium
+  - **Impact:** Determines if class variable pattern is acceptable
+  - **Timeline:** Consider for v2.0 or if multi-threaded use is required
+
+- [ ] Decide on parameter design for `Currency` (6 parameters vs. 5 max)
+  - **Effort:** Low
+  - **Impact:** Could simplify API
+  - **Timeline:** Can defer if current design is stable
+
+### Priority 3: Test Organization (Optional)
+- [ ] Consider refactoring test assertions to reduce `Minitest/MultipleAssertions` violations
+  - **Effort:** High
+  - **Impact:** Improves test organization, but current approach is acceptable
+  - **Timeline:** Only if test maintainability becomes an issue
+
+- [ ] Consider splitting large test/benchmark classes (`money_format_test.rb`, benchmark files)
+  - **Effort:** Medium-High
+  - **Impact:** Improves file organization
+  - **Timeline:** Optional; not critical
+
+---
+
+## Configuration Adjustments
+
+### Option A: Accept Current Baseline (Recommended)
+Keep current `.rubocop.yml` configuration. The violations represent:
+- Acceptable complexity trade-offs for a measurement gem
+- Best practices for test organization given domain requirements
+- Intentional design choices for performance and clarity
+
+### Option B: Relax Thresholds
+Add exceptions to `.rubocop.yml` for known violations:
+```yaml
+Minitest/MultipleAssertions:
+  Enabled: false  # Disable for this gem; multi-assertion tests are necessary
+
+Metrics/AbcSize:
+  Exclude:
+    - test/performance/**/*
+```
+
+### Option C: Strict Compliance (Not Recommended)
+Refactor to meet all thresholds. Would require:
+- Splitting large test classes (disruptive to test organization)
+- Reducing assertions per test (reduces coverage clarity)
+- Architectural changes to reduce method complexity
+
+---
+
+## Summary Table
+
+| Category | Count | Severity | Effort | Recommendation |
+|----------|-------|----------|--------|-----------------|
+| Ruby 3.4 Compatibility | 1 | High | Low | **Fix immediately** |
+| Empty When Branches | 4 | Medium | Low | **Fix/clarify** |
+| Thread Safety | 4 | Medium | Medium | Monitor & plan |
+| Parameter Lists | 1 | Low | Low | Optional refactor |
+| Method Complexity | 8 | Low | Medium | Accept as-is |
+| Test Assertions | 34 | Low | High | Accept/document intent |
+| Test Organization | 37 | Low | High | Optional refactor |
+
+---
+
+## Next Steps
+
+1. **Immediate (This Sprint):**
+   - Fix `Lint/ItWithoutArgumentsInBlock` warning
+   - Address `Lint/EmptyWhen` warnings (fix or document intent)
+   - Run full test suite to verify fixes don't break anything
+
+2. **Short-term (This Quarter):**
+   - Evaluate thread-safety requirements
+   - Decide on currency parameter design
+   - Document rationale for test assertion counts
+
+3. **Long-term (v2.0 Planning):**
+   - Consider architectural improvements to reduce complexity
+   - Evaluate thread-safety refactoring if multi-threaded use becomes a requirement
+   - Plan test organization improvements if maintainability becomes an issue
+
+---
+
+## Appendix: Full Issue List
+
+### Production Code - All Issues
+
+**lib/minting/mint/currency.rb**
+- Line 23: `Metrics/ParameterLists` - 6 parameters vs. 5 max
+
+**lib/minting/mint/registry.rb**
+- Line 21, 64, 72, 80: `ThreadSafety/ClassInstanceVariable` - 4 violations (class instance variables for caching)
+
+**lib/minting/money/allocation.rb**
+- Line 15: `Metrics/AbcSize` - allocate method (18.68/17)
+- Line 56: `Lint/ItWithoutArgumentsInBlock` - Warning for Ruby 3.4
+
+**lib/minting/money/formatting.rb**
+- Line 81: `Metrics/AbcSize` - format_amount method (22.65/17)
+
+**lib/minting/money/money.rb**
+- Line 122: `Metrics/AbcSize` - clamp method (20.05/17)
+- Line 122: `Metrics/CyclomaticComplexity` - clamp method (11/7)
+- Line 122: `Metrics/PerceivedComplexity` - clamp method (10/8)
+- Lines 136, 137, 147, 148: `Lint/EmptyWhen` - 4 empty when branches
+
+**lib/minting/money/parse.rb**
+- Line 43: `Metrics/CyclomaticComplexity` - normalize_separators (8/7)
+- Line 43: `Metrics/PerceivedComplexity` - normalize_separators (9/8)
+
+### Test Code - Summary
+- 34 `Minitest/MultipleAssertions` violations across test files
+- 22 `Metrics/AbcSize` violations in tests
+- 4 `Metrics/ClassLength` violations
+- 3 `Metrics/BlockLength` violations in benchmarks
+- 1 `Metrics/ModuleLength` in benchmark_helper.rb
+- 1 `Performance/CollectionLiteralInLoop` in algorithm_benchmark.rb
+
+See detailed output above for specific line numbers and messages.
+
+---
+
+**Generated:** 2026-06-03  
+**Rubocop Version:** 1.87.0  
+**Ruby Version:** 4.0.1