chrono_forge 0.9.1 → 0.11.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-06-03-unified-retry-policy-design.md

@@ -0,0 +1,226 @@
+# Unified RetryPolicy — Design
+
+**Date:** 2026-06-03
+**Status:** Approved (pending spec review)
+**Scope:** Internal API. No external callers; clean break, no deprecation shim.
+
+## Problem
+
+ChronoForge currently has three independent retry systems, two backoff
+algorithms, and three different "should we retry?" decision models:
+
+1. **Workflow-level** (uncaught errors in `perform`)
+   - `should_retry?(error, attempt)` → hardcoded `attempt < 3`, ignores the error
+   - `RetryStrategy.schedule_retry` → fixed array `[1s, 5s, 30s, 2m, 10m]`
+   - guard: `attempt >= RetryStrategy.max_attempts` (= 5)
+   - **Dead config:** `should_retry?` stops at 3, so the array's `2m`/`10m`
+     entries and `max_attempts == 5` are unreachable.
+
+2. **Step-level** (`durably_execute`, `durably_repeat`)
+   - `max_attempts:` param (default 3)
+   - backoff `2**[attempts, 5].min` — a *different* algorithm (exponential,
+     32s cap) than the workflow level
+   - `durably_repeat` adds `on_error: :continue | :fail_workflow`
+   - **Dead arg:** the reschedule passes `retry_method:`, which `perform`'s
+     signature never binds — it falls into `**kwargs` and is ignored. Replay
+     skipping completed steps is what actually resumes the step, not this arg.
+
+3. **`wait_until`**
+   - `retry_on: [ExceptionClass, …]` — a third model (error-class allowlist)
+   - no attempt cap (bounded by `timeout`), same `2**n` backoff
+
+Additional finding: workflow-level attempts (the `attempt:` job arg, lives only
+in the job payload) and step attempts (`execution_log.attempts`, a DB column)
+are unrelated counters.
+
+Net: backoff is implemented twice and configurable nowhere per-call; "should we
+retry?" is answered three ways (attempt-count / max_attempts / error-class); and
+the workflow-level cap is internally contradictory (3 vs 5).
+
+## Goal
+
+Collapse to **one** `RetryPolicy` type with **one** backoff algorithm, used by
+all four sites. Today's three behaviors become three *default configurations* of
+the same type. Retry behavior becomes expressible per-call.
+
+The unification is of **type + mechanism**, not of default *values*: each call
+site keeps a default tuned to its purpose, but all defaults are instances of the
+same object and all are overridable.
+
+## Decisions (locked during brainstorming)
+
+| Decision | Choice |
+|---|---|
+| Ambition | Option A — one unified `RetryPolicy`, `wait_until` folded in |
+| Backoff curve | Exponential + jitter, single default, per-call overridable |
+| Compatibility | Clean break — internal code, fix all call sites in the same change |
+| Surface | Class-level default DSL + per-call `retry_policy:` override |
+| Attempt counters | Workflow-level stays in the `attempt:` job arg; steps stay on `execution_log.attempts`. Policy unifies; counting storage does not (no migration) |
+| `wait_until` poll cadence | Stays **out** of `RetryPolicy` (`check_interval`/`timeout` are polling, not retry) |
+| Per-site backoff defaults | Steps `max_attempts: 3, cap: 30`. Workflow-level `max_attempts: 10, cap: 600` — a tolerant window up to ~8.5 min (≈4 min typical with jitter) for transient infra errors on uncaught `perform` errors (revised post-review from an inconsistent `8/600`, where the 600 cap was unreachable). `cap: 600` is a per-delay ceiling, not a dead default: it binds when a caller configures more attempts. |
+
+## Design
+
+### 1. `RetryPolicy` value object
+
+New file: `lib/chrono_forge/executor/retry_policy.rb`
+
+```ruby
+RetryPolicy.new(
+  max_attempts: 3,        # Integer cap, or nil = no count cap (bounded elsewhere)
+  base: 1,                # seconds
+  cap: 30,                # seconds, max single delay
+  jitter: true,
+  retry_on: nil           # nil = retry any StandardError; [Classes] = only these
+)
+```
+
+Two methods are the entire decision surface. `attempts` is the 1-based count of
+attempts made so far, *including* the one that just failed (matching
+`ExecutionLog#attempts`); on the first failure `attempts == 1`.
+
+- `retryable?(error, attempts)` →
+  `(max_attempts.nil? || attempts < max_attempts)` **and** the error matches
+  `retry_on` (`retry_on.nil?` means any `StandardError`; otherwise
+  `retry_on.any? { |k| error.is_a?(k) }`).
+- `backoff_for(attempts)` → `delay = [cap, base * 2**(attempts - 1)].min`, then
+  equal jitter when enabled: `delay / 2.0 + rand(0.0..delay / 2.0)`. Returns an
+  `ActiveSupport::Duration` suitable for `set(wait:)`.
+
+**Jitter & determinism:** `backoff_for` is called once, at the moment a retry
+job is re-enqueued. The result is never persisted or replayed, so `rand`
+introduces no replay nondeterminism. (Stated explicitly because this is a
+replay engine.)
+
+### 2. Per-site default policies
+
+A single gem-wide default, overridable per class and per call. Two sites need
+distinct *defaults* to preserve current semantics:
+
+| Site | Default policy | Rationale (= today's behavior) |
+|---|---|---|
+| `durably_execute`, `durably_repeat` | `max_attempts: 3, base: 1, cap: 30, retry_on: nil` (retry **all** errors) | matches current `rescue => e; retry`; flaky calls fast-fail |
+| Workflow-level | `max_attempts: 10, base: 1, cap: 600, retry_on: nil` | only fires on uncaught `perform` errors (step failures stall instead), which are rare and may be transient infra blips. 10 attempts (up to ~8.5 min, ≈4 min typical with jitter) rides those out; each retry replays the whole workflow, so the count is bounded rather than open-ended. `cap: 600` (10 min) ceils any single backoff |
+| `wait_until` (error path) | `retry_on: []` (retry **nothing** by default) | a condition that *raises* is usually a bug, not transient — matches current `retry_on: []` |
+
+`wait_until`'s polling cadence (`check_interval` / `timeout`) is **not** retry
+and is untouched. `RetryPolicy` governs only what happens when the condition
+*raises*.
+
+### 3. Surface — class default + per-call override
+
+```ruby
+class ChargeWorkflow < ApplicationJob
+  prepend ChronoForge::Executor
+  retry_policy max_attempts: 5, base: 2, cap: 60   # class-wide default
+
+  def perform
+    durably_execute :charge, retry_policy: RetryPolicy.new(max_attempts: 8, retry_on: [Net::OpenTimeout])
+    wait_until :settled?, retry_policy: RetryPolicy.new(retry_on: [BankApiError])
+  end
+end
+```
+
+`retry_policy(**)` is a class-level DSL added by the prepended `Executor` that
+builds and stores a `RetryPolicy` in `default_retry_policy` (a `class_attribute`,
+so it inherits). The per-call kwarg is named `retry_policy:` (not `retry:`)
+because `retry` is a Ruby keyword — a `retry:` parameter could not be read inside
+the method without `binding.local_variable_get(:retry)`. `retry_policy:` also
+reads consistently with the class-level DSL.
+
+**Resolution rules (precise — to remove ambiguity):**
+
+- **Error-retry sites** (`durably_execute`, `durably_repeat`, workflow-level):
+  explicit per-call `retry_policy:` → class `default_retry_policy` → that site's
+  built-in default (table above). So a declared class default replaces the
+  built-in for *both* steps and the workflow level, collapsing their differing
+  built-ins (3/30 vs 5/30) onto one value. This is the intended, predictable
+  meaning of "class-wide default."
+- **`wait_until`** does **not** inherit the class `default_retry_policy`. It uses
+  its built-in `retry_on: []` unless an explicit per-call `retry_policy:` is passed.
+  Rationale: a class-wide "retry all errors 5×" must not silently turn
+  condition-evaluation bugs into retried errors. `wait_until`'s retry set is a
+  deliberate per-call opt-in, not a class-wide inheritance.
+
+### 4. Integration / deletions
+
+- **Delete** `lib/chrono_forge/executor/retry_strategy.rb` (`RetryStrategy`).
+- **Delete** private `should_retry?` in `executor.rb` (the dead `attempt < 3`).
+- **Delete** the dead `retry_method:` arg in `durably_execute`'s reschedule.
+- **Replace** the `max_attempts:` / `retry_on:` kwargs on `durably_execute`,
+  `durably_repeat`, and `wait_until` with a single `retry_policy:` kwarg.
+- **`executor.rb#perform`:** the resolved policy here is `default_retry_policy`
+  (class DSL) or the workflow-level built-in (`max_attempts: 10, cap: 600`);
+  there is no per-call `retry_policy:` since an uncaught error has no call site.
+  - top guard becomes `attempt >= resolved_policy.max_attempts`
+  - the `rescue => e` block routes through the resolved policy:
+    ```ruby
+    if policy.retryable?(e, attempt)
+      self.class.set(wait: policy.backoff_for(attempt)).perform_later(key, attempt: attempt + 1)
+    else
+      fail_workflow!(error_log)
+    end
+    ```
+- **`durably_execute` / `durably_repeat`:** on error, use
+  `policy.retryable?(e, execution_log.attempts)` and
+  `policy.backoff_for(execution_log.attempts)`; otherwise mark failed and raise
+  `ExecutionFailedError` (`durably_repeat` keeps its `on_error` branch).
+- **`wait_until`:** replace the `retry_on.include?(e.class)` check and the
+  inline `2**n` backoff with the resolved policy. The poll/timeout path is
+  unchanged.
+
+The old extensibility model — `self.class::RetryStrategy` magic constant +
+overriding private `should_retry?` — is removed in favor of passing a
+`RetryPolicy`.
+
+### 5. Backoff impact (informational)
+
+Delays in seconds; current step/wait curve is `2**min(attempts,5)`, current
+workflow curve is the fixed array (truncated at attempt 3 by the dead config).
+
+| Site | Today (actual) | New default |
+|---|---|---|
+| `durably_execute`/`durably_repeat` (`max_attempts:3`) | `2, 4` then fail | `~1, ~2` (jittered) then fail |
+| `wait_until` error path | `2, 4, 8, …` cap 32 | unchanged in shape; cap 30 |
+| Workflow-level | `1, 5, 30` then fail | `~1, 2, 4, 8, 16, 32, 64, 128, 256` (jittered) then fail, `max_attempts:10` (up to ~8.5 min, ≈4 min typical) |
+
+Steps and `wait_until` are effectively unchanged (jitter added, cap 32→30). The
+workflow level keeps the array's intended 5-attempt count but with one curve;
+it does **not** add a long backoff tail — each workflow-level retry replays the
+whole workflow, so the attempt count is deliberately kept modest.
+
+## Files touched
+
+- **New:** `lib/chrono_forge/executor/retry_policy.rb`
+- **Delete:** `lib/chrono_forge/executor/retry_strategy.rb`
+- **Edit:** `lib/chrono_forge/executor.rb` (perform rescue + guard, remove
+  `should_retry?`), `lib/chrono_forge/workflow.rb` (add `retry_policy` DSL +
+  `default_retry_policy`), `lib/chrono_forge/executor/methods/durably_execute.rb`,
+  `.../durably_repeat.rb`, `.../wait_until.rb`
+- **Edit:** test suite, example workflows, and `README.md` retry sections
+  (~lines 165–261, 393, 765–769) — clean break, all call sites updated together
+
+## Testing
+
+**`RetryPolicy` unit tests**
+- `retryable?` truth table: count cap reached/not; `max_attempts: nil` (never
+  count-capped); `retry_on: nil` (any StandardError); `retry_on: [A]` match and
+  miss; `retry_on: []` (never).
+- `backoff_for`: exponential growth; cap clamp; jitter bounds with a
+  seeded/stubbed `rand`; `jitter: false` is exact.
+
+**Integration (per method)**
+- retries → succeeds; retries → exhausts → fails (`ExecutionFailedError` /
+  `fail_workflow!`); per-call `retry_policy:` override is honored.
+- `wait_until`: fails fast on an unlisted error; retries a listed one; poll
+  cadence/timeout unaffected.
+- workflow-level: uncaught error retries with `attempt+1` and the workflow-level
+  policy; stops at `max_attempts`.
+- `durably_repeat`: `on_error: :continue` vs `:fail_workflow` still branch
+  correctly after exhaustion.
+
+## Out of scope
+
+- Migrating workflow-level attempt counting into the DB (explicitly deferred).
+- Changing `wait_until`'s polling model (`check_interval`/`timeout`).
+- `durably_repeat`'s `on_error` semantics (kept as-is).

data/docs/superpowers/specs/2026-06-25-chrono_forge-dashboard-design.md

@@ -0,0 +1,190 @@
+# ChronoForge Dashboard — Design
+
+**Date:** 2026-06-25
+**Status:** Approved (pending spec review)
+**Scope:** New companion gem `chrono_forge-dashboard`, a mountable Rails engine.
+Additive; does not change the published `chrono_forge` gem.
+
+## Problem
+
+ChronoForge exposes rich per-step data (execution logs, error logs, persistent
+context, wait states, periodic tasks) but no UI. Operators recover stalled
+workflows and inspect failures from a Rails console. Competing job dashboards
+(Sidekiq, GoodJob, Mission Control) show queues and jobs, not the interior of a
+long-running workflow. A free, self-contained dashboard over ChronoForge's data
+is both a useful tool and the project's strongest adoption lever.
+
+## Goal
+
+A mountable, zero-build Rails engine giving full visibility and operational
+control over ChronoForge workflows: list/triage, a step **replay timeline**, a
+context inspector, periodic-task health, wait-state age, and the recovery actions
+(`retry_later`, force-unlock, bulk retry) — behind fail-closed auth.
+
+## Decisions (locked during brainstorming)
+
+| Decision | Choice |
+|---|---|
+| Repo layout | **Monorepo subfolder** `chrono_forge-dashboard/` with its own gemspec; core gem excludes the dir from `spec.files` so the published `chrono_forge` stays lean. |
+| Scope | **Full build** — all tiers (visibility, triage, timeline, periodic health, wait-state, actions) in v1. |
+| Frontend | **Server-rendered, zero-build** — ERB + one bundled CSS + one vanilla JS file, served by the engine itself. No npm/bundler/importmap; CSP-friendly; polling for live updates. |
+| Auth | **Fail-closed, pluggable** — built-in HTTP Basic, a custom hook, or explicit `:none` (to use routing constraints). Mounting without configuring any of them **raises**. |
+| Data | **Reuse core models read-only**; engine holds its own query objects/presenters. No schema changes; minimal-to-no core changes. Offset pagination. |
+| Engine | Namespace-isolated `ChronoForge::Dashboard::Engine`, Zeitwerk-loaded. |
+
+## Architecture
+
+```
+chrono_forge/                         # repo root (core gem)
+  lib/ chrono_forge.gemspec           # core; rejects chrono_forge-dashboard/ from spec.files
+  chrono_forge-dashboard/
+    chrono_forge-dashboard.gemspec    # add_dependency "chrono_forge", "railties"
+    lib/chrono_forge/dashboard.rb         # config object + Engine
+    lib/chrono_forge/dashboard/engine.rb
+    app/controllers/chrono_forge/dashboard/...
+    app/views/chrono_forge/dashboard/...
+    app/assets/chrono_forge/dashboard/{dashboard.css,dashboard.js}
+    app/queries/chrono_forge/dashboard/...     # query objects
+    app/presenters/chrono_forge/dashboard/...  # timeline / context / sparkline builders
+    test/                              # Combustion dummy app mounting the engine
+```
+
+Host mounts it:
+
+```ruby
+mount ChronoForge::Dashboard::Engine, at: "/chrono_forge"
+```
+
+`isolate_namespace ChronoForge::Dashboard` keeps routes/helpers/table-name
+prefixes contained. Engine views and assets are wholly self-contained.
+
+## Components
+
+### 1. Configuration & auth (`ChronoForge::Dashboard`)
+
+A config singleton:
+
+```ruby
+ChronoForge::Dashboard.configure do |c|
+  c.http_basic = { username: ENV["CF_USER"], password: ENV["CF_PASS"] }  # built-in
+  # c.authenticate { |controller| controller.head(:forbidden) unless controller.current_user&.admin? }
+  # c.authentication = :none   # opt out; you mount behind your own routing constraint
+  c.polling_interval = 5        # seconds; 0 disables auto-refresh
+  c.page_size = 50
+  c.long_wait_threshold = 1.hour
+end
+```
+
+`BaseController` runs `before_action :authenticate!`, resolved fail-closed in
+this order:
+
+1. **hook present** → call it (host integrates Devise/Pundit/etc.).
+2. **else `http_basic` present** → `authenticate_or_request_with_http_basic`.
+3. **else `authentication == :none`** → permit (host guards via routing
+   constraint).
+4. **else → raise `ChronoForge::Dashboard::AuthenticationNotConfigured`** at
+   request time, with a message naming the three options.
+
+So a forgotten config fails loudly instead of leaking workflow context.
+
+### 2. Read / query layer
+
+- Reuses `ChronoForge::Workflow`, `ExecutionLog`, `ErrorLog` read-only.
+- **`WorkflowsQuery`** — filter by `state`, `job_class`, `key` (search),
+  date range; offset-paginated; recency-sorted.
+- **`StatsQuery`** — counts by state + recent failure rate in one grouped query
+  (no N+1).
+- **`StepNameParser`** — decodes step names into `{kind, name, timestamp}`:
+  `durably_execute$<name>`, `wait_until$<condition>`, `durably_repeat$<name>`
+  (coordination) and `durably_repeat$<name>$<ts>` (repetition). `$` is the core's
+  reserved delimiter, so parsing is unambiguous.
+- Detail-view logs are paginated (a `durably_repeat` workflow accumulates
+  unbounded repetition logs; never load them all).
+
+### 3. Presenters
+
+- **`TimelinePresenter`** — orders a workflow's `execution_logs` into a replay
+  sequence; each entry: kind, status (completed/failed/pending/waiting),
+  attempts, started/completed, duration, error summary. Repetitions roll up under
+  their coordination log. Marks the "current position" (last failed/running, or
+  the active wait).
+- **`ContextPresenter`** — renders the JSON context as a collapsible tree with
+  value types and a size-vs-16KB indicator. Read-only.
+- **`PeriodicHealthPresenter`** — per `durably_repeat` coordination log: last run
+  (`metadata.last_execution_at`), next scheduled, missed/timed-out count
+  (repetition logs with `error_class == "TimeoutError"`), recent-latency
+  sparkline data, and per-error `retry_counts` from metadata.
+- **`WaitStatePresenter`** — for idle workflows whose latest step is a pending
+  `wait_until`: condition, wait age (`now - last_executed_at`), `timeout_at`.
+
+### 4. Controllers & routes
+
+- `WorkflowsController#index` — list + stats + filters + pagination.
+- `WorkflowsController#show` — detail: timeline, context, errors, wait callout,
+  periodic health.
+- `WaitStatesController#index` — idle-waiting workflows by wait age, flagging
+  those past `long_wait_threshold`.
+- `ActionsController` (POST, CSRF-protected):
+  - `#retry` → `workflow.retry_later` (guarded by `retryable?`; 422 + flash if not).
+  - `#unlock` → clear `locked_at`/`locked_by`, set `idle` (loud duplicate-exec warning in the UI).
+  - `#bulk_retry` → `ChronoForge::Workflow.failed.find_each(&:retry_later)`; returns affected count.
+- `AssetsController#show` — serves `dashboard.css` / `dashboard.js` with long-cache
+  headers, so the engine needs no host asset pipeline.
+- Fragment endpoints (`index`/`show` with a partial format) back the JS polling
+  refresh.
+
+### 5. Frontend
+
+- ERB views + one layout; all classes prefixed `cf-`.
+- One `dashboard.css`, one `dashboard.js` (vanilla), served by `AssetsController`.
+- **CSP-friendly**: no CDN/external fonts; behavior attached via
+  `addEventListener` + `data-` attributes (no inline `<script>` handlers, no
+  inline event attributes).
+- JS responsibilities: collapsible context tree; confirm dialogs for destructive
+  actions; inline-SVG sparklines (no chart lib); polling that refreshes the
+  list/stats fragment (and a running workflow's detail) every
+  `polling_interval` seconds, with a pause toggle.
+
+## Error handling
+
+- Missing/legacy step names that don't parse fall back to a raw display rather
+  than raising.
+- Actions on a workflow whose state changed under the operator (e.g. retry on a
+  now-running workflow) surface the core's `WorkflowNotRetryableError` as a flash,
+  not a 500.
+- Force-unlock always shows the duplicate-execution warning and requires confirm.
+- Auth misconfiguration raises a clear, actionable error (see §1).
+
+## Testing
+
+Combustion dummy app (mirroring core's `test/internal`) mounting the engine, with
+seeded workflows across every state and a `durably_repeat` workflow. Minitest +
+standardrb.
+
+- **Queries**: `WorkflowsQuery` filters/pagination; `StatsQuery` counts;
+  `StepNameParser` for each kind incl. repetitions and unparseable names.
+- **Presenters**: timeline ordering + repetition rollup + current-position;
+  context tree + size indicator; periodic health (missed/timeout/sparkline);
+  wait-state age.
+- **Controllers**: index filters/pagination; show renders all panels; wait-state
+  list + threshold flag.
+- **Actions**: retry calls `retry_later` and guards non-retryable; unlock clears
+  the lock; bulk retry count.
+- **Auth**: raises when unconfigured; HTTP Basic accept/reject; hook;
+  `:none` permits.
+- **Assets**: `AssetsController` serves CSS/JS with cache headers.
+
+## Build order (for the implementation plan)
+
+Engine skeleton + gemspec + core `spec.files` exclusion + auth → list + stats +
+filters → detail (context + errors) → step replay timeline → periodic health +
+wait-state age → operational actions → assets + JS polling → README/docs. Each
+step is independently testable.
+
+## Out of scope (v1)
+
+- Real-time push (ActionCable/SSE) — polling only.
+- Editing context or workflow internals from the UI (read-only except the three
+  actions).
+- Cross-workflow search by context value (only key/class/state/date filters).
+- Triggering `CleanupJob` from the UI (operator runs cleanup on their schedule).