change_requests 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5121ac3d2657395d7e5587ab4cbed6ef9338bb17a15be4c7252ebd09a9a68202
-  data.tar.gz: 1255001fa45221fee226d66e986666e2a6b5f8fb417ffea8c89bb9069c8e7c9d
+  metadata.gz: 60c060656fc690b5b61123d202e1a3c857836d978cf378ec1275c923863c78c7
+  data.tar.gz: 629a3e88dde76ecc8e2d73c63948050d409fe19bc7ccc07704579cbb6b5098cf
 SHA512:
-  metadata.gz: 0627a54b60fe7cf7d2ad407f2f52227b28605b36a4c4b97bdb833a532155962d9d9dcde116feeb38d7b6ad13c154809be2b000de39e0d4e689950aa5ee2887b6
-  data.tar.gz: cb8d036a00b8f9cca8dab2d0ff00c9df9b0737662ea913072b93dce704d239cb39ae4bb46d203c9b93bdce729eceeefbe2da15f705980e235952e58adeec2bc0
+  metadata.gz: 9b7344ea008f2a2cec9ac577d44c51a2232475066ce280165f6c60b8ba8d8f617a168d062b2b49f3864d89b9992967b1c52193677d5d375f67f640861aee310e
+  data.tar.gz: 4502a057ff2fd923566ffaef2ee0149fe39170b11e6254d498138e2959b1eb3992cb2bdfeabc098aa9d205b6822cea5293f25cf41b509a9b63813af4b31e2a1b

data/README.md

@@ -53,6 +53,10 @@ external API can pass on as that API's own idempotency key.
 resolves, and that it answers the singleton method dispatch will call. Idempotence it cannot check, and
 does not try.
 
+[docs/05_execution_and_idempotency.md](docs/05_execution_and_idempotency.md) covers the rest: how an
+execution is claimed and settled, inline against background mode, and the two maintenance tasks that
+belong on a crontab.
+
 ## Architecture
 
 The decisions behind the gem's shape — and what each one costs — are recorded as ADRs in

data/config/locales/en.yml

@@ -37,11 +37,18 @@ en:
       not_cancelable: "This request cannot be cancelled."
       not_executable: "This request cannot be executed."
       not_rejectable: "This request cannot be rejected."
+      not_executing: "This request is not being executed."
+      not_stuck: "This request's execution has not been running long enough to write off."
       not_unapprovable: "This decision cannot be taken back."
       override_not_permitted: "You are not allowed to override the approvals."
       quorum_not_met: "This request does not have the approvals it needs."
       transition_error: "This request will not accept that."
 
+    # Event bodies the gem writes for itself, where there is no actor to supply one. Translatable
+    # rather than a hardcoded sentence, with the same fallback every other lookup has (§5.11).
+    events:
+      operation_undeclared: "This operation is no longer declared, so the request could never run."
+
     # Stage and quorum names are declaration identifiers, not display text (§5.9). The host names
     # every stage, so the gem ships no entry here at all: a host adds a key per name it declares,
     # and anything unlisted falls back to `name.humanize` - "sign_off" reads as "Sign off" with no

data/docs/05_execution_and_idempotency.md

@@ -0,0 +1,129 @@
+# Execution and idempotency
+
+A change request defers an action. This is what happens when someone finally executes it, what the
+gem promises about running it twice, and what has to be swept up afterwards.
+
+## The target contract
+
+A change-request target is a **public singleton method** taking **keyword arguments only**, whose
+effect is **idempotent** — running it twice with the same payload leaves the same result as running
+it once.
+
+```ruby
+class Members::UpdateRoles
+  def self.call(member_id:, roles:, change_request_id: nil)
+    Member.find(member_id).update!(roles: roles)
+  end
+end
+```
+
+There is no flag to declare otherwise. A failed request keeps its approval and may be retried up to
+`op.max_attempts`, so a target that cannot meet the requirement leaves that at `1` and gets one
+attempt — the retry ceiling is the only bound the gem can actually enforce.
+
+A target declaring `change_request_id:` receives it, **stable across every attempt**. A target
+calling an external API can hand that over as the API's own idempotency key, so a provider that saw
+a timed-out first call recognises the retry instead of charging twice. A per-attempt token would
+defeat exactly that.
+
+`rake change_requests:verify` checks the half of this that is checkable: every declared service
+resolves, answers the singleton method dispatch will call, and takes keyword arguments only.
+Idempotence it cannot check, and does not try.
+
+## Three transactions
+
+Execution must never happen twice, and no row lock may be held while the target runs — an external
+call can take seconds, and a lock held across it blocks every other reader of that request.
+
+```
+T1  with_lock   guard, claim the row, write the attempt, emit execution_started, COMMIT
+T2  no lock     invoke the target
+T3  with_lock   record the outcome on the request and the attempt, emit its event
+```
+
+The claim is **committed before the side effect runs**, which is what makes this stronger than one
+lock around all three. Between T1 and T3 the request is visibly `executing` to every other process
+and to the UI, and a second executor is refused.
+
+T1's `UPDATE … WHERE status IN ('approved','failed')` is the invariant beneath the guard: zero rows
+means somebody else holds the claim, and nothing is invoked. The unique index on
+`(change_request_id, number)` is its second lock — two processes cannot both write attempt 3.
+
+T3's failure branch is its own transaction, so a target that raises leaves **no business change and
+a durable record of the failure**: `error_class`, `error_message` and a bounded backtrace on the
+attempt, and an `execution_failed` event carrying the message.
+
+## Inline and background
+
+```ruby
+config.execution_mode = :inline      # default
+config.execution_mode = :background  # T2 and T3 run in ChangeRequests::Execution::Job
+config.job_class      = "ChangeRequests::Execution::Job"
+config.job_queue      = :default
+```
+
+T1 commits synchronously in both modes, so the request shows `executing` the moment the call
+returns and the UI never has to guess. Only the invocation and its outcome move to the job.
+
+`ChangeRequests::Execution::Job` is defined **only where ActiveJob is loaded**. The gem has no
+ActiveJob dependency, so a headless process may have `:background` configured and no job at all:
+it boots, `validate!` passes, and `ChangeRequests.background_available?` answers `false`. The
+failure arrives when something tries to enqueue, naming ActiveJob.
+
+## Keeping the tables tidy
+
+Three sweeps, none of which happens on its own. Each reports how many rows it moved and exits
+non-zero only on error.
+
+| Task | Moves | Why it is not automatic |
+|------|-------|--------------------------|
+| `change_requests:expire_stale` | `pending` / `approved` past `expires_at` → `expired` | nothing to decide; put it on cron |
+| `change_requests:reap_stuck_executions` | `executing` whose attempt nobody settled → `failed`, attempt `abandoned` | nothing to decide; put it on cron |
+| `change_requests:cancel_undeclared` | open requests whose operation is no longer declared → `canceled` | **run it by hand** — see below |
+
+### The crontab
+
+```cron
+5 * * * *  cd /app && bin/rails change_requests:expire_stale
+6 * * * *  cd /app && bin/rails change_requests:reap_stuck_executions
+```
+
+Five past rather than on the hour, so they do not land with every other hourly job in the estate,
+and a minute apart so they do not contend with each other.
+
+**The interval is a recommendation, not a requirement.** `expires_at` and the reaper's `older_than`
+are the real deadlines; a sweeper running late moves the same rows, just later. Run them every ten
+minutes if your requests are short-lived, or nightly if they are not.
+
+The reaper's threshold defaults to one hour and takes an override:
+
+```bash
+bin/rails change_requests:reap_stuck_executions OLDER_THAN=600
+```
+
+Set it comfortably longer than your slowest target. A threshold shorter than a legitimate run will
+write off an execution that is still working — the row goes to `failed` while the target keeps
+going, and nothing recalls it.
+
+### Why `cancel_undeclared` is not on that crontab
+
+A request whose `operation_key` is no longer declared can never execute, and the gem already treats
+it as finished: every guard but `Comment`, `Cancel` and `Reap` refuses it, and it disappears from
+inboxes and badges immediately.
+
+Both of those are **immediate and reversible**. Cancelling is neither — `canceled` is final. And a
+missing declaration is as likely to be a deploy accident, an initializer that did not load or a file
+renamed, as a deliberate removal. A scheduled sweep would turn a bad deploy into a table of
+permanently cancelled requests within the hour.
+
+So it runs when an operator has looked and decided:
+
+```bash
+bin/rails change_requests:cancel_undeclared
+```
+
+If the declaration vanished by mistake, revert the change instead and the requests carry on from
+where they were, with nothing lost.
+
+To retire an operation that still has live requests, deprecate rather than delete: keep the
+declaration, stop creating requests against it, and let the outstanding ones drain.

data/docs/adr/0015-one-guard-object-per-transition.md

@@ -24,14 +24,26 @@ and the presenter build the same object.
   `Guards::Base::REASONS`, the closed shared vocabulary. Branch order inside `refusal` is part of
   the contract: it decides which of several true refusals the person is shown.
 - `refuses_with` declares the error class, rather than deriving it from the guard's name —
-  `Comment` and `Expire` refuse with `NotAuthorized`, the decision guards with their own
+  `Comment`, `Expire` and `Reap` refuse with `NotAuthorized`, the decision guards with their own
   `TransitionError` ([ADR-0012](0012-declared-error-taxonomy.md)).
-- One reason overrides that declaration: `:already_finalized` always raises `AlreadyFinalized`,
-  whichever guard produced it, so a host rescuing "this request is over" catches every command. It
-  is the same class and the same reason the model's terminal-state guard raises underneath.
+- Two reasons override that declaration, through `Guards::Base::REASON_ERRORS`.
+  `:already_finalized` always raises `AlreadyFinalized`, whichever guard produced it, so a host
+  rescuing "this request is over" catches every command — the same class and reason the model's
+  terminal-state guard raises underneath. `:override_not_permitted` always raises
+  `OverrideNotPermitted`, so a host alerting on attempted break-glass rescues it by name rather
+  than filtering `NotExecutable` by reason.
 - The undeclared-operation refusal lives in `Guards::Base` and runs before `refusal`, so no guard
-  repeats it. `Comment` opts out with `exempt_from_undeclared_operation!` — a request stranded by a
-  removed declaration is exactly the one someone needs to leave a note on.
+  repeats it. Three guards opt out with `exempt_from_undeclared_operation!`: `Comment`, because a
+  request stranded by a removed declaration is exactly the one someone needs to leave a note on;
+  `Cancel`, because it is the one worth clearing away — and to anyone, the requester-or-approver
+  rule being dropped along with the refusal; and `Reap`, because a claim that died is dead whatever
+  the registry says. The third exists because `Cancel` refuses an `executing` request, so without
+  it a request claimed as its declaration vanished could be cleared by nothing at all.
+
+**One guard object, built once.** Where a command needs both the decision and what it was decided
+about, it reads them off the same instance rather than recomputing: `Guards::Approve#countable_quorums`
+is the quorums an approval links to, and `Guards::Reap#stuck_attempt` is the row the reaper writes
+off. Recomputing either in the command is how the reason and the write drift apart.
 
 **There is no `Guards::Create`.** A guard asks "may this actor do X *to this row*", and at creation
 there is no row. `Commands::Create` runs the three equivalent checks inline. The presenter's half of
@@ -58,3 +70,10 @@ implementation, not by a guard carrying a second signature.
   had already drifted once before that spec existed.
 - A guard resolves the acting actor through the registry, so an unregistered class raises
   `UnknownActorType` rather than producing a refusal. The allowlist is deliberately not a reason.
+- Two guards are system-only — `Expire` and `Reap` — so supplying an actor at all is itself the
+  refusal (`:not_system`). Every cross-guard spec has to special-case them, because the actor axis
+  the other six share does not apply.
+- `Guards::Execute` answers two questions in one class: the ordinary branch and §8.1's override
+  branch, chosen by an `override:` option. They are separate methods rather than one relaxed
+  ordering, but they are still one class, and a reader has to notice which branch a reason came
+  from.

data/docs/adr/0016-commands-are-the-only-writers.md

@@ -38,12 +38,28 @@ locked rather than the object it was handed.
 - `ActiveRecord::StaleObjectError` maps to `StaleRequest`. `lock_version` is the belt to
   `with_lock`'s braces.
 
-Two commands depart from the shape, each for a stated reason. `Commands::Create` has no row to lock
-until it has written one, so it wraps a transaction instead — the request and its whole stage,
-quorum, permission and eligible-actor graph are all-or-nothing.
-`Commands::EvaluateWorkflow` ([ADR-0017](0017-approvals-count-through-links.md)) takes no lock of its
-own: it is internal, invoked only from inside a caller that already holds one, and re-locking would
-reload the row that caller has just written to.
+**A distinct intent gets a distinct command class, never a flag.** Every command hard-codes the event
+kind it emits, so a caller-supplied kind would be the first exception to that. `Commands::Override`
+is `Execute` with `override: true`; `Commands::CancelUndeclared` is `Cancel` emitting
+`operation_undeclared` instead of `canceled`. Both are **subclasses**, not delegations, so the rows
+and events they write cannot drift from the command they wrap — there is nothing there to drift.
+`Cancel` carries exactly two seams for it, the event kind and the metadata, and nothing else.
+
+Three commands depart from the locking shape, each for a stated reason:
+
+- `Commands::Create` has no row to lock until it has written one, so it wraps a transaction instead
+  — the request and its whole stage, quorum, permission and eligible-actor graph are all-or-nothing.
+- `Commands::EvaluateWorkflow` ([ADR-0017](0017-approvals-count-through-links.md)) takes no lock of
+  its own: it is internal, invoked only from inside a caller that already holds one, and re-locking
+  would reload the row that caller has just written to.
+- `Commands::Execute` takes none either, for the opposite reason to Create's: §8 forbids holding a
+  lock across the target invocation, and the three transactions it drives each take their own
+  ([ADR-0022](0022-execution-in-three-transactions.md)).
+
+`Commands::SettleExecution` is the one command that does not stamp the acting actor on its event. It
+takes no actor at all: the executer's triple was recorded on the attempt when the claim was made, and
+it reads that back — which is what lets a background job settle a claim it never made, and makes the
+`executed` event name whoever actually claimed the run.
 
 ## Consequences
 
@@ -63,4 +79,9 @@ reload the row that caller has just written to.
   — it catches a path no spec exercises — but it is a regular expression over the tree, and a
   sufficiently creative write would slip past it.
 - Commands return the request, except `Comment`, which returns the event it wrote, because the
-  request is unchanged by it.
+  request is unchanged by it, and `Commands::ClaimExecution`, which returns the attempt its
+  successor has to finish.
+- "Commands are the only writers" is now enforced across more classes than a reader expects:
+  `ClaimExecution`, `SettleExecution` and `Reap` are commands nobody calls directly, existing only
+  so that a sweep or a runner has something to write through. The alternative was a second event
+  path, which is the rule this record exists to keep.

data/docs/adr/0022-execution-in-three-transactions.md

@@ -0,0 +1,77 @@
+# ADR-0022: Split execution into three transactions, and commit the claim before the side effect
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+Executing a change request means invoking host code that the gem knows nothing about. It may take
+seconds, call an external API, or die halfway through when the box is replaced.
+
+Two requirements pull against each other. A request must never execute twice — that is the whole
+promise of the approval gate, and a double charge is worse than no charge. And no row lock may be
+held while the target runs, because a lock held across an outbound call blocks every reader of that
+request for as long as the call takes, which on a bad day is the socket timeout.
+
+The obvious shape — wrap guard, invoke and record in one `with_lock` — satisfies the first and
+violates the second. It also loses the failure: if the target raises, the transaction rolls back and
+takes the record of the failure with it, so the row looks untouched and nobody knows an attempt
+happened.
+
+## Decision
+
+Three transactions, driven by `Execution::Runner`:
+
+```
+T1  with_lock   guard, claim the row, write the attempt, emit execution_started, COMMIT
+T2  no lock     invoke the target
+T3  with_lock   record the outcome on the request and the attempt, emit its event
+```
+
+- **The claim is committed before the side effect runs.** That is what makes this stronger than one
+  lock around all three: between T1 and T3 the request is `executing` to every other process and to
+  the UI, and a second executor is refused by the guard rather than by luck.
+- **T1's conditional `UPDATE … WHERE status IN ('approved','failed')`** is the invariant beneath the
+  guard. Zero rows means somebody else holds the claim, and nothing is invoked. With the guard inside
+  the same lock the ordinary race never reaches it — the loser is refused `:executing` first — so the
+  UPDATE is defence for the paths that skip the guard, not the primary mechanism.
+- **The unique index on `(change_request_id, number)` is the claim's second lock.** Two processes
+  cannot both write attempt 3, whatever either believes about the status column.
+- **T3's failure branch is its own transaction**, so a target that raises leaves no business change
+  and a durable record of the failure: `error_class`, `error_message` and a bounded backtrace on the
+  attempt, and an `execution_failed` event. The error is then re-raised as `TargetFailed` from inside
+  the rescue, so `#cause` is the target's own.
+- Each transaction is a command ([ADR-0016](0016-commands-are-the-only-writers.md)):
+  `ClaimExecution` and `SettleExecution`, internal in the way `EvaluateWorkflow` is. The runner
+  orchestrates and writes nothing itself.
+
+## Consequences
+
+### Positive
+
+- No lock is held across I/O, and that is measured rather than assumed: a `FOR UPDATE NOWAIT` attempt
+  while the target is blocked in T2 succeeds, and the same probe against a runner that collapses the
+  three into one lock fails. The control is what makes the measurement mean anything.
+- A failed execution is fully recorded — which attempt, what raised, and when — while the business
+  change it attempted is absent.
+- `executing` is a real, visible state, so the UI can show a request mid-flight instead of guessing
+  from the absence of an outcome.
+- Because T1 commits on its own, background mode is a small change rather than a different design:
+  only T2 and T3 move ([ADR-0027](0027-activejob-is-optional.md)).
+
+### Negative
+
+- **A process that dies between T1 and T3 strands the row in `executing`**, which no command will
+  move. That is the direct cost of committing the claim, and it is why
+  `Maintenance.reap_stuck_executions!` and `Guards::Reap` exist at all
+  ([ADR-0028](0028-sweeps-are-rake-tasks.md)). A crash-free design would have been simpler and would
+  have executed twice.
+- The reaper's threshold is a guess about the host's slowest target. Set shorter than a legitimate
+  run, it writes off an execution that is still working: the row goes to `failed` while the target
+  keeps going, and nothing recalls it.
+- Three transactions mean three chances to fail, and the second and third are not covered by the
+  first's rollback. A `SettleExecution` that cannot write is a stuck row the reaper later mislabels
+  as abandoned.
+- `executing` is the one status no other command will move — `Cancel` refuses it — so the reaper is
+  the only way out, and a request whose declaration vanished while executing needed a third
+  exemption from the undeclared refusal to stay reachable at all.

data/docs/adr/0023-one-declaration-surface.md

@@ -0,0 +1,68 @@
+# ADR-0023: One way to declare a workflow
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+M1b shipped `op.approvals permissions:, required:` — one stage, one quorum, no ceremony — as the
+shorthand for the common case, with the full `op.workflow` block DSL planned for M2 to express
+staged, multi-quorum policies.
+
+When both existed they wrote the same `@workflow` slot. A declaration carrying one of each silently
+kept whichever came last, with no error and no warning. The two had also already drifted: the same
+number was `required:` in one and `threshold:` in the other, and nothing but attention kept the next
+pair of spellings from diverging too.
+
+## Decision
+
+`op.workflow` is the only way to declare who approves. `op.approvals` is deleted, not deprecated.
+
+```ruby
+op.workflow do |w|
+  w.stage :operational, satisfied_by: :all_quorums do |q|
+    q.quorum :admin,  permissions: [{ actor_type: "Admin" }], threshold: 1
+    q.quorum :owners, permissions: %w(owner), threshold: 2
+  end
+
+  w.stage :director, permissions: %w(director), threshold: 1
+end
+```
+
+- A stage with one counting rule takes its `permissions` and `threshold` inline; a stage with more
+  takes a block. The two produce identical descriptions for the same policy, which is asserted
+  rather than assumed.
+- **`threshold:` everywhere.** There is no second spelling to drift from.
+- **The host names every stage.** The gem invents none, so `config/locales/en.yml` ships no stage or
+  quorum names at all and `name.humanize` covers everything unlisted.
+- `Workflow::Builder` and `Workflow::StageBuilder` build a **description** and nothing else.
+  `Commands::Create` materialises whatever it is handed, so there is one producer and one
+  materialiser, not two of either.
+- Declaration-time refusals for anything the database or the evaluator would otherwise refuse much
+  later: a quorum nobody qualifies for, a threshold below one, an unknown `match` or `satisfied_by`,
+  a duplicate stage or quorum name, a nameless stage, a stage block declaring no quorum, and a stage
+  given both a block and inline keywords.
+
+## Consequences
+
+### Positive
+
+- One slot, one writer. The silent-overwrite failure is not fixed, it is unreachable.
+- Mistakes are refused in the initializer where they were made, naming the stage and quorum, rather
+  than as a unique-index violation at creation or a request that sits pending until it expires.
+- One normalisation of `permissions:` / `actor_type:` / `eligible_actors:` / `match:`, so the inline
+  and block forms cannot disagree about what a quorum means.
+
+### Negative
+
+- Every host declaration changes. There is no deprecation path and no shim — acceptable only because
+  nothing was released, and this record would read very differently otherwise.
+- The common case got longer. `op.approvals permissions: %w(admin), required: 2` became a three-line
+  block, and that is a real cost paid by every operation to remove an overwrite bug most hosts would
+  never have hit.
+- A quorum name is null when its stage holds one, and a string when it holds several, so event
+  metadata carries the key sometimes and omits it otherwise. Readers of the trail have to handle
+  both.
+- `op.workflow` is the declarer and its reader is `workflow` with no block — a convention that
+  worked because a block disambiguates, and which `op.override` then could not follow
+  ([ADR-0026](0026-distinct-intent-distinct-command.md)).

data/docs/adr/0024-idempotence-is-required-not-declared.md

@@ -0,0 +1,57 @@
+# ADR-0024: Require idempotence of every target rather than declaring it per operation
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+A failed execution can be retried. Whether that is safe depends entirely on the target: running
+`Member#update!` twice is harmless, charging a card twice is not.
+
+`Operation` carried an `op.idempotent` flag, defaulting to `false`, intended to gate retries. By the
+time execution was built, nothing read it — and writing the code that would have read it made the
+problem visible. The flag is a promise about host code that the gem cannot verify, cannot test, and
+would have to trust completely while deciding whether to repeat a side effect.
+
+## Decision
+
+The flag is removed. **Every change-request target must be idempotent**, and the README says so as a
+contract rather than an option:
+
+> A change-request target is a public singleton method that accepts keyword arguments only, and whose
+> effect is idempotent — running it twice with the same payload leaves the same result as running it
+> once.
+
+- `retryable?` is `failed? && attempts.count < max_attempts`, and nothing else. The **retry ceiling
+  is the only bound**, because it is the only one the gem can enforce.
+- A host that cannot make a target idempotent leaves `op.max_attempts` at its default of `1` and gets
+  one attempt. That is the same outcome `idempotent: false` would have produced, declared in terms of
+  a number the gem actually acts on.
+- A target declaring `change_request_id:` receives it, stable across every attempt, so one calling an
+  external API can hand it over as that API's idempotency key. A per-attempt token would have defeated
+  exactly the case retries exist for.
+- `rake change_requests:verify` checks the checkable half of the contract — the constant resolves, it
+  answers the singleton method dispatch will call, and it takes keyword arguments only. Idempotence it
+  does not check, and does not pretend to.
+
+## Consequences
+
+### Positive
+
+- One fewer setting whose value the gem has to believe. `max_attempts` is a number with observable
+  behaviour; `idempotent: true` was an assertion with none.
+- The requirement is stated once, in the README, where a host writing their first target reads it —
+  rather than implied by a default they would have had to reason about.
+- `Request#retryable?` needed no change when execution was finally built, because it had never
+  learned about the flag.
+
+### Negative
+
+- **The gem now depends on a property it cannot check.** A host that writes a non-idempotent target
+  and leaves `max_attempts` above 1 gets a double side effect, and nothing in the gem will have
+  warned them. The flag would not have prevented this either — it would have recorded the same
+  unverified claim — but its absence makes the reliance explicit rather than ceremonial.
+- `max_attempts = 1` now carries two meanings: "this is cheap to retry but rarely worth it" and "this
+  must never run twice". A reader of a declaration cannot tell which was meant.
+- Removing a public attribute is a breaking change for anyone who set it. Acceptable only because
+  nothing was released.

data/docs/adr/0025-verification-from-one-set-of-checks.md

@@ -0,0 +1,62 @@
+# ADR-0025: Verify declarations at boot, from the same checks the runtime reads
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+An operation can be wrong in ways nothing notices until the worst moment. A `service` naming a
+constant that does not exist fails when someone finally executes a request two approvals in. A
+workflow with no stages produces a request that can never leave `pending`.
+
+`Commands::Create` already refused some of these at creation, in its own words. §6.12 promised a
+boot-time `verify!` that would refuse more of them. Written independently, those two would answer the
+same question differently — and a third reader was already planned, `Operation#requestable_by?` for
+the "raise a request" button that has no guard to consult.
+
+## Decision
+
+One set of checks, split by what they need in order to run:
+
+- **`Operation#problems`** — everything checkable without loading the host's classes: a `version`, a
+  `service`, a `method_name`, a non-empty workflow, a positive threshold on every quorum. Read by
+  `validate!` at declaration, by `Commands::Create` at creation, and by `verify!` at boot. An
+  incomplete operation therefore never enters the registry at all; `Create`'s check is the backstop
+  for one edited afterwards.
+- **`Operation#target_problems`** — what needs the host's classes loaded, so it runs at boot and
+  nowhere else: the constant resolves, and it answers the public singleton method dispatch will call,
+  taking keyword arguments only. Constantizing during declaration would hold references to classes an
+  initializer has not finished defining, and in a reloading application to classes about to be
+  replaced.
+- **`Execution::TargetContract`** holds the target half and its wording, read by `verify!` at boot and
+  by `Execution::Dispatcher` at dispatch. The two cannot describe the same defect differently.
+- `Operations#verify!` raises one `ConfigurationError` listing every problem across every operation,
+  the shape `Configuration#validate!` already uses. A host that has seen one has seen both.
+- Two entry points: `rake change_requests:verify` for CI and deploys, and a `to_prepare` hook
+  registered in the engine and gated on `Rails.env.local?`. Production runs the task instead, because
+  `verify!` constantizes every declared service and a booted application should not pay for that on
+  every request cycle.
+
+## Consequences
+
+### Positive
+
+- A misconfigured operation fails in CI, or on the next reload in development, rather than on the
+  first execution of a request someone has already approved.
+- Boot-time and creation-time cannot word the same defect differently, because they read the same
+  method — asserted by a spec that compares the two messages.
+- The `to_prepare` hook holds nothing across a reload, which is proven by replacing the resolved
+  class and watching the next run refuse.
+
+### Negative
+
+- `validate!` growing to the full `#problems` set made declaration stricter than it was. Every
+  incomplete fixture in the suite had to gain a service and a workflow, and a host that liked
+  declaring an operation in pieces across two initializers no longer can.
+- **`verify!` does not check everything §6.12 claims.** An unsatisfiable `all_quorums` stage is still
+  unchecked, because "unsatisfiable" is undecidable once permission rows are involved — eligibility is
+  a host runtime question. The gap is recorded in §17.1 rather than papered over.
+- The `to_prepare` hook runs on every reload in development, so a large registry pays a constantize
+  per cycle. Cheap today; a host with hundreds of operations may disagree.
+- Three readers of `#problems` means changing it changes three behaviours at once. That is the point,
+  and it is also the risk.

data/docs/adr/0026-distinct-intent-distinct-command.md

@@ -0,0 +1,59 @@
+# ADR-0026: Give a distinct intent a distinct command class, not a flag
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+Two transitions in the gem are the same mechanics with a different meaning.
+
+Executing with `override: true` does what executing does, on a request that never reached `approved`
+— but §8.1 wants the exception to *look* like one, and `Execute.call(…, override: true)` buried in a
+controller does not. Cancelling because a declaration vanished writes the same columns an ordinary
+cancellation writes, but "nobody decided this, its declaration disappeared" is a different fact from
+"someone called it off", and a timeline should not have to infer which from the actor column.
+
+Both could have been a boolean. Both would then have needed a caller-supplied event kind, which no
+command in the gem has: every one hard-codes the kind it emits.
+
+## Decision
+
+A distinct intent gets a distinct command class, implemented as a **subclass** of the command it
+wraps:
+
+- `Commands::Override < Execute` — `.call(request:, actor:, reason:)`, which is `Execute` with
+  `override: true`. It adds a name and nothing else.
+- `Commands::CancelUndeclared < Cancel` — emits `operation_undeclared` instead of `canceled`, and
+  adds the operation key and the request's creation-time version to the metadata. `Cancel` carries
+  exactly two seams for it, the event kind and the metadata, and is otherwise untouched.
+
+Subclassing rather than delegation is deliberate: the rows and events the wrapper writes **cannot**
+drift from the command it wraps, because there is nothing in the wrapper to drift. The equivalence is
+asserted anyway, by comparing both snapshots.
+
+The same rule decides which event a cancellation emits. **Who cancelled decides**: a person
+cancelling a stranded request emits `canceled` with their own reason, because they cancelled it; the
+sweeper emits `operation_undeclared`, because nobody did.
+
+## Consequences
+
+### Positive
+
+- M5's presenter renders `:execute` and `:execute_override` as two actions — the second `tone:
+  :danger` and always confirmed — without branching on a boolean.
+- A timeline records the fact, not the mechanism. Filtering for `operation_undeclared` finds every
+  request closed out by a vanished declaration, with no join to the actor column.
+- Every command still hard-codes its own event kind, so the "one kind per class" rule holds without
+  exception.
+
+### Negative
+
+- Two classes exist that add almost no code, and a reader looking for the override logic finds it in
+  `Guards::Execute` and `ClaimExecution` rather than in `Commands::Override`. The name is the point,
+  but the name is also all there is.
+- `Commands::Cancel` carries two seams it never uses itself, which is a small permanent cost paid so
+  a subclass can exist.
+- The convention did not extend cleanly to declarations. `op.override` is a declarer whose reader had
+  to be named `override_policy`, because — unlike `op.workflow` — it has no block to distinguish
+  "declare this" from "tell me what was declared", and a bare `op.override` that read instead of
+  declaring would have left the gate shut while looking open.

data/docs/adr/0027-activejob-is-optional.md

@@ -0,0 +1,55 @@
+# ADR-0027: Make background execution a setting and ActiveJob an optional dependency
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+A target that calls an external API should not run in the request cycle. §8 therefore offers
+`config.execution_mode = :background`, moving the invocation and its outcome into an ActiveJob job.
+
+[ADR-0001](0001-headless-domain-core.md) says the domain core must load and run with no Rails at all —
+from a job, a console, an API or a rake task. ActiveJob is a Rails framework. Adding it as a runtime
+dependency to support an optional mode would make every headless adopter carry it, and
+[ADR-0014](0014-executable-architecture-rules.md) forbids the domain from naming the constant at all.
+
+## Decision
+
+`execution_mode` is an ordinary setting, and ActiveJob is not a dependency.
+
+- `ChangeRequests::Execution::Job` lives in a file Zeitwerk **ignores**, required by
+  `ChangeRequests.load_execution_job!` on the same terms `load_engine!` already established:
+  idempotent, public, guarded by `defined?(::ActiveJob::Base)`. Requiring it without ActiveJob defines
+  nothing at all. The engine hooks `ActiveSupport.on_load(:active_job)`, so a host never calls it.
+- **T1 commits synchronously in both modes**, so the request shows `executing` the moment the call
+  returns and the UI never has to guess. Only T2 and T3 move
+  ([ADR-0022](0022-execution-in-three-transactions.md)).
+- The job takes two ids, not two objects — a job argument has to survive serialisation. It can settle
+  a claim it never made because the executer's triple was recorded on the attempt at claim time.
+- `validate!` deliberately does **not** check that `job_class` resolves. A headless process may have
+  `:background` configured and no ActiveJob, and refusing that would fail a boot that works.
+  `ChangeRequests.background_available?` answers the question, and the enqueue reports it, naming
+  ActiveJob.
+- `config.job_class` is a string, resolved at enqueue time and never held: a reloading application
+  redefines it.
+
+## Consequences
+
+### Positive
+
+- A headless adopter carries no ActiveJob and loses nothing they were using. That is asserted in a
+  subprocess: `:background` configured, `validate!` true, `background_available?` false, and a clear
+  refusal on enqueue.
+- The UI shows `executing` immediately in both modes, so background is a deployment choice rather than
+  a different user experience.
+- Nothing in the domain names `ActiveJob`, except two `archspec:disable` lines carrying the reason.
+
+### Negative
+
+- A file Zeitwerk ignores is a file the eager-load check does not cover, so a constant misplaced in
+  `execution/job.rb` fails at a host's first enqueue rather than in this gem's suite.
+- The "is it available" question has three answers depending on when it is asked — at require time,
+  after `on_load`, and at enqueue — and only the last is authoritative.
+- `execution_mode = :background` is valid in a process that can never perform it. That is the price of
+  not failing a headless boot, and it means the misconfiguration surfaces at the first execution
+  rather than at deploy.