chrono_forge 0.10.0 → 0.12.0

data/docs/superpowers/plans/2026-07-01-workflow-definition-dag.md.tasks.json

@@ -0,0 +1,68 @@
+{
+  "planPath": "docs/superpowers/plans/2026-07-01-workflow-definition-dag.md",
+  "tasks": [
+    {
+      "id": 1,
+      "subject": "Task 1: Definition value objects + Prism dep",
+      "status": "completed",
+      "description": "Graph data model (Definition/Node/Edge) + prism runtime dependency, round-trippable to_h.\n\n```json:metadata\n{\"files\": [\"lib/chrono_forge/definition.rb\", \"chrono_forge.gemspec\", \"test/definition_test.rb\"], \"verifyCommand\": \"bundle exec ruby -I test test/definition_test.rb\", \"acceptanceCriteria\": [\"Definition holds nodes/edges/warnings; to_h JSON-safe\", \"Node#dynamic?\", \"prism declared dependency\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 2: Analyzer — linear steps",
+      "status": "completed",
+      "blockedBy": [1],
+      "description": "DefinitionAnalyzer.call resolves perform via Prism; a node per straight-line durable call with sequential edges from start.\n\n```json:metadata\n{\"files\": [\"lib/chrono_forge/definition_analyzer.rb\", \"test/support/definition_fixtures.rb\", \"test/definition_analyzer_test.rb\"], \"verifyCommand\": \"bundle exec ruby -I test test/definition_analyzer_test.rb\", \"acceptanceCriteria\": [\"node per durable call in source order with exact step_name\", \"seq edges start->n1->n2\", \"non-durable Ruby ignored\", \"no DB/exec\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 3,
+      "subject": "Task 3: Analyzer — conditionals & guards",
+      "status": "completed",
+      "blockedBy": [2],
+      "description": "if/unless/case around durable calls -> :conditional edges with guard labels; rejoin skip/body; continue_if false path -> :terminal.\n\n```json:metadata\n{\"files\": [\"lib/chrono_forge/definition_analyzer.rb\", \"test/support/definition_fixtures.rb\", \"test/definition_analyzer_test.rb\"], \"verifyCommand\": \"bundle exec ruby -I test test/definition_analyzer_test.rb\", \"acceptanceCriteria\": [\"guarded conditional edge with source guard\", \"rejoin skip+body\", \"continue_if terminal edge\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 4,
+      "subject": "Task 4: Analyzer — branch fan-out + merge join",
+      "status": "completed",
+      "blockedBy": [3],
+      "description": "branch block -> :branch fan-out node + child-group node via :fanout edge; merge_branches -> :join edge from branch.\n\n```json:metadata\n{\"files\": [\"lib/chrono_forge/definition_analyzer.rb\", \"test/support/definition_fixtures.rb\", \"test/definition_analyzer_test.rb\"], \"verifyCommand\": \"bundle exec ruby -I test test/definition_analyzer_test.rb\", \"acceptanceCriteria\": [\"branch$name node + child-group with pattern\", \"branch->child :fanout\", \"branch->merge :join\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 5,
+      "subject": "Task 5: Analyzer — repeat, helper tracing, loop warnings",
+      "status": "completed",
+      "blockedBy": [4],
+      "description": "durably_repeat -> :repeat node; trace durable calls in same-class helpers (recursion-guarded); durable call inside a loop -> warning, no crash.\n\n```json:metadata\n{\"files\": [\"lib/chrono_forge/definition_analyzer.rb\", \"test/support/definition_fixtures.rb\", \"test/definition_analyzer_test.rb\"], \"verifyCommand\": \"bundle exec ruby -I test test/definition_analyzer_test.rb\", \"acceptanceCriteria\": [\"durably_repeat$tick single repeat node\", \"same-class helper traced in position\", \"loop-with-durable warns\", \"no infinite recursion\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 6,
+      "subject": "Task 6: Dashboard — DefinitionOverlay",
+      "status": "completed",
+      "blockedBy": [1],
+      "description": "Annotate nodes with runtime status from execution_logs; fan-out/repeat aggregates via BranchProbe/rep logs; append unmapped nodes.\n\n```json:metadata\n{\"files\": [\"chrono_forge-dashboard/app/presenters/chrono_forge/dashboard/definition_overlay.rb\", \"chrono_forge-dashboard/test/definition_overlay_test.rb\"], \"verifyCommand\": \"cd chrono_forge-dashboard && bundle exec rake test TEST=test/definition_overlay_test.rb\", \"acceptanceCriteria\": [\"exact-name status\", \"branch/merge counts\", \"repeat repetitions\", \"unmapped logs appended\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 7,
+      "subject": "Task 7: Dashboard — MermaidRenderer",
+      "status": "completed",
+      "blockedBy": [6],
+      "description": "Statused nodes + edges -> Mermaid flowchart TD string with shapes by kind, :::status classes, guard edge labels, classDef lines.\n\n```json:metadata\n{\"files\": [\"chrono_forge-dashboard/app/presenters/chrono_forge/dashboard/mermaid_renderer.rb\", \"chrono_forge-dashboard/test/mermaid_renderer_test.rb\"], \"verifyCommand\": \"cd chrono_forge-dashboard && bundle exec rake test TEST=test/mermaid_renderer_test.rb\", \"acceptanceCriteria\": [\"flowchart TD header\", \"node line per node with :::status\", \"edge lines with guard labels\", \"classDef per used status\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 8,
+      "subject": "Task 8: Dashboard — definition page (route/controller/view/Mermaid/link)",
+      "status": "completed",
+      "blockedBy": [5, 6, 7],
+      "description": "GET workflows/:id/definition page — analyze class, overlay run, render Mermaid client-side (vendored), warnings panel, graceful degradation, link from detail page.\n\n```json:metadata\n{\"files\": [\"chrono_forge-dashboard/config/routes.rb\", \"chrono_forge-dashboard/app/controllers/chrono_forge/dashboard/definitions_controller.rb\", \"chrono_forge-dashboard/app/views/chrono_forge/dashboard/definitions/show.html.erb\", \"chrono_forge-dashboard/app/assets/chrono_forge/dashboard/mermaid.min.js\", \"chrono_forge-dashboard/app/views/chrono_forge/dashboard/workflows/show.html.erb\", \"chrono_forge-dashboard/test/definitions_controller_test.rb\"], \"verifyCommand\": \"cd chrono_forge-dashboard && bundle exec rake test TEST=test/definitions_controller_test.rb\", \"acceptanceCriteria\": [\"200 with flowchart TD for analyzable wf\", \"unknown class degrades to warning not 500\", \"detail page links to page\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 9,
+      "subject": "Task 9: Full suite + docs",
+      "status": "completed",
+      "blockedBy": [8],
+      "description": "Both packages green, lint clean, document the definition page.\n\n```json:metadata\n{\"files\": [\"chrono_forge-dashboard/README.md\"], \"verifyCommand\": \"bundle exec rake test && cd chrono_forge-dashboard && bundle exec rake test\", \"acceptanceCriteria\": [\"core suite green\", \"dashboard suite green\", \"lint clean on new files\"], \"requiresUserVerification\": false}\n```"
+    }
+  ],
+  "lastUpdated": "2026-07-01T00:00:00Z"
+}

data/docs/superpowers/specs/2026-07-01-workflow-definition-dag-design.md

@@ -0,0 +1,203 @@
+# Workflow Definition DAG — static "future timeline" for ChronoForge
+
+**Status:** Design approved (pending written-spec review)
+**Date:** 2026-07-01
+**Reference:** the `durable_flow` gem's `DefinitionAnalyzer` (Prism-based static analyzer + definition DAG overlaid with runtime status).
+
+## Problem
+
+The dashboard today shows only the **historical** timeline of a workflow — the
+`execution_logs` that have already run. There is no forward view: an operator
+can't see the steps a workflow *will* run, where the current run sits in the
+overall shape, or which branches/loops are still ahead.
+
+ChronoForge workflows are plain Ruby: a `perform` method that the engine
+**replays** every resume, with each durable step identified by a string name
+(`durably_execute$name`, `wait_until$cond`, `branch$name`, `merge$a,b`,
+`durably_repeat$name$<ts>`). Because the structure is expressed in source, we can
+recover a *projection* of the step sequence by statically parsing `perform` with
+Prism — without executing anything — and then paint the run's actual status onto
+that static map.
+
+## Goal
+
+A **new per-run dashboard page** that renders a workflow's **conditional DAG**
+(the static definition graph) with the current run's `execution_logs` **overlaid**
+as node status. The existing workflow detail page is unchanged; it gains a link
+to this page.
+
+Non-goals for v1 are listed under [Scope](#scope-v1).
+
+## Key decisions (locked during brainstorming)
+
+1. **Primary consumer:** dashboard overlay — run status painted on the static map
+   (mirrors durable_flow's run → definition-DAG view).
+2. **Map shape:** a **conditional DAG** — guarded edges for `if`/`continue_if`,
+   fan-out groups for branches, joins for merges.
+3. **Fidelity:** **conservative + trace same-class helper methods**. Resolve step
+   names statically where possible; anything unresolvable (computed `name:`,
+   data-dependent loop count, a durable call behind an unknown/external call)
+   becomes an explicit **`dynamic` node with a warning**. No unrolling, no
+   cross-class tracing.
+4. **Rendering:** **Mermaid.js** (client-side, vendored). The analyzer's graph
+   model is rendering-agnostic; a renderer emits Mermaid flowchart text with
+   status encoded as node classes.
+5. **Static vs runtime:** static Prism analysis is the source of the *shape*
+   (only it can show not-yet-run steps and untaken branches); the run log is the
+   *overlay*, never the source of the graph.
+6. **Placement:** a **new route/page**, not an inline addition to the detail page.
+
+## Architecture
+
+```
+workflow_class
+   │  DefinitionAnalyzer.call            (core gem; Prism; memoized by class + source digest)
+   ▼
+Definition (Node[], Edge[], warnings)    (plain, JSON-serializable value objects)
+   │  DefinitionOverlay(execution_logs)  (dashboard; read-only queries; per-run; never cached)
+   ▼
+statused Definition
+   │  MermaidRenderer                     (dashboard; statused graph → flowchart text)
+   ▼
+new DAG page  →  vendored Mermaid JS renders client-side (inside data-poll-region)
+```
+
+### Core gem — `lib/chrono_forge/` (rendering-agnostic, no dashboard/DB dependency)
+
+- **`ChronoForge::DefinitionAnalyzer`** — `.call(workflow_class) → Definition`.
+  - Resolves `workflow_class.instance_method(:perform).source_location`, reads the
+    file, `Prism.parse`, locates the `perform` def node, and walks its body with a
+    visitor.
+  - **Traces durable calls in same-class helper methods** to a fixed point within
+    the class (a call to a method defined on the same class whose body contains
+    durable DSL calls is expanded inline; recursion is guarded).
+  - Emits nodes, edges, and warnings. **Only reads source text — never touches the
+    DB, never executes workflow code.**
+- **`ChronoForge::Definition`** (+ `Node`, `Edge`) — plain value objects,
+  JSON-serializable so a `Definition` can be cached.
+  - `Node`: `id`, `kind` ∈ `{:execute, :wait, :wait_until, :continue_if, :branch,
+    :merge, :repeat, :dynamic}`, `label`, and **either** an exact `step_name`
+    **or** a `step_name_pattern` (fan-out/repeat/dynamic), plus optional `guard`
+    (condition source label) and `warnings`.
+  - `Edge`: `from`, `to`, optional `guard` label, and a `kind` (`:seq`,
+    `:conditional`, `:fanout`, `:join`, `:terminal`).
+
+### Dashboard package — `chrono_forge-dashboard/`
+
+- **`DefinitionOverlay`** — takes a `Definition` + a workflow's `execution_logs`
+  (and, for `:branch`/`:merge` nodes, child-workflow state counts via the existing
+  `BranchProbe`) and annotates each node with a runtime `status`. Read-only.
+- **`MermaidRenderer`** — `statused Definition → flowchart text`; status encoded
+  as `classDef` + `class` assignments.
+- **New controller action + view** — `GET workflows/:id/definition`, plus a
+  "Definition graph" link from the existing detail page.
+- **Vendored Mermaid JS** — the dashboard's first client script, initialized
+  inside the existing `data-poll-region` so the DAG re-renders on the normal
+  page refresh.
+
+## Node → step-name binding
+
+Each node knows the step-name it *would* produce, so the overlay is a lookup, not
+guesswork:
+
+| DSL call | Node kind | Binds to |
+|---|---|---|
+| `durably_execute :m` / `name: "x"` | `:execute` | exact `durably_execute$x` (or `$m`) |
+| `durably_execute :m, name: <expr>` | `:dynamic` | prefix `durably_execute$`, by ordinal |
+| `wait <duration>, "n"` | `:wait` | exact `wait$n` (name is the 2nd positional) |
+| `wait_until :cond` | `:wait_until` | exact `wait_until$cond` |
+| `continue_if :cond` | `:continue_if` | exact `continue_if$cond` |
+| `branch :name { spawn/spawn_each }` | `:branch` (fan-out) | `branch$name` + child-workflow aggregate |
+| `merge_branches :a, :b` | `:merge` (join) | `merge$a,b` (names sorted) |
+| `durably_repeat :name` | `:repeat` (loop) | `durably_repeat$name` coord + `$<ts>` reps |
+
+**Fan-out (`branch`/`spawn_each`) and `durably_repeat` collapse to a single node
+with aggregate status** — not one node per child/iteration.
+
+## Overlay status vocabulary (→ Mermaid classes)
+
+- `done` — matching log is `completed`.
+- `active` — log is `started`/`running`, not completed.
+- `pending` — reached but not done (a coordination log exists, work outstanding).
+- `not_reached` — no log yet.
+- `failed` / `stalled` — from the log state.
+- `conditional` — statically guarded; may be skipped.
+- `dynamic` — unresolved name; bound by prefix + ordinal.
+- `unmapped` — **a runtime log with no matching static node**; appended so
+  analyzer gaps are surfaced, not hidden.
+
+Aggregates:
+- `:repeat` → "N done, current active, `till` met?" from the coordination log +
+  its `$<ts>` repetition logs.
+- `:branch`/`:merge` → child-workflow state counts (running/idle/completed/failed)
+  via `BranchProbe`.
+
+## Edges & conditionals
+
+- Sequential DSL calls → `:seq` edges.
+- `if`/`unless`/`case`/`&&`/`||`/early-return around a step → `:conditional` edge
+  labeled with the condition source; steps only reachable under a guard render
+  `conditional`.
+- `continue_if` → a gate node; its false path is a `:terminal` edge (workflow
+  halts).
+- `branch` block → fans out (`:fanout`) to its spawn/`spawn_each` child-group;
+  `merge_branches` is the `:join` those edges reconnect into.
+- `each`/`times`/`while` containing durable calls → one node + a "dynamic loop
+  count" **warning** (conservative — no unrolling).
+
+## Error handling
+
+The analyzer must never break the dashboard:
+
+- Source unavailable (`source_location` nil, C-defined, `eval`'d, unreadable
+  file) → return a `Definition` carrying a single `unavailable` warning; the page
+  renders "can't be statically analyzed" gracefully. Never raises.
+- Any Prism parse issue degrades the same way (Prism is error-tolerant).
+- Missing/unloadable `job_class`, or a partially-resolved analysis → render what
+  was found plus a warnings panel.
+- **Analyzer is pure/read-only over source text**; the overlay does read-only
+  queries only.
+
+## Caching
+
+- Memoize `Definition` by `job_class` + source-file digest — auto-invalidates on
+  dev code reload, stable in prod.
+- The **overlay is never cached** — it is per-run and changes every poll.
+
+## Testing
+
+- **Analyzer unit tests (no DB):** a fixture set of workflow classes — linear,
+  conditional/`continue_if`, `branch`+`spawn_each`, `durably_repeat`, dynamic
+  `name:`, helper-traced, unanalyzable loop — asserting node kinds, edges, guards,
+  and warnings. Deterministic and fast.
+- **Overlay tests (dashboard harness):** seed `execution_logs` + child workflows;
+  assert per-node status, fan-out aggregates, repeat counts, and the `unmapped`
+  path.
+- **`MermaidRenderer`:** golden-text tests (statused `Definition` → expected
+  flowchart string).
+
+## Scope (v1)
+
+**In:** all seven primitives as nodes + conditional edges + fan-out/repeat
+aggregation + the overlay + the new per-run DAG page + Mermaid rendering;
+same-class helper tracing.
+
+**Out (deferred):**
+- Cross-class helper tracing.
+- Recursively expanding a spawned child *workflow class* into its own graph
+  (v1 shows it as one fan-out node; "drill into child" is a future feature).
+- Per-node ETA/timing beyond status + counts (that's the separate progress/ETA
+  feature).
+- A class-level (no-overlay) definition view (trivial later addition).
+
+## Open questions / risks
+
+- **Helper-tracing fixed point:** need a clear rule for what counts as "a durable
+  call inside a same-class method" vs. ordinary work, and recursion/mutual-call
+  guards. The analyzer stays conservative — when in doubt, emit a `dynamic` node +
+  warning rather than a confident-but-wrong expansion.
+- **Ordinal binding for dynamic siblings** is best-effort; if two dynamic
+  `durably_execute` calls interleave at runtime out of source order, the overlay
+  may mis-bind. Acceptable for v1 (surfaced as `dynamic`).
+- **Mermaid as first client dependency** — keep it vendored and isolated so the
+  rest of the dashboard stays server-rendered.

data/docs/superpowers/specs/2026-07-09-chrono-forge-reaper-design.md

@@ -0,0 +1,175 @@
+# Design: Stalled-Workflow Reaper for ChronoForge
+
+**Date:** 2026-07-09
+**Gem:** `chrono_forge` (with `chrono_forge-dashboard`)
+**Status:** Approved for planning
+
+## Problem
+
+A workflow that is mid-pass when its worker is **hard-killed** (SIGKILL: deploy/rollout,
+OOM, node eviction, SolidQueue heartbeat prune) is stranded permanently in `state: running`
+with a stale lock, and nothing ever resumes it.
+
+The mechanism, confirmed against the code:
+
+- `Executor#perform` releases the lock and publishes the resume continuation in its `ensure`
+  block (`lib/chrono_forge/executor.rb:178-197`): `release_lock` first, then
+  `flush_continuation!`.
+- `enqueue_continuation` (`executor.rb:369-371`) only records `@continuation` in memory;
+  `flush_continuation!` (`executor.rb:376-382`) is what actually enqueues the ActiveJob.
+- On SIGKILL, Ruby's `ensure` does not run. So (1) `release_lock` never runs — the row stays
+  `state: running` with a past `locked_at`; and (2) `flush_continuation!` never runs — no job
+  is scheduled to resume the workflow.
+
+The workflow is fully *resumable* — `Workflow#executable?` is `idle? || running?`
+(`workflow.rb:48-50`) and `LockStrategy.acquire_lock` steals any lock older than
+`max_duration` (10 min) (`lock_strategy.rb:17-21`) — but nothing re-enqueues it. Existing
+recovery mechanisms do not cover this:
+
+- **`BranchMergeJob` rekick** (`branch_merge_job.rb:232-273`) only re-enqueues children that
+  are `state: idle, started_at: nil` (never-started dropped dispatches). A child hard-killed
+  **mid-pass** is `state: running` with `started_at` set — explicitly excluded (see the
+  comment at `branch_merge_job.rb:226-231`). So branch children have the identical gap.
+- **Workflow-level retry** rides on the same process that must survive to its `ensure`; a
+  killed process never reaches it.
+- **`retry_now`/`retry_later`** require `retryable?` (`stalled? || failed?`,
+  `workflow.rb:53-55`); a stranded workflow is `running`, so they refuse it.
+- **Dashboard "Force unlock"** clears the lock but enqueues nothing.
+
+Real-world impact (reported): 735 workflows stranded over ~8.5 months in one production app,
+still accruing ~8/day.
+
+## Solution Overview
+
+Add a reconciliation entry point, `ChronoForge::Workflow.reap_stalled`, that finds workflows
+stuck in `running` past a safety threshold and re-enqueues them. Re-enqueue is safe:
+`acquire_lock` steals the stale lock and completed durable steps replay as no-ops.
+
+### Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Shipping | **Class method only** | No Railtie/rake task/self-scheduling job. Host apps call it from their own cron/recurring job. Smallest surface; no new gem infrastructure. |
+| Scope | **All stranded `running` workflows** (top-level AND branch children) | Strictly more correct — rekick misses mid-pass-killed children. Re-enqueue of a child directly is the proven-safe pattern rekick already uses. |
+| Threshold | **Config + per-call override** | `ChronoForge.config.reap_stale_after` (default `30.minutes`), overridable via `stale_after:` arg. Parity with the existing `branch_merge_queue` config. |
+| Deliverable | **Code + tests + docs** | Implementation, tests (incl. simulated hard-kill strand), and docs covering the reaper + step-idempotency expectations. |
+
+## Component
+
+`ChronoForge::Workflow.reap_stalled` — a class method on the AR model. It only queries and
+re-enqueues; it holds no lock and performs no replay itself (the re-enqueued job does the
+replay, under the normal lock protocol).
+
+```ruby
+# ChronoForge::Workflow
+def self.reap_stalled(stale_after: ChronoForge.config.reap_stale_after)
+  reaped = 0
+  where(state: states[:running])
+    .where("locked_at < ?", stale_after.ago)
+    .find_each do |wf|
+      wf.job_klass.perform_later(wf.key, **wf.kwargs.symbolize_keys)
+      reaped += 1
+    rescue => e
+      Rails.logger.error { "ChronoForge reap failed for workflow(#{wf.key}): #{e.class}: #{e.message}" }
+    end
+  Rails.logger.info { "ChronoForge reaped #{reaped} stalled workflow(s)" } if reaped.positive?
+  reaped
+end
+```
+
+Design points:
+
+- **Target = `running` + stale `locked_at`.** The strand happens precisely because the
+  `ensure` never ran, so `release_lock` never flipped the row off `running`. A `NULL locked_at`
+  cannot match `locked_at < ?` and is naturally excluded (an anomalous running-without-lock row
+  is not our target).
+- **Sweeps children too.** No `parent_execution_log_id` filter. A re-enqueued child runs,
+  replays, completes, and updates its `BranchProbe` state so the parent's merge poller observes
+  completion.
+- **Re-enqueue via the public guarded `perform_later`.** `wf.kwargs` is a JSON column (string
+  keys); `.symbolize_keys` for `**`, matching `setup_workflow!` and `rekick_dropped_jobs`. The
+  guard rejects `RESERVED_KWARGS`, which stored user kwargs never contain. Fresh `attempt: 0`
+  — a full workflow-retry budget, exactly like a normal resume.
+- **Per-row rescue** so one bad row (e.g. cross-version kwarg drift tripping the enqueue guard)
+  never aborts the sweep — mirrors `rekick_dropped_jobs` (`branch_merge_job.rb:265-270`).
+- **Returns the reaped count** for cron visibility; logs via `Rails.logger` block syntax.
+
+## Configuration
+
+`max_duration` (previously a hardcoded `10.minutes` in the executor) becomes a config value,
+and `reap_stale_after` **derives from it** so the "reap threshold must exceed the lock-steal
+threshold" invariant is automatic rather than documented-and-hoped.
+
+Add to `ChronoForge::Configuration`:
+
+```ruby
+# How long a single pass may hold its lock before it's stealable (feeds
+# LockStrategy.acquire_lock via the executor's #max_duration). Default 10 minutes.
+attr_accessor :max_duration
+
+# Age past which a :running workflow is considered stranded and re-enqueued by
+# Workflow.reap_stalled. Defaults to 3x max_duration (30 min out of the box) so it always
+# clears the lock-steal threshold; an explicit value overrides the derived default.
+def reap_stale_after
+  @reap_stale_after || max_duration * 3
+end
+attr_writer :reap_stale_after
+
+# in #initialize:
+@max_duration = 10.minutes
+@reap_stale_after = nil
+```
+
+The executor's `#max_duration` now reads `ChronoForge.config.max_duration` instead of
+returning a literal. Deriving `reap_stale_after` from `max_duration` means raising one raises
+the other, so the reaper can never be configured below the lock-steal threshold by accident.
+
+## Idempotency & Safety (documented behavior)
+
+- **Concurrency-safe.** Overlapping cron runs, or a re-enqueue landing while the old stale
+  lock still shows, at worst enqueue a duplicate job — the second loses the `acquire_lock`
+  race and no-ops via `ConcurrentExecutionError`. Mild, harmless churn. Recommend a cron
+  interval comfortably longer than a typical resume pass.
+- **Step idempotency.** Reaping replays the interrupted pass. A `durably_execute` step only
+  short-circuits when `completed`, so a step whose side effect committed but whose log never
+  reached `completed` will re-run on replay. Steps with external side effects must be
+  idempotent (natural/unique key + `create_or_find_by`/rescue). Documented alongside
+  `wait`/`durably_execute`.
+
+## Non-Goals (conscious boundaries)
+
+- **Dropped `BranchMergeJob` poller → parent stranded `idle`.** A parent parked on a merge
+  whose poller was hard-killed sits `idle`, not `running`, so this reaper won't catch it. A
+  distinct failure mode; the code already hints (`branch_merge_job.rb:181-184`) that a
+  "`next_poll_at` far in the past with work still pending" detector is the right fix. Out of
+  scope here.
+- **Micro-window between `release_lock` and `flush_continuation!`.** A process dying between
+  those two statements yields `idle` + no continuation. Theoretically possible, not seen in the
+  reported evidence (all strands were `running`), not covered.
+
+## Testing
+
+- **Query selection (unit):** selects only `running` + stale-lock rows; excludes
+  fresh-lock `running`, `idle`, `completed`, `failed`, `stalled`, and `NULL locked_at`.
+- **Strand-and-recover (behavioral):** create a workflow, force it into `running` with an old
+  `locked_at` and no scheduled resume job (simulating the hard-kill), run `reap_stalled`,
+  assert a job is enqueued and that draining the queue resumes and completes the workflow.
+  Cover both a top-level workflow and a branch child.
+- **Per-row rescue:** a row that raises on re-enqueue does not abort the sweep; the returned
+  count reflects only successful re-enqueues.
+- **Config:** default `reap_stale_after` honored; per-call `stale_after:` override honored.
+
+## Documentation
+
+- Document `Workflow.reap_stalled` and the recommended cron wiring (host-owned; no shipped
+  task), including the `reap_stale_after > max_duration` constraint.
+- Document the step-idempotency expectation alongside `wait`/`durably_execute`.
+
+## Alternatives Considered
+
+- **Railtie + `chrono_forge:reap` rake task** (angarium `angarium:reap` parity) — rejected;
+  heavier, would add the gem's first Railtie.
+- **Self-scheduling reaper ActiveJob** — rejected; adds an always-on job and scheduling
+  assumptions the host may not want.
+- **Top-level-only sweep** (`parent_execution_log_id IS NULL`) — rejected; leaves
+  mid-pass-killed branch children stranded, which rekick does not recover.