@hivehub/rulebook 4.2.2 → 4.3.0

package/templates/languages/RUBY.md

@@ -1,421 +1,421 @@
-<!-- RUBY:START -->
-# Ruby Project Rules
-
-## Agent Automation Commands
-
-**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
-
-```bash
-# Complete quality check sequence:
-bundle exec rubocop       # Linting and formatting
-bundle exec rspec         # All tests (100% pass)
-bundle exec rspec --format documentation  # Test coverage
-
-# Security audit:
-bundle audit              # Vulnerability scan
-bundle outdated           # Check outdated deps
-```
-
-## Ruby Configuration
-
-**CRITICAL**: Use Ruby 3.2+ with RuboCop and modern tooling.
-
-- **Version**: Ruby 3.2+
-- **Recommended**: Ruby 3.3+
-- **Style Guide**: Ruby Style Guide (RuboCop)
-- **Testing**: RSpec (recommended) or Minitest
-- **Type Checking**: RBS + Steep (optional but recommended)
-
-### Gemfile Requirements
-
-```ruby
-source 'https://rubygems.org'
-
-ruby '>= 3.2.0'
-
-# Production dependencies
-gem 'rake', '~> 13.0'
-
-# Development dependencies
-group :development do
-  gem 'rubocop', '~> 1.60', require: false
-  gem 'rubocop-performance', require: false
-  gem 'rubocop-rspec', require: false
-end
-
-# Test dependencies
-group :test do
-  gem 'rspec', '~> 3.12'
-  gem 'simplecov', require: false
-  gem 'simplecov-lcov', require: false
-end
-
-# Both development and test
-group :development, :test do
-  gem 'pry'
-  gem 'pry-byebug'
-end
-```
-
-### Gemspec Requirements (for gems)
-
-```ruby
-Gem::Specification.new do |spec|
-  spec.name = 'your_gem'
-  spec.version = '0.1.0'
-  spec.authors = ['Your Name']
-  spec.email = ['you@example.com']
-
-  spec.summary = 'Brief summary'
-  spec.description = 'Longer description'
-  spec.homepage = 'https://github.com/you/your_gem'
-  spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.2.0'
-
-  spec.files = Dir.glob('{lib,bin}/**/*') + %w[README.md LICENSE.txt]
-  spec.bindir = 'exe'
-  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-
-  spec.add_dependency 'rake', '~> 13.0'
-  
-  spec.add_development_dependency 'rspec', '~> 3.12'
-  spec.add_development_dependency 'rubocop', '~> 1.60'
-end
-```
-
-## Code Quality Standards
-
-### Mandatory Quality Checks
-
-**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
-
-**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
-
-```bash
-# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
-
-# 1. Lint (MUST pass with no warnings - matches workflow)
-bundle exec rubocop
-
-# 2. Run all tests (MUST pass 100% - matches workflow)
-bundle exec rspec
-# or: bundle exec rake test (for Minitest)
-
-# 3. Check coverage (MUST meet threshold - matches workflow)
-COVERAGE=true bundle exec rspec
-
-# 4. Security audit (matches workflow)
-bundle exec bundler-audit check --update
-
-# 5. Build gem (if gem project - matches workflow)
-gem build *.gemspec
-
-# If ANY fails: ❌ DO NOT COMMIT - Fix first!
-```
-
-**If ANY of these fail, you MUST fix the issues before committing.**
-
-**Why This Matters:**
-- Running different commands locally than in CI causes "works on my machine" failures
-- CI/CD workflows will fail if commands don't match
-- Example: Using `rubocop -a` (auto-correct) locally but `rubocop` in CI = failure
-- Example: Missing security audit locally = CI catches vulnerabilities in dependencies
-
-### Linting with RuboCop
-
-- Configuration in `.rubocop.yml`
-- Must pass with no offenses
-- Auto-correct safe offenses only
-
-Example `.rubocop.yml`:
-```yaml
-require:
-  - rubocop-performance
-  - rubocop-rspec
-
-AllCops:
-  TargetRubyVersion: 3.2
-  NewCops: enable
-  Exclude:
-    - 'vendor/**/*'
-    - 'tmp/**/*'
-    - 'bin/**/*'
-
-Style/StringLiterals:
-  EnforcedStyle: single_quotes
-
-Metrics/MethodLength:
-  Max: 15
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/BlockLength:
-  Exclude:
-    - 'spec/**/*'
-    - '*.gemspec'
-```
-
-### Testing
-
-- **Framework**: RSpec (recommended) or Minitest
-- **Location**: `/spec` (RSpec) or `/test` (Minitest)
-- **Coverage**: SimpleCov (80%+ threshold)
-- **Focus**: Write descriptive specs
-
-Example RSpec test:
-```ruby
-# spec/my_class_spec.rb
-
-RSpec.describe MyClass do
-  let(:instance) { described_class.new(value: 'test') }
-  
-  describe '#process' do
-    context 'with valid input' do
-      it 'returns processed value' do
-        result = instance.process('input')
-        expect(result).to eq('PROCESSED: input')
-      end
-      
-      it 'handles empty strings' do
-        expect(instance.process('')).to be_nil
-      end
-    end
-    
-    context 'with invalid input' do
-      it 'raises ArgumentError' do
-        expect { instance.process(nil) }.to raise_error(ArgumentError)
-      end
-    end
-  end
-  
-  describe '#validate' do
-    it 'returns true for valid data' do
-      expect(instance.validate('valid')).to be true
-    end
-    
-    it 'returns false for invalid data' do
-      expect(instance.validate('')).to be false
-    end
-  end
-end
-```
-
-Example Minitest:
-```ruby
-# test/my_class_test.rb
-
-require 'test_helper'
-
-class MyClassTest < Minitest::Test
-  def setup
-    @instance = MyClass.new(value: 'test')
-  end
-  
-  def test_process_returns_expected_value
-    result = @instance.process('input')
-    assert_equal 'PROCESSED: input', result
-  end
-  
-  def test_process_handles_empty_strings
-    assert_nil @instance.process('')
-  end
-  
-  def test_process_raises_on_nil
-    assert_raises(ArgumentError) { @instance.process(nil) }
-  end
-end
-```
-
-### Coverage Configuration
-
-Create `spec/spec_helper.rb`:
-```ruby
-if ENV['COVERAGE']
-  require 'simplecov'
-  require 'simplecov-lcov'
-  
-  SimpleCov::Formatter::LcovFormatter.config.report_with_single_file = true
-  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new([
-    SimpleCov::Formatter::HTMLFormatter,
-    SimpleCov::Formatter::LcovFormatter
-  ])
-  
-  SimpleCov.start do
-    add_filter '/spec/'
-    add_filter '/test/'
-    
-    minimum_coverage 80
-    minimum_coverage_by_file 70
-  end
-end
-
-require 'your_gem'
-
-RSpec.configure do |config|
-  config.expect_with :rspec do |expectations|
-    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
-  end
-
-  config.mock_with :rspec do |mocks|
-    mocks.verify_partial_doubles = true
-  end
-
-  config.shared_context_metadata_behavior = :apply_to_host_groups
-  config.filter_run_when_matching :focus
-  config.example_status_persistence_file_path = 'spec/examples.txt'
-  config.disable_monkey_patching!
-  config.warnings = true
-  
-  config.default_formatter = 'doc' if config.files_to_run.one?
-  config.profile_examples = 10
-  config.order = :random
-  Kernel.srand config.seed
-end
-```
-
-## Dependency Management
-
-### Using Bundler
-
-```bash
-# Install dependencies
-bundle install
-
-# Update dependencies
-bundle update
-
-# Check for outdated gems
-bundle outdated
-
-# Security audit
-bundle exec bundler-audit check --update
-```
-
-### Gemfile.lock
-
-- **MUST** commit Gemfile.lock for applications
-- For gems: Add to `.gitignore`
-- Ensures reproducible builds
-
-## Best Practices
-
-### DO's ✅
-
-- **USE** meaningful variable and method names
-- **FOLLOW** Ruby naming conventions (snake_case)
-- **WRITE** descriptive tests with context blocks
-- **HANDLE** exceptions explicitly
-- **VALIDATE** inputs
-- **DOCUMENT** public APIs
-- **USE** symbols for hash keys when possible
-- **FREEZE** string literals in Ruby 3+
-
-### DON'Ts ❌
-
-- **NEVER** use global variables
-- **NEVER** monkey-patch core classes without extreme caution
-- **NEVER** skip tests
-- **NEVER** commit `.byebug_history` or debug files
-- **NEVER** use `eval` unless absolutely necessary
-- **NEVER** ignore RuboCop offenses without justification
-- **NEVER** commit with failing tests
-
-Example code style:
-```ruby
-# ✅ GOOD: Clean Ruby code
-class DataProcessor
-  def initialize(options = {})
-    @threshold = options.fetch(:threshold, 0.5)
-    @verbose = options.fetch(:verbose, false)
-  end
-  
-  def process(data)
-    validate_input!(data)
-    
-    log('Processing data...') if @verbose
-    
-    data.select { |item| item[:value] > @threshold }
-  end
-  
-  private
-  
-  def validate_input!(data)
-    raise ArgumentError, 'Data must be an array' unless data.is_a?(Array)
-    raise ArgumentError, 'Data cannot be empty' if data.empty?
-  end
-  
-  def log(message)
-    puts "[#{Time.now.iso8601}] #{message}"
-  end
-end
-
-# ❌ BAD: Poor practices
-class DataProcessor
-  def process(data)
-    $threshold = 0.5  # DON'T use globals!
-    
-    if data == nil  # Use nil? method
-      return false
-    end
-    
-    result = []
-    for item in data  # Use .each or .map
-      if item[:value] > $threshold
-        result.push(item)
-      end
-    end
-    
-    puts result  # DON'T print in library code
-    result
-  end
-end
-```
-
-## CI/CD Requirements
-
-Must include GitHub Actions workflows:
-
-1. **Testing** (`ruby-test.yml`):
-   - Test on ubuntu-latest, windows-latest, macos-latest
-   - Ruby versions: 3.2, 3.3
-   - Upload coverage to Codecov
-
-2. **Linting** (`ruby-lint.yml`):
-   - RuboCop checks
-   - Bundler audit for security
-
-3. **Build** (`ruby-build.yml`):
-   - Build gem
-   - Verify gem structure
-
-## Publishing to RubyGems
-
-### Prerequisites
-
-1. Create account at https://rubygems.org
-2. Get API key: `gem signin`
-3. Add `RUBYGEMS_API_KEY` to GitHub secrets
-
-### Publishing Workflow
-
-```bash
-# 1. Update version in gemspec or version.rb
-# 2. Update CHANGELOG.md
-# 3. Run all quality checks
-bundle exec rubocop
-bundle exec rspec
-gem build *.gemspec
-
-# 4. Create git tag
-git tag -a v1.0.0 -m "Release version 1.0.0"
-
-# 5. Push (manual if SSH password)
-# git push origin main
-# git push origin v1.0.0
-
-# 6. Publish to RubyGems (or use GitHub Actions)
-gem push your_gem-1.0.0.gem
-```
-
-<!-- RUBY:END -->
+<!-- RUBY:START -->
+# Ruby Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+bundle exec rubocop       # Linting and formatting
+bundle exec rspec         # All tests (100% pass)
+bundle exec rspec --format documentation  # Test coverage
+
+# Security audit:
+bundle audit              # Vulnerability scan
+bundle outdated           # Check outdated deps
+```
+
+## Ruby Configuration
+
+**CRITICAL**: Use Ruby 3.2+ with RuboCop and modern tooling.
+
+- **Version**: Ruby 3.2+
+- **Recommended**: Ruby 3.3+
+- **Style Guide**: Ruby Style Guide (RuboCop)
+- **Testing**: RSpec (recommended) or Minitest
+- **Type Checking**: RBS + Steep (optional but recommended)
+
+### Gemfile Requirements
+
+```ruby
+source 'https://rubygems.org'
+
+ruby '>= 3.2.0'
+
+# Production dependencies
+gem 'rake', '~> 13.0'
+
+# Development dependencies
+group :development do
+  gem 'rubocop', '~> 1.60', require: false
+  gem 'rubocop-performance', require: false
+  gem 'rubocop-rspec', require: false
+end
+
+# Test dependencies
+group :test do
+  gem 'rspec', '~> 3.12'
+  gem 'simplecov', require: false
+  gem 'simplecov-lcov', require: false
+end
+
+# Both development and test
+group :development, :test do
+  gem 'pry'
+  gem 'pry-byebug'
+end
+```
+
+### Gemspec Requirements (for gems)
+
+```ruby
+Gem::Specification.new do |spec|
+  spec.name = 'your_gem'
+  spec.version = '0.1.0'
+  spec.authors = ['Your Name']
+  spec.email = ['you@example.com']
+
+  spec.summary = 'Brief summary'
+  spec.description = 'Longer description'
+  spec.homepage = 'https://github.com/you/your_gem'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.files = Dir.glob('{lib,bin}/**/*') + %w[README.md LICENSE.txt]
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'rake', '~> 13.0'
+  
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+end
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Lint (MUST pass with no warnings - matches workflow)
+bundle exec rubocop
+
+# 2. Run all tests (MUST pass 100% - matches workflow)
+bundle exec rspec
+# or: bundle exec rake test (for Minitest)
+
+# 3. Check coverage (MUST meet threshold - matches workflow)
+COVERAGE=true bundle exec rspec
+
+# 4. Security audit (matches workflow)
+bundle exec bundler-audit check --update
+
+# 5. Build gem (if gem project - matches workflow)
+gem build *.gemspec
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- Running different commands locally than in CI causes "works on my machine" failures
+- CI/CD workflows will fail if commands don't match
+- Example: Using `rubocop -a` (auto-correct) locally but `rubocop` in CI = failure
+- Example: Missing security audit locally = CI catches vulnerabilities in dependencies
+
+### Linting with RuboCop
+
+- Configuration in `.rubocop.yml`
+- Must pass with no offenses
+- Auto-correct safe offenses only
+
+Example `.rubocop.yml`:
+```yaml
+require:
+  - rubocop-performance
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'bin/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Metrics/MethodLength:
+  Max: 15
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+```
+
+### Testing
+
+- **Framework**: RSpec (recommended) or Minitest
+- **Location**: `/spec` (RSpec) or `/test` (Minitest)
+- **Coverage**: SimpleCov (80%+ threshold)
+- **Focus**: Write descriptive specs
+
+Example RSpec test:
+```ruby
+# spec/my_class_spec.rb
+
+RSpec.describe MyClass do
+  let(:instance) { described_class.new(value: 'test') }
+  
+  describe '#process' do
+    context 'with valid input' do
+      it 'returns processed value' do
+        result = instance.process('input')
+        expect(result).to eq('PROCESSED: input')
+      end
+      
+      it 'handles empty strings' do
+        expect(instance.process('')).to be_nil
+      end
+    end
+    
+    context 'with invalid input' do
+      it 'raises ArgumentError' do
+        expect { instance.process(nil) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+  
+  describe '#validate' do
+    it 'returns true for valid data' do
+      expect(instance.validate('valid')).to be true
+    end
+    
+    it 'returns false for invalid data' do
+      expect(instance.validate('')).to be false
+    end
+  end
+end
+```
+
+Example Minitest:
+```ruby
+# test/my_class_test.rb
+
+require 'test_helper'
+
+class MyClassTest < Minitest::Test
+  def setup
+    @instance = MyClass.new(value: 'test')
+  end
+  
+  def test_process_returns_expected_value
+    result = @instance.process('input')
+    assert_equal 'PROCESSED: input', result
+  end
+  
+  def test_process_handles_empty_strings
+    assert_nil @instance.process('')
+  end
+  
+  def test_process_raises_on_nil
+    assert_raises(ArgumentError) { @instance.process(nil) }
+  end
+end
+```
+
+### Coverage Configuration
+
+Create `spec/spec_helper.rb`:
+```ruby
+if ENV['COVERAGE']
+  require 'simplecov'
+  require 'simplecov-lcov'
+  
+  SimpleCov::Formatter::LcovFormatter.config.report_with_single_file = true
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new([
+    SimpleCov::Formatter::HTMLFormatter,
+    SimpleCov::Formatter::LcovFormatter
+  ])
+  
+  SimpleCov.start do
+    add_filter '/spec/'
+    add_filter '/test/'
+    
+    minimum_coverage 80
+    minimum_coverage_by_file 70
+  end
+end
+
+require 'your_gem'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.example_status_persistence_file_path = 'spec/examples.txt'
+  config.disable_monkey_patching!
+  config.warnings = true
+  
+  config.default_formatter = 'doc' if config.files_to_run.one?
+  config.profile_examples = 10
+  config.order = :random
+  Kernel.srand config.seed
+end
+```
+
+## Dependency Management
+
+### Using Bundler
+
+```bash
+# Install dependencies
+bundle install
+
+# Update dependencies
+bundle update
+
+# Check for outdated gems
+bundle outdated
+
+# Security audit
+bundle exec bundler-audit check --update
+```
+
+### Gemfile.lock
+
+- **MUST** commit Gemfile.lock for applications
+- For gems: Add to `.gitignore`
+- Ensures reproducible builds
+
+## Best Practices
+
+### DO's ✅
+
+- **USE** meaningful variable and method names
+- **FOLLOW** Ruby naming conventions (snake_case)
+- **WRITE** descriptive tests with context blocks
+- **HANDLE** exceptions explicitly
+- **VALIDATE** inputs
+- **DOCUMENT** public APIs
+- **USE** symbols for hash keys when possible
+- **FREEZE** string literals in Ruby 3+
+
+### DON'Ts ❌
+
+- **NEVER** use global variables
+- **NEVER** monkey-patch core classes without extreme caution
+- **NEVER** skip tests
+- **NEVER** commit `.byebug_history` or debug files
+- **NEVER** use `eval` unless absolutely necessary
+- **NEVER** ignore RuboCop offenses without justification
+- **NEVER** commit with failing tests
+
+Example code style:
+```ruby
+# ✅ GOOD: Clean Ruby code
+class DataProcessor
+  def initialize(options = {})
+    @threshold = options.fetch(:threshold, 0.5)
+    @verbose = options.fetch(:verbose, false)
+  end
+  
+  def process(data)
+    validate_input!(data)
+    
+    log('Processing data...') if @verbose
+    
+    data.select { |item| item[:value] > @threshold }
+  end
+  
+  private
+  
+  def validate_input!(data)
+    raise ArgumentError, 'Data must be an array' unless data.is_a?(Array)
+    raise ArgumentError, 'Data cannot be empty' if data.empty?
+  end
+  
+  def log(message)
+    puts "[#{Time.now.iso8601}] #{message}"
+  end
+end
+
+# ❌ BAD: Poor practices
+class DataProcessor
+  def process(data)
+    $threshold = 0.5  # DON'T use globals!
+    
+    if data == nil  # Use nil? method
+      return false
+    end
+    
+    result = []
+    for item in data  # Use .each or .map
+      if item[:value] > $threshold
+        result.push(item)
+      end
+    end
+    
+    puts result  # DON'T print in library code
+    result
+  end
+end
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows:
+
+1. **Testing** (`ruby-test.yml`):
+   - Test on ubuntu-latest, windows-latest, macos-latest
+   - Ruby versions: 3.2, 3.3
+   - Upload coverage to Codecov
+
+2. **Linting** (`ruby-lint.yml`):
+   - RuboCop checks
+   - Bundler audit for security
+
+3. **Build** (`ruby-build.yml`):
+   - Build gem
+   - Verify gem structure
+
+## Publishing to RubyGems
+
+### Prerequisites
+
+1. Create account at https://rubygems.org
+2. Get API key: `gem signin`
+3. Add `RUBYGEMS_API_KEY` to GitHub secrets
+
+### Publishing Workflow
+
+```bash
+# 1. Update version in gemspec or version.rb
+# 2. Update CHANGELOG.md
+# 3. Run all quality checks
+bundle exec rubocop
+bundle exec rspec
+gem build *.gemspec
+
+# 4. Create git tag
+git tag -a v1.0.0 -m "Release version 1.0.0"
+
+# 5. Push (manual if SSH password)
+# git push origin main
+# git push origin v1.0.0
+
+# 6. Publish to RubyGems (or use GitHub Actions)
+gem push your_gem-1.0.0.gem
+```
+
+<!-- RUBY:END -->