Gate a stage with checks

This guide makes a stage that a task cannot leave until a check has passed, and that advances the task on its own once it does. You will register a check, add rules to two stages, and see honestly where the task will wait for a person.

If checks and rules are new, read What moves a task without a person first.

Before you start

Every step here needs admin on the space. See Authentication. You also need a workflow with two stages in sequence — this guide uses In review and Done — and, for the automatic move in step 4, the workflow's auto_advance_enabled turned on (see Workflows).

The examples use MCP tools; the reference pages list every field.

1. Register the check

Define the check in the space's registry with checks_registry_create:

// checks_registry_create
{ "space_key": "OPS", "code": "reviewed", "description": "A reviewer approved the work" }

2. Create the check when a task reaches the stage

check_rules_create identifies a stage by its numeric stage_id, not by name. Get the ids for your workflow's stages with stages_list:

// stages_list
{ "space_key": "OPS", "workflow_slug": "delivery" }

The response lists each stage with its id:

{ "stages": [ { "id": "148", "name": "In review", "group": "Doing" }, { "id": "149", "name": "Done", "group": "Done" } ] }

Add a create check rule on In review (here stage_id 148), so that entering the stage puts a pending reviewed check on the task:

// check_rules_create
{ "space_key": "OPS", "check_code": "reviewed", "stage_id": 148, "effect": "create" }

3. Gate the next stage on it

Add a require check rule on Done (here stage_id 149), so a task cannot enter Done until reviewed has passed:

// check_rules_create
{ "space_key": "OPS", "check_code": "reviewed", "stage_id": 149, "effect": "require" }

Now a transition into Done while reviewed is not passed is refused with requires check reviewed to be passed (currently pending).

4. Advance the task automatically once it passes

Add a sentinel rule on In review that moves the task to Done once its checks all pass:

// sentinel_rules_create
{ "space_key": "OPS", "workflow": "delivery", "stage": "In review", "predicate": "all_passed", "action": "transition", "target_stage": "Done" }

When reviewed passes, the sentinel can move the task to Done with no person involved, and because reviewed is passed, the require gate on Done lets it in. The move is not instant: it happens on the next sentinel sweep, which runs every 30 seconds and again shortly after a check is set. It happens only while all of these hold:

• the task has no blocking hold
• no lease of a pool named by an assignment rule at In review that applies to the task, created since the task entered In review, is still active
• a WIP constraint on Done, if there is one, has room; while it is full, the sentinel tries again on each sweep
• the space, the stage and the task are not archived, and the task has not been resolved since it entered In review

The full list is in What moves a task without a person § A sentinel rule advances or holds the task.

Where the task waits for a person

Be clear about the limits before you rely on this:

• A check only passes when someone sets it. Nothing in Cadence passes reviewed on its own; a worker on the stage or an operator sets it to passed (see Checks). Until then the task waits in In review indefinitely — the sentinel's all_passed predicate is not true while reviewed is still pending.
• A blocking hold stops the move. The sentinel never moves a task with a blocking hold, and Cadence never clears one on its own. A person clears it, or a worker whose lease reaches the task replaces it with an advisory hold and clears that (see Hold a task and clear a hold). Cadence places some blocking holds itself, for example when a worker's lease fails, so a task can stop in In review with reviewed passed until you clear the hold.
• An admin can force past the gate. A transition with force: true bypasses the require gate. Forcing needs admin, and the bypass is recorded.

For the full account of what runs on its own and what does not, read What moves a task without a person.