bug_bunny 4.6.0 → 4.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c9f75619decb8d892d2bfe8c56424822672b6b6b5f3be85442be1399c38e76a
-  data.tar.gz: 7fc1e66a10f46d0a6120dd6164b10b0f1b30d2ff91e8d5daed4358f771f2cc49
+  metadata.gz: b3b2260d4ec9ac9684adce0a4ea1c8ab7d86508a601eba51e630438ba5c36059
+  data.tar.gz: c8a41ed643ba5293babfe946476fce1c022137916dfe534224159574928e8b08
 SHA512:
-  metadata.gz: fd5f4141f5a7892f84d5b3894535632fe63ce24320637a5896530b025c4f3dc8f002f75c41f7cbec57258bca857d58cd1d531c0abf3d6f2047e049cc6119ae98
-  data.tar.gz: c13414d24ee769acb483fe4a9ee1f9aa2073ea6bf8bea81e1ac290499ad45cd85471ffd022a304bb6da9cc56e737f868bc441870a1b084b05a60892c6f3b6366
+  metadata.gz: 6e8ef4dc6d1e9fc6aa4ac067da0aa48ccf5a291c91cb2c8474ed5811e34a57cbbeb44b9b6a813de8d5158a3351a96c15513c1e0715adf5a47e12ef70681935d4
+  data.tar.gz: a036a4e0a8c8b8fc29286f5490be2c506561951167c765461ef668b79c77dfcf0bb8e7f2020df28847820875697008129f24e4a97f34079cb54d5202a6e36d65

data/.claude/commands/pr.md

@@ -0,0 +1,42 @@
+Create a Pull Request for BugBunny via GitHub CLI. Usage: /pr
+
+Creá un PR desde la rama actual hacia `main` usando `gh`.
+
+## Pasos
+
+1. Verificá que hay commits en la rama que no están en main: `git log main..HEAD --oneline`
+2. Revisá todos los cambios del PR: `git diff main...HEAD`
+3. Determiná el tipo de cambio (feature, bugfix, refactor, docs, chore)
+4. Creá el PR con `gh pr create`:
+
+```bash
+gh pr create --title "tipo: descripción breve" --body "$(cat <<'EOF'
+## Summary
+- Bullet points de los cambios principales
+
+## Test plan
+- [ ] Tests existentes pasan (`/test`)
+- [ ] RuboCop sin offenses (`/rubocop`)
+- [ ] YARD documentado en métodos nuevos/modificados
+
+## Notes
+Contexto adicional si es necesario.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+## Convenciones de título
+
+- `feat: descripción` — feature nueva
+- `fix: descripción` — bugfix
+- `chore: descripción` — mantenimiento, deps, config
+- `docs: descripción` — solo documentación
+- `refactor: descripción` — refactor sin cambio de comportamiento
+
+## Importante
+
+- El remote SSH está roto — si el PR requiere push previo, usar HTTPS temporalmente
+- Mostrar la URL del PR creado al usuario
+- No crear el PR sin confirmación del usuario

data/.claude/commands/release.md

@@ -0,0 +1,41 @@
+Release BugBunny gem. Usage: /release [patch|minor|major]
+
+Ejecutá el flujo completo de release para BugBunny. El argumento determina el tipo de bump:
+- `patch` → bugfix (4.6.1 → 4.6.2)
+- `minor` → feature nueva (4.6.1 → 4.7.0)
+- `major` → breaking change (4.6.1 → 5.0.0)
+
+## Pasos
+
+1. **Leer versión actual** de `lib/bug_bunny/version.rb`
+2. **Calcular nueva versión** según el tipo de bump
+3. **Actualizar `lib/bug_bunny/version.rb`** con la nueva versión
+4. **Agregar entrada al tope de `CHANGELOG.md`** con formato:
+   ```
+   ## [X.Y.Z] - YYYY-MM-DD
+   ### ✨ New Features / 🐛 Bug Fixes / 💥 Breaking Changes
+   * Descripción de los cambios
+   ```
+5. **Mostrar el diff completo** al usuario y pedir confirmación antes de continuar
+6. **Commit** con mensaje: `feat|fix|chore: descripción breve vX.Y.Z`
+7. **Merge a main** desde `/Users/gabriel/src/gems/bug_bunny`: `git merge --ff-only <branch>`
+8. **Push via HTTPS**:
+   ```bash
+   git remote set-url origin https://github.com/gedera/bug_bunny.git
+   git push origin main
+   git remote set-url origin git@github.com:gedera/bug_bunny.git
+   ```
+9. **Tag y push**:
+   ```bash
+   git tag vX.Y.Z
+   git remote set-url origin https://github.com/gedera/bug_bunny.git
+   git push origin vX.Y.Z
+   git remote set-url origin git@github.com:gedera/bug_bunny.git
+   ```
+
+## Importante
+
+- Nunca commitear ni pushear sin confirmación explícita del usuario
+- El worktree de main está en `/Users/gabriel/src/gems/bug_bunny`
+- SSH está roto — siempre usar HTTPS para push y restaurar SSH después
+- Sourcear chruby antes de cualquier comando Ruby: `source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8`

data/.claude/commands/rubocop.md

@@ -0,0 +1,22 @@
+Run RuboCop for BugBunny. Usage: /rubocop [--fix]
+
+Ejecutá RuboCop con rubocop-rails-omakase sobre el código modificado.
+
+## Comandos
+
+Sin argumentos — solo reporte:
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rubocop
+```
+
+Con `--fix` — autocorrect seguro:
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rubocop -a
+```
+
+## Reglas importantes
+
+- **Solo corregir código nuevo o modificado en el PR actual** — nunca tocar código existente no relacionado
+- Si hay offenses que requieren intervención manual (no autocorregibles), reportalos con línea y descripción
+- rubocop-rails-omakase tiene opiniones fuertes sobre estilo — seguirlas sin discutir
+- Si hay un offense legítimo que debe ignorarse, usar `# rubocop:disable Cop/Name` en la línea específica con un comentario explicativo

data/.claude/commands/test.md

@@ -0,0 +1,28 @@
+Run RSpec tests for BugBunny. Usage: /test [path]
+
+Ejecutá la suite de tests de BugBunny con Ruby 3.3.8.
+
+## Comando base
+
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rspec
+```
+
+Si se pasa un path como argumento, corré solo ese archivo o directorio:
+
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec rspec $ARGUMENTS
+```
+
+## Después de correr los tests
+
+- Si hay failures: analizá el error, identificá la causa raíz, proponé el fix al usuario antes de tocar código
+- Si hay warnings de deprecación: reportalos al usuario
+- Si todos pasan: confirmá con el conteo de ejemplos y tiempo de ejecución
+
+## Convenciones de RSpec en este proyecto
+
+- Tests en `spec/`
+- Sin mocks de RabbitMQ real — usar doubles de Bunny
+- Describir comportamiento, no implementación
+- Un `context` por escenario, `it` con descripción en español o inglés consistente con el archivo

data/.claude/commands/yard.md

@@ -0,0 +1,46 @@
+Validate and generate YARD documentation for BugBunny. Usage: /yard
+
+Verificá y generá la documentación YARD de la gema.
+
+## Comandos
+
+Generar docs:
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec yard doc
+```
+
+Ver métodos sin documentar:
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8 && bundle exec yard stats --list-undoc
+```
+
+## Estándar YARD de este proyecto
+
+Todo método público nuevo o modificado debe tener:
+
+```ruby
+# Descripción breve en una línea.
+#
+# Descripción extendida opcional si la firma no es autoexplicativa.
+#
+# @param nombre [Tipo] Descripción del parámetro
+# @return [Tipo] Descripción del valor de retorno
+# @raise [ClaseError] Condición bajo la cual se lanza
+# @example
+#   resultado = mi_metodo(arg)
+def mi_metodo(nombre)
+```
+
+## Tipos comunes en este proyecto
+
+- `[String]`, `[Integer]`, `[Boolean]`, `[Hash]`, `[Array]`, `[Symbol]`
+- `[Bunny::Session]`, `[Bunny::Channel]`, `[Bunny::MessageProperties]`
+- `[BugBunny::Session]`, `[BugBunny::Request]`, `[BugBunny::Configuration]`
+- `[Proc, nil]` para callbacks opcionales
+- `[void]` para métodos sin return value relevante
+
+## Después de correr
+
+- Reportá los métodos públicos sin documentar
+- No documentar métodos privados (YARD los ignora por defecto con `private`)
+- No documentar métodos triviales (`attr_reader`, `attr_accessor`) salvo que necesiten contexto

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [4.7.0] - 2026-04-01
+
+### ✨ New Features
+* **Routing — Namespace blocks:** Nuevo método `namespace` en el DSL de rutas para organizar controladores en módulos Ruby. Los namespaces son acumulativos y anidables: `namespace :api { namespace :v1 { resources :metrics } }` resuelve a `Api::V1::MetricsController`. El namespace de la ruta tiene precedencia sobre `config.controller_namespace`.
+* **Controller — `after_action`:** Nuevo callback que se ejecuta después de la acción exitosa. No se invoca si un `before_action` haltó la cadena ni si la acción lanzó una excepción, siguiendo el comportamiento de Rails. Soporta `only:` y `except:`, y se hereda entre controladores.
+* **Controller — `render` con `headers:`:** El método `render` acepta un keyword `headers:` para adjuntar headers por-respuesta sin mutar `response_headers`. `response_headers` se inicializa con `with_indifferent_access`.
+* **Consumer — `shutdown`:** Nuevo método público que detiene el health check timer y cierra el canal AMQP de forma ordenada. Se invoca automáticamente vía `ensure` cuando `subscribe` termina por cualquier motivo (señal, error, fin de loop), garantizando limpieza completa de recursos.
+* **Configuration — `validate!`:** `BugBunny.configure` invoca `validate!` al final del bloque. Verifica presencia de campos requeridos (`host`, `port`, `username`, `password`, `vhost`) y rangos válidos para timeouts y `channel_prefetch`. Lanza `BugBunny::ConfigurationError` con mensaje descriptivo en lugar de fallar silenciosamente al conectar.
+
+### ⚡ Performance & Robustness
+* **Client — Session & Producer pooling:** `BugBunny::Client` ya no crea ni destruye un `Session` (canal AMQP) y un `Producer` por request. Ambos se cachean como ivars sobre el objeto conexión del pool (`@_bug_bunny_session`, `@_bug_bunny_producer`) y se reutilizan en todos los requests del mismo slot. El cacheo del `Producer` es crítico: el Producer registra un `basic_consume` en el canal para escuchar replies RPC; recrearlo sobre un canal reutilizado intentaría un segundo `basic_consume` causando un error AMQP. Thread-safe sin mutex adicional: `ConnectionPool` garantiza que cada slot es usado por un único thread a la vez.
+* **Session — Double-checked locking:** El método `channel` usa un patrón de double-checked locking con `@channel_mutex` para evitar que múltiples threads creen canales simultáneamente cuando el canal cae. `close` también está protegido por el mismo mutex.
+* **ConsumerMiddleware::Stack — Thread safety:** `use`, `empty?` y `call` están protegidos por un `Mutex`. `call` toma un snapshot del array bajo mutex y ejecuta la cadena fuera del lock, evitando serializar el procesamiento de mensajes durante registros concurrentes.
+
+### 🔍 Observability
+* **`Observability::SENSITIVE_KEYS` expandido:** La lista de claves filtradas en logs crece de 5 a 11 entradas: se agregan `authorization`, `credential`, `private_key`, `csrf`, `session_id` y `passwd`. El matching pasa de comparación exacta por symbol a substring matching en lowercase con normalización de hyphens a underscores, cubriendo variantes como `X-Api-Key`, `user_password` o `accessToken`.
+* **`Observability.sensitive_key?` público:** El método de detección de claves sensibles se expone como método de módulo reutilizable por componentes externos (middlewares, integraciones).
+
+### 🐛 Bug Fixes
+* **Resource — dirty tracking híbrido:** Se corrigen los overrides `changed?` y `changed` para combinar correctamente el tracking nativo de `ActiveModel::Dirty` (atributos tipados) con el tracking manual de atributos dinámicos (`@dynamic_changes`). Anteriormente, `changed?` solo reflejaba atributos tipados. `id=` ahora registra el cambio en `@dynamic_changes` cuando `id` no está declarado como `attribute`.
+* **Resource — inicialización:** `initialize` pasa `attributes` directamente a `super` en lugar del patrón `super() + assign_attributes`, delegando correctamente a `ActiveModel::Model`.
+
+## [4.6.1] - 2026-03-31
+
+### 🐛 Bug Fixes
+* **Observability:** `safe_log` ahora serializa valores `Hash` siempre como JSON compacto (`val.to_json`), sin pasar por `.inspect`. Anteriormente, si el JSON del Hash contenía espacios, se llamaba `.inspect` produciendo strings escapados como `"{\"exclusive\":false}"` en lugar del objeto JSON esperado `{"exclusive":false}`. Afectaba a los eventos `consumer.start` (campo `queue_opts`) y `consumer.bound` (campo `exchange_opts`).
+
 ## [4.6.0] - 2026-03-31
 
 ### ✨ New Features
@@ -73,33 +100,33 @@
 
 ## [4.2.0] - 2026-03-22
 
-### 🔠 Observability & Structured Logging
-* **Structured Logs (Key-Value):** Se migraron todos los logs del framework a un formato \`key=value\` estructurado, ideal para herramientas de monitoreo como Datadog o CloudWatch. Se eliminaron emojis y texto libre para mejorar el parseo automático.
-* **Lazy Evaluation (Debug Blocks):** Las llamadas a \`logger.debug\` ahora utilizan bloques para evitar la interpolación de strings innecesaria en producción, optimizando el uso de CPU y memoria.
+### Observability & Structured Logging
+* **Structured Logs (Key-Value):** Se migraron todos los logs del framework a un formato `key=value` estructurado, ideal para herramientas de monitoreo como Datadog o CloudWatch. Se eliminaron emojis y texto libre para mejorar el parseo automático.
+* **Lazy Evaluation (Debug Blocks):** Las llamadas a `logger.debug` ahora utilizan bloques para evitar la interpolación de strings innecesaria en producción, optimizando el uso de CPU y memoria.
 
-### ðŸ›¡ï¸  Resilience & Connectivity
-* **Exponential Backoff:** El \`Consumer\` ahora implementa un algoritmo de reintento exponencial para reconectarse a RabbitMQ, evitando picos de carga durante caídas del broker.
-* **Max Reconnect Attempts:** Nueva configuración \`max_reconnect_attempts\` que permite que el worker falle definitivamente tras N intentos, facilitando el reinicio del Pod por parte de orquestadores como Kubernetes.
-* **Performance Tuning:** Se desactivaron los \`publisher_confirms\` en el canal del \`Consumer\` al responder RPCs para reducir la latencia de respuesta (round-trips innecesarios).
+### Resilience & Connectivity
+* **Exponential Backoff:** El `Consumer` ahora implementa un algoritmo de reintento exponencial para reconectarse a RabbitMQ, evitando picos de carga durante caídas del broker.
+* **Max Reconnect Attempts:** Nueva configuración `max_reconnect_attempts` que permite que el worker falle definitivamente tras N intentos, facilitando el reinicio del Pod por parte de orquestadores como Kubernetes.
+* **Performance Tuning:** Se desactivaron los `publisher_confirms` en el canal del `Consumer` al responder RPCs para reducir la latencia de respuesta (round-trips innecesarios).
 
 ## [4.1.2] - 2026-03-22
 
-### ✨ Improvements
-* **Controller:** Ahora lanza una excepción \`BugBunny::BadRequest\` (400) si el cuerpo de la petición contiene un JSON inválido, mejorando la depuración en el cliente.
-* **Resource:** Se añadió una protección a \`.with\` (\`ScopeProxy\`) para asegurar que el contexto sea de un solo uso, evitando efectos secundarios en llamadas encadenadas.
+### Improvements
+* **Controller:** Ahora lanza una excepción `BugBunny::BadRequest` (400) si el cuerpo de la petición contiene un JSON inválido, mejorando la depuración en el cliente.
+* **Resource:** Se añadió una protección a `.with` (`ScopeProxy`) para asegurar que el contexto sea de un solo uso, evitando efectos secundarios en llamadas encadenadas.
 
 ## [4.1.1] - 2026-03-22
 
 ### 🐛 Bug Fixes
-* **Consumer:** Previene memory leak al detener el `TimerTask` de health check previo antes de realizar una reconexión.
-* **Controller:** Corrige la mutación accidental de \`log_tags\` globales al usar una lógica de herencia no destructiva en \`compute_tags\`.
+* **Consumer:** Previene memory leak al detener el `TimerTask` de health check previo antes de realizar una reconexión.
+* **Controller:** Corrige la mutación accidental de `log_tags` globales al usar una lógica de herencia no destructiva en `compute_tags`.
 
 ## [4.1.0] - 2026-03-22
 
 ### 🚀 New Features & Improvements
-* **Faraday-style Client API:** Se introdujo el método \`Client#send\` como punto de entrada genérico, permitiendo una sintaxis más familiar y flexible.
-* **Flexible Delivery Modes:** Introducción del atributo \`delivery_mode\` (:rpc o :publish). Ahora es posible configurar la estrategia de envío a nivel de cliente o por cada petición individual.
-* **Smart Request Defaults:** Los métodos \`request\` y \`publish\` ahora delegan internamente en \`send\`, manteniendo la compatibilidad pero beneficiándose de la nueva arquitectura de peticiones.
+* **Faraday-style Client API:** Se introdujo el método `Client#send` como punto de entrada genérico, permitiendo una sintaxis más familiar y flexible.
+* **Flexible Delivery Modes:** Introducción del atributo `delivery_mode` (:rpc o :publish). Ahora es posible configurar la estrategia de envío a nivel de cliente o por cada petición individual.
+* **Smart Request Defaults:** Los métodos `request` y `publish` ahora delegan internamente en `send`, manteniendo la compatibilidad pero beneficiándose de la nueva arquitectura de peticiones.
 
 ## [4.0.1] - 2026-03-13
 

data/CLAUDE.md

@@ -0,0 +1,228 @@
+# BugBunny — Project Intelligence
+
+## ¿Qué es BugBunny?
+
+BugBunny es una gema Ruby que implementa una capa de enrutamiento RESTful sobre AMQP (RabbitMQ). Permite que microservicios se comuniquen via RabbitMQ usando patrones familiares de HTTP: verbos (GET, POST, PUT, DELETE), controladores, rutas declarativas, RPC síncrono y fire-and-forget.
+
+**Problema que resuelve:** Eliminar el acoplamiento directo entre microservicios via HTTP, usando RabbitMQ como bus de mensajes con la misma ergonomía de un framework web.
+
+## Arquitectura
+
+```
+Publisher (Client/Resource)
+  └─ Producer → Session → Bunny → RabbitMQ Exchange
+                                        │
+                                   RabbitMQ Queue
+                                        │
+Consumer (subscribe loop)
+  └─ ConsumerMiddleware::Stack
+       └─ process_message
+            └─ Router → Controller → Action
+                              └─ reply (RPC)
+```
+
+### Componentes clave
+
+| Clase | Responsabilidad |
+|---|---|
+| `BugBunny::Session` | Wrapper de canal Bunny. Declara exchanges y queues. |
+| `BugBunny::Consumer` | Subscribe loop. Rutea mensajes a controladores via `BugBunny.routes`. |
+| `BugBunny::ConsumerMiddleware::Stack` | Pipeline de middlewares antes de `process_message`. |
+| `BugBunny::Producer` | Publica mensajes. Implementa RPC con `Concurrent::IVar`. |
+| `BugBunny::Client` | API de alto nivel para el publicador. Pool de conexiones. |
+| `BugBunny::Controller` | Base class tipo Rails. `around_action`, `before_action`, `render`. |
+| `BugBunny::Resource` | ActiveRecord-like sobre AMQP. `find`, `where`, `create`, etc. |
+| `BugBunny::Request` | Value object del mensaje saliente (path, method, params, headers). |
+| `BugBunny::Observability` | Mixin de logging estructurado. `safe_log`, `exception_metadata`. |
+| `BugBunny::Configuration` | Configuración global. Logger, timeouts, middleware hooks. |
+
+### Flujo RPC completo
+
+1. `Resource.find(id)` → `Client#request` → `Producer#rpc`
+2. Producer publica en exchange con `reply_to: 'amq.rabbitmq.reply-to'`
+3. `Concurrent::IVar` bloquea el thread principal (`future.value(timeout)`)
+4. Consumer recibe → middleware stack → controller → `reply(response)`
+5. Reply listener thread setea `future.set({ body:, headers: })`
+6. Thread principal: `on_rpc_reply&.call(headers)` → `parse_response(body)`
+
+## Hooks de extensión
+
+```ruby
+# Middleware antes de process_message (ej: tracing, auth)
+BugBunny.consumer_middlewares.use MyMiddleware
+
+# Headers a inyectar en el reply RPC (ej: trace context actualizado)
+config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => Tracer.header } }
+
+# Callback en el thread principal al recibir el reply (ej: hidratar tracer)
+config.on_rpc_reply = ->(headers) { Tracer.hydrate(headers['X-Amzn-Trace-Id']) }
+```
+
+---
+
+## Dominio y Expertise
+
+Al trabajar en esta gema aplicá expertise en:
+
+- **Ruby idiomático**: módulos, mixins, metaprogramación, `class_attribute`, `Concurrent::*`
+- **RabbitMQ / AMQP**: exchanges (direct/topic/fanout), queues, bindings, `reply_to`, `correlation_id`, `properties.headers`, publisher confirms, manual ack
+- **Bunny**: la gema Ruby que wrappea AMQP. `channel`, `basic_consume`, `basic_publish`, `IVar`
+- **Rails patterns**: `ActiveModel`, `ActiveSupport`, `class_attribute`, `concerns`, `constantize`
+- **Rack**: `Rack::Utils.parse_nested_query`, `build_nested_query`
+
+---
+
+## Observability — Estándar de Logging
+
+Esta gema implementa su propio patrón de observability via `BugBunny::Observability`.
+
+### Reglas fundamentales
+
+- **Formato**: `component=x event=clase.evento [key=value ...]` — todo en una línea
+- **Nunca** llamar al logger directamente. Siempre usar `safe_log`
+- **Nunca** `Kernel#warn`, `$stderr`, `puts`
+- **Niveles**: `ERROR`=excepción, `WARN`=inesperado+continuó, `INFO`=normal, `DEBUG`=detalle
+- `DEBUG` siempre en bloque: `logger.debug { "k=#{v}" }` — `safe_log` lo maneja internamente
+- Duraciones: `Process.clock_gettime(Process::CLOCK_MONOTONIC)`, nunca `Time.now`
+- Logger failures **nunca** interrumpen el flujo — `safe_log` tiene `rescue StandardError`
+
+### Uso en clases nuevas
+
+```ruby
+class BugBunny::MiClase
+  include BugBunny::Observability
+
+  def initialize
+    @logger = BugBunny.configuration.logger
+  end
+
+  def mi_metodo
+    start = monotonic_now
+    # ...
+    safe_log(:info, "mi_clase.mi_evento", campo: valor, duration_s: duration_s(start))
+  rescue StandardError => e
+    safe_log(:error, "mi_clase.error", **exception_metadata(e))
+  end
+end
+```
+
+### Naming de eventos
+
+Formato estricto: `"clase.evento"` (string, nunca symbol)
+
+| Evento | Nivel | Cuándo |
+|---|---|---|
+| `consumer.start` | INFO | Consumer inicia subscribe |
+| `consumer.bound` | INFO | Queue bindeada al exchange |
+| `consumer.message_received` | INFO | Mensaje recibido, antes del routing |
+| `consumer.route_matched` | DEBUG | Ruta encontrada |
+| `consumer.message_processed` | INFO | Procesamiento exitoso con duración |
+| `consumer.execution_error` | ERROR | Excepción en el procesamiento |
+| `producer.publish` | INFO | Mensaje publicado |
+| `producer.rpc_waiting` | DEBUG | Bloqueando esperando respuesta |
+| `producer.rpc_response_received` | DEBUG | Reply recibido (thread principal) |
+
+### Campos estándar
+
+```ruby
+safe_log(:error, "clase.error", **exception_metadata(e))
+# => error_class: "RuntimeError", error_message: "..."
+
+safe_log(:info, "clase.evento", duration_s: duration_s(start_time))
+# => duration_s: 0.001234
+
+# Valores sensibles se filtran automáticamente:
+# password, token, secret, api_key, auth → [FILTERED]
+```
+
+---
+
+## Standards de Código
+
+### RuboCop
+
+Esta gema usa **rubocop-rails-omakase**. Todo código nuevo o modificado debe cumplir.
+
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
+bundle exec rubocop
+bundle exec rubocop -a   # autocorrect
+```
+
+**No corregir código existente no tocado.** Solo el código nuevo o modificado en el PR.
+
+### YARD
+
+Todo método público nuevo o modificado lleva documentación YARD:
+
+```ruby
+# Descripción breve.
+#
+# Descripción extendida si es necesario.
+#
+# @param name [Type] Descripción
+# @return [Type] Descripción
+# @raise [ErrorClass] Cuándo se lanza
+# @example
+#   resultado = mi_metodo(arg)
+def mi_metodo(name)
+```
+
+```bash
+bundle exec yard doc
+bundle exec yard stats --list-undoc
+```
+
+### RSpec
+
+Tests en `spec/`. Sin mocks de dependencias externas reales (RabbitMQ se mockea con doubles de Bunny).
+
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
+bundle exec rspec
+bundle exec rspec spec/bug_bunny/consumer_spec.rb   # archivo específico
+```
+
+---
+
+## Entorno de Desarrollo
+
+### Ruby
+
+```bash
+source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
+```
+
+Nunca usar `bundle exec ruby` con el Ruby del sistema (2.6). Siempre sourcear chruby primero.
+
+### Worktrees
+
+- **Main**: `/Users/gabriel/src/gems/bug_bunny` (rama `main`)
+- **Work**: `/Users/gabriel/src/gems/worktrees/current-5n3` (ramas de feature)
+- `main` está checkeado en otro worktree — no se puede hacer `git checkout main` desde el worktree de trabajo
+
+### Push a remoto
+
+SSH está roto en este entorno. Para push siempre:
+
+```bash
+git remote set-url origin https://github.com/gedera/bug_bunny.git
+git push origin main
+git remote set-url origin git@github.com:gedera/bug_bunny.git   # restaurar
+```
+
+---
+
+## Release Workflow
+
+Usá el comando `/release` para el flujo completo. Manualmente:
+
+1. Determinar tipo: `patch`=bugfix, `minor`=feature nueva, `major`=breaking change
+2. Actualizar `lib/bug_bunny/version.rb`
+3. Agregar entrada al tope de `CHANGELOG.md`
+4. Commit con mensaje convencional
+5. Desde `/Users/gabriel/src/gems/bug_bunny`: `git merge --ff-only <branch>`
+6. Push via HTTPS + restaurar SSH
+7. `git tag vX.Y.Z && git push origin vX.Y.Z`
+
+**Nunca commitear ni pushear sin permiso explícito del usuario.**