kicks_liveness 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 206f62be48c616553a219c499e1106beb68a49fd3c91ca30a1d7f3ee812c15f7
-  data.tar.gz: b2edcb9d1a6dd351df5b7a25d27e358582def6b6d8cdc4f7ad70b055ad1c25a9
+  metadata.gz: df61d00933097bb96e6d752e024e349ab631cd7c9d571cd9bff9ff63b8adda40
+  data.tar.gz: 78864373ca06cd998cdee192d064cd00ed69a4ecd73eb1b657474d77ab593066
 SHA512:
-  metadata.gz: 06caaf5bfe502f5a83eebe11d03a8122f91ad03672fe2b11f046143ed107d6b81d126344cc293afc2ee311c6fb2f1a1f42739e82ff37b3e737cad7d3b71d97fb
-  data.tar.gz: 6cf539fef1a39318702015363035bc8f1538fa9cabaaa6543eca038a62059db98a21b9b82a2a53be62a0315e6872adc7b6891c586df52d1bff3700b2071eb700
+  metadata.gz: '007091e18fea1b216ba25c634bab1a4770d25cc0f062ee30ba2885563075bc94e7662e58eebbac9507b448217508725612f172189b692e3a4d616e5f81fdd46b'
+  data.tar.gz: f460271ca68fdf912559b3fa2c41b02074d5eb457e946d2f985e3e2b0ac3da66dc94ce90c9d5639212a0fc7bb6537046654f31921cf6766fe15c903bd7dc04ef

data/.yardopts

@@ -0,0 +1,13 @@
+--markup markdown
+--readme README.md
+--title "kicks_liveness"
+--no-private
+lib/**/*.rb
+-
+docs/SETUP.md
+docs/DESIGN.md
+docs/KUBERNETES.md
+docs/LIMITATIONS.md
+docs/VERIFYING.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -3,6 +3,61 @@
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.1.2] - 2026-09-11
+
+### Fixed
+
+- Reject heartbeat files inherited from a previous container incarnation. A
+  Kubernetes `emptyDir` survives container restarts, so a fresh mark left by a
+  formerly healthy worker could make the next container pass `startupProbe`
+  before its consumers had subscribed. Cache files elsewhere in the same
+  `emptyDir` remain untouched and available to warm the next application boot.
+  This protection assumes the default container-private PID namespace; pods
+  using `shareProcessNamespace` or `hostPID` retain the 0.1.1 freshness-only
+  behavior (see `docs/LIMITATIONS.md`).
+  The marks directory now contains `<dir>/generation`, and each
+  `worker-<slot>` mark carries the same value; tooling that enumerates the
+  directory should allow for this new metadata file.
+
+## [0.1.1] - 2026-09-09
+
+### Added
+
+- Add a repository-hosted social-preview asset for the project documentation.
+
+### Changed
+
+- Rework the README into a shorter entry point while retaining the operational
+  detail in the focused guides under `docs/`.
+- Reject initializer values where `tick >= max_age`, and require
+  `startup_grace_ticks` to be a positive integer. Initializers that previously
+  supplied either invalid value now stop application boot with `ArgumentError`.
+- Reject bundles that activate both `kicks` and `sneakers` with `LoadError`
+  instead of letting their shared `lib/sneakers.rb` resolve silently by
+  load-path order. Applications that still bundle both worker gems must remove
+  one before upgrading.
+- Replace the contributor-only `AMQP_WORKER_GEM` and
+  `AMQP_WORKER_GEM_VERSION` test selection with Appraisal-generated dependency
+  sets, including current and supported-floor targets for both worker gems.
+
+### Fixed
+
+- Recover environment values where `tick >= max_age` with a warning and a safe
+  interval, preventing a healthy heartbeat from becoming stale between normal
+  monitor ticks.
+- Keep worker startup, heartbeat publication, and the monitor loop alive when a
+  custom logger raises while handling an INFO or ERROR event.
+- Correct the runtime-scaling documentation: live changes to `workers` are not
+  supported in either direction. During scale-up, old and new forks otherwise
+  race to publish different expected counts; during scale-down, retired slots
+  remain expected.
+- Strengthen the release gate with floor-version coverage, style checks, tag
+  ancestry validation, and a packaged-executable smoke test.
+- Include `.yardopts` in the gem so RubyDoc builds the intended README and
+  public guide set from the packaged release.
+
 ## [0.1.0] - 2026-09-08
 
 ### Added
@@ -18,4 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   [docs/](https://github.com/PoroshkinaVV/kicks_liveness/tree/main/docs); start
   with `SETUP.md`, and read `LIMITATIONS.md` before relying on it.
 
+[Unreleased]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/PoroshkinaVV/kicks_liveness/releases/tag/v0.1.0

data/README.md

@@ -1,119 +1,75 @@
 # kicks_liveness
 
-A liveness probe for [Kicks](https://github.com/ruby-amqp/kicks) workers (and
-for its predecessor Sneakers): the worker itself publishes a liveness mark to
-tmpfs, and the probe only reads it.
+[![Gem Version](https://badge.fury.io/rb/kicks_liveness.svg)](https://rubygems.org/gems/kicks_liveness)
+[![CI](https://github.com/PoroshkinaVV/kicks_liveness/actions/workflows/ci.yml/badge.svg)](https://github.com/PoroshkinaVV/kicks_liveness/actions/workflows/ci.yml)
 
-## Documentation
+![kicks_liveness — Kicks and Sneakers worker health](https://raw.githubusercontent.com/PoroshkinaVV/kicks_liveness/main/assets/github-social-preview.png)
 
-- [docs/SETUP.md](docs/SETUP.md) — installation and wiring: Rails, Sinatra,
-  Hanami, Roda, and no framework at all; what `install!` does and when to call
-  it.
-- [docs/DESIGN.md](docs/DESIGN.md) — why the gem is built this way: the health
-  predicate, the mark files, slots instead of PIDs, where the hooks attach, what
-  is configurable and why `dir` and `max_age` live in the environment only.
-- [docs/KUBERNETES.md](docs/KUBERNETES.md) — the manifest, the budget
-  arithmetic, verifying on a live pod, the alert on consumers.
-- [docs/LIMITATIONS.md](docs/LIMITATIONS.md) — where the in-memory predicate
-  stops being truthful.
-- [docs/VERIFYING.md](docs/VERIFYING.md) — the runbook that causes the real failures on a local cluster: what was observed, and how long each took.
-
-## Why
-
-The usual implementation is a rake task that boots Rails and asks RabbitMQ for
-`consumer_count`. It has three defects that cannot be fixed in place:
-
-1. **It is expensive.** Booting Rails every few seconds inside the worker's own
-   cgroup. On one real service this cost 2.7 s per invocation on a 15 s
-   period — 38% of the container's CPU request, around the clock.
-2. **It depends on the disk.** A disk that stalls for a few seconds stretches
-   the boot past `timeoutSeconds`, and the kubelet kills a healthy pod.
-3. **It cascades.** A liveness probe that checks an external dependency turns a
-   broker hiccup into every replica restarting at once, finishing the broker off.
-
-On top of that, `consumer_count` is a metric of the **queue**, not of the pod:
-with two replicas the live one covers for the stalled one, and the probe cannot
-tell.
-
-This gem inverts that. Every 10 seconds the worker checks, against the Bunny
-objects **in its own memory**, that its consumers are in place, and touches a
-file. The standard probe invocation took 156 ms in the fixture container, makes
-no network call, boots no framework, and reads the state it judges from tmpfs,
-which is RAM. It does still load Bundler, the interpreter and the gem's probe
-files from the image filesystem, so the disk is not out of the picture
-altogether — it is reduced to a small process startup instead of a full
-application boot on every probe.
-
-## Installation
+**Know when a [Kicks](https://github.com/ruby-amqp/kicks) or
+[Sneakers](https://github.com/jondot/sneakers) worker is stuck — without booting
+Rails or querying RabbitMQ from the probe.**
 
-```ruby
-gem 'kicks_liveness'
-```
+The worker checks its own Bunny consumers and publishes a heartbeat to tmpfs.
+The probe only reads that heartbeat, scoped to the current container
+incarnation. No application boot, no network call, and no healthy replica
+hiding a stalled one.
 
-You need `kicks` (>= 3.0) **or** `sneakers` (>= 2.11). Neither is declared as a
-dependency of this gem, on purpose: at runtime only the `Sneakers` namespace is
-required, and both gems provide it. If neither is present, `install!` raises a
-`LoadError` naming both. Both floors are exercised in CI at their exact
-versions, not just through a `~>` that resolves to the newest release.
+That restart scoping assumes Kubernetes' default container-private PID
+namespace; see
+[Limitations](docs/LIMITATIONS.md#container-generations-require-linux-procfs-and-container-owned-pid-1)
+for pods that set `shareProcessNamespace` or `hostPID`.
 
-Keeping both gems in one `Gemfile` is **not** allowed, and nothing enforces
-that: not Bundler, not a crash at boot. Both own the file `lib/sneakers.rb`, so
-one silently wins the load path. An application that has moved to `kicks` would
-keep executing `sneakers` 2.12 code while its `Gemfile.lock` claims otherwise.
-`sneakers` also caps the `kicks` and `bunny` versions.
+## Install: one line in Rails
 
-The gem installs its hooks itself through a Railtie. Outside Rails, call
-`KicksLiveness.install!` before the runner starts: the tie to Rails is a single
-conditionally required file; it is not loaded outside Rails, and no Rails code is
-pulled in. The details, including the one genuine restriction — workers must be
-started through `Sneakers::Runner` — are in [docs/SETUP.md](docs/SETUP.md).
+```ruby
+# Gemfile — keep exactly one of kicks or sneakers alongside it
+gem 'kicks_liveness'
+```
 
-### Initializer
+```bash
+bundle install
+```
 
-Optional. For example, a Rails application can disable the monitor locally:
+In Rails, that is all the application-side setup: the Railtie installs the hooks
+automatically. Without Rails, add two lines before `Sneakers::Runner` starts:
 
 ```ruby
-KicksLiveness.configure do |config|
-  config.enabled = !Rails.env.local?
-end
+require 'kicks_liveness'
+KicksLiveness.install!
 ```
 
-The full list: `logger` (defaults lazily to `Sneakers.logger`), `enabled`,
-`tick` (10 s), `startup_grace_ticks` (6).
-A non-positive `tick` raises `ArgumentError`: the monitor thread sleeps on it,
-so a non-positive value is not a setting but a broken monitor.
+Requirements: Ruby >= 3.1 and exactly one of `kicks` >= 3.0 or `sneakers` >=
+2.11. CI pins both floors and tracks the current release of both worker lines.
+Do not put both worker gems in the same bundle: both provide
+`lib/sneakers.rb`, so `install!` rejects that ambiguous process.
+Framework-specific examples are in [Setup](docs/SETUP.md).
+
+## Why replace the usual probe?
 
-### Environment variables
+The common alternative is a rake task that boots the application and asks
+RabbitMQ for `consumer_count`.
 
-| Variable | Default | |
+| | Rails + `consumer_count` probe | `kicks_liveness` |
 |---|---|---|
-| `KICKS_LIVENESS_DIR` | `/opt/app/tmp/health` | marks directory, **must live on tmpfs** |
-| `KICKS_LIVENESS_MAX_AGE` | `45` | seconds after which a mark is stale |
-| `KICKS_LIVENESS_TICK` | `10` | interval between ticks |
-
-`tick` is the one setting that appears in both places; the initializer wins over
-the variable, and only the worker reads it either way.
-
-**Two runners in one pod need two directories.** An application that runs both
-`rake sneakers:run` and `rake sneakers:active_job` has two supervisors, each
-numbering its forks from zero — so with the default `KICKS_LIVENESS_DIR` they
-would overwrite each other's `expected` and `worker-0`, and the probe would
-answer for whichever wrote last. In separate pods, which is the usual
-arrangement, there is nothing to do: each gets its own `emptyDir`. In one pod,
-give each runner its own `KICKS_LIVENESS_DIR`.
-
-`dir` and `max_age` deliberately **cannot** be set in the initializer. The probe
-is launched by the kubelet as a separate process, which does not — and cannot —
-read the application's initializer. Were they settable in two places, a
-mismatch between the worker and the probe would pass unnoticed.
-
-Garbage in a value does not bring the worker down — it falls back to the default.
-An empty string counts as unset: in a ConfigMap that is what you get by
-declaring a key and leaving it blank. `max_age` and `tick` are durations, so
-zero and negative values fall back too: they parse perfectly well, and a
-negative `max_age` would make every mark stale on arrival.
-
-## Manifest
+| Code started on every probe | Rails and the application | Ruby, Bundler, and the probe files |
+| Network call | RabbitMQ request | none |
+| Health scope | a queue shared by every replica | this worker process |
+| Decision path | application files plus RabbitMQ | process memory plus a tmpfs heartbeat |
+| Measured invocation | **2.7 s of CPU** on a real service | **156 ms** in the fixture container |
+| Continuous cost in the measured setups | **~0.18 core** at a 15 s period | **~0.005 core** at a 30 s period |
+| During Bunny network recovery | may restart every replica together | stays healthy while Bunny reconnects |
+
+Absolute timings depend on the image and hardware; the two columns are measured
+examples, not a same-host microbenchmark. The calculation and faster 52 ms and
+~10 ms probe forms are documented in [Running under Kubernetes](docs/KUBERNETES.md#why-the-command-looks-like-that).
+
+Every 10 seconds by default, each worker verifies that all expected consumers
+are subscribed and touches its own mark. `bundle exec kicks-liveness` exits 0
+only when every expected worker mark is present and fresh.
+
+## Kubernetes
+
+Use a startup probe for the boot budget and a liveness probe for steady state:
 
 ```yaml
         startupProbe:
@@ -131,7 +87,7 @@ negative `max_age` would make every mark stale on arrival.
       terminationGracePeriodSeconds: 60
 ```
 
-The marks directory has to be on tmpfs:
+Put the heartbeat directory on tmpfs:
 
 ```yaml
         volumeMounts:
@@ -140,180 +96,108 @@ The marks directory has to be on tmpfs:
       volumes:
         - name: app-tmp
           emptyDir:
-            medium: Memory        # without this the mark lands on disk
+            medium: Memory
 ```
 
-The container needs a writable volume mounted at, or above,
-`KICKS_LIVENESS_DIR`. The default mount at `/opt/app/tmp` covers
-`/opt/app/tmp/health`, and the gem creates the `health` subdirectory itself.
-Without this mount, a container using `readOnlyRootFilesystem: true` cannot
-publish heartbeat files and never passes the startup probe.
-
-Why it looks like this:
-
-- **`bundle exec kicks-liveness` is the standard command**, and it works
-  regardless of where Bundler installed the gems. There is a faster form —
-  `ruby -e "require 'kicks_liveness/probe'"`, 52 ms against
-  156 ms — but it needs the gems to be in `GEM_HOME`, and **setting
-  `BUNDLE_PATH` at all moves them**, even to the directory `GEM_HOME` already
-  points at. Check before you optimise:
-
-  ```bash
-  docker run --rm your-image bundle exec kicks-liveness
-  docker run --rm your-image ruby -e "require 'kicks_liveness/probe'"
-  ```
-
-  Both should print `no .../expected` and exit 1. If the second raises
-  `LoadError`, keep the standard command — at `periodSeconds: 30` it costs about
-  0.005 of a core, against roughly 0.18 for a probe that boots the application.
-  The trade-offs are in
-  [docs/KUBERNETES.md](docs/KUBERNETES.md#where-your-image-puts-its-gems).
-
-- **`startupProbe` is mandatory.** Startup and steady state have different time
-  budgets, and one probe cannot serve both. While it runs, liveness is disabled
-  and the container is not Ready. `failureThreshold: 60` buys 300 s, which is
-  deliberately generous — measure a *freshly created* pod before trimming it, as
-  a restarted container inherits a warm compile cache and a new pod does not:
-  [measure the cold start](docs/KUBERNETES.md#measure-the-cold-start-not-the-restart).
-- **It also protects rollouts — given `maxUnavailable: 0`.** Because the
-  container is not Ready until the mark exists, a `RollingUpdate` that is not
-  allowed to drop below full capacity cannot remove the old pod before the new
-  one has subscribed. That is a property of the strategy as much as of the probe:
-  with a non-zero `maxUnavailable`, or with `Recreate`, the old pod may go first
-  and leave the queue uncovered.
-- **`initialDelaySeconds` on liveness is unnecessary**; the startupProbe plays
-  that role.
-- Before a kill there is `max_age + periodSeconds × failureThreshold` = 45 + 90 =
-  **135 s** of confirmed silence. Slow on purpose: a worker is not
-  latency-critical, and a false restart costs more than two minutes of stalling.
-
-## Required companion: an alert on consumers
-
-The probe deliberately reports healthy while Bunny is reconnecting — otherwise a
-broker hiccup would restart every replica at once. The price is that **broker
-unavailability stops being visible automatically**. A pod can be consuming
-nothing and look perfectly healthy.
-
-So the probe needs an alert alongside it, and that alert should be in place
-**before** the manifest is switched over:
+The default heartbeat directory is `/opt/app/tmp/health`; the gem creates the
+`health` subdirectory. The mount is also required with
+`readOnlyRootFilesystem: true`.
 
-```yaml
-- alert: QueueWithoutConsumers
-  expr: rabbitmq_detailed_queue_consumers{queue=~"myapp\..+", queue!~".*delayed_active_job.*"} == 0
-  for: 5m
-
-# Not optional: the expression above cannot fire when the series is gone.
-- alert: QueueConsumerMetricMissing
-  expr: absent_over_time(rabbitmq_detailed_queue_consumers{queue=~"myapp\..+"}[10m])
-  for: 5m
-```
+With the values above, confirmed silence lasts at most `45 + 30 × 3 = 135 s`
+before Kubernetes kills the container. Size the startup budget from fresh-pod
+measurements, not warm restarts. See [the full manifest and budget
+arithmetic](docs/KUBERNETES.md).
 
-Excluding the delayed queues is mandatory — they have no consumers by design, and
-without the exclusion the alert fires permanently until someone silences it.
-Match them as a **substring**: under ActiveJob the full name looks like
-`myapp.active_job.myapp.delayed_active_job:60`, so an anchored pattern never
-matches.
+## Configuration
 
-Two traps in getting that metric, both measured on RabbitMQ 3.13.7 rather than
-recalled. The per-queue series is `rabbitmq_detailed_queue_consumers`, and it
-only exists on `/metrics/detailed` **scraped with `family=queue_consumer_count`**
-— bare, that endpoint serves no queue metrics at all, while plain `/metrics`
-offers a same-sounding `rabbitmq_queue_consumers` that is a single label-less
-cluster total, so a `{queue=~...}` matcher against it is quietly never true. And
-the series **disappears** rather than going to zero when the queue is deleted or
-the broker stops, which is why the second alert is there.
-[docs/KUBERNETES.md](docs/KUBERNETES.md#getting-that-metric-at-all) has the
-scrape config.
+Everything is optional. Application settings belong in an initializer:
 
-## What is checked
+```ruby
+KicksLiveness.configure do |config|
+  config.enabled = !Rails.env.local?
+end
+```
 
-The mark is written only if **every** worker in the process has subscribed:
+| Ruby setting | Default | Purpose | Valid values |
+|---|---|---|---|
+| `logger` | `Sneakers.logger`, resolved lazily | transition and error logs | logger-compatible object |
+| `enabled` | `true` | start the monitor thread | `true` or `false` |
+| `tick` | `10` | seconds between worker checks | positive number smaller than `max_age` |
+| `startup_grace_ticks` | `6` | unhealthy startup ticks before one ERROR | positive integer |
 
-| State | Verdict |
-|---|---|
-| consumers in place, channel open | healthy |
-| Bunny is recovering the connection | **healthy** — the broker heals itself |
-| connection open, no consumers | unhealthy, a restart is the cure |
-| not the whole set subscribed | unhealthy |
+The separate probe cannot read an application initializer. The shared path and
+freshness threshold therefore come from the environment; `tick` may use the
+environment too:
 
-The expected consumer count comes from `config[:worker_classes]` — the same set
-kicks itself builds its workers from. That way the queue list is never
-duplicated and cannot drift from the configuration.
+| Environment variable | Default | Purpose | Invalid or blank value |
+|---|---|---|---|
+| `KICKS_LIVENESS_DIR` | `/opt/app/tmp/health` | heartbeat directory; must be on tmpfs | uses the default |
+| `KICKS_LIVENESS_MAX_AGE` | `45` | seconds before a mark is stale | uses the default |
+| `KICKS_LIVENESS_TICK` | `10` | seconds between worker checks | uses the default, then the safety fallback below if needed |
 
-The files are named by supervisor slot rather than by PID: a dead fork is
-respawned into the same slot and overwrites its own file. With a PID in the
-name, SIGKILL would leave a stale file forever. With `workers > 1` the probe
-requires every slot to be fresh.
+If the effective environment tick is not smaller than `max_age`, the worker
+writes a WARN to stderr and uses `10` seconds when that is safe, or half of
+`max_age` otherwise. This keeps a ConfigMap mistake from stopping the worker
+while guaranteeing that a healthy heartbeat cannot become stale between
+ordinary ticks.
 
-## Limitations
+An initializer value for `tick` wins over `KICKS_LIVENESS_TICK`. `dir` and
+`max_age` deliberately have no initializer setters: allowing two configuration
+sources could make the worker and probe silently disagree.
 
-The predicate is computed over the Bunny objects **in the process's memory** —
-that is the whole point, but it has a boundary: it is exactly as truthful as
-Bunny's own bookkeeping. The broker is never asked for its opinion.
+If two runners share one pod — for example `sneakers:run` and
+`sneakers:active_job` — give each a different `KICKS_LIVENESS_DIR`. Separate
+pods already have separate `emptyDir` volumes.
 
-**1. Consumer bookkeeping is updated on the worker's thread pool.** When the
-broker cancels a consumer (on `consumer_timeout`, for example), it sends
-`basic.cancel`, and Bunny removes the entry from its list — but it does so
-through `@work_pool.submit`, that is, on the same pool that processes jobs
-(`threads: 10` by default). Until a thread frees up, `any_consumers?` still
-answers yes.
+## What is healthy?
 
-In practice this means: if **all** of the worker's threads are busy with stuck
-jobs, the probe stays green even though the pod is consuming nothing. One stuck
-job out of ten does not produce that effect.
+| Worker state | Probe verdict | Reason |
+|---|---|---|
+| every consumer subscribed, channel open | healthy | the process can consume work |
+| Bunny recovering its connection | **healthy** | Bunny reconnects itself; restarting adds a reconnect storm |
+| connection open, no consumers | unhealthy | a restart is the cure |
+| only part of the expected worker set subscribed | unhealthy | one healthy worker must not hide a missing one |
+
+The check reads Bunny objects already in the worker's memory. It never asks the
+broker for its view.
 
-**2. `recover_cancelled_consumers!` makes the probe blind to a cancelled
-consumer.** `Bunny::Channel#recover_cancelled_consumers!` is an opt-in method
-that neither Kicks nor Sneakers enables. With it on, Bunny re-subscribes the
-consumer itself on `basic.cancel` and **keeps** the entry in its list — so the
-"consumer was cancelled" case stops being detectable at all. Do not enable it
-together with this probe.
+## Operational contract
 
-**3. Broker unavailability is invisible by design** — see [the alert on
-consumers](#required-companion-an-alert-on-consumers) above.
+- Start workers through `Sneakers::Runner`; that is where the monitor hook is
+  attached. `rake sneakers:run` already does this.
+- Keep the `startupProbe`. With `RollingUpdate` and `maxUnavailable: 0`, it also
+  keeps the old pod until the new worker has subscribed.
+- Add an external alert for queues with zero or missing consumers **before**
+  switching probes. Broker unavailability is invisible here by design; the
+  exact Prometheus rules are in [Running under Kubernetes](docs/KUBERNETES.md#required-companion-an-alert-on-consumers).
+- Restart the runner after changing its process count; changing `workers` at
+  runtime is not supported.
 
-All three limitations point the same way: an alert on consumers, watching the
-broker **from the outside**, is not a nice-to-have but part of the design. It
-catches exactly what an in-memory predicate cannot see.
+The other boundaries — blocked worker pools, cancelled-consumer recovery, and
+per-pod versus per-queue scope — are collected in [Limitations](docs/LIMITATIONS.md).
 
-## Verifying on a live pod
+## Verify it
 
 ```bash
 kubectl exec deploy/myapp -- ls -l /opt/app/tmp/health/
 kubectl exec deploy/myapp -- sh -c 'bundle exec kicks-liveness; echo "exit=$?"'
-kubectl logs deploy/myapp | grep liveness
 ```
 
-Check the **negative** path too — otherwise a working probe is
-indistinguishable from an always-green one:
-
-```bash
-kubectl exec deploy/myapp -- sh -c 'touch -d "2 minutes ago" /opt/app/tmp/health/worker-0; bundle exec kicks-liveness; echo "exit=$?"'
-```
+The healthy result is `N process(es) healthy` with exit code 0. Also test the
+negative path before rollout; the commands and expected output are in
+[Verifying the probe](docs/VERIFYING.md#2-a-stale-mark).
 
-Expect `worker-0 stale 120s > 45s` and `exit=1`. One tick later the mark repairs
-itself.
+## Documentation
 
-## Logs
+| Guide | Use it for |
+|---|---|
+| [Setup](docs/SETUP.md) | Rails, Sinatra, Hanami, Roda, standalone runners, and hook verification |
+| [Design](docs/DESIGN.md) | health predicate, heartbeat files, hooks, configuration choices, and measurements |
+| [Running under Kubernetes](docs/KUBERNETES.md) | full manifest, CPU/startup budgets, alerts, and live-pod verification |
+| [Limitations](docs/LIMITATIONS.md) | cases the in-memory predicate intentionally cannot cover |
+| [Verification scenarios](docs/VERIFYING.md) | eleven deliberately induced failures and their observed outcomes |
 
-Events are logged, not the pulse: the pulse lives in the mark's mtime.
+## Contributing
 
-| Event | Level |
-|---|---|
-| started, with the effective settings | INFO |
-| waiting for consumers | INFO |
-| became healthy | INFO |
-| shutting down | INFO |
-| still not healthy after `startup_grace_ticks` ticks | ERROR |
-| was healthy, became unhealthy | ERROR |
-| a slot respawning without ever becoming healthy, once per grace window | ERROR |
-| the monitor thread caught an exception | ERROR |
-| the monitor could not be started at all | ERROR |
-
-ERROR is reserved for genuine failure: a logger usually comes up with
-`LOG_LEVEL` defaulting to `error`, so anything that matters must survive that
-filter, while an ordinary deploy must not make noise. That is also why shutdown
-is an event of its own: the workers unsubscribe while the thread pool drains,
-and judged by the consumer count alone a normal deploy would look exactly like
-a fault. From the moment shutdown begins the probe keeps the mark fresh
-instead, so a slow drain gets the full `terminationGracePeriodSeconds`.
+Setup, running the suite against both worker gems, and the release procedure are
+in [CONTRIBUTING.md](https://github.com/PoroshkinaVV/kicks_liveness/blob/main/CONTRIBUTING.md).