The bob do Machine

The bob do machine

bob do gives unstructured work the same evidence-driven state machinery that warp-drive gives requirements: the spike, the hour spent poking at something, the “should we even do this?”. It is BoB’s third state machine (#2974), built on the shared engine beside warp-drive and bob decompose. To run one, see Run unstructured work with bob do.

What goes wrong without it

An unplanned hour has no requirement, so nothing says when it is finished or what it should leave behind. It can end in a useful answer or in nothing at all, and from the outside the two look the same until someone asks what happened. Warp-drive cannot help here, because every path through it assumes the work was worth doing.

The framing gate is the point

A run starts in framing and cannot leave until it has two things on its state:

a one-line question, what the hour is for
an artifact type from a closed set, what the hour will produce

Artifact	What the hour leaves behind
`decision`	a `/journal decision` issue
`lesson`	a `/journal lesson` issue
`doc`	a file under `docs/` that passes the docs check
`spike`	a `research`-labelled issue or a doc
`issue-set`	filed `req`, `task` or `bug` issues
`discard`	a `decision` issue saying why not

An unknown value is refused at the transition, and the refusal is recorded on the state. It is not accepted and reported later. The set is closed on purpose. With a free-text artifact, “I looked into it” would pass the gate. Every entry in the set maps onto something BoB already knows how to file, so a later phase can check that it exists.

This separates a productive hour from a lost one before the hour starts.

The phases

framing --framed--> working --worked--> landing --landed--> recording --recorded--> done
                       |                   |
                       +------discard------+--> discarded

There are six transitions and nothing else. done and discarded are the terminals.

framing: the gate above, fired by the framing gate itself. A bare engine transition cannot claim it.
working: bounded by a budget in minutes or tokens (from --budget, else _workflow.do_budget_minutes), or ended early when you declare enough with a one-line reason. When the budget is spent, the next look at the run moves it to landing with budget_exhausted: true, so a run cannot quietly grow into an afternoon.
landing: the declared artifact must exist. The gate reads it back at the moment of the transition, from the forge (the issue, its label, the question in it) or from the tree (the doc is committed and passes the docs check). A run cannot claim an outcome it did not produce.
recording: the artifact and whatever prompted the run (an issue, a brief) must link to each other, and both directions are read back, so the next person or session can find it. A run with no prompt records prompted_by: none explicitly. done writes the outcome and the artifact’s URL or path on the state.

The evidence each artifact type needs is listed in the bob do reference.

Why discarded is a success

Often the best outcome of an hour is “no, and here is why”. In a tool that only knows how to finish work, that outcome ends up as an abandoned session: nothing is filed, and the next person asks the same question again.

discarded is a terminal state that exits 0, and a run can only reach it with a decision on record. The gate reads a decision issue back from the forge: the issue must exist, carry the decision label and name the run’s question. The run’s own claim that one was filed is not enough. The “no” becomes a searchable record, linked to the question that produced it, and the hour counts as a result.

bob do stop is the other way out. It leaves no record and only frees the checkout. That is right when a run was started by mistake and wrong when the hour answered something.

How it relates to warp-drive and bob decompose

All three machines share the engine’s mechanics: the state-file discipline, the liveness rule, transition validation and evidence-fired events. Each machine keeps its own phase list and state file, and warp-drive’s phase contract is untouched.

Machine	Artifact	Runs beside warp-drive?
warp-drive	commits, merged to a branch	—
`bob decompose`	filed child requirements	Yes. It writes issues, not files.
`bob do`	one artifact from the closed set	No. It writes files.

Because bob do writes in the working tree, it is declared concurrent_with_warp: false, and the rule holds in both directions:

bob do refuses to start while warp-drive is active in the checkout, and names that run’s issue and phase.
warp-drive’s init exits 3 and bob warp start exits 5 while a do run is active. Both name the run’s question and phase.

A run is active when its state is not terminal and its session is alive. That session is the Claude Code process that started it, found as the nearest claude ancestor, or --pid if you pass one. A stale run (dead process, or older than 24 hours) holds nothing.

#2798, the brief that proposed bob do and ordered it after bob decompose.
#2978, showing a do run in bob viz like any other session.