ruby_reactor 0.8.4 → 0.8.5

data/specs/007-execution-flow-analysis/spec.md

@@ -0,0 +1,270 @@
+# Feature Specification: Execution Flow & Compensation Analysis
+
+**Feature Branch**: `execution_flow_analysis`
+
+**Created**: 2026-09-26
+
+**Status**: Draft
+
+**Input**: User description: "We need to do a thorough analysis of the execution flow. That means
+to figure out all the invariants and paths the execution flows in all conditions. We have to get:
+order of execution of reactors and compensation in all the possible conditions.
+
+We have to take into account:
+- composed reactors
+- maps
+- async steps
+- async reactors
+
+In all the invariants:
+- locks
+- retries
+- failures
+
+This is important because we have to figure out if compensation is predictable and the DSL helps
+clearly understand how everything is gonna be executed.
+
+For example: I'm not very sure how compensation behaves in composed reactors and maps. In maps:
+- we are not compensating individually all the maps already executed.
+- when composed reactors fail do we compensate all previous composed reactors.
+
+Should we add an entry point for maps to compensate all on failure? for example:
+
+```ruby
+map :many_things do
+  compensate_all do |all_elements|
+    all_elements.destroy
+  end
+  # or
+  compensate_each do |element|
+    element.destroy
+  end
+end
+```
+
+This initiative is a research project to later figure out what solutions we could implement based
+on data and evidence. We could suggest fixes at the end but they will be later analysed.
+ONLY DOCUMENTATION."
+
+## User Scenarios & Testing *(mandatory)*
+
+The "users" of this research are the RubyReactor maintainers who must decide whether (and how) to
+change rollback semantics, and reactor authors who need to predict what runs, in what order, when
+something fails.
+
+### User Story 1 - Look up the exact rollback order for any failure (Priority: P1)
+
+A maintainer picks a reactor shape (plain steps, a composed reactor, a map, an async step, an async
+reactor, or any nesting of these) and a point of failure, and finds the exact ordered sequence of
+forward executions, compensations and undos that the library performs — including which already
+completed work is **not** rolled back.
+
+**Why this priority**: This is the core question of the initiative ("is compensation
+predictable?"). Every later decision depends on knowing current behavior precisely.
+
+**Independent Test**: Take any row of the delivered execution-order matrix, build that reactor
+shape, trigger the failure at the stated point, and compare the observed sequence of step events
+with the documented sequence. They match.
+
+**Acceptance Scenarios**:
+
+1. **Given** a reactor whose third of four plain steps fails, **When** the maintainer reads the
+   matrix, **Then** they find the failing step's compensation followed by undo of steps two and one
+   (in that order), and that step four never runs.
+2. **Given** a map whose fifth element fails after four elements succeeded, **When** the maintainer
+   reads the map section, **Then** they find whether the four succeeded elements are individually
+   rolled back, rolled back as a whole, or left in place — for both synchronous and asynchronous
+   map execution and for each failure-tolerance setting.
+3. **Given** a parent reactor with two composed child reactors where the second child fails,
+   **When** the maintainer reads the composition section, **Then** they find whether the first
+   child's completed steps are undone, in what order relative to the parent's own steps, and whether
+   the second child's own completed steps are undone before the parent learns of the failure.
+
+---
+
+### User Story 2 - Answer the open questions explicitly (Priority: P1)
+
+The maintainer finds a dedicated answer, with evidence, to each question raised in the input:
+(a) are already-executed map elements compensated individually; (b) when a composed reactor fails,
+are previously completed composed reactors compensated; (c) would a map-level "compensate all" /
+"compensate each" entry point close a real gap.
+
+**Why this priority**: These are the concrete doubts that triggered the research; they must be
+answered unambiguously, not left implicit in a large matrix.
+
+**Independent Test**: Read the "Answers" section in isolation; each question has a yes/no/depends
+answer, the conditions under which it holds, and the evidence that supports it.
+
+**Acceptance Scenarios**:
+
+1. **Given** question (a), **When** the maintainer reads its answer, **Then** it states what
+   happens to completed elements when a later element fails and when a step *after* the map fails,
+   in every map execution mode.
+2. **Given** question (c), **When** the maintainer reads its answer, **Then** it states whether the
+   gap exists today and what problem each proposed entry point would and would not solve.
+
+---
+
+### User Story 3 - Catalogue of invariants under locks, retries and failures (Priority: P2)
+
+The maintainer reads a list of invariants — statements that must always hold about execution and
+rollback (e.g. "a step whose lock was never acquired is never compensated", "retries are exhausted
+before compensation starts", "a lock taken by a step is held while that step is undone") — each
+marked as holding, violated, holding only under conditions, or undetermined, with evidence.
+
+**Why this priority**: Locks, retries and asynchrony multiply the paths through the executor. A
+tested catalogue of invariants is what makes future changes safe to review.
+
+**Independent Test**: Pick any invariant marked "holds" and reproduce the scenario it names; the
+observed behavior agrees. Pick any marked "violated" and reproduce the counter-example.
+
+**Acceptance Scenarios**:
+
+1. **Given** a step that is retried and ultimately exhausts its attempts, **When** the maintainer
+   reads the retry invariants, **Then** they learn whether compensation runs once or per attempt,
+   and whether it runs synchronously or when the last retry fails in the background.
+2. **Given** a step protected by a lock that fails, **When** the maintainer reads the lock
+   invariants, **Then** they learn when the lock is released relative to the step's compensation
+   and to the undo of earlier steps.
+
+---
+
+### User Story 4 - Predictability and DSL clarity assessment (Priority: P2)
+
+The maintainer reads a ranked list of findings where behavior is surprising, inconsistent between
+execution modes (inline vs background), not visible from the reactor definition, or different from
+what README/documentation claims.
+
+**Why this priority**: The initiative's stated goal is judging whether "the DSL helps clearly
+understand how everything is going to be executed". Findings are the bridge from facts to decisions.
+
+**Independent Test**: Each finding names the scenario, the expected-by-a-reader behavior, the
+actual behavior, and a severity; a reviewer can verify it without reading the rest of the report.
+
+**Acceptance Scenarios**:
+
+1. **Given** a documented claim about compensation or ordering, **When** the actual behavior
+   differs, **Then** the finding quotes the claim and the location it appears in.
+
+---
+
+### User Story 5 - Evidence-based improvement options (Priority: P3)
+
+For each significant finding, the maintainer reads candidate remedies (including the proposed map
+`compensate_all` / `compensate_each` entry points), each with trade-offs, compatibility impact and
+open questions — explicitly **not** a decision.
+
+**Why this priority**: The user wants suggestions to analyse later; they are useful but depend on
+the facts produced by stories 1–4.
+
+**Independent Test**: Each option references the finding(s) it addresses and states at least one
+downside.
+
+**Acceptance Scenarios**:
+
+1. **Given** the map-compensation gap (if confirmed), **When** the maintainer reads its options,
+   **Then** they see at least the two proposed shapes compared on failure semantics, async
+   behavior, and interaction with retries and failure tolerance.
+
+---
+
+### Edge Cases
+
+- The compensation or undo of a step itself fails (returns failure or raises): does rollback of
+  earlier steps continue, and what does the final result report?
+- A failure occurs while an async step or async reactor is still pending, and the parent is
+  resumed later in a different process.
+- A map configured to tolerate element failures (collect results instead of failing fast) versus
+  one that fails fast; partially dispatched async maps when the failure happens.
+- A composed reactor nested inside a map, and a map nested inside a composed reactor.
+- A step that fails because its lock/semaphore could not be acquired (never started) versus a step
+  whose body started and then failed.
+- A step that returns a halt/skip signal instead of success or failure.
+- A reactor that is paused (interrupt) and later resumed, then fails after resume: are steps
+  completed before the pause undone?
+- A worker crashes mid-execution and the sweeper re-drives it: can any step run or be compensated
+  twice?
+- Input validation failures on the reactor or a step (before any body runs).
+- Steps that define neither compensation nor undo.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The deliverable MUST inventory every execution construct in scope — plain step,
+  composed reactor, map (synchronous and asynchronous, fail-fast and failure-tolerant), async step,
+  async/background reactor, interrupt step — and describe each one's lifecycle from scheduling to
+  terminal state.
+- **FR-002**: The deliverable MUST provide an execution-order matrix: for each construct and each
+  failure location (before, inside, after the construct; in a nested child), the ordered sequence
+  of forward runs, compensations and undos, and the list of completed work that is left in place.
+- **FR-003**: The matrix MUST distinguish inline (same process) execution from background
+  execution wherever their ordering or rollback coverage differ.
+- **FR-004**: The deliverable MUST cover the cross-cutting conditions: locks (reactor-level,
+  step-level, ordered locks, semaphores), retries (in-attempt, re-enqueued, exhausted), and failure
+  kinds (returned failure, raised error, input validation failure, coordination contention,
+  compensation/undo failure, timeout, crash and re-drive).
+- **FR-005**: The deliverable MUST answer the three questions of User Story 2 in a dedicated
+  section with explicit conditions and evidence.
+- **FR-006**: The deliverable MUST state invariants as testable propositions, each with a status
+  (holds / violated / conditional / undetermined) and supporting evidence.
+- **FR-007**: Every behavioral claim MUST cite evidence: a source location, an existing automated
+  test, and/or a reproducible observation. Claims MUST be labelled with the kind of evidence that
+  supports them, and claims backed only by reading MUST be distinguishable from observed ones.
+- **FR-008**: The deliverable MUST map each invariant to the existing automated tests that cover it
+  (or state that none do), so coverage gaps are visible.
+- **FR-009**: The deliverable MUST list predictability/DSL-clarity findings, each with scenario,
+  expected-by-reader behavior, actual behavior, severity, and any contradicting documentation.
+- **FR-010**: The deliverable MUST propose improvement options for significant findings, including
+  an evaluation of map-level `compensate_all` and `compensate_each`, with trade-offs and
+  compatibility impact, and MUST mark all options as proposals pending later analysis.
+- **FR-011**: The initiative MUST NOT change library runtime behavior, the test suite, or the demo
+  application; its outputs are documentation only.
+- **FR-012**: Ordering descriptions MUST be presented so a reader can follow them without reading
+  source (numbered sequences and/or diagrams per scenario).
+
+### Key Entities
+
+- **Execution construct**: a unit the reactor schedules (step, compose, map, async step, async
+  reactor, interrupt), with its lifecycle states and rollback hooks.
+- **Scenario**: a reactor shape plus a failure location plus cross-cutting conditions (lock,
+  retry, execution mode).
+- **Execution trace**: the ordered list of forward, compensation and undo events for a scenario.
+- **Invariant**: a proposition about ordering or rollback, with status, evidence and test coverage.
+- **Finding**: a place where behavior is unpredictable, inconsistent, invisible in the DSL, or
+  contradicts documentation; carries severity.
+- **Improvement option**: a candidate remedy linked to findings, with trade-offs; not a decision.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% of construct × failure-location cells in the matrix are filled with a sequence
+  or explicitly marked "not reachable", with no blank cells.
+- **SC-002**: A maintainer unfamiliar with the executor internals can answer each of the three
+  input questions from the deliverable in under 5 minutes.
+- **SC-003**: 100% of behavioral claims carry an evidence label; at least the headline claims for
+  maps, composition, async steps and async reactors (the four constructs named by the user) are
+  backed by a reproducible observation, not only by reading.
+- **SC-004**: Every finding rated high severity has at least two improvement options, each with at
+  least one stated downside.
+- **SC-005**: Zero changes to library runtime code, automated tests or demo application result
+  from this initiative.
+
+## Assumptions
+
+- "Compensation" follows the library's existing vocabulary: *compensate* is the failing step's own
+  cleanup, *undo* is the reverse-order rollback of previously completed steps. The analysis covers
+  both and refers to them together as "rollback".
+- Interrupts (pause/resume) are in scope only where they change execution or rollback order; they
+  were not named by the user but affect "all conditions".
+- Reproducible observations may be produced by throwaway probe reactors run against the project's
+  real storage; the probes and their recorded outputs are kept alongside the research documents as
+  evidence, not added to the library, test suite or demo app.
+- README.md and ./documentation are audited for claims that contradict findings, but not edited:
+  documenting current behavior as contract before the follow-up decision would lock it in.
+  Documentation changes ship with whichever remedy is later chosen.
+- Rate limits and periods are treated as a kind of coordination contention (like locks) and not
+  analysed separately unless they produce a distinct rollback path.
+- The analysis reflects the current `main`-based code at the time of writing (after step-scoped
+  retry declarations and inputs protection landed).

data/specs/007-execution-flow-analysis/tasks.md

@@ -0,0 +1,257 @@
+# Tasks: Execution Flow & Compensation Analysis
+
+**Input**: Design documents from `specs/007-execution-flow-analysis/`
+
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/report-structure.md,
+quickstart.md
+
+**Tests**: No test tasks. This is documentation-only (FR-011). Evidence probes are research
+artifacts under `evidence/` and check themselves (expected vs observed).
+
+**Organization**: Tasks are grouped by user story. `FD` below = `specs/007-execution-flow-analysis`.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: User story the task belongs to (US1–US5)
+
+## Rules for every probe task
+
+- Each probe is a `scenario "S-<area>-<nn>", "<shape>", mode:, expected: [...] do … end` block
+  (harness from T002). Step bodies call `rec("run:x")` / `rec("compensate:x")` / `rec("undo:x")`.
+- `expected` starts as the hypothesis from research.md. If the probe prints `MISMATCH`, the
+  **observation wins**. Update `expected` to the observed sequence and record the deviation in the
+  report (a refuted hypothesis is a result, not a failure).
+- Use `base_delay: 0` for retries. Drain async work with `drain` (harness).
+- Never edit `lib/`, `spec/`, `demo_app/`, `README.md`, `documentation/`.
+
+---
+
+## Phase 1: Setup
+
+**Purpose**: Evidence harness able to run a scenario end to end against real Redis.
+
+- [X] T001 Create `FD/analysis/` and `FD/evidence/probes/`. Confirm test Redis answers `PING` at
+  `redis://localhost:6780` (or `RUBY_REACTOR_TEST_REDIS_URL`) and that
+  `bundle exec ruby -e 'require "ruby_reactor"'` loads from the repo root.
+- [X] T002 Create `FD/evidence/harness.rb`. Configure RubyReactor storage (redis URL from env,
+  default 6780) and `async_router = Adapters::Sidekiq::Router`. Put `Sidekiq::Testing.fake!` on.
+  Define a global event recorder `rec(event)`. Define a `Recorder` middleware (subclass of
+  `RubyReactor::Middleware`) that logs `lock_acquired`, `lock_released`, `semaphore_acquired`,
+  `semaphore_released`, `retry_attempt`, `start_compensation`, `start_undo`, and register it
+  globally. Define `scenario(id, title, mode:, expected:, &block)`: it FLUSHDBs, clears Sidekiq
+  jobs and the recorder, runs the block (the block returns the final result), appends
+  `=> success|failure(<step>)|halt|paused`, then prints the block format from
+  contracts/report-structure.md and tallies MATCH/MISMATCH. Define `drain` wrapping
+  `RubyReactor::RSpec::SidekiqHelpers.drain_async_jobs`, and `outcome(result)`.
+- [X] T003 Create `FD/evidence/run.rb`. Require the harness and every `probes/*.rb` in sorted
+  order, honour the `PROBE=<substring>` filter, and print a final
+  `N scenarios, X match, Y mismatch` line.
+
+---
+
+## Phase 2: Foundational (blocking)
+
+**Purpose**: Establish the plain-step rollback baseline that every other construct is described
+against. Refuting it would change every later expectation.
+
+- [X] T004 Create `FD/evidence/probes/01_plain.rb` covering research H1–H6.
+  `S-plain-01` a→b(fails)→c. `S-plain-02` b raises vs returns Failure. `S-plain-03` b's
+  compensate fails (prior undos still run? rollback_failures?). `S-plain-04` an undo fails
+  (remaining undos run?). `S-plain-05` b returns Halt (no rollback). `S-plain-06` a Skipped step
+  before the failure (not undone). `S-plain-07` an argument `transform` raises a StandardError
+  after a completed step (H5: is `a` undone?). `S-plain-08` an output validation failure (H6).
+  `S-plain-09` a DAG with two independent branches (undo order = completion order reversed).
+  Run `PROBE=plain`, fix expectations until they MATCH, and save the transcript.
+- [X] T005 Write the "Rollback algorithm" section of `FD/analysis/execution-order.md` (generic
+  compensate → reverse-undo, never-started exception, Halt/Skipped, error classes that skip
+  rollback) with a Mermaid flow and `[R]`/`[O: S-plain-*]` labels.
+
+**Checkpoint**: Baseline confirmed. Construct probes can now be written in parallel.
+
+---
+
+## Phase 3: User Story 1 — Exact rollback order for any failure (P1) 🎯 MVP
+
+**Goal**: A per-construct order matrix with no blank cells (FR-001/002/003/012, SC-001).
+
+**Independent Test**: Pick any matrix row, run its probe id with `PROBE=<id>`, and see `MATCH`.
+
+- [X] T006 [P] [US1] Create `FD/evidence/probes/02_compose.rb` (H10–H13). `S-compose-01` parent
+  a → compose(c1→c2 fails) → b. `S-compose-02` a → compose(c1→c2) → b fails (compose undone ⇒
+  c2, c1 undone). `S-compose-03` compose X(x1,x2) → compose Y(y1→y2 fails) (**Q2**: X's steps
+  undone?). `S-compose-04` compose nested two levels, innermost fails. `S-compose-05` compose with
+  `retries max_attempts: 2`, child c2 fails once then succeeds (H12: are undone c1 results reused
+  without re-running c1?). `S-compose-06` compose inside background worker (`background all:`),
+  failure after it.
+- [X] T007 [P] [US1] Create `FD/evidence/probes/03_map.rb` (H14–H18). Element reactor has steps
+  e1→e2 with undo on both. `S-map-01` inline fail_fast, element 2 of 4 fails (**Q1**: are elements
+  0–1 undone?). `S-map-02` inline `fail_fast false`, one element fails. `S-map-03` inline map ok →
+  next parent step fails (map elements undone?). `S-map-04` fan-out fail_fast, one element fails
+  (drain; which elements ran, which were rolled back, parent rollback). `S-map-05` fan-out
+  `fail_fast false`. `S-map-06` fan-out ok → next parent step fails. `S-map-07` map inside a
+  composed child, element fails. `S-map-08` element reactor that composes a child, element fails.
+- [X] T008 [P] [US1] Create `FD/evidence/probes/04_async.rb` (H19–H22). `S-async-01` async_step
+  fails, no reader (parent outcome? step's compensate?). `S-async-02` async_step fails, reader
+  `fail!`s (whose compensate runs? async_step's compensate/undo?). `S-async-03` async_step
+  succeeds, later parent step fails (async_step undone?). `S-async-04` async_reactor child fails
+  (child's own rollback, parent unaffected). `S-async-05` async_reactor child fails, reader
+  `fail!`s. `S-async-06` async_reactor child succeeds, parent fails later (child undone?).
+  `S-async-07` async_step with `retries max_attempts: 3` always failing (attempt count,
+  compensate calls).
+- [X] T009 [P] [US1] Create `FD/evidence/probes/05_background.rb` (H8, H23). `S-bg-01`
+  `background all: true`, step 3 fails (same order as inline?). `S-bg-02` `background after: :a`,
+  worker step c fails (is caller-side a undone?). `S-bg-03` `background all:` with a retrying step
+  that exhausts (re-enqueue per attempt, single compensate at the end). `S-bg-04` `background all:`
+  with a retrying step that succeeds on attempt 2 (no compensate at all).
+- [X] T010 [US1] Run `bundle exec ruby FD/evidence/run.rb | tee FD/evidence/output.txt`. Reconcile
+  every MISMATCH in T006–T009 (observation wins) and re-run until clean. Note refuted hypotheses
+  for the report.
+- [X] T011 [US1] Write "Construct lifecycles" in `FD/analysis/execution-order.md`: step, compose,
+  map inline, map fan-out (dispatcher → element executor → collector → parent resume),
+  async_step (dispatch → StepWorker → record → reader), async_reactor, background reactor,
+  interrupt. Each is a numbered lifecycle saying where rollback hooks attach and where locks are
+  held, with `[R]` citations.
+- [X] T012 [US1] Write the "Order matrix" tables in `FD/analysis/execution-order.md`, one table per
+  construct, with columns per contracts/report-structure.md. Fill every cell from `output.txt`
+  (`[O]`) or reading (`[R]`, labelled *by reading*). Mark unreachable combinations as
+  `not reachable: <reason>`.
+
+**Checkpoint**: US1 complete. The matrix alone answers "what runs, in what order, what is left in
+place".
+
+---
+
+## Phase 4: User Story 2 — Explicit answers to the open questions (P1)
+
+**Goal**: The three questions each answered in under 5 minutes of reading (FR-005, SC-002).
+
+**Independent Test**: Read `FD/analysis/README.md` "Answers" alone. Each has a verdict line,
+conditions, evidence and links.
+
+- [X] T013 [US2] Write `FD/analysis/README.md`: scope & baseline, how to read (vocabulary,
+  labels, scales), **Answers** Q1 (map elements), Q2 (earlier composed reactors), Q3
+  (compensate_all/compensate_each gap: gap exists? what each shape would/would not fix, with a
+  forward link to options). Include per-mode conditions (inline vs fan-out, fail_fast on/off),
+  and a file index. Top-findings list is filled in T019.
+
+---
+
+## Phase 5: User Story 3 — Invariants under locks, retries, failures (P2)
+
+**Goal**: Testable invariant catalogue with status, evidence, coverage (FR-006, FR-008).
+
+**Independent Test**: Re-run any `[O]` scenario an invariant cites. A `VIOLATED` one reproduces
+its counter-example.
+
+- [X] T014 [P] [US3] Create `FD/evidence/probes/06_coordination.rb` (H2, H7, H24, H25).
+  `S-lock-01` reactor `with_lock`, step fails (lock_released after last undo?). `S-lock-02`
+  step-class `with_lock` on b, c fails (b's lock released after run, re-acquired around undo:b).
+  `S-lock-03` step lock pre-held by another owner, sync run (b never started ⇒ no compensate:b,
+  a undone). `S-lock-04` step `with_semaphore limit: 1` same as 02. `S-retry-01` b retries 3× then
+  fails (3 run:b, then one compensate:b). `S-retry-02` `fail!(…, retry: false)` inside a retrying
+  step (no further attempts). `S-retry-03` a retrying step that succeeds on attempt 2 (no
+  compensate).
+- [X] T015 [P] [US3] Create `FD/evidence/probes/07_interrupts_manual.rb` (H26–H28). `S-intr-01`
+  a → interrupt → c fails after `continue` (a undone?). `S-intr-02` interrupt payload validation
+  exhausting `max_attempts` (undo of a?). `S-intr-03` `Reactor.cancel` on a paused reactor (no
+  rollback). `S-intr-04` `Reactor.undo(id)` on a completed reactor (reverse undo, reactor lock
+  taken or not?).
+- [X] T016 [US3] Re-run the full probe set, update `FD/evidence/output.txt`, reconcile mismatches.
+- [X] T017 [US3] Map each invariant to existing specs: grep `spec/` (e.g. `compensation_*`,
+  `undo_spec`, `compose_spec`, `map/*`, `step_coordination/*`, `retry_*`, `interrupt_*`,
+  `async_*`) and record `[T: path:line]` or `none`.
+- [X] T018 [US3] Write `FD/analysis/invariants.md`: `INV-nn` entries grouped by area (ordering,
+  rollback coverage, never-started, retries, locks, async isolation, interrupts/manual,
+  crash/re-drive), each with all data-model fields, ending with the coverage summary (counts by
+  status, list of `coverage: none`).
+
+---
+
+## Phase 6: User Story 4 — Predictability & DSL-clarity findings (P2)
+
+**Goal**: A ranked list of findings plus the documentation audit (FR-009). This is the
+constitution's documentation task (plan.md Complexity Tracking).
+
+**Independent Test**: Each finding stands alone: scenario, reader expectation, actual, severity,
+doc conflict.
+
+- [X] T019 [US4] Write the "Findings" section of `FD/analysis/findings-and-options.md`: `F-nn`
+  ranked High → Low with all data-model fields, derived from VIOLATED/CONDITIONAL invariants,
+  refuted hypotheses and DSL gaps (e.g. map has no compensate/undo/retries surface, compose has no
+  compensate/undo hook, async unit compensate blocks never run). Then fill the Top-findings list
+  in `FD/analysis/README.md`.
+- [X] T020 [US4] Write the "Documentation audit" table in `FD/analysis/findings-and-options.md`:
+  every README.md / `documentation/*.md` claim about ordering or rollback that is contradicted,
+  incomplete or unstated. Cover README "Error Handling and Compensation", async_step/async_reactor
+  sections, `documentation/composition.md` compose-vs-async_reactor table,
+  `documentation/background_and_async.md` "Compensation is opt-in" and "Error Handling and
+  Compensation", `documentation/data_pipelines.md` fail_fast, `documentation/core_concepts.md`
+  "Compensation Order", `documentation/DAG.md`. Quote the claim and give `file:line`. **No edits to
+  those files.**
+
+---
+
+## Phase 7: User Story 5 — Improvement options (P3)
+
+**Goal**: Proposals only, linked to findings (FR-010, SC-004).
+
+**Independent Test**: Every option names its finding(s) and at least one con. Every High finding
+has ≥2 options.
+
+- [X] T021 [US5] Write the "Options" section of `FD/analysis/findings-and-options.md`. Include the
+  required evaluation of map `compensate_all` vs `compensate_each` (and alternatives, e.g.
+  element-reactor undo replay / MapStep#undo over stored element contexts), compared on
+  fail_fast on/off, inline vs fan-out, element retries, a later-step failure, and data
+  availability. Give ≥2 options per High finding, each with compatibility impact and open
+  questions. Close with the "proposals pending later analysis" note.
+
+---
+
+## Phase 8: Polish & Cross-Cutting
+
+- [X] T022 Run the quickstart.md validation. Check for no `TBD|TODO|???` in `FD/analysis/*.md`.
+  Check that every `[O: S-…]` label resolves to a block in `FD/evidence/output.txt`. Check that
+  every High finding has ≥2 options with cons. Fix gaps.
+- [X] T023 Documentation task (REQUIRED, Constitution Development Workflow). Confirm T020's audit
+  covers README.md and each relevant `./documentation` file. Per plan.md Complexity Tracking,
+  README/documentation are **not edited**: behavior is unchanged, and doc updates ship with the
+  chosen remedy. Record that decision in `FD/analysis/README.md` scope.
+- [X] T024 Verify zero product diff: `git status --porcelain` / `git diff --stat` show changes
+  only under `FD/`, `CLAUDE.md` (agent pointer) and `.specify/feature.json` (SC-005, FR-011).
+- [X] T025 Mark all tasks complete in `FD/tasks.md`.
+
+**Constitution Principle VI**: N/A. No public API or user-facing behavior change, so no demo
+reactor, rake task or demo spec. Any remedy chosen later carries its own.
+
+---
+
+## Dependencies & Execution Order
+
+- **Setup (T001–T003)** → **Foundational (T004–T005)** → user stories.
+- **US1 (T006–T012)**: T006–T009 in parallel (separate probe files). T010 after all four.
+  T011–T012 after T010.
+- **US2 (T013)**: after US1 (answers cite matrix rows).
+- **US3 (T014–T018)**: T014/T015 can start right after Foundational, in parallel with US1 probes.
+  T016 after T014/T015 (and T010, since it re-runs everything). T017 is independent. T018 after
+  T016+T017.
+- **US4 (T019–T020)**: after US1 and US3 (findings derive from matrix + invariants). T020 can
+  start any time (reading only).
+- **US5 (T021)**: after T019.
+- **Polish (T022–T025)**: last.
+
+### Parallel Example
+
+```text
+# After T005:
+T006 02_compose.rb   T007 03_map.rb   T008 04_async.rb   T009 05_background.rb
+T014 06_coordination.rb   T015 07_interrupts_manual.rb   T017 spec coverage grep   T020 doc audit
+```
+
+## Implementation Strategy
+
+1. **MVP = Setup + Foundational + US1 + US2**: the matrix plus the three direct answers already
+   settle the user's immediate doubts (maps, compose).
+2. Add US3 (invariants) for review-safety of future changes.
+3. Add US4 + US5 (findings, audit, options) as input to the follow-up decision.
+4. Probes stay re-runnable, so any later remedy can re-run them and compare before/after.

data/specs/008-rollback-reliability/checklists/requirements.md

@@ -0,0 +1,43 @@
+# Specification Quality Checklist: Reliable Rollback Across Constructs
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-09-26
+**Revised**: 2026-09-27 (PR #65 review)
+**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 (FR-029 defaulted to option A, 2026-09-27)
+- [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 "stakeholders" are reactor authors and maintainers. The DSL
+  words used (`map`, `compose`, `async_reactor`, `async_step`, `retries`, `where`/`guard`,
+  `Skipped`, `compensate`/`undo`) are the public vocabulary, not implementation internals. No file
+  paths, classes or storage mechanisms appear in the requirements.
+- Success criteria cite the 007 invariants and evidence set. They are the agreed, reproducible
+  baseline, not technology choices.
+- 2026-09-27 revision: FR-009, FR-010, FR-014, FR-016, FR-018 revised; FR-028, FR-029 and US6 added.
+  FR numbers kept stable so plan, research and tasks references still resolve.
+- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`