rubino-agent 0.3.0

data/rubino-agent.gemspec

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "lib/rubino/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rubino-agent"
+  spec.version = Rubino::VERSION
+  spec.authors = ["Jhon Rojas"]
+  spec.email = ["jhon@example.com"]
+
+  spec.summary = "A lightweight Ruby coding and automation agent with persistent memory, sessions, and context compaction"
+  spec.description = "A standalone, self-contained coding and automation agent built on ruby_llm. " \
+                     "Provides an agent loop, persistent memory, SQLite sessions, context compaction, " \
+                     "a job system, a tool registry, and an extensible UI layer."
+  spec.homepage = "https://github.com/Jhonnyr97/rubino-agent"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    # Use git if available, otherwise glob
+    if system("git rev-parse --git-dir > /dev/null 2>&1")
+      `git ls-files -z`.split("\x0").reject do |f|
+        (File.expand_path(f) == __FILE__) ||
+          f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+      end
+    else
+      Dir.glob("{lib,exe}/**/*").reject { |f| File.directory?(f) } +
+        %w[Gemfile Rakefile README.md CHANGELOG.md]
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = ["rubino"]
+  spec.require_paths = ["lib"]
+
+  # Core dependencies
+  spec.add_dependency "dry-configurable", "~> 1.0"
+  spec.add_dependency "dry-schema", "~> 1.13"
+  spec.add_dependency "faraday", "~> 2.9"
+  spec.add_dependency "faraday-retry", "~> 2.2"
+  spec.add_dependency "oauth2", "~> 2.0"
+  spec.add_dependency "puma", "~> 6.4"
+  spec.add_dependency "rack", "~> 3.1"
+  spec.add_dependency "ruby_llm", "~> 1.0"
+  spec.add_dependency "ruby_llm-mcp", "~> 1.0"
+  spec.add_dependency "rufus-scheduler", "~> 3.9"
+  spec.add_dependency "sequel", "~> 5.0"
+  spec.add_dependency "sqlite3", "~> 2.0"
+  spec.add_dependency "thor", "~> 1.3"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+
+  # CLI UI dependencies
+  spec.add_dependency "kramdown", "~> 2.5"
+  spec.add_dependency "kramdown-parser-gfm", "~> 1.1"
+  spec.add_dependency "pastel", "~> 0.8"
+  spec.add_dependency "tty-box", "~> 0.7"
+  spec.add_dependency "tty-prompt", "~> 0.23"
+  spec.add_dependency "tty-spinner", "~> 0.9"
+  spec.add_dependency "tty-table", "~> 0.12"
+  spec.add_dependency "unicode-display_width", "~> 2.6"
+
+  # Reline used to ship with Ruby, but it was removed from default gems
+  # in Ruby 4.0 and is now a regular gem. UI::LineInput depends on it for
+  # the interactive prompt (history, completion, multi-line editing).
+  spec.add_dependency "reline", "~> 0.5"
+
+  # `csv` left the default gems in Ruby 3.4. The in-repo document converter
+  # (Rubino::Documents) uses it for the CORE csv->Markdown format, so it is a
+  # hard runtime dependency (the converter still falls back to a built-in
+  # splitter if it is ever absent, but we ship it so csv always works).
+  spec.add_dependency "csv", "~> 3.2"
+
+  # Optional document-conversion extraction gems (Rubino::Documents, #6). These
+  # are NOT hard runtime dependencies: each converter `require`s its gem lazily
+  # inside begin/rescue LoadError and reports itself unavailable when the gem is
+  # absent, so the module loads and runs with none of them installed (callers
+  # then fall back to the shell-extraction hint). They are declared as
+  # development dependencies so CI/specs can exercise the gem-backed converters;
+  # an end user installs only the formats they need (e.g. `gem install roo`).
+  # All MIT-licensed. html/xml use kramdown/rexml which are already present.
+  #
+  # NOTE: `ruby_powerpoint` is deliberately NOT in the dev bundle -- it pins
+  # `rubyzip ~> 1.0`, which is irreconcilable with `docx`/`roo` (rubyzip ~> 2.x)
+  # in a single Gemfile. The Pptx converter is therefore exercised by its
+  # degradation path and unit-level shaping (a stubbed gem interface) rather
+  # than the live gem; an end user who needs pptx installs ruby_powerpoint into
+  # their own (compatible) environment. This is exactly the optional-require
+  # design: a missing/absent gem never breaks the module.
+  spec.add_development_dependency "docx", "~> 0.8"
+  spec.add_development_dependency "pdf-reader", "~> 2.12"
+  spec.add_development_dependency "roo", "~> 2.10"
+
+  # Development dependencies
+  spec.add_development_dependency "rack-test", "~> 2.1"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.60"
+  spec.add_development_dependency "rubocop-rspec", "~> 3.0"
+end

data/skills/ruby-expert/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ruby-expert
+description: Deep Ruby & Rails expertise — idioms, OO design, metaprogramming, errors/types, concurrency, Rails, testing, performance, security, tooling, gem authoring. Load when writing, reviewing, debugging, or designing Ruby or Rails code, or when a Ruby/Rails decision needs an authoritative answer.
+---
+
+# Ruby expert
+
+Authoritative, current (Ruby 3.2–3.4, Rails 7.1–8.x) knowledge for writing,
+reviewing, and designing idiomatic Ruby. This file is the router: it carries the
+non-negotiable defaults, then points you at one bundled reference for deep,
+task-specific guidance. **Load the matching reference before answering a
+non-trivial question in that area** — don't work from memory when a reference
+covers it.
+
+## Non-negotiable defaults
+
+Apply these unless the surrounding project clearly does otherwise (existing
+project conventions always win over these defaults):
+
+- **Match the codebase first.** Read neighbouring files and mirror their naming,
+  structure, and idioms before introducing your own. Consistency beats personal
+  preference.
+- **`# frozen_string_literal: true`** as the first line of every Ruby source file.
+- **Naming:** `snake_case` for methods/variables, `CamelCase` for classes/modules,
+  `SCREAMING_SNAKE_CASE` for constants, `?` suffix for predicates, `!` suffix only
+  for the dangerous/mutating variant that has a safe sibling.
+- **Keyword arguments** for anything with more than one or two parameters, or any
+  boolean/optional flag — never a positional boolean.
+- **`rescue StandardError`**, never a bare `rescue` or `rescue Exception`. Never
+  rescue just to swallow — handle, re-raise, or don't rescue.
+- **Two-space indentation, no tabs.** Guard clauses over deep nesting. Prefer the
+  smallest method that reads clearly.
+- **Tests are part of "done."** New behavior ships with a spec; a bug fix ships
+  with the regression test that would have caught it.
+- **Run the linter.** Honor the project's `.rubocop.yml` / `standard`; don't fight
+  it or disable cops without a reason in a comment.
+- **Security is not optional.** Never interpolate untrusted input into SQL, shell,
+  `eval`, `send`, or deserialization. See `references/security.md`.
+
+## Which reference to load
+
+| Load `references/…` | When the task involves |
+| --- | --- |
+| `language-idioms.md` | Day-to-day Ruby: collections/Enumerable, pattern matching, blocks/procs/lambdas, keyword args, `Data`/`Struct`, hash idioms, nil handling, numbers/money |
+| `datetime-and-encoding.md` | Dates/times/time zones (the `Time.now` vs `Time.zone.now` footgun, DST, parsing, monotonic clock) and string encoding (UTF-8, `force_encoding` vs `encode`, scrubbing bad bytes) |
+| `metaprogramming.md` | `define_method`, `method_missing`, `send`, hooks, `class_eval`, refinements, building DSLs, introspection |
+| `oo-design.md` | Class/module design, SOLID, composition vs inheritance, service/value/query/policy objects, Result objects, dependency injection, refactoring a god object |
+| `errors-and-types.md` | Exception design, `rescue`/`retry`/`ensure`, custom errors, cause chaining, and RBS/Sorbet type checking |
+| `concurrency.md` | Threads, mutexes/queues, the GVL, fibers, the `async` gem, Ractors, processes/fork — choosing a concurrency model |
+| `rails.md` | Anything Rails: Active Record, migrations, controllers, routing, concerns, jobs, Hotwire, caching, Rails secure defaults |
+| `testing.md` | RSpec or Minitest, FactoryBot, TDD, doubles/mocks, WebMock/VCR, request vs system specs, fixing flaky tests |
+| `performance.md` | Profiling, memory/allocations, GC, YJIT, fixing a slow path or high-memory process |
+| `security.md` | Injection (SQL/command/eval), mass assignment, deserialization, XSS/CSRF, authz/IDOR, secrets, Brakeman, dependency audit, ReDoS |
+| `tooling.md` | Bundler, version managers (rbenv/asdf/mise/rv), the `debug` gem/pry, RuboCop/standard, Rake, CI, LSP |
+| `gem-authoring.md` | Building or releasing a gem: gemspec, Zeitwerk, versioning/CHANGELOG, `rake release`, shipping assets |
+
+When a task spans areas (e.g. "make this Rails query fast and safe"), load each
+relevant reference. Each reference ends with a `## Quick checklist` you can scan
+for the rules without re-reading the whole file.
+
+## How to apply
+
+1. Identify the area(s) the task touches and load the matching reference(s) above.
+2. Inspect the actual project (Gemfile, `.rubocop.yml`, existing code) — its
+   conventions override the generic defaults here.
+3. Write the change, then verify it: run the tests and the linter before calling
+   it done.

data/skills/ruby-expert/references/concurrency.md

@@ -0,0 +1,357 @@
+# Concurrency & parallelism
+
+How to pick and use a concurrency model in modern Ruby (MRI/CRuby 3.2–3.4). The single most important fact: **MRI has a Global VM Lock (GVL), so threads give you concurrency for IO-bound work but NOT parallelism for CPU-bound work.** Choose the model from the workload, not from habit.
+
+## The GVL/GIL — what it does and does not do
+
+The GVL (historically "GIL") ensures only **one thread executes Ruby bytecode at a time** in a single MRI process.
+
+- It **does** prevent true parallel execution of pure-Ruby CPU work. Two threads spinning on math run no faster than one.
+- It is **released** during blocking IO (sockets, file reads, `sleep`, many DB driver calls) and during some C-extension sections. So while one thread waits on the network, another runs Ruby. This is why threads help IO-bound workloads.
+- It does **NOT** make your code thread-safe. The GVL can switch threads between bytecode instructions, so `count += 1` (read, add, write) can interleave and lose updates. You still need locks. See "Thread-safety hazards" below.
+
+```ruby
+# CPU-bound: threads do NOT help on MRI (GVL serializes the work)
+threads = 4.times.map { Thread.new { fib(35) } }  # ~same wall time as serial
+threads.each(&:join)
+
+# IO-bound: threads DO help (GVL released during the HTTP wait)
+urls.map { |u| Thread.new { Net::HTTP.get(URI(u)) } }.each(&:join)
+```
+
+JRuby and TruffleRuby have **no GVL** — threads run truly parallel there, so CPU-bound threading works on those runtimes.
+
+## Thread basics
+
+```ruby
+t = Thread.new(arg) do |x|   # pass args explicitly; do NOT close over a loop var
+  do_work(x)
+end
+result = t.value             # join + return the block's value (re-raises if it failed)
+t.join                       # wait without caring about return value
+t.join(5)                    # returns nil on timeout, else the thread
+```
+
+DO pass loop variables as block args; DON'T capture them by closure:
+
+```ruby
+# WRONG: all threads may see the final value of `i`
+(0..9).each { |i| Thread.new { puts i } }
+
+# RIGHT: bind per-thread via block argument
+(0..9).each { |i| Thread.new(i) { |n| puts n } }
+```
+
+**Thread-local / fiber-local storage.** `Thread#[]` is actually *fiber*-local (scoped to the current fiber). Use `Thread#thread_variable_get/set` for true per-thread state.
+
+```ruby
+Thread.current[:tag] = "fiber-local"          # fiber-scoped (surprising name)
+Thread.current.thread_variable_set(:id, 7)    # genuinely thread-scoped
+```
+
+### Exceptions in threads
+
+An unhandled exception in a thread is stored and **re-raised when you call `join`/`value`**. If you never join, the exception is silently swallowed.
+
+```ruby
+t = Thread.new { raise "boom" }
+sleep 0.1            # main thread keeps running; nothing printed yet
+t.join               # NOW it raises "boom"
+```
+
+DON'T flip `Thread.abort_on_exception = true` globally in libraries (it crashes the whole process on any thread error). For dev visibility prefer `Thread.report_on_exception = true` (default since 2.5) which logs but doesn't abort. Better: always `join` or wrap work in `begin/rescue` and push errors to a `Queue`.
+
+## Synchronization primitives
+
+### Mutex
+
+```ruby
+mutex = Mutex.new
+mutex.synchronize { @balance += amount }   # critical section
+```
+
+DON'T re-lock the same `Mutex` from the same thread (e.g. recursive call) — it raises `ThreadError` (deadlock). Use `Monitor` for reentrancy.
+
+### Monitor (reentrant mutex + condition vars)
+
+```ruby
+require "monitor"
+class Counter
+  include MonitorMixin               # adds #synchronize to instances
+  def initialize = (super; @n = 0)
+  def incr = synchronize { @n += 1 } # reentrant: safe to call other synchronized methods
+end
+```
+
+### ConditionVariable — wait/signal
+
+Use when a thread must wait for a condition another thread sets. Always re-check the predicate in a loop (guard against spurious wakeups).
+
+```ruby
+mutex, cond = Mutex.new, ConditionVariable.new
+ready = false
+
+# consumer
+mutex.synchronize { cond.wait(mutex) until ready; consume }
+# producer
+mutex.synchronize { ready = true; cond.signal }   # or broadcast for all waiters
+```
+
+### Queue / SizedQueue — the preferred producer-consumer tool
+
+`Thread::Queue` is thread-safe and blocking out of the box. Prefer it over hand-rolled Mutex+ConditionVariable.
+
+```ruby
+q = Thread::Queue.new            # unbounded
+sq = Thread::SizedQueue.new(100) # bounded -> applies backpressure on push
+
+# producers
+producers = files.map { |f| Thread.new { sq.push(parse(f)) } }
+
+# consumers
+workers = 4.times.map do
+  Thread.new do
+    while (item = sq.pop)        # pop blocks until an item is available
+      handle(item)
+    end
+  end
+end
+
+producers.each(&:join)
+workers.size.times { sq.push(nil) }  # poison pills to stop consumers
+workers.each(&:join)
+# Alt: sq.close then `while (i = sq.pop); ...` exits when closed+drained
+```
+
+`SizedQueue` is the idiomatic way to bound memory and rate: `push` blocks when full.
+
+## concurrent-ruby (`Concurrent::*`)
+
+Battle-tested toolkit. Reach for it instead of building pools/atomics yourself.
+
+```ruby
+require "concurrent-ruby"
+
+# Bounded thread pool (don't spawn unbounded threads)
+pool = Concurrent::FixedThreadPool.new(8)
+pool.post { do_io }
+pool.shutdown; pool.wait_for_termination
+
+# Futures (run now, collect later)
+futures = urls.map { |u| Concurrent::Future.execute { Net::HTTP.get(URI(u)) } }
+results = futures.map(&:value)         # blocks; check #rejected? / #reason for errors
+
+# Thread-safe map (use instead of a plain Hash shared across threads)
+cache = Concurrent::Map.new
+cache.compute_if_absent(key) { expensive(key) }   # atomic memoization
+
+# Atomic counter (no Mutex needed)
+counter = Concurrent::AtomicFixnum.new(0)
+counter.increment
+```
+
+Other useful types: `Concurrent::Array`/`Concurrent::Hash` (thread-safe wrappers), `Concurrent::Promises` (composable futures), `Concurrent::TimerTask`, `Concurrent::ThreadLocalVar`.
+
+DON'T use raw `Concurrent::Future`/`Promise` without checking for rejection — a failed future returns `nil` from `value` and hides the error in `#reason`.
+
+## Thread-safety hazards & patterns
+
+### Shared mutable state
+
+Any object mutated by multiple threads needs a lock or a thread-safe type. Plain `Hash`, `Array`, and `+=` are NOT atomic.
+
+```ruby
+# WRONG: lost updates under contention
+@total += n
+@list << item
+@hash[k] = v
+
+# RIGHT: guard with a mutex, or use Concurrent::* types
+@mutex.synchronize { @total += n }
+```
+
+### Check-then-act races
+
+`if !exists then create` is two operations; another thread can act in between.
+
+```ruby
+# WRONG (TOCTOU)
+@conn = connect unless @conn
+
+# RIGHT: atomic compute-if-absent, or lock the whole check+act
+@mutex.synchronize { @conn ||= connect }
+```
+
+### Memoization races
+
+`@x ||= compute` is fine for **idempotent, side-effect-free** values where a rare double-compute is harmless. It is NOT safe when `compute` has side effects or must run exactly once.
+
+```ruby
+# Risky if compute is expensive/side-effectful: two threads may both run it
+def config = @config ||= load_config
+
+# Safe: compute exactly once
+def config
+  @mutex.synchronize { @config ||= load_config }
+end
+```
+
+Pattern: **make objects immutable and share those**. Build state on one thread, `freeze` it, hand the frozen object to others. Frozen + no shared mutation = no locks needed.
+
+## Fibers & the Fiber scheduler
+
+Fibers are cooperative, lightweight units of execution (no OS thread per fiber). You can have hundreds of thousands. They yield control explicitly.
+
+```ruby
+f = Fiber.new { puts "a"; Fiber.yield; puts "b" }
+f.resume   # => "a"
+f.resume   # => "b"
+```
+
+Since Ruby 3.0 a **Fiber scheduler** can make blocking IO automatically yield, so thousands of fibers multiplex over a few threads with normal-looking blocking code. You rarely implement the scheduler yourself — use the `async` gem.
+
+```ruby
+Fiber.set_scheduler(MyScheduler.new)   # what `Async{}` does for you
+```
+
+## The `async` gem — high-concurrency IO
+
+Idiomatic high-level fiber concurrency. Code reads sequentially but runs concurrently; IO automatically suspends the fiber.
+
+```ruby
+require "async"
+require "async/http/internet"
+
+Async do |task|
+  internet = Async::HTTP::Internet.new
+  results = urls.map do |u|
+    task.async { internet.get(u).read }   # each runs concurrently
+  end.map(&:wait)
+ensure
+  internet&.close
+end
+```
+
+Bound concurrency with a **Semaphore**; coordinate completion with a **Barrier**:
+
+```ruby
+require "async/semaphore"
+require "async/barrier"
+
+Async do
+  barrier   = Async::Barrier.new
+  semaphore = Async::Semaphore.new(10, parent: barrier)  # max 10 in flight
+
+  urls.each { |u| semaphore.async { fetch(u) } }
+  barrier.wait     # wait for all spawned tasks
+end
+```
+
+DON'T mix `async`-style fiber concurrency with blocking C-extensions that don't release the GVL or cooperate with the scheduler — they block the whole reactor. Use `async`-aware libraries (e.g. `async-http`, `async-postgres`).
+
+## Ractors — true parallelism on MRI (experimental)
+
+Ractors run Ruby code **in parallel** (each has its own GVL) by forbidding shared mutable state. As of 3.2–3.4 they are still **experimental** (emit a warning) and many gems aren't Ractor-safe.
+
+- Only **shareable** objects cross Ractor boundaries: immutable/frozen objects, `Integer`, `Symbol`, `true/false/nil`, deeply-frozen structures, classes/modules. Check with `Ractor.shareable?(obj)`.
+- Communicate by **message passing**, not shared memory: `send`/`receive` (copy, mailbox) and `yield`/`take` (push/pull).
+
+```ruby
+r = Ractor.new do
+  msg = Ractor.receive          # block until a message arrives
+  msg * 2
+end
+r.send(21)
+r.take                          # => 42  (the block's value)
+
+# Parallel map across CPUs
+ractors = inputs.map { |x| Ractor.new(x) { |v| heavy_cpu(v) } }
+results = ractors.map(&:take)
+```
+
+Limits to know: non-shareable globals/constants raise `IsolationError`; many stdlib/gems aren't Ractor-safe; debugging is harder; the warning is emitted on first use. Treat Ractors as promising for isolated CPU-bound fan-out, not as a drop-in thread replacement yet.
+
+## Processes & fork — real parallelism, the safe default for CPU work on MRI
+
+Separate processes each have their own GVL, so they run in parallel. The cost is no shared memory (communicate via pipes/IPC) and OS process overhead.
+
+```ruby
+pid = Process.fork do
+  # child: independent memory (copy-on-write of parent's pages)
+  result = heavy_cpu
+  # return value is NOT visible to parent — must use IPC
+end
+Process.wait(pid)               # reap the child; avoid zombies
+```
+
+Pass results back over an `IO.pipe` (or use a higher-level tool):
+
+```ruby
+reader, writer = IO.pipe
+pid = fork { reader.close; writer.write(Marshal.dump(compute)); writer.close }
+writer.close
+data = Marshal.load(reader.read); reader.close
+Process.wait(pid)
+```
+
+`fork` is **not available on Windows** and is fragile with threads (only the forking thread survives in the child) and with open connections/file handles — reconnect DBs/clients in the child.
+
+### `parallel` gem — fork made easy
+
+```ruby
+require "parallel"
+# CPU-bound: spread across cores with processes
+Parallel.map(items, in_processes: 8) { |i| heavy_cpu(i) }
+# IO-bound: lighter-weight threads
+Parallel.map(items, in_threads: 16) { |i| fetch(i) }
+```
+
+`in_processes` serializes args/results via Marshal across the fork boundary — objects must be Marshalable, and side effects in children don't propagate back.
+
+## Choosing a model
+
+| Workload | Use |
+|---|---|
+| IO-bound, moderate concurrency | Threads + `SizedQueue`, or `Concurrent::FixedThreadPool` |
+| IO-bound, very high concurrency (10k+ sockets) | Fibers via the `async` gem |
+| CPU-bound on MRI | Processes (`fork` / `parallel` gem) or Ractors (if isolatable) |
+| CPU-bound, want shared memory + parallelism | JRuby or TruffleRuby (no GVL) |
+
+Rules of thumb:
+- IO-bound -> **threads / async / fibers**.
+- CPU-bound -> **processes / Ractors / JRuby / TruffleRuby**.
+- Always **bound** concurrency (fixed pool, sized queue, semaphore). Unbounded `Thread.new` per item exhausts memory and OS threads.
+
+Rails background jobs (ActiveJob/Sidekiq) are a separate, higher-level concern — see references/rails.md. Profiling concurrency for performance — see references/performance.md.
+
+## Timeouts — `Timeout` caveats
+
+`Timeout.timeout` raises an exception in the target thread at an **arbitrary point**, which can interrupt the middle of a critical section, leave locks held, or corrupt state. Treat it as a last resort.
+
+```ruby
+# RISKY: can fire mid-operation, leaving inconsistent state / undefined behavior
+Timeout.timeout(5) { do_complex_thing }
+
+# PREFER: native/library timeouts that abort cleanly at safe points
+Net::HTTP.start(host, open_timeout: 5, read_timeout: 5) { ... }
+db.connect(connect_timeout: 5)
+socket.read_nonblock(...)   # with IO.select for the deadline
+```
+
+If you must use `Timeout`, keep the block tiny, avoid holding mutexes inside it, and never wrap operations that mutate shared state without cleanup.
+
+## Quick checklist
+
+- MRI GVL: threads help **IO-bound**, never CPU-bound. CPU-bound -> processes/Ractors/JRuby/TruffleRuby.
+- The GVL does **not** make code thread-safe; `+=`, `<<`, `Hash[]=` are not atomic.
+- Always `join`/`value` threads (or push errors to a `Queue`) — unjoined exceptions vanish.
+- Pass loop vars as block args to `Thread.new(x) { |x| }`; don't capture by closure.
+- Prefer `Thread::Queue`/`SizedQueue` for producer-consumer; use `SizedQueue` for backpressure.
+- Use `Concurrent::*` (FixedThreadPool, Future, Map, AtomicFixnum) over hand-rolled primitives.
+- Guard check-then-act and side-effecting memoization with a `Mutex`/`Monitor`; `||=` only for idempotent values.
+- Prefer immutable, `frozen` objects shared across threads to avoid locks entirely.
+- Bound concurrency: fixed pools, sized queues, `Async::Semaphore`. Never unbounded `Thread.new`.
+- High-concurrency IO -> `async` gem (`Async{}`, semaphores, barriers).
+- Ractors are experimental: only shareable/frozen objects cross boundaries; communicate by message passing.
+- `fork`: no Windows, fragile with threads/connections; reconnect clients in the child; reap with `Process.wait`.
+- Avoid `Timeout.timeout` for stateful work — prefer library/socket-level timeouts.