Gates Walkthrough: Complete Agent Session with Real Payloads

This page is a transcript of an actual session. Every response is real; long state echoes are abridged for readability. Follow along to see how transition guards, human-only fields, version discipline, and the event log behave together.

The board

Four stages, six custom fields, four policies:

Spec  ──gate-build──▶  Build  ──gate-review──▶  Review  ──┐
                                                          ├──gate-done──▶  Done
                          (any group) ─────────────────────┘

Groups: spec (position 0), build (position 1), review (position 2), done (position 3) Fields:

"field_schema": {
  "task": {
    "priority":         { "type": "enum", "values": ["low", "med", "high"] },
    "spec_doc":         { "type": "string" },
    "plan_approved":    { "type": "boolean" },
    "tests_passing":    { "type": "boolean" },
    "reviewer":         { "type": "string" },
    "shipped_approved": { "type": "boolean", "human_only": true }
  }
}

Policies:

Id	Type	Rule
`gate-build`	`transition_guard`	`spec → build`, requires `plan_approved = true`
`gate-review`	`transition_guard`	`build → review`, requires `tests_passing = true`
`gate-done`	`transition_guard`	`* → done`, requires `reviewer` not empty AND `shipped_approved = true`
`resp-tests`	`agent_responsibility`	when `group_id = build`, message: “Write tests as you go…”

Validate the board before the session starts:

$ substrate validate
Board delivery (Delivery): 4 policies, 4 groups
✓ 1 board(s), 4 policies, 0 member(s) — loaded; definitions parse + group refs resolve, no warnings.

Operation 1 — Create work

Create a task in Spec and another directly in Build:

{
  "board_id": "delivery",
  "group_id": "spec",
  "title": "Add CSV export to the reports page",
  "description": "Users want the report table as a file.",
  "custom_data": { "priority": "high", "spec_doc": "docs/specs/csv-export.md" },
  "agent_name": "claude-code"
}

{
  "ok": true,
  "applied": {
    "entity": "task",
    "id": "6fb97c36-…",
    "version": 1,
    "state": { "…": "…" }
  },
  "policies_fired": []
}

Now create one directly in Build:

{
  "board_id": "delivery",
  "group_id": "build",
  "title": "Fix flaky signup test",
  "custom_data": { "priority": "low", "plan_approved": true },
  "agent_name": "claude-code"
}

{
  "ok": true,
  "applied": { "entity": "task", "id": "68be5428-…", "version": 1, "state": { "…": "…" } },
  "policies_fired": [
    {
      "policy_id": "resp-tests",
      "policy_name": "Tests during development",
      "policy_type": "agent_responsibility",
      "message": "Write tests as you go — tests_passing gates the move to Review."
    }
  ]
}

This task entered Build without passing gate-build. Guards fire on transitions, not on creation. A task can be created directly in any group.

Operation 2 — Move without meeting the gate

Check first, then attempt the move:

{ "task_id": "6fb97c36-…", "to_group": "build" }

{
  "allowed": false,
  "from_group": "spec",
  "to_group": "build",
  "blocked_by": {
    "policy_id": "gate-build",
    "message": "Set plan_approved=true once the plan is signed off."
  }
}

{ "id": "6fb97c36-…", "version": 1, "group_id": "build", "agent_name": "claude-code" }

{
  "ok": false,
  "error": {
    "code": "transition_blocked",
    "message": "Set plan_approved=true once the plan is signed off.",
    "details": { "policy_id": "gate-build", "from_group": "spec", "to_group": "build" }
  }
}

Three things to note here:

The on_failure_message from the policy is the error message — write it as an instruction to the agent.
A blocked write changes nothing, including the task’s version.
The block is recorded as a move_blocked event in the task’s history.

Operation 3 — Satisfy the gate and move in one write

The gate evaluates the task as it would look after the move. Set the required field and change group_id in a single update_task call:

{
  "id": "6fb97c36-…",
  "version": 1,
  "group_id": "build",
  "custom_data": { "plan_approved": true },
  "agent_name": "claude-code"
}

{
  "ok": true,
  "applied": { "entity": "task", "id": "6fb97c36-…", "version": 2, "state": { "…": "…" } },
  "policies_fired": [
    {
      "policy_id": "resp-tests",
      "policy_type": "agent_responsibility",
      "message": "Write tests as you go — tests_passing gates the move to Review."
    }
  ]
}

custom_data is merged, not replaced. The call only sent plan_approved, but priority and spec_doc remain on the task unchanged.

Operation 4 — Stale version

If another write has occurred since your last read, you will receive version_mismatch:

{ "id": "6fb97c36-…", "version": 1, "title": "Add CSV export", "agent_name": "claude-code" }

{
  "ok": false,
  "error": {
    "code": "version_mismatch",
    "message": "This task has been updated since you last read it. Call get_task to re-read, reconcile any conflicts, then retry with the new version.",
    "details": { "id": "6fb97c36-…", "current_version": 2 }
  }
}

The correct response is to re-read with get_task, reconcile any conflicts, then retry. Do not resend the same body with version: 2 — that would silently overwrite another writer’s changes.

Operation 5 — Second gate

Moving from Build to Review requires tests_passing = true (gate-review). Attempting the move without it fails with the same pattern as Operation 2. Set tests_passing: true and move in one call — the task lands in Review at version: 3.

Nothing ran the tests. The agent set tests_passing: true itself. This gate is a confession step, not a verification.

Operation 6 — The human gate

gate-done requires both reviewer (not empty) and shipped_approved = true. The shipped_approved field is human_only.

{ "task_id": "6fb97c36-…", "to_group": "done" }

{
  "allowed": false,
  "from_group": "review",
  "to_group": "done",
  "blocked_by": {
    "policy_id": "gate-done",
    "message": "Done needs a reviewer and a human sign-off: substrate approve <task_id> shipped_approved"
  }
}

The agent attempts to set both fields at once:

{
  "id": "6fb97c36-…",
  "version": 3,
  "custom_data": { "reviewer": "dana", "shipped_approved": true },
  "agent_name": "claude-code"
}

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "Field(s) shipped_approved are human-only — a human must set them (e.g. `substrate approve 6fb97c36-54cb-466b-a010-ab5fb4097461 shipped_approved`). An agent cannot set them via update_task.",
    "details": { "fields": ["shipped_approved"] }
  }
}

The error code is forbidden, not transition_blocked. The entire write is rejected — including the legitimate reviewer field — before anything is applied. Split the call: set only reviewer first, then wait for human approval.

After setting reviewer separately, the agent calls list_pending_approvals to surface what needs human attention:

{
  "project_name": "demo",
  "count": 3,
  "items": [
    {
      "board_id": "delivery",
      "board_name": "Delivery",
      "task_id": "6fb97c36-…",
      "task_title": "Add CSV export to the reports page",
      "group_id": "review",
      "gate": { "policy_id": "gate-done", "to_group": "done" },
      "awaiting_fields": ["shipped_approved"]
    }
  ]
}

The count is 3, not 1, because gate-done is a "*" → done wildcard — every task on the board is one move away from a gate it cannot pass. A wildcard human gate makes this report noisy on a busy board. If that bothers you, gate a specific from_group instead.

Operation 7 — The human decides

$ substrate pending-approval
3 task(s) pending human approval in demo:

Delivery
  Task                                  Move           Awaiting          Approve
  Add CSV export to the r…  (6fb97c36)  review → done  shipped_approved  substrate approve 6fb97c36-54cb-466b-a010-ab5fb4097461 shipped_approved
  Fix flaky signup test     (68be5428)  build → done   shipped_approved  substrate approve 68be5428-0a59-4f30-b2a2-0c4ee6c1b652 shipped_approved
  Rate-limit the public A…  (3c2559b6)  spec → done    shipped_approved  substrate approve 3c2559b6-5c54-4b8e-9a39-3d0ceb6f2a4f shipped_approved

Each row carries the exact command that clears it. Run one:

$ substrate approve 6fb97c36-54cb-466b-a010-ab5fb4097461 shipped_approved
Approved: set shipped_approved = true on task 6fb97c36-54cb-466b-a010-ab5fb4097461 (as human:diegoferreyra, version 5).

The approval is stamped human:diegoferreyra, not the agent name. It bumps the version to 5 — the agent’s cached version 4 is now stale and must be re-read before the next write.

The agent re-checks and moves:

{ "allowed": true, "from_group": "review", "to_group": "done" }

{
  "ok": true,
  "applied": { "version": 6, "state": { "group_id": "done" } },
  "policies_fired": []
}

substrate approve sets the field; it does not move the task. The human decides; the agent performs the move.

Operation 8 — Revoking an approval

$ substrate unapprove 6fb97c36-54cb-466b-a010-ab5fb4097461 shipped_approved
Revoked: cleared shipped_approved (was true) on task … (as human:diegoferreyra, version 7).
Warning: task … is in group 'done', past the gate that required shipped_approved.
         unapprove does not move tasks — move it back on the board if that was a mistake.

The field is deleted, not set to false. Both an exists check and an eq true check will re-block correctly if the task is moved back through the gate.

What the history remembers

#	Event	What it records
1	`created`	Initial state — group `spec`, title, `custom_data`
4	`move_blocked`	`gate-build`, `spec → build`, failure message
5	`updated`	Before/after group and `custom_data`, plus `policies_fired`
6	`move_blocked`	`gate-review`, `build → review`
7	`updated`	Into Review with `tests_passing`
8	`updated`	`reviewer` set. Actor `claude-code`
9	`move_blocked`	`gate-done`, `review → done`
10	`updated`	`shipped_approved` set. Actor `human:diegoferreyra`
11	`updated`	`review → done`. Actor `claude-code`

Event 10, verbatim:

{
  "id": 10,
  "task_id": "6fb97c36-…",
  "event_type": "updated",
  "changes": {
    "before": { "custom_data": { "…": "…", "reviewer": "dana" } },
    "after":  { "custom_data": { "…": "…", "reviewer": "dana", "shipped_approved": true } }
  },
  "actor_agent_name": "human:diegoferreyra",
  "occurred_at": "2026-09-06T23:32:45.074Z"
}

The blocked attempts are as informative as the successful ones. Three move_blocked events show the rails engaged three times, and the single human: actor shows exactly where a person entered the loop.

What this board does and doesn’t give you

What you get

An agent that cannot quietly skip a stage. Reminders delivered at the moment they apply. A durable record of every attempt including refused ones. One step that genuinely waits on a person.

What you don't get

Verified tests — self-attested. Immutable rails — policies are data, and an agent could archive_policy, but that act is git-visible and event-logged.

Policies and Gates

Full reference for transition_guard and agent_responsibility — operators, compounds, and what guards guarantee.

Validate Your Gates

Run substrate validate and test your policies before relying on them in a live workflow.

Get Started

Concepts

Working with Agents

Authoring a Substrate

Operations

Gates Walkthrough: Complete Agent Session with Real Payloads

The board

Operation 1 — Create work

Operation 2 — Move without meeting the gate

Operation 3 — Satisfy the gate and move in one write

Operation 4 — Stale version

Operation 5 — Second gate

Operation 6 — The human gate

Operation 7 — The human decides

Operation 8 — Revoking an approval

What the history remembers

What this board does and doesn’t give you

What you get

What you don't get

Policies and Gates

Validate Your Gates

​The board

​Operation 1 — Create work

​Operation 2 — Move without meeting the gate

​Operation 3 — Satisfy the gate and move in one write

​Operation 4 — Stale version

​Operation 5 — Second gate

​Operation 6 — The human gate

​Operation 7 — The human decides

​Operation 8 — Revoking an approval

​What the history remembers

​What this board does and doesn’t give you

What you get

What you don't get

Policies and Gates

Validate Your Gates

The board

Operation 1 — Create work

Operation 2 — Move without meeting the gate

Operation 3 — Satisfy the gate and move in one write

Operation 4 — Stale version

Operation 5 — Second gate

Operation 6 — The human gate

Operation 7 — The human decides

Operation 8 — Revoking an approval

What the history remembers

What this board does and doesn’t give you