Guide
A person in the acceptance loop: how reviews and disputes work
Ten qualified meetings were delivered. Eight passed every check. One failed a clear rule. One came back uncertain: the calendar shows the meeting, the call log doesn't. Nobody wants a meter to guess on that one. So the record routes it to a named person with a deadline, and whatever they decide lands in the record with their name on it.
Most acceptance runs on rules. A Spool says what one unit of work is, what evidence proves it, and who judges it, and most units land cleanly on pass or fail. Some don't. The evidence is thin, two sources disagree, or the rule needs a judgment the checker was never asked to make. Those units are uncertain, and an acceptance system has to say what happens to them.
There are two lazy answers. Accept them, and you've paid for work nobody confirmed. Reject them, and you've refused work that was probably done. The third answer is the one people use in every other part of commerce: ask someone who can know, give them a deadline, and write down what they said. That's what a review request is. This article walks through what one does to the record, what a dispute does, and the one rule that holds the whole thing together: silence never accepts.
The review request: one person, one link, one deadline
A review request is opened against a receipt. It names four things:
- Scope. One or more units, or the whole outcome.
- Reviewer. A subject and a role: the buyer, the provider, or a third party. The reviewer doesn't need a Spoolis account.
- Deadline. Up to 30 days out.
- What silence means.
hold,reject, orkeep_accepted, chosen when the request is opened (more on this below).
The reviewer gets one hosted link. It works once, it expires at the deadline, and it doesn't carry their email. The page shows the acceptance criteria verbatim, each scoped unit's verdict and the reason behind it, the evidence with digests and provenance, and the clock. Two actions: Confirm, or Dispute with a required reason and optional counter-evidence. That's the whole interface, because the person is there to answer one question, not to learn a product.
What Confirm does to the record
Confirm is a fact, not a mood. For each unit in scope, the governing condition result is rewritten with method: human_confirmed and confirmed_by set to the reviewer. Then one of two things happens:
- A verdict changed (uncertain became pass). Spoolis re-aggregates and issues a successor receipt with the reason
review_decision. The original receipt is never edited; the new one says what it supersedes and why. - Nothing changed (the reviewer confirmed a unit that was already accepted). The decision is recorded on the review. No new receipt, because the record didn't move.
Either way, anyone reading the record later can see that a person decided, who they were, and when. Spoolis maintains the canonical accepted commercial state under the agreement's rules and authority model; a human decision is one more entry in that record, with provenance, not a side channel.
What Dispute does
Dispute needs a reason and can carry counter-evidence as text or a URL. It opens a dispute object under the Spool's dispute policy, and that object reports five figures side by side: claimed, accepted, disputed, final, and payable.
While the dispute is open, the policy marks the disputed value as not currently final or payable. That's a statement about the record. Spoolis does not restrict or control money; the payment system you already use moves funds under its own rules, and it reads the accepted state from the record when it's ready to.
What happens next is whatever the Spool declared in its dispute policy:
- Re-verify. Verification runs again for the units in scope, with the counter-evidence included if the policy allows new evidence, and issues a successor receipt with the reason
dispute_resolution. - External judge. The dispute is recorded as waiting for the named judge and shows on the status endpoint until they decide.
- None. The dispute stays open until the window ends.
When the window ends, the declared finality rule applies: either the current state becomes final, or the Spool stays disputed. Both are choices the buyer and provider made up front, and both are visible on the record.
Silence never accepts
The one rule that makes a human step trustworthy is that not answering can't be a way to get paid. A review request carries its own timeout rule, and the validator only allows the three below.
| Timeout rule | What it does |
|---|---|
hold | The unit keeps its current state, on the record as still waiting for a person. Nothing is accepted by default. |
reject | The unit is treated as not accepted. The buyer chose that outcome for silence when the Spool was written. |
keep_accepted | Allowed only when every unit in scope was already accepted before the review. Silence keeps an accepted unit accepted; it never promotes one. |
An uncertain or rejected unit never becomes accepted because a deadline passed. A cron sweeps expired reviews every five minutes and applies the rule the request declared. If someone forgets, the record says exactly what forgetting meant.
Every step is a machine step too
The hosted page exists for the human. Everything it can do, software can do without anyone awake:
- API: open a review, read it, record a decision, open a dispute, read a dispute.
- MCP tools:
request_review,get_review,decide_review,open_dispute,get_dispute. - CLI:
spoolis review request|get|decideandspoolis dispute open|get. - Status: the receipt status endpoint reports pending reviews and open disputes, and a consumer can require
require_no_open_disputesbefore it acts. - Events:
review.requested,review.decided,review.expired,dispute.opened,dispute.resolved,dispute.expired.
So an agent can notice an uncertain unit, route it to the right person, wait for the decision, and continue only when the record says it can. The person is in the loop; the loop doesn't stop for them.
Why this matters
- Buyers: you get a real second look at the units that deserve one, with a deadline you set, and nothing gets accepted because you were busy.
- Sellers: an uncertain unit isn't a lost unit. A confirmation lands in the record with a name on it and supersedes the old verdict cleanly.
- Builders: the human step has the same shape as every other step: an object with a status, an event, a receipt that supersedes another. Nothing to special-case.
Scope
- This describes reviews and disputes as they run on Spoolis today. The docs page is the authoritative reference for field names, limits, and errors.
- Counter-evidence in a dispute is text or a URL. Files and structured evidence go through the Spool's normal evidence path.
- The review link is single use and expires at the deadline. A second decision needs a second request.
Try it
Read the reviews and disputes reference, then run the review_and_dispute scenario from the sandbox quickstart. It delivers ten units, routes the uncertain one to a reviewer, confirms it, opens a dispute on another, and hands you back a status you can read: the decided review, one open dispute, and the five figures.