Repository navigation
The checklist, annotated
Bryan Hamilton edited this page Nov 7, 2026
·
1 revision
docs/checklist.md is the terse version you skim before a deploy. This page is the version that explains why each rule exists. Cross-references: needle rules in Anatomy of a needle, incident detail in Failure modes.
- Probe before patching. Live bytes or it didn't happen. Templates, memories, and local copies all lie. (See needle Rule 1.)
- Byte-exact needles. Entities, em dashes, and quote styles drift in transit. Copy, never retype.
- Map control flow around the inject point. Create before test. This is the only rule whose failure mode is silent (Failure mode 4).
- One change per needle. Count must be 1; both 0 and 2+ are aborts, not puzzles.
-
Token-gate everything.
hash_equalsagainst the token; render the site's real 404 on failure so the worker's existence is not a signal. - Marker check first. Idempotency by refusal: a patched file aborts the run before any needle is counted.
-
Guard every needle.
guard()before any filesystem call. -
Backup before write.
.bak-<tag>.bak, restore on any failure. The backup is the difference between an abort message and an incident. - Verify the patch, not the intent. Require the marker and the replacement to be present in a re-read of the file - not a boolean from the write call.
-
Lint-gate PHP writes.
php -lthe patched file; a parse error in a shared include takes the whole site down. Restore before anything else. - Self-delete the worker. One-shot means one shot. Exclude the worker from its own directory scans.
- Delta-based balance checks. Never assert "zero stray braces" in a file full of strings; assert the count delta introduced by your patch is what you intended.
-
Cache-bust every check.
?cb=<timestamp>. (See Cache-aware verification.) - Verify the new behavior. Marker presence beats symptom absence.
- Reproduce front-end bugs clean. Fresh headless browser before any patch. Ghost bugs get ghost patches.
-
Keep backups for risky patches - deliberately.
keepBackup: trueis a decision, and deleting the backup is the next worker's first job. - Act on exactly the named suspect. Scope creep during a patch is how one bug becomes three.
- Three-layer escaping. Generator -> PHP string -> JS output each eats backslashes differently. Explicit byte strings, verified char-by-char. (Failure mode 7.)
Guarded Deploy Workers
Repo