Complete is a claim
The failure of treating a file that says complete as the observation. The file can be wrong. The catch is to run the check again and report that exit code.
When to use
Use this failure mode when a status file says complete and someone is about to report success from that sentence alone.
When not to
Do not use the status file as the check. Do not delete status files as a remedy. The remedy is to run the real check and believe its exit code.
Author-attested
Original teaching specimen written for the Campaign Hub library. Not a transcript of a private run.
# Complete is a claim
This file is a failure mode: a named way the work lies about being done, and the observation that catches it.
## When to use
Use this name when a piece of work is carrying a file, a badge, or a sentence that says it is complete. The sentence may be true. It may be stale. It may have been written before the check existed. The failure mode is treating the sentence as the observation.
Name the failure out loud, then run the check.
## When not to
Do not use this failure mode as a reason to stop writing status down. A status line is useful as a claim. It is useless as a proof.
Do not "fix" the failure by editing the status file from complete to incomplete without running the check. You would have replaced one unobserved sentence with another.
## The specimen
The artifact is this failure mode.
```text
name: complete is a claim
class: the work lies about being done
failure:
A file or a sentence says the work is complete.
A reader reports success because that sentence exists.
The reader does not run the check the work itself named.
why it passes a casual look:
The status file is easy to open.
The check may be a script, a second file, or a command.
The sentence and the bytes can disagree, and the sentence is the one in front of the reader.
smallest example:
status file contains: status: complete
beside it, a bead is missing how_checked
the bead check exits 1
reporting success from the status file is the failure
catch:
Run the check again.
Report the exit code and the line the check printed.
If the check exits non-zero, the work is not done, whatever the status file says.
If the check exits 0, you may say complete, and you cite that run.
not the catch:
- deleting the status file
- rewriting the status file
- asking the author whether they meant it
```
The status file in the smallest example is a claim that the bead is finished. The observation is `check-bead.sh`. On the known-bad envelope the observation exits 1. The failure mode is real whenever those two disagree and the reader picks the file. This catch guards the four-field envelope: a bead can carry a proud status and still be unfinished.
## How a stranger checks it
A stranger produces the failure and then applies the catch.
1. Write a file `STATUS.txt` whose only line is `status: complete`.
2. Place the known-bad bead, the one with no `how_checked`, in the same directory.
3. Ask a reader who has been told "trust the status file" what the directory's state is. If they say finished, they have reproduced the failure.
4. Apply the catch: run `bash check-bead.sh` on the bad bead. The exit code is 1. The honest report is that exit code, not the status line.
The failure mode's own text fails if its catch says anything other than running the check again. "Update the status file" is a second copy of the same mistake.
How a stranger checks it
- CLAIM-1 A complete-file whose paired check exits non-zero is reported as a failure, not as success. Write a status file that says complete beside the known-bad bead. Run check-bead.sh. Report the check's exit code. Reporting success from the status file fails this catch.