Skip to content

The checklist, annotated

Bryan Hamilton edited this page Nov 7, 2026 · 1 revision

The checklist, annotated

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.

Before writing the patch

  1. Probe before patching. Live bytes or it didn't happen. Templates, memories, and local copies all lie. (See needle Rule 1.)
  2. Byte-exact needles. Entities, em dashes, and quote styles drift in transit. Copy, never retype.
  3. Map control flow around the inject point. Create before test. This is the only rule whose failure mode is silent (Failure mode 4).
  4. One change per needle. Count must be 1; both 0 and 2+ are aborts, not puzzles.

In the worker

  1. Token-gate everything. hash_equals against the token; render the site's real 404 on failure so the worker's existence is not a signal.
  2. Marker check first. Idempotency by refusal: a patched file aborts the run before any needle is counted.
  3. Guard every needle. guard() before any filesystem call.
  4. Backup before write. .bak-<tag>.bak, restore on any failure. The backup is the difference between an abort message and an incident.
  5. 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.
  6. Lint-gate PHP writes. php -l the patched file; a parse error in a shared include takes the whole site down. Restore before anything else.
  7. Self-delete the worker. One-shot means one shot. Exclude the worker from its own directory scans.
  8. 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.

After the deploy

  1. Cache-bust every check. ?cb=<timestamp>. (See Cache-aware verification.)
  2. Verify the new behavior. Marker presence beats symptom absence.
  3. Reproduce front-end bugs clean. Fresh headless browser before any patch. Ghost bugs get ghost patches.
  4. Keep backups for risky patches - deliberately. keepBackup: true is a decision, and deleting the backup is the next worker's first job.
  5. Act on exactly the named suspect. Scope creep during a patch is how one bug becomes three.

Known trap

  1. Three-layer escaping. Generator -> PHP string -> JS output each eats backslashes differently. Explicit byte strings, verified char-by-char. (Failure mode 7.)

Clone this wiki locally