docs(agents): require persisting state before publishing handoffs

[behinddwalls]

Summary

Why?

A queue message that hands work to a later stage races the write that backs it. Within a service boundary the payload is only the entity ID and the consumer reloads from storage, so a message published before its write lands lets the consumer read an entity that was never recorded — or a version older than the one the message describes — and then act on an assumption that was never true. The other ordering is self-correcting: a failed publish leaves the state durable and the retry re-publishes, where the reverse leaves a message describing a state nothing wrote.

The repo already depends on this ordering but never wrote it down. Two sites deliberately publish first — the recovery nudge in speculate/finalize.go and the status log in buildsignal.go — each with a local comment explaining why. Stated as a blanket rule, it would read as something those two sites violate, and the next reader would "fix" them.

What?

Adds "Persist before you publish" as Key Concept #6, scoped to messages that hand off work. It carves out messages whose consumer depends on nothing the write does — a status log recording a transition, an idempotent nudge whose consumer re-derives from current state — and points at the two sites that document that reasoning in place.

Cross-references the rule from the queue-payload guidance, since reloading from storage is what makes the ordering load-bearing there.