# The four-field envelope This file is a bead: one dispatchable unit with a deliverable, a check, a writable scope, and a protected scope. ## When to use Use this when you send one bead to a worker. The worker should be able to finish without asking what "done" means, what they are allowed to edit, or what they must leave alone. The four fields are the envelope. They travel together. A bead that arrives without its check is unfinished before the worker starts. ## When not to Do not send a bead whose check is "use your judgment," "looks good," or "mark complete when finished." Those are not observations a stranger can run. Do not let `may_change` say "anything" and `must_not_touch` say "nothing." A scope that wide is not a scope. Split the work or name the real boundary. ## The specimen The artifact is this bead. Each label starts a line. Each line has a value. The check named here is the script in the specimen "A check that can fail." ```text deliverable: One specimen file a stranger can reuse without the author present. how_checked: check-bead.sh on this file exits 0. may_change: The single specimen file this bead names. must_not_touch: The roster, the seed files, and every other specimen. ``` How to read the four fields when you write your own bead: - `deliverable` names the thing that will exist when the bead is done. One bead, one deliverable. - `how_checked` names an observation a stranger can run, with the result that counts as pass and the result that counts as fail. A missing or empty `how_checked` means the bead is unfinished. - `may_change` names the writable scope. The worker may edit what this line names. - `must_not_touch` names the protected scope. The worker does not edit what this line names, even if editing it would make the check easier to pass. The labels are the contract. A prose paragraph that mentions the same ideas without the labels will not satisfy the check, because the check looks for the labels. The known-bad pair, a bead that omits `how_checked`, lives in the specimen "An envelope that goes red." ## How a stranger checks it Save the fenced bead as `good-bead.txt`. Run the bead check from "A check that can fail": ```bash bash check-bead.sh good-bead.txt ``` The run exits 0 and prints `pass`. Then delete the `how_checked` line and run the same command again. The run exits 1 and prints `fail: bead has no how_checked observation`. Put the line back. The bead is the four lines together. A stranger who cannot run the script yet can still do this reading: four labels, each at the start of a line, each followed by a non-empty value. Any missing label fails. `how_checked` with nothing after the colon fails. That empty value is the same failure as a missing line: the bead has no observation.