familia 2.0.0.pre16 → 2.0.0.pre18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebaf394ebbccf9d096e87da84c693040c71d963860002a9d970d9b04edc11b6c
-  data.tar.gz: 4862991d1b2a1538876089030657986eb1b56f5551c7e5e9978a1009c77e86f9
+  metadata.gz: e5bbf0ac2fc6a1243d74f679c7027040be00783af625dd90d376637e32417394
+  data.tar.gz: 4b354347a0c2403490dc20fdc12f93b3e71b826cf0b2b08638f6fd884a883630
 SHA512:
-  metadata.gz: 533af9a33a115e8a59c87ae35e5b82401e1d72edbe43fd4a2963a3ca25a2c1ac259e5aaf02e68945d9d2f576393c6f77e9843ec87c4ed92696ca41d0b06e4d4c
-  data.tar.gz: b74dca7e415cbd0d6933beb77185e7738d33b3c10a704569120892fa9062fe92874fe2b879439f8d9508b8d02ba0e8154c79cb1546b029ac9e6bbdde442fd5e1
+  metadata.gz: 221116e1aa14bc7114cb51164727587dcb0e8435dd8b85bb7d14618393ef446446376fd7febf6dbc9993098e2c819b3b0aa6f3c8bedce1c965b99ec4c8832a7b
+  data.tar.gz: 457b0e5bfef1f203c8f2edf934d1ee37915df04c49b0cb8b097ab9732738186ba9e8e92496851699f0952426971d2d3d244e61e594719439672996a0ccde2050

data/.github/workflows/ci.yml

@@ -35,8 +35,8 @@ jobs:
           --health-retries 5
         ports:
           # https://docs.github.com/en/actions/using-containerized-services/creating-redis-service-containers#running-jobs-in-containers
-          # Maps port 6379 on service container to the host
-          - 6379:6379
+          # Maps port 6379 on service container to 2525 on the host
+          - 2525:6379
 
     steps:
       - uses: actions/checkout@v4

data/.github/workflows/{code-smellage.yml → code-smells.yml}

@@ -1,4 +1,6 @@
-name: Any Code Smellage?
+# ..github/workflows/code-smells.yml
+---
+name: Code Smells
 
 on:
   pull_request:
@@ -81,65 +83,3 @@ jobs:
             reek-report.html
           if-no-files-found: ignore
           retention-days: 30
-
-  # Add other code quality checks here
-  additional-quality-checks:
-    name: Additional Quality Checks
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.4
-          bundler-cache: true
-
-      - name: Configure Bundler for secure gem installation
-        run: |
-          bundle config set --local path 'vendor/bundle'
-          bundle config set --local deployment 'false'
-
-      - name: Install dependencies
-        run: bundle install --jobs 4 --retry 3
-
-      - name: Check for TODO/FIXME comments
-        run: |
-          echo "=== Scanning for TODO/FIXME comments ==="
-          echo "This helps track technical debt and action items."
-          echo ""
-
-          # Find TODO/FIXME comments (excluding this workflow file)
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            xargs grep -Hn -i -E "(TODO|FIXME|HACK|XXX|NOTE):" 2>/dev/null | \
-            head -20 || echo "No TODO/FIXME comments found"
-        continue-on-error: true
-
-      - name: Check Ruby file syntax
-        run: |
-          echo "=== Checking Ruby syntax ==="
-          echo "Validates that all Ruby files have correct syntax."
-          echo ""
-
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            while read -r file; do
-              if ! ruby -c "$file" > /dev/null 2>&1; then
-                echo "Syntax error in: $file"
-                ruby -c "$file"
-              fi
-            done
-        continue-on-error: true
-
-      - name: Check for long lines
-        run: |
-          echo "=== Checking for long lines (>120 characters) ==="
-          echo "Identifies potentially hard-to-read code lines."
-          echo ""
-
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            xargs grep -Hn "^.\{121,\}$" | \
-            head -10 || echo "No overly long lines found"
-        continue-on-error: true

data/.gitignore

@@ -14,7 +14,9 @@
 *.log
 *.txt
 .ruby-version
+dump.rdb
 appendonlydir
+data
 log
 tmp
 vendor

data/.rubocop.yml

@@ -124,6 +124,9 @@ Style/NegatedIfElseCondition:
 Naming/AsciiIdentifiers:
   Enabled: false
 
+Naming/PredicateMethod:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: single_quotes
@@ -135,6 +138,9 @@ Style/FrozenStringLiteralComment:
 Naming/MemoizedInstanceVariableName:
   Enabled: false
 
+ThreadSafety/ClassAndModuleAttributes:
+  Enabled: false
+
 ThreadSafety/ClassInstanceVariable:
   Enabled: false
 

data/CHANGELOG.rst

@@ -12,6 +12,88 @@ Versioning <https://semver.org/spec/v2.0.0.html>`__.
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre18:
+
+2.0.0.pre18 — 2025-10-05
+========================
+
+Added
+-----
+
+- Added ``Familia.reconnect!`` method to refresh connection pools with current middleware configuration. This solves issues in test suites where middleware (like DatabaseLogger) is enabled after connection pools are created. The method clears the connection chain, increments the middleware version, and clears fiber-local connections, ensuring new connections include the latest middleware. See ``lib/familia/connection/middleware.rb:81-117``.
+
+Changed
+-------
+
+- **BREAKING**: Implemented type-preserving JSON serialization for Horreum field values. Non-string values (Integer, Boolean, Float, nil, Hash, Array) are JSON-encoded for storage and JSON-decoded on retrieval. **Strings are stored as-is without JSON encoding** to avoid double-quoting and maintain Redis baseline simplicity. Type preservation is achieved through smart deserialization: values that parse as JSON restore to their original types, otherwise remain as strings.
+
+- **BREAKING**: Changed default Hash key format from symbols to strings throughout the codebase (``symbolize: false`` default). This eliminates ambiguity with HTTP request parameters and IndifferentHash-style implementations, providing strict adherence to JSON parsing rules and avoiding key duplication issues.
+
+- **BREAKING**: Fixed ``initialize_with_keyword_args`` to properly handle ``false`` and ``0`` values during object initialization. Previously, falsy values were incorrectly skipped due to truthiness checks. Now uses explicit nil checking with ``fetch`` to preserve all non-nil values including ``false`` and ``0``.
+
+- **String serialization now uses JSON encoding**: All string values are JSON-encoded during storage (wrapped in quotes) for consistent type preservation. The lenient deserializer handles both new JSON-encoded strings and legacy plain strings automatically. PR #152
+
+Removed
+-------
+
+- **BREAKING**: Removed ``dump_method`` and ``load_method`` configuration options from ``Familia::Base`` and ``Familia::Horreum::Definition``. JSON serialization is now hard-coded for consistency and type safety. Custom serialization methods are no longer supported.
+
+Fixed
+-----
+
+- Fixed type coercion bugs where Integer fields (e.g., ``age: 35``) became Strings (``"35"``) and Boolean fields (e.g., ``active: true``) became Strings (``"true"``) after database round-trips. All primitive types now maintain their original types through ``find_by_dbkey``, ``refresh!``, and ``batch_update`` operations.
+
+- Fixed ``deserialize_value`` to return all JSON-parsed types instead of filtering to Hash/Array only. This enables proper deserialization of primitive types (Integer, Boolean, Float, String) from Redis storage.
+
+- Added JSON deserialization in ``find_by_dbkey`` using existing ``initialize_with_keyword_args_deserialize_value`` helper method to maintain DRY principles and ensure loaded objects receive properly typed field values rather than raw Redis strings.
+
+- Optimized serialization to avoid double-encoding strings - strings stored directly in Redis as-is, only non-string types use JSON encoding. This reduces storage overhead and maintains Redis's string baseline semantics.
+
+- Fixed encrypted fields with ``category: :encrypted`` appearing in ``to_h()`` output. These fields now correctly set ``loggable: false`` to prevent accidental exposure in logs, APIs, or external interfaces. PR #152
+
+- Fixed middleware registration to only set ``@middleware_registered`` flag when middleware is actually enabled and registered. Previously, calling ``create_dbclient`` before enabling middleware would set the flag to ``true`` without registering anything, preventing later middleware enablement from working. The fix ensures ``register_middleware_once`` only sets the flag after successful registration. See ``lib/familia/connection/middleware.rb:124-146``.
+
+Security
+--------
+
+- Encrypted fields defined via ``field :name, category: :encrypted`` now properly excluded from ``to_h()`` serialization, matching the security behavior of ``encrypted_field``. PR #152
+
+Documentation
+-------------
+
+- Added comprehensive type preservation test suite (``try/unit/horreum/json_type_preservation_try.rb``) with 30 test cases covering Integer, Boolean, String, Float, Hash, Array, nested structures, nil handling, empty strings, zero values, round-trip consistency, ``batch_update``, and ``refresh!`` operations.
+
+AI Assistance
+-------------
+
+- Claude Code (claude-sonnet-4-5) provided implementation guidance, identified the ``initialize_with_keyword_args`` falsy value bug, wrote comprehensive test suite, and coordinated multi-file changes across serialization, management, and base modules.
+
+- Issue analysis, implementation guidance, test verification, and documentation for JSON serialization changes and encrypted field security fix.
+
+- Claude Code (Sonnet 4.5) provided architecture analysis, implementation design, and identified critical issues through the second-opinion agent. Key contributions included recommending the simplified approach without pool shutdown lifecycle management, identifying the race condition risk in clearing ``@middleware_registered``, and suggesting the use of natural pool aging instead of explicit shutdown.
+
+.. _changelog-2.0.0.pre17:
+
+2.0.0.pre17 — 2025-10-03
+========================
+
+Added
+-----
+
+- **SortedSet#add**: Full ZADD option support (NX, XX, GT, LT, CH) for atomic conditional operations and accurate change tracking. This enables proper index management with timestamp preservation, update-only operations, conditional score updates, and analytics tracking. Closes issue #135.
+
+Fixed
+-----
+
+- Restored objid provenance tracking when loading objects from Redis. The ``ObjectIdentifier`` feature now infers the generator type (:uuid_v7, :uuid_v4, :hex) from the objid format, enabling dependent features like ``ExternalIdentifier`` to derive external identifiers from loaded objects. PR #131
+
+AI Assistance
+-------------
+
+- Claude Code assisted with implementing the ``infer_objid_generator`` method and updating the setter logic in ``lib/familia/features/object_identifier.rb``.
+
+- Claude Code assisted with Redis ZADD option semantics research, mutual exclusivity validation design, comprehensive test case matrix creation (50+ test cases), and YAML documentation examples.
+
 .. _changelog-2.0.0.pre16:
 
 2.0.0.pre16 — 2025-09-30

data/CLAUDE.md

@@ -92,6 +92,44 @@ Familia uses a modular feature system where features are mixed into classes:
 
 **Inheritance Chain**: `MyClass < Familia::Horreum` automatically extends `ClassMethods` and `Features`
 
+**Common Pitfall: Overriding initialize**
+
+⚠️ **Do NOT override `initialize` without calling `super`** - this breaks related field initialization.
+
+**Bad - will cause crashes:**
+```ruby
+class User < Familia::Horreum
+  def initialize(email)
+    @email = email  # Missing super! Related fields won't work
+  end
+end
+```
+
+**Good - use the `init` hook instead:**
+```ruby
+class User < Familia::Horreum
+  def init(email = nil)
+    @email = email  # Called after super, related fields work
+  end
+end
+```
+
+**Good - call super explicitly:**
+```ruby
+class User < Familia::Horreum
+  def initialize(email = nil, **kwargs)
+    super(**kwargs)  # ✓ Related fields initialized
+    @email = email
+  end
+end
+```
+
+**Why this matters**: Familia's `initialize` method calls `initialize_relatives` to set up DataType objects (lists, sets, etc.). Without calling `super`, these objects remain nil and you'll get helpful errors pointing to the missing super call.
+
+**When to use each approach:**
+- **Use `init` hook** (preferred): For simple initialization logic that doesn't need to intercept constructor arguments. The `init` method is called automatically after `super` with the same arguments passed to `new`.
+- **Use explicit `super`**: When you need full control over initialization order or need to transform arguments before passing to parent. Remember to pass `**kwargs` to preserve keyword argument handling.
+
 **DataType Definition**: Use class methods to define keystore database-backed attributes:
 ```ruby
 class User < Familia::Horreum
@@ -116,8 +154,15 @@ end
 
 ### Important Implementation Notes
 
-**Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended.
-**Serialization**: Uses JSON by default but supports custom `serialize_value`/`deserialize_value` methods.
+**Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended. All non-nil values including `false` and `0` are preserved during initialization.
+
+**Serialization**: All field values are JSON-encoded for storage and JSON-decoded on retrieval to preserve Ruby types (Integer, Boolean, String, Float, Hash, Array, nil). This ensures type preservation across the Redis storage boundary. For example:
+- `age: 35` (Integer) stores as `"35"` in Redis and loads back as Integer `35`
+- `active: true` (Boolean) stores as `"true"` in Redis and loads back as Boolean `true`
+- `metadata: {key: "value"}` (Hash) stores as JSON and loads back as Hash with proper types
+
 **Database Key Generation**: Automatic key generation using class name, identifier, and field/type names (aka dbkey). Pattern: `classname:identifier:fieldname`
+
 **Memory Efficiency**: Only non-nil values are stored in keystore database to optimize memory usage.
+
 **Thread Safety**: Data types are frozen after instantiation to ensure immutability.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre16)
+    familia (2.0.0.pre18)
       benchmark (~> 0.4)
       connection_pool (~> 2.5)
       csv (~> 3.3)

data/README.md

@@ -438,6 +438,19 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+### PR Compliance Checks
+
+Pull requests are automatically reviewed by [Qodo Merge](https://qodo.ai) with compliance checks for:
+- **Error Handling** - External API calls and database operations must have proper error handling
+- **Test Coverage** - New features must include tests using the Tryouts framework
+- **Changelog Fragments** - User-facing changes should include a changelog entry
+- **Documentation** - API changes must update documentation
+- **Backward Compatibility** - Breaking changes must be documented
+- **Thread Safety** - Shared state must be properly synchronized
+- **Database Key Naming** - Keys must follow Familia conventions
+
+See [docs/qodo-merge-compliance.md](docs/qodo-merge-compliance.md) for details.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

data/bin/irb

@@ -1,3 +1,3 @@
 #!/bin/bash
 
-irb -Ilib -r familia -Itry -r helpers/test_helpers
+irb -Ilib -r familia -Itry -r support/helpers/test_helpers

data/docs/archive/FAMILIA_TECHNICAL.md

@@ -722,7 +722,7 @@ require 'familia'
 
 # Use separate Valkey/Redis database for tests
 Familia.configure do |config|
-  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:6379/15')
+  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:2525/3')
 end
 
 module TestHelpers

data/docs/guides/core-field-system.md

@@ -50,17 +50,20 @@ customer.email = "admin@acme.com"     # Custom method name
 customer.name!("Updated Corp")        # Fast writer (immediate DB persistence)
 ```
 
-### Field Categories
+### Special Field Types
 
-Fields can be categorized for special processing by features:
+Use dedicated field methods provided by features for special field behaviors:
 
 ```ruby
 class Document < Familia::Horreum
-  field :title                           # Regular field
-  field :content, category: :encrypted   # Will be processed by encrypted_fields feature
-  field :api_key, category: :transient   # Non-persistent field
-  field :tags, category: :indexed        # Custom category for indexing
-  field :metadata, category: :json       # Custom JSON serialization
+  feature :encrypted_fields
+  feature :transient_fields
+
+  field :title                    # Regular persistent field
+  encrypted_field :content        # Encrypted storage
+  transient_field :api_key        # Non-persistent (memory only)
+  field :tags                     # Regular field
+  field :metadata                 # Regular field
 end
 ```
 
@@ -285,27 +288,28 @@ order.priority_urgent?   # => false
 
 ```ruby
 class Product < Familia::Horreum
-  field :name, category: :searchable
-  field :price, category: :numeric
-  field :description, category: :text
-  field :secret_key, category: :encrypted
+  feature :transient_fields
+
+  field :name
+  field :price
+  field :description
   transient_field :temp_data
 end
 
 # Get all field names
 Product.fields
-# => [:name, :price, :description, :secret_key, :temp_data]
+# => [:name, :price, :description, :temp_data]
 
 # Get field types registry
 Product.field_types
 # => { name: #<FieldType...>, price: #<FieldType...>, ... }
 
-# Get fields by category
-Product.fields.select { |f| Product.field_types[f].category == :searchable }
-# => [:name]
+# Get fields by category (read-only introspection)
+Product.fields.select { |f| Product.field_types[f].category == :transient }
+# => [:temp_data]
 
 # Get persistent vs transient fields
-Product.persistent_fields  # => [:name, :price, :description, :secret_key]
+Product.persistent_fields  # => [:name, :price, :description]
 Product.transient_fields   # => [:temp_data]
 
 # Field method mapping (for backward compatibility)
@@ -313,15 +317,24 @@ Product.field_method_map
 # => { name: :name, price: :price, secret_key: :secret_key, temp_data: :temp_data }
 ```
 
-### Field Categories for Feature Processing
+### Using Field Type Category for Introspection
+
+The `category` method on FieldType provides read-only metadata for introspection:
 
 ```ruby
-# Features can process fields by category
+# Custom field type with category metadata
+class SearchableFieldType < Familia::FieldType
+  def category
+    :searchable
+  end
+end
+
+# Features can process fields by inspecting their category
 module SearchableFieldsFeature
   def self.included(base)
     base.extend ClassMethods
 
-    # Process all searchable fields
+    # Find all searchable fields by inspecting field type category
     searchable_fields = base.fields.select do |field|
       base.field_types[field].category == :searchable
     end
@@ -348,11 +361,17 @@ module SearchableFieldsFeature
 end
 
 class Product < Familia::Horreum
-  feature :searchable_fields  # Processes all :searchable category fields
+  feature :searchable_fields
 
-  field :name, category: :searchable
-  field :description, category: :searchable
-  field :internal_id, category: :system
+  # Use custom field type with searchable category
+  def self.searchable_field(name, **options)
+    field_type = SearchableFieldType.new(name, **options)
+    register_field_type(field_type)
+  end
+
+  searchable_field :name
+  searchable_field :description
+  field :internal_id
 end
 
 # Auto-generated search methods available
@@ -733,10 +752,13 @@ end
 ### 1. Choose Appropriate Field Types
 
 ```ruby
-# Use built-in field types when possible
+# Use dedicated field methods provided by features
 class User < Familia::Horreum
-  field :name                    # Simple string field
-  field :metadata, category: :json  # For complex data
+  feature :transient_fields
+  feature :encrypted_fields
+
+  field :name                    # Simple persistent field
+  field :metadata                # For complex data
   transient_field :temp_token    # For runtime-only data
   encrypted_field :api_key       # For sensitive data
 end

data/docs/migrating/v2.0.0-pre18.md

@@ -0,0 +1,58 @@
+# Migrating Guide: v2.0.0-pre18
+
+This version completes the JSON serialization implementation by removing the string-as-is optimization and fixes encrypted field visibility in serialization.
+
+## JSON Serialization for All Types
+
+**What Changed:**
+
+All field values (including strings) are now JSON-encoded during storage for consistent type preservation.
+
+**Storage Format:**
+
+```ruby
+# Before (v2.0.0-pre14):
+HGET user:123 name
+"John Doe"                    # Plain string
+
+# After (v2.0.0-pre18):
+HGET user:123 name
+"\"John Doe\""                # JSON-encoded string
+```
+
+**Migration:**
+
+No migration needed. The deserializer automatically handles:
+- **New format**: `"\"value\""` → `"value"`
+- **Legacy format**: `"value"` → `"value"`
+
+**Why This Matters:**
+
+Prevents data corruption for edge cases:
+- Badge `"007"` stays `"007"` (not converted to integer `7`)
+- String `"true"` stays `"true"` (not converted to boolean)
+- String `"null"` stays `"null"` (not converted to `nil`)
+
+## Encrypted Field Security Fix
+
+**What Changed:**
+
+Fields defined with `category: :encrypted` now correctly exclude encrypted data from `to_h()` output.
+
+**Before:**
+```ruby
+field :secret, category: :encrypted
+user.to_h  # => {"id" => "123", "secret" => {...}}  # ❌ Exposed!
+```
+
+**After:**
+```ruby
+field :secret, category: :encrypted
+user.to_h  # => {"id" => "123"}  # ✅ Secure
+```
+
+Both `encrypted_field` and `field :name, category: :encrypted` now behave identically for security.
+
+**Migration:**
+
+No code changes needed. Review any code relying on encrypted fields appearing in `to_h()` output.

data/docs/overview.md

@@ -708,7 +708,7 @@ when 'production'
 when 'development'
   Familia.uri = 'redis://localhost:6379/0'
 when 'test'
-  Familia.uri = 'redis://localhost:6379/15'
+  Familia.uri = 'redis://localhost:2525/3'
 end
 ```
 
@@ -868,7 +868,7 @@ Familia.redis.keys('*')  # List all keys (use carefully in production)
 require 'familia'
 
 # Use separate test database
-Familia.uri = 'redis://localhost:6379/15'
+Familia.uri = 'redis://localhost:2525/3'
 
 # Setup encryption for tests
 test_keys = {

data/docs/qodo-merge-compliance.md

@@ -0,0 +1,96 @@
+# Qodo Merge Compliance Configuration
+
+This document describes the Qodo Merge (formerly PR-Agent) configuration for the Familia project.
+
+## Overview
+
+Qodo Merge provides automated PR analysis, code reviews, and compliance checks. Our configuration enables two key compliance features:
+
+1. **Codebase Duplication Compliance** - Uses RAG (Retrieval-Augmented Generation) to check for duplicate code across related repositories
+2. **Custom Compliance** - Project-specific rules tailored to Familia's development practices
+
+## Configuration Files
+
+### pr_agent.toml
+
+The main Qodo Merge configuration file located in the repository root. It includes:
+
+- **Response Language**: Set to English for consistency
+- **RAG Context Enrichment**: Enabled with related repositories (`delano/familia`, `delano/tryouts`, `delano/otto`)
+- **Custom Compliance Path**: References our custom compliance checklist
+- **Ignore Rules**: Excludes generated files and build artifacts from analysis
+
+### pr_compliance_checklist.yaml
+
+Custom compliance rules specific to Familia development:
+
+#### ErrorHandling
+All external API calls and database operations must have proper error handling with try-catch blocks or appropriate error handling mechanisms.
+
+#### TestCoverage
+New features must include tests using the Tryouts framework. Test files should be in the `try/` directory following the `*_try.rb` or `*.try.rb` naming convention.
+
+#### ChangelogFragment
+User-facing changes must include a changelog fragment in the `changelog.d/` directory following RST format, or provide explicit justification for omission.
+
+#### DocumentationUpdates
+API changes must be reflected in documentation, including YARD comments for new public methods or updates to the `docs/` directory.
+
+#### BackwardCompatibility
+Changes must maintain backward compatibility or document breaking changes in migration guides with deprecation warnings.
+
+#### ThreadSafety
+Code handling shared state must be thread-safe with proper synchronization or clear documentation of thread-safety assumptions.
+
+#### DatabaseKeyNaming
+Database key generation must follow Familia conventions:
+- Use the configured `delim` separator (default `:`)
+- Avoid reserved keywords: `ttl`, `db`, `valkey`, `redis`
+- Handle empty identifiers to prevent stack overflow
+
+## Interactive Commands
+
+Team members can trigger on-demand Qodo Merge analysis in PR comments:
+
+- `/analyze --review` - Run code review
+- `/analyze --test` - Generate test suggestions
+- `/improve` - Get improvement suggestions
+- `/ask` - Ask questions about the PR
+
+## Compliance Status
+
+In PR comments from `@qodo-merge-pro`, you'll see:
+
+- 🟢 Green circle - Compliance check passed
+- 🔴 Red circle - Compliance check failed with details
+- ⚪ White circle - Compliance check not configured (should not appear with proper configuration)
+
+## References
+
+- [Qodo Merge Configuration Options](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/)
+- [RAG Context Enrichment Guide](https://qodo-merge-docs.qodo.ai/core-abilities/rag_context_enrichment/)
+- [Compliance Guide](https://qodo-merge-docs.qodo.ai/tools/compliance/)
+- [Best Practices](https://docs.qodo.ai/qodo-documentation/qodo-merge/features/best-practices)
+
+## Maintenance
+
+### Updating Compliance Rules
+
+To add or modify compliance rules:
+
+1. Edit `pr_compliance_checklist.yaml`
+2. Ensure YAML syntax is valid: `ruby -r yaml -e "YAML.load_file('pr_compliance_checklist.yaml')"`
+3. Commit changes - they take effect immediately on new PRs
+
+### Updating Ignore Rules
+
+To exclude additional files from analysis:
+
+1. Edit the `[ignore]` section in `pr_agent.toml`
+2. Use glob patterns to match file paths
+3. Test with new PRs to verify exclusions work as expected
+
+## Future Improvements (Optional)
+
+- **Centralized Configuration**: Create a `pr-agent-settings` repository with `metadata.yaml` to share configuration across all repos
+- **Wiki Configuration**: Enable repo wiki and create `.pr_agent.toml` page (wiki config takes precedence over local files)

data/docs/reference/api-technical.md

@@ -1167,7 +1167,7 @@ require 'familia'
 
 # Use separate Valkey/Redis database for tests
 Familia.configure do |config|
-  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:6379/15')
+  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:2525/3')
 end
 
 module TestHelpers

data/examples/encrypted_fields.rb

@@ -10,7 +10,7 @@ $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'familia'
 
 # Configure connection
-Familia.uri = 'redis://localhost:6379/15'
+Familia.uri = 'redis://localhost:2525/3'
 
 puts '=== Encrypted Fields Feature Examples ==='
 puts

data/examples/safe_dump.rb

@@ -10,7 +10,7 @@ $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'familia'
 
 # Configure connection
-Familia.uri = 'redis://localhost:6379/15'
+Familia.uri = 'redis://localhost:2525/3'
 
 puts '=== SafeDump Feature Examples ==='
 puts