[Harry-kp]

Why

approval_engine 1.0.0 shipped on 2026-06-17 and was never announced. The numbers as of today: 5 unique GitHub visitors in 14 days, 1 star, 0 forks, one all-time referrer (rubygems.org), and zero mentions of the gem anywhere on the web. It was not evaluated and rejected — it was never seen.

Two real product gaps turned up while diagnosing that:

1. The README's headline differentiator — "routing rules that admins change at runtime, without a deploy" — had no code behind it. config/routes.rb was resources :approvals, only: %i[index show] and there was no CRUD for TrackTemplate, TemplateStep or TriggerRule anywhere in the gem. Admins had to use a Rails console.
2. There was no notification layer at all — no mailer, no reminder. An approval system that never tells the approver they have an approval is a half-system, and every adopter was writing that themselves.

Prior art says the category has demand: ringlesoft/laravel-process-approval has 552 stars for the same idea in Laravel.

What's in it

ApprovalEngine.define_flow — a declarative, idempotent flow builder. Getting one approval running used to take ~10 concepts. Now:

ApprovalEngine.define_flow "High-value invoice", tenant: account.id, model: Invoice do
  on :create, when: { amount: { gt: 10_000 } }

  step "Manager sign-off", group: "manager"
  step "CFO sign-off",     group: "cfo"
end

It writes real TrackTemplate / TemplateStep / TriggerRule rows, so the admin UI can still edit them. It reconciles rather than inserts, so it is safe in db/seeds.rb on every deploy — and it cannot disturb an in-flight approval, because ApprovalBuilder copies template facts onto the ledger rather than holding a foreign key. Rules are deactivated, never destroyed, because Approval#trigger_rule is on_delete: :nullify and deleting one would silently erase provenance.

A built-in admin UI, gated by config.admin_enabled, default false. Full CRUD for templates, steps and rules, with a zero-JavaScript rule builder: field dropdown populated from exposes_for_approval, human operator labels, and an automatic fallback to a raw JSON Logic textarea for any condition the simple form cannot represent without changing its meaning.

Default false is deliberate and not a preference: 1.0 shipped a read-only dashboard that hosts mounted behind whatever auth they judged adequate for information disclosure. A gem upgrade must not turn that route into "anyone who can reach this can approve a payment."

Notifications and reminders, gated by config.notifications_enabled, default false. Six mailer actions, HTML and text, dispatched through the existing transactional outbox so a dead SMTP host can never roll back an approval. ReminderSweepJob nudges quiet approvers, idempotently.

ApprovalEngine::Condition — the shared JSON Logic authoring seam. JSON Logic is the right storage format and the wrong authoring format; this translates between a field/operator/value triple and the AST, and is honest about its limits rather than mangling a rule someone hand-wrote.

Positioning. The README opened with "Multi-tenant, immutable-ledger human approval flows for Rails" — an accurate spec sheet aimed at someone who already knows they want it. It now opens with the job. The "Look elsewhere when" list used to route its largest audience away with "you just need a boolean flag"; it now shows that column becoming a projection of the ledger, so adopting doesn't mean rewriting the queries you have.

Also: test/docs_test.rb fails CI when the README documents a config key, an ApprovalEngine method, a generator, or an image that doesn't exist. A README whose first code block raises NoMethodError is a worse launch than no launch.

Review

An adversarial pass over the diff (five lenses; each finding independently attacked by a skeptic and a line-by-line tracer) found defects that are fixed here:

• Deleting a trigger rule from the admin erased approval provenance. The template's delete path already refused this and reconcile_rules! already deactivated instead of destroying — the rule controller was the one place that didn't.
• Subclassing NotificationMailer raised ActionView::MissingTemplate for all six notifications, because Action Mailer resolves templates from the subclass's own mailer_name. The documented config.mailer_class route did not work.
• define_flow rejected valid JSON Logic. var is also written ["amount", 0] and "a.b"; both were compared verbatim against the exposure list, so the seed died blaming an attribute name nobody typed.
• parallel(approvals_required: <count>) wrote a template ApprovalBuilder then refused to build — the count reads as flat across the layer but is validated per group.
• TemplateStep validated layer but not timeout_after, so a negative deadline typed into the admin produced steps overdue on creation.
• reassign! never cleared reminded_at, so the person handed a stalled approval was the one person the sweep never reminded.
• A substring in round-tripped through Condition as array membership, silently changing what a hand-written rule matched.

The CHANGELOG's upgrade note was also overclaiming. It said "no behaviour change"; in fact step.activated is emitted unconditionally, so existing installs get one extra outbox row per step and wildcard approval_engine.* subscribers see a new channel. The gate stays as-is — that's additive, and both surfaces that touch users or host code are properly off — but the note now says so.

Findings deliberately not fixed are recorded in #8.

Verification

• 319 runs, 1028 assertions, 0 failures (baseline before this work: 141). Stable across seeds and under eager loading.
• bundle exec rubocop clean across 78 files.
• gem build clean; packaging asserted by test/gemspec_test.rb (docs ship, assets/ and docs/launch/ do not).
• The admin UI and its raw-JSON fallback were driven in a real browser, not just unit-tested. The screenshots in the README are from that session.

Not done, on purpose

• No hosted live demo. It needs Docker/Fly credentials I can't test against here, and an untested deploy config that 404s on launch day is worse than none. bin/demo is the path, and the seed now produces a lived-in dataset rather than one empty approval.
• Still PostgreSQL-only. jsonb and gin are load-bearing for routing; changing that is an architecture project, not an adoption release.
• Nothing has been posted anywhere. The drafts are in docs/launch/posts.md — and their origin story is invented and flagged as such; it needs replacing with what actually happened before anything goes out.

🤖 Generated with Claude Code