The four-field envelope
A bead with four fields: the deliverable, how it is checked, what it may change, and what it must not touch. A missing check leaves the bead unfinished.
When to use
Use this envelope when you dispatch one unit of work and the worker must see the deliverable, the check, the writable scope, and the protected scope together.
When not to
Do not dispatch a bead that names a deliverable and omits the check. Do not use a status file as a substitute for the how_checked field.
Author-attested
Original teaching specimen written for the Campaign Hub library. Not a transcript of a private run.
# 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.
How a stranger checks it
- BEAD-1 The fenced bead has non-empty deliverable, how_checked, may_change, and must_not_touch lines, and check-bead.sh exits 0 on it. Save the fenced bead and run check-bead.sh on it. Exit 0 and the line pass are required. A copy with how_checked removed must exit 1.