smalltalk pre-release

Products and gates

When a worker says a step is complete, that's a report, not a verdict. smalltalk decides "done" with two things a step can declare: products and gates. The step only advances when every product holds and every gate passes.

Products#

produces names graph state that the work promises to create, such as a resource in a given state or a message that has been read. The worker creates it, and smalltalk checks it. Until the products hold, the step stays in verifying, and smalltalk tells the worker exactly what it is still waiting for.

Gates#

A gate decides whether finished work can pass. All of a step's gates must pass. There are four kinds:

• Graph predicates check facts in the graph: a subject exists, a field has a value, every check on a pull request succeeded.
• Mechanical gates run a shell command, like a test suite, with a time limit.
• LLM gates ask a model to judge. They name the model, the tools, a token budget and a time limit explicitly, and a gate that runs over its budget fails.
• Human gates ask one named person.

A pass releases the step and a failure fails it. A graph or human gate that can't decide yet keeps the step pending.

An example#

Here, an agent prepares release notes, a mechanical gate checks that they were pushed, and a person approves them. The two later steps are agentless, so the seat is free for other work while they wait.

step "prepare" timeout="45m" {
  assigned-to "agent/example/worker"
  goal "Write RELEASE-NOTES.md for 1.4.0 and push the release-notes branch."
}

step "verify" {
  agentless
  depends-on { step "prepare" completed }
  gate "the pushed branch has release notes" {
    exec "git fetch --quiet origin release-notes && git cat-file -e FETCH_HEAD:RELEASE-NOTES.md"
    host "local"
    workspace "${ST_WORKSPACE}"
    time-limit "2m"
  }
}

step "approve" {
  agentless
  depends-on { step "verify" completed }
  gate "the operator approves the release notes" type="human" {
    reviewer "person/operator"
    question "Publish the release notes on the release-notes branch as 1.4.0?"
  }
}

The human gate appears in the reviewer's attention inbox with the exact commands to approve or reject it. Nobody has to notice a message.

Why it matters#

Gates make "done" something you declare up front, instead of something an agent claims afterwards. Every gate result is recorded in the graph with its evidence, so you can see why a step passed or failed without asking anyone.

Missions can declare products and gates too. Those are the contract for the whole run, checked after every step has finished.