traject-solr_pool 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ba919dd1768bd1f05ff1e29af8236790aee47bd0333f97c9be2cd66b691fa0a
+  data.tar.gz: 01e411c06eb9dd7f101630e42829c0dddacb13931ee1bb0c38f4966383fdcb5a
+SHA512:
+  metadata.gz: 131acdc7092f6f935ba9d16b1aa4c50047b86694d06dc4ba571c4d8415624ff461efe549351e4c8db76d106ab58539f469fd3491bc8bd709d1875d65eaa73794
+  data.tar.gz: '0687c890c8944c6b2b024c49b09748f78c8626a7a8531ce0aac553cc5c5bd173537e7ef9cf0a30f23c33976022e7a41f40d2587cb4056bfe5fb23a1e0f8cd040'

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.3', '3.4']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      # `rake ci` runs bundle:audit:check OFFLINE. No advisory DB is cloned in
+      # this job, so that step no-ops; the authoritative CVE scan is the
+      # `security` job below, which refreshes the DB over the network.
+      - run: bundle exec rake ci
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - run: bundle exec rake audit

data/CLAUDE.md

@@ -0,0 +1,237 @@
+# CLAUDE.md — traject-solr_pool
+
+## Project Goal
+
+This gem is a **plugin for [traject](https://github.com/traject/traject)** that
+lets traject writers (and future readers) send Solr/HTTP traffic over a
+**persistent, pooled, thread-safe, Fiber-scheduler-aware HTTP client** instead
+of opening a fresh connection per request.
+
+The pooling itself is **not** reimplemented here. It is provided by the
+`http_connection_pool` gem (a sibling project), which keeps one pool of
+persistent `HTTP::Session` connections per origin, credential-isolated and safe
+under heavy concurrency. This gem is the **traject-facing adapter**: it exposes
+a writer (initially a drop-in replacement for `Traject::SolrJsonWriter`) that
+speaks traject's writer contract while borrowing connections from that pool.
+
+The deliverable is a Solr JSON writer that:
+
+- registers via traject's `writer_class_name` setting,
+- honours the existing `solr.*` / `solr_writer.*` settings surface so it is a
+  drop-in for the stock writer wherever practical,
+- and routes every HTTP call through an `http_connection_pool` pool keyed by
+  the Solr origin.
+
+A reader is explicitly **future scope** — design the code so a reader can reuse
+the same pooling seam later, but do not build it until asked.
+
+---
+
+## Dependency Situation (resolved)
+
+`http_connection_pool` requires `http ~> 6.0`. Earlier released traject gems
+capped their dependency at `http < 6`, so the two could not co-install from
+RubyGems, and the project bridged the gap with a Gemfile `path:` override to a
+local edge checkout.
+
+- **traject 3.9.0 (released 2026-07-21) relaxed the cap** to `http >= 3.0,
+  < 7`, so traject now co-installs with `http_connection_pool` straight from
+  RubyGems. The gemspec pins `traject '~> 3.9'`.
+- The `path:` override is **no longer needed**. It is commented out in the
+  `Gemfile` (kept as a hook in case a local traject checkout is ever needed
+  again, e.g. to test an unreleased fix) — do not re-enable it for normal work.
+- Do **not** hardcode absolute local filesystem paths anywhere in committed
+  source, specs, or docs. Any local override lives in the `Gemfile` and refers
+  to a sibling checkout by relative path.
+
+---
+
+## Non-Negotiable Constraints
+
+### 1. Git and publishing
+- **You may `git commit`. You may NEVER `git push`** — recommend the push
+  command and let the user run it. This also covers `gem push`, `gem release`,
+  `rake release`, and `git push --force` (all forbidden; user-only).
+- Follow `~/.gitignore` hygiene: never stage `Gemfile.lock` (it is gitignored
+  here), never use `git add -A`/`git add .` — add files by name, and check
+  `.gitignore` before staging.
+- Verify no secrets (Solr credentials, tokens) are ever committed.
+
+### 2. Test-driven development
+- **RSpec, TDD.** Write a failing spec before implementation code. See the
+  RSpec section below.
+- The whole point of the gem is concurrency-safe pooling, so writer behaviour
+  under a multi-thread `solr_writer.thread_pool` must be covered by specs, not
+  assumed.
+
+### 3. Thread safety, Sidekiq, Zeitwerk, and Rails compatibility (MUST)
+This gem must be as safe and portable to embed as `http_connection_pool` is.
+These are hard requirements, not aspirations:
+
+- **Thread safety is mandatory.** The writer is exercised concurrently — both
+  by traject's own `solr_writer.thread_pool` and by hosting apps. All shared
+  state must be safe under concurrent access. Prefer `concurrent-ruby`
+  primitives (`Concurrent::AtomicFixnum`, `Concurrent::Map`, etc.) as the stock
+  `SolrJsonWriter` does; never guard the hot path with a coarse global `Mutex`.
+  Let the underlying `http_connection_pool` own connection checkout/return —
+  never hold a borrowed connection across threads.
+- **Sidekiq >= 8 compatibility is a target.** The writer must be usable from
+  inside a Sidekiq >= 8 worker: instances may be created and torn down per job,
+  many workers/threads run concurrently, and the process forks. Rely on
+  `http_connection_pool`'s fork-safety (`connection_pool >= 2.5`
+  `auto_reload_after_fork`); do not cache raw sockets or connection objects
+  across a fork in this gem. Cover the "used from a background job / forked
+  worker" path with specs, mirroring the sibling gem's background-job specs.
+- **Zeitwerk + Rails compatibility is a target.** The gem must coexist cleanly
+  with a Rails app's Zeitwerk loader and not corrupt eager-loading. Keep the
+  file/constant layout Zeitwerk-conformant (file path matches constant name)
+  even though traject itself loads via plain `require`. No Rails **runtime**
+  dependency — Rails/Zeitwerk are **test-only** concerns, verified by
+  integration specs (mirror `http_connection_pool`'s Rails-compat and
+  clean-subprocess Zeitwerk specs). Do not add `rails`, `activesupport`, or
+  `zeitwerk` to `spec.add_dependency`.
+
+### 4. Respect the traject writer contract
+A traject writer is any class that responds to:
+- `initialize(settings)` — receives a `Traject::Indexer::Settings` (a Hash).
+- `put(context)` — enqueue one `Traject::Indexer::Context` for output.
+- `close` — flush remaining work, shut down threads, optionally commit.
+
+`SolrJsonWriter` additionally provides `flush`, `commit`, `delete`,
+`delete_all!`, and `skipped_record_count`. Mirror this surface so the writer is
+a genuine drop-in. **Do not invent a new settings vocabulary** — reuse the
+documented `solr.*` and `solr_writer.*` keys. New settings, if unavoidable, go
+under a clearly namespaced prefix and must be documented.
+
+### 5. Use the pool through its public API
+- Integrate via `http_connection_pool`'s public surface (the `Connectable`
+  mixin / `Registry` / `Pool`). Do not reach into its internals or reimplement
+  keep-alive, mutexes, or socket handling.
+- `base_url` for a pool is an **origin** (`scheme://host:port`); request paths
+  (e.g. `/solr/<core>/update/json`) are **relative** and passed per request.
+- Solr basic-auth credentials and content-type headers belong in
+  `pool_options` (e.g. `headers:`), never baked into the origin. Pools are
+  keyed by a SHA-256 digest of `(origin, options)`, so distinct credentials get
+  distinct pools automatically — never defeat that isolation.
+- `pool_options` **replaces, does not merge**. If merge semantics are needed,
+  the caller composes the hash explicitly.
+- `http_connection_pool` rejects non-scalar option values such as
+  `ssl_context:` (raises `OptionKeyError`). Do not pass one; translate SSL
+  needs through supported options or document the limitation.
+
+### 6. No leakage of credentials in logs or errors
+- The stock writer deliberately strips embedded user/password from the update
+  URL before logging (`determine_solr_update_url`). Preserve that: never log or
+  raise a message containing basic-auth credentials or auth headers.
+
+### 7. Ruby and portability
+- `required_ruby_version >= 3.3.0`. Target and test on **MRI (CRuby)**. JRuby is
+  not verified — do not claim JRuby support until it is exercised.
+
+---
+
+## Code Style
+
+- **RuboCop is authoritative and must be clean before any commit.** Config is
+  `.rubocop.yml`; it enforces **single-quoted** non-interpolated string literals
+  (`Style/StringLiterals: single_quotes`) — follow it. Use double quotes only
+  when the string interpolates.
+- Every Ruby file begins with `# frozen_string_literal: true`.
+- Run `bundle exec rubocop -a` to auto-fix correctable offences. Never silence a
+  cop with an inline `# rubocop:disable` unless there is genuinely no
+  alternative — restructure or extract a method instead.
+- Comments explain *why* (hidden constraints, invariants, workarounds), not
+  *what*. Prefer `attr_reader` over hand-written getters. Keep methods short.
+- Plugins are declared with `plugins:` syntax in `.rubocop.yml`:
+  `rubocop-performance`, `rubocop-rake`, `rubocop-rspec`.
+
+---
+
+## RSpec
+
+- **Never use apostrophes in `it`/`describe`/`context` strings** — `it 'a b's c'`
+  is a Ruby `SyntaxError`. Rephrase to avoid the apostrophe.
+- Helper methods/classes for specs go in a `spec/support` module included by tag
+  — never define a top-level `class`/`def` in a spec file (it leaks a global
+  constant). `spec/support/**/*.rb` should be auto-required by `spec_helper.rb`.
+- Use `after do` (not `after(:each) do`) for teardown. Reset any global pool
+  registry between examples so state never leaks (mirror the sibling gem's
+  `Registry.reset!` teardown pattern).
+- Stub Solr HTTP at the pool/connection boundary so unit specs do not require a
+  live Solr. Reserve live-Solr exercises for clearly tagged integration specs.
+- Concurrency is a first-class behaviour: cover `put`/`send_batch`/`close` under
+  a threaded `solr_writer.thread_pool`, not just the single-thread path.
+- Rails/Zeitwerk/Sidekiq compatibility lives in tagged integration specs (see
+  constraint 3); keep them out of the fast unit path.
+
+---
+
+## Documentation
+
+- **Whenever a change affects behaviour, settings, dependencies, or usage,
+  update `README.md` and any relevant files under `docs/` in the same change.**
+  This is standing — do not wait to be asked.
+- Document the settings the writer honours, the temporary edge-traject
+  dependency and how to remove it, and a `writer_class_name` usage example.
+- Markdown: one `#` H1 per file, sentence-case headings in nesting order, fenced
+  code blocks with a language tag, blank lines around headings/lists/fences.
+
+---
+
+## File / Constant Layout
+
+Namespaced under `Traject::SolrPool` (traject convention; traject does not use
+Zeitwerk itself — load with `require`/`require_relative`, not autoloading). The
+layout must still be **Zeitwerk-conformant** (file path matches constant name)
+so a host Rails app's loader stays happy — verify with an integration spec.
+
+```
+lib/
+  traject/solr_pool.rb               # entry point
+  traject/solr_pool/
+    version.rb                       # Traject::SolrPool::VERSION
+    ...                              # writer + supporting classes (TBD in design)
+```
+
+`version.rb` defines `Traject::SolrPool::VERSION`. Keep the constant tree
+matching the file tree.
+
+---
+
+## Rake Tasks
+
+| Task                      | What it does                                          |
+| ------------------------- | ----------------------------------------------------- |
+| `rake` / `rake ci`        | `bundle:audit:check` (offline) → RuboCop → RSpec      |
+| `rake audit`              | `bundle:audit:update` (network) → `bundle:audit:check`|
+| `rake spec`               | RSpec only                                            |
+| `rake rubocop`            | RuboCop only                                          |
+| `rake bundle:audit:check` | Offline CVE scan                                      |
+
+`rake ci` must run clean before any commit. Never bypass bundler-audit.
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs on push to `main` and on PRs: a `test` matrix
+over MRI Ruby `3.3` and `3.4` running `rake ci` (offline audit + RuboCop +
+RSpec), plus a separate `security` job running `rake audit` (network advisory-DB
+refresh + check). MRI only — mirrors `http_connection_pool`'s CI. `Gemfile.lock`
+is gitignored, so CI resolves dependencies fresh each run.
+
+Automated publishing (`release.yml` / OIDC Trusted Publishing) is planned but
+not yet wired; the initial release is published manually by the maintainer.
+
+---
+
+## Key Decisions (do not reverse without discussion)
+
+1. **Pooling is delegated to `http_connection_pool`** — this gem is a thin
+   traject adapter, not a second pooling implementation.
+2. **Drop-in for `SolrJsonWriter`** — reuse its settings vocabulary and public
+   method surface; do not fork a new configuration language.
+3. **Thread-safe, Sidekiq >= 8, Zeitwerk, and Rails compatible** — first-class
+   requirements verified by specs, matching `http_connection_pool`'s guarantees.
+4. **Released traject only** — pin `traject '~> 3.9'` (3.9.0 lifted the
+   `http < 6` cap). The old edge `path:` override is commented out in the
+   Gemfile; do not re-enable it except to test an unreleased traject fix.
+5. **Reader is future scope** — leave a clean seam, build only when asked.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 bbarberBPL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,167 @@
+# Traject::SolrPool
+
+`Traject::SolrPool::SolrJsonWriter` is a drop-in pooled replacement for the
+stock `Traject::SolrJsonWriter`. It routes every Solr update through a
+persistent, credential-isolated, thread-safe HTTP connection pool provided by
+[`http_connection_pool`][hcp] instead of opening a fresh `HTTPClient`
+connection per request.
+
+It reuses the stock writer's `solr.*` / `solr_writer.*` settings vocabulary, so
+it is a drop-in wherever those settings are practical. The writer is:
+
+- thread-safe (shared state uses `concurrent-ruby` primitives; a borrowed
+  connection is never held across threads),
+- usable from Sidekiq >= 8 workers (fork-safe via `connection_pool >= 2.5`),
+- Zeitwerk-conformant, and
+- compatible with Rails (no Rails runtime dependency).
+
+All four properties are verified by the test suite (unit, concurrency, Sidekiq,
+Zeitwerk, and Rails-coexistence specs).
+
+[hcp]: https://github.com/bbarberBPL/http_connection_pool
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem 'traject-solr_pool'
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+## Requirements
+
+- Ruby >= 3.3
+- `traject` >= 3.9 (3.9.0 relaxed its HTTP cap to `http >= 3.0, < 7`, so it
+  co-installs with `http_connection_pool`'s `http ~> 6.0` directly from
+  RubyGems — no edge checkout needed)
+- `http_connection_pool` >= 0.1.1
+
+Earlier releases of `traject` capped their HTTP dependency at `http < 6`, which
+collided with `http_connection_pool`'s `http ~> 6.0`; the Gemfile once carried a
+`path:` override to a local edge checkout to work around that. It is no longer
+required and the override is commented out.
+
+## Usage
+
+Register the writer with traject's `writer_class_name` setting:
+
+```ruby
+require 'traject/solr_pool'
+
+settings do
+  provide 'writer_class_name', 'Traject::SolrPool::SolrJsonWriter'
+  provide 'solr.url', 'http://localhost:8983/solr/my_core'
+  provide 'solr_writer.thread_pool', 4
+  provide 'solr_pool.pool_size', 5
+end
+```
+
+The origin (`scheme://host:port`) derived from `solr.url` becomes the pool's
+`base_url`; the remainder of the URL becomes the relative request path. Basic
+auth credentials are sent as an `Authorization` header, never baked into the
+origin, so distinct credentials resolve to distinct pools and never share
+connections.
+
+## Settings
+
+The writer honours the stock `solr.*` / `solr_writer.*` vocabulary, plus one
+new namespaced setting.
+
+| Setting | Default | Role |
+| --- | --- | --- |
+| `solr.url` | (required unless `solr.update_url` set) | Base Solr URL; `/update/json` is derived from it |
+| `solr.update_url` | derived from `solr.url` | Full update handler URL; used verbatim when provided |
+| `solr_writer.batch_size` | `100` | Documents per batched update |
+| `solr_writer.thread_pool` | `1` | Number of background writer threads |
+| `solr_writer.max_skipped` | `0` | Skip tolerance before `MaxSkippedRecordsExceeded` (negative disables the cap) |
+| `solr_writer.skippable_exceptions` | http.rb-native list (see below) | Exceptions treated as skippable during per-record retry |
+| `solr_writer.commit_on_close` | `false` | Send a commit when the writer closes (legacy `solrj_writer.commit_on_close` also honoured) |
+| `solr_writer.solr_update_args` | none | Query params (e.g. `{ 'commitWithin' => 1000 }`) applied to every update and delete request |
+| `solr_writer.commit_solr_update_args` | `{ 'commit' => 'true' }` | Query params for the commit request |
+| `solr_writer.commit_timeout` | `600` (10 min) | Read timeout applied to the commit request only, so a slow commit is not cut off by a short `http_timeout` |
+| `solr_writer.basic_auth_user` | embedded URI user | Basic-auth user (overrides credentials embedded in the URL) |
+| `solr_writer.basic_auth_password` | embedded URI password | Basic-auth password (overrides credentials embedded in the URL) |
+| `solr_writer.http_timeout` | none | Per-request HTTP timeout, passed to the pool connection |
+| `solr_writer.pool_timeout` | pool default | Max time to wait for a connection checkout from the pool |
+| `solr_pool.pool_size` | `solr_writer.thread_pool` + 1 | Pool capacity, sized so no writer thread starves on checkout while the caller thread can still flush/commit |
+
+### Dropped settings
+
+Two `solr_json_writer.*` settings from the stock writer are HTTPClient-specific
+and are not supported:
+
+- `solr_json_writer.http_client` — the pool owns connection construction, so
+  there is no `HTTPClient` instance to inject.
+- `solr_json_writer.use_packaged_certs` — an `HTTPClient` ssl_config quirk;
+  http.rb uses the operating system's certificate store instead.
+
+## Error handling
+
+- `Traject::SolrPool::SolrJsonWriter::BadHttpResponse` (a `RuntimeError`) is
+  raised on any non-200 response. Its `#response` accessor returns the raw
+  http.rb response (use `#code` / `#to_s`), and it extracts Solr's JSON
+  `error.msg` into the message when present.
+- The default `solr_writer.skippable_exceptions` list is http.rb-native:
+
+  ```ruby
+  [
+    HTTP::TimeoutError,
+    HttpConnectionPool::TimeoutError,
+    HTTP::ConnectionError,
+    SocketError,
+    Errno::ECONNREFUSED,
+    Traject::SolrPool::SolrJsonWriter::BadHttpResponse
+  ]
+  ```
+
+  A batch that fails is retried record by record; a record that raises a
+  skippable exception is logged and counted, aborting the run only once
+  `solr_writer.max_skipped` is exceeded.
+- Setting `solr_writer.skippable_exceptions` explicitly replaces the default
+  list entirely with your own.
+- `commit`, `delete`, and `delete_all!` raise raw on failure; they are not part
+  of the skip path.
+- Credentials never appear in logs or error messages: auth lives in a header
+  and logs show the origin only.
+
+## Pool lifecycle
+
+`close` flushes any queued records, waits for the background threads, and
+commits when `solr_writer.commit_on_close` is set. It then **leaves the pool
+warm** in the `http_connection_pool` registry so later writers (or a future
+reader) on the same origin reuse it.
+
+Teardown is the host application's concern. Close the pools explicitly on
+process shutdown or after a fork, for example:
+
+```ruby
+HttpConnectionPool::Registry.instance.close_all
+```
+
+## Development
+
+Run the full CI pipeline (offline bundler-audit, RuboCop, RSpec):
+
+```bash
+bundle exec rake ci
+```
+
+Individual tasks (`rake spec`, `rake rubocop`, `rake bundle:audit:check`) are
+also available.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Releasing and pushing are maintainer
+responsibilities — contributors should not push tags or publish gems.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][mit].
+
+[mit]: https://opensource.org/licenses/MIT

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'bundler/audit/task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+Bundler::Audit::Task.new
+
+# The default task runs offline, so `ci` only *checks* against whatever
+# advisory DB is present. `audit` refreshes the DB from the network first;
+# `bundle:audit:check` no-ops gracefully if the DB was never cloned.
+desc 'Refresh the advisory DB, then scan dependencies for known CVEs'
+task audit: ['bundle:audit:update', 'bundle:audit:check']
+
+desc 'Audit dependencies (offline), run RuboCop, then the RSpec suite'
+task ci: %i[bundle:audit:check rubocop spec]
+
+task default: :ci

data/docs/agents/README.md

@@ -0,0 +1,41 @@
+# Agents
+
+Project-specific subagent definitions for `traject-solr_pool`.
+
+When a task in this project benefits from a dedicated subagent (a focused
+reviewer, a migration helper, a release auditor, etc.), define it here as one
+Markdown file per agent. Keep each agent's responsibility narrow and its
+instructions self-contained, so it can run without the parent session's
+context.
+
+## File convention
+
+- One file per agent: `docs/agents/<agent-name>.md`.
+- Start with a short purpose line: what the agent does and when to reach for it.
+- List the tools it needs and the inputs it expects (file paths, not pasted
+  context).
+- Describe the report format it must return.
+
+## Reusable from the sibling `http_connection_pool` gem
+
+This gem shares that gem's thread-safety and security constraints, so several of
+its agents transfer directly (see `../../../http_connection_pool/docs/agents/`).
+Adapt the file paths/tags to this project when reused:
+
+- `concurrency-spec-reviewer` — reviews concurrency specs for assertions a race
+  can invalidate, then stress-loops them for flakiness. Directly applicable to
+  our `:thread_safety` and `:background_jobs` integration specs.
+- `dependency-security-auditor` — audits the dependency tree against primary
+  sources (RubyGems API, GitHub advisory DB). Applicable to our gemspec/Gemfile
+  whenever a dependency floor changes.
+- `memory-leak-auditor` — hunts unbounded retention with `ObjectSpace`/`GC`
+  probes. Applicable to verifying the writer/pool do not accumulate objects
+  per-batch or per-job.
+
+## Defined agents
+
+_None yet. Candidate for this project:_
+
+- **writer-parity-reviewer** — diff our `Traject::SolrPool::SolrJsonWriter`
+  against the stock `Traject::SolrJsonWriter` to confirm settings/method-surface
+  parity and flag any silently-dropped behaviour. Advisory only.

data/docs/skills/README.md

@@ -0,0 +1,42 @@
+# Skills
+
+Project-specific skills for `traject-solr_pool`.
+
+When a repeatable workflow emerges in this project (a release checklist, a
+dependency-audit routine, a Solr round-trip verification), capture it here as a
+skill so future sessions follow the same steps instead of rediscovering them.
+
+## File convention
+
+- One directory per skill: `docs/skills/<skill-name>/SKILL.md`.
+- The `SKILL.md` opens with YAML frontmatter (`name`, `description`) describing
+  when the skill applies, followed by the steps.
+- Keep steps concrete and ordered; prefer checklists the session can turn into
+  todos.
+- Reference supporting files by relative path within the skill directory.
+
+## Reusable from the sibling `http_connection_pool` gem
+
+See `../../../http_connection_pool/docs/skills/`. These transfer with minor path
+changes:
+
+- `dependency-audit` — security sweep that verifies every advisory/version claim
+  against primary sources before recommending a change. Reuse verbatim whenever
+  a dependency floor changes.
+- `memory-leak-audit` — drives churn and measures retention with
+  `ObjectSpace`/`GC` rather than reading code. Adapt the churn driver to enqueue
+  writer batches / background jobs against a WebMock-stubbed Solr.
+
+## Defined skills
+
+_None yet. Candidates for this project:_
+
+- **edge-traject-cutover** — _done (2026-07-27)._ traject 3.9.0 lifted the
+  `http < 6` cap; the gemspec now pins `traject '~> 3.9'` and the Gemfile
+  `path:` override is commented out. Retained here as a record of the cutover
+  procedure (verify the published version via the RubyGems API, update the
+  gemspec constraint, drop the override, re-run `rake ci`) in case a similar
+  edge-dependency bridge is needed again.
+- **solr-roundtrip-verify** — bring up a local Solr, run a real index + commit +
+  delete round-trip through the pooled writer, and confirm connection reuse via
+  registry stats (mirrors the sibling gem's `examples/solr_update_demo.rb`).