add CI, CONTRIBUTING, STYLE, lefthook; tidy runtime and specs; drop planning docs

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nficano

.github/workflows/ruby.yml

@@ -0,0 +1,37 @@
+name: Ruby
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+      - run: bundle exec rubocop --parallel
+      - run: bundle exec bundle-audit check --update
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+      - run: bundle exec rspec
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+      - run: bundle exec yard --fail-on-warning

.rubocop.yml

@@ -1,6 +1,7 @@
 plugins:
   - rubocop-rspec
   - rubocop-performance
+  - rubocop-rake
 
 AllCops:
   TargetRubyVersion: 3.4
@@ -20,16 +21,17 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: single_quotes
 
+# YARD docstrings exist where they add protocol value; blanket top-level
+# class/module comments are not required for this gem.
 Style/Documentation:
   Enabled: false
 
 Style/FrozenStringLiteralComment:
   Enabled: true
   EnforcedStyle: always
 
-Naming/AccessorMethodName:
-  Enabled: false
-
+# Protocol/runtime objects are intentionally larger than Sandi Metz-style
+# service classes; these limits flag outliers without forcing extra indirection.
 Metrics/MethodLength:
   Max: 40
 
@@ -58,16 +60,20 @@ Metrics/ParameterLists:
   Max: 8
   CountKeywordArgs: false
 
+# Short names are allowed for narrow protocol ids and tiny block locals.
 Naming/MethodParameterName:
   AllowedNames:
     - a
     - b
     - id
     - kw
 
+# Integration specs are organized by protocol scenario first, not by a single
+# nested umbrella describe.
 RSpec/MultipleDescribes:
   Enabled: false
 
+# Keep implementation files readable without forcing awkward envelope wrapping.
 Layout/LineLength:
   Max: 110
   Exclude:
@@ -76,15 +82,11 @@ Layout/LineLength:
 RSpec/ExampleLength:
   Max: 60
 
+# Some manager command methods return booleans to signal whether a state change
+# happened; forcing `?` names there would misrepresent them as pure predicates.
 Naming/PredicateMethod:
   Enabled: false
 
-Lint/DuplicateBranch:
-  Enabled: false
-
-Style/MultilineBlockChain:
-  Enabled: false
-
 RSpec/MultipleExpectations:
   Max: 8
 
@@ -99,6 +101,8 @@ RSpec/DescribeClass:
     - 'spec/integration/**/*'
     - 'spec/e2e/**/*'
 
+# Specs are grouped by test layer (`unit`, `integration`, `e2e`) instead of
+# mirroring the source tree exactly.
 RSpec/SpecFilePathFormat:
   Enabled: false
 

CONFORMANCE.md

@@ -0,0 +1,36 @@
+# Contributing
+
+## Environment
+
+- Use Ruby `3.4.8`.
+- This repository includes both `.ruby-version` and `.tool-versions`.
+- If your shell does not activate the project Ruby automatically, make sure
+  your version manager does before running Bundler commands. With `asdf`, use
+  `asdf exec bundle exec ...` as a fallback.
+
+## Setup
+
+1. `bundle install`
+2. Install `lefthook` if you do not already have it.
+3. `lefthook install`
+
+## Local checks
+
+Run these before opening a pull request:
+
+- `bundle exec rubocop`
+- `bundle exec rspec`
+- `bundle exec bundle-audit check --update`
+- `bundle exec yard --fail-on-warning`
+- `bundle exec rake`
+
+`spec/spec_helper.rb` enforces a minimum SimpleCov line coverage floor. If a
+refactor reduces coverage, add or fix tests in the same change.
+
+## Change discipline
+
+- Preserve public behavior unless the change is explicitly approved.
+- Read the implementation, its tests, and its callers before refactoring.
+- Keep commits single-purpose and easy to review.
+- Log architectural follow-up work in `REFACTOR_BACKLOG.md` instead of mixing
+  design changes into an idiom pass.

CONTRIBUTING.md

@@ -5,10 +5,12 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'bundler-audit', require: false
   gem 'rake', '~> 13.0'
   gem 'rspec', '~> 3.13'
   gem 'rubocop', '~> 1.60', require: false
   gem 'rubocop-performance', require: false
+  gem 'rubocop-rake', require: false
   gem 'rubocop-rspec', require: false
   gem 'simplecov', '~> 0.22', require: false
   gem 'yard', '~> 0.9', require: false

Gemfile

@@ -40,6 +40,9 @@ GEM
       protocol-websocket (~> 0.17)
     base64 (0.3.0)
     bigdecimal (4.1.2)
+    bundler-audit (0.9.3)
+      bundler (>= 1.2.0)
+      thor (~> 1.0)
     console (1.34.3)
       fiber-annotation
       fiber-local (~> 1.1)
@@ -122,6 +125,9 @@ GEM
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
     rubocop-rspec (3.9.0)
       lint_roller (~> 1.1)
       rubocop (~> 1.81)
@@ -143,6 +149,7 @@ GEM
     sqlite3 (2.9.4-x86_64-darwin)
     sqlite3 (2.9.4-x86_64-linux-gnu)
     sqlite3 (2.9.4-x86_64-linux-musl)
+    thor (1.5.0)
     traces (0.18.2)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
@@ -163,10 +170,12 @@ PLATFORMS
 
 DEPENDENCIES
   arcp!
+  bundler-audit
   rake (~> 13.0)
   rspec (~> 3.13)
   rubocop (~> 1.60)
   rubocop-performance
+  rubocop-rake
   rubocop-rspec
   simplecov (~> 0.22)
   yard (~> 0.9)