ruby_reactor 0.8.3 → 0.8.5

data/lib/ruby_reactor/web/public/index.html

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="./vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ui</title>
-    <script type="module" crossorigin src="./assets/index-CeZU-ESu.js"></script>
+    <script type="module" crossorigin src="./assets/index-CQbgHtd0.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-BQvIWPdx.css">
   </head>
   <body>

data/lib/ruby_reactor/worker.rb

@@ -8,7 +8,7 @@ module RubyReactor
   # `Adapters::ActiveJob::Compat` on ActiveJob::Base) — nothing here references
   # a specific backend.
   module Worker
-    TERMINAL_STATUSES = %w[completed failed cancelled skipped].freeze
+    TERMINAL_STATUSES = %w[completed failed cancelled skipped aborted].freeze
 
     # Use the error's `retry_after_seconds` hint when available
     # (RateLimit::ExceededError carries the time until the bucket rolls);
@@ -89,6 +89,8 @@ module RubyReactor
       reactor_class_name ||= RubyReactor.reactor_storage_name(nil)
       data = RubyReactor.configuration.storage_adapter.retrieve_context(context_id, reactor_class_name)
       return if data.nil?
+      # An aborted run is never resumed forward: only a manual undo applies (008 R-08).
+      return if (data["status"] || data[:status]).to_s == "aborted"
 
       begin
         context = ContextSerializer.deserialize_hash(data)

data/lib/ruby_reactor.rb

@@ -7,6 +7,7 @@ require "time"
 require_relative "ruby_reactor/registry"
 require_relative "ruby_reactor/utils/code_extractor"
 require_relative "ruby_reactor/dsl/lockable" # Add this
+require_relative "ruby_reactor/dsl/retryable"
 require_relative "ruby_reactor/lock"
 require_relative "ruby_reactor/ordered_lock"
 require_relative "ruby_reactor/semaphore"
@@ -102,10 +103,11 @@ module RubyReactor
     undef_method :skipped?
   end
 
-  # Marks a single step as skipped while the reactor continues. Behaves
-  # exactly like Success — the value flows to dependants via `result(:step)` —
-  # except `skipped?` is true and the step is not enrolled for rollback
-  # (nothing happened, so there is nothing to undo).
+  # Marks a single step as skipped: an instrumentation mark (008 R-19). The
+  # run continues exactly as for a Success — the value flows to dependants via
+  # `result(:step)`, hand-offs and period marks happen — except `skipped?` is
+  # true, the trace records it, and the step is not enrolled for undo (it had
+  # nothing to do, so there is nothing to revert).
   class Skipped < Success
     # Sentinel distinguishing "no value argument given" (the old Halt call
     # shape reused this class's name) from an explicit `Skipped(nil)`.
@@ -132,6 +134,10 @@ module RubyReactor
   end
 
   class Failure
+    # A stack overflow's backtrace runs to thousands of frames; the Failure is
+    # stored with the context, so keep the frames that locate the cause.
+    MAX_BACKTRACE_FRAMES = 100
+
     attr_reader :error, :retryable, :step_name, :inputs, :backtrace, :reactor_name, :step_arguments, :exception_class,
                 :file_path, :line_number, :code_snippet, :validation_errors, :rollback_failures
 
@@ -172,7 +178,7 @@ module RubyReactor
       @inputs = inputs
       @step_arguments = step_arguments
       raw_backtrace ||= backtrace || (@error.respond_to?(:backtrace) ? @error.backtrace : caller)
-      @backtrace = filter_backtrace(raw_backtrace)
+      @backtrace = cap_backtrace(filter_backtrace(raw_backtrace))
       @redact_inputs = redact_inputs
       @exception_class = exception_class || (@error.is_a?(Exception) ? @error.class.name : nil)
       @file_path = file_path
@@ -293,6 +299,12 @@ module RubyReactor
       msg << backtrace.take(10).map { |line| "  #{line}" }.join("\n")
     end
 
+    def cap_backtrace(backtrace)
+      return backtrace if backtrace.nil? || backtrace.size <= MAX_BACKTRACE_FRAMES
+
+      backtrace.first(MAX_BACKTRACE_FRAMES) << "... #{backtrace.size - MAX_BACKTRACE_FRAMES} more frames"
+    end
+
     def filter_backtrace(backtrace)
       return backtrace if ENV["RUBY_REACTOR_DEBUG"] == "true"
       return backtrace if backtrace.nil? || backtrace.empty?
@@ -344,7 +356,7 @@ module RubyReactor
       }
     end
 
-    ROLLBACK_FAILURE_SYMBOLS = %i[step kind reason].freeze
+    ROLLBACK_FAILURE_SYMBOLS = %i[step kind reason map_step].freeze
     private_constant :ROLLBACK_FAILURE_SYMBOLS
 
     # A stored failure comes back with string keys (and, through plain JSON,
@@ -387,8 +399,9 @@ module RubyReactor
   end
 
   # Global helper methods
+  # A step returning its own inputs (`Success(inputs)`) stores the Hash.
   def self.Success(value = nil)
-    Success.new(value)
+    Success.new(value.is_a?(Step::Inputs) ? value.to_h : value)
   end
 
   def self.Failure(error, **kwargs)

data/specs/006-step-retry-declarations/checklists/requirements.md

@@ -0,0 +1,41 @@
+# Specification Quality Checklist: Step-Scoped Retry Declarations
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-09-25
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The product is a library, so its user-facing DSL words (`retries`, `compose`,
+  `async_reactor`, `map`) are the user vocabulary, not implementation detail. Internal classes,
+  files, and storage are not named.
+- Resolved 2026-09-25: a direct call to a step class runs once. Only the reactor coordinates
+  retries (FR-013, Clarifications).
+- Removing reactor-wide defaults was added from the user's follow-up messages. It is US1 and is
+  delivered first as a standalone change (FR-005 to FR-007, FR-017 delivery order, FR-020
+  migration note); step class work (US2 onward) starts after it.

data/specs/006-step-retry-declarations/contracts/dsl-surface.md

@@ -0,0 +1,89 @@
+# Contract: Retry DSL Surface
+
+The public API after this feature. Anything not listed here keeps its current behavior.
+
+## 1. Removed: `retry_defaults` (Phase A)
+
+```ruby
+class PaymentReactor < RubyReactor::Reactor
+  retry_defaults max_attempts: 3   # => raises at class definition
+end
+```
+
+- Raises `RubyReactor::Error::DeprecatedDslError` (a `ValidationError`) when the class body
+  runs, whatever the arguments.
+- Message (shape): ``"`retry_defaults` has been removed from PaymentReactor: reactor-wide
+  defaults silently applied only to steps declared after them. Declare `retries` on each step
+  class (or step block) that should retry; a step with no `retries` runs once."``
+- There is no reader. `PaymentReactor.retry_defaults` with no arguments raises the same error.
+
+## 2. `retries` on a step class (Phase B)
+
+```ruby
+class ChargeCard < RubyReactor::Step
+  with_lock { |i| "card:#{i[:card_token]}" }
+  input :card_token, :string
+  retries max_attempts: 3, backoff: :exponential, base_delay: 5   # all keywords optional
+
+  def run = Success(PaymentService.charge(inputs[:card_token]))
+end
+```
+
+| Call                                   | Result                                                     |
+|----------------------------------------|------------------------------------------------------------|
+| `retries`                              | `{max_attempts: 3, backoff: :exponential, base_delay: 1}`  |
+| `retries max_attempts: 5`              | `{max_attempts: 5, backoff: :exponential, base_delay: 1}`  |
+| `retries max_attempts: 1`              | explicit "never retry"                                     |
+| `retries max_attempts: 0` / `2.5` / `"3"` | `ArgumentError` naming `ChargeCard`, `max_attempts`, value |
+| `retries backoff: :jitter`             | `ArgumentError` naming `ChargeCard`, `backoff`, value      |
+| `retries base_delay: -1`               | `ArgumentError` naming `ChargeCard`, `base_delay`, value   |
+| `ChargeCard.retry_config`              | the hash above, or `nil` if never declared                 |
+
+Inheritance: `class ChargeCardEU < ChargeCard; end` returns ChargeCard's policy from
+`retry_config`. Redeclaring in `ChargeCardEU` changes only `ChargeCardEU`.
+
+## 3. `retries` in a reactor step block (unchanged vocabulary)
+
+The same module provides it, so the table above also applies inside `step`, `async_step`,
+`compose` and `async_reactor` blocks (the error names the step, e.g. `charge_card`).
+
+```ruby
+step :charge_card do                 # inline: valid, as today
+  retries max_attempts: 3, backoff: :exponential, base_delay: 5
+  run { |args, _ctx| PaymentService.charge(args[:card_token]) }
+end
+
+step :charge_card, LegacyCharge do   # class without its own policy: valid, as today
+  retries max_attempts: 3
+end
+
+step :charge_card, ChargeCard do     # ChargeCard declares retries: REFUSED
+  retries max_attempts: 5
+end
+# => Error::ValidationError at reactor definition:
+#    "PaymentReactor step :charge_card declares `retries` inline, but ChargeCard declares it
+#     too. Keep ONE: drop the inline declaration to use ChargeCard's, or remove it from
+#     ChargeCard. To vary the policy per workflow, subclass ChargeCard."
+```
+
+## 4. Effective policy introspection
+
+```ruby
+PaymentReactor.steps[:charge_card].retry_config  # => {max_attempts: 3, backoff: …, base_delay: …}
+PaymentReactor.steps[:charge_card].retry_source  # => :step_class | :step_block | :none
+PaymentReactor.steps[:charge_card].retryable?    # => max_attempts > 1
+```
+
+## 5. Direct invocation
+
+`ChargeCard.run(args)` / `.call(args)` runs **once**, whatever `retries` says, and returns
+its `Failure` to the caller. Only a reactor coordinates retries. (Locks, by contrast, are
+taken on a direct call.)
+
+## 6. Runtime (unchanged)
+
+Under a class policy, retry behavior is the same as under a step-block policy with the same
+values: which failures are retried (`Failure#retryable?`, `fail!(retry: false)`, input
+contract failures), attempt counting across requeues, in-process sleep versus background
+`perform_in`, `MaxRetriesExhaustedFailure`, the `retry_attempt` middleware event, and
+compensation after the last attempt.

data/specs/006-step-retry-declarations/data-model.md

@@ -0,0 +1,58 @@
+# Data Model: Step-Scoped Retry Declarations
+
+No persisted data changes. The per-execution attempt record (`RetryContext#step_attempts`)
+and its serialization stay the same. Everything below is class-level configuration held in
+memory.
+
+## Retry Policy
+
+A frozen-shape hash. It is the same shape every consumer reads today.
+
+| Key            | Type                              | Default        | Validation (declaration time, `ArgumentError`) |
+|----------------|-----------------------------------|----------------|------------------------------------------------|
+| `max_attempts` | Integer                           | `3` (declared) | `Integer`, `>= 1`                              |
+| `backoff`      | Symbol                            | `:exponential` | one of `:exponential`, `:linear`, `:fixed`     |
+| `base_delay`   | Numeric (incl. AS::Duration)      | `1`            | `Numeric`, `>= 0`                              |
+
+`NO_RETRIES = { max_attempts: 1, backoff: :exponential, base_delay: 1 }` is the effective
+policy when nothing is declared. `retryable?` is false for it.
+
+## Declaration holders
+
+| Holder                              | How it declares                      | Reader                   | Inheritance                            |
+|-------------------------------------|--------------------------------------|--------------------------|----------------------------------------|
+| Step class (`< RubyReactor::Step`)  | `retries …` in class body            | `.retry_config` (or nil) | copied to subclass on `inherited`      |
+| `StepBuilder` (step / async_step)   | `retries …` in the reactor step block | `#retry_config` (or nil) | n/a                                    |
+| `ComposeBuilder`, `AsyncReactorBuilder` | `retries …` in the block         | `#retry_config` (or nil) | n/a                                    |
+| Reactor class                       | **none**: `retry_defaults` raises `DeprecatedDslError` | n/a | n/a                            |
+
+All four `retries` entry points come from one module (`Dsl::Retryable`), so vocabulary,
+defaults and validation are identical.
+
+## Effective policy (`StepConfig`)
+
+```text
+StepConfig#retry_config
+  = own (from builder)                         -> source :step_block
+  | impl.retry_config  (impl responds, non-nil) -> source :step_class
+  | NO_RETRIES                                  -> source :none
+
+StepConfig#retry_source  ∈ { :step_block, :step_class, :none }
+```
+
+Resolved lazily on each read, like `lock_config`. The reactor class is never consulted.
+
+## Definition-time rules
+
+| Rule                                                               | Where                         | Error                        |
+|--------------------------------------------------------------------|-------------------------------|------------------------------|
+| Invalid policy value                                               | `Retryable#retries`           | `ArgumentError`              |
+| `retries` in step block **and** on `impl` (own or inherited)       | `StepBuilder#build`           | `Error::ValidationError`     |
+| `retry_defaults` called on a reactor                               | `Dsl::Reactor.retry_defaults` | `Error::DeprecatedDslError`  |
+
+## Runtime (unchanged)
+
+The attempt record is `RetryContext#step_attempts[step_name]`, kept through serialization and
+requeue. `RetryManager` (in-process and background requeue) and `StepWorker` (`async_step`)
+compare it with `step_config.retry_config[:max_attempts]`. A direct `Step.run` never
+consults a policy (`StepCoordination#retry_pending?` is false for direct calls).

data/specs/006-step-retry-declarations/plan.md

@@ -0,0 +1,187 @@
+# Implementation Plan: Step-Scoped Retry Declarations
+
+**Branch**: `retry_confs_in_steps` | **Date**: 2026-09-25 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/006-step-retry-declarations/spec.md`
+
+## Summary
+
+Two phases, delivered in this order (spec FR-017):
+
+- **Phase A: remove `retry_defaults`.** `retry_defaults` becomes a stub that raises
+  `DeprecatedDslError`. Every read of it is deleted: the three builder fallbacks, the
+  `RetryManager` fallback, the `TestSubject` copies, and the `included` ivar. After this,
+  `StepConfig`'s policy can come only from its own block. Ships as a standalone `feat!`
+  commit with the suite green.
+- **Phase B: `retries` on step classes.** A new `Dsl::Retryable` module, modeled on
+  `Dsl::Lockable::ClassMethods`, provides `retries` with validation, a `retry_config` reader,
+  and `inherited` propagation. `RubyReactor::Step` extends it; the step, compose and
+  async-reactor builders include it, which replaces their duplicated `retries` methods.
+  `StepConfig#retry_config` resolves lazily in the order own declaration, then
+  `impl.retry_config`, then `NO_RETRIES`, the same way `lock_config` does. Declaring the policy
+  both on the class and in the step block is refused, like locks.
+
+Runtime retry code (`RetryManager`, `StepWorker`, `RetryContext`) is unchanged apart from
+deleting the fallback. Direct `Step.run` already never retries (research R7).
+
+## Technical Context
+
+**Language/Version**: Ruby >= 3.0
+
+**Primary Dependencies**: existing only: dry-validation, Sidekiq/ActiveJob adapters. No new
+gems.
+
+**Storage**: Redis (unchanged; no new keys, no serialization change)
+
+**Testing**: RSpec against real Redis (`bundle exec rspec`); `demo_app` RSpec with the shipped
+`RubyReactor::RSpec` surface; RuboCop
+
+**Target Platform**: Ruby gem (MRI), sync and background (Sidekiq/ActiveJob) execution
+
+**Project Type**: library (gem) + `demo_app` Rails integration example
+
+**Performance Goals**: no runtime cost beyond one extra `||` per `retry_config` read
+
+**Constraints**: public API change. The removal is breaking (`feat!`, migration note). Phase B
+is additive. Behavior for reactors that never used `retry_defaults` must not change.
+
+**Scale/Scope**: about 8 lib files touched, 1 new module; ~4 spec files migrated; 1 new spec
+file; 1 demo reactor + rake task + spec; ~10 docs files
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+| --- | --- | --- |
+| I. Gem-first | ✅ | All code in `lib/`, reachable via `require "ruby_reactor"`; no host coupling. |
+| II. Saga integrity | ✅ | Compensation after the last attempt is unchanged; the new specs cover exhaust-then-compensate on class steps. |
+| III. Test-first, real infra | ✅ | Each phase starts with failing specs; background paths drained against real Redis; no Redis mocking. |
+| IV. Observability | ✅ | `retry_attempt` events and `MaxRetriesExhaustedFailure` unchanged; `StepConfig#retry_source` adds introspection. |
+| V. Simplicity & SemVer | ✅ | One module replaces 3 duplicated methods (net deletion); no policy object (R3). Removal ships as `feat!` with a migration note (R9). |
+| VI. Demo-app proof | ✅ | `StepRetryDemoReactor` + `demo:step_retry` + spec using only the shipped matchers (`have_retried_step`, `be_failure`, `be_success`). |
+| Workflow: class-based steps in docs/examples | ✅ | Docs lead with the step class form. |
+
+- [x] Documentation impact identified: which `README.md` sections and which file(s) under
+      `./documentation` this feature will require updating (Constitution Development Workflow;
+      carried into tasks.md as a required task):
+  - **Phase A**: `documentation/retry_configuration.md` (delete "Reactor-Level Defaults", add
+    a "Migrating from `retry_defaults`" section), `documentation/core_concepts.md` (≈360,
+    remove "Uses reactor defaults"), `documentation/background_and_async.md` (≈482-530),
+    `documentation/examples/{inventory_management,order_processing,payment_processing}.md`,
+    the `demo_app/documentation/` copies of the same, README line 1486 ("reactor or step
+    level"), and `llms*.txt` if they mention it.
+  - **Phase B**: `documentation/retry_configuration.md` (step class form first; precedence;
+    conflict rule; subclassing to vary per workflow; direct call runs once, unlike locks),
+    `documentation/core_concepts.md` retry section, the README Features bullet (line 24),
+    and the README Retry Configuration blurb.
+
+**Post-design re-check**: ✅ no violations. Complexity Tracking is empty.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-step-retry-declarations/
+├── spec.md
+├── plan.md              # this file
+├── research.md          # Phase 0
+├── data-model.md        # Phase 1
+├── quickstart.md        # Phase 1
+├── contracts/
+│   └── dsl-surface.md   # Phase 1
+├── checklists/
+│   └── requirements.md
+└── tasks.md             # /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+lib/ruby_reactor/
+├── dsl/
+│   ├── retryable.rb              # NEW (B): retries + validation, retry_config, inherited
+│   ├── reactor.rb                # A: retry_defaults -> DeprecatedDslError stub; drop included ivar
+│   ├── step_builder.rb           # A: drop reactor fallback; B: include Retryable, drop own
+│   │                             #    retries, check_retry_conflict!, StepConfig lazy
+│   │                             #    retry_config + retry_source + NO_RETRIES
+│   ├── compose_builder.rb        # A: drop fallback; B: include Retryable, drop own retries
+│   └── async_reactor_builder.rb  # A: drop fallback; B: include Retryable, drop own retries
+├── step.rb                       # B: extend Dsl::Retryable
+├── executor/retry_manager.rb     # A: drop reactor_class.retry_defaults fallbacks
+└── rspec/test_subject.rb         # A: drop 3 @retry_defaults copies
+
+spec/
+├── async_retry_dsl_spec.rb               # A: retry_defaults example -> asserts removal error
+├── ruby_reactor_spec.rb                  # A: move retry_defaults into step-level retries
+├── support/order_processing_reactor.rb   # A: same
+└── ruby_reactor/step_retries/*_spec.rb  # NEW: removal (A); declaration, class_policy,
+                                          #   step_block_parity, conflict, execution_paths,
+                                          #   inheritance, introspection, test_surface (B)
+
+demo_app/
+├── spec/support/order_processing_reactor.rb      # A: drop retry_defaults
+├── app/reactors/step_retry_demo_reactor.rb       # NEW (B)
+├── lib/tasks/demo_reactors.rake                  # B: demo:step_retry
+└── spec/reactors/step_retry_demo_reactor_spec.rb # NEW (B)
+```
+
+**Structure Decision**: single gem layout (`lib/`, `spec/`) plus `demo_app/`, as in every
+earlier feature. The new module lives next to `dsl/lockable.rb`, which it mirrors.
+
+## Phase A: remove `retry_defaults` (ships first, standalone)
+
+1. **Red**: change `spec/async_retry_dsl_spec.rb:23-33` to expect `DeprecatedDslError`,
+   message included. Add: a subclass of `RubyReactor::Reactor` with no retry declarations runs
+   a failing step exactly once.
+2. **Green**: stub in `dsl/reactor.rb`; delete the `included` ivar; builders pass their own
+   `@retry_config` (initialized `nil`, not `{}`); `StepConfig` defaults to `NO_RETRIES` when
+   nil; `RetryManager#calculate_backoff_delay` reads only `step_config.retry_config` (drop the
+   now-unused `reactor_class` argument or rename it `_reactor_class`); delete the
+   `TestSubject` copies.
+3. Migrate `spec/ruby_reactor_spec.rb`, `spec/support/order_processing_reactor.rb` and
+   `demo_app/spec/support/order_processing_reactor.rb` to step-level `retries` on the steps
+   that relied on the default. Keep their assertions unchanged, so behavior is proven
+   identical.
+4. Docs (see the Constitution Check list) and the `BREAKING CHANGE:` footer with the
+   migration text.
+5. Gate: `grep retry_defaults` is clean except the stub and its spec; `rspec` and `rubocop`
+   are green. Commit `feat!: remove reactor-wide retry_defaults`.
+
+## Phase B: `retries` on step classes
+
+1. **Red**: `spec/ruby_reactor/step_retries/*_spec.rb` (one file per story) covering the quickstart table.
+2. **Green**:
+   - `Dsl::Retryable` (R3, R4): `BACKOFF_STRATEGIES`, `retries`, `retry_config`,
+     `inherited`.
+   - `Step` extends it. `StepBuilder`, `ComposeBuilder` and `AsyncReactorBuilder` include it
+     and delete their own `retries`; remove `retry_config` from `StepBuilder`'s
+     `attr_accessor`.
+   - `StepConfig` (R5): store `@retry_config` raw; lazy `retry_config`; `retry_source`.
+   - `StepBuilder#check_retry_conflict!` (R6), called from `build` next to
+     `check_coordination_conflicts!`.
+3. **Demo** (Constitution VI): `StepRetryDemoReactor` with class steps, showing
+   succeed-after-retry, exhaust-then-compensate, and a single-attempt undeclared step, using
+   `base_delay` near zero so the task runs fast; the `demo:step_retry` task depends on
+   `[:environment, :flush_redis]`; the spec uses only `test_reactor`, `failing_at`/`mock_step`,
+   `be_success`, `be_failure` and `have_retried_step`.
+4. Docs (Phase B list above).
+5. Gate: `rspec`, `rubocop`, and the docker demo run. Commit `feat: declare retries on step
+   classes`.
+
+## Risks
+
+- **Hidden `{}`-vs-`nil` assumptions.** Code that checks `retry_config.empty?` breaks once
+  the builders pass `nil`. Mitigation: `grep -rn "retry_config" lib` during Phase A; every
+  consumer goes through `StepConfig#retry_config`, which never returns nil.
+- **`name` collision in validation messages.** Builders' `name` is the step symbol and
+  `Step.name` is the class name. Both are what the message should show. An anonymous step
+  class has `name == nil`, so fall back to `inspect`.
+- **Rubocop.** `inherited` in an included module triggers no cop today (Lockable does the
+  same). The unused `reactor_class` argument in `RetryManager` needs removing or renaming to
+  `_reactor_class`.
+
+## Complexity Tracking
+
+No violations. The table is empty.

data/specs/006-step-retry-declarations/quickstart.md

@@ -0,0 +1,80 @@
+# Quickstart: Validating Step-Scoped Retry Declarations
+
+The API is in [contracts/dsl-surface.md](contracts/dsl-surface.md) and the resolution rules
+are in [data-model.md](data-model.md).
+
+## Prerequisites
+
+- Ruby >= 3.0, `bundle install`
+- Redis reachable by the suite (Constitution III): `docker compose up -d redis` or a local
+  `redis-server`
+- For the demo: `docker compose up` (see the constitution, Principle VI §4)
+
+## Phase A: `retry_defaults` removed (validate before starting Phase B)
+
+1. The removal error fires at definition time:
+
+   ```bash
+   bundle exec ruby -Ilib -e 'require "ruby_reactor"; Class.new(RubyReactor::Reactor) { retry_defaults max_attempts: 3 }'
+   ```
+
+   Expected: `RubyReactor::Error::DeprecatedDslError`, with a message pointing to step-level
+   `retries`.
+
+2. No references remain outside the removal stub and its spec:
+
+   ```bash
+   grep -rn "retry_defaults" lib spec demo_app README.md documentation llms*.txt
+   ```
+
+   Expected: only `lib/ruby_reactor/dsl/reactor.rb` (the stub) and the spec asserting it
+   raises.
+
+3. The full suite and lint are green:
+
+   ```bash
+   bundle exec rspec && bundle exec rubocop
+   ```
+
+## Phase B: `retries` on step classes
+
+Run the feature specs, then the full suite:
+
+```bash
+bundle exec rspec spec/ruby_reactor/step_retries/
+bundle exec rspec && bundle exec rubocop
+```
+
+What the feature spec must show (each maps to a spec story):
+
+| Scenario | Expected | Spec |
+| --- | --- | --- |
+| Class declares 3 attempts, body fails twice, reactor has no wiring | success on attempt 3 | US2 |
+| Same class, body always fails | `MaxRetriesExhaustedFailure`, 3 attempts, compensation runs | US2 |
+| Inline `retries` vs class `retries`, same values and failures | same attempts, delays, outcome | US3 |
+| Class `retries` + step block `retries` | `ValidationError` at reactor definition | US4 |
+| Class `retries max_attempts: 1` | not retried | US4 |
+| Same class under `background all: true` (drained) | attempts requeued, same count | US5 |
+| Same class as `async_step` | `StepWorker` honors the class policy | US5 |
+| Subclass without / with its own `retries` | inherits / overrides; parent unchanged | US6 |
+| `failing_at` / `mock_step` on a class step | still retried under the class policy | US7 |
+| `steps[:x].retry_source` | `:step_class` / `:step_block` / `:none` | US7 |
+| `ChargeCard.run(args)` directly, failing | one attempt, `Failure` returned | FR-013 |
+| `retries backoff: :bogus` on a class | `ArgumentError` at class definition | FR-004 |
+
+## Demo acceptance run
+
+```bash
+docker compose run --rm demo-app bin/rails demo:step_retry
+docker compose run --rm demo-app bundle exec rspec spec/reactors/step_retry_demo_reactor_spec.rb
+```
+
+The rake task prints three outcomes:
+
+1. a class step that succeeds after retries (`attempts=3 success?=true`);
+2. a class step that exhausts its retries, with an earlier step compensated
+   (`success?=false attempts=3 compensated=true`);
+3. a step with no declaration that is attempted once (`attempts=1`).
+
+When running from a git worktree, pass an isolated compose project name (`-p <name>`) so
+the fixed container names don't collide with another worktree's stack.