ruby_reactor 0.8.2 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31b3ac286396e1d29f1bad40e87f4f55b8ecc3e6c715e6cfd2ca0496d9c8dd0c
-  data.tar.gz: d518e5aceb0e5fa6dd43007e1f324612c84a53528e73a76463db7ecb652f0a95
+  metadata.gz: ac772fc307621dcf2fba69d726aeb670a34201a0c06e17e1e9213b4779f4cd03
+  data.tar.gz: 5ed6d5e4251643fc16fafaf48ecde75aa31f95cc09f9b1fe9d0b879b190fa61b
 SHA512:
-  metadata.gz: 2e91db7e2c548b834f285fe514747bc407b29fbb4cdb10e4aef44b05ff556d518ccf77ad4d02fc3e097907d7298843bc32b7e5a57d4f4a8ae687795dc702fa71
-  data.tar.gz: 6a2252e7fdf4740f1d297f2855bb60f07c4b66e0a551c8d90e4394fd1acafd829098323d40afb4f9bc650c76a53818d76566c70f65c89c4b60ed11f9018a3d48
+  metadata.gz: c61a1ec89ce310154e5bd9d2b09c3dc997e682a83d1bb5b18a87d47128f792133e27e7c8648db699cbfa5de8830522dad9bdfbb7b953addf89273fa3eb3042e0
+  data.tar.gz: b78511087cfccec3eb6912000c3d744fa0f1cabca1f87eed9a500d223eb2aa4e6d1e4219a85eb2c6774f54e14493179d3c86ba836e4012cf9a86ec3a553955c1

data/.claude/skills/speckit-review/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: "speckit-review"
+description: "Review the code changes produced by /speckit-implement against RubyReactor's runtime invariants: saga unwind/compensation/undo, retry semantics, async isolation, lock safety without deadlock, validation ordering, and the behavioral claims made in README/documentation."
+argument-hint: "Optional: review scope (e.g. 'locks only', a path, or a git ref to diff against)"
+compatibility: "Requires spec-kit project structure with .specify/ directory and a git repository"
+metadata:
+  author: "project"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty). Treat it as a scope
+narrowing hint only — it MAY reduce which files are inspected, it MUST NOT disable any gate
+below for files that remain in scope.
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before review)**:
+
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_review` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` → `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+
+    ```text
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+
+  - **Mandatory hook** (`optional: false`):
+
+    ```text
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Goal.
+    ```
+
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Goal
+
+Review the **code changes** made for the current feature (normally right after
+`/speckit-implement`) and decide whether they are safe to merge. The review answers one
+question per gate, with file/line evidence, and ends in a single verdict: `PASS`,
+`PASS WITH FINDINGS`, or `BLOCKED`.
+
+This command is **read-only**. It MUST NOT edit source, specs, docs, `tasks.md`, or git
+state. Remediation is handed off to `/speckit-converge` (append tasks) or
+`/speckit-implement` (fix), not performed here.
+
+It differs from its neighbours:
+
+- `/speckit-analyze` → consistency **between artifacts** (spec/plan/tasks).
+- `/speckit-converge` → what the artifacts demand that the code does **not yet do**.
+- `/speckit-review` (this one) → whether the code that now exists is **correct, safe, and
+  honest** at runtime — saga unwind, retries, async isolation, locks, validation, and the
+  claims the docs make about all of it. Constitution/process compliance is out of scope
+  here; `/speckit-plan` and `/speckit-converge` already cover it.
+
+## Execution Steps
+
+### 1. Establish Review Scope
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks`
+from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive:
+
+- SPEC = FEATURE_DIR/spec.md, PLAN = FEATURE_DIR/plan.md, TASKS = FEATURE_DIR/tasks.md
+
+These are context for *what the change was meant to do* — the gates below judge the code,
+not the artifacts.
+
+If the prerequisites script fails (no active feature), do **not** stop: fall back to a
+pure diff review and say so in the report header — none of the gates below require spec
+artifacts.
+
+Compute the change set:
+
+```bash
+git rev-parse --abbrev-ref HEAD
+git merge-base HEAD main
+git diff --stat $(git merge-base HEAD main)...HEAD
+git diff $(git merge-base HEAD main)...HEAD
+git status --porcelain          # uncommitted work is in scope too
+```
+
+If the user supplied a git ref in `$ARGUMENTS`, diff against that instead of `main`.
+Read the **full current content** of every non-trivially changed file under `lib/` —
+a diff hunk alone is not enough to reason about unwind order or lock release paths.
+
+Load `README.md` and the files under `./documentation/` that cover the touched areas
+(`DAG.md`, `background_and_async.md`, `locks_and_semaphores.md`, `retry_configuration.md`,
+`interrupts.md`, `composition.md`, `core_concepts.md`, `testing.md`).
+
+### 2. Run the Gates
+
+Every gate produces: `PASS`, `FINDING`, or `BLOCKER`, each with concrete evidence
+(`path/to/file.rb:LINE`). A gate with no changed code in its area is `N/A` — say so
+explicitly rather than silently passing it.
+
+#### G1 — Distributed Rules and Documented Claims Hold
+
+The gem is consumed as a distributed coordinator; the docs are a contract.
+
+- Every behavioral claim in `README.md` and `./documentation/` that touches changed code is
+  still literally true. Quote the claim, then cite the code that satisfies or breaks it.
+  A claim the code no longer honors is a **BLOCKER** (fix the code or fix the claim —
+  the report says which, it does not do either).
+- Multi-process correctness: no state that must be shared lives in a process-local ivar,
+  class variable, or memoized constant where a second worker process would miss it;
+  Redis keys carry the discriminators (reactor/step/run/lock identity) needed to avoid
+  cross-run or cross-worker collision; TTLs exist wherever a crashed process would
+  otherwise leak a key.
+- Crash safety: for each new Redis write, ask what happens if the process dies
+  immediately before and immediately after it. A window that strands a run with no
+  sweeper/recovery path (`step_sweeper.rb`, `sweeper.rb`) is a BLOCKER.
+- Serialization: anything crossing a process boundary round-trips through
+  `context_serializer.rb` without silent loss (watch `false`/`nil` handling, symbol vs
+  string keys, and context size limits).
+
+#### G2 — Saga Robustness: Predictable Unwind, Compensation, Undo
+
+The core promise of the library: a run either completes or unwinds cleanly. For every step
+touched or added:
+
+- A step producing a side effect declares rollback (`compensate`/`undo`) — and the
+  reviewed code actually routes failures into it.
+- **Unwind order is deterministic**: compensation runs in reverse completion order per the
+  DAG, and is reproducible across runs of the same failure. Any dependence on hash order,
+  thread completion order, or wall-clock ordering is a BLOCKER.
+- **Compensation is idempotent and re-entrant**: running it twice (crash mid-unwind, then
+  sweeper retry) leaves the same state.
+- A failure *inside* compensation/undo is handled explicitly (`compensation_error.rb`,
+  `undo_error.rb`) — never swallowed, never allowed to abort the remaining unwind silently.
+- No orphaned steps: a step that started cannot end with neither a result nor a
+  compensation record. Partial execution with no recovery path is forbidden.
+- Interrupts/pause/resume remain first-class: a paused run resumes to the same DAG position
+  with the same context, and unwinding a paused or resumed run compensates exactly the
+  steps that actually ran — not more, not fewer.
+- Async steps that fail after dispatch still reach compensation of their upstream steps.
+
+#### G3 — Retries Do What They Claim
+
+- Retry counting is per-step and survives process boundaries (`retry_context.rb`,
+  `retry_queued_result.rb`); a retry that re-enters through a worker does not reset the
+  counter or double-count it.
+- `max_retries` exhaustion produces `max_retries_exhausted_failure.rb` and then flows into
+  the same compensation path as any other failure.
+- Backoff/delay semantics match `documentation/retry_configuration.md` exactly (units,
+  first-attempt-vs-retry counting, jitter, caps).
+- A retried step re-acquires whatever locks/semaphores/rate-limit tokens it needs, and
+  releases those from the failed attempt first — no token or lock leak per retry.
+- Retries do not re-run already-successful upstream steps and do not skip validation.
+- Retry of a step with side effects either compensates the failed attempt first or is
+  documented as idempotent — whichever the docs claim, the code must do.
+
+#### G4 — Async Reactors and Steps Are Isolated
+
+- No shared mutable state between concurrently executing steps: context writes are
+  per-step and merged, not mutated in place across threads/processes.
+- An async step's failure is contained — it fails its own step and the run's declared
+  policy, and cannot corrupt or cross-talk into a sibling async step or another reactor
+  run (`executor/async_step_dispatch.rb`, `async_waiter.rb`, `step_worker.rb`).
+- Job payloads carry full identity (run id, step name, attempt) so a worker cannot act on
+  the wrong run; late/duplicate job delivery is a no-op, not a second execution.
+- Waiting is bounded: every wait has a timeout path (`async_wait_timeout_error.rb`) and
+  `async_result_pending.rb` handling that cannot park forever.
+- Adapter isolation holds: `adapters/sidekiq` and `adapters/active_job` stay
+  interchangeable; no adapter-specific behavior leaks into the executor.
+
+#### G5 — Locks Protect Resources Without Deadlocking
+
+Covers `lock.rb`, `ordered_lock.rb`, `semaphore.rb`, `rate_limit*.rb`, `period.rb`,
+`dsl/lockable.rb`, and this feature's independent step-lock work.
+
+- Every acquire has a release on **all** paths: success, failure, compensation, undo,
+  exception, pause, and process crash (TTL). Show the release path for each new acquire.
+- **Deadlock freedom**: multi-lock acquisition follows one global deterministic order
+  (that is what `ordered_lock.rb` is for) — no step acquires A-then-B while another can
+  acquire B-then-A. Any new acquisition site must be shown to respect the order.
+- No lock is held across an async dispatch or a blocking wait unless that is explicitly
+  designed, documented, and TTL-bounded.
+- Ownership tokens: release only releases a lock this run still owns (fencing/ownership
+  check), so a TTL-expired holder cannot release a lock now held by someone else.
+- Semaphore/rate-limit accounting cannot drift: crashed holders are reclaimed, and
+  double-release cannot inflate available tokens.
+- Behavior matches `documentation/locks_and_semaphores.md` (blocking vs non-blocking,
+  timeout, what a contended run returns).
+
+#### G6 — Validations Predictable and Run Before `run`
+
+- Input validation executes **before** the step's `run` body — always, including on retry,
+  resume-from-pause, and async re-entry paths. A path that reaches `run` with unvalidated
+  input is a BLOCKER.
+- Validation failures produce `input_validation_error.rb` / `validation_error.rb` as
+  failures with the documented shape — never exceptions escaping the executor, never a
+  silent skip.
+- A validation failure produces **no side effects** and unwinds any already-completed steps
+  per G2.
+- dry-validation schemas stay inside the reactor/step DSL (`dsl/validation_helpers.rb`,
+  `validation/`), not scattered into application code.
+- Validation is deterministic: same input → same outcome, no I/O, no clock, no network
+  inside a schema.
+- Defaults/coercions applied by validation are visible to `run` and to serialization
+  consistently (this is where `false`/`nil` bugs hide).
+
+### 3. Verify Dynamically Where Cheap
+
+Evidence beats reasoning. When the change touches runtime behavior, run what already
+exists rather than asserting:
+
+```bash
+bundle exec rubocop
+bundle exec rspec <specs covering the changed area>
+```
+
+For user-facing behavior, run it end to end against real Redis:
+`docker compose run --rm demo-app bin/rails demo:<task>` (or `/demo-app-e2e-verify`).
+Report command output honestly — a failing or skipped check is a finding with its output
+quoted, never "should pass". If a check is not run, say which and why.
+
+### 4. Report
+
+Output in-session (no file writes):
+
+```markdown
+## Review — <feature> (<base>...<head>)
+
+**Verdict**: BLOCKED | PASS WITH FINDINGS | PASS
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| G1 Distributed + claims | BLOCKER | documentation/locks_and_semaphores.md:88 claims X; lib/ruby_reactor/lock.rb:142 does Y |
+| G2 Saga unwind/compensation | ... | ... |
+| G3 Retries | ... | ... |
+| G4 Async isolation | ... | ... |
+| G5 Locks / deadlock | ... | ... |
+| G6 Validations | ... | ... |
+
+### Findings
+
+**[BLOCKER] F1 — <one-line defect>** (G5, `lib/ruby_reactor/lock.rb:142`)
+Failure scenario: <concrete interleaving/inputs → wrong state or hang>
+Fix: <smallest change that closes it>
+
+### Checks Run
+- `bundle exec rubocop` → <result>
+- `bundle exec rspec …` → <result>
+- not run: <what, why>
+```
+
+Rules for the report:
+
+- Order findings BLOCKER → FINDING, most severe first.
+- Every finding names a **concrete failure scenario** (interleaving, crash point, or input
+  that produces the wrong result). A finding that cannot state one is speculation — drop it.
+- No finding without a file:line. No gate row without either evidence or `N/A`.
+- Verdict is `BLOCKED` if any gate is a BLOCKER, `PASS WITH FINDINGS` if only findings
+  remain, `PASS` only when every in-scope gate passed **and** the checks in Step 3 ran.
+
+### 5. Handoff
+
+- `BLOCKED` / `PASS WITH FINDINGS`: recommend `/speckit-converge` to append the remediation
+  work as traceable tasks, then `/speckit-implement`. Do not fix anything here.
+- `PASS`: recommend proceeding to PR, carrying the gate table into the PR description as
+  the reviewer-facing evidence.
+
+### 6. Check for extension hooks
+
+After producing the report, check if `.specify/extensions.yml` exists in the project root.
+
+- If it exists, read it and look for entries under the `hooks.after_review` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` → `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+
+    ```text
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+
+  - **Mandatory hook** (`optional: false`):
+
+    ```text
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.2"
+  ".": "0.8.3"
 }

data/.specify/extensions.yml

@@ -21,3 +21,13 @@ hooks:
     prompt: Execute speckit.agent-context.update?
     description: Refresh agent context after planning
     condition: null
+  after_implement:
+  - extension: project
+    command: speckit.review
+    enabled: true
+    optional: false
+    priority: 10
+    prompt: Execute speckit.review?
+    description: Review the implemented changes against RubyReactor
+      runtime invariants (saga, retries, async isolation, locks, validation, documented claims)
+    condition: null

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/004-inheritable-step-class"
+  "feature_directory": "specs/005-step-coordination-remediation"
 }

data/.specify/workflows/speckit/workflow.yml

@@ -4,7 +4,7 @@ workflow:
   name: "Full SDD Cycle"
   version: "1.0.0"
   author: "GitHub"
-  description: "Runs specify → plan → tasks → implement with review gates"
+  description: "Runs specify → plan → tasks → implement → review with review gates"
 
 requires:
   # 0.8.5 is the first release with engine-side resolution of the
@@ -75,3 +75,15 @@ steps:
     integration: "{{ inputs.integration }}"
     input:
       args: "{{ inputs.spec }}"
+
+  - id: review
+    command: speckit.review
+    integration: "{{ inputs.integration }}"
+    input:
+      args: "{{ inputs.spec }}"
+
+  - id: review-gate
+    type: gate
+    message: "Review findings above (constitution + saga/retry/async/lock/validation gates). Approve to finish, reject to send remaining work back through converge/implement."
+    options: [approve, reject]
+    on_reject: abort

data/.specify/workflows/workflow-registry.json

@@ -4,10 +4,10 @@
     "speckit": {
       "name": "Full SDD Cycle",
       "version": "1.0.0",
-      "description": "Runs specify \u2192 plan \u2192 tasks \u2192 implement with review gates",
+      "description": "Runs specify → plan → tasks → implement → review with review gates",
       "source": "bundled",
       "installed_at": "2026-06-23T23:29:12.184843+00:00",
       "updated_at": "2026-06-23T23:29:12.184848+00:00"
     }
   }
-}
+}

data/CHANGELOG.md

@@ -80,6 +80,19 @@
 
 ### Features
 
+* **Step-scoped coordination.** Steps can declare `with_lock`, `with_semaphore`, `with_rate_limit`,
+  `with_period`, and `with_ordered_lock` — the same macros as the reactor form, keyed on the step's
+  own resolved arguments instead of the reactor's inputs — so one step of a workflow can be
+  serialized (or rate-limited, deduped, or strictly ordered) without serializing the whole
+  workflow. Works on class steps and inline `step :x do ... end` blocks (or both on one step —
+  taken once, in one fixed order); a direct `MyStep.run(args)` call is protected too, as its own
+  unit of work that waits then fails. Contention parks the execution in a worker (bounded by
+  `lock_snooze_max_attempts`, never consuming the step's own `retries` budget; the parked step
+  releases what it took and never spends a rate-limit slot on a park) and waits-then-fails
+  synchronously. Re-entrancy, the async dispatch deadlock guard, and rollback
+  (`compensate`/`undo` re-take lock/semaphore only) all follow the same rules as reactor-level
+  coordination. See
+  [Step-Scoped Coordination](documentation/locks_and_semaphores.md#step-scoped-coordination).
 * **Step input contracts.** A step class declares its own inputs with `input :name, :type, **predicates`
   (plus `optional:`, `default:`, `redact:`, the `do |i| ... end` macro block and `validate:`) and
   cross-field rules with `validate_inputs`. The contract is enforced before `run` on every path
@@ -103,6 +116,20 @@
 * A step that returns another unit's validation failure (e.g. an `async_step` reader propagating
   the worker's `Failure`) keeps its `validation_errors` on the reactor's final failure.
 
+* **`rollback_wait:` on step `with_lock` / `with_semaphore`.** How long a step's `undo` /
+  `compensate` waits to re-take its key. Defaults to the lock's `ttl` (60 s for a semaphore);
+  rollback still never parks, so in a worker the wait blocks the thread.
+* **`Failure#rollback_failures`.** Every undo or compensation that did not complete —
+  `{ step:, kind: :undo | :compensate, key:, reason: :coordination_unavailable | :returned_failure | :raised, message: }`,
+  including composed children's (flattened). Always an Array; part of `Failure#to_h` and the
+  stored failure of a background run.
+* **`:snooze_step` middleware event** (`on_snooze_step(step_name, error, context)`): a step's
+  attempt ended in a park — it lost its own contention in a worker, or it is a `compose` step whose
+  child parked — at any nesting depth. Never `:failed_step`. A step whose own arguments wait on a
+  background result parks before it starts, so it fires neither `:start_step` nor `:snooze_step`.
+  The OpenTelemetry middleware closes the span as `step.status = "parked"`.
+* **`have_rollback_failure(step)` matcher**, with `.for_key(key)` and `.because(reason)`.
+
 ### Deprecations
 
 * Rules on `argument` (`argument :x, src, :type, **predicates`) and `validate_args` keep working
@@ -128,6 +155,61 @@
 * A class step that calls `halt!` under `async_step` is recorded as a halt rather than an
   ordinary `nil` success, and `result(:step)` hands the reader the `Halt` — the same way it
   already hands over a `Failure`.
+* Step coordination (F1): a step's undo is no longer dropped because another execution holds its
+  key at that moment — it waits up to `rollback_wait`, and one that still cannot run is reported
+  on `Failure#rollback_failures` instead of only in the trace.
+* Step coordination (F2): a park inside a composed child no longer releases the parent's reactor
+  lock or semaphore, and no longer charges the parent's rate limit again on redelivery — every
+  level keeps its own holds and is admitted once, at any depth.
+* Step coordination (F3): a synchronous execution that reaches a strict step-level ordered lock
+  out of turn fails without poisoning the chain; later arrivals run instead of being skipped.
+* Step coordination (F4): the docs name `context.coordinating_step` (not `current_step`) as the
+  attribution for coordination middleware events.
+* Step coordination (F5): a parked `async_step` no longer overwrites its parent's saved context;
+  its park state (ordered-lock position, "waiting" marker) lives on its own step result record.
+* Step coordination (F6): documented the cross-level key-ordering rule that avoids two workflows
+  waiting on each other's reactor and step locks.
+* Step coordination (F7): a step whose ordered-lock batch expired before its retry is skipped
+  (`Skipped(reason: :ordered_lock_stale_batch)`) instead of running unordered.
+* Step coordination (F8): a step-level ordered-lock heartbeat stops when the step body exits
+  abnormally (e.g. `Sidekiq::Shutdown`), so the poison pill can release the position.
+* Step coordination (F9): a step class invoked directly from another step's body names itself in
+  contention errors and coordination events, not the calling step.
+* An `async_step` no longer writes its parent's context when it finishes (it already stopped
+  doing so on a park). Its older snapshot overwrote whatever the parent saved while the unit ran —
+  a parent could revert to "running" and lose later steps' results. The unit's run (arguments,
+  attempts, start time) now lives on its Step Result Record, and the dashboard rebuilds it from the
+  parent's link, at any composition depth. `context.execution_trace` no longer has a `:run` entry
+  for an `async_step`, and changes an `async_step` body makes to `context` are not persisted.
+* A park after a fan-out map (a later step's contention, or an awaited background result) now
+  requeues the parent on its own worker instead of escaping the map collector and leaving the run
+  "running" forever; the collector also no longer re-saves the parent after resuming it, which
+  could overwrite a newer save by the parent's next worker.
+* An `async_step` refused at dispatch because it would deadlock on a key the reactor holds is no
+  longer compensated. It was never dispatched or run. The steps before it still roll back.
+* A step of a composed child that reads a not-yet-finished background result in a worker (F10)
+  parks the execution, keeping the child's lock, instead of failing the parent with
+  "async result … still pending".
+* A background reactor whose own `with_lock` / `with_semaphore` is busy when it starts no longer
+  charges its `with_rate_limit` again on every snoozed redelivery.
+* A `compensate` that raises no longer stops the rollback: the completed steps are still undone,
+  and the reactor fails with `CompensationError` and a `reason: :raised` rollback failure.
+* A composed child whose own `with_lock` / `with_semaphore` / `with_rate_limit` is busy inside a
+  worker now parks the execution and snoozes the job instead of failing the parent. After
+  `lock_snooze_max_attempts` parks it fails the `compose` step, which rolls the parent back.
+* A park that comes up through a `compose` step (the child's contention, or its wait on a
+  background result) no longer uses up that step's `retries` budget.
+* Docs: `on_snooze_step` is documented for what it covers — a step's own contention park and a
+  `compose` step whose child parked, not a step whose own arguments wait on a background result.
+* Docs: a park keeps each level's lock without a second `:lock_acquired` only while the gap stays
+  within the lock's `ttl`; a lapsed lock is acquired again.
+
+## [0.8.3](https://github.com/arturictus/ruby_reactor/compare/v0.8.2...v0.8.3) (2026-09-25)
+
+
+### Features
+
+* move locks declarations to step classes ([#56](https://github.com/arturictus/ruby_reactor/issues/56)) ([a7862ca](https://github.com/arturictus/ruby_reactor/commit/a7862ca765ae706aebb361d9eadcf4c0ead12caf))
 
 ## [0.8.2](https://github.com/arturictus/ruby_reactor/compare/v0.8.1...v0.8.2) (2026-09-22)
 

data/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
-shell commands, and other important information, read the current plan:
-`specs/004-inheritable-step-class/plan.md`
+shell commands, and other important information, read the current plan
+at specs/005-step-coordination-remediation/plan.md
 <!-- SPECKIT END -->

data/README.md

@@ -720,6 +720,23 @@ class RefundOrderReactor < RubyReactor::Reactor
   end
 end
 
+class ChargeStep < RubyReactor::Step
+  input :account_id
+
+  # All five macros also work declared on a STEP, not just the reactor —
+  # keying the critical section down to this one operation instead of the
+  # whole workflow. Surrounding steps (audit, notify, ...) keep overlapping
+  # across concurrent executions; only :charge serializes. Its undo re-takes
+  # the key, waiting up to `rollback_wait:` (default: `ttl`; 60 s for a
+  # step `with_semaphore`) — an undo that still can't run is reported on
+  # `Failure#rollback_failures`, never dropped.
+  with_lock(ttl: 60, rollback_wait: nil) { |args| "acct:#{args[:account_id]}" }
+
+  def run
+    Success(charge!(inputs))
+  end
+end
+
 class GeocodeReactor < RubyReactor::Reactor
   input :address
 
@@ -843,7 +860,7 @@ step :maybe_sync do
 end
 ```
 
-See [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, ordered-lock assignment + poison-pill semantics, and operational notes.
+See [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, ordered-lock assignment + poison-pill semantics, step-scoped coordination, and operational notes.
 
 ### Map & Parallel Execution
 
@@ -1376,6 +1393,22 @@ end
 # Result: Complete rollback of the transaction
 ```
 
+A rollback that did not complete is never silent. `Failure#rollback_failures`
+lists every undo or compensation that raised, returned a `Failure`, or could not
+re-take its step's lock/semaphore within `rollback_wait:` — including those of
+composed children (flattened). It is always an Array, empty when rollback
+completed, and is part of `Failure#to_h`:
+
+```ruby
+result = TransactionReactor.run(from_account: 1, to_account: 2, amount: 10)
+result.rollback_failures
+# => [{ step: :debit_account, kind: :undo, key: nil, reason: :raised, message: "gateway timeout" }]
+```
+
+`reason` is `:coordination_unavailable`, `:returned_failure`, or `:raised`; `kind`
+is `:undo` or `:compensate`. See
+[Step Rollback](documentation/locks_and_semaphores.md#step-rollback).
+
 ### Using Pre-defined Schemas
 
 You can use existing dry-validation schemas:
@@ -1460,7 +1493,7 @@ Comprehensive guide to testing reactors with RubyReactor's testing utilities. Le
 
 ### [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md)
 
-Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), calendar-bucketed dedup (`with_period`, returning `Halt` results), and strict sequential ordering via a monotonically increasing nonce assigned at enqueue (`with_ordered_lock`). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-background contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, once-per-day/month/year scheduling patterns, ordered-lock counter reset on drain, poison-pill timeouts, and deadlock-safe composition rules.
+Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), calendar-bucketed dedup (`with_period`, returning `Halt` results), and strict sequential ordering via a monotonically increasing nonce assigned at enqueue (`with_ordered_lock`). Every primitive is also available [declared on a step](documentation/locks_and_semaphores.md#step-scoped-coordination) instead of the whole reactor, keying the critical section down to one operation. Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, once-per-day/month/year scheduling patterns, ordered-lock counter reset on drain, poison-pill timeouts, and deadlock-safe composition rules.
 
 ### [Middlewares & OpenTelemetry](documentation/middlewares.md)
 

data/lib/ruby_reactor/adapters/active_job/router.rb

@@ -34,6 +34,25 @@ module RubyReactor
           RubyReactor::DispatchResult.new(job_id: job_id)
         end
 
+        # Delayed re-enqueue of an `async_step`'s body — the park path
+        # (Finding 6). See Sidekiq::Router#perform_step_in.
+        # rubocop:disable Metrics/ParameterLists
+        def self.perform_step_in(delay, root_context_id:, reactor_class_name:, step_context_id:, step_name:,
+                                 contention_attempts: 0)
+          # rubocop:enable Metrics/ParameterLists
+          job_id = RubyReactor::Adapters::ActiveJob::StepWorker.perform_in(
+            delay,
+            {
+              "root_context_id" => root_context_id,
+              "reactor_class_name" => reactor_class_name,
+              "step_context_id" => step_context_id,
+              "step_name" => step_name.to_s,
+              "contention_attempts" => contention_attempts
+            }
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
                                            strict_ordering:, parent_context_id:, parent_reactor_class_name:,

data/lib/ruby_reactor/adapters/sidekiq/router.rb

@@ -34,6 +34,27 @@ module RubyReactor
           RubyReactor::DispatchResult.new(job_id: job_id)
         end
 
+        # Delayed re-enqueue of an `async_step`'s body — the park path
+        # (Finding 6): the worker rescues `StepCoordination::Contended` and
+        # reschedules itself instead of failing, carrying the contention
+        # attempt count forward so `lock_snooze_max_attempts` still bounds it.
+        # rubocop:disable Metrics/ParameterLists
+        def self.perform_step_in(delay, root_context_id:, reactor_class_name:, step_context_id:, step_name:,
+                                 contention_attempts: 0)
+          # rubocop:enable Metrics/ParameterLists
+          job_id = RubyReactor::Adapters::Sidekiq::StepWorker.perform_in(
+            delay,
+            {
+              "root_context_id" => root_context_id,
+              "reactor_class_name" => reactor_class_name,
+              "step_context_id" => step_context_id,
+              "step_name" => step_name.to_s,
+              "contention_attempts" => contention_attempts
+            }
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
                                            strict_ordering:, parent_context_id:, parent_reactor_class_name:,